Your IP : 216.73.216.86
PK %�\L�Zs� � html/_images/logging_flow.pngnu �[��� �PNG
IHDR � � I� sRGB �� � gAMA �� �a cHRM z& �� � �� u0 �` :� p��Q< �nIDATx^�M�fG�� ��m��i����GmZ��lz!jd��aJ�&e�B�1Nޤ!yk�4N�µH��18��� -�01xD�
�a�.��U 4����A����*]U����u>"Ή��!I��y�D��x�s=����g?�� @ ����/��������?��?������_|�ɓ'��3�O��}>����H1s@ �@�>���W^yE�}��z��O>� 4� |
���)x��w��ys�ߒX@��B1�� !��g���!O�� �@1�%E9@ e��?�裏�1��K�{P4���Z� �M@
bUڃ �_%�bfF�M���G�}�z@ � j%��_����(�Z���@1��D�V h���q@ ��!�c>;�f&�b� ��*#@ se�9hVg��* ��^�i�$sI��}<��c�Y X|d��� P� ��,_j߇ �y δr�Q�i�s!�T[� �2ʱ�����cMKG W��i� sA�T]� +�Jҥ��P��� �lP��PR�^ȕ�i�)I �\�.u O�\Ǐd%�bΊ�� @ � �i�4si��,☏�O�� ���#���P̥ S� P�{P������cO�E���`�ҒP�%�R�^P�{���c����N��������RȕQ�,��I ż'm�ڟ �2�gN�E �����r�+�O����(O�*1�Q�%�R' �BP̅�Rm9�+������ �Y�Ŝ�)5�D�\5��d �b� �*�%q�(f~0�C�0��W_}��?_yk;5,�c}<�8=��_TU!�+ L�B ż� � B ż�L�� p�b~�7^~�� ��^{��r�����^��}z&c���B(�
��@1o�ǵ�@1�ew&Џb.�����K7M�����w���ܰ���sv�TX�@�� *c�[�� �K1+�A��ǣG��y{��r!����.��*>f����ҋ��|�avy �ʵ�%�Ǹ�c��<�Q��?�<mB���x���Q�����O���}�_ԉ^���S�re�a ��{��ЗM�+�<�p�ץ�� �z��~ JQ��;w�H5Z���r�h}�4��%Ζ�Ϩ
Gmz�?%dC�ꅕ� Ŭ���ª'��D%��Y�-��5�0! KL �l��pqY;xinX(沟djo� �2�� ��s,�h���;[=�xէ��.)ZWx�|����!!ki�w�+��٩G��b��XWŲB����e4qҵݾ/��8�SL��@1�vK���<ڍ��֫� �pS1��|� �S�<�vp ����" �i�E�r6*#�ˎ��8vI �e?�nD�� �\>���ƚ
@1s{���P�5ߤ���.Ŝ�{�^�Zud�C �k�cNc :|]1�- �7�?�B�*���vNT�uŜ�~�d�M�����Cd�c���Ōb>� ���[� @ �ܥ*��SG*f �X]g�(�h'k�`�th��J_���=�h�5ϖ�ϷE����h�^qx�~W��Ws��:�G]�� �.�(g�7�M��Ջ5�Q��
�\�-{ @��}n7�� ?��_i?��?_�Q���T�����V��댣�C;:�Wgt> �gw�Ug�O:��Fu�""|a��\�3�}�ש4w�iIGK�ۯ� E��X�<�2Ṗ@1���S3ȕ��݉��_>��o ���3G1ϯ32�In��k����ѝ�ۛT���|�( ���N �C�}�� ��~F��nF�Єb� vhD��V��{����<w#\!@� T��P�ܟ �ʿ�
�V��s��j#@ s
���m@1�vK��t���7��p�
��O��k��͗_���?� eχ ��c�u��r�l� ����װ6|�����=Y�!c���(8�n� /�UI�cop2@f<z����?��q���SC�(��?��"s
��am��?�_�/?��X��B1/%F�� t�+�b�~�?�}�۟O�����W_��ԅq>�����鵶��'�yb��t��? pC�ݣQ�7?�2�fI
�C�\�� ���y�[
=�I��\g���������
8��]I[�T�v=�� �����-�U�e����>�x �w
�b>kC\+��.q<��l��z�Z��O#��o"��/ � {@1sρ�t�+�b���~�����k�e�T��� ���k���u����r��YU� ��1lH�YlL�t����m����Y�5��ٛ��P����T&;���P̑��f2;�e��;W�n�iКn��sr;]t�S��;Lj�_� Э^w��5�o���(���0tp���SmM��a�ʵ���]�����7t;���U@�J��Y�|�y�ݜ��3[g�0���s, M1;ǜ$�qlԗ��N"�d�}C�ˠ�8�VI�О�L��c�<O��~��X&eµ��I�o�rdX7���o)Rs�z������D���C���l�m�b�m�Q�\ޢ�ÆpHGG������o�'Ѭ��b'j}\�щ
�_���cly�%�W|���#+��Z��b��z����ؗ����#~�ښ܊�D�2��
K��Ҕ�ڴ��)fy
����Z��סm���f�����m]�&;HUg �-s�_]8�"��N� ]b_�U��XR�Q��p@��_�� �1�A�9��! 6��� um@�<�����v-G1��9=���L`� ��J�7F�}{�;�7p�e��&�L�>o �Z�gb-�������95ƫVt'�7B<��t��S����!Ŝ�%�(�k'7�oMg[��Kcg��m��\qs� �& �`5 ��j}�!�>o��'�� R��>�N�D�ʜ���5��1�b��e��Sw���"�~I1+$#�,*��]˷�;W����nZ�-=-�uW�b��2�֓���u(f�TU��EI���'7��c��6��zmߊ^8��� e�0���������rU�R��]�O��)��F�B��mZ�����Q��ǙhZԺ/�Cw��O�UR�] >�\�㙡�r��S��.�v�M~�u��s����~����@��2��z��r^e*ي9�S�Q�v��n�m.K%�>��|̺���觍�G��� e�,�X�;�^o� �pۂ���#O�� �ҳ>f ��(O����<�;��p
> >�K�og�p�n�#�6��n� ���h��Esz��[��>��>t ՟�������w]��� ��:Ψ ߮U��τ�� ��;����q�x�n"����7v�{z&�-ւ_o=��p� n��t�+c���k�|3������1�|�3K���}[�-,�m�L���^ݎ�Lj^5�#\�>��� ��seL�hV߇��:�ɩ�����N 5[+�(��d�b�a̰GY�����<��D�cs�9��\.��b�,C��V�O ���T[w�q�j:b�O�"Ғ֯�t1<&!�m��B���W�� ��z(泽h�vW����1/�
�I�dcm��WH��ˋx^)<�b��Ïa
!�9� �<q���bV���s��٨ =Qt@�W�,Ṟ�Ej��8'��> ���.�YH��X�b>��C�2s|�u2�t ��(�L����HMO:%�/9��S�m�k?�0|F���?�_>9cŜ�ܣWZ����nt���b��Y.Q[� s�w̫�@ߊ�K;R�� ������Ż���^��d�E�5� H �<i��i�`M�z����Q�F�s�+���^�/t���E��Y/§�3�� ��Sg���n��%[�q��~Nwz�_�J�k�z�c8NC�^8Bcrfb��\o=��^�yOk�*3�yW(�o�|8���u������7 ��]�ɾ�����>$( �.[k_7;H���gV���ȋo��e�]��ӈ�c�q�S_��-�O�̈
��vyW��j�1��9=��� }��Һߵ;9��8��Ս��ʸyף�!P���;�Ȟ�ΕqȽ�F��M1[ O�>h���/�s��SS��i� �5�[��q.^�}c���L ��S��Nny�ӫB[��Hs�����u�>�V&��3a������Uޛ�zM�{ީFhk�\����K �<�
�>�E`�Dyo������N�_�4@bf%y��F6筟�j @� �rv%�b��c�
��;WFC�qLSkS��:\��b>��
i�c���B�c�U/�y�M{�b.�I�ھ � ��m�p*�?��N(f�P�u���r(��U����+�?`�>P̻�ő��Ȋ�{��YB�C�� :�^ ���VZ!�b��y s+7
�,J�\(�] ���ד5��ǻZ� I��~�-��8P/�t��Y��,;�F=�-?�u���ȕ��j ��;�b�>�Κ�|���3M}�w�1Ͽy�]�� ЫbΕ�"�d��wł�'W� ���%��#+�4��$�g����(x�k�jrep=�@ߊY!O�9��dgz�ɛ���L$������%U̮$�ujg�w��}htÉcF1�J`XŬ;��&��{�nܚ����|���1 �i�cŬ�ml��G�sd�Š���>����Jz>�؝�.U�ޒp�}��B1�{�G1�����}W��X/��S`�F �E��j�n��,�E ����@}+fH#�B�5*`ݖ#@ُ�_��M|��6�Q��O�%�3PϞP�(�] �����J�N�hՍշfߋ��?��Ż{�h�N(��"Mw���N�n���H�T�u��pǬ?�ܹ�bq8�#ڪ�&�U7 D���G��W��������� 6��?}��uhRޜ����>�^UOy�I �fWt=�aI%ȕ�l=��P�ٱ���b�3É�v��;Y�3�b��^�� �ʸqH���9��<T�r?�� :HNt�n�A`�D*6�>��h��~e���b�M;<к{O�� �JT���;re���=j�N`@����.%@��c%�����|��Z�s�Ք�[�-_F|��×�)�c�# �C;�:�k�s�~.z����"�ż]�QC (fn[� �yp�zl�{U��g �� �9�ȣ��P̋>� ��Ŭ�'��ٟ� �:���F���]��KI,�Z|,���8� �9�ң�<P��h�N�
c��O�$�g�Z p� ���V�%�2���X �\�Yqc����~x��6�%�zU�&JGd �^��V� j���YHn��B� s-w���@1o��syCȕ1����R�F��>�ޣdΡ��p���o�I���,L���c���֯5(�>�S� �2���5۳ҊY�%+'��'��S(T����lյ. K9b#!Q���u���]oV�%ժ6����˧��v�.�^Ϲ�Lv]�s e���+�F;(�f�b����
��؍is�*f P+]� �6�Nʥ:Ѿ�ͺ*�$���֙8�2�ש�>��W�Ϸ.W"�:�S��Fu���R�7���ېsE/���y �<��>���~ީ�N(�v�Q�Z^T1K��GQ*��8=Z6�QRzT�`;}u�R�����-��83�@_)iݟ6�Ȇ�����Y*�b�~�E�P̅>�T[��������| �&��ɕ]�S�+�m��4-�S5�jk��#L=��Wz�Z1_�ے�OcE�b�T Ŝ���zP�]�n;�b^����͕�P�0u@3�Ȝǎֻ�ߛ��/��ZQ���TsG���]R�g7�^��/u�6;=�d�!%�zq�&�TM.?[�s��.�+�[��E�P��� h}O�se�i
mA`)���Y�Q�PP�O���:]��%}Ѻ��q���!�?��ӆ�'jHXm����봰5�j��~-�v��/U�Ɓ�J^o�:A�&�A������g�����ѡ�QX�ׅ m�(�>㴻'���2���� ��� �Ҫκ�%s[IK�=�E��k��ɕрl �Ds�w�C`n �(��lW�.O�����㨮�hw�F'+j撣��c��?�� ��{[��`���(8��C��|�����Ћw�}wSu\ �* �S�Uv� �s(f�AsP��
�
���� � � � sc:x�P̃O��O��G
���ݻw��_|�E�@�K�ret��N�A ���8� re 8�t9��8��TztM ����9re�9���Jnf ̣
�P�]�+c(Dt�� ����K/���3��ū���b��V:��= ���� �/��?���������� ��� �J�h�� ��yz�,s�C��_�sB)2���o�Ǭ;�\q��@P����=�P:��Wd� }?� ��@�4������y)f?�{��|������ �������f���#��H�\;¦�|~�(�M�܉B>� (B>��5A�`��8x h>7Mi ̹�R� ȕ�e��B@��G?���0�wɥ
%�%��ݻ��,̩�@^zl�m����VKm(G�\��Rs~��OZ��7ߜS�;Ｃ�
S�2�� �2j l[D@�C��%C�s�?�SA֟,H��|y�]F@���_��Enc݈''�,Ʋ�(
���\�h`�J
��C�M��Zy���@�l_(�}y��rV�rE�MVг�K�rK����K��(�N� �ԝf_���-7��:A;C@1=��w^�\�z(O�< d˯ܱpB �̔h��t�j�Ћ+��D֟�;��[N���z�� ��0��V�] y2��l�vwM�\]o���-��B�I�d�b�n�ѱ� �+���4I�✙��c<���@6Η��^$Db�I���� ȕ��"u�#��r0� ���b��|=�&�'@���L��/ 9͗���,�,j���N�8ffH-�N�y�k�=Y�] �@B�8f�C���'�6#{%�b�ud[ꗟt�'qH6{'U��\-Q�֑��G�V�Z(ٮ�E�Э�� ��� ��S��n�Jdql_#��� Z?K ��Ĩ��i."����gB߶�+���w��J�{�ÆqG W��i�6��S)�[C�{g�:߶��A�\9(R�l5B8DD�� ����� &p�v}�q��O&�O� W����n���v���2ı���A�\L����4�G�����4��}C s��[W�K�Twʤ�C���� k�#@ s}c2�E��ږ���p�\h�Ç��N�Q��b u��w���8JO_��ˌ� �
3��^顜568�mVU�c�@1g�H% �1u�-��4�O �<�%K�7WK������F�ѧN W3� ��X�KjA�6T�� }gȟ��.����XC�kr�Bm�˯?b�F���ȕ��L��*��>�:�W3�%/� j�C (K �Rh㽲-e� �FV�T�
re02ȾKjf�rT'�_��r���"ȕQ+�^&��k��!k�`☛�f�,�Kj��W̉�4���o�:�b�%�137v#����n��h�F �#b y�s�}�]Rs���.;��!L�*�g���;�Bm9z�����a� ��y��.�͝wI-ؓ�U;w�Ǵ�Y ��@1G<|
V�i�v:��6���y �+#�ak9d��:i�F��Ǐ �Q� 5m�2� �ʍ�Bm���l��;����a+�+�������wI���/M� ���m--?��|?�}WN}a+��N �3�<#ku(k
)S�<4��� �'�pml�6��@��a�~}ǫ�%u}7�]�� yk�Q��b nW��-���j�]Jzʍz��
J�w��ա�����B� reT0�0�B�t���P
����t��\pwճ ��!��9M��"kf/J�� ?�cw.��`A.�rۡ�\b*[� �'��Ypm �)X�q�
h�^�]R�ʂ��:���ɇz`�^��>���^x�({�B��4�1)�U��(�flg�P{2��v����ΦPtGQu_��^��-��c�b�p�� ���.��G�;*���_�D~뭷 �(�,M)��~BT8F�Lҗ�>&r9�0�A1gG:`�,Ծ4�5�6����:�Mwr-�3�O +��2�^|��2z��3뾎ɕ��,=���%5��Jr f�چ����\�駟Ω��R0o���߬*��! z)f�e���?�|����+�^�A�����\�#D
�#��fݑW�:{!�2�� �6j� q�6t�Z��n��z/�c4��t'o7%��W�g} K@�kre�>��� ���g�(�� J��B��9��ZIO P�����xG��ӳ�;�.w7 =z�،��O��-�E? �
,�v~a� �u1��jK��P�j�`��X���Z ��H���2�
���nN�>������Nt����X�W��!WƖY��K�i��E�����GNO���(�zjU�0��9FP��-:����?�
Mƫ�#A��CL����3NU6(&�7C�I8�%}�����?8�G3ǿ�}\t+���=|���nC�
�ڐn��l&���X�Wyd��K�%i%'�� ���O���}�x��t1���gq2��b5�qS�gK���� O���E7 b7����65�J�#�L�p�T��յ~���?�v�� -%Ѭ��[D���e���&?q�Z�o u��O�f�5���_�7�Xx�6�zV���H���HMu�����WN����=�� �
�}���ˤ���9;ã�W̢n/�.��w�;���G�%��K/���>�־���Z՟�h��ڒz�fI�St �*u�}r�i+*o �SX��5Q�*����F�P
���y�&5�o5�3�N�Tktd�ɋ�N��%�~�iF�R�E)��\#�ǻYjF1g�8B%N� �uN�Ez�eт�͒v`�XL���95���ޓ9�Ӯ
E��|s(�����?��h�ߒs��,��' ��l��b�>57E3���ѩ���>��}�bN5�nC�^��ڲ4 8��Z�Z��Z�<
{�Y2�з��Խ�wF��H��ڷ�0OH��=J��ȅb��gD7���*Q%gd�0߉/ٮ�P�Q�� ��3�N=��+c�mU� �E�ess[C��g7�|�7�_��c��^
g�_>���^ЍzQ��[��K��&�fX1�/�:��}qh��M�t(k.�_� #WF�#��m^ +�6�qS1�#=��9*#��Q,�Q��-�fI_e-� nqS1����u����3�PAT� )\��/����&^{�]@w[�{�]ⶫ����kwI�
ԧ��V��U�+c;þkp^��'���n��a�c��O�� `7����w�g%�f�9mnb��0)�*��l�������t��yr����2yH��v��U� :����T݉p��s[~��?�ۼ�By7��nFl�+c;�&kP|�n����U���6Dj�'vT�ފx �;�g><��m~�tV1�,��x��9�3\>�~�b�?���])n[g�gN��1��C�)�GϹvhZ�1����6���~6 �4�B�Ou�}�qI1{=��c82uƎ��u&~7Q̾�Ww(9�q=��JI�|Ū�V<�6ر
n�*3 N���bܖ��|����`�uLRU�-�v���t��_"�� cN�}=���O���8ȕ�}��Q�j��>�Z��ߤ|���7n��uI��C�t9�o��ۖ�@M��fz����ۥo�q�?��F+z�[��і�Ѿ���Џ�2�`��Z1�ڥ.��g�|����,��� �@}�nw�+c��j� =����П�ɡ�����y�-.n�qN��.I F>��2C�<U�Q_�*�i+*��QRWH|�B
�1a�%G�ͻ��,�4-�Z闈 �ڵ� �| g���K��D�+�'����i��x@6y���T �����\:�g|��F�|�����n_)��p5�� �ΟZ�VTL�L�>*��n�~���ڳ�
a��g �]�t���=�\QO����� y(ө��G���=��g ���#�9�m�}H ���P����O��� >�r ]fr�,W]��G+���6L 8u����K�S��Y��*zB;3�q�l��]��a��䎗X|�۳��Lv+� �y�Q���}�3���<���̼��>�rXU��a�>�gsԝ���4dYJ1�o&�1Mr�Ӓ�v,�����N���?i4'�m�37�IY��w���o�
ż`O�;6`沇K���4���a�bV
�e"X�>��KZ�� �T1�9�:Ŝ�D���ݯظ`�F ײ;5N~�+�}�]�b��Fz�/{& � �ũX�I
�(}��XFz��V �$��X7+�G϶J�H���E���lӜ�� o�>?۲�@1��KM��'��:� �sI1�a����y�oT�
��`��O�Y �͒��U��C�ر��[N��2ibӉ�"�
!~꓾91��R.�V9��� p|�~ Ń囜�,��Գ��ɕ��( ���� ��~[��Z�5���?���/�:� ���aݬ � �s�T_��d�_���'���ӯ�� ���֕��%D��u�{��9Ζf0�4I%c���~D4���uZr���Pχ�jh� ��%]�%����k�J�6ƞ״�+q����'�f� ) ,���ڸޣ\�}���4����� ��Ů{(ȕ��gK� k�]$Z�˶ʷ$*1���u �.�b��w���G�� ��<P�DH�K��˛� �}�,��(��o�ј�p�J�n%�[�~Z�JfZus�M���Y��;,מx� /献��䀓_z�59Y�ٛ6�2�2����ҖՂu/;�>9'����Ct�(�A�d���#6�e|GN}��/=�}��
�26l��c�jnڱf�"���gn��=�N�.;��Y�\� L �#��n�^�t�LбC�?��c���ix:q���U�i�4���? nf
N7�珁���FWk��W����$�m�Y�����kل�6f^��Xd��8���s�@F�^#rCg Ǭw-�#��:�\eᜒW��� d��\���0����k���4v��N����q<��3������Lj���� ��TOG�@ݴ�^���Ĝ �]�b����2G�-[��b}f
�,�{���=)E�3~�?�e�3�'���K��s��B�-8M��xe��@�>I�U�W�_>�f�lM(�-C�ܵ�{�?esx�1X�[9|�;����X�qt���/����/���M6aHW��b�I}5�9@�h�tw2UP�|v�je��e�� }�N}�i,�4���b�Cv V�v ����>)j� _fL�31{�& �v�=� ��Υ=�Z�Ss�<���2��]/�żW녽nA��W��n���~�~�� �)�eU(f���_����$N��N��!�W|*��R��b>�#c�y�G���8ɕ�r3�휶,}�O��z�sd �k?��Jgk�xjs��� ^e�;UW�q�$���T����^�B����D1���/Z���rS6�R�n��9�/red� �W��e�4oI[����;b� �VC�&�� []� �
��[ٮ�V$�ޯ�Fv#���ܬ�7�&<I��W|�H0^G���{�<���]�K�:�E$�) i�J{2�a�|���F:!��uZ� T'�nCѦ�ӏ�W ��� Ǯ�zm��[����aӨ�hH��Π�$��E5��,���CO��e����43��JU3kp�Tkڣ1���2�}�ǭ�)'��'���OGٮ�d� ����Ƞ�vX�g7���t����s5�>�d��
��N��$φt�+c��k���d�{ �ۮ�&��`ߞR�:)vI1�֧��� �w�"���I ���0�^&����e�04�ȲE�l W�Ɓh�rOK�,um�Ի���ڥ�lT����Q�ek���hQ[� .2cK� �5t������W��Y�D�T�}zq�KI�Yޞ ��u���PB1�����fQ��!Q����Sq��-m�*��!iz�I�D1��'t��Ȥ���dY�vsvU[@BG��,+ip�W;ʻ�9�4mY�6}g���C��⼻�K�_�7�S����ܷ�*��C;wբ�;��/U��k �#��q��8��S��D-�i� ��9��M@ �6���˜~�5@nij;p���bo���dD��\ �}��슈�~�v<Fܣ�<ֿ&#O��;�RI�k����ʵ9X�t�o � }�={�v�t.�z��.d�j�{ �tZg�Wi�� �.�b���lqQڲ�m��h�C���7�?O�1�5گOo�g�LO��U̗BTm�&��j����χխ�sOj� �]�/���K��z�JҞ�*f' �?�=%��׃�,?���S��W͜�V���kG1�F��%���M�����C��f��VG���c��-�裏��Sgw�mP�n�4 �N:Y�����ݞ�j:��z��ࢽV�zD���:�b.=^
��eWV&E_��
P�]�/PɈ=��"�A�gs���L�|z�䱞�n��UszWW�ؼ�O '5� > �?�N�djm<f�[��l�|(�]9�ݢeve.j��/�&WF� V�kd��C�}���]Xj���}�UM��+B�&�Lkcwȕ�`�G^�+�O�*fiD?�ӻz!A�b�����R��r�b���s��M����7sک���LnΖ�� J���I�\7? #�/{ñ�(5l�U�'(P�X���.#�<l,�n�iH�sT��K�?���L�,��w��ˡM#㧪�j���jʸd�b>�6�ͮ��8f��
��xiY��1'i
�����=��3V�\�]���0�Ϧ"��� l��u��A�� ���&z�|�HD�k9�����v�f�n>܌��w� kf hre� �v�Au���"����ELps����m� �1ى-.�2;���>��U�QsYq�ڈ�s���8u;��lp
N'��:�S
�N�_K�T1��QI#{=)�y�j������'5X��
��y�{�8�G�����zģ߬�])WH�!��ҨnF�g�U�bU�J �X»L s�a�*�:=�P�����k�0��?���(g;�L僚��-&w���q�.�\�ڬ�U B>N�
�O[�����q&ݩĖ،�y��l�»�]P��̕����4� �+��(�$)���%A0'� ^"���z�ձF\:�r�(CV� 4�hy� %5G1/�ic�Wv0}�ڊ�
v��U=÷�t\��
e�����%���\�&�b ��α��*��,�x2�5� �$�������?�?�C9� )f���^� ���[u��T���@c���� ż��`W6w����4M~=#�u������M�Eoks�ا��:{�\� Go��'�H�ӡm�ͳ�� J?*��B�Y!��Њ��wg��~�Z r*?��_��H��҄;��\4 ^w:nl������[[�,V u�M� 5�+c��/�'C� 7jL�����O�[�����%@�_�y�o}�[��w�֩H+fy_��xkxy�H,�XA��� 4}����/g>�� �\+>P\�
~���wI�����L� ����~�w~�@r5M��\$G��D=�F�ǧgq�/���rj�&G��)� �� �yѧ��� � �%"N���� U����k�] ��?�� [a q�+�qI9��i��8�=��oF]��Q��'�_� �|s�P`�1ˣ,���˅2$�BO� �`�b�͌bf�o'0�s�]Ih=����h��,'�n��?ơk�;��d�V��2��g�Q�y��je�2�y��^���$���M�P�ڭ�|�P{8��p3��7�.���7%t�J ve\�4��s������?������^�}W�L� >� t�1��r�rh� ��f��܇��\���=:�Lr�i!� �U�Flg�ª�G�9� ^�ާ#��؇�@�ؓ!Yٙ'C?|�)��&[�l�8��p3� �Z$໙���v7�'�,Ԯm��5�������\����ddy r,/�ś���9v�������Н����������5�V�\��H7�h�PO�F�o[U_�V�u���cnk:5i�<
�oד���~��$�`�گ��?�G�1w0��va��>�j'�İp0W�fF1�2���ӿ�K���l�a�O��Pu�sG�IW��8����S'S��`��͌b�4�T3��n[JĦ�MD�ys�^�:�1\=A1�0��aG�� 7ȎsgSSs�nfrelc.^A <�.�է�
�W�l��t��ɕQ���դn�)��~�� �Q��ru:�ȕ�м��Ty2�P���� JV�D �a�64+��F1��;�@` �����=ݚn��~�Ҷj��:{A��:�e����5tXaJ��4��:�k�Ԗ
�(fre�5�V �6�Ah�G~B(��`n�f�L Ԭ��cf� L@���u���n��h������Q����hV6�� [ѠJg��Ʀ�(��G��O���|� R �
��d����V6�: �� a���1B���b�e$�GI�d(s�nOӼQ!Su~��=J�(�QF�~�B�N�Ǐ ��ڸԿp��p�)P���3�2�?
,"���+6t�m(��"�N t��ɕ�Į��D�s%��~B�P�u%�X�5+fs#WF��gD����}��'C :�&in/���>w��7���$�(���Y�캜ʃ'���5S�f�L��f��h��'#��ԭ��=� ���n3�2�Oj�N@t��S4��g��/U�'�j��d��q赡�3�2z�u��KT�9��d�'#vI�g�4tc�n3�2f�6E �M��HP��wh�'�;@>� �i�y[<;�Лg�WP�}�'����. y��WV�=�ٕ���,s��K�v!�N�n�ڻt�F�@1��K�H
{� W�2OG�n5+fre�0���|OF�p�~�
ٓn3�2���MvZ�
�ȵ�zϐ�&qwgtٰ͊ɕ�ݤ�C�=%� v����u��{ $�� �6����B)v7�u�f�L������YOFѴt�o�@7��\��= �Q��K��R�, �� Ԭ�ɕ����_H=�l}��t��ɕ����� �� ������O�/?cR�9�R� (�z�K:$ O�o��o�[��m{�!v�%s�K�Z"�'$�q�L�7�vF���Z�5��(�ǟޗ'�������BcP̍
�K@�W_y�e�8
��B z��/ z6�@͊�\���B�@1W>@G�b&W�QS�v��F'r$+�ćj��Yk��~� a^���V�b6Ure�;����P�̃��Q̌/�!*�������n:HG��Y1�+c��rm-P̵�Devt��ɕQ������O��뿾4���V��z5+freT?}0p� H#�F1�+c���u�->��"�[C ż��@`>�|VC�D15�t�!(�kOSQ�{Ҧ� ��G �}F1πD @ �| ���Y1�+�������o�n3�2���v����n�Y͊� #WƦ��� �� �:
�F1� �� �y5��/�Y1�+��7J�P̣���~v��ɕ�p�)^;s�#t�}5+fre 4)h6+sV��T֍b&WF?���|M ��D8K ��Ā@Y�b~�� =z�}���/���� \�j�� ���a�(���� ���(K U̟~��$�|rn��^KtY;��2(��s � ���
��ɕ���$*�7ސ�Y {�������֡>#߳����}Ht��ɕ��� ����՝�}��#�2r�5� C�4�ٱr6��zV��L���E��8`㭷ޒh>�zZ-F��\�C��b�ꫯN �� 30G�Z�b&W�ѳ��s8U̎�_�ű��]X�ӧO�{�R��ꨈ@7��\�*L�A U̓P:UO4]�M�Q�b&WF�S
�'��ʘ,��8N{��r�+Z��ͫn3�2�����h��t� ����}��N��#0G1K"+��6I(��4K4�g1-�B ż f��b�q�~ ��4�N�u^wo�/%�f� �t��W���!�� �Q����F�{�^���;�\˺)� ��a`�7P���I�T1;6#]�-��Q���� r|(�Ν� Vl�9����Y1�+c��raE�*f�+R+����u�
_��U��\Q�0e3�n3�26�*����\�� C���r ��No�u�
k6�Y1�[���0�\Z���`j4��\#\l��g��Y�D1�]�Ҷ�YO��l�ҊԬ�ɕQ�D���P̫�}a7��\}O�{7G1{��xT�F�ʱ�D>�4!Ҁ��r͊�\�ͷ{�b q�g��L���M���Q��4���x��8�Y�q�-�� [Q�3 Q��7��RsϣK�Z&pV1���D�X~�tC���L s���vs��J�*"�b�h0j2�\�h` �!�.�̆�jV���`�@ ���(�C7��\fU I �|$��ۮY1�2*�>�6� �y��t��G <��5s�û�s5+fre� W��� �����ʒn3�2��W�� �y;�.k�Y1�+��)7\�P��
��w��ɕ1o�)� s3C���(�}y��xP��� ��ga�v'�b� y
���'�l��{�w'9 >|�b/��s!�T ��P��zy͊�\�κ����/Z3?��3
� ��t��n3�2n
5�7F ���en͊� ȕ��\���͌�� ݶ��F1�= X�(f&�Y5+fre0i{ 73� 2w �Q����=5��0� Zy�O��?y��g�E����+#P�b&WFe��As~�h!��ǿ��������A���y�س��(fre�<M��[��)���ݻ��� ��� ���@~�W*8���� n�P ����(檆c `�m�̊� ����-b�ҡ�d�/��n�c(�
�� `7�o��o*�h���yjV��ʘ7���@ Ōb���эb&WF�� ۖP,���S���?����?��ɓ�5P�W5+f3'WF�s�x�P�(��lC�(�
����G?�� � |���2����Hg>�裊 Ŕ�Ԭ�ɕqФ�Y3���܍b&WF�� �fP��<�o���ir =Ey饗�ݻGN��0{-V�b&WF��n�~��Q�;M�U�t��ɕ�j���
��2�Ÿ.������oKR�b7v�N ż;r܋ �ż�\[��y
5��@>z<�0 ������g)5UA �\�0`D (fs�y��Ns.���V���~��� �X���KjV���hzj o<��|�,�lA7��\5O3l;%�%.��w߽� �^ Ԭ�͜\�ν�B1���O�
t��70�R�J o�4�Ʈݠ��Ԭ�ɕqФ�Y3���܍b&WF�� ۂ��o�]"���4^���7��&P�b&WF�s�x�P�(��lC�(frel�\�eSVz� ���O)���PY�O����C� �y�4r3���y7�M�\R���ZzT�<ʒ�;lA"�,�,ݬ��k�庪 ��� ��B Ōb�2J_�b.M��'�
��_�r��� �vV���5�l��v P�b&W���&�)��?�����z�7ff�!5dm
�J�Ѝb&WF�B�K �^'��
�˅a\7IA�[[ɞ �X:v5��Y1��2j�?U�VH1?z���_�R�zq������}U���E���ڡp7�yV4���1@���]���� Pk
��n����@͊�\�O���+���>}*�����^��u,$�Q���upU7��\ ���`�*�rU
� � ޅ�3�2� mPB1K.+ #��駟�Ϗ?�XoI=�П֯�����[.�?}�* .o�m�*� s �[��F1�+c�4��,"
�0��p���4�4/��P �y�Q ��%�n(��N�[�9�W_}�zm��d�4�/qD�^��Y/"�#}�q�P�af�
Ŝ#� N���vv��q�鑷�(�<��";+��p|�հ�g��/a 力���./=mGu�Ŝ���P��R��Z����^v�k��5+fre4:�j1��bV��$�X�� �\g\,��UF:XjXA �>�T1
nF1�2/iG7��\�M��iz�%�V&��;��0��c͊�4ȕ������9��&Ia�`��Hs�:P����4��������~�3��&��߸4x(�ڦu7��6���7�nv��������w5+fre�4��K Ŭn8jB�V���:�*f��|�p/�s�����>��]�6\�+m���9#�,Uu��ɕ�e>P�Mz��s���|�p�ّ�y�- � R��5+freT>yj7��bV�%p� �/��>�4#ih ��dz&��d�>�3#bsF�Y��F1�+#�|����3N Y-��oOiH4k7o� �5@1�<:ض�@9żɬ�.F1 �b�(��F{�$�0 ݾ�/I߂RjL�4��w���U"�bftK Ŝ-�����b�mD��6
ZP�t��c�f[ {�_�쭰�A�[�a�:kV���(:�W�bF1�<˻Q��ʨy��k�}�
�h� �,�j��:8�^U�b6re ;Cn Ōb�y�v��k��m-�d$�Wq���_�v�s�6�ɕ��r3����x��n3�2j�fm���
K�b��,/a��Rz�
R�Ҟu֬�ɕ��L谭���;]��k�6N�^+��${��'�N'�[tǼ���Q����a�����ώ��O߽{�M�psÄ�k쯘S+�wy�ݷ���~�U�g�ڭ�y7�4T9���9@����=~�� ����@1�cK�ȥ���dl b�ާ�����?�� I�{Nw��f%>������:��$*�f(Kᢘ�+] �\�0��O@~S�!VԲb��X �������.��\�z͊�\+�K�!�E1[�j��w�
���^x�l�`���ׇ�ҟV�R���ƶخ�� z7�P����ܹ�JTƛ�7�F1w0ѻQ����`6 �� ���
9��F���4t�E�]h�����+���u��Y��i�ƌ@�ԝ콯���e�"�r�P��V��p�N��:O�u�b�"�|����|7�9 ���n����=��mc�<So�f@� $H#�Y�Ԭ�ɕ1k)t�@.�,�MXצ�VB6s��
�k ���O��g�N�����s s��L��>&�>�����7�7%�#�m���p䛞��y���}5\�Y]O�7�i������
�8�)_yq�,��`y�*9jV��ʨd��jFŬO�B,��1ֻq[L}�Aʑv3���tU��Ȥ�x � uJm�d��U��8l>�V'ebw7��\ �� � ����Z���s���C����W� G�y����ޖDI��Q�����
�E����J��e*J�1��:KN���wk=֢�� ,�L`�b�[�^�����֩V�ү�0�vv�_|�]�.t
V�^M������2�8Zw�/�
�s�rDu(�#���1E��"�H�X�a���R+}2M�y�X\��Z�y��uc��l�C���U��N�Mڊz��$�-g
����LZq��u���uaG�o�Q.ꑿO��lJ �Ws��3y���b�2M C`�b�=.��V̾����>�֯�g�>S��
����^� �Q[>���9���!���� �\3A�V żj:����r�j�Z8A'�9l�Φ�|� ���^�>��D���Iל_��'��'Tz߶1~���m�j�$ =m+걣Dm�6 �u�T�(q��� J�W4�۔|a��UX.|�fmx�pol��&]
P'�N��L<Y��sy͊�\sF�2 ,U��Q��kQ��#���D1o�W��n3�2JL��lh�@�K�9�V�� �pD���հ�D8r��5k� �ppċ(�g[�b>
�=�VT�:S���
����F�QW��(�aV�ộ(f���_Mg�Ӹ��j�]�M/ ��R�[�s͊ٸȕ���.�S�^��{>��ż�^�k�Q�%�Pg�����<���%Ŝ��X �n�o%��cV��s?�Z{�W(�-N�bhζu�����TV�PG�L��}�J�;�}�Z+�0 �d�xG�FS��3�T1��q���x�^��3X�b&WF�̃�/���ت�Q̫����L�������cW�K �'B��B&��'�,-1}L�X'> ;b��T� '�n��϶xV�^j�T1�Q����I���K�
�� �����k�����mM���9�]/������ǚ3�2��ݶ�bN��\�D�F1�+���u�=
���3y7�oJ�JCG�:!M+�㉼��INم�>FrO��*�Hm�Ҹ��-I-a�ų��R[��Yg" #*�!O���k�X��O�z���
Ґ��Y���S� kC��C� �k����\�ܢ�(�E�(�3���b�yt�m)-8S�8->���F��](�w���G�b/�X�&�?u.�r/<u�FƷx�
\��
�-JÝ�b�m˦���ǵ%aU�/�~9��T1�'��XJ�b� J.K4K:K@/ ��;
��`+� �㨌D1��&�bF1�=疴�b^B���P� ai�YA��Q�>����ْ���Eg���o�lə��3Ӽ��
�P��B5q�pJ�f�L� ��&(f� T��n3�2
ϔz�W���I���7�5wx�<^
�i(H��A�Y1�2��0-�bF1�<_�Q�5Cƶr� �Y��[�f��U�F�g�쬰�3�2*�0-��bF1�<_�Q��ʨy���͒�{Y�0JXH�7 (�\?x~� ( �LڋG�&�C
�+��4�bF1�<��Q��ʨy�����e�_�r�܇�� ���[��?��L�H1�6 ż���VP�(�'7�������]����� b'�o��I ���h�Q̍\-f��Q̵��sv��k l�C�{�)m�"s攟�q*��^J�v��I��'R�-��R��:��ȝw��J.;U��b��0c�T�re� ��&P�(��w7��\5O� lS�2��{�)�n�b��
DV�+깾Uފ�uɢtog
�\H1�^�D���&�"WF�T��(fs���6u��k��m���Y��Ei˼m�����I��q��[���
�m���/�~x>��/�W�U,��$�U�q&5#.w�g�r��3 P�e7�Vb��Td��;w�x�3���z�X�a�F�0�}>�B����4��\�<�F1�+��i��mKsh��Y�R2�k�B׆��
KMJ
�Ll�lq�3�֛E�p�|;}�[^O��t%��v�5�}�5��٫\�����~��Q��6u� �L}̮$�J�,��91��3���'@ �̻jQ��g�=|y�?��8� =6�v�oW�nvg�Q��ʘ=�C���9�^D��o��N
5y��wC1�.z�$�y����LN�JGK���KWY
��ĺ+��U��JO� �|� �^���A��!>o��$�y��.�Y�z�T�����f�Ǡ�E(S�*(�Uظ�3�Ls�< �MUr�vl��R�<q٦��g� �>�=U�0��z}��[vK[L�Ǥ��&RA �R�i��k�C��Dsn��wk�#Z�ͪ ��� ��L@K�^y�+{˅��TM�sák�*�P�*�Tk�5˅�EL��*�37�R��yR^��!v��G�1��H qS%��GK0ًq��m�re�7fX|J �̬8K��L� f������̋�BNz�.^I���K���UI, <U�Q���$��.�d����Y��r��qt�]����^/h�Iv�_��5 Wrz(ٟ2dk &�0��H�+cء��(�N2w7�Q̹�P_o�e�2i�n�! �,�O34˟�2:�䦗�IpK�Z��� �Z1�Q2�����[v�p�V: �,x��RM/� �����;z!�U�da�:b��^�OT���\%��ͽ� �3� �2�q�T�P�u��a�u��ɕq� j�����˦ �m�X��W�(��:��a�h�:j!@ s-#� [������n3�2:��ٻ�=�e��b7 � 2g+��0���Ç��� *<� ��@�4�� �9ʾ*B1�5��f.ie������^C�_%�G�
��*�@@P�L� ��{�}@1�J����ݻw_}�UEk4ct �*U�~ohIe �`EȕQ�0`�F(� {���L��^����Z@�h]`7AE�)JZY��(ʹ��ɕ���a�� ���g t��_l! �,��֮5�4U� g���?o2�dy��a�%��ָ䳳�Bre�1����<� ��n3�2��� ���-E���x��:��ގE5�/
¾����{ ٱ��b k�g���L���cN� u�1��RXD�c�-]�m�� �<�һ�3J�,�"��+�V̓ �g��[=�D��F7څ(��F����� �ͽB1oFH}P�a��w�yg{� )�A���w���:��a���x�>��f�V̾�{�ݹsg�ٵ���n�j� ҲHVFf�9B%(�F��>��� �U=D1���ECP�ƽ{��ob'��Pc��jY�^ ��qZ�e���9_ v��
�N{i��ĝ,g�ޝh���N�H\Q� B�\� t��D1w>�k�b&W��)�u7h��f�:5D�d Y���g ���<29cM�*�S� }P����+X��Z��/+ p�j��X�� � �b�b�3��\ Z,��o��z�T1�b7�ã ͏ =J}�rN�T��^G?v�}]
\52re�<��� ���Xf�I7��\Y���!�9&O�27����%��
y� \�#�( 圞Qa�;���Ţ�4��ҋ�sa�N)��;�0V�� ����s�X��(fre� Ty�������^���+o���dMV�NJ���gT,�D�eۤ?���:HڇΤ� Be��2Ge�f���(v� ����s�X�(�P��ʡa��zW�����B=�@�]�rP���R�~P��n�%sSÅ�p�t�v��J�+�t�� �F� W3�(� F�@ �Q���(0;��6�F}���+��� R �+c!0�WF �\ـ�bN7����1$�+�Fq�N��({�!��k�+c
5��� ����Ğn3�2*�QÚ��ѕ�p���� ;�t�&�o"�@P�
�&v��ɕq���)�3�!�P�-������L �\��`�\(湤+�b l��� ��XQ왧0 eYg� �h� (�.�q�N��������(A@A��J7k���ϩSA��WV����)Ol$@��� ��
(�*��>#�Q��ʨora�Ϸ@�{���4��3�^WN��ۥ9�+�9�6s��W�ns1BT ������ �ڻ�u^1���ʵ�Os3,��(ȕ1�H��Os�㻺w�(fre��\�=�V�9 Y�+ל�����ߥ]�S���,L�H ���8K��L� fx�B�f,�G��O �%�b>�?��!�b�ñ�ZP��
) ���~�)H#c���Q ��ž����cO�����&sW�Ig�!�eeށ+ �!��� W�~�i� s9�M�܍b&WF��pL�#��R&/%PC���6S~��d���&��ۡ�ֱn�6 \
��H.+e� F��!�0p4\ re�7&X�� �y9�!��F1�+c���o'���B5�w��]�� z�� q� `Q�Br`H.��C/��6����t�@7��\L�� �W��jQ��
�a(��ޕ����b�P̽��(��S�g�y��/��l �xS�D175\�?E�+HC�[�� ��}[ het�n� =l� ��١��_��Y� �@ %�bf>@�B��ZH"+ C;�h��T@Wh0&A@ȕ�4h�@��q07?��;Ѝb&WF�A}P�� �� <�쳊8:������XB���px\}va��Q�s�y @t~�TY� �2
¥���� ��V���
�B��L��V� v�'�b�ϊ�5 ���Q���4�_��x���D���ŕ��F1�-���t�g�j&A[P�m��~C 6��lDJZ�� Eh�!)� ��i �j ��� ;K ���h���)�i6"%��[J��d�0:+sV�T��P�9iRWy��(Ϙ��P׳�ǬMY�q6U~Vs��j�(freT=�0n�*l\t0re < 4?��t�M�$�OS��i�2��F1w3"tA ��dh� �2��q����x�tS(��W�Ƹ��y7��\��n��b�vh;�q̝lG��PJ��zS(�
'l&U~G�bVW�Q�h�Y�M��0��.����IP/+]y��(]E�nT��² P�L
TK@ ��"�Z�0 (f�D�
ES���f]%�bf�@�Z��w�Z�0 ��`JTG�+��A� t��ɕ1{�)� s3C�� re0 � �gV�9Yꪀ�t��70�RTJ �\�`���`j�B@{���ȕ�Pj� t��ɕ�api�P̕ f] @ 3S�x��Z{� ����n����L�Q�d�4#��"(�Sf@1πD�b�C+?�ψ�4�52�b}���Ek̺�B-@1�0J�8(��l�Q��]��kWe��M���|��vkg������,I ����� ��ڡ���ȕ��8�� 1K++��!a�;���vTD�B�@C�Y t��ɕ�u^PYP�U F,$@����(�����j'�ʃ d�R��o��q�n�(F?G"�b i�{�+�2z�&��[�!҄�2ҾpiT� o��vv��ɕq�D��P�%�Rg9�1�cK��h:>XA��[3�f�F1�+c�S�!��� ����O?�ꫯ���J ������/�0�7������ ��k#v��(� ��Y�,�|�Ν��z+�����o��ƈ��seP̕
HG�D��n�� �7����_WP���%,$pI1���矻>�B�/E�\��^��0����Ҵ �7���iu��Q���X=��Z��$�G�^{�b~�������_�7re�=���NI0���_���i�v(��+�:��,M-&Ѝb^�s.�@��(f�� �>f e�8��o����ret5��vF�d��� r0 k�>�K.K4k�B}��i�V��F1�+c��S�~��V�:6ÊYZY/�S�4�\�wf!q̝
�a�Q�8����a\g����O��a�i�2�n3�2������_�f�U���G1�7%*����j�<�ah��K2��U�?�_(�,Y���d"�y�Ѧ������ �e�ΐ8v$F���k�w�梘� ��z ��0 ��G�_��ċ-��+ L�� �Q̒�V�v9��,dz|�`���ȕ�3�~�s4��0��R��(:�XF�N�/ �(fre� �x4���ܩ�%}�&z�倬�;z�n�\C����˛oW��>�
ȥ�g���(�=���!��:�i�V �� �2�3 ��J �U��;˞�;�8��M��F1�+��� ���#�¢�c.���ʽsI!
��;�u'�E �*܍b&W�QS�v�@1�cK�%��KP�N' ֞ rt�ַ���IS]��P� `Q�@1�˛ֶ@1o%������ ����)�����_5�e��:�z|,�D��������4��'�rm��� ����2����M j��F(� �|g���xK�) Ca���U%�����[ Ԣ�{����KHz=�|��֙�f��,�p���LKԝ�o�����.��LJ��������v&� �u��ɕ��l��� ��wNsY�+# �~*��P�N���"ݘTJqϼ�j+e:u�`= ���I[��r�"� ���{N?E����� 3�����i�T�QgSO�^�gϞ��F1� �� ��>�i%re�"�I=���O>-u�T��ka$��p<?}�T'��������Y��3�]]�B�I%���a�cvy�qڢ�۫��m|�Vԣ��Vt�]�T�+�I+?��$ m��H/���C z18� �!t:��t;.J�рřE���n3�26�.�� ���A��+�cfz|C@�O%vH}���Y2�^g�x"��rH�l
��C��T�v�VT���������l�V�����<��Y ��_(`���Au��=�oX�:Y�uPJ/�n�~�/��%���H6�nfk�1[��u�F1�+�;uO�)��_ za
*'�b�|�v2Oi $�_;�nWs� 1d����^�g�n�����R�\V(�K-�
�>m�RT�����*��
� ��W/�w�7��R��' /.�Z[��`�n&~D�b�6��z��u���3,]4��^�z\ �B�vS��� ii!�T�� �9/�jSx�vٸ���T1�)�D �O�C1� �RHWH��[L��k���c�s�I��sR�ٶ.����m���9.���e�F�{J�ע��T1�3?�+� ���%]A1�wK��1h���s�=�J�1m�^�+c�K��s���b����b��pK�J ���1�?�.O����v�b>��Y�|����9�谏9m�1g�!���wEJ)9.�V�k}�4��z���kJ��B��"8�L��G7��\;��ؓ@���}��'.ڪ� �2���,�0��?�O���<?g�ZJ*�����Q�O���Q�Jz ݤ�|�v;��ų��l[i=$��3�+���ѷq��g��w��],�;8G)zoE���T�܌=�i5 t?U�4H'Ҟ
�Q̛G�
P 9tTgA�re 75�� z1��~��cR^Q�h��b�#�D���O��[����8���xwҢ���en�l[N|�w�
�%e���3iUv6G8�$oZt-��3��@���*�\�f}���<g��,s��r���L��\Sb�z�PB��ʏ��Q��2���F�� �I ��kiB�d���"3�k�eH�ڡ�<E6+�Y�k�0�B#�Q��ʨpvUe�~S)͑n�>�����{[IB9�З��
��
r������-�bnq��ج�1=�W�8�X��w�5
������F ż�W5D@N*�~N��u�@�;�^A�S��3B�(�GYO�����* l#J7������Y���/�� ����{j6>��D���~Q�
)��l�B-�@��(
�@�\5�BY���v�i��ri�v����������q�J��_�K��_����������`�vA?��
9M���j�D@�_C�S�IB���G�i�x���0G�t/�;r��
=$���4Z���k�+R�B�S��@1s��
)S3re�<:�m��rYҖ�I�,�����:�n=���>*Ճ��M`7��%u;�O y2x�: ZZ��L��u�˫��t[ �C%����S;Ds%�Q� ☋⭮r�BR�2�&ޒ�,�F|��3���hQj��ƇP�A1�ye/�ݠ��P7��8�֧b.���I7p�r.�Y��phP����JP�5�N)�$���t^�ЛqxO;3�3=R��=M��I��%�P'�Q�j����8���^���� ����*�f��R�uyja�G���Nt�6� �G����o_��;����zpe/�u5x�y�A��
�%��!֠hh*4 �2@1g��XU
�X��,��w���$V�g�w��� R��v�ܴ`���е9pBoy�?+r�b��:㝖ӝJ�wړ��t�.Im�J�.O-T��9:.�,������ݱ���J֠H1�q�՜(�9�(�
E�i9J+֎f���U}:�2� ��sڲ�{˅���5ڐ�L# �X* u�R8�[ ��E1�� �k��c��h�u��KW���]a�b����>7s������^ً�V$$ n�녻Q����8+�J���z��`�]n�l
�gG[���Zre����%�[N��gދSŜFY��\RŜ�?U��֝im.fwr v Or���W��+:- �Z�M� ���9��4L�Ҍ�^������� �nsv2T� \��� �-�+c ���U�2��I� jR��.�u���(�zp ��w��v ��)���t�c t���H%��b�rUDb�U��V��^�I�I*�Su�*�p���3C�����}��Q���(7I��Y��5��_V>X S���<�7��r�d�n� ��`KL�p �ī��*Y
R/"��+� J���za��k2�kg*��W9l�6�i Z��ϴ�1Ǝ�P����f�ZYQ�W�s�w�w5��L7��\{M�J�I�9l,=�$�YFw6Ǥ��Cn�Ym8PnVu�� %��XW��N}1ׯ=�di�|�͕D177d�
������ ��M��a�n�q���ƥZ\�U��pܧt��tUqmܛT���͙��ӫ�߂S�r�"#���cJ��,t� ��Ձ�g@G
��;̡���F�J�4�lN ��ob�!J��������>�;{I�pe�@ڍ2�ݢ���)��v
�D4k�4X�,�p+P̭���v*iC�h�X(���4��}�y�|6�9osj{�w֥(�S9e&P�L�>�9������w�Lh;(�v��*����I���I�5� J6D�\
�ަzE�>�%V�9��/�7�#4t�dK�]��_�4��ݛ��r{��Ѝb&W��Νo�_R���雪^�p^y;h�c�=VUMn�ιi��� ���]���:�x�����ǧ9E}��G��>o��v�I�!����oյ�W�[ן:�:�S�%zj2��~�x�`b;���� �5]>q3��5������rX�tJ�!����g��* c�V��[ ��n�ȃH���� g��])�H B9�:�B=��F�ΉbvX]�i���8W{]1[Ȫ�Ů^xňk�л��"��p��Q��^���k }���g,�CG��EZ[�I�|Z:���
x��`���cK��.�5��ffg�uX֦���A\W W�#Ѝb&Wƺ ��Uz ��I7�8ӕ~+Bݬ}2D��|)�O����n��b�lD
2��Y�{U�}�g�u�N�hZ�ի�C�����D��\��v�b>�9��J>۴-�`i��{�"%@ 3�a.��,����3�) C�Ny�%wf^B���Q����;1ڪ�]�b���ɑJ�B�y��
�l�����G<ɤSg������ �U�3>�|���OY�z�O��5X�����!�b�C�2��S ��P�F,Ci�Nd����n���:Y�#J�W�}OC��+A1�FDž��t9Ŝf�O㘣E��T&:�!U̱V��Ա�ב�� ��z�S����tZ�O:�L s� _���/[�~�k�.Q�|v�Z�b��s���!��6�=���w��!�}��f�v�Q�rb�2*�'����&+�t��n�<�Ǭ��nSz ��b��n�q͡Y}_u
Q�����X������nf����%� ����6]nu>_1;Ѿus,C���_��l����m�$]4+��즊�+����XM KC�Z��./��b ~���}��.69�� ��
W��:Ӽuq ���=�� Y:^m%�(freT;�1L>�X{}i�t3��&���n��[��u>
�� L�2��Ҹq[N��p��7���O����x��Z;�<���?*��&v��+#����0}kR���$T:���<�gz�ʞȕ�'����Q�x�=HCw"���~��pE8w�U�����ov��1\ vrL�'�G�G%#���pyJ��̰N@Q^E [I�fO��ِك�/ �ó��W�d5��I��Y�� �+�����}� >��a�l�D�e�I�3��\/�H��x�g� ~��b���S_�R �������_"Ѝb&W��\��&�B��u��E���r��='rYfk��.�s��[E �v��� O�<�����9N.��
����Mτ�>�g��^�E.G<�t3�B�(freT8��4I?�����̞�W���0m� �h�Kv#�b�
�
E���u&�Y�c(G�r�0�/d����c���0�T1�k�bc���(Č�:�b><��'��x�J䯗�� i���GMu@1�5 }X��K���9���"���F�
SN��Ep��uƫ���'N����K]h��>&@=�@1�3X�������ͼc��54 v�+G��ɕq�tk�ҽ�&~_/��=����Icu�3�z��Hs���{ { .�v`�n3�2�E�4���:�KR�� �\� ���T8�<��ܼ"Hö���X?�@7)9���t}�}[�{K�xڛ&�-'Ѝb^�u�萀\\JL��v�!�j��A�����)b�2�`�Ҕ��c
�PF WI�+Ųt��1�m�F1�+���W�Z�Eu;�w{9�+j�phP��[��a/!�yء��R�x��V�(O��V�8�{Ϙ �u��ɕ�c:tR�}�J�S!��{0� s9��<% ?��K���۩6^��>��|3�64��A1�gEɆxu5*��!����� �>�i�
�\�Z�+ � e�ܺB ���蕀#�{j��p>2=
�;�+�&"
!�h%�0ڡ��"��~��(fre�?�@��m��r�䯝/pa|���&��pЏ��5U����vW( ?��YЍb�-�B@�f��Q�� i4����:���IE9W[9�2� �Q �!k���I.�}�ٴ�F1�+�����;��:H�Ν;�_�o��� � [�`XAf��쳷�
�cne�:��At��5��9�!�b&WƐ�we���_Ff[�"ך�0
&Δ�s���P�}�g˽��i���OO��k� �_$�bfr@ �@(�,�$�Hm����/E#�YY��
[���k � �re46`�����պ�+���CK7�m�#w��L����1}� �!@��z�K~A@ZY�V��C� ��Ѥ�%� �ȅ��z�Q̕s�<@ � WF�C�v=A�Tyc���Q>��Ms<�Q���o��c@�.�1�5 Xs���p��I�?���F1�+c��K�! �������F`E�q�xhF�~(�� ! 4A ���0a�/��q�O�
�r(��� �B�\��v~C�z ��:36��F1�+��9�a��Pȕ1�pw�ٳ{�)XY�5�QS��t����(f��|���|/�1h0� |
J
�hK�P�#�����ă����J��}O�C� u��l"�bFU���_��_������ �][Z��c�ʡ�7}+s�$����[��� k ��F�3�\^�|�I�<� ���(Y's��Us �7��Ҕ� �y����UP��s�=w�Ν� Vm(�A��-B�_7s��s�u(����0r0K.��̼h� ��� �~��3�B�Q�L N �� �B ż� � O �|�Ti���a�����7�X�ioQ̝�0�B13��:�b^Ƌ��M`�`�͜0��M ż7q��K Ŝ�g7����J:�(%S���C��_|ѯ����`6P�́� ��� �b֣����b,# ���+�,����� ���1��%P�Kh
T�<�`�U@ � ���3���P�%�6\7����t@ �@1�7&X�� �y ��ʢ�l�Z7�2� ��K �<���$�b�s\�
�|�` L ��L� ���q �(�q�j�Q�L TB �\�@`�F(� ��`(����Q̵� v
G �<ܐw�as�;L�P�� �������4 \%�bf��M ���� �\ -C � �y�Q��(�F3c_P�aR� *c =��� ������5P�k�
p
�y�A��m@1�1NXy� ��!ޯ��Y��[o���k����O?��+X�� �9'M�(�
�"(�SV8���x�;w���^���W��%�@17:p�� sc:f�P�c�{?�����߿/� ~�T1�-1����@ON���� �� �9#L�:��%�,M���_�M���!1-�G������P̅S= ������z{E1���ĎͰb��Y/��}��iL������ Q� fl$�b���&p]1["K+� �_Yn�4���|V(�8� � ��׳�ʚ��k
lYN�bV}��8��u�h���۸���8a� P� �]D11� w�bVߥ��:ù2"C7q���?��c8#w
�<��������YM ż VA�R>��y�� e���Z�'�L��*Ư�(�bh����P�#�zO}fϿ�F3c_P�aR ���m@1�=~ŬG1CK�XF���e�(]+s�#�]����q��y�!�õ@1�:2ص� �y/J�F �\ۈTb����� ���}@1�1���<��_�9����J��+��H ż � L �|� ��<��֑�.@ M@179l P�L��P�L @ �H Ŝ&U @ �| ��D1�0J�8�2��:�b `���"����]�9�zv\ ��P�YqR�aṖ���,P�Y0�W ���1�G�@17:p�=!�bfJ�M ���� �\ -C`�2^��� ��֑��yP��8
W
�<ܐ�a@ % ��Kҥ��P��7����a�h@ �@1�:2�5� �y ��J���r:\+�2j �ZF ż��k#�b�mD*��\�@`P�́>����{��;���+�}�śo�9"�|� ����J��+��H ż � F�/�x�g���O3���#�b�oL�hP(�A��n���ґ:���C �w��o�z� ��6#J@ ��l(�٨(X �p3�`�op��|� �< �������z#73��v�Q̷Q� *c�4R� ��8�^���/_}�U-�;���w�������ڠօB�^Ǻ�~��[ 5l� ���a �S(�=O�?���{N�Bx��� �Ԓ� �9E�@(� ��(�
�M���֭M��[-73�9?�
5��7��R�$�b�I���#�b>�}�-���D1�6�Q̵��@ h� ����;�x3���w�m�-B�@ ����hJ Ōb���b�yt�m(De 5� w�������\v�m� ż� WC s6�Tt(�[n<�b�ꫯ>N��?��-6�1�6^(��F{�%�b v�;�8���ݯ;y�o��� /���C��>}��3��*�RՕJP̥ /� ż��!P� ��X�ݙ �yg�4�]1��VrY�9 ,U�b�B��JP�m��B �� ������YV�z!��k���c�����OUOx�]OZU.���s��U�9I� @13
VȮ� =z�Hf=����,�
���w�z�-��w��OϤ]
�^ąj+����e(�,3V�b��� �� Q[�qm=P��Ec�dW�i �Dp�&�
ׁ���z!��Χg�*f�p]��{�H Ŝf��P�Y0R �@1ogH
5@1�0
Mڐ]1��6�WXJWoI ��U&
Ij�)�뽩O���1��Y�Q�MN��F��g�� �@1��K�{@1�E��v�Q�ҵJ<gx�1K+��Vp�^��Ia�b��� ��3� >�0�T�b�J �� �y;Cj�� ���Qh҆}���t�hO����:tF��I����_9.��,�Q�Y0f�Ŝ&UA � ��9��@^�,Gr��'�?!���n��k�I6��I+�8����ϗ/C1gG��B�F�\@ )3�a%���y��\�b�f(~a�����a �1��w�qsg�_wP�)k�~3o^K(�y�(��P���.P̻`�3���y�b�yt�m((框���; ܲ]C1���ΰm������jd#�bΆ��%�b>ˍ��Q�5�_sͣ�m� �#�bnn�j1x�bV��t'��݈z�E��z�\�Lv�C��Z�K Ė:Q�[�q- L������?��[��c'�Y�].tv��u��+݊� Q�� KU(�,�� ���!5�@ �\�(4`�s�=��ɓT7�S�ʅ�-���>��]+鲜���7�bz�g�ϟΧ�^{ۿ�V�����m�����kպ�b>�e��qB1�6�Q̵�� K �<��w�qsgZ�;w�>RݼB1[���)�k�*y��
�u���U��]�>���P1]����o��U��
�B�ן���Zٵ����خ-m�h/��\j歭ż� �A 3sf�Tw�A�[k֊9����������w�v���Н4���NM�"��W��x�c�&�jU�*Ҷ,��]��`]kE�CתX4:�k*�b^�k��(� ��@1ϡD�� ���ݻ��>^o$��|�7~�7�O�Pɩb�SY�V�X��sx��u��z|�������p*���|i1Y���}����<��U^_�h0�A`&�<n�B) �� ���n��Y|̡bC��))Nk�� 圪�P̩��^�b��
�p�GpP1Gq������ٵev�� s �� @`X(�a�~Ydz�1�U�ָ�T�g}̎-VЅ�& ��K��u��\���b��ٲ�%S��36 �%*c�̨�4��֑�.@ M@179l��=WF��9^[
��*= R��3N_{�^����,籃:$�-�'��#*C%'�t��mt>g|��Y�SżgZ� 0� �����1o����Q̵����� @ M@17=|G�4�ܑ��o�\��P��xQ� �@13AV@1��P�+�Q��P���R1 � ��G �,}F1���L�B��� ��Z@ c@1�9�z�bF1g�FŪ@1CK�� F$�b qԳ�� ��G�s�GI��Ω���9��,�bޓ6mA � ���!.����q$xv'ץR�Ŝc�JP�aR ���+ \W�� �[^��tߐx�:\&}�?�;�/��X��R8�H��Ŝ�zl��w���mCX���jZ�uf��v(�Ө�e(�bh����P�#�z�>_Q�ޏZrVۂx>���vc7l��km ���
�*��%��Dg�ڻ�y�?)W��#v϶�us��O�����U�JW����@ ��7O�q)�ŜeRe�Ŝ&UA � ��9����,e��yg�K��.[+f��.����7�OJ�:#�
�o�bV���ڐז�zK����۲V��.���B1��F�.C1CK�� F$�b qԳ�bgm4tV1�2N�)$d�o�q�� �T ��+�9m.dwj�%uZC����W����b�2�2V�b��� @ �� XI`�bv�"�,9�0�&ޢ�e�Uo�� ��V� z11 żr� w��8�� @�C(�u�.]Q�ң�+�*1j�*ä� X�����
��
Gk誥�Y�%����zV�Z�W[�Q�h+�U/"*#]xJ �>�n~+(�( @ 7 ��o"��yW��}8��:8� ��#�8}��^�爈X�qɡ���/*хi=^ާ#
(�B�}��;��A :���]�ku�+��<��T@1�9A1�6"�@�i(榇�H�o�c��pae�c��
_�-�!Ms�( ��X hsZϩ�(曣VOs=c�%� : �b�`���M�|�Y�[��X��L�;ٱ�R�Χ�=VX��y�������r@ �@1�6��ۜbVϥ���:��Hv�G��y#�
hE/A1�K�� F#�b mij��EŜ��'��˱]W3�y 7�� ��P�L��P�)8��iT�2s1�T @`D(�G=K�Q�(�,�P%(�B`����P�c�{�^��Q��Q�*P���R1 � ��G �,}F1���L�B��� ��Z@ c@1�9�z-��s�9��� �� k�Z��7f��0$T�@13 @ #sF�cU��_���Z�v��[��[��cmP�B��_�5��-����:@ �@176`�;!��,�@13% @ #sF�Tu ��[h���(a# �f���* =K ���8K ��Ā ��P�aR�P�@o�Is ���� �!�bnf�0 3s`>�|V�� ��P�7Q�j��� ��C1 Ǟ�! tH ����%�P�=��(�( @ 7 ��o"�@�P�U�qơ��cO�� :$�b�pP���y���Y�|V�� ��P�7Q�j(檇�8�P�DZ�e@ @1w8�Cu �<�p��,�y>+JB ��M(曈(P5s��s�q(����2 � ��; ԡ��b j��w�<�%! @�&�MD�� ����9�8�q�i�@�P� �P]B15��;�b�ϊ�� p� ��&"
TM �\�� g ��8�� @�C(�u�.����E1�gEI@ �I �|�&�b�zx�3�| {Z� �!s��:T�P�C
���糢$ �$�b���U@1W=<��b>�=-C � ���A �KO�<�� > ��ts� J�� ��P�3AQ�:?��O�{�9k�g�y�/���D :� ��8�� @�C(�u�.���8�>��(晠(@ s���P�L��f�\�� j��P�4@�7(��Ft���͌�y�A��_� J�� ��P�3AQ�F_~�� �� ���1�8<�ڄb>?�C � ��� �?�.?���o���{ｧJ3� �q�OO�@13C @ #sF�T���>���_T0�|�nRZY�������NF�L�P�u��A h� ����\E_����/���'�|r���>�{���4~� ��� �� �9#L�*K��7ߔ��w߽�� | �~��@�5�ګ$�b�rX0
�@�P̭��PvKK+��
Ҙ)���8TgQ�C
7�� P� ��4a��D@a�- ���+��
��dWO �\�a ����[��l�b>%�ظ���?�,
㰝E1;�t �@ (�T�s+�adL�Tt�P��Z��@172P� @�
(�6�i +��B�.t(�E�^+H�ʳ��tyk��
��+ L� �.s�cכ�
���>EP�\�o��͒�lXr
5��kl� �
s7C�vG�3N!�Jp�Ͼ}
�P��B5ڦ��� ��� � �� �9#L�ZC@�,��BI-vv�*[�v
�n��5vsM�P�u��A h� �����\kV�a �Y6}�^�i �� ���q�*@ �@17:p͛]U\��1!�^ @1�0J�@�(�f��C�\{�Ϻ�n������ #,� �sC�ռ���w+�ۮ��k�(��F {! TM �\���d\C{�d�?��ql�/(�VF
;! 4A`Ŭ^ڼ��C���?�LJ���;�4132��>չ��Έ��@1/�Ea@ �N`�,��|�K����?>܌;w�`^ɼW���)�R�Ub�"3d�ݻw���5]H�� �� � ��=ԛ�{�z���/�(f�h� �� +
�\5\�
�G��%5
s���P� �$�b� *[��$��*t&1�`���lSߊP��5@ �@1�=�}+��>���0i�i�K/��h���s��Ṗ�q@ �@1�=��*f/������ۛ��)��<� < Hc_��ZC1/�Ei@ �J ż��R1K%K+K1K7�
�g����ڧ�P�L@ �H Ŝ欪:S���C��ǘ��
��,O����:wԭN��b�d � �:��� �n���I/j���kjO1͊lV|���k�kt[P̣� �@ +sV�3*�C1+g��0�>b�0��c� 2c
Pd(�=(� �a��� ���\�ڑD���R�L ;ݥ������N���� �� �9#�YU���� >|�0 ᕑV`�~Q(��_�>�
�����b@ #@1�=�*f%����ɓ'{�j�=%Q&�������[�~ �W_}��oT5V(檆c �N ż�6���B+۔�颹 ��\���/��� ����|���s�҅Q̥ S? ����� ��$����2��V�%�S�= ��X]I�J1�x���*f h ��� �|v� �+�J� �ډ����� V�駟�a�ҙъbV ��0����7�`)�B��8� ��g�f���fV���v�ZD ��N�kzL|�V�
���O��բ�o"� �'P�b���w�u�D��}�(6}1 @)e G�|�.Y�by�;-��.�«�.��!�g�3�g�o ie�Sp�� 'o����*�͈� I�p<���k�kC1��J�� �%P�b��9�D:4���-w�����׳�S7�\_*f�e_T�D
�L��2=mEgT�fD��
� =Z�f�Y1+ Ci��A)�R\1 ��c�]�,e>��?�P
7m����`�f��gi�:�����NM�93�1��"}}��*�zl���d:9�p�A�sQ A�<�5�Y�2��Ŝ#�@ �� Ԩ�e��h�5,I�� �%}O� ����Oe������x��.��W�%�U`�>ۊ�6մ;դ}f�L�S1��0�Sh���R�8}�`
�:!� ¥Q�����3A�^I�����u1_�qws�V�f��\RF��0Ŝ�́P�!��ԣ �z���M��Py�/��)TC���^k,�c��:E1�0X� @ � T�����A�����H�9����ޚ< �%gs<>V�x}����TUaO7Qe�0���ؿC�f�8��J�R�_֗&c�O��d����'UƊY��w?"F9j�$�p�6�L:��D��3�I-<ۻ� TG�k��� �kH'���߁��_��'P�o�Z��|v� �+�Js��O�-��"=R��H��wv�<��O}��Z�xԬ;P��䠽6�gr�,g���ä!B1an��j� ��Pީ';~)y �k㗒���9tm���y���!U�g�@����s�w�n
Ҹw�^��H ���ϒ��_5>�
�@1���E� E�FŬ/c�'zW_�i���O}��
��H1��ҟb�l��k��K�K:�"Mq��# ٗ`��� �' �!!����� ׆12 T�Y s����$��"�<��K�����x}3H�[ >�҄� ��PjT�~�+=�uR�ob� Tj#u�4R?�ד�]��}��Vx��>�W���\R̍�1K%+ `�tiT��8�e���\�4D�>ݔ��:�B�z��I�i�:��>� ;��5��}2�ʞ-��q2��k� S̙����o��b�z7S1��î�y�(�<�
���jT�'"�<JxY��'�Po��+ ٫ ;�W���~ �pR��-�&������:i�h>v�R4(C��ǘ9��|�1(���1[��X\�� ��
݄�D4�Q[j�"�5DC��#ecB����93�����#�ƕz��c�D��93��ȵ P����3�� ��)@ T��3�����R�Rc�ACj�Ħ�gc�o���f1��P��ܸyI���O ���mɷ�#�y =�� � ��S�Ŭ�q
�P��B{�U��p�@�d�p� ����� b:@`O(�=i�����n�+�]��G���>8�g{4�bރ2m@ � �y��S1+㯶e&(v�1�ڞBϕ~�;��B58���_�5��CAe� 0.��c��b��Yb�D��=̙ڋ$����_> � ��2� �@ �:F` ��L�4��� ����S1���Ӗ)?]�Wt>+e�Ra��_��h�[�\���F�E>� @ �쭘ӝD����N6{[Q��KNm�_1� =�-; ��]l6���˝��Y�&;�donE��6�^!����~@ U�Y1�K�wxNm8D1�S����pR�鏮 sl�#c&[H��W�)�I�$�yM��6s��y� �"p�bv�0 �2�>og�PJ�xS �wPGl{�J�*�3�P#�љ�=G"yY�nX�bLZ��qt=*�>���q�b��Җ ���4X1@�Zeb���a����
��� ��S�G J��
J ! �t��.�h��6�?�14� �*�CO�! � p�bN7C�M�$\�9�}x־�fȒJ+���"{(��F=�;<���i���N%��I[ k-��£ ��3U���O��eR��㉽Qv�xmU�b��1�g�5F�y2(2�{=��n�/����|:�VƓ�{�\���͏��h�k�MP� ��糢$ �$p�bN7{�Ҳ� s%_$k&r��%<�* Q�t�t�O\>�Ǖ�hҦU�ճT��΄b�V�E�wSZ���Ԭ����� ���%� ��Knk̙+�9}K�聋����N?��M�lT�
��b��G ��R`>�|V�� ���W��M厣2n*��C��>_R��%'�Y�:�CJ��Bʺ<<����a�ݖbv�s%dH��k���C¦�����.U̎<N�����c(��b� �4&J�M���P�+�q \"p�bN5kH��Ol�b��'��\׆�R _;w�+� �ډC:=�����̦֦��B�����H�+�������:�
�n*a��7�u�bN��+T���_5�'�~�;���ag��$Hc5.y��*[>�Օp�(f� d$p�b�����,��X�ԟ:"TT��g|R�Z�!���9���ނ�
�)D����Ր�MZQ��ד�*k�֯S���+�.͞�>���ݻ�����5�Ͱ�������K��氦�Y�
�G��Aџ���n��Ӄ��`1�l�N��Y �iL�RV�MF��%� �X�nQy�"\� ���V̩�N9
����.���'S��kC6����|^��e<[ҞlU��� ���O����]��.m7=_�b6%%5�fiJp������
�饻���<reX~̇ɠ����L�j�����ɀ�Ζ�>f`(s�����T� ��4a� 0����R3����%�[�� ��f��p�a�+fuDAo���������W�%�+C�W�8�1�d@g ~���pjEH >|��H�xk�
�\��` ��T���i �=� �9M ��u9-~jd���6+x@��<��gQ�_�C� u�G�O�.�3L$�"�:ܥ�m b�xp� �� T����!-���
G��
�3�n��[�l[�T�k��P��@ �H Ŝ欪�R�o%��
mV)�5E�+ C��� ٟ �y�@�c(��E�,F��U*42<̙.�:��#:�bNyʔ �b.A�:! K ż��7����Y�� M��{�k�=���T�kY����FsϣK� �N ż7��a)9�D!;�M�������e�0��P�k�\�(` �n��� ���)HC����IͶ� -lOI0�ϔ�Br��� ¥j@ �@1�=�}(fS�RT�a��~98 �_{�n��b�E��! @`�XY����
D������ad�T�� �9/Oj� 08���?�,�^��̓�xc�� ����3�
@ �H ż���R1��4�ϪF���?0k�C1�%�u� p� �y�iѱb6J�����RF���ޟ�
�7��R@ �@1�='�W�*�,���������ds{(��� � �!�b�{6����T 4�pMq��؛r��� %Ѿ-�|�I�Z��8sq�4 @`${(f�� ��a�>��H�AZ���:�<�0Q2��,�`3s � 2�C1g4wKU�w�&�p˵�IOGc7*�T7ע��J:@��(fie�w%�k�>�
��7|��g ��9��^���� ���(�Y�A��3ΞUռ�� �ZV ъ�qIUP�U
�@ h����f ��k���i�J�5)^
#��
(��" �� ��������\�V �xE�D���P�r9 ��W̩�7sm����ڇ�ܻ��/j��(^*� 0��������)��;�("B�{ڦ�qjTI<�ۛpO�ն�b�vh0 �@��W�1*|��<A��}��$� ~X�N=v�dо$J�Q�-�?� �����. �. ��� �V;���Zֺ��_�A��:�؍b�e$� �*����H (^��� /��o� ��� E �|yڅ �%s���|�[�qM��>x�0��g����g�� �&�b�͈Gp�7 ��I"wOrY���^��!Ṗ`�Q@ �@1�:����>X����o�B%��=�M �<! @�6�mF�8����Vp�����OZY�����p�1�(�C��( �^ ��{ ��� e�V���5.uOe�6Nj�J��Х(f& d$�b���� �
� ����Vz
���jc;h�n(��� 4F ��a� H K7�8��V�e�h6�c�� ��� @ ��3¤�] 8 �w�w����]���,�� ���q�
@ �@1w2��v���� ��a�O�/@137 @ #sF�Tu ���q@�4Y7s��u� #�bnl�0wB �̔8K ��Ā ��P�aR�P�@o�Is ���� �!�bnf�0�,3 3s � J@1�&L�e ����m�v|�� �C �� ���Q���P��Y
U�<�p�Y@ � ��K���P�e�6[;��١�p@ 5@1�8*�4� �y>��J���n: @�4si��_� ��,�fkG17;t@�F(�G��@1�g5TI�P�Mg! �&�b.M���@1���l�(�f��! �H �\�`�|(��*�b j��, ��P̥ SY(�|�� ����a8 � ��k l�O �<��P%Q�C
7�� P� ��4a�/K �\�o����� : � P#s���M� ����$�y�ᦳ� J@1�&L�e ����m�vs�C��� j$�b�qT�i>�|VC�D15�t�@i(�҄��,sY��֎bnv�0 �@�P�5�
6�'�b��j��(框��B (M �\�0��%�b.˷��Q�� �C �� ���Q���P��Y
U�<�p�Y@ � ��K���P�e�6[;��١�p@ 5@1�8*�4�@��_~��G� ŵ��� /���� ϯ���@1w3�t�@
P�5�6�'�*�O?�T��?tu���Z*���
@178h� @�^(�z����De����4����/|�O h *�3�=��I�9mQ�!(� S! �O �\�a�5�q̎͐�9t�ճ�4T���-�u�o���D3�;#�b�l@� �c ����O�[ �*f�f�/��XJ �x��}�_�9B8����@1W6 �@�m(�����ʘ,��8N{��r�+Z��M$scJ� H �| |��@`�b�DV��P��9
h�h�`
U�D �\�h` �� ��� �;0G1+�B�X�z�
As���4b���$;�>����;� �%�b>�?�o%pV1K��Wi�����
\�n��*������5@1�4�@�y(��p������R�Q�L @ �H Ŝ&U @ �| ��D1�0J�@�(�f�
C�@131�@131 @ #sF�Tu ��[h���(a# �f���* ��� �O �<�%! @�&�MD�� >檇�8�P�DZ�e@ @1w8�Cu �<�p��,�y>+JB ��M(曈(P5s��s�q(����2 � ��; ԡ��b j��w�<�%! @�&�MD�� ����9�8�q�i�@�P� �P]B15��;�b�ϊ�� p� ��&"
TM �\�� g ��8�� @�C(�u�.����E1�gEI@ �I �|�&�b�zx�3�| {Z� �!s��:T�P�C
���糢$ �$�b���U@1W=<��b>�=-C � ���A �K(框{~gQ��YQ� n@1�DD�� ��� ��C1 Ǟ�! tH ����%�P�=��(�( @ 7 ��o"�@�>��#���}}�Ż�[���u��i�@�P��m� ��/�y�;�<�{��L�@1�gEI@ �I �|�%���C �_|�^+��(�#��& �n ��� �:nf �# ��>���0 \'�bf��M@nf �ma�Q�e�R+ �A �� �n��G�G?�я�� �E Ŝ�$�@ ���������^��x���_z�O>��՞`w(�P����P��}�=��O*���>���P�9�f<x���/�l�_X�� �9#L�� 3s�1Z��Ͽ������~�m����� �b. �*! �K �<��7���'�Aw��U��K���,O����:7�A �H Ŝ&UA � ��9� �`�a|��s�UL�"��ݻwE[ϩ�2�@1�;vX@�B(�
�~��;�#��0��\V_��!�WH �\�` �v ��� ��-��*^���0=D13�t�� P�{P����#� �^j!�+'�b�|�0�@[P�m���Jy�$� ?>M�1�:�b l��. ��P�e�R�"��*K+K1����G���,L� P?s�c4��Jj���l��*Zc�Cv�<��i@ ���K����C~_������/Pi���� ��0+��\�` �v ��� � ,W~eie��Cv��V�XWp���M��@13 @ #sF�T����0�{�d�����_����(z� ��!އ �P� `Q4 ���*yE�
�Tbo�Ç�vg���P��@ �H Ŝ&U�&��a�a�=��ɓ�#�oS��r(��̸� .@139v"*�b�&W5Y;��nU\TsÀ� z!�b�e$+���r*��YrY�� <x ]1ZL�H ��� ��P�aR��iO))� ø>f�}PB_� msP��
C �� ����i�6%��jQB��ݴZ���ܬ��m��`֣�p� @�,sY�c�.��0�nT�'�|"�$tM���f#�y�ᦳ� J@1�&<\�ںOZYa��\��k-F��7 �{�b m��/ ��P�E�U� �Z-w�� �v�+HCi����z�bnmİ�@�P�UO+�IG*��t� ���ꫯ*D��Ly�̟v��KP�N@ �@1;��:��ʆ�����HEJ� �Ǐ �Qሡ�+ L� �.s�cw���(˯,��;KK+K1K7W���3� P� &@ � ����ܳ'�1�b��l�ζ��
�i(Z�N �
�<��e@ ���˱�f%��WU91��i-��h]� �U�J]�b.E�z! I �<䰯��+#
���� �[˘��@1��H-� �53a�a(�@*������J{�(� !+7Y�+�b.ǖ�! H �<�/���o�l,n[��"��6A���*�b�E�z @ 3s����%�ں���ɓ1S�Õ�*sF�T@ ��7́�^{��ӧi:�`�M��q��?(����t|��Wo��� �UR��>���~����EA�m��駟����)�����[7��P żd�� 0�~���_x�P � =�b�Tc˝��Z�6g#�?�XnZ-ea��g*�u ^�zq���m!�ѿs�N:����E1Ϝ�� �9P�s(]+#����~�v�'��G��ԥ�3�8��J�ʊ"P���0�T1��S�i�-��i .9q�N�O Q�__��Z�9mZ'���]_�]��31���L��� ij�^�1Jɧ�"
��:��^�D@GL�T1�O ������gN�� :&�b�:�X�Or9�:{ uRr9��'a!�"{k�Y�W � %�P����b���ZR�&^g!R� ��*���*�^:�k�u�.�?u^/|�$ F��
�]U��z&�zt,�G�����=��nT�^��GAZ(��At�A�#�%��Co���]�b��RŜ#�@ �� ��3��f����ͯ��U`���W�)
�0�.��O�%��S�v#�Bjr2���@XW�J�kėH����P�piO�z�Z�8ӵ �Tm_�ǿ�t�is�'Ӻ�'��ߧd�x�P̓h��ӱ�m(�}8�
�A��� ��A� ݠ3���.��F�i~C-�Pƺ:&>f�r8Uީb��q��d 擊QK (pv�{îk]�&�9=��7�9F�=a��l#����rW��Os�?�YrZ3�yOڴ@�{(�<C|����K1�/O��S�ixC-�_c�Z�P�6DZ�w;qS1K�:n8��-���v�~5�7�,�C����b�bOFŬ�,Zg�a��\�wlF�Igx���� �*E1� �@ Ŝg�'�ف^UQ�*cײ�E��W��|g�_c{��4*#��G�CXw]1;�ۅ �|*� �1�:�����|�6��o���H�."~F'��|ݞ���v���j� ^4����� ��i� �� ��� <UC � �9ϘKcMB��t����p��q�o��v�=5R ��)�� �<=���R< �Vզ�x���M��NQ�k], Q��[���7�P_{ݞ�́��4�_�@M�'?6L~��AD1繵Q |M �<�D���.�۷Y"rΦ g���όKo���?Zn�Sb�'y.�(�\$�� P̣�%��w��<J����ids��x)͟4�Rj4ap�F��+ L� �.|���\˕C�0�c� �S���|��^��8%�+�L���f�Ŝ )B ��X�Y~��# ?���\������6����W��/�l�~@ (D` Ŭܷ�������_��]��
� �݁�� ~���mj�Ua,�� �'M@ ��@�y��t�Ѵe�K �"'F�V�Ԝ1 `{�� 0,�C_ڲ4�[�!�4szq3WF93�Ԝ7 �)@ ��%(�Q�F�i��
D
��5G�`-<M]�ݥ��p�I�� N �<��6mY(f�v�}Lҭ1�Ͳm>����b�m�b�2���:�w�q��R������� @ ��� �y�)Qa�2+f��V�z�-�%v�߲O�&��r\�9�6\�:���� ox�FtWf��I G��g@ h� �����jlU͊YWB9z)]�
�#M�� W�toj�������:9����N����uqe��Y�.� tM �����\=a ���q�j�LC�#�"U��V�:9Y���)��O5�-N�ޯ6H�T��� �&s���j/5{���k-�'rV
X�_v�#T�o��}̓�|:�@�S�,�n
[T�3�2@ �@�P��a�<y�Dۤ)�Y�
��dIai_��TV`�#�%���9.T�BY�|�N���u�:}�'�[4v� tO ��/蠷��s�:/�,GQI^'�����i��O�L���*֟�?�v\k��ԣ�3�n×��2�xQ� Ps �P������S�m
v9�- % ����� >k��0~� }���f��j�� @ ����� ���;�w
�8 ��,K"KG&
/�ɪ_���{�)�E�I���� ,%�b^Jl��
��r@����5�'?��+��r���J ��b�l@ ���P���o�uk��_ ͷh��{�a��Xč�� �
��+ �Mz��w�+�?0�iQ�K( @ �@�P��Mu�y�27�v���|��'U���na @�A(��P���ꫯ*0W��5��Ɲ�O�(���W � �E ���x��%P��ǏI�`���_�vځ J �<�oﶴ��t����ڭ�{�˻|� ����r@ �@P�M S�F*6C��P�F�V��L�C�ϋ���\�j� @�
(�*��u#�P~V� �Ϫ<�+'F�c��� �$�b����(H�"Ry�f]�l!�WV7��y��Xa8 @ s ��b
T�^'���
�N!(���9 @ ��%(f�F~��j��n�4�AW6���9�+�@ h� ���Qj��'O���(m�a�J�͙��� ��P�[ r��M��M=� Di@t�] � � 02�ȣ�S�%������őm�-�w�%4@ �� �����4P����`e�ʎ���B � �!�bއ3����j9�27W�� ��PB œ0f� @�P�̄� h�<i( ]U�Tj^k��0��'�A � �'�b�~�:5P�H�*e[
��ʘ�` @ )3��0��U�棌���}
څ @�,3�`
�.z��� T}��< @ �$�bf.TA��)���.!
%�bx0� 06���_S凌wX{�br�F [ @ #@1�8�5���6{�o@X�a @�o(�Ƿ��)ś2i��+HC;���w�y�U"�
@ ��qP�DZ����֬�f�8oA�D ���9EK���õ� K �<�з�q�R(����SJ���Z퓢D +�]��! @ � ����k�1�O �imM�z@ ��AP����������"X��_���R�� @�+(殆���8�⥗^�^}���<�at?� @`O(�=i�V ʩ,/r��Oa� ?�Z�<mP @ �%3s�UJ�Lڽ�J1�JE�*� @� s�Ժ -|��i(Zc�i� � ��+������ IEND�B`�PK %�\���� � & html/_sources/c-api/exceptions.rst.txtnu �[��� .. highlightlang:: c
.. _exceptionhandling:
******************
Exception Handling
******************
The functions described in this chapter will let you handle and raise Python
exceptions. It is important to understand some of the basics of Python
exception handling. It works somewhat like the Unix :c:data:`errno` variable:
there is a global indicator (per thread) of the last error that occurred. Most
functions don't clear this on success, but will set it to indicate the cause of
the error on failure. Most functions also return an error indicator, usually
*NULL* if they are supposed to return a pointer, or ``-1`` if they return an
integer (exception: the :c:func:`PyArg_\*` functions return ``1`` for success and
``0`` for failure).
When a function must fail because some function it called failed, it generally
doesn't set the error indicator; the function it called already set it. It is
responsible for either handling the error and clearing the exception or
returning after cleaning up any resources it holds (such as object references or
memory allocations); it should *not* continue normally if it is not prepared to
handle the error. If returning due to an error, it is important to indicate to
the caller that an error has been set. If the error is not handled or carefully
propagated, additional calls into the Python/C API may not behave as intended
and may fail in mysterious ways.
.. index::
single: exc_type (in module sys)
single: exc_value (in module sys)
single: exc_traceback (in module sys)
The error indicator consists of three Python objects corresponding to the
Python variables ``sys.exc_type``, ``sys.exc_value`` and ``sys.exc_traceback``.
API functions exist to interact with the error indicator in various ways. There
is a separate error indicator for each thread.
.. XXX Order of these should be more thoughtful.
Either alphabetical or some kind of structure.
.. c:function:: void PyErr_PrintEx(int set_sys_last_vars)
Print a standard traceback to ``sys.stderr`` and clear the error indicator.
Call this function only when the error indicator is set. (Otherwise it will
cause a fatal error!)
If *set_sys_last_vars* is nonzero, the variables :data:`sys.last_type`,
:data:`sys.last_value` and :data:`sys.last_traceback` will be set to the
type, value and traceback of the printed exception, respectively.
.. c:function:: void PyErr_Print()
Alias for ``PyErr_PrintEx(1)``.
.. c:function:: PyObject* PyErr_Occurred()
Test whether the error indicator is set. If set, return the exception *type*
(the first argument to the last call to one of the :c:func:`PyErr_Set\*`
functions or to :c:func:`PyErr_Restore`). If not set, return *NULL*. You do not
own a reference to the return value, so you do not need to :c:func:`Py_DECREF`
it.
.. note::
Do not compare the return value to a specific exception; use
:c:func:`PyErr_ExceptionMatches` instead, shown below. (The comparison could
easily fail since the exception may be an instance instead of a class, in the
case of a class exception, or it may be a subclass of the expected exception.)
.. c:function:: int PyErr_ExceptionMatches(PyObject *exc)
Equivalent to ``PyErr_GivenExceptionMatches(PyErr_Occurred(), exc)``. This
should only be called when an exception is actually set; a memory access
violation will occur if no exception has been raised.
.. c:function:: int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc)
Return true if the *given* exception matches the exception in *exc*. If
*exc* is a class object, this also returns true when *given* is an instance
of a subclass. If *exc* is a tuple, all exceptions in the tuple (and
recursively in subtuples) are searched for a match.
.. c:function:: void PyErr_NormalizeException(PyObject**exc, PyObject**val, PyObject**tb)
Under certain circumstances, the values returned by :c:func:`PyErr_Fetch` below
can be "unnormalized", meaning that ``*exc`` is a class object but ``*val`` is
not an instance of the same class. This function can be used to instantiate
the class in that case. If the values are already normalized, nothing happens.
The delayed normalization is implemented to improve performance.
.. c:function:: void PyErr_Clear()
Clear the error indicator. If the error indicator is not set, there is no
effect.
.. c:function:: void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)
Retrieve the error indicator into three variables whose addresses are passed.
If the error indicator is not set, set all three variables to *NULL*. If it is
set, it will be cleared and you own a reference to each object retrieved. The
value and traceback object may be *NULL* even when the type object is not.
.. note::
This function is normally only used by code that needs to handle exceptions or
by code that needs to save and restore the error indicator temporarily.
.. c:function:: void PyErr_Restore(PyObject *type, PyObject *value, PyObject *traceback)
Set the error indicator from the three objects. If the error indicator is
already set, it is cleared first. If the objects are *NULL*, the error
indicator is cleared. Do not pass a *NULL* type and non-*NULL* value or
traceback. The exception type should be a class. Do not pass an invalid
exception type or value. (Violating these rules will cause subtle problems
later.) This call takes away a reference to each object: you must own a
reference to each object before the call and after the call you no longer own
these references. (If you don't understand this, don't use this function. I
warned you.)
.. note::
This function is normally only used by code that needs to save and restore the
error indicator temporarily; use :c:func:`PyErr_Fetch` to save the current
exception state.
.. c:function:: void PyErr_SetString(PyObject *type, const char *message)
This is the most common way to set the error indicator. The first argument
specifies the exception type; it is normally one of the standard exceptions,
e.g. :c:data:`PyExc_RuntimeError`. You need not increment its reference count.
The second argument is an error message; it is converted to a string object.
.. c:function:: void PyErr_SetObject(PyObject *type, PyObject *value)
This function is similar to :c:func:`PyErr_SetString` but lets you specify an
arbitrary Python object for the "value" of the exception.
.. c:function:: PyObject* PyErr_Format(PyObject *exception, const char *format, ...)
This function sets the error indicator and returns *NULL*. *exception*
should be a Python exception class. The *format* and subsequent
parameters help format the error message; they have the same meaning and
values as in :c:func:`PyString_FromFormat`.
.. c:function:: void PyErr_SetNone(PyObject *type)
This is a shorthand for ``PyErr_SetObject(type, Py_None)``.
.. c:function:: int PyErr_BadArgument()
This is a shorthand for ``PyErr_SetString(PyExc_TypeError, message)``, where
*message* indicates that a built-in operation was invoked with an illegal
argument. It is mostly for internal use.
.. c:function:: PyObject* PyErr_NoMemory()
This is a shorthand for ``PyErr_SetNone(PyExc_MemoryError)``; it returns *NULL*
so an object allocation function can write ``return PyErr_NoMemory();`` when it
runs out of memory.
.. c:function:: PyObject* PyErr_SetFromErrno(PyObject *type)
.. index:: single: strerror()
This is a convenience function to raise an exception when a C library function
has returned an error and set the C variable :c:data:`errno`. It constructs a
tuple object whose first item is the integer :c:data:`errno` value and whose
second item is the corresponding error message (gotten from :c:func:`strerror`),
and then calls ``PyErr_SetObject(type, object)``. On Unix, when the
:c:data:`errno` value is :const:`EINTR`, indicating an interrupted system call,
this calls :c:func:`PyErr_CheckSignals`, and if that set the error indicator,
leaves it set to that. The function always returns *NULL*, so a wrapper
function around a system call can write ``return PyErr_SetFromErrno(type);``
when the system call returns an error.
.. c:function:: PyObject* PyErr_SetFromErrnoWithFilenameObject(PyObject *type, PyObject *filenameObject)
Similar to :c:func:`PyErr_SetFromErrno`, with the additional behavior that if
*filenameObject* is not *NULL*, it is passed to the constructor of *type* as
a third parameter. In the case of exceptions such as :exc:`IOError` and
:exc:`OSError`, this is used to define the :attr:`filename` attribute of the
exception instance.
.. c:function:: PyObject* PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename)
Similar to :c:func:`PyErr_SetFromErrnoWithFilenameObject`, but the filename
is given as a C string.
.. c:function:: PyObject* PyErr_SetFromWindowsErr(int ierr)
This is a convenience function to raise :exc:`WindowsError`. If called with
*ierr* of :c:data:`0`, the error code returned by a call to :c:func:`GetLastError`
is used instead. It calls the Win32 function :c:func:`FormatMessage` to retrieve
the Windows description of error code given by *ierr* or :c:func:`GetLastError`,
then it constructs a tuple object whose first item is the *ierr* value and whose
second item is the corresponding error message (gotten from
:c:func:`FormatMessage`), and then calls ``PyErr_SetObject(PyExc_WindowsError,
object)``. This function always returns *NULL*. Availability: Windows.
.. c:function:: PyObject* PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)
Similar to :c:func:`PyErr_SetFromWindowsErr`, with an additional parameter
specifying the exception type to be raised. Availability: Windows.
.. versionadded:: 2.3
.. c:function:: PyObject* PyErr_SetFromWindowsErrWithFilenameObject(int ierr, PyObject *filenameObject)
Similar to :c:func:`PyErr_SetFromWindowsErr`, with the additional behavior that
if *filenameObject* is not *NULL*, it is passed to the constructor of
:exc:`WindowsError` as a third parameter. Availability: Windows.
.. c:function:: PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)
Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, but the
filename is given as a C string. Availability: Windows.
.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilenameObject(PyObject *type, int ierr, PyObject *filename)
Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, with an
additional parameter specifying the exception type to be raised.
Availability: Windows.
.. versionadded:: 2.3
.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, const char *filename)
Similar to :c:func:`PyErr_SetFromWindowsErrWithFilename`, with an additional
parameter specifying the exception type to be raised. Availability: Windows.
.. versionadded:: 2.3
.. c:function:: void PyErr_BadInternalCall()
This is a shorthand for ``PyErr_SetString(PyExc_SystemError, message)``,
where *message* indicates that an internal operation (e.g. a Python/C API
function) was invoked with an illegal argument. It is mostly for internal
use.
.. c:function:: int PyErr_WarnEx(PyObject *category, char *message, int stacklevel)
Issue a warning message. The *category* argument is a warning category (see
below) or *NULL*; the *message* argument is a message string. *stacklevel* is a
positive number giving a number of stack frames; the warning will be issued from
the currently executing line of code in that stack frame. A *stacklevel* of 1
is the function calling :c:func:`PyErr_WarnEx`, 2 is the function above that,
and so forth.
This function normally prints a warning message to *sys.stderr*; however, it is
also possible that the user has specified that warnings are to be turned into
errors, and in that case this will raise an exception. It is also possible that
the function raises an exception because of a problem with the warning machinery
(the implementation imports the :mod:`warnings` module to do the heavy lifting).
The return value is ``0`` if no exception is raised, or ``-1`` if an exception
is raised. (It is not possible to determine whether a warning message is
actually printed, nor what the reason is for the exception; this is
intentional.) If an exception is raised, the caller should do its normal
exception handling (for example, :c:func:`Py_DECREF` owned references and return
an error value).
Warning categories must be subclasses of :c:data:`PyExc_Warning`;
:c:data:`PyExc_Warning` is a subclass of :c:data:`PyExc_Exception`;
the default warning category is :c:data:`PyExc_RuntimeWarning`. The standard
Python warning categories are available as global variables whose names are
enumerated at :ref:`standardwarningcategories`.
For information about warning control, see the documentation for the
:mod:`warnings` module and the :option:`-W` option in the command line
documentation. There is no C API for warning control.
.. c:function:: int PyErr_Warn(PyObject *category, char *message)
Issue a warning message. The *category* argument is a warning category (see
below) or *NULL*; the *message* argument is a message string. The warning will
appear to be issued from the function calling :c:func:`PyErr_Warn`, equivalent to
calling :c:func:`PyErr_WarnEx` with a *stacklevel* of 1.
Deprecated; use :c:func:`PyErr_WarnEx` instead.
.. c:function:: int PyErr_WarnExplicit(PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry)
Issue a warning message with explicit control over all warning attributes. This
is a straightforward wrapper around the Python function
:func:`warnings.warn_explicit`, see there for more information. The *module*
and *registry* arguments may be set to *NULL* to get the default effect
described there.
.. c:function:: int PyErr_WarnPy3k(char *message, int stacklevel)
Issue a :exc:`DeprecationWarning` with the given *message* and *stacklevel*
if the :c:data:`Py_Py3kWarningFlag` flag is enabled.
.. versionadded:: 2.6
.. c:function:: int PyErr_CheckSignals()
.. index::
module: signal
single: SIGINT
single: KeyboardInterrupt (built-in exception)
This function interacts with Python's signal handling. It checks whether a
signal has been sent to the processes and if so, invokes the corresponding
signal handler. If the :mod:`signal` module is supported, this can invoke a
signal handler written in Python. In all cases, the default effect for
:const:`SIGINT` is to raise the :exc:`KeyboardInterrupt` exception. If an
exception is raised the error indicator is set and the function returns ``-1``;
otherwise the function returns ``0``. The error indicator may or may not be
cleared if it was previously set.
.. c:function:: void PyErr_SetInterrupt()
.. index::
single: SIGINT
single: KeyboardInterrupt (built-in exception)
This function simulates the effect of a :const:`SIGINT` signal arriving --- the
next time :c:func:`PyErr_CheckSignals` is called, :exc:`KeyboardInterrupt` will
be raised. It may be called without holding the interpreter lock.
.. % XXX This was described as obsolete, but is used in
.. % thread.interrupt_main() (used from IDLE), so it's still needed.
.. c:function:: int PySignal_SetWakeupFd(int fd)
This utility function specifies a file descriptor to which a ``'\0'`` byte will
be written whenever a signal is received. It returns the previous such file
descriptor. The value ``-1`` disables the feature; this is the initial state.
This is equivalent to :func:`signal.set_wakeup_fd` in Python, but without any
error checking. *fd* should be a valid file descriptor. The function should
only be called from the main thread.
.. versionadded:: 2.6
.. c:function:: PyObject* PyErr_NewException(char *name, PyObject *base, PyObject *dict)
This utility function creates and returns a new exception class. The *name*
argument must be the name of the new exception, a C string of the form
``module.classname``. The *base* and *dict* arguments are normally *NULL*.
This creates a class object derived from :exc:`Exception` (accessible in C as
:c:data:`PyExc_Exception`).
The :attr:`__module__` attribute of the new class is set to the first part (up
to the last dot) of the *name* argument, and the class name is set to the last
part (after the last dot). The *base* argument can be used to specify alternate
base classes; it can either be only one class or a tuple of classes. The *dict*
argument can be used to specify a dictionary of class variables and methods.
.. c:function:: PyObject* PyErr_NewExceptionWithDoc(char *name, char *doc, PyObject *base, PyObject *dict)
Same as :c:func:`PyErr_NewException`, except that the new exception class can
easily be given a docstring: If *doc* is non-*NULL*, it will be used as the
docstring for the exception class.
.. versionadded:: 2.7
.. c:function:: void PyErr_WriteUnraisable(PyObject *obj)
This utility function prints a warning message to ``sys.stderr`` when an
exception has been set but it is impossible for the interpreter to actually
raise the exception. It is used, for example, when an exception occurs in an
:meth:`__del__` method.
The function is called with a single argument *obj* that identifies the context
in which the unraisable exception occurred. If possible,
the repr of *obj* will be printed in the warning message.
.. _unicodeexceptions:
Unicode Exception Objects
=========================
The following functions are used to create and modify Unicode exceptions from C.
.. c:function:: PyObject* PyUnicodeDecodeError_Create(const char *encoding, const char *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
Create a :class:`UnicodeDecodeError` object with the attributes *encoding*,
*object*, *length*, *start*, *end* and *reason*.
.. c:function:: PyObject* PyUnicodeEncodeError_Create(const char *encoding, const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
Create a :class:`UnicodeEncodeError` object with the attributes *encoding*,
*object*, *length*, *start*, *end* and *reason*.
.. c:function:: PyObject* PyUnicodeTranslateError_Create(const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
Create a :class:`UnicodeTranslateError` object with the attributes *object*,
*length*, *start*, *end* and *reason*.
.. c:function:: PyObject* PyUnicodeDecodeError_GetEncoding(PyObject *exc)
PyObject* PyUnicodeEncodeError_GetEncoding(PyObject *exc)
Return the *encoding* attribute of the given exception object.
.. c:function:: PyObject* PyUnicodeDecodeError_GetObject(PyObject *exc)
PyObject* PyUnicodeEncodeError_GetObject(PyObject *exc)
PyObject* PyUnicodeTranslateError_GetObject(PyObject *exc)
Return the *object* attribute of the given exception object.
.. c:function:: int PyUnicodeDecodeError_GetStart(PyObject *exc, Py_ssize_t *start)
int PyUnicodeEncodeError_GetStart(PyObject *exc, Py_ssize_t *start)
int PyUnicodeTranslateError_GetStart(PyObject *exc, Py_ssize_t *start)
Get the *start* attribute of the given exception object and place it into
*\*start*. *start* must not be *NULL*. Return ``0`` on success, ``-1`` on
failure.
.. c:function:: int PyUnicodeDecodeError_SetStart(PyObject *exc, Py_ssize_t start)
int PyUnicodeEncodeError_SetStart(PyObject *exc, Py_ssize_t start)
int PyUnicodeTranslateError_SetStart(PyObject *exc, Py_ssize_t start)
Set the *start* attribute of the given exception object to *start*. Return
``0`` on success, ``-1`` on failure.
.. c:function:: int PyUnicodeDecodeError_GetEnd(PyObject *exc, Py_ssize_t *end)
int PyUnicodeEncodeError_GetEnd(PyObject *exc, Py_ssize_t *end)
int PyUnicodeTranslateError_GetEnd(PyObject *exc, Py_ssize_t *end)
Get the *end* attribute of the given exception object and place it into
*\*end*. *end* must not be *NULL*. Return ``0`` on success, ``-1`` on
failure.
.. c:function:: int PyUnicodeDecodeError_SetEnd(PyObject *exc, Py_ssize_t end)
int PyUnicodeEncodeError_SetEnd(PyObject *exc, Py_ssize_t end)
int PyUnicodeTranslateError_SetEnd(PyObject *exc, Py_ssize_t end)
Set the *end* attribute of the given exception object to *end*. Return ``0``
on success, ``-1`` on failure.
.. c:function:: PyObject* PyUnicodeDecodeError_GetReason(PyObject *exc)
PyObject* PyUnicodeEncodeError_GetReason(PyObject *exc)
PyObject* PyUnicodeTranslateError_GetReason(PyObject *exc)
Return the *reason* attribute of the given exception object.
.. c:function:: int PyUnicodeDecodeError_SetReason(PyObject *exc, const char *reason)
int PyUnicodeEncodeError_SetReason(PyObject *exc, const char *reason)
int PyUnicodeTranslateError_SetReason(PyObject *exc, const char *reason)
Set the *reason* attribute of the given exception object to *reason*. Return
``0`` on success, ``-1`` on failure.
Recursion Control
=================
These two functions provide a way to perform safe recursive calls at the C
level, both in the core and in extension modules. They are needed if the
recursive code does not necessarily invoke Python code (which tracks its
recursion depth automatically).
.. c:function:: int Py_EnterRecursiveCall(const char *where)
Marks a point where a recursive C-level call is about to be performed.
If :const:`USE_STACKCHECK` is defined, this function checks if the OS
stack overflowed using :c:func:`PyOS_CheckStack`. In this is the case, it
sets a :exc:`MemoryError` and returns a nonzero value.
The function then checks if the recursion limit is reached. If this is the
case, a :exc:`RuntimeError` is set and a nonzero value is returned.
Otherwise, zero is returned.
*where* should be a string such as ``" in instance check"`` to be
concatenated to the :exc:`RuntimeError` message caused by the recursion depth
limit.
.. c:function:: void Py_LeaveRecursiveCall()
Ends a :c:func:`Py_EnterRecursiveCall`. Must be called once for each
*successful* invocation of :c:func:`Py_EnterRecursiveCall`.
.. _standardexceptions:
Standard Exceptions
===================
All standard Python exceptions are available as global variables whose names are
``PyExc_`` followed by the Python exception name. These have the type
:c:type:`PyObject\*`; they are all class objects. For completeness, here are all
the variables:
.. index::
single: PyExc_BaseException
single: PyExc_Exception
single: PyExc_StandardError
single: PyExc_ArithmeticError
single: PyExc_AssertionError
single: PyExc_AttributeError
single: PyExc_BufferError
single: PyExc_EnvironmentError
single: PyExc_EOFError
single: PyExc_FloatingPointError
single: PyExc_GeneratorExit
single: PyExc_ImportError
single: PyExc_IndentationError
single: PyExc_IndexError
single: PyExc_IOError
single: PyExc_KeyError
single: PyExc_KeyboardInterrupt
single: PyExc_LookupError
single: PyExc_MemoryError
single: PyExc_NameError
single: PyExc_NotImplementedError
single: PyExc_OSError
single: PyExc_OverflowError
single: PyExc_ReferenceError
single: PyExc_RuntimeError
single: PyExc_StopIteration
single: PyExc_SyntaxError
single: PyExc_SystemError
single: PyExc_SystemExit
single: PyExc_TabError
single: PyExc_TypeError
single: PyExc_UnboundLocalError
single: PyExc_UnicodeDecodeError
single: PyExc_UnicodeEncodeError
single: PyExc_UnicodeError
single: PyExc_UnicodeTranslateError
single: PyExc_VMSError
single: PyExc_ValueError
single: PyExc_WindowsError
single: PyExc_ZeroDivisionError
+-----------------------------------------+---------------------------------+----------+
| C Name | Python Name | Notes |
+=========================================+=================================+==========+
| :c:data:`PyExc_BaseException` | :exc:`BaseException` | (1), (4) |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_Exception` | :exc:`Exception` | \(1) |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_StandardError` | :exc:`StandardError` | \(1) |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_ArithmeticError` | :exc:`ArithmeticError` | \(1) |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_AssertionError` | :exc:`AssertionError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_AttributeError` | :exc:`AttributeError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_BufferError` | :exc:`BufferError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_EnvironmentError` | :exc:`EnvironmentError` | \(1) |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_EOFError` | :exc:`EOFError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_FloatingPointError` | :exc:`FloatingPointError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_GeneratorExit` | :exc:`GeneratorExit` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_ImportError` | :exc:`ImportError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_IndentationError` | :exc:`IndentationError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_IndexError` | :exc:`IndexError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_IOError` | :exc:`IOError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_KeyError` | :exc:`KeyError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_KeyboardInterrupt` | :exc:`KeyboardInterrupt` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_LookupError` | :exc:`LookupError` | \(1) |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_MemoryError` | :exc:`MemoryError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_NameError` | :exc:`NameError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_NotImplementedError` | :exc:`NotImplementedError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_OSError` | :exc:`OSError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_OverflowError` | :exc:`OverflowError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_ReferenceError` | :exc:`ReferenceError` | \(2) |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_RuntimeError` | :exc:`RuntimeError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_StopIteration` | :exc:`StopIteration` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_SyntaxError` | :exc:`SyntaxError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_SystemError` | :exc:`SystemError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_SystemExit` | :exc:`SystemExit` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_TabError` | :exc:`TabError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_TypeError` | :exc:`TypeError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_UnboundLocalError` | :exc:`UnboundLocalError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_UnicodeDecodeError` | :exc:`UnicodeDecodeError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_UnicodeEncodeError` | :exc:`UnicodeEncodeError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_UnicodeError` | :exc:`UnicodeError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_UnicodeTranslateError` | :exc:`UnicodeTranslateError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_VMSError` | :exc:`VMSError` | \(5) |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_ValueError` | :exc:`ValueError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_WindowsError` | :exc:`WindowsError` | \(3) |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_ZeroDivisionError` | :exc:`ZeroDivisionError` | |
+-----------------------------------------+---------------------------------+----------+
Notes:
(1)
This is a base class for other standard exceptions.
(2)
This is the same as :exc:`weakref.ReferenceError`.
(3)
Only defined on Windows; protect code that uses this by testing that the
preprocessor macro ``MS_WINDOWS`` is defined.
(4)
.. versionadded:: 2.5
(5)
Only defined on VMS; protect code that uses this by testing that the
preprocessor macro ``__VMS`` is defined.
.. _standardwarningcategories:
Standard Warning Categories
===========================
All standard Python warning categories are available as global variables whose
names are ``PyExc_`` followed by the Python exception name. These have the type
:c:type:`PyObject\*`; they are all class objects. For completeness, here are all
the variables:
.. index::
single: PyExc_Warning
single: PyExc_BytesWarning
single: PyExc_DeprecationWarning
single: PyExc_FutureWarning
single: PyExc_ImportWarning
single: PyExc_PendingDeprecationWarning
single: PyExc_RuntimeWarning
single: PyExc_SyntaxWarning
single: PyExc_UnicodeWarning
single: PyExc_UserWarning
+------------------------------------------+---------------------------------+----------+
| C Name | Python Name | Notes |
+==========================================+=================================+==========+
| :c:data:`PyExc_Warning` | :exc:`Warning` | \(1) |
+------------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_BytesWarning` | :exc:`BytesWarning` | |
+------------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_DeprecationWarning` | :exc:`DeprecationWarning` | |
+------------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_FutureWarning` | :exc:`FutureWarning` | |
+------------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_ImportWarning` | :exc:`ImportWarning` | |
+------------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_PendingDeprecationWarning`| :exc:`PendingDeprecationWarning`| |
+------------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_RuntimeWarning` | :exc:`RuntimeWarning` | |
+------------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_SyntaxWarning` | :exc:`SyntaxWarning` | |
+------------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_UnicodeWarning` | :exc:`UnicodeWarning` | |
+------------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_UserWarning` | :exc:`UserWarning` | |
+------------------------------------------+---------------------------------+----------+
Notes:
(1)
This is a base class for other standard warning categories.
String Exceptions
=================
.. versionchanged:: 2.6
All exceptions to be raised or caught must be derived from :exc:`BaseException`.
Trying to raise a string exception now raises :exc:`TypeError`.
PK %�\��~/6 6 html/_sources/c-api/file.rst.txtnu �[��� .. highlightlang:: c
.. _fileobjects:
File Objects
------------
.. index:: object: file
Python's built-in file objects are implemented entirely on the :c:type:`FILE\*`
support from the C standard library. This is an implementation detail and may
change in future releases of Python.
.. c:type:: PyFileObject
This subtype of :c:type:`PyObject` represents a Python file object.
.. c:var:: PyTypeObject PyFile_Type
.. index:: single: FileType (in module types)
This instance of :c:type:`PyTypeObject` represents the Python file type. This is
exposed to Python programs as ``file`` and ``types.FileType``.
.. c:function:: int PyFile_Check(PyObject *p)
Return true if its argument is a :c:type:`PyFileObject` or a subtype of
:c:type:`PyFileObject`.
.. versionchanged:: 2.2
Allowed subtypes to be accepted.
.. c:function:: int PyFile_CheckExact(PyObject *p)
Return true if its argument is a :c:type:`PyFileObject`, but not a subtype of
:c:type:`PyFileObject`.
.. versionadded:: 2.2
.. c:function:: PyObject* PyFile_FromString(char *filename, char *mode)
.. index:: single: fopen()
On success, return a new file object that is opened on the file given by
*filename*, with a file mode given by *mode*, where *mode* has the same
semantics as the standard C routine :c:func:`fopen`. On failure, return *NULL*.
.. c:function:: PyObject* PyFile_FromFile(FILE *fp, char *name, char *mode, int (*close)(FILE*))
Create a new :c:type:`PyFileObject` from the already-open standard C file
pointer, *fp*. The function *close* will be called when the file should be
closed. Return *NULL* and close the file using *close* on failure.
*close* is optional and can be set to *NULL*.
.. c:function:: FILE* PyFile_AsFile(PyObject \*p)
Return the file object associated with *p* as a :c:type:`FILE\*`.
If the caller will ever use the returned :c:type:`FILE\*` object while
the :term:`GIL` is released it must also call the :c:func:`PyFile_IncUseCount` and
:c:func:`PyFile_DecUseCount` functions described below as appropriate.
.. c:function:: void PyFile_IncUseCount(PyFileObject \*p)
Increments the PyFileObject's internal use count to indicate
that the underlying :c:type:`FILE\*` is being used.
This prevents Python from calling f_close() on it from another thread.
Callers of this must call :c:func:`PyFile_DecUseCount` when they are
finished with the :c:type:`FILE\*`. Otherwise the file object will
never be closed by Python.
The :term:`GIL` must be held while calling this function.
The suggested use is to call this after :c:func:`PyFile_AsFile` and before
you release the GIL::
FILE *fp = PyFile_AsFile(p);
PyFile_IncUseCount(p);
/* ... */
Py_BEGIN_ALLOW_THREADS
do_something(fp);
Py_END_ALLOW_THREADS
/* ... */
PyFile_DecUseCount(p);
.. versionadded:: 2.6
.. c:function:: void PyFile_DecUseCount(PyFileObject \*p)
Decrements the PyFileObject's internal unlocked_count member to
indicate that the caller is done with its own use of the :c:type:`FILE\*`.
This may only be called to undo a prior call to :c:func:`PyFile_IncUseCount`.
The :term:`GIL` must be held while calling this function (see the example
above).
.. versionadded:: 2.6
.. c:function:: PyObject* PyFile_GetLine(PyObject *p, int n)
.. index:: single: EOFError (built-in exception)
Equivalent to ``p.readline([n])``, this function reads one line from the
object *p*. *p* may be a file object or any object with a
:meth:`~io.IOBase.readline`
method. If *n* is ``0``, exactly one line is read, regardless of the length of
the line. If *n* is greater than ``0``, no more than *n* bytes will be read
from the file; a partial line can be returned. In both cases, an empty string
is returned if the end of the file is reached immediately. If *n* is less than
``0``, however, one line is read regardless of length, but :exc:`EOFError` is
raised if the end of the file is reached immediately.
.. c:function:: PyObject* PyFile_Name(PyObject *p)
Return the name of the file specified by *p* as a string object.
.. c:function:: void PyFile_SetBufSize(PyFileObject *p, int n)
.. index:: single: setvbuf()
Available on systems with :c:func:`setvbuf` only. This should only be called
immediately after file object creation.
.. c:function:: int PyFile_SetEncoding(PyFileObject *p, const char *enc)
Set the file's encoding for Unicode output to *enc*. Return ``1`` on success and ``0``
on failure.
.. versionadded:: 2.3
.. c:function:: int PyFile_SetEncodingAndErrors(PyFileObject *p, const char *enc, *errors)
Set the file's encoding for Unicode output to *enc*, and its error
mode to *err*. Return ``1`` on success and ``0`` on failure.
.. versionadded:: 2.6
.. c:function:: int PyFile_SoftSpace(PyObject *p, int newflag)
.. index:: single: softspace (file attribute)
This function exists for internal use by the interpreter. Set the
:attr:`softspace` attribute of *p* to *newflag* and return the previous value.
*p* does not have to be a file object for this function to work properly; any
object is supported (thought its only interesting if the :attr:`softspace`
attribute can be set). This function clears any errors, and will return ``0``
as the previous value if the attribute either does not exist or if there were
errors in retrieving it. There is no way to detect errors from this function,
but doing so should not be needed.
.. c:function:: int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags)
.. index:: single: Py_PRINT_RAW
Write object *obj* to file object *p*. The only supported flag for *flags* is
:const:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written
instead of the :func:`repr`. Return ``0`` on success or ``-1`` on failure; the
appropriate exception will be set.
.. c:function:: int PyFile_WriteString(const char *s, PyObject *p)
Write string *s* to file object *p*. Return ``0`` on success or ``-1`` on
failure; the appropriate exception will be set.
PK %�\�J�+
+
! html/_sources/c-api/float.rst.txtnu �[��� .. highlightlang:: c
.. _floatobjects:
Floating Point Objects
----------------------
.. index:: object: floating point
.. c:type:: PyFloatObject
This subtype of :c:type:`PyObject` represents a Python floating point object.
.. c:var:: PyTypeObject PyFloat_Type
.. index:: single: FloatType (in modules types)
This instance of :c:type:`PyTypeObject` represents the Python floating point
type. This is the same object as ``float`` and ``types.FloatType``.
.. c:function:: int PyFloat_Check(PyObject *p)
Return true if its argument is a :c:type:`PyFloatObject` or a subtype of
:c:type:`PyFloatObject`.
.. versionchanged:: 2.2
Allowed subtypes to be accepted.
.. c:function:: int PyFloat_CheckExact(PyObject *p)
Return true if its argument is a :c:type:`PyFloatObject`, but not a subtype of
:c:type:`PyFloatObject`.
.. versionadded:: 2.2
.. c:function:: PyObject* PyFloat_FromString(PyObject *str, char **pend)
Create a :c:type:`PyFloatObject` object based on the string value in *str*, or
*NULL* on failure. The *pend* argument is ignored. It remains only for
backward compatibility.
.. c:function:: PyObject* PyFloat_FromDouble(double v)
Create a :c:type:`PyFloatObject` object from *v*, or *NULL* on failure.
.. c:function:: double PyFloat_AsDouble(PyObject *pyfloat)
Return a C :c:type:`double` representation of the contents of *pyfloat*. If
*pyfloat* is not a Python floating point object but has a :meth:`__float__`
method, this method will first be called to convert *pyfloat* into a float.
This method returns ``-1.0`` upon failure, so one should call
:c:func:`PyErr_Occurred` to check for errors.
.. c:function:: double PyFloat_AS_DOUBLE(PyObject *pyfloat)
Return a C :c:type:`double` representation of the contents of *pyfloat*, but
without error checking.
.. c:function:: PyObject* PyFloat_GetInfo(void)
Return a structseq instance which contains information about the
precision, minimum and maximum values of a float. It's a thin wrapper
around the header file :file:`float.h`.
.. versionadded:: 2.6
.. c:function:: double PyFloat_GetMax()
Return the maximum representable finite float *DBL_MAX* as C :c:type:`double`.
.. versionadded:: 2.6
.. c:function:: double PyFloat_GetMin()
Return the minimum normalized positive float *DBL_MIN* as C :c:type:`double`.
.. versionadded:: 2.6
.. c:function:: int PyFloat_ClearFreeList()
Clear the float free list. Return the number of items that could not
be freed.
.. versionadded:: 2.6
.. c:function:: void PyFloat_AsString(char *buf, PyFloatObject *v)
Convert the argument *v* to a string, using the same rules as
:func:`str`. The length of *buf* should be at least 100.
This function is unsafe to call because it writes to a buffer whose
length it does not know.
.. deprecated:: 2.7
Use :func:`PyObject_Str` or :func:`PyOS_double_to_string` instead.
.. c:function:: void PyFloat_AsReprString(char *buf, PyFloatObject *v)
Same as PyFloat_AsString, except uses the same rules as
:func:`repr`. The length of *buf* should be at least 100.
This function is unsafe to call because it writes to a buffer whose
length it does not know.
.. deprecated:: 2.7
Use :func:`PyObject_Repr` or :func:`PyOS_double_to_string` instead.
PK %�\��g�u u $ html/_sources/c-api/function.rst.txtnu �[��� .. highlightlang:: c
.. _function-objects:
Function Objects
----------------
.. index:: object: function
There are a few functions specific to Python functions.
.. c:type:: PyFunctionObject
The C structure used for functions.
.. c:var:: PyTypeObject PyFunction_Type
.. index:: single: MethodType (in module types)
This is an instance of :c:type:`PyTypeObject` and represents the Python function
type. It is exposed to Python programmers as ``types.FunctionType``.
.. c:function:: int PyFunction_Check(PyObject *o)
Return true if *o* is a function object (has type :c:data:`PyFunction_Type`).
The parameter must not be *NULL*.
.. c:function:: PyObject* PyFunction_New(PyObject *code, PyObject *globals)
Return a new function object associated with the code object *code*. *globals*
must be a dictionary with the global variables accessible to the function.
The function's docstring, name and *__module__* are retrieved from the code
object, the argument defaults and closure are set to *NULL*.
.. c:function:: PyObject* PyFunction_GetCode(PyObject *op)
Return the code object associated with the function object *op*.
.. c:function:: PyObject* PyFunction_GetGlobals(PyObject *op)
Return the globals dictionary associated with the function object *op*.
.. c:function:: PyObject* PyFunction_GetModule(PyObject *op)
Return the *__module__* attribute of the function object *op*. This is normally
a string containing the module name, but can be set to any other object by
Python code.
.. c:function:: PyObject* PyFunction_GetDefaults(PyObject *op)
Return the argument default values of the function object *op*. This can be a
tuple of arguments or *NULL*.
.. c:function:: int PyFunction_SetDefaults(PyObject *op, PyObject *defaults)
Set the argument default values for the function object *op*. *defaults* must be
*Py_None* or a tuple.
Raises :exc:`SystemError` and returns ``-1`` on failure.
.. c:function:: PyObject* PyFunction_GetClosure(PyObject *op)
Return the closure associated with the function object *op*. This can be *NULL*
or a tuple of cell objects.
.. c:function:: int PyFunction_SetClosure(PyObject *op, PyObject *closure)
Set the closure associated with the function object *op*. *closure* must be
*Py_None* or a tuple of cell objects.
Raises :exc:`SystemError` and returns ``-1`` on failure.
PK %�\X?�� � % html/_sources/c-api/gcsupport.rst.txtnu �[��� .. highlightlang:: c
.. _supporting-cycle-detection:
Supporting Cyclic Garbage Collection
====================================
Python's support for detecting and collecting garbage which involves circular
references requires support from object types which are "containers" for other
objects which may also be containers. Types which do not store references to
other objects, or which only store references to atomic types (such as numbers
or strings), do not need to provide any explicit support for garbage
collection.
.. An example showing the use of these interfaces can be found in "Supporting the
.. Cycle Collector (XXX not found: ../ext/example-cycle-support.html)".
To create a container type, the :c:member:`~PyTypeObject.tp_flags` field of the type object must
include the :const:`Py_TPFLAGS_HAVE_GC` and provide an implementation of the
:c:member:`~PyTypeObject.tp_traverse` handler. If instances of the type are mutable, a
:c:member:`~PyTypeObject.tp_clear` implementation must also be provided.
.. data:: Py_TPFLAGS_HAVE_GC
:noindex:
Objects with a type with this flag set must conform with the rules
documented here. For convenience these objects will be referred to as
container objects.
Constructors for container types must conform to two rules:
#. The memory for the object must be allocated using :c:func:`PyObject_GC_New`
or :c:func:`PyObject_GC_NewVar`.
#. Once all the fields which may contain references to other containers are
initialized, it must call :c:func:`PyObject_GC_Track`.
.. c:function:: TYPE* PyObject_GC_New(TYPE, PyTypeObject *type)
Analogous to :c:func:`PyObject_New` but for container objects with the
:const:`Py_TPFLAGS_HAVE_GC` flag set.
.. c:function:: TYPE* PyObject_GC_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)
Analogous to :c:func:`PyObject_NewVar` but for container objects with the
:const:`Py_TPFLAGS_HAVE_GC` flag set.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: TYPE* PyObject_GC_Resize(TYPE, PyVarObject *op, Py_ssize_t newsize)
Resize an object allocated by :c:func:`PyObject_NewVar`. Returns the
resized object or *NULL* on failure. *op* must not be tracked by the collector yet.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *newsize*. This might
require changes in your code for properly supporting 64-bit systems.
.. c:function:: void PyObject_GC_Track(PyObject *op)
Adds the object *op* to the set of container objects tracked by the
collector. The collector can run at unexpected times so objects must be
valid while being tracked. This should be called once all the fields
followed by the :c:member:`~PyTypeObject.tp_traverse` handler become valid, usually near the
end of the constructor.
.. c:function:: void _PyObject_GC_TRACK(PyObject *op)
A macro version of :c:func:`PyObject_GC_Track`. It should not be used for
extension modules.
Similarly, the deallocator for the object must conform to a similar pair of
rules:
#. Before fields which refer to other containers are invalidated,
:c:func:`PyObject_GC_UnTrack` must be called.
#. The object's memory must be deallocated using :c:func:`PyObject_GC_Del`.
.. c:function:: void PyObject_GC_Del(void *op)
Releases memory allocated to an object using :c:func:`PyObject_GC_New` or
:c:func:`PyObject_GC_NewVar`.
.. c:function:: void PyObject_GC_UnTrack(void *op)
Remove the object *op* from the set of container objects tracked by the
collector. Note that :c:func:`PyObject_GC_Track` can be called again on
this object to add it back to the set of tracked objects. The deallocator
(:c:member:`~PyTypeObject.tp_dealloc` handler) should call this for the object before any of
the fields used by the :c:member:`~PyTypeObject.tp_traverse` handler become invalid.
.. c:function:: void _PyObject_GC_UNTRACK(PyObject *op)
A macro version of :c:func:`PyObject_GC_UnTrack`. It should not be used for
extension modules.
The :c:member:`~PyTypeObject.tp_traverse` handler accepts a function parameter of this type:
.. c:type:: int (*visitproc)(PyObject *object, void *arg)
Type of the visitor function passed to the :c:member:`~PyTypeObject.tp_traverse` handler.
The function should be called with an object to traverse as *object* and
the third parameter to the :c:member:`~PyTypeObject.tp_traverse` handler as *arg*. The
Python core uses several visitor functions to implement cyclic garbage
detection; it's not expected that users will need to write their own
visitor functions.
The :c:member:`~PyTypeObject.tp_traverse` handler must have the following type:
.. c:type:: int (*traverseproc)(PyObject *self, visitproc visit, void *arg)
Traversal function for a container object. Implementations must call the
*visit* function for each object directly contained by *self*, with the
parameters to *visit* being the contained object and the *arg* value passed
to the handler. The *visit* function must not be called with a *NULL*
object argument. If *visit* returns a non-zero value that value should be
returned immediately.
To simplify writing :c:member:`~PyTypeObject.tp_traverse` handlers, a :c:func:`Py_VISIT` macro is
provided. In order to use this macro, the :c:member:`~PyTypeObject.tp_traverse` implementation
must name its arguments exactly *visit* and *arg*:
.. c:function:: void Py_VISIT(PyObject *o)
If *o* is not *NULL*, call the *visit* callback, with arguments *o*
and *arg*. If *visit* returns a non-zero value, then return it.
Using this macro, :c:member:`~PyTypeObject.tp_traverse` handlers
look like::
static int
my_traverse(Noddy *self, visitproc visit, void *arg)
{
Py_VISIT(self->foo);
Py_VISIT(self->bar);
return 0;
}
.. versionadded:: 2.4
The :c:member:`~PyTypeObject.tp_clear` handler must be of the :c:type:`inquiry` type, or *NULL*
if the object is immutable.
.. c:type:: int (*inquiry)(PyObject *self)
Drop references that may have created reference cycles. Immutable objects
do not have to define this method since they can never directly create
reference cycles. Note that the object must still be valid after calling
this method (don't just call :c:func:`Py_DECREF` on a reference). The
collector will call this method if it detects that this object is involved
in a reference cycle.
PK %�\���E� � html/_sources/c-api/gen.rst.txtnu �[��� .. highlightlang:: c
.. _gen-objects:
Generator Objects
-----------------
Generator objects are what Python uses to implement generator iterators. They
are normally created by iterating over a function that yields values, rather
than explicitly calling :c:func:`PyGen_New`.
.. c:type:: PyGenObject
The C structure used for generator objects.
.. c:var:: PyTypeObject PyGen_Type
The type object corresponding to generator objects.
.. c:function:: int PyGen_Check(ob)
Return true if *ob* is a generator object; *ob* must not be *NULL*.
.. c:function:: int PyGen_CheckExact(ob)
Return true if *ob*'s type is *PyGen_Type* is a generator object; *ob* must not
be *NULL*.
.. c:function:: PyObject* PyGen_New(PyFrameObject *frame)
Create and return a new generator object based on the *frame* object. A
reference to *frame* is stolen by this function. The parameter must not be
*NULL*.
PK %�\@i1�+ �+ " html/_sources/c-api/import.rst.txtnu �[��� .. highlightlang:: c
.. _importing:
Importing Modules
=================
.. c:function:: PyObject* PyImport_ImportModule(const char *name)
.. index::
single: package variable; __all__
single: __all__ (package variable)
single: modules (in module sys)
This is a simplified interface to :c:func:`PyImport_ImportModuleEx` below,
leaving the *globals* and *locals* arguments set to *NULL* and *level* set
to 0. When the *name*
argument contains a dot (when it specifies a submodule of a package), the
*fromlist* argument is set to the list ``['*']`` so that the return value is the
named module rather than the top-level package containing it as would otherwise
be the case. (Unfortunately, this has an additional side effect when *name* in
fact specifies a subpackage instead of a submodule: the submodules specified in
the package's ``__all__`` variable are loaded.) Return a new reference to the
imported module, or *NULL* with an exception set on failure. Before Python 2.4,
the module may still be created in the failure case --- examine ``sys.modules``
to find out. Starting with Python 2.4, a failing import of a module no longer
leaves the module in ``sys.modules``.
.. versionchanged:: 2.4
Failing imports remove incomplete module objects.
.. versionchanged:: 2.6
Always uses absolute imports.
.. c:function:: PyObject* PyImport_ImportModuleNoBlock(const char *name)
This version of :c:func:`PyImport_ImportModule` does not block. It's intended
to be used in C functions that import other modules to execute a function.
The import may block if another thread holds the import lock. The function
:c:func:`PyImport_ImportModuleNoBlock` never blocks. It first tries to fetch
the module from sys.modules and falls back to :c:func:`PyImport_ImportModule`
unless the lock is held, in which case the function will raise an
:exc:`ImportError`.
.. versionadded:: 2.6
.. c:function:: PyObject* PyImport_ImportModuleEx(char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)
.. index:: builtin: __import__
Import a module. This is best described by referring to the built-in Python
function :func:`__import__`, as the standard :func:`__import__` function calls
this function directly.
The return value is a new reference to the imported module or top-level package,
or *NULL* with an exception set on failure (before Python 2.4, the module may
still be created in this case). Like for :func:`__import__`, the return value
when a submodule of a package was requested is normally the top-level package,
unless a non-empty *fromlist* was given.
.. versionchanged:: 2.4
Failing imports remove incomplete module objects.
.. versionchanged:: 2.6
The function is an alias for :c:func:`PyImport_ImportModuleLevel` with
``-1`` as level, meaning relative import.
.. c:function:: PyObject* PyImport_ImportModuleLevel(char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)
Import a module. This is best described by referring to the built-in Python
function :func:`__import__`, as the standard :func:`__import__` function calls
this function directly.
The return value is a new reference to the imported module or top-level package,
or *NULL* with an exception set on failure. Like for :func:`__import__`,
the return value when a submodule of a package was requested is normally the
top-level package, unless a non-empty *fromlist* was given.
.. versionadded:: 2.5
.. c:function:: PyObject* PyImport_Import(PyObject *name)
.. index::
module: rexec
module: ihooks
This is a higher-level interface that calls the current "import hook function".
It invokes the :func:`__import__` function from the ``__builtins__`` of the
current globals. This means that the import is done using whatever import hooks
are installed in the current environment, e.g. by :mod:`rexec` or :mod:`ihooks`.
.. versionchanged:: 2.6
Always uses absolute imports.
.. c:function:: PyObject* PyImport_ReloadModule(PyObject *m)
.. index:: builtin: reload
Reload a module. This is best described by referring to the built-in Python
function :func:`reload`, as the standard :func:`reload` function calls this
function directly. Return a new reference to the reloaded module, or *NULL*
with an exception set on failure (the module still exists in this case).
.. c:function:: PyObject* PyImport_AddModule(const char *name)
Return the module object corresponding to a module name. The *name* argument
may be of the form ``package.module``. First check the modules dictionary if
there's one there, and if not, create a new one and insert it in the modules
dictionary. Return *NULL* with an exception set on failure.
.. note::
This function does not load or import the module; if the module wasn't already
loaded, you will get an empty module object. Use :c:func:`PyImport_ImportModule`
or one of its variants to import a module. Package structures implied by a
dotted name for *name* are not created if not already present.
.. c:function:: PyObject* PyImport_ExecCodeModule(char *name, PyObject *co)
.. index:: builtin: compile
Given a module name (possibly of the form ``package.module``) and a code object
read from a Python bytecode file or obtained from the built-in function
:func:`compile`, load the module. Return a new reference to the module object,
or *NULL* with an exception set if an error occurred. Before Python 2.4, the
module could still be created in error cases. Starting with Python 2.4, *name*
is removed from :attr:`sys.modules` in error cases, and even if *name* was already
in :attr:`sys.modules` on entry to :c:func:`PyImport_ExecCodeModule`. Leaving
incompletely initialized modules in :attr:`sys.modules` is dangerous, as imports of
such modules have no way to know that the module object is an unknown (and
probably damaged with respect to the module author's intents) state.
The module's :attr:`__file__` attribute will be set to the code object's
:c:member:`co_filename`.
This function will reload the module if it was already imported. See
:c:func:`PyImport_ReloadModule` for the intended way to reload a module.
If *name* points to a dotted name of the form ``package.module``, any package
structures not already created will still not be created.
.. versionchanged:: 2.4
*name* is removed from :attr:`sys.modules` in error cases.
.. c:function:: PyObject* PyImport_ExecCodeModuleEx(char *name, PyObject *co, char *pathname)
Like :c:func:`PyImport_ExecCodeModule`, but the :attr:`__file__` attribute of
the module object is set to *pathname* if it is non-``NULL``.
.. c:function:: long PyImport_GetMagicNumber()
Return the magic number for Python bytecode files (a.k.a. :file:`.pyc` and
:file:`.pyo` files). The magic number should be present in the first four bytes
of the bytecode file, in little-endian byte order.
.. c:function:: PyObject* PyImport_GetModuleDict()
Return the dictionary used for the module administration (a.k.a.
``sys.modules``). Note that this is a per-interpreter variable.
.. c:function:: PyObject* PyImport_GetImporter(PyObject *path)
Return an importer object for a :data:`sys.path`/:attr:`pkg.__path__` item
*path*, possibly by fetching it from the :data:`sys.path_importer_cache`
dict. If it wasn't yet cached, traverse :data:`sys.path_hooks` until a hook
is found that can handle the path item. Return ``None`` if no hook could;
this tells our caller it should fall back to the built-in import mechanism.
Cache the result in :data:`sys.path_importer_cache`. Return a new reference
to the importer object.
.. versionadded:: 2.6
.. c:function:: void _PyImport_Init()
Initialize the import mechanism. For internal use only.
.. c:function:: void PyImport_Cleanup()
Empty the module table. For internal use only.
.. c:function:: void _PyImport_Fini()
Finalize the import mechanism. For internal use only.
.. c:function:: PyObject* _PyImport_FindExtension(char *, char *)
For internal use only.
.. c:function:: PyObject* _PyImport_FixupExtension(char *, char *)
For internal use only.
.. c:function:: int PyImport_ImportFrozenModule(char *name)
Load a frozen module named *name*. Return ``1`` for success, ``0`` if the
module is not found, and ``-1`` with an exception set if the initialization
failed. To access the imported module on a successful load, use
:c:func:`PyImport_ImportModule`. (Note the misnomer --- this function would
reload the module if it was already imported.)
.. c:type:: struct _frozen
.. index:: single: freeze utility
This is the structure type definition for frozen module descriptors, as
generated by the :program:`freeze` utility (see :file:`Tools/freeze/` in the
Python source distribution). Its definition, found in :file:`Include/import.h`,
is::
struct _frozen {
char *name;
unsigned char *code;
int size;
};
.. c:var:: struct _frozen* PyImport_FrozenModules
This pointer is initialized to point to an array of :c:type:`struct _frozen`
records, terminated by one whose members are all *NULL* or zero. When a frozen
module is imported, it is searched in this table. Third-party code could play
tricks with this to provide a dynamically created collection of frozen modules.
.. c:function:: int PyImport_AppendInittab(const char *name, void (*initfunc)(void))
Add a single module to the existing table of built-in modules. This is a
convenience wrapper around :c:func:`PyImport_ExtendInittab`, returning ``-1`` if
the table could not be extended. The new module can be imported by the name
*name*, and uses the function *initfunc* as the initialization function called
on the first attempted import. This should be called before
:c:func:`Py_Initialize`.
.. c:type:: struct _inittab
Structure describing a single entry in the list of built-in modules. Each of
these structures gives the name and initialization function for a module built
into the interpreter. Programs which embed Python may use an array of these
structures in conjunction with :c:func:`PyImport_ExtendInittab` to provide
additional built-in modules. The structure is defined in
:file:`Include/import.h` as::
struct _inittab {
char *name;
void (*initfunc)(void);
};
.. c:function:: int PyImport_ExtendInittab(struct _inittab *newtab)
Add a collection of modules to the table of built-in modules. The *newtab*
array must end with a sentinel entry which contains *NULL* for the :attr:`name`
field; failure to provide the sentinel value can result in a memory fault.
Returns ``0`` on success or ``-1`` if insufficient memory could be allocated to
extend the internal table. In the event of failure, no modules are added to the
internal table. This should be called before :c:func:`Py_Initialize`.
PK %�\�~V.B B ! html/_sources/c-api/index.rst.txtnu �[��� .. _c-api-index:
##################################
Python/C API Reference Manual
##################################
This manual documents the API used by C and C++ programmers who want to write
extension modules or embed Python. It is a companion to :ref:`extending-index`,
which describes the general principles of extension writing but does not
document the API functions in detail.
.. toctree::
:maxdepth: 2
intro.rst
veryhigh.rst
refcounting.rst
exceptions.rst
utilities.rst
abstract.rst
concrete.rst
init.rst
memory.rst
objimpl.rst
PK %�\�T6�� � html/_sources/c-api/init.rst.txtnu �[��� .. highlightlang:: c
.. _initialization:
*****************************************
Initialization, Finalization, and Threads
*****************************************
Initializing and finalizing the interpreter
===========================================
.. c:function:: void Py_Initialize()
.. index::
single: Py_SetProgramName()
single: PyEval_InitThreads()
single: PyEval_ReleaseLock()
single: PyEval_AcquireLock()
single: modules (in module sys)
single: path (in module sys)
module: __builtin__
module: __main__
module: sys
triple: module; search; path
single: PySys_SetArgv()
single: PySys_SetArgvEx()
single: Py_Finalize()
Initialize the Python interpreter. In an application embedding Python, this
should be called before using any other Python/C API functions; with the
exception of :c:func:`Py_SetProgramName`, :c:func:`Py_SetPythonHome`, :c:func:`PyEval_InitThreads`,
:c:func:`PyEval_ReleaseLock`, and :c:func:`PyEval_AcquireLock`. This initializes
the table of loaded modules (``sys.modules``), and creates the fundamental
modules :mod:`__builtin__`, :mod:`__main__` and :mod:`sys`. It also initializes
the module search path (``sys.path``). It does not set ``sys.argv``; use
:c:func:`PySys_SetArgvEx` for that. This is a no-op when called for a second time
(without calling :c:func:`Py_Finalize` first). There is no return value; it is a
fatal error if the initialization fails.
.. c:function:: void Py_InitializeEx(int initsigs)
This function works like :c:func:`Py_Initialize` if *initsigs* is ``1``. If
*initsigs* is ``0``, it skips initialization registration of signal handlers, which
might be useful when Python is embedded.
.. versionadded:: 2.4
.. c:function:: int Py_IsInitialized()
Return true (nonzero) when the Python interpreter has been initialized, false
(zero) if not. After :c:func:`Py_Finalize` is called, this returns false until
:c:func:`Py_Initialize` is called again.
.. c:function:: void Py_Finalize()
Undo all initializations made by :c:func:`Py_Initialize` and subsequent use of
Python/C API functions, and destroy all sub-interpreters (see
:c:func:`Py_NewInterpreter` below) that were created and not yet destroyed since
the last call to :c:func:`Py_Initialize`. Ideally, this frees all memory
allocated by the Python interpreter. This is a no-op when called for a second
time (without calling :c:func:`Py_Initialize` again first). There is no return
value; errors during finalization are ignored.
This function is provided for a number of reasons. An embedding application
might want to restart Python without having to restart the application itself.
An application that has loaded the Python interpreter from a dynamically
loadable library (or DLL) might want to free all memory allocated by Python
before unloading the DLL. During a hunt for memory leaks in an application a
developer might want to free all memory allocated by Python before exiting from
the application.
**Bugs and caveats:** The destruction of modules and objects in modules is done
in random order; this may cause destructors (:meth:`__del__` methods) to fail
when they depend on other objects (even functions) or modules. Dynamically
loaded extension modules loaded by Python are not unloaded. Small amounts of
memory allocated by the Python interpreter may not be freed (if you find a leak,
please report it). Memory tied up in circular references between objects is not
freed. Some memory allocated by extension modules may not be freed. Some
extensions may not work properly if their initialization routine is called more
than once; this can happen if an application calls :c:func:`Py_Initialize` and
:c:func:`Py_Finalize` more than once.
Process-wide parameters
=======================
.. c:function:: void Py_SetProgramName(char *name)
.. index::
single: Py_Initialize()
single: main()
single: Py_GetPath()
This function should be called before :c:func:`Py_Initialize` is called for
the first time, if it is called at all. It tells the interpreter the value
of the ``argv[0]`` argument to the :c:func:`main` function of the program.
This is used by :c:func:`Py_GetPath` and some other functions below to find
the Python run-time libraries relative to the interpreter executable. The
default value is ``'python'``. The argument should point to a
zero-terminated character string in static storage whose contents will not
change for the duration of the program's execution. No code in the Python
interpreter will change the contents of this storage.
.. c:function:: char* Py_GetProgramName()
.. index:: single: Py_SetProgramName()
Return the program name set with :c:func:`Py_SetProgramName`, or the default.
The returned string points into static storage; the caller should not modify its
value.
.. c:function:: char* Py_GetPrefix()
Return the *prefix* for installed platform-independent files. This is derived
through a number of complicated rules from the program name set with
:c:func:`Py_SetProgramName` and some environment variables; for example, if the
program name is ``'/usr/local/bin/python'``, the prefix is ``'/usr/local'``. The
returned string points into static storage; the caller should not modify its
value. This corresponds to the :makevar:`prefix` variable in the top-level
:file:`Makefile` and the ``--prefix`` argument to the :program:`configure`
script at build time. The value is available to Python code as ``sys.prefix``.
It is only useful on Unix. See also the next function.
.. c:function:: char* Py_GetExecPrefix()
Return the *exec-prefix* for installed platform-*dependent* files. This is
derived through a number of complicated rules from the program name set with
:c:func:`Py_SetProgramName` and some environment variables; for example, if the
program name is ``'/usr/local/bin/python'``, the exec-prefix is
``'/usr/local'``. The returned string points into static storage; the caller
should not modify its value. This corresponds to the :makevar:`exec_prefix`
variable in the top-level :file:`Makefile` and the ``--exec-prefix``
argument to the :program:`configure` script at build time. The value is
available to Python code as ``sys.exec_prefix``. It is only useful on Unix.
Background: The exec-prefix differs from the prefix when platform dependent
files (such as executables and shared libraries) are installed in a different
directory tree. In a typical installation, platform dependent files may be
installed in the :file:`/usr/local/plat` subtree while platform independent may
be installed in :file:`/usr/local`.
Generally speaking, a platform is a combination of hardware and software
families, e.g. Sparc machines running the Solaris 2.x operating system are
considered the same platform, but Intel machines running Solaris 2.x are another
platform, and Intel machines running Linux are yet another platform. Different
major revisions of the same operating system generally also form different
platforms. Non-Unix operating systems are a different story; the installation
strategies on those systems are so different that the prefix and exec-prefix are
meaningless, and set to the empty string. Note that compiled Python bytecode
files are platform independent (but not independent from the Python version by
which they were compiled!).
System administrators will know how to configure the :program:`mount` or
:program:`automount` programs to share :file:`/usr/local` between platforms
while having :file:`/usr/local/plat` be a different filesystem for each
platform.
.. c:function:: char* Py_GetProgramFullPath()
.. index::
single: Py_SetProgramName()
single: executable (in module sys)
Return the full program name of the Python executable; this is computed as a
side-effect of deriving the default module search path from the program name
(set by :c:func:`Py_SetProgramName` above). The returned string points into
static storage; the caller should not modify its value. The value is available
to Python code as ``sys.executable``.
.. c:function:: char* Py_GetPath()
.. index::
triple: module; search; path
single: path (in module sys)
Return the default module search path; this is computed from the program name
(set by :c:func:`Py_SetProgramName` above) and some environment variables.
The returned string consists of a series of directory names separated by a
platform dependent delimiter character. The delimiter character is ``':'``
on Unix and Mac OS X, ``';'`` on Windows. The returned string points into
static storage; the caller should not modify its value. The list
:data:`sys.path` is initialized with this value on interpreter startup; it
can be (and usually is) modified later to change the search path for loading
modules.
.. XXX should give the exact rules
.. c:function:: const char* Py_GetVersion()
Return the version of this Python interpreter. This is a string that looks
something like ::
"1.5 (#67, Dec 31 1997, 22:34:28) [GCC 2.7.2.2]"
.. index:: single: version (in module sys)
The first word (up to the first space character) is the current Python version;
the first three characters are the major and minor version separated by a
period. The returned string points into static storage; the caller should not
modify its value. The value is available to Python code as ``sys.version``.
.. c:function:: const char* Py_GetPlatform()
.. index:: single: platform (in module sys)
Return the platform identifier for the current platform. On Unix, this is
formed from the "official" name of the operating system, converted to lower
case, followed by the major revision number; e.g., for Solaris 2.x, which is
also known as SunOS 5.x, the value is ``'sunos5'``. On Mac OS X, it is
``'darwin'``. On Windows, it is ``'win'``. The returned string points into
static storage; the caller should not modify its value. The value is available
to Python code as ``sys.platform``.
.. c:function:: const char* Py_GetCopyright()
Return the official copyright string for the current Python version, for example
``'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'``
.. index:: single: copyright (in module sys)
The returned string points into static storage; the caller should not modify its
value. The value is available to Python code as ``sys.copyright``.
.. c:function:: const char* Py_GetCompiler()
Return an indication of the compiler used to build the current Python version,
in square brackets, for example::
"[GCC 2.7.2.2]"
.. index:: single: version (in module sys)
The returned string points into static storage; the caller should not modify its
value. The value is available to Python code as part of the variable
``sys.version``.
.. c:function:: const char* Py_GetBuildInfo()
Return information about the sequence number and build date and time of the
current Python interpreter instance, for example ::
"#67, Aug 1 1997, 22:34:28"
.. index:: single: version (in module sys)
The returned string points into static storage; the caller should not modify its
value. The value is available to Python code as part of the variable
``sys.version``.
.. c:function:: void PySys_SetArgvEx(int argc, char **argv, int updatepath)
.. index::
single: main()
single: Py_FatalError()
single: argv (in module sys)
Set :data:`sys.argv` based on *argc* and *argv*. These parameters are
similar to those passed to the program's :c:func:`main` function with the
difference that the first entry should refer to the script file to be
executed rather than the executable hosting the Python interpreter. If there
isn't a script that will be run, the first entry in *argv* can be an empty
string. If this function fails to initialize :data:`sys.argv`, a fatal
condition is signalled using :c:func:`Py_FatalError`.
If *updatepath* is zero, this is all the function does. If *updatepath*
is non-zero, the function also modifies :data:`sys.path` according to the
following algorithm:
- If the name of an existing script is passed in ``argv[0]``, the absolute
path of the directory where the script is located is prepended to
:data:`sys.path`.
- Otherwise (that is, if *argc* is 0 or ``argv[0]`` doesn't point
to an existing file name), an empty string is prepended to
:data:`sys.path`, which is the same as prepending the current working
directory (``"."``).
.. note::
It is recommended that applications embedding the Python interpreter
for purposes other than executing a single script pass ``0`` as *updatepath*,
and update :data:`sys.path` themselves if desired.
See `CVE-2008-5983 <https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2008-5983>`_.
On versions before 2.6.6, you can achieve the same effect by manually
popping the first :data:`sys.path` element after having called
:c:func:`PySys_SetArgv`, for example using::
PyRun_SimpleString("import sys; sys.path.pop(0)\n");
.. versionadded:: 2.6.6
.. XXX impl. doesn't seem consistent in allowing ``0``/``NULL`` for the params;
check w/ Guido.
.. c:function:: void PySys_SetArgv(int argc, char **argv)
This function works like :c:func:`PySys_SetArgvEx` with *updatepath* set to ``1``.
.. c:function:: void Py_SetPythonHome(char *home)
Set the default "home" directory, that is, the location of the standard
Python libraries. See :envvar:`PYTHONHOME` for the meaning of the
argument string.
The argument should point to a zero-terminated character string in static
storage whose contents will not change for the duration of the program's
execution. No code in the Python interpreter will change the contents of
this storage.
.. c:function:: char* Py_GetPythonHome()
Return the default "home", that is, the value set by a previous call to
:c:func:`Py_SetPythonHome`, or the value of the :envvar:`PYTHONHOME`
environment variable if it is set.
.. _threads:
Thread State and the Global Interpreter Lock
============================================
.. index::
single: GIL
single: global interpreter lock
single: interpreter lock
single: lock, interpreter
The Python interpreter is not fully thread-safe. In order to support
multi-threaded Python programs, there's a global lock, called the :term:`global
interpreter lock` or :term:`GIL`, that must be held by the current thread before
it can safely access Python objects. Without the lock, even the simplest
operations could cause problems in a multi-threaded program: for example, when
two threads simultaneously increment the reference count of the same object, the
reference count could end up being incremented only once instead of twice.
.. index:: single: setcheckinterval() (in module sys)
Therefore, the rule exists that only the thread that has acquired the
:term:`GIL` may operate on Python objects or call Python/C API functions.
In order to emulate concurrency of execution, the interpreter regularly
tries to switch threads (see :func:`sys.setcheckinterval`). The lock is also
released around potentially blocking I/O operations like reading or writing
a file, so that other Python threads can run in the meantime.
.. index::
single: PyThreadState
single: PyThreadState
The Python interpreter keeps some thread-specific bookkeeping information
inside a data structure called :c:type:`PyThreadState`. There's also one
global variable pointing to the current :c:type:`PyThreadState`: it can
be retrieved using :c:func:`PyThreadState_Get`.
Releasing the GIL from extension code
-------------------------------------
Most extension code manipulating the :term:`GIL` has the following simple
structure::
Save the thread state in a local variable.
Release the global interpreter lock.
... Do some blocking I/O operation ...
Reacquire the global interpreter lock.
Restore the thread state from the local variable.
This is so common that a pair of macros exists to simplify it::
Py_BEGIN_ALLOW_THREADS
... Do some blocking I/O operation ...
Py_END_ALLOW_THREADS
.. index::
single: Py_BEGIN_ALLOW_THREADS
single: Py_END_ALLOW_THREADS
The :c:macro:`Py_BEGIN_ALLOW_THREADS` macro opens a new block and declares a
hidden local variable; the :c:macro:`Py_END_ALLOW_THREADS` macro closes the
block. These two macros are still available when Python is compiled without
thread support (they simply have an empty expansion).
When thread support is enabled, the block above expands to the following code::
PyThreadState *_save;
_save = PyEval_SaveThread();
...Do some blocking I/O operation...
PyEval_RestoreThread(_save);
.. index::
single: PyEval_RestoreThread()
single: PyEval_SaveThread()
Here is how these functions work: the global interpreter lock is used to protect the pointer to the
current thread state. When releasing the lock and saving the thread state,
the current thread state pointer must be retrieved before the lock is released
(since another thread could immediately acquire the lock and store its own thread
state in the global variable). Conversely, when acquiring the lock and restoring
the thread state, the lock must be acquired before storing the thread state
pointer.
.. note::
Calling system I/O functions is the most common use case for releasing
the GIL, but it can also be useful before calling long-running computations
which don't need access to Python objects, such as compression or
cryptographic functions operating over memory buffers. For example, the
standard :mod:`zlib` and :mod:`hashlib` modules release the GIL when
compressing or hashing data.
.. _gilstate:
Non-Python created threads
--------------------------
When threads are created using the dedicated Python APIs (such as the
:mod:`threading` module), a thread state is automatically associated to them
and the code showed above is therefore correct. However, when threads are
created from C (for example by a third-party library with its own thread
management), they don't hold the GIL, nor is there a thread state structure
for them.
If you need to call Python code from these threads (often this will be part
of a callback API provided by the aforementioned third-party library),
you must first register these threads with the interpreter by
creating a thread state data structure, then acquiring the GIL, and finally
storing their thread state pointer, before you can start using the Python/C
API. When you are done, you should reset the thread state pointer, release
the GIL, and finally free the thread state data structure.
The :c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release` functions do
all of the above automatically. The typical idiom for calling into Python
from a C thread is::
PyGILState_STATE gstate;
gstate = PyGILState_Ensure();
/* Perform Python actions here. */
result = CallSomeFunction();
/* evaluate result or handle exception */
/* Release the thread. No Python API allowed beyond this point. */
PyGILState_Release(gstate);
Note that the :c:func:`PyGILState_\*` functions assume there is only one global
interpreter (created automatically by :c:func:`Py_Initialize`). Python
supports the creation of additional interpreters (using
:c:func:`Py_NewInterpreter`), but mixing multiple interpreters and the
:c:func:`PyGILState_\*` API is unsupported.
Another important thing to note about threads is their behaviour in the face
of the C :c:func:`fork` call. On most systems with :c:func:`fork`, after a
process forks only the thread that issued the fork will exist. That also
means any locks held by other threads will never be released. Python solves
this for :func:`os.fork` by acquiring the locks it uses internally before
the fork, and releasing them afterwards. In addition, it resets any
:ref:`lock-objects` in the child. When extending or embedding Python, there
is no way to inform Python of additional (non-Python) locks that need to be
acquired before or reset after a fork. OS facilities such as
:c:func:`pthread_atfork` would need to be used to accomplish the same thing.
Additionally, when extending or embedding Python, calling :c:func:`fork`
directly rather than through :func:`os.fork` (and returning to or calling
into Python) may result in a deadlock by one of Python's internal locks
being held by a thread that is defunct after the fork.
:c:func:`PyOS_AfterFork` tries to reset the necessary locks, but is not
always able to.
High-level API
--------------
These are the most commonly used types and functions when writing C extension
code, or when embedding the Python interpreter:
.. c:type:: PyInterpreterState
This data structure represents the state shared by a number of cooperating
threads. Threads belonging to the same interpreter share their module
administration and a few other internal items. There are no public members in
this structure.
Threads belonging to different interpreters initially share nothing, except
process state like available memory, open file descriptors and such. The global
interpreter lock is also shared by all threads, regardless of to which
interpreter they belong.
.. c:type:: PyThreadState
This data structure represents the state of a single thread. The only public
data member is :c:type:`PyInterpreterState \*`:attr:`interp`, which points to
this thread's interpreter state.
.. c:function:: void PyEval_InitThreads()
.. index::
single: PyEval_ReleaseLock()
single: PyEval_ReleaseThread()
single: PyEval_SaveThread()
single: PyEval_RestoreThread()
Initialize and acquire the global interpreter lock. It should be called in the
main thread before creating a second thread or engaging in any other thread
operations such as :c:func:`PyEval_ReleaseLock` or
``PyEval_ReleaseThread(tstate)``. It is not needed before calling
:c:func:`PyEval_SaveThread` or :c:func:`PyEval_RestoreThread`.
.. index:: single: Py_Initialize()
This is a no-op when called for a second time. It is safe to call this function
before calling :c:func:`Py_Initialize`.
.. index:: module: thread
.. note::
When only the main thread exists, no GIL operations are needed. This is a
common situation (most Python programs do not use threads), and the lock
operations slow the interpreter down a bit. Therefore, the lock is not
created initially. This situation is equivalent to having acquired the lock:
when there is only a single thread, all object accesses are safe. Therefore,
when this function initializes the global interpreter lock, it also acquires
it. Before the Python :mod:`_thread` module creates a new thread, knowing
that either it has the lock or the lock hasn't been created yet, it calls
:c:func:`PyEval_InitThreads`. When this call returns, it is guaranteed that
the lock has been created and that the calling thread has acquired it.
It is **not** safe to call this function when it is unknown which thread (if
any) currently has the global interpreter lock.
This function is not available when thread support is disabled at compile time.
.. c:function:: int PyEval_ThreadsInitialized()
Returns a non-zero value if :c:func:`PyEval_InitThreads` has been called. This
function can be called without holding the GIL, and therefore can be used to
avoid calls to the locking API when running single-threaded. This function is
not available when thread support is disabled at compile time.
.. versionadded:: 2.4
.. c:function:: PyThreadState* PyEval_SaveThread()
Release the global interpreter lock (if it has been created and thread
support is enabled) and reset the thread state to *NULL*, returning the
previous thread state (which is not *NULL*). If the lock has been created,
the current thread must have acquired it. (This function is available even
when thread support is disabled at compile time.)
.. c:function:: void PyEval_RestoreThread(PyThreadState *tstate)
Acquire the global interpreter lock (if it has been created and thread
support is enabled) and set the thread state to *tstate*, which must not be
*NULL*. If the lock has been created, the current thread must not have
acquired it, otherwise deadlock ensues. (This function is available even
when thread support is disabled at compile time.)
.. c:function:: PyThreadState* PyThreadState_Get()
Return the current thread state. The global interpreter lock must be held.
When the current thread state is *NULL*, this issues a fatal error (so that
the caller needn't check for *NULL*).
.. c:function:: PyThreadState* PyThreadState_Swap(PyThreadState *tstate)
Swap the current thread state with the thread state given by the argument
*tstate*, which may be *NULL*. The global interpreter lock must be held
and is not released.
.. c:function:: void PyEval_ReInitThreads()
This function is called from :c:func:`PyOS_AfterFork` to ensure that newly
created child processes don't hold locks referring to threads which
are not running in the child process.
The following functions use thread-local storage, and are not compatible
with sub-interpreters:
.. c:function:: PyGILState_STATE PyGILState_Ensure()
Ensure that the current thread is ready to call the Python C API regardless
of the current state of Python, or of the global interpreter lock. This may
be called as many times as desired by a thread as long as each call is
matched with a call to :c:func:`PyGILState_Release`. In general, other
thread-related APIs may be used between :c:func:`PyGILState_Ensure` and
:c:func:`PyGILState_Release` calls as long as the thread state is restored to
its previous state before the Release(). For example, normal usage of the
:c:macro:`Py_BEGIN_ALLOW_THREADS` and :c:macro:`Py_END_ALLOW_THREADS` macros is
acceptable.
The return value is an opaque "handle" to the thread state when
:c:func:`PyGILState_Ensure` was called, and must be passed to
:c:func:`PyGILState_Release` to ensure Python is left in the same state. Even
though recursive calls are allowed, these handles *cannot* be shared - each
unique call to :c:func:`PyGILState_Ensure` must save the handle for its call
to :c:func:`PyGILState_Release`.
When the function returns, the current thread will hold the GIL and be able
to call arbitrary Python code. Failure is a fatal error.
.. versionadded:: 2.3
.. c:function:: void PyGILState_Release(PyGILState_STATE)
Release any resources previously acquired. After this call, Python's state will
be the same as it was prior to the corresponding :c:func:`PyGILState_Ensure` call
(but generally this state will be unknown to the caller, hence the use of the
GILState API).
Every call to :c:func:`PyGILState_Ensure` must be matched by a call to
:c:func:`PyGILState_Release` on the same thread.
.. versionadded:: 2.3
.. c:function:: PyThreadState* PyGILState_GetThisThreadState()
Get the current thread state for this thread. May return ``NULL`` if no
GILState API has been used on the current thread. Note that the main thread
always has such a thread-state, even if no auto-thread-state call has been
made on the main thread. This is mainly a helper/diagnostic function.
.. versionadded:: 2.3
The following macros are normally used without a trailing semicolon; look for
example usage in the Python source distribution.
.. c:macro:: Py_BEGIN_ALLOW_THREADS
This macro expands to ``{ PyThreadState *_save; _save = PyEval_SaveThread();``.
Note that it contains an opening brace; it must be matched with a following
:c:macro:`Py_END_ALLOW_THREADS` macro. See above for further discussion of this
macro. It is a no-op when thread support is disabled at compile time.
.. c:macro:: Py_END_ALLOW_THREADS
This macro expands to ``PyEval_RestoreThread(_save); }``. Note that it contains
a closing brace; it must be matched with an earlier
:c:macro:`Py_BEGIN_ALLOW_THREADS` macro. See above for further discussion of
this macro. It is a no-op when thread support is disabled at compile time.
.. c:macro:: Py_BLOCK_THREADS
This macro expands to ``PyEval_RestoreThread(_save);``: it is equivalent to
:c:macro:`Py_END_ALLOW_THREADS` without the closing brace. It is a no-op when
thread support is disabled at compile time.
.. c:macro:: Py_UNBLOCK_THREADS
This macro expands to ``_save = PyEval_SaveThread();``: it is equivalent to
:c:macro:`Py_BEGIN_ALLOW_THREADS` without the opening brace and variable
declaration. It is a no-op when thread support is disabled at compile time.
Low-level API
-------------
All of the following functions are only available when thread support is enabled
at compile time, and must be called only when the global interpreter lock has
been created.
.. c:function:: PyInterpreterState* PyInterpreterState_New()
Create a new interpreter state object. The global interpreter lock need not
be held, but may be held if it is necessary to serialize calls to this
function.
.. c:function:: void PyInterpreterState_Clear(PyInterpreterState *interp)
Reset all information in an interpreter state object. The global interpreter
lock must be held.
.. c:function:: void PyInterpreterState_Delete(PyInterpreterState *interp)
Destroy an interpreter state object. The global interpreter lock need not be
held. The interpreter state must have been reset with a previous call to
:c:func:`PyInterpreterState_Clear`.
.. c:function:: PyThreadState* PyThreadState_New(PyInterpreterState *interp)
Create a new thread state object belonging to the given interpreter object.
The global interpreter lock need not be held, but may be held if it is
necessary to serialize calls to this function.
.. c:function:: void PyThreadState_Clear(PyThreadState *tstate)
Reset all information in a thread state object. The global interpreter lock
must be held.
.. c:function:: void PyThreadState_Delete(PyThreadState *tstate)
Destroy a thread state object. The global interpreter lock need not be held.
The thread state must have been reset with a previous call to
:c:func:`PyThreadState_Clear`.
.. c:function:: PyObject* PyThreadState_GetDict()
Return a dictionary in which extensions can store thread-specific state
information. Each extension should use a unique key to use to store state in
the dictionary. It is okay to call this function when no current thread state
is available. If this function returns *NULL*, no exception has been raised and
the caller should assume no current thread state is available.
.. versionchanged:: 2.3
Previously this could only be called when a current thread is active, and *NULL*
meant that an exception was raised.
.. c:function:: int PyThreadState_SetAsyncExc(long id, PyObject *exc)
Asynchronously raise an exception in a thread. The *id* argument is the thread
id of the target thread; *exc* is the exception object to be raised. This
function does not steal any references to *exc*. To prevent naive misuse, you
must write your own C extension to call this. Must be called with the GIL held.
Returns the number of thread states modified; this is normally one, but will be
zero if the thread id isn't found. If *exc* is :const:`NULL`, the pending
exception (if any) for the thread is cleared. This raises no exceptions.
.. versionadded:: 2.3
.. c:function:: void PyEval_AcquireThread(PyThreadState *tstate)
Acquire the global interpreter lock and set the current thread state to
*tstate*, which should not be *NULL*. The lock must have been created earlier.
If this thread already has the lock, deadlock ensues.
:c:func:`PyEval_RestoreThread` is a higher-level function which is always
available (even when thread support isn't enabled or when threads have
not been initialized).
.. c:function:: void PyEval_ReleaseThread(PyThreadState *tstate)
Reset the current thread state to *NULL* and release the global interpreter
lock. The lock must have been created earlier and must be held by the current
thread. The *tstate* argument, which must not be *NULL*, is only used to check
that it represents the current thread state --- if it isn't, a fatal error is
reported.
:c:func:`PyEval_SaveThread` is a higher-level function which is always
available (even when thread support isn't enabled or when threads have
not been initialized).
.. c:function:: void PyEval_AcquireLock()
Acquire the global interpreter lock. The lock must have been created earlier.
If this thread already has the lock, a deadlock ensues.
.. warning::
This function does not change the current thread state. Please use
:c:func:`PyEval_RestoreThread` or :c:func:`PyEval_AcquireThread`
instead.
.. c:function:: void PyEval_ReleaseLock()
Release the global interpreter lock. The lock must have been created earlier.
.. warning::
This function does not change the current thread state. Please use
:c:func:`PyEval_SaveThread` or :c:func:`PyEval_ReleaseThread`
instead.
Sub-interpreter support
=======================
While in most uses, you will only embed a single Python interpreter, there
are cases where you need to create several independent interpreters in the
same process and perhaps even in the same thread. Sub-interpreters allow
you to do that. You can switch between sub-interpreters using the
:c:func:`PyThreadState_Swap` function. You can create and destroy them
using the following functions:
.. c:function:: PyThreadState* Py_NewInterpreter()
.. index::
module: builtins
module: __main__
module: sys
single: stdout (in module sys)
single: stderr (in module sys)
single: stdin (in module sys)
Create a new sub-interpreter. This is an (almost) totally separate environment
for the execution of Python code. In particular, the new interpreter has
separate, independent versions of all imported modules, including the
fundamental modules :mod:`builtins`, :mod:`__main__` and :mod:`sys`. The
table of loaded modules (``sys.modules``) and the module search path
(``sys.path``) are also separate. The new environment has no ``sys.argv``
variable. It has new standard I/O stream file objects ``sys.stdin``,
``sys.stdout`` and ``sys.stderr`` (however these refer to the same underlying
file descriptors).
The return value points to the first thread state created in the new
sub-interpreter. This thread state is made in the current thread state.
Note that no actual thread is created; see the discussion of thread states
below. If creation of the new interpreter is unsuccessful, *NULL* is
returned; no exception is set since the exception state is stored in the
current thread state and there may not be a current thread state. (Like all
other Python/C API functions, the global interpreter lock must be held before
calling this function and is still held when it returns; however, unlike most
other Python/C API functions, there needn't be a current thread state on
entry.)
.. index::
single: Py_Finalize()
single: Py_Initialize()
Extension modules are shared between (sub-)interpreters as follows: the first
time a particular extension is imported, it is initialized normally, and a
(shallow) copy of its module's dictionary is squirreled away. When the same
extension is imported by another (sub-)interpreter, a new module is initialized
and filled with the contents of this copy; the extension's ``init`` function is
not called. Note that this is different from what happens when an extension is
imported after the interpreter has been completely re-initialized by calling
:c:func:`Py_Finalize` and :c:func:`Py_Initialize`; in that case, the extension's
``initmodule`` function *is* called again.
.. index:: single: close() (in module os)
.. c:function:: void Py_EndInterpreter(PyThreadState *tstate)
.. index:: single: Py_Finalize()
Destroy the (sub-)interpreter represented by the given thread state. The given
thread state must be the current thread state. See the discussion of thread
states below. When the call returns, the current thread state is *NULL*. All
thread states associated with this interpreter are destroyed. (The global
interpreter lock must be held before calling this function and is still held
when it returns.) :c:func:`Py_Finalize` will destroy all sub-interpreters that
haven't been explicitly destroyed at that point.
Bugs and caveats
----------------
Because sub-interpreters (and the main interpreter) are part of the same
process, the insulation between them isn't perfect --- for example, using
low-level file operations like :func:`os.close` they can
(accidentally or maliciously) affect each other's open files. Because of the
way extensions are shared between (sub-)interpreters, some extensions may not
work properly; this is especially likely when the extension makes use of
(static) global variables, or when the extension manipulates its module's
dictionary after its initialization. It is possible to insert objects created
in one sub-interpreter into a namespace of another sub-interpreter; this should
be done with great care to avoid sharing user-defined functions, methods,
instances or classes between sub-interpreters, since import operations executed
by such objects may affect the wrong (sub-)interpreter's dictionary of loaded
modules.
Also note that combining this functionality with :c:func:`PyGILState_\*` APIs
is delicate, because these APIs assume a bijection between Python thread states
and OS-level threads, an assumption broken by the presence of sub-interpreters.
It is highly recommended that you don't switch sub-interpreters between a pair
of matching :c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release` calls.
Furthermore, extensions (such as :mod:`ctypes`) using these APIs to allow calling
of Python code from non-Python created threads will probably be broken when using
sub-interpreters.
Asynchronous Notifications
==========================
A mechanism is provided to make asynchronous notifications to the main
interpreter thread. These notifications take the form of a function
pointer and a void pointer argument.
.. c:function:: int Py_AddPendingCall(int (*func)(void *), void *arg)
.. index:: single: Py_AddPendingCall()
Schedule a function to be called from the main interpreter thread. On
success, ``0`` is returned and *func* is queued for being called in the
main thread. On failure, ``-1`` is returned without setting any exception.
When successfully queued, *func* will be *eventually* called from the
main interpreter thread with the argument *arg*. It will be called
asynchronously with respect to normally running Python code, but with
both these conditions met:
* on a :term:`bytecode` boundary;
* with the main thread holding the :term:`global interpreter lock`
(*func* can therefore use the full C API).
*func* must return ``0`` on success, or ``-1`` on failure with an exception
set. *func* won't be interrupted to perform another asynchronous
notification recursively, but it can still be interrupted to switch
threads if the global interpreter lock is released.
This function doesn't need a current thread state to run, and it doesn't
need the global interpreter lock.
.. warning::
This is a low-level function, only useful for very special cases.
There is no guarantee that *func* will be called as quick as
possible. If the main thread is busy executing a system call,
*func* won't be called before the system call returns. This
function is generally **not** suitable for calling Python code from
arbitrary C threads. Instead, use the :ref:`PyGILState API<gilstate>`.
.. versionadded:: 2.7
.. _profiling:
Profiling and Tracing
=====================
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
The Python interpreter provides some low-level support for attaching profiling
and execution tracing facilities. These are used for profiling, debugging, and
coverage analysis tools.
Starting with Python 2.2, the implementation of this facility was substantially
revised, and an interface from C was added. This C interface allows the
profiling or tracing code to avoid the overhead of calling through Python-level
callable objects, making a direct C function call instead. The essential
attributes of the facility have not changed; the interface allows trace
functions to be installed per-thread, and the basic events reported to the trace
function are the same as had been reported to the Python-level trace functions
in previous versions.
.. c:type:: int (*Py_tracefunc)(PyObject *obj, PyFrameObject *frame, int what, PyObject *arg)
The type of the trace function registered using :c:func:`PyEval_SetProfile` and
:c:func:`PyEval_SetTrace`. The first parameter is the object passed to the
registration function as *obj*, *frame* is the frame object to which the event
pertains, *what* is one of the constants :const:`PyTrace_CALL`,
:const:`PyTrace_EXCEPTION`, :const:`PyTrace_LINE`, :const:`PyTrace_RETURN`,
:const:`PyTrace_C_CALL`, :const:`PyTrace_C_EXCEPTION`, or
:const:`PyTrace_C_RETURN`, and *arg* depends on the value of *what*:
+------------------------------+--------------------------------------+
| Value of *what* | Meaning of *arg* |
+==============================+======================================+
| :const:`PyTrace_CALL` | Always :c:data:`Py_None`. |
+------------------------------+--------------------------------------+
| :const:`PyTrace_EXCEPTION` | Exception information as returned by |
| | :func:`sys.exc_info`. |
+------------------------------+--------------------------------------+
| :const:`PyTrace_LINE` | Always :c:data:`Py_None`. |
+------------------------------+--------------------------------------+
| :const:`PyTrace_RETURN` | Value being returned to the caller, |
| | or *NULL* if caused by an exception. |
+------------------------------+--------------------------------------+
| :const:`PyTrace_C_CALL` | Function object being called. |
+------------------------------+--------------------------------------+
| :const:`PyTrace_C_EXCEPTION` | Function object being called. |
+------------------------------+--------------------------------------+
| :const:`PyTrace_C_RETURN` | Function object being called. |
+------------------------------+--------------------------------------+
.. c:var:: int PyTrace_CALL
The value of the *what* parameter to a :c:type:`Py_tracefunc` function when a new
call to a function or method is being reported, or a new entry into a generator.
Note that the creation of the iterator for a generator function is not reported
as there is no control transfer to the Python bytecode in the corresponding
frame.
.. c:var:: int PyTrace_EXCEPTION
The value of the *what* parameter to a :c:type:`Py_tracefunc` function when an
exception has been raised. The callback function is called with this value for
*what* when after any bytecode is processed after which the exception becomes
set within the frame being executed. The effect of this is that as exception
propagation causes the Python stack to unwind, the callback is called upon
return to each frame as the exception propagates. Only trace functions receives
these events; they are not needed by the profiler.
.. c:var:: int PyTrace_LINE
The value passed as the *what* parameter to a trace function (but not a
profiling function) when a line-number event is being reported.
.. c:var:: int PyTrace_RETURN
The value for the *what* parameter to :c:type:`Py_tracefunc` functions when a
call is about to return.
.. c:var:: int PyTrace_C_CALL
The value for the *what* parameter to :c:type:`Py_tracefunc` functions when a C
function is about to be called.
.. c:var:: int PyTrace_C_EXCEPTION
The value for the *what* parameter to :c:type:`Py_tracefunc` functions when a C
function has raised an exception.
.. c:var:: int PyTrace_C_RETURN
The value for the *what* parameter to :c:type:`Py_tracefunc` functions when a C
function has returned.
.. c:function:: void PyEval_SetProfile(Py_tracefunc func, PyObject *obj)
Set the profiler function to *func*. The *obj* parameter is passed to the
function as its first parameter, and may be any Python object, or *NULL*. If
the profile function needs to maintain state, using a different value for *obj*
for each thread provides a convenient and thread-safe place to store it. The
profile function is called for all monitored events except :const:`PyTrace_LINE`
and :const:`PyTrace_EXCEPTION`.
.. c:function:: void PyEval_SetTrace(Py_tracefunc func, PyObject *obj)
Set the tracing function to *func*. This is similar to
:c:func:`PyEval_SetProfile`, except the tracing function does receive line-number
events and does not receive any event related to C function objects being called. Any
trace function registered using :c:func:`PyEval_SetTrace` will not receive
:const:`PyTrace_C_CALL`, :const:`PyTrace_C_EXCEPTION` or :const:`PyTrace_C_RETURN`
as a value for the *what* parameter.
.. c:function:: PyObject* PyEval_GetCallStats(PyObject *self)
Return a tuple of function call counts. There are constants defined for the
positions within the tuple:
+-------------------------------+-------+
| Name | Value |
+===============================+=======+
| :const:`PCALL_ALL` | 0 |
+-------------------------------+-------+
| :const:`PCALL_FUNCTION` | 1 |
+-------------------------------+-------+
| :const:`PCALL_FAST_FUNCTION` | 2 |
+-------------------------------+-------+
| :const:`PCALL_FASTER_FUNCTION`| 3 |
+-------------------------------+-------+
| :const:`PCALL_METHOD` | 4 |
+-------------------------------+-------+
| :const:`PCALL_BOUND_METHOD` | 5 |
+-------------------------------+-------+
| :const:`PCALL_CFUNCTION` | 6 |
+-------------------------------+-------+
| :const:`PCALL_TYPE` | 7 |
+-------------------------------+-------+
| :const:`PCALL_GENERATOR` | 8 |
+-------------------------------+-------+
| :const:`PCALL_OTHER` | 9 |
+-------------------------------+-------+
| :const:`PCALL_POP` | 10 |
+-------------------------------+-------+
:const:`PCALL_FAST_FUNCTION` means no argument tuple needs to be created.
:const:`PCALL_FASTER_FUNCTION` means that the fast-path frame setup code is used.
If there is a method call where the call can be optimized by changing
the argument tuple and calling the function directly, it gets recorded
twice.
This function is only present if Python is compiled with :const:`CALL_PROFILE`
defined.
.. _advanced-debugging:
Advanced Debugger Support
=========================
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
These functions are only intended to be used by advanced debugging tools.
.. c:function:: PyInterpreterState* PyInterpreterState_Head()
Return the interpreter state object at the head of the list of all such objects.
.. versionadded:: 2.2
.. c:function:: PyInterpreterState* PyInterpreterState_Next(PyInterpreterState *interp)
Return the next interpreter state object after *interp* from the list of all
such objects.
.. versionadded:: 2.2
.. c:function:: PyThreadState * PyInterpreterState_ThreadHead(PyInterpreterState *interp)
Return the pointer to the first :c:type:`PyThreadState` object in the list of
threads associated with the interpreter *interp*.
.. versionadded:: 2.2
.. c:function:: PyThreadState* PyThreadState_Next(PyThreadState *tstate)
Return the next thread state object after *tstate* from the list of all such
objects belonging to the same :c:type:`PyInterpreterState` object.
.. versionadded:: 2.2
PK %�\�O��� � html/_sources/c-api/int.rst.txtnu �[��� .. highlightlang:: c
.. _intobjects:
Plain Integer Objects
---------------------
.. index:: object: integer
.. c:type:: PyIntObject
This subtype of :c:type:`PyObject` represents a Python integer object.
.. c:var:: PyTypeObject PyInt_Type
.. index:: single: IntType (in modules types)
This instance of :c:type:`PyTypeObject` represents the Python plain integer type.
This is the same object as ``int`` and ``types.IntType``.
.. c:function:: int PyInt_Check(PyObject *o)
Return true if *o* is of type :c:data:`PyInt_Type` or a subtype of
:c:data:`PyInt_Type`.
.. versionchanged:: 2.2
Allowed subtypes to be accepted.
.. c:function:: int PyInt_CheckExact(PyObject *o)
Return true if *o* is of type :c:data:`PyInt_Type`, but not a subtype of
:c:data:`PyInt_Type`.
.. versionadded:: 2.2
.. c:function:: PyObject* PyInt_FromString(char *str, char **pend, int base)
Return a new :c:type:`PyIntObject` or :c:type:`PyLongObject` based on the string
value in *str*, which is interpreted according to the radix in *base*. If
*pend* is non-*NULL*, ``*pend`` will point to the first character in *str* which
follows the representation of the number. If *base* is ``0``, the radix will be
determined based on the leading characters of *str*: if *str* starts with
``'0x'`` or ``'0X'``, radix 16 will be used; if *str* starts with ``'0'``, radix
8 will be used; otherwise radix 10 will be used. If *base* is not ``0``, it
must be between ``2`` and ``36``, inclusive. Leading spaces are ignored. If
there are no digits, :exc:`ValueError` will be raised. If the string represents
a number too large to be contained within the machine's :c:type:`long int` type
and overflow warnings are being suppressed, a :c:type:`PyLongObject` will be
returned. If overflow warnings are not being suppressed, *NULL* will be
returned in this case.
.. c:function:: PyObject* PyInt_FromLong(long ival)
Create a new integer object with a value of *ival*.
The current implementation keeps an array of integer objects for all integers
between ``-5`` and ``256``, when you create an int in that range you actually
just get back a reference to the existing object. So it should be possible to
change the value of ``1``. I suspect the behaviour of Python in this case is
undefined. :-)
.. c:function:: PyObject* PyInt_FromSsize_t(Py_ssize_t ival)
Create a new integer object with a value of *ival*. If the value is larger
than ``LONG_MAX`` or smaller than ``LONG_MIN``, a long integer object is
returned.
.. versionadded:: 2.5
.. c:function:: PyObject* PyInt_FromSize_t(size_t ival)
Create a new integer object with a value of *ival*. If the value exceeds
``LONG_MAX``, a long integer object is returned.
.. versionadded:: 2.5
.. c:function:: long PyInt_AsLong(PyObject *io)
Will first attempt to cast the object to a :c:type:`PyIntObject`, if it is not
already one, and then return its value. If there is an error, ``-1`` is
returned, and the caller should check ``PyErr_Occurred()`` to find out whether
there was an error, or whether the value just happened to be ``-1``.
.. c:function:: long PyInt_AS_LONG(PyObject *io)
Return the value of the object *io*. No error checking is performed.
.. c:function:: unsigned long PyInt_AsUnsignedLongMask(PyObject *io)
Will first attempt to cast the object to a :c:type:`PyIntObject` or
:c:type:`PyLongObject`, if it is not already one, and then return its value as
unsigned long. This function does not check for overflow.
.. versionadded:: 2.3
.. c:function:: unsigned PY_LONG_LONG PyInt_AsUnsignedLongLongMask(PyObject *io)
Will first attempt to cast the object to a :c:type:`PyIntObject` or
:c:type:`PyLongObject`, if it is not already one, and then return its value as
unsigned long long, without checking for overflow.
.. versionadded:: 2.3
.. c:function:: Py_ssize_t PyInt_AsSsize_t(PyObject *io)
Will first attempt to cast the object to a :c:type:`PyIntObject` or
:c:type:`PyLongObject`, if it is not already one, and then return its value as
:c:type:`Py_ssize_t`.
.. versionadded:: 2.5
.. c:function:: long PyInt_GetMax()
.. index:: single: LONG_MAX
Return the system's idea of the largest integer it can handle
(:const:`LONG_MAX`, as defined in the system header files).
.. c:function:: int PyInt_ClearFreeList()
Clear the integer free list. Return the number of items that could not
be freed.
.. versionadded:: 2.6
PK %�\�?��9o 9o ! html/_sources/c-api/intro.rst.txtnu �[��� .. highlightlang:: c
.. _api-intro:
************
Introduction
************
The Application Programmer's Interface to Python gives C and C++ programmers
access to the Python interpreter at a variety of levels. The API is equally
usable from C++, but for brevity it is generally referred to as the Python/C
API. There are two fundamentally different reasons for using the Python/C API.
The first reason is to write *extension modules* for specific purposes; these
are C modules that extend the Python interpreter. This is probably the most
common use. The second reason is to use Python as a component in a larger
application; this technique is generally referred to as :dfn:`embedding` Python
in an application.
Writing an extension module is a relatively well-understood process, where a
"cookbook" approach works well. There are several tools that automate the
process to some extent. While people have embedded Python in other
applications since its early existence, the process of embedding Python is less
straightforward than writing an extension.
Many API functions are useful independent of whether you're embedding or
extending Python; moreover, most applications that embed Python will need to
provide a custom extension as well, so it's probably a good idea to become
familiar with writing an extension before attempting to embed Python in a real
application.
.. _api-includes:
Include Files
=============
All function, type and macro definitions needed to use the Python/C API are
included in your code by the following line::
#include "Python.h"
This implies inclusion of the following standard headers: ``<stdio.h>``,
``<string.h>``, ``<errno.h>``, ``<limits.h>``, ``<assert.h>`` and ``<stdlib.h>``
(if available).
.. note::
Since Python may define some pre-processor definitions which affect the standard
headers on some systems, you *must* include :file:`Python.h` before any standard
headers are included.
All user visible names defined by Python.h (except those defined by the included
standard headers) have one of the prefixes ``Py`` or ``_Py``. Names beginning
with ``_Py`` are for internal use by the Python implementation and should not be
used by extension writers. Structure member names do not have a reserved prefix.
**Important:** user code should never define names that begin with ``Py`` or
``_Py``. This confuses the reader, and jeopardizes the portability of the user
code to future Python versions, which may define additional names beginning with
one of these prefixes.
The header files are typically installed with Python. On Unix, these are
located in the directories :file:`{prefix}/include/pythonversion/` and
:file:`{exec_prefix}/include/pythonversion/`, where :envvar:`prefix` and
:envvar:`exec_prefix` are defined by the corresponding parameters to Python's
:program:`configure` script and *version* is ``sys.version[:3]``. On Windows,
the headers are installed in :file:`{prefix}/include`, where :envvar:`prefix` is
the installation directory specified to the installer.
To include the headers, place both directories (if different) on your compiler's
search path for includes. Do *not* place the parent directories on the search
path and then use ``#include <pythonX.Y/Python.h>``; this will break on
multi-platform builds since the platform independent headers under
:envvar:`prefix` include the platform specific headers from
:envvar:`exec_prefix`.
C++ users should note that though the API is defined entirely using C, the
header files do properly declare the entry points to be ``extern "C"``, so there
is no need to do anything special to use the API from C++.
.. _api-objects:
Objects, Types and Reference Counts
===================================
.. index:: object: type
Most Python/C API functions have one or more arguments as well as a return value
of type :c:type:`PyObject\*`. This type is a pointer to an opaque data type
representing an arbitrary Python object. Since all Python object types are
treated the same way by the Python language in most situations (e.g.,
assignments, scope rules, and argument passing), it is only fitting that they
should be represented by a single C type. Almost all Python objects live on the
heap: you never declare an automatic or static variable of type
:c:type:`PyObject`, only pointer variables of type :c:type:`PyObject\*` can be
declared. The sole exception are the type objects; since these must never be
deallocated, they are typically static :c:type:`PyTypeObject` objects.
All Python objects (even Python integers) have a :dfn:`type` and a
:dfn:`reference count`. An object's type determines what kind of object it is
(e.g., an integer, a list, or a user-defined function; there are many more as
explained in :ref:`types`). For each of the well-known types there is a macro
to check whether an object is of that type; for instance, ``PyList_Check(a)`` is
true if (and only if) the object pointed to by *a* is a Python list.
.. _api-refcounts:
Reference Counts
----------------
The reference count is important because today's computers have a finite (and
often severely limited) memory size; it counts how many different places there
are that have a reference to an object. Such a place could be another object,
or a global (or static) C variable, or a local variable in some C function.
When an object's reference count becomes zero, the object is deallocated. If
it contains references to other objects, their reference count is decremented.
Those other objects may be deallocated in turn, if this decrement makes their
reference count become zero, and so on. (There's an obvious problem with
objects that reference each other here; for now, the solution is "don't do
that.")
.. index::
single: Py_INCREF()
single: Py_DECREF()
Reference counts are always manipulated explicitly. The normal way is to use
the macro :c:func:`Py_INCREF` to increment an object's reference count by one,
and :c:func:`Py_DECREF` to decrement it by one. The :c:func:`Py_DECREF` macro
is considerably more complex than the incref one, since it must check whether
the reference count becomes zero and then cause the object's deallocator to be
called. The deallocator is a function pointer contained in the object's type
structure. The type-specific deallocator takes care of decrementing the
reference counts for other objects contained in the object if this is a compound
object type, such as a list, as well as performing any additional finalization
that's needed. There's no chance that the reference count can overflow; at
least as many bits are used to hold the reference count as there are distinct
memory locations in virtual memory (assuming ``sizeof(Py_ssize_t) >= sizeof(void*)``).
Thus, the reference count increment is a simple operation.
It is not necessary to increment an object's reference count for every local
variable that contains a pointer to an object. In theory, the object's
reference count goes up by one when the variable is made to point to it and it
goes down by one when the variable goes out of scope. However, these two
cancel each other out, so at the end the reference count hasn't changed. The
only real reason to use the reference count is to prevent the object from being
deallocated as long as our variable is pointing to it. If we know that there
is at least one other reference to the object that lives at least as long as
our variable, there is no need to increment the reference count temporarily.
An important situation where this arises is in objects that are passed as
arguments to C functions in an extension module that are called from Python;
the call mechanism guarantees to hold a reference to every argument for the
duration of the call.
However, a common pitfall is to extract an object from a list and hold on to it
for a while without incrementing its reference count. Some other operation might
conceivably remove the object from the list, decrementing its reference count
and possible deallocating it. The real danger is that innocent-looking
operations may invoke arbitrary Python code which could do this; there is a code
path which allows control to flow back to the user from a :c:func:`Py_DECREF`, so
almost any operation is potentially dangerous.
A safe approach is to always use the generic operations (functions whose name
begins with ``PyObject_``, ``PyNumber_``, ``PySequence_`` or ``PyMapping_``).
These operations always increment the reference count of the object they return.
This leaves the caller with the responsibility to call :c:func:`Py_DECREF` when
they are done with the result; this soon becomes second nature.
.. _api-refcountdetails:
Reference Count Details
^^^^^^^^^^^^^^^^^^^^^^^
The reference count behavior of functions in the Python/C API is best explained
in terms of *ownership of references*. Ownership pertains to references, never
to objects (objects are not owned: they are always shared). "Owning a
reference" means being responsible for calling Py_DECREF on it when the
reference is no longer needed. Ownership can also be transferred, meaning that
the code that receives ownership of the reference then becomes responsible for
eventually decref'ing it by calling :c:func:`Py_DECREF` or :c:func:`Py_XDECREF`
when it's no longer needed---or passing on this responsibility (usually to its
caller). When a function passes ownership of a reference on to its caller, the
caller is said to receive a *new* reference. When no ownership is transferred,
the caller is said to *borrow* the reference. Nothing needs to be done for a
borrowed reference.
Conversely, when a calling function passes in a reference to an object, there
are two possibilities: the function *steals* a reference to the object, or it
does not. *Stealing a reference* means that when you pass a reference to a
function, that function assumes that it now owns that reference, and you are not
responsible for it any longer.
.. index::
single: PyList_SetItem()
single: PyTuple_SetItem()
Few functions steal references; the two notable exceptions are
:c:func:`PyList_SetItem` and :c:func:`PyTuple_SetItem`, which steal a reference
to the item (but not to the tuple or list into which the item is put!). These
functions were designed to steal a reference because of a common idiom for
populating a tuple or list with newly created objects; for example, the code to
create the tuple ``(1, 2, "three")`` could look like this (forgetting about
error handling for the moment; a better way to code this is shown below)::
PyObject *t;
t = PyTuple_New(3);
PyTuple_SetItem(t, 0, PyInt_FromLong(1L));
PyTuple_SetItem(t, 1, PyInt_FromLong(2L));
PyTuple_SetItem(t, 2, PyString_FromString("three"));
Here, :c:func:`PyInt_FromLong` returns a new reference which is immediately
stolen by :c:func:`PyTuple_SetItem`. When you want to keep using an object
although the reference to it will be stolen, use :c:func:`Py_INCREF` to grab
another reference before calling the reference-stealing function.
Incidentally, :c:func:`PyTuple_SetItem` is the *only* way to set tuple items;
:c:func:`PySequence_SetItem` and :c:func:`PyObject_SetItem` refuse to do this
since tuples are an immutable data type. You should only use
:c:func:`PyTuple_SetItem` for tuples that you are creating yourself.
Equivalent code for populating a list can be written using :c:func:`PyList_New`
and :c:func:`PyList_SetItem`.
However, in practice, you will rarely use these ways of creating and populating
a tuple or list. There's a generic function, :c:func:`Py_BuildValue`, that can
create most common objects from C values, directed by a :dfn:`format string`.
For example, the above two blocks of code could be replaced by the following
(which also takes care of the error checking)::
PyObject *tuple, *list;
tuple = Py_BuildValue("(iis)", 1, 2, "three");
list = Py_BuildValue("[iis]", 1, 2, "three");
It is much more common to use :c:func:`PyObject_SetItem` and friends with items
whose references you are only borrowing, like arguments that were passed in to
the function you are writing. In that case, their behaviour regarding reference
counts is much saner, since you don't have to increment a reference count so you
can give a reference away ("have it be stolen"). For example, this function
sets all items of a list (actually, any mutable sequence) to a given item::
int
set_all(PyObject *target, PyObject *item)
{
int i, n;
n = PyObject_Length(target);
if (n < 0)
return -1;
for (i = 0; i < n; i++) {
PyObject *index = PyInt_FromLong(i);
if (!index)
return -1;
if (PyObject_SetItem(target, index, item) < 0) {
Py_DECREF(index);
return -1;
}
Py_DECREF(index);
}
return 0;
}
.. index:: single: set_all()
The situation is slightly different for function return values. While passing
a reference to most functions does not change your ownership responsibilities
for that reference, many functions that return a reference to an object give
you ownership of the reference. The reason is simple: in many cases, the
returned object is created on the fly, and the reference you get is the only
reference to the object. Therefore, the generic functions that return object
references, like :c:func:`PyObject_GetItem` and :c:func:`PySequence_GetItem`,
always return a new reference (the caller becomes the owner of the reference).
It is important to realize that whether you own a reference returned by a
function depends on which function you call only --- *the plumage* (the type of
the object passed as an argument to the function) *doesn't enter into it!*
Thus, if you extract an item from a list using :c:func:`PyList_GetItem`, you
don't own the reference --- but if you obtain the same item from the same list
using :c:func:`PySequence_GetItem` (which happens to take exactly the same
arguments), you do own a reference to the returned object.
.. index::
single: PyList_GetItem()
single: PySequence_GetItem()
Here is an example of how you could write a function that computes the sum of
the items in a list of integers; once using :c:func:`PyList_GetItem`, and once
using :c:func:`PySequence_GetItem`. ::
long
sum_list(PyObject *list)
{
int i, n;
long total = 0;
PyObject *item;
n = PyList_Size(list);
if (n < 0)
return -1; /* Not a list */
for (i = 0; i < n; i++) {
item = PyList_GetItem(list, i); /* Can't fail */
if (!PyInt_Check(item)) continue; /* Skip non-integers */
total += PyInt_AsLong(item);
}
return total;
}
.. index:: single: sum_list()
::
long
sum_sequence(PyObject *sequence)
{
int i, n;
long total = 0;
PyObject *item;
n = PySequence_Length(sequence);
if (n < 0)
return -1; /* Has no length */
for (i = 0; i < n; i++) {
item = PySequence_GetItem(sequence, i);
if (item == NULL)
return -1; /* Not a sequence, or other failure */
if (PyInt_Check(item))
total += PyInt_AsLong(item);
Py_DECREF(item); /* Discard reference ownership */
}
return total;
}
.. index:: single: sum_sequence()
.. _api-types:
Types
-----
There are few other data types that play a significant role in the Python/C
API; most are simple C types such as :c:type:`int`, :c:type:`long`,
:c:type:`double` and :c:type:`char\*`. A few structure types are used to
describe static tables used to list the functions exported by a module or the
data attributes of a new object type, and another is used to describe the value
of a complex number. These will be discussed together with the functions that
use them.
.. _api-exceptions:
Exceptions
==========
The Python programmer only needs to deal with exceptions if specific error
handling is required; unhandled exceptions are automatically propagated to the
caller, then to the caller's caller, and so on, until they reach the top-level
interpreter, where they are reported to the user accompanied by a stack
traceback.
.. index:: single: PyErr_Occurred()
For C programmers, however, error checking always has to be explicit. All
functions in the Python/C API can raise exceptions, unless an explicit claim is
made otherwise in a function's documentation. In general, when a function
encounters an error, it sets an exception, discards any object references that
it owns, and returns an error indicator. If not documented otherwise, this
indicator is either *NULL* or ``-1``, depending on the function's return type.
A few functions return a Boolean true/false result, with false indicating an
error. Very few functions return no explicit error indicator or have an
ambiguous return value, and require explicit testing for errors with
:c:func:`PyErr_Occurred`. These exceptions are always explicitly documented.
.. index::
single: PyErr_SetString()
single: PyErr_Clear()
Exception state is maintained in per-thread storage (this is equivalent to
using global storage in an unthreaded application). A thread can be in one of
two states: an exception has occurred, or not. The function
:c:func:`PyErr_Occurred` can be used to check for this: it returns a borrowed
reference to the exception type object when an exception has occurred, and
*NULL* otherwise. There are a number of functions to set the exception state:
:c:func:`PyErr_SetString` is the most common (though not the most general)
function to set the exception state, and :c:func:`PyErr_Clear` clears the
exception state.
.. index::
single: exc_type (in module sys)
single: exc_value (in module sys)
single: exc_traceback (in module sys)
The full exception state consists of three objects (all of which can be
*NULL*): the exception type, the corresponding exception value, and the
traceback. These have the same meanings as the Python objects
``sys.exc_type``, ``sys.exc_value``, and ``sys.exc_traceback``; however, they
are not the same: the Python objects represent the last exception being handled
by a Python :keyword:`try` ... :keyword:`except` statement, while the C level
exception state only exists while an exception is being passed on between C
functions until it reaches the Python bytecode interpreter's main loop, which
takes care of transferring it to ``sys.exc_type`` and friends.
.. index:: single: exc_info() (in module sys)
Note that starting with Python 1.5, the preferred, thread-safe way to access the
exception state from Python code is to call the function :func:`sys.exc_info`,
which returns the per-thread exception state for Python code. Also, the
semantics of both ways to access the exception state have changed so that a
function which catches an exception will save and restore its thread's exception
state so as to preserve the exception state of its caller. This prevents common
bugs in exception handling code caused by an innocent-looking function
overwriting the exception being handled; it also reduces the often unwanted
lifetime extension for objects that are referenced by the stack frames in the
traceback.
As a general principle, a function that calls another function to perform some
task should check whether the called function raised an exception, and if so,
pass the exception state on to its caller. It should discard any object
references that it owns, and return an error indicator, but it should *not* set
another exception --- that would overwrite the exception that was just raised,
and lose important information about the exact cause of the error.
.. index:: single: sum_sequence()
A simple example of detecting exceptions and passing them on is shown in the
:c:func:`sum_sequence` example above. It so happens that this example doesn't
need to clean up any owned references when it detects an error. The following
example function shows some error cleanup. First, to remind you why you like
Python, we show the equivalent Python code::
def incr_item(dict, key):
try:
item = dict[key]
except KeyError:
item = 0
dict[key] = item + 1
.. index:: single: incr_item()
Here is the corresponding C code, in all its glory::
int
incr_item(PyObject *dict, PyObject *key)
{
/* Objects all initialized to NULL for Py_XDECREF */
PyObject *item = NULL, *const_one = NULL, *incremented_item = NULL;
int rv = -1; /* Return value initialized to -1 (failure) */
item = PyObject_GetItem(dict, key);
if (item == NULL) {
/* Handle KeyError only: */
if (!PyErr_ExceptionMatches(PyExc_KeyError))
goto error;
/* Clear the error and use zero: */
PyErr_Clear();
item = PyInt_FromLong(0L);
if (item == NULL)
goto error;
}
const_one = PyInt_FromLong(1L);
if (const_one == NULL)
goto error;
incremented_item = PyNumber_Add(item, const_one);
if (incremented_item == NULL)
goto error;
if (PyObject_SetItem(dict, key, incremented_item) < 0)
goto error;
rv = 0; /* Success */
/* Continue with cleanup code */
error:
/* Cleanup code, shared by success and failure path */
/* Use Py_XDECREF() to ignore NULL references */
Py_XDECREF(item);
Py_XDECREF(const_one);
Py_XDECREF(incremented_item);
return rv; /* -1 for error, 0 for success */
}
.. index:: single: incr_item()
.. index::
single: PyErr_ExceptionMatches()
single: PyErr_Clear()
single: Py_XDECREF()
This example represents an endorsed use of the ``goto`` statement in C!
It illustrates the use of :c:func:`PyErr_ExceptionMatches` and
:c:func:`PyErr_Clear` to handle specific exceptions, and the use of
:c:func:`Py_XDECREF` to dispose of owned references that may be *NULL* (note the
``'X'`` in the name; :c:func:`Py_DECREF` would crash when confronted with a
*NULL* reference). It is important that the variables used to hold owned
references are initialized to *NULL* for this to work; likewise, the proposed
return value is initialized to ``-1`` (failure) and only set to success after
the final call made is successful.
.. _api-embedding:
Embedding Python
================
The one important task that only embedders (as opposed to extension writers) of
the Python interpreter have to worry about is the initialization, and possibly
the finalization, of the Python interpreter. Most functionality of the
interpreter can only be used after the interpreter has been initialized.
.. index::
single: Py_Initialize()
module: __builtin__
module: __main__
module: sys
module: exceptions
triple: module; search; path
single: path (in module sys)
The basic initialization function is :c:func:`Py_Initialize`. This initializes
the table of loaded modules, and creates the fundamental modules
:mod:`__builtin__`, :mod:`__main__`, :mod:`sys`, and :mod:`exceptions`. It also
initializes the module search path (``sys.path``).
.. index:: single: PySys_SetArgvEx()
:c:func:`Py_Initialize` does not set the "script argument list" (``sys.argv``).
If this variable is needed by Python code that will be executed later, it must
be set explicitly with a call to ``PySys_SetArgvEx(argc, argv, updatepath)``
after the call to :c:func:`Py_Initialize`.
On most systems (in particular, on Unix and Windows, although the details are
slightly different), :c:func:`Py_Initialize` calculates the module search path
based upon its best guess for the location of the standard Python interpreter
executable, assuming that the Python library is found in a fixed location
relative to the Python interpreter executable. In particular, it looks for a
directory named :file:`lib/python{X.Y}` relative to the parent directory
where the executable named :file:`python` is found on the shell command search
path (the environment variable :envvar:`PATH`).
For instance, if the Python executable is found in
:file:`/usr/local/bin/python`, it will assume that the libraries are in
:file:`/usr/local/lib/python{X.Y}`. (In fact, this particular path is also
the "fallback" location, used when no executable file named :file:`python` is
found along :envvar:`PATH`.) The user can override this behavior by setting the
environment variable :envvar:`PYTHONHOME`, or insert additional directories in
front of the standard path by setting :envvar:`PYTHONPATH`.
.. index::
single: Py_SetProgramName()
single: Py_GetPath()
single: Py_GetPrefix()
single: Py_GetExecPrefix()
single: Py_GetProgramFullPath()
The embedding application can steer the search by calling
``Py_SetProgramName(file)`` *before* calling :c:func:`Py_Initialize`. Note that
:envvar:`PYTHONHOME` still overrides this and :envvar:`PYTHONPATH` is still
inserted in front of the standard path. An application that requires total
control has to provide its own implementation of :c:func:`Py_GetPath`,
:c:func:`Py_GetPrefix`, :c:func:`Py_GetExecPrefix`, and
:c:func:`Py_GetProgramFullPath` (all defined in :file:`Modules/getpath.c`).
.. index:: single: Py_IsInitialized()
Sometimes, it is desirable to "uninitialize" Python. For instance, the
application may want to start over (make another call to
:c:func:`Py_Initialize`) or the application is simply done with its use of
Python and wants to free memory allocated by Python. This can be accomplished
by calling :c:func:`Py_Finalize`. The function :c:func:`Py_IsInitialized` returns
true if Python is currently in the initialized state. More information about
these functions is given in a later chapter. Notice that :c:func:`Py_Finalize`
does *not* free all memory allocated by the Python interpreter, e.g. memory
allocated by extension modules currently cannot be released.
.. _api-debugging:
Debugging Builds
================
Python can be built with several macros to enable extra checks of the
interpreter and extension modules. These checks tend to add a large amount of
overhead to the runtime so they are not enabled by default.
A full list of the various types of debugging builds is in the file
:file:`Misc/SpecialBuilds.txt` in the Python source distribution. Builds are
available that support tracing of reference counts, debugging the memory
allocator, or low-level profiling of the main interpreter loop. Only the most
frequently-used builds will be described in the remainder of this section.
Compiling the interpreter with the :c:macro:`Py_DEBUG` macro defined produces
what is generally meant by "a debug build" of Python. :c:macro:`Py_DEBUG` is
enabled in the Unix build by adding ``--with-pydebug`` to the
:file:`./configure` command. It is also implied by the presence of the
not-Python-specific :c:macro:`_DEBUG` macro. When :c:macro:`Py_DEBUG` is enabled
in the Unix build, compiler optimization is disabled.
In addition to the reference count debugging described below, the following
extra checks are performed:
* Extra checks are added to the object allocator.
* Extra checks are added to the parser and compiler.
* Downcasts from wide types to narrow types are checked for loss of information.
* A number of assertions are added to the dictionary and set implementations.
In addition, the set object acquires a :meth:`test_c_api` method.
* Sanity checks of the input arguments are added to frame creation.
* The storage for long ints is initialized with a known invalid pattern to catch
reference to uninitialized digits.
* Low-level tracing and extra exception checking are added to the runtime
virtual machine.
* Extra checks are added to the memory arena implementation.
* Extra debugging is added to the thread module.
There may be additional checks not mentioned here.
Defining :c:macro:`Py_TRACE_REFS` enables reference tracing. When defined, a
circular doubly linked list of active objects is maintained by adding two extra
fields to every :c:type:`PyObject`. Total allocations are tracked as well. Upon
exit, all existing references are printed. (In interactive mode this happens
after every statement run by the interpreter.) Implied by :c:macro:`Py_DEBUG`.
Please refer to :file:`Misc/SpecialBuilds.txt` in the Python source distribution
for more detailed information.
PK %�\���n n html/_sources/c-api/iter.rst.txtnu �[��� .. highlightlang:: c
.. _iterator:
Iterator Protocol
=================
.. versionadded:: 2.2
There are two functions specifically for working with iterators.
.. c:function:: int PyIter_Check(PyObject *o)
Return true if the object *o* supports the iterator protocol.
This function can return a false positive in the case of old-style
classes because those classes always define a :c:member:`tp_iternext`
slot with logic that either invokes a :meth:`next` method or raises
a :exc:`TypeError`.
.. c:function:: PyObject* PyIter_Next(PyObject *o)
Return the next value from the iteration *o*. The object must be an iterator
(it is up to the caller to check this). If there are no remaining values,
returns *NULL* with no exception set. If an error occurs while retrieving
the item, returns *NULL* and passes along the exception.
To write a loop which iterates over an iterator, the C code should look
something like this::
PyObject *iterator = PyObject_GetIter(obj);
PyObject *item;
if (iterator == NULL) {
/* propagate error */
}
while (item = PyIter_Next(iterator)) {
/* do something with item */
...
/* release reference when done */
Py_DECREF(item);
}
Py_DECREF(iterator);
if (PyErr_Occurred()) {
/* propagate error */
}
else {
/* continue doing useful work */
}
PK %�\�ѥ $ html/_sources/c-api/iterator.rst.txtnu �[��� .. highlightlang:: c
.. _iterator-objects:
Iterator Objects
----------------
Python provides two general-purpose iterator objects. The first, a sequence
iterator, works with an arbitrary sequence supporting the :meth:`__getitem__`
method. The second works with a callable object and a sentinel value, calling
the callable for each item in the sequence, and ending the iteration when the
sentinel value is returned.
.. c:var:: PyTypeObject PySeqIter_Type
Type object for iterator objects returned by :c:func:`PySeqIter_New` and the
one-argument form of the :func:`iter` built-in function for built-in sequence
types.
.. versionadded:: 2.2
.. c:function:: int PySeqIter_Check(op)
Return true if the type of *op* is :c:data:`PySeqIter_Type`.
.. versionadded:: 2.2
.. c:function:: PyObject* PySeqIter_New(PyObject *seq)
Return an iterator that works with a general sequence object, *seq*. The
iteration ends when the sequence raises :exc:`IndexError` for the subscripting
operation.
.. versionadded:: 2.2
.. c:var:: PyTypeObject PyCallIter_Type
Type object for iterator objects returned by :c:func:`PyCallIter_New` and the
two-argument form of the :func:`iter` built-in function.
.. versionadded:: 2.2
.. c:function:: int PyCallIter_Check(op)
Return true if the type of *op* is :c:data:`PyCallIter_Type`.
.. versionadded:: 2.2
.. c:function:: PyObject* PyCallIter_New(PyObject *callable, PyObject *sentinel)
Return a new iterator. The first parameter, *callable*, can be any Python
callable object that can be called with no parameters; each call to it should
return the next item in the iteration. When *callable* returns a value equal to
*sentinel*, the iteration will be terminated.
.. versionadded:: 2.2
PK %�\��`F� � html/_sources/c-api/list.rst.txtnu �[��� .. highlightlang:: c
.. _listobjects:
List Objects
------------
.. index:: object: list
.. c:type:: PyListObject
This subtype of :c:type:`PyObject` represents a Python list object.
.. c:var:: PyTypeObject PyList_Type
This instance of :c:type:`PyTypeObject` represents the Python list type. This
is the same object as ``list`` in the Python layer.
.. c:function:: int PyList_Check(PyObject *p)
Return true if *p* is a list object or an instance of a subtype of the list
type.
.. versionchanged:: 2.2
Allowed subtypes to be accepted.
.. c:function:: int PyList_CheckExact(PyObject *p)
Return true if *p* is a list object, but not an instance of a subtype of
the list type.
.. versionadded:: 2.2
.. c:function:: PyObject* PyList_New(Py_ssize_t len)
Return a new list of length *len* on success, or *NULL* on failure.
.. note::
If *len* is greater than zero, the returned list object's items are
set to ``NULL``. Thus you cannot use abstract API functions such as
:c:func:`PySequence_SetItem` or expose the object to Python code before
setting all items to a real object with :c:func:`PyList_SetItem`.
.. versionchanged:: 2.5
This function used an :c:type:`int` for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: Py_ssize_t PyList_Size(PyObject *list)
.. index:: builtin: len
Return the length of the list object in *list*; this is equivalent to
``len(list)`` on a list object.
.. versionchanged:: 2.5
This function returned an :c:type:`int`. This might require changes in
your code for properly supporting 64-bit systems.
.. c:function:: Py_ssize_t PyList_GET_SIZE(PyObject *list)
Macro form of :c:func:`PyList_Size` without error checking.
.. versionchanged:: 2.5
This macro returned an :c:type:`int`. This might require changes in your
code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyList_GetItem(PyObject *list, Py_ssize_t index)
Return the object at position *index* in the list pointed to by *list*. The
position must be positive, indexing from the end of the list is not
supported. If *index* is out of bounds, return *NULL* and set an
:exc:`IndexError` exception.
.. versionchanged:: 2.5
This function used an :c:type:`int` for *index*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyList_GET_ITEM(PyObject *list, Py_ssize_t i)
Macro form of :c:func:`PyList_GetItem` without error checking.
.. versionchanged:: 2.5
This macro used an :c:type:`int` for *i*. This might require changes in
your code for properly supporting 64-bit systems.
.. c:function:: int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item)
Set the item at index *index* in list to *item*. Return ``0`` on success
or ``-1`` on failure.
.. note::
This function "steals" a reference to *item* and discards a reference to
an item already in the list at the affected position.
.. versionchanged:: 2.5
This function used an :c:type:`int` for *index*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o)
Macro form of :c:func:`PyList_SetItem` without error checking. This is
normally only used to fill in new lists where there is no previous content.
.. note::
This macro "steals" a reference to *item*, and, unlike
:c:func:`PyList_SetItem`, does *not* discard a reference to any item that
it being replaced; any reference in *list* at position *i* will be
leaked.
.. versionchanged:: 2.5
This macro used an :c:type:`int` for *i*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: int PyList_Insert(PyObject *list, Py_ssize_t index, PyObject *item)
Insert the item *item* into list *list* in front of index *index*. Return
``0`` if successful; return ``-1`` and set an exception if unsuccessful.
Analogous to ``list.insert(index, item)``.
.. versionchanged:: 2.5
This function used an :c:type:`int` for *index*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: int PyList_Append(PyObject *list, PyObject *item)
Append the object *item* at the end of list *list*. Return ``0`` if
successful; return ``-1`` and set an exception if unsuccessful. Analogous
to ``list.append(item)``.
.. c:function:: PyObject* PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high)
Return a list of the objects in *list* containing the objects *between* *low*
and *high*. Return *NULL* and set an exception if unsuccessful. Analogous
to ``list[low:high]``. Negative indices, as when slicing from Python, are not
supported.
.. versionchanged:: 2.5
This function used an :c:type:`int` for *low* and *high*. This might
require changes in your code for properly supporting 64-bit systems.
.. c:function:: int PyList_SetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist)
Set the slice of *list* between *low* and *high* to the contents of
*itemlist*. Analogous to ``list[low:high] = itemlist``. The *itemlist* may
be *NULL*, indicating the assignment of an empty list (slice deletion).
Return ``0`` on success, ``-1`` on failure. Negative indices, as when
slicing from Python, are not supported.
.. versionchanged:: 2.5
This function used an :c:type:`int` for *low* and *high*. This might
require changes in your code for properly supporting 64-bit systems.
.. c:function:: int PyList_Sort(PyObject *list)
Sort the items of *list* in place. Return ``0`` on success, ``-1`` on
failure. This is equivalent to ``list.sort()``.
.. c:function:: int PyList_Reverse(PyObject *list)
Reverse the items of *list* in place. Return ``0`` on success, ``-1`` on
failure. This is the equivalent of ``list.reverse()``.
.. c:function:: PyObject* PyList_AsTuple(PyObject *list)
.. index:: builtin: tuple
Return a new tuple object containing the contents of *list*; equivalent to
``tuple(list)``.
PK %�\�=9�3 3 html/_sources/c-api/long.rst.txtnu �[��� .. highlightlang:: c
.. _longobjects:
Long Integer Objects
--------------------
.. index:: object: long integer
.. c:type:: PyLongObject
This subtype of :c:type:`PyObject` represents a Python long integer object.
.. c:var:: PyTypeObject PyLong_Type
.. index:: single: LongType (in modules types)
This instance of :c:type:`PyTypeObject` represents the Python long integer type.
This is the same object as ``long`` and ``types.LongType``.
.. c:function:: int PyLong_Check(PyObject *p)
Return true if its argument is a :c:type:`PyLongObject` or a subtype of
:c:type:`PyLongObject`.
.. versionchanged:: 2.2
Allowed subtypes to be accepted.
.. c:function:: int PyLong_CheckExact(PyObject *p)
Return true if its argument is a :c:type:`PyLongObject`, but not a subtype of
:c:type:`PyLongObject`.
.. versionadded:: 2.2
.. c:function:: PyObject* PyLong_FromLong(long v)
Return a new :c:type:`PyLongObject` object from *v*, or *NULL* on failure.
.. c:function:: PyObject* PyLong_FromUnsignedLong(unsigned long v)
Return a new :c:type:`PyLongObject` object from a C :c:type:`unsigned long`, or
*NULL* on failure.
.. c:function:: PyObject* PyLong_FromSsize_t(Py_ssize_t v)
Return a new :c:type:`PyLongObject` object from a C :c:type:`Py_ssize_t`, or
*NULL* on failure.
.. versionadded:: 2.6
.. c:function:: PyObject* PyLong_FromSize_t(size_t v)
Return a new :c:type:`PyLongObject` object from a C :c:type:`size_t`, or
*NULL* on failure.
.. versionadded:: 2.6
.. c:function:: PyObject* PyLong_FromLongLong(PY_LONG_LONG v)
Return a new :c:type:`PyLongObject` object from a C :c:type:`long long`, or *NULL*
on failure.
.. c:function:: PyObject* PyLong_FromUnsignedLongLong(unsigned PY_LONG_LONG v)
Return a new :c:type:`PyLongObject` object from a C :c:type:`unsigned long long`,
or *NULL* on failure.
.. c:function:: PyObject* PyLong_FromDouble(double v)
Return a new :c:type:`PyLongObject` object from the integer part of *v*, or
*NULL* on failure.
.. c:function:: PyObject* PyLong_FromString(char *str, char **pend, int base)
Return a new :c:type:`PyLongObject` based on the string value in *str*, which is
interpreted according to the radix in *base*. If *pend* is non-*NULL*,
*\*pend* will point to the first character in *str* which follows the
representation of the number. If *base* is ``0``, the radix will be determined
based on the leading characters of *str*: if *str* starts with ``'0x'`` or
``'0X'``, radix 16 will be used; if *str* starts with ``'0'``, radix 8 will be
used; otherwise radix 10 will be used. If *base* is not ``0``, it must be
between ``2`` and ``36``, inclusive. Leading spaces are ignored. If there are
no digits, :exc:`ValueError` will be raised.
.. c:function:: PyObject* PyLong_FromUnicode(Py_UNICODE *u, Py_ssize_t length, int base)
Convert a sequence of Unicode digits to a Python long integer value. The first
parameter, *u*, points to the first character of the Unicode string, *length*
gives the number of characters, and *base* is the radix for the conversion. The
radix must be in the range [2, 36]; if it is out of range, :exc:`ValueError`
will be raised.
.. versionadded:: 1.6
.. versionchanged:: 2.5
This function used an :c:type:`int` for *length*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyLong_FromVoidPtr(void *p)
Create a Python integer or long integer from the pointer *p*. The pointer value
can be retrieved from the resulting value using :c:func:`PyLong_AsVoidPtr`.
.. versionadded:: 1.5.2
.. versionchanged:: 2.5
If the integer is larger than LONG_MAX, a positive long integer is returned.
.. c:function:: long PyLong_AsLong(PyObject *pylong)
.. index::
single: LONG_MAX
single: OverflowError (built-in exception)
Return a C :c:type:`long` representation of the contents of *pylong*. If
*pylong* is greater than :const:`LONG_MAX`, an :exc:`OverflowError` is raised
and ``-1`` will be returned.
.. c:function:: long PyLong_AsLongAndOverflow(PyObject *pylong, int *overflow)
Return a C :c:type:`long` representation of the contents of
*pylong*. If *pylong* is greater than :const:`LONG_MAX` or less
than :const:`LONG_MIN`, set *\*overflow* to ``1`` or ``-1``,
respectively, and return ``-1``; otherwise, set *\*overflow* to
``0``. If any other exception occurs (for example a TypeError or
MemoryError), then ``-1`` will be returned and *\*overflow* will
be ``0``.
.. versionadded:: 2.7
.. c:function:: PY_LONG_LONG PyLong_AsLongLongAndOverflow(PyObject *pylong, int *overflow)
Return a C :c:type:`long long` representation of the contents of
*pylong*. If *pylong* is greater than :const:`PY_LLONG_MAX` or less
than :const:`PY_LLONG_MIN`, set *\*overflow* to ``1`` or ``-1``,
respectively, and return ``-1``; otherwise, set *\*overflow* to
``0``. If any other exception occurs (for example a TypeError or
MemoryError), then ``-1`` will be returned and *\*overflow* will
be ``0``.
.. versionadded:: 2.7
.. c:function:: Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)
.. index::
single: PY_SSIZE_T_MAX
single: OverflowError (built-in exception)
Return a C :c:type:`Py_ssize_t` representation of the contents of *pylong*. If
*pylong* is greater than :const:`PY_SSIZE_T_MAX`, an :exc:`OverflowError` is raised
and ``-1`` will be returned.
.. versionadded:: 2.6
.. c:function:: unsigned long PyLong_AsUnsignedLong(PyObject *pylong)
.. index::
single: ULONG_MAX
single: OverflowError (built-in exception)
Return a C :c:type:`unsigned long` representation of the contents of *pylong*.
If *pylong* is greater than :const:`ULONG_MAX`, an :exc:`OverflowError` is
raised.
.. c:function:: PY_LONG_LONG PyLong_AsLongLong(PyObject *pylong)
.. index::
single: OverflowError (built-in exception)
Return a C :c:type:`long long` from a Python long integer. If
*pylong* cannot be represented as a :c:type:`long long`, an
:exc:`OverflowError` is raised and ``-1`` is returned.
.. versionadded:: 2.2
.. c:function:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLong(PyObject *pylong)
.. index::
single: OverflowError (built-in exception)
Return a C :c:type:`unsigned long long` from a Python long integer. If
*pylong* cannot be represented as an :c:type:`unsigned long long`, an
:exc:`OverflowError` is raised and ``(unsigned long long)-1`` is
returned.
.. versionadded:: 2.2
.. versionchanged:: 2.7
A negative *pylong* now raises :exc:`OverflowError`, not
:exc:`TypeError`.
.. c:function:: unsigned long PyLong_AsUnsignedLongMask(PyObject *io)
Return a C :c:type:`unsigned long` from a Python long integer, without checking
for overflow.
.. versionadded:: 2.3
.. c:function:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLongMask(PyObject *io)
Return a C :c:type:`unsigned long long` from a Python long integer, without
checking for overflow.
.. versionadded:: 2.3
.. c:function:: double PyLong_AsDouble(PyObject *pylong)
Return a C :c:type:`double` representation of the contents of *pylong*. If
*pylong* cannot be approximately represented as a :c:type:`double`, an
:exc:`OverflowError` exception is raised and ``-1.0`` will be returned.
.. c:function:: void* PyLong_AsVoidPtr(PyObject *pylong)
Convert a Python integer or long integer *pylong* to a C :c:type:`void` pointer.
If *pylong* cannot be converted, an :exc:`OverflowError` will be raised. This
is only assured to produce a usable :c:type:`void` pointer for values created
with :c:func:`PyLong_FromVoidPtr`.
.. versionadded:: 1.5.2
.. versionchanged:: 2.5
For values outside 0..LONG_MAX, both signed and unsigned integers are accepted.
PK %�\$;��: : # html/_sources/c-api/mapping.rst.txtnu �[��� .. highlightlang:: c
.. _mapping:
Mapping Protocol
================
.. c:function:: int PyMapping_Check(PyObject *o)
Return ``1`` if the object provides mapping protocol, and ``0`` otherwise. This
function always succeeds.
.. c:function:: Py_ssize_t PyMapping_Size(PyObject *o)
Py_ssize_t PyMapping_Length(PyObject *o)
.. index:: builtin: len
Returns the number of keys in object *o* on success, and ``-1`` on failure. For
objects that do not provide mapping protocol, this is equivalent to the Python
expression ``len(o)``.
.. versionchanged:: 2.5
These functions returned an :c:type:`int` type. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: int PyMapping_DelItemString(PyObject *o, char *key)
Remove the mapping for object *key* from the object *o*. Return ``-1`` on
failure. This is equivalent to the Python statement ``del o[key]``.
.. c:function:: int PyMapping_DelItem(PyObject *o, PyObject *key)
Remove the mapping for object *key* from the object *o*. Return ``-1`` on
failure. This is equivalent to the Python statement ``del o[key]``.
.. c:function:: int PyMapping_HasKeyString(PyObject *o, char *key)
On success, return ``1`` if the mapping object has the key *key* and ``0``
otherwise. This is equivalent to ``o[key]``, returning ``True`` on success
and ``False`` on an exception. This function always succeeds.
.. c:function:: int PyMapping_HasKey(PyObject *o, PyObject *key)
Return ``1`` if the mapping object has the key *key* and ``0`` otherwise.
This is equivalent to ``o[key]``, returning ``True`` on success and ``False``
on an exception. This function always succeeds.
.. c:function:: PyObject* PyMapping_Keys(PyObject *o)
On success, return a list of the keys in object *o*. On failure, return *NULL*.
This is equivalent to the Python expression ``o.keys()``.
.. c:function:: PyObject* PyMapping_Values(PyObject *o)
On success, return a list of the values in object *o*. On failure, return
*NULL*. This is equivalent to the Python expression ``o.values()``.
.. c:function:: PyObject* PyMapping_Items(PyObject *o)
On success, return a list of the items in object *o*, where each item is a tuple
containing a key-value pair. On failure, return *NULL*. This is equivalent to
the Python expression ``o.items()``.
.. c:function:: PyObject* PyMapping_GetItemString(PyObject *o, char *key)
Return element of *o* corresponding to the object *key* or *NULL* on failure.
This is the equivalent of the Python expression ``o[key]``.
.. c:function:: int PyMapping_SetItemString(PyObject *o, char *key, PyObject *v)
Map the object *key* to the value *v* in object *o*. Returns ``-1`` on failure.
This is the equivalent of the Python statement ``o[key] = v``.
PK %�\���� � # html/_sources/c-api/marshal.rst.txtnu �[��� .. highlightlang:: c
.. _marshalling-utils:
Data marshalling support
========================
These routines allow C code to work with serialized objects using the same
data format as the :mod:`marshal` module. There are functions to write data
into the serialization format, and additional functions that can be used to
read the data back. Files used to store marshalled data must be opened in
binary mode.
Numeric values are stored with the least significant byte first.
The module supports two versions of the data format: version ``0`` is the
historical version, version ``1`` (new in Python 2.4) shares interned strings in
the file, and upon unmarshalling. Version 2 (new in Python 2.5) uses a binary
format for floating point numbers. *Py_MARSHAL_VERSION* indicates the current
file format (currently 2).
.. c:function:: void PyMarshal_WriteLongToFile(long value, FILE *file, int version)
Marshal a :c:type:`long` integer, *value*, to *file*. This will only write
the least-significant 32 bits of *value*; regardless of the size of the
native :c:type:`long` type.
.. versionchanged:: 2.4
*version* indicates the file format.
.. c:function:: void PyMarshal_WriteObjectToFile(PyObject *value, FILE *file, int version)
Marshal a Python object, *value*, to *file*.
.. versionchanged:: 2.4
*version* indicates the file format.
.. c:function:: PyObject* PyMarshal_WriteObjectToString(PyObject *value, int version)
Return a string object containing the marshalled representation of *value*.
.. versionchanged:: 2.4
*version* indicates the file format.
The following functions allow marshalled values to be read back in.
XXX What about error detection? It appears that reading past the end of the
file will always result in a negative numeric value (where that's relevant),
but it's not clear that negative values won't be handled properly when there's
no error. What's the right way to tell? Should only non-negative values be
written using these routines?
.. c:function:: long PyMarshal_ReadLongFromFile(FILE *file)
Return a C :c:type:`long` from the data stream in a :c:type:`FILE\*` opened
for reading. Only a 32-bit value can be read in using this function,
regardless of the native size of :c:type:`long`.
.. c:function:: int PyMarshal_ReadShortFromFile(FILE *file)
Return a C :c:type:`short` from the data stream in a :c:type:`FILE\*` opened
for reading. Only a 16-bit value can be read in using this function,
regardless of the native size of :c:type:`short`.
.. c:function:: PyObject* PyMarshal_ReadObjectFromFile(FILE *file)
Return a Python object from the data stream in a :c:type:`FILE\*` opened for
reading. On error, sets the appropriate exception (:exc:`EOFError` or
:exc:`TypeError`) and returns *NULL*.
.. c:function:: PyObject* PyMarshal_ReadLastObjectFromFile(FILE *file)
Return a Python object from the data stream in a :c:type:`FILE\*` opened for
reading. Unlike :c:func:`PyMarshal_ReadObjectFromFile`, this function
assumes that no further objects will be read from the file, allowing it to
aggressively load file data into memory so that the de-serialization can
operate from data in memory rather than reading a byte at a time from the
file. Only use these variant if you are certain that you won't be reading
anything else from the file. On error, sets the appropriate exception
(:exc:`EOFError` or :exc:`TypeError`) and returns *NULL*.
.. c:function:: PyObject* PyMarshal_ReadObjectFromString(char *string, Py_ssize_t len)
Return a Python object from the data stream in a character buffer
containing *len* bytes pointed to by *string*. On error, sets the
appropriate exception (:exc:`EOFError` or :exc:`TypeError`) and returns
*NULL*.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *len*. This might require
changes in your code for properly supporting 64-bit systems.
PK %�\& 6y$- $- " html/_sources/c-api/memory.rst.txtnu �[��� .. highlightlang:: c
.. _memory:
*****************
Memory Management
*****************
.. sectionauthor:: Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>
.. _memoryoverview:
Overview
========
Memory management in Python involves a private heap containing all Python
objects and data structures. The management of this private heap is ensured
internally by the *Python memory manager*. The Python memory manager has
different components which deal with various dynamic storage management aspects,
like sharing, segmentation, preallocation or caching.
At the lowest level, a raw memory allocator ensures that there is enough room in
the private heap for storing all Python-related data by interacting with the
memory manager of the operating system. On top of the raw memory allocator,
several object-specific allocators operate on the same heap and implement
distinct memory management policies adapted to the peculiarities of every object
type. For example, integer objects are managed differently within the heap than
strings, tuples or dictionaries because integers imply different storage
requirements and speed/space tradeoffs. The Python memory manager thus delegates
some of the work to the object-specific allocators, but ensures that the latter
operate within the bounds of the private heap.
It is important to understand that the management of the Python heap is
performed by the interpreter itself and that the user has no control over it,
even if they regularly manipulate object pointers to memory blocks inside that
heap. The allocation of heap space for Python objects and other internal
buffers is performed on demand by the Python memory manager through the Python/C
API functions listed in this document.
.. index::
single: malloc()
single: calloc()
single: realloc()
single: free()
To avoid memory corruption, extension writers should never try to operate on
Python objects with the functions exported by the C library: :c:func:`malloc`,
:c:func:`calloc`, :c:func:`realloc` and :c:func:`free`. This will result in mixed
calls between the C allocator and the Python memory manager with fatal
consequences, because they implement different algorithms and operate on
different heaps. However, one may safely allocate and release memory blocks
with the C library allocator for individual purposes, as shown in the following
example::
PyObject *res;
char *buf = (char *) malloc(BUFSIZ); /* for I/O */
if (buf == NULL)
return PyErr_NoMemory();
...Do some I/O operation involving buf...
res = PyString_FromString(buf);
free(buf); /* malloc'ed */
return res;
In this example, the memory request for the I/O buffer is handled by the C
library allocator. The Python memory manager is involved only in the allocation
of the string object returned as a result.
In most situations, however, it is recommended to allocate memory from the
Python heap specifically because the latter is under control of the Python
memory manager. For example, this is required when the interpreter is extended
with new object types written in C. Another reason for using the Python heap is
the desire to *inform* the Python memory manager about the memory needs of the
extension module. Even when the requested memory is used exclusively for
internal, highly-specific purposes, delegating all memory requests to the Python
memory manager causes the interpreter to have a more accurate image of its
memory footprint as a whole. Consequently, under certain circumstances, the
Python memory manager may or may not trigger appropriate actions, like garbage
collection, memory compaction or other preventive procedures. Note that by using
the C library allocator as shown in the previous example, the allocated memory
for the I/O buffer escapes completely the Python memory manager.
.. _memoryinterface:
Memory Interface
================
The following function sets, modeled after the ANSI C standard, but specifying
behavior when requesting zero bytes, are available for allocating and releasing
memory from the Python heap:
.. c:function:: void* PyMem_Malloc(size_t n)
Allocates *n* bytes and returns a pointer of type :c:type:`void\*` to the
allocated memory, or *NULL* if the request fails. Requesting zero bytes returns
a distinct non-*NULL* pointer if possible, as if ``PyMem_Malloc(1)`` had
been called instead. The memory will not have been initialized in any way.
.. c:function:: void* PyMem_Realloc(void *p, size_t n)
Resizes the memory block pointed to by *p* to *n* bytes. The contents will be
unchanged to the minimum of the old and the new sizes. If *p* is *NULL*, the
call is equivalent to ``PyMem_Malloc(n)``; else if *n* is equal to zero,
the memory block is resized but is not freed, and the returned pointer is
non-*NULL*. Unless *p* is *NULL*, it must have been returned by a previous call
to :c:func:`PyMem_Malloc` or :c:func:`PyMem_Realloc`. If the request fails,
:c:func:`PyMem_Realloc` returns *NULL* and *p* remains a valid pointer to the
previous memory area.
.. c:function:: void PyMem_Free(void *p)
Frees the memory block pointed to by *p*, which must have been returned by a
previous call to :c:func:`PyMem_Malloc` or :c:func:`PyMem_Realloc`. Otherwise, or
if ``PyMem_Free(p)`` has been called before, undefined behavior occurs. If
*p* is *NULL*, no operation is performed.
The following type-oriented macros are provided for convenience. Note that
*TYPE* refers to any C type.
.. c:function:: TYPE* PyMem_New(TYPE, size_t n)
Same as :c:func:`PyMem_Malloc`, but allocates ``(n * sizeof(TYPE))`` bytes of
memory. Returns a pointer cast to :c:type:`TYPE\*`. The memory will not have
been initialized in any way.
.. c:function:: TYPE* PyMem_Resize(void *p, TYPE, size_t n)
Same as :c:func:`PyMem_Realloc`, but the memory block is resized to ``(n *
sizeof(TYPE))`` bytes. Returns a pointer cast to :c:type:`TYPE\*`. On return,
*p* will be a pointer to the new memory area, or *NULL* in the event of
failure. This is a C preprocessor macro; p is always reassigned. Save
the original value of p to avoid losing memory when handling errors.
.. c:function:: void PyMem_Del(void *p)
Same as :c:func:`PyMem_Free`.
In addition, the following macro sets are provided for calling the Python memory
allocator directly, without involving the C API functions listed above. However,
note that their use does not preserve binary compatibility across Python
versions and is therefore deprecated in extension modules.
:c:func:`PyMem_MALLOC`, :c:func:`PyMem_REALLOC`, :c:func:`PyMem_FREE`.
:c:func:`PyMem_NEW`, :c:func:`PyMem_RESIZE`, :c:func:`PyMem_DEL`.
Object allocators
=================
The following function sets, modeled after the ANSI C standard, but specifying
behavior when requesting zero bytes, are available for allocating and releasing
memory from the Python heap.
By default, these functions use :ref:`pymalloc memory allocator <pymalloc>`.
.. warning::
The :term:`GIL <global interpreter lock>` must be held when using these
functions.
.. c:function:: void* PyObject_Malloc(size_t n)
Allocates *n* bytes and returns a pointer of type :c:type:`void\*` to the
allocated memory, or *NULL* if the request fails.
Requesting zero bytes returns a distinct non-*NULL* pointer if possible, as
if ``PyObject_Malloc(1)`` had been called instead. The memory will not have
been initialized in any way.
.. c:function:: void* PyObject_Realloc(void *p, size_t n)
Resizes the memory block pointed to by *p* to *n* bytes. The contents will be
unchanged to the minimum of the old and the new sizes.
If *p* is *NULL*, the call is equivalent to ``PyObject_Malloc(n)``; else if *n*
is equal to zero, the memory block is resized but is not freed, and the
returned pointer is non-*NULL*.
Unless *p* is *NULL*, it must have been returned by a previous call to
:c:func:`PyObject_Malloc`, :c:func:`PyObject_Realloc` or :c:func:`PyObject_Calloc`.
If the request fails, :c:func:`PyObject_Realloc` returns *NULL* and *p* remains
a valid pointer to the previous memory area.
.. c:function:: void PyObject_Free(void *p)
Frees the memory block pointed to by *p*, which must have been returned by a
previous call to :c:func:`PyObject_Malloc`, :c:func:`PyObject_Realloc` or
:c:func:`PyObject_Calloc`. Otherwise, or if ``PyObject_Free(p)`` has been called
before, undefined behavior occurs.
If *p* is *NULL*, no operation is performed.
In addition, the following macro sets are provided:
* :c:func:`PyObject_MALLOC`: alias to :c:func:`PyObject_Malloc`
* :c:func:`PyObject_REALLOC`: alias to :c:func:`PyObject_Realloc`
* :c:func:`PyObject_FREE`: alias to :c:func:`PyObject_Free`
* :c:func:`PyObject_Del`: alias to :c:func:`PyObject_Free`
* :c:func:`PyObject_DEL`: alias to :c:func:`PyObject_FREE` (so finally an alias
to :c:func:`PyObject_Free`)
.. _pymalloc:
The pymalloc allocator
======================
Python has a *pymalloc* allocator optimized for small objects (smaller or equal
to 512 bytes) with a short lifetime. It uses memory mappings called "arenas"
with a fixed size of 256 KiB. It falls back to :c:func:`malloc` and
:c:func:`realloc` for allocations larger than 512 bytes.
*pymalloc* is the default allocator of :c:func:`PyObject_Malloc`.
The arena allocator uses the following functions:
* :c:func:`mmap` and :c:func:`munmap` if available,
* :c:func:`malloc` and :c:func:`free` otherwise.
.. versionchanged:: 2.7.7
The threshold changed from 256 to 512 bytes. The arena allocator now
uses :c:func:`mmap` if available.
.. _memoryexamples:
Examples
========
Here is the example from section :ref:`memoryoverview`, rewritten so that the
I/O buffer is allocated from the Python heap by using the first function set::
PyObject *res;
char *buf = (char *) PyMem_Malloc(BUFSIZ); /* for I/O */
if (buf == NULL)
return PyErr_NoMemory();
/* ...Do some I/O operation involving buf... */
res = PyString_FromString(buf);
PyMem_Free(buf); /* allocated with PyMem_Malloc */
return res;
The same code using the type-oriented function set::
PyObject *res;
char *buf = PyMem_New(char, BUFSIZ); /* for I/O */
if (buf == NULL)
return PyErr_NoMemory();
/* ...Do some I/O operation involving buf... */
res = PyString_FromString(buf);
PyMem_Del(buf); /* allocated with PyMem_New */
return res;
Note that in the two examples above, the buffer is always manipulated via
functions belonging to the same set. Indeed, it is required to use the same
memory API family for a given memory block, so that the risk of mixing different
allocators is reduced to a minimum. The following code sequence contains two
errors, one of which is labeled as *fatal* because it mixes two different
allocators operating on different heaps. ::
char *buf1 = PyMem_New(char, BUFSIZ);
char *buf2 = (char *) malloc(BUFSIZ);
char *buf3 = (char *) PyMem_Malloc(BUFSIZ);
...
PyMem_Del(buf3); /* Wrong -- should be PyMem_Free() */
free(buf2); /* Right -- allocated via malloc() */
free(buf1); /* Fatal -- should be PyMem_Del() */
In addition to the functions aimed at handling raw memory blocks from the Python
heap, objects in Python are allocated and released with :c:func:`PyObject_New`,
:c:func:`PyObject_NewVar` and :c:func:`PyObject_Del`.
These will be explained in the next chapter on defining and implementing new
object types in C.
PK %�\9� �3 3 " html/_sources/c-api/method.rst.txtnu �[��� .. highlightlang:: c
.. _method-objects:
Method Objects
--------------
.. index:: object: method
There are some useful functions that are useful for working with method objects.
.. c:var:: PyTypeObject PyMethod_Type
.. index:: single: MethodType (in module types)
This instance of :c:type:`PyTypeObject` represents the Python method type. This
is exposed to Python programs as ``types.MethodType``.
.. c:function:: int PyMethod_Check(PyObject *o)
Return true if *o* is a method object (has type :c:data:`PyMethod_Type`). The
parameter must not be *NULL*.
.. c:function:: PyObject* PyMethod_New(PyObject *func, PyObject *self, PyObject *class)
Return a new method object, with *func* being any callable object; this is the
function that will be called when the method is called. If this method should
be bound to an instance, *self* should be the instance and *class* should be the
class of *self*, otherwise *self* should be *NULL* and *class* should be the
class which provides the unbound method..
.. c:function:: PyObject* PyMethod_Class(PyObject *meth)
Return the class object from which the method *meth* was created; if this was
created from an instance, it will be the class of the instance.
.. c:function:: PyObject* PyMethod_GET_CLASS(PyObject *meth)
Macro version of :c:func:`PyMethod_Class` which avoids error checking.
.. c:function:: PyObject* PyMethod_Function(PyObject *meth)
Return the function object associated with the method *meth*.
.. c:function:: PyObject* PyMethod_GET_FUNCTION(PyObject *meth)
Macro version of :c:func:`PyMethod_Function` which avoids error checking.
.. c:function:: PyObject* PyMethod_Self(PyObject *meth)
Return the instance associated with the method *meth* if it is bound, otherwise
return *NULL*.
.. c:function:: PyObject* PyMethod_GET_SELF(PyObject *meth)
Macro version of :c:func:`PyMethod_Self` which avoids error checking.
.. c:function:: int PyMethod_ClearFreeList()
Clear the free list. Return the total number of freed items.
.. versionadded:: 2.6
PK %�\��J� " html/_sources/c-api/module.rst.txtnu �[��� .. highlightlang:: c
.. _moduleobjects:
Module Objects
--------------
.. index:: object: module
There are only a few functions special to module objects.
.. c:var:: PyTypeObject PyModule_Type
.. index:: single: ModuleType (in module types)
This instance of :c:type:`PyTypeObject` represents the Python module type. This
is exposed to Python programs as ``types.ModuleType``.
.. c:function:: int PyModule_Check(PyObject *p)
Return true if *p* is a module object, or a subtype of a module object.
.. versionchanged:: 2.2
Allowed subtypes to be accepted.
.. c:function:: int PyModule_CheckExact(PyObject *p)
Return true if *p* is a module object, but not a subtype of
:c:data:`PyModule_Type`.
.. versionadded:: 2.2
.. c:function:: PyObject* PyModule_New(const char *name)
.. index::
single: __name__ (module attribute)
single: __doc__ (module attribute)
single: __file__ (module attribute)
Return a new module object with the :attr:`__name__` attribute set to *name*.
Only the module's :attr:`__doc__` and :attr:`__name__` attributes are filled in;
the caller is responsible for providing a :attr:`__file__` attribute.
.. c:function:: PyObject* PyModule_GetDict(PyObject *module)
.. index:: single: __dict__ (module attribute)
Return the dictionary object that implements *module*'s namespace; this object
is the same as the :attr:`~object.__dict__` attribute of the module object. This
function never fails. It is recommended extensions use other
:c:func:`PyModule_\*` and :c:func:`PyObject_\*` functions rather than directly
manipulate a module's :attr:`~object.__dict__`.
.. c:function:: char* PyModule_GetName(PyObject *module)
.. index::
single: __name__ (module attribute)
single: SystemError (built-in exception)
Return *module*'s :attr:`__name__` value. If the module does not provide one,
or if it is not a string, :exc:`SystemError` is raised and *NULL* is returned.
.. c:function:: char* PyModule_GetFilename(PyObject *module)
.. index::
single: __file__ (module attribute)
single: SystemError (built-in exception)
Return the name of the file from which *module* was loaded using *module*'s
:attr:`__file__` attribute. If this is not defined, or if it is not a string,
raise :exc:`SystemError` and return *NULL*.
.. c:function:: int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)
Add an object to *module* as *name*. This is a convenience function which can
be used from the module's initialization function. This steals a reference to
*value*. Return ``-1`` on error, ``0`` on success.
.. versionadded:: 2.0
.. c:function:: int PyModule_AddIntConstant(PyObject *module, const char *name, long value)
Add an integer constant to *module* as *name*. This convenience function can be
used from the module's initialization function. Return ``-1`` on error, ``0`` on
success.
.. versionadded:: 2.0
.. c:function:: int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)
Add a string constant to *module* as *name*. This convenience function can be
used from the module's initialization function. The string *value* must be
null-terminated. Return ``-1`` on error, ``0`` on success.
.. versionadded:: 2.0
.. c:function:: int PyModule_AddIntMacro(PyObject *module, macro)
Add an int constant to *module*. The name and the value are taken from
*macro*. For example ``PyModule_AddIntMacro(module, AF_INET)`` adds the int
constant *AF_INET* with the value of *AF_INET* to *module*.
Return ``-1`` on error, ``0`` on success.
.. versionadded:: 2.6
.. c:function:: int PyModule_AddStringMacro(PyObject *module, macro)
Add a string constant to *module*.
.. versionadded:: 2.6
PK %�\�Q9� � html/_sources/c-api/none.rst.txtnu �[��� .. highlightlang:: c
.. _noneobject:
The ``None`` Object
-------------------
.. index:: object: None
Note that the :c:type:`PyTypeObject` for ``None`` is not directly exposed in the
Python/C API. Since ``None`` is a singleton, testing for object identity (using
``==`` in C) is sufficient. There is no :c:func:`PyNone_Check` function for the
same reason.
.. c:var:: PyObject* Py_None
The Python ``None`` object, denoting lack of value. This object has no methods.
It needs to be treated just like any other object with respect to reference
counts.
.. c:macro:: Py_RETURN_NONE
Properly handle returning :c:data:`Py_None` from within a C function.
.. versionadded:: 2.4
PK %�\fj�ϣ. �. " html/_sources/c-api/number.rst.txtnu �[��� .. highlightlang:: c
.. _number:
Number Protocol
===============
.. c:function:: int PyNumber_Check(PyObject *o)
Returns ``1`` if the object *o* provides numeric protocols, and false otherwise.
This function always succeeds.
.. c:function:: PyObject* PyNumber_Add(PyObject *o1, PyObject *o2)
Returns the result of adding *o1* and *o2*, or *NULL* on failure. This is the
equivalent of the Python expression ``o1 + o2``.
.. c:function:: PyObject* PyNumber_Subtract(PyObject *o1, PyObject *o2)
Returns the result of subtracting *o2* from *o1*, or *NULL* on failure. This is
the equivalent of the Python expression ``o1 - o2``.
.. c:function:: PyObject* PyNumber_Multiply(PyObject *o1, PyObject *o2)
Returns the result of multiplying *o1* and *o2*, or *NULL* on failure. This is
the equivalent of the Python expression ``o1 * o2``.
.. c:function:: PyObject* PyNumber_Divide(PyObject *o1, PyObject *o2)
Returns the result of dividing *o1* by *o2*, or *NULL* on failure. This is the
equivalent of the Python expression ``o1 / o2``.
.. c:function:: PyObject* PyNumber_FloorDivide(PyObject *o1, PyObject *o2)
Return the floor of *o1* divided by *o2*, or *NULL* on failure. This is
equivalent to the "classic" division of integers.
.. versionadded:: 2.2
.. c:function:: PyObject* PyNumber_TrueDivide(PyObject *o1, PyObject *o2)
Return a reasonable approximation for the mathematical value of *o1* divided by
*o2*, or *NULL* on failure. The return value is "approximate" because binary
floating point numbers are approximate; it is not possible to represent all real
numbers in base two. This function can return a floating point value when
passed two integers.
.. versionadded:: 2.2
.. c:function:: PyObject* PyNumber_Remainder(PyObject *o1, PyObject *o2)
Returns the remainder of dividing *o1* by *o2*, or *NULL* on failure. This is
the equivalent of the Python expression ``o1 % o2``.
.. c:function:: PyObject* PyNumber_Divmod(PyObject *o1, PyObject *o2)
.. index:: builtin: divmod
See the built-in function :func:`divmod`. Returns *NULL* on failure. This is
the equivalent of the Python expression ``divmod(o1, o2)``.
.. c:function:: PyObject* PyNumber_Power(PyObject *o1, PyObject *o2, PyObject *o3)
.. index:: builtin: pow
See the built-in function :func:`pow`. Returns *NULL* on failure. This is the
equivalent of the Python expression ``pow(o1, o2, o3)``, where *o3* is optional.
If *o3* is to be ignored, pass :c:data:`Py_None` in its place (passing *NULL* for
*o3* would cause an illegal memory access).
.. c:function:: PyObject* PyNumber_Negative(PyObject *o)
Returns the negation of *o* on success, or *NULL* on failure. This is the
equivalent of the Python expression ``-o``.
.. c:function:: PyObject* PyNumber_Positive(PyObject *o)
Returns *o* on success, or *NULL* on failure. This is the equivalent of the
Python expression ``+o``.
.. c:function:: PyObject* PyNumber_Absolute(PyObject *o)
.. index:: builtin: abs
Returns the absolute value of *o*, or *NULL* on failure. This is the equivalent
of the Python expression ``abs(o)``.
.. c:function:: PyObject* PyNumber_Invert(PyObject *o)
Returns the bitwise negation of *o* on success, or *NULL* on failure. This is
the equivalent of the Python expression ``~o``.
.. c:function:: PyObject* PyNumber_Lshift(PyObject *o1, PyObject *o2)
Returns the result of left shifting *o1* by *o2* on success, or *NULL* on
failure. This is the equivalent of the Python expression ``o1 << o2``.
.. c:function:: PyObject* PyNumber_Rshift(PyObject *o1, PyObject *o2)
Returns the result of right shifting *o1* by *o2* on success, or *NULL* on
failure. This is the equivalent of the Python expression ``o1 >> o2``.
.. c:function:: PyObject* PyNumber_And(PyObject *o1, PyObject *o2)
Returns the "bitwise and" of *o1* and *o2* on success and *NULL* on failure.
This is the equivalent of the Python expression ``o1 & o2``.
.. c:function:: PyObject* PyNumber_Xor(PyObject *o1, PyObject *o2)
Returns the "bitwise exclusive or" of *o1* by *o2* on success, or *NULL* on
failure. This is the equivalent of the Python expression ``o1 ^ o2``.
.. c:function:: PyObject* PyNumber_Or(PyObject *o1, PyObject *o2)
Returns the "bitwise or" of *o1* and *o2* on success, or *NULL* on failure.
This is the equivalent of the Python expression ``o1 | o2``.
.. c:function:: PyObject* PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2)
Returns the result of adding *o1* and *o2*, or *NULL* on failure. The operation
is done *in-place* when *o1* supports it. This is the equivalent of the Python
statement ``o1 += o2``.
.. c:function:: PyObject* PyNumber_InPlaceSubtract(PyObject *o1, PyObject *o2)
Returns the result of subtracting *o2* from *o1*, or *NULL* on failure. The
operation is done *in-place* when *o1* supports it. This is the equivalent of
the Python statement ``o1 -= o2``.
.. c:function:: PyObject* PyNumber_InPlaceMultiply(PyObject *o1, PyObject *o2)
Returns the result of multiplying *o1* and *o2*, or *NULL* on failure. The
operation is done *in-place* when *o1* supports it. This is the equivalent of
the Python statement ``o1 *= o2``.
.. c:function:: PyObject* PyNumber_InPlaceDivide(PyObject *o1, PyObject *o2)
Returns the result of dividing *o1* by *o2*, or *NULL* on failure. The
operation is done *in-place* when *o1* supports it. This is the equivalent of
the Python statement ``o1 /= o2``.
.. c:function:: PyObject* PyNumber_InPlaceFloorDivide(PyObject *o1, PyObject *o2)
Returns the mathematical floor of dividing *o1* by *o2*, or *NULL* on failure.
The operation is done *in-place* when *o1* supports it. This is the equivalent
of the Python statement ``o1 //= o2``.
.. versionadded:: 2.2
.. c:function:: PyObject* PyNumber_InPlaceTrueDivide(PyObject *o1, PyObject *o2)
Return a reasonable approximation for the mathematical value of *o1* divided by
*o2*, or *NULL* on failure. The return value is "approximate" because binary
floating point numbers are approximate; it is not possible to represent all real
numbers in base two. This function can return a floating point value when
passed two integers. The operation is done *in-place* when *o1* supports it.
.. versionadded:: 2.2
.. c:function:: PyObject* PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2)
Returns the remainder of dividing *o1* by *o2*, or *NULL* on failure. The
operation is done *in-place* when *o1* supports it. This is the equivalent of
the Python statement ``o1 %= o2``.
.. c:function:: PyObject* PyNumber_InPlacePower(PyObject *o1, PyObject *o2, PyObject *o3)
.. index:: builtin: pow
See the built-in function :func:`pow`. Returns *NULL* on failure. The operation
is done *in-place* when *o1* supports it. This is the equivalent of the Python
statement ``o1 **= o2`` when o3 is :c:data:`Py_None`, or an in-place variant of
``pow(o1, o2, o3)`` otherwise. If *o3* is to be ignored, pass :c:data:`Py_None`
in its place (passing *NULL* for *o3* would cause an illegal memory access).
.. c:function:: PyObject* PyNumber_InPlaceLshift(PyObject *o1, PyObject *o2)
Returns the result of left shifting *o1* by *o2* on success, or *NULL* on
failure. The operation is done *in-place* when *o1* supports it. This is the
equivalent of the Python statement ``o1 <<= o2``.
.. c:function:: PyObject* PyNumber_InPlaceRshift(PyObject *o1, PyObject *o2)
Returns the result of right shifting *o1* by *o2* on success, or *NULL* on
failure. The operation is done *in-place* when *o1* supports it. This is the
equivalent of the Python statement ``o1 >>= o2``.
.. c:function:: PyObject* PyNumber_InPlaceAnd(PyObject *o1, PyObject *o2)
Returns the "bitwise and" of *o1* and *o2* on success and *NULL* on failure. The
operation is done *in-place* when *o1* supports it. This is the equivalent of
the Python statement ``o1 &= o2``.
.. c:function:: PyObject* PyNumber_InPlaceXor(PyObject *o1, PyObject *o2)
Returns the "bitwise exclusive or" of *o1* by *o2* on success, or *NULL* on
failure. The operation is done *in-place* when *o1* supports it. This is the
equivalent of the Python statement ``o1 ^= o2``.
.. c:function:: PyObject* PyNumber_InPlaceOr(PyObject *o1, PyObject *o2)
Returns the "bitwise or" of *o1* and *o2* on success, or *NULL* on failure. The
operation is done *in-place* when *o1* supports it. This is the equivalent of
the Python statement ``o1 |= o2``.
.. c:function:: int PyNumber_Coerce(PyObject **p1, PyObject **p2)
.. index:: builtin: coerce
This function takes the addresses of two variables of type :c:type:`PyObject\*`.
If the objects pointed to by ``*p1`` and ``*p2`` have the same type, increment
their reference count and return ``0`` (success). If the objects can be
converted to a common numeric type, replace ``*p1`` and ``*p2`` by their
converted value (with 'new' reference counts), and return ``0``. If no
conversion is possible, or if some other error occurs, return ``-1`` (failure)
and don't increment the reference counts. The call ``PyNumber_Coerce(&o1,
&o2)`` is equivalent to the Python statement ``o1, o2 = coerce(o1, o2)``.
.. c:function:: int PyNumber_CoerceEx(PyObject **p1, PyObject **p2)
This function is similar to :c:func:`PyNumber_Coerce`, except that it returns
``1`` when the conversion is not possible and when no error is raised.
Reference counts are still not increased in this case.
.. c:function:: PyObject* PyNumber_Int(PyObject *o)
.. index:: builtin: int
Returns the *o* converted to an integer object on success, or *NULL* on failure.
If the argument is outside the integer range a long object will be returned
instead. This is the equivalent of the Python expression ``int(o)``.
.. c:function:: PyObject* PyNumber_Long(PyObject *o)
.. index:: builtin: long
Returns the *o* converted to a long integer object on success, or *NULL* on
failure. This is the equivalent of the Python expression ``long(o)``.
.. c:function:: PyObject* PyNumber_Float(PyObject *o)
.. index:: builtin: float
Returns the *o* converted to a float object on success, or *NULL* on failure.
This is the equivalent of the Python expression ``float(o)``.
.. c:function:: PyObject* PyNumber_Index(PyObject *o)
Returns the *o* converted to a Python int or long on success or *NULL* with a
:exc:`TypeError` exception raised on failure.
.. versionadded:: 2.5
.. c:function:: PyObject* PyNumber_ToBase(PyObject *n, int base)
Returns the integer *n* converted to *base* as a string with a base
marker of ``'0b'``, ``'0o'``, or ``'0x'`` if applicable. When
*base* is not 2, 8, 10, or 16, the format is ``'x#num'`` where x is the
base. If *n* is not an int object, it is converted with
:c:func:`PyNumber_Index` first.
.. versionadded:: 2.6
.. c:function:: Py_ssize_t PyNumber_AsSsize_t(PyObject *o, PyObject *exc)
Returns *o* converted to a Py_ssize_t value if *o* can be interpreted as an
integer. If *o* can be converted to a Python int or long but the attempt to
convert to a Py_ssize_t value would raise an :exc:`OverflowError`, then the
*exc* argument is the type of exception that will be raised (usually
:exc:`IndexError` or :exc:`OverflowError`). If *exc* is *NULL*, then the
exception is cleared and the value is clipped to *PY_SSIZE_T_MIN* for a negative
integer or *PY_SSIZE_T_MAX* for a positive integer.
.. versionadded:: 2.5
.. c:function:: int PyIndex_Check(PyObject *o)
Returns ``1`` if *o* is an index integer (has the nb_index slot of the
tp_as_number structure filled in), and ``0`` otherwise.
.. versionadded:: 2.5
PK %�\o���� � % html/_sources/c-api/objbuffer.rst.txtnu �[��� .. highlightlang:: c
.. _abstract-buffer:
Old Buffer Protocol
===================
This section describes the legacy buffer protocol, which has been introduced
in Python 1.6. It is still supported but deprecated in the Python 2.x series.
Python 3 introduces a new buffer protocol which fixes weaknesses and
shortcomings of the protocol, and has been backported to Python 2.6. See
:ref:`bufferobjects` for more information.
.. c:function:: int PyObject_AsCharBuffer(PyObject *obj, const char **buffer, Py_ssize_t *buffer_len)
Returns a pointer to a read-only memory location usable as character-based
input. The *obj* argument must support the single-segment character buffer
interface. On success, returns ``0``, sets *buffer* to the memory location
and *buffer_len* to the buffer length. Returns ``-1`` and sets a
:exc:`TypeError` on error.
.. versionadded:: 1.6
.. versionchanged:: 2.5
This function used an :c:type:`int *` type for *buffer_len*. This might
require changes in your code for properly supporting 64-bit systems.
.. c:function:: int PyObject_AsReadBuffer(PyObject *obj, const void **buffer, Py_ssize_t *buffer_len)
Returns a pointer to a read-only memory location containing arbitrary data.
The *obj* argument must support the single-segment readable buffer
interface. On success, returns ``0``, sets *buffer* to the memory location
and *buffer_len* to the buffer length. Returns ``-1`` and sets a
:exc:`TypeError` on error.
.. versionadded:: 1.6
.. versionchanged:: 2.5
This function used an :c:type:`int *` type for *buffer_len*. This might
require changes in your code for properly supporting 64-bit systems.
.. c:function:: int PyObject_CheckReadBuffer(PyObject *o)
Returns ``1`` if *o* supports the single-segment readable buffer interface.
Otherwise returns ``0``.
.. versionadded:: 2.2
.. c:function:: int PyObject_AsWriteBuffer(PyObject *obj, void **buffer, Py_ssize_t *buffer_len)
Returns a pointer to a writeable memory location. The *obj* argument must
support the single-segment, character buffer interface. On success,
returns ``0``, sets *buffer* to the memory location and *buffer_len* to the
buffer length. Returns ``-1`` and sets a :exc:`TypeError` on error.
.. versionadded:: 1.6
.. versionchanged:: 2.5
This function used an :c:type:`int *` type for *buffer_len*. This might
require changes in your code for properly supporting 64-bit systems.
PK %�\���SD SD " html/_sources/c-api/object.rst.txtnu �[��� .. highlightlang:: c
.. _object:
Object Protocol
===============
.. c:function:: int PyObject_Print(PyObject *o, FILE *fp, int flags)
Print an object *o*, on file *fp*. Returns ``-1`` on error. The flags argument
is used to enable certain printing options. The only option currently supported
is :const:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written
instead of the :func:`repr`.
.. c:function:: int PyObject_HasAttr(PyObject *o, PyObject *attr_name)
Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise. This
is equivalent to the Python expression ``hasattr(o, attr_name)``. This function
always succeeds.
.. c:function:: int PyObject_HasAttrString(PyObject *o, const char *attr_name)
Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise. This
is equivalent to the Python expression ``hasattr(o, attr_name)``. This function
always succeeds.
.. c:function:: PyObject* PyObject_GetAttr(PyObject *o, PyObject *attr_name)
Retrieve an attribute named *attr_name* from object *o*. Returns the attribute
value on success, or *NULL* on failure. This is the equivalent of the Python
expression ``o.attr_name``.
.. c:function:: PyObject* PyObject_GetAttrString(PyObject *o, const char *attr_name)
Retrieve an attribute named *attr_name* from object *o*. Returns the attribute
value on success, or *NULL* on failure. This is the equivalent of the Python
expression ``o.attr_name``.
.. c:function:: PyObject* PyObject_GenericGetAttr(PyObject *o, PyObject *name)
Generic attribute getter function that is meant to be put into a type
object's ``tp_getattro`` slot. It looks for a descriptor in the dictionary
of classes in the object's MRO as well as an attribute in the object's
:attr:`~object.__dict__` (if present). As outlined in :ref:`descriptors`,
data descriptors take preference over instance attributes, while non-data
descriptors don't. Otherwise, an :exc:`AttributeError` is raised.
.. c:function:: int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v)
Set the value of the attribute named *attr_name*, for object *o*, to the value
*v*. Raise an exception and return ``-1`` on failure;
return ``0`` on success. This is the equivalent of the Python statement
``o.attr_name = v``.
If *v* is *NULL*, the attribute is deleted, however this feature is
deprecated in favour of using :c:func:`PyObject_DelAttr`.
.. c:function:: int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v)
Set the value of the attribute named *attr_name*, for object *o*, to the value
*v*. Raise an exception and return ``-1`` on failure;
return ``0`` on success. This is the equivalent of the Python statement
``o.attr_name = v``.
If *v* is *NULL*, the attribute is deleted, however this feature is
deprecated in favour of using :c:func:`PyObject_DelAttrString`.
.. c:function:: int PyObject_GenericSetAttr(PyObject *o, PyObject *name, PyObject *value)
Generic attribute setter and deleter function that is meant
to be put into a type object's :c:member:`~PyTypeObject.tp_setattro`
slot. It looks for a data descriptor in the
dictionary of classes in the object's MRO, and if found it takes preference
over setting or deleting the attribute in the instance dictionary. Otherwise, the
attribute is set or deleted in the object's :attr:`~object.__dict__` (if present).
On success, ``0`` is returned, otherwise an :exc:`AttributeError`
is raised and ``-1`` is returned.
.. c:function:: int PyObject_DelAttr(PyObject *o, PyObject *attr_name)
Delete attribute named *attr_name*, for object *o*. Returns ``-1`` on failure.
This is the equivalent of the Python statement ``del o.attr_name``.
.. c:function:: int PyObject_DelAttrString(PyObject *o, const char *attr_name)
Delete attribute named *attr_name*, for object *o*. Returns ``-1`` on failure.
This is the equivalent of the Python statement ``del o.attr_name``.
.. c:function:: PyObject* PyObject_RichCompare(PyObject *o1, PyObject *o2, int opid)
Compare the values of *o1* and *o2* using the operation specified by *opid*,
which must be one of :const:`Py_LT`, :const:`Py_LE`, :const:`Py_EQ`,
:const:`Py_NE`, :const:`Py_GT`, or :const:`Py_GE`, corresponding to ``<``,
``<=``, ``==``, ``!=``, ``>``, or ``>=`` respectively. This is the equivalent of
the Python expression ``o1 op o2``, where ``op`` is the operator corresponding
to *opid*. Returns the value of the comparison on success, or *NULL* on failure.
.. c:function:: int PyObject_RichCompareBool(PyObject *o1, PyObject *o2, int opid)
Compare the values of *o1* and *o2* using the operation specified by *opid*,
which must be one of :const:`Py_LT`, :const:`Py_LE`, :const:`Py_EQ`,
:const:`Py_NE`, :const:`Py_GT`, or :const:`Py_GE`, corresponding to ``<``,
``<=``, ``==``, ``!=``, ``>``, or ``>=`` respectively. Returns ``-1`` on error,
``0`` if the result is false, ``1`` otherwise. This is the equivalent of the
Python expression ``o1 op o2``, where ``op`` is the operator corresponding to
*opid*.
.. note::
If *o1* and *o2* are the same object, :c:func:`PyObject_RichCompareBool`
will always return ``1`` for :const:`Py_EQ` and ``0`` for :const:`Py_NE`.
.. c:function:: int PyObject_Cmp(PyObject *o1, PyObject *o2, int *result)
.. index:: builtin: cmp
Compare the values of *o1* and *o2* using a routine provided by *o1*, if one
exists, otherwise with a routine provided by *o2*. The result of the comparison
is returned in *result*. Returns ``-1`` on failure. This is the equivalent of
the Python statement ``result = cmp(o1, o2)``.
.. c:function:: int PyObject_Compare(PyObject *o1, PyObject *o2)
.. index:: builtin: cmp
Compare the values of *o1* and *o2* using a routine provided by *o1*, if one
exists, otherwise with a routine provided by *o2*. Returns the result of the
comparison on success. On error, the value returned is undefined; use
:c:func:`PyErr_Occurred` to detect an error. This is equivalent to the Python
expression ``cmp(o1, o2)``.
.. c:function:: PyObject* PyObject_Repr(PyObject *o)
.. index:: builtin: repr
Compute a string representation of object *o*. Returns the string
representation on success, *NULL* on failure. This is the equivalent of the
Python expression ``repr(o)``. Called by the :func:`repr` built-in function and
by reverse quotes.
.. c:function:: PyObject* PyObject_Str(PyObject *o)
.. index:: builtin: str
Compute a string representation of object *o*. Returns the string
representation on success, *NULL* on failure. This is the equivalent of the
Python expression ``str(o)``. Called by the :func:`str` built-in function and
by the :keyword:`print` statement.
.. c:function:: PyObject* PyObject_Bytes(PyObject *o)
.. index:: builtin: bytes
Compute a bytes representation of object *o*. In 2.x, this is just an alias
for :c:func:`PyObject_Str`.
.. c:function:: PyObject* PyObject_Unicode(PyObject *o)
.. index:: builtin: unicode
Compute a Unicode string representation of object *o*. Returns the Unicode
string representation on success, *NULL* on failure. This is the equivalent of
the Python expression ``unicode(o)``. Called by the :func:`unicode` built-in
function.
.. c:function:: int PyObject_IsInstance(PyObject *inst, PyObject *cls)
Returns ``1`` if *inst* is an instance of the class *cls* or a subclass of
*cls*, or ``0`` if not. On error, returns ``-1`` and sets an exception. If
*cls* is a type object rather than a class object, :c:func:`PyObject_IsInstance`
returns ``1`` if *inst* is of type *cls*. If *cls* is a tuple, the check will
be done against every entry in *cls*. The result will be ``1`` when at least one
of the checks returns ``1``, otherwise it will be ``0``. If *inst* is not a
class instance and *cls* is neither a type object, nor a class object, nor a
tuple, *inst* must have a :attr:`~instance.__class__` attribute --- the
class relationship of the value of that attribute with *cls* will be used
to determine the result of this function.
.. versionadded:: 2.1
.. versionchanged:: 2.2
Support for a tuple as the second argument added.
Subclass determination is done in a fairly straightforward way, but includes a
wrinkle that implementors of extensions to the class system may want to be aware
of. If :class:`A` and :class:`B` are class objects, :class:`B` is a subclass of
:class:`A` if it inherits from :class:`A` either directly or indirectly. If
either is not a class object, a more general mechanism is used to determine the
class relationship of the two objects. When testing if *B* is a subclass of
*A*, if *A* is *B*, :c:func:`PyObject_IsSubclass` returns true. If *A* and *B*
are different objects, *B*'s :attr:`~class.__bases__` attribute is searched in
a depth-first fashion for *A* --- the presence of the :attr:`~class.__bases__`
attribute is considered sufficient for this determination.
.. c:function:: int PyObject_IsSubclass(PyObject *derived, PyObject *cls)
Returns ``1`` if the class *derived* is identical to or derived from the class
*cls*, otherwise returns ``0``. In case of an error, returns ``-1``. If *cls*
is a tuple, the check will be done against every entry in *cls*. The result will
be ``1`` when at least one of the checks returns ``1``, otherwise it will be
``0``. If either *derived* or *cls* is not an actual class object (or tuple),
this function uses the generic algorithm described above.
.. versionadded:: 2.1
.. versionchanged:: 2.3
Older versions of Python did not support a tuple as the second argument.
.. c:function:: int PyCallable_Check(PyObject *o)
Determine if the object *o* is callable. Return ``1`` if the object is callable
and ``0`` otherwise. This function always succeeds.
.. c:function:: PyObject* PyObject_Call(PyObject *callable_object, PyObject *args, PyObject *kw)
.. index:: builtin: apply
Call a callable Python object *callable_object*, with arguments given by the
tuple *args*, and named arguments given by the dictionary *kw*. If no named
arguments are needed, *kw* may be *NULL*. *args* must not be *NULL*, use an
empty tuple if no arguments are needed. Returns the result of the call on
success, or *NULL* on failure. This is the equivalent of the Python expression
``apply(callable_object, args, kw)`` or ``callable_object(*args, **kw)``.
.. versionadded:: 2.2
.. c:function:: PyObject* PyObject_CallObject(PyObject *callable_object, PyObject *args)
.. index:: builtin: apply
Call a callable Python object *callable_object*, with arguments given by the
tuple *args*. If no arguments are needed, then *args* may be *NULL*. Returns
the result of the call on success, or *NULL* on failure. This is the equivalent
of the Python expression ``apply(callable_object, args)`` or
``callable_object(*args)``.
.. c:function:: PyObject* PyObject_CallFunction(PyObject *callable, char *format, ...)
.. index:: builtin: apply
Call a callable Python object *callable*, with a variable number of C arguments.
The C arguments are described using a :c:func:`Py_BuildValue` style format
string. The format may be *NULL*, indicating that no arguments are provided.
Returns the result of the call on success, or *NULL* on failure. This is the
equivalent of the Python expression ``apply(callable, args)`` or
``callable(*args)``. Note that if you only pass :c:type:`PyObject \*` args,
:c:func:`PyObject_CallFunctionObjArgs` is a faster alternative.
.. c:function:: PyObject* PyObject_CallMethod(PyObject *o, char *method, char *format, ...)
Call the method named *method* of object *o* with a variable number of C
arguments. The C arguments are described by a :c:func:`Py_BuildValue` format
string that should produce a tuple. The format may be *NULL*, indicating that
no arguments are provided. Returns the result of the call on success, or *NULL*
on failure. This is the equivalent of the Python expression ``o.method(args)``.
Note that if you only pass :c:type:`PyObject \*` args,
:c:func:`PyObject_CallMethodObjArgs` is a faster alternative.
.. c:function:: PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ..., NULL)
Call a callable Python object *callable*, with a variable number of
:c:type:`PyObject\*` arguments. The arguments are provided as a variable number
of parameters followed by *NULL*. Returns the result of the call on success, or
*NULL* on failure.
.. versionadded:: 2.2
.. c:function:: PyObject* PyObject_CallMethodObjArgs(PyObject *o, PyObject *name, ..., NULL)
Calls a method of the object *o*, where the name of the method is given as a
Python string object in *name*. It is called with a variable number of
:c:type:`PyObject\*` arguments. The arguments are provided as a variable number
of parameters followed by *NULL*. Returns the result of the call on success, or
*NULL* on failure.
.. versionadded:: 2.2
.. c:function:: long PyObject_Hash(PyObject *o)
.. index:: builtin: hash
Compute and return the hash value of an object *o*. On failure, return ``-1``.
This is the equivalent of the Python expression ``hash(o)``.
.. c:function:: long PyObject_HashNotImplemented(PyObject *o)
Set a :exc:`TypeError` indicating that ``type(o)`` is not hashable and return ``-1``.
This function receives special treatment when stored in a ``tp_hash`` slot,
allowing a type to explicitly indicate to the interpreter that it is not
hashable.
.. versionadded:: 2.6
.. c:function:: int PyObject_IsTrue(PyObject *o)
Returns ``1`` if the object *o* is considered to be true, and ``0`` otherwise.
This is equivalent to the Python expression ``not not o``. On failure, return
``-1``.
.. c:function:: int PyObject_Not(PyObject *o)
Returns ``0`` if the object *o* is considered to be true, and ``1`` otherwise.
This is equivalent to the Python expression ``not o``. On failure, return
``-1``.
.. c:function:: PyObject* PyObject_Type(PyObject *o)
.. index:: builtin: type
When *o* is non-*NULL*, returns a type object corresponding to the object type
of object *o*. On failure, raises :exc:`SystemError` and returns *NULL*. This
is equivalent to the Python expression ``type(o)``. This function increments the
reference count of the return value. There's really no reason to use this
function instead of the common expression ``o->ob_type``, which returns a
pointer of type :c:type:`PyTypeObject\*`, except when the incremented reference
count is needed.
.. c:function:: int PyObject_TypeCheck(PyObject *o, PyTypeObject *type)
Return true if the object *o* is of type *type* or a subtype of *type*. Both
parameters must be non-*NULL*.
.. versionadded:: 2.2
.. c:function:: Py_ssize_t PyObject_Length(PyObject *o)
Py_ssize_t PyObject_Size(PyObject *o)
.. index:: builtin: len
Return the length of object *o*. If the object *o* provides either the sequence
and mapping protocols, the sequence length is returned. On error, ``-1`` is
returned. This is the equivalent to the Python expression ``len(o)``.
.. versionchanged:: 2.5
These functions returned an :c:type:`int` type. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyObject_GetItem(PyObject *o, PyObject *key)
Return element of *o* corresponding to the object *key* or *NULL* on failure.
This is the equivalent of the Python expression ``o[key]``.
.. c:function:: int PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v)
Map the object *key* to the value *v*. Raise an exception and
return ``-1`` on failure; return ``0`` on success. This is the
equivalent of the Python statement ``o[key] = v``.
.. c:function:: int PyObject_DelItem(PyObject *o, PyObject *key)
Delete the mapping for *key* from *o*. Returns ``-1`` on failure. This is the
equivalent of the Python statement ``del o[key]``.
.. c:function:: int PyObject_AsFileDescriptor(PyObject *o)
Derives a file descriptor from a Python object. If the object is an integer or
long integer, its value is returned. If not, the object's :meth:`fileno` method
is called if it exists; the method must return an integer or long integer, which
is returned as the file descriptor value. Returns ``-1`` on failure.
.. c:function:: PyObject* PyObject_Dir(PyObject *o)
This is equivalent to the Python expression ``dir(o)``, returning a (possibly
empty) list of strings appropriate for the object argument, or *NULL* if there
was an error. If the argument is *NULL*, this is like the Python ``dir()``,
returning the names of the current locals; in this case, if no execution frame
is active then *NULL* is returned but :c:func:`PyErr_Occurred` will return false.
.. c:function:: PyObject* PyObject_GetIter(PyObject *o)
This is equivalent to the Python expression ``iter(o)``. It returns a new
iterator for the object argument, or the object itself if the object is already
an iterator. Raises :exc:`TypeError` and returns *NULL* if the object cannot be
iterated.
PK %�\D�<1 1 # html/_sources/c-api/objimpl.rst.txtnu �[��� .. highlightlang:: c
.. _newtypes:
*****************************
Object Implementation Support
*****************************
This chapter describes the functions, types, and macros used when defining new
object types.
.. toctree::
allocation.rst
structures.rst
typeobj.rst
gcsupport.rst
PK %�\���tv v ' html/_sources/c-api/refcounting.rst.txtnu �[��� .. highlightlang:: c
.. _countingrefs:
******************
Reference Counting
******************
The macros in this section are used for managing reference counts of Python
objects.
.. c:function:: void Py_INCREF(PyObject *o)
Increment the reference count for object *o*. The object must not be *NULL*; if
you aren't sure that it isn't *NULL*, use :c:func:`Py_XINCREF`.
.. c:function:: void Py_XINCREF(PyObject *o)
Increment the reference count for object *o*. The object may be *NULL*, in
which case the macro has no effect.
.. c:function:: void Py_DECREF(PyObject *o)
Decrement the reference count for object *o*. The object must not be *NULL*; if
you aren't sure that it isn't *NULL*, use :c:func:`Py_XDECREF`. If the reference
count reaches zero, the object's type's deallocation function (which must not be
*NULL*) is invoked.
.. warning::
The deallocation function can cause arbitrary Python code to be invoked (e.g.
when a class instance with a :meth:`__del__` method is deallocated). While
exceptions in such code are not propagated, the executed code has free access to
all Python global variables. This means that any object that is reachable from
a global variable should be in a consistent state before :c:func:`Py_DECREF` is
invoked. For example, code to delete an object from a list should copy a
reference to the deleted object in a temporary variable, update the list data
structure, and then call :c:func:`Py_DECREF` for the temporary variable.
.. c:function:: void Py_XDECREF(PyObject *o)
Decrement the reference count for object *o*. The object may be *NULL*, in
which case the macro has no effect; otherwise the effect is the same as for
:c:func:`Py_DECREF`, and the same warning applies.
.. c:function:: void Py_CLEAR(PyObject *o)
Decrement the reference count for object *o*. The object may be *NULL*, in
which case the macro has no effect; otherwise the effect is the same as for
:c:func:`Py_DECREF`, except that the argument is also set to *NULL*. The warning
for :c:func:`Py_DECREF` does not apply with respect to the object passed because
the macro carefully uses a temporary variable and sets the argument to *NULL*
before decrementing its reference count.
It is a good idea to use this macro whenever decrementing the value of a
variable that might be traversed during garbage collection.
.. versionadded:: 2.4
The following functions are for runtime dynamic embedding of Python:
``Py_IncRef(PyObject *o)``, ``Py_DecRef(PyObject *o)``. They are
simply exported function versions of :c:func:`Py_XINCREF` and
:c:func:`Py_XDECREF`, respectively.
The following functions or macros are only for use within the interpreter core:
:c:func:`_Py_Dealloc`, :c:func:`_Py_ForgetReference`, :c:func:`_Py_NewReference`,
as well as the global variable :c:data:`_Py_RefTotal`.
PK %�\�'
� & html/_sources/c-api/reflection.rst.txtnu �[��� .. highlightlang:: c
.. _reflection:
Reflection
==========
.. c:function:: PyObject* PyEval_GetBuiltins()
Return a dictionary of the builtins in the current execution frame,
or the interpreter of the thread state if no frame is currently executing.
.. c:function:: PyObject* PyEval_GetLocals()
Return a dictionary of the local variables in the current execution frame,
or *NULL* if no frame is currently executing.
.. c:function:: PyObject* PyEval_GetGlobals()
Return a dictionary of the global variables in the current execution frame,
or *NULL* if no frame is currently executing.
.. c:function:: PyFrameObject* PyEval_GetFrame()
Return the current thread state's frame, which is *NULL* if no frame is
currently executing.
.. c:function:: int PyFrame_GetLineNumber(PyFrameObject *frame)
Return the line number that *frame* is currently executing.
.. c:function:: int PyEval_GetRestricted()
If there is a current frame and it is executing in restricted mode, return true,
otherwise false.
.. c:function:: const char* PyEval_GetFuncName(PyObject *func)
Return the name of *func* if it is a function, class or instance object, else the
name of *func*\s type.
.. c:function:: const char* PyEval_GetFuncDesc(PyObject *func)
Return a description string, depending on the type of *func*.
Return values include "()" for functions and methods, " constructor",
" instance", and " object". Concatenated with the result of
:c:func:`PyEval_GetFuncName`, the result will be a description of
*func*.
PK %�\��`s " " $ html/_sources/c-api/sequence.rst.txtnu �[��� .. highlightlang:: c
.. _sequence:
Sequence Protocol
=================
.. c:function:: int PySequence_Check(PyObject *o)
Return ``1`` if the object provides sequence protocol, and ``0`` otherwise.
This function always succeeds.
.. c:function:: Py_ssize_t PySequence_Size(PyObject *o)
Py_ssize_t PySequence_Length(PyObject *o)
.. index:: builtin: len
Returns the number of objects in sequence *o* on success, and ``-1`` on
failure. This is equivalent to the Python expression ``len(o)``.
.. versionchanged:: 2.5
These functions returned an :c:type:`int` type. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PySequence_Concat(PyObject *o1, PyObject *o2)
Return the concatenation of *o1* and *o2* on success, and *NULL* on failure.
This is the equivalent of the Python expression ``o1 + o2``.
.. c:function:: PyObject* PySequence_Repeat(PyObject *o, Py_ssize_t count)
Return the result of repeating sequence object *o* *count* times, or *NULL* on
failure. This is the equivalent of the Python expression ``o * count``.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *count*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PySequence_InPlaceConcat(PyObject *o1, PyObject *o2)
Return the concatenation of *o1* and *o2* on success, and *NULL* on failure.
The operation is done *in-place* when *o1* supports it. This is the equivalent
of the Python expression ``o1 += o2``.
.. c:function:: PyObject* PySequence_InPlaceRepeat(PyObject *o, Py_ssize_t count)
Return the result of repeating sequence object *o* *count* times, or *NULL* on
failure. The operation is done *in-place* when *o* supports it. This is the
equivalent of the Python expression ``o *= count``.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *count*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PySequence_GetItem(PyObject *o, Py_ssize_t i)
Return the *i*\ th element of *o*, or *NULL* on failure. This is the equivalent of
the Python expression ``o[i]``.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *i*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PySequence_GetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2)
Return the slice of sequence object *o* between *i1* and *i2*, or *NULL* on
failure. This is the equivalent of the Python expression ``o[i1:i2]``.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *i1* and *i2*. This might
require changes in your code for properly supporting 64-bit systems.
.. c:function:: int PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v)
Assign object *v* to the *i*\ th element of *o*. Raise an exception
and return ``-1`` on failure; return ``0`` on success. This
is the equivalent of the Python statement ``o[i] = v``. This function *does
not* steal a reference to *v*.
If *v* is *NULL*, the element is deleted, however this feature is
deprecated in favour of using :c:func:`PySequence_DelItem`.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *i*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: int PySequence_DelItem(PyObject *o, Py_ssize_t i)
Delete the *i*\ th element of object *o*. Returns ``-1`` on failure. This is the
equivalent of the Python statement ``del o[i]``.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *i*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: int PySequence_SetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2, PyObject *v)
Assign the sequence object *v* to the slice in sequence object *o* from *i1* to
*i2*. Raise an exception and return ``-1`` on failure; return ``0`` on success.
This is the equivalent of the Python statement ``o[i1:i2] = v``.
If *v* is *NULL*, the slice is deleted, however this feature is
deprecated in favour of using :c:func:`PySequence_DelSlice`.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *i1* and *i2*. This might
require changes in your code for properly supporting 64-bit systems.
.. c:function:: int PySequence_DelSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2)
Delete the slice in sequence object *o* from *i1* to *i2*. Returns ``-1`` on
failure. This is the equivalent of the Python statement ``del o[i1:i2]``.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *i1* and *i2*. This might
require changes in your code for properly supporting 64-bit systems.
.. c:function:: Py_ssize_t PySequence_Count(PyObject *o, PyObject *value)
Return the number of occurrences of *value* in *o*, that is, return the number
of keys for which ``o[key] == value``. On failure, return ``-1``. This is
equivalent to the Python expression ``o.count(value)``.
.. versionchanged:: 2.5
This function returned an :c:type:`int` type. This might require changes
in your code for properly supporting 64-bit systems.
.. c:function:: int PySequence_Contains(PyObject *o, PyObject *value)
Determine if *o* contains *value*. If an item in *o* is equal to *value*,
return ``1``, otherwise return ``0``. On error, return ``-1``. This is
equivalent to the Python expression ``value in o``.
.. c:function:: Py_ssize_t PySequence_Index(PyObject *o, PyObject *value)
Return the first index *i* for which ``o[i] == value``. On error, return
``-1``. This is equivalent to the Python expression ``o.index(value)``.
.. versionchanged:: 2.5
This function returned an :c:type:`int` type. This might require changes
in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PySequence_List(PyObject *o)
Return a list object with the same contents as the arbitrary sequence *o*. The
returned list is guaranteed to be new.
.. c:function:: PyObject* PySequence_Tuple(PyObject *o)
.. index:: builtin: tuple
Return a tuple object with the same contents as the arbitrary sequence *o* or
*NULL* on failure. If *o* is a tuple, a new reference will be returned,
otherwise a tuple will be constructed with the appropriate contents. This is
equivalent to the Python expression ``tuple(o)``.
.. c:function:: PyObject* PySequence_Fast(PyObject *o, const char *m)
Return the sequence *o* as a list, unless it is already a tuple or list, in
which case *o* is returned. Use :c:func:`PySequence_Fast_GET_ITEM` to access
the members of the result. Returns *NULL* on failure. If the object is not
a sequence, raises :exc:`TypeError` with *m* as the message text.
.. c:function:: PyObject* PySequence_Fast_GET_ITEM(PyObject *o, Py_ssize_t i)
Return the *i*\ th element of *o*, assuming that *o* was returned by
:c:func:`PySequence_Fast`, *o* is not *NULL*, and that *i* is within bounds.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *i*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject** PySequence_Fast_ITEMS(PyObject *o)
Return the underlying array of PyObject pointers. Assumes that *o* was returned
by :c:func:`PySequence_Fast` and *o* is not *NULL*.
Note, if a list gets resized, the reallocation may relocate the items array.
So, only use the underlying array pointer in contexts where the sequence
cannot change.
.. versionadded:: 2.4
.. c:function:: PyObject* PySequence_ITEM(PyObject *o, Py_ssize_t i)
Return the *i*\ th element of *o* or *NULL* on failure. Macro form of
:c:func:`PySequence_GetItem` but without checking that
:c:func:`PySequence_Check` on *o* is true and without adjustment for negative
indices.
.. versionadded:: 2.3
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *i*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: Py_ssize_t PySequence_Fast_GET_SIZE(PyObject *o)
Returns the length of *o*, assuming that *o* was returned by
:c:func:`PySequence_Fast` and that *o* is not *NULL*. The size can also be
gotten by calling :c:func:`PySequence_Size` on *o*, but
:c:func:`PySequence_Fast_GET_SIZE` is faster because it can assume *o* is a list
or tuple.
PK %�\���� � html/_sources/c-api/set.rst.txtnu �[��� .. highlightlang:: c
.. _setobjects:
Set Objects
-----------
.. sectionauthor:: Raymond D. Hettinger <python@rcn.com>
.. index::
object: set
object: frozenset
.. versionadded:: 2.5
This section details the public API for :class:`set` and :class:`frozenset`
objects. Any functionality not listed below is best accessed using the either
the abstract object protocol (including :c:func:`PyObject_CallMethod`,
:c:func:`PyObject_RichCompareBool`, :c:func:`PyObject_Hash`,
:c:func:`PyObject_Repr`, :c:func:`PyObject_IsTrue`, :c:func:`PyObject_Print`, and
:c:func:`PyObject_GetIter`) or the abstract number protocol (including
:c:func:`PyNumber_And`, :c:func:`PyNumber_Subtract`, :c:func:`PyNumber_Or`,
:c:func:`PyNumber_Xor`, :c:func:`PyNumber_InPlaceAnd`,
:c:func:`PyNumber_InPlaceSubtract`, :c:func:`PyNumber_InPlaceOr`, and
:c:func:`PyNumber_InPlaceXor`).
.. c:type:: PySetObject
This subtype of :c:type:`PyObject` is used to hold the internal data for both
:class:`set` and :class:`frozenset` objects. It is like a :c:type:`PyDictObject`
in that it is a fixed size for small sets (much like tuple storage) and will
point to a separate, variable sized block of memory for medium and large sized
sets (much like list storage). None of the fields of this structure should be
considered public and are subject to change. All access should be done through
the documented API rather than by manipulating the values in the structure.
.. c:var:: PyTypeObject PySet_Type
This is an instance of :c:type:`PyTypeObject` representing the Python
:class:`set` type.
.. c:var:: PyTypeObject PyFrozenSet_Type
This is an instance of :c:type:`PyTypeObject` representing the Python
:class:`frozenset` type.
The following type check macros work on pointers to any Python object. Likewise,
the constructor functions work with any iterable Python object.
.. c:function:: int PySet_Check(PyObject *p)
Return true if *p* is a :class:`set` object or an instance of a subtype.
.. versionadded:: 2.6
.. c:function:: int PyFrozenSet_Check(PyObject *p)
Return true if *p* is a :class:`frozenset` object or an instance of a
subtype.
.. versionadded:: 2.6
.. c:function:: int PyAnySet_Check(PyObject *p)
Return true if *p* is a :class:`set` object, a :class:`frozenset` object, or an
instance of a subtype.
.. c:function:: int PyAnySet_CheckExact(PyObject *p)
Return true if *p* is a :class:`set` object or a :class:`frozenset` object but
not an instance of a subtype.
.. c:function:: int PyFrozenSet_CheckExact(PyObject *p)
Return true if *p* is a :class:`frozenset` object but not an instance of a
subtype.
.. c:function:: PyObject* PySet_New(PyObject *iterable)
Return a new :class:`set` containing objects returned by the *iterable*. The
*iterable* may be *NULL* to create a new empty set. Return the new set on
success or *NULL* on failure. Raise :exc:`TypeError` if *iterable* is not
actually iterable. The constructor is also useful for copying a set
(``c=set(s)``).
.. c:function:: PyObject* PyFrozenSet_New(PyObject *iterable)
Return a new :class:`frozenset` containing objects returned by the *iterable*.
The *iterable* may be *NULL* to create a new empty frozenset. Return the new
set on success or *NULL* on failure. Raise :exc:`TypeError` if *iterable* is
not actually iterable.
.. versionchanged:: 2.6
Now guaranteed to return a brand-new :class:`frozenset`. Formerly,
frozensets of zero-length were a singleton. This got in the way of
building-up new frozensets with :meth:`PySet_Add`.
The following functions and macros are available for instances of :class:`set`
or :class:`frozenset` or instances of their subtypes.
.. c:function:: Py_ssize_t PySet_Size(PyObject *anyset)
.. index:: builtin: len
Return the length of a :class:`set` or :class:`frozenset` object. Equivalent to
``len(anyset)``. Raises a :exc:`PyExc_SystemError` if *anyset* is not a
:class:`set`, :class:`frozenset`, or an instance of a subtype.
.. versionchanged:: 2.5
This function returned an :c:type:`int`. This might require changes in
your code for properly supporting 64-bit systems.
.. c:function:: Py_ssize_t PySet_GET_SIZE(PyObject *anyset)
Macro form of :c:func:`PySet_Size` without error checking.
.. c:function:: int PySet_Contains(PyObject *anyset, PyObject *key)
Return ``1`` if found, ``0`` if not found, and ``-1`` if an error is encountered. Unlike
the Python :meth:`__contains__` method, this function does not automatically
convert unhashable sets into temporary frozensets. Raise a :exc:`TypeError` if
the *key* is unhashable. Raise :exc:`PyExc_SystemError` if *anyset* is not a
:class:`set`, :class:`frozenset`, or an instance of a subtype.
.. c:function:: int PySet_Add(PyObject *set, PyObject *key)
Add *key* to a :class:`set` instance. Does not apply to :class:`frozenset`
instances. Return ``0`` on success or ``-1`` on failure. Raise a :exc:`TypeError` if
the *key* is unhashable. Raise a :exc:`MemoryError` if there is no room to grow.
Raise a :exc:`SystemError` if *set* is not an instance of :class:`set` or its
subtype.
.. versionchanged:: 2.6
Now works with instances of :class:`frozenset` or its subtypes.
Like :c:func:`PyTuple_SetItem` in that it can be used to fill-in the
values of brand new frozensets before they are exposed to other code.
The following functions are available for instances of :class:`set` or its
subtypes but not for instances of :class:`frozenset` or its subtypes.
.. c:function:: int PySet_Discard(PyObject *set, PyObject *key)
Return ``1`` if found and removed, ``0`` if not found (no action taken), and ``-1`` if an
error is encountered. Does not raise :exc:`KeyError` for missing keys. Raise a
:exc:`TypeError` if the *key* is unhashable. Unlike the Python :meth:`~set.discard`
method, this function does not automatically convert unhashable sets into
temporary frozensets. Raise :exc:`PyExc_SystemError` if *set* is not an
instance of :class:`set` or its subtype.
.. c:function:: PyObject* PySet_Pop(PyObject *set)
Return a new reference to an arbitrary object in the *set*, and removes the
object from the *set*. Return *NULL* on failure. Raise :exc:`KeyError` if the
set is empty. Raise a :exc:`SystemError` if *set* is not an instance of
:class:`set` or its subtype.
.. c:function:: int PySet_Clear(PyObject *set)
Empty an existing set of all elements.
PK %�\�3�$� � ! html/_sources/c-api/slice.rst.txtnu �[��� .. highlightlang:: c
.. _slice-objects:
Slice Objects
-------------
.. c:var:: PyTypeObject PySlice_Type
.. index:: single: SliceType (in module types)
The type object for slice objects. This is the same as ``slice`` and
``types.SliceType``.
.. c:function:: int PySlice_Check(PyObject *ob)
Return true if *ob* is a slice object; *ob* must not be *NULL*.
.. c:function:: PyObject* PySlice_New(PyObject *start, PyObject *stop, PyObject *step)
Return a new slice object with the given values. The *start*, *stop*, and
*step* parameters are used as the values of the slice object attributes of
the same names. Any of the values may be *NULL*, in which case the
``None`` will be used for the corresponding attribute. Return *NULL* if
the new object could not be allocated.
.. c:function:: int PySlice_GetIndices(PySliceObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step)
Retrieve the start, stop and step indices from the slice object *slice*,
assuming a sequence of length *length*. Treats indices greater than
*length* as errors.
Returns ``0`` on success and ``-1`` on error with no exception set (unless one of
the indices was not :const:`None` and failed to be converted to an integer,
in which case ``-1`` is returned with an exception set).
You probably do not want to use this function. If you want to use slice
objects in versions of Python prior to 2.3, you would probably do well to
incorporate the source of :c:func:`PySlice_GetIndicesEx`, suitably renamed,
in the source of your extension.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *length* and an
:c:type:`int *` type for *start*, *stop*, and *step*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: int PySlice_GetIndicesEx(PySliceObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step, Py_ssize_t *slicelength)
Usable replacement for :c:func:`PySlice_GetIndices`. Retrieve the start,
stop, and step indices from the slice object *slice* assuming a sequence of
length *length*, and store the length of the slice in *slicelength*. Out
of bounds indices are clipped in a manner consistent with the handling of
normal slices.
Returns ``0`` on success and ``-1`` on error with exception set.
.. versionadded:: 2.3
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *length* and an
:c:type:`int *` type for *start*, *stop*, *step*, and *slicelength*. This
might require changes in your code for properly supporting 64-bit
systems.
Ellipsis Object
---------------
.. c:var:: PyObject *Py_Ellipsis
The Python ``Ellipsis`` object. This object has no methods. It needs to be
treated just like any other object with respect to reference counts. Like
:c:data:`Py_None` it is a singleton object.
PK %�\Qē'>< >< " html/_sources/c-api/string.rst.txtnu �[��� .. highlightlang:: c
.. _stringobjects:
String/Bytes Objects
--------------------
These functions raise :exc:`TypeError` when expecting a string parameter and are
called with a non-string parameter.
.. note::
These functions have been renamed to PyBytes_* in Python 3.x. Unless
otherwise noted, the PyBytes functions available in 3.x are aliased to their
PyString_* equivalents to help porting.
.. index:: object: string
.. c:type:: PyStringObject
This subtype of :c:type:`PyObject` represents a Python string object.
.. c:var:: PyTypeObject PyString_Type
.. index:: single: StringType (in module types)
This instance of :c:type:`PyTypeObject` represents the Python string type; it is
the same object as ``str`` and ``types.StringType`` in the Python layer. .
.. c:function:: int PyString_Check(PyObject *o)
Return true if the object *o* is a string object or an instance of a subtype of
the string type.
.. versionchanged:: 2.2
Allowed subtypes to be accepted.
.. c:function:: int PyString_CheckExact(PyObject *o)
Return true if the object *o* is a string object, but not an instance of a
subtype of the string type.
.. versionadded:: 2.2
.. c:function:: PyObject* PyString_FromString(const char *v)
Return a new string object with a copy of the string *v* as value on success,
and *NULL* on failure. The parameter *v* must not be *NULL*; it will not be
checked.
.. c:function:: PyObject* PyString_FromStringAndSize(const char *v, Py_ssize_t len)
Return a new string object with a copy of the string *v* as value and length
*len* on success, and *NULL* on failure. If *v* is *NULL*, the contents of the
string are uninitialized.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *len*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyString_FromFormat(const char *format, ...)
Take a C :c:func:`printf`\ -style *format* string and a variable number of
arguments, calculate the size of the resulting Python string and return a string
with the values formatted into it. The variable arguments must be C types and
must correspond exactly to the format characters in the *format* string. The
following format characters are allowed:
.. % This should be exactly the same as the table in PyErr_Format.
.. % One should just refer to the other.
.. % The descriptions for %zd and %zu are wrong, but the truth is complicated
.. % because not all compilers support the %z width modifier -- we fake it
.. % when necessary via interpolating PY_FORMAT_SIZE_T.
.. % Similar comments apply to the %ll width modifier and
.. % PY_FORMAT_LONG_LONG.
.. % %u, %lu, %zu should have "new in Python 2.5" blurbs.
+-------------------+---------------+--------------------------------+
| Format Characters | Type | Comment |
+===================+===============+================================+
| :attr:`%%` | *n/a* | The literal % character. |
+-------------------+---------------+--------------------------------+
| :attr:`%c` | int | A single character, |
| | | represented as a C int. |
+-------------------+---------------+--------------------------------+
| :attr:`%d` | int | Exactly equivalent to |
| | | ``printf("%d")``. |
+-------------------+---------------+--------------------------------+
| :attr:`%u` | unsigned int | Exactly equivalent to |
| | | ``printf("%u")``. |
+-------------------+---------------+--------------------------------+
| :attr:`%ld` | long | Exactly equivalent to |
| | | ``printf("%ld")``. |
+-------------------+---------------+--------------------------------+
| :attr:`%lu` | unsigned long | Exactly equivalent to |
| | | ``printf("%lu")``. |
+-------------------+---------------+--------------------------------+
| :attr:`%lld` | long long | Exactly equivalent to |
| | | ``printf("%lld")``. |
+-------------------+---------------+--------------------------------+
| :attr:`%llu` | unsigned | Exactly equivalent to |
| | long long | ``printf("%llu")``. |
+-------------------+---------------+--------------------------------+
| :attr:`%zd` | Py_ssize_t | Exactly equivalent to |
| | | ``printf("%zd")``. |
+-------------------+---------------+--------------------------------+
| :attr:`%zu` | size_t | Exactly equivalent to |
| | | ``printf("%zu")``. |
+-------------------+---------------+--------------------------------+
| :attr:`%i` | int | Exactly equivalent to |
| | | ``printf("%i")``. |
+-------------------+---------------+--------------------------------+
| :attr:`%x` | int | Exactly equivalent to |
| | | ``printf("%x")``. |
+-------------------+---------------+--------------------------------+
| :attr:`%s` | char\* | A null-terminated C character |
| | | array. |
+-------------------+---------------+--------------------------------+
| :attr:`%p` | void\* | The hex representation of a C |
| | | pointer. Mostly equivalent to |
| | | ``printf("%p")`` except that |
| | | it is guaranteed to start with |
| | | the literal ``0x`` regardless |
| | | of what the platform's |
| | | ``printf`` yields. |
+-------------------+---------------+--------------------------------+
An unrecognized format character causes all the rest of the format string to be
copied as-is to the result string, and any extra arguments discarded.
.. note::
The `"%lld"` and `"%llu"` format specifiers are only available
when :const:`HAVE_LONG_LONG` is defined.
.. versionchanged:: 2.7
Support for `"%lld"` and `"%llu"` added.
.. c:function:: PyObject* PyString_FromFormatV(const char *format, va_list vargs)
Identical to :c:func:`PyString_FromFormat` except that it takes exactly two
arguments.
.. c:function:: Py_ssize_t PyString_Size(PyObject *string)
Return the length of the string in string object *string*.
.. versionchanged:: 2.5
This function returned an :c:type:`int` type. This might require changes
in your code for properly supporting 64-bit systems.
.. c:function:: Py_ssize_t PyString_GET_SIZE(PyObject *string)
Macro form of :c:func:`PyString_Size` but without error checking.
.. versionchanged:: 2.5
This macro returned an :c:type:`int` type. This might require changes in
your code for properly supporting 64-bit systems.
.. c:function:: char* PyString_AsString(PyObject *string)
Return a NUL-terminated representation of the contents of *string*. The pointer
refers to the internal buffer of *string*, not a copy. The data must not be
modified in any way, unless the string was just created using
``PyString_FromStringAndSize(NULL, size)``. It must not be deallocated. If
*string* is a Unicode object, this function computes the default encoding of
*string* and operates on that. If *string* is not a string object at all,
:c:func:`PyString_AsString` returns *NULL* and raises :exc:`TypeError`.
.. c:function:: char* PyString_AS_STRING(PyObject *string)
Macro form of :c:func:`PyString_AsString` but without error checking. Only
string objects are supported; no Unicode objects should be passed.
.. c:function:: int PyString_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)
Return a NUL-terminated representation of the contents of the object *obj*
through the output variables *buffer* and *length*.
The function accepts both string and Unicode objects as input. For Unicode
objects it returns the default encoded version of the object. If *length* is
*NULL*, the resulting buffer may not contain NUL characters; if it does, the
function returns ``-1`` and a :exc:`TypeError` is raised.
The buffer refers to an internal string buffer of *obj*, not a copy. The data
must not be modified in any way, unless the string was just created using
``PyString_FromStringAndSize(NULL, size)``. It must not be deallocated. If
*string* is a Unicode object, this function computes the default encoding of
*string* and operates on that. If *string* is not a string object at all,
:c:func:`PyString_AsStringAndSize` returns ``-1`` and raises :exc:`TypeError`.
.. versionchanged:: 2.5
This function used an :c:type:`int *` type for *length*. This might
require changes in your code for properly supporting 64-bit systems.
.. c:function:: void PyString_Concat(PyObject **string, PyObject *newpart)
Create a new string object in *\*string* containing the contents of *newpart*
appended to *string*; the caller will own the new reference. The reference to
the old value of *string* will be stolen. If the new string cannot be created,
the old reference to *string* will still be discarded and the value of
*\*string* will be set to *NULL*; the appropriate exception will be set.
.. c:function:: void PyString_ConcatAndDel(PyObject **string, PyObject *newpart)
Create a new string object in *\*string* containing the contents of *newpart*
appended to *string*. This version decrements the reference count of *newpart*.
.. c:function:: int _PyString_Resize(PyObject **string, Py_ssize_t newsize)
A way to resize a string object even though it is "immutable". Only use this to
build up a brand new string object; don't use this if the string may already be
known in other parts of the code. It is an error to call this function if the
refcount on the input string object is not one. Pass the address of an existing
string object as an lvalue (it may be written into), and the new size desired.
On success, *\*string* holds the resized string object and ``0`` is returned;
the address in *\*string* may differ from its input value. If the reallocation
fails, the original string object at *\*string* is deallocated, *\*string* is
set to *NULL*, a memory exception is set, and ``-1`` is returned.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *newsize*. This might
require changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyString_Format(PyObject *format, PyObject *args)
Return a new string object from *format* and *args*. Analogous to ``format %
args``. The *args* argument must be a tuple or dict.
.. c:function:: void PyString_InternInPlace(PyObject **string)
Intern the argument *\*string* in place. The argument must be the address of a
pointer variable pointing to a Python string object. If there is an existing
interned string that is the same as *\*string*, it sets *\*string* to it
(decrementing the reference count of the old string object and incrementing the
reference count of the interned string object), otherwise it leaves *\*string*
alone and interns it (incrementing its reference count). (Clarification: even
though there is a lot of talk about reference counts, think of this function as
reference-count-neutral; you own the object after the call if and only if you
owned it before the call.)
.. note::
This function is not available in 3.x and does not have a PyBytes alias.
.. c:function:: PyObject* PyString_InternFromString(const char *v)
A combination of :c:func:`PyString_FromString` and
:c:func:`PyString_InternInPlace`, returning either a new string object that has
been interned, or a new ("owned") reference to an earlier interned string object
with the same value.
.. note::
This function is not available in 3.x and does not have a PyBytes alias.
.. c:function:: PyObject* PyString_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)
Create an object by decoding *size* bytes of the encoded buffer *s* using the
codec registered for *encoding*. *encoding* and *errors* have the same meaning
as the parameters of the same name in the :func:`unicode` built-in function.
The codec to be used is looked up using the Python codec registry. Return
*NULL* if an exception was raised by the codec.
.. note::
This function is not available in 3.x and does not have a PyBytes alias.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyString_AsDecodedObject(PyObject *str, const char *encoding, const char *errors)
Decode a string object by passing it to the codec registered for *encoding* and
return the result as Python object. *encoding* and *errors* have the same
meaning as the parameters of the same name in the string :meth:`encode` method.
The codec to be used is looked up using the Python codec registry. Return *NULL*
if an exception was raised by the codec.
.. note::
This function is not available in 3.x and does not have a PyBytes alias.
.. c:function:: PyObject* PyString_Encode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)
Encode the :c:type:`char` buffer of the given size by passing it to the codec
registered for *encoding* and return a Python object. *encoding* and *errors*
have the same meaning as the parameters of the same name in the string
:meth:`encode` method. The codec to be used is looked up using the Python codec
registry. Return *NULL* if an exception was raised by the codec.
.. note::
This function is not available in 3.x and does not have a PyBytes alias.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyString_AsEncodedObject(PyObject *str, const char *encoding, const char *errors)
Encode a string object using the codec registered for *encoding* and return the
result as Python object. *encoding* and *errors* have the same meaning as the
parameters of the same name in the string :meth:`encode` method. The codec to be
used is looked up using the Python codec registry. Return *NULL* if an exception
was raised by the codec.
.. note::
This function is not available in 3.x and does not have a PyBytes alias.
PK %�\����v: v: & html/_sources/c-api/structures.rst.txtnu �[��� .. highlightlang:: c
.. _common-structs:
Common Object Structures
========================
There are a large number of structures which are used in the definition of
object types for Python. This section describes these structures and how they
are used.
All Python objects ultimately share a small number of fields at the beginning
of the object's representation in memory. These are represented by the
:c:type:`PyObject` and :c:type:`PyVarObject` types, which are defined, in turn,
by the expansions of some macros also used, whether directly or indirectly, in
the definition of all other Python objects.
.. c:type:: PyObject
All object types are extensions of this type. This is a type which
contains the information Python needs to treat a pointer to an object as an
object. In a normal "release" build, it contains only the object's
reference count and a pointer to the corresponding type object. It
corresponds to the fields defined by the expansion of the ``PyObject_HEAD``
macro.
.. c:type:: PyVarObject
This is an extension of :c:type:`PyObject` that adds the :attr:`ob_size`
field. This is only used for objects that have some notion of *length*.
This type does not often appear in the Python/C API. It corresponds to the
fields defined by the expansion of the ``PyObject_VAR_HEAD`` macro.
These macros are used in the definition of :c:type:`PyObject` and
:c:type:`PyVarObject`:
.. c:macro:: PyObject_HEAD
This is a macro which expands to the declarations of the fields of the
:c:type:`PyObject` type; it is used when declaring new types which represent
objects without a varying length. The specific fields it expands to depend
on the definition of :c:macro:`Py_TRACE_REFS`. By default, that macro is
not defined, and :c:macro:`PyObject_HEAD` expands to::
Py_ssize_t ob_refcnt;
PyTypeObject *ob_type;
When :c:macro:`Py_TRACE_REFS` is defined, it expands to::
PyObject *_ob_next, *_ob_prev;
Py_ssize_t ob_refcnt;
PyTypeObject *ob_type;
.. c:macro:: PyObject_VAR_HEAD
This is a macro which expands to the declarations of the fields of the
:c:type:`PyVarObject` type; it is used when declaring new types which
represent objects with a length that varies from instance to instance.
This macro always expands to::
PyObject_HEAD
Py_ssize_t ob_size;
Note that :c:macro:`PyObject_HEAD` is part of the expansion, and that its own
expansion varies depending on the definition of :c:macro:`Py_TRACE_REFS`.
.. c:macro:: Py_TYPE(o)
This macro is used to access the :attr:`ob_type` member of a Python object.
It expands to::
(((PyObject*)(o))->ob_type)
.. versionadded:: 2.6
.. c:macro:: Py_REFCNT(o)
This macro is used to access the :attr:`ob_refcnt` member of a Python
object.
It expands to::
(((PyObject*)(o))->ob_refcnt)
.. versionadded:: 2.6
.. c:macro:: Py_SIZE(o)
This macro is used to access the :attr:`ob_size` member of a Python object.
It expands to::
(((PyVarObject*)(o))->ob_size)
.. versionadded:: 2.6
.. c:macro:: PyObject_HEAD_INIT(type)
This is a macro which expands to initialization values for a new
:c:type:`PyObject` type. This macro expands to::
_PyObject_EXTRA_INIT
1, type,
.. c:macro:: PyVarObject_HEAD_INIT(type, size)
This is a macro which expands to initialization values for a new
:c:type:`PyVarObject` type, including the :attr:`ob_size` field.
This macro expands to::
_PyObject_EXTRA_INIT
1, type, size,
.. c:type:: PyCFunction
Type of the functions used to implement most Python callables in C.
Functions of this type take two :c:type:`PyObject\*` parameters and return
one such value. If the return value is *NULL*, an exception shall have
been set. If not *NULL*, the return value is interpreted as the return
value of the function as exposed in Python. The function must return a new
reference.
.. c:type:: PyMethodDef
Structure used to describe a method of an extension type. This structure has
four fields:
+------------------+-------------+-------------------------------+
| Field | C Type | Meaning |
+==================+=============+===============================+
| :attr:`ml_name` | char \* | name of the method |
+------------------+-------------+-------------------------------+
| :attr:`ml_meth` | PyCFunction | pointer to the C |
| | | implementation |
+------------------+-------------+-------------------------------+
| :attr:`ml_flags` | int | flag bits indicating how the |
| | | call should be constructed |
+------------------+-------------+-------------------------------+
| :attr:`ml_doc` | char \* | points to the contents of the |
| | | docstring |
+------------------+-------------+-------------------------------+
The :attr:`ml_meth` is a C function pointer. The functions may be of different
types, but they always return :c:type:`PyObject\*`. If the function is not of
the :c:type:`PyCFunction`, the compiler will require a cast in the method table.
Even though :c:type:`PyCFunction` defines the first parameter as
:c:type:`PyObject\*`, it is common that the method implementation uses the
specific C type of the *self* object.
The :attr:`ml_flags` field is a bitfield which can include the following flags.
The individual flags indicate either a calling convention or a binding
convention. Of the calling convention flags, only :const:`METH_VARARGS` and
:const:`METH_KEYWORDS` can be combined. Any of the calling convention flags
can be combined with a binding flag.
.. data:: METH_VARARGS
This is the typical calling convention, where the methods have the type
:c:type:`PyCFunction`. The function expects two :c:type:`PyObject\*` values.
The first one is the *self* object for methods; for module functions, it is
the module object. The second parameter (often called *args*) is a tuple
object representing all arguments. This parameter is typically processed
using :c:func:`PyArg_ParseTuple` or :c:func:`PyArg_UnpackTuple`.
.. data:: METH_KEYWORDS
Methods with these flags must be of type :c:type:`PyCFunctionWithKeywords`.
The function expects three parameters: *self*, *args*, and a dictionary of
all the keyword arguments. The flag is typically combined with
:const:`METH_VARARGS`, and the parameters are typically processed using
:c:func:`PyArg_ParseTupleAndKeywords`.
.. data:: METH_NOARGS
Methods without parameters don't need to check whether arguments are given if
they are listed with the :const:`METH_NOARGS` flag. They need to be of type
:c:type:`PyCFunction`. The first parameter is typically named ``self`` and
will hold a reference to the module or object instance. In all cases the
second parameter will be *NULL*.
.. data:: METH_O
Methods with a single object argument can be listed with the :const:`METH_O`
flag, instead of invoking :c:func:`PyArg_ParseTuple` with a ``"O"`` argument.
They have the type :c:type:`PyCFunction`, with the *self* parameter, and a
:c:type:`PyObject\*` parameter representing the single argument.
.. data:: METH_OLDARGS
This calling convention is deprecated. The method must be of type
:c:type:`PyCFunction`. The second argument is *NULL* if no arguments are
given, a single object if exactly one argument is given, and a tuple of
objects if more than one argument is given. There is no way for a function
using this convention to distinguish between a call with multiple arguments
and a call with a tuple as the only argument.
These two constants are not used to indicate the calling convention but the
binding when use with methods of classes. These may not be used for functions
defined for modules. At most one of these flags may be set for any given
method.
.. data:: METH_CLASS
.. index:: builtin: classmethod
The method will be passed the type object as the first parameter rather
than an instance of the type. This is used to create *class methods*,
similar to what is created when using the :func:`classmethod` built-in
function.
.. versionadded:: 2.3
.. data:: METH_STATIC
.. index:: builtin: staticmethod
The method will be passed *NULL* as the first parameter rather than an
instance of the type. This is used to create *static methods*, similar to
what is created when using the :func:`staticmethod` built-in function.
.. versionadded:: 2.3
One other constant controls whether a method is loaded in place of another
definition with the same method name.
.. data:: METH_COEXIST
The method will be loaded in place of existing definitions. Without
*METH_COEXIST*, the default is to skip repeated definitions. Since slot
wrappers are loaded before the method table, the existence of a
*sq_contains* slot, for example, would generate a wrapped method named
:meth:`__contains__` and preclude the loading of a corresponding
PyCFunction with the same name. With the flag defined, the PyCFunction
will be loaded in place of the wrapper object and will co-exist with the
slot. This is helpful because calls to PyCFunctions are optimized more
than wrapper object calls.
.. versionadded:: 2.4
.. c:type:: PyMemberDef
Structure which describes an attribute of a type which corresponds to a C
struct member. Its fields are:
+------------------+-------------+-------------------------------+
| Field | C Type | Meaning |
+==================+=============+===============================+
| :attr:`name` | char \* | name of the member |
+------------------+-------------+-------------------------------+
| :attr:`!type` | int | the type of the member in the |
| | | C struct |
+------------------+-------------+-------------------------------+
| :attr:`offset` | Py_ssize_t | the offset in bytes that the |
| | | member is located on the |
| | | type's object struct |
+------------------+-------------+-------------------------------+
| :attr:`flags` | int | flag bits indicating if the |
| | | field should be read-only or |
| | | writable |
+------------------+-------------+-------------------------------+
| :attr:`doc` | char \* | points to the contents of the |
| | | docstring |
+------------------+-------------+-------------------------------+
:attr:`!type` can be one of many ``T_`` macros corresponding to various C
types. When the member is accessed in Python, it will be converted to the
equivalent Python type.
=============== ==================
Macro name C type
=============== ==================
T_SHORT short
T_INT int
T_LONG long
T_FLOAT float
T_DOUBLE double
T_STRING char \*
T_OBJECT PyObject \*
T_OBJECT_EX PyObject \*
T_CHAR char
T_BYTE char
T_UBYTE unsigned char
T_UINT unsigned int
T_USHORT unsigned short
T_ULONG unsigned long
T_BOOL char
T_LONGLONG long long
T_ULONGLONG unsigned long long
T_PYSSIZET Py_ssize_t
=============== ==================
:c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX` differ in that
:c:macro:`T_OBJECT` returns ``None`` if the member is *NULL* and
:c:macro:`T_OBJECT_EX` raises an :exc:`AttributeError`. Try to use
:c:macro:`T_OBJECT_EX` over :c:macro:`T_OBJECT` because :c:macro:`T_OBJECT_EX`
handles use of the :keyword:`del` statement on that attribute more correctly
than :c:macro:`T_OBJECT`.
:attr:`flags` can be ``0`` for write and read access or :c:macro:`READONLY` for
read-only access. Using :c:macro:`T_STRING` for :attr:`type` implies
:c:macro:`READONLY`. Only :c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX`
members can be deleted. (They are set to *NULL*).
.. c:type:: PyGetSetDef
Structure to define property-like access for a type. See also description of
the :c:member:`PyTypeObject.tp_getset` slot.
+-------------+------------------+-----------------------------------+
| Field | C Type | Meaning |
+=============+==================+===================================+
| name | char \* | attribute name |
+-------------+------------------+-----------------------------------+
| get | getter | C Function to get the attribute |
+-------------+------------------+-----------------------------------+
| set | setter | optional C function to set or |
| | | delete the attribute, if omitted |
| | | the attribute is readonly |
+-------------+------------------+-----------------------------------+
| doc | char \* | optional docstring |
+-------------+------------------+-----------------------------------+
| closure | void \* | optional function pointer, |
| | | providing additional data for |
| | | getter and setter |
+-------------+------------------+-----------------------------------+
The ``get`` function takes one :c:type:`PyObject\*` parameter (the
instance) and a function pointer (the associated ``closure``)::
typedef PyObject *(*getter)(PyObject *, void *);
It should return a new reference on success or *NULL* with a set exception
on failure.
``set`` functions take two :c:type:`PyObject\*` parameters (the instance and
the value to be set) and a function pointer (the associated ``closure``)::
typedef int (*setter)(PyObject *, PyObject *, void *);
In case the attribute should be deleted the second parameter is *NULL*.
Should return ``0`` on success or ``-1`` with a set exception on failure.
.. c:function:: PyObject* Py_FindMethod(PyMethodDef table[], PyObject *ob, char *name)
Return a bound method object for an extension type implemented in C. This
can be useful in the implementation of a :c:member:`~PyTypeObject.tp_getattro` or
:c:member:`~PyTypeObject.tp_getattr` handler that does not use the
:c:func:`PyObject_GenericGetAttr` function.
PK %�\$�+�R R html/_sources/c-api/sys.rst.txtnu �[��� .. highlightlang:: c
.. _os:
Operating System Utilities
==========================
.. c:function:: int Py_FdIsInteractive(FILE *fp, const char *filename)
Return true (nonzero) if the standard I/O file *fp* with name *filename* is
deemed interactive. This is the case for files for which ``isatty(fileno(fp))``
is true. If the global flag :c:data:`Py_InteractiveFlag` is true, this function
also returns true if the *filename* pointer is *NULL* or if the name is equal to
one of the strings ``'<stdin>'`` or ``'???'``.
.. c:function:: void PyOS_AfterFork()
Function to update some internal state after a process fork; this should be
called in the new process if the Python interpreter will continue to be used.
If a new executable is loaded into the new process, this function does not need
to be called.
.. c:function:: int PyOS_CheckStack()
Return true when the interpreter runs out of stack space. This is a reliable
check, but is only available when :const:`USE_STACKCHECK` is defined (currently
on Windows using the Microsoft Visual C++ compiler). :const:`USE_STACKCHECK`
will be defined automatically; you should never change the definition in your
own code.
.. c:function:: PyOS_sighandler_t PyOS_getsig(int i)
Return the current signal handler for signal *i*. This is a thin wrapper around
either :c:func:`sigaction` or :c:func:`signal`. Do not call those functions
directly! :c:type:`PyOS_sighandler_t` is a typedef alias for :c:type:`void
(\*)(int)`.
.. c:function:: PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)
Set the signal handler for signal *i* to be *h*; return the old signal handler.
This is a thin wrapper around either :c:func:`sigaction` or :c:func:`signal`. Do
not call those functions directly! :c:type:`PyOS_sighandler_t` is a typedef
alias for :c:type:`void (\*)(int)`.
.. _systemfunctions:
System Functions
================
These are utility functions that make functionality from the :mod:`sys` module
accessible to C code. They all work with the current interpreter thread's
:mod:`sys` module's dict, which is contained in the internal thread state structure.
.. c:function:: PyObject *PySys_GetObject(char *name)
Return the object *name* from the :mod:`sys` module or *NULL* if it does
not exist, without setting an exception.
.. c:function:: FILE *PySys_GetFile(char *name, FILE *def)
Return the :c:type:`FILE*` associated with the object *name* in the
:mod:`sys` module, or *def* if *name* is not in the module or is not associated
with a :c:type:`FILE*`.
.. c:function:: int PySys_SetObject(char *name, PyObject *v)
Set *name* in the :mod:`sys` module to *v* unless *v* is *NULL*, in which
case *name* is deleted from the sys module. Returns ``0`` on success, ``-1``
on error.
.. c:function:: void PySys_ResetWarnOptions()
Reset :data:`sys.warnoptions` to an empty list.
.. c:function:: void PySys_AddWarnOption(char *s)
Append *s* to :data:`sys.warnoptions`.
.. c:function:: void PySys_SetPath(char *path)
Set :data:`sys.path` to a list object of paths found in *path* which should
be a list of paths separated with the platform's search path delimiter
(``:`` on Unix, ``;`` on Windows).
.. c:function:: void PySys_WriteStdout(const char *format, ...)
Write the output string described by *format* to :data:`sys.stdout`. No
exceptions are raised, even if truncation occurs (see below).
*format* should limit the total size of the formatted output string to
1000 bytes or less -- after 1000 bytes, the output string is truncated.
In particular, this means that no unrestricted "%s" formats should occur;
these should be limited using "%.<N>s" where <N> is a decimal number
calculated so that <N> plus the maximum size of other formatted text does not
exceed 1000 bytes. Also watch out for "%f", which can print hundreds of
digits for very large numbers.
If a problem occurs, or :data:`sys.stdout` is unset, the formatted message
is written to the real (C level) *stdout*.
.. c:function:: void PySys_WriteStderr(const char *format, ...)
As above, but write to :data:`sys.stderr` or *stderr* instead.
.. _processcontrol:
Process Control
===============
.. c:function:: void Py_FatalError(const char *message)
.. index:: single: abort()
Print a fatal error message and kill the process. No cleanup is performed.
This function should only be invoked when a condition is detected that would
make it dangerous to continue using the Python interpreter; e.g., when the
object administration appears to be corrupted. On Unix, the standard C library
function :c:func:`abort` is called which will attempt to produce a :file:`core`
file.
.. c:function:: void Py_Exit(int status)
.. index::
single: Py_Finalize()
single: exit()
Exit the current process. This calls :c:func:`Py_Finalize` and then calls the
standard C library function ``exit(status)``.
.. c:function:: int Py_AtExit(void (*func) ())
.. index::
single: Py_Finalize()
single: cleanup functions
Register a cleanup function to be called by :c:func:`Py_Finalize`. The cleanup
function will be called with no arguments and should return no value. At most
32 cleanup functions can be registered. When the registration is successful,
:c:func:`Py_AtExit` returns ``0``; on failure, it returns ``-1``. The cleanup
function registered last is called first. Each cleanup function will be called
at most once. Since Python's internal finalization will have completed before
the cleanup function, no Python APIs should be called by *func*.
PK %�\Fm�hs s ! html/_sources/c-api/tuple.rst.txtnu �[��� .. highlightlang:: c
.. _tupleobjects:
Tuple Objects
-------------
.. index:: object: tuple
.. c:type:: PyTupleObject
This subtype of :c:type:`PyObject` represents a Python tuple object.
.. c:var:: PyTypeObject PyTuple_Type
.. index:: single: TupleType (in module types)
This instance of :c:type:`PyTypeObject` represents the Python tuple type; it is
the same object as ``tuple`` and ``types.TupleType`` in the Python layer..
.. c:function:: int PyTuple_Check(PyObject *p)
Return true if *p* is a tuple object or an instance of a subtype of the tuple
type.
.. versionchanged:: 2.2
Allowed subtypes to be accepted.
.. c:function:: int PyTuple_CheckExact(PyObject *p)
Return true if *p* is a tuple object, but not an instance of a subtype of the
tuple type.
.. versionadded:: 2.2
.. c:function:: PyObject* PyTuple_New(Py_ssize_t len)
Return a new tuple object of size *len*, or *NULL* on failure.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *len*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyTuple_Pack(Py_ssize_t n, ...)
Return a new tuple object of size *n*, or *NULL* on failure. The tuple values
are initialized to the subsequent *n* C arguments pointing to Python objects.
``PyTuple_Pack(2, a, b)`` is equivalent to ``Py_BuildValue("(OO)", a, b)``.
.. versionadded:: 2.4
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *n*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: Py_ssize_t PyTuple_Size(PyObject *p)
Take a pointer to a tuple object, and return the size of that tuple.
.. versionchanged:: 2.5
This function returned an :c:type:`int` type. This might require changes
in your code for properly supporting 64-bit systems.
.. c:function:: Py_ssize_t PyTuple_GET_SIZE(PyObject *p)
Return the size of the tuple *p*, which must be non-*NULL* and point to a tuple;
no error checking is performed.
.. versionchanged:: 2.5
This function returned an :c:type:`int` type. This might require changes
in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyTuple_GetItem(PyObject *p, Py_ssize_t pos)
Return the object at position *pos* in the tuple pointed to by *p*. If *pos* is
out of bounds, return *NULL* and sets an :exc:`IndexError` exception.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *pos*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)
Like :c:func:`PyTuple_GetItem`, but does no checking of its arguments.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *pos*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)
Take a slice of the tuple pointed to by *p* from *low* to *high* and return it
as a new tuple.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *low* and *high*. This might
require changes in your code for properly supporting 64-bit systems.
.. c:function:: int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)
Insert a reference to object *o* at position *pos* of the tuple pointed to by
*p*. Return ``0`` on success.
.. note::
This function "steals" a reference to *o*.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *pos*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o)
Like :c:func:`PyTuple_SetItem`, but does no error checking, and should *only* be
used to fill in brand new tuples.
.. note::
This function "steals" a reference to *o*.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *pos*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize)
Can be used to resize a tuple. *newsize* will be the new length of the tuple.
Because tuples are *supposed* to be immutable, this should only be used if there
is only one reference to the object. Do *not* use this if the tuple may already
be known to some other part of the code. The tuple will always grow or shrink
at the end. Think of this as destroying the old tuple and creating a new one,
only more efficiently. Returns ``0`` on success. Client code should never
assume that the resulting value of ``*p`` will be the same as before calling
this function. If the object referenced by ``*p`` is replaced, the original
``*p`` is destroyed. On failure, returns ``-1`` and sets ``*p`` to *NULL*, and
raises :exc:`MemoryError` or :exc:`SystemError`.
.. versionchanged:: 2.2
Removed unused third parameter, *last_is_sticky*.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *newsize*. This might
require changes in your code for properly supporting 64-bit systems.
.. c:function:: int PyTuple_ClearFreeList()
Clear the free list. Return the total number of freed items.
.. versionadded:: 2.6
PK %�\>d5��
�
html/_sources/c-api/type.rst.txtnu �[��� .. highlightlang:: c
.. _typeobjects:
Type Objects
------------
.. index:: object: type
.. c:type:: PyTypeObject
The C structure of the objects used to describe built-in types.
.. c:var:: PyObject* PyType_Type
.. index:: single: TypeType (in module types)
This is the type object for type objects; it is the same object as ``type`` and
``types.TypeType`` in the Python layer.
.. c:function:: int PyType_Check(PyObject *o)
Return true if the object *o* is a type object, including instances of types
derived from the standard type object. Return false in all other cases.
.. c:function:: int PyType_CheckExact(PyObject *o)
Return true if the object *o* is a type object, but not a subtype of the
standard type object. Return false in all other cases.
.. versionadded:: 2.2
.. c:function:: unsigned int PyType_ClearCache()
Clear the internal lookup cache. Return the current version tag.
.. versionadded:: 2.6
.. c:function:: void PyType_Modified(PyTypeObject *type)
Invalidate the internal lookup cache for the type and all of its
subtypes. This function must be called after any manual
modification of the attributes or base classes of the type.
.. versionadded:: 2.6
.. c:function:: int PyType_HasFeature(PyObject *o, int feature)
Return true if the type object *o* sets the feature *feature*. Type features
are denoted by single bit flags.
.. c:function:: int PyType_IS_GC(PyObject *o)
Return true if the type object includes support for the cycle detector; this
tests the type flag :const:`Py_TPFLAGS_HAVE_GC`.
.. versionadded:: 2.0
.. c:function:: int PyType_IsSubtype(PyTypeObject *a, PyTypeObject *b)
Return true if *a* is a subtype of *b*.
.. versionadded:: 2.2
This function only checks for actual subtypes, which means that
:meth:`~class.__subclasscheck__` is not called on *b*. Call
:c:func:`PyObject_IsSubclass` to do the same check that :func:`issubclass`
would do.
.. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
.. versionadded:: 2.2
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *nitems*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds)
.. versionadded:: 2.2
.. c:function:: int PyType_Ready(PyTypeObject *type)
Finalize a type object. This should be called on all type objects to finish
their initialization. This function is responsible for adding inherited slots
from a type's base class. Return ``0`` on success, or return ``-1`` and sets an
exception on error.
.. versionadded:: 2.2
PK %�\�c�(x x # html/_sources/c-api/typeobj.rst.txtnu �[��� .. highlightlang:: c
.. _type-structs:
Type Objects
============
Perhaps one of the most important structures of the Python object system is the
structure that defines a new type: the :c:type:`PyTypeObject` structure. Type
objects can be handled using any of the :c:func:`PyObject_\*` or
:c:func:`PyType_\*` functions, but do not offer much that's interesting to most
Python applications. These objects are fundamental to how objects behave, so
they are very important to the interpreter itself and to any extension module
that implements new types.
Type objects are fairly large compared to most of the standard types. The reason
for the size is that each type object stores a large number of values, mostly C
function pointers, each of which implements a small part of the type's
functionality. The fields of the type object are examined in detail in this
section. The fields will be described in the order in which they occur in the
structure.
Typedefs: unaryfunc, binaryfunc, ternaryfunc, inquiry, coercion, intargfunc,
intintargfunc, intobjargproc, intintobjargproc, objobjargproc, destructor,
freefunc, printfunc, getattrfunc, getattrofunc, setattrfunc, setattrofunc,
cmpfunc, reprfunc, hashfunc
The structure definition for :c:type:`PyTypeObject` can be found in
:file:`Include/object.h`. For convenience of reference, this repeats the
definition found there:
.. literalinclude:: ../includes/typestruct.h
The type object structure extends the :c:type:`PyVarObject` structure. The
:attr:`ob_size` field is used for dynamic types (created by :func:`type_new`,
usually called from a class statement). Note that :c:data:`PyType_Type` (the
metatype) initializes :c:member:`~PyTypeObject.tp_itemsize`, which means that its instances (i.e.
type objects) *must* have the :attr:`ob_size` field.
.. c:member:: PyObject* PyObject._ob_next
PyObject* PyObject._ob_prev
These fields are only present when the macro ``Py_TRACE_REFS`` is defined.
Their initialization to *NULL* is taken care of by the ``PyObject_HEAD_INIT``
macro. For statically allocated objects, these fields always remain *NULL*.
For dynamically allocated objects, these two fields are used to link the object
into a doubly-linked list of *all* live objects on the heap. This could be used
for various debugging purposes; currently the only use is to print the objects
that are still alive at the end of a run when the environment variable
:envvar:`PYTHONDUMPREFS` is set.
These fields are not inherited by subtypes.
.. c:member:: Py_ssize_t PyObject.ob_refcnt
This is the type object's reference count, initialized to ``1`` by the
``PyObject_HEAD_INIT`` macro. Note that for statically allocated type objects,
the type's instances (objects whose :attr:`ob_type` points back to the type) do
*not* count as references. But for dynamically allocated type objects, the
instances *do* count as references.
This field is not inherited by subtypes.
.. versionchanged:: 2.5
This field used to be an :c:type:`int` type. This might require changes
in your code for properly supporting 64-bit systems.
.. c:member:: PyTypeObject* PyObject.ob_type
This is the type's type, in other words its metatype. It is initialized by the
argument to the ``PyObject_HEAD_INIT`` macro, and its value should normally be
``&PyType_Type``. However, for dynamically loadable extension modules that must
be usable on Windows (at least), the compiler complains that this is not a valid
initializer. Therefore, the convention is to pass *NULL* to the
``PyObject_HEAD_INIT`` macro and to initialize this field explicitly at the
start of the module's initialization function, before doing anything else. This
is typically done like this::
Foo_Type.ob_type = &PyType_Type;
This should be done before any instances of the type are created.
:c:func:`PyType_Ready` checks if :attr:`ob_type` is *NULL*, and if so,
initializes it: in Python 2.2, it is set to ``&PyType_Type``; in Python 2.2.1
and later it is initialized to the :attr:`ob_type` field of the base class.
:c:func:`PyType_Ready` will not change this field if it is non-zero.
In Python 2.2, this field is not inherited by subtypes. In 2.2.1, and in 2.3
and beyond, it is inherited by subtypes.
.. c:member:: Py_ssize_t PyVarObject.ob_size
For statically allocated type objects, this should be initialized to zero. For
dynamically allocated type objects, this field has a special internal meaning.
This field is not inherited by subtypes.
.. c:member:: char* PyTypeObject.tp_name
Pointer to a NUL-terminated string containing the name of the type. For types
that are accessible as module globals, the string should be the full module
name, followed by a dot, followed by the type name; for built-in types, it
should be just the type name. If the module is a submodule of a package, the
full package name is part of the full module name. For example, a type named
:class:`T` defined in module :mod:`M` in subpackage :mod:`Q` in package :mod:`P`
should have the :c:member:`~PyTypeObject.tp_name` initializer ``"P.Q.M.T"``.
For dynamically allocated type objects, this should just be the type name, and
the module name explicitly stored in the type dict as the value for key
``'__module__'``.
For statically allocated type objects, the tp_name field should contain a dot.
Everything before the last dot is made accessible as the :attr:`__module__`
attribute, and everything after the last dot is made accessible as the
:attr:`~definition.__name__` attribute.
If no dot is present, the entire :c:member:`~PyTypeObject.tp_name` field is made accessible as the
:attr:`~definition.__name__` attribute, and the :attr:`__module__` attribute is undefined
(unless explicitly set in the dictionary, as explained above). This means your
type will be impossible to pickle. Additionally, it will not be listed in
module documentations created with pydoc.
This field is not inherited by subtypes.
.. c:member:: Py_ssize_t PyTypeObject.tp_basicsize
Py_ssize_t PyTypeObject.tp_itemsize
These fields allow calculating the size in bytes of instances of the type.
There are two kinds of types: types with fixed-length instances have a zero
:c:member:`~PyTypeObject.tp_itemsize` field, types with variable-length instances have a non-zero
:c:member:`~PyTypeObject.tp_itemsize` field. For a type with fixed-length instances, all
instances have the same size, given in :c:member:`~PyTypeObject.tp_basicsize`.
For a type with variable-length instances, the instances must have an
:attr:`ob_size` field, and the instance size is :c:member:`~PyTypeObject.tp_basicsize` plus N
times :c:member:`~PyTypeObject.tp_itemsize`, where N is the "length" of the object. The value of
N is typically stored in the instance's :attr:`ob_size` field. There are
exceptions: for example, long ints use a negative :attr:`ob_size` to indicate a
negative number, and N is ``abs(ob_size)`` there. Also, the presence of an
:attr:`ob_size` field in the instance layout doesn't mean that the instance
structure is variable-length (for example, the structure for the list type has
fixed-length instances, yet those instances have a meaningful :attr:`ob_size`
field).
The basic size includes the fields in the instance declared by the macro
:c:macro:`PyObject_HEAD` or :c:macro:`PyObject_VAR_HEAD` (whichever is used to
declare the instance struct) and this in turn includes the :attr:`_ob_prev` and
:attr:`_ob_next` fields if they are present. This means that the only correct
way to get an initializer for the :c:member:`~PyTypeObject.tp_basicsize` is to use the
``sizeof`` operator on the struct used to declare the instance layout.
The basic size does not include the GC header size (this is new in Python 2.2;
in 2.1 and 2.0, the GC header size was included in :c:member:`~PyTypeObject.tp_basicsize`).
These fields are inherited separately by subtypes. If the base type has a
non-zero :c:member:`~PyTypeObject.tp_itemsize`, it is generally not safe to set
:c:member:`~PyTypeObject.tp_itemsize` to a different non-zero value in a subtype (though this
depends on the implementation of the base type).
A note about alignment: if the variable items require a particular alignment,
this should be taken care of by the value of :c:member:`~PyTypeObject.tp_basicsize`. Example:
suppose a type implements an array of ``double``. :c:member:`~PyTypeObject.tp_itemsize` is
``sizeof(double)``. It is the programmer's responsibility that
:c:member:`~PyTypeObject.tp_basicsize` is a multiple of ``sizeof(double)`` (assuming this is the
alignment requirement for ``double``).
.. c:member:: destructor PyTypeObject.tp_dealloc
A pointer to the instance destructor function. This function must be defined
unless the type guarantees that its instances will never be deallocated (as is
the case for the singletons ``None`` and ``Ellipsis``).
The destructor function is called by the :c:func:`Py_DECREF` and
:c:func:`Py_XDECREF` macros when the new reference count is zero. At this point,
the instance is still in existence, but there are no references to it. The
destructor function should free all references which the instance owns, free all
memory buffers owned by the instance (using the freeing function corresponding
to the allocation function used to allocate the buffer), and finally (as its
last action) call the type's :c:member:`~PyTypeObject.tp_free` function. If the type is not
subtypable (doesn't have the :const:`Py_TPFLAGS_BASETYPE` flag bit set), it is
permissible to call the object deallocator directly instead of via
:c:member:`~PyTypeObject.tp_free`. The object deallocator should be the one used to allocate the
instance; this is normally :c:func:`PyObject_Del` if the instance was allocated
using :c:func:`PyObject_New` or :c:func:`PyObject_VarNew`, or
:c:func:`PyObject_GC_Del` if the instance was allocated using
:c:func:`PyObject_GC_New` or :c:func:`PyObject_GC_NewVar`.
This field is inherited by subtypes.
.. c:member:: printfunc PyTypeObject.tp_print
An optional pointer to the instance print function.
The print function is only called when the instance is printed to a *real* file;
when it is printed to a pseudo-file (like a :class:`~StringIO.StringIO` instance), the
instance's :c:member:`~PyTypeObject.tp_repr` or :c:member:`~PyTypeObject.tp_str` function is called to convert it to
a string. These are also called when the type's :c:member:`~PyTypeObject.tp_print` field is
*NULL*. A type should never implement :c:member:`~PyTypeObject.tp_print` in a way that produces
different output than :c:member:`~PyTypeObject.tp_repr` or :c:member:`~PyTypeObject.tp_str` would.
The print function is called with the same signature as :c:func:`PyObject_Print`:
``int tp_print(PyObject *self, FILE *file, int flags)``. The *self* argument is
the instance to be printed. The *file* argument is the stdio file to which it
is to be printed. The *flags* argument is composed of flag bits. The only flag
bit currently defined is :const:`Py_PRINT_RAW`. When the :const:`Py_PRINT_RAW`
flag bit is set, the instance should be printed the same way as :c:member:`~PyTypeObject.tp_str`
would format it; when the :const:`Py_PRINT_RAW` flag bit is clear, the instance
should be printed the same was as :c:member:`~PyTypeObject.tp_repr` would format it. It should
return ``-1`` and set an exception condition when an error occurred during the
comparison.
It is possible that the :c:member:`~PyTypeObject.tp_print` field will be deprecated. In any case,
it is recommended not to define :c:member:`~PyTypeObject.tp_print`, but instead to rely on
:c:member:`~PyTypeObject.tp_repr` and :c:member:`~PyTypeObject.tp_str` for printing.
This field is inherited by subtypes.
.. c:member:: getattrfunc PyTypeObject.tp_getattr
An optional pointer to the get-attribute-string function.
This field is deprecated. When it is defined, it should point to a function
that acts the same as the :c:member:`~PyTypeObject.tp_getattro` function, but taking a C string
instead of a Python string object to give the attribute name. The signature is ::
PyObject * tp_getattr(PyObject *o, char *attr_name);
This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_getattro`: a subtype
inherits both :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject.tp_getattro` from its base type when
the subtype's :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject.tp_getattro` are both *NULL*.
.. c:member:: setattrfunc PyTypeObject.tp_setattr
An optional pointer to the function for setting and deleting attributes.
This field is deprecated. When it is defined, it should point to a function
that acts the same as the :c:member:`~PyTypeObject.tp_setattro` function, but taking a C string
instead of a Python string object to give the attribute name. The signature is ::
PyObject * tp_setattr(PyObject *o, char *attr_name, PyObject *v);
The *v* argument is set to *NULL* to delete the attribute.
This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_setattro`: a subtype
inherits both :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` from its base type when
the subtype's :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` are both *NULL*.
.. c:member:: cmpfunc PyTypeObject.tp_compare
An optional pointer to the three-way comparison function.
The signature is the same as for :c:func:`PyObject_Compare`. The function should
return ``1`` if *self* greater than *other*, ``0`` if *self* is equal to
*other*, and ``-1`` if *self* less than *other*. It should return ``-1`` and
set an exception condition when an error occurred during the comparison.
This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_richcompare` and
:c:member:`~PyTypeObject.tp_hash`: a subtypes inherits all three of :c:member:`~PyTypeObject.tp_compare`,
:c:member:`~PyTypeObject.tp_richcompare`, and :c:member:`~PyTypeObject.tp_hash` when the subtype's
:c:member:`~PyTypeObject.tp_compare`, :c:member:`~PyTypeObject.tp_richcompare`, and :c:member:`~PyTypeObject.tp_hash` are all *NULL*.
.. c:member:: reprfunc PyTypeObject.tp_repr
.. index:: builtin: repr
An optional pointer to a function that implements the built-in function
:func:`repr`.
The signature is the same as for :c:func:`PyObject_Repr`; it must return a string
or a Unicode object. Ideally, this function should return a string that, when
passed to :func:`eval`, given a suitable environment, returns an object with the
same value. If this is not feasible, it should return a string starting with
``'<'`` and ending with ``'>'`` from which both the type and the value of the
object can be deduced.
When this field is not set, a string of the form ``<%s object at %p>`` is
returned, where ``%s`` is replaced by the type name, and ``%p`` by the object's
memory address.
This field is inherited by subtypes.
.. c:member:: PyNumberMethods* tp_as_number
Pointer to an additional structure that contains fields relevant only to
objects which implement the number protocol. These fields are documented in
:ref:`number-structs`.
The :c:member:`~PyTypeObject.tp_as_number` field is not inherited, but the contained fields are
inherited individually.
.. c:member:: PySequenceMethods* tp_as_sequence
Pointer to an additional structure that contains fields relevant only to
objects which implement the sequence protocol. These fields are documented
in :ref:`sequence-structs`.
The :c:member:`~PyTypeObject.tp_as_sequence` field is not inherited, but the contained fields
are inherited individually.
.. c:member:: PyMappingMethods* tp_as_mapping
Pointer to an additional structure that contains fields relevant only to
objects which implement the mapping protocol. These fields are documented in
:ref:`mapping-structs`.
The :c:member:`~PyTypeObject.tp_as_mapping` field is not inherited, but the contained fields
are inherited individually.
.. c:member:: hashfunc PyTypeObject.tp_hash
.. index:: builtin: hash
An optional pointer to a function that implements the built-in function
:func:`hash`.
The signature is the same as for :c:func:`PyObject_Hash`; it must return a C
long. The value ``-1`` should not be returned as a normal return value; when an
error occurs during the computation of the hash value, the function should set
an exception and return ``-1``.
This field can be set explicitly to :c:func:`PyObject_HashNotImplemented` to
block inheritance of the hash method from a parent type. This is interpreted
as the equivalent of ``__hash__ = None`` at the Python level, causing
``isinstance(o, collections.Hashable)`` to correctly return ``False``. Note
that the converse is also true - setting ``__hash__ = None`` on a class at
the Python level will result in the ``tp_hash`` slot being set to
:c:func:`PyObject_HashNotImplemented`.
When this field is not set, two possibilities exist: if the :c:member:`~PyTypeObject.tp_compare`
and :c:member:`~PyTypeObject.tp_richcompare` fields are both *NULL*, a default hash value based on
the object's address is returned; otherwise, a :exc:`TypeError` is raised.
This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_richcompare` and
:c:member:`~PyTypeObject.tp_compare`: a subtypes inherits all three of :c:member:`~PyTypeObject.tp_compare`,
:c:member:`~PyTypeObject.tp_richcompare`, and :c:member:`~PyTypeObject.tp_hash`, when the subtype's
:c:member:`~PyTypeObject.tp_compare`, :c:member:`~PyTypeObject.tp_richcompare` and :c:member:`~PyTypeObject.tp_hash` are all *NULL*.
.. c:member:: ternaryfunc PyTypeObject.tp_call
An optional pointer to a function that implements calling the object. This
should be *NULL* if the object is not callable. The signature is the same as
for :c:func:`PyObject_Call`.
This field is inherited by subtypes.
.. c:member:: reprfunc PyTypeObject.tp_str
An optional pointer to a function that implements the built-in operation
:func:`str`. (Note that :class:`str` is a type now, and :func:`str` calls the
constructor for that type. This constructor calls :c:func:`PyObject_Str` to do
the actual work, and :c:func:`PyObject_Str` will call this handler.)
The signature is the same as for :c:func:`PyObject_Str`; it must return a string
or a Unicode object. This function should return a "friendly" string
representation of the object, as this is the representation that will be used by
the print statement.
When this field is not set, :c:func:`PyObject_Repr` is called to return a string
representation.
This field is inherited by subtypes.
.. c:member:: getattrofunc PyTypeObject.tp_getattro
An optional pointer to the get-attribute function.
The signature is the same as for :c:func:`PyObject_GetAttr`. It is usually
convenient to set this field to :c:func:`PyObject_GenericGetAttr`, which
implements the normal way of looking for object attributes.
This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_getattr`: a subtype
inherits both :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject.tp_getattro` from its base type when
the subtype's :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject.tp_getattro` are both *NULL*.
.. c:member:: setattrofunc PyTypeObject.tp_setattro
An optional pointer to the function for setting and deleting attributes.
The signature is the same as for :c:func:`PyObject_SetAttr`, but setting
*v* to *NULL* to delete an attribute must be supported. It is usually
convenient to set this field to :c:func:`PyObject_GenericSetAttr`, which
implements the normal way of setting object attributes.
This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_setattr`: a subtype
inherits both :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` from its base type when
the subtype's :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` are both *NULL*.
.. c:member:: PyBufferProcs* PyTypeObject.tp_as_buffer
Pointer to an additional structure that contains fields relevant only to objects
which implement the buffer interface. These fields are documented in
:ref:`buffer-structs`.
The :c:member:`~PyTypeObject.tp_as_buffer` field is not inherited, but the contained fields are
inherited individually.
.. c:member:: long PyTypeObject.tp_flags
This field is a bit mask of various flags. Some flags indicate variant
semantics for certain situations; others are used to indicate that certain
fields in the type object (or in the extension structures referenced via
:c:member:`~PyTypeObject.tp_as_number`, :c:member:`~PyTypeObject.tp_as_sequence`, :c:member:`~PyTypeObject.tp_as_mapping`, and
:c:member:`~PyTypeObject.tp_as_buffer`) that were historically not always present are valid; if
such a flag bit is clear, the type fields it guards must not be accessed and
must be considered to have a zero or *NULL* value instead.
Inheritance of this field is complicated. Most flag bits are inherited
individually, i.e. if the base type has a flag bit set, the subtype inherits
this flag bit. The flag bits that pertain to extension structures are strictly
inherited if the extension structure is inherited, i.e. the base type's value of
the flag bit is copied into the subtype together with a pointer to the extension
structure. The :const:`Py_TPFLAGS_HAVE_GC` flag bit is inherited together with
the :c:member:`~PyTypeObject.tp_traverse` and :c:member:`~PyTypeObject.tp_clear` fields, i.e. if the
:const:`Py_TPFLAGS_HAVE_GC` flag bit is clear in the subtype and the
:c:member:`~PyTypeObject.tp_traverse` and :c:member:`~PyTypeObject.tp_clear` fields in the subtype exist (as
indicated by the :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag bit) and have *NULL*
values.
The following bit masks are currently defined; these can be ORed together using
the ``|`` operator to form the value of the :c:member:`~PyTypeObject.tp_flags` field. The macro
:c:func:`PyType_HasFeature` takes a type and a flags value, *tp* and *f*, and
checks whether ``tp->tp_flags & f`` is non-zero.
.. data:: Py_TPFLAGS_HAVE_GETCHARBUFFER
If this bit is set, the :c:type:`PyBufferProcs` struct referenced by
:c:member:`~PyTypeObject.tp_as_buffer` has the :attr:`bf_getcharbuffer` field.
.. data:: Py_TPFLAGS_HAVE_SEQUENCE_IN
If this bit is set, the :c:type:`PySequenceMethods` struct referenced by
:c:member:`~PyTypeObject.tp_as_sequence` has the :attr:`sq_contains` field.
.. data:: Py_TPFLAGS_GC
This bit is obsolete. The bit it used to name is no longer in use. The symbol
is now defined as zero.
.. data:: Py_TPFLAGS_HAVE_INPLACEOPS
If this bit is set, the :c:type:`PySequenceMethods` struct referenced by
:c:member:`~PyTypeObject.tp_as_sequence` and the :c:type:`PyNumberMethods` structure referenced by
:c:member:`~PyTypeObject.tp_as_number` contain the fields for in-place operators. In particular,
this means that the :c:type:`PyNumberMethods` structure has the fields
:attr:`nb_inplace_add`, :attr:`nb_inplace_subtract`,
:attr:`nb_inplace_multiply`, :attr:`nb_inplace_divide`,
:attr:`nb_inplace_remainder`, :attr:`nb_inplace_power`,
:attr:`nb_inplace_lshift`, :attr:`nb_inplace_rshift`, :attr:`nb_inplace_and`,
:attr:`nb_inplace_xor`, and :attr:`nb_inplace_or`; and the
:c:type:`PySequenceMethods` struct has the fields :attr:`sq_inplace_concat` and
:attr:`sq_inplace_repeat`.
.. data:: Py_TPFLAGS_CHECKTYPES
If this bit is set, the binary and ternary operations in the
:c:type:`PyNumberMethods` structure referenced by :c:member:`~PyTypeObject.tp_as_number` accept
arguments of arbitrary object types, and do their own type conversions if
needed. If this bit is clear, those operations require that all arguments have
the current type as their type, and the caller is supposed to perform a coercion
operation first. This applies to :attr:`nb_add`, :attr:`nb_subtract`,
:attr:`nb_multiply`, :attr:`nb_divide`, :attr:`nb_remainder`, :attr:`nb_divmod`,
:attr:`nb_power`, :attr:`nb_lshift`, :attr:`nb_rshift`, :attr:`nb_and`,
:attr:`nb_xor`, and :attr:`nb_or`.
.. data:: Py_TPFLAGS_HAVE_RICHCOMPARE
If this bit is set, the type object has the :c:member:`~PyTypeObject.tp_richcompare` field, as
well as the :c:member:`~PyTypeObject.tp_traverse` and the :c:member:`~PyTypeObject.tp_clear` fields.
.. data:: Py_TPFLAGS_HAVE_WEAKREFS
If this bit is set, the :c:member:`~PyTypeObject.tp_weaklistoffset` field is defined. Instances
of a type are weakly referenceable if the type's :c:member:`~PyTypeObject.tp_weaklistoffset` field
has a value greater than zero.
.. data:: Py_TPFLAGS_HAVE_ITER
If this bit is set, the type object has the :c:member:`~PyTypeObject.tp_iter` and
:c:member:`~PyTypeObject.tp_iternext` fields.
.. data:: Py_TPFLAGS_HAVE_CLASS
If this bit is set, the type object has several new fields defined starting in
Python 2.2: :c:member:`~PyTypeObject.tp_methods`, :c:member:`~PyTypeObject.tp_members`, :c:member:`~PyTypeObject.tp_getset`,
:c:member:`~PyTypeObject.tp_base`, :c:member:`~PyTypeObject.tp_dict`, :c:member:`~PyTypeObject.tp_descr_get`, :c:member:`~PyTypeObject.tp_descr_set`,
:c:member:`~PyTypeObject.tp_dictoffset`, :c:member:`~PyTypeObject.tp_init`, :c:member:`~PyTypeObject.tp_alloc`, :c:member:`~PyTypeObject.tp_new`,
:c:member:`~PyTypeObject.tp_free`, :c:member:`~PyTypeObject.tp_is_gc`, :c:member:`~PyTypeObject.tp_bases`, :c:member:`~PyTypeObject.tp_mro`,
:c:member:`~PyTypeObject.tp_cache`, :c:member:`~PyTypeObject.tp_subclasses`, and :c:member:`~PyTypeObject.tp_weaklist`.
.. data:: Py_TPFLAGS_HEAPTYPE
This bit is set when the type object itself is allocated on the heap. In this
case, the :attr:`ob_type` field of its instances is considered a reference to
the type, and the type object is INCREF'ed when a new instance is created, and
DECREF'ed when an instance is destroyed (this does not apply to instances of
subtypes; only the type referenced by the instance's ob_type gets INCREF'ed or
DECREF'ed).
.. data:: Py_TPFLAGS_BASETYPE
This bit is set when the type can be used as the base type of another type. If
this bit is clear, the type cannot be subtyped (similar to a "final" class in
Java).
.. data:: Py_TPFLAGS_READY
This bit is set when the type object has been fully initialized by
:c:func:`PyType_Ready`.
.. data:: Py_TPFLAGS_READYING
This bit is set while :c:func:`PyType_Ready` is in the process of initializing
the type object.
.. data:: Py_TPFLAGS_HAVE_GC
This bit is set when the object supports garbage collection. If this bit
is set, instances must be created using :c:func:`PyObject_GC_New` and
destroyed using :c:func:`PyObject_GC_Del`. More information in section
:ref:`supporting-cycle-detection`. This bit also implies that the
GC-related fields :c:member:`~PyTypeObject.tp_traverse` and :c:member:`~PyTypeObject.tp_clear` are present in
the type object; but those fields also exist when
:const:`Py_TPFLAGS_HAVE_GC` is clear but
:const:`Py_TPFLAGS_HAVE_RICHCOMPARE` is set.
.. data:: Py_TPFLAGS_DEFAULT
This is a bitmask of all the bits that pertain to the existence of certain
fields in the type object and its extension structures. Currently, it includes
the following bits: :const:`Py_TPFLAGS_HAVE_GETCHARBUFFER`,
:const:`Py_TPFLAGS_HAVE_SEQUENCE_IN`, :const:`Py_TPFLAGS_HAVE_INPLACEOPS`,
:const:`Py_TPFLAGS_HAVE_RICHCOMPARE`, :const:`Py_TPFLAGS_HAVE_WEAKREFS`,
:const:`Py_TPFLAGS_HAVE_ITER`, and :const:`Py_TPFLAGS_HAVE_CLASS`.
.. c:member:: char* PyTypeObject.tp_doc
An optional pointer to a NUL-terminated C string giving the docstring for this
type object. This is exposed as the :attr:`__doc__` attribute on the type and
instances of the type.
This field is *not* inherited by subtypes.
The following three fields only exist if the
:const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag bit is set.
.. c:member:: traverseproc PyTypeObject.tp_traverse
An optional pointer to a traversal function for the garbage collector. This is
only used if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is set. More information
about Python's garbage collection scheme can be found in section
:ref:`supporting-cycle-detection`.
The :c:member:`~PyTypeObject.tp_traverse` pointer is used by the garbage collector to detect
reference cycles. A typical implementation of a :c:member:`~PyTypeObject.tp_traverse` function
simply calls :c:func:`Py_VISIT` on each of the instance's members that are Python
objects. For example, this is function :c:func:`local_traverse` from the
:mod:`thread` extension module::
static int
local_traverse(localobject *self, visitproc visit, void *arg)
{
Py_VISIT(self->args);
Py_VISIT(self->kw);
Py_VISIT(self->dict);
return 0;
}
Note that :c:func:`Py_VISIT` is called only on those members that can participate
in reference cycles. Although there is also a ``self->key`` member, it can only
be *NULL* or a Python string and therefore cannot be part of a reference cycle.
On the other hand, even if you know a member can never be part of a cycle, as a
debugging aid you may want to visit it anyway just so the :mod:`gc` module's
:func:`~gc.get_referents` function will include it.
Note that :c:func:`Py_VISIT` requires the *visit* and *arg* parameters to
:c:func:`local_traverse` to have these specific names; don't name them just
anything.
This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_clear` and the
:const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :c:member:`~PyTypeObject.tp_traverse`, and
:c:member:`~PyTypeObject.tp_clear` are all inherited from the base type if they are all zero in
the subtype *and* the subtype has the :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag
bit set.
.. c:member:: inquiry PyTypeObject.tp_clear
An optional pointer to a clear function for the garbage collector. This is only
used if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is set.
The :c:member:`~PyTypeObject.tp_clear` member function is used to break reference cycles in cyclic
garbage detected by the garbage collector. Taken together, all :c:member:`~PyTypeObject.tp_clear`
functions in the system must combine to break all reference cycles. This is
subtle, and if in any doubt supply a :c:member:`~PyTypeObject.tp_clear` function. For example,
the tuple type does not implement a :c:member:`~PyTypeObject.tp_clear` function, because it's
possible to prove that no reference cycle can be composed entirely of tuples.
Therefore the :c:member:`~PyTypeObject.tp_clear` functions of other types must be sufficient to
break any cycle containing a tuple. This isn't immediately obvious, and there's
rarely a good reason to avoid implementing :c:member:`~PyTypeObject.tp_clear`.
Implementations of :c:member:`~PyTypeObject.tp_clear` should drop the instance's references to
those of its members that may be Python objects, and set its pointers to those
members to *NULL*, as in the following example::
static int
local_clear(localobject *self)
{
Py_CLEAR(self->key);
Py_CLEAR(self->args);
Py_CLEAR(self->kw);
Py_CLEAR(self->dict);
return 0;
}
The :c:func:`Py_CLEAR` macro should be used, because clearing references is
delicate: the reference to the contained object must not be decremented until
after the pointer to the contained object is set to *NULL*. This is because
decrementing the reference count may cause the contained object to become trash,
triggering a chain of reclamation activity that may include invoking arbitrary
Python code (due to finalizers, or weakref callbacks, associated with the
contained object). If it's possible for such code to reference *self* again,
it's important that the pointer to the contained object be *NULL* at that time,
so that *self* knows the contained object can no longer be used. The
:c:func:`Py_CLEAR` macro performs the operations in a safe order.
Because the goal of :c:member:`~PyTypeObject.tp_clear` functions is to break reference cycles,
it's not necessary to clear contained objects like Python strings or Python
integers, which can't participate in reference cycles. On the other hand, it may
be convenient to clear all contained Python objects, and write the type's
:c:member:`~PyTypeObject.tp_dealloc` function to invoke :c:member:`~PyTypeObject.tp_clear`.
More information about Python's garbage collection scheme can be found in
section :ref:`supporting-cycle-detection`.
This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_traverse` and the
:const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :c:member:`~PyTypeObject.tp_traverse`, and
:c:member:`~PyTypeObject.tp_clear` are all inherited from the base type if they are all zero in
the subtype *and* the subtype has the :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag
bit set.
.. c:member:: richcmpfunc PyTypeObject.tp_richcompare
An optional pointer to the rich comparison function, whose signature is
``PyObject *tp_richcompare(PyObject *a, PyObject *b, int op)``.
The function should return the result of the comparison (usually ``Py_True``
or ``Py_False``). If the comparison is undefined, it must return
``Py_NotImplemented``, if another error occurred it must return ``NULL`` and
set an exception condition.
.. note::
If you want to implement a type for which only a limited set of
comparisons makes sense (e.g. ``==`` and ``!=``, but not ``<`` and
friends), directly raise :exc:`TypeError` in the rich comparison function.
This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_compare` and
:c:member:`~PyTypeObject.tp_hash`: a subtype inherits all three of :c:member:`~PyTypeObject.tp_compare`,
:c:member:`~PyTypeObject.tp_richcompare`, and :c:member:`~PyTypeObject.tp_hash`, when the subtype's
:c:member:`~PyTypeObject.tp_compare`, :c:member:`~PyTypeObject.tp_richcompare`, and :c:member:`~PyTypeObject.tp_hash` are all *NULL*.
The following constants are defined to be used as the third argument for
:c:member:`~PyTypeObject.tp_richcompare` and for :c:func:`PyObject_RichCompare`:
+----------------+------------+
| Constant | Comparison |
+================+============+
| :const:`Py_LT` | ``<`` |
+----------------+------------+
| :const:`Py_LE` | ``<=`` |
+----------------+------------+
| :const:`Py_EQ` | ``==`` |
+----------------+------------+
| :const:`Py_NE` | ``!=`` |
+----------------+------------+
| :const:`Py_GT` | ``>`` |
+----------------+------------+
| :const:`Py_GE` | ``>=`` |
+----------------+------------+
The next field only exists if the :const:`Py_TPFLAGS_HAVE_WEAKREFS` flag bit is
set.
.. c:member:: long PyTypeObject.tp_weaklistoffset
If the instances of this type are weakly referenceable, this field is greater
than zero and contains the offset in the instance structure of the weak
reference list head (ignoring the GC header, if present); this offset is used by
:c:func:`PyObject_ClearWeakRefs` and the :c:func:`PyWeakref_\*` functions. The
instance structure needs to include a field of type :c:type:`PyObject\*` which is
initialized to *NULL*.
Do not confuse this field with :c:member:`~PyTypeObject.tp_weaklist`; that is the list head for
weak references to the type object itself.
This field is inherited by subtypes, but see the rules listed below. A subtype
may override this offset; this means that the subtype uses a different weak
reference list head than the base type. Since the list head is always found via
:c:member:`~PyTypeObject.tp_weaklistoffset`, this should not be a problem.
When a type defined by a class statement has no :attr:`~object.__slots__` declaration,
and none of its base types are weakly referenceable, the type is made weakly
referenceable by adding a weak reference list head slot to the instance layout
and setting the :c:member:`~PyTypeObject.tp_weaklistoffset` of that slot's offset.
When a type's :attr:`__slots__` declaration contains a slot named
:attr:`__weakref__`, that slot becomes the weak reference list head for
instances of the type, and the slot's offset is stored in the type's
:c:member:`~PyTypeObject.tp_weaklistoffset`.
When a type's :attr:`__slots__` declaration does not contain a slot named
:attr:`__weakref__`, the type inherits its :c:member:`~PyTypeObject.tp_weaklistoffset` from its
base type.
The next two fields only exist if the :const:`Py_TPFLAGS_HAVE_ITER` flag bit is
set.
.. c:member:: getiterfunc PyTypeObject.tp_iter
An optional pointer to a function that returns an iterator for the object. Its
presence normally signals that the instances of this type are iterable (although
sequences may be iterable without this function, and classic instances always
have this function, even if they don't define an :meth:`__iter__` method).
This function has the same signature as :c:func:`PyObject_GetIter`.
This field is inherited by subtypes.
.. c:member:: iternextfunc PyTypeObject.tp_iternext
An optional pointer to a function that returns the next item in an iterator.
When the iterator is exhausted, it must return *NULL*; a :exc:`StopIteration`
exception may or may not be set. When another error occurs, it must return
*NULL* too. Its presence normally signals that the instances of this type
are iterators (although classic instances always have this function, even if
they don't define a :meth:`~iterator.next` method).
Iterator types should also define the :c:member:`~PyTypeObject.tp_iter` function, and that
function should return the iterator instance itself (not a new iterator
instance).
This function has the same signature as :c:func:`PyIter_Next`.
This field is inherited by subtypes.
The next fields, up to and including :c:member:`~PyTypeObject.tp_weaklist`, only exist if the
:const:`Py_TPFLAGS_HAVE_CLASS` flag bit is set.
.. c:member:: struct PyMethodDef* PyTypeObject.tp_methods
An optional pointer to a static *NULL*-terminated array of :c:type:`PyMethodDef`
structures, declaring regular methods of this type.
For each entry in the array, an entry is added to the type's dictionary (see
:c:member:`~PyTypeObject.tp_dict` below) containing a method descriptor.
This field is not inherited by subtypes (methods are inherited through a
different mechanism).
.. c:member:: struct PyMemberDef* PyTypeObject.tp_members
An optional pointer to a static *NULL*-terminated array of :c:type:`PyMemberDef`
structures, declaring regular data members (fields or slots) of instances of
this type.
For each entry in the array, an entry is added to the type's dictionary (see
:c:member:`~PyTypeObject.tp_dict` below) containing a member descriptor.
This field is not inherited by subtypes (members are inherited through a
different mechanism).
.. c:member:: struct PyGetSetDef* PyTypeObject.tp_getset
An optional pointer to a static *NULL*-terminated array of :c:type:`PyGetSetDef`
structures, declaring computed attributes of instances of this type.
For each entry in the array, an entry is added to the type's dictionary (see
:c:member:`~PyTypeObject.tp_dict` below) containing a getset descriptor.
This field is not inherited by subtypes (computed attributes are inherited
through a different mechanism).
.. c:member:: PyTypeObject* PyTypeObject.tp_base
An optional pointer to a base type from which type properties are inherited. At
this level, only single inheritance is supported; multiple inheritance require
dynamically creating a type object by calling the metatype.
This field is not inherited by subtypes (obviously), but it defaults to
``&PyBaseObject_Type`` (which to Python programmers is known as the type
:class:`object`).
.. c:member:: PyObject* PyTypeObject.tp_dict
The type's dictionary is stored here by :c:func:`PyType_Ready`.
This field should normally be initialized to *NULL* before PyType_Ready is
called; it may also be initialized to a dictionary containing initial attributes
for the type. Once :c:func:`PyType_Ready` has initialized the type, extra
attributes for the type may be added to this dictionary only if they don't
correspond to overloaded operations (like :meth:`__add__`).
This field is not inherited by subtypes (though the attributes defined in here
are inherited through a different mechanism).
.. c:member:: descrgetfunc PyTypeObject.tp_descr_get
An optional pointer to a "descriptor get" function.
The function signature is ::
PyObject * tp_descr_get(PyObject *self, PyObject *obj, PyObject *type);
.. XXX explain.
This field is inherited by subtypes.
.. c:member:: descrsetfunc PyTypeObject.tp_descr_set
An optional pointer to a function for setting and deleting
a descriptor's value.
The function signature is ::
int tp_descr_set(PyObject *self, PyObject *obj, PyObject *value);
The *value* argument is set to *NULL* to delete the value.
This field is inherited by subtypes.
.. XXX explain.
.. c:member:: long PyTypeObject.tp_dictoffset
If the instances of this type have a dictionary containing instance variables,
this field is non-zero and contains the offset in the instances of the type of
the instance variable dictionary; this offset is used by
:c:func:`PyObject_GenericGetAttr`.
Do not confuse this field with :c:member:`~PyTypeObject.tp_dict`; that is the dictionary for
attributes of the type object itself.
If the value of this field is greater than zero, it specifies the offset from
the start of the instance structure. If the value is less than zero, it
specifies the offset from the *end* of the instance structure. A negative
offset is more expensive to use, and should only be used when the instance
structure contains a variable-length part. This is used for example to add an
instance variable dictionary to subtypes of :class:`str` or :class:`tuple`. Note
that the :c:member:`~PyTypeObject.tp_basicsize` field should account for the dictionary added to
the end in that case, even though the dictionary is not included in the basic
object layout. On a system with a pointer size of 4 bytes,
:c:member:`~PyTypeObject.tp_dictoffset` should be set to ``-4`` to indicate that the dictionary is
at the very end of the structure.
The real dictionary offset in an instance can be computed from a negative
:c:member:`~PyTypeObject.tp_dictoffset` as follows::
dictoffset = tp_basicsize + abs(ob_size)*tp_itemsize + tp_dictoffset
if dictoffset is not aligned on sizeof(void*):
round up to sizeof(void*)
where :c:member:`~PyTypeObject.tp_basicsize`, :c:member:`~PyTypeObject.tp_itemsize` and :c:member:`~PyTypeObject.tp_dictoffset` are
taken from the type object, and :attr:`ob_size` is taken from the instance. The
absolute value is taken because long ints use the sign of :attr:`ob_size` to
store the sign of the number. (There's never a need to do this calculation
yourself; it is done for you by :c:func:`_PyObject_GetDictPtr`.)
This field is inherited by subtypes, but see the rules listed below. A subtype
may override this offset; this means that the subtype instances store the
dictionary at a difference offset than the base type. Since the dictionary is
always found via :c:member:`~PyTypeObject.tp_dictoffset`, this should not be a problem.
When a type defined by a class statement has no :attr:`~object.__slots__` declaration,
and none of its base types has an instance variable dictionary, a dictionary
slot is added to the instance layout and the :c:member:`~PyTypeObject.tp_dictoffset` is set to
that slot's offset.
When a type defined by a class statement has a :attr:`__slots__` declaration,
the type inherits its :c:member:`~PyTypeObject.tp_dictoffset` from its base type.
(Adding a slot named :attr:`~object.__dict__` to the :attr:`__slots__` declaration does
not have the expected effect, it just causes confusion. Maybe this should be
added as a feature just like :attr:`__weakref__` though.)
.. c:member:: initproc PyTypeObject.tp_init
An optional pointer to an instance initialization function.
This function corresponds to the :meth:`__init__` method of classes. Like
:meth:`__init__`, it is possible to create an instance without calling
:meth:`__init__`, and it is possible to reinitialize an instance by calling its
:meth:`__init__` method again.
The function signature is ::
int tp_init(PyObject *self, PyObject *args, PyObject *kwds)
The self argument is the instance to be initialized; the *args* and *kwds*
arguments represent positional and keyword arguments of the call to
:meth:`__init__`.
The :c:member:`~PyTypeObject.tp_init` function, if not *NULL*, is called when an instance is
created normally by calling its type, after the type's :c:member:`~PyTypeObject.tp_new` function
has returned an instance of the type. If the :c:member:`~PyTypeObject.tp_new` function returns an
instance of some other type that is not a subtype of the original type, no
:c:member:`~PyTypeObject.tp_init` function is called; if :c:member:`~PyTypeObject.tp_new` returns an instance of a
subtype of the original type, the subtype's :c:member:`~PyTypeObject.tp_init` is called. (VERSION
NOTE: described here is what is implemented in Python 2.2.1 and later. In
Python 2.2, the :c:member:`~PyTypeObject.tp_init` of the type of the object returned by
:c:member:`~PyTypeObject.tp_new` was always called, if not *NULL*.)
This field is inherited by subtypes.
.. c:member:: allocfunc PyTypeObject.tp_alloc
An optional pointer to an instance allocation function.
The function signature is ::
PyObject *tp_alloc(PyTypeObject *self, Py_ssize_t nitems)
The purpose of this function is to separate memory allocation from memory
initialization. It should return a pointer to a block of memory of adequate
length for the instance, suitably aligned, and initialized to zeros, but with
:attr:`ob_refcnt` set to ``1`` and :attr:`ob_type` set to the type argument. If
the type's :c:member:`~PyTypeObject.tp_itemsize` is non-zero, the object's :attr:`ob_size` field
should be initialized to *nitems* and the length of the allocated memory block
should be ``tp_basicsize + nitems*tp_itemsize``, rounded up to a multiple of
``sizeof(void*)``; otherwise, *nitems* is not used and the length of the block
should be :c:member:`~PyTypeObject.tp_basicsize`.
Do not use this function to do any other instance initialization, not even to
allocate additional memory; that should be done by :c:member:`~PyTypeObject.tp_new`.
This field is inherited by static subtypes, but not by dynamic subtypes
(subtypes created by a class statement); in the latter, this field is always set
to :c:func:`PyType_GenericAlloc`, to force a standard heap allocation strategy.
That is also the recommended value for statically defined types.
.. c:member:: newfunc PyTypeObject.tp_new
An optional pointer to an instance creation function.
If this function is *NULL* for a particular type, that type cannot be called to
create new instances; presumably there is some other way to create instances,
like a factory function.
The function signature is ::
PyObject *tp_new(PyTypeObject *subtype, PyObject *args, PyObject *kwds)
The subtype argument is the type of the object being created; the *args* and
*kwds* arguments represent positional and keyword arguments of the call to the
type. Note that subtype doesn't have to equal the type whose :c:member:`~PyTypeObject.tp_new`
function is called; it may be a subtype of that type (but not an unrelated
type).
The :c:member:`~PyTypeObject.tp_new` function should call ``subtype->tp_alloc(subtype, nitems)``
to allocate space for the object, and then do only as much further
initialization as is absolutely necessary. Initialization that can safely be
ignored or repeated should be placed in the :c:member:`~PyTypeObject.tp_init` handler. A good
rule of thumb is that for immutable types, all initialization should take place
in :c:member:`~PyTypeObject.tp_new`, while for mutable types, most initialization should be
deferred to :c:member:`~PyTypeObject.tp_init`.
This field is inherited by subtypes, except it is not inherited by static types
whose :c:member:`~PyTypeObject.tp_base` is *NULL* or ``&PyBaseObject_Type``. The latter exception
is a precaution so that old extension types don't become callable simply by
being linked with Python 2.2.
.. c:member:: destructor PyTypeObject.tp_free
An optional pointer to an instance deallocation function.
The signature of this function has changed slightly: in Python 2.2 and 2.2.1,
its signature is :c:type:`destructor`::
void tp_free(PyObject *)
In Python 2.3 and beyond, its signature is :c:type:`freefunc`::
void tp_free(void *)
The only initializer that is compatible with both versions is ``_PyObject_Del``,
whose definition has suitably adapted in Python 2.3.
This field is inherited by static subtypes, but not by dynamic subtypes
(subtypes created by a class statement); in the latter, this field is set to a
deallocator suitable to match :c:func:`PyType_GenericAlloc` and the value of the
:const:`Py_TPFLAGS_HAVE_GC` flag bit.
.. c:member:: inquiry PyTypeObject.tp_is_gc
An optional pointer to a function called by the garbage collector.
The garbage collector needs to know whether a particular object is collectible
or not. Normally, it is sufficient to look at the object's type's
:c:member:`~PyTypeObject.tp_flags` field, and check the :const:`Py_TPFLAGS_HAVE_GC` flag bit. But
some types have a mixture of statically and dynamically allocated instances, and
the statically allocated instances are not collectible. Such types should
define this function; it should return ``1`` for a collectible instance, and
``0`` for a non-collectible instance. The signature is ::
int tp_is_gc(PyObject *self)
(The only example of this are types themselves. The metatype,
:c:data:`PyType_Type`, defines this function to distinguish between statically
and dynamically allocated types.)
This field is inherited by subtypes. (VERSION NOTE: in Python 2.2, it was not
inherited. It is inherited in 2.2.1 and later versions.)
.. c:member:: PyObject* PyTypeObject.tp_bases
Tuple of base types.
This is set for types created by a class statement. It should be *NULL* for
statically defined types.
This field is not inherited.
.. c:member:: PyObject* PyTypeObject.tp_mro
Tuple containing the expanded set of base types, starting with the type itself
and ending with :class:`object`, in Method Resolution Order.
This field is not inherited; it is calculated fresh by :c:func:`PyType_Ready`.
.. c:member:: PyObject* PyTypeObject.tp_cache
Unused. Not inherited. Internal use only.
.. c:member:: PyObject* PyTypeObject.tp_subclasses
List of weak references to subclasses. Not inherited. Internal use only.
.. c:member:: PyObject* PyTypeObject.tp_weaklist
Weak reference list head, for weak references to this type object. Not
inherited. Internal use only.
The remaining fields are only defined if the feature test macro
:const:`COUNT_ALLOCS` is defined, and are for internal use only. They are
documented here for completeness. None of these fields are inherited by
subtypes. See the :envvar:`PYTHONSHOWALLOCCOUNT` environment variable.
.. c:member:: Py_ssize_t PyTypeObject.tp_allocs
Number of allocations.
.. c:member:: Py_ssize_t PyTypeObject.tp_frees
Number of frees.
.. c:member:: Py_ssize_t PyTypeObject.tp_maxalloc
Maximum simultaneously allocated objects.
.. c:member:: PyTypeObject* PyTypeObject.tp_next
Pointer to the next type object with a non-zero :c:member:`~PyTypeObject.tp_allocs` field.
Also, note that, in a garbage collected Python, tp_dealloc may be called from
any Python thread, not just the thread which created the object (if the object
becomes part of a refcount cycle, that cycle might be collected by a garbage
collection on any thread). This is not a problem for Python API calls, since
the thread on which tp_dealloc is called will own the Global Interpreter Lock
(GIL). However, if the object being destroyed in turn destroys objects from some
other C or C++ library, care should be taken to ensure that destroying those
objects on the thread which called tp_dealloc will not violate any assumptions
of the library.
.. _number-structs:
Number Object Structures
========================
.. sectionauthor:: Amaury Forgeot d'Arc
.. c:type:: PyNumberMethods
This structure holds pointers to the functions which an object uses to
implement the number protocol. Almost every function below is used by the
function of similar name documented in the :ref:`number` section.
Here is the structure definition::
typedef struct {
binaryfunc nb_add;
binaryfunc nb_subtract;
binaryfunc nb_multiply;
binaryfunc nb_divide;
binaryfunc nb_remainder;
binaryfunc nb_divmod;
ternaryfunc nb_power;
unaryfunc nb_negative;
unaryfunc nb_positive;
unaryfunc nb_absolute;
inquiry nb_nonzero; /* Used by PyObject_IsTrue */
unaryfunc nb_invert;
binaryfunc nb_lshift;
binaryfunc nb_rshift;
binaryfunc nb_and;
binaryfunc nb_xor;
binaryfunc nb_or;
coercion nb_coerce; /* Used by the coerce() function */
unaryfunc nb_int;
unaryfunc nb_long;
unaryfunc nb_float;
unaryfunc nb_oct;
unaryfunc nb_hex;
/* Added in release 2.0 */
binaryfunc nb_inplace_add;
binaryfunc nb_inplace_subtract;
binaryfunc nb_inplace_multiply;
binaryfunc nb_inplace_divide;
binaryfunc nb_inplace_remainder;
ternaryfunc nb_inplace_power;
binaryfunc nb_inplace_lshift;
binaryfunc nb_inplace_rshift;
binaryfunc nb_inplace_and;
binaryfunc nb_inplace_xor;
binaryfunc nb_inplace_or;
/* Added in release 2.2 */
binaryfunc nb_floor_divide;
binaryfunc nb_true_divide;
binaryfunc nb_inplace_floor_divide;
binaryfunc nb_inplace_true_divide;
/* Added in release 2.5 */
unaryfunc nb_index;
} PyNumberMethods;
Binary and ternary functions may receive different kinds of arguments, depending
on the flag bit :const:`Py_TPFLAGS_CHECKTYPES`:
- If :const:`Py_TPFLAGS_CHECKTYPES` is not set, the function arguments are
guaranteed to be of the object's type; the caller is responsible for calling
the coercion method specified by the :attr:`nb_coerce` member to convert the
arguments:
.. c:member:: coercion PyNumberMethods.nb_coerce
This function is used by :c:func:`PyNumber_CoerceEx` and has the same
signature. The first argument is always a pointer to an object of the
defined type. If the conversion to a common "larger" type is possible, the
function replaces the pointers with new references to the converted objects
and returns ``0``. If the conversion is not possible, the function returns
``1``. If an error condition is set, it will return ``-1``.
- If the :const:`Py_TPFLAGS_CHECKTYPES` flag is set, binary and ternary
functions must check the type of all their operands, and implement the
necessary conversions (at least one of the operands is an instance of the
defined type). This is the recommended way; with Python 3 coercion will
disappear completely.
If the operation is not defined for the given operands, binary and ternary
functions must return ``Py_NotImplemented``, if another error occurred they must
return ``NULL`` and set an exception.
.. _mapping-structs:
Mapping Object Structures
=========================
.. sectionauthor:: Amaury Forgeot d'Arc
.. c:type:: PyMappingMethods
This structure holds pointers to the functions which an object uses to
implement the mapping protocol. It has three members:
.. c:member:: lenfunc PyMappingMethods.mp_length
This function is used by :c:func:`PyMapping_Length` and
:c:func:`PyObject_Size`, and has the same signature. This slot may be set to
*NULL* if the object has no defined length.
.. c:member:: binaryfunc PyMappingMethods.mp_subscript
This function is used by :c:func:`PyObject_GetItem` and has the same
signature. This slot must be filled for the :c:func:`PyMapping_Check`
function to return ``1``, it can be *NULL* otherwise.
.. c:member:: objobjargproc PyMappingMethods.mp_ass_subscript
This function is used by :c:func:`PyObject_SetItem` and
:c:func:`PyObject_DelItem`. It has the same signature as
:c:func:`PyObject_SetItem`, but *v* can also be set to *NULL* to delete
an item. If this slot is *NULL*, the object does not support item
assignment and deletion.
.. _sequence-structs:
Sequence Object Structures
==========================
.. sectionauthor:: Amaury Forgeot d'Arc
.. c:type:: PySequenceMethods
This structure holds pointers to the functions which an object uses to
implement the sequence protocol.
.. c:member:: lenfunc PySequenceMethods.sq_length
This function is used by :c:func:`PySequence_Size` and :c:func:`PyObject_Size`,
and has the same signature.
.. c:member:: binaryfunc PySequenceMethods.sq_concat
This function is used by :c:func:`PySequence_Concat` and has the same
signature. It is also used by the ``+`` operator, after trying the numeric
addition via the :c:member:`~PyTypeObject.tp_as_number.nb_add` slot.
.. c:member:: ssizeargfunc PySequenceMethods.sq_repeat
This function is used by :c:func:`PySequence_Repeat` and has the same
signature. It is also used by the ``*`` operator, after trying numeric
multiplication via the :c:member:`~PyTypeObject.tp_as_number.nb_multiply`
slot.
.. c:member:: ssizeargfunc PySequenceMethods.sq_item
This function is used by :c:func:`PySequence_GetItem` and has the same
signature. This slot must be filled for the :c:func:`PySequence_Check`
function to return ``1``, it can be *NULL* otherwise.
Negative indexes are handled as follows: if the :attr:`sq_length` slot is
filled, it is called and the sequence length is used to compute a positive
index which is passed to :attr:`sq_item`. If :attr:`sq_length` is *NULL*,
the index is passed as is to the function.
.. c:member:: ssizeobjargproc PySequenceMethods.sq_ass_item
This function is used by :c:func:`PySequence_SetItem` and has the same
signature. This slot may be left to *NULL* if the object does not support
item assignment and deletion.
.. c:member:: objobjproc PySequenceMethods.sq_contains
This function may be used by :c:func:`PySequence_Contains` and has the same
signature. This slot may be left to *NULL*, in this case
:c:func:`PySequence_Contains` simply traverses the sequence until it finds a
match.
.. c:member:: binaryfunc PySequenceMethods.sq_inplace_concat
This function is used by :c:func:`PySequence_InPlaceConcat` and has the same
signature. It should modify its first operand, and return it.
.. c:member:: ssizeargfunc PySequenceMethods.sq_inplace_repeat
This function is used by :c:func:`PySequence_InPlaceRepeat` and has the same
signature. It should modify its first operand, and return it.
.. XXX need to explain precedence between mapping and sequence
.. XXX explains when to implement the sq_inplace_* slots
.. _buffer-structs:
Buffer Object Structures
========================
.. sectionauthor:: Greg J. Stein <greg@lyra.org>
The buffer interface exports a model where an object can expose its internal
data as a set of chunks of data, where each chunk is specified as a
pointer/length pair. These chunks are called :dfn:`segments` and are presumed
to be non-contiguous in memory.
If an object does not export the buffer interface, then its :c:member:`~PyTypeObject.tp_as_buffer`
member in the :c:type:`PyTypeObject` structure should be *NULL*. Otherwise, the
:c:member:`~PyTypeObject.tp_as_buffer` will point to a :c:type:`PyBufferProcs` structure.
.. note::
It is very important that your :c:type:`PyTypeObject` structure uses
:const:`Py_TPFLAGS_DEFAULT` for the value of the :c:member:`~PyTypeObject.tp_flags` member rather
than ``0``. This tells the Python runtime that your :c:type:`PyBufferProcs`
structure contains the :attr:`bf_getcharbuffer` slot. Older versions of Python
did not have this member, so a new Python interpreter using an old extension
needs to be able to test for its presence before using it.
.. c:type:: PyBufferProcs
Structure used to hold the function pointers which define an implementation of
the buffer protocol.
The first slot is :attr:`bf_getreadbuffer`, of type :c:type:`readbufferproc`.
If this slot is *NULL*, then the object does not support reading from the
internal data. This is non-sensical, so implementors should fill this in, but
callers should test that the slot contains a non-*NULL* value.
The next slot is :attr:`bf_getwritebuffer` having type
:c:type:`writebufferproc`. This slot may be *NULL* if the object does not
allow writing into its returned buffers.
The third slot is :attr:`bf_getsegcount`, with type :c:type:`segcountproc`.
This slot must not be *NULL* and is used to inform the caller how many segments
the object contains. Simple objects such as :c:type:`PyString_Type` and
:c:type:`PyBuffer_Type` objects contain a single segment.
.. index:: single: PyType_HasFeature()
The last slot is :attr:`bf_getcharbuffer`, of type :c:type:`charbufferproc`.
This slot will only be present if the :const:`Py_TPFLAGS_HAVE_GETCHARBUFFER`
flag is present in the :c:member:`~PyTypeObject.tp_flags` field of the object's
:c:type:`PyTypeObject`. Before using this slot, the caller should test whether it
is present by using the :c:func:`PyType_HasFeature` function. If the flag is
present, :attr:`bf_getcharbuffer` may be *NULL*, indicating that the object's
contents cannot be used as *8-bit characters*. The slot function may also raise
an error if the object's contents cannot be interpreted as 8-bit characters.
For example, if the object is an array which is configured to hold floating
point values, an exception may be raised if a caller attempts to use
:attr:`bf_getcharbuffer` to fetch a sequence of 8-bit characters. This notion of
exporting the internal buffers as "text" is used to distinguish between objects
that are binary in nature, and those which have character-based content.
.. note::
The current policy seems to state that these characters may be multi-byte
characters. This implies that a buffer size of *N* does not mean there are *N*
characters present.
.. data:: Py_TPFLAGS_HAVE_GETCHARBUFFER
Flag bit set in the type structure to indicate that the :attr:`bf_getcharbuffer`
slot is known. This being set does not indicate that the object supports the
buffer interface or that the :attr:`bf_getcharbuffer` slot is non-*NULL*.
.. c:type:: Py_ssize_t (*readbufferproc) (PyObject *self, Py_ssize_t segment, void **ptrptr)
Return a pointer to a readable segment of the buffer in ``*ptrptr``. This
function is allowed to raise an exception, in which case it must return ``-1``.
The *segment* which is specified must be zero or positive, and strictly less
than the number of segments returned by the :attr:`bf_getsegcount` slot
function. On success, it returns the length of the segment, and sets
``*ptrptr`` to a pointer to that memory.
.. c:type:: Py_ssize_t (*writebufferproc) (PyObject *self, Py_ssize_t segment, void **ptrptr)
Return a pointer to a writable memory buffer in ``*ptrptr``, and the length of
that segment as the function return value. The memory buffer must correspond to
buffer segment *segment*. Must return ``-1`` and set an exception on error.
:exc:`TypeError` should be raised if the object only supports read-only buffers,
and :exc:`SystemError` should be raised when *segment* specifies a segment that
doesn't exist.
.. Why doesn't it raise ValueError for this one?
GJS: because you shouldn't be calling it with an invalid
segment. That indicates a blatant programming error in the C code.
.. c:type:: Py_ssize_t (*segcountproc) (PyObject *self, Py_ssize_t *lenp)
Return the number of memory segments which comprise the buffer. If *lenp* is
not *NULL*, the implementation must report the sum of the sizes (in bytes) of
all segments in ``*lenp``. The function cannot fail.
.. c:type:: Py_ssize_t (*charbufferproc) (PyObject *self, Py_ssize_t segment, char **ptrptr)
Return the size of the segment *segment* that *ptrptr* is set to. ``*ptrptr``
is set to the memory buffer. Returns ``-1`` on error.
PK %�\pin6F� F� # html/_sources/c-api/unicode.rst.txtnu �[��� .. highlightlang:: c
.. _unicodeobjects:
Unicode Objects and Codecs
--------------------------
.. sectionauthor:: Marc-Andre Lemburg <mal@lemburg.com>
Unicode Objects
^^^^^^^^^^^^^^^
Unicode Type
""""""""""""
These are the basic Unicode object types used for the Unicode implementation in
Python:
.. c:type:: Py_UNICODE
This type represents the storage type which is used by Python internally as
basis for holding Unicode ordinals. Python's default builds use a 16-bit type
for :c:type:`Py_UNICODE` and store Unicode values internally as UCS2. It is also
possible to build a UCS4 version of Python (most recent Linux distributions come
with UCS4 builds of Python). These builds then use a 32-bit type for
:c:type:`Py_UNICODE` and store Unicode data internally as UCS4. On platforms
where :c:type:`wchar_t` is available and compatible with the chosen Python
Unicode build variant, :c:type:`Py_UNICODE` is a typedef alias for
:c:type:`wchar_t` to enhance native platform compatibility. On all other
platforms, :c:type:`Py_UNICODE` is a typedef alias for either :c:type:`unsigned
short` (UCS2) or :c:type:`unsigned long` (UCS4).
Note that UCS2 and UCS4 Python builds are not binary compatible. Please keep
this in mind when writing extensions or interfaces.
.. c:type:: PyUnicodeObject
This subtype of :c:type:`PyObject` represents a Python Unicode object.
.. c:var:: PyTypeObject PyUnicode_Type
This instance of :c:type:`PyTypeObject` represents the Python Unicode type. It
is exposed to Python code as ``unicode`` and ``types.UnicodeType``.
The following APIs are really C macros and can be used to do fast checks and to
access internal read-only data of Unicode objects:
.. c:function:: int PyUnicode_Check(PyObject *o)
Return true if the object *o* is a Unicode object or an instance of a Unicode
subtype.
.. versionchanged:: 2.2
Allowed subtypes to be accepted.
.. c:function:: int PyUnicode_CheckExact(PyObject *o)
Return true if the object *o* is a Unicode object, but not an instance of a
subtype.
.. versionadded:: 2.2
.. c:function:: Py_ssize_t PyUnicode_GET_SIZE(PyObject *o)
Return the size of the object. *o* has to be a :c:type:`PyUnicodeObject` (not
checked).
.. versionchanged:: 2.5
This function returned an :c:type:`int` type. This might require changes
in your code for properly supporting 64-bit systems.
.. c:function:: Py_ssize_t PyUnicode_GET_DATA_SIZE(PyObject *o)
Return the size of the object's internal buffer in bytes. *o* has to be a
:c:type:`PyUnicodeObject` (not checked).
.. versionchanged:: 2.5
This function returned an :c:type:`int` type. This might require changes
in your code for properly supporting 64-bit systems.
.. c:function:: Py_UNICODE* PyUnicode_AS_UNICODE(PyObject *o)
Return a pointer to the internal :c:type:`Py_UNICODE` buffer of the object. *o*
has to be a :c:type:`PyUnicodeObject` (not checked).
.. c:function:: const char* PyUnicode_AS_DATA(PyObject *o)
Return a pointer to the internal buffer of the object. *o* has to be a
:c:type:`PyUnicodeObject` (not checked).
.. c:function:: int PyUnicode_ClearFreeList()
Clear the free list. Return the total number of freed items.
.. versionadded:: 2.6
Unicode Character Properties
""""""""""""""""""""""""""""
Unicode provides many different character properties. The most often needed ones
are available through these macros which are mapped to C functions depending on
the Python configuration.
.. c:function:: int Py_UNICODE_ISSPACE(Py_UNICODE ch)
Return ``1`` or ``0`` depending on whether *ch* is a whitespace character.
.. c:function:: int Py_UNICODE_ISLOWER(Py_UNICODE ch)
Return ``1`` or ``0`` depending on whether *ch* is a lowercase character.
.. c:function:: int Py_UNICODE_ISUPPER(Py_UNICODE ch)
Return ``1`` or ``0`` depending on whether *ch* is an uppercase character.
.. c:function:: int Py_UNICODE_ISTITLE(Py_UNICODE ch)
Return ``1`` or ``0`` depending on whether *ch* is a titlecase character.
.. c:function:: int Py_UNICODE_ISLINEBREAK(Py_UNICODE ch)
Return ``1`` or ``0`` depending on whether *ch* is a linebreak character.
.. c:function:: int Py_UNICODE_ISDECIMAL(Py_UNICODE ch)
Return ``1`` or ``0`` depending on whether *ch* is a decimal character.
.. c:function:: int Py_UNICODE_ISDIGIT(Py_UNICODE ch)
Return ``1`` or ``0`` depending on whether *ch* is a digit character.
.. c:function:: int Py_UNICODE_ISNUMERIC(Py_UNICODE ch)
Return ``1`` or ``0`` depending on whether *ch* is a numeric character.
.. c:function:: int Py_UNICODE_ISALPHA(Py_UNICODE ch)
Return ``1`` or ``0`` depending on whether *ch* is an alphabetic character.
.. c:function:: int Py_UNICODE_ISALNUM(Py_UNICODE ch)
Return ``1`` or ``0`` depending on whether *ch* is an alphanumeric character.
These APIs can be used for fast direct character conversions:
.. c:function:: Py_UNICODE Py_UNICODE_TOLOWER(Py_UNICODE ch)
Return the character *ch* converted to lower case.
.. c:function:: Py_UNICODE Py_UNICODE_TOUPPER(Py_UNICODE ch)
Return the character *ch* converted to upper case.
.. c:function:: Py_UNICODE Py_UNICODE_TOTITLE(Py_UNICODE ch)
Return the character *ch* converted to title case.
.. c:function:: int Py_UNICODE_TODECIMAL(Py_UNICODE ch)
Return the character *ch* converted to a decimal positive integer. Return
``-1`` if this is not possible. This macro does not raise exceptions.
.. c:function:: int Py_UNICODE_TODIGIT(Py_UNICODE ch)
Return the character *ch* converted to a single digit integer. Return ``-1`` if
this is not possible. This macro does not raise exceptions.
.. c:function:: double Py_UNICODE_TONUMERIC(Py_UNICODE ch)
Return the character *ch* converted to a double. Return ``-1.0`` if this is not
possible. This macro does not raise exceptions.
Plain Py_UNICODE
""""""""""""""""
To create Unicode objects and access their basic sequence properties, use these
APIs:
.. c:function:: PyObject* PyUnicode_FromUnicode(const Py_UNICODE *u, Py_ssize_t size)
Create a Unicode object from the Py_UNICODE buffer *u* of the given size. *u*
may be *NULL* which causes the contents to be undefined. It is the user's
responsibility to fill in the needed data. The buffer is copied into the new
object. If the buffer is not *NULL*, the return value might be a shared object.
Therefore, modification of the resulting Unicode object is only allowed when *u*
is *NULL*.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyUnicode_FromStringAndSize(const char *u, Py_ssize_t size)
Create a Unicode object from the char buffer *u*. The bytes will be interpreted
as being UTF-8 encoded. *u* may also be *NULL* which
causes the contents to be undefined. It is the user's responsibility to fill in
the needed data. The buffer is copied into the new object. If the buffer is not
*NULL*, the return value might be a shared object. Therefore, modification of
the resulting Unicode object is only allowed when *u* is *NULL*.
.. versionadded:: 2.6
.. c:function:: PyObject *PyUnicode_FromString(const char *u)
Create a Unicode object from a UTF-8 encoded null-terminated char buffer
*u*.
.. versionadded:: 2.6
.. c:function:: PyObject* PyUnicode_FromFormat(const char *format, ...)
Take a C :c:func:`printf`\ -style *format* string and a variable number of
arguments, calculate the size of the resulting Python unicode string and return
a string with the values formatted into it. The variable arguments must be C
types and must correspond exactly to the format characters in the *format*
string. The following format characters are allowed:
.. % The descriptions for %zd and %zu are wrong, but the truth is complicated
.. % because not all compilers support the %z width modifier -- we fake it
.. % when necessary via interpolating PY_FORMAT_SIZE_T.
.. tabularcolumns:: |l|l|L|
+-------------------+---------------------+--------------------------------+
| Format Characters | Type | Comment |
+===================+=====================+================================+
| :attr:`%%` | *n/a* | The literal % character. |
+-------------------+---------------------+--------------------------------+
| :attr:`%c` | int | A single character, |
| | | represented as a C int. |
+-------------------+---------------------+--------------------------------+
| :attr:`%d` | int | Exactly equivalent to |
| | | ``printf("%d")``. |
+-------------------+---------------------+--------------------------------+
| :attr:`%u` | unsigned int | Exactly equivalent to |
| | | ``printf("%u")``. |
+-------------------+---------------------+--------------------------------+
| :attr:`%ld` | long | Exactly equivalent to |
| | | ``printf("%ld")``. |
+-------------------+---------------------+--------------------------------+
| :attr:`%lu` | unsigned long | Exactly equivalent to |
| | | ``printf("%lu")``. |
+-------------------+---------------------+--------------------------------+
| :attr:`%zd` | Py_ssize_t | Exactly equivalent to |
| | | ``printf("%zd")``. |
+-------------------+---------------------+--------------------------------+
| :attr:`%zu` | size_t | Exactly equivalent to |
| | | ``printf("%zu")``. |
+-------------------+---------------------+--------------------------------+
| :attr:`%i` | int | Exactly equivalent to |
| | | ``printf("%i")``. |
+-------------------+---------------------+--------------------------------+
| :attr:`%x` | int | Exactly equivalent to |
| | | ``printf("%x")``. |
+-------------------+---------------------+--------------------------------+
| :attr:`%s` | char\* | A null-terminated C character |
| | | array. |
+-------------------+---------------------+--------------------------------+
| :attr:`%p` | void\* | The hex representation of a C |
| | | pointer. Mostly equivalent to |
| | | ``printf("%p")`` except that |
| | | it is guaranteed to start with |
| | | the literal ``0x`` regardless |
| | | of what the platform's |
| | | ``printf`` yields. |
+-------------------+---------------------+--------------------------------+
| :attr:`%U` | PyObject\* | A unicode object. |
+-------------------+---------------------+--------------------------------+
| :attr:`%V` | PyObject\*, char \* | A unicode object (which may be |
| | | *NULL*) and a null-terminated |
| | | C character array as a second |
| | | parameter (which will be used, |
| | | if the first parameter is |
| | | *NULL*). |
+-------------------+---------------------+--------------------------------+
| :attr:`%S` | PyObject\* | The result of calling |
| | | :func:`PyObject_Unicode`. |
+-------------------+---------------------+--------------------------------+
| :attr:`%R` | PyObject\* | The result of calling |
| | | :func:`PyObject_Repr`. |
+-------------------+---------------------+--------------------------------+
An unrecognized format character causes all the rest of the format string to be
copied as-is to the result string, and any extra arguments discarded.
.. versionadded:: 2.6
.. c:function:: PyObject* PyUnicode_FromFormatV(const char *format, va_list vargs)
Identical to :func:`PyUnicode_FromFormat` except that it takes exactly two
arguments.
.. versionadded:: 2.6
.. c:function:: Py_UNICODE* PyUnicode_AsUnicode(PyObject *unicode)
Return a read-only pointer to the Unicode object's internal
:c:type:`Py_UNICODE` buffer, *NULL* if *unicode* is not a Unicode object.
Note that the resulting :c:type:`Py_UNICODE*` string may contain embedded
null characters, which would cause the string to be truncated when used in
most C functions.
.. c:function:: Py_ssize_t PyUnicode_GetSize(PyObject *unicode)
Return the length of the Unicode object.
.. versionchanged:: 2.5
This function returned an :c:type:`int` type. This might require changes
in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyUnicode_FromEncodedObject(PyObject *obj, const char *encoding, const char *errors)
Coerce an encoded object *obj* to a Unicode object and return a reference with
incremented refcount.
String and other char buffer compatible objects are decoded according to the
given encoding and using the error handling defined by errors. Both can be
*NULL* to have the interface use the default values (see the next section for
details).
All other objects, including Unicode objects, cause a :exc:`TypeError` to be
set.
The API returns *NULL* if there was an error. The caller is responsible for
decref'ing the returned objects.
.. c:function:: PyObject* PyUnicode_FromObject(PyObject *obj)
Shortcut for ``PyUnicode_FromEncodedObject(obj, NULL, "strict")`` which is used
throughout the interpreter whenever coercion to Unicode is needed.
If the platform supports :c:type:`wchar_t` and provides a header file wchar.h,
Python can interface directly to this type using the following functions.
Support is optimized if Python's own :c:type:`Py_UNICODE` type is identical to
the system's :c:type:`wchar_t`.
wchar_t Support
"""""""""""""""
:c:type:`wchar_t` support for platforms which support it:
.. c:function:: PyObject* PyUnicode_FromWideChar(const wchar_t *w, Py_ssize_t size)
Create a Unicode object from the :c:type:`wchar_t` buffer *w* of the given *size*.
Return *NULL* on failure.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: Py_ssize_t PyUnicode_AsWideChar(PyUnicodeObject *unicode, wchar_t *w, Py_ssize_t size)
Copy the Unicode object contents into the :c:type:`wchar_t` buffer *w*. At most
*size* :c:type:`wchar_t` characters are copied (excluding a possibly trailing
0-termination character). Return the number of :c:type:`wchar_t` characters
copied or ``-1`` in case of an error. Note that the resulting :c:type:`wchar_t`
string may or may not be 0-terminated. It is the responsibility of the caller
to make sure that the :c:type:`wchar_t` string is 0-terminated in case this is
required by the application. Also, note that the :c:type:`wchar_t*` string
might contain null characters, which would cause the string to be truncated
when used with most C functions.
.. versionchanged:: 2.5
This function returned an :c:type:`int` type and used an :c:type:`int`
type for *size*. This might require changes in your code for properly
supporting 64-bit systems.
.. _builtincodecs:
Built-in Codecs
^^^^^^^^^^^^^^^
Python provides a set of built-in codecs which are written in C for speed. All of
these codecs are directly usable via the following functions.
Many of the following APIs take two arguments encoding and errors, and they
have the same semantics as the ones of the built-in :func:`unicode` Unicode
object constructor.
Setting encoding to *NULL* causes the default encoding to be used which is
ASCII. The file system calls should use :c:data:`Py_FileSystemDefaultEncoding`
as the encoding for file names. This variable should be treated as read-only: on
some systems, it will be a pointer to a static string, on others, it will change
at run-time (such as when the application invokes setlocale).
Error handling is set by errors which may also be set to *NULL* meaning to use
the default handling defined for the codec. Default error handling for all
built-in codecs is "strict" (:exc:`ValueError` is raised).
The codecs all use a similar interface. Only deviation from the following
generic ones are documented for simplicity.
Generic Codecs
""""""""""""""
These are the generic codec APIs:
.. c:function:: PyObject* PyUnicode_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)
Create a Unicode object by decoding *size* bytes of the encoded string *s*.
*encoding* and *errors* have the same meaning as the parameters of the same name
in the :func:`unicode` built-in function. The codec to be used is looked up
using the Python codec registry. Return *NULL* if an exception was raised by
the codec.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyUnicode_Encode(const Py_UNICODE *s, Py_ssize_t size, const char *encoding, const char *errors)
Encode the :c:type:`Py_UNICODE` buffer *s* of the given *size* and return a Python
string object. *encoding* and *errors* have the same meaning as the parameters
of the same name in the Unicode :meth:`~unicode.encode` method. The codec
to be used is looked up using the Python codec registry. Return *NULL* if
an exception was raised by the codec.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors)
Encode a Unicode object and return the result as Python string object.
*encoding* and *errors* have the same meaning as the parameters of the same name
in the Unicode :meth:`encode` method. The codec to be used is looked up using
the Python codec registry. Return *NULL* if an exception was raised by the
codec.
UTF-8 Codecs
""""""""""""
These are the UTF-8 codec APIs:
.. c:function:: PyObject* PyUnicode_DecodeUTF8(const char *s, Py_ssize_t size, const char *errors)
Create a Unicode object by decoding *size* bytes of the UTF-8 encoded string
*s*. Return *NULL* if an exception was raised by the codec.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyUnicode_DecodeUTF8Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
If *consumed* is *NULL*, behave like :c:func:`PyUnicode_DecodeUTF8`. If
*consumed* is not *NULL*, trailing incomplete UTF-8 byte sequences will not be
treated as an error. Those bytes will not be decoded and the number of bytes
that have been decoded will be stored in *consumed*.
.. versionadded:: 2.4
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyUnicode_EncodeUTF8(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
Encode the :c:type:`Py_UNICODE` buffer *s* of the given *size* using UTF-8 and return a
Python string object. Return *NULL* if an exception was raised by the codec.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyUnicode_AsUTF8String(PyObject *unicode)
Encode a Unicode object using UTF-8 and return the result as Python string
object. Error handling is "strict". Return *NULL* if an exception was raised
by the codec.
UTF-32 Codecs
"""""""""""""
These are the UTF-32 codec APIs:
.. c:function:: PyObject* PyUnicode_DecodeUTF32(const char *s, Py_ssize_t size, const char *errors, int *byteorder)
Decode *size* bytes from a UTF-32 encoded buffer string and return the
corresponding Unicode object. *errors* (if non-*NULL*) defines the error
handling. It defaults to "strict".
If *byteorder* is non-*NULL*, the decoder starts decoding using the given byte
order::
*byteorder == -1: little endian
*byteorder == 0: native order
*byteorder == 1: big endian
If ``*byteorder`` is zero, and the first four bytes of the input data are a
byte order mark (BOM), the decoder switches to this byte order and the BOM is
not copied into the resulting Unicode string. If ``*byteorder`` is ``-1`` or
``1``, any byte order mark is copied to the output.
After completion, *\*byteorder* is set to the current byte order at the end
of input data.
In a narrow build code points outside the BMP will be decoded as surrogate pairs.
If *byteorder* is *NULL*, the codec starts in native order mode.
Return *NULL* if an exception was raised by the codec.
.. versionadded:: 2.6
.. c:function:: PyObject* PyUnicode_DecodeUTF32Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)
If *consumed* is *NULL*, behave like :c:func:`PyUnicode_DecodeUTF32`. If
*consumed* is not *NULL*, :c:func:`PyUnicode_DecodeUTF32Stateful` will not treat
trailing incomplete UTF-32 byte sequences (such as a number of bytes not divisible
by four) as an error. Those bytes will not be decoded and the number of bytes
that have been decoded will be stored in *consumed*.
.. versionadded:: 2.6
.. c:function:: PyObject* PyUnicode_EncodeUTF32(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)
Return a Python bytes object holding the UTF-32 encoded value of the Unicode
data in *s*. Output is written according to the following byte order::
byteorder == -1: little endian
byteorder == 0: native byte order (writes a BOM mark)
byteorder == 1: big endian
If byteorder is ``0``, the output string will always start with the Unicode BOM
mark (U+FEFF). In the other two modes, no BOM mark is prepended.
If *Py_UNICODE_WIDE* is not defined, surrogate pairs will be output
as a single code point.
Return *NULL* if an exception was raised by the codec.
.. versionadded:: 2.6
.. c:function:: PyObject* PyUnicode_AsUTF32String(PyObject *unicode)
Return a Python string using the UTF-32 encoding in native byte order. The
string always starts with a BOM mark. Error handling is "strict". Return
*NULL* if an exception was raised by the codec.
.. versionadded:: 2.6
UTF-16 Codecs
"""""""""""""
These are the UTF-16 codec APIs:
.. c:function:: PyObject* PyUnicode_DecodeUTF16(const char *s, Py_ssize_t size, const char *errors, int *byteorder)
Decode *size* bytes from a UTF-16 encoded buffer string and return the
corresponding Unicode object. *errors* (if non-*NULL*) defines the error
handling. It defaults to "strict".
If *byteorder* is non-*NULL*, the decoder starts decoding using the given byte
order::
*byteorder == -1: little endian
*byteorder == 0: native order
*byteorder == 1: big endian
If ``*byteorder`` is zero, and the first two bytes of the input data are a
byte order mark (BOM), the decoder switches to this byte order and the BOM is
not copied into the resulting Unicode string. If ``*byteorder`` is ``-1`` or
``1``, any byte order mark is copied to the output (where it will result in
either a ``\ufeff`` or a ``\ufffe`` character).
After completion, *\*byteorder* is set to the current byte order at the end
of input data.
If *byteorder* is *NULL*, the codec starts in native order mode.
Return *NULL* if an exception was raised by the codec.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyUnicode_DecodeUTF16Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)
If *consumed* is *NULL*, behave like :c:func:`PyUnicode_DecodeUTF16`. If
*consumed* is not *NULL*, :c:func:`PyUnicode_DecodeUTF16Stateful` will not treat
trailing incomplete UTF-16 byte sequences (such as an odd number of bytes or a
split surrogate pair) as an error. Those bytes will not be decoded and the
number of bytes that have been decoded will be stored in *consumed*.
.. versionadded:: 2.4
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *size* and an :c:type:`int *`
type for *consumed*. This might require changes in your code for
properly supporting 64-bit systems.
.. c:function:: PyObject* PyUnicode_EncodeUTF16(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)
Return a Python string object holding the UTF-16 encoded value of the Unicode
data in *s*. Output is written according to the following byte order::
byteorder == -1: little endian
byteorder == 0: native byte order (writes a BOM mark)
byteorder == 1: big endian
If byteorder is ``0``, the output string will always start with the Unicode BOM
mark (U+FEFF). In the other two modes, no BOM mark is prepended.
If *Py_UNICODE_WIDE* is defined, a single :c:type:`Py_UNICODE` value may get
represented as a surrogate pair. If it is not defined, each :c:type:`Py_UNICODE`
values is interpreted as a UCS-2 character.
Return *NULL* if an exception was raised by the codec.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyUnicode_AsUTF16String(PyObject *unicode)
Return a Python string using the UTF-16 encoding in native byte order. The
string always starts with a BOM mark. Error handling is "strict". Return
*NULL* if an exception was raised by the codec.
UTF-7 Codecs
""""""""""""
These are the UTF-7 codec APIs:
.. c:function:: PyObject* PyUnicode_DecodeUTF7(const char *s, Py_ssize_t size, const char *errors)
Create a Unicode object by decoding *size* bytes of the UTF-7 encoded string
*s*. Return *NULL* if an exception was raised by the codec.
.. c:function:: PyObject* PyUnicode_DecodeUTF7Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
If *consumed* is *NULL*, behave like :c:func:`PyUnicode_DecodeUTF7`. If
*consumed* is not *NULL*, trailing incomplete UTF-7 base-64 sections will not
be treated as an error. Those bytes will not be decoded and the number of
bytes that have been decoded will be stored in *consumed*.
.. c:function:: PyObject* PyUnicode_EncodeUTF7(const Py_UNICODE *s, Py_ssize_t size, int base64SetO, int base64WhiteSpace, const char *errors)
Encode the :c:type:`Py_UNICODE` buffer of the given size using UTF-7 and
return a Python bytes object. Return *NULL* if an exception was raised by
the codec.
If *base64SetO* is nonzero, "Set O" (punctuation that has no otherwise
special meaning) will be encoded in base-64. If *base64WhiteSpace* is
nonzero, whitespace will be encoded in base-64. Both are set to zero for the
Python "utf-7" codec.
Unicode-Escape Codecs
"""""""""""""""""""""
These are the "Unicode Escape" codec APIs:
.. c:function:: PyObject* PyUnicode_DecodeUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)
Create a Unicode object by decoding *size* bytes of the Unicode-Escape encoded
string *s*. Return *NULL* if an exception was raised by the codec.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyUnicode_EncodeUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size)
Encode the :c:type:`Py_UNICODE` buffer of the given *size* using Unicode-Escape and
return a Python string object. Return *NULL* if an exception was raised by the
codec.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyUnicode_AsUnicodeEscapeString(PyObject *unicode)
Encode a Unicode object using Unicode-Escape and return the result as Python
string object. Error handling is "strict". Return *NULL* if an exception was
raised by the codec.
Raw-Unicode-Escape Codecs
"""""""""""""""""""""""""
These are the "Raw Unicode Escape" codec APIs:
.. c:function:: PyObject* PyUnicode_DecodeRawUnicodeEscape(const char *s, Py_ssize_t size, const char *errors)
Create a Unicode object by decoding *size* bytes of the Raw-Unicode-Escape
encoded string *s*. Return *NULL* if an exception was raised by the codec.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyUnicode_EncodeRawUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
Encode the :c:type:`Py_UNICODE` buffer of the given *size* using Raw-Unicode-Escape
and return a Python string object. Return *NULL* if an exception was raised by
the codec.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)
Encode a Unicode object using Raw-Unicode-Escape and return the result as
Python string object. Error handling is "strict". Return *NULL* if an exception
was raised by the codec.
Latin-1 Codecs
""""""""""""""
These are the Latin-1 codec APIs: Latin-1 corresponds to the first 256 Unicode
ordinals and only these are accepted by the codecs during encoding.
.. c:function:: PyObject* PyUnicode_DecodeLatin1(const char *s, Py_ssize_t size, const char *errors)
Create a Unicode object by decoding *size* bytes of the Latin-1 encoded string
*s*. Return *NULL* if an exception was raised by the codec.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyUnicode_EncodeLatin1(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
Encode the :c:type:`Py_UNICODE` buffer of the given *size* using Latin-1 and return
a Python string object. Return *NULL* if an exception was raised by the codec.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyUnicode_AsLatin1String(PyObject *unicode)
Encode a Unicode object using Latin-1 and return the result as Python string
object. Error handling is "strict". Return *NULL* if an exception was raised
by the codec.
ASCII Codecs
""""""""""""
These are the ASCII codec APIs. Only 7-bit ASCII data is accepted. All other
codes generate errors.
.. c:function:: PyObject* PyUnicode_DecodeASCII(const char *s, Py_ssize_t size, const char *errors)
Create a Unicode object by decoding *size* bytes of the ASCII encoded string
*s*. Return *NULL* if an exception was raised by the codec.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyUnicode_EncodeASCII(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
Encode the :c:type:`Py_UNICODE` buffer of the given *size* using ASCII and return a
Python string object. Return *NULL* if an exception was raised by the codec.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyUnicode_AsASCIIString(PyObject *unicode)
Encode a Unicode object using ASCII and return the result as Python string
object. Error handling is "strict". Return *NULL* if an exception was raised
by the codec.
Character Map Codecs
""""""""""""""""""""
This codec is special in that it can be used to implement many different codecs
(and this is in fact what was done to obtain most of the standard codecs
included in the :mod:`encodings` package). The codec uses mapping to encode and
decode characters.
Decoding mappings must map single string characters to single Unicode
characters, integers (which are then interpreted as Unicode ordinals) or ``None``
(meaning "undefined mapping" and causing an error).
Encoding mappings must map single Unicode characters to single string
characters, integers (which are then interpreted as Latin-1 ordinals) or ``None``
(meaning "undefined mapping" and causing an error).
The mapping objects provided must only support the __getitem__ mapping
interface.
If a character lookup fails with a LookupError, the character is copied as-is
meaning that its ordinal value will be interpreted as Unicode or Latin-1 ordinal
resp. Because of this, mappings only need to contain those mappings which map
characters to different code points.
These are the mapping codec APIs:
.. c:function:: PyObject* PyUnicode_DecodeCharmap(const char *s, Py_ssize_t size, PyObject *mapping, const char *errors)
Create a Unicode object by decoding *size* bytes of the encoded string *s* using
the given *mapping* object. Return *NULL* if an exception was raised by the
codec. If *mapping* is *NULL* latin-1 decoding will be done. Else it can be a
dictionary mapping byte or a unicode string, which is treated as a lookup table.
Byte values greater that the length of the string and U+FFFE "characters" are
treated as "undefined mapping".
.. versionchanged:: 2.4
Allowed unicode string as mapping argument.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyUnicode_EncodeCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *mapping, const char *errors)
Encode the :c:type:`Py_UNICODE` buffer of the given *size* using the given
*mapping* object and return a Python string object. Return *NULL* if an
exception was raised by the codec.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)
Encode a Unicode object using the given *mapping* object and return the result
as Python string object. Error handling is "strict". Return *NULL* if an
exception was raised by the codec.
The following codec API is special in that maps Unicode to Unicode.
.. c:function:: PyObject* PyUnicode_TranslateCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *table, const char *errors)
Translate a :c:type:`Py_UNICODE` buffer of the given *size* by applying a
character mapping *table* to it and return the resulting Unicode object. Return
*NULL* when an exception was raised by the codec.
The *mapping* table must map Unicode ordinal integers to Unicode ordinal
integers or ``None`` (causing deletion of the character).
Mapping tables need only provide the :meth:`__getitem__` interface; dictionaries
and sequences work well. Unmapped character ordinals (ones which cause a
:exc:`LookupError`) are left untouched and are copied as-is.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
MBCS codecs for Windows
"""""""""""""""""""""""
These are the MBCS codec APIs. They are currently only available on Windows and
use the Win32 MBCS converters to implement the conversions. Note that MBCS (or
DBCS) is a class of encodings, not just one. The target encoding is defined by
the user settings on the machine running the codec.
.. c:function:: PyObject* PyUnicode_DecodeMBCS(const char *s, Py_ssize_t size, const char *errors)
Create a Unicode object by decoding *size* bytes of the MBCS encoded string *s*.
Return *NULL* if an exception was raised by the codec.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyUnicode_DecodeMBCSStateful(const char *s, int size, const char *errors, int *consumed)
If *consumed* is *NULL*, behave like :c:func:`PyUnicode_DecodeMBCS`. If
*consumed* is not *NULL*, :c:func:`PyUnicode_DecodeMBCSStateful` will not decode
trailing lead byte and the number of bytes that have been decoded will be stored
in *consumed*.
.. versionadded:: 2.5
.. c:function:: PyObject* PyUnicode_EncodeMBCS(const Py_UNICODE *s, Py_ssize_t size, const char *errors)
Encode the :c:type:`Py_UNICODE` buffer of the given *size* using MBCS and return a
Python string object. Return *NULL* if an exception was raised by the codec.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyUnicode_AsMBCSString(PyObject *unicode)
Encode a Unicode object using MBCS and return the result as Python string
object. Error handling is "strict". Return *NULL* if an exception was raised
by the codec.
Methods & Slots
"""""""""""""""
.. _unicodemethodsandslots:
Methods and Slot Functions
^^^^^^^^^^^^^^^^^^^^^^^^^^
The following APIs are capable of handling Unicode objects and strings on input
(we refer to them as strings in the descriptions) and return Unicode objects or
integers as appropriate.
They all return *NULL* or ``-1`` if an exception occurs.
.. c:function:: PyObject* PyUnicode_Concat(PyObject *left, PyObject *right)
Concat two strings giving a new Unicode string.
.. c:function:: PyObject* PyUnicode_Split(PyObject *s, PyObject *sep, Py_ssize_t maxsplit)
Split a string giving a list of Unicode strings. If *sep* is *NULL*, splitting
will be done at all whitespace substrings. Otherwise, splits occur at the given
separator. At most *maxsplit* splits will be done. If negative, no limit is
set. Separators are not included in the resulting list.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *maxsplit*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyUnicode_Splitlines(PyObject *s, int keepend)
Split a Unicode string at line breaks, returning a list of Unicode strings.
CRLF is considered to be one line break. If *keepend* is ``0``, the Line break
characters are not included in the resulting strings.
.. c:function:: PyObject* PyUnicode_Translate(PyObject *str, PyObject *table, const char *errors)
Translate a string by applying a character mapping table to it and return the
resulting Unicode object.
The mapping table must map Unicode ordinal integers to Unicode ordinal integers
or ``None`` (causing deletion of the character).
Mapping tables need only provide the :meth:`__getitem__` interface; dictionaries
and sequences work well. Unmapped character ordinals (ones which cause a
:exc:`LookupError`) are left untouched and are copied as-is.
*errors* has the usual meaning for codecs. It may be *NULL* which indicates to
use the default error handling.
.. c:function:: PyObject* PyUnicode_Join(PyObject *separator, PyObject *seq)
Join a sequence of strings using the given *separator* and return the resulting
Unicode string.
.. c:function:: Py_ssize_t PyUnicode_Tailmatch(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)
Return ``1`` if *substr* matches ``str[start:end]`` at the given tail end
(*direction* == ``-1`` means to do a prefix match, *direction* == ``1`` a suffix match),
``0`` otherwise. Return ``-1`` if an error occurred.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *start* and *end*. This
might require changes in your code for properly supporting 64-bit
systems.
.. c:function:: Py_ssize_t PyUnicode_Find(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)
Return the first position of *substr* in ``str[start:end]`` using the given
*direction* (*direction* == ``1`` means to do a forward search, *direction* == ``-1`` a
backward search). The return value is the index of the first match; a value of
``-1`` indicates that no match was found, and ``-2`` indicates that an error
occurred and an exception has been set.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *start* and *end*. This
might require changes in your code for properly supporting 64-bit
systems.
.. c:function:: Py_ssize_t PyUnicode_Count(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end)
Return the number of non-overlapping occurrences of *substr* in
``str[start:end]``. Return ``-1`` if an error occurred.
.. versionchanged:: 2.5
This function returned an :c:type:`int` type and used an :c:type:`int`
type for *start* and *end*. This might require changes in your code for
properly supporting 64-bit systems.
.. c:function:: PyObject* PyUnicode_Replace(PyObject *str, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)
Replace at most *maxcount* occurrences of *substr* in *str* with *replstr* and
return the resulting Unicode object. *maxcount* == ``-1`` means replace all
occurrences.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *maxcount*. This might
require changes in your code for properly supporting 64-bit systems.
.. c:function:: int PyUnicode_Compare(PyObject *left, PyObject *right)
Compare two strings and return ``-1``, ``0``, ``1`` for less than, equal, and greater than,
respectively.
.. c:function:: int PyUnicode_RichCompare(PyObject *left, PyObject *right, int op)
Rich compare two unicode strings and return one of the following:
* ``NULL`` in case an exception was raised
* :const:`Py_True` or :const:`Py_False` for successful comparisons
* :const:`Py_NotImplemented` in case the type combination is unknown
Note that :const:`Py_EQ` and :const:`Py_NE` comparisons can cause a
:exc:`UnicodeWarning` in case the conversion of the arguments to Unicode fails
with a :exc:`UnicodeDecodeError`.
Possible values for *op* are :const:`Py_GT`, :const:`Py_GE`, :const:`Py_EQ`,
:const:`Py_NE`, :const:`Py_LT`, and :const:`Py_LE`.
.. c:function:: PyObject* PyUnicode_Format(PyObject *format, PyObject *args)
Return a new string object from *format* and *args*; this is analogous to
``format % args``.
.. c:function:: int PyUnicode_Contains(PyObject *container, PyObject *element)
Check whether *element* is contained in *container* and return true or false
accordingly.
*element* has to coerce to a one element Unicode string. ``-1`` is returned if
there was an error.
PK %�\E���� � % html/_sources/c-api/utilities.rst.txtnu �[��� .. highlightlang:: c
.. _utilities:
*********
Utilities
*********
The functions in this chapter perform various utility tasks, ranging from
helping C code be more portable across platforms, using Python modules from C,
and parsing function arguments and constructing Python values from C values.
.. toctree::
sys.rst
import.rst
marshal.rst
arg.rst
conversion.rst
reflection.rst
codec.rst
PK %�\�n\w34 34 $ html/_sources/c-api/veryhigh.rst.txtnu �[��� .. highlightlang:: c
.. _veryhigh:
*************************
The Very High Level Layer
*************************
The functions in this chapter will let you execute Python source code given in a
file or a buffer, but they will not let you interact in a more detailed way with
the interpreter.
Several of these functions accept a start symbol from the grammar as a
parameter. The available start symbols are :const:`Py_eval_input`,
:const:`Py_file_input`, and :const:`Py_single_input`. These are described
following the functions which accept them as parameters.
Note also that several of these functions take :c:type:`FILE\*` parameters. One
particular issue which needs to be handled carefully is that the :c:type:`FILE`
structure for different C libraries can be different and incompatible. Under
Windows (at least), it is possible for dynamically linked extensions to actually
use different libraries, so care should be taken that :c:type:`FILE\*` parameters
are only passed to these functions if it is certain that they were created by
the same library that the Python runtime is using.
.. c:function:: int Py_Main(int argc, char **argv)
The main program for the standard interpreter. This is made available for
programs which embed Python. The *argc* and *argv* parameters should be
prepared exactly as those which are passed to a C program's :c:func:`main`
function. It is important to note that the argument list may be modified (but
the contents of the strings pointed to by the argument list are not). The return
value will be ``0`` if the interpreter exits normally (ie, without an
exception), ``1`` if the interpreter exits due to an exception, or ``2``
if the parameter list does not represent a valid Python command line.
Note that if an otherwise unhandled :exc:`SystemExit` is raised, this
function will not return ``1``, but exit the process, as long as
``Py_InspectFlag`` is not set.
.. c:function:: int PyRun_AnyFile(FILE *fp, const char *filename)
This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, leaving
*closeit* set to ``0`` and *flags* set to *NULL*.
.. c:function:: int PyRun_AnyFileFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)
This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, leaving
the *closeit* argument set to ``0``.
.. c:function:: int PyRun_AnyFileEx(FILE *fp, const char *filename, int closeit)
This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, leaving
the *flags* argument set to *NULL*.
.. c:function:: int PyRun_AnyFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)
If *fp* refers to a file associated with an interactive device (console or
terminal input or Unix pseudo-terminal), return the value of
:c:func:`PyRun_InteractiveLoop`, otherwise return the result of
:c:func:`PyRun_SimpleFile`. If *filename* is *NULL*, this function uses
``"???"`` as the filename.
.. c:function:: int PyRun_SimpleString(const char *command)
This is a simplified interface to :c:func:`PyRun_SimpleStringFlags` below,
leaving the *PyCompilerFlags\** argument set to NULL.
.. c:function:: int PyRun_SimpleStringFlags(const char *command, PyCompilerFlags *flags)
Executes the Python source code from *command* in the :mod:`__main__` module
according to the *flags* argument. If :mod:`__main__` does not already exist, it
is created. Returns ``0`` on success or ``-1`` if an exception was raised. If
there was an error, there is no way to get the exception information. For the
meaning of *flags*, see below.
Note that if an otherwise unhandled :exc:`SystemExit` is raised, this
function will not return ``-1``, but exit the process, as long as
``Py_InspectFlag`` is not set.
.. c:function:: int PyRun_SimpleFile(FILE *fp, const char *filename)
This is a simplified interface to :c:func:`PyRun_SimpleFileExFlags` below,
leaving *closeit* set to ``0`` and *flags* set to *NULL*.
.. c:function:: int PyRun_SimpleFileFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)
This is a simplified interface to :c:func:`PyRun_SimpleFileExFlags` below,
leaving *closeit* set to ``0``.
.. c:function:: int PyRun_SimpleFileEx(FILE *fp, const char *filename, int closeit)
This is a simplified interface to :c:func:`PyRun_SimpleFileExFlags` below,
leaving *flags* set to *NULL*.
.. c:function:: int PyRun_SimpleFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)
Similar to :c:func:`PyRun_SimpleStringFlags`, but the Python source code is read
from *fp* instead of an in-memory string. *filename* should be the name of the
file. If *closeit* is true, the file is closed before PyRun_SimpleFileExFlags
returns.
.. c:function:: int PyRun_InteractiveOne(FILE *fp, const char *filename)
This is a simplified interface to :c:func:`PyRun_InteractiveOneFlags` below,
leaving *flags* set to *NULL*.
.. c:function:: int PyRun_InteractiveOneFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)
Read and execute a single statement from a file associated with an
interactive device according to the *flags* argument. The user will be
prompted using ``sys.ps1`` and ``sys.ps2``. Returns ``0`` when the input was
executed successfully, ``-1`` if there was an exception, or an error code
from the :file:`errcode.h` include file distributed as part of Python if
there was a parse error. (Note that :file:`errcode.h` is not included by
:file:`Python.h`, so must be included specifically if needed.)
.. c:function:: int PyRun_InteractiveLoop(FILE *fp, const char *filename)
This is a simplified interface to :c:func:`PyRun_InteractiveLoopFlags` below,
leaving *flags* set to *NULL*.
.. c:function:: int PyRun_InteractiveLoopFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)
Read and execute statements from a file associated with an interactive device
until EOF is reached. The user will be prompted using ``sys.ps1`` and
``sys.ps2``. Returns ``0`` at EOF.
.. c:function:: struct _node* PyParser_SimpleParseString(const char *str, int start)
This is a simplified interface to
:c:func:`PyParser_SimpleParseStringFlagsFilename` below, leaving *filename* set
to *NULL* and *flags* set to ``0``.
.. c:function:: struct _node* PyParser_SimpleParseStringFlags( const char *str, int start, int flags)
This is a simplified interface to
:c:func:`PyParser_SimpleParseStringFlagsFilename` below, leaving *filename* set
to *NULL*.
.. c:function:: struct _node* PyParser_SimpleParseStringFlagsFilename( const char *str, const char *filename, int start, int flags)
Parse Python source code from *str* using the start token *start* according to
the *flags* argument. The result can be used to create a code object which can
be evaluated efficiently. This is useful if a code fragment must be evaluated
many times.
.. c:function:: struct _node* PyParser_SimpleParseFile(FILE *fp, const char *filename, int start)
This is a simplified interface to :c:func:`PyParser_SimpleParseFileFlags` below,
leaving *flags* set to ``0``.
.. c:function:: struct _node* PyParser_SimpleParseFileFlags(FILE *fp, const char *filename, int start, int flags)
Similar to :c:func:`PyParser_SimpleParseStringFlagsFilename`, but the Python
source code is read from *fp* instead of an in-memory string.
.. c:function:: PyObject* PyRun_String(const char *str, int start, PyObject *globals, PyObject *locals)
This is a simplified interface to :c:func:`PyRun_StringFlags` below, leaving
*flags* set to *NULL*.
.. c:function:: PyObject* PyRun_StringFlags(const char *str, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)
Execute Python source code from *str* in the context specified by the
dictionaries *globals* and *locals* with the compiler flags specified by
*flags*. The parameter *start* specifies the start token that should be used to
parse the source code.
Returns the result of executing the code as a Python object, or *NULL* if an
exception was raised.
.. c:function:: PyObject* PyRun_File(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals)
This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving
*closeit* set to ``0`` and *flags* set to *NULL*.
.. c:function:: PyObject* PyRun_FileEx(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit)
This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving
*flags* set to *NULL*.
.. c:function:: PyObject* PyRun_FileFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)
This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving
*closeit* set to ``0``.
.. c:function:: PyObject* PyRun_FileExFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit, PyCompilerFlags *flags)
Similar to :c:func:`PyRun_StringFlags`, but the Python source code is read from
*fp* instead of an in-memory string. *filename* should be the name of the file.
If *closeit* is true, the file is closed before :c:func:`PyRun_FileExFlags`
returns.
.. c:function:: PyObject* Py_CompileString(const char *str, const char *filename, int start)
This is a simplified interface to :c:func:`Py_CompileStringFlags` below, leaving
*flags* set to *NULL*.
.. c:function:: PyObject* Py_CompileStringFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags)
Parse and compile the Python source code in *str*, returning the resulting code
object. The start token is given by *start*; this can be used to constrain the
code which can be compiled and should be :const:`Py_eval_input`,
:const:`Py_file_input`, or :const:`Py_single_input`. The filename specified by
*filename* is used to construct the code object and may appear in tracebacks or
:exc:`SyntaxError` exception messages. This returns *NULL* if the code cannot
be parsed or compiled.
.. c:function:: PyObject* PyEval_EvalCode(PyCodeObject *co, PyObject *globals, PyObject *locals)
This is a simplified interface to :c:func:`PyEval_EvalCodeEx`, with just
the code object, and the dictionaries of global and local variables.
The other arguments are set to *NULL*.
.. c:function:: PyObject* PyEval_EvalCodeEx(PyCodeObject *co, PyObject *globals, PyObject *locals, PyObject **args, int argcount, PyObject **kws, int kwcount, PyObject **defs, int defcount, PyObject *closure)
Evaluate a precompiled code object, given a particular environment for its
evaluation. This environment consists of dictionaries of global and local
variables, arrays of arguments, keywords and defaults, and a closure tuple of
cells.
.. c:function:: PyObject* PyEval_EvalFrame(PyFrameObject *f)
Evaluate an execution frame. This is a simplified interface to
PyEval_EvalFrameEx, for backward compatibility.
.. c:function:: PyObject* PyEval_EvalFrameEx(PyFrameObject *f, int throwflag)
This is the main, unvarnished function of Python interpretation. It is
literally 2000 lines long. The code object associated with the execution
frame *f* is executed, interpreting bytecode and executing calls as needed.
The additional *throwflag* parameter can mostly be ignored - if true, then
it causes an exception to immediately be thrown; this is used for the
:meth:`~generator.throw` methods of generator objects.
.. c:function:: int PyEval_MergeCompilerFlags(PyCompilerFlags *cf)
This function changes the flags of the current evaluation frame, and returns
true on success, false on failure.
.. c:var:: int Py_eval_input
.. index:: single: Py_CompileString()
The start symbol from the Python grammar for isolated expressions; for use with
:c:func:`Py_CompileString`.
.. c:var:: int Py_file_input
.. index:: single: Py_CompileString()
The start symbol from the Python grammar for sequences of statements as read
from a file or other source; for use with :c:func:`Py_CompileString`. This is
the symbol to use when compiling arbitrarily long Python source code.
.. c:var:: int Py_single_input
.. index:: single: Py_CompileString()
The start symbol from the Python grammar for a single statement; for use with
:c:func:`Py_CompileString`. This is the symbol used for the interactive
interpreter loop.
.. c:type:: struct PyCompilerFlags
This is the structure used to hold compiler flags. In cases where code is only
being compiled, it is passed as ``int flags``, and in cases where code is being
executed, it is passed as ``PyCompilerFlags *flags``. In this case, ``from
__future__ import`` can modify *flags*.
Whenever ``PyCompilerFlags *flags`` is *NULL*, :attr:`cf_flags` is treated as
equal to ``0``, and any modification due to ``from __future__ import`` is
discarded. ::
struct PyCompilerFlags {
int cf_flags;
}
.. c:var:: int CO_FUTURE_DIVISION
This bit can be set in *flags* to cause division operator ``/`` to be
interpreted as "true division" according to :pep:`238`.
PK %�\$�q9 # html/_sources/c-api/weakref.rst.txtnu �[��� .. highlightlang:: c
.. _weakrefobjects:
Weak Reference Objects
----------------------
Python supports *weak references* as first-class objects. There are two
specific object types which directly implement weak references. The first is a
simple reference object, and the second acts as a proxy for the original object
as much as it can.
.. c:function:: int PyWeakref_Check(ob)
Return true if *ob* is either a reference or proxy object.
.. versionadded:: 2.2
.. c:function:: int PyWeakref_CheckRef(ob)
Return true if *ob* is a reference object.
.. versionadded:: 2.2
.. c:function:: int PyWeakref_CheckProxy(ob)
Return true if *ob* is a proxy object.
.. versionadded:: 2.2
.. c:function:: PyObject* PyWeakref_NewRef(PyObject *ob, PyObject *callback)
Return a weak reference object for the object *ob*. This will always return
a new reference, but is not guaranteed to create a new object; an existing
reference object may be returned. The second parameter, *callback*, can be a
callable object that receives notification when *ob* is garbage collected; it
should accept a single parameter, which will be the weak reference object
itself. *callback* may also be ``None`` or *NULL*. If *ob* is not a
weakly-referencable object, or if *callback* is not callable, ``None``, or
*NULL*, this will return *NULL* and raise :exc:`TypeError`.
.. versionadded:: 2.2
.. c:function:: PyObject* PyWeakref_NewProxy(PyObject *ob, PyObject *callback)
Return a weak reference proxy object for the object *ob*. This will always
return a new reference, but is not guaranteed to create a new object; an
existing proxy object may be returned. The second parameter, *callback*, can
be a callable object that receives notification when *ob* is garbage
collected; it should accept a single parameter, which will be the weak
reference object itself. *callback* may also be ``None`` or *NULL*. If *ob*
is not a weakly-referencable object, or if *callback* is not callable,
``None``, or *NULL*, this will return *NULL* and raise :exc:`TypeError`.
.. versionadded:: 2.2
.. c:function:: PyObject* PyWeakref_GetObject(PyObject *ref)
Return the referenced object from a weak reference, *ref*. If the referent is
no longer live, returns :const:`Py_None`.
.. versionadded:: 2.2
.. warning::
This function returns a **borrowed reference** to the referenced object.
This means that you should always call :c:func:`Py_INCREF` on the object
except if you know that it cannot be destroyed while you are still
using it.
.. c:function:: PyObject* PyWeakref_GET_OBJECT(PyObject *ref)
Similar to :c:func:`PyWeakref_GetObject`, but implemented as a macro that does no
error checking.
.. versionadded:: 2.2
PK %�\��H�� � $ html/_sources/c-api/abstract.rst.txtnu �[��� .. highlightlang:: c
.. _abstract:
**********************
Abstract Objects Layer
**********************
The functions in this chapter interact with Python objects regardless of their
type, or with wide classes of object types (e.g. all numerical types, or all
sequence types). When used on object types for which they do not apply, they
will raise a Python exception.
It is not possible to use these functions on objects that are not properly
initialized, such as a list object that has been created by :c:func:`PyList_New`,
but whose items have not been set to some non-\ ``NULL`` value yet.
.. toctree::
object.rst
number.rst
sequence.rst
mapping.rst
iter.rst
objbuffer.rst
PK %�\���A� � & html/_sources/c-api/allocation.rst.txtnu �[��� .. highlightlang:: c
.. _allocating-objects:
Allocating Objects on the Heap
==============================
.. c:function:: PyObject* _PyObject_New(PyTypeObject *type)
.. c:function:: PyVarObject* _PyObject_NewVar(PyTypeObject *type, Py_ssize_t size)
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: void _PyObject_Del(PyObject *op)
.. c:function:: PyObject* PyObject_Init(PyObject *op, PyTypeObject *type)
Initialize a newly-allocated object *op* with its type and initial
reference. Returns the initialized object. If *type* indicates that the
object participates in the cyclic garbage detector, it is added to the
detector's set of observed objects. Other fields of the object are not
affected.
.. c:function:: PyVarObject* PyObject_InitVar(PyVarObject *op, PyTypeObject *type, Py_ssize_t size)
This does everything :c:func:`PyObject_Init` does, and also initializes the
length information for a variable-size object.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: TYPE* PyObject_New(TYPE, PyTypeObject *type)
Allocate a new Python object using the C structure type *TYPE* and the
Python type object *type*. Fields not defined by the Python object header
are not initialized; the object's reference count will be one. The size of
the memory allocation is determined from the :c:member:`~PyTypeObject.tp_basicsize` field of
the type object.
.. c:function:: TYPE* PyObject_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)
Allocate a new Python object using the C structure type *TYPE* and the
Python type object *type*. Fields not defined by the Python object header
are not initialized. The allocated memory allows for the *TYPE* structure
plus *size* fields of the size given by the :c:member:`~PyTypeObject.tp_itemsize` field of
*type*. This is useful for implementing objects like tuples, which are
able to determine their size at construction time. Embedding the array of
fields into the same allocation decreases the number of allocations,
improving the memory management efficiency.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: void PyObject_Del(PyObject *op)
Releases memory allocated to an object using :c:func:`PyObject_New` or
:c:func:`PyObject_NewVar`. This is normally called from the
:c:member:`~PyTypeObject.tp_dealloc` handler specified in the object's type. The fields of
the object should not be accessed after this call as the memory is no
longer a valid Python object.
.. c:function:: PyObject* Py_InitModule(char *name, PyMethodDef *methods)
Create a new module object based on a name and table of functions,
returning the new module object.
.. versionchanged:: 2.3
Older versions of Python did not support *NULL* as the value for the
*methods* argument.
.. c:function:: PyObject* Py_InitModule3(char *name, PyMethodDef *methods, char *doc)
Create a new module object based on a name and table of functions,
returning the new module object. If *doc* is non-*NULL*, it will be used
to define the docstring for the module.
.. versionchanged:: 2.3
Older versions of Python did not support *NULL* as the value for the
*methods* argument.
.. c:function:: PyObject* Py_InitModule4(char *name, PyMethodDef *methods, char *doc, PyObject *self, int apiver)
Create a new module object based on a name and table of functions,
returning the new module object. If *doc* is non-*NULL*, it will be used
to define the docstring for the module. If *self* is non-*NULL*, it will
be passed to the functions of the module as their (otherwise *NULL*) first
parameter. (This was added as an experimental feature, and there are no
known uses in the current version of Python.) For *apiver*, the only value
which should be passed is defined by the constant
:const:`PYTHON_API_VERSION`.
.. note::
Most uses of this function should probably be using the
:c:func:`Py_InitModule3` instead; only use this if you are sure you need
it.
.. versionchanged:: 2.3
Older versions of Python did not support *NULL* as the value for the
*methods* argument.
.. c:var:: PyObject _Py_NoneStruct
Object which is visible in Python as ``None``. This should only be
accessed using the ``Py_None`` macro, which evaluates to a pointer to this
object.
PK %�\��n�e �e html/_sources/c-api/arg.rst.txtnu �[��� .. highlightlang:: c
.. _arg-parsing:
Parsing arguments and building values
=====================================
These functions are useful when creating your own extensions functions and
methods. Additional information and examples are available in
:ref:`extending-index`.
The first three of these functions described, :c:func:`PyArg_ParseTuple`,
:c:func:`PyArg_ParseTupleAndKeywords`, and :c:func:`PyArg_Parse`, all use
*format strings* which are used to tell the function about the expected
arguments. The format strings use the same syntax for each of these
functions.
A format string consists of zero or more "format units." A format unit
describes one Python object; it is usually a single character or a
parenthesized sequence of format units. With a few exceptions, a format unit
that is not a parenthesized sequence normally corresponds to a single address
argument to these functions. In the following description, the quoted form is
the format unit; the entry in (round) parentheses is the Python object type
that matches the format unit; and the entry in [square] brackets is the type
of the C variable(s) whose address should be passed.
These formats allow accessing an object as a contiguous chunk of memory.
You don't have to provide raw storage for the returned unicode or bytes
area. Also, you won't have to release any memory yourself, except with the
``es``, ``es#``, ``et`` and ``et#`` formats.
``s`` (string or Unicode) [const char \*]
Convert a Python string or Unicode object to a C pointer to a character
string. You must not provide storage for the string itself; a pointer to
an existing string is stored into the character pointer variable whose
address you pass. The C string is NUL-terminated. The Python string must
not contain embedded NUL bytes; if it does, a :exc:`TypeError` exception is
raised. Unicode objects are converted to C strings using the default
encoding. If this conversion fails, a :exc:`UnicodeError` is raised.
``s#`` (string, Unicode or any read buffer compatible object) [const char \*, int (or :c:type:`Py_ssize_t`, see below)]
This variant on ``s`` stores into two C variables, the first one a pointer
to a character string, the second one its length. In this case the Python
string may contain embedded null bytes. Unicode objects pass back a
pointer to the default encoded string version of the object if such a
conversion is possible. All other read-buffer compatible objects pass back
a reference to the raw internal data representation.
Starting with Python 2.5 the type of the length argument can be controlled
by defining the macro :c:macro:`PY_SSIZE_T_CLEAN` before including
:file:`Python.h`. If the macro is defined, length is a :c:type:`Py_ssize_t`
rather than an int.
``s*`` (string, Unicode, or any buffer compatible object) [Py_buffer]
Similar to ``s#``, this code fills a Py_buffer structure provided by the
caller. The buffer gets locked, so that the caller can subsequently use
the buffer even inside a ``Py_BEGIN_ALLOW_THREADS`` block; the caller is
responsible for calling ``PyBuffer_Release`` with the structure after it
has processed the data.
.. versionadded:: 2.6
``z`` (string, Unicode or ``None``) [const char \*]
Like ``s``, but the Python object may also be ``None``, in which case the C
pointer is set to *NULL*.
``z#`` (string, Unicode, ``None`` or any read buffer compatible object) [const char \*, int]
This is to ``s#`` as ``z`` is to ``s``.
``z*`` (string, Unicode, ``None`` or any buffer compatible object) [Py_buffer]
This is to ``s*`` as ``z`` is to ``s``.
.. versionadded:: 2.6
``u`` (Unicode) [Py_UNICODE \*]
Convert a Python Unicode object to a C pointer to a NUL-terminated buffer
of 16-bit Unicode (UTF-16) data. As with ``s``, there is no need to
provide storage for the Unicode data buffer; a pointer to the existing
Unicode data is stored into the :c:type:`Py_UNICODE` pointer variable whose
address you pass.
``u#`` (Unicode) [Py_UNICODE \*, int]
This variant on ``u`` stores into two C variables, the first one a pointer
to a Unicode data buffer, the second one its length. Non-Unicode objects
are handled by interpreting their read-buffer pointer as pointer to a
:c:type:`Py_UNICODE` array.
``es`` (string, Unicode or character buffer compatible object) [const char \*encoding, char \*\*buffer]
This variant on ``s`` is used for encoding Unicode and objects convertible
to Unicode into a character buffer. It only works for encoded data without
embedded NUL bytes.
This format requires two arguments. The first is only used as input, and
must be a :c:type:`const char\*` which points to the name of an encoding as
a NUL-terminated string, or *NULL*, in which case the default encoding is
used. An exception is raised if the named encoding is not known to Python.
The second argument must be a :c:type:`char\*\*`; the value of the pointer
it references will be set to a buffer with the contents of the argument
text. The text will be encoded in the encoding specified by the first
argument.
:c:func:`PyArg_ParseTuple` will allocate a buffer of the needed size, copy
the encoded data into this buffer and adjust *\*buffer* to reference the
newly allocated storage. The caller is responsible for calling
:c:func:`PyMem_Free` to free the allocated buffer after use.
``et`` (string, Unicode or character buffer compatible object) [const char \*encoding, char \*\*buffer]
Same as ``es`` except that 8-bit string objects are passed through without
recoding them. Instead, the implementation assumes that the string object
uses the encoding passed in as parameter.
``es#`` (string, Unicode or character buffer compatible object) [const char \*encoding, char \*\*buffer, int \*buffer_length]
This variant on ``s#`` is used for encoding Unicode and objects convertible
to Unicode into a character buffer. Unlike the ``es`` format, this variant
allows input data which contains NUL characters.
It requires three arguments. The first is only used as input, and must be
a :c:type:`const char\*` which points to the name of an encoding as a
NUL-terminated string, or *NULL*, in which case the default encoding is
used. An exception is raised if the named encoding is not known to Python.
The second argument must be a :c:type:`char\*\*`; the value of the pointer
it references will be set to a buffer with the contents of the argument
text. The text will be encoded in the encoding specified by the first
argument. The third argument must be a pointer to an integer; the
referenced integer will be set to the number of bytes in the output buffer.
There are two modes of operation:
If *\*buffer* points a *NULL* pointer, the function will allocate a buffer
of the needed size, copy the encoded data into this buffer and set
*\*buffer* to reference the newly allocated storage. The caller is
responsible for calling :c:func:`PyMem_Free` to free the allocated buffer
after usage.
If *\*buffer* points to a non-*NULL* pointer (an already allocated buffer),
:c:func:`PyArg_ParseTuple` will use this location as the buffer and
interpret the initial value of *\*buffer_length* as the buffer size. It
will then copy the encoded data into the buffer and NUL-terminate it. If
the buffer is not large enough, a :exc:`TypeError` will be set.
Note: starting from Python 3.6 a :exc:`ValueError` will be set.
In both cases, *\*buffer_length* is set to the length of the encoded data
without the trailing NUL byte.
``et#`` (string, Unicode or character buffer compatible object) [const char \*encoding, char \*\*buffer, int \*buffer_length]
Same as ``es#`` except that string objects are passed through without
recoding them. Instead, the implementation assumes that the string object
uses the encoding passed in as parameter.
``b`` (integer) [unsigned char]
Convert a nonnegative Python integer to an unsigned tiny int, stored in a C
:c:type:`unsigned char`.
``B`` (integer) [unsigned char]
Convert a Python integer to a tiny int without overflow checking, stored in
a C :c:type:`unsigned char`.
.. versionadded:: 2.3
``h`` (integer) [short int]
Convert a Python integer to a C :c:type:`short int`.
``H`` (integer) [unsigned short int]
Convert a Python integer to a C :c:type:`unsigned short int`, without
overflow checking.
.. versionadded:: 2.3
``i`` (integer) [int]
Convert a Python integer to a plain C :c:type:`int`.
``I`` (integer) [unsigned int]
Convert a Python integer to a C :c:type:`unsigned int`, without overflow
checking.
.. versionadded:: 2.3
``l`` (integer) [long int]
Convert a Python integer to a C :c:type:`long int`.
``k`` (integer) [unsigned long]
Convert a Python integer or long integer to a C :c:type:`unsigned long`
without overflow checking.
.. versionadded:: 2.3
``L`` (integer) [PY_LONG_LONG]
Convert a Python integer to a C :c:type:`long long`. This format is only
available on platforms that support :c:type:`long long` (or :c:type:`_int64`
on Windows).
``K`` (integer) [unsigned PY_LONG_LONG]
Convert a Python integer or long integer to a C :c:type:`unsigned long long`
without overflow checking. This format is only available on platforms that
support :c:type:`unsigned long long` (or :c:type:`unsigned _int64` on
Windows).
.. versionadded:: 2.3
``n`` (integer) [Py_ssize_t]
Convert a Python integer or long integer to a C :c:type:`Py_ssize_t`.
.. versionadded:: 2.5
``c`` (string of length 1) [char]
Convert a Python character, represented as a string of length 1, to a C
:c:type:`char`.
``f`` (float) [float]
Convert a Python floating point number to a C :c:type:`float`.
``d`` (float) [double]
Convert a Python floating point number to a C :c:type:`double`.
``D`` (complex) [Py_complex]
Convert a Python complex number to a C :c:type:`Py_complex` structure.
``O`` (object) [PyObject \*]
Store a Python object (without any conversion) in a C object pointer. The
C program thus receives the actual object that was passed. The object's
reference count is not increased. The pointer stored is not *NULL*.
``O!`` (object) [*typeobject*, PyObject \*]
Store a Python object in a C object pointer. This is similar to ``O``, but
takes two C arguments: the first is the address of a Python type object,
the second is the address of the C variable (of type :c:type:`PyObject\*`)
into which the object pointer is stored. If the Python object does not
have the required type, :exc:`TypeError` is raised.
``O&`` (object) [*converter*, *anything*]
Convert a Python object to a C variable through a *converter* function.
This takes two arguments: the first is a function, the second is the
address of a C variable (of arbitrary type), converted to :c:type:`void \*`.
The *converter* function in turn is called as follows::
status = converter(object, address);
where *object* is the Python object to be converted and *address* is the
:c:type:`void\*` argument that was passed to the :c:func:`PyArg_Parse\*`
function. The returned *status* should be ``1`` for a successful
conversion and ``0`` if the conversion has failed. When the conversion
fails, the *converter* function should raise an exception and leave the
content of *address* unmodified.
``S`` (string) [PyStringObject \*]
Like ``O`` but requires that the Python object is a string object. Raises
:exc:`TypeError` if the object is not a string object. The C variable may
also be declared as :c:type:`PyObject\*`.
``U`` (Unicode string) [PyUnicodeObject \*]
Like ``O`` but requires that the Python object is a Unicode object. Raises
:exc:`TypeError` if the object is not a Unicode object. The C variable may
also be declared as :c:type:`PyObject\*`.
``t#`` (read-only character buffer) [char \*, int]
Like ``s#``, but accepts any object which implements the read-only buffer
interface. The :c:type:`char\*` variable is set to point to the first byte
of the buffer, and the :c:type:`int` is set to the length of the buffer.
Only single-segment buffer objects are accepted; :exc:`TypeError` is raised
for all others.
``w`` (read-write character buffer) [char \*]
Similar to ``s``, but accepts any object which implements the read-write
buffer interface. The caller must determine the length of the buffer by
other means, or use ``w#`` instead. Only single-segment buffer objects are
accepted; :exc:`TypeError` is raised for all others.
``w#`` (read-write character buffer) [char \*, Py_ssize_t]
Like ``s#``, but accepts any object which implements the read-write buffer
interface. The :c:type:`char \*` variable is set to point to the first byte
of the buffer, and the :c:type:`Py_ssize_t` is set to the length of the
buffer. Only single-segment buffer objects are accepted; :exc:`TypeError`
is raised for all others.
``w*`` (read-write byte-oriented buffer) [Py_buffer]
This is to ``w`` what ``s*`` is to ``s``.
.. versionadded:: 2.6
``(items)`` (tuple) [*matching-items*]
The object must be a Python sequence whose length is the number of format
units in *items*. The C arguments must correspond to the individual format
units in *items*. Format units for sequences may be nested.
.. note::
Prior to Python version 1.5.2, this format specifier only accepted a
tuple containing the individual parameters, not an arbitrary sequence.
Code which previously caused :exc:`TypeError` to be raised here may now
proceed without an exception. This is not expected to be a problem for
existing code.
It is possible to pass Python long integers where integers are requested;
however no proper range checking is done --- the most significant bits are
silently truncated when the receiving field is too small to receive the value
(actually, the semantics are inherited from downcasts in C --- your mileage
may vary).
A few other characters have a meaning in a format string. These may not occur
inside nested parentheses. They are:
``|``
Indicates that the remaining arguments in the Python argument list are
optional. The C variables corresponding to optional arguments should be
initialized to their default value --- when an optional argument is not
specified, :c:func:`PyArg_ParseTuple` does not touch the contents of the
corresponding C variable(s).
``:``
The list of format units ends here; the string after the colon is used as
the function name in error messages (the "associated value" of the
exception that :c:func:`PyArg_ParseTuple` raises).
``;``
The list of format units ends here; the string after the semicolon is used
as the error message *instead* of the default error message. ``:`` and
``;`` mutually exclude each other.
Note that any Python object references which are provided to the caller are
*borrowed* references; do not decrement their reference count!
Additional arguments passed to these functions must be addresses of variables
whose type is determined by the format string; these are used to store values
from the input tuple. There are a few cases, as described in the list of
format units above, where these parameters are used as input values; they
should match what is specified for the corresponding format unit in that case.
For the conversion to succeed, the *arg* object must match the format and the
format must be exhausted. On success, the :c:func:`PyArg_Parse\*` functions
return true, otherwise they return false and raise an appropriate exception.
When the :c:func:`PyArg_Parse\*` functions fail due to conversion failure in
one of the format units, the variables at the addresses corresponding to that
and the following format units are left untouched.
.. c:function:: int PyArg_ParseTuple(PyObject *args, const char *format, ...)
Parse the parameters of a function that takes only positional parameters
into local variables. Returns true on success; on failure, it returns
false and raises the appropriate exception.
.. c:function:: int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)
Identical to :c:func:`PyArg_ParseTuple`, except that it accepts a va_list
rather than a variable number of arguments.
.. c:function:: int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], ...)
Parse the parameters of a function that takes both positional and keyword
parameters into local variables. Returns true on success; on failure, it
returns false and raises the appropriate exception.
.. c:function:: int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], va_list vargs)
Identical to :c:func:`PyArg_ParseTupleAndKeywords`, except that it accepts a
va_list rather than a variable number of arguments.
.. c:function:: int PyArg_Parse(PyObject *args, const char *format, ...)
Function used to deconstruct the argument lists of "old-style" functions
--- these are functions which use the :const:`METH_OLDARGS` parameter
parsing method. This is not recommended for use in parameter parsing in
new code, and most code in the standard interpreter has been modified to no
longer use this for that purpose. It does remain a convenient way to
decompose other tuples, however, and may continue to be used for that
purpose.
.. c:function:: int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)
A simpler form of parameter retrieval which does not use a format string to
specify the types of the arguments. Functions which use this method to
retrieve their parameters should be declared as :const:`METH_VARARGS` in
function or method tables. The tuple containing the actual parameters
should be passed as *args*; it must actually be a tuple. The length of the
tuple must be at least *min* and no more than *max*; *min* and *max* may be
equal. Additional arguments must be passed to the function, each of which
should be a pointer to a :c:type:`PyObject\*` variable; these will be filled
in with the values from *args*; they will contain borrowed references. The
variables which correspond to optional parameters not given by *args* will
not be filled in; these should be initialized by the caller. This function
returns true on success and false if *args* is not a tuple or contains the
wrong number of elements; an exception will be set if there was a failure.
This is an example of the use of this function, taken from the sources for
the :mod:`_weakref` helper module for weak references::
static PyObject *
weakref_ref(PyObject *self, PyObject *args)
{
PyObject *object;
PyObject *callback = NULL;
PyObject *result = NULL;
if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) {
result = PyWeakref_NewRef(object, callback);
}
return result;
}
The call to :c:func:`PyArg_UnpackTuple` in this example is entirely
equivalent to this call to :c:func:`PyArg_ParseTuple`::
PyArg_ParseTuple(args, "O|O:ref", &object, &callback)
.. versionadded:: 2.2
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *min* and *max*. This might
require changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* Py_BuildValue(const char *format, ...)
Create a new value based on a format string similar to those accepted by
the :c:func:`PyArg_Parse\*` family of functions and a sequence of values.
Returns the value or *NULL* in the case of an error; an exception will be
raised if *NULL* is returned.
:c:func:`Py_BuildValue` does not always build a tuple. It builds a tuple
only if its format string contains two or more format units. If the format
string is empty, it returns ``None``; if it contains exactly one format
unit, it returns whatever object is described by that format unit. To
force it to return a tuple of size ``0`` or one, parenthesize the format
string.
When memory buffers are passed as parameters to supply data to build
objects, as for the ``s`` and ``s#`` formats, the required data is copied.
Buffers provided by the caller are never referenced by the objects created
by :c:func:`Py_BuildValue`. In other words, if your code invokes
:c:func:`malloc` and passes the allocated memory to :c:func:`Py_BuildValue`,
your code is responsible for calling :c:func:`free` for that memory once
:c:func:`Py_BuildValue` returns.
In the following description, the quoted form is the format unit; the entry
in (round) parentheses is the Python object type that the format unit will
return; and the entry in [square] brackets is the type of the C value(s) to
be passed.
The characters space, tab, colon and comma are ignored in format strings
(but not within format units such as ``s#``). This can be used to make
long format strings a tad more readable.
``s`` (string) [char \*]
Convert a null-terminated C string to a Python object. If the C string
pointer is *NULL*, ``None`` is used.
``s#`` (string) [char \*, int]
Convert a C string and its length to a Python object. If the C string
pointer is *NULL*, the length is ignored and ``None`` is returned.
``z`` (string or ``None``) [char \*]
Same as ``s``.
``z#`` (string or ``None``) [char \*, int]
Same as ``s#``.
``u`` (Unicode string) [Py_UNICODE \*]
Convert a null-terminated buffer of Unicode (UCS-2 or UCS-4) data to a
Python Unicode object. If the Unicode buffer pointer is *NULL*,
``None`` is returned.
``u#`` (Unicode string) [Py_UNICODE \*, int]
Convert a Unicode (UCS-2 or UCS-4) data buffer and its length to a
Python Unicode object. If the Unicode buffer pointer is *NULL*, the
length is ignored and ``None`` is returned.
``i`` (integer) [int]
Convert a plain C :c:type:`int` to a Python integer object.
``b`` (integer) [char]
Convert a plain C :c:type:`char` to a Python integer object.
``h`` (integer) [short int]
Convert a plain C :c:type:`short int` to a Python integer object.
``l`` (integer) [long int]
Convert a C :c:type:`long int` to a Python integer object.
``B`` (integer) [unsigned char]
Convert a C :c:type:`unsigned char` to a Python integer object.
``H`` (integer) [unsigned short int]
Convert a C :c:type:`unsigned short int` to a Python integer object.
``I`` (integer/long) [unsigned int]
Convert a C :c:type:`unsigned int` to a Python integer object or a Python
long integer object, if it is larger than ``sys.maxint``.
``k`` (integer/long) [unsigned long]
Convert a C :c:type:`unsigned long` to a Python integer object or a
Python long integer object, if it is larger than ``sys.maxint``.
``L`` (long) [PY_LONG_LONG]
Convert a C :c:type:`long long` to a Python long integer object. Only
available on platforms that support :c:type:`long long`.
``K`` (long) [unsigned PY_LONG_LONG]
Convert a C :c:type:`unsigned long long` to a Python long integer object.
Only available on platforms that support :c:type:`unsigned long long`.
``n`` (int) [Py_ssize_t]
Convert a C :c:type:`Py_ssize_t` to a Python integer or long integer.
.. versionadded:: 2.5
``c`` (string of length 1) [char]
Convert a C :c:type:`int` representing a character to a Python string of
length 1.
``d`` (float) [double]
Convert a C :c:type:`double` to a Python floating point number.
``f`` (float) [float]
Same as ``d``.
``D`` (complex) [Py_complex \*]
Convert a C :c:type:`Py_complex` structure to a Python complex number.
``O`` (object) [PyObject \*]
Pass a Python object untouched (except for its reference count, which is
incremented by one). If the object passed in is a *NULL* pointer, it is
assumed that this was caused because the call producing the argument
found an error and set an exception. Therefore, :c:func:`Py_BuildValue`
will return *NULL* but won't raise an exception. If no exception has
been raised yet, :exc:`SystemError` is set.
``S`` (object) [PyObject \*]
Same as ``O``.
``N`` (object) [PyObject \*]
Same as ``O``, except it doesn't increment the reference count on the
object. Useful when the object is created by a call to an object
constructor in the argument list.
``O&`` (object) [*converter*, *anything*]
Convert *anything* to a Python object through a *converter* function.
The function is called with *anything* (which should be compatible with
:c:type:`void \*`) as its argument and should return a "new" Python
object, or *NULL* if an error occurred.
``(items)`` (tuple) [*matching-items*]
Convert a sequence of C values to a Python tuple with the same number of
items.
``[items]`` (list) [*matching-items*]
Convert a sequence of C values to a Python list with the same number of
items.
``{items}`` (dictionary) [*matching-items*]
Convert a sequence of C values to a Python dictionary. Each pair of
consecutive C values adds one item to the dictionary, serving as key and
value, respectively.
If there is an error in the format string, the :exc:`SystemError` exception
is set and *NULL* returned.
.. c:function:: PyObject* Py_VaBuildValue(const char *format, va_list vargs)
Identical to :c:func:`Py_BuildValue`, except that it accepts a va_list
rather than a variable number of arguments.
PK %�\
��2 html/_sources/c-api/bool.rst.txtnu �[��� .. highlightlang:: c
.. _boolobjects:
Boolean Objects
---------------
Booleans in Python are implemented as a subclass of integers. There are only
two booleans, :const:`Py_False` and :const:`Py_True`. As such, the normal
creation and deletion functions don't apply to booleans. The following macros
are available, however.
.. c:function:: int PyBool_Check(PyObject *o)
Return true if *o* is of type :c:data:`PyBool_Type`.
.. versionadded:: 2.3
.. c:var:: PyObject* Py_False
The Python ``False`` object. This object has no methods. It needs to be
treated just like any other object with respect to reference counts.
.. c:var:: PyObject* Py_True
The Python ``True`` object. This object has no methods. It needs to be treated
just like any other object with respect to reference counts.
.. c:macro:: Py_RETURN_FALSE
Return :const:`Py_False` from a function, properly incrementing its reference
count.
.. versionadded:: 2.4
.. c:macro:: Py_RETURN_TRUE
Return :const:`Py_True` from a function, properly incrementing its reference
count.
.. versionadded:: 2.4
.. c:function:: PyObject* PyBool_FromLong(long v)
Return a new reference to :const:`Py_True` or :const:`Py_False` depending on the
truth value of *v*.
.. versionadded:: 2.3
PK %�\�Wf�Y �Y " html/_sources/c-api/buffer.rst.txtnu �[��� .. highlightlang:: c
.. _bufferobjects:
Buffers and Memoryview Objects
------------------------------
.. sectionauthor:: Greg Stein <gstein@lyra.org>
.. sectionauthor:: Benjamin Peterson
.. index::
object: buffer
single: buffer interface
Python objects implemented in C can export a group of functions called the
"buffer interface." These functions can be used by an object to expose its
data in a raw, byte-oriented format. Clients of the object can use the buffer
interface to access the object data directly, without needing to copy it
first.
Two examples of objects that support the buffer interface are strings and
arrays. The string object exposes the character contents in the buffer
interface's byte-oriented form. An array can only expose its contents via the
old-style buffer interface. This limitation does not apply to Python 3,
where :class:`memoryview` objects can be constructed from arrays, too.
Array elements may be multi-byte values.
An example user of the buffer interface is the file object's :meth:`write`
method. Any object that can export a series of bytes through the buffer
interface can be written to a file. There are a number of format codes to
:c:func:`PyArg_ParseTuple` that operate against an object's buffer interface,
returning data from the target object.
Starting from version 1.6, Python has been providing Python-level buffer
objects and a C-level buffer API so that any built-in or used-defined type can
expose its characteristics. Both, however, have been deprecated because of
various shortcomings, and have been officially removed in Python 3 in favour
of a new C-level buffer API and a new Python-level object named
:class:`memoryview`.
The new buffer API has been backported to Python 2.6, and the
:class:`memoryview` object has been backported to Python 2.7. It is strongly
advised to use them rather than the old APIs, unless you are blocked from
doing so for compatibility reasons.
The new-style Py_buffer struct
==============================
.. c:type:: Py_buffer
.. c:member:: void *buf
A pointer to the start of the memory for the object.
.. c:member:: Py_ssize_t len
:noindex:
The total length of the memory in bytes.
.. c:member:: int readonly
An indicator of whether the buffer is read only.
.. c:member:: const char *format
:noindex:
A *NULL* terminated string in :mod:`struct` module style syntax giving
the contents of the elements available through the buffer. If this is
*NULL*, ``"B"`` (unsigned bytes) is assumed.
.. c:member:: int ndim
The number of dimensions the memory represents as a multi-dimensional
array. If it is ``0``, :c:data:`strides` and :c:data:`suboffsets` must be
*NULL*.
.. c:member:: Py_ssize_t *shape
An array of :c:type:`Py_ssize_t`\s the length of :c:data:`ndim` giving the
shape of the memory as a multi-dimensional array. Note that
``((*shape)[0] * ... * (*shape)[ndims-1])*itemsize`` should be equal to
:c:data:`len`.
.. c:member:: Py_ssize_t *strides
An array of :c:type:`Py_ssize_t`\s the length of :c:data:`ndim` giving the
number of bytes to skip to get to a new element in each dimension.
.. c:member:: Py_ssize_t *suboffsets
An array of :c:type:`Py_ssize_t`\s the length of :c:data:`ndim`. If these
suboffset numbers are greater than or equal to 0, then the value stored
along the indicated dimension is a pointer and the suboffset value
dictates how many bytes to add to the pointer after de-referencing. A
suboffset value that it negative indicates that no de-referencing should
occur (striding in a contiguous memory block).
If all suboffsets are negative (i.e. no de-referencing is needed), then
this field must be NULL (the default value).
Here is a function that returns a pointer to the element in an N-D array
pointed to by an N-dimensional index when there are both non-NULL strides
and suboffsets::
void *get_item_pointer(int ndim, void *buf, Py_ssize_t *strides,
Py_ssize_t *suboffsets, Py_ssize_t *indices) {
char *pointer = (char*)buf;
int i;
for (i = 0; i < ndim; i++) {
pointer += strides[i] * indices[i];
if (suboffsets[i] >=0 ) {
pointer = *((char**)pointer) + suboffsets[i];
}
}
return (void*)pointer;
}
.. c:member:: Py_ssize_t itemsize
This is a storage for the itemsize (in bytes) of each element of the
shared memory. It is technically un-necessary as it can be obtained
using :c:func:`PyBuffer_SizeFromFormat`, however an exporter may know
this information without parsing the format string and it is necessary
to know the itemsize for proper interpretation of striding. Therefore,
storing it is more convenient and faster.
.. c:member:: void *internal
This is for use internally by the exporting object. For example, this
might be re-cast as an integer by the exporter and used to store flags
about whether or not the shape, strides, and suboffsets arrays must be
freed when the buffer is released. The consumer should never alter this
value.
Buffer related functions
========================
.. c:function:: int PyObject_CheckBuffer(PyObject *obj)
Return ``1`` if *obj* supports the buffer interface otherwise ``0``.
.. c:function:: int PyObject_GetBuffer(PyObject *obj, Py_buffer *view, int flags)
Export *obj* into a :c:type:`Py_buffer`, *view*. These arguments must
never be *NULL*. The *flags* argument is a bit field indicating what
kind of buffer the caller is prepared to deal with and therefore what
kind of buffer the exporter is allowed to return. The buffer interface
allows for complicated memory sharing possibilities, but some caller may
not be able to handle all the complexity but may want to see if the
exporter will let them take a simpler view to its memory.
Some exporters may not be able to share memory in every possible way and
may need to raise errors to signal to some consumers that something is
just not possible. These errors should be a :exc:`BufferError` unless
there is another error that is actually causing the problem. The
exporter can use flags information to simplify how much of the
:c:data:`Py_buffer` structure is filled in with non-default values and/or
raise an error if the object can't support a simpler view of its memory.
``0`` is returned on success and ``-1`` on error.
The following table gives possible values to the *flags* arguments.
+-------------------------------+---------------------------------------------------+
| Flag | Description |
+===============================+===================================================+
| :c:macro:`PyBUF_SIMPLE` | This is the default flag state. The returned |
| | buffer may or may not have writable memory. The |
| | format of the data will be assumed to be unsigned |
| | bytes. This is a "stand-alone" flag constant. It |
| | never needs to be '|'d to the others. The exporter|
| | will raise an error if it cannot provide such a |
| | contiguous buffer of bytes. |
| | |
+-------------------------------+---------------------------------------------------+
| :c:macro:`PyBUF_WRITABLE` | The returned buffer must be writable. If it is |
| | not writable, then raise an error. |
+-------------------------------+---------------------------------------------------+
| :c:macro:`PyBUF_STRIDES` | This implies :c:macro:`PyBUF_ND`. The returned |
| | buffer must provide strides information (i.e. the |
| | strides cannot be NULL). This would be used when |
| | the consumer can handle strided, discontiguous |
| | arrays. Handling strides automatically assumes |
| | you can handle shape. The exporter can raise an |
| | error if a strided representation of the data is |
| | not possible (i.e. without the suboffsets). |
| | |
+-------------------------------+---------------------------------------------------+
| :c:macro:`PyBUF_ND` | The returned buffer must provide shape |
| | information. The memory will be assumed C-style |
| | contiguous (last dimension varies the |
| | fastest). The exporter may raise an error if it |
| | cannot provide this kind of contiguous buffer. If |
| | this is not given then shape will be *NULL*. |
| | |
| | |
| | |
+-------------------------------+---------------------------------------------------+
|:c:macro:`PyBUF_C_CONTIGUOUS` | These flags indicate that the contiguity returned |
|:c:macro:`PyBUF_F_CONTIGUOUS` | buffer must be respectively, C-contiguous (last |
|:c:macro:`PyBUF_ANY_CONTIGUOUS`| dimension varies the fastest), Fortran contiguous |
| | (first dimension varies the fastest) or either |
| | one. All of these flags imply |
| | :c:macro:`PyBUF_STRIDES` and guarantee that the |
| | strides buffer info structure will be filled in |
| | correctly. |
| | |
+-------------------------------+---------------------------------------------------+
| :c:macro:`PyBUF_INDIRECT` | This flag indicates the returned buffer must have |
| | suboffsets information (which can be NULL if no |
| | suboffsets are needed). This can be used when |
| | the consumer can handle indirect array |
| | referencing implied by these suboffsets. This |
| | implies :c:macro:`PyBUF_STRIDES`. |
| | |
| | |
| | |
+-------------------------------+---------------------------------------------------+
| :c:macro:`PyBUF_FORMAT` | The returned buffer must have true format |
| | information if this flag is provided. This would |
| | be used when the consumer is going to be checking |
| | for what 'kind' of data is actually stored. An |
| | exporter should always be able to provide this |
| | information if requested. If format is not |
| | explicitly requested then the format must be |
| | returned as *NULL* (which means ``'B'``, or |
| | unsigned bytes) |
+-------------------------------+---------------------------------------------------+
| :c:macro:`PyBUF_STRIDED` | This is equivalent to ``(PyBUF_STRIDES | |
| | PyBUF_WRITABLE)``. |
+-------------------------------+---------------------------------------------------+
| :c:macro:`PyBUF_STRIDED_RO` | This is equivalent to ``(PyBUF_STRIDES)``. |
| | |
+-------------------------------+---------------------------------------------------+
| :c:macro:`PyBUF_RECORDS` | This is equivalent to ``(PyBUF_STRIDES | |
| | PyBUF_FORMAT | PyBUF_WRITABLE)``. |
+-------------------------------+---------------------------------------------------+
| :c:macro:`PyBUF_RECORDS_RO` | This is equivalent to ``(PyBUF_STRIDES | |
| | PyBUF_FORMAT)``. |
+-------------------------------+---------------------------------------------------+
| :c:macro:`PyBUF_FULL` | This is equivalent to ``(PyBUF_INDIRECT | |
| | PyBUF_FORMAT | PyBUF_WRITABLE)``. |
+-------------------------------+---------------------------------------------------+
| :c:macro:`PyBUF_FULL_RO` | This is equivalent to ``(PyBUF_INDIRECT | |
| | PyBUF_FORMAT)``. |
+-------------------------------+---------------------------------------------------+
| :c:macro:`PyBUF_CONTIG` | This is equivalent to ``(PyBUF_ND | |
| | PyBUF_WRITABLE)``. |
+-------------------------------+---------------------------------------------------+
| :c:macro:`PyBUF_CONTIG_RO` | This is equivalent to ``(PyBUF_ND)``. |
| | |
+-------------------------------+---------------------------------------------------+
.. c:function:: void PyBuffer_Release(Py_buffer *view)
Release the buffer *view*. This should be called when the buffer
is no longer being used as it may free memory from it.
.. c:function:: Py_ssize_t PyBuffer_SizeFromFormat(const char *)
Return the implied :c:data:`~Py_buffer.itemsize` from the struct-stype
:c:data:`~Py_buffer.format`.
.. c:function:: int PyBuffer_IsContiguous(Py_buffer *view, char fortran)
Return ``1`` if the memory defined by the *view* is C-style (*fortran* is
``'C'``) or Fortran-style (*fortran* is ``'F'``) contiguous or either one
(*fortran* is ``'A'``). Return ``0`` otherwise.
.. c:function:: void PyBuffer_FillContiguousStrides(int ndims, Py_ssize_t *shape, Py_ssize_t *strides, int itemsize, char fortran)
Fill the *strides* array with byte-strides of a contiguous (C-style if
*fortran* is ``'C'`` or Fortran-style if *fortran* is ``'F'``) array of the
given shape with the given number of bytes per element.
.. c:function:: int PyBuffer_FillInfo(Py_buffer *view, PyObject *obj, void *buf, Py_ssize_t len, int readonly, int infoflags)
Fill in a buffer-info structure, *view*, correctly for an exporter that can
only share a contiguous chunk of memory of "unsigned bytes" of the given
length. Return ``0`` on success and ``-1`` (with raising an error) on error.
MemoryView objects
==================
.. versionadded:: 2.7
A :class:`memoryview` object exposes the new C level buffer interface as a
Python object which can then be passed around like any other object.
.. c:function:: PyObject *PyMemoryView_FromObject(PyObject *obj)
Create a memoryview object from an object that defines the new buffer
interface.
.. c:function:: PyObject *PyMemoryView_FromBuffer(Py_buffer *view)
Create a memoryview object wrapping the given buffer-info structure *view*.
The memoryview object then owns the buffer, which means you shouldn't
try to release it yourself: it will be released on deallocation of the
memoryview object.
.. c:function:: PyObject *PyMemoryView_GetContiguous(PyObject *obj, int buffertype, char order)
Create a memoryview object to a contiguous chunk of memory (in either
'C' or 'F'ortran *order*) from an object that defines the buffer
interface. If memory is contiguous, the memoryview object points to the
original memory. Otherwise copy is made and the memoryview points to a
new bytes object.
.. c:function:: int PyMemoryView_Check(PyObject *obj)
Return true if the object *obj* is a memoryview object. It is not
currently allowed to create subclasses of :class:`memoryview`.
.. c:function:: Py_buffer *PyMemoryView_GET_BUFFER(PyObject *obj)
Return a pointer to the buffer-info structure wrapped by the given
object. The object **must** be a memoryview instance; this macro doesn't
check its type, you must do it yourself or you will risk crashes.
Old-style buffer objects
========================
.. index:: single: PyBufferProcs
More information on the old buffer interface is provided in the section
:ref:`buffer-structs`, under the description for :c:type:`PyBufferProcs`.
A "buffer object" is defined in the :file:`bufferobject.h` header (included by
:file:`Python.h`). These objects look very similar to string objects at the
Python programming level: they support slicing, indexing, concatenation, and
some other standard string operations. However, their data can come from one
of two sources: from a block of memory, or from another object which exports
the buffer interface.
Buffer objects are useful as a way to expose the data from another object's
buffer interface to the Python programmer. They can also be used as a
zero-copy slicing mechanism. Using their ability to reference a block of
memory, it is possible to expose any data to the Python programmer quite
easily. The memory could be a large, constant array in a C extension, it could
be a raw block of memory for manipulation before passing to an operating
system library, or it could be used to pass around structured data in its
native, in-memory format.
.. c:type:: PyBufferObject
This subtype of :c:type:`PyObject` represents a buffer object.
.. c:var:: PyTypeObject PyBuffer_Type
.. index:: single: BufferType (in module types)
The instance of :c:type:`PyTypeObject` which represents the Python buffer type;
it is the same object as ``buffer`` and ``types.BufferType`` in the Python
layer. .
.. c:var:: int Py_END_OF_BUFFER
This constant may be passed as the *size* parameter to
:c:func:`PyBuffer_FromObject` or :c:func:`PyBuffer_FromReadWriteObject`. It
indicates that the new :c:type:`PyBufferObject` should refer to *base*
object from the specified *offset* to the end of its exported buffer.
Using this enables the caller to avoid querying the *base* object for its
length.
.. c:function:: int PyBuffer_Check(PyObject *p)
Return true if the argument has type :c:data:`PyBuffer_Type`.
.. c:function:: PyObject* PyBuffer_FromObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size)
Return a new read-only buffer object. This raises :exc:`TypeError` if
*base* doesn't support the read-only buffer protocol or doesn't provide
exactly one buffer segment, or it raises :exc:`ValueError` if *offset* is
less than zero. The buffer will hold a reference to the *base* object, and
the buffer's contents will refer to the *base* object's buffer interface,
starting as position *offset* and extending for *size* bytes. If *size* is
:const:`Py_END_OF_BUFFER`, then the new buffer's contents extend to the
length of the *base* object's exported buffer data.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *offset* and *size*. This
might require changes in your code for properly supporting 64-bit
systems.
.. c:function:: PyObject* PyBuffer_FromReadWriteObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size)
Return a new writable buffer object. Parameters and exceptions are similar
to those for :c:func:`PyBuffer_FromObject`. If the *base* object does not
export the writeable buffer protocol, then :exc:`TypeError` is raised.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *offset* and *size*. This
might require changes in your code for properly supporting 64-bit
systems.
.. c:function:: PyObject* PyBuffer_FromMemory(void *ptr, Py_ssize_t size)
Return a new read-only buffer object that reads from a specified location
in memory, with a specified size. The caller is responsible for ensuring
that the memory buffer, passed in as *ptr*, is not deallocated while the
returned buffer object exists. Raises :exc:`ValueError` if *size* is less
than zero. Note that :const:`Py_END_OF_BUFFER` may *not* be passed for the
*size* parameter; :exc:`ValueError` will be raised in that case.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyBuffer_FromReadWriteMemory(void *ptr, Py_ssize_t size)
Similar to :c:func:`PyBuffer_FromMemory`, but the returned buffer is
writable.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: PyObject* PyBuffer_New(Py_ssize_t size)
Return a new writable buffer object that maintains its own memory buffer of
*size* bytes. :exc:`ValueError` is returned if *size* is not zero or
positive. Note that the memory buffer (as returned by
:c:func:`PyObject_AsWriteBuffer`) is not specifically aligned.
.. versionchanged:: 2.5
This function used an :c:type:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
PK %�\D��T� � % html/_sources/c-api/bytearray.rst.txtnu �[��� .. highlightlang:: c
.. _bytearrayobjects:
Byte Array Objects
------------------
.. index:: object: bytearray
.. versionadded:: 2.6
.. c:type:: PyByteArrayObject
This subtype of :c:type:`PyObject` represents a Python bytearray object.
.. c:var:: PyTypeObject PyByteArray_Type
This instance of :c:type:`PyTypeObject` represents the Python bytearray type;
it is the same object as ``bytearray`` in the Python layer.
Type check macros
^^^^^^^^^^^^^^^^^
.. c:function:: int PyByteArray_Check(PyObject *o)
Return true if the object *o* is a bytearray object or an instance of a
subtype of the bytearray type.
.. c:function:: int PyByteArray_CheckExact(PyObject *o)
Return true if the object *o* is a bytearray object, but not an instance of a
subtype of the bytearray type.
Direct API functions
^^^^^^^^^^^^^^^^^^^^
.. c:function:: PyObject* PyByteArray_FromObject(PyObject *o)
Return a new bytearray object from any object, *o*, that implements the
buffer protocol.
.. XXX expand about the buffer protocol, at least somewhere
.. c:function:: PyObject* PyByteArray_FromStringAndSize(const char *string, Py_ssize_t len)
Create a new bytearray object from *string* and its length, *len*. On
failure, *NULL* is returned.
.. c:function:: PyObject* PyByteArray_Concat(PyObject *a, PyObject *b)
Concat bytearrays *a* and *b* and return a new bytearray with the result.
.. c:function:: Py_ssize_t PyByteArray_Size(PyObject *bytearray)
Return the size of *bytearray* after checking for a *NULL* pointer.
.. c:function:: char* PyByteArray_AsString(PyObject *bytearray)
Return the contents of *bytearray* as a char array after checking for a
*NULL* pointer.
.. c:function:: int PyByteArray_Resize(PyObject *bytearray, Py_ssize_t len)
Resize the internal buffer of *bytearray* to *len*.
Macros
^^^^^^
These macros trade safety for speed and they don't check pointers.
.. c:function:: char* PyByteArray_AS_STRING(PyObject *bytearray)
Macro version of :c:func:`PyByteArray_AsString`.
.. c:function:: Py_ssize_t PyByteArray_GET_SIZE(PyObject *bytearray)
Macro version of :c:func:`PyByteArray_Size`.
PK %�\�
�mm m # html/_sources/c-api/capsule.rst.txtnu �[��� .. highlightlang:: c
.. _capsules:
Capsules
--------
.. index:: object: Capsule
Refer to :ref:`using-capsules` for more information on using these objects.
.. versionadded:: 2.7
.. c:type:: PyCapsule
This subtype of :c:type:`PyObject` represents an opaque value, useful for C
extension modules who need to pass an opaque value (as a :c:type:`void\*`
pointer) through Python code to other C code. It is often used to make a C
function pointer defined in one module available to other modules, so the
regular import mechanism can be used to access C APIs defined in dynamically
loaded modules.
.. c:type:: PyCapsule_Destructor
The type of a destructor callback for a capsule. Defined as::
typedef void (*PyCapsule_Destructor)(PyObject *);
See :c:func:`PyCapsule_New` for the semantics of PyCapsule_Destructor
callbacks.
.. c:function:: int PyCapsule_CheckExact(PyObject *p)
Return true if its argument is a :c:type:`PyCapsule`.
.. c:function:: PyObject* PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)
Create a :c:type:`PyCapsule` encapsulating the *pointer*. The *pointer*
argument may not be *NULL*.
On failure, set an exception and return *NULL*.
The *name* string may either be *NULL* or a pointer to a valid C string. If
non-*NULL*, this string must outlive the capsule. (Though it is permitted to
free it inside the *destructor*.)
If the *destructor* argument is not *NULL*, it will be called with the
capsule as its argument when it is destroyed.
If this capsule will be stored as an attribute of a module, the *name* should
be specified as ``modulename.attributename``. This will enable other modules
to import the capsule using :c:func:`PyCapsule_Import`.
.. c:function:: void* PyCapsule_GetPointer(PyObject *capsule, const char *name)
Retrieve the *pointer* stored in the capsule. On failure, set an exception
and return *NULL*.
The *name* parameter must compare exactly to the name stored in the capsule.
If the name stored in the capsule is *NULL*, the *name* passed in must also
be *NULL*. Python uses the C function :c:func:`strcmp` to compare capsule
names.
.. c:function:: PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)
Return the current destructor stored in the capsule. On failure, set an
exception and return *NULL*.
It is legal for a capsule to have a *NULL* destructor. This makes a *NULL*
return code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or
:c:func:`PyErr_Occurred` to disambiguate.
.. c:function:: void* PyCapsule_GetContext(PyObject *capsule)
Return the current context stored in the capsule. On failure, set an
exception and return *NULL*.
It is legal for a capsule to have a *NULL* context. This makes a *NULL*
return code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or
:c:func:`PyErr_Occurred` to disambiguate.
.. c:function:: const char* PyCapsule_GetName(PyObject *capsule)
Return the current name stored in the capsule. On failure, set an exception
and return *NULL*.
It is legal for a capsule to have a *NULL* name. This makes a *NULL* return
code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or
:c:func:`PyErr_Occurred` to disambiguate.
.. c:function:: void* PyCapsule_Import(const char *name, int no_block)
Import a pointer to a C object from a capsule attribute in a module. The
*name* parameter should specify the full name to the attribute, as in
``module.attribute``. The *name* stored in the capsule must match this
string exactly. If *no_block* is true, import the module without blocking
(using :c:func:`PyImport_ImportModuleNoBlock`). If *no_block* is false,
import the module conventionally (using :c:func:`PyImport_ImportModule`).
Return the capsule's internal *pointer* on success. On failure, set an
exception and return *NULL*.
.. c:function:: int PyCapsule_IsValid(PyObject *capsule, const char *name)
Determines whether or not *capsule* is a valid capsule. A valid capsule is
non-*NULL*, passes :c:func:`PyCapsule_CheckExact`, has a non-*NULL* pointer
stored in it, and its internal name matches the *name* parameter. (See
:c:func:`PyCapsule_GetPointer` for information on how capsule names are
compared.)
In other words, if :c:func:`PyCapsule_IsValid` returns a true value, calls to
any of the accessors (any function starting with :c:func:`PyCapsule_Get`) are
guaranteed to succeed.
Return a nonzero value if the object is valid and matches the name passed in.
Return ``0`` otherwise. This function will not fail.
.. c:function:: int PyCapsule_SetContext(PyObject *capsule, void *context)
Set the context pointer inside *capsule* to *context*.
Return ``0`` on success. Return nonzero and set an exception on failure.
.. c:function:: int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)
Set the destructor inside *capsule* to *destructor*.
Return ``0`` on success. Return nonzero and set an exception on failure.
.. c:function:: int PyCapsule_SetName(PyObject *capsule, const char *name)
Set the name inside *capsule* to *name*. If non-*NULL*, the name must
outlive the capsule. If the previous *name* stored in the capsule was not
*NULL*, no attempt is made to free it.
Return ``0`` on success. Return nonzero and set an exception on failure.
.. c:function:: int PyCapsule_SetPointer(PyObject *capsule, void *pointer)
Set the void pointer inside *capsule* to *pointer*. The pointer may not be
*NULL*.
Return ``0`` on success. Return nonzero and set an exception on failure.
PK %�\mʼW� � html/_sources/c-api/cell.rst.txtnu �[��� .. highlightlang:: c
.. _cell-objects:
Cell Objects
------------
"Cell" objects are used to implement variables referenced by multiple scopes.
For each such variable, a cell object is created to store the value; the local
variables of each stack frame that references the value contains a reference to
the cells from outer scopes which also use that variable. When the value is
accessed, the value contained in the cell is used instead of the cell object
itself. This de-referencing of the cell object requires support from the
generated byte-code; these are not automatically de-referenced when accessed.
Cell objects are not likely to be useful elsewhere.
.. c:type:: PyCellObject
The C structure used for cell objects.
.. c:var:: PyTypeObject PyCell_Type
The type object corresponding to cell objects.
.. c:function:: int PyCell_Check(ob)
Return true if *ob* is a cell object; *ob* must not be *NULL*.
.. c:function:: PyObject* PyCell_New(PyObject *ob)
Create and return a new cell object containing the value *ob*. The parameter may
be *NULL*.
.. c:function:: PyObject* PyCell_Get(PyObject *cell)
Return the contents of the cell *cell*.
.. c:function:: PyObject* PyCell_GET(PyObject *cell)
Return the contents of the cell *cell*, but without checking that *cell* is
non-*NULL* and a cell object.
.. c:function:: int PyCell_Set(PyObject *cell, PyObject *value)
Set the contents of the cell object *cell* to *value*. This releases the
reference to any current content of the cell. *value* may be *NULL*. *cell*
must be non-*NULL*; if it is not a cell object, ``-1`` will be returned. On
success, ``0`` will be returned.
.. c:function:: void PyCell_SET(PyObject *cell, PyObject *value)
Sets the value of the cell object *cell* to *value*. No reference counts are
adjusted, and no checks are made for safety; *cell* must be non-*NULL* and must
be a cell object.
PK %�\� �?J J ! html/_sources/c-api/class.rst.txtnu �[��� .. highlightlang:: c
.. _classobjects:
Class and Instance Objects
--------------------------
.. index:: object: class
Note that the class objects described here represent old-style classes, which
will go away in Python 3. When creating new types for extension modules, you
will want to work with type objects (section :ref:`typeobjects`).
.. c:type:: PyClassObject
The C structure of the objects used to describe built-in classes.
.. c:var:: PyObject* PyClass_Type
.. index:: single: ClassType (in module types)
This is the type object for class objects; it is the same object as
``types.ClassType`` in the Python layer.
.. c:function:: int PyClass_Check(PyObject *o)
Return true if the object *o* is a class object, including instances of types
derived from the standard class object. Return false in all other cases.
.. c:function:: int PyClass_IsSubclass(PyObject *klass, PyObject *base)
Return true if *klass* is a subclass of *base*. Return false in all other cases.
.. index:: object: instance
There are very few functions specific to instance objects.
.. c:var:: PyTypeObject PyInstance_Type
Type object for class instances.
.. c:function:: int PyInstance_Check(PyObject *obj)
Return true if *obj* is an instance.
.. c:function:: PyObject* PyInstance_New(PyObject *class, PyObject *arg, PyObject *kw)
Create a new instance of a specific class. The parameters *arg* and *kw* are
used as the positional and keyword parameters to the object's constructor.
.. c:function:: PyObject* PyInstance_NewRaw(PyObject *class, PyObject *dict)
Create a new instance of a specific class without calling its constructor.
*class* is the class of new object. The *dict* parameter will be used as the
object's :attr:`~object.__dict__`; if *NULL*, a new dictionary will be created for the
instance.
PK %�\ � �N N # html/_sources/c-api/cobject.rst.txtnu �[��� .. highlightlang:: c
.. _cobjects:
CObjects
--------
.. index:: object: CObject
.. warning::
The CObject API is deprecated as of Python 2.7. Please switch to the new
:ref:`capsules` API.
.. c:type:: PyCObject
This subtype of :c:type:`PyObject` represents an opaque value, useful for C
extension modules who need to pass an opaque value (as a :c:type:`void\*`
pointer) through Python code to other C code. It is often used to make a C
function pointer defined in one module available to other modules, so the
regular import mechanism can be used to access C APIs defined in dynamically
loaded modules.
.. c:function:: int PyCObject_Check(PyObject *p)
Return true if its argument is a :c:type:`PyCObject`.
.. c:function:: PyObject* PyCObject_FromVoidPtr(void* cobj, void (*destr)(void *))
Create a :c:type:`PyCObject` from the ``void *`` *cobj*. The *destr* function
will be called when the object is reclaimed, unless it is *NULL*.
.. c:function:: PyObject* PyCObject_FromVoidPtrAndDesc(void* cobj, void* desc, void (*destr)(void *, void *))
Create a :c:type:`PyCObject` from the :c:type:`void \*` *cobj*. The *destr*
function will be called when the object is reclaimed. The *desc* argument can
be used to pass extra callback data for the destructor function.
.. c:function:: void* PyCObject_AsVoidPtr(PyObject* self)
Return the object :c:type:`void \*` that the :c:type:`PyCObject` *self* was
created with.
.. c:function:: void* PyCObject_GetDesc(PyObject* self)
Return the description :c:type:`void \*` that the :c:type:`PyCObject` *self* was
created with.
.. c:function:: int PyCObject_SetVoidPtr(PyObject* self, void* cobj)
Set the void pointer inside *self* to *cobj*. The :c:type:`PyCObject` must not
have an associated destructor. Return true on success, false on failure.
PK %�\��l�c c html/_sources/c-api/code.rst.txtnu �[��� .. highlightlang:: c
.. _codeobjects:
.. index:: object; code, code object
Code Objects
------------
.. sectionauthor:: Jeffrey Yasskin <jyasskin@gmail.com>
Code objects are a low-level detail of the CPython implementation.
Each one represents a chunk of executable code that hasn't yet been
bound into a function.
.. c:type:: PyCodeObject
The C structure of the objects used to describe code objects. The
fields of this type are subject to change at any time.
.. c:var:: PyTypeObject PyCode_Type
This is an instance of :c:type:`PyTypeObject` representing the Python
:class:`code` type.
.. c:function:: int PyCode_Check(PyObject *co)
Return true if *co* is a :class:`code` object.
.. c:function:: int PyCode_GetNumFree(PyObject *co)
Return the number of free variables in *co*.
.. c:function:: PyCodeObject *PyCode_New(int argcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, int firstlineno, PyObject *lnotab)
Return a new code object. If you need a dummy code object to
create a frame, use :c:func:`PyCode_NewEmpty` instead. Calling
:c:func:`PyCode_New` directly can bind you to a precise Python
version since the definition of the bytecode changes often.
.. c:function:: int PyCode_NewEmpty(const char *filename, const char *funcname, int firstlineno)
Return a new empty code object with the specified filename,
function name, and first line number. It is illegal to
:keyword:`exec` or :func:`eval` the resulting code object.
PK %�\|-�# # ! html/_sources/c-api/codec.rst.txtnu �[��� .. _codec-registry:
Codec registry and support functions
====================================
.. c:function:: int PyCodec_Register(PyObject *search_function)
Register a new codec search function.
As side effect, this tries to load the :mod:`encodings` package, if not yet
done, to make sure that it is always first in the list of search functions.
.. c:function:: int PyCodec_KnownEncoding(const char *encoding)
Return ``1`` or ``0`` depending on whether there is a registered codec for
the given *encoding*.
.. c:function:: PyObject* PyCodec_Encode(PyObject *object, const char *encoding, const char *errors)
Generic codec based encoding API.
*object* is passed through the encoder function found for the given
*encoding* using the error handling method defined by *errors*. *errors* may
be *NULL* to use the default method defined for the codec. Raises a
:exc:`LookupError` if no encoder can be found.
.. c:function:: PyObject* PyCodec_Decode(PyObject *object, const char *encoding, const char *errors)
Generic codec based decoding API.
*object* is passed through the decoder function found for the given
*encoding* using the error handling method defined by *errors*. *errors* may
be *NULL* to use the default method defined for the codec. Raises a
:exc:`LookupError` if no encoder can be found.
Codec lookup API
----------------
In the following functions, the *encoding* string is looked up converted to all
lower-case characters, which makes encodings looked up through this mechanism
effectively case-insensitive. If no codec is found, a :exc:`KeyError` is set
and *NULL* returned.
.. c:function:: PyObject* PyCodec_Encoder(const char *encoding)
Get an encoder function for the given *encoding*.
.. c:function:: PyObject* PyCodec_Decoder(const char *encoding)
Get a decoder function for the given *encoding*.
.. c:function:: PyObject* PyCodec_IncrementalEncoder(const char *encoding, const char *errors)
Get an :class:`~codecs.IncrementalEncoder` object for the given *encoding*.
.. c:function:: PyObject* PyCodec_IncrementalDecoder(const char *encoding, const char *errors)
Get an :class:`~codecs.IncrementalDecoder` object for the given *encoding*.
.. c:function:: PyObject* PyCodec_StreamReader(const char *encoding, PyObject *stream, const char *errors)
Get a :class:`~codecs.StreamReader` factory function for the given *encoding*.
.. c:function:: PyObject* PyCodec_StreamWriter(const char *encoding, PyObject *stream, const char *errors)
Get a :class:`~codecs.StreamWriter` factory function for the given *encoding*.
Registry API for Unicode encoding error handlers
------------------------------------------------
.. c:function:: int PyCodec_RegisterError(const char *name, PyObject *error)
Register the error handling callback function *error* under the given *name*.
This callback function will be called by a codec when it encounters
unencodable characters/undecodable bytes and *name* is specified as the error
parameter in the call to the encode/decode function.
The callback gets a single argument, an instance of
:exc:`UnicodeEncodeError`, :exc:`UnicodeDecodeError` or
:exc:`UnicodeTranslateError` that holds information about the problematic
sequence of characters or bytes and their offset in the original string (see
:ref:`unicodeexceptions` for functions to extract this information). The
callback must either raise the given exception, or return a two-item tuple
containing the replacement for the problematic sequence, and an integer
giving the offset in the original string at which encoding/decoding should be
resumed.
Return ``0`` on success, ``-1`` on error.
.. c:function:: PyObject* PyCodec_LookupError(const char *name)
Lookup the error handling callback function registered under *name*. As a
special case *NULL* can be passed, in which case the error handling callback
for "strict" will be returned.
.. c:function:: PyObject* PyCodec_StrictErrors(PyObject *exc)
Raise *exc* as an exception.
.. c:function:: PyObject* PyCodec_IgnoreErrors(PyObject *exc)
Ignore the unicode error, skipping the faulty input.
.. c:function:: PyObject* PyCodec_ReplaceErrors(PyObject *exc)
Replace the unicode encode error with ``?`` or ``U+FFFD``.
.. c:function:: PyObject* PyCodec_XMLCharRefReplaceErrors(PyObject *exc)
Replace the unicode encode error with XML character references.
.. c:function:: PyObject* PyCodec_BackslashReplaceErrors(PyObject *exc)
Replace the unicode encode error with backslash escapes (``\x``, ``\u`` and
``\U``).
PK %�\��� � # html/_sources/c-api/complex.rst.txtnu �[��� .. highlightlang:: c
.. _complexobjects:
Complex Number Objects
----------------------
.. index:: object: complex number
Python's complex number objects are implemented as two distinct types when
viewed from the C API: one is the Python object exposed to Python programs, and
the other is a C structure which represents the actual complex number value.
The API provides functions for working with both.
Complex Numbers as C Structures
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Note that the functions which accept these structures as parameters and return
them as results do so *by value* rather than dereferencing them through
pointers. This is consistent throughout the API.
.. c:type:: Py_complex
The C structure which corresponds to the value portion of a Python complex
number object. Most of the functions for dealing with complex number objects
use structures of this type as input or output values, as appropriate. It is
defined as::
typedef struct {
double real;
double imag;
} Py_complex;
.. c:function:: Py_complex _Py_c_sum(Py_complex left, Py_complex right)
Return the sum of two complex numbers, using the C :c:type:`Py_complex`
representation.
.. c:function:: Py_complex _Py_c_diff(Py_complex left, Py_complex right)
Return the difference between two complex numbers, using the C
:c:type:`Py_complex` representation.
.. c:function:: Py_complex _Py_c_neg(Py_complex complex)
Return the negation of the complex number *complex*, using the C
:c:type:`Py_complex` representation.
.. c:function:: Py_complex _Py_c_prod(Py_complex left, Py_complex right)
Return the product of two complex numbers, using the C :c:type:`Py_complex`
representation.
.. c:function:: Py_complex _Py_c_quot(Py_complex dividend, Py_complex divisor)
Return the quotient of two complex numbers, using the C :c:type:`Py_complex`
representation.
If *divisor* is null, this method returns zero and sets
:c:data:`errno` to :c:data:`EDOM`.
.. c:function:: Py_complex _Py_c_pow(Py_complex num, Py_complex exp)
Return the exponentiation of *num* by *exp*, using the C :c:type:`Py_complex`
representation.
If *num* is null and *exp* is not a positive real number,
this method returns zero and sets :c:data:`errno` to :c:data:`EDOM`.
Complex Numbers as Python Objects
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. c:type:: PyComplexObject
This subtype of :c:type:`PyObject` represents a Python complex number object.
.. c:var:: PyTypeObject PyComplex_Type
This instance of :c:type:`PyTypeObject` represents the Python complex number
type. It is the same object as ``complex`` and ``types.ComplexType``.
.. c:function:: int PyComplex_Check(PyObject *p)
Return true if its argument is a :c:type:`PyComplexObject` or a subtype of
:c:type:`PyComplexObject`.
.. versionchanged:: 2.2
Allowed subtypes to be accepted.
.. c:function:: int PyComplex_CheckExact(PyObject *p)
Return true if its argument is a :c:type:`PyComplexObject`, but not a subtype of
:c:type:`PyComplexObject`.
.. versionadded:: 2.2
.. c:function:: PyObject* PyComplex_FromCComplex(Py_complex v)
Create a new Python complex number object from a C :c:type:`Py_complex` value.
.. c:function:: PyObject* PyComplex_FromDoubles(double real, double imag)
Return a new :c:type:`PyComplexObject` object from *real* and *imag*.
.. c:function:: double PyComplex_RealAsDouble(PyObject *op)
Return the real part of *op* as a C :c:type:`double`.
.. c:function:: double PyComplex_ImagAsDouble(PyObject *op)
Return the imaginary part of *op* as a C :c:type:`double`.
.. c:function:: Py_complex PyComplex_AsCComplex(PyObject *op)
Return the :c:type:`Py_complex` value of the complex number *op*.
Upon failure, this method returns ``-1.0`` as a real value.
.. versionchanged:: 2.6
If *op* is not a Python complex number object but has a :meth:`__complex__`
method, this method will first be called to convert *op* to a Python complex
number object.
PK %�\i��
� � $ html/_sources/c-api/concrete.rst.txtnu �[��� .. highlightlang:: c
.. _concrete:
**********************
Concrete Objects Layer
**********************
The functions in this chapter are specific to certain Python object types.
Passing them an object of the wrong type is not a good idea; if you receive an
object from a Python program and you are not sure that it has the right type,
you must perform a type check first; for example, to check that an object is a
dictionary, use :c:func:`PyDict_Check`. The chapter is structured like the
"family tree" of Python object types.
.. warning::
While the functions described in this chapter carefully check the type of the
objects which are passed in, many of them do not check for *NULL* being passed
instead of a valid object. Allowing *NULL* to be passed in can cause memory
access violations and immediate termination of the interpreter.
.. _fundamental:
Fundamental Objects
===================
This section describes Python type objects and the singleton object ``None``.
.. toctree::
type.rst
none.rst
.. _numericobjects:
Numeric Objects
===============
.. index:: object: numeric
.. toctree::
int.rst
bool.rst
long.rst
float.rst
complex.rst
.. _sequenceobjects:
Sequence Objects
================
.. index:: object: sequence
Generic operations on sequence objects were discussed in the previous chapter;
this section deals with the specific kinds of sequence objects that are
intrinsic to the Python language.
.. toctree::
bytearray.rst
string.rst
unicode.rst
buffer.rst
tuple.rst
list.rst
.. _mapobjects:
Mapping Objects
===============
.. index:: object: mapping
.. toctree::
dict.rst
.. _otherobjects:
Other Objects
=============
.. toctree::
class.rst
function.rst
method.rst
file.rst
module.rst
iterator.rst
descriptor.rst
slice.rst
weakref.rst
capsule.rst
cobject.rst
cell.rst
gen.rst
datetime.rst
set.rst
code.rst
PK %�\�0�� � & html/_sources/c-api/conversion.rst.txtnu �[��� .. highlightlang:: c
.. _string-conversion:
String conversion and formatting
================================
Functions for number conversion and formatted string output.
.. c:function:: int PyOS_snprintf(char *str, size_t size, const char *format, ...)
Output not more than *size* bytes to *str* according to the format string
*format* and the extra arguments. See the Unix man page :manpage:`snprintf(2)`.
.. c:function:: int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)
Output not more than *size* bytes to *str* according to the format string
*format* and the variable argument list *va*. Unix man page
:manpage:`vsnprintf(2)`.
:c:func:`PyOS_snprintf` and :c:func:`PyOS_vsnprintf` wrap the Standard C library
functions :c:func:`snprintf` and :c:func:`vsnprintf`. Their purpose is to
guarantee consistent behavior in corner cases, which the Standard C functions do
not.
The wrappers ensure that *str*[*size*-1] is always ``'\0'`` upon return. They
never write more than *size* bytes (including the trailing ``'\0'`` into str.
Both functions require that ``str != NULL``, ``size > 0`` and ``format !=
NULL``.
If the platform doesn't have :c:func:`vsnprintf` and the buffer size needed to
avoid truncation exceeds *size* by more than 512 bytes, Python aborts with a
*Py_FatalError*.
The return value (*rv*) for these functions should be interpreted as follows:
* When ``0 <= rv < size``, the output conversion was successful and *rv*
characters were written to *str* (excluding the trailing ``'\0'`` byte at
*str*[*rv*]).
* When ``rv >= size``, the output conversion was truncated and a buffer with
``rv + 1`` bytes would have been needed to succeed. *str*[*size*-1] is ``'\0'``
in this case.
* When ``rv < 0``, "something bad happened." *str*[*size*-1] is ``'\0'`` in
this case too, but the rest of *str* is undefined. The exact cause of the error
depends on the underlying platform.
The following functions provide locale-independent string to number conversions.
.. c:function:: double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception)
Convert a string ``s`` to a :c:type:`double`, raising a Python
exception on failure. The set of accepted strings corresponds to
the set of strings accepted by Python's :func:`float` constructor,
except that ``s`` must not have leading or trailing whitespace.
The conversion is independent of the current locale.
If ``endptr`` is ``NULL``, convert the whole string. Raise
ValueError and return ``-1.0`` if the string is not a valid
representation of a floating-point number.
If endptr is not ``NULL``, convert as much of the string as
possible and set ``*endptr`` to point to the first unconverted
character. If no initial segment of the string is the valid
representation of a floating-point number, set ``*endptr`` to point
to the beginning of the string, raise ValueError, and return
``-1.0``.
If ``s`` represents a value that is too large to store in a float
(for example, ``"1e500"`` is such a string on many platforms) then
if ``overflow_exception`` is ``NULL`` return ``Py_HUGE_VAL`` (with
an appropriate sign) and don't set any exception. Otherwise,
``overflow_exception`` must point to a Python exception object;
raise that exception and return ``-1.0``. In both cases, set
``*endptr`` to point to the first character after the converted value.
If any other error occurs during the conversion (for example an
out-of-memory error), set the appropriate Python exception and
return ``-1.0``.
.. versionadded:: 2.7
.. c:function:: double PyOS_ascii_strtod(const char *nptr, char **endptr)
Convert a string to a :c:type:`double`. This function behaves like the Standard C
function :c:func:`strtod` does in the C locale. It does this without changing the
current locale, since that would not be thread-safe.
:c:func:`PyOS_ascii_strtod` should typically be used for reading configuration
files or other non-user input that should be locale independent.
See the Unix man page :manpage:`strtod(2)` for details.
.. versionadded:: 2.4
.. deprecated:: 2.7
Use :c:func:`PyOS_string_to_double` instead.
.. c:function:: char* PyOS_ascii_formatd(char *buffer, size_t buf_len, const char *format, double d)
Convert a :c:type:`double` to a string using the ``'.'`` as the decimal
separator. *format* is a :c:func:`printf`\ -style format string specifying the
number format. Allowed conversion characters are ``'e'``, ``'E'``, ``'f'``,
``'F'``, ``'g'`` and ``'G'``.
The return value is a pointer to *buffer* with the converted string or NULL if
the conversion failed.
.. versionadded:: 2.4
.. deprecated:: 2.7
This function is removed in Python 2.7 and 3.1. Use :func:`PyOS_double_to_string`
instead.
.. c:function:: char* PyOS_double_to_string(double val, char format_code, int precision, int flags, int *ptype)
Convert a :c:type:`double` *val* to a string using supplied
*format_code*, *precision*, and *flags*.
*format_code* must be one of ``'e'``, ``'E'``, ``'f'``, ``'F'``,
``'g'``, ``'G'`` or ``'r'``. For ``'r'``, the supplied *precision*
must be ``0`` and is ignored. The ``'r'`` format code specifies the
standard :func:`repr` format.
*flags* can be zero or more of the values *Py_DTSF_SIGN*,
*Py_DTSF_ADD_DOT_0*, or *Py_DTSF_ALT*, or-ed together:
* *Py_DTSF_SIGN* means to always precede the returned string with a sign
character, even if *val* is non-negative.
* *Py_DTSF_ADD_DOT_0* means to ensure that the returned string will not look
like an integer.
* *Py_DTSF_ALT* means to apply "alternate" formatting rules. See the
documentation for the :c:func:`PyOS_snprintf` ``'#'`` specifier for
details.
If *ptype* is non-NULL, then the value it points to will be set to one of
*Py_DTST_FINITE*, *Py_DTST_INFINITE*, or *Py_DTST_NAN*, signifying that
*val* is a finite number, an infinite number, or not a number, respectively.
The return value is a pointer to *buffer* with the converted string or
*NULL* if the conversion failed. The caller is responsible for freeing the
returned string by calling :c:func:`PyMem_Free`.
.. versionadded:: 2.7
.. c:function:: double PyOS_ascii_atof(const char *nptr)
Convert a string to a :c:type:`double` in a locale-independent way.
See the Unix man page :manpage:`atof(2)` for details.
.. versionadded:: 2.4
.. deprecated:: 3.1
Use :c:func:`PyOS_string_to_double` instead.
.. c:function:: char* PyOS_stricmp(char *s1, char *s2)
Case insensitive comparison of strings. The function works almost
identically to :c:func:`strcmp` except that it ignores the case.
.. versionadded:: 2.6
.. c:function:: char* PyOS_strnicmp(char *s1, char *s2, Py_ssize_t size)
Case insensitive comparison of strings. The function works almost
identically to :c:func:`strncmp` except that it ignores the case.
.. versionadded:: 2.6
PK %�\I�͖
$ html/_sources/c-api/datetime.rst.txtnu �[��� .. highlightlang:: c
.. _datetimeobjects:
DateTime Objects
----------------
Various date and time objects are supplied by the :mod:`datetime` module.
Before using any of these functions, the header file :file:`datetime.h` must be
included in your source (note that this is not included by :file:`Python.h`),
and the macro :c:macro:`PyDateTime_IMPORT` must be invoked, usually as part of
the module initialisation function. The macro puts a pointer to a C structure
into a static variable, :c:data:`PyDateTimeAPI`, that is used by the following
macros.
Type-check macros:
.. c:function:: int PyDate_Check(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_DateType` or a subtype of
:c:data:`PyDateTime_DateType`. *ob* must not be *NULL*.
.. versionadded:: 2.4
.. c:function:: int PyDate_CheckExact(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_DateType`. *ob* must not be
*NULL*.
.. versionadded:: 2.4
.. c:function:: int PyDateTime_Check(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType` or a subtype of
:c:data:`PyDateTime_DateTimeType`. *ob* must not be *NULL*.
.. versionadded:: 2.4
.. c:function:: int PyDateTime_CheckExact(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType`. *ob* must not
be *NULL*.
.. versionadded:: 2.4
.. c:function:: int PyTime_Check(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_TimeType` or a subtype of
:c:data:`PyDateTime_TimeType`. *ob* must not be *NULL*.
.. versionadded:: 2.4
.. c:function:: int PyTime_CheckExact(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_TimeType`. *ob* must not be
*NULL*.
.. versionadded:: 2.4
.. c:function:: int PyDelta_Check(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_DeltaType` or a subtype of
:c:data:`PyDateTime_DeltaType`. *ob* must not be *NULL*.
.. versionadded:: 2.4
.. c:function:: int PyDelta_CheckExact(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_DeltaType`. *ob* must not be
*NULL*.
.. versionadded:: 2.4
.. c:function:: int PyTZInfo_Check(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType` or a subtype of
:c:data:`PyDateTime_TZInfoType`. *ob* must not be *NULL*.
.. versionadded:: 2.4
.. c:function:: int PyTZInfo_CheckExact(PyObject *ob)
Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType`. *ob* must not be
*NULL*.
.. versionadded:: 2.4
Macros to create objects:
.. c:function:: PyObject* PyDate_FromDate(int year, int month, int day)
Return a ``datetime.date`` object with the specified year, month and day.
.. versionadded:: 2.4
.. c:function:: PyObject* PyDateTime_FromDateAndTime(int year, int month, int day, int hour, int minute, int second, int usecond)
Return a ``datetime.datetime`` object with the specified year, month, day, hour,
minute, second and microsecond.
.. versionadded:: 2.4
.. c:function:: PyObject* PyTime_FromTime(int hour, int minute, int second, int usecond)
Return a ``datetime.time`` object with the specified hour, minute, second and
microsecond.
.. versionadded:: 2.4
.. c:function:: PyObject* PyDelta_FromDSU(int days, int seconds, int useconds)
Return a ``datetime.timedelta`` object representing the given number of days,
seconds and microseconds. Normalization is performed so that the resulting
number of microseconds and seconds lie in the ranges documented for
``datetime.timedelta`` objects.
.. versionadded:: 2.4
Macros to extract fields from date objects. The argument must be an instance of
:c:data:`PyDateTime_Date`, including subclasses (such as
:c:data:`PyDateTime_DateTime`). The argument must not be *NULL*, and the type is
not checked:
.. c:function:: int PyDateTime_GET_YEAR(PyDateTime_Date *o)
Return the year, as a positive int.
.. versionadded:: 2.4
.. c:function:: int PyDateTime_GET_MONTH(PyDateTime_Date *o)
Return the month, as an int from 1 through 12.
.. versionadded:: 2.4
.. c:function:: int PyDateTime_GET_DAY(PyDateTime_Date *o)
Return the day, as an int from 1 through 31.
.. versionadded:: 2.4
Macros to extract fields from datetime objects. The argument must be an
instance of :c:data:`PyDateTime_DateTime`, including subclasses. The argument
must not be *NULL*, and the type is not checked:
.. c:function:: int PyDateTime_DATE_GET_HOUR(PyDateTime_DateTime *o)
Return the hour, as an int from 0 through 23.
.. versionadded:: 2.4
.. c:function:: int PyDateTime_DATE_GET_MINUTE(PyDateTime_DateTime *o)
Return the minute, as an int from 0 through 59.
.. versionadded:: 2.4
.. c:function:: int PyDateTime_DATE_GET_SECOND(PyDateTime_DateTime *o)
Return the second, as an int from 0 through 59.
.. versionadded:: 2.4
.. c:function:: int PyDateTime_DATE_GET_MICROSECOND(PyDateTime_DateTime *o)
Return the microsecond, as an int from 0 through 999999.
.. versionadded:: 2.4
Macros to extract fields from time objects. The argument must be an instance of
:c:data:`PyDateTime_Time`, including subclasses. The argument must not be *NULL*,
and the type is not checked:
.. c:function:: int PyDateTime_TIME_GET_HOUR(PyDateTime_Time *o)
Return the hour, as an int from 0 through 23.
.. versionadded:: 2.4
.. c:function:: int PyDateTime_TIME_GET_MINUTE(PyDateTime_Time *o)
Return the minute, as an int from 0 through 59.
.. versionadded:: 2.4
.. c:function:: int PyDateTime_TIME_GET_SECOND(PyDateTime_Time *o)
Return the second, as an int from 0 through 59.
.. versionadded:: 2.4
.. c:function:: int PyDateTime_TIME_GET_MICROSECOND(PyDateTime_Time *o)
Return the microsecond, as an int from 0 through 999999.
.. versionadded:: 2.4
Macros for the convenience of modules implementing the DB API:
.. c:function:: PyObject* PyDateTime_FromTimestamp(PyObject *args)
Create and return a new ``datetime.datetime`` object given an argument tuple
suitable for passing to ``datetime.datetime.fromtimestamp()``.
.. versionadded:: 2.4
.. c:function:: PyObject* PyDate_FromTimestamp(PyObject *args)
Create and return a new ``datetime.date`` object given an argument tuple
suitable for passing to ``datetime.date.fromtimestamp()``.
.. versionadded:: 2.4
PK %�\�
�� & html/_sources/c-api/descriptor.rst.txtnu �[��� .. highlightlang:: c
.. _descriptor-objects:
Descriptor Objects
------------------
"Descriptors" are objects that describe some attribute of an object. They are
found in the dictionary of type objects.
.. c:var:: PyTypeObject PyProperty_Type
The type object for the built-in descriptor types.
.. versionadded:: 2.2
.. c:function:: PyObject* PyDescr_NewGetSet(PyTypeObject *type, struct PyGetSetDef *getset)
.. versionadded:: 2.2
.. c:function:: PyObject* PyDescr_NewMember(PyTypeObject *type, struct PyMemberDef *meth)
.. versionadded:: 2.2
.. c:function:: PyObject* PyDescr_NewMethod(PyTypeObject *type, struct PyMethodDef *meth)
.. versionadded:: 2.2
.. c:function:: PyObject* PyDescr_NewWrapper(PyTypeObject *type, struct wrapperbase *wrapper, void *wrapped)
.. versionadded:: 2.2
.. c:function:: PyObject* PyDescr_NewClassMethod(PyTypeObject *type, PyMethodDef *method)
.. versionadded:: 2.3
.. c:function:: int PyDescr_IsData(PyObject *descr)
Return true if the descriptor objects *descr* describes a data attribute, or
false if it describes a method. *descr* must be a descriptor object; there is
no error checking.
.. versionadded:: 2.2
.. c:function:: PyObject* PyWrapper_New(PyObject *, PyObject *)
.. versionadded:: 2.2
PK %�\���M M html/_sources/c-api/dict.rst.txtnu �[��� .. highlightlang:: c
.. _dictobjects:
Dictionary Objects
------------------
.. index:: object: dictionary
.. c:type:: PyDictObject
This subtype of :c:type:`PyObject` represents a Python dictionary object.
.. c:var:: PyTypeObject PyDict_Type
.. index::
single: DictType (in module types)
single: DictionaryType (in module types)
This instance of :c:type:`PyTypeObject` represents the Python dictionary
type. This is exposed to Python programs as ``dict`` and
``types.DictType``.
.. c:function:: int PyDict_Check(PyObject *p)
Return true if *p* is a dict object or an instance of a subtype of the dict
type.
.. versionchanged:: 2.2
Allowed subtypes to be accepted.
.. c:function:: int PyDict_CheckExact(PyObject *p)
Return true if *p* is a dict object, but not an instance of a subtype of
the dict type.
.. versionadded:: 2.4
.. c:function:: PyObject* PyDict_New()
Return a new empty dictionary, or *NULL* on failure.
.. c:function:: PyObject* PyDictProxy_New(PyObject *dict)
Return a proxy object for a mapping which enforces read-only behavior.
This is normally used to create a proxy to prevent modification of the
dictionary for non-dynamic class types.
.. versionadded:: 2.2
.. c:function:: void PyDict_Clear(PyObject *p)
Empty an existing dictionary of all key-value pairs.
.. c:function:: int PyDict_Contains(PyObject *p, PyObject *key)
Determine if dictionary *p* contains *key*. If an item in *p* is matches
*key*, return ``1``, otherwise return ``0``. On error, return ``-1``.
This is equivalent to the Python expression ``key in p``.
.. versionadded:: 2.4
.. c:function:: PyObject* PyDict_Copy(PyObject *p)
Return a new dictionary that contains the same key-value pairs as *p*.
.. versionadded:: 1.6
.. c:function:: int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)
Insert *value* into the dictionary *p* with a key of *key*. *key* must be
:term:`hashable`; if it isn't, :exc:`TypeError` will be raised. Return
``0`` on success or ``-1`` on failure.
.. c:function:: int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)
.. index:: single: PyString_FromString()
Insert *value* into the dictionary *p* using *key* as a key. *key* should
be a :c:type:`char\*`. The key object is created using
``PyString_FromString(key)``. Return ``0`` on success or ``-1`` on
failure.
.. c:function:: int PyDict_DelItem(PyObject *p, PyObject *key)
Remove the entry in dictionary *p* with key *key*. *key* must be hashable;
if it isn't, :exc:`TypeError` is raised. Return ``0`` on success or ``-1``
on failure.
.. c:function:: int PyDict_DelItemString(PyObject *p, char *key)
Remove the entry in dictionary *p* which has a key specified by the string
*key*. Return ``0`` on success or ``-1`` on failure.
.. c:function:: PyObject* PyDict_GetItem(PyObject *p, PyObject *key)
Return the object from dictionary *p* which has a key *key*. Return *NULL*
if the key *key* is not present, but *without* setting an exception.
.. c:function:: PyObject* PyDict_GetItemString(PyObject *p, const char *key)
This is the same as :c:func:`PyDict_GetItem`, but *key* is specified as a
:c:type:`char\*`, rather than a :c:type:`PyObject\*`.
.. c:function:: PyObject* PyDict_Items(PyObject *p)
Return a :c:type:`PyListObject` containing all the items from the
dictionary, as in the dictionary method :meth:`dict.items`.
.. c:function:: PyObject* PyDict_Keys(PyObject *p)
Return a :c:type:`PyListObject` containing all the keys from the dictionary,
as in the dictionary method :meth:`dict.keys`.
.. c:function:: PyObject* PyDict_Values(PyObject *p)
Return a :c:type:`PyListObject` containing all the values from the
dictionary *p*, as in the dictionary method :meth:`dict.values`.
.. c:function:: Py_ssize_t PyDict_Size(PyObject *p)
.. index:: builtin: len
Return the number of items in the dictionary. This is equivalent to
``len(p)`` on a dictionary.
.. versionchanged:: 2.5
This function returned an :c:type:`int` type. This might require changes
in your code for properly supporting 64-bit systems.
.. c:function:: int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)
Iterate over all key-value pairs in the dictionary *p*. The
:c:type:`Py_ssize_t` referred to by *ppos* must be initialized to ``0``
prior to the first call to this function to start the iteration; the
function returns true for each pair in the dictionary, and false once all
pairs have been reported. The parameters *pkey* and *pvalue* should either
point to :c:type:`PyObject\*` variables that will be filled in with each key
and value, respectively, or may be *NULL*. Any references returned through
them are borrowed. *ppos* should not be altered during iteration. Its
value represents offsets within the internal dictionary structure, and
since the structure is sparse, the offsets are not consecutive.
For example::
PyObject *key, *value;
Py_ssize_t pos = 0;
while (PyDict_Next(self->dict, &pos, &key, &value)) {
/* do something interesting with the values... */
...
}
The dictionary *p* should not be mutated during iteration. It is safe
(since Python 2.1) to modify the values of the keys as you iterate over the
dictionary, but only so long as the set of keys does not change. For
example::
PyObject *key, *value;
Py_ssize_t pos = 0;
while (PyDict_Next(self->dict, &pos, &key, &value)) {
int i = PyInt_AS_LONG(value) + 1;
PyObject *o = PyInt_FromLong(i);
if (o == NULL)
return -1;
if (PyDict_SetItem(self->dict, key, o) < 0) {
Py_DECREF(o);
return -1;
}
Py_DECREF(o);
}
.. versionchanged:: 2.5
This function used an :c:type:`int *` type for *ppos*. This might require
changes in your code for properly supporting 64-bit systems.
.. c:function:: int PyDict_Merge(PyObject *a, PyObject *b, int override)
Iterate over mapping object *b* adding key-value pairs to dictionary *a*.
*b* may be a dictionary, or any object supporting :c:func:`PyMapping_Keys`
and :c:func:`PyObject_GetItem`. If *override* is true, existing pairs in *a*
will be replaced if a matching key is found in *b*, otherwise pairs will
only be added if there is not a matching key in *a*. Return ``0`` on
success or ``-1`` if an exception was raised.
.. versionadded:: 2.2
.. c:function:: int PyDict_Update(PyObject *a, PyObject *b)
This is the same as ``PyDict_Merge(a, b, 1)`` in C, and is similar to
``a.update(b)`` in Python except that :c:func:`PyDict_Update` doesn't fall
back to the iterating over a sequence of key value pairs if the second
argument has no "keys" attribute. Return ``0`` on success or ``-1`` if an
exception was raised.
.. versionadded:: 2.2
.. c:function:: int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)
Update or merge into dictionary *a*, from the key-value pairs in *seq2*.
*seq2* must be an iterable object producing iterable objects of length 2,
viewed as key-value pairs. In case of duplicate keys, the last wins if
*override* is true, else the first wins. Return ``0`` on success or ``-1``
if an exception was raised. Equivalent Python (except for the return
value)::
def PyDict_MergeFromSeq2(a, seq2, override):
for key, value in seq2:
if override or key not in a:
a[key] = value
.. versionadded:: 2.2
PK %�\���RO O ( html/_sources/distributing/index.rst.txtnu �[��� .. _distributing-index:
###############################
Distributing Python Modules
###############################
:Email: distutils-sig@python.org
As a popular open source development project, Python has an active
supporting community of contributors and users that also make their software
available for other Python developers to use under open source license terms.
This allows Python users to share and collaborate effectively, benefiting
from the solutions others have already created to common (and sometimes
even rare!) problems, as well as potentially contributing their own
solutions to the common pool.
This guide covers the distribution part of the process. For a guide to
installing other Python projects, refer to the
:ref:`installation guide <installing-index>`.
.. note::
For corporate and other institutional users, be aware that many
organisations have their own policies around using and contributing to
open source software. Please take such policies into account when making
use of the distribution and installation tools provided with Python.
Key terms
=========
* the `Python Packaging Index <https://pypi.org>`__ is a public
repository of open source licensed packages made available for use by
other Python users
* the `Python Packaging Authority
<https://www.pypa.io/>`__ are the group of
developers and documentation authors responsible for the maintenance and
evolution of the standard packaging tools and the associated metadata and
file format standards. They maintain a variety of tools, documentation
and issue trackers on both `GitHub <https://github.com/pypa>`__ and
`BitBucket <https://bitbucket.org/pypa/>`__.
* :mod:`distutils` is the original build and distribution system first added
to the Python standard library in 1998. While direct use of :mod:`distutils`
is being phased out, it still laid the foundation for the current packaging
and distribution infrastructure, and it not only remains part of the
standard library, but its name lives on in other ways (such as the name
of the mailing list used to coordinate Python packaging standards
development).
* `setuptools`_ is a (largely) drop-in replacement for :mod:`distutils` first
published in 2004. Its most notable addition over the unmodified
:mod:`distutils` tools was the ability to declare dependencies on other
packages. It is currently recommended as a more regularly updated
alternative to :mod:`distutils` that offers consistent support for more
recent packaging standards across a wide range of Python versions.
* `wheel`_ (in this context) is a project that adds the ``bdist_wheel``
command to :mod:`distutils`/`setuptools`_. This produces a cross platform
binary packaging format (called "wheels" or "wheel files" and defined in
:pep:`427`) that allows Python libraries, even those including binary
extensions, to be installed on a system without needing to be built
locally.
.. _setuptools: https://setuptools.readthedocs.io/en/latest/
.. _wheel: https://wheel.readthedocs.org
Open source licensing and collaboration
=======================================
In most parts of the world, software is automatically covered by copyright.
This means that other developers require explicit permission to copy, use,
modify and redistribute the software.
Open source licensing is a way of explicitly granting such permission in a
relatively consistent way, allowing developers to share and collaborate
efficiently by making common solutions to various problems freely available.
This leaves many developers free to spend more time focusing on the problems
that are relatively unique to their specific situation.
The distribution tools provided with Python are designed to make it
reasonably straightforward for developers to make their own contributions
back to that common pool of software if they choose to do so.
The same distribution tools can also be used to distribute software within
an organisation, regardless of whether that software is published as open
source software or not.
Installing the tools
====================
The standard library does not include build tools that support modern
Python packaging standards, as the core development team has found that it
is important to have standard tools that work consistently, even on older
versions of Python.
The currently recommended build and distribution tools can be installed
by invoking the ``pip`` module at the command line::
python -m pip install setuptools wheel twine
.. note::
For POSIX users (including Mac OS X and Linux users), these instructions
assume the use of a :term:`virtual environment`.
For Windows users, these instructions assume that the option to
adjust the system PATH environment variable was selected when installing
Python.
The Python Packaging User Guide includes more details on the `currently
recommended tools`_.
.. _currently recommended tools: https://packaging.python.org/en/latest/current/#packaging-tool-recommendations
Reading the guide
=================
The Python Packaging User Guide covers the various key steps and elements
involved in creating a project:
* `Project structure`_
* `Building and packaging the project`_
* `Uploading the project to the Python Packaging Index`_
.. _Project structure: \
https://packaging.python.org/en/latest/distributing/
.. _Building and packaging the project: \
https://packaging.python.org/en/latest/distributing/#packaging-your-project
.. _Uploading the project to the Python Packaging Index: \
https://packaging.python.org/en/latest/distributing/#uploading-your-project-to-pypi
How do I...?
============
These are quick answers or links for some common tasks.
... choose a name for my project?
---------------------------------
This isn't an easy topic, but here are a few tips:
* check the Python Packaging Index to see if the name is already in use
* check popular hosting sites like GitHub, BitBucket, etc to see if there
is already a project with that name
* check what comes up in a web search for the name you're considering
* avoid particularly common words, especially ones with multiple meanings,
as they can make it difficult for users to find your software when
searching for it
... create and distribute binary extensions?
--------------------------------------------
This is actually quite a complex topic, with a variety of alternatives
available depending on exactly what you're aiming to achieve. See the
Python Packaging User Guide for more information and recommendations.
.. seealso::
`Python Packaging User Guide: Binary Extensions
<https://packaging.python.org/en/latest/extensions>`__
.. other topics:
Once the Development & Deployment part of PPUG is fleshed out, some of
those sections should be linked from new questions here (most notably,
we should have a question about avoiding depending on PyPI that links to
https://packaging.python.org/en/latest/mirrors/)
PK %�\ �� �p �p & html/_sources/distutils/apiref.rst.txtnu �[��� .. _api-reference:
*************
API Reference
*************
:mod:`distutils.core` --- Core Distutils functionality
======================================================
.. module:: distutils.core
:synopsis: The core Distutils functionality
The :mod:`distutils.core` module is the only module that needs to be installed
to use the Distutils. It provides the :func:`setup` (which is called from the
setup script). Indirectly provides the :class:`distutils.dist.Distribution` and
:class:`distutils.cmd.Command` class.
.. function:: setup(arguments)
The basic do-everything function that does most everything you could ever ask
for from a Distutils method.
The setup function takes a large number of arguments. These are laid out in the
following table.
.. tabularcolumns:: |l|L|L|
+--------------------+--------------------------------+-------------------------------------------------------------+
| argument name | value | type |
+====================+================================+=============================================================+
| *name* | The name of the package | a string |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *version* | The version number of the | a string |
| | package; see | |
| | :mod:`distutils.version` | |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *description* | A single line describing the | a string |
| | package | |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *long_description* | Longer description of the | a string |
| | package | |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *author* | The name of the package author | a string |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *author_email* | The email address of the | a string |
| | package author | |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *maintainer* | The name of the current | a string |
| | maintainer, if different from | |
| | the author. Note that if | |
| | the maintainer is provided, | |
| | distutils will use it as the | |
| | author in :file:`PKG-INFO` | |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *maintainer_email* | The email address of the | a string |
| | current maintainer, if | |
| | different from the author | |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *url* | A URL for the package | a string |
| | (homepage) | |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *download_url* | A URL to download the package | a string |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *packages* | A list of Python packages that | a list of strings |
| | distutils will manipulate | |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *py_modules* | A list of Python modules that | a list of strings |
| | distutils will manipulate | |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *scripts* | A list of standalone script | a list of strings |
| | files to be built and | |
| | installed | |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *ext_modules* | A list of Python extensions to | a list of instances of |
| | be built | :class:`distutils.core.Extension` |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *classifiers* | A list of categories for the | a list of strings; valid classifiers are listed on `PyPI |
| | package | <https://pypi.org/classifiers>`_. |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *distclass* | the :class:`Distribution` | a subclass of |
| | class to use | :class:`distutils.core.Distribution` |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *script_name* | The name of the setup.py | a string |
| | script - defaults to | |
| | ``sys.argv[0]`` | |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *script_args* | Arguments to supply to the | a list of strings |
| | setup script | |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *options* | default options for the setup | a dictionary |
| | script | |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *license* | The license for the package | a string |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *keywords* | Descriptive meta-data, see | a list of strings or a comma-separated string |
| | :pep:`314` | |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *platforms* | | a list of strings or a comma-separated string |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *cmdclass* | A mapping of command names to | a dictionary |
| | :class:`Command` subclasses | |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *data_files* | A list of data files to | a list |
| | install | |
+--------------------+--------------------------------+-------------------------------------------------------------+
| *package_dir* | A mapping of package to | a dictionary |
| | directory names | |
+--------------------+--------------------------------+-------------------------------------------------------------+
.. function:: run_setup(script_name[, script_args=None, stop_after='run'])
Run a setup script in a somewhat controlled environment, and return the
:class:`distutils.dist.Distribution` instance that drives things. This is
useful if you need to find out the distribution meta-data (passed as keyword
args from *script* to :func:`setup`), or the contents of the config files or
command-line.
*script_name* is a file that will be run with :func:`execfile` ``sys.argv[0]``
will be replaced with *script* for the duration of the call. *script_args* is a
list of strings; if supplied, ``sys.argv[1:]`` will be replaced by *script_args*
for the duration of the call.
*stop_after* tells :func:`setup` when to stop processing; possible values:
.. tabularcolumns:: |l|L|
+---------------+---------------------------------------------+
| value | description |
+===============+=============================================+
| *init* | Stop after the :class:`Distribution` |
| | instance has been created and populated |
| | with the keyword arguments to :func:`setup` |
+---------------+---------------------------------------------+
| *config* | Stop after config files have been parsed |
| | (and their data stored in the |
| | :class:`Distribution` instance) |
+---------------+---------------------------------------------+
| *commandline* | Stop after the command-line |
| | (``sys.argv[1:]`` or *script_args*) have |
| | been parsed (and the data stored in the |
| | :class:`Distribution` instance.) |
+---------------+---------------------------------------------+
| *run* | Stop after all commands have been run (the |
| | same as if :func:`setup` had been called |
| | in the usual way). This is the default |
| | value. |
+---------------+---------------------------------------------+
In addition, the :mod:`distutils.core` module exposed a number of classes that
live elsewhere.
* :class:`~distutils.extension.Extension` from :mod:`distutils.extension`
* :class:`~distutils.cmd.Command` from :mod:`distutils.cmd`
* :class:`~distutils.dist.Distribution` from :mod:`distutils.dist`
A short description of each of these follows, but see the relevant module for
the full reference.
.. class:: Extension
The Extension class describes a single C or C++ extension module in a setup
script. It accepts the following keyword arguments in its constructor
.. tabularcolumns:: |l|L|l|
+------------------------+--------------------------------+---------------------------+
| argument name | value | type |
+========================+================================+===========================+
| *name* | the full name of the | a string |
| | extension, including any | |
| | packages --- ie. *not* a | |
| | filename or pathname, but | |
| | Python dotted name | |
+------------------------+--------------------------------+---------------------------+
| *sources* | list of source filenames, | a list of strings |
| | relative to the distribution | |
| | root (where the setup script | |
| | lives), in Unix form (slash- | |
| | separated) for portability. | |
| | Source files may be C, C++, | |
| | SWIG (.i), platform-specific | |
| | resource files, or whatever | |
| | else is recognized by the | |
| | :command:`build_ext` command | |
| | as source for a Python | |
| | extension. | |
+------------------------+--------------------------------+---------------------------+
| *include_dirs* | list of directories to search | a list of strings |
| | for C/C++ header files (in | |
| | Unix form for portability) | |
+------------------------+--------------------------------+---------------------------+
| *define_macros* | list of macros to define; each | a list of tuples |
| | macro is defined using a | |
| | 2-tuple ``(name, value)``, | |
| | where *value* is | |
| | either the string to define it | |
| | to or ``None`` to define it | |
| | without a particular value | |
| | (equivalent of ``#define FOO`` | |
| | in source or :option:`!-DFOO` | |
| | on Unix C compiler command | |
| | line) | |
+------------------------+--------------------------------+---------------------------+
| *undef_macros* | list of macros to undefine | a list of strings |
| | explicitly | |
+------------------------+--------------------------------+---------------------------+
| *library_dirs* | list of directories to search | a list of strings |
| | for C/C++ libraries at link | |
| | time | |
+------------------------+--------------------------------+---------------------------+
| *libraries* | list of library names (not | a list of strings |
| | filenames or paths) to link | |
| | against | |
+------------------------+--------------------------------+---------------------------+
| *runtime_library_dirs* | list of directories to search | a list of strings |
| | for C/C++ libraries at run | |
| | time (for shared extensions, | |
| | this is when the extension is | |
| | loaded) | |
+------------------------+--------------------------------+---------------------------+
| *extra_objects* | list of extra files to link | a list of strings |
| | with (eg. object files not | |
| | implied by 'sources', static | |
| | library that must be | |
| | explicitly specified, binary | |
| | resource files, etc.) | |
+------------------------+--------------------------------+---------------------------+
| *extra_compile_args* | any extra platform- and | a list of strings |
| | compiler-specific information | |
| | to use when compiling the | |
| | source files in 'sources'. For | |
| | platforms and compilers where | |
| | a command line makes sense, | |
| | this is typically a list of | |
| | command-line arguments, but | |
| | for other platforms it could | |
| | be anything. | |
+------------------------+--------------------------------+---------------------------+
| *extra_link_args* | any extra platform- and | a list of strings |
| | compiler-specific information | |
| | to use when linking object | |
| | files together to create the | |
| | extension (or to create a new | |
| | static Python interpreter). | |
| | Similar interpretation as for | |
| | 'extra_compile_args'. | |
+------------------------+--------------------------------+---------------------------+
| *export_symbols* | list of symbols to be exported | a list of strings |
| | from a shared extension. Not | |
| | used on all platforms, and not | |
| | generally necessary for Python | |
| | extensions, which typically | |
| | export exactly one symbol: | |
| | ``init`` + extension_name. | |
+------------------------+--------------------------------+---------------------------+
| *depends* | list of files that the | a list of strings |
| | extension depends on | |
+------------------------+--------------------------------+---------------------------+
| *language* | extension language (i.e. | a string |
| | ``'c'``, ``'c++'``, | |
| | ``'objc'``). Will be detected | |
| | from the source extensions if | |
| | not provided. | |
+------------------------+--------------------------------+---------------------------+
.. class:: Distribution
A :class:`Distribution` describes how to build, install and package up a Python
software package.
See the :func:`setup` function for a list of keyword arguments accepted by the
Distribution constructor. :func:`setup` creates a Distribution instance.
.. class:: Command
A :class:`Command` class (or rather, an instance of one of its subclasses)
implement a single distutils command.
:mod:`distutils.ccompiler` --- CCompiler base class
===================================================
.. module:: distutils.ccompiler
:synopsis: Abstract CCompiler class
This module provides the abstract base class for the :class:`CCompiler`
classes. A :class:`CCompiler` instance can be used for all the compile and
link steps needed to build a single project. Methods are provided to set
options for the compiler --- macro definitions, include directories, link path,
libraries and the like.
This module provides the following functions.
.. function:: gen_lib_options(compiler, library_dirs, runtime_library_dirs, libraries)
Generate linker options for searching library directories and linking with
specific libraries. *libraries* and *library_dirs* are, respectively, lists of
library names (not filenames!) and search directories. Returns a list of
command-line options suitable for use with some compiler (depending on the two
format strings passed in).
.. function:: gen_preprocess_options(macros, include_dirs)
Generate C pre-processor options (:option:`!-D`, :option:`!-U`, :option:`!-I`) as
used by at least two types of compilers: the typical Unix compiler and Visual
C++. *macros* is the usual thing, a list of 1- or 2-tuples, where ``(name,)``
means undefine (:option:`!-U`) macro *name*, and ``(name, value)`` means define
(:option:`!-D`) macro *name* to *value*. *include_dirs* is just a list of
directory names to be added to the header file search path (:option:`!-I`).
Returns a list of command-line options suitable for either Unix compilers or
Visual C++.
.. function:: get_default_compiler(osname, platform)
Determine the default compiler to use for the given platform.
*osname* should be one of the standard Python OS names (i.e. the ones returned
by ``os.name``) and *platform* the common value returned by ``sys.platform`` for
the platform in question.
The default values are ``os.name`` and ``sys.platform`` in case the parameters
are not given.
.. function:: new_compiler(plat=None, compiler=None, verbose=0, dry_run=0, force=0)
Factory function to generate an instance of some CCompiler subclass for the
supplied platform/compiler combination. *plat* defaults to ``os.name`` (eg.
``'posix'``, ``'nt'``), and *compiler* defaults to the default compiler for
that platform. Currently only ``'posix'`` and ``'nt'`` are supported, and the
default compilers are "traditional Unix interface" (:class:`UnixCCompiler`
class) and Visual C++ (:class:`MSVCCompiler` class). Note that it's perfectly
possible to ask for a Unix compiler object under Windows, and a Microsoft
compiler object under Unix---if you supply a value for *compiler*, *plat* is
ignored.
.. % Is the posix/nt only thing still true? Mac OS X seems to work, and
.. % returns a UnixCCompiler instance. How to document this... hmm.
.. function:: show_compilers()
Print list of available compilers (used by the :option:`!--help-compiler` options
to :command:`build`, :command:`build_ext`, :command:`build_clib`).
.. class:: CCompiler([verbose=0, dry_run=0, force=0])
The abstract base class :class:`CCompiler` defines the interface that must be
implemented by real compiler classes. The class also has some utility methods
used by several compiler classes.
The basic idea behind a compiler abstraction class is that each instance can be
used for all the compile/link steps in building a single project. Thus,
attributes common to all of those compile and link steps --- include
directories, macros to define, libraries to link against, etc. --- are
attributes of the compiler instance. To allow for variability in how individual
files are treated, most of those attributes may be varied on a per-compilation
or per-link basis.
The constructor for each subclass creates an instance of the Compiler object.
Flags are *verbose* (show verbose output), *dry_run* (don't actually execute the
steps) and *force* (rebuild everything, regardless of dependencies). All of
these flags default to ``0`` (off). Note that you probably don't want to
instantiate :class:`CCompiler` or one of its subclasses directly - use the
:func:`distutils.CCompiler.new_compiler` factory function instead.
The following methods allow you to manually alter compiler options for the
instance of the Compiler class.
.. method:: CCompiler.add_include_dir(dir)
Add *dir* to the list of directories that will be searched for header files.
The compiler is instructed to search directories in the order in which they are
supplied by successive calls to :meth:`add_include_dir`.
.. method:: CCompiler.set_include_dirs(dirs)
Set the list of directories that will be searched to *dirs* (a list of strings).
Overrides any preceding calls to :meth:`add_include_dir`; subsequent calls to
:meth:`add_include_dir` add to the list passed to :meth:`set_include_dirs`.
This does not affect any list of standard include directories that the compiler
may search by default.
.. method:: CCompiler.add_library(libname)
Add *libname* to the list of libraries that will be included in all links driven
by this compiler object. Note that *libname* should \*not\* be the name of a
file containing a library, but the name of the library itself: the actual
filename will be inferred by the linker, the compiler, or the compiler class
(depending on the platform).
The linker will be instructed to link against libraries in the order they were
supplied to :meth:`add_library` and/or :meth:`set_libraries`. It is perfectly
valid to duplicate library names; the linker will be instructed to link against
libraries as many times as they are mentioned.
.. method:: CCompiler.set_libraries(libnames)
Set the list of libraries to be included in all links driven by this compiler
object to *libnames* (a list of strings). This does not affect any standard
system libraries that the linker may include by default.
.. method:: CCompiler.add_library_dir(dir)
Add *dir* to the list of directories that will be searched for libraries
specified to :meth:`add_library` and :meth:`set_libraries`. The linker will be
instructed to search for libraries in the order they are supplied to
:meth:`add_library_dir` and/or :meth:`set_library_dirs`.
.. method:: CCompiler.set_library_dirs(dirs)
Set the list of library search directories to *dirs* (a list of strings). This
does not affect any standard library search path that the linker may search by
default.
.. method:: CCompiler.add_runtime_library_dir(dir)
Add *dir* to the list of directories that will be searched for shared libraries
at runtime.
.. method:: CCompiler.set_runtime_library_dirs(dirs)
Set the list of directories to search for shared libraries at runtime to *dirs*
(a list of strings). This does not affect any standard search path that the
runtime linker may search by default.
.. method:: CCompiler.define_macro(name[, value=None])
Define a preprocessor macro for all compilations driven by this compiler object.
The optional parameter *value* should be a string; if it is not supplied, then
the macro will be defined without an explicit value and the exact outcome
depends on the compiler used.
.. XXX true? does ANSI say anything about this?
.. method:: CCompiler.undefine_macro(name)
Undefine a preprocessor macro for all compilations driven by this compiler
object. If the same macro is defined by :meth:`define_macro` and
undefined by :meth:`undefine_macro` the last call takes precedence
(including multiple redefinitions or undefinitions). If the macro is
redefined/undefined on a per-compilation basis (ie. in the call to
:meth:`compile`), then that takes precedence.
.. method:: CCompiler.add_link_object(object)
Add *object* to the list of object files (or analogues, such as explicitly named
library files or the output of "resource compilers") to be included in every
link driven by this compiler object.
.. method:: CCompiler.set_link_objects(objects)
Set the list of object files (or analogues) to be included in every link to
*objects*. This does not affect any standard object files that the linker may
include by default (such as system libraries).
The following methods implement methods for autodetection of compiler options,
providing some functionality similar to GNU :program:`autoconf`.
.. method:: CCompiler.detect_language(sources)
Detect the language of a given file, or list of files. Uses the instance
attributes :attr:`language_map` (a dictionary), and :attr:`language_order` (a
list) to do the job.
.. method:: CCompiler.find_library_file(dirs, lib[, debug=0])
Search the specified list of directories for a static or shared library file
*lib* and return the full path to that file. If *debug* is true, look for a
debugging version (if that makes sense on the current platform). Return
``None`` if *lib* wasn't found in any of the specified directories.
.. method:: CCompiler.has_function(funcname [, includes=None, include_dirs=None, libraries=None, library_dirs=None])
Return a boolean indicating whether *funcname* is supported on the current
platform. The optional arguments can be used to augment the compilation
environment by providing additional include files and paths and libraries and
paths.
.. method:: CCompiler.library_dir_option(dir)
Return the compiler option to add *dir* to the list of directories searched for
libraries.
.. method:: CCompiler.library_option(lib)
Return the compiler option to add *lib* to the list of libraries linked into the
shared library or executable.
.. method:: CCompiler.runtime_library_dir_option(dir)
Return the compiler option to add *dir* to the list of directories searched for
runtime libraries.
.. method:: CCompiler.set_executables(**args)
Define the executables (and options for them) that will be run to perform the
various stages of compilation. The exact set of executables that may be
specified here depends on the compiler class (via the 'executables' class
attribute), but most will have:
+--------------+------------------------------------------+
| attribute | description |
+==============+==========================================+
| *compiler* | the C/C++ compiler |
+--------------+------------------------------------------+
| *linker_so* | linker used to create shared objects and |
| | libraries |
+--------------+------------------------------------------+
| *linker_exe* | linker used to create binary executables |
+--------------+------------------------------------------+
| *archiver* | static library creator |
+--------------+------------------------------------------+
On platforms with a command-line (Unix, DOS/Windows), each of these is a string
that will be split into executable name and (optional) list of arguments.
(Splitting the string is done similarly to how Unix shells operate: words are
delimited by spaces, but quotes and backslashes can override this. See
:func:`distutils.util.split_quoted`.)
The following methods invoke stages in the build process.
.. method:: CCompiler.compile(sources[, output_dir=None, macros=None, include_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, depends=None])
Compile one or more source files. Generates object files (e.g. transforms a
:file:`.c` file to a :file:`.o` file.)
*sources* must be a list of filenames, most likely C/C++ files, but in reality
anything that can be handled by a particular compiler and compiler class (eg.
:class:`MSVCCompiler` can handle resource files in *sources*). Return a list of
object filenames, one per source filename in *sources*. Depending on the
implementation, not all source files will necessarily be compiled, but all
corresponding object filenames will be returned.
If *output_dir* is given, object files will be put under it, while retaining
their original path component. That is, :file:`foo/bar.c` normally compiles to
:file:`foo/bar.o` (for a Unix implementation); if *output_dir* is *build*, then
it would compile to :file:`build/foo/bar.o`.
*macros*, if given, must be a list of macro definitions. A macro definition is
either a ``(name, value)`` 2-tuple or a ``(name,)`` 1-tuple. The former defines
a macro; if the value is ``None``, the macro is defined without an explicit
value. The 1-tuple case undefines a macro. Later
definitions/redefinitions/undefinitions take precedence.
*include_dirs*, if given, must be a list of strings, the directories to add to
the default include file search path for this compilation only.
*debug* is a boolean; if true, the compiler will be instructed to output debug
symbols in (or alongside) the object file(s).
*extra_preargs* and *extra_postargs* are implementation-dependent. On platforms
that have the notion of a command-line (e.g. Unix, DOS/Windows), they are most
likely lists of strings: extra command-line arguments to prepend/append to the
compiler command line. On other platforms, consult the implementation class
documentation. In any event, they are intended as an escape hatch for those
occasions when the abstract compiler framework doesn't cut the mustard.
*depends*, if given, is a list of filenames that all targets depend on. If a
source file is older than any file in depends, then the source file will be
recompiled. This supports dependency tracking, but only at a coarse
granularity.
Raises :exc:`CompileError` on failure.
.. method:: CCompiler.create_static_lib(objects, output_libname[, output_dir=None, debug=0, target_lang=None])
Link a bunch of stuff together to create a static library file. The "bunch of
stuff" consists of the list of object files supplied as *objects*, the extra
object files supplied to :meth:`add_link_object` and/or
:meth:`set_link_objects`, the libraries supplied to :meth:`add_library` and/or
:meth:`set_libraries`, and the libraries supplied as *libraries* (if any).
*output_libname* should be a library name, not a filename; the filename will be
inferred from the library name. *output_dir* is the directory where the library
file will be put.
.. XXX defaults to what?
*debug* is a boolean; if true, debugging information will be included in the
library (note that on most platforms, it is the compile step where this matters:
the *debug* flag is included here just for consistency).
*target_lang* is the target language for which the given objects are being
compiled. This allows specific linkage time treatment of certain languages.
Raises :exc:`LibError` on failure.
.. method:: CCompiler.link(target_desc, objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])
Link a bunch of stuff together to create an executable or shared library file.
The "bunch of stuff" consists of the list of object files supplied as *objects*.
*output_filename* should be a filename. If *output_dir* is supplied,
*output_filename* is relative to it (i.e. *output_filename* can provide
directory components if needed).
*libraries* is a list of libraries to link against. These are library names,
not filenames, since they're translated into filenames in a platform-specific
way (eg. *foo* becomes :file:`libfoo.a` on Unix and :file:`foo.lib` on
DOS/Windows). However, they can include a directory component, which means the
linker will look in that specific directory rather than searching all the normal
locations.
*library_dirs*, if supplied, should be a list of directories to search for
libraries that were specified as bare library names (ie. no directory
component). These are on top of the system default and those supplied to
:meth:`add_library_dir` and/or :meth:`set_library_dirs`. *runtime_library_dirs*
is a list of directories that will be embedded into the shared library and used
to search for other shared libraries that \*it\* depends on at run-time. (This
may only be relevant on Unix.)
*export_symbols* is a list of symbols that the shared library will export.
(This appears to be relevant only on Windows.)
*debug* is as for :meth:`compile` and :meth:`create_static_lib`, with the
slight distinction that it actually matters on most platforms (as opposed to
:meth:`create_static_lib`, which includes a *debug* flag mostly for form's
sake).
*extra_preargs* and *extra_postargs* are as for :meth:`compile` (except of
course that they supply command-line arguments for the particular linker being
used).
*target_lang* is the target language for which the given objects are being
compiled. This allows specific linkage time treatment of certain languages.
Raises :exc:`LinkError` on failure.
.. method:: CCompiler.link_executable(objects, output_progname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, target_lang=None])
Link an executable. *output_progname* is the name of the file executable, while
*objects* are a list of object filenames to link in. Other arguments are as for
the :meth:`link` method.
.. method:: CCompiler.link_shared_lib(objects, output_libname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])
Link a shared library. *output_libname* is the name of the output library,
while *objects* is a list of object filenames to link in. Other arguments are
as for the :meth:`link` method.
.. method:: CCompiler.link_shared_object(objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])
Link a shared object. *output_filename* is the name of the shared object that
will be created, while *objects* is a list of object filenames to link in.
Other arguments are as for the :meth:`link` method.
.. method:: CCompiler.preprocess(source[, output_file=None, macros=None, include_dirs=None, extra_preargs=None, extra_postargs=None])
Preprocess a single C/C++ source file, named in *source*. Output will be written
to file named *output_file*, or *stdout* if *output_file* not supplied.
*macros* is a list of macro definitions as for :meth:`compile`, which will
augment the macros set with :meth:`define_macro` and :meth:`undefine_macro`.
*include_dirs* is a list of directory names that will be added to the default
list, in the same way as :meth:`add_include_dir`.
Raises :exc:`PreprocessError` on failure.
The following utility methods are defined by the :class:`CCompiler` class, for
use by the various concrete subclasses.
.. method:: CCompiler.executable_filename(basename[, strip_dir=0, output_dir=''])
Returns the filename of the executable for the given *basename*. Typically for
non-Windows platforms this is the same as the basename, while Windows will get
a :file:`.exe` added.
.. method:: CCompiler.library_filename(libname[, lib_type='static', strip_dir=0, output_dir=''])
Returns the filename for the given library name on the current platform. On Unix
a library with *lib_type* of ``'static'`` will typically be of the form
:file:`liblibname.a`, while a *lib_type* of ``'dynamic'`` will be of the form
:file:`liblibname.so`.
.. method:: CCompiler.object_filenames(source_filenames[, strip_dir=0, output_dir=''])
Returns the name of the object files for the given source files.
*source_filenames* should be a list of filenames.
.. method:: CCompiler.shared_object_filename(basename[, strip_dir=0, output_dir=''])
Returns the name of a shared object file for the given file name *basename*.
.. method:: CCompiler.execute(func, args[, msg=None, level=1])
Invokes :func:`distutils.util.execute`. This method invokes a Python function
*func* with the given arguments *args*, after logging and taking into account
the *dry_run* flag.
.. method:: CCompiler.spawn(cmd)
Invokes :func:`distutils.util.spawn`. This invokes an external process to run
the given command.
.. method:: CCompiler.mkpath(name[, mode=511])
Invokes :func:`distutils.dir_util.mkpath`. This creates a directory and any
missing ancestor directories.
.. method:: CCompiler.move_file(src, dst)
Invokes :meth:`distutils.file_util.move_file`. Renames *src* to *dst*.
.. method:: CCompiler.announce(msg[, level=1])
Write a message using :func:`distutils.log.debug`.
.. method:: CCompiler.warn(msg)
Write a warning message *msg* to standard error.
.. method:: CCompiler.debug_print(msg)
If the *debug* flag is set on this :class:`CCompiler` instance, print *msg* to
standard output, otherwise do nothing.
.. % \subsection{Compiler-specific modules}
.. %
.. % The following modules implement concrete subclasses of the abstract
.. % \class{CCompiler} class. They should not be instantiated directly, but should
.. % be created using \function{distutils.ccompiler.new_compiler()} factory
.. % function.
:mod:`distutils.unixccompiler` --- Unix C Compiler
==================================================
.. module:: distutils.unixccompiler
:synopsis: UNIX C Compiler
This module provides the :class:`UnixCCompiler` class, a subclass of
:class:`CCompiler` that handles the typical Unix-style command-line C compiler:
* macros defined with :option:`!-Dname[=value]`
* macros undefined with :option:`!-Uname`
* include search directories specified with :option:`!-Idir`
* libraries specified with :option:`!-llib`
* library search directories specified with :option:`!-Ldir`
* compile handled by :program:`cc` (or similar) executable with :option:`!-c`
option: compiles :file:`.c` to :file:`.o`
* link static library handled by :program:`ar` command (possibly with
:program:`ranlib`)
* link shared library handled by :program:`cc` :option:`!-shared`
:mod:`distutils.msvccompiler` --- Microsoft Compiler
====================================================
.. module:: distutils.msvccompiler
:synopsis: Microsoft Compiler
This module provides :class:`MSVCCompiler`, an implementation of the abstract
:class:`CCompiler` class for Microsoft Visual Studio. Typically, extension
modules need to be compiled with the same compiler that was used to compile
Python. For Python 2.3 and earlier, the compiler was Visual Studio 6. For Python
2.4 and 2.5, the compiler is Visual Studio .NET 2003. The AMD64 and Itanium
binaries are created using the Platform SDK.
:class:`MSVCCompiler` will normally choose the right compiler, linker etc. on
its own. To override this choice, the environment variables *DISTUTILS_USE_SDK*
and *MSSdk* must be both set. *MSSdk* indicates that the current environment has
been setup by the SDK's ``SetEnv.Cmd`` script, or that the environment variables
had been registered when the SDK was installed; *DISTUTILS_USE_SDK* indicates
that the distutils user has made an explicit choice to override the compiler
selection by :class:`MSVCCompiler`.
:mod:`distutils.bcppcompiler` --- Borland Compiler
==================================================
.. module:: distutils.bcppcompiler
This module provides :class:`BorlandCCompiler`, a subclass of the abstract
:class:`CCompiler` class for the Borland C++ compiler.
:mod:`distutils.cygwincompiler` --- Cygwin Compiler
===================================================
.. module:: distutils.cygwinccompiler
This module provides the :class:`CygwinCCompiler` class, a subclass of
:class:`UnixCCompiler` that handles the Cygwin port of the GNU C compiler to
Windows. It also contains the Mingw32CCompiler class which handles the mingw32
port of GCC (same as cygwin in no-cygwin mode).
:mod:`distutils.emxccompiler` --- OS/2 EMX Compiler
===================================================
.. module:: distutils.emxccompiler
:synopsis: OS/2 EMX Compiler support
This module provides the EMXCCompiler class, a subclass of
:class:`UnixCCompiler` that handles the EMX port of the GNU C compiler to OS/2.
:mod:`distutils.archive_util` --- Archiving utilities
======================================================
.. module:: distutils.archive_util
:synopsis: Utility functions for creating archive files (tarballs, zip files, ...)
This module provides a few functions for creating archive files, such as
tarballs or zipfiles.
.. function:: make_archive(base_name, format[, root_dir=None, base_dir=None, verbose=0, dry_run=0])
Create an archive file (eg. ``zip`` or ``tar``). *base_name* is the name of
the file to create, minus any format-specific extension; *format* is the
archive format: one of ``zip``, ``tar``, ``ztar``, or ``gztar``. *root_dir* is
a directory that will be the root directory of the archive; ie. we typically
``chdir`` into *root_dir* before creating the archive. *base_dir* is the
directory where we start archiving from; ie. *base_dir* will be the common
prefix of all files and directories in the archive. *root_dir* and *base_dir*
both default to the current directory. Returns the name of the archive file.
.. function:: make_tarball(base_name, base_dir[, compress='gzip', verbose=0, dry_run=0])
'Create an (optional compressed) archive as a tar file from all files in and
under *base_dir*. *compress* must be ``'gzip'`` (the default), ``'compress'``,
``'bzip2'``, or ``None``. Both :program:`tar` and the compression utility named
by *compress* must be on the default program search path, so this is probably
Unix-specific. The output tar file will be named :file:`base_dir.tar`,
possibly plus the appropriate compression extension (:file:`.gz`, :file:`.bz2`
or :file:`.Z`). Return the output filename.
.. function:: make_zipfile(base_name, base_dir[, verbose=0, dry_run=0])
Create a zip file from all files in and under *base_dir*. The output zip file
will be named *base_name* + :file:`.zip`. Uses either the :mod:`zipfile` Python
module (if available) or the InfoZIP :file:`zip` utility (if installed and
found on the default search path). If neither tool is available, raises
:exc:`DistutilsExecError`. Returns the name of the output zip file.
:mod:`distutils.dep_util` --- Dependency checking
=================================================
.. module:: distutils.dep_util
:synopsis: Utility functions for simple dependency checking
This module provides functions for performing simple, timestamp-based
dependency of files and groups of files; also, functions based entirely on such
timestamp dependency analysis.
.. function:: newer(source, target)
Return true if *source* exists and is more recently modified than *target*, or
if *source* exists and *target* doesn't. Return false if both exist and *target*
is the same age or newer than *source*. Raise :exc:`DistutilsFileError` if
*source* does not exist.
.. function:: newer_pairwise(sources, targets)
Walk two filename lists in parallel, testing if each source is newer than its
corresponding target. Return a pair of lists (*sources*, *targets*) where
source is newer than target, according to the semantics of :func:`newer`.
.. % % equivalent to a listcomp...
.. function:: newer_group(sources, target[, missing='error'])
Return true if *target* is out-of-date with respect to any file listed in
*sources*. In other words, if *target* exists and is newer than every file in
*sources*, return false; otherwise return true. *missing* controls what we do
when a source file is missing; the default (``'error'``) is to blow up with an
:exc:`OSError` from inside :func:`os.stat`; if it is ``'ignore'``, we silently
drop any missing source files; if it is ``'newer'``, any missing source files
make us assume that *target* is out-of-date (this is handy in "dry-run" mode:
it'll make you pretend to carry out commands that wouldn't work because inputs
are missing, but that doesn't matter because you're not actually going to run
the commands).
:mod:`distutils.dir_util` --- Directory tree operations
=======================================================
.. module:: distutils.dir_util
:synopsis: Utility functions for operating on directories and directory trees
This module provides functions for operating on directories and trees of
directories.
.. function:: mkpath(name[, mode=0777, verbose=0, dry_run=0])
Create a directory and any missing ancestor directories. If the directory
already exists (or if *name* is the empty string, which means the current
directory, which of course exists), then do nothing. Raise
:exc:`DistutilsFileError` if unable to create some directory along the way (eg.
some sub-path exists, but is a file rather than a directory). If *verbose* is
true, print a one-line summary of each mkdir to stdout. Return the list of
directories actually created.
.. function:: create_tree(base_dir, files[, mode=0777, verbose=0, dry_run=0])
Create all the empty directories under *base_dir* needed to put *files* there.
*base_dir* is just the name of a directory which doesn't necessarily exist
yet; *files* is a list of filenames to be interpreted relative to *base_dir*.
*base_dir* + the directory portion of every file in *files* will be created if
it doesn't already exist. *mode*, *verbose* and *dry_run* flags are as for
:func:`mkpath`.
.. function:: copy_tree(src, dst[, preserve_mode=1, preserve_times=1, preserve_symlinks=0, update=0, verbose=0, dry_run=0])
Copy an entire directory tree *src* to a new location *dst*. Both *src* and
*dst* must be directory names. If *src* is not a directory, raise
:exc:`DistutilsFileError`. If *dst* does not exist, it is created with
:func:`mkpath`. The end result of the copy is that every file in *src* is
copied to *dst*, and directories under *src* are recursively copied to *dst*.
Return the list of files that were copied or might have been copied, using their
output name. The return value is unaffected by *update* or *dry_run*: it is
simply the list of all files under *src*, with the names changed to be under
*dst*.
*preserve_mode* and *preserve_times* are the same as for
:func:`distutils.file_util.copy_file`; note that they only apply to
regular files, not to
directories. If *preserve_symlinks* is true, symlinks will be copied as
symlinks (on platforms that support them!); otherwise (the default), the
destination of the symlink will be copied. *update* and *verbose* are the same
as for :func:`copy_file`.
Files in *src* that begin with :file:`.nfs` are skipped (more information on
these files is available in answer D2 of the `NFS FAQ page
<http://nfs.sourceforge.net/#section_d>`_.
.. versionchanged:: 2.7.4
NFS files are ignored.
.. function:: remove_tree(directory[, verbose=0, dry_run=0])
Recursively remove *directory* and all files and directories underneath it. Any
errors are ignored (apart from being reported to ``sys.stdout`` if *verbose* is
true).
:mod:`distutils.file_util` --- Single file operations
=====================================================
.. module:: distutils.file_util
:synopsis: Utility functions for operating on single files
This module contains some utility functions for operating on individual files.
.. function:: copy_file(src, dst[, preserve_mode=1, preserve_times=1, update=0, link=None, verbose=0, dry_run=0])
Copy file *src* to *dst*. If *dst* is a directory, then *src* is copied there
with the same name; otherwise, it must be a filename. (If the file exists, it
will be ruthlessly clobbered.) If *preserve_mode* is true (the default), the
file's mode (type and permission bits, or whatever is analogous on the
current platform) is copied. If *preserve_times* is true (the default), the
last-modified and last-access times are copied as well. If *update* is true,
*src* will only be copied if *dst* does not exist, or if *dst* does exist but
is older than *src*.
*link* allows you to make hard links (using :func:`os.link`) or symbolic links
(using :func:`os.symlink`) instead of copying: set it to ``'hard'`` or
``'sym'``; if it is ``None`` (the default), files are copied. Don't set *link*
on systems that don't support it: :func:`copy_file` doesn't check if hard or
symbolic linking is available. It uses :func:`_copy_file_contents` to copy file
contents.
Return a tuple ``(dest_name, copied)``: *dest_name* is the actual name of the
output file, and *copied* is true if the file was copied (or would have been
copied, if *dry_run* true).
.. % XXX if the destination file already exists, we clobber it if
.. % copying, but blow up if linking. Hmmm. And I don't know what
.. % macostools.copyfile() does. Should definitely be consistent, and
.. % should probably blow up if destination exists and we would be
.. % changing it (ie. it's not already a hard/soft link to src OR
.. % (not update) and (src newer than dst)).
.. function:: move_file(src, dst[, verbose, dry_run])
Move file *src* to *dst*. If *dst* is a directory, the file will be moved into
it with the same name; otherwise, *src* is just renamed to *dst*. Returns the
new full name of the file.
.. warning::
Handles cross-device moves on Unix using :func:`copy_file`. What about
other systems?
.. function:: write_file(filename, contents)
Create a file called *filename* and write *contents* (a sequence of strings
without line terminators) to it.
:mod:`distutils.util` --- Miscellaneous other utility functions
===============================================================
.. module:: distutils.util
:synopsis: Miscellaneous other utility functions
This module contains other assorted bits and pieces that don't fit into any
other utility module.
.. function:: get_platform()
Return a string that identifies the current platform. This is used mainly to
distinguish platform-specific build directories and platform-specific built
distributions. Typically includes the OS name and version and the architecture
(as supplied by 'os.uname()'), although the exact information included depends
on the OS; eg. for IRIX the architecture isn't particularly important (IRIX only
runs on SGI hardware), but for Linux the kernel version isn't particularly
important.
Examples of returned values:
* ``linux-i586``
* ``linux-alpha``
* ``solaris-2.6-sun4u``
* ``irix-5.3``
* ``irix64-6.2``
For non-POSIX platforms, currently just returns ``sys.platform``.
For Mac OS X systems the OS version reflects the minimal version on which
binaries will run (that is, the value of ``MACOSX_DEPLOYMENT_TARGET``
during the build of Python), not the OS version of the current system.
For universal binary builds on Mac OS X the architecture value reflects
the universal binary status instead of the architecture of the current
processor. For 32-bit universal binaries the architecture is ``fat``,
for 64-bit universal binaries the architecture is ``fat64``, and
for 4-way universal binaries the architecture is ``universal``. Starting
from Python 2.7 and Python 3.2 the architecture ``fat3`` is used for
a 3-way universal build (ppc, i386, x86_64) and ``intel`` is used for
a universal build with the i386 and x86_64 architectures
Examples of returned values on Mac OS X:
* ``macosx-10.3-ppc``
* ``macosx-10.3-fat``
* ``macosx-10.5-universal``
* ``macosx-10.6-intel``
.. function:: convert_path(pathname)
Return 'pathname' as a name that will work on the native filesystem, i.e. split
it on '/' and put it back together again using the current directory separator.
Needed because filenames in the setup script are always supplied in Unix style,
and have to be converted to the local convention before we can actually use them
in the filesystem. Raises :exc:`ValueError` on non-Unix-ish systems if
*pathname* either starts or ends with a slash.
.. function:: change_root(new_root, pathname)
Return *pathname* with *new_root* prepended. If *pathname* is relative, this is
equivalent to ``os.path.join(new_root,pathname)`` Otherwise, it requires making
*pathname* relative and then joining the two, which is tricky on DOS/Windows.
.. function:: check_environ()
Ensure that 'os.environ' has all the environment variables we guarantee that
users can use in config files, command-line options, etc. Currently this
includes:
* :envvar:`HOME` - user's home directory (Unix only)
* :envvar:`PLAT` - description of the current platform, including hardware and
OS (see :func:`get_platform`)
.. function:: subst_vars(s, local_vars)
Perform shell/Perl-style variable substitution on *s*. Every occurrence of
``$`` followed by a name is considered a variable, and variable is substituted
by the value found in the *local_vars* dictionary, or in ``os.environ`` if it's
not in *local_vars*. *os.environ* is first checked/augmented to guarantee that
it contains certain values: see :func:`check_environ`. Raise :exc:`ValueError`
for any variables not found in either *local_vars* or ``os.environ``.
Note that this is not a fully-fledged string interpolation function. A valid
``$variable`` can consist only of upper and lower case letters, numbers and an
underscore. No { } or ( ) style quoting is available.
.. function:: split_quoted(s)
Split a string up according to Unix shell-like rules for quotes and backslashes.
In short: words are delimited by spaces, as long as those spaces are not escaped
by a backslash, or inside a quoted string. Single and double quotes are
equivalent, and the quote characters can be backslash-escaped. The backslash is
stripped from any two-character escape sequence, leaving only the escaped
character. The quote characters are stripped from any quoted string. Returns a
list of words.
.. % Should probably be moved into the standard library.
.. function:: execute(func, args[, msg=None, verbose=0, dry_run=0])
Perform some action that affects the outside world (for instance, writing to the
filesystem). Such actions are special because they are disabled by the
*dry_run* flag. This method takes care of all that bureaucracy for you; all
you have to do is supply the function to call and an argument tuple for it (to
embody the "external action" being performed), and an optional message to print.
.. function:: strtobool(val)
Convert a string representation of truth to true (1) or false (0).
True values are ``y``, ``yes``, ``t``, ``true``, ``on`` and ``1``; false values
are ``n``, ``no``, ``f``, ``false``, ``off`` and ``0``. Raises
:exc:`ValueError` if *val* is anything else.
.. function:: byte_compile(py_files[, optimize=0, force=0, prefix=None, base_dir=None, verbose=1, dry_run=0, direct=None])
Byte-compile a collection of Python source files to either :file:`.pyc` or
:file:`.pyo` files in the same directory. *py_files* is a list of files to
compile; any files that don't end in :file:`.py` are silently skipped.
*optimize* must be one of the following:
* ``0`` - don't optimize (generate :file:`.pyc`)
* ``1`` - normal optimization (like ``python -O``)
* ``2`` - extra optimization (like ``python -OO``)
If *force* is true, all files are recompiled regardless of timestamps.
The source filename encoded in each :term:`bytecode` file defaults to the filenames
listed in *py_files*; you can modify these with *prefix* and *basedir*.
*prefix* is a string that will be stripped off of each source filename, and
*base_dir* is a directory name that will be prepended (after *prefix* is
stripped). You can supply either or both (or neither) of *prefix* and
*base_dir*, as you wish.
If *dry_run* is true, doesn't actually do anything that would affect the
filesystem.
Byte-compilation is either done directly in this interpreter process with the
standard :mod:`py_compile` module, or indirectly by writing a temporary script
and executing it. Normally, you should let :func:`byte_compile` figure out to
use direct compilation or not (see the source for details). The *direct* flag
is used by the script generated in indirect mode; unless you know what you're
doing, leave it set to ``None``.
.. function:: rfc822_escape(header)
Return a version of *header* escaped for inclusion in an :rfc:`822` header, by
ensuring there are 8 spaces space after each newline. Note that it does no other
modification of the string.
.. % this _can_ be replaced
.. % \subsection{Distutils objects}
:mod:`distutils.dist` --- The Distribution class
================================================
.. module:: distutils.dist
:synopsis: Provides the Distribution class, which represents the module distribution being
built/installed/distributed
This module provides the :class:`~distutils.core.Distribution` class, which
represents the module distribution being built/installed/distributed.
:mod:`distutils.extension` --- The Extension class
==================================================
.. module:: distutils.extension
:synopsis: Provides the Extension class, used to describe C/C++ extension modules in setup
scripts
This module provides the :class:`Extension` class, used to describe C/C++
extension modules in setup scripts.
.. % \subsection{Ungrouped modules}
.. % The following haven't been moved into a more appropriate section yet.
:mod:`distutils.debug` --- Distutils debug mode
===============================================
.. module:: distutils.debug
:synopsis: Provides the debug flag for distutils
This module provides the DEBUG flag.
:mod:`distutils.errors` --- Distutils exceptions
================================================
.. module:: distutils.errors
:synopsis: Provides standard distutils exceptions
Provides exceptions used by the Distutils modules. Note that Distutils modules
may raise standard exceptions; in particular, SystemExit is usually raised for
errors that are obviously the end-user's fault (eg. bad command-line arguments).
This module is safe to use in ``from ... import *`` mode; it only exports
symbols whose names start with ``Distutils`` and end with ``Error``.
:mod:`distutils.fancy_getopt` --- Wrapper around the standard getopt module
===========================================================================
.. module:: distutils.fancy_getopt
:synopsis: Additional getopt functionality
This module provides a wrapper around the standard :mod:`getopt` module that
provides the following additional features:
* short and long options are tied together
* options have help strings, so :func:`fancy_getopt` could potentially create a
complete usage summary
* options set attributes of a passed-in object
* boolean options can have "negative aliases" --- eg. if :option:`!--quiet` is
the "negative alias" of :option:`!--verbose`, then :option:`!--quiet` on the
command line sets *verbose* to false.
.. function:: fancy_getopt(options, negative_opt, object, args)
Wrapper function. *options* is a list of ``(long_option, short_option,
help_string)`` 3-tuples as described in the constructor for
:class:`FancyGetopt`. *negative_opt* should be a dictionary mapping option names
to option names, both the key and value should be in the *options* list.
*object* is an object which will be used to store values (see the :meth:`getopt`
method of the :class:`FancyGetopt` class). *args* is the argument list. Will use
``sys.argv[1:]`` if you pass ``None`` as *args*.
.. function:: wrap_text(text, width)
Wraps *text* to less than *width* wide.
.. class:: FancyGetopt([option_table=None])
The option_table is a list of 3-tuples: ``(long_option, short_option,
help_string)``
If an option takes an argument, its *long_option* should have ``'='`` appended;
*short_option* should just be a single character, no ``':'`` in any case.
*short_option* should be ``None`` if a *long_option* doesn't have a
corresponding *short_option*. All option tuples must have long options.
The :class:`FancyGetopt` class provides the following methods:
.. method:: FancyGetopt.getopt([args=None, object=None])
Parse command-line options in args. Store as attributes on *object*.
If *args* is ``None`` or not supplied, uses ``sys.argv[1:]``. If *object* is
``None`` or not supplied, creates a new :class:`OptionDummy` instance, stores
option values there, and returns a tuple ``(args, object)``. If *object* is
supplied, it is modified in place and :func:`getopt` just returns *args*; in
both cases, the returned *args* is a modified copy of the passed-in *args* list,
which is left untouched.
.. % and args returned are?
.. method:: FancyGetopt.get_option_order()
Returns the list of ``(option, value)`` tuples processed by the previous run of
:meth:`getopt` Raises :exc:`RuntimeError` if :meth:`getopt` hasn't been called
yet.
.. method:: FancyGetopt.generate_help([header=None])
Generate help text (a list of strings, one per suggested line of output) from
the option table for this :class:`FancyGetopt` object.
If supplied, prints the supplied *header* at the top of the help.
:mod:`distutils.filelist` --- The FileList class
================================================
.. module:: distutils.filelist
:synopsis: The FileList class, used for poking about the file system and
building lists of files.
This module provides the :class:`FileList` class, used for poking about the
filesystem and building lists of files.
:mod:`distutils.log` --- Simple PEP 282-style logging
=====================================================
.. module:: distutils.log
:synopsis: A simple logging mechanism, 282-style
:mod:`distutils.spawn` --- Spawn a sub-process
==============================================
.. module:: distutils.spawn
:synopsis: Provides the spawn() function
This module provides the :func:`spawn` function, a front-end to various
platform-specific functions for launching another program in a sub-process.
Also provides :func:`find_executable` to search the path for a given executable
name.
:mod:`distutils.sysconfig` --- System configuration information
===============================================================
.. module:: distutils.sysconfig
:synopsis: Low-level access to configuration information of the Python interpreter.
.. moduleauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
.. moduleauthor:: Greg Ward <gward@python.net>
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
The :mod:`distutils.sysconfig` module provides access to Python's low-level
configuration information. The specific configuration variables available
depend heavily on the platform and configuration. The specific variables depend
on the build process for the specific version of Python being run; the variables
are those found in the :file:`Makefile` and configuration header that are
installed with Python on Unix systems. The configuration header is called
:file:`pyconfig.h` for Python versions starting with 2.2, and :file:`config.h`
for earlier versions of Python.
Some additional functions are provided which perform some useful manipulations
for other parts of the :mod:`distutils` package.
.. data:: PREFIX
The result of ``os.path.normpath(sys.prefix)``.
.. data:: EXEC_PREFIX
The result of ``os.path.normpath(sys.exec_prefix)``.
.. function:: get_config_var(name)
Return the value of a single variable. This is equivalent to
``get_config_vars().get(name)``.
.. function:: get_config_vars(...)
Return a set of variable definitions. If there are no arguments, this returns a
dictionary mapping names of configuration variables to values. If arguments are
provided, they should be strings, and the return value will be a sequence giving
the associated values. If a given name does not have a corresponding value,
``None`` will be included for that variable.
.. function:: get_config_h_filename()
Return the full path name of the configuration header. For Unix, this will be
the header generated by the :program:`configure` script; for other platforms the
header will have been supplied directly by the Python source distribution. The
file is a platform-specific text file.
.. function:: get_makefile_filename()
Return the full path name of the :file:`Makefile` used to build Python. For
Unix, this will be a file generated by the :program:`configure` script; the
meaning for other platforms will vary. The file is a platform-specific text
file, if it exists. This function is only useful on POSIX platforms.
.. function:: get_python_inc([plat_specific[, prefix]])
Return the directory for either the general or platform-dependent C include
files. If *plat_specific* is true, the platform-dependent include directory is
returned; if false or omitted, the platform-independent directory is returned.
If *prefix* is given, it is used as either the prefix instead of
:const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if
*plat_specific* is true.
.. function:: get_python_lib([plat_specific[, standard_lib[, prefix]]])
Return the directory for either the general or platform-dependent library
installation. If *plat_specific* is true, the platform-dependent include
directory is returned; if false or omitted, the platform-independent directory
is returned. If *prefix* is given, it is used as either the prefix instead of
:const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if
*plat_specific* is true. If *standard_lib* is true, the directory for the
standard library is returned rather than the directory for the installation of
third-party extensions.
The following function is only intended for use within the :mod:`distutils`
package.
.. function:: customize_compiler(compiler)
Do any platform-specific customization of a
:class:`distutils.ccompiler.CCompiler` instance.
This function is only needed on Unix at this time, but should be called
consistently to support forward-compatibility. It inserts the information that
varies across Unix flavors and is stored in Python's :file:`Makefile`. This
information includes the selected compiler, compiler and linker options, and the
extension used by the linker for shared objects.
This function is even more special-purpose, and should only be used from
Python's own build procedures.
.. function:: set_python_build()
Inform the :mod:`distutils.sysconfig` module that it is being used as part of
the build process for Python. This changes a lot of relative locations for
files, allowing them to be located in the build area rather than in an installed
Python.
:mod:`distutils.text_file` --- The TextFile class
=================================================
.. module:: distutils.text_file
:synopsis: provides the TextFile class, a simple interface to text files
This module provides the :class:`TextFile` class, which gives an interface to
text files that (optionally) takes care of stripping comments, ignoring blank
lines, and joining lines with backslashes.
.. class:: TextFile([filename=None, file=None, **options])
This class provides a file-like object that takes care of all the things you
commonly want to do when processing a text file that has some line-by-line
syntax: strip comments (as long as ``#`` is your comment character), skip blank
lines, join adjacent lines by escaping the newline (ie. backslash at end of
line), strip leading and/or trailing whitespace. All of these are optional and
independently controllable.
The class provides a :meth:`warn` method so you can generate warning messages
that report physical line number, even if the logical line in question spans
multiple physical lines. Also provides :meth:`unreadline` for implementing
line-at-a-time lookahead.
:class:`TextFile` instances are create with either *filename*, *file*, or both.
:exc:`RuntimeError` is raised if both are ``None``. *filename* should be a
string, and *file* a file object (or something that provides :meth:`readline`
and :meth:`close` methods). It is recommended that you supply at least
*filename*, so that :class:`TextFile` can include it in warning messages. If
*file* is not supplied, :class:`TextFile` creates its own using the
:func:`open` built-in function.
The options are all boolean, and affect the values returned by :meth:`readline`
.. tabularcolumns:: |l|L|l|
+------------------+--------------------------------+---------+
| option name | description | default |
+==================+================================+=========+
| *strip_comments* | strip from ``'#'`` to end-of- | true |
| | line, as well as any | |
| | whitespace leading up to the | |
| | ``'#'``\ ---unless it is | |
| | escaped by a backslash | |
+------------------+--------------------------------+---------+
| *lstrip_ws* | strip leading whitespace from | false |
| | each line before returning it | |
+------------------+--------------------------------+---------+
| *rstrip_ws* | strip trailing whitespace | true |
| | (including line terminator!) | |
| | from each line before | |
| | returning it. | |
+------------------+--------------------------------+---------+
| *skip_blanks* | skip lines that are empty | true |
| | \*after\* stripping comments | |
| | and whitespace. (If both | |
| | lstrip_ws and rstrip_ws are | |
| | false, then some lines may | |
| | consist of solely whitespace: | |
| | these will \*not\* be skipped, | |
| | even if *skip_blanks* is | |
| | true.) | |
+------------------+--------------------------------+---------+
| *join_lines* | if a backslash is the last | false |
| | non-newline character on a | |
| | line after stripping comments | |
| | and whitespace, join the | |
| | following line to it to form | |
| | one logical line; if N | |
| | consecutive lines end with a | |
| | backslash, then N+1 physical | |
| | lines will be joined to form | |
| | one logical line. | |
+------------------+--------------------------------+---------+
| *collapse_join* | strip leading whitespace from | false |
| | lines that are joined to their | |
| | predecessor; only matters if | |
| | ``(join_lines and not | |
| | lstrip_ws)`` | |
+------------------+--------------------------------+---------+
Note that since *rstrip_ws* can strip the trailing newline, the semantics of
:meth:`readline` must differ from those of the built-in file object's
:meth:`readline` method! In particular, :meth:`readline` returns ``None`` for
end-of-file: an empty string might just be a blank line (or an all-whitespace
line), if *rstrip_ws* is true but *skip_blanks* is not.
.. method:: TextFile.open(filename)
Open a new file *filename*. This overrides any *file* or *filename*
constructor arguments.
.. method:: TextFile.close()
Close the current file and forget everything we know about it (including the
filename and the current line number).
.. method:: TextFile.warn(msg[,line=None])
Print (to stderr) a warning message tied to the current logical line in the
current file. If the current logical line in the file spans multiple physical
lines, the warning refers to the whole range, such as ``"lines 3-5"``. If
*line* is supplied, it overrides the current line number; it may be a list or
tuple to indicate a range of physical lines, or an integer for a single
physical line.
.. method:: TextFile.readline()
Read and return a single logical line from the current file (or from an internal
buffer if lines have previously been "unread" with :meth:`unreadline`). If the
*join_lines* option is true, this may involve reading multiple physical lines
concatenated into a single string. Updates the current line number, so calling
:meth:`warn` after :meth:`readline` emits a warning about the physical line(s)
just read. Returns ``None`` on end-of-file, since the empty string can occur
if *rstrip_ws* is true but *strip_blanks* is not.
.. method:: TextFile.readlines()
Read and return the list of all logical lines remaining in the current file.
This updates the current line number to the last line of the file.
.. method:: TextFile.unreadline(line)
Push *line* (a string) onto an internal buffer that will be checked by future
:meth:`readline` calls. Handy for implementing a parser with line-at-a-time
lookahead. Note that lines that are "unread" with :meth:`unreadline` are not
subsequently re-cleansed (whitespace stripped, or whatever) when read with
:meth:`readline`. If multiple calls are made to :meth:`unreadline` before a call
to :meth:`readline`, the lines will be returned most in most recent first order.
:mod:`distutils.version` --- Version number classes
===================================================
.. module:: distutils.version
:synopsis: implements classes that represent module version numbers.
.. % todo
.. % \section{Distutils Commands}
.. %
.. % This part of Distutils implements the various Distutils commands, such
.. % as \code{build}, \code{install} \&c. Each command is implemented as a
.. % separate module, with the command name as the name of the module.
:mod:`distutils.cmd` --- Abstract base class for Distutils commands
===================================================================
.. module:: distutils.cmd
:synopsis: This module provides the abstract base class Command. This class
is subclassed by the modules in the distutils.command subpackage.
This module supplies the abstract base class :class:`Command`.
.. class:: Command(dist)
Abstract base class for defining command classes, the "worker bees" of the
Distutils. A useful analogy for command classes is to think of them as
subroutines with local variables called *options*. The options are declared
in :meth:`initialize_options` and defined (given their final values) in
:meth:`finalize_options`, both of which must be defined by every command
class. The distinction between the two is necessary because option values
might come from the outside world (command line, config file, ...), and any
options dependent on other options must be computed after these outside
influences have been processed --- hence :meth:`finalize_options`. The body
of the subroutine, where it does all its work based on the values of its
options, is the :meth:`run` method, which must also be implemented by every
command class.
The class constructor takes a single argument *dist*, a
:class:`~distutils.core.Distribution` instance.
Creating a new Distutils command
================================
This section outlines the steps to create a new Distutils command.
A new command lives in a module in the :mod:`distutils.command` package. There
is a sample template in that directory called :file:`command_template`. Copy
this file to a new module with the same name as the new command you're
implementing. This module should implement a class with the same name as the
module (and the command). So, for instance, to create the command
``peel_banana`` (so that users can run ``setup.py peel_banana``), you'd copy
:file:`command_template` to :file:`distutils/command/peel_banana.py`, then edit
it so that it's implementing the class :class:`peel_banana`, a subclass of
:class:`distutils.cmd.Command`.
Subclasses of :class:`Command` must define the following methods.
.. method:: Command.initialize_options()
Set default values for all the options that this command supports. Note that
these defaults may be overridden by other commands, by the setup script, by
config files, or by the command-line. Thus, this is not the place to code
dependencies between options; generally, :meth:`initialize_options`
implementations are just a bunch of ``self.foo = None`` assignments.
.. method:: Command.finalize_options()
Set final values for all the options that this command supports. This is
always called as late as possible, ie. after any option assignments from the
command-line or from other commands have been done. Thus, this is the place
to code option dependencies: if *foo* depends on *bar*, then it is safe to
set *foo* from *bar* as long as *foo* still has the same value it was
assigned in :meth:`initialize_options`.
.. method:: Command.run()
A command's raison d'etre: carry out the action it exists to perform, controlled
by the options initialized in :meth:`initialize_options`, customized by other
commands, the setup script, the command-line, and config files, and finalized in
:meth:`finalize_options`. All terminal output and filesystem interaction should
be done by :meth:`run`.
.. attribute:: Command.sub_commands
*sub_commands* formalizes the notion of a "family" of commands,
e.g. ``install`` as the parent with sub-commands ``install_lib``,
``install_headers``, etc. The parent of a family of commands defines
*sub_commands* as a class attribute; it's a list of 2-tuples ``(command_name,
predicate)``, with *command_name* a string and *predicate* a function, a
string or ``None``. *predicate* is a method of the parent command that
determines whether the corresponding command is applicable in the current
situation. (E.g. ``install_headers`` is only applicable if we have any C
header files to install.) If *predicate* is ``None``, that command is always
applicable.
*sub_commands* is usually defined at the *end* of a class, because
predicates can be methods of the class, so they must already have been
defined. The canonical example is the :command:`install` command.
:mod:`distutils.command` --- Individual Distutils commands
==========================================================
.. module:: distutils.command
:synopsis: This subpackage contains one module for each standard Distutils command.
.. % \subsubsection{Individual Distutils commands}
.. % todo
:mod:`distutils.command.bdist` --- Build a binary installer
===========================================================
.. module:: distutils.command.bdist
:synopsis: Build a binary installer for a package
.. % todo
:mod:`distutils.command.bdist_packager` --- Abstract base class for packagers
=============================================================================
.. module:: distutils.command.bdist_packager
:synopsis: Abstract base class for packagers
.. % todo
:mod:`distutils.command.bdist_dumb` --- Build a "dumb" installer
================================================================
.. module:: distutils.command.bdist_dumb
:synopsis: Build a "dumb" installer - a simple archive of files
.. % todo
:mod:`distutils.command.bdist_msi` --- Build a Microsoft Installer binary package
=================================================================================
.. module:: distutils.command.bdist_msi
:synopsis: Build a binary distribution as a Windows MSI file
.. class:: bdist_msi
Builds a `Windows Installer`_ (.msi) binary package.
.. _Windows Installer: https://msdn.microsoft.com/en-us/library/cc185688(VS.85).aspx
In most cases, the ``bdist_msi`` installer is a better choice than the
``bdist_wininst`` installer, because it provides better support for
Win64 platforms, allows administrators to perform non-interactive
installations, and allows installation through group policies.
:mod:`distutils.command.bdist_rpm` --- Build a binary distribution as a Redhat RPM and SRPM
===========================================================================================
.. module:: distutils.command.bdist_rpm
:synopsis: Build a binary distribution as a Redhat RPM and SRPM
.. % todo
:mod:`distutils.command.bdist_wininst` --- Build a Windows installer
====================================================================
.. module:: distutils.command.bdist_wininst
:synopsis: Build a Windows installer
.. % todo
:mod:`distutils.command.sdist` --- Build a source distribution
==============================================================
.. module:: distutils.command.sdist
:synopsis: Build a source distribution
.. % todo
:mod:`distutils.command.build` --- Build all files of a package
===============================================================
.. module:: distutils.command.build
:synopsis: Build all files of a package
.. % todo
:mod:`distutils.command.build_clib` --- Build any C libraries in a package
==========================================================================
.. module:: distutils.command.build_clib
:synopsis: Build any C libraries in a package
.. % todo
:mod:`distutils.command.build_ext` --- Build any extensions in a package
========================================================================
.. module:: distutils.command.build_ext
:synopsis: Build any extensions in a package
.. % todo
:mod:`distutils.command.build_py` --- Build the .py/.pyc files of a package
===========================================================================
.. module:: distutils.command.build_py
:synopsis: Build the .py/.pyc files of a package
:mod:`distutils.command.build_scripts` --- Build the scripts of a package
=========================================================================
.. module:: distutils.command.build_scripts
:synopsis: Build the scripts of a package
.. % todo
:mod:`distutils.command.clean` --- Clean a package build area
=============================================================
.. module:: distutils.command.clean
:synopsis: Clean a package build area
This command removes the temporary files created by :command:`build`
and its subcommands, like intermediary compiled object files. With
the ``--all`` option, the complete build directory will be removed.
Extension modules built :ref:`in place <distutils-build-ext-inplace>`
will not be cleaned, as they are not in the build directory.
:mod:`distutils.command.config` --- Perform package configuration
=================================================================
.. module:: distutils.command.config
:synopsis: Perform package configuration
.. % todo
:mod:`distutils.command.install` --- Install a package
======================================================
.. module:: distutils.command.install
:synopsis: Install a package
.. % todo
:mod:`distutils.command.install_data` --- Install data files from a package
===========================================================================
.. module:: distutils.command.install_data
:synopsis: Install data files from a package
.. % todo
:mod:`distutils.command.install_headers` --- Install C/C++ header files from a package
======================================================================================
.. module:: distutils.command.install_headers
:synopsis: Install C/C++ header files from a package
.. % todo
:mod:`distutils.command.install_lib` --- Install library files from a package
=============================================================================
.. module:: distutils.command.install_lib
:synopsis: Install library files from a package
.. % todo
:mod:`distutils.command.install_scripts` --- Install script files from a package
================================================================================
.. module:: distutils.command.install_scripts
:synopsis: Install script files from a package
.. % todo
:mod:`distutils.command.register` --- Register a module with the Python Package Index
=====================================================================================
.. module:: distutils.command.register
:synopsis: Register a module with the Python Package Index
The ``register`` command registers the package with the Python Package Index.
This is described in more detail in :pep:`301`.
.. % todo
:mod:`distutils.command.check` --- Check the meta-data of a package
===================================================================
.. module:: distutils.command.check
:synopsis: Check the metadata of a package
The ``check`` command performs some tests on the meta-data of a package.
For example, it verifies that all required meta-data are provided as
the arguments passed to the :func:`setup` function.
.. % todo
PK %�\'7�IfV fV ) html/_sources/distutils/builtdist.rst.txtnu �[��� .. _built-dist:
****************************
Creating Built Distributions
****************************
A "built distribution" is what you're probably used to thinking of either as a
"binary package" or an "installer" (depending on your background). It's not
necessarily binary, though, because it might contain only Python source code
and/or byte-code; and we don't call it a package, because that word is already
spoken for in Python. (And "installer" is a term specific to the world of
mainstream desktop systems.)
A built distribution is how you make life as easy as possible for installers of
your module distribution: for users of RPM-based Linux systems, it's a binary
RPM; for Windows users, it's an executable installer; for Debian-based Linux
users, it's a Debian package; and so forth. Obviously, no one person will be
able to create built distributions for every platform under the sun, so the
Distutils are designed to enable module developers to concentrate on their
specialty---writing code and creating source distributions---while an
intermediary species called *packagers* springs up to turn source distributions
into built distributions for as many platforms as there are packagers.
Of course, the module developer could be their own packager; or the packager could
be a volunteer "out there" somewhere who has access to a platform which the
original developer does not; or it could be software periodically grabbing new
source distributions and turning them into built distributions for as many
platforms as the software has access to. Regardless of who they are, a packager
uses the setup script and the :command:`bdist` command family to generate built
distributions.
As a simple example, if I run the following command in the Distutils source
tree::
python setup.py bdist
then the Distutils builds my module distribution (the Distutils itself in this
case), does a "fake" installation (also in the :file:`build` directory), and
creates the default type of built distribution for my platform. The default
format for built distributions is a "dumb" tar file on Unix, and a simple
executable installer on Windows. (That tar file is considered "dumb" because it
has to be unpacked in a specific location to work.)
Thus, the above command on a Unix system creates
:file:`Distutils-1.0.{plat}.tar.gz`; unpacking this tarball from the right place
installs the Distutils just as though you had downloaded the source distribution
and run ``python setup.py install``. (The "right place" is either the root of
the filesystem or Python's :file:`{prefix}` directory, depending on the options
given to the :command:`bdist_dumb` command; the default is to make dumb
distributions relative to :file:`{prefix}`.)
Obviously, for pure Python distributions, this isn't any simpler than just
running ``python setup.py install``\ ---but for non-pure distributions, which
include extensions that would need to be compiled, it can mean the difference
between someone being able to use your extensions or not. And creating "smart"
built distributions, such as an RPM package or an executable installer for
Windows, is far more convenient for users even if your distribution doesn't
include any extensions.
The :command:`bdist` command has a :option:`!--formats` option, similar to the
:command:`sdist` command, which you can use to select the types of built
distribution to generate: for example, ::
python setup.py bdist --format=zip
would, when run on a Unix system, create :file:`Distutils-1.0.{plat}.zip`\
---again, this archive would be unpacked from the root directory to install the
Distutils.
The available formats for built distributions are:
+-------------+------------------------------+---------+
| Format | Description | Notes |
+=============+==============================+=========+
| ``gztar`` | gzipped tar file | (1),(3) |
| | (:file:`.tar.gz`) | |
+-------------+------------------------------+---------+
| ``ztar`` | compressed tar file | \(3) |
| | (:file:`.tar.Z`) | |
+-------------+------------------------------+---------+
| ``tar`` | tar file (:file:`.tar`) | \(3) |
+-------------+------------------------------+---------+
| ``zip`` | zip file (:file:`.zip`) | (2),(4) |
+-------------+------------------------------+---------+
| ``rpm`` | RPM | \(5) |
+-------------+------------------------------+---------+
| ``pkgtool`` | Solaris :program:`pkgtool` | |
+-------------+------------------------------+---------+
| ``sdux`` | HP-UX :program:`swinstall` | |
+-------------+------------------------------+---------+
| ``wininst`` | self-extracting ZIP file for | \(4) |
| | Windows | |
+-------------+------------------------------+---------+
| ``msi`` | Microsoft Installer. | |
+-------------+------------------------------+---------+
Notes:
(1)
default on Unix
(2)
default on Windows
(3)
requires external utilities: :program:`tar` and possibly one of :program:`gzip`,
:program:`bzip2`, or :program:`compress`
(4)
requires either external :program:`zip` utility or :mod:`zipfile` module (part
of the standard Python library since Python 1.6)
(5)
requires external :program:`rpm` utility, version 3.0.4 or better (use ``rpm
--version`` to find out which version you have)
You don't have to use the :command:`bdist` command with the :option:`!--formats`
option; you can also use the command that directly implements the format you're
interested in. Some of these :command:`bdist` "sub-commands" actually generate
several similar formats; for instance, the :command:`bdist_dumb` command
generates all the "dumb" archive formats (``tar``, ``ztar``, ``gztar``, and
``zip``), and :command:`bdist_rpm` generates both binary and source RPMs. The
:command:`bdist` sub-commands, and the formats generated by each, are:
+--------------------------+-----------------------+
| Command | Formats |
+==========================+=======================+
| :command:`bdist_dumb` | tar, ztar, gztar, zip |
+--------------------------+-----------------------+
| :command:`bdist_rpm` | rpm, srpm |
+--------------------------+-----------------------+
| :command:`bdist_wininst` | wininst |
+--------------------------+-----------------------+
| :command:`bdist_msi` | msi |
+--------------------------+-----------------------+
The following sections give details on the individual :command:`bdist_\*`
commands.
.. _creating-dumb:
Creating dumb built distributions
=================================
.. XXX Need to document absolute vs. prefix-relative packages here, but first
I have to implement it!
.. _creating-rpms:
Creating RPM packages
=====================
The RPM format is used by many popular Linux distributions, including Red Hat,
SuSE, and Mandrake. If one of these (or any of the other RPM-based Linux
distributions) is your usual environment, creating RPM packages for other users
of that same distribution is trivial. Depending on the complexity of your module
distribution and differences between Linux distributions, you may also be able
to create RPMs that work on different RPM-based distributions.
The usual way to create an RPM of your module distribution is to run the
:command:`bdist_rpm` command::
python setup.py bdist_rpm
or the :command:`bdist` command with the :option:`!--format` option::
python setup.py bdist --formats=rpm
The former allows you to specify RPM-specific options; the latter allows you to
easily specify multiple formats in one run. If you need to do both, you can
explicitly specify multiple :command:`bdist_\*` commands and their options::
python setup.py bdist_rpm --packager="John Doe <jdoe@example.org>" \
bdist_wininst --target-version="2.0"
Creating RPM packages is driven by a :file:`.spec` file, much as using the
Distutils is driven by the setup script. To make your life easier, the
:command:`bdist_rpm` command normally creates a :file:`.spec` file based on the
information you supply in the setup script, on the command line, and in any
Distutils configuration files. Various options and sections in the
:file:`.spec` file are derived from options in the setup script as follows:
+------------------------------------------+----------------------------------------------+
| RPM :file:`.spec` file option or section | Distutils setup script option |
+==========================================+==============================================+
| Name | ``name`` |
+------------------------------------------+----------------------------------------------+
| Summary (in preamble) | ``description`` |
+------------------------------------------+----------------------------------------------+
| Version | ``version`` |
+------------------------------------------+----------------------------------------------+
| Vendor | ``author`` and ``author_email``, |
| | or --- & ``maintainer`` and |
| | ``maintainer_email`` |
+------------------------------------------+----------------------------------------------+
| Copyright | ``license`` |
+------------------------------------------+----------------------------------------------+
| Url | ``url`` |
+------------------------------------------+----------------------------------------------+
| %description (section) | ``long_description`` |
+------------------------------------------+----------------------------------------------+
Additionally, there are many options in :file:`.spec` files that don't have
corresponding options in the setup script. Most of these are handled through
options to the :command:`bdist_rpm` command as follows:
+-------------------------------+-----------------------------+-------------------------+
| RPM :file:`.spec` file option | :command:`bdist_rpm` option | default value |
| or section | | |
+===============================+=============================+=========================+
| Release | ``release`` | "1" |
+-------------------------------+-----------------------------+-------------------------+
| Group | ``group`` | "Development/Libraries" |
+-------------------------------+-----------------------------+-------------------------+
| Vendor | ``vendor`` | (see above) |
+-------------------------------+-----------------------------+-------------------------+
| Packager | ``packager`` | (none) |
+-------------------------------+-----------------------------+-------------------------+
| Provides | ``provides`` | (none) |
+-------------------------------+-----------------------------+-------------------------+
| Requires | ``requires`` | (none) |
+-------------------------------+-----------------------------+-------------------------+
| Conflicts | ``conflicts`` | (none) |
+-------------------------------+-----------------------------+-------------------------+
| Obsoletes | ``obsoletes`` | (none) |
+-------------------------------+-----------------------------+-------------------------+
| Distribution | ``distribution_name`` | (none) |
+-------------------------------+-----------------------------+-------------------------+
| BuildRequires | ``build_requires`` | (none) |
+-------------------------------+-----------------------------+-------------------------+
| Icon | ``icon`` | (none) |
+-------------------------------+-----------------------------+-------------------------+
Obviously, supplying even a few of these options on the command-line would be
tedious and error-prone, so it's usually best to put them in the setup
configuration file, :file:`setup.cfg`\ ---see section :ref:`setup-config`. If
you distribute or package many Python module distributions, you might want to
put options that apply to all of them in your personal Distutils configuration
file (:file:`~/.pydistutils.cfg`). If you want to temporarily disable
this file, you can pass the --no-user-cfg option to setup.py.
There are three steps to building a binary RPM package, all of which are
handled automatically by the Distutils:
#. create a :file:`.spec` file, which describes the package (analogous to the
Distutils setup script; in fact, much of the information in the setup script
winds up in the :file:`.spec` file)
#. create the source RPM
#. create the "binary" RPM (which may or may not contain binary code, depending
on whether your module distribution contains Python extensions)
Normally, RPM bundles the last two steps together; when you use the Distutils,
all three steps are typically bundled together.
If you wish, you can separate these three steps. You can use the
:option:`!--spec-only` option to make :command:`bdist_rpm` just create the
:file:`.spec` file and exit; in this case, the :file:`.spec` file will be
written to the "distribution directory"---normally :file:`dist/`, but
customizable with the :option:`!--dist-dir` option. (Normally, the :file:`.spec`
file winds up deep in the "build tree," in a temporary directory created by
:command:`bdist_rpm`.)
.. % \XXX{this isn't implemented yet---is it needed?!}
.. % You can also specify a custom \file{.spec} file with the
.. % \longprogramopt{spec-file} option; used in conjunction with
.. % \longprogramopt{spec-only}, this gives you an opportunity to customize
.. % the \file{.spec} file manually:
.. %
.. % \ begin{verbatim}
.. % > python setup.py bdist_rpm --spec-only
.. % # ...edit dist/FooBar-1.0.spec
.. % > python setup.py bdist_rpm --spec-file=dist/FooBar-1.0.spec
.. % \ end{verbatim}
.. %
.. % (Although a better way to do this is probably to override the standard
.. % \command{bdist\_rpm} command with one that writes whatever else you want
.. % to the \file{.spec} file.)
.. _creating-wininst:
Creating Windows Installers
===========================
Executable installers are the natural format for binary distributions on
Windows. They display a nice graphical user interface, display some information
about the module distribution to be installed taken from the metadata in the
setup script, let the user select a few options, and start or cancel the
installation.
Since the metadata is taken from the setup script, creating Windows installers
is usually as easy as running::
python setup.py bdist_wininst
or the :command:`bdist` command with the :option:`!--formats` option::
python setup.py bdist --formats=wininst
If you have a pure module distribution (only containing pure Python modules and
packages), the resulting installer will be version independent and have a name
like :file:`foo-1.0.win32.exe`. These installers can even be created on Unix
platforms or Mac OS X.
If you have a non-pure distribution, the extensions can only be created on a
Windows platform, and will be Python version dependent. The installer filename
will reflect this and now has the form :file:`foo-1.0.win32-py2.0.exe`. You
have to create a separate installer for every Python version you want to
support.
The installer will try to compile pure modules into :term:`bytecode` after installation
on the target system in normal and optimizing mode. If you don't want this to
happen for some reason, you can run the :command:`bdist_wininst` command with
the :option:`!--no-target-compile` and/or the :option:`!--no-target-optimize`
option.
By default the installer will display the cool "Python Powered" logo when it is
run, but you can also supply your own 152x261 bitmap which must be a Windows
:file:`.bmp` file with the :option:`!--bitmap` option.
The installer will also display a large title on the desktop background window
when it is run, which is constructed from the name of your distribution and the
version number. This can be changed to another text by using the
:option:`!--title` option.
The installer file will be written to the "distribution directory" --- normally
:file:`dist/`, but customizable with the :option:`!--dist-dir` option.
.. _cross-compile-windows:
Cross-compiling on Windows
==========================
Starting with Python 2.6, distutils is capable of cross-compiling between
Windows platforms. In practice, this means that with the correct tools
installed, you can use a 32bit version of Windows to create 64bit extensions
and vice-versa.
To build for an alternate platform, specify the :option:`!--plat-name` option
to the build command. Valid values are currently 'win32', 'win-amd64' and
'win-ia64'. For example, on a 32bit version of Windows, you could execute::
python setup.py build --plat-name=win-amd64
to build a 64bit version of your extension. The Windows Installers also
support this option, so the command::
python setup.py build --plat-name=win-amd64 bdist_wininst
would create a 64bit installation executable on your 32bit version of Windows.
To cross-compile, you must download the Python source code and cross-compile
Python itself for the platform you are targeting - it is not possible from a
binary installation of Python (as the .lib etc file for other platforms are
not included.) In practice, this means the user of a 32 bit operating
system will need to use Visual Studio 2008 to open the
:file:`PCBuild/PCbuild.sln` solution in the Python source tree and build the
"x64" configuration of the 'pythoncore' project before cross-compiling
extensions is possible.
Note that by default, Visual Studio 2008 does not install 64bit compilers or
tools. You may need to reexecute the Visual Studio setup process and select
these tools (using Control Panel->[Add/Remove] Programs is a convenient way to
check or modify your existing install.)
.. _postinstallation-script:
The Postinstallation script
---------------------------
Starting with Python 2.3, a postinstallation script can be specified with the
:option:`!--install-script` option. The basename of the script must be
specified, and the script filename must also be listed in the scripts argument
to the setup function.
This script will be run at installation time on the target system after all the
files have been copied, with ``argv[1]`` set to :option:`!-install`, and again at
uninstallation time before the files are removed with ``argv[1]`` set to
:option:`!-remove`.
The installation script runs embedded in the windows installer, every output
(``sys.stdout``, ``sys.stderr``) is redirected into a buffer and will be
displayed in the GUI after the script has finished.
Some functions especially useful in this context are available as additional
built-in functions in the installation script.
.. function:: directory_created(path)
file_created(path)
These functions should be called when a directory or file is created by the
postinstall script at installation time. It will register *path* with the
uninstaller, so that it will be removed when the distribution is uninstalled.
To be safe, directories are only removed if they are empty.
.. function:: get_special_folder_path(csidl_string)
This function can be used to retrieve special folder locations on Windows like
the Start Menu or the Desktop. It returns the full path to the folder.
*csidl_string* must be one of the following strings::
"CSIDL_APPDATA"
"CSIDL_COMMON_STARTMENU"
"CSIDL_STARTMENU"
"CSIDL_COMMON_DESKTOPDIRECTORY"
"CSIDL_DESKTOPDIRECTORY"
"CSIDL_COMMON_STARTUP"
"CSIDL_STARTUP"
"CSIDL_COMMON_PROGRAMS"
"CSIDL_PROGRAMS"
"CSIDL_FONTS"
If the folder cannot be retrieved, :exc:`OSError` is raised.
Which folders are available depends on the exact Windows version, and probably
also the configuration. For details refer to Microsoft's documentation of the
:c:func:`SHGetSpecialFolderPath` function.
.. function:: create_shortcut(target, description, filename[, arguments[, workdir[, iconpath[, iconindex]]]])
This function creates a shortcut. *target* is the path to the program to be
started by the shortcut. *description* is the description of the shortcut.
*filename* is the title of the shortcut that the user will see. *arguments*
specifies the command line arguments, if any. *workdir* is the working directory
for the program. *iconpath* is the file containing the icon for the shortcut,
and *iconindex* is the index of the icon in the file *iconpath*. Again, for
details consult the Microsoft documentation for the :class:`IShellLink`
interface.
Vista User Access Control (UAC)
===============================
Starting with Python 2.6, bdist_wininst supports a :option:`!--user-access-control`
option. The default is 'none' (meaning no UAC handling is done), and other
valid values are 'auto' (meaning prompt for UAC elevation if Python was
installed for all users) and 'force' (meaning always prompt for elevation).
PK %�\ �F` * html/_sources/distutils/commandref.rst.txtnu �[��� .. _reference:
*****************
Command Reference
*****************
.. % \section{Building modules: the \protect\command{build} command family}
.. % \label{build-cmds}
.. % \subsubsection{\protect\command{build}}
.. % \label{build-cmd}
.. % \subsubsection{\protect\command{build\_py}}
.. % \label{build-py-cmd}
.. % \subsubsection{\protect\command{build\_ext}}
.. % \label{build-ext-cmd}
.. % \subsubsection{\protect\command{build\_clib}}
.. % \label{build-clib-cmd}
.. _install-cmd:
Installing modules: the :command:`install` command family
=========================================================
The install command ensures that the build commands have been run and then runs
the subcommands :command:`install_lib`, :command:`install_data` and
:command:`install_scripts`.
.. % \subsubsection{\protect\command{install\_lib}}
.. % \label{install-lib-cmd}
.. _install-data-cmd:
:command:`install_data`
-----------------------
This command installs all data files provided with the distribution.
.. _install-scripts-cmd:
:command:`install_scripts`
--------------------------
This command installs all (Python) scripts in the distribution.
.. % \subsection{Cleaning up: the \protect\command{clean} command}
.. % \label{clean-cmd}
.. % \section{Creating a built distribution: the
.. % \protect\command{bdist} command family}
.. % \label{bdist-cmds}
.. % \subsection{\protect\command{bdist}}
.. % \subsection{\protect\command{bdist\_dumb}}
.. % \subsection{\protect\command{bdist\_rpm}}
.. % \subsection{\protect\command{bdist\_wininst}}
PK %�\U'HI * html/_sources/distutils/configfile.rst.txtnu �[��� .. _setup-config:
************************************
Writing the Setup Configuration File
************************************
Often, it's not possible to write down everything needed to build a distribution
*a priori*: you may need to get some information from the user, or from the
user's system, in order to proceed. As long as that information is fairly
simple---a list of directories to search for C header files or libraries, for
example---then providing a configuration file, :file:`setup.cfg`, for users to
edit is a cheap and easy way to solicit it. Configuration files also let you
provide default values for any command option, which the installer can then
override either on the command-line or by editing the config file.
The setup configuration file is a useful middle-ground between the setup script
---which, ideally, would be opaque to installers [#]_---and the command-line to
the setup script, which is outside of your control and entirely up to the
installer. In fact, :file:`setup.cfg` (and any other Distutils configuration
files present on the target system) are processed after the contents of the
setup script, but before the command-line. This has several useful
consequences:
.. % (If you have more advanced needs, such as determining which extensions
.. % to build based on what capabilities are present on the target system,
.. % then you need the Distutils ``auto-configuration'' facility. This
.. % started to appear in Distutils 0.9 but, as of this writing, isn't mature
.. % or stable enough yet for real-world use.)
* installers can override some of what you put in :file:`setup.py` by editing
:file:`setup.cfg`
* you can provide non-standard defaults for options that are not easily set in
:file:`setup.py`
* installers can override anything in :file:`setup.cfg` using the command-line
options to :file:`setup.py`
The basic syntax of the configuration file is simple::
[command]
option=value
...
where *command* is one of the Distutils commands (e.g. :command:`build_py`,
:command:`install`), and *option* is one of the options that command supports.
Any number of options can be supplied for each command, and any number of
command sections can be included in the file. Blank lines are ignored, as are
comments, which run from a ``'#'`` character until the end of the line. Long
option values can be split across multiple lines simply by indenting the
continuation lines.
You can find out the list of options supported by a particular command with the
universal :option:`!--help` option, e.g. ::
> python setup.py --help build_ext
[...]
Options for 'build_ext' command:
--build-lib (-b) directory for compiled extension modules
--build-temp (-t) directory for temporary files (build by-products)
--inplace (-i) ignore build-lib and put compiled extensions into the
source directory alongside your pure Python modules
--include-dirs (-I) list of directories to search for header files
--define (-D) C preprocessor macros to define
--undef (-U) C preprocessor macros to undefine
--swig-opts list of SWIG command line options
[...]
Note that an option spelled :option:`!--foo-bar` on the command-line is spelled
``foo_bar`` in configuration files.
.. _distutils-build-ext-inplace:
For example, say you want your extensions to be built "in-place"---that is, you
have an extension :mod:`pkg.ext`, and you want the compiled extension file
(:file:`ext.so` on Unix, say) to be put in the same source directory as your
pure Python modules :mod:`pkg.mod1` and :mod:`pkg.mod2`. You can always use the
:option:`!--inplace` option on the command-line to ensure this::
python setup.py build_ext --inplace
But this requires that you always specify the :command:`build_ext` command
explicitly, and remember to provide :option:`!--inplace`. An easier way is to
"set and forget" this option, by encoding it in :file:`setup.cfg`, the
configuration file for this distribution::
[build_ext]
inplace=1
This will affect all builds of this module distribution, whether or not you
explicitly specify :command:`build_ext`. If you include :file:`setup.cfg` in
your source distribution, it will also affect end-user builds---which is
probably a bad idea for this option, since always building extensions in-place
would break installation of the module distribution. In certain peculiar cases,
though, modules are built right in their installation directory, so this is
conceivably a useful ability. (Distributing extensions that expect to be built
in their installation directory is almost always a bad idea, though.)
Another example: certain commands take a lot of options that don't change from
run to run; for example, :command:`bdist_rpm` needs to know everything required
to generate a "spec" file for creating an RPM distribution. Some of this
information comes from the setup script, and some is automatically generated by
the Distutils (such as the list of files installed). But some of it has to be
supplied as options to :command:`bdist_rpm`, which would be very tedious to do
on the command-line for every run. Hence, here is a snippet from the Distutils'
own :file:`setup.cfg`::
[bdist_rpm]
release = 1
packager = Greg Ward <gward@python.net>
doc_files = CHANGES.txt
README.txt
USAGE.txt
doc/
examples/
Note that the ``doc_files`` option is simply a whitespace-separated string
split across multiple lines for readability.
.. seealso::
:ref:`inst-config-syntax` in "Installing Python Modules"
More information on the configuration files is available in the manual for
system administrators.
.. rubric:: Footnotes
.. [#] This ideal probably won't be achieved until auto-configuration is fully
supported by the Distutils.
PK %�\$� �Z Z ( html/_sources/distutils/examples.rst.txtnu �[��� .. _examples:
********
Examples
********
This chapter provides a number of basic examples to help get started with
distutils. Additional information about using distutils can be found in the
Distutils Cookbook.
.. seealso::
`Distutils Cookbook <https://wiki.python.org/moin/Distutils/Cookbook>`_
Collection of recipes showing how to achieve more control over distutils.
.. _pure-mod:
Pure Python distribution (by module)
====================================
If you're just distributing a couple of modules, especially if they don't live
in a particular package, you can specify them individually using the
``py_modules`` option in the setup script.
In the simplest case, you'll have two files to worry about: a setup script and
the single module you're distributing, :file:`foo.py` in this example::
<root>/
setup.py
foo.py
(In all diagrams in this section, *<root>* will refer to the distribution root
directory.) A minimal setup script to describe this situation would be::
from distutils.core import setup
setup(name='foo',
version='1.0',
py_modules=['foo'],
)
Note that the name of the distribution is specified independently with the
``name`` option, and there's no rule that says it has to be the same as
the name of the sole module in the distribution (although that's probably a good
convention to follow). However, the distribution name is used to generate
filenames, so you should stick to letters, digits, underscores, and hyphens.
Since ``py_modules`` is a list, you can of course specify multiple
modules, eg. if you're distributing modules :mod:`foo` and :mod:`bar`, your
setup might look like this::
<root>/
setup.py
foo.py
bar.py
and the setup script might be ::
from distutils.core import setup
setup(name='foobar',
version='1.0',
py_modules=['foo', 'bar'],
)
You can put module source files into another directory, but if you have enough
modules to do that, it's probably easier to specify modules by package rather
than listing them individually.
.. _pure-pkg:
Pure Python distribution (by package)
=====================================
If you have more than a couple of modules to distribute, especially if they are
in multiple packages, it's probably easier to specify whole packages rather than
individual modules. This works even if your modules are not in a package; you
can just tell the Distutils to process modules from the root package, and that
works the same as any other package (except that you don't have to have an
:file:`__init__.py` file).
The setup script from the last example could also be written as ::
from distutils.core import setup
setup(name='foobar',
version='1.0',
packages=[''],
)
(The empty string stands for the root package.)
If those two files are moved into a subdirectory, but remain in the root
package, e.g.::
<root>/
setup.py
src/ foo.py
bar.py
then you would still specify the root package, but you have to tell the
Distutils where source files in the root package live::
from distutils.core import setup
setup(name='foobar',
version='1.0',
package_dir={'': 'src'},
packages=[''],
)
More typically, though, you will want to distribute multiple modules in the same
package (or in sub-packages). For example, if the :mod:`foo` and :mod:`bar`
modules belong in package :mod:`foobar`, one way to layout your source tree is
::
<root>/
setup.py
foobar/
__init__.py
foo.py
bar.py
This is in fact the default layout expected by the Distutils, and the one that
requires the least work to describe in your setup script::
from distutils.core import setup
setup(name='foobar',
version='1.0',
packages=['foobar'],
)
If you want to put modules in directories not named for their package, then you
need to use the ``package_dir`` option again. For example, if the
:file:`src` directory holds modules in the :mod:`foobar` package::
<root>/
setup.py
src/
__init__.py
foo.py
bar.py
an appropriate setup script would be ::
from distutils.core import setup
setup(name='foobar',
version='1.0',
package_dir={'foobar': 'src'},
packages=['foobar'],
)
Or, you might put modules from your main package right in the distribution
root::
<root>/
setup.py
__init__.py
foo.py
bar.py
in which case your setup script would be ::
from distutils.core import setup
setup(name='foobar',
version='1.0',
package_dir={'foobar': ''},
packages=['foobar'],
)
(The empty string also stands for the current directory.)
If you have sub-packages, they must be explicitly listed in ``packages``,
but any entries in ``package_dir`` automatically extend to sub-packages.
(In other words, the Distutils does *not* scan your source tree, trying to
figure out which directories correspond to Python packages by looking for
:file:`__init__.py` files.) Thus, if the default layout grows a sub-package::
<root>/
setup.py
foobar/
__init__.py
foo.py
bar.py
subfoo/
__init__.py
blah.py
then the corresponding setup script would be ::
from distutils.core import setup
setup(name='foobar',
version='1.0',
packages=['foobar', 'foobar.subfoo'],
)
.. _single-ext:
Single extension module
=======================
Extension modules are specified using the ``ext_modules`` option.
``package_dir`` has no effect on where extension source files are found;
it only affects the source for pure Python modules. The simplest case, a
single extension module in a single C source file, is::
<root>/
setup.py
foo.c
If the :mod:`foo` extension belongs in the root package, the setup script for
this could be ::
from distutils.core import setup
from distutils.extension import Extension
setup(name='foobar',
version='1.0',
ext_modules=[Extension('foo', ['foo.c'])],
)
If the extension actually belongs in a package, say :mod:`foopkg`, then
With exactly the same source tree layout, this extension can be put in the
:mod:`foopkg` package simply by changing the name of the extension::
from distutils.core import setup
from distutils.extension import Extension
setup(name='foobar',
version='1.0',
ext_modules=[Extension('foopkg.foo', ['foo.c'])],
)
.. % \section{Multiple extension modules}
.. % \label{multiple-ext}
.. % \section{Putting it all together}
PK %�\cG�� � ) html/_sources/distutils/extending.rst.txtnu �[��� .. _extending-distutils:
*******************
Extending Distutils
*******************
Distutils can be extended in various ways. Most extensions take the form of new
commands or replacements for existing commands. New commands may be written to
support new types of platform-specific packaging, for example, while
replacements for existing commands may be made to modify details of how the
command operates on a package.
Most extensions of the distutils are made within :file:`setup.py` scripts that
want to modify existing commands; many simply add a few file extensions that
should be copied into packages in addition to :file:`.py` files as a
convenience.
Most distutils command implementations are subclasses of the
:class:`distutils.cmd.Command` class. New commands may directly inherit from
:class:`Command`, while replacements often derive from :class:`Command`
indirectly, directly subclassing the command they are replacing. Commands are
required to derive from :class:`Command`.
.. % \section{Extending existing commands}
.. % \label{extend-existing}
.. % \section{Writing new commands}
.. % \label{new-commands}
.. % \XXX{Would an uninstall command be a good example here?}
Integrating new commands
========================
There are different ways to integrate new command implementations into
distutils. The most difficult is to lobby for the inclusion of the new features
in distutils itself, and wait for (and require) a version of Python that
provides that support. This is really hard for many reasons.
The most common, and possibly the most reasonable for most needs, is to include
the new implementations with your :file:`setup.py` script, and cause the
:func:`distutils.core.setup` function use them::
from distutils.command.build_py import build_py as _build_py
from distutils.core import setup
class build_py(_build_py):
"""Specialized Python source builder."""
# implement whatever needs to be different...
setup(cmdclass={'build_py': build_py},
...)
This approach is most valuable if the new implementations must be used to use a
particular package, as everyone interested in the package will need to have the
new command implementation.
Beginning with Python 2.4, a third option is available, intended to allow new
commands to be added which can support existing :file:`setup.py` scripts without
requiring modifications to the Python installation. This is expected to allow
third-party extensions to provide support for additional packaging systems, but
the commands can be used for anything distutils commands can be used for. A new
configuration option, ``command_packages`` (command-line option
:option:`!--command-packages`), can be used to specify additional packages to be
searched for modules implementing commands. Like all distutils options, this
can be specified on the command line or in a configuration file. This option
can only be set in the ``[global]`` section of a configuration file, or before
any commands on the command line. If set in a configuration file, it can be
overridden from the command line; setting it to an empty string on the command
line causes the default to be used. This should never be set in a configuration
file provided with a package.
This new option can be used to add any number of packages to the list of
packages searched for command implementations; multiple package names should be
separated by commas. When not specified, the search is only performed in the
:mod:`distutils.command` package. When :file:`setup.py` is run with the option
``--command-packages distcmds,buildcmds``, however, the packages
:mod:`distutils.command`, :mod:`distcmds`, and :mod:`buildcmds` will be searched
in that order. New commands are expected to be implemented in modules of the
same name as the command by classes sharing the same name. Given the example
command line option above, the command :command:`bdist_openpkg` could be
implemented by the class :class:`distcmds.bdist_openpkg.bdist_openpkg` or
:class:`buildcmds.bdist_openpkg.bdist_openpkg`.
Adding new distribution types
=============================
Commands that create distributions (files in the :file:`dist/` directory) need
to add ``(command, filename)`` pairs to ``self.distribution.dist_files`` so that
:command:`upload` can upload it to PyPI. The *filename* in the pair contains no
path information, only the name of the file itself. In dry-run mode, pairs
should still be added to represent what would have been created.
PK %�\�0� � % html/_sources/distutils/index.rst.txtnu �[��� .. _distutils-index:
##############################################
Distributing Python Modules (Legacy version)
##############################################
:Authors: Greg Ward, Anthony Baxter
:Email: distutils-sig@python.org
.. seealso::
:ref:`distributing-index`
The up to date module distribution documentations
This document describes the Python Distribution Utilities ("Distutils") from
the module developer's point of view, describing how to use the Distutils to
make Python modules and extensions easily available to a wider audience with
very little overhead for build/release/install mechanics.
.. note::
This guide only covers the basic tools for building and distributing
extensions that are provided as part of this version of Python. Third party
tools offer easier to use and more secure alternatives. Refer to the `quick
recommendations section <https://packaging.python.org/en/latest/current/>`__
in the Python Packaging User Guide for more information.
.. toctree::
:maxdepth: 2
:numbered:
introduction.rst
setupscript.rst
configfile.rst
sourcedist.rst
builtdist.rst
packageindex.rst
examples.rst
extending.rst
commandref.rst
apiref.rst
PK %�\ϓ�*r! r! , html/_sources/distutils/introduction.rst.txtnu �[��� .. _distutils-intro:
****************************
An Introduction to Distutils
****************************
This document covers using the Distutils to distribute your Python modules,
concentrating on the role of developer/distributor: if you're looking for
information on installing Python modules, you should refer to the
:ref:`install-index` chapter.
.. _distutils-concepts:
Concepts & Terminology
======================
Using the Distutils is quite simple, both for module developers and for
users/administrators installing third-party modules. As a developer, your
responsibilities (apart from writing solid, well-documented and well-tested
code, of course!) are:
* write a setup script (:file:`setup.py` by convention)
* (optional) write a setup configuration file
* create a source distribution
* (optional) create one or more built (binary) distributions
Each of these tasks is covered in this document.
Not all module developers have access to a multitude of platforms, so it's not
always feasible to expect them to create a multitude of built distributions. It
is hoped that a class of intermediaries, called *packagers*, will arise to
address this need. Packagers will take source distributions released by module
developers, build them on one or more platforms, and release the resulting built
distributions. Thus, users on the most popular platforms will be able to
install most popular Python module distributions in the most natural way for
their platform, without having to run a single setup script or compile a line of
code.
.. _distutils-simple-example:
A Simple Example
================
The setup script is usually quite simple, although since it's written in Python,
there are no arbitrary limits to what you can do with it, though you should be
careful about putting arbitrarily expensive operations in your setup script.
Unlike, say, Autoconf-style configure scripts, the setup script may be run
multiple times in the course of building and installing your module
distribution.
If all you want to do is distribute a module called :mod:`foo`, contained in a
file :file:`foo.py`, then your setup script can be as simple as this::
from distutils.core import setup
setup(name='foo',
version='1.0',
py_modules=['foo'],
)
Some observations:
* most information that you supply to the Distutils is supplied as keyword
arguments to the :func:`setup` function
* those keyword arguments fall into two categories: package metadata (name,
version number) and information about what's in the package (a list of pure
Python modules, in this case)
* modules are specified by module name, not filename (the same will hold true
for packages and extensions)
* it's recommended that you supply a little more metadata, in particular your
name, email address and a URL for the project (see section :ref:`setup-script`
for an example)
To create a source distribution for this module, you would create a setup
script, :file:`setup.py`, containing the above code, and run this command from a
terminal::
python setup.py sdist
For Windows, open a command prompt windows (:menuselection:`Start -->
Accessories`) and change the command to::
setup.py sdist
:command:`sdist` will create an archive file (e.g., tarball on Unix, ZIP file on Windows)
containing your setup script :file:`setup.py`, and your module :file:`foo.py`.
The archive file will be named :file:`foo-1.0.tar.gz` (or :file:`.zip`), and
will unpack into a directory :file:`foo-1.0`.
If an end-user wishes to install your :mod:`foo` module, all they have to do is
download :file:`foo-1.0.tar.gz` (or :file:`.zip`), unpack it, and---from the
:file:`foo-1.0` directory---run ::
python setup.py install
which will ultimately copy :file:`foo.py` to the appropriate directory for
third-party modules in their Python installation.
This simple example demonstrates some fundamental concepts of the Distutils.
First, both developers and installers have the same basic user interface, i.e.
the setup script. The difference is which Distutils *commands* they use: the
:command:`sdist` command is almost exclusively for module developers, while
:command:`install` is more often for installers (although most developers will
want to install their own code occasionally).
If you want to make things really easy for your users, you can create one or
more built distributions for them. For instance, if you are running on a
Windows machine, and want to make things easy for other Windows users, you can
create an executable installer (the most appropriate type of built distribution
for this platform) with the :command:`bdist_wininst` command. For example::
python setup.py bdist_wininst
will create an executable installer, :file:`foo-1.0.win32.exe`, in the current
directory.
Other useful built distribution formats are RPM, implemented by the
:command:`bdist_rpm` command, Solaris :program:`pkgtool`
(:command:`bdist_pkgtool`), and HP-UX :program:`swinstall`
(:command:`bdist_sdux`). For example, the following command will create an RPM
file called :file:`foo-1.0.noarch.rpm`::
python setup.py bdist_rpm
(The :command:`bdist_rpm` command uses the :command:`rpm` executable, therefore
this has to be run on an RPM-based system such as Red Hat Linux, SuSE Linux, or
Mandrake Linux.)
You can find out what distribution formats are available at any time by running
::
python setup.py bdist --help-formats
.. _python-terms:
General Python terminology
==========================
If you're reading this document, you probably have a good idea of what modules,
extensions, and so forth are. Nevertheless, just to be sure that everyone is
operating from a common starting point, we offer the following glossary of
common Python terms:
module
the basic unit of code reusability in Python: a block of code imported by some
other code. Three types of modules concern us here: pure Python modules,
extension modules, and packages.
pure Python module
a module written in Python and contained in a single :file:`.py` file (and
possibly associated :file:`.pyc` and/or :file:`.pyo` files). Sometimes referred
to as a "pure module."
extension module
a module written in the low-level language of the Python implementation: C/C++
for Python, Java for Jython. Typically contained in a single dynamically
loadable pre-compiled file, e.g. a shared object (:file:`.so`) file for Python
extensions on Unix, a DLL (given the :file:`.pyd` extension) for Python
extensions on Windows, or a Java class file for Jython extensions. (Note that
currently, the Distutils only handles C/C++ extensions for Python.)
package
a module that contains other modules; typically contained in a directory in the
filesystem and distinguished from other directories by the presence of a file
:file:`__init__.py`.
root package
the root of the hierarchy of packages. (This isn't really a package, since it
doesn't have an :file:`__init__.py` file. But we have to call it something.)
The vast majority of the standard library is in the root package, as are many
small, standalone third-party modules that don't belong to a larger module
collection. Unlike regular packages, modules in the root package can be found in
many directories: in fact, every directory listed in ``sys.path`` contributes
modules to the root package.
.. _distutils-term:
Distutils-specific terminology
==============================
The following terms apply more specifically to the domain of distributing Python
modules using the Distutils:
module distribution
a collection of Python modules distributed together as a single downloadable
resource and meant to be installed *en masse*. Examples of some well-known
module distributions are Numeric Python, PyXML, Pillow,
or mxBase. (This would be called a *package*, except that term is
already taken in the Python context: a single module distribution may contain
zero, one, or many Python packages.)
pure module distribution
a module distribution that contains only pure Python modules and packages.
Sometimes referred to as a "pure distribution."
non-pure module distribution
a module distribution that contains at least one extension module. Sometimes
referred to as a "non-pure distribution."
distribution root
the top-level directory of your source tree (or source distribution); the
directory where :file:`setup.py` exists. Generally :file:`setup.py` will be
run from this directory.
PK %�\ ��! �! , html/_sources/distutils/packageindex.rst.txtnu �[��� .. index::
single: Python Package Index (PyPI)
single: PyPI; (see Python Package Index (PyPI))
.. _package-index:
*******************************
The Python Package Index (PyPI)
*******************************
The `Python Package Index (PyPI)`_ stores :ref:`meta-data <meta-data>`
describing distributions packaged with distutils, as well as package data like
distribution files if a package author wishes.
Distutils provides the :command:`register` and :command:`upload` commands for
pushing meta-data and distribution files to PyPI, respectively. See
:ref:`package-commands` for information on these commands.
PyPI overview
=============
PyPI lets you submit any number of versions of your distribution to the index.
If you alter the meta-data for a particular version, you can submit it again
and the index will be updated.
PyPI holds a record for each (name, version) combination submitted. The first
user to submit information for a given name is designated the Owner of that
name. Changes can be submitted through the :command:`register` command or
through the web interface. Owners can designate other users as Owners or
Maintainers. Maintainers can edit the package information, but not designate
new Owners or Maintainers.
By default PyPI displays only the newest version of a given package. The web
interface lets one change this default behavior and manually select which
versions to display and hide.
For each version, PyPI displays a home page. The home page is created from
the ``long_description`` which can be submitted via the :command:`register`
command. See :ref:`package-display` for more information.
.. _package-commands:
Distutils commands
==================
Distutils exposes two commands for submitting package data to PyPI: the
:ref:`register <package-register>` command for submitting meta-data to PyPI
and the :ref:`upload <package-upload>` command for submitting distribution
files. Both commands read configuration data from a special file called a
:ref:`.pypirc file <pypirc>`.
.. _package-register:
The ``register`` command
------------------------
The distutils command :command:`register` is used to submit your distribution's
meta-data to an index server. It is invoked as follows::
python setup.py register
Distutils will respond with the following prompt::
running register
We need to know who you are, so please choose either:
1. use your existing login,
2. register as a new user,
3. have the server generate a new password for you (and email it to you), or
4. quit
Your selection [default 1]:
Note: if your username and password are saved locally, you will not see this
menu. Also, refer to :ref:`pypirc` for how to store your credentials in a
:file:`.pypirc` file.
If you have not registered with PyPI, then you will need to do so now. You
should choose option 2, and enter your details as required. Soon after
submitting your details, you will receive an email which will be used to confirm
your registration.
Once you are registered, you may choose option 1 from the menu. You will be
prompted for your PyPI username and password, and :command:`register` will then
submit your meta-data to the index.
See :ref:`package-cmdoptions` for options to the :command:`register` command.
.. _package-upload:
The ``upload`` command
----------------------
.. versionadded:: 2.5
The distutils command :command:`upload` pushes the distribution files to PyPI.
The command is invoked immediately after building one or more distribution
files. For example, the command ::
python setup.py sdist bdist_wininst upload
will cause the source distribution and the Windows installer to be uploaded to
PyPI. Note that these will be uploaded even if they are built using an earlier
invocation of :file:`setup.py`, but that only distributions named on the command
line for the invocation including the :command:`upload` command are uploaded.
If a :command:`register` command was previously called in the same command,
and if the password was entered in the prompt, :command:`upload` will reuse the
entered password. This is useful if you do not want to store a password in
clear text in a :file:`.pypirc` file.
You can use the ``--sign`` option to tell :command:`upload` to sign each
uploaded file using GPG (GNU Privacy Guard). The :program:`gpg` program must
be available for execution on the system :envvar:`PATH`. You can also specify
which key to use for signing using the ``--identity=name`` option.
See :ref:`package-cmdoptions` for additional options to the :command:`upload`
command.
.. _package-cmdoptions:
Additional command options
--------------------------
This section describes options common to both the :command:`register` and
:command:`upload` commands.
The ``--repository`` or ``-r`` option lets you specify a PyPI server
different from the default. For example::
python setup.py sdist bdist_wininst upload -r https://example.com/pypi
For convenience, a name can be used in place of the URL when the
:file:`.pypirc` file is configured to do so. For example::
python setup.py register -r other
See :ref:`pypirc` for more information on defining alternate servers.
The ``--show-response`` option displays the full response text from the PyPI
server, which is useful when debugging problems with registering and uploading.
.. index::
single: .pypirc file
single: Python Package Index (PyPI); .pypirc file
.. _pypirc:
The ``.pypirc`` file
--------------------
The :command:`register` and :command:`upload` commands both check for the
existence of a :file:`.pypirc` file at the location :file:`$HOME/.pypirc`.
If this file exists, the command uses the username, password, and repository
URL configured in the file. The format of a :file:`.pypirc` file is as
follows::
[distutils]
index-servers =
pypi
[pypi]
repository: <repository-url>
username: <username>
password: <password>
The *distutils* section defines an *index-servers* variable that lists the
name of all sections describing a repository.
Each section describing a repository defines three variables:
- *repository*, that defines the url of the PyPI server. Defaults to
``https://www.python.org/pypi``.
- *username*, which is the registered username on the PyPI server.
- *password*, that will be used to authenticate. If omitted the user
will be prompt to type it when needed.
If you want to define another server a new section can be created and
listed in the *index-servers* variable::
[distutils]
index-servers =
pypi
other
[pypi]
repository: <repository-url>
username: <username>
password: <password>
[other]
repository: https://example.com/pypi
username: <username>
password: <password>
This allows the :command:`register` and :command:`upload` commands to be
called with the ``--repository`` option as described in
:ref:`package-cmdoptions`.
Specifically, you might want to add the `PyPI Test Repository
<https://wiki.python.org/moin/TestPyPI>`_ to your ``.pypirc`` to facilitate
testing before doing your first upload to ``PyPI`` itself.
.. _package-display:
PyPI package display
====================
The ``long_description`` field plays a special role at PyPI. It is used by
the server to display a home page for the registered package.
If you use the `reStructuredText <http://docutils.sourceforge.net/rst.html>`_
syntax for this field, PyPI will parse it and display an HTML output for
the package home page.
The ``long_description`` field can be attached to a text file located
in the package::
from distutils.core import setup
with open('README.txt') as file:
long_description = file.read()
setup(name='Distutils',
long_description=long_description)
In that case, :file:`README.txt` is a regular reStructuredText text file located
in the root of the package besides :file:`setup.py`.
To prevent registering broken reStructuredText content, you can use the
:program:`rst2html` program that is provided by the :mod:`docutils` package and
check the ``long_description`` from the command line:
.. code-block:: shell-session
$ python setup.py --long-description | rst2html.py > output.html
:mod:`docutils` will display a warning if there's something wrong with your
syntax. Because PyPI applies additional checks (e.g. by passing ``--no-raw``
to ``rst2html.py`` in the command above), being able to run the command above
without warnings does not guarantee that PyPI will convert the content
successfully.
.. _Python Package Index (PyPI): https://pypi.org
PK %�\�� �y �y + html/_sources/distutils/setupscript.rst.txtnu �[��� .. _setup-script:
************************
Writing the Setup Script
************************
The setup script is the centre of all activity in building, distributing, and
installing modules using the Distutils. The main purpose of the setup script is
to describe your module distribution to the Distutils, so that the various
commands that operate on your modules do the right thing. As we saw in section
:ref:`distutils-simple-example` above, the setup script consists mainly of a call to
:func:`setup`, and most information supplied to the Distutils by the module
developer is supplied as keyword arguments to :func:`setup`.
Here's a slightly more involved example, which we'll follow for the next couple
of sections: the Distutils' own setup script. (Keep in mind that although the
Distutils are included with Python 1.6 and later, they also have an independent
existence so that Python 1.5.2 users can use them to install other module
distributions. The Distutils' own setup script, shown here, is used to install
the package into Python 1.5.2.) ::
#!/usr/bin/env python
from distutils.core import setup
setup(name='Distutils',
version='1.0',
description='Python Distribution Utilities',
author='Greg Ward',
author_email='gward@python.net',
url='https://www.python.org/sigs/distutils-sig/',
packages=['distutils', 'distutils.command'],
)
There are only two differences between this and the trivial one-file
distribution presented in section :ref:`distutils-simple-example`: more metadata, and the
specification of pure Python modules by package, rather than by module. This is
important since the Distutils consist of a couple of dozen modules split into
(so far) two packages; an explicit list of every module would be tedious to
generate and difficult to maintain. For more information on the additional
meta-data, see section :ref:`meta-data`.
Note that any pathnames (files or directories) supplied in the setup script
should be written using the Unix convention, i.e. slash-separated. The
Distutils will take care of converting this platform-neutral representation into
whatever is appropriate on your current platform before actually using the
pathname. This makes your setup script portable across operating systems, which
of course is one of the major goals of the Distutils. In this spirit, all
pathnames in this document are slash-separated.
This, of course, only applies to pathnames given to Distutils functions. If
you, for example, use standard Python functions such as :func:`glob.glob` or
:func:`os.listdir` to specify files, you should be careful to write portable
code instead of hardcoding path separators::
glob.glob(os.path.join('mydir', 'subdir', '*.html'))
os.listdir(os.path.join('mydir', 'subdir'))
.. _listing-packages:
Listing whole packages
======================
The ``packages`` option tells the Distutils to process (build, distribute,
install, etc.) all pure Python modules found in each package mentioned in the
``packages`` list. In order to do this, of course, there has to be a
correspondence between package names and directories in the filesystem. The
default correspondence is the most obvious one, i.e. package :mod:`distutils` is
found in the directory :file:`distutils` relative to the distribution root.
Thus, when you say ``packages = ['foo']`` in your setup script, you are
promising that the Distutils will find a file :file:`foo/__init__.py` (which
might be spelled differently on your system, but you get the idea) relative to
the directory where your setup script lives. If you break this promise, the
Distutils will issue a warning but still process the broken package anyway.
If you use a different convention to lay out your source directory, that's no
problem: you just have to supply the ``package_dir`` option to tell the
Distutils about your convention. For example, say you keep all Python source
under :file:`lib`, so that modules in the "root package" (i.e., not in any
package at all) are in :file:`lib`, modules in the :mod:`foo` package are in
:file:`lib/foo`, and so forth. Then you would put ::
package_dir = {'': 'lib'}
in your setup script. The keys to this dictionary are package names, and an
empty package name stands for the root package. The values are directory names
relative to your distribution root. In this case, when you say ``packages =
['foo']``, you are promising that the file :file:`lib/foo/__init__.py` exists.
Another possible convention is to put the :mod:`foo` package right in
:file:`lib`, the :mod:`foo.bar` package in :file:`lib/bar`, etc. This would be
written in the setup script as ::
package_dir = {'foo': 'lib'}
A ``package: dir`` entry in the ``package_dir`` dictionary implicitly
applies to all packages below *package*, so the :mod:`foo.bar` case is
automatically handled here. In this example, having ``packages = ['foo',
'foo.bar']`` tells the Distutils to look for :file:`lib/__init__.py` and
:file:`lib/bar/__init__.py`. (Keep in mind that although ``package_dir``
applies recursively, you must explicitly list all packages in
``packages``: the Distutils will *not* recursively scan your source tree
looking for any directory with an :file:`__init__.py` file.)
.. _listing-modules:
Listing individual modules
==========================
For a small module distribution, you might prefer to list all modules rather
than listing packages---especially the case of a single module that goes in the
"root package" (i.e., no package at all). This simplest case was shown in
section :ref:`distutils-simple-example`; here is a slightly more involved example::
py_modules = ['mod1', 'pkg.mod2']
This describes two modules, one of them in the "root" package, the other in the
:mod:`pkg` package. Again, the default package/directory layout implies that
these two modules can be found in :file:`mod1.py` and :file:`pkg/mod2.py`, and
that :file:`pkg/__init__.py` exists as well. And again, you can override the
package/directory correspondence using the ``package_dir`` option.
.. _describing-extensions:
Describing extension modules
============================
Just as writing Python extension modules is a bit more complicated than writing
pure Python modules, describing them to the Distutils is a bit more complicated.
Unlike pure modules, it's not enough just to list modules or packages and expect
the Distutils to go out and find the right files; you have to specify the
extension name, source file(s), and any compile/link requirements (include
directories, libraries to link with, etc.).
.. XXX read over this section
All of this is done through another keyword argument to :func:`setup`, the
``ext_modules`` option. ``ext_modules`` is just a list of
:class:`~distutils.core.Extension` instances, each of which describes a
single extension module.
Suppose your distribution includes a single extension, called :mod:`foo` and
implemented by :file:`foo.c`. If no additional instructions to the
compiler/linker are needed, describing this extension is quite simple::
Extension('foo', ['foo.c'])
The :class:`Extension` class can be imported from :mod:`distutils.core` along
with :func:`setup`. Thus, the setup script for a module distribution that
contains only this one extension and nothing else might be::
from distutils.core import setup, Extension
setup(name='foo',
version='1.0',
ext_modules=[Extension('foo', ['foo.c'])],
)
The :class:`Extension` class (actually, the underlying extension-building
machinery implemented by the :command:`build_ext` command) supports a great deal
of flexibility in describing Python extensions, which is explained in the
following sections.
Extension names and packages
----------------------------
The first argument to the :class:`~distutils.core.Extension` constructor is
always the name of the extension, including any package names. For example, ::
Extension('foo', ['src/foo1.c', 'src/foo2.c'])
describes an extension that lives in the root package, while ::
Extension('pkg.foo', ['src/foo1.c', 'src/foo2.c'])
describes the same extension in the :mod:`pkg` package. The source files and
resulting object code are identical in both cases; the only difference is where
in the filesystem (and therefore where in Python's namespace hierarchy) the
resulting extension lives.
If you have a number of extensions all in the same package (or all under the
same base package), use the ``ext_package`` keyword argument to
:func:`setup`. For example, ::
setup(...,
ext_package='pkg',
ext_modules=[Extension('foo', ['foo.c']),
Extension('subpkg.bar', ['bar.c'])],
)
will compile :file:`foo.c` to the extension :mod:`pkg.foo`, and :file:`bar.c` to
:mod:`pkg.subpkg.bar`.
Extension source files
----------------------
The second argument to the :class:`~distutils.core.Extension` constructor is
a list of source
files. Since the Distutils currently only support C, C++, and Objective-C
extensions, these are normally C/C++/Objective-C source files. (Be sure to use
appropriate extensions to distinguish C++ source files: :file:`.cc` and
:file:`.cpp` seem to be recognized by both Unix and Windows compilers.)
However, you can also include SWIG interface (:file:`.i`) files in the list; the
:command:`build_ext` command knows how to deal with SWIG extensions: it will run
SWIG on the interface file and compile the resulting C/C++ file into your
extension.
.. XXX SWIG support is rough around the edges and largely untested!
This warning notwithstanding, options to SWIG can be currently passed like
this::
setup(...,
ext_modules=[Extension('_foo', ['foo.i'],
swig_opts=['-modern', '-I../include'])],
py_modules=['foo'],
)
Or on the commandline like this::
> python setup.py build_ext --swig-opts="-modern -I../include"
On some platforms, you can include non-source files that are processed by the
compiler and included in your extension. Currently, this just means Windows
message text (:file:`.mc`) files and resource definition (:file:`.rc`) files for
Visual C++. These will be compiled to binary resource (:file:`.res`) files and
linked into the executable.
Preprocessor options
--------------------
Three optional arguments to :class:`~distutils.core.Extension` will help if
you need to specify include directories to search or preprocessor macros to
define/undefine: ``include_dirs``, ``define_macros``, and ``undef_macros``.
For example, if your extension requires header files in the :file:`include`
directory under your distribution root, use the ``include_dirs`` option::
Extension('foo', ['foo.c'], include_dirs=['include'])
You can specify absolute directories there; if you know that your extension will
only be built on Unix systems with X11R6 installed to :file:`/usr`, you can get
away with ::
Extension('foo', ['foo.c'], include_dirs=['/usr/include/X11'])
You should avoid this sort of non-portable usage if you plan to distribute your
code: it's probably better to write C code like ::
#include <X11/Xlib.h>
If you need to include header files from some other Python extension, you can
take advantage of the fact that header files are installed in a consistent way
by the Distutils :command:`install_headers` command. For example, the Numerical
Python header files are installed (on a standard Unix installation) to
:file:`/usr/local/include/python1.5/Numerical`. (The exact location will differ
according to your platform and Python installation.) Since the Python include
directory---\ :file:`/usr/local/include/python1.5` in this case---is always
included in the search path when building Python extensions, the best approach
is to write C code like ::
#include <Numerical/arrayobject.h>
If you must put the :file:`Numerical` include directory right into your header
search path, though, you can find that directory using the Distutils
:mod:`distutils.sysconfig` module::
from distutils.sysconfig import get_python_inc
incdir = os.path.join(get_python_inc(plat_specific=1), 'Numerical')
setup(...,
Extension(..., include_dirs=[incdir]),
)
Even though this is quite portable---it will work on any Python installation,
regardless of platform---it's probably easier to just write your C code in the
sensible way.
You can define and undefine pre-processor macros with the ``define_macros`` and
``undef_macros`` options. ``define_macros`` takes a list of ``(name, value)``
tuples, where ``name`` is the name of the macro to define (a string) and
``value`` is its value: either a string or ``None``. (Defining a macro ``FOO``
to ``None`` is the equivalent of a bare ``#define FOO`` in your C source: with
most compilers, this sets ``FOO`` to the string ``1``.) ``undef_macros`` is
just a list of macros to undefine.
For example::
Extension(...,
define_macros=[('NDEBUG', '1'),
('HAVE_STRFTIME', None)],
undef_macros=['HAVE_FOO', 'HAVE_BAR'])
is the equivalent of having this at the top of every C source file::
#define NDEBUG 1
#define HAVE_STRFTIME
#undef HAVE_FOO
#undef HAVE_BAR
Library options
---------------
You can also specify the libraries to link against when building your extension,
and the directories to search for those libraries. The ``libraries`` option is
a list of libraries to link against, ``library_dirs`` is a list of directories
to search for libraries at link-time, and ``runtime_library_dirs`` is a list of
directories to search for shared (dynamically loaded) libraries at run-time.
For example, if you need to link against libraries known to be in the standard
library search path on target systems ::
Extension(...,
libraries=['gdbm', 'readline'])
If you need to link with libraries in a non-standard location, you'll have to
include the location in ``library_dirs``::
Extension(...,
library_dirs=['/usr/X11R6/lib'],
libraries=['X11', 'Xt'])
(Again, this sort of non-portable construct should be avoided if you intend to
distribute your code.)
.. XXX Should mention clib libraries here or somewhere else!
Other options
-------------
There are still some other options which can be used to handle special cases.
The ``extra_objects`` option is a list of object files to be passed to the
linker. These files must not have extensions, as the default extension for the
compiler is used.
``extra_compile_args`` and ``extra_link_args`` can be used to
specify additional command line options for the respective compiler and linker
command lines.
``export_symbols`` is only useful on Windows. It can contain a list of
symbols (functions or variables) to be exported. This option is not needed when
building compiled extensions: Distutils will automatically add ``initmodule``
to the list of exported symbols.
The ``depends`` option is a list of files that the extension depends on
(for example header files). The build command will call the compiler on the
sources to rebuild extension if any on this files has been modified since the
previous build.
Relationships between Distributions and Packages
================================================
A distribution may relate to packages in three specific ways:
#. It can require packages or modules.
#. It can provide packages or modules.
#. It can obsolete packages or modules.
These relationships can be specified using keyword arguments to the
:func:`distutils.core.setup` function.
Dependencies on other Python modules and packages can be specified by supplying
the *requires* keyword argument to :func:`setup`. The value must be a list of
strings. Each string specifies a package that is required, and optionally what
versions are sufficient.
To specify that any version of a module or package is required, the string
should consist entirely of the module or package name. Examples include
``'mymodule'`` and ``'xml.parsers.expat'``.
If specific versions are required, a sequence of qualifiers can be supplied in
parentheses. Each qualifier may consist of a comparison operator and a version
number. The accepted comparison operators are::
< > ==
<= >= !=
These can be combined by using multiple qualifiers separated by commas (and
optional whitespace). In this case, all of the qualifiers must be matched; a
logical AND is used to combine the evaluations.
Let's look at a bunch of examples:
+-------------------------+----------------------------------------------+
| Requires Expression | Explanation |
+=========================+==============================================+
| ``==1.0`` | Only version ``1.0`` is compatible |
+-------------------------+----------------------------------------------+
| ``>1.0, !=1.5.1, <2.0`` | Any version after ``1.0`` and before ``2.0`` |
| | is compatible, except ``1.5.1`` |
+-------------------------+----------------------------------------------+
Now that we can specify dependencies, we also need to be able to specify what we
provide that other distributions can require. This is done using the *provides*
keyword argument to :func:`setup`. The value for this keyword is a list of
strings, each of which names a Python module or package, and optionally
identifies the version. If the version is not specified, it is assumed to match
that of the distribution.
Some examples:
+---------------------+----------------------------------------------+
| Provides Expression | Explanation |
+=====================+==============================================+
| ``mypkg`` | Provide ``mypkg``, using the distribution |
| | version |
+---------------------+----------------------------------------------+
| ``mypkg (1.1)`` | Provide ``mypkg`` version 1.1, regardless of |
| | the distribution version |
+---------------------+----------------------------------------------+
A package can declare that it obsoletes other packages using the *obsoletes*
keyword argument. The value for this is similar to that of the *requires*
keyword: a list of strings giving module or package specifiers. Each specifier
consists of a module or package name optionally followed by one or more version
qualifiers. Version qualifiers are given in parentheses after the module or
package name.
The versions identified by the qualifiers are those that are obsoleted by the
distribution being described. If no qualifiers are given, all versions of the
named module or package are understood to be obsoleted.
.. _distutils-installing-scripts:
Installing Scripts
==================
So far we have been dealing with pure and non-pure Python modules, which are
usually not run by themselves but imported by scripts.
Scripts are files containing Python source code, intended to be started from the
command line. Scripts don't require Distutils to do anything very complicated.
The only clever feature is that if the first line of the script starts with
``#!`` and contains the word "python", the Distutils will adjust the first line
to refer to the current interpreter location. By default, it is replaced with
the current interpreter location. The :option:`!--executable` (or :option:`!-e`)
option will allow the interpreter path to be explicitly overridden.
The ``scripts`` option simply is a list of files to be handled in this
way. From the PyXML setup script::
setup(...,
scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val']
)
.. versionchanged:: 2.7
All the scripts will also be added to the ``MANIFEST``
file if no template is provided. See :ref:`manifest`.
.. _distutils-installing-package-data:
Installing Package Data
=======================
Often, additional files need to be installed into a package. These files are
often data that's closely related to the package's implementation, or text files
containing documentation that might be of interest to programmers using the
package. These files are called :dfn:`package data`.
Package data can be added to packages using the ``package_data`` keyword
argument to the :func:`setup` function. The value must be a mapping from
package name to a list of relative path names that should be copied into the
package. The paths are interpreted as relative to the directory containing the
package (information from the ``package_dir`` mapping is used if appropriate);
that is, the files are expected to be part of the package in the source
directories. They may contain glob patterns as well.
The path names may contain directory portions; any necessary directories will be
created in the installation.
For example, if a package should contain a subdirectory with several data files,
the files can be arranged like this in the source tree::
setup.py
src/
mypkg/
__init__.py
module.py
data/
tables.dat
spoons.dat
forks.dat
The corresponding call to :func:`setup` might be::
setup(...,
packages=['mypkg'],
package_dir={'mypkg': 'src/mypkg'},
package_data={'mypkg': ['data/*.dat']},
)
.. versionadded:: 2.4
.. versionchanged:: 2.7
All the files that match ``package_data`` will be added to the ``MANIFEST``
file if no template is provided. See :ref:`manifest`.
.. _distutils-additional-files:
Installing Additional Files
===========================
The ``data_files`` option can be used to specify additional files needed
by the module distribution: configuration files, message catalogs, data files,
anything which doesn't fit in the previous categories.
``data_files`` specifies a sequence of (*directory*, *files*) pairs in the
following way::
setup(...,
data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']),
('config', ['cfg/data.cfg']),
)
Each (*directory*, *files*) pair in the sequence specifies the installation
directory and the files to install there.
Each file name in *files* is interpreted relative to the :file:`setup.py`
script at the top of the package source distribution. Note that you can
specify the directory where the data files will be installed, but you cannot
rename the data files themselves.
The *directory* should be a relative path. It is interpreted relative to the
installation prefix (Python's ``sys.prefix`` for system installations;
``site.USER_BASE`` for user installations). Distutils allows *directory* to be
an absolute installation path, but this is discouraged since it is
incompatible with the wheel packaging format. No directory information from
*files* is used to determine the final location of the installed file; only
the name of the file is used.
You can specify the ``data_files`` options as a simple sequence of files
without specifying a target directory, but this is not recommended, and the
:command:`install` command will print a warning in this case. To install data
files directly in the target directory, an empty string should be given as the
directory.
.. versionchanged:: 2.7
All the files that match ``data_files`` will be added to the ``MANIFEST``
file if no template is provided. See :ref:`manifest`.
.. _meta-data:
Additional meta-data
====================
The setup script may include additional meta-data beyond the name and version.
This information includes:
+----------------------+---------------------------+-----------------+--------+
| Meta-Data | Description | Value | Notes |
+======================+===========================+=================+========+
| ``name`` | name of the package | short string | \(1) |
+----------------------+---------------------------+-----------------+--------+
| ``version`` | version of this release | short string | (1)(2) |
+----------------------+---------------------------+-----------------+--------+
| ``author`` | package author's name | short string | \(3) |
+----------------------+---------------------------+-----------------+--------+
| ``author_email`` | email address of the | email address | \(3) |
| | package author | | |
+----------------------+---------------------------+-----------------+--------+
| ``maintainer`` | package maintainer's name | short string | \(3) |
+----------------------+---------------------------+-----------------+--------+
| ``maintainer_email`` | email address of the | email address | \(3) |
| | package maintainer | | |
+----------------------+---------------------------+-----------------+--------+
| ``url`` | home page for the package | URL | \(1) |
+----------------------+---------------------------+-----------------+--------+
| ``description`` | short, summary | short string | |
| | description of the | | |
| | package | | |
+----------------------+---------------------------+-----------------+--------+
| ``long_description`` | longer description of the | long string | \(5) |
| | package | | |
+----------------------+---------------------------+-----------------+--------+
| ``download_url`` | location where the | URL | \(4) |
| | package may be downloaded | | |
+----------------------+---------------------------+-----------------+--------+
| ``classifiers`` | a list of classifiers | list of strings | \(4) |
+----------------------+---------------------------+-----------------+--------+
| ``platforms`` | a list of platforms | list of strings | |
+----------------------+---------------------------+-----------------+--------+
| ``license`` | license for the package | short string | \(6) |
+----------------------+---------------------------+-----------------+--------+
Notes:
(1)
These fields are required.
(2)
It is recommended that versions take the form *major.minor[.patch[.sub]]*.
(3)
Either the author or the maintainer must be identified. If maintainer is
provided, distutils lists it as the author in :file:`PKG-INFO`.
(4)
These fields should not be used if your package is to be compatible with Python
versions prior to 2.2.3 or 2.3. The list is available from the `PyPI website
<https://pypi.org>`_.
(5)
The ``long_description`` field is used by PyPI when you are
:ref:`registering <package-register>` a package, to
:ref:`build its home page <package-display>`.
(6)
The ``license`` field is a text indicating the license covering the
package where the license is not a selection from the "License" Trove
classifiers. See the ``Classifier`` field. Notice that
there's a ``licence`` distribution option which is deprecated but still
acts as an alias for ``license``.
'short string'
A single line of text, not more than 200 characters.
'long string'
Multiple lines of plain text in reStructuredText format (see
http://docutils.sourceforge.net/).
'list of strings'
See below.
None of the string values may be Unicode.
Encoding the version information is an art in itself. Python packages generally
adhere to the version format *major.minor[.patch][sub]*. The major number is 0
for initial, experimental releases of software. It is incremented for releases
that represent major milestones in a package. The minor number is incremented
when important new features are added to the package. The patch number
increments when bug-fix releases are made. Additional trailing version
information is sometimes used to indicate sub-releases. These are
"a1,a2,...,aN" (for alpha releases, where functionality and API may change),
"b1,b2,...,bN" (for beta releases, which only fix bugs) and "pr1,pr2,...,prN"
(for final pre-release release testing). Some examples:
0.1.0
the first, experimental release of a package
1.0.1a2
the second alpha release of the first patch version of 1.0
``classifiers`` are specified in a Python list::
setup(...,
classifiers=[
'Development Status :: 4 - Beta',
'Environment :: Console',
'Environment :: Web Environment',
'Intended Audience :: End Users/Desktop',
'Intended Audience :: Developers',
'Intended Audience :: System Administrators',
'License :: OSI Approved :: Python Software Foundation License',
'Operating System :: MacOS :: MacOS X',
'Operating System :: Microsoft :: Windows',
'Operating System :: POSIX',
'Programming Language :: Python',
'Topic :: Communications :: Email',
'Topic :: Office/Business',
'Topic :: Software Development :: Bug Tracking',
],
)
If you wish to include classifiers in your :file:`setup.py` file and also wish
to remain backwards-compatible with Python releases prior to 2.2.3, then you can
include the following code fragment in your :file:`setup.py` before the
:func:`setup` call. ::
# patch distutils if it can't cope with the "classifiers" or
# "download_url" keywords
from sys import version
if version < '2.2.3':
from distutils.dist import DistributionMetadata
DistributionMetadata.classifiers = None
DistributionMetadata.download_url = None
.. _debug-setup-script:
Debugging the setup script
==========================
Sometimes things go wrong, and the setup script doesn't do what the developer
wants.
Distutils catches any exceptions when running the setup script, and print a
simple error message before the script is terminated. The motivation for this
behaviour is to not confuse administrators who don't know much about Python and
are trying to install a package. If they get a big long traceback from deep
inside the guts of Distutils, they may think the package or the Python
installation is broken because they don't read all the way down to the bottom
and see that it's a permission problem.
On the other hand, this doesn't help the developer to find the cause of the
failure. For this purpose, the :envvar:`DISTUTILS_DEBUG` environment variable can be set
to anything except an empty string, and distutils will now print detailed
information about what it is doing, dump the full traceback when an exception
occurs, and print the whole command line when an external program (like a C
compiler) fails.
PK %�\��z�0 �0 * html/_sources/distutils/sourcedist.rst.txtnu �[��� .. _source-dist:
******************************
Creating a Source Distribution
******************************
As shown in section :ref:`distutils-simple-example`, you use the :command:`sdist` command
to create a source distribution. In the simplest case, ::
python setup.py sdist
(assuming you haven't specified any :command:`sdist` options in the setup script
or config file), :command:`sdist` creates the archive of the default format for
the current platform. The default format is a gzip'ed tar file
(:file:`.tar.gz`) on Unix, and ZIP file on Windows.
You can specify as many formats as you like using the :option:`!--formats`
option, for example::
python setup.py sdist --formats=gztar,zip
to create a gzipped tarball and a zip file. The available formats are:
+-----------+-------------------------+---------+
| Format | Description | Notes |
+===========+=========================+=========+
| ``zip`` | zip file (:file:`.zip`) | (1),(3) |
+-----------+-------------------------+---------+
| ``gztar`` | gzip'ed tar file | \(2) |
| | (:file:`.tar.gz`) | |
+-----------+-------------------------+---------+
| ``bztar`` | bzip2'ed tar file | |
| | (:file:`.tar.bz2`) | |
+-----------+-------------------------+---------+
| ``ztar`` | compressed tar file | \(4) |
| | (:file:`.tar.Z`) | |
+-----------+-------------------------+---------+
| ``tar`` | tar file (:file:`.tar`) | |
+-----------+-------------------------+---------+
Notes:
(1)
default on Windows
(2)
default on Unix
(3)
requires either external :program:`zip` utility or :mod:`zipfile` module (part
of the standard Python library since Python 1.6)
(4)
requires the :program:`compress` program.
When using any ``tar`` format (``gztar``, ``bztar``, ``ztar`` or
``tar``) under Unix, you can specify the ``owner`` and ``group`` names
that will be set for each member of the archive.
For example, if you want all files of the archive to be owned by root::
python setup.py sdist --owner=root --group=root
.. _manifest:
Specifying the files to distribute
==================================
If you don't supply an explicit list of files (or instructions on how to
generate one), the :command:`sdist` command puts a minimal default set into the
source distribution:
* all Python source files implied by the ``py_modules`` and
``packages`` options
* all C source files mentioned in the ``ext_modules`` or
``libraries`` options
.. XXX Getting C library sources is currently broken -- no
:meth:`get_source_files` method in :file:`build_clib.py`!
* scripts identified by the ``scripts`` option
See :ref:`distutils-installing-scripts`.
* anything that looks like a test script: :file:`test/test\*.py` (currently, the
Distutils don't do anything with test scripts except include them in source
distributions, but in the future there will be a standard for testing Python
module distributions)
* :file:`README.txt` (or :file:`README`), :file:`setup.py` (or whatever you
called your setup script), and :file:`setup.cfg`
* all files that matches the ``package_data`` metadata.
See :ref:`distutils-installing-package-data`.
* all files that matches the ``data_files`` metadata.
See :ref:`distutils-additional-files`.
Sometimes this is enough, but usually you will want to specify additional files
to distribute. The typical way to do this is to write a *manifest template*,
called :file:`MANIFEST.in` by default. The manifest template is just a list of
instructions for how to generate your manifest file, :file:`MANIFEST`, which is
the exact list of files to include in your source distribution. The
:command:`sdist` command processes this template and generates a manifest based
on its instructions and what it finds in the filesystem.
If you prefer to roll your own manifest file, the format is simple: one filename
per line, regular files (or symlinks to them) only. If you do supply your own
:file:`MANIFEST`, you must specify everything: the default set of files
described above does not apply in this case.
.. versionchanged:: 2.7
An existing generated :file:`MANIFEST` will be regenerated without
:command:`sdist` comparing its modification time to the one of
:file:`MANIFEST.in` or :file:`setup.py`.
.. versionchanged:: 2.7.1
:file:`MANIFEST` files start with a comment indicating they are generated.
Files without this comment are not overwritten or removed.
.. versionchanged:: 2.7.3
:command:`sdist` will read a :file:`MANIFEST` file if no :file:`MANIFEST.in`
exists, like it did before 2.7.
See :ref:`manifest_template` section for a syntax reference.
.. _manifest-options:
Manifest-related options
========================
The normal course of operations for the :command:`sdist` command is as follows:
* if the manifest file (:file:`MANIFEST` by default) exists and the first line
does not have a comment indicating it is generated from :file:`MANIFEST.in`,
then it is used as is, unaltered
* if the manifest file doesn't exist or has been previously automatically
generated, read :file:`MANIFEST.in` and create the manifest
* if neither :file:`MANIFEST` nor :file:`MANIFEST.in` exist, create a manifest
with just the default file set
* use the list of files now in :file:`MANIFEST` (either just generated or read
in) to create the source distribution archive(s)
There are a couple of options that modify this behaviour. First, use the
:option:`!--no-defaults` and :option:`!--no-prune` to disable the standard
"include" and "exclude" sets.
Second, you might just want to (re)generate the manifest, but not create a
source distribution::
python setup.py sdist --manifest-only
:option:`!-o` is a shortcut for :option:`!--manifest-only`.
.. _manifest_template:
The MANIFEST.in template
========================
A :file:`MANIFEST.in` file can be added in a project to define the list of
files to include in the distribution built by the :command:`sdist` command.
When :command:`sdist` is run, it will look for the :file:`MANIFEST.in` file
and interpret it to generate the :file:`MANIFEST` file that contains the
list of files that will be included in the package.
This mechanism can be used when the default list of files is not enough.
(See :ref:`manifest`).
Principle
---------
The manifest template has one command per line, where each command specifies a
set of files to include or exclude from the source distribution. For an
example, let's look at the Distutils' own manifest template::
include *.txt
recursive-include examples *.txt *.py
prune examples/sample?/build
The meanings should be fairly clear: include all files in the distribution root
matching :file:`\*.txt`, all files anywhere under the :file:`examples` directory
matching :file:`\*.txt` or :file:`\*.py`, and exclude all directories matching
:file:`examples/sample?/build`. All of this is done *after* the standard
include set, so you can exclude files from the standard set with explicit
instructions in the manifest template. (Or, you can use the
:option:`!--no-defaults` option to disable the standard set entirely.)
The order of commands in the manifest template matters: initially, we have the
list of default files as described above, and each command in the template adds
to or removes from that list of files. Once we have fully processed the
manifest template, we remove files that should not be included in the source
distribution:
* all files in the Distutils "build" tree (default :file:`build/`)
* all files in directories named :file:`RCS`, :file:`CVS`, :file:`.svn`,
:file:`.hg`, :file:`.git`, :file:`.bzr` or :file:`_darcs`
Now we have our complete list of files, which is written to the manifest for
future reference, and then used to build the source distribution archive(s).
You can disable the default set of included files with the
:option:`!--no-defaults` option, and you can disable the standard exclude set
with :option:`!--no-prune`.
Following the Distutils' own manifest template, let's trace how the
:command:`sdist` command builds the list of files to include in the Distutils
source distribution:
#. include all Python source files in the :file:`distutils` and
:file:`distutils/command` subdirectories (because packages corresponding to
those two directories were mentioned in the ``packages`` option in the
setup script---see section :ref:`setup-script`)
#. include :file:`README.txt`, :file:`setup.py`, and :file:`setup.cfg` (standard
files)
#. include :file:`test/test\*.py` (standard files)
#. include :file:`\*.txt` in the distribution root (this will find
:file:`README.txt` a second time, but such redundancies are weeded out later)
#. include anything matching :file:`\*.txt` or :file:`\*.py` in the sub-tree
under :file:`examples`,
#. exclude all files in the sub-trees starting at directories matching
:file:`examples/sample?/build`\ ---this may exclude files included by the
previous two steps, so it's important that the ``prune`` command in the manifest
template comes after the ``recursive-include`` command
#. exclude the entire :file:`build` tree, and any :file:`RCS`, :file:`CVS`,
:file:`.svn`, :file:`.hg`, :file:`.git`, :file:`.bzr` and :file:`_darcs`
directories
Just like in the setup script, file and directory names in the manifest template
should always be slash-separated; the Distutils will take care of converting
them to the standard representation on your platform. That way, the manifest
template is portable across operating systems.
Commands
--------
The manifest template commands are:
+-------------------------------------------+-----------------------------------------------+
| Command | Description |
+===========================================+===============================================+
| :command:`include pat1 pat2 ...` | include all files matching any of the listed |
| | patterns |
+-------------------------------------------+-----------------------------------------------+
| :command:`exclude pat1 pat2 ...` | exclude all files matching any of the listed |
| | patterns |
+-------------------------------------------+-----------------------------------------------+
| :command:`recursive-include dir pat1 pat2 | include all files under *dir* matching any of |
| ...` | the listed patterns |
+-------------------------------------------+-----------------------------------------------+
| :command:`recursive-exclude dir pat1 pat2 | exclude all files under *dir* matching any of |
| ...` | the listed patterns |
+-------------------------------------------+-----------------------------------------------+
| :command:`global-include pat1 pat2 ...` | include all files anywhere in the source tree |
| | matching --- & any of the listed patterns |
+-------------------------------------------+-----------------------------------------------+
| :command:`global-exclude pat1 pat2 ...` | exclude all files anywhere in the source tree |
| | matching --- & any of the listed patterns |
+-------------------------------------------+-----------------------------------------------+
| :command:`prune dir` | exclude all files under *dir* |
+-------------------------------------------+-----------------------------------------------+
| :command:`graft dir` | include all files under *dir* |
+-------------------------------------------+-----------------------------------------------+
The patterns here are Unix-style "glob" patterns: ``*`` matches any sequence of
regular filename characters, ``?`` matches any single regular filename
character, and ``[range]`` matches any of the characters in *range* (e.g.,
``a-z``, ``a-zA-Z``, ``a-f0-9_.``). The definition of "regular filename
character" is platform-specific: on Unix it is anything except slash; on Windows
anything except backslash or colon.
PK %�\7Ru�� � ) html/_sources/distutils/uploading.rst.txtnu �[��� :orphan:
***************************************
Uploading Packages to the Package Index
***************************************
The contents of this page have moved to the section :ref:`package-index`.
PK %�\� �V ( html/_sources/extending/building.rst.txtnu �[��� .. highlightlang:: c
.. _building:
********************************************
Building C and C++ Extensions with distutils
********************************************
.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
Starting in Python 1.4, Python provides, on Unix, a special make file for
building make files for building dynamically-linked extensions and custom
interpreters. Starting with Python 2.0, this mechanism (known as related to
Makefile.pre.in, and Setup files) is no longer supported. Building custom
interpreters was rarely used, and extension modules can be built using
distutils.
Building an extension module using distutils requires that distutils is
installed on the build machine, which is included in Python 2.x and available
separately for Python 1.5. Since distutils also supports creation of binary
packages, users don't necessarily need a compiler and distutils to install the
extension.
A distutils package contains a driver script, :file:`setup.py`. This is a plain
Python file, which, in the most simple case, could look like this:
.. code-block:: python
from distutils.core import setup, Extension
module1 = Extension('demo',
sources = ['demo.c'])
setup (name = 'PackageName',
version = '1.0',
description = 'This is a demo package',
ext_modules = [module1])
With this :file:`setup.py`, and a file :file:`demo.c`, running ::
python setup.py build
will compile :file:`demo.c`, and produce an extension module named ``demo`` in
the :file:`build` directory. Depending on the system, the module file will end
up in a subdirectory :file:`build/lib.system`, and may have a name like
:file:`demo.so` or :file:`demo.pyd`.
In the :file:`setup.py`, all execution is performed by calling the ``setup``
function. This takes a variable number of keyword arguments, of which the
example above uses only a subset. Specifically, the example specifies
meta-information to build packages, and it specifies the contents of the
package. Normally, a package will contain of addition modules, like Python
source modules, documentation, subpackages, etc. Please refer to the distutils
documentation in :ref:`distutils-index` to learn more about the features of
distutils; this section explains building extension modules only.
It is common to pre-compute arguments to :func:`setup`, to better structure the
driver script. In the example above, the ``ext_modules`` argument to
:func:`setup` is a list of extension modules, each of which is an instance of
the :class:`~distutils.extension.Extension`. In the example, the instance
defines an extension named ``demo`` which is build by compiling a single source
file, :file:`demo.c`.
In many cases, building an extension is more complex, since additional
preprocessor defines and libraries may be needed. This is demonstrated in the
example below.
.. code-block:: python
from distutils.core import setup, Extension
module1 = Extension('demo',
define_macros = [('MAJOR_VERSION', '1'),
('MINOR_VERSION', '0')],
include_dirs = ['/usr/local/include'],
libraries = ['tcl83'],
library_dirs = ['/usr/local/lib'],
sources = ['demo.c'])
setup (name = 'PackageName',
version = '1.0',
description = 'This is a demo package',
author = 'Martin v. Loewis',
author_email = 'martin@v.loewis.de',
url = 'https://docs.python.org/extending/building',
long_description = '''
This is really just a demo package.
''',
ext_modules = [module1])
In this example, :func:`setup` is called with additional meta-information, which
is recommended when distribution packages have to be built. For the extension
itself, it specifies preprocessor defines, include directories, library
directories, and libraries. Depending on the compiler, distutils passes this
information in different ways to the compiler. For example, on Unix, this may
result in the compilation commands ::
gcc -DNDEBUG -g -O3 -Wall -Wstrict-prototypes -fPIC -DMAJOR_VERSION=1 -DMINOR_VERSION=0 -I/usr/local/include -I/usr/local/include/python2.2 -c demo.c -o build/temp.linux-i686-2.2/demo.o
gcc -shared build/temp.linux-i686-2.2/demo.o -L/usr/local/lib -ltcl83 -o build/lib.linux-i686-2.2/demo.so
These lines are for demonstration purposes only; distutils users should trust
that distutils gets the invocations right.
.. _distributing:
Distributing your extension modules
===================================
When an extension has been successfully build, there are three ways to use it.
End-users will typically want to install the module, they do so by running ::
python setup.py install
Module maintainers should produce source packages; to do so, they run ::
python setup.py sdist
In some cases, additional files need to be included in a source distribution;
this is done through a :file:`MANIFEST.in` file; see the distutils documentation
for details.
If the source distribution has been build successfully, maintainers can also
create binary distributions. Depending on the platform, one of the following
commands can be used to do so. ::
python setup.py bdist_wininst
python setup.py bdist_rpm
python setup.py bdist_dumb
PK %�\�w��{/ {/ ) html/_sources/extending/embedding.rst.txtnu �[��� .. highlightlang:: c
.. _embedding:
***************************************
Embedding Python in Another Application
***************************************
The previous chapters discussed how to extend Python, that is, how to extend the
functionality of Python by attaching a library of C functions to it. It is also
possible to do it the other way around: enrich your C/C++ application by
embedding Python in it. Embedding provides your application with the ability to
implement some of the functionality of your application in Python rather than C
or C++. This can be used for many purposes; one example would be to allow users
to tailor the application to their needs by writing some scripts in Python. You
can also use it yourself if some of the functionality can be written in Python
more easily.
Embedding Python is similar to extending it, but not quite. The difference is
that when you extend Python, the main program of the application is still the
Python interpreter, while if you embed Python, the main program may have nothing
to do with Python --- instead, some parts of the application occasionally call
the Python interpreter to run some Python code.
So if you are embedding Python, you are providing your own main program. One of
the things this main program has to do is initialize the Python interpreter. At
the very least, you have to call the function :c:func:`Py_Initialize`. There are
optional calls to pass command line arguments to Python. Then later you can
call the interpreter from any part of the application.
There are several different ways to call the interpreter: you can pass a string
containing Python statements to :c:func:`PyRun_SimpleString`, or you can pass a
stdio file pointer and a file name (for identification in error messages only)
to :c:func:`PyRun_SimpleFile`. You can also call the lower-level operations
described in the previous chapters to construct and use Python objects.
A simple demo of embedding Python can be found in the directory
:file:`Demo/embed/` of the source distribution.
.. seealso::
:ref:`c-api-index`
The details of Python's C interface are given in this manual. A great deal of
necessary information can be found here.
.. _high-level-embedding:
Very High Level Embedding
=========================
The simplest form of embedding Python is the use of the very high level
interface. This interface is intended to execute a Python script without needing
to interact with the application directly. This can for example be used to
perform some operation on a file. ::
#include <Python.h>
int
main(int argc, char *argv[])
{
Py_SetProgramName(argv[0]); /* optional but recommended */
Py_Initialize();
PyRun_SimpleString("from time import time,ctime\n"
"print 'Today is',ctime(time())\n");
Py_Finalize();
return 0;
}
The :c:func:`Py_SetProgramName` function should be called before
:c:func:`Py_Initialize` to inform the interpreter about paths to Python run-time
libraries. Next, the Python interpreter is initialized with
:c:func:`Py_Initialize`, followed by the execution of a hard-coded Python script
that prints the date and time. Afterwards, the :c:func:`Py_Finalize` call shuts
the interpreter down, followed by the end of the program. In a real program,
you may want to get the Python script from another source, perhaps a text-editor
routine, a file, or a database. Getting the Python code from a file can better
be done by using the :c:func:`PyRun_SimpleFile` function, which saves you the
trouble of allocating memory space and loading the file contents.
.. _lower-level-embedding:
Beyond Very High Level Embedding: An overview
=============================================
The high level interface gives you the ability to execute arbitrary pieces of
Python code from your application, but exchanging data values is quite
cumbersome to say the least. If you want that, you should use lower level calls.
At the cost of having to write more C code, you can achieve almost anything.
It should be noted that extending Python and embedding Python is quite the same
activity, despite the different intent. Most topics discussed in the previous
chapters are still valid. To show this, consider what the extension code from
Python to C really does:
#. Convert data values from Python to C,
#. Perform a function call to a C routine using the converted values, and
#. Convert the data values from the call from C to Python.
When embedding Python, the interface code does:
#. Convert data values from C to Python,
#. Perform a function call to a Python interface routine using the converted
values, and
#. Convert the data values from the call from Python to C.
As you can see, the data conversion steps are simply swapped to accommodate the
different direction of the cross-language transfer. The only difference is the
routine that you call between both data conversions. When extending, you call a
C routine, when embedding, you call a Python routine.
This chapter will not discuss how to convert data from Python to C and vice
versa. Also, proper use of references and dealing with errors is assumed to be
understood. Since these aspects do not differ from extending the interpreter,
you can refer to earlier chapters for the required information.
.. _pure-embedding:
Pure Embedding
==============
The first program aims to execute a function in a Python script. Like in the
section about the very high level interface, the Python interpreter does not
directly interact with the application (but that will change in the next
section).
The code to run a function defined in a Python script is:
.. literalinclude:: ../includes/run-func.c
This code loads a Python script using ``argv[1]``, and calls the function named
in ``argv[2]``. Its integer arguments are the other values of the ``argv``
array. If you compile and link this program (let's call the finished executable
:program:`call`), and use it to execute a Python script, such as:
.. code-block:: python
def multiply(a,b):
print "Will compute", a, "times", b
c = 0
for i in range(0, a):
c = c + b
return c
then the result should be:
.. code-block:: shell-session
$ call multiply multiply 3 2
Will compute 3 times 2
Result of call: 6
Although the program is quite large for its functionality, most of the code is
for data conversion between Python and C, and for error reporting. The
interesting part with respect to embedding Python starts with ::
Py_Initialize();
pName = PyString_FromString(argv[1]);
/* Error checking of pName left out */
pModule = PyImport_Import(pName);
After initializing the interpreter, the script is loaded using
:c:func:`PyImport_Import`. This routine needs a Python string as its argument,
which is constructed using the :c:func:`PyString_FromString` data conversion
routine. ::
pFunc = PyObject_GetAttrString(pModule, argv[2]);
/* pFunc is a new reference */
if (pFunc && PyCallable_Check(pFunc)) {
...
}
Py_XDECREF(pFunc);
Once the script is loaded, the name we're looking for is retrieved using
:c:func:`PyObject_GetAttrString`. If the name exists, and the object returned is
callable, you can safely assume that it is a function. The program then
proceeds by constructing a tuple of arguments as normal. The call to the Python
function is then made with::
pValue = PyObject_CallObject(pFunc, pArgs);
Upon return of the function, ``pValue`` is either *NULL* or it contains a
reference to the return value of the function. Be sure to release the reference
after examining the value.
.. _extending-with-embedding:
Extending Embedded Python
=========================
Until now, the embedded Python interpreter had no access to functionality from
the application itself. The Python API allows this by extending the embedded
interpreter. That is, the embedded interpreter gets extended with routines
provided by the application. While it sounds complex, it is not so bad. Simply
forget for a while that the application starts the Python interpreter. Instead,
consider the application to be a set of subroutines, and write some glue code
that gives Python access to those routines, just like you would write a normal
Python extension. For example::
static int numargs=0;
/* Return the number of arguments of the application command line */
static PyObject*
emb_numargs(PyObject *self, PyObject *args)
{
if(!PyArg_ParseTuple(args, ":numargs"))
return NULL;
return Py_BuildValue("i", numargs);
}
static PyMethodDef EmbMethods[] = {
{"numargs", emb_numargs, METH_VARARGS,
"Return the number of arguments received by the process."},
{NULL, NULL, 0, NULL}
};
Insert the above code just above the :c:func:`main` function. Also, insert the
following two statements directly after :c:func:`Py_Initialize`::
numargs = argc;
Py_InitModule("emb", EmbMethods);
These two lines initialize the ``numargs`` variable, and make the
:func:`emb.numargs` function accessible to the embedded Python interpreter.
With these extensions, the Python script can do things like
.. code-block:: python
import emb
print "Number of arguments", emb.numargs()
In a real application, the methods will expose an API of the application to
Python.
.. TODO: threads, code examples do not really behave well if errors happen
(what to watch out for)
.. _embeddingincplusplus:
Embedding Python in C++
=======================
It is also possible to embed Python in a C++ program; precisely how this is done
will depend on the details of the C++ system used; in general you will need to
write the main program in C++, and use the C++ compiler to compile and link your
program. There is no need to recompile Python itself using C++.
.. _link-reqs:
Compiling and Linking under Unix-like systems
=============================================
It is not necessarily trivial to find the right flags to pass to your
compiler (and linker) in order to embed the Python interpreter into your
application, particularly because Python needs to load library modules
implemented as C dynamic extensions (:file:`.so` files) linked against
it.
To find out the required compiler and linker flags, you can execute the
:file:`python{X.Y}-config` script which is generated as part of the
installation process (a :file:`python-config` script may also be
available). This script has several options, of which the following will
be directly useful to you:
* ``pythonX.Y-config --cflags`` will give you the recommended flags when
compiling:
.. code-block:: shell-session
$ /opt/bin/python2.7-config --cflags
-I/opt/include/python2.7 -fno-strict-aliasing -DNDEBUG -g -fwrapv -O3 -Wall -Wstrict-prototypes
* ``pythonX.Y-config --ldflags`` will give you the recommended flags when
linking:
.. code-block:: shell-session
$ /opt/bin/python2.7-config --ldflags
-L/opt/lib/python2.7/config -lpthread -ldl -lutil -lm -lpython2.7 -Xlinker -export-dynamic
.. note::
To avoid confusion between several Python installations (and especially
between the system Python and your own compiled Python), it is recommended
that you use the absolute path to :file:`python{X.Y}-config`, as in the above
example.
If this procedure doesn't work for you (it is not guaranteed to work for
all Unix-like platforms; however, we welcome :ref:`bug reports <reporting-bugs>`)
you will have to read your system's documentation about dynamic linking and/or
examine Python's :file:`Makefile` (use :func:`sysconfig.get_makefile_filename`
to find its location) and compilation
options. In this case, the :mod:`sysconfig` module is a useful tool to
programmatically extract the configuration values that you will want to
combine together. For example:
.. code-block:: python
>>> import sysconfig
>>> sysconfig.get_config_var('LIBS')
'-lpthread -ldl -lutil'
>>> sysconfig.get_config_var('LINKFORSHARED')
'-Xlinker -export-dynamic'
.. XXX similar documentation for Windows missing
PK %�\��1N�� �� ) html/_sources/extending/extending.rst.txtnu �[��� .. highlightlang:: c
.. _extending-intro:
******************************
Extending Python with C or C++
******************************
It is quite easy to add new built-in modules to Python, if you know how to
program in C. Such :dfn:`extension modules` can do two things that can't be
done directly in Python: they can implement new built-in object types, and they
can call C library functions and system calls.
To support extensions, the Python API (Application Programmers Interface)
defines a set of functions, macros and variables that provide access to most
aspects of the Python run-time system. The Python API is incorporated in a C
source file by including the header ``"Python.h"``.
The compilation of an extension module depends on its intended use as well as on
your system setup; details are given in later chapters.
.. note::
The C extension interface is specific to CPython, and extension modules do
not work on other Python implementations. In many cases, it is possible to
avoid writing C extensions and preserve portability to other implementations.
For example, if your use case is calling C library functions or system calls,
you should consider using the :mod:`ctypes` module or the `cffi
<https://cffi.readthedocs.org>`_ library rather than writing custom C code.
These modules let you write Python code to interface with C code and are more
portable between implementations of Python than writing and compiling a C
extension module.
.. _extending-simpleexample:
A Simple Example
================
Let's create an extension module called ``spam`` (the favorite food of Monty
Python fans...) and let's say we want to create a Python interface to the C
library function :c:func:`system` [#]_. This function takes a null-terminated
character string as argument and returns an integer. We want this function to
be callable from Python as follows::
>>> import spam
>>> status = spam.system("ls -l")
Begin by creating a file :file:`spammodule.c`. (Historically, if a module is
called ``spam``, the C file containing its implementation is called
:file:`spammodule.c`; if the module name is very long, like ``spammify``, the
module name can be just :file:`spammify.c`.)
The first line of our file can be::
#include <Python.h>
which pulls in the Python API (you can add a comment describing the purpose of
the module and a copyright notice if you like).
.. note::
Since Python may define some pre-processor definitions which affect the standard
headers on some systems, you *must* include :file:`Python.h` before any standard
headers are included.
All user-visible symbols defined by :file:`Python.h` have a prefix of ``Py`` or
``PY``, except those defined in standard header files. For convenience, and
since they are used extensively by the Python interpreter, ``"Python.h"``
includes a few standard header files: ``<stdio.h>``, ``<string.h>``,
``<errno.h>``, and ``<stdlib.h>``. If the latter header file does not exist on
your system, it declares the functions :c:func:`malloc`, :c:func:`free` and
:c:func:`realloc` directly.
The next thing we add to our module file is the C function that will be called
when the Python expression ``spam.system(string)`` is evaluated (we'll see
shortly how it ends up being called)::
static PyObject *
spam_system(PyObject *self, PyObject *args)
{
const char *command;
int sts;
if (!PyArg_ParseTuple(args, "s", &command))
return NULL;
sts = system(command);
return Py_BuildValue("i", sts);
}
There is a straightforward translation from the argument list in Python (for
example, the single expression ``"ls -l"``) to the arguments passed to the C
function. The C function always has two arguments, conventionally named *self*
and *args*.
For module functions, the *self* argument is *NULL* or a pointer selected while
initializing the module (see :c:func:`Py_InitModule4`). For a method, it would
point to the object instance.
The *args* argument will be a pointer to a Python tuple object containing the
arguments. Each item of the tuple corresponds to an argument in the call's
argument list. The arguments are Python objects --- in order to do anything
with them in our C function we have to convert them to C values. The function
:c:func:`PyArg_ParseTuple` in the Python API checks the argument types and
converts them to C values. It uses a template string to determine the required
types of the arguments as well as the types of the C variables into which to
store the converted values. More about this later.
:c:func:`PyArg_ParseTuple` returns true (nonzero) if all arguments have the right
type and its components have been stored in the variables whose addresses are
passed. It returns false (zero) if an invalid argument list was passed. In the
latter case it also raises an appropriate exception so the calling function can
return *NULL* immediately (as we saw in the example).
.. _extending-errors:
Intermezzo: Errors and Exceptions
=================================
An important convention throughout the Python interpreter is the following: when
a function fails, it should set an exception condition and return an error value
(usually a *NULL* pointer). Exceptions are stored in a static global variable
inside the interpreter; if this variable is *NULL* no exception has occurred. A
second global variable stores the "associated value" of the exception (the
second argument to :keyword:`raise`). A third variable contains the stack
traceback in case the error originated in Python code. These three variables
are the C equivalents of the Python variables ``sys.exc_type``,
``sys.exc_value`` and ``sys.exc_traceback`` (see the section on module
:mod:`sys` in the Python Library Reference). It is important to know about them
to understand how errors are passed around.
The Python API defines a number of functions to set various types of exceptions.
The most common one is :c:func:`PyErr_SetString`. Its arguments are an exception
object and a C string. The exception object is usually a predefined object like
:c:data:`PyExc_ZeroDivisionError`. The C string indicates the cause of the error
and is converted to a Python string object and stored as the "associated value"
of the exception.
Another useful function is :c:func:`PyErr_SetFromErrno`, which only takes an
exception argument and constructs the associated value by inspection of the
global variable :c:data:`errno`. The most general function is
:c:func:`PyErr_SetObject`, which takes two object arguments, the exception and
its associated value. You don't need to :c:func:`Py_INCREF` the objects passed
to any of these functions.
You can test non-destructively whether an exception has been set with
:c:func:`PyErr_Occurred`. This returns the current exception object, or *NULL*
if no exception has occurred. You normally don't need to call
:c:func:`PyErr_Occurred` to see whether an error occurred in a function call,
since you should be able to tell from the return value.
When a function *f* that calls another function *g* detects that the latter
fails, *f* should itself return an error value (usually *NULL* or ``-1``). It
should *not* call one of the :c:func:`PyErr_\*` functions --- one has already
been called by *g*. *f*'s caller is then supposed to also return an error
indication to *its* caller, again *without* calling :c:func:`PyErr_\*`, and so on
--- the most detailed cause of the error was already reported by the function
that first detected it. Once the error reaches the Python interpreter's main
loop, this aborts the currently executing Python code and tries to find an
exception handler specified by the Python programmer.
(There are situations where a module can actually give a more detailed error
message by calling another :c:func:`PyErr_\*` function, and in such cases it is
fine to do so. As a general rule, however, this is not necessary, and can cause
information about the cause of the error to be lost: most operations can fail
for a variety of reasons.)
To ignore an exception set by a function call that failed, the exception
condition must be cleared explicitly by calling :c:func:`PyErr_Clear`. The only
time C code should call :c:func:`PyErr_Clear` is if it doesn't want to pass the
error on to the interpreter but wants to handle it completely by itself
(possibly by trying something else, or pretending nothing went wrong).
Every failing :c:func:`malloc` call must be turned into an exception --- the
direct caller of :c:func:`malloc` (or :c:func:`realloc`) must call
:c:func:`PyErr_NoMemory` and return a failure indicator itself. All the
object-creating functions (for example, :c:func:`PyInt_FromLong`) already do
this, so this note is only relevant to those who call :c:func:`malloc` directly.
Also note that, with the important exception of :c:func:`PyArg_ParseTuple` and
friends, functions that return an integer status usually return a positive value
or zero for success and ``-1`` for failure, like Unix system calls.
Finally, be careful to clean up garbage (by making :c:func:`Py_XDECREF` or
:c:func:`Py_DECREF` calls for objects you have already created) when you return
an error indicator!
The choice of which exception to raise is entirely yours. There are predeclared
C objects corresponding to all built-in Python exceptions, such as
:c:data:`PyExc_ZeroDivisionError`, which you can use directly. Of course, you
should choose exceptions wisely --- don't use :c:data:`PyExc_TypeError` to mean
that a file couldn't be opened (that should probably be :c:data:`PyExc_IOError`).
If something's wrong with the argument list, the :c:func:`PyArg_ParseTuple`
function usually raises :c:data:`PyExc_TypeError`. If you have an argument whose
value must be in a particular range or must satisfy other conditions,
:c:data:`PyExc_ValueError` is appropriate.
You can also define a new exception that is unique to your module. For this, you
usually declare a static object variable at the beginning of your file::
static PyObject *SpamError;
and initialize it in your module's initialization function (:c:func:`initspam`)
with an exception object (leaving out the error checking for now)::
PyMODINIT_FUNC
initspam(void)
{
PyObject *m;
m = Py_InitModule("spam", SpamMethods);
if (m == NULL)
return;
SpamError = PyErr_NewException("spam.error", NULL, NULL);
Py_INCREF(SpamError);
PyModule_AddObject(m, "error", SpamError);
}
Note that the Python name for the exception object is :exc:`spam.error`. The
:c:func:`PyErr_NewException` function may create a class with the base class
being :exc:`Exception` (unless another class is passed in instead of *NULL*),
described in :ref:`bltin-exceptions`.
Note also that the :c:data:`SpamError` variable retains a reference to the newly
created exception class; this is intentional! Since the exception could be
removed from the module by external code, an owned reference to the class is
needed to ensure that it will not be discarded, causing :c:data:`SpamError` to
become a dangling pointer. Should it become a dangling pointer, C code which
raises the exception could cause a core dump or other unintended side effects.
We discuss the use of ``PyMODINIT_FUNC`` as a function return type later in this
sample.
The :exc:`spam.error` exception can be raised in your extension module using a
call to :c:func:`PyErr_SetString` as shown below::
static PyObject *
spam_system(PyObject *self, PyObject *args)
{
const char *command;
int sts;
if (!PyArg_ParseTuple(args, "s", &command))
return NULL;
sts = system(command);
if (sts < 0) {
PyErr_SetString(SpamError, "System command failed");
return NULL;
}
return PyLong_FromLong(sts);
}
.. _backtoexample:
Back to the Example
===================
Going back to our example function, you should now be able to understand this
statement::
if (!PyArg_ParseTuple(args, "s", &command))
return NULL;
It returns *NULL* (the error indicator for functions returning object pointers)
if an error is detected in the argument list, relying on the exception set by
:c:func:`PyArg_ParseTuple`. Otherwise the string value of the argument has been
copied to the local variable :c:data:`command`. This is a pointer assignment and
you are not supposed to modify the string to which it points (so in Standard C,
the variable :c:data:`command` should properly be declared as ``const char
*command``).
The next statement is a call to the Unix function :c:func:`system`, passing it
the string we just got from :c:func:`PyArg_ParseTuple`::
sts = system(command);
Our :func:`spam.system` function must return the value of :c:data:`sts` as a
Python object. This is done using the function :c:func:`Py_BuildValue`, which is
something like the inverse of :c:func:`PyArg_ParseTuple`: it takes a format
string and an arbitrary number of C values, and returns a new Python object.
More info on :c:func:`Py_BuildValue` is given later. ::
return Py_BuildValue("i", sts);
In this case, it will return an integer object. (Yes, even integers are objects
on the heap in Python!)
If you have a C function that returns no useful argument (a function returning
:c:type:`void`), the corresponding Python function must return ``None``. You
need this idiom to do so (which is implemented by the :c:macro:`Py_RETURN_NONE`
macro)::
Py_INCREF(Py_None);
return Py_None;
:c:data:`Py_None` is the C name for the special Python object ``None``. It is a
genuine Python object rather than a *NULL* pointer, which means "error" in most
contexts, as we have seen.
.. _methodtable:
The Module's Method Table and Initialization Function
=====================================================
I promised to show how :c:func:`spam_system` is called from Python programs.
First, we need to list its name and address in a "method table"::
static PyMethodDef SpamMethods[] = {
...
{"system", spam_system, METH_VARARGS,
"Execute a shell command."},
...
{NULL, NULL, 0, NULL} /* Sentinel */
};
Note the third entry (``METH_VARARGS``). This is a flag telling the interpreter
the calling convention to be used for the C function. It should normally always
be ``METH_VARARGS`` or ``METH_VARARGS | METH_KEYWORDS``; a value of ``0`` means
that an obsolete variant of :c:func:`PyArg_ParseTuple` is used.
When using only ``METH_VARARGS``, the function should expect the Python-level
parameters to be passed in as a tuple acceptable for parsing via
:c:func:`PyArg_ParseTuple`; more information on this function is provided below.
The :const:`METH_KEYWORDS` bit may be set in the third field if keyword
arguments should be passed to the function. In this case, the C function should
accept a third ``PyObject *`` parameter which will be a dictionary of keywords.
Use :c:func:`PyArg_ParseTupleAndKeywords` to parse the arguments to such a
function.
The method table must be passed to the interpreter in the module's
initialization function. The initialization function must be named
:c:func:`initname`, where *name* is the name of the module, and should be the
only non-\ ``static`` item defined in the module file::
PyMODINIT_FUNC
initspam(void)
{
(void) Py_InitModule("spam", SpamMethods);
}
Note that PyMODINIT_FUNC declares the function as ``void`` return type,
declares any special linkage declarations required by the platform, and for C++
declares the function as ``extern "C"``.
When the Python program imports module :mod:`spam` for the first time,
:c:func:`initspam` is called. (See below for comments about embedding Python.)
It calls :c:func:`Py_InitModule`, which creates a "module object" (which is
inserted in the dictionary ``sys.modules`` under the key ``"spam"``), and
inserts built-in function objects into the newly created module based upon the
table (an array of :c:type:`PyMethodDef` structures) that was passed as its
second argument. :c:func:`Py_InitModule` returns a pointer to the module object
that it creates (which is unused here). It may abort with a fatal error for
certain errors, or return *NULL* if the module could not be initialized
satisfactorily.
When embedding Python, the :c:func:`initspam` function is not called
automatically unless there's an entry in the :c:data:`_PyImport_Inittab` table.
The easiest way to handle this is to statically initialize your
statically-linked modules by directly calling :c:func:`initspam` after the call
to :c:func:`Py_Initialize`::
int
main(int argc, char *argv[])
{
/* Pass argv[0] to the Python interpreter */
Py_SetProgramName(argv[0]);
/* Initialize the Python interpreter. Required. */
Py_Initialize();
/* Add a static module */
initspam();
...
An example may be found in the file :file:`Demo/embed/demo.c` in the Python
source distribution.
.. note::
Removing entries from ``sys.modules`` or importing compiled modules into
multiple interpreters within a process (or following a :c:func:`fork` without an
intervening :c:func:`exec`) can create problems for some extension modules.
Extension module authors should exercise caution when initializing internal data
structures. Note also that the :func:`reload` function can be used with
extension modules, and will call the module initialization function
(:c:func:`initspam` in the example), but will not load the module again if it was
loaded from a dynamically loadable object file (:file:`.so` on Unix,
:file:`.dll` on Windows).
A more substantial example module is included in the Python source distribution
as :file:`Modules/xxmodule.c`. This file may be used as a template or simply
read as an example.
.. _compilation:
Compilation and Linkage
=======================
There are two more things to do before you can use your new extension: compiling
and linking it with the Python system. If you use dynamic loading, the details
may depend on the style of dynamic loading your system uses; see the chapters
about building extension modules (chapter :ref:`building`) and additional
information that pertains only to building on Windows (chapter
:ref:`building-on-windows`) for more information about this.
If you can't use dynamic loading, or if you want to make your module a permanent
part of the Python interpreter, you will have to change the configuration setup
and rebuild the interpreter. Luckily, this is very simple on Unix: just place
your file (:file:`spammodule.c` for example) in the :file:`Modules/` directory
of an unpacked source distribution, add a line to the file
:file:`Modules/Setup.local` describing your file::
spam spammodule.o
and rebuild the interpreter by running :program:`make` in the toplevel
directory. You can also run :program:`make` in the :file:`Modules/`
subdirectory, but then you must first rebuild :file:`Makefile` there by running
':program:`make` Makefile'. (This is necessary each time you change the
:file:`Setup` file.)
If your module requires additional libraries to link with, these can be listed
on the line in the configuration file as well, for instance::
spam spammodule.o -lX11
.. _callingpython:
Calling Python Functions from C
===============================
So far we have concentrated on making C functions callable from Python. The
reverse is also useful: calling Python functions from C. This is especially the
case for libraries that support so-called "callback" functions. If a C
interface makes use of callbacks, the equivalent Python often needs to provide a
callback mechanism to the Python programmer; the implementation will require
calling the Python callback functions from a C callback. Other uses are also
imaginable.
Fortunately, the Python interpreter is easily called recursively, and there is a
standard interface to call a Python function. (I won't dwell on how to call the
Python parser with a particular string as input --- if you're interested, have a
look at the implementation of the :option:`-c` command line option in
:file:`Modules/main.c` from the Python source code.)
Calling a Python function is easy. First, the Python program must somehow pass
you the Python function object. You should provide a function (or some other
interface) to do this. When this function is called, save a pointer to the
Python function object (be careful to :c:func:`Py_INCREF` it!) in a global
variable --- or wherever you see fit. For example, the following function might
be part of a module definition::
static PyObject *my_callback = NULL;
static PyObject *
my_set_callback(PyObject *dummy, PyObject *args)
{
PyObject *result = NULL;
PyObject *temp;
if (PyArg_ParseTuple(args, "O:set_callback", &temp)) {
if (!PyCallable_Check(temp)) {
PyErr_SetString(PyExc_TypeError, "parameter must be callable");
return NULL;
}
Py_XINCREF(temp); /* Add a reference to new callback */
Py_XDECREF(my_callback); /* Dispose of previous callback */
my_callback = temp; /* Remember new callback */
/* Boilerplate to return "None" */
Py_INCREF(Py_None);
result = Py_None;
}
return result;
}
This function must be registered with the interpreter using the
:const:`METH_VARARGS` flag; this is described in section :ref:`methodtable`. The
:c:func:`PyArg_ParseTuple` function and its arguments are documented in section
:ref:`parsetuple`.
The macros :c:func:`Py_XINCREF` and :c:func:`Py_XDECREF` increment/decrement the
reference count of an object and are safe in the presence of *NULL* pointers
(but note that *temp* will not be *NULL* in this context). More info on them
in section :ref:`refcounts`.
.. index:: single: PyObject_CallObject()
Later, when it is time to call the function, you call the C function
:c:func:`PyObject_CallObject`. This function has two arguments, both pointers to
arbitrary Python objects: the Python function, and the argument list. The
argument list must always be a tuple object, whose length is the number of
arguments. To call the Python function with no arguments, pass in NULL, or
an empty tuple; to call it with one argument, pass a singleton tuple.
:c:func:`Py_BuildValue` returns a tuple when its format string consists of zero
or more format codes between parentheses. For example::
int arg;
PyObject *arglist;
PyObject *result;
...
arg = 123;
...
/* Time to call the callback */
arglist = Py_BuildValue("(i)", arg);
result = PyObject_CallObject(my_callback, arglist);
Py_DECREF(arglist);
:c:func:`PyObject_CallObject` returns a Python object pointer: this is the return
value of the Python function. :c:func:`PyObject_CallObject` is
"reference-count-neutral" with respect to its arguments. In the example a new
tuple was created to serve as the argument list, which is :c:func:`Py_DECREF`\
-ed immediately after the :c:func:`PyObject_CallObject` call.
The return value of :c:func:`PyObject_CallObject` is "new": either it is a brand
new object, or it is an existing object whose reference count has been
incremented. So, unless you want to save it in a global variable, you should
somehow :c:func:`Py_DECREF` the result, even (especially!) if you are not
interested in its value.
Before you do this, however, it is important to check that the return value
isn't *NULL*. If it is, the Python function terminated by raising an exception.
If the C code that called :c:func:`PyObject_CallObject` is called from Python, it
should now return an error indication to its Python caller, so the interpreter
can print a stack trace, or the calling Python code can handle the exception.
If this is not possible or desirable, the exception should be cleared by calling
:c:func:`PyErr_Clear`. For example::
if (result == NULL)
return NULL; /* Pass error back */
...use result...
Py_DECREF(result);
Depending on the desired interface to the Python callback function, you may also
have to provide an argument list to :c:func:`PyObject_CallObject`. In some cases
the argument list is also provided by the Python program, through the same
interface that specified the callback function. It can then be saved and used
in the same manner as the function object. In other cases, you may have to
construct a new tuple to pass as the argument list. The simplest way to do this
is to call :c:func:`Py_BuildValue`. For example, if you want to pass an integral
event code, you might use the following code::
PyObject *arglist;
...
arglist = Py_BuildValue("(l)", eventcode);
result = PyObject_CallObject(my_callback, arglist);
Py_DECREF(arglist);
if (result == NULL)
return NULL; /* Pass error back */
/* Here maybe use the result */
Py_DECREF(result);
Note the placement of ``Py_DECREF(arglist)`` immediately after the call, before
the error check! Also note that strictly speaking this code is not complete:
:c:func:`Py_BuildValue` may run out of memory, and this should be checked.
You may also call a function with keyword arguments by using
:c:func:`PyObject_Call`, which supports arguments and keyword arguments. As in
the above example, we use :c:func:`Py_BuildValue` to construct the dictionary. ::
PyObject *dict;
...
dict = Py_BuildValue("{s:i}", "name", val);
result = PyObject_Call(my_callback, NULL, dict);
Py_DECREF(dict);
if (result == NULL)
return NULL; /* Pass error back */
/* Here maybe use the result */
Py_DECREF(result);
.. _parsetuple:
Extracting Parameters in Extension Functions
============================================
.. index:: single: PyArg_ParseTuple()
The :c:func:`PyArg_ParseTuple` function is declared as follows::
int PyArg_ParseTuple(PyObject *arg, char *format, ...);
The *arg* argument must be a tuple object containing an argument list passed
from Python to a C function. The *format* argument must be a format string,
whose syntax is explained in :ref:`arg-parsing` in the Python/C API Reference
Manual. The remaining arguments must be addresses of variables whose type is
determined by the format string.
Note that while :c:func:`PyArg_ParseTuple` checks that the Python arguments have
the required types, it cannot check the validity of the addresses of C variables
passed to the call: if you make mistakes there, your code will probably crash or
at least overwrite random bits in memory. So be careful!
Note that any Python object references which are provided to the caller are
*borrowed* references; do not decrement their reference count!
Some example calls::
int ok;
int i, j;
long k, l;
const char *s;
int size;
ok = PyArg_ParseTuple(args, ""); /* No arguments */
/* Python call: f() */
::
ok = PyArg_ParseTuple(args, "s", &s); /* A string */
/* Possible Python call: f('whoops!') */
::
ok = PyArg_ParseTuple(args, "lls", &k, &l, &s); /* Two longs and a string */
/* Possible Python call: f(1, 2, 'three') */
::
ok = PyArg_ParseTuple(args, "(ii)s#", &i, &j, &s, &size);
/* A pair of ints and a string, whose size is also returned */
/* Possible Python call: f((1, 2), 'three') */
::
{
const char *file;
const char *mode = "r";
int bufsize = 0;
ok = PyArg_ParseTuple(args, "s|si", &file, &mode, &bufsize);
/* A string, and optionally another string and an integer */
/* Possible Python calls:
f('spam')
f('spam', 'w')
f('spam', 'wb', 100000) */
}
::
{
int left, top, right, bottom, h, v;
ok = PyArg_ParseTuple(args, "((ii)(ii))(ii)",
&left, &top, &right, &bottom, &h, &v);
/* A rectangle and a point */
/* Possible Python call:
f(((0, 0), (400, 300)), (10, 10)) */
}
::
{
Py_complex c;
ok = PyArg_ParseTuple(args, "D:myfunction", &c);
/* a complex, also providing a function name for errors */
/* Possible Python call: myfunction(1+2j) */
}
.. _parsetupleandkeywords:
Keyword Parameters for Extension Functions
==========================================
.. index:: single: PyArg_ParseTupleAndKeywords()
The :c:func:`PyArg_ParseTupleAndKeywords` function is declared as follows::
int PyArg_ParseTupleAndKeywords(PyObject *arg, PyObject *kwdict,
char *format, char *kwlist[], ...);
The *arg* and *format* parameters are identical to those of the
:c:func:`PyArg_ParseTuple` function. The *kwdict* parameter is the dictionary of
keywords received as the third parameter from the Python runtime. The *kwlist*
parameter is a *NULL*-terminated list of strings which identify the parameters;
the names are matched with the type information from *format* from left to
right. On success, :c:func:`PyArg_ParseTupleAndKeywords` returns true, otherwise
it returns false and raises an appropriate exception.
.. note::
Nested tuples cannot be parsed when using keyword arguments! Keyword parameters
passed in which are not present in the *kwlist* will cause :exc:`TypeError` to
be raised.
.. index:: single: Philbrick, Geoff
Here is an example module which uses keywords, based on an example by Geoff
Philbrick (philbrick@hks.com)::
#include "Python.h"
static PyObject *
keywdarg_parrot(PyObject *self, PyObject *args, PyObject *keywds)
{
int voltage;
char *state = "a stiff";
char *action = "voom";
char *type = "Norwegian Blue";
static char *kwlist[] = {"voltage", "state", "action", "type", NULL};
if (!PyArg_ParseTupleAndKeywords(args, keywds, "i|sss", kwlist,
&voltage, &state, &action, &type))
return NULL;
printf("-- This parrot wouldn't %s if you put %i Volts through it.\n",
action, voltage);
printf("-- Lovely plumage, the %s -- It's %s!\n", type, state);
Py_INCREF(Py_None);
return Py_None;
}
static PyMethodDef keywdarg_methods[] = {
/* The cast of the function is necessary since PyCFunction values
* only take two PyObject* parameters, and keywdarg_parrot() takes
* three.
*/
{"parrot", (PyCFunction)keywdarg_parrot, METH_VARARGS | METH_KEYWORDS,
"Print a lovely skit to standard output."},
{NULL, NULL, 0, NULL} /* sentinel */
};
::
void
initkeywdarg(void)
{
/* Create the module and add the functions */
Py_InitModule("keywdarg", keywdarg_methods);
}
.. _buildvalue:
Building Arbitrary Values
=========================
This function is the counterpart to :c:func:`PyArg_ParseTuple`. It is declared
as follows::
PyObject *Py_BuildValue(char *format, ...);
It recognizes a set of format units similar to the ones recognized by
:c:func:`PyArg_ParseTuple`, but the arguments (which are input to the function,
not output) must not be pointers, just values. It returns a new Python object,
suitable for returning from a C function called from Python.
One difference with :c:func:`PyArg_ParseTuple`: while the latter requires its
first argument to be a tuple (since Python argument lists are always represented
as tuples internally), :c:func:`Py_BuildValue` does not always build a tuple. It
builds a tuple only if its format string contains two or more format units. If
the format string is empty, it returns ``None``; if it contains exactly one
format unit, it returns whatever object is described by that format unit. To
force it to return a tuple of size 0 or one, parenthesize the format string.
Examples (to the left the call, to the right the resulting Python value):
.. code-block:: none
Py_BuildValue("") None
Py_BuildValue("i", 123) 123
Py_BuildValue("iii", 123, 456, 789) (123, 456, 789)
Py_BuildValue("s", "hello") 'hello'
Py_BuildValue("ss", "hello", "world") ('hello', 'world')
Py_BuildValue("s#", "hello", 4) 'hell'
Py_BuildValue("()") ()
Py_BuildValue("(i)", 123) (123,)
Py_BuildValue("(ii)", 123, 456) (123, 456)
Py_BuildValue("(i,i)", 123, 456) (123, 456)
Py_BuildValue("[i,i]", 123, 456) [123, 456]
Py_BuildValue("{s:i,s:i}",
"abc", 123, "def", 456) {'abc': 123, 'def': 456}
Py_BuildValue("((ii)(ii)) (ii)",
1, 2, 3, 4, 5, 6) (((1, 2), (3, 4)), (5, 6))
.. _refcounts:
Reference Counts
================
In languages like C or C++, the programmer is responsible for dynamic allocation
and deallocation of memory on the heap. In C, this is done using the functions
:c:func:`malloc` and :c:func:`free`. In C++, the operators ``new`` and
``delete`` are used with essentially the same meaning and we'll restrict
the following discussion to the C case.
Every block of memory allocated with :c:func:`malloc` should eventually be
returned to the pool of available memory by exactly one call to :c:func:`free`.
It is important to call :c:func:`free` at the right time. If a block's address
is forgotten but :c:func:`free` is not called for it, the memory it occupies
cannot be reused until the program terminates. This is called a :dfn:`memory
leak`. On the other hand, if a program calls :c:func:`free` for a block and then
continues to use the block, it creates a conflict with re-use of the block
through another :c:func:`malloc` call. This is called :dfn:`using freed memory`.
It has the same bad consequences as referencing uninitialized data --- core
dumps, wrong results, mysterious crashes.
Common causes of memory leaks are unusual paths through the code. For instance,
a function may allocate a block of memory, do some calculation, and then free
the block again. Now a change in the requirements for the function may add a
test to the calculation that detects an error condition and can return
prematurely from the function. It's easy to forget to free the allocated memory
block when taking this premature exit, especially when it is added later to the
code. Such leaks, once introduced, often go undetected for a long time: the
error exit is taken only in a small fraction of all calls, and most modern
machines have plenty of virtual memory, so the leak only becomes apparent in a
long-running process that uses the leaking function frequently. Therefore, it's
important to prevent leaks from happening by having a coding convention or
strategy that minimizes this kind of errors.
Since Python makes heavy use of :c:func:`malloc` and :c:func:`free`, it needs a
strategy to avoid memory leaks as well as the use of freed memory. The chosen
method is called :dfn:`reference counting`. The principle is simple: every
object contains a counter, which is incremented when a reference to the object
is stored somewhere, and which is decremented when a reference to it is deleted.
When the counter reaches zero, the last reference to the object has been deleted
and the object is freed.
An alternative strategy is called :dfn:`automatic garbage collection`.
(Sometimes, reference counting is also referred to as a garbage collection
strategy, hence my use of "automatic" to distinguish the two.) The big
advantage of automatic garbage collection is that the user doesn't need to call
:c:func:`free` explicitly. (Another claimed advantage is an improvement in speed
or memory usage --- this is no hard fact however.) The disadvantage is that for
C, there is no truly portable automatic garbage collector, while reference
counting can be implemented portably (as long as the functions :c:func:`malloc`
and :c:func:`free` are available --- which the C Standard guarantees). Maybe some
day a sufficiently portable automatic garbage collector will be available for C.
Until then, we'll have to live with reference counts.
While Python uses the traditional reference counting implementation, it also
offers a cycle detector that works to detect reference cycles. This allows
applications to not worry about creating direct or indirect circular references;
these are the weakness of garbage collection implemented using only reference
counting. Reference cycles consist of objects which contain (possibly indirect)
references to themselves, so that each object in the cycle has a reference count
which is non-zero. Typical reference counting implementations are not able to
reclaim the memory belonging to any objects in a reference cycle, or referenced
from the objects in the cycle, even though there are no further references to
the cycle itself.
The cycle detector is able to detect garbage cycles and can reclaim them so long
as there are no finalizers implemented in Python (:meth:`__del__` methods).
When there are such finalizers, the detector exposes the cycles through the
:mod:`gc` module (specifically, the :attr:`~gc.garbage` variable in that module).
The :mod:`gc` module also exposes a way to run the detector (the
:func:`~gc.collect` function), as well as configuration
interfaces and the ability to disable the detector at runtime. The cycle
detector is considered an optional component; though it is included by default,
it can be disabled at build time using the :option:`!--without-cycle-gc` option
to the :program:`configure` script on Unix platforms (including Mac OS X) or by
removing the definition of ``WITH_CYCLE_GC`` in the :file:`pyconfig.h` header on
other platforms. If the cycle detector is disabled in this way, the :mod:`gc`
module will not be available.
.. _refcountsinpython:
Reference Counting in Python
----------------------------
There are two macros, ``Py_INCREF(x)`` and ``Py_DECREF(x)``, which handle the
incrementing and decrementing of the reference count. :c:func:`Py_DECREF` also
frees the object when the count reaches zero. For flexibility, it doesn't call
:c:func:`free` directly --- rather, it makes a call through a function pointer in
the object's :dfn:`type object`. For this purpose (and others), every object
also contains a pointer to its type object.
The big question now remains: when to use ``Py_INCREF(x)`` and ``Py_DECREF(x)``?
Let's first introduce some terms. Nobody "owns" an object; however, you can
:dfn:`own a reference` to an object. An object's reference count is now defined
as the number of owned references to it. The owner of a reference is
responsible for calling :c:func:`Py_DECREF` when the reference is no longer
needed. Ownership of a reference can be transferred. There are three ways to
dispose of an owned reference: pass it on, store it, or call :c:func:`Py_DECREF`.
Forgetting to dispose of an owned reference creates a memory leak.
It is also possible to :dfn:`borrow` [#]_ a reference to an object. The
borrower of a reference should not call :c:func:`Py_DECREF`. The borrower must
not hold on to the object longer than the owner from which it was borrowed.
Using a borrowed reference after the owner has disposed of it risks using freed
memory and should be avoided completely [#]_.
The advantage of borrowing over owning a reference is that you don't need to
take care of disposing of the reference on all possible paths through the code
--- in other words, with a borrowed reference you don't run the risk of leaking
when a premature exit is taken. The disadvantage of borrowing over owning is
that there are some subtle situations where in seemingly correct code a borrowed
reference can be used after the owner from which it was borrowed has in fact
disposed of it.
A borrowed reference can be changed into an owned reference by calling
:c:func:`Py_INCREF`. This does not affect the status of the owner from which the
reference was borrowed --- it creates a new owned reference, and gives full
owner responsibilities (the new owner must dispose of the reference properly, as
well as the previous owner).
.. _ownershiprules:
Ownership Rules
---------------
Whenever an object reference is passed into or out of a function, it is part of
the function's interface specification whether ownership is transferred with the
reference or not.
Most functions that return a reference to an object pass on ownership with the
reference. In particular, all functions whose function it is to create a new
object, such as :c:func:`PyInt_FromLong` and :c:func:`Py_BuildValue`, pass
ownership to the receiver. Even if the object is not actually new, you still
receive ownership of a new reference to that object. For instance,
:c:func:`PyInt_FromLong` maintains a cache of popular values and can return a
reference to a cached item.
Many functions that extract objects from other objects also transfer ownership
with the reference, for instance :c:func:`PyObject_GetAttrString`. The picture
is less clear, here, however, since a few common routines are exceptions:
:c:func:`PyTuple_GetItem`, :c:func:`PyList_GetItem`, :c:func:`PyDict_GetItem`, and
:c:func:`PyDict_GetItemString` all return references that you borrow from the
tuple, list or dictionary.
The function :c:func:`PyImport_AddModule` also returns a borrowed reference, even
though it may actually create the object it returns: this is possible because an
owned reference to the object is stored in ``sys.modules``.
When you pass an object reference into another function, in general, the
function borrows the reference from you --- if it needs to store it, it will use
:c:func:`Py_INCREF` to become an independent owner. There are exactly two
important exceptions to this rule: :c:func:`PyTuple_SetItem` and
:c:func:`PyList_SetItem`. These functions take over ownership of the item passed
to them --- even if they fail! (Note that :c:func:`PyDict_SetItem` and friends
don't take over ownership --- they are "normal.")
When a C function is called from Python, it borrows references to its arguments
from the caller. The caller owns a reference to the object, so the borrowed
reference's lifetime is guaranteed until the function returns. Only when such a
borrowed reference must be stored or passed on, it must be turned into an owned
reference by calling :c:func:`Py_INCREF`.
The object reference returned from a C function that is called from Python must
be an owned reference --- ownership is transferred from the function to its
caller.
.. _thinice:
Thin Ice
--------
There are a few situations where seemingly harmless use of a borrowed reference
can lead to problems. These all have to do with implicit invocations of the
interpreter, which can cause the owner of a reference to dispose of it.
The first and most important case to know about is using :c:func:`Py_DECREF` on
an unrelated object while borrowing a reference to a list item. For instance::
void
bug(PyObject *list)
{
PyObject *item = PyList_GetItem(list, 0);
PyList_SetItem(list, 1, PyInt_FromLong(0L));
PyObject_Print(item, stdout, 0); /* BUG! */
}
This function first borrows a reference to ``list[0]``, then replaces
``list[1]`` with the value ``0``, and finally prints the borrowed reference.
Looks harmless, right? But it's not!
Let's follow the control flow into :c:func:`PyList_SetItem`. The list owns
references to all its items, so when item 1 is replaced, it has to dispose of
the original item 1. Now let's suppose the original item 1 was an instance of a
user-defined class, and let's further suppose that the class defined a
:meth:`__del__` method. If this class instance has a reference count of 1,
disposing of it will call its :meth:`__del__` method.
Since it is written in Python, the :meth:`__del__` method can execute arbitrary
Python code. Could it perhaps do something to invalidate the reference to
``item`` in :c:func:`bug`? You bet! Assuming that the list passed into
:c:func:`bug` is accessible to the :meth:`__del__` method, it could execute a
statement to the effect of ``del list[0]``, and assuming this was the last
reference to that object, it would free the memory associated with it, thereby
invalidating ``item``.
The solution, once you know the source of the problem, is easy: temporarily
increment the reference count. The correct version of the function reads::
void
no_bug(PyObject *list)
{
PyObject *item = PyList_GetItem(list, 0);
Py_INCREF(item);
PyList_SetItem(list, 1, PyInt_FromLong(0L));
PyObject_Print(item, stdout, 0);
Py_DECREF(item);
}
This is a true story. An older version of Python contained variants of this bug
and someone spent a considerable amount of time in a C debugger to figure out
why his :meth:`__del__` methods would fail...
The second case of problems with a borrowed reference is a variant involving
threads. Normally, multiple threads in the Python interpreter can't get in each
other's way, because there is a global lock protecting Python's entire object
space. However, it is possible to temporarily release this lock using the macro
:c:macro:`Py_BEGIN_ALLOW_THREADS`, and to re-acquire it using
:c:macro:`Py_END_ALLOW_THREADS`. This is common around blocking I/O calls, to
let other threads use the processor while waiting for the I/O to complete.
Obviously, the following function has the same problem as the previous one::
void
bug(PyObject *list)
{
PyObject *item = PyList_GetItem(list, 0);
Py_BEGIN_ALLOW_THREADS
...some blocking I/O call...
Py_END_ALLOW_THREADS
PyObject_Print(item, stdout, 0); /* BUG! */
}
.. _nullpointers:
NULL Pointers
-------------
In general, functions that take object references as arguments do not expect you
to pass them *NULL* pointers, and will dump core (or cause later core dumps) if
you do so. Functions that return object references generally return *NULL* only
to indicate that an exception occurred. The reason for not testing for *NULL*
arguments is that functions often pass the objects they receive on to other
function --- if each function were to test for *NULL*, there would be a lot of
redundant tests and the code would run more slowly.
It is better to test for *NULL* only at the "source:" when a pointer that may be
*NULL* is received, for example, from :c:func:`malloc` or from a function that
may raise an exception.
The macros :c:func:`Py_INCREF` and :c:func:`Py_DECREF` do not check for *NULL*
pointers --- however, their variants :c:func:`Py_XINCREF` and :c:func:`Py_XDECREF`
do.
The macros for checking for a particular object type (``Pytype_Check()``) don't
check for *NULL* pointers --- again, there is much code that calls several of
these in a row to test an object against various different expected types, and
this would generate redundant tests. There are no variants with *NULL*
checking.
The C function calling mechanism guarantees that the argument list passed to C
functions (``args`` in the examples) is never *NULL* --- in fact it guarantees
that it is always a tuple [#]_.
It is a severe error to ever let a *NULL* pointer "escape" to the Python user.
.. Frank Stajano:
A pedagogically buggy example, along the lines of the previous listing, would
be helpful here -- showing in more concrete terms what sort of actions could
cause the problem. I can't very well imagine it from the description.
.. _cplusplus:
Writing Extensions in C++
=========================
It is possible to write extension modules in C++. Some restrictions apply. If
the main program (the Python interpreter) is compiled and linked by the C
compiler, global or static objects with constructors cannot be used. This is
not a problem if the main program is linked by the C++ compiler. Functions that
will be called by the Python interpreter (in particular, module initialization
functions) have to be declared using ``extern "C"``. It is unnecessary to
enclose the Python header files in ``extern "C" {...}`` --- they use this form
already if the symbol ``__cplusplus`` is defined (all recent C++ compilers
define this symbol).
.. _using-capsules:
Providing a C API for an Extension Module
=========================================
.. sectionauthor:: Konrad Hinsen <hinsen@cnrs-orleans.fr>
Many extension modules just provide new functions and types to be used from
Python, but sometimes the code in an extension module can be useful for other
extension modules. For example, an extension module could implement a type
"collection" which works like lists without order. Just like the standard Python
list type has a C API which permits extension modules to create and manipulate
lists, this new collection type should have a set of C functions for direct
manipulation from other extension modules.
At first sight this seems easy: just write the functions (without declaring them
``static``, of course), provide an appropriate header file, and document
the C API. And in fact this would work if all extension modules were always
linked statically with the Python interpreter. When modules are used as shared
libraries, however, the symbols defined in one module may not be visible to
another module. The details of visibility depend on the operating system; some
systems use one global namespace for the Python interpreter and all extension
modules (Windows, for example), whereas others require an explicit list of
imported symbols at module link time (AIX is one example), or offer a choice of
different strategies (most Unices). And even if symbols are globally visible,
the module whose functions one wishes to call might not have been loaded yet!
Portability therefore requires not to make any assumptions about symbol
visibility. This means that all symbols in extension modules should be declared
``static``, except for the module's initialization function, in order to
avoid name clashes with other extension modules (as discussed in section
:ref:`methodtable`). And it means that symbols that *should* be accessible from
other extension modules must be exported in a different way.
Python provides a special mechanism to pass C-level information (pointers) from
one extension module to another one: Capsules. A Capsule is a Python data type
which stores a pointer (:c:type:`void \*`). Capsules can only be created and
accessed via their C API, but they can be passed around like any other Python
object. In particular, they can be assigned to a name in an extension module's
namespace. Other extension modules can then import this module, retrieve the
value of this name, and then retrieve the pointer from the Capsule.
There are many ways in which Capsules can be used to export the C API of an
extension module. Each function could get its own Capsule, or all C API pointers
could be stored in an array whose address is published in a Capsule. And the
various tasks of storing and retrieving the pointers can be distributed in
different ways between the module providing the code and the client modules.
Whichever method you choose, it's important to name your Capsules properly.
The function :c:func:`PyCapsule_New` takes a name parameter
(:c:type:`const char \*`); you're permitted to pass in a *NULL* name, but
we strongly encourage you to specify a name. Properly named Capsules provide
a degree of runtime type-safety; there is no feasible way to tell one unnamed
Capsule from another.
In particular, Capsules used to expose C APIs should be given a name following
this convention::
modulename.attributename
The convenience function :c:func:`PyCapsule_Import` makes it easy to
load a C API provided via a Capsule, but only if the Capsule's name
matches this convention. This behavior gives C API users a high degree
of certainty that the Capsule they load contains the correct C API.
The following example demonstrates an approach that puts most of the burden on
the writer of the exporting module, which is appropriate for commonly used
library modules. It stores all C API pointers (just one in the example!) in an
array of :c:type:`void` pointers which becomes the value of a Capsule. The header
file corresponding to the module provides a macro that takes care of importing
the module and retrieving its C API pointers; client modules only have to call
this macro before accessing the C API.
The exporting module is a modification of the :mod:`spam` module from section
:ref:`extending-simpleexample`. The function :func:`spam.system` does not call
the C library function :c:func:`system` directly, but a function
:c:func:`PySpam_System`, which would of course do something more complicated in
reality (such as adding "spam" to every command). This function
:c:func:`PySpam_System` is also exported to other extension modules.
The function :c:func:`PySpam_System` is a plain C function, declared
``static`` like everything else::
static int
PySpam_System(const char *command)
{
return system(command);
}
The function :c:func:`spam_system` is modified in a trivial way::
static PyObject *
spam_system(PyObject *self, PyObject *args)
{
const char *command;
int sts;
if (!PyArg_ParseTuple(args, "s", &command))
return NULL;
sts = PySpam_System(command);
return Py_BuildValue("i", sts);
}
In the beginning of the module, right after the line ::
#include "Python.h"
two more lines must be added::
#define SPAM_MODULE
#include "spammodule.h"
The ``#define`` is used to tell the header file that it is being included in the
exporting module, not a client module. Finally, the module's initialization
function must take care of initializing the C API pointer array::
PyMODINIT_FUNC
initspam(void)
{
PyObject *m;
static void *PySpam_API[PySpam_API_pointers];
PyObject *c_api_object;
m = Py_InitModule("spam", SpamMethods);
if (m == NULL)
return;
/* Initialize the C API pointer array */
PySpam_API[PySpam_System_NUM] = (void *)PySpam_System;
/* Create a Capsule containing the API pointer array's address */
c_api_object = PyCapsule_New((void *)PySpam_API, "spam._C_API", NULL);
if (c_api_object != NULL)
PyModule_AddObject(m, "_C_API", c_api_object);
}
Note that ``PySpam_API`` is declared ``static``; otherwise the pointer
array would disappear when :func:`initspam` terminates!
The bulk of the work is in the header file :file:`spammodule.h`, which looks
like this::
#ifndef Py_SPAMMODULE_H
#define Py_SPAMMODULE_H
#ifdef __cplusplus
extern "C" {
#endif
/* Header file for spammodule */
/* C API functions */
#define PySpam_System_NUM 0
#define PySpam_System_RETURN int
#define PySpam_System_PROTO (const char *command)
/* Total number of C API pointers */
#define PySpam_API_pointers 1
#ifdef SPAM_MODULE
/* This section is used when compiling spammodule.c */
static PySpam_System_RETURN PySpam_System PySpam_System_PROTO;
#else
/* This section is used in modules that use spammodule's API */
static void **PySpam_API;
#define PySpam_System \
(*(PySpam_System_RETURN (*)PySpam_System_PROTO) PySpam_API[PySpam_System_NUM])
/* Return -1 on error, 0 on success.
* PyCapsule_Import will set an exception if there's an error.
*/
static int
import_spam(void)
{
PySpam_API = (void **)PyCapsule_Import("spam._C_API", 0);
return (PySpam_API != NULL) ? 0 : -1;
}
#endif
#ifdef __cplusplus
}
#endif
#endif /* !defined(Py_SPAMMODULE_H) */
All that a client module must do in order to have access to the function
:c:func:`PySpam_System` is to call the function (or rather macro)
:c:func:`import_spam` in its initialization function::
PyMODINIT_FUNC
initclient(void)
{
PyObject *m;
m = Py_InitModule("client", ClientMethods);
if (m == NULL)
return;
if (import_spam() < 0)
return;
/* additional initialization can happen here */
}
The main disadvantage of this approach is that the file :file:`spammodule.h` is
rather complicated. However, the basic structure is the same for each function
that is exported, so it has to be learned only once.
Finally it should be mentioned that Capsules offer additional functionality,
which is especially useful for memory allocation and deallocation of the pointer
stored in a Capsule. The details are described in the Python/C API Reference
Manual in the section :ref:`capsules` and in the implementation of Capsules (files
:file:`Include/pycapsule.h` and :file:`Objects/pycapsule.c` in the Python source
code distribution).
.. rubric:: Footnotes
.. [#] An interface for this function already exists in the standard module :mod:`os`
--- it was chosen as a simple and straightforward example.
.. [#] The metaphor of "borrowing" a reference is not completely correct: the owner
still has a copy of the reference.
.. [#] Checking that the reference count is at least 1 **does not work** --- the
reference count itself could be in freed memory and may thus be reused for
another object!
.. [#] These guarantees don't hold when you use the "old" style calling convention ---
this is still found in much existing code.
PK %�\�Cs4S S % html/_sources/extending/index.rst.txtnu �[��� .. _extending-index:
##################################################
Extending and Embedding the Python Interpreter
##################################################
This document describes how to write modules in C or C++ to extend the Python
interpreter with new modules. Those modules can not only define new functions
but also new object types and their methods. The document also describes how
to embed the Python interpreter in another application, for use as an extension
language. Finally, it shows how to compile and link extension modules so that
they can be loaded dynamically (at run time) into the interpreter, if the
underlying operating system supports this feature.
This document assumes basic knowledge about Python. For an informal
introduction to the language, see :ref:`tutorial-index`. :ref:`reference-index`
gives a more formal definition of the language. :ref:`library-index` documents
the existing object types, functions and modules (both built-in and written in
Python) that give the language its wide application range.
For a detailed description of the whole Python/C API, see the separate
:ref:`c-api-index`.
.. note::
This guide only covers the basic tools for creating extensions provided
as part of this version of CPython. Third party tools may offer simpler
alternatives. Refer to the `binary extensions section
<https://packaging.python.org/en/latest/extensions/>`__ in the Python
Packaging User Guide for more information.
.. toctree::
:maxdepth: 2
:numbered:
extending.rst
newtypes.rst
building.rst
windows.rst
embedding.rst
PK %�\XO���� �� ( html/_sources/extending/newtypes.rst.txtnu �[��� .. highlightlang:: c
.. _defining-new-types:
******************
Defining New Types
******************
.. sectionauthor:: Michael Hudson <mwh@python.net>
.. sectionauthor:: Dave Kuhlman <dkuhlman@rexx.com>
.. sectionauthor:: Jim Fulton <jim@zope.com>
As mentioned in the last chapter, Python allows the writer of an extension
module to define new types that can be manipulated from Python code, much like
strings and lists in core Python.
This is not hard; the code for all extension types follows a pattern, but there
are some details that you need to understand before you can get started.
.. note::
The way new types are defined changed dramatically (and for the better) in
Python 2.2. This document documents how to define new types for Python 2.2 and
later. If you need to support older versions of Python, you will need to refer
to `older versions of this documentation
<https://www.python.org/doc/versions/>`_.
.. _dnt-basics:
The Basics
==========
The Python runtime sees all Python objects as variables of type
:c:type:`PyObject\*`. A :c:type:`PyObject` is not a very magnificent object - it
just contains the refcount and a pointer to the object's "type object". This is
where the action is; the type object determines which (C) functions get called
when, for instance, an attribute gets looked up on an object or it is multiplied
by another object. These C functions are called "type methods".
So, if you want to define a new object type, you need to create a new type
object.
This sort of thing can only be explained by example, so here's a minimal, but
complete, module that defines a new type:
.. literalinclude:: ../includes/noddy.c
Now that's quite a bit to take in at once, but hopefully bits will seem familiar
from the last chapter.
The first bit that will be new is::
typedef struct {
PyObject_HEAD
} noddy_NoddyObject;
This is what a Noddy object will contain---in this case, nothing more than every
Python object contains, namely a refcount and a pointer to a type object. These
are the fields the ``PyObject_HEAD`` macro brings in. The reason for the macro
is to standardize the layout and to enable special debugging fields in debug
builds. Note that there is no semicolon after the ``PyObject_HEAD`` macro; one
is included in the macro definition. Be wary of adding one by accident; it's
easy to do from habit, and your compiler might not complain, but someone else's
probably will! (On Windows, MSVC is known to call this an error and refuse to
compile the code.)
For contrast, let's take a look at the corresponding definition for standard
Python integers::
typedef struct {
PyObject_HEAD
long ob_ival;
} PyIntObject;
Moving on, we come to the crunch --- the type object. ::
static PyTypeObject noddy_NoddyType = {
PyVarObject_HEAD_INIT(NULL, 0)
"noddy.Noddy", /* tp_name */
sizeof(noddy_NoddyObject), /* tp_basicsize */
0, /* tp_itemsize */
0, /* tp_dealloc */
0, /* tp_print */
0, /* tp_getattr */
0, /* tp_setattr */
0, /* tp_compare */
0, /* tp_repr */
0, /* tp_as_number */
0, /* tp_as_sequence */
0, /* tp_as_mapping */
0, /* tp_hash */
0, /* tp_call */
0, /* tp_str */
0, /* tp_getattro */
0, /* tp_setattro */
0, /* tp_as_buffer */
Py_TPFLAGS_DEFAULT, /* tp_flags */
"Noddy objects", /* tp_doc */
};
Now if you go and look up the definition of :c:type:`PyTypeObject` in
:file:`object.h` you'll see that it has many more fields that the definition
above. The remaining fields will be filled with zeros by the C compiler, and
it's common practice to not specify them explicitly unless you need them.
This is so important that we're going to pick the top of it apart still
further::
PyVarObject_HEAD_INIT(NULL, 0)
This line is a bit of a wart; what we'd like to write is::
PyVarObject_HEAD_INIT(&PyType_Type, 0)
as the type of a type object is "type", but this isn't strictly conforming C and
some compilers complain. Fortunately, this member will be filled in for us by
:c:func:`PyType_Ready`. ::
"noddy.Noddy", /* tp_name */
The name of our type. This will appear in the default textual representation of
our objects and in some error messages, for example::
>>> "" + noddy.new_noddy()
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: cannot add type "noddy.Noddy" to string
Note that the name is a dotted name that includes both the module name and the
name of the type within the module. The module in this case is :mod:`noddy` and
the type is :class:`Noddy`, so we set the type name to :class:`noddy.Noddy`.
One side effect of using an undotted name is that the pydoc documentation tool
will not list the new type in the module documentation. ::
sizeof(noddy_NoddyObject), /* tp_basicsize */
This is so that Python knows how much memory to allocate when you call
:c:func:`PyObject_New`.
.. note::
If you want your type to be subclassable from Python, and your type has the same
:c:member:`~PyTypeObject.tp_basicsize` as its base type, you may have problems with multiple
inheritance. A Python subclass of your type will have to list your type first
in its :attr:`~class.__bases__`, or else it will not be able to call your type's
:meth:`__new__` method without getting an error. You can avoid this problem by
ensuring that your type has a larger value for :c:member:`~PyTypeObject.tp_basicsize` than its
base type does. Most of the time, this will be true anyway, because either your
base type will be :class:`object`, or else you will be adding data members to
your base type, and therefore increasing its size.
::
0, /* tp_itemsize */
This has to do with variable length objects like lists and strings. Ignore this
for now.
Skipping a number of type methods that we don't provide, we set the class flags
to :const:`Py_TPFLAGS_DEFAULT`. ::
Py_TPFLAGS_DEFAULT, /* tp_flags */
All types should include this constant in their flags. It enables all of the
members defined by the current version of Python.
We provide a doc string for the type in :c:member:`~PyTypeObject.tp_doc`. ::
"Noddy objects", /* tp_doc */
Now we get into the type methods, the things that make your objects different
from the others. We aren't going to implement any of these in this version of
the module. We'll expand this example later to have more interesting behavior.
For now, all we want to be able to do is to create new :class:`Noddy` objects.
To enable object creation, we have to provide a :c:member:`~PyTypeObject.tp_new` implementation.
In this case, we can just use the default implementation provided by the API
function :c:func:`PyType_GenericNew`. We'd like to just assign this to the
:c:member:`~PyTypeObject.tp_new` slot, but we can't, for portability sake, On some platforms or
compilers, we can't statically initialize a structure member with a function
defined in another C module, so, instead, we'll assign the :c:member:`~PyTypeObject.tp_new` slot
in the module initialization function just before calling
:c:func:`PyType_Ready`::
noddy_NoddyType.tp_new = PyType_GenericNew;
if (PyType_Ready(&noddy_NoddyType) < 0)
return;
All the other type methods are *NULL*, so we'll go over them later --- that's
for a later section!
Everything else in the file should be familiar, except for some code in
:c:func:`initnoddy`::
if (PyType_Ready(&noddy_NoddyType) < 0)
return;
This initializes the :class:`Noddy` type, filing in a number of members,
including :attr:`ob_type` that we initially set to *NULL*. ::
PyModule_AddObject(m, "Noddy", (PyObject *)&noddy_NoddyType);
This adds the type to the module dictionary. This allows us to create
:class:`Noddy` instances by calling the :class:`Noddy` class::
>>> import noddy
>>> mynoddy = noddy.Noddy()
That's it! All that remains is to build it; put the above code in a file called
:file:`noddy.c` and ::
from distutils.core import setup, Extension
setup(name="noddy", version="1.0",
ext_modules=[Extension("noddy", ["noddy.c"])])
in a file called :file:`setup.py`; then typing
.. code-block:: shell-session
$ python setup.py build
at a shell should produce a file :file:`noddy.so` in a subdirectory; move to
that directory and fire up Python --- you should be able to ``import noddy`` and
play around with Noddy objects.
That wasn't so hard, was it?
Of course, the current Noddy type is pretty uninteresting. It has no data and
doesn't do anything. It can't even be subclassed.
Adding data and methods to the Basic example
--------------------------------------------
Let's extend the basic example to add some data and methods. Let's also make
the type usable as a base class. We'll create a new module, :mod:`noddy2` that
adds these capabilities:
.. literalinclude:: ../includes/noddy2.c
This version of the module has a number of changes.
We've added an extra include::
#include <structmember.h>
This include provides declarations that we use to handle attributes, as
described a bit later.
The name of the :class:`Noddy` object structure has been shortened to
:class:`Noddy`. The type object name has been shortened to :class:`NoddyType`.
The :class:`Noddy` type now has three data attributes, *first*, *last*, and
*number*. The *first* and *last* variables are Python strings containing first
and last names. The *number* attribute is an integer.
The object structure is updated accordingly::
typedef struct {
PyObject_HEAD
PyObject *first;
PyObject *last;
int number;
} Noddy;
Because we now have data to manage, we have to be more careful about object
allocation and deallocation. At a minimum, we need a deallocation method::
static void
Noddy_dealloc(Noddy* self)
{
Py_XDECREF(self->first);
Py_XDECREF(self->last);
Py_TYPE(self)->tp_free((PyObject*)self);
}
which is assigned to the :c:member:`~PyTypeObject.tp_dealloc` member::
(destructor)Noddy_dealloc, /*tp_dealloc*/
This method decrements the reference counts of the two Python attributes. We use
:c:func:`Py_XDECREF` here because the :attr:`first` and :attr:`last` members
could be *NULL*. It then calls the :c:member:`~PyTypeObject.tp_free` member of the object's type
to free the object's memory. Note that the object's type might not be
:class:`NoddyType`, because the object may be an instance of a subclass.
We want to make sure that the first and last names are initialized to empty
strings, so we provide a new method::
static PyObject *
Noddy_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
{
Noddy *self;
self = (Noddy *)type->tp_alloc(type, 0);
if (self != NULL) {
self->first = PyString_FromString("");
if (self->first == NULL)
{
Py_DECREF(self);
return NULL;
}
self->last = PyString_FromString("");
if (self->last == NULL)
{
Py_DECREF(self);
return NULL;
}
self->number = 0;
}
return (PyObject *)self;
}
and install it in the :c:member:`~PyTypeObject.tp_new` member::
Noddy_new, /* tp_new */
The new member is responsible for creating (as opposed to initializing) objects
of the type. It is exposed in Python as the :meth:`__new__` method. See the
paper titled "Unifying types and classes in Python" for a detailed discussion of
the :meth:`__new__` method. One reason to implement a new method is to assure
the initial values of instance variables. In this case, we use the new method
to make sure that the initial values of the members :attr:`first` and
:attr:`last` are not *NULL*. If we didn't care whether the initial values were
*NULL*, we could have used :c:func:`PyType_GenericNew` as our new method, as we
did before. :c:func:`PyType_GenericNew` initializes all of the instance variable
members to *NULL*.
The new method is a static method that is passed the type being instantiated and
any arguments passed when the type was called, and that returns the new object
created. New methods always accept positional and keyword arguments, but they
often ignore the arguments, leaving the argument handling to initializer
methods. Note that if the type supports subclassing, the type passed may not be
the type being defined. The new method calls the tp_alloc slot to allocate
memory. We don't fill the :c:member:`~PyTypeObject.tp_alloc` slot ourselves. Rather
:c:func:`PyType_Ready` fills it for us by inheriting it from our base class,
which is :class:`object` by default. Most types use the default allocation.
.. note::
If you are creating a co-operative :c:member:`~PyTypeObject.tp_new` (one that calls a base type's
:c:member:`~PyTypeObject.tp_new` or :meth:`__new__`), you must *not* try to determine what method
to call using method resolution order at runtime. Always statically determine
what type you are going to call, and call its :c:member:`~PyTypeObject.tp_new` directly, or via
``type->tp_base->tp_new``. If you do not do this, Python subclasses of your
type that also inherit from other Python-defined classes may not work correctly.
(Specifically, you may not be able to create instances of such subclasses
without getting a :exc:`TypeError`.)
We provide an initialization function::
static int
Noddy_init(Noddy *self, PyObject *args, PyObject *kwds)
{
PyObject *first=NULL, *last=NULL, *tmp;
static char *kwlist[] = {"first", "last", "number", NULL};
if (! PyArg_ParseTupleAndKeywords(args, kwds, "|OOi", kwlist,
&first, &last,
&self->number))
return -1;
if (first) {
tmp = self->first;
Py_INCREF(first);
self->first = first;
Py_XDECREF(tmp);
}
if (last) {
tmp = self->last;
Py_INCREF(last);
self->last = last;
Py_XDECREF(tmp);
}
return 0;
}
by filling the :c:member:`~PyTypeObject.tp_init` slot. ::
(initproc)Noddy_init, /* tp_init */
The :c:member:`~PyTypeObject.tp_init` slot is exposed in Python as the :meth:`__init__` method. It
is used to initialize an object after it's created. Unlike the new method, we
can't guarantee that the initializer is called. The initializer isn't called
when unpickling objects and it can be overridden. Our initializer accepts
arguments to provide initial values for our instance. Initializers always accept
positional and keyword arguments.
Initializers can be called multiple times. Anyone can call the :meth:`__init__`
method on our objects. For this reason, we have to be extra careful when
assigning the new values. We might be tempted, for example to assign the
:attr:`first` member like this::
if (first) {
Py_XDECREF(self->first);
Py_INCREF(first);
self->first = first;
}
But this would be risky. Our type doesn't restrict the type of the
:attr:`first` member, so it could be any kind of object. It could have a
destructor that causes code to be executed that tries to access the
:attr:`first` member. To be paranoid and protect ourselves against this
possibility, we almost always reassign members before decrementing their
reference counts. When don't we have to do this?
* when we absolutely know that the reference count is greater than 1
* when we know that deallocation of the object [#]_ will not cause any calls
back into our type's code
* when decrementing a reference count in a :c:member:`~PyTypeObject.tp_dealloc` handler when
garbage-collections is not supported [#]_
We want to expose our instance variables as attributes. There are a
number of ways to do that. The simplest way is to define member definitions::
static PyMemberDef Noddy_members[] = {
{"first", T_OBJECT_EX, offsetof(Noddy, first), 0,
"first name"},
{"last", T_OBJECT_EX, offsetof(Noddy, last), 0,
"last name"},
{"number", T_INT, offsetof(Noddy, number), 0,
"noddy number"},
{NULL} /* Sentinel */
};
and put the definitions in the :c:member:`~PyTypeObject.tp_members` slot::
Noddy_members, /* tp_members */
Each member definition has a member name, type, offset, access flags and
documentation string. See the :ref:`Generic-Attribute-Management` section below for
details.
A disadvantage of this approach is that it doesn't provide a way to restrict the
types of objects that can be assigned to the Python attributes. We expect the
first and last names to be strings, but any Python objects can be assigned.
Further, the attributes can be deleted, setting the C pointers to *NULL*. Even
though we can make sure the members are initialized to non-*NULL* values, the
members can be set to *NULL* if the attributes are deleted.
We define a single method, :meth:`name`, that outputs the objects name as the
concatenation of the first and last names. ::
static PyObject *
Noddy_name(Noddy* self)
{
static PyObject *format = NULL;
PyObject *args, *result;
if (format == NULL) {
format = PyString_FromString("%s %s");
if (format == NULL)
return NULL;
}
if (self->first == NULL) {
PyErr_SetString(PyExc_AttributeError, "first");
return NULL;
}
if (self->last == NULL) {
PyErr_SetString(PyExc_AttributeError, "last");
return NULL;
}
args = Py_BuildValue("OO", self->first, self->last);
if (args == NULL)
return NULL;
result = PyString_Format(format, args);
Py_DECREF(args);
return result;
}
The method is implemented as a C function that takes a :class:`Noddy` (or
:class:`Noddy` subclass) instance as the first argument. Methods always take an
instance as the first argument. Methods often take positional and keyword
arguments as well, but in this case we don't take any and don't need to accept
a positional argument tuple or keyword argument dictionary. This method is
equivalent to the Python method::
def name(self):
return "%s %s" % (self.first, self.last)
Note that we have to check for the possibility that our :attr:`first` and
:attr:`last` members are *NULL*. This is because they can be deleted, in which
case they are set to *NULL*. It would be better to prevent deletion of these
attributes and to restrict the attribute values to be strings. We'll see how to
do that in the next section.
Now that we've defined the method, we need to create an array of method
definitions::
static PyMethodDef Noddy_methods[] = {
{"name", (PyCFunction)Noddy_name, METH_NOARGS,
"Return the name, combining the first and last name"
},
{NULL} /* Sentinel */
};
and assign them to the :c:member:`~PyTypeObject.tp_methods` slot::
Noddy_methods, /* tp_methods */
Note that we used the :const:`METH_NOARGS` flag to indicate that the method is
passed no arguments.
Finally, we'll make our type usable as a base class. We've written our methods
carefully so far so that they don't make any assumptions about the type of the
object being created or used, so all we need to do is to add the
:const:`Py_TPFLAGS_BASETYPE` to our class flag definition::
Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /*tp_flags*/
We rename :c:func:`initnoddy` to :c:func:`initnoddy2` and update the module name
passed to :c:func:`Py_InitModule3`.
Finally, we update our :file:`setup.py` file to build the new module::
from distutils.core import setup, Extension
setup(name="noddy", version="1.0",
ext_modules=[
Extension("noddy", ["noddy.c"]),
Extension("noddy2", ["noddy2.c"]),
])
Providing finer control over data attributes
--------------------------------------------
In this section, we'll provide finer control over how the :attr:`first` and
:attr:`last` attributes are set in the :class:`Noddy` example. In the previous
version of our module, the instance variables :attr:`first` and :attr:`last`
could be set to non-string values or even deleted. We want to make sure that
these attributes always contain strings.
.. literalinclude:: ../includes/noddy3.c
To provide greater control, over the :attr:`first` and :attr:`last` attributes,
we'll use custom getter and setter functions. Here are the functions for
getting and setting the :attr:`first` attribute::
Noddy_getfirst(Noddy *self, void *closure)
{
Py_INCREF(self->first);
return self->first;
}
static int
Noddy_setfirst(Noddy *self, PyObject *value, void *closure)
{
if (value == NULL) {
PyErr_SetString(PyExc_TypeError, "Cannot delete the first attribute");
return -1;
}
if (! PyString_Check(value)) {
PyErr_SetString(PyExc_TypeError,
"The first attribute value must be a string");
return -1;
}
Py_DECREF(self->first);
Py_INCREF(value);
self->first = value;
return 0;
}
The getter function is passed a :class:`Noddy` object and a "closure", which is
void pointer. In this case, the closure is ignored. (The closure supports an
advanced usage in which definition data is passed to the getter and setter. This
could, for example, be used to allow a single set of getter and setter functions
that decide the attribute to get or set based on data in the closure.)
The setter function is passed the :class:`Noddy` object, the new value, and the
closure. The new value may be *NULL*, in which case the attribute is being
deleted. In our setter, we raise an error if the attribute is deleted or if the
attribute value is not a string.
We create an array of :c:type:`PyGetSetDef` structures::
static PyGetSetDef Noddy_getseters[] = {
{"first",
(getter)Noddy_getfirst, (setter)Noddy_setfirst,
"first name",
NULL},
{"last",
(getter)Noddy_getlast, (setter)Noddy_setlast,
"last name",
NULL},
{NULL} /* Sentinel */
};
and register it in the :c:member:`~PyTypeObject.tp_getset` slot::
Noddy_getseters, /* tp_getset */
to register our attribute getters and setters.
The last item in a :c:type:`PyGetSetDef` structure is the closure mentioned
above. In this case, we aren't using the closure, so we just pass *NULL*.
We also remove the member definitions for these attributes::
static PyMemberDef Noddy_members[] = {
{"number", T_INT, offsetof(Noddy, number), 0,
"noddy number"},
{NULL} /* Sentinel */
};
We also need to update the :c:member:`~PyTypeObject.tp_init` handler to only allow strings [#]_ to
be passed::
static int
Noddy_init(Noddy *self, PyObject *args, PyObject *kwds)
{
PyObject *first=NULL, *last=NULL, *tmp;
static char *kwlist[] = {"first", "last", "number", NULL};
if (! PyArg_ParseTupleAndKeywords(args, kwds, "|SSi", kwlist,
&first, &last,
&self->number))
return -1;
if (first) {
tmp = self->first;
Py_INCREF(first);
self->first = first;
Py_DECREF(tmp);
}
if (last) {
tmp = self->last;
Py_INCREF(last);
self->last = last;
Py_DECREF(tmp);
}
return 0;
}
With these changes, we can assure that the :attr:`first` and :attr:`last`
members are never *NULL* so we can remove checks for *NULL* values in almost all
cases. This means that most of the :c:func:`Py_XDECREF` calls can be converted to
:c:func:`Py_DECREF` calls. The only place we can't change these calls is in the
deallocator, where there is the possibility that the initialization of these
members failed in the constructor.
We also rename the module initialization function and module name in the
initialization function, as we did before, and we add an extra definition to the
:file:`setup.py` file.
Supporting cyclic garbage collection
------------------------------------
Python has a cyclic-garbage collector that can identify unneeded objects even
when their reference counts are not zero. This can happen when objects are
involved in cycles. For example, consider::
>>> l = []
>>> l.append(l)
>>> del l
In this example, we create a list that contains itself. When we delete it, it
still has a reference from itself. Its reference count doesn't drop to zero.
Fortunately, Python's cyclic-garbage collector will eventually figure out that
the list is garbage and free it.
In the second version of the :class:`Noddy` example, we allowed any kind of
object to be stored in the :attr:`first` or :attr:`last` attributes [#]_. This
means that :class:`Noddy` objects can participate in cycles::
>>> import noddy2
>>> n = noddy2.Noddy()
>>> l = [n]
>>> n.first = l
This is pretty silly, but it gives us an excuse to add support for the
cyclic-garbage collector to the :class:`Noddy` example. To support cyclic
garbage collection, types need to fill two slots and set a class flag that
enables these slots:
.. literalinclude:: ../includes/noddy4.c
The traversal method provides access to subobjects that could participate in
cycles::
static int
Noddy_traverse(Noddy *self, visitproc visit, void *arg)
{
int vret;
if (self->first) {
vret = visit(self->first, arg);
if (vret != 0)
return vret;
}
if (self->last) {
vret = visit(self->last, arg);
if (vret != 0)
return vret;
}
return 0;
}
For each subobject that can participate in cycles, we need to call the
:c:func:`visit` function, which is passed to the traversal method. The
:c:func:`visit` function takes as arguments the subobject and the extra argument
*arg* passed to the traversal method. It returns an integer value that must be
returned if it is non-zero.
Python 2.4 and higher provide a :c:func:`Py_VISIT` macro that automates calling
visit functions. With :c:func:`Py_VISIT`, :c:func:`Noddy_traverse` can be
simplified::
static int
Noddy_traverse(Noddy *self, visitproc visit, void *arg)
{
Py_VISIT(self->first);
Py_VISIT(self->last);
return 0;
}
.. note::
Note that the :c:member:`~PyTypeObject.tp_traverse` implementation must name its arguments exactly
*visit* and *arg* in order to use :c:func:`Py_VISIT`. This is to encourage
uniformity across these boring implementations.
We also need to provide a method for clearing any subobjects that can
participate in cycles.
::
static int
Noddy_clear(Noddy *self)
{
PyObject *tmp;
tmp = self->first;
self->first = NULL;
Py_XDECREF(tmp);
tmp = self->last;
self->last = NULL;
Py_XDECREF(tmp);
return 0;
}
Notice the use of a temporary variable in :c:func:`Noddy_clear`. We use the
temporary variable so that we can set each member to *NULL* before decrementing
its reference count. We do this because, as was discussed earlier, if the
reference count drops to zero, we might cause code to run that calls back into
the object. In addition, because we now support garbage collection, we also
have to worry about code being run that triggers garbage collection. If garbage
collection is run, our :c:member:`~PyTypeObject.tp_traverse` handler could get called. We can't
take a chance of having :c:func:`Noddy_traverse` called when a member's reference
count has dropped to zero and its value hasn't been set to *NULL*.
Python 2.4 and higher provide a :c:func:`Py_CLEAR` that automates the careful
decrementing of reference counts. With :c:func:`Py_CLEAR`, the
:c:func:`Noddy_clear` function can be simplified::
static int
Noddy_clear(Noddy *self)
{
Py_CLEAR(self->first);
Py_CLEAR(self->last);
return 0;
}
Note that :c:func:`Noddy_dealloc` may call arbitrary functions through
``__del__`` method or weakref callback. It means circular GC can be
triggered inside the function. Since GC assumes reference count is not zero,
we need to untrack the object from GC by calling :c:func:`PyObject_GC_UnTrack`
before clearing members. Here is reimplemented deallocator which uses
:c:func:`PyObject_GC_UnTrack` and :c:func:`Noddy_clear`.
::
static void
Noddy_dealloc(Noddy* self)
{
PyObject_GC_UnTrack(self);
Noddy_clear(self);
Py_TYPE(self)->tp_free((PyObject*)self);
}
Finally, we add the :const:`Py_TPFLAGS_HAVE_GC` flag to the class flags::
Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, /* tp_flags */
That's pretty much it. If we had written custom :c:member:`~PyTypeObject.tp_alloc` or
:c:member:`~PyTypeObject.tp_free` slots, we'd need to modify them for cyclic-garbage collection.
Most extensions will use the versions automatically provided.
Subclassing other types
-----------------------
It is possible to create new extension types that are derived from existing
types. It is easiest to inherit from the built in types, since an extension can
easily use the :class:`PyTypeObject` it needs. It can be difficult to share
these :class:`PyTypeObject` structures between extension modules.
In this example we will create a :class:`Shoddy` type that inherits from the
built-in :class:`list` type. The new type will be completely compatible with
regular lists, but will have an additional :meth:`increment` method that
increases an internal counter. ::
>>> import shoddy
>>> s = shoddy.Shoddy(range(3))
>>> s.extend(s)
>>> print len(s)
6
>>> print s.increment()
1
>>> print s.increment()
2
.. literalinclude:: ../includes/shoddy.c
As you can see, the source code closely resembles the :class:`Noddy` examples in
previous sections. We will break down the main differences between them. ::
typedef struct {
PyListObject list;
int state;
} Shoddy;
The primary difference for derived type objects is that the base type's object
structure must be the first value. The base type will already include the
:c:func:`PyObject_HEAD` at the beginning of its structure.
When a Python object is a :class:`Shoddy` instance, its *PyObject\** pointer can
be safely cast to both *PyListObject\** and *Shoddy\**. ::
static int
Shoddy_init(Shoddy *self, PyObject *args, PyObject *kwds)
{
if (PyList_Type.tp_init((PyObject *)self, args, kwds) < 0)
return -1;
self->state = 0;
return 0;
}
In the :attr:`__init__` method for our type, we can see how to call through to
the :attr:`__init__` method of the base type.
This pattern is important when writing a type with custom :attr:`new` and
:attr:`dealloc` methods. The :attr:`new` method should not actually create the
memory for the object with :c:member:`~PyTypeObject.tp_alloc`, that will be handled by the base
class when calling its :c:member:`~PyTypeObject.tp_new`.
When filling out the :c:func:`PyTypeObject` for the :class:`Shoddy` type, you see
a slot for :c:func:`tp_base`. Due to cross platform compiler issues, you can't
fill that field directly with the :c:func:`PyList_Type`; it can be done later in
the module's :c:func:`init` function. ::
PyMODINIT_FUNC
initshoddy(void)
{
PyObject *m;
ShoddyType.tp_base = &PyList_Type;
if (PyType_Ready(&ShoddyType) < 0)
return;
m = Py_InitModule3("shoddy", NULL, "Shoddy module");
if (m == NULL)
return;
Py_INCREF(&ShoddyType);
PyModule_AddObject(m, "Shoddy", (PyObject *) &ShoddyType);
}
Before calling :c:func:`PyType_Ready`, the type structure must have the
:c:member:`~PyTypeObject.tp_base` slot filled in. When we are deriving a new type, it is not
necessary to fill out the :c:member:`~PyTypeObject.tp_alloc` slot with :c:func:`PyType_GenericNew`
-- the allocate function from the base type will be inherited.
After that, calling :c:func:`PyType_Ready` and adding the type object to the
module is the same as with the basic :class:`Noddy` examples.
.. _dnt-type-methods:
Type Methods
============
This section aims to give a quick fly-by on the various type methods you can
implement and what they do.
Here is the definition of :c:type:`PyTypeObject`, with some fields only used in
debug builds omitted:
.. literalinclude:: ../includes/typestruct.h
Now that's a *lot* of methods. Don't worry too much though - if you have a type
you want to define, the chances are very good that you will only implement a
handful of these.
As you probably expect by now, we're going to go over this and give more
information about the various handlers. We won't go in the order they are
defined in the structure, because there is a lot of historical baggage that
impacts the ordering of the fields; be sure your type initialization keeps the
fields in the right order! It's often easiest to find an example that includes
all the fields you need (even if they're initialized to ``0``) and then change
the values to suit your new type. ::
char *tp_name; /* For printing */
The name of the type - as mentioned in the last section, this will appear in
various places, almost entirely for diagnostic purposes. Try to choose something
that will be helpful in such a situation! ::
int tp_basicsize, tp_itemsize; /* For allocation */
These fields tell the runtime how much memory to allocate when new objects of
this type are created. Python has some built-in support for variable length
structures (think: strings, lists) which is where the :c:member:`~PyTypeObject.tp_itemsize` field
comes in. This will be dealt with later. ::
char *tp_doc;
Here you can put a string (or its address) that you want returned when the
Python script references ``obj.__doc__`` to retrieve the doc string.
Now we come to the basic type methods---the ones most extension types will
implement.
Finalization and De-allocation
------------------------------
.. index::
single: object; deallocation
single: deallocation, object
single: object; finalization
single: finalization, of objects
::
destructor tp_dealloc;
This function is called when the reference count of the instance of your type is
reduced to zero and the Python interpreter wants to reclaim it. If your type
has memory to free or other clean-up to perform, you can put it here. The
object itself needs to be freed here as well. Here is an example of this
function::
static void
newdatatype_dealloc(newdatatypeobject * obj)
{
free(obj->obj_UnderlyingDatatypePtr);
Py_TYPE(obj)->tp_free(obj);
}
.. index::
single: PyErr_Fetch()
single: PyErr_Restore()
One important requirement of the deallocator function is that it leaves any
pending exceptions alone. This is important since deallocators are frequently
called as the interpreter unwinds the Python stack; when the stack is unwound
due to an exception (rather than normal returns), nothing is done to protect the
deallocators from seeing that an exception has already been set. Any actions
which a deallocator performs which may cause additional Python code to be
executed may detect that an exception has been set. This can lead to misleading
errors from the interpreter. The proper way to protect against this is to save
a pending exception before performing the unsafe action, and restoring it when
done. This can be done using the :c:func:`PyErr_Fetch` and
:c:func:`PyErr_Restore` functions::
static void
my_dealloc(PyObject *obj)
{
MyObject *self = (MyObject *) obj;
PyObject *cbresult;
if (self->my_callback != NULL) {
PyObject *err_type, *err_value, *err_traceback;
int have_error = PyErr_Occurred() ? 1 : 0;
if (have_error)
PyErr_Fetch(&err_type, &err_value, &err_traceback);
cbresult = PyObject_CallObject(self->my_callback, NULL);
if (cbresult == NULL)
PyErr_WriteUnraisable(self->my_callback);
else
Py_DECREF(cbresult);
if (have_error)
PyErr_Restore(err_type, err_value, err_traceback);
Py_DECREF(self->my_callback);
}
Py_TYPE(obj)->tp_free((PyObject*)self);
}
Object Presentation
-------------------
.. index::
builtin: repr
builtin: str
In Python, there are three ways to generate a textual representation of an
object: the :func:`repr` function (or equivalent back-tick syntax), the
:func:`str` function, and the :keyword:`print` statement. For most objects, the
:keyword:`print` statement is equivalent to the :func:`str` function, but it is
possible to special-case printing to a :c:type:`FILE\*` if necessary; this should
only be done if efficiency is identified as a problem and profiling suggests
that creating a temporary string object to be written to a file is too
expensive.
These handlers are all optional, and most types at most need to implement the
:c:member:`~PyTypeObject.tp_str` and :c:member:`~PyTypeObject.tp_repr` handlers. ::
reprfunc tp_repr;
reprfunc tp_str;
printfunc tp_print;
The :c:member:`~PyTypeObject.tp_repr` handler should return a string object containing a
representation of the instance for which it is called. Here is a simple
example::
static PyObject *
newdatatype_repr(newdatatypeobject * obj)
{
return PyString_FromFormat("Repr-ified_newdatatype{{size:\%d}}",
obj->obj_UnderlyingDatatypePtr->size);
}
If no :c:member:`~PyTypeObject.tp_repr` handler is specified, the interpreter will supply a
representation that uses the type's :c:member:`~PyTypeObject.tp_name` and a uniquely-identifying
value for the object.
The :c:member:`~PyTypeObject.tp_str` handler is to :func:`str` what the :c:member:`~PyTypeObject.tp_repr` handler
described above is to :func:`repr`; that is, it is called when Python code calls
:func:`str` on an instance of your object. Its implementation is very similar
to the :c:member:`~PyTypeObject.tp_repr` function, but the resulting string is intended for human
consumption. If :c:member:`~PyTypeObject.tp_str` is not specified, the :c:member:`~PyTypeObject.tp_repr` handler is
used instead.
Here is a simple example::
static PyObject *
newdatatype_str(newdatatypeobject * obj)
{
return PyString_FromFormat("Stringified_newdatatype{{size:\%d}}",
obj->obj_UnderlyingDatatypePtr->size);
}
The print function will be called whenever Python needs to "print" an instance
of the type. For example, if 'node' is an instance of type TreeNode, then the
print function is called when Python code calls::
print node
There is a flags argument and one flag, :const:`Py_PRINT_RAW`, and it suggests
that you print without string quotes and possibly without interpreting escape
sequences.
The print function receives a file object as an argument. You will likely want
to write to that file object.
Here is a sample print function::
static int
newdatatype_print(newdatatypeobject *obj, FILE *fp, int flags)
{
if (flags & Py_PRINT_RAW) {
fprintf(fp, "<{newdatatype object--size: %d}>",
obj->obj_UnderlyingDatatypePtr->size);
}
else {
fprintf(fp, "\"<{newdatatype object--size: %d}>\"",
obj->obj_UnderlyingDatatypePtr->size);
}
return 0;
}
Attribute Management
--------------------
For every object which can support attributes, the corresponding type must
provide the functions that control how the attributes are resolved. There needs
to be a function which can retrieve attributes (if any are defined), and another
to set attributes (if setting attributes is allowed). Removing an attribute is
a special case, for which the new value passed to the handler is *NULL*.
Python supports two pairs of attribute handlers; a type that supports attributes
only needs to implement the functions for one pair. The difference is that one
pair takes the name of the attribute as a :c:type:`char\*`, while the other
accepts a :c:type:`PyObject\*`. Each type can use whichever pair makes more
sense for the implementation's convenience. ::
getattrfunc tp_getattr; /* char * version */
setattrfunc tp_setattr;
/* ... */
getattrofunc tp_getattrofunc; /* PyObject * version */
setattrofunc tp_setattrofunc;
If accessing attributes of an object is always a simple operation (this will be
explained shortly), there are generic implementations which can be used to
provide the :c:type:`PyObject\*` version of the attribute management functions.
The actual need for type-specific attribute handlers almost completely
disappeared starting with Python 2.2, though there are many examples which have
not been updated to use some of the new generic mechanism that is available.
.. _generic-attribute-management:
Generic Attribute Management
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. versionadded:: 2.2
Most extension types only use *simple* attributes. So, what makes the
attributes simple? There are only a couple of conditions that must be met:
#. The name of the attributes must be known when :c:func:`PyType_Ready` is
called.
#. No special processing is needed to record that an attribute was looked up or
set, nor do actions need to be taken based on the value.
Note that this list does not place any restrictions on the values of the
attributes, when the values are computed, or how relevant data is stored.
When :c:func:`PyType_Ready` is called, it uses three tables referenced by the
type object to create :term:`descriptor`\s which are placed in the dictionary of the
type object. Each descriptor controls access to one attribute of the instance
object. Each of the tables is optional; if all three are *NULL*, instances of
the type will only have attributes that are inherited from their base type, and
should leave the :c:member:`~PyTypeObject.tp_getattro` and :c:member:`~PyTypeObject.tp_setattro` fields *NULL* as
well, allowing the base type to handle attributes.
The tables are declared as three fields of the type object::
struct PyMethodDef *tp_methods;
struct PyMemberDef *tp_members;
struct PyGetSetDef *tp_getset;
If :c:member:`~PyTypeObject.tp_methods` is not *NULL*, it must refer to an array of
:c:type:`PyMethodDef` structures. Each entry in the table is an instance of this
structure::
typedef struct PyMethodDef {
const char *ml_name; /* method name */
PyCFunction ml_meth; /* implementation function */
int ml_flags; /* flags */
const char *ml_doc; /* docstring */
} PyMethodDef;
One entry should be defined for each method provided by the type; no entries are
needed for methods inherited from a base type. One additional entry is needed
at the end; it is a sentinel that marks the end of the array. The
:attr:`ml_name` field of the sentinel must be *NULL*.
XXX Need to refer to some unified discussion of the structure fields, shared
with the next section.
The second table is used to define attributes which map directly to data stored
in the instance. A variety of primitive C types are supported, and access may
be read-only or read-write. The structures in the table are defined as::
typedef struct PyMemberDef {
char *name;
int type;
int offset;
int flags;
char *doc;
} PyMemberDef;
For each entry in the table, a :term:`descriptor` will be constructed and added to the
type which will be able to extract a value from the instance structure. The
:attr:`type` field should contain one of the type codes defined in the
:file:`structmember.h` header; the value will be used to determine how to
convert Python values to and from C values. The :attr:`flags` field is used to
store flags which control how the attribute can be accessed.
XXX Need to move some of this to a shared section!
The following flag constants are defined in :file:`structmember.h`; they may be
combined using bitwise-OR.
+---------------------------+----------------------------------------------+
| Constant | Meaning |
+===========================+==============================================+
| :const:`READONLY` | Never writable. |
+---------------------------+----------------------------------------------+
| :const:`RO` | Shorthand for :const:`READONLY`. |
+---------------------------+----------------------------------------------+
| :const:`READ_RESTRICTED` | Not readable in restricted mode. |
+---------------------------+----------------------------------------------+
| :const:`WRITE_RESTRICTED` | Not writable in restricted mode. |
+---------------------------+----------------------------------------------+
| :const:`RESTRICTED` | Not readable or writable in restricted mode. |
+---------------------------+----------------------------------------------+
.. index::
single: READONLY
single: RO
single: READ_RESTRICTED
single: WRITE_RESTRICTED
single: RESTRICTED
An interesting advantage of using the :c:member:`~PyTypeObject.tp_members` table to build
descriptors that are used at runtime is that any attribute defined this way can
have an associated doc string simply by providing the text in the table. An
application can use the introspection API to retrieve the descriptor from the
class object, and get the doc string using its :attr:`__doc__` attribute.
As with the :c:member:`~PyTypeObject.tp_methods` table, a sentinel entry with a :attr:`name` value
of *NULL* is required.
.. XXX Descriptors need to be explained in more detail somewhere, but not here.
Descriptor objects have two handler functions which correspond to the
\member{tp_getattro} and \member{tp_setattro} handlers. The
\method{__get__()} handler is a function which is passed the descriptor,
instance, and type objects, and returns the value of the attribute, or it
returns \NULL{} and sets an exception. The \method{__set__()} handler is
passed the descriptor, instance, type, and new value;
Type-specific Attribute Management
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
For simplicity, only the :c:type:`char\*` version will be demonstrated here; the
type of the name parameter is the only difference between the :c:type:`char\*`
and :c:type:`PyObject\*` flavors of the interface. This example effectively does
the same thing as the generic example above, but does not use the generic
support added in Python 2.2. The value in showing this is two-fold: it
demonstrates how basic attribute management can be done in a way that is
portable to older versions of Python, and explains how the handler functions are
called, so that if you do need to extend their functionality, you'll understand
what needs to be done.
The :c:member:`~PyTypeObject.tp_getattr` handler is called when the object requires an attribute
look-up. It is called in the same situations where the :meth:`__getattr__`
method of a class would be called.
A likely way to handle this is (1) to implement a set of functions (such as
:c:func:`newdatatype_getSize` and :c:func:`newdatatype_setSize` in the example
below), (2) provide a method table listing these functions, and (3) provide a
getattr function that returns the result of a lookup in that table. The method
table uses the same structure as the :c:member:`~PyTypeObject.tp_methods` field of the type
object.
Here is an example::
static PyMethodDef newdatatype_methods[] = {
{"getSize", (PyCFunction)newdatatype_getSize, METH_VARARGS,
"Return the current size."},
{"setSize", (PyCFunction)newdatatype_setSize, METH_VARARGS,
"Set the size."},
{NULL, NULL, 0, NULL} /* sentinel */
};
static PyObject *
newdatatype_getattr(newdatatypeobject *obj, char *name)
{
return Py_FindMethod(newdatatype_methods, (PyObject *)obj, name);
}
The :c:member:`~PyTypeObject.tp_setattr` handler is called when the :meth:`__setattr__` or
:meth:`__delattr__` method of a class instance would be called. When an
attribute should be deleted, the third parameter will be *NULL*. Here is an
example that simply raises an exception; if this were really all you wanted, the
:c:member:`~PyTypeObject.tp_setattr` handler should be set to *NULL*. ::
static int
newdatatype_setattr(newdatatypeobject *obj, char *name, PyObject *v)
{
(void)PyErr_Format(PyExc_RuntimeError, "Read-only attribute: \%s", name);
return -1;
}
Object Comparison
-----------------
::
cmpfunc tp_compare;
The :c:member:`~PyTypeObject.tp_compare` handler is called when comparisons are needed and the
object does not implement the specific rich comparison method which matches the
requested comparison. (It is always used if defined and the
:c:func:`PyObject_Compare` or :c:func:`PyObject_Cmp` functions are used, or if
:func:`cmp` is used from Python.) It is analogous to the :meth:`__cmp__` method.
This function should return ``-1`` if *obj1* is less than *obj2*, ``0`` if they
are equal, and ``1`` if *obj1* is greater than *obj2*. (It was previously
allowed to return arbitrary negative or positive integers for less than and
greater than, respectively; as of Python 2.2, this is no longer allowed. In the
future, other return values may be assigned a different meaning.)
A :c:member:`~PyTypeObject.tp_compare` handler may raise an exception. In this case it should
return a negative value. The caller has to test for the exception using
:c:func:`PyErr_Occurred`.
Here is a sample implementation::
static int
newdatatype_compare(newdatatypeobject * obj1, newdatatypeobject * obj2)
{
long result;
if (obj1->obj_UnderlyingDatatypePtr->size <
obj2->obj_UnderlyingDatatypePtr->size) {
result = -1;
}
else if (obj1->obj_UnderlyingDatatypePtr->size >
obj2->obj_UnderlyingDatatypePtr->size) {
result = 1;
}
else {
result = 0;
}
return result;
}
Abstract Protocol Support
-------------------------
Python supports a variety of *abstract* 'protocols;' the specific interfaces
provided to use these interfaces are documented in :ref:`abstract`.
A number of these abstract interfaces were defined early in the development of
the Python implementation. In particular, the number, mapping, and sequence
protocols have been part of Python since the beginning. Other protocols have
been added over time. For protocols which depend on several handler routines
from the type implementation, the older protocols have been defined as optional
blocks of handlers referenced by the type object. For newer protocols there are
additional slots in the main type object, with a flag bit being set to indicate
that the slots are present and should be checked by the interpreter. (The flag
bit does not indicate that the slot values are non-*NULL*. The flag may be set
to indicate the presence of a slot, but a slot may still be unfilled.) ::
PyNumberMethods *tp_as_number;
PySequenceMethods *tp_as_sequence;
PyMappingMethods *tp_as_mapping;
If you wish your object to be able to act like a number, a sequence, or a
mapping object, then you place the address of a structure that implements the C
type :c:type:`PyNumberMethods`, :c:type:`PySequenceMethods`, or
:c:type:`PyMappingMethods`, respectively. It is up to you to fill in this
structure with appropriate values. You can find examples of the use of each of
these in the :file:`Objects` directory of the Python source distribution. ::
hashfunc tp_hash;
This function, if you choose to provide it, should return a hash number for an
instance of your data type. Here is a moderately pointless example::
static long
newdatatype_hash(newdatatypeobject *obj)
{
long result;
result = obj->obj_UnderlyingDatatypePtr->size;
result = result * 3;
return result;
}
::
ternaryfunc tp_call;
This function is called when an instance of your data type is "called", for
example, if ``obj1`` is an instance of your data type and the Python script
contains ``obj1('hello')``, the :c:member:`~PyTypeObject.tp_call` handler is invoked.
This function takes three arguments:
#. *arg1* is the instance of the data type which is the subject of the call. If
the call is ``obj1('hello')``, then *arg1* is ``obj1``.
#. *arg2* is a tuple containing the arguments to the call. You can use
:c:func:`PyArg_ParseTuple` to extract the arguments.
#. *arg3* is a dictionary of keyword arguments that were passed. If this is
non-*NULL* and you support keyword arguments, use
:c:func:`PyArg_ParseTupleAndKeywords` to extract the arguments. If you do not
want to support keyword arguments and this is non-*NULL*, raise a
:exc:`TypeError` with a message saying that keyword arguments are not supported.
Here is a desultory example of the implementation of the call function. ::
/* Implement the call function.
* obj1 is the instance receiving the call.
* obj2 is a tuple containing the arguments to the call, in this
* case 3 strings.
*/
static PyObject *
newdatatype_call(newdatatypeobject *obj, PyObject *args, PyObject *other)
{
PyObject *result;
char *arg1;
char *arg2;
char *arg3;
if (!PyArg_ParseTuple(args, "sss:call", &arg1, &arg2, &arg3)) {
return NULL;
}
result = PyString_FromFormat(
"Returning -- value: [\%d] arg1: [\%s] arg2: [\%s] arg3: [\%s]\n",
obj->obj_UnderlyingDatatypePtr->size,
arg1, arg2, arg3);
printf("\%s", PyString_AS_STRING(result));
return result;
}
XXX some fields need to be added here... ::
/* Added in release 2.2 */
/* Iterators */
getiterfunc tp_iter;
iternextfunc tp_iternext;
These functions provide support for the iterator protocol. Any object which
wishes to support iteration over its contents (which may be generated during
iteration) must implement the ``tp_iter`` handler. Objects which are returned
by a ``tp_iter`` handler must implement both the ``tp_iter`` and ``tp_iternext``
handlers. Both handlers take exactly one parameter, the instance for which they
are being called, and return a new reference. In the case of an error, they
should set an exception and return *NULL*.
For an object which represents an iterable collection, the ``tp_iter`` handler
must return an iterator object. The iterator object is responsible for
maintaining the state of the iteration. For collections which can support
multiple iterators which do not interfere with each other (as lists and tuples
do), a new iterator should be created and returned. Objects which can only be
iterated over once (usually due to side effects of iteration) should implement
this handler by returning a new reference to themselves, and should also
implement the ``tp_iternext`` handler. File objects are an example of such an
iterator.
Iterator objects should implement both handlers. The ``tp_iter`` handler should
return a new reference to the iterator (this is the same as the ``tp_iter``
handler for objects which can only be iterated over destructively). The
``tp_iternext`` handler should return a new reference to the next object in the
iteration if there is one. If the iteration has reached the end, it may return
*NULL* without setting an exception or it may set :exc:`StopIteration`; avoiding
the exception can yield slightly better performance. If an actual error occurs,
it should set an exception and return *NULL*.
.. _weakref-support:
Weak Reference Support
----------------------
One of the goals of Python's weak-reference implementation is to allow any type
to participate in the weak reference mechanism without incurring the overhead on
those objects which do not benefit by weak referencing (such as numbers).
For an object to be weakly referencable, the extension must include a
:c:type:`PyObject\*` field in the instance structure for the use of the weak
reference mechanism; it must be initialized to *NULL* by the object's
constructor. It must also set the :c:member:`~PyTypeObject.tp_weaklistoffset` field of the
corresponding type object to the offset of the field. For example, the instance
type is defined with the following structure::
typedef struct {
PyObject_HEAD
PyClassObject *in_class; /* The class object */
PyObject *in_dict; /* A dictionary */
PyObject *in_weakreflist; /* List of weak references */
} PyInstanceObject;
The statically-declared type object for instances is defined this way::
PyTypeObject PyInstance_Type = {
PyObject_HEAD_INIT(&PyType_Type)
0,
"module.instance",
/* Lots of stuff omitted for brevity... */
Py_TPFLAGS_DEFAULT, /* tp_flags */
0, /* tp_doc */
0, /* tp_traverse */
0, /* tp_clear */
0, /* tp_richcompare */
offsetof(PyInstanceObject, in_weakreflist), /* tp_weaklistoffset */
};
The type constructor is responsible for initializing the weak reference list to
*NULL*::
static PyObject *
instance_new() {
/* Other initialization stuff omitted for brevity */
self->in_weakreflist = NULL;
return (PyObject *) self;
}
The only further addition is that the destructor needs to call the weak
reference manager to clear any weak references. This is only required if the
weak reference list is non-*NULL*::
static void
instance_dealloc(PyInstanceObject *inst)
{
/* Allocate temporaries if needed, but do not begin
destruction just yet.
*/
if (inst->in_weakreflist != NULL)
PyObject_ClearWeakRefs((PyObject *) inst);
/* Proceed with object destruction normally. */
}
More Suggestions
----------------
Remember that you can omit most of these functions, in which case you provide
``0`` as a value. There are type definitions for each of the functions you must
provide. They are in :file:`object.h` in the Python include directory that
comes with the source distribution of Python.
In order to learn how to implement any specific method for your new data type,
do the following: Download and unpack the Python source distribution. Go the
:file:`Objects` directory, then search the C source files for ``tp_`` plus the
function you want (for example, ``tp_print`` or ``tp_compare``). You will find
examples of the function you want to implement.
When you need to verify that an object is an instance of the type you are
implementing, use the :c:func:`PyObject_TypeCheck` function. A sample of its use
might be something like the following::
if (! PyObject_TypeCheck(some_object, &MyType)) {
PyErr_SetString(PyExc_TypeError, "arg #1 not a mything");
return NULL;
}
.. rubric:: Footnotes
.. [#] This is true when we know that the object is a basic type, like a string or a
float.
.. [#] We relied on this in the :c:member:`~PyTypeObject.tp_dealloc` handler in this example, because our
type doesn't support garbage collection. Even if a type supports garbage
collection, there are calls that can be made to "untrack" the object from
garbage collection, however, these calls are advanced and not covered here.
.. [#] We now know that the first and last members are strings, so perhaps we could be
less careful about decrementing their reference counts, however, we accept
instances of string subclasses. Even though deallocating normal strings won't
call back into our objects, we can't guarantee that deallocating an instance of
a string subclass won't call back into our objects.
.. [#] Even in the third version, we aren't guaranteed to avoid cycles. Instances of
string subclasses are allowed and string subclasses could allow cycles even if
normal strings don't.
PK %�\:n � ' html/_sources/extending/windows.rst.txtnu �[��� .. highlightlang:: c
.. _building-on-windows:
****************************************
Building C and C++ Extensions on Windows
****************************************
This chapter briefly explains how to create a Windows extension module for
Python using Microsoft Visual C++, and follows with more detailed background
information on how it works. The explanatory material is useful for both the
Windows programmer learning to build Python extensions and the Unix programmer
interested in producing software which can be successfully built on both Unix
and Windows.
Module authors are encouraged to use the distutils approach for building
extension modules, instead of the one described in this section. You will still
need the C compiler that was used to build Python; typically Microsoft Visual
C++.
.. note::
This chapter mentions a number of filenames that include an encoded Python
version number. These filenames are represented with the version number shown
as ``XY``; in practice, ``'X'`` will be the major version number and ``'Y'``
will be the minor version number of the Python release you're working with. For
example, if you are using Python 2.2.1, ``XY`` will actually be ``22``.
.. _win-cookbook:
A Cookbook Approach
===================
There are two approaches to building extension modules on Windows, just as there
are on Unix: use the :mod:`distutils` package to control the build process, or
do things manually. The distutils approach works well for most extensions;
documentation on using :mod:`distutils` to build and package extension modules
is available in :ref:`distutils-index`. If you find you really need to do
things manually, it may be instructive to study the project file for the
:source:`winsound <PCbuild/winsound.vcxproj>` standard library module.
.. _dynamic-linking:
Differences Between Unix and Windows
====================================
.. sectionauthor:: Chris Phoenix <cphoenix@best.com>
Unix and Windows use completely different paradigms for run-time loading of
code. Before you try to build a module that can be dynamically loaded, be aware
of how your system works.
In Unix, a shared object (:file:`.so`) file contains code to be used by the
program, and also the names of functions and data that it expects to find in the
program. When the file is joined to the program, all references to those
functions and data in the file's code are changed to point to the actual
locations in the program where the functions and data are placed in memory.
This is basically a link operation.
In Windows, a dynamic-link library (:file:`.dll`) file has no dangling
references. Instead, an access to functions or data goes through a lookup
table. So the DLL code does not have to be fixed up at runtime to refer to the
program's memory; instead, the code already uses the DLL's lookup table, and the
lookup table is modified at runtime to point to the functions and data.
In Unix, there is only one type of library file (:file:`.a`) which contains code
from several object files (:file:`.o`). During the link step to create a shared
object file (:file:`.so`), the linker may find that it doesn't know where an
identifier is defined. The linker will look for it in the object files in the
libraries; if it finds it, it will include all the code from that object file.
In Windows, there are two types of library, a static library and an import
library (both called :file:`.lib`). A static library is like a Unix :file:`.a`
file; it contains code to be included as necessary. An import library is
basically used only to reassure the linker that a certain identifier is legal,
and will be present in the program when the DLL is loaded. So the linker uses
the information from the import library to build the lookup table for using
identifiers that are not included in the DLL. When an application or a DLL is
linked, an import library may be generated, which will need to be used for all
future DLLs that depend on the symbols in the application or DLL.
Suppose you are building two dynamic-load modules, B and C, which should share
another block of code A. On Unix, you would *not* pass :file:`A.a` to the
linker for :file:`B.so` and :file:`C.so`; that would cause it to be included
twice, so that B and C would each have their own copy. In Windows, building
:file:`A.dll` will also build :file:`A.lib`. You *do* pass :file:`A.lib` to the
linker for B and C. :file:`A.lib` does not contain code; it just contains
information which will be used at runtime to access A's code.
In Windows, using an import library is sort of like using ``import spam``; it
gives you access to spam's names, but does not create a separate copy. On Unix,
linking with a library is more like ``from spam import *``; it does create a
separate copy.
.. _win-dlls:
Using DLLs in Practice
======================
.. sectionauthor:: Chris Phoenix <cphoenix@best.com>
Windows Python is built in Microsoft Visual C++; using other compilers may or
may not work (though Borland seems to). The rest of this section is MSVC++
specific.
When creating DLLs in Windows, you must pass :file:`pythonXY.lib` to the linker.
To build two DLLs, spam and ni (which uses C functions found in spam), you could
use these commands::
cl /LD /I/python/include spam.c ../libs/pythonXY.lib
cl /LD /I/python/include ni.c spam.lib ../libs/pythonXY.lib
The first command created three files: :file:`spam.obj`, :file:`spam.dll` and
:file:`spam.lib`. :file:`Spam.dll` does not contain any Python functions (such
as :c:func:`PyArg_ParseTuple`), but it does know how to find the Python code
thanks to :file:`pythonXY.lib`.
The second command created :file:`ni.dll` (and :file:`.obj` and :file:`.lib`),
which knows how to find the necessary functions from spam, and also from the
Python executable.
Not every identifier is exported to the lookup table. If you want any other
modules (including Python) to be able to see your identifiers, you have to say
``_declspec(dllexport)``, as in ``void _declspec(dllexport) initspam(void)`` or
``PyObject _declspec(dllexport) *NiGetSpamData(void)``.
Developer Studio will throw in a lot of import libraries that you do not really
need, adding about 100K to your executable. To get rid of them, use the Project
Settings dialog, Link tab, to specify *ignore default libraries*. Add the
correct :file:`msvcrtxx.lib` to the list of libraries.
PK %�\P�9s� � html/_sources/faq/design.rst.txtnu �[��� ======================
Design and History FAQ
======================
.. only:: html
.. contents::
Why does Python use indentation for grouping of statements?
-----------------------------------------------------------
Guido van Rossum believes that using indentation for grouping is extremely
elegant and contributes a lot to the clarity of the average Python program.
Most people learn to love this feature after a while.
Since there are no begin/end brackets there cannot be a disagreement between
grouping perceived by the parser and the human reader. Occasionally C
programmers will encounter a fragment of code like this::
if (x <= y)
x++;
y--;
z++;
Only the ``x++`` statement is executed if the condition is true, but the
indentation leads you to believe otherwise. Even experienced C programmers will
sometimes stare at it a long time wondering why ``y`` is being decremented even
for ``x > y``.
Because there are no begin/end brackets, Python is much less prone to
coding-style conflicts. In C there are many different ways to place the braces.
If you're used to reading and writing code that uses one style, you will feel at
least slightly uneasy when reading (or being required to write) another style.
Many coding styles place begin/end brackets on a line by themselves. This makes
programs considerably longer and wastes valuable screen space, making it harder
to get a good overview of a program. Ideally, a function should fit on one
screen (say, 20--30 lines). 20 lines of Python can do a lot more work than 20
lines of C. This is not solely due to the lack of begin/end brackets -- the
lack of declarations and the high-level data types are also responsible -- but
the indentation-based syntax certainly helps.
Why am I getting strange results with simple arithmetic operations?
-------------------------------------------------------------------
See the next question.
Why are floating point calculations so inaccurate?
--------------------------------------------------
People are often very surprised by results like this::
>>> 1.2 - 1.0
0.19999999999999996
and think it is a bug in Python. It's not. This has nothing to do with Python,
but with how the underlying C platform handles floating point numbers, and
ultimately with the inaccuracies introduced when writing down numbers as a
string of a fixed number of digits.
The internal representation of floating point numbers uses a fixed number of
binary digits to represent a decimal number. Some decimal numbers can't be
represented exactly in binary, resulting in small roundoff errors.
In decimal math, there are many numbers that can't be represented with a fixed
number of decimal digits, e.g. 1/3 = 0.3333333333.......
In base 2, 1/2 = 0.1, 1/4 = 0.01, 1/8 = 0.001, etc. .2 equals 2/10 equals 1/5,
resulting in the binary fractional number 0.001100110011001...
Floating point numbers only have 32 or 64 bits of precision, so the digits are
cut off at some point, and the resulting number is 0.199999999999999996 in
decimal, not 0.2.
A floating point number's ``repr()`` function prints as many digits are
necessary to make ``eval(repr(f)) == f`` true for any float f. The ``str()``
function prints fewer digits and this often results in the more sensible number
that was probably intended::
>>> 1.1 - 0.9
0.20000000000000007
>>> print 1.1 - 0.9
0.2
One of the consequences of this is that it is error-prone to compare the result
of some computation to a float with ``==``. Tiny inaccuracies may mean that
``==`` fails. Instead, you have to check that the difference between the two
numbers is less than a certain threshold::
epsilon = 0.0000000000001 # Tiny allowed error
expected_result = 0.4
if expected_result-epsilon <= computation() <= expected_result+epsilon:
...
Please see the chapter on :ref:`floating point arithmetic <tut-fp-issues>` in
the Python tutorial for more information.
Why are Python strings immutable?
---------------------------------
There are several advantages.
One is performance: knowing that a string is immutable means we can allocate
space for it at creation time, and the storage requirements are fixed and
unchanging. This is also one of the reasons for the distinction between tuples
and lists.
Another advantage is that strings in Python are considered as "elemental" as
numbers. No amount of activity will change the value 8 to anything else, and in
Python, no amount of activity will change the string "eight" to anything else.
.. _why-self:
Why must 'self' be used explicitly in method definitions and calls?
-------------------------------------------------------------------
The idea was borrowed from Modula-3. It turns out to be very useful, for a
variety of reasons.
First, it's more obvious that you are using a method or instance attribute
instead of a local variable. Reading ``self.x`` or ``self.meth()`` makes it
absolutely clear that an instance variable or method is used even if you don't
know the class definition by heart. In C++, you can sort of tell by the lack of
a local variable declaration (assuming globals are rare or easily recognizable)
-- but in Python, there are no local variable declarations, so you'd have to
look up the class definition to be sure. Some C++ and Java coding standards
call for instance attributes to have an ``m_`` prefix, so this explicitness is
still useful in those languages, too.
Second, it means that no special syntax is necessary if you want to explicitly
reference or call the method from a particular class. In C++, if you want to
use a method from a base class which is overridden in a derived class, you have
to use the ``::`` operator -- in Python you can write
``baseclass.methodname(self, <argument list>)``. This is particularly useful
for :meth:`__init__` methods, and in general in cases where a derived class
method wants to extend the base class method of the same name and thus has to
call the base class method somehow.
Finally, for instance variables it solves a syntactic problem with assignment:
since local variables in Python are (by definition!) those variables to which a
value is assigned in a function body (and that aren't explicitly declared
global), there has to be some way to tell the interpreter that an assignment was
meant to assign to an instance variable instead of to a local variable, and it
should preferably be syntactic (for efficiency reasons). C++ does this through
declarations, but Python doesn't have declarations and it would be a pity having
to introduce them just for this purpose. Using the explicit ``self.var`` solves
this nicely. Similarly, for using instance variables, having to write
``self.var`` means that references to unqualified names inside a method don't
have to search the instance's directories. To put it another way, local
variables and instance variables live in two different namespaces, and you need
to tell Python which namespace to use.
Why can't I use an assignment in an expression?
-----------------------------------------------
Many people used to C or Perl complain that they want to use this C idiom:
.. code-block:: c
while (line = readline(f)) {
// do something with line
}
where in Python you're forced to write this::
while True:
line = f.readline()
if not line:
break
... # do something with line
The reason for not allowing assignment in Python expressions is a common,
hard-to-find bug in those other languages, caused by this construct:
.. code-block:: c
if (x = 0) {
// error handling
}
else {
// code that only works for nonzero x
}
The error is a simple typo: ``x = 0``, which assigns 0 to the variable ``x``,
was written while the comparison ``x == 0`` is certainly what was intended.
Many alternatives have been proposed. Most are hacks that save some typing but
use arbitrary or cryptic syntax or keywords, and fail the simple criterion for
language change proposals: it should intuitively suggest the proper meaning to a
human reader who has not yet been introduced to the construct.
An interesting phenomenon is that most experienced Python programmers recognize
the ``while True`` idiom and don't seem to be missing the assignment in
expression construct much; it's only newcomers who express a strong desire to
add this to the language.
There's an alternative way of spelling this that seems attractive but is
generally less robust than the "while True" solution::
line = f.readline()
while line:
... # do something with line...
line = f.readline()
The problem with this is that if you change your mind about exactly how you get
the next line (e.g. you want to change it into ``sys.stdin.readline()``) you
have to remember to change two places in your program -- the second occurrence
is hidden at the bottom of the loop.
The best approach is to use iterators, making it possible to loop through
objects using the ``for`` statement. For example, in the current version of
Python file objects support the iterator protocol, so you can now write simply::
for line in f:
... # do something with line...
Why does Python use methods for some functionality (e.g. list.index()) but functions for other (e.g. len(list))?
----------------------------------------------------------------------------------------------------------------
As Guido said:
(a) For some operations, prefix notation just reads better than
postfix -- prefix (and infix!) operations have a long tradition in
mathematics which likes notations where the visuals help the
mathematician thinking about a problem. Compare the easy with which we
rewrite a formula like x*(a+b) into x*a + x*b to the clumsiness of
doing the same thing using a raw OO notation.
(b) When I read code that says len(x) I *know* that it is asking for
the length of something. This tells me two things: the result is an
integer, and the argument is some kind of container. To the contrary,
when I read x.len(), I have to already know that x is some kind of
container implementing an interface or inheriting from a class that
has a standard len(). Witness the confusion we occasionally have when
a class that is not implementing a mapping has a get() or keys()
method, or something that isn't a file has a write() method.
-- https://mail.python.org/pipermail/python-3000/2006-November/004643.html
Why is join() a string method instead of a list or tuple method?
----------------------------------------------------------------
Strings became much more like other standard types starting in Python 1.6, when
methods were added which give the same functionality that has always been
available using the functions of the string module. Most of these new methods
have been widely accepted, but the one which appears to make some programmers
feel uncomfortable is::
", ".join(['1', '2', '4', '8', '16'])
which gives the result::
"1, 2, 4, 8, 16"
There are two common arguments against this usage.
The first runs along the lines of: "It looks really ugly using a method of a
string literal (string constant)", to which the answer is that it might, but a
string literal is just a fixed value. If the methods are to be allowed on names
bound to strings there is no logical reason to make them unavailable on
literals.
The second objection is typically cast as: "I am really telling a sequence to
join its members together with a string constant". Sadly, you aren't. For some
reason there seems to be much less difficulty with having :meth:`~str.split` as
a string method, since in that case it is easy to see that ::
"1, 2, 4, 8, 16".split(", ")
is an instruction to a string literal to return the substrings delimited by the
given separator (or, by default, arbitrary runs of white space). In this case a
Unicode string returns a list of Unicode strings, an ASCII string returns a list
of ASCII strings, and everyone is happy.
:meth:`~str.join` is a string method because in using it you are telling the
separator string to iterate over a sequence of strings and insert itself between
adjacent elements. This method can be used with any argument which obeys the
rules for sequence objects, including any new classes you might define yourself.
Because this is a string method it can work for Unicode strings as well as plain
ASCII strings. If ``join()`` were a method of the sequence types then the
sequence types would have to decide which type of string to return depending on
the type of the separator.
.. XXX remove next paragraph eventually
If none of these arguments persuade you, then for the moment you can continue to
use the ``join()`` function from the string module, which allows you to write ::
string.join(['1', '2', '4', '8', '16'], ", ")
How fast are exceptions?
------------------------
A try/except block is extremely efficient if no exceptions are raised. Actually
catching an exception is expensive. In versions of Python prior to 2.0 it was
common to use this idiom::
try:
value = mydict[key]
except KeyError:
mydict[key] = getvalue(key)
value = mydict[key]
This only made sense when you expected the dict to have the key almost all the
time. If that wasn't the case, you coded it like this::
if key in mydict:
value = mydict[key]
else:
value = mydict[key] = getvalue(key)
.. note::
In Python 2.0 and higher, you can code this as ``value =
mydict.setdefault(key, getvalue(key))``.
Why isn't there a switch or case statement in Python?
-----------------------------------------------------
You can do this easily enough with a sequence of ``if... elif... elif... else``.
There have been some proposals for switch statement syntax, but there is no
consensus (yet) on whether and how to do range tests. See :pep:`275` for
complete details and the current status.
For cases where you need to choose from a very large number of possibilities,
you can create a dictionary mapping case values to functions to call. For
example::
def function_1(...):
...
functions = {'a': function_1,
'b': function_2,
'c': self.method_1, ...}
func = functions[value]
func()
For calling methods on objects, you can simplify yet further by using the
:func:`getattr` built-in to retrieve methods with a particular name::
def visit_a(self, ...):
...
...
def dispatch(self, value):
method_name = 'visit_' + str(value)
method = getattr(self, method_name)
method()
It's suggested that you use a prefix for the method names, such as ``visit_`` in
this example. Without such a prefix, if values are coming from an untrusted
source, an attacker would be able to call any method on your object.
Can't you emulate threads in the interpreter instead of relying on an OS-specific thread implementation?
--------------------------------------------------------------------------------------------------------
Answer 1: Unfortunately, the interpreter pushes at least one C stack frame for
each Python stack frame. Also, extensions can call back into Python at almost
random moments. Therefore, a complete threads implementation requires thread
support for C.
Answer 2: Fortunately, there is `Stackless Python <http://www.stackless.com>`_,
which has a completely redesigned interpreter loop that avoids the C stack.
Why can't lambda expressions contain statements?
------------------------------------------------
Python lambda expressions cannot contain statements because Python's syntactic
framework can't handle statements nested inside expressions. However, in
Python, this is not a serious problem. Unlike lambda forms in other languages,
where they add functionality, Python lambdas are only a shorthand notation if
you're too lazy to define a function.
Functions are already first class objects in Python, and can be declared in a
local scope. Therefore the only advantage of using a lambda instead of a
locally-defined function is that you don't need to invent a name for the
function -- but that's just a local variable to which the function object (which
is exactly the same type of object that a lambda expression yields) is assigned!
Can Python be compiled to machine code, C or some other language?
-----------------------------------------------------------------
`Cython <http://cython.org/>`_ compiles a modified version of Python with
optional annotations into C extensions. `Nuitka <http://www.nuitka.net/>`_ is
an up-and-coming compiler of Python into C++ code, aiming to support the full
Python language. For compiling to Java you can consider
`VOC <https://voc.readthedocs.io>`_.
How does Python manage memory?
------------------------------
The details of Python memory management depend on the implementation. The
standard C implementation of Python uses reference counting to detect
inaccessible objects, and another mechanism to collect reference cycles,
periodically executing a cycle detection algorithm which looks for inaccessible
cycles and deletes the objects involved. The :mod:`gc` module provides functions
to perform a garbage collection, obtain debugging statistics, and tune the
collector's parameters.
Jython relies on the Java runtime so the JVM's garbage collector is used. This
difference can cause some subtle porting problems if your Python code depends on
the behavior of the reference counting implementation.
.. XXX relevant for Python 2.6?
Sometimes objects get stuck in tracebacks temporarily and hence are not
deallocated when you might expect. Clear the tracebacks with::
import sys
sys.exc_clear()
sys.exc_traceback = sys.last_traceback = None
Tracebacks are used for reporting errors, implementing debuggers and related
things. They contain a portion of the program state extracted during the
handling of an exception (usually the most recent exception).
In the absence of circularities and tracebacks, Python programs do not need to
manage memory explicitly.
Why doesn't Python use a more traditional garbage collection scheme? For one
thing, this is not a C standard feature and hence it's not portable. (Yes, we
know about the Boehm GC library. It has bits of assembler code for *most*
common platforms, not for all of them, and although it is mostly transparent, it
isn't completely transparent; patches are required to get Python to work with
it.)
Traditional GC also becomes a problem when Python is embedded into other
applications. While in a standalone Python it's fine to replace the standard
malloc() and free() with versions provided by the GC library, an application
embedding Python may want to have its *own* substitute for malloc() and free(),
and may not want Python's. Right now, Python works with anything that
implements malloc() and free() properly.
In Jython, the following code (which is fine in CPython) will probably run out
of file descriptors long before it runs out of memory::
for file in very_long_list_of_files:
f = open(file)
c = f.read(1)
Using the current reference counting and destructor scheme, each new assignment
to f closes the previous file. Using GC, this is not guaranteed. If you want
to write code that will work with any Python implementation, you should
explicitly close the file or use the :keyword:`with` statement; this will work
regardless of GC::
for file in very_long_list_of_files:
with open(file) as f:
c = f.read(1)
Why isn't all memory freed when Python exits?
---------------------------------------------
Objects referenced from the global namespaces of Python modules are not always
deallocated when Python exits. This may happen if there are circular
references. There are also certain bits of memory that are allocated by the C
library that are impossible to free (e.g. a tool like Purify will complain about
these). Python is, however, aggressive about cleaning up memory on exit and
does try to destroy every single object.
If you want to force Python to delete certain things on deallocation use the
:mod:`atexit` module to run a function that will force those deletions.
Why are there separate tuple and list data types?
-------------------------------------------------
Lists and tuples, while similar in many respects, are generally used in
fundamentally different ways. Tuples can be thought of as being similar to
Pascal records or C structs; they're small collections of related data which may
be of different types which are operated on as a group. For example, a
Cartesian coordinate is appropriately represented as a tuple of two or three
numbers.
Lists, on the other hand, are more like arrays in other languages. They tend to
hold a varying number of objects all of which have the same type and which are
operated on one-by-one. For example, ``os.listdir('.')`` returns a list of
strings representing the files in the current directory. Functions which
operate on this output would generally not break if you added another file or
two to the directory.
Tuples are immutable, meaning that once a tuple has been created, you can't
replace any of its elements with a new value. Lists are mutable, meaning that
you can always change a list's elements. Only immutable elements can be used as
dictionary keys, and hence only tuples and not lists can be used as keys.
How are lists implemented in CPython?
-------------------------------------
CPython's lists are really variable-length arrays, not Lisp-style linked lists.
The implementation uses a contiguous array of references to other objects, and
keeps a pointer to this array and the array's length in a list head structure.
This makes indexing a list ``a[i]`` an operation whose cost is independent of
the size of the list or the value of the index.
When items are appended or inserted, the array of references is resized. Some
cleverness is applied to improve the performance of appending items repeatedly;
when the array must be grown, some extra space is allocated so the next few
times don't require an actual resize.
How are dictionaries implemented in CPython?
--------------------------------------------
CPython's dictionaries are implemented as resizable hash tables. Compared to
B-trees, this gives better performance for lookup (the most common operation by
far) under most circumstances, and the implementation is simpler.
Dictionaries work by computing a hash code for each key stored in the dictionary
using the :func:`hash` built-in function. The hash code varies widely depending
on the key; for example, "Python" hashes to -539294296 while "python", a string
that differs by a single bit, hashes to 1142331976. The hash code is then used
to calculate a location in an internal array where the value will be stored.
Assuming that you're storing keys that all have different hash values, this
means that dictionaries take constant time -- O(1), in computer science notation
-- to retrieve a key. It also means that no sorted order of the keys is
maintained, and traversing the array as the ``.keys()`` and ``.items()`` do will
output the dictionary's content in some arbitrary jumbled order.
Why must dictionary keys be immutable?
--------------------------------------
The hash table implementation of dictionaries uses a hash value calculated from
the key value to find the key. If the key were a mutable object, its value
could change, and thus its hash could also change. But since whoever changes
the key object can't tell that it was being used as a dictionary key, it can't
move the entry around in the dictionary. Then, when you try to look up the same
object in the dictionary it won't be found because its hash value is different.
If you tried to look up the old value it wouldn't be found either, because the
value of the object found in that hash bin would be different.
If you want a dictionary indexed with a list, simply convert the list to a tuple
first; the function ``tuple(L)`` creates a tuple with the same entries as the
list ``L``. Tuples are immutable and can therefore be used as dictionary keys.
Some unacceptable solutions that have been proposed:
- Hash lists by their address (object ID). This doesn't work because if you
construct a new list with the same value it won't be found; e.g.::
mydict = {[1, 2]: '12'}
print mydict[[1, 2]]
would raise a KeyError exception because the id of the ``[1, 2]`` used in the
second line differs from that in the first line. In other words, dictionary
keys should be compared using ``==``, not using :keyword:`is`.
- Make a copy when using a list as a key. This doesn't work because the list,
being a mutable object, could contain a reference to itself, and then the
copying code would run into an infinite loop.
- Allow lists as keys but tell the user not to modify them. This would allow a
class of hard-to-track bugs in programs when you forgot or modified a list by
accident. It also invalidates an important invariant of dictionaries: every
value in ``d.keys()`` is usable as a key of the dictionary.
- Mark lists as read-only once they are used as a dictionary key. The problem
is that it's not just the top-level object that could change its value; you
could use a tuple containing a list as a key. Entering anything as a key into
a dictionary would require marking all objects reachable from there as
read-only -- and again, self-referential objects could cause an infinite loop.
There is a trick to get around this if you need to, but use it at your own risk:
You can wrap a mutable structure inside a class instance which has both a
:meth:`__eq__` and a :meth:`__hash__` method. You must then make sure that the
hash value for all such wrapper objects that reside in a dictionary (or other
hash based structure), remain fixed while the object is in the dictionary (or
other structure). ::
class ListWrapper:
def __init__(self, the_list):
self.the_list = the_list
def __eq__(self, other):
return self.the_list == other.the_list
def __hash__(self):
l = self.the_list
result = 98767 - len(l)*555
for i, el in enumerate(l):
try:
result = result + (hash(el) % 9999999) * 1001 + i
except Exception:
result = (result % 7777777) + i * 333
return result
Note that the hash computation is complicated by the possibility that some
members of the list may be unhashable and also by the possibility of arithmetic
overflow.
Furthermore it must always be the case that if ``o1 == o2`` (ie ``o1.__eq__(o2)
is True``) then ``hash(o1) == hash(o2)`` (ie, ``o1.__hash__() == o2.__hash__()``),
regardless of whether the object is in a dictionary or not. If you fail to meet
these restrictions dictionaries and other hash based structures will misbehave.
In the case of ListWrapper, whenever the wrapper object is in a dictionary the
wrapped list must not change to avoid anomalies. Don't do this unless you are
prepared to think hard about the requirements and the consequences of not
meeting them correctly. Consider yourself warned.
Why doesn't list.sort() return the sorted list?
-----------------------------------------------
In situations where performance matters, making a copy of the list just to sort
it would be wasteful. Therefore, :meth:`list.sort` sorts the list in place. In
order to remind you of that fact, it does not return the sorted list. This way,
you won't be fooled into accidentally overwriting a list when you need a sorted
copy but also need to keep the unsorted version around.
In Python 2.4 a new built-in function -- :func:`sorted` -- has been added.
This function creates a new list from a provided iterable, sorts it and returns
it. For example, here's how to iterate over the keys of a dictionary in sorted
order::
for key in sorted(mydict):
... # do whatever with mydict[key]...
How do you specify and enforce an interface spec in Python?
-----------------------------------------------------------
An interface specification for a module as provided by languages such as C++ and
Java describes the prototypes for the methods and functions of the module. Many
feel that compile-time enforcement of interface specifications helps in the
construction of large programs.
Python 2.6 adds an :mod:`abc` module that lets you define Abstract Base Classes
(ABCs). You can then use :func:`isinstance` and :func:`issubclass` to check
whether an instance or a class implements a particular ABC. The
:mod:`collections` module defines a set of useful ABCs such as
:class:`~collections.Iterable`, :class:`~collections.Container`, and
:class:`~collections.MutableMapping`.
For Python, many of the advantages of interface specifications can be obtained
by an appropriate test discipline for components. There is also a tool,
PyChecker, which can be used to find problems due to subclassing.
A good test suite for a module can both provide a regression test and serve as a
module interface specification and a set of examples. Many Python modules can
be run as a script to provide a simple "self test." Even modules which use
complex external interfaces can often be tested in isolation using trivial
"stub" emulations of the external interface. The :mod:`doctest` and
:mod:`unittest` modules or third-party test frameworks can be used to construct
exhaustive test suites that exercise every line of code in a module.
An appropriate testing discipline can help build large complex applications in
Python as well as having interface specifications would. In fact, it can be
better because an interface specification cannot test certain properties of a
program. For example, the :meth:`append` method is expected to add new elements
to the end of some internal list; an interface specification cannot test that
your :meth:`append` implementation will actually do this correctly, but it's
trivial to check this property in a test suite.
Writing test suites is very helpful, and you might want to design your code with
an eye to making it easily tested. One increasingly popular technique,
test-directed development, calls for writing parts of the test suite first,
before you write any of the actual code. Of course Python allows you to be
sloppy and not write test cases at all.
Why is there no goto?
---------------------
You can use exceptions to provide a "structured goto" that even works across
function calls. Many feel that exceptions can conveniently emulate all
reasonable uses of the "go" or "goto" constructs of C, Fortran, and other
languages. For example::
class label: pass # declare a label
try:
...
if condition: raise label() # goto label
...
except label: # where to goto
pass
...
This doesn't allow you to jump into the middle of a loop, but that's usually
considered an abuse of goto anyway. Use sparingly.
Why can't raw strings (r-strings) end with a backslash?
-------------------------------------------------------
More precisely, they can't end with an odd number of backslashes: the unpaired
backslash at the end escapes the closing quote character, leaving an
unterminated string.
Raw strings were designed to ease creating input for processors (chiefly regular
expression engines) that want to do their own backslash escape processing. Such
processors consider an unmatched trailing backslash to be an error anyway, so
raw strings disallow that. In return, they allow you to pass on the string
quote character by escaping it with a backslash. These rules work well when
r-strings are used for their intended purpose.
If you're trying to build Windows pathnames, note that all Windows system calls
accept forward slashes too::
f = open("/mydir/file.txt") # works fine!
If you're trying to build a pathname for a DOS command, try e.g. one of ::
dir = r"\this\is\my\dos\dir" "\\"
dir = r"\this\is\my\dos\dir\ "[:-1]
dir = "\\this\\is\\my\\dos\\dir\\"
Why doesn't Python have a "with" statement for attribute assignments?
---------------------------------------------------------------------
Python has a 'with' statement that wraps the execution of a block, calling code
on the entrance and exit from the block. Some language have a construct that
looks like this::
with obj:
a = 1 # equivalent to obj.a = 1
total = total + 1 # obj.total = obj.total + 1
In Python, such a construct would be ambiguous.
Other languages, such as Object Pascal, Delphi, and C++, use static types, so
it's possible to know, in an unambiguous way, what member is being assigned
to. This is the main point of static typing -- the compiler *always* knows the
scope of every variable at compile time.
Python uses dynamic types. It is impossible to know in advance which attribute
will be referenced at runtime. Member attributes may be added or removed from
objects on the fly. This makes it impossible to know, from a simple reading,
what attribute is being referenced: a local one, a global one, or a member
attribute?
For instance, take the following incomplete snippet::
def foo(a):
with a:
print x
The snippet assumes that "a" must have a member attribute called "x". However,
there is nothing in Python that tells the interpreter this. What should happen
if "a" is, let us say, an integer? If there is a global variable named "x",
will it be used inside the with block? As you see, the dynamic nature of Python
makes such choices much harder.
The primary benefit of "with" and similar language features (reduction of code
volume) can, however, easily be achieved in Python by assignment. Instead of::
function(args).mydict[index][index].a = 21
function(args).mydict[index][index].b = 42
function(args).mydict[index][index].c = 63
write this::
ref = function(args).mydict[index][index]
ref.a = 21
ref.b = 42
ref.c = 63
This also has the side-effect of increasing execution speed because name
bindings are resolved at run-time in Python, and the second version only needs
to perform the resolution once.
Why are colons required for the if/while/def/class statements?
--------------------------------------------------------------
The colon is required primarily to enhance readability (one of the results of
the experimental ABC language). Consider this::
if a == b
print a
versus ::
if a == b:
print a
Notice how the second one is slightly easier to read. Notice further how a
colon sets off the example in this FAQ answer; it's a standard usage in English.
Another minor reason is that the colon makes it easier for editors with syntax
highlighting; they can look for colons to decide when indentation needs to be
increased instead of having to do a more elaborate parsing of the program text.
Why does Python allow commas at the end of lists and tuples?
------------------------------------------------------------
Python lets you add a trailing comma at the end of lists, tuples, and
dictionaries::
[1, 2, 3,]
('a', 'b', 'c',)
d = {
"A": [1, 5],
"B": [6, 7], # last trailing comma is optional but good style
}
There are several reasons to allow this.
When you have a literal value for a list, tuple, or dictionary spread across
multiple lines, it's easier to add more elements because you don't have to
remember to add a comma to the previous line. The lines can also be reordered
without creating a syntax error.
Accidentally omitting the comma can lead to errors that are hard to diagnose.
For example::
x = [
"fee",
"fie"
"foo",
"fum"
]
This list looks like it has four elements, but it actually contains three:
"fee", "fiefoo" and "fum". Always adding the comma avoids this source of error.
Allowing the trailing comma may also make programmatic code generation easier.
PK %�\{ۻ#�F �F # html/_sources/faq/extending.rst.txtnu �[��� =======================
Extending/Embedding FAQ
=======================
.. only:: html
.. contents::
.. highlight:: c
Can I create my own functions in C?
-----------------------------------
Yes, you can create built-in modules containing functions, variables, exceptions
and even new types in C. This is explained in the document
:ref:`extending-index`.
Most intermediate or advanced Python books will also cover this topic.
Can I create my own functions in C++?
-------------------------------------
Yes, using the C compatibility features found in C++. Place ``extern "C" {
... }`` around the Python include files and put ``extern "C"`` before each
function that is going to be called by the Python interpreter. Global or static
C++ objects with constructors are probably not a good idea.
.. _c-wrapper-software:
Writing C is hard; are there any alternatives?
----------------------------------------------
There are a number of alternatives to writing your own C extensions, depending
on what you're trying to do.
.. XXX make sure these all work; mention Cython
If you need more speed, `Psyco <http://psyco.sourceforge.net/>`_ generates x86
assembly code from Python bytecode. You can use Psyco to compile the most
time-critical functions in your code, and gain a significant improvement with
very little effort, as long as you're running on a machine with an
x86-compatible processor.
`Cython <http://cython.org>`_ and its relative `Pyrex
<https://www.cosc.canterbury.ac.nz/greg.ewing/python/Pyrex/>`_ are compilers
that accept a slightly modified form of Python and generate the corresponding
C code. Pyrex makes it possible to write an extension without having to learn
Python's C API.
If you need to interface to some C or C++ library for which no Python extension
currently exists, you can try wrapping the library's data types and functions
with a tool such as `SWIG <http://www.swig.org>`_. `SIP
<https://riverbankcomputing.com/software/sip/intro>`__, `CXX
<http://cxx.sourceforge.net/>`_ `Boost
<http://www.boost.org/libs/python/doc/index.html>`_, or `Weave
<https://github.com/scipy/weave>`_ are also
alternatives for wrapping C++ libraries.
How can I execute arbitrary Python statements from C?
-----------------------------------------------------
The highest-level function to do this is :c:func:`PyRun_SimpleString` which takes
a single string argument to be executed in the context of the module
``__main__`` and returns 0 for success and -1 when an exception occurred
(including ``SyntaxError``). If you want more control, use
:c:func:`PyRun_String`; see the source for :c:func:`PyRun_SimpleString` in
``Python/pythonrun.c``.
How can I evaluate an arbitrary Python expression from C?
---------------------------------------------------------
Call the function :c:func:`PyRun_String` from the previous question with the
start symbol :c:data:`Py_eval_input`; it parses an expression, evaluates it and
returns its value.
How do I extract C values from a Python object?
-----------------------------------------------
That depends on the object's type. If it's a tuple, :c:func:`PyTuple_Size`
returns its length and :c:func:`PyTuple_GetItem` returns the item at a specified
index. Lists have similar functions, :c:func:`PyListSize` and
:c:func:`PyList_GetItem`.
For strings, :c:func:`PyString_Size` returns its length and
:c:func:`PyString_AsString` a pointer to its value. Note that Python strings may
contain null bytes so C's :c:func:`strlen` should not be used.
To test the type of an object, first make sure it isn't *NULL*, and then use
:c:func:`PyString_Check`, :c:func:`PyTuple_Check`, :c:func:`PyList_Check`, etc.
There is also a high-level API to Python objects which is provided by the
so-called 'abstract' interface -- read ``Include/abstract.h`` for further
details. It allows interfacing with any kind of Python sequence using calls
like :c:func:`PySequence_Length`, :c:func:`PySequence_GetItem`, etc.) as well as
many other useful protocols.
How do I use Py_BuildValue() to create a tuple of arbitrary length?
-------------------------------------------------------------------
You can't. Use ``t = PyTuple_New(n)`` instead, and fill it with objects using
``PyTuple_SetItem(t, i, o)`` -- note that this "eats" a reference count of
``o``, so you have to :c:func:`Py_INCREF` it. Lists have similar functions
``PyList_New(n)`` and ``PyList_SetItem(l, i, o)``. Note that you *must* set all
the tuple items to some value before you pass the tuple to Python code --
``PyTuple_New(n)`` initializes them to NULL, which isn't a valid Python value.
How do I call an object's method from C?
----------------------------------------
The :c:func:`PyObject_CallMethod` function can be used to call an arbitrary
method of an object. The parameters are the object, the name of the method to
call, a format string like that used with :c:func:`Py_BuildValue`, and the
argument values::
PyObject *
PyObject_CallMethod(PyObject *object, char *method_name,
char *arg_format, ...);
This works for any object that has methods -- whether built-in or user-defined.
You are responsible for eventually :c:func:`Py_DECREF`\ 'ing the return value.
To call, e.g., a file object's "seek" method with arguments 10, 0 (assuming the
file object pointer is "f")::
res = PyObject_CallMethod(f, "seek", "(ii)", 10, 0);
if (res == NULL) {
... an exception occurred ...
}
else {
Py_DECREF(res);
}
Note that since :c:func:`PyObject_CallObject` *always* wants a tuple for the
argument list, to call a function without arguments, pass "()" for the format,
and to call a function with one argument, surround the argument in parentheses,
e.g. "(i)".
How do I catch the output from PyErr_Print() (or anything that prints to stdout/stderr)?
----------------------------------------------------------------------------------------
In Python code, define an object that supports the ``write()`` method. Assign
this object to :data:`sys.stdout` and :data:`sys.stderr`. Call print_error, or
just allow the standard traceback mechanism to work. Then, the output will go
wherever your ``write()`` method sends it.
The easiest way to do this is to use the StringIO class in the standard library.
Sample code and use for catching stdout:
.. code-block:: pycon
>>> class StdoutCatcher:
... def __init__(self):
... self.data = ''
... def write(self, stuff):
... self.data = self.data + stuff
...
>>> import sys
>>> sys.stdout = StdoutCatcher()
>>> print 'foo'
>>> print 'hello world!'
>>> sys.stderr.write(sys.stdout.data)
foo
hello world!
How do I access a module written in Python from C?
--------------------------------------------------
You can get a pointer to the module object as follows::
module = PyImport_ImportModule("<modulename>");
If the module hasn't been imported yet (i.e. it is not yet present in
:data:`sys.modules`), this initializes the module; otherwise it simply returns
the value of ``sys.modules["<modulename>"]``. Note that it doesn't enter the
module into any namespace -- it only ensures it has been initialized and is
stored in :data:`sys.modules`.
You can then access the module's attributes (i.e. any name defined in the
module) as follows::
attr = PyObject_GetAttrString(module, "<attrname>");
Calling :c:func:`PyObject_SetAttrString` to assign to variables in the module
also works.
How do I interface to C++ objects from Python?
----------------------------------------------
Depending on your requirements, there are many approaches. To do this manually,
begin by reading :ref:`the "Extending and Embedding" document
<extending-index>`. Realize that for the Python run-time system, there isn't a
whole lot of difference between C and C++ -- so the strategy of building a new
Python type around a C structure (pointer) type will also work for C++ objects.
For C++ libraries, see :ref:`c-wrapper-software`.
I added a module using the Setup file and the make fails; why?
--------------------------------------------------------------
Setup must end in a newline, if there is no newline there, the build process
fails. (Fixing this requires some ugly shell script hackery, and this bug is so
minor that it doesn't seem worth the effort.)
How do I debug an extension?
----------------------------
When using GDB with dynamically loaded extensions, you can't set a breakpoint in
your extension until your extension is loaded.
In your ``.gdbinit`` file (or interactively), add the command:
.. code-block:: none
br _PyImport_LoadDynamicModule
Then, when you run GDB:
.. code-block:: shell-session
$ gdb /local/bin/python
gdb) run myscript.py
gdb) continue # repeat until your extension is loaded
gdb) finish # so that your extension is loaded
gdb) br myfunction.c:50
gdb) continue
I want to compile a Python module on my Linux system, but some files are missing. Why?
--------------------------------------------------------------------------------------
Most packaged versions of Python don't include the
:file:`/usr/lib/python2.{x}/config/` directory, which contains various files
required for compiling Python extensions.
For Red Hat, install the python-devel RPM to get the necessary files.
For Debian, run ``apt-get install python-dev``.
What does "SystemError: _PyImport_FixupExtension: module yourmodule not loaded" mean?
-------------------------------------------------------------------------------------
This means that you have created an extension module named "yourmodule", but
your module init function does not initialize with that name.
Every module init function will have a line similar to::
module = Py_InitModule("yourmodule", yourmodule_functions);
If the string passed to this function is not the same name as your extension
module, the :exc:`SystemError` exception will be raised.
How do I tell "incomplete input" from "invalid input"?
------------------------------------------------------
Sometimes you want to emulate the Python interactive interpreter's behavior,
where it gives you a continuation prompt when the input is incomplete (e.g. you
typed the start of an "if" statement or you didn't close your parentheses or
triple string quotes), but it gives you a syntax error message immediately when
the input is invalid.
In Python you can use the :mod:`codeop` module, which approximates the parser's
behavior sufficiently. IDLE uses this, for example.
The easiest way to do it in C is to call :c:func:`PyRun_InteractiveLoop` (perhaps
in a separate thread) and let the Python interpreter handle the input for
you. You can also set the :c:func:`PyOS_ReadlineFunctionPointer` to point at your
custom input function. See ``Modules/readline.c`` and ``Parser/myreadline.c``
for more hints.
However sometimes you have to run the embedded Python interpreter in the same
thread as your rest application and you can't allow the
:c:func:`PyRun_InteractiveLoop` to stop while waiting for user input. The one
solution then is to call :c:func:`PyParser_ParseString` and test for ``e.error``
equal to ``E_EOF``, which means the input is incomplete. Here's a sample code
fragment, untested, inspired by code from Alex Farber::
#include <Python.h>
#include <node.h>
#include <errcode.h>
#include <grammar.h>
#include <parsetok.h>
#include <compile.h>
int testcomplete(char *code)
/* code should end in \n */
/* return -1 for error, 0 for incomplete, 1 for complete */
{
node *n;
perrdetail e;
n = PyParser_ParseString(code, &_PyParser_Grammar,
Py_file_input, &e);
if (n == NULL) {
if (e.error == E_EOF)
return 0;
return -1;
}
PyNode_Free(n);
return 1;
}
Another solution is trying to compile the received string with
:c:func:`Py_CompileString`. If it compiles without errors, try to execute the
returned code object by calling :c:func:`PyEval_EvalCode`. Otherwise save the
input for later. If the compilation fails, find out if it's an error or just
more input is required - by extracting the message string from the exception
tuple and comparing it to the string "unexpected EOF while parsing". Here is a
complete example using the GNU readline library (you may want to ignore
**SIGINT** while calling readline())::
#include <stdio.h>
#include <readline.h>
#include <Python.h>
#include <object.h>
#include <compile.h>
#include <eval.h>
int main (int argc, char* argv[])
{
int i, j, done = 0; /* lengths of line, code */
char ps1[] = ">>> ";
char ps2[] = "... ";
char *prompt = ps1;
char *msg, *line, *code = NULL;
PyObject *src, *glb, *loc;
PyObject *exc, *val, *trb, *obj, *dum;
Py_Initialize ();
loc = PyDict_New ();
glb = PyDict_New ();
PyDict_SetItemString (glb, "__builtins__", PyEval_GetBuiltins ());
while (!done)
{
line = readline (prompt);
if (NULL == line) /* Ctrl-D pressed */
{
done = 1;
}
else
{
i = strlen (line);
if (i > 0)
add_history (line); /* save non-empty lines */
if (NULL == code) /* nothing in code yet */
j = 0;
else
j = strlen (code);
code = realloc (code, i + j + 2);
if (NULL == code) /* out of memory */
exit (1);
if (0 == j) /* code was empty, so */
code[0] = '\0'; /* keep strncat happy */
strncat (code, line, i); /* append line to code */
code[i + j] = '\n'; /* append '\n' to code */
code[i + j + 1] = '\0';
src = Py_CompileString (code, "<stdin>", Py_single_input);
if (NULL != src) /* compiled just fine - */
{
if (ps1 == prompt || /* ">>> " or */
'\n' == code[i + j - 1]) /* "... " and double '\n' */
{ /* so execute it */
dum = PyEval_EvalCode ((PyCodeObject *)src, glb, loc);
Py_XDECREF (dum);
Py_XDECREF (src);
free (code);
code = NULL;
if (PyErr_Occurred ())
PyErr_Print ();
prompt = ps1;
}
} /* syntax error or E_EOF? */
else if (PyErr_ExceptionMatches (PyExc_SyntaxError))
{
PyErr_Fetch (&exc, &val, &trb); /* clears exception! */
if (PyArg_ParseTuple (val, "sO", &msg, &obj) &&
!strcmp (msg, "unexpected EOF while parsing")) /* E_EOF */
{
Py_XDECREF (exc);
Py_XDECREF (val);
Py_XDECREF (trb);
prompt = ps2;
}
else /* some other syntax error */
{
PyErr_Restore (exc, val, trb);
PyErr_Print ();
free (code);
code = NULL;
prompt = ps1;
}
}
else /* some non-syntax error */
{
PyErr_Print ();
free (code);
code = NULL;
prompt = ps1;
}
free (line);
}
}
Py_XDECREF(glb);
Py_XDECREF(loc);
Py_Finalize();
exit(0);
}
How do I find undefined g++ symbols __builtin_new or __pure_virtual?
--------------------------------------------------------------------
To dynamically load g++ extension modules, you must recompile Python, relink it
using g++ (change LINKCC in the Python Modules Makefile), and link your
extension module using g++ (e.g., ``g++ -shared -o mymodule.so mymodule.o``).
Can I create an object class with some methods implemented in C and others in Python (e.g. through inheritance)?
----------------------------------------------------------------------------------------------------------------
Yes, you can inherit from built-in classes such as :class:`int`, :class:`list`,
:class:`dict`, etc.
The Boost Python Library (BPL, http://www.boost.org/libs/python/doc/index.html)
provides a way of doing this from C++ (i.e. you can inherit from an extension
class written in C++ using the BPL).
When importing module X, why do I get "undefined symbol: PyUnicodeUCS2*"?
-------------------------------------------------------------------------
You are using a version of Python that uses a 4-byte representation for Unicode
characters, but some C extension module you are importing was compiled using a
Python that uses a 2-byte representation for Unicode characters (the default).
If instead the name of the undefined symbol starts with ``PyUnicodeUCS4``, the
problem is the reverse: Python was built using 2-byte Unicode characters, and
the extension module was compiled using a Python with 4-byte Unicode characters.
This can easily occur when using pre-built extension packages. RedHat Linux
7.x, in particular, provided a "python2" binary that is compiled with 4-byte
Unicode. This only causes the link failure if the extension uses any of the
``PyUnicode_*()`` functions. It is also a problem if an extension uses any of
the Unicode-related format specifiers for :c:func:`Py_BuildValue` (or similar) or
parameter specifications for :c:func:`PyArg_ParseTuple`.
You can check the size of the Unicode character a Python interpreter is using by
checking the value of sys.maxunicode:
.. code-block:: pycon
>>> import sys
>>> if sys.maxunicode > 65535:
... print 'UCS4 build'
... else:
... print 'UCS2 build'
The only way to solve this problem is to use extension modules compiled with a
Python binary built using the same size for Unicode characters.
PK %�\�T=�GV GV ! html/_sources/faq/general.rst.txtnu �[��� :tocdepth: 2
==================
General Python FAQ
==================
.. only:: html
.. contents::
General Information
===================
What is Python?
---------------
Python is an interpreted, interactive, object-oriented programming language. It
incorporates modules, exceptions, dynamic typing, very high level dynamic data
types, and classes. Python combines remarkable power with very clear syntax.
It has interfaces to many system calls and libraries, as well as to various
window systems, and is extensible in C or C++. It is also usable as an
extension language for applications that need a programmable interface.
Finally, Python is portable: it runs on many Unix variants, on the Mac, and on
PCs under MS-DOS, Windows, Windows NT, and OS/2.
To find out more, start with :ref:`tutorial-index`. The `Beginner's Guide to
Python <https://wiki.python.org/moin/BeginnersGuide>`_ links to other
introductory tutorials and resources for learning Python.
What is the Python Software Foundation?
---------------------------------------
The Python Software Foundation is an independent non-profit organization that
holds the copyright on Python versions 2.1 and newer. The PSF's mission is to
advance open source technology related to the Python programming language and to
publicize the use of Python. The PSF's home page is at
https://www.python.org/psf/.
Donations to the PSF are tax-exempt in the US. If you use Python and find it
helpful, please contribute via `the PSF donation page
<https://www.python.org/psf/donations/>`_.
Are there copyright restrictions on the use of Python?
------------------------------------------------------
You can do anything you want with the source, as long as you leave the
copyrights in and display those copyrights in any documentation about Python
that you produce. If you honor the copyright rules, it's OK to use Python for
commercial use, to sell copies of Python in source or binary form (modified or
unmodified), or to sell products that incorporate Python in some form. We would
still like to know about all commercial use of Python, of course.
See `the PSF license page <https://www.python.org/psf/license/>`_ to find further
explanations and a link to the full text of the license.
The Python logo is trademarked, and in certain cases permission is required to
use it. Consult `the Trademark Usage Policy
<https://www.python.org/psf/trademarks/>`__ for more information.
Why was Python created in the first place?
------------------------------------------
Here's a *very* brief summary of what started it all, written by Guido van
Rossum:
I had extensive experience with implementing an interpreted language in the
ABC group at CWI, and from working with this group I had learned a lot about
language design. This is the origin of many Python features, including the
use of indentation for statement grouping and the inclusion of
very-high-level data types (although the details are all different in
Python).
I had a number of gripes about the ABC language, but also liked many of its
features. It was impossible to extend the ABC language (or its
implementation) to remedy my complaints -- in fact its lack of extensibility
was one of its biggest problems. I had some experience with using Modula-2+
and talked with the designers of Modula-3 and read the Modula-3 report.
Modula-3 is the origin of the syntax and semantics used for exceptions, and
some other Python features.
I was working in the Amoeba distributed operating system group at CWI. We
needed a better way to do system administration than by writing either C
programs or Bourne shell scripts, since Amoeba had its own system call
interface which wasn't easily accessible from the Bourne shell. My
experience with error handling in Amoeba made me acutely aware of the
importance of exceptions as a programming language feature.
It occurred to me that a scripting language with a syntax like ABC but with
access to the Amoeba system calls would fill the need. I realized that it
would be foolish to write an Amoeba-specific language, so I decided that I
needed a language that was generally extensible.
During the 1989 Christmas holidays, I had a lot of time on my hand, so I
decided to give it a try. During the next year, while still mostly working
on it in my own time, Python was used in the Amoeba project with increasing
success, and the feedback from colleagues made me add many early
improvements.
In February 1991, after just over a year of development, I decided to post to
USENET. The rest is in the ``Misc/HISTORY`` file.
What is Python good for?
------------------------
Python is a high-level general-purpose programming language that can be applied
to many different classes of problems.
The language comes with a large standard library that covers areas such as
string processing (regular expressions, Unicode, calculating differences between
files), Internet protocols (HTTP, FTP, SMTP, XML-RPC, POP, IMAP, CGI
programming), software engineering (unit testing, logging, profiling, parsing
Python code), and operating system interfaces (system calls, filesystems, TCP/IP
sockets). Look at the table of contents for :ref:`library-index` to get an idea
of what's available. A wide variety of third-party extensions are also
available. Consult `the Python Package Index <https://pypi.org>`_ to
find packages of interest to you.
How does the Python version numbering scheme work?
--------------------------------------------------
Python versions are numbered A.B.C or A.B. A is the major version number -- it
is only incremented for really major changes in the language. B is the minor
version number, incremented for less earth-shattering changes. C is the
micro-level -- it is incremented for each bugfix release. See :pep:`6` for more
information about bugfix releases.
Not all releases are bugfix releases. In the run-up to a new major release, a
series of development releases are made, denoted as alpha, beta, or release
candidate. Alphas are early releases in which interfaces aren't yet finalized;
it's not unexpected to see an interface change between two alpha releases.
Betas are more stable, preserving existing interfaces but possibly adding new
modules, and release candidates are frozen, making no changes except as needed
to fix critical bugs.
Alpha, beta and release candidate versions have an additional suffix. The
suffix for an alpha version is "aN" for some small number N, the suffix for a
beta version is "bN" for some small number N, and the suffix for a release
candidate version is "cN" for some small number N. In other words, all versions
labeled 2.0aN precede the versions labeled 2.0bN, which precede versions labeled
2.0cN, and *those* precede 2.0.
You may also find version numbers with a "+" suffix, e.g. "2.2+". These are
unreleased versions, built directly from the CPython development repository. In
practice, after a final minor release is made, the version is incremented to the
next minor version, which becomes the "a0" version, e.g. "2.4a0".
See also the documentation for :data:`sys.version`, :data:`sys.hexversion`, and
:data:`sys.version_info`.
How do I obtain a copy of the Python source?
--------------------------------------------
The latest Python source distribution is always available from python.org, at
https://www.python.org/downloads/. The latest development sources can be obtained
at https://github.com/python/cpython/.
The source distribution is a gzipped tar file containing the complete C source,
Sphinx-formatted documentation, Python library modules, example programs, and
several useful pieces of freely distributable software. The source will compile
and run out of the box on most UNIX platforms.
Consult the `Getting Started section of the Python Developer's Guide
<https://docs.python.org/devguide/setup.html>`__ for more
information on getting the source code and compiling it.
How do I get documentation on Python?
-------------------------------------
.. XXX mention py3k
The standard documentation for the current stable version of Python is available
at https://docs.python.org/3/. PDF, plain text, and downloadable HTML versions are
also available at https://docs.python.org/3/download.html.
The documentation is written in reStructuredText and processed by `the Sphinx
documentation tool <http://sphinx-doc.org/>`__. The reStructuredText source for
the documentation is part of the Python source distribution.
I've never programmed before. Is there a Python tutorial?
---------------------------------------------------------
There are numerous tutorials and books available. The standard documentation
includes :ref:`tutorial-index`.
Consult `the Beginner's Guide <https://wiki.python.org/moin/BeginnersGuide>`_ to
find information for beginning Python programmers, including lists of tutorials.
Is there a newsgroup or mailing list devoted to Python?
-------------------------------------------------------
There is a newsgroup, :newsgroup:`comp.lang.python`, and a mailing list,
`python-list <https://mail.python.org/mailman/listinfo/python-list>`_. The
newsgroup and mailing list are gatewayed into each other -- if you can read news
it's unnecessary to subscribe to the mailing list.
:newsgroup:`comp.lang.python` is high-traffic, receiving hundreds of postings
every day, and Usenet readers are often more able to cope with this volume.
Announcements of new software releases and events can be found in
comp.lang.python.announce, a low-traffic moderated list that receives about five
postings per day. It's available as `the python-announce mailing list
<https://mail.python.org/mailman/listinfo/python-announce-list>`_.
More info about other mailing lists and newsgroups
can be found at https://www.python.org/community/lists/.
How do I get a beta test version of Python?
-------------------------------------------
Alpha and beta releases are available from https://www.python.org/downloads/. All
releases are announced on the comp.lang.python and comp.lang.python.announce
newsgroups and on the Python home page at https://www.python.org/; an RSS feed of
news is available.
You can also access the development version of Python through Git. See
`The Python Developer's Guide <https://docs.python.org/devguide/>`_ for details.
How do I submit bug reports and patches for Python?
---------------------------------------------------
To report a bug or submit a patch, please use the Roundup installation at
https://bugs.python.org/.
You must have a Roundup account to report bugs; this makes it possible for us to
contact you if we have follow-up questions. It will also enable Roundup to send
you updates as we act on your bug. If you had previously used SourceForge to
report bugs to Python, you can obtain your Roundup password through Roundup's
`password reset procedure <https://bugs.python.org/user?@template=forgotten>`_.
For more information on how Python is developed, consult `the Python Developer's
Guide <https://docs.python.org/devguide/>`_.
Are there any published articles about Python that I can reference?
-------------------------------------------------------------------
It's probably best to cite your favorite book about Python.
The very first article about Python was written in 1991 and is now quite
outdated.
Guido van Rossum and Jelke de Boer, "Interactively Testing Remote Servers
Using the Python Programming Language", CWI Quarterly, Volume 4, Issue 4
(December 1991), Amsterdam, pp 283--303.
Are there any books on Python?
------------------------------
Yes, there are many, and more are being published. See the python.org wiki at
https://wiki.python.org/moin/PythonBooks for a list.
You can also search online bookstores for "Python" and filter out the Monty
Python references; or perhaps search for "Python" and "language".
Where in the world is www.python.org located?
---------------------------------------------
The Python project's infrastructure is located all over the world.
`www.python.org <https://www.python.org>`_ is graciously hosted by `Rackspace
<https://www.rackspace.com>`_, with CDN caching provided by `Fastly
<https://www.fastly.com>`_. `Upfront Systems
<http://www.upfrontsystems.co.za/>`_ hosts `bugs.python.org
<https://bugs.python.org>`_. Many other Python services like `the Wiki
<https://wiki.python.org>`_ are hosted by `Oregon State
University Open Source Lab <https://osuosl.org>`_.
Why is it called Python?
------------------------
When he began implementing Python, Guido van Rossum was also reading the
published scripts from `"Monty Python's Flying Circus"
<https://en.wikipedia.org/wiki/Monty_Python>`__, a BBC comedy series from the 1970s. Van Rossum
thought he needed a name that was short, unique, and slightly mysterious, so he
decided to call the language Python.
Do I have to like "Monty Python's Flying Circus"?
-------------------------------------------------
No, but it helps. :)
Python in the real world
========================
How stable is Python?
---------------------
Very stable. New, stable releases have been coming out roughly every 6 to 18
months since 1991, and this seems likely to continue. Currently there are
usually around 18 months between major releases.
The developers issue "bugfix" releases of older versions, so the stability of
existing releases gradually improves. Bugfix releases, indicated by a third
component of the version number (e.g. 3.5.3, 3.6.2), are managed for stability;
only fixes for known problems are included in a bugfix release, and it's
guaranteed that interfaces will remain the same throughout a series of bugfix
releases.
The latest stable releases can always be found on the `Python download page
<https://www.python.org/downloads/>`_. There are two production-ready version
of Python: 2.x and 3.x, but the recommended one at this times is Python 3.x.
Although Python 2.x is still widely used, `it will not be
maintained after January 1, 2020 <https://www.python.org/dev/peps/pep-0373/>`_.
Python 2.x was known for having more third-party libraries available, however,
by the time of this writing, most of the widely used libraries support Python 3.x,
and some are even dropping the Python 2.x support.
How many people are using Python?
---------------------------------
There are probably tens of thousands of users, though it's difficult to obtain
an exact count.
Python is available for free download, so there are no sales figures, and it's
available from many different sites and packaged with many Linux distributions,
so download statistics don't tell the whole story either.
The comp.lang.python newsgroup is very active, but not all Python users post to
the group or even read it.
Have any significant projects been done in Python?
--------------------------------------------------
See https://www.python.org/about/success for a list of projects that use Python.
Consulting the proceedings for `past Python conferences
<https://www.python.org/community/workshops/>`_ will reveal contributions from many
different companies and organizations.
High-profile Python projects include `the Mailman mailing list manager
<http://www.list.org>`_ and `the Zope application server
<http://www.zope.org>`_. Several Linux distributions, most notably `Red Hat
<https://www.redhat.com>`_, have written part or all of their installer and
system administration software in Python. Companies that use Python internally
include Google, Yahoo, and Lucasfilm Ltd.
What new developments are expected for Python in the future?
------------------------------------------------------------
See https://www.python.org/dev/peps/ for the Python Enhancement Proposals
(PEPs). PEPs are design documents describing a suggested new feature for Python,
providing a concise technical specification and a rationale. Look for a PEP
titled "Python X.Y Release Schedule", where X.Y is a version that hasn't been
publicly released yet.
New development is discussed on `the python-dev mailing list
<https://mail.python.org/mailman/listinfo/python-dev/>`_.
Is it reasonable to propose incompatible changes to Python?
-----------------------------------------------------------
In general, no. There are already millions of lines of Python code around the
world, so any change in the language that invalidates more than a very small
fraction of existing programs has to be frowned upon. Even if you can provide a
conversion program, there's still the problem of updating all documentation;
many books have been written about Python, and we don't want to invalidate them
all at a single stroke.
Providing a gradual upgrade path is necessary if a feature has to be changed.
:pep:`5` describes the procedure followed for introducing backward-incompatible
changes while minimizing disruption for users.
Is Python a good language for beginning programmers?
----------------------------------------------------
Yes.
It is still common to start students with a procedural and statically typed
language such as Pascal, C, or a subset of C++ or Java. Students may be better
served by learning Python as their first language. Python has a very simple and
consistent syntax and a large standard library and, most importantly, using
Python in a beginning programming course lets students concentrate on important
programming skills such as problem decomposition and data type design. With
Python, students can be quickly introduced to basic concepts such as loops and
procedures. They can probably even work with user-defined objects in their very
first course.
For a student who has never programmed before, using a statically typed language
seems unnatural. It presents additional complexity that the student must master
and slows the pace of the course. The students are trying to learn to think
like a computer, decompose problems, design consistent interfaces, and
encapsulate data. While learning to use a statically typed language is
important in the long term, it is not necessarily the best topic to address in
the students' first programming course.
Many other aspects of Python make it a good first language. Like Java, Python
has a large standard library so that students can be assigned programming
projects very early in the course that *do* something. Assignments aren't
restricted to the standard four-function calculator and check balancing
programs. By using the standard library, students can gain the satisfaction of
working on realistic applications as they learn the fundamentals of programming.
Using the standard library also teaches students about code reuse. Third-party
modules such as PyGame are also helpful in extending the students' reach.
Python's interactive interpreter enables students to test language features
while they're programming. They can keep a window with the interpreter running
while they enter their program's source in another window. If they can't
remember the methods for a list, they can do something like this::
>>> L = []
>>> dir(L) # doctest: +NORMALIZE_WHITESPACE
['__add__', '__class__', '__contains__', '__delattr__', '__delitem__',
'__delslice__', '__doc__', '__eq__', '__format__', '__ge__',
'__getattribute__', '__getitem__', '__getslice__', '__gt__',
'__hash__', '__iadd__', '__imul__', '__init__', '__iter__', '__le__',
'__len__', '__lt__', '__mul__', '__ne__', '__new__', '__reduce__',
'__reduce_ex__', '__repr__', '__reversed__', '__rmul__',
'__setattr__', '__setitem__', '__setslice__', '__sizeof__', '__str__',
'__subclasshook__', 'append', 'count', 'extend', 'index', 'insert',
'pop', 'remove', 'reverse', 'sort']
>>> help(L.append)
Help on built-in function append:
<BLANKLINE>
append(...)
L.append(object) -- append object to end
<BLANKLINE>
>>> L.append(1)
>>> L
[1]
With the interpreter, documentation is never far from the student as he's
programming.
There are also good IDEs for Python. IDLE is a cross-platform IDE for Python
that is written in Python using Tkinter. PythonWin is a Windows-specific IDE.
Emacs users will be happy to know that there is a very good Python mode for
Emacs. All of these programming environments provide syntax highlighting,
auto-indenting, and access to the interactive interpreter while coding. Consult
`the Python wiki <https://wiki.python.org/moin/PythonEditors>`_ for a full list
of Python editing environments.
If you want to discuss Python's use in education, you may be interested in
joining `the edu-sig mailing list
<https://www.python.org/community/sigs/current/edu-sig>`_.
Upgrading Python
================
What is this bsddb185 module my application keeps complaining about?
--------------------------------------------------------------------
.. XXX remove this question?
Starting with Python2.3, the distribution includes the `PyBSDDB package
<http://pybsddb.sf.net/>` as a replacement for the old bsddb module. It
includes functions which provide backward compatibility at the API level, but
requires a newer version of the underlying `Berkeley DB
<http://www.sleepycat.com>`_ library. Files created with the older bsddb module
can't be opened directly using the new module.
Using your old version of Python and a pair of scripts which are part of Python
2.3 (db2pickle.py and pickle2db.py, in the Tools/scripts directory) you can
convert your old database files to the new format. Using your old Python
version, run the db2pickle.py script to convert it to a pickle, e.g.::
python2.2 <pathto>/db2pickley.py database.db database.pck
Rename your database file::
mv database.db olddatabase.db
Now convert the pickle file to a new format database::
python <pathto>/pickle2db.py database.db database.pck
The precise commands you use will vary depending on the particulars of your
installation. For full details about operation of these two scripts check the
doc string at the start of each one.
PK %�\�mi� � html/_sources/faq/gui.rst.txtnu �[��� :tocdepth: 2
==========================
Graphic User Interface FAQ
==========================
.. only:: html
.. contents::
What platform-independent GUI toolkits exist for Python?
========================================================
Depending on what platform(s) you are aiming at, there are several.
.. XXX check links
Tkinter
-------
Standard builds of Python include an object-oriented interface to the Tcl/Tk
widget set, called Tkinter. This is probably the easiest to install and use.
For more info about Tk, including pointers to the source, see the Tcl/Tk home
page at https://www.tcl.tk. Tcl/Tk is fully portable to the Mac OS X, Windows,
and Unix platforms.
wxWidgets
---------
wxWidgets (https://www.wxwidgets.org) is a free, portable GUI class
library written in C++ that provides a native look and feel on a
number of platforms, with Windows, Mac OS X, GTK, X11, all listed as
current stable targets. Language bindings are available for a number
of languages including Python, Perl, Ruby, etc.
wxPython (http://www.wxpython.org) is the Python binding for
wxwidgets. While it often lags slightly behind the official wxWidgets
releases, it also offers a number of features via pure Python
extensions that are not available in other language bindings. There
is an active wxPython user and developer community.
Both wxWidgets and wxPython are free, open source, software with
permissive licences that allow their use in commercial products as
well as in freeware or shareware.
Qt
---
There are bindings available for the Qt toolkit (using either `PyQt
<https://riverbankcomputing.com/software/pyqt/intro>`_ or `PySide
<https://wiki.qt.io/PySide>`_) and for KDE (`PyKDE4 <https://techbase.kde.org/Languages/Python/Using_PyKDE_4>`__).
PyQt is currently more mature than PySide, but you must buy a PyQt license from
`Riverbank Computing <https://www.riverbankcomputing.com/commercial/license-faq>`_
if you want to write proprietary applications. PySide is free for all applications.
Qt 4.5 upwards is licensed under the LGPL license; also, commercial licenses
are available from `The Qt Company <https://www.qt.io/licensing/>`_.
Gtk+
----
PyGtk bindings for the `Gtk+ toolkit <http://www.gtk.org>`_ have been
implemented by James Henstridge; see <http://www.pygtk.org>.
FLTK
----
Python bindings for `the FLTK toolkit <http://www.fltk.org>`_, a simple yet
powerful and mature cross-platform windowing system, are available from `the
PyFLTK project <http://pyfltk.sourceforge.net>`_.
OpenGL
------
For OpenGL bindings, see `PyOpenGL <http://pyopengl.sourceforge.net>`_.
What platform-specific GUI toolkits exist for Python?
========================================================
By installing the `PyObjc Objective-C bridge
<https://pythonhosted.org/pyobjc/>`_, Python programs can use Mac OS X's
Cocoa libraries.
:ref:`Pythonwin <windows-faq>` by Mark Hammond includes an interface to the
Microsoft Foundation Classes and a Python programming environment
that's written mostly in Python using the MFC classes.
Tkinter questions
=================
How do I freeze Tkinter applications?
-------------------------------------
Freeze is a tool to create stand-alone applications. When freezing Tkinter
applications, the applications will not be truly stand-alone, as the application
will still need the Tcl and Tk libraries.
One solution is to ship the application with the Tcl and Tk libraries, and point
to them at run-time using the :envvar:`TCL_LIBRARY` and :envvar:`TK_LIBRARY`
environment variables.
To get truly stand-alone applications, the Tcl scripts that form the library
have to be integrated into the application as well. One tool supporting that is
SAM (stand-alone modules), which is part of the Tix distribution
(http://tix.sourceforge.net/).
Build Tix with SAM enabled, perform the appropriate call to
:c:func:`Tclsam_init`, etc. inside Python's
:file:`Modules/tkappinit.c`, and link with libtclsam and libtksam (you
might include the Tix libraries as well).
Can I have Tk events handled while waiting for I/O?
---------------------------------------------------
On platforms other than Windows, yes, and you don't even
need threads! But you'll have to restructure your I/O
code a bit. Tk has the equivalent of Xt's :c:func:`XtAddInput()` call, which allows you
to register a callback function which will be called from the Tk mainloop when
I/O is possible on a file descriptor. See :ref:`tkinter-file-handlers`.
I can't get key bindings to work in Tkinter: why?
-------------------------------------------------
An often-heard complaint is that event handlers bound to events with the
:meth:`bind` method don't get handled even when the appropriate key is pressed.
The most common cause is that the widget to which the binding applies doesn't
have "keyboard focus". Check out the Tk documentation for the focus command.
Usually a widget is given the keyboard focus by clicking in it (but not for
labels; see the takefocus option).
PK %�\Vv�� html/_sources/faq/index.rst.txtnu �[��� .. _faq-index:
###################################
Python Frequently Asked Questions
###################################
.. toctree::
:maxdepth: 1
general.rst
programming.rst
design.rst
library.rst
extending.rst
windows.rst
gui.rst
installed.rst
PK %�\��}- - # html/_sources/faq/installed.rst.txtnu �[��� =============================================
"Why is Python Installed on my Computer?" FAQ
=============================================
What is Python?
---------------
Python is a programming language. It's used for many different applications.
It's used in some high schools and colleges as an introductory programming
language because Python is easy to learn, but it's also used by professional
software developers at places such as Google, NASA, and Lucasfilm Ltd.
If you wish to learn more about Python, start with the `Beginner's Guide to
Python <https://wiki.python.org/moin/BeginnersGuide>`_.
Why is Python installed on my machine?
--------------------------------------
If you find Python installed on your system but don't remember installing it,
there are several possible ways it could have gotten there.
* Perhaps another user on the computer wanted to learn programming and installed
it; you'll have to figure out who's been using the machine and might have
installed it.
* A third-party application installed on the machine might have been written in
Python and included a Python installation. For a home computer, the most
common such application is `PySol <http://pysolfc.sourceforge.net/>`_, a
solitaire game that includes over 1000 different games and variations.
* Some Windows machines also have Python installed. At this writing we're aware
of computers from Hewlett-Packard and Compaq that include Python. Apparently
some of HP/Compaq's administrative tools are written in Python.
* All Apple computers running Mac OS X have Python installed; it's included in
the base installation.
Can I delete Python?
--------------------
That depends on where Python came from.
If someone installed it deliberately, you can remove it without hurting
anything. On Windows, use the Add/Remove Programs icon in the Control Panel.
If Python was installed by a third-party application, you can also remove it,
but that application will no longer work. You should use that application's
uninstaller rather than removing Python directly.
If Python came with your operating system, removing it is not recommended. If
you remove it, whatever tools were written in Python will no longer run, and
some of them might be important to you. Reinstalling the whole system would
then be required to fix things again.
PK %�\S�{� {� ! html/_sources/faq/library.rst.txtnu �[��� :tocdepth: 2
=========================
Library and Extension FAQ
=========================
.. only:: html
.. contents::
General Library Questions
=========================
How do I find a module or application to perform task X?
--------------------------------------------------------
Check :ref:`the Library Reference <library-index>` to see if there's a relevant
standard library module. (Eventually you'll learn what's in the standard
library and will be able to skip this step.)
For third-party packages, search the `Python Package Index
<https://pypi.org>`_ or try `Google <https://www.google.com>`_ or
another Web search engine. Searching for "Python" plus a keyword or two for
your topic of interest will usually find something helpful.
Where is the math.py (socket.py, regex.py, etc.) source file?
-------------------------------------------------------------
If you can't find a source file for a module it may be a built-in or
dynamically loaded module implemented in C, C++ or other compiled language.
In this case you may not have the source file or it may be something like
:file:`mathmodule.c`, somewhere in a C source directory (not on the Python Path).
There are (at least) three kinds of modules in Python:
1) modules written in Python (.py);
2) modules written in C and dynamically loaded (.dll, .pyd, .so, .sl, etc);
3) modules written in C and linked with the interpreter; to get a list of these,
type::
import sys
print sys.builtin_module_names
How do I make a Python script executable on Unix?
-------------------------------------------------
You need to do two things: the script file's mode must be executable and the
first line must begin with ``#!`` followed by the path of the Python
interpreter.
The first is done by executing ``chmod +x scriptfile`` or perhaps ``chmod 755
scriptfile``.
The second can be done in a number of ways. The most straightforward way is to
write ::
#!/usr/local/bin/python
as the very first line of your file, using the pathname for where the Python
interpreter is installed on your platform.
If you would like the script to be independent of where the Python interpreter
lives, you can use the :program:`env` program. Almost all Unix variants support
the following, assuming the Python interpreter is in a directory on the user's
:envvar:`PATH`::
#!/usr/bin/env python
*Don't* do this for CGI scripts. The :envvar:`PATH` variable for CGI scripts is
often very minimal, so you need to use the actual absolute pathname of the
interpreter.
Occasionally, a user's environment is so full that the :program:`/usr/bin/env`
program fails; or there's no env program at all. In that case, you can try the
following hack (due to Alex Rezinsky)::
#! /bin/sh
""":"
exec python $0 ${1+"$@"}
"""
The minor disadvantage is that this defines the script's __doc__ string.
However, you can fix that by adding ::
__doc__ = """...Whatever..."""
Is there a curses/termcap package for Python?
---------------------------------------------
.. XXX curses *is* built by default, isn't it?
For Unix variants the standard Python source distribution comes with a curses
module in the :source:`Modules` subdirectory, though it's not compiled by default.
(Note that this is not available in the Windows distribution -- there is no
curses module for Windows.)
The :mod:`curses` module supports basic curses features as well as many additional
functions from ncurses and SYSV curses such as colour, alternative character set
support, pads, and mouse support. This means the module isn't compatible with
operating systems that only have BSD curses, but there don't seem to be any
currently maintained OSes that fall into this category.
For Windows: use `the consolelib module
<http://effbot.org/zone/console-index.htm>`_.
Is there an equivalent to C's onexit() in Python?
-------------------------------------------------
The :mod:`atexit` module provides a register function that is similar to C's
:c:func:`onexit`.
Why don't my signal handlers work?
----------------------------------
The most common problem is that the signal handler is declared with the wrong
argument list. It is called as ::
handler(signum, frame)
so it should be declared with two arguments::
def handler(signum, frame):
...
Common tasks
============
How do I test a Python program or component?
--------------------------------------------
Python comes with two testing frameworks. The :mod:`doctest` module finds
examples in the docstrings for a module and runs them, comparing the output with
the expected output given in the docstring.
The :mod:`unittest` module is a fancier testing framework modelled on Java and
Smalltalk testing frameworks.
To make testing easier, you should use good modular design in your program.
Your program should have almost all functionality
encapsulated in either functions or class methods -- and this sometimes has the
surprising and delightful effect of making the program run faster (because local
variable accesses are faster than global accesses). Furthermore the program
should avoid depending on mutating global variables, since this makes testing
much more difficult to do.
The "global main logic" of your program may be as simple as ::
if __name__ == "__main__":
main_logic()
at the bottom of the main module of your program.
Once your program is organized as a tractable collection of functions and class
behaviours you should write test functions that exercise the behaviours. A test
suite that automates a sequence of tests can be associated with each module.
This sounds like a lot of work, but since Python is so terse and flexible it's
surprisingly easy. You can make coding much more pleasant and fun by writing
your test functions in parallel with the "production code", since this makes it
easy to find bugs and even design flaws earlier.
"Support modules" that are not intended to be the main module of a program may
include a self-test of the module. ::
if __name__ == "__main__":
self_test()
Even programs that interact with complex external interfaces may be tested when
the external interfaces are unavailable by using "fake" interfaces implemented
in Python.
How do I create documentation from doc strings?
-----------------------------------------------
The :mod:`pydoc` module can create HTML from the doc strings in your Python
source code. An alternative for creating API documentation purely from
docstrings is `epydoc <http://epydoc.sourceforge.net/>`_. `Sphinx
<http://sphinx-doc.org>`_ can also include docstring content.
How do I get a single keypress at a time?
-----------------------------------------
For Unix variants there are several solutions. It's straightforward to do this
using curses, but curses is a fairly large module to learn. Here's a solution
without curses::
import termios, fcntl, sys, os
fd = sys.stdin.fileno()
oldterm = termios.tcgetattr(fd)
newattr = termios.tcgetattr(fd)
newattr[3] = newattr[3] & ~termios.ICANON & ~termios.ECHO
termios.tcsetattr(fd, termios.TCSANOW, newattr)
oldflags = fcntl.fcntl(fd, fcntl.F_GETFL)
fcntl.fcntl(fd, fcntl.F_SETFL, oldflags | os.O_NONBLOCK)
try:
while 1:
try:
c = sys.stdin.read(1)
print "Got character", repr(c)
except IOError: pass
finally:
termios.tcsetattr(fd, termios.TCSAFLUSH, oldterm)
fcntl.fcntl(fd, fcntl.F_SETFL, oldflags)
You need the :mod:`termios` and the :mod:`fcntl` module for any of this to work,
and I've only tried it on Linux, though it should work elsewhere. In this code,
characters are read and printed one at a time.
:func:`termios.tcsetattr` turns off stdin's echoing and disables canonical mode.
:func:`fcntl.fnctl` is used to obtain stdin's file descriptor flags and modify
them for non-blocking mode. Since reading stdin when it is empty results in an
:exc:`IOError`, this error is caught and ignored.
Threads
=======
How do I program using threads?
-------------------------------
.. XXX it's _thread in py3k
Be sure to use the :mod:`threading` module and not the :mod:`thread` module.
The :mod:`threading` module builds convenient abstractions on top of the
low-level primitives provided by the :mod:`thread` module.
Aahz has a set of slides from his threading tutorial that are helpful; see
http://www.pythoncraft.com/OSCON2001/.
None of my threads seem to run: why?
------------------------------------
As soon as the main thread exits, all threads are killed. Your main thread is
running too quickly, giving the threads no time to do any work.
A simple fix is to add a sleep to the end of the program that's long enough for
all the threads to finish::
import threading, time
def thread_task(name, n):
for i in range(n): print name, i
for i in range(10):
T = threading.Thread(target=thread_task, args=(str(i), i))
T.start()
time.sleep(10) # <----------------------------!
But now (on many platforms) the threads don't run in parallel, but appear to run
sequentially, one at a time! The reason is that the OS thread scheduler doesn't
start a new thread until the previous thread is blocked.
A simple fix is to add a tiny sleep to the start of the run function::
def thread_task(name, n):
time.sleep(0.001) # <---------------------!
for i in range(n): print name, i
for i in range(10):
T = threading.Thread(target=thread_task, args=(str(i), i))
T.start()
time.sleep(10)
Instead of trying to guess a good delay value for :func:`time.sleep`,
it's better to use some kind of semaphore mechanism. One idea is to use the
:mod:`Queue` module to create a queue object, let each thread append a token to
the queue when it finishes, and let the main thread read as many tokens from the
queue as there are threads.
How do I parcel out work among a bunch of worker threads?
---------------------------------------------------------
Use the :mod:`Queue` module to create a queue containing a list of jobs. The
:class:`~Queue.Queue` class maintains a list of objects and has a ``.put(obj)``
method that adds items to the queue and a ``.get()`` method to return them.
The class will take care of the locking necessary to ensure that each job is
handed out exactly once.
Here's a trivial example::
import threading, Queue, time
# The worker thread gets jobs off the queue. When the queue is empty, it
# assumes there will be no more work and exits.
# (Realistically workers will run until terminated.)
def worker():
print 'Running worker'
time.sleep(0.1)
while True:
try:
arg = q.get(block=False)
except Queue.Empty:
print 'Worker', threading.currentThread(),
print 'queue empty'
break
else:
print 'Worker', threading.currentThread(),
print 'running with argument', arg
time.sleep(0.5)
# Create queue
q = Queue.Queue()
# Start a pool of 5 workers
for i in range(5):
t = threading.Thread(target=worker, name='worker %i' % (i+1))
t.start()
# Begin adding work to the queue
for i in range(50):
q.put(i)
# Give threads time to run
print 'Main thread sleeping'
time.sleep(5)
When run, this will produce the following output:
.. code-block:: none
Running worker
Running worker
Running worker
Running worker
Running worker
Main thread sleeping
Worker <Thread(worker 1, started)> running with argument 0
Worker <Thread(worker 2, started)> running with argument 1
Worker <Thread(worker 3, started)> running with argument 2
Worker <Thread(worker 4, started)> running with argument 3
Worker <Thread(worker 5, started)> running with argument 4
Worker <Thread(worker 1, started)> running with argument 5
...
Consult the module's documentation for more details; the :class:`~Queue.Queue`
class provides a featureful interface.
What kinds of global value mutation are thread-safe?
----------------------------------------------------
A :term:`global interpreter lock` (GIL) is used internally to ensure that only
one thread runs in the Python VM at a time. In general, Python offers to switch
among threads only between bytecode instructions; how frequently it switches can
be set via :func:`sys.setcheckinterval`. Each bytecode instruction and
therefore all the C implementation code reached from each instruction is
therefore atomic from the point of view of a Python program.
In theory, this means an exact accounting requires an exact understanding of the
PVM bytecode implementation. In practice, it means that operations on shared
variables of built-in data types (ints, lists, dicts, etc) that "look atomic"
really are.
For example, the following operations are all atomic (L, L1, L2 are lists, D,
D1, D2 are dicts, x, y are objects, i, j are ints)::
L.append(x)
L1.extend(L2)
x = L[i]
x = L.pop()
L1[i:j] = L2
L.sort()
x = y
x.field = y
D[x] = y
D1.update(D2)
D.keys()
These aren't::
i = i+1
L.append(L[-1])
L[i] = L[j]
D[x] = D[x] + 1
Operations that replace other objects may invoke those other objects'
:meth:`__del__` method when their reference count reaches zero, and that can
affect things. This is especially true for the mass updates to dictionaries and
lists. When in doubt, use a mutex!
Can't we get rid of the Global Interpreter Lock?
------------------------------------------------
.. XXX mention multiprocessing
.. XXX link to dbeazley's talk about GIL?
The :term:`global interpreter lock` (GIL) is often seen as a hindrance to Python's
deployment on high-end multiprocessor server machines, because a multi-threaded
Python program effectively only uses one CPU, due to the insistence that
(almost) all Python code can only run while the GIL is held.
Back in the days of Python 1.5, Greg Stein actually implemented a comprehensive
patch set (the "free threading" patches) that removed the GIL and replaced it
with fine-grained locking. Unfortunately, even on Windows (where locks are very
efficient) this ran ordinary Python code about twice as slow as the interpreter
using the GIL. On Linux the performance loss was even worse because pthread
locks aren't as efficient.
Since then, the idea of getting rid of the GIL has occasionally come up but
nobody has found a way to deal with the expected slowdown, and users who don't
use threads would not be happy if their code ran at half the speed. Greg's
free threading patch set has not been kept up-to-date for later Python versions.
This doesn't mean that you can't make good use of Python on multi-CPU machines!
You just have to be creative with dividing the work up between multiple
*processes* rather than multiple *threads*. Judicious use of C extensions will
also help; if you use a C extension to perform a time-consuming task, the
extension can release the GIL while the thread of execution is in the C code and
allow other threads to get some work done.
It has been suggested that the GIL should be a per-interpreter-state lock rather
than truly global; interpreters then wouldn't be able to share objects.
Unfortunately, this isn't likely to happen either. It would be a tremendous
amount of work, because many object implementations currently have global state.
For example, small integers and short strings are cached; these caches would
have to be moved to the interpreter state. Other object types have their own
free list; these free lists would have to be moved to the interpreter state.
And so on.
And I doubt that it can even be done in finite time, because the same problem
exists for 3rd party extensions. It is likely that 3rd party extensions are
being written at a faster rate than you can convert them to store all their
global state in the interpreter state.
And finally, once you have multiple interpreters not sharing any state, what
have you gained over running each interpreter in a separate process?
Input and Output
================
How do I delete a file? (And other file questions...)
-----------------------------------------------------
Use ``os.remove(filename)`` or ``os.unlink(filename)``; for documentation, see
the :mod:`os` module. The two functions are identical; :func:`unlink` is simply
the name of the Unix system call for this function.
To remove a directory, use :func:`os.rmdir`; use :func:`os.mkdir` to create one.
``os.makedirs(path)`` will create any intermediate directories in ``path`` that
don't exist. ``os.removedirs(path)`` will remove intermediate directories as
long as they're empty; if you want to delete an entire directory tree and its
contents, use :func:`shutil.rmtree`.
To rename a file, use ``os.rename(old_path, new_path)``.
To truncate a file, open it using ``f = open(filename, "r+")``, and use
``f.truncate(offset)``; offset defaults to the current seek position. There's
also ``os.ftruncate(fd, offset)`` for files opened with :func:`os.open`, where
*fd* is the file descriptor (a small integer).
The :mod:`shutil` module also contains a number of functions to work on files
including :func:`~shutil.copyfile`, :func:`~shutil.copytree`, and
:func:`~shutil.rmtree`.
How do I copy a file?
---------------------
The :mod:`shutil` module contains a :func:`~shutil.copyfile` function. Note
that on MacOS 9 it doesn't copy the resource fork and Finder info.
How do I read (or write) binary data?
-------------------------------------
To read or write complex binary data formats, it's best to use the :mod:`struct`
module. It allows you to take a string containing binary data (usually numbers)
and convert it to Python objects; and vice versa.
For example, the following code reads two 2-byte integers and one 4-byte integer
in big-endian format from a file::
import struct
f = open(filename, "rb") # Open in binary mode for portability
s = f.read(8)
x, y, z = struct.unpack(">hhl", s)
The '>' in the format string forces big-endian data; the letter 'h' reads one
"short integer" (2 bytes), and 'l' reads one "long integer" (4 bytes) from the
string.
For data that is more regular (e.g. a homogeneous list of ints or floats),
you can also use the :mod:`array` module.
I can't seem to use os.read() on a pipe created with os.popen(); why?
---------------------------------------------------------------------
:func:`os.read` is a low-level function which takes a file descriptor, a small
integer representing the opened file. :func:`os.popen` creates a high-level
file object, the same type returned by the built-in :func:`open` function.
Thus, to read *n* bytes from a pipe *p* created with :func:`os.popen`, you need to
use ``p.read(n)``.
How do I run a subprocess with pipes connected to both input and output?
------------------------------------------------------------------------
.. XXX update to use subprocess
Use the :mod:`popen2` module. For example::
import popen2
fromchild, tochild = popen2.popen2("command")
tochild.write("input\n")
tochild.flush()
output = fromchild.readline()
Warning: in general it is unwise to do this because you can easily cause a
deadlock where your process is blocked waiting for output from the child while
the child is blocked waiting for input from you. This can be caused by the
parent expecting the child to output more text than it does or by data being
stuck in stdio buffers due to lack of flushing. The Python parent
can of course explicitly flush the data it sends to the child before it reads
any output, but if the child is a naive C program it may have been written to
never explicitly flush its output, even if it is interactive, since flushing is
normally automatic.
Note that a deadlock is also possible if you use :func:`popen3` to read stdout
and stderr. If one of the two is too large for the internal buffer (increasing
the buffer size does not help) and you ``read()`` the other one first, there is
a deadlock, too.
Note on a bug in popen2: unless your program calls ``wait()`` or ``waitpid()``,
finished child processes are never removed, and eventually calls to popen2 will
fail because of a limit on the number of child processes. Calling
:func:`os.waitpid` with the :data:`os.WNOHANG` option can prevent this; a good
place to insert such a call would be before calling ``popen2`` again.
In many cases, all you really need is to run some data through a command and get
the result back. Unless the amount of data is very large, the easiest way to do
this is to write it to a temporary file and run the command with that temporary
file as input. The standard module :mod:`tempfile` exports a
:func:`~tempfile.mktemp` function to generate unique temporary file names. ::
import tempfile
import os
class Popen3:
"""
This is a deadlock-safe version of popen that returns
an object with errorlevel, out (a string) and err (a string).
(capturestderr may not work under windows.)
Example: print Popen3('grep spam','\n\nhere spam\n\n').out
"""
def __init__(self,command,input=None,capturestderr=None):
outfile=tempfile.mktemp()
command="( %s ) > %s" % (command,outfile)
if input:
infile=tempfile.mktemp()
open(infile,"w").write(input)
command=command+" <"+infile
if capturestderr:
errfile=tempfile.mktemp()
command=command+" 2>"+errfile
self.errorlevel=os.system(command) >> 8
self.out=open(outfile,"r").read()
os.remove(outfile)
if input:
os.remove(infile)
if capturestderr:
self.err=open(errfile,"r").read()
os.remove(errfile)
Note that many interactive programs (e.g. vi) don't work well with pipes
substituted for standard input and output. You will have to use pseudo ttys
("ptys") instead of pipes. Or you can use a Python interface to Don Libes'
"expect" library. A Python extension that interfaces to expect is called "expy"
and available from http://expectpy.sourceforge.net. A pure Python solution that
works like expect is `pexpect <https://pypi.org/project/pexpect/>`_.
How do I access the serial (RS232) port?
----------------------------------------
For Win32, POSIX (Linux, BSD, etc.), Jython:
http://pyserial.sourceforge.net
For Unix, see a Usenet post by Mitch Chapman:
https://groups.google.com/groups?selm=34A04430.CF9@ohioee.com
Why doesn't closing sys.stdout (stdin, stderr) really close it?
---------------------------------------------------------------
Python file objects are a high-level layer of abstraction on top of C streams,
which in turn are a medium-level layer of abstraction on top of (among other
things) low-level C file descriptors.
For most file objects you create in Python via the built-in ``file``
constructor, ``f.close()`` marks the Python file object as being closed from
Python's point of view, and also arranges to close the underlying C stream.
This also happens automatically in ``f``'s destructor, when ``f`` becomes
garbage.
But stdin, stdout and stderr are treated specially by Python, because of the
special status also given to them by C. Running ``sys.stdout.close()`` marks
the Python-level file object as being closed, but does *not* close the
associated C stream.
To close the underlying C stream for one of these three, you should first be
sure that's what you really want to do (e.g., you may confuse extension modules
trying to do I/O). If it is, use os.close::
os.close(0) # close C's stdin stream
os.close(1) # close C's stdout stream
os.close(2) # close C's stderr stream
Network/Internet Programming
============================
What WWW tools are there for Python?
------------------------------------
See the chapters titled :ref:`internet` and :ref:`netdata` in the Library
Reference Manual. Python has many modules that will help you build server-side
and client-side web systems.
.. XXX check if wiki page is still up to date
A summary of available frameworks is maintained by Paul Boddie at
https://wiki.python.org/moin/WebProgramming\ .
Cameron Laird maintains a useful set of pages about Python web technologies at
http://phaseit.net/claird/comp.lang.python/web_python.
How can I mimic CGI form submission (METHOD=POST)?
--------------------------------------------------
I would like to retrieve web pages that are the result of POSTing a form. Is
there existing code that would let me do this easily?
Yes. Here's a simple example that uses httplib::
#!/usr/local/bin/python
import httplib, sys, time
# build the query string
qs = "First=Josephine&MI=Q&Last=Public"
# connect and send the server a path
httpobj = httplib.HTTP('www.some-server.out-there', 80)
httpobj.putrequest('POST', '/cgi-bin/some-cgi-script')
# now generate the rest of the HTTP headers...
httpobj.putheader('Accept', '*/*')
httpobj.putheader('Connection', 'Keep-Alive')
httpobj.putheader('Content-type', 'application/x-www-form-urlencoded')
httpobj.putheader('Content-length', '%d' % len(qs))
httpobj.endheaders()
httpobj.send(qs)
# find out what the server said in response...
reply, msg, hdrs = httpobj.getreply()
if reply != 200:
sys.stdout.write(httpobj.getfile().read())
Note that in general for percent-encoded POST operations, query strings must be
quoted using :func:`urllib.urlencode`. For example, to send
``name=Guy Steele, Jr.``::
>>> import urllib
>>> urllib.urlencode({'name': 'Guy Steele, Jr.'})
'name=Guy+Steele%2C+Jr.'
What module should I use to help with generating HTML?
------------------------------------------------------
.. XXX add modern template languages
You can find a collection of useful links on the `Web Programming wiki page
<https://wiki.python.org/moin/WebProgramming>`_.
How do I send mail from a Python script?
----------------------------------------
Use the standard library module :mod:`smtplib`.
Here's a very simple interactive mail sender that uses it. This method will
work on any host that supports an SMTP listener. ::
import sys, smtplib
fromaddr = raw_input("From: ")
toaddrs = raw_input("To: ").split(',')
print "Enter message, end with ^D:"
msg = ''
while True:
line = sys.stdin.readline()
if not line:
break
msg += line
# The actual mail send
server = smtplib.SMTP('localhost')
server.sendmail(fromaddr, toaddrs, msg)
server.quit()
A Unix-only alternative uses sendmail. The location of the sendmail program
varies between systems; sometimes it is ``/usr/lib/sendmail``, sometimes
``/usr/sbin/sendmail``. The sendmail manual page will help you out. Here's
some sample code::
import os
SENDMAIL = "/usr/sbin/sendmail" # sendmail location
p = os.popen("%s -t -i" % SENDMAIL, "w")
p.write("To: receiver@example.com\n")
p.write("Subject: test\n")
p.write("\n") # blank line separating headers from body
p.write("Some text\n")
p.write("some more text\n")
sts = p.close()
if sts != 0:
print "Sendmail exit status", sts
How do I avoid blocking in the connect() method of a socket?
------------------------------------------------------------
The select module is commonly used to help with asynchronous I/O on sockets.
To prevent the TCP connect from blocking, you can set the socket to non-blocking
mode. Then when you do the ``connect()``, you will either connect immediately
(unlikely) or get an exception that contains the error number as ``.errno``.
``errno.EINPROGRESS`` indicates that the connection is in progress, but hasn't
finished yet. Different OSes will return different values, so you're going to
have to check what's returned on your system.
You can use the ``connect_ex()`` method to avoid creating an exception. It will
just return the errno value. To poll, you can call ``connect_ex()`` again later
-- 0 or ``errno.EISCONN`` indicate that you're connected -- or you can pass this
socket to select to check if it's writable.
Databases
=========
Are there any interfaces to database packages in Python?
--------------------------------------------------------
Yes.
.. XXX remove bsddb in py3k, fix other module names
Python 2.3 includes the :mod:`bsddb` package which provides an interface to the
BerkeleyDB library. Interfaces to disk-based hashes such as :mod:`DBM <dbm>`
and :mod:`GDBM <gdbm>` are also included with standard Python.
Support for most relational databases is available. See the
`DatabaseProgramming wiki page
<https://wiki.python.org/moin/DatabaseProgramming>`_ for details.
How do you implement persistent objects in Python?
--------------------------------------------------
The :mod:`pickle` library module solves this in a very general way (though you
still can't store things like open files, sockets or windows), and the
:mod:`shelve` library module uses pickle and (g)dbm to create persistent
mappings containing arbitrary Python objects. For better performance, you can
use the :mod:`cPickle` module.
A more awkward way of doing things is to use pickle's little sister, marshal.
The :mod:`marshal` module provides very fast ways to store noncircular basic
Python types to files and strings, and back again. Although marshal does not do
fancy things like store instances or handle shared references properly, it does
run extremely fast. For example, loading a half megabyte of data may take less
than a third of a second. This often beats doing something more complex and
general such as using gdbm with pickle/shelve.
Why is cPickle so slow?
-----------------------
.. XXX update this, default protocol is 2/3
By default :mod:`pickle` uses a relatively old and slow format for backward
compatibility. You can however specify other protocol versions that are
faster::
largeString = 'z' * (100 * 1024)
myPickle = cPickle.dumps(largeString, protocol=1)
If my program crashes with a bsddb (or anydbm) database open, it gets corrupted. How come?
------------------------------------------------------------------------------------------
Databases opened for write access with the bsddb module (and often by the anydbm
module, since it will preferentially use bsddb) must explicitly be closed using
the ``.close()`` method of the database. The underlying library caches database
contents which need to be converted to on-disk form and written.
If you have initialized a new bsddb database but not written anything to it
before the program crashes, you will often wind up with a zero-length file and
encounter an exception the next time the file is opened.
I tried to open Berkeley DB file, but bsddb produces bsddb.error: (22, 'Invalid argument'). Help! How can I restore my data?
----------------------------------------------------------------------------------------------------------------------------
Don't panic! Your data is probably intact. The most frequent cause for the error
is that you tried to open an earlier Berkeley DB file with a later version of
the Berkeley DB library.
Many Linux systems now have all three versions of Berkeley DB available. If you
are migrating from version 1 to a newer version use db_dump185 to dump a plain
text version of the database. If you are migrating from version 2 to version 3
use db2_dump to create a plain text version of the database. In either case,
use db_load to create a new native database for the latest version installed on
your computer. If you have version 3 of Berkeley DB installed, you should be
able to use db2_load to create a native version 2 database.
You should move away from Berkeley DB version 1 files because the hash file code
contains known bugs that can corrupt your data.
Mathematics and Numerics
========================
How do I generate random numbers in Python?
-------------------------------------------
The standard module :mod:`random` implements a random number generator. Usage
is simple::
import random
random.random()
This returns a random floating point number in the range [0, 1).
There are also many other specialized generators in this module, such as:
* ``randrange(a, b)`` chooses an integer in the range [a, b).
* ``uniform(a, b)`` chooses a floating point number in the range [a, b).
* ``normalvariate(mean, sdev)`` samples the normal (Gaussian) distribution.
Some higher-level functions operate on sequences directly, such as:
* ``choice(S)`` chooses random element from a given sequence
* ``shuffle(L)`` shuffles a list in-place, i.e. permutes it randomly
There's also a ``Random`` class you can instantiate to create independent
multiple random number generators.
PK %�\����" " % html/_sources/faq/programming.rst.txtnu �[��� :tocdepth: 2
===============
Programming FAQ
===============
.. only:: html
.. contents::
General Questions
=================
Is there a source code level debugger with breakpoints, single-stepping, etc.?
------------------------------------------------------------------------------
Yes.
The pdb module is a simple but adequate console-mode debugger for Python. It is
part of the standard Python library, and is :mod:`documented in the Library
Reference Manual <pdb>`. You can also write your own debugger by using the code
for pdb as an example.
The IDLE interactive development environment, which is part of the standard
Python distribution (normally available as Tools/scripts/idle), includes a
graphical debugger.
PythonWin is a Python IDE that includes a GUI debugger based on pdb. The
Pythonwin debugger colors breakpoints and has quite a few cool features such as
debugging non-Pythonwin programs. Pythonwin is available as part of the `Python
for Windows Extensions <https://sourceforge.net/projects/pywin32/>`__ project and
as a part of the ActivePython distribution (see
https://www.activestate.com/activepython\ ).
`Boa Constructor <http://boa-constructor.sourceforge.net/>`_ is an IDE and GUI
builder that uses wxWidgets. It offers visual frame creation and manipulation,
an object inspector, many views on the source like object browsers, inheritance
hierarchies, doc string generated html documentation, an advanced debugger,
integrated help, and Zope support.
`Eric <http://eric-ide.python-projects.org/>`_ is an IDE built on PyQt
and the Scintilla editing component.
Pydb is a version of the standard Python debugger pdb, modified for use with DDD
(Data Display Debugger), a popular graphical debugger front end. Pydb can be
found at http://bashdb.sourceforge.net/pydb/ and DDD can be found at
https://www.gnu.org/software/ddd.
There are a number of commercial Python IDEs that include graphical debuggers.
They include:
* Wing IDE (https://wingware.com/)
* Komodo IDE (https://komodoide.com/)
* PyCharm (https://www.jetbrains.com/pycharm/)
Is there a tool to help find bugs or perform static analysis?
-------------------------------------------------------------
Yes.
PyChecker is a static analysis tool that finds bugs in Python source code and
warns about code complexity and style. You can get PyChecker from
http://pychecker.sourceforge.net/.
`Pylint <https://www.pylint.org/>`_ is another tool that checks
if a module satisfies a coding standard, and also makes it possible to write
plug-ins to add a custom feature. In addition to the bug checking that
PyChecker performs, Pylint offers some additional features such as checking line
length, whether variable names are well-formed according to your coding
standard, whether declared interfaces are fully implemented, and more.
https://docs.pylint.org/ provides a full list of Pylint's features.
How can I create a stand-alone binary from a Python script?
-----------------------------------------------------------
You don't need the ability to compile Python to C code if all you want is a
stand-alone program that users can download and run without having to install
the Python distribution first. There are a number of tools that determine the
set of modules required by a program and bind these modules together with a
Python binary to produce a single executable.
One is to use the freeze tool, which is included in the Python source tree as
``Tools/freeze``. It converts Python byte code to C arrays; a C compiler you can
embed all your modules into a new program, which is then linked with the
standard Python modules.
It works by scanning your source recursively for import statements (in both
forms) and looking for the modules in the standard Python path as well as in the
source directory (for built-in modules). It then turns the bytecode for modules
written in Python into C code (array initializers that can be turned into code
objects using the marshal module) and creates a custom-made config file that
only contains those built-in modules which are actually used in the program. It
then compiles the generated C code and links it with the rest of the Python
interpreter to form a self-contained binary which acts exactly like your script.
Obviously, freeze requires a C compiler. There are several other utilities
which don't. One is Thomas Heller's py2exe (Windows only) at
http://www.py2exe.org/
Another tool is Anthony Tuininga's `cx_Freeze <http://cx-freeze.sourceforge.net/>`_.
Are there coding standards or a style guide for Python programs?
----------------------------------------------------------------
Yes. The coding style required for standard library modules is documented as
:pep:`8`.
My program is too slow. How do I speed it up?
---------------------------------------------
That's a tough one, in general. There are many tricks to speed up Python code;
consider rewriting parts in C as a last resort.
In some cases it's possible to automatically translate Python to C or x86
assembly language, meaning that you don't have to modify your code to gain
increased speed.
.. XXX seems to have overlap with other questions!
`Pyrex <http://www.cosc.canterbury.ac.nz/~greg/python/Pyrex/>`_ can compile a
slightly modified version of Python code into a C extension, and can be used on
many different platforms.
`Psyco <http://psyco.sourceforge.net>`_ is a just-in-time compiler that
translates Python code into x86 assembly language. If you can use it, Psyco can
provide dramatic speedups for critical functions.
The rest of this answer will discuss various tricks for squeezing a bit more
speed out of Python code. *Never* apply any optimization tricks unless you know
you need them, after profiling has indicated that a particular function is the
heavily executed hot spot in the code. Optimizations almost always make the
code less clear, and you shouldn't pay the costs of reduced clarity (increased
development time, greater likelihood of bugs) unless the resulting performance
benefit is worth it.
There is a page on the wiki devoted to `performance tips
<https://wiki.python.org/moin/PythonSpeed/PerformanceTips>`_.
Guido van Rossum has written up an anecdote related to optimization at
https://www.python.org/doc/essays/list2str.
One thing to notice is that function and (especially) method calls are rather
expensive; if you have designed a purely OO interface with lots of tiny
functions that don't do much more than get or set an instance variable or call
another method, you might consider using a more direct way such as directly
accessing instance variables. Also see the standard module :mod:`profile` which
makes it possible to find out where your program is spending most of its time
(if you have some patience -- the profiling itself can slow your program down by
an order of magnitude).
Remember that many standard optimization heuristics you may know from other
programming experience may well apply to Python. For example it may be faster
to send output to output devices using larger writes rather than smaller ones in
order to reduce the overhead of kernel system calls. Thus CGI scripts that
write all output in "one shot" may be faster than those that write lots of small
pieces of output.
Also, be sure to use Python's core features where appropriate. For example,
slicing allows programs to chop up lists and other sequence objects in a single
tick of the interpreter's mainloop using highly optimized C implementations.
Thus to get the same effect as::
L2 = []
for i in range(3):
L2.append(L1[i])
it is much shorter and far faster to use ::
L2 = list(L1[:3]) # "list" is redundant if L1 is a list.
Note that the functionally-oriented built-in functions such as :func:`map`,
:func:`zip`, and friends can be a convenient accelerator for loops that
perform a single task. For example to pair the elements of two lists
together::
>>> zip([1, 2, 3], [4, 5, 6])
[(1, 4), (2, 5), (3, 6)]
or to compute a number of sines::
>>> map(math.sin, (1, 2, 3, 4))
[0.841470984808, 0.909297426826, 0.14112000806, -0.756802495308]
The operation completes very quickly in such cases.
Other examples include the ``join()`` and ``split()`` :ref:`methods
of string objects <string-methods>`.
For example if s1..s7 are large (10K+) strings then
``"".join([s1,s2,s3,s4,s5,s6,s7])`` may be far faster than the more obvious
``s1+s2+s3+s4+s5+s6+s7``, since the "summation" will compute many
subexpressions, whereas ``join()`` does all the copying in one pass. For
manipulating strings, use the ``replace()`` and the ``format()`` :ref:`methods
on string objects <string-methods>`. Use regular expressions only when you're
not dealing with constant string patterns. You may still use :ref:`the old %
operations <string-formatting>` ``string % tuple`` and ``string % dictionary``.
Be sure to use the :meth:`list.sort` built-in method to do sorting, and see the
`sorting mini-HOWTO <https://wiki.python.org/moin/HowTo/Sorting>`_ for examples
of moderately advanced usage. :meth:`list.sort` beats other techniques for
sorting in all but the most extreme circumstances.
Another common trick is to "push loops into functions or methods." For example
suppose you have a program that runs slowly and you use the profiler to
determine that a Python function ``ff()`` is being called lots of times. If you
notice that ``ff()``::
def ff(x):
... # do something with x computing result...
return result
tends to be called in loops like::
list = map(ff, oldlist)
or::
for x in sequence:
value = ff(x)
... # do something with value...
then you can often eliminate function call overhead by rewriting ``ff()`` to::
def ffseq(seq):
resultseq = []
for x in seq:
... # do something with x computing result...
resultseq.append(result)
return resultseq
and rewrite the two examples to ``list = ffseq(oldlist)`` and to::
for value in ffseq(sequence):
... # do something with value...
Single calls to ``ff(x)`` translate to ``ffseq([x])[0]`` with little penalty.
Of course this technique is not always appropriate and there are other variants
which you can figure out.
You can gain some performance by explicitly storing the results of a function or
method lookup into a local variable. A loop like::
for key in token:
dict[key] = dict.get(key, 0) + 1
resolves ``dict.get`` every iteration. If the method isn't going to change, a
slightly faster implementation is::
dict_get = dict.get # look up the method once
for key in token:
dict[key] = dict_get(key, 0) + 1
Default arguments can be used to determine values once, at compile time instead
of at run time. This can only be done for functions or objects which will not
be changed during program execution, such as replacing ::
def degree_sin(deg):
return math.sin(deg * math.pi / 180.0)
with ::
def degree_sin(deg, factor=math.pi/180.0, sin=math.sin):
return sin(deg * factor)
Because this trick uses default arguments for terms which should not be changed,
it should only be used when you are not concerned with presenting a possibly
confusing API to your users.
Core Language
=============
Why am I getting an UnboundLocalError when the variable has a value?
--------------------------------------------------------------------
It can be a surprise to get the UnboundLocalError in previously working
code when it is modified by adding an assignment statement somewhere in
the body of a function.
This code:
>>> x = 10
>>> def bar():
... print x
>>> bar()
10
works, but this code:
>>> x = 10
>>> def foo():
... print x
... x += 1
results in an UnboundLocalError:
>>> foo()
Traceback (most recent call last):
...
UnboundLocalError: local variable 'x' referenced before assignment
This is because when you make an assignment to a variable in a scope, that
variable becomes local to that scope and shadows any similarly named variable
in the outer scope. Since the last statement in foo assigns a new value to
``x``, the compiler recognizes it as a local variable. Consequently when the
earlier ``print x`` attempts to print the uninitialized local variable and
an error results.
In the example above you can access the outer scope variable by declaring it
global:
>>> x = 10
>>> def foobar():
... global x
... print x
... x += 1
>>> foobar()
10
This explicit declaration is required in order to remind you that (unlike the
superficially analogous situation with class and instance variables) you are
actually modifying the value of the variable in the outer scope:
>>> print x
11
What are the rules for local and global variables in Python?
------------------------------------------------------------
In Python, variables that are only referenced inside a function are implicitly
global. If a variable is assigned a value anywhere within the function's body,
it's assumed to be a local unless explicitly declared as global.
Though a bit surprising at first, a moment's consideration explains this. On
one hand, requiring :keyword:`global` for assigned variables provides a bar
against unintended side-effects. On the other hand, if ``global`` was required
for all global references, you'd be using ``global`` all the time. You'd have
to declare as global every reference to a built-in function or to a component of
an imported module. This clutter would defeat the usefulness of the ``global``
declaration for identifying side-effects.
Why do lambdas defined in a loop with different values all return the same result?
----------------------------------------------------------------------------------
Assume you use a for loop to define a few different lambdas (or even plain
functions), e.g.::
>>> squares = []
>>> for x in range(5):
... squares.append(lambda: x**2)
This gives you a list that contains 5 lambdas that calculate ``x**2``. You
might expect that, when called, they would return, respectively, ``0``, ``1``,
``4``, ``9``, and ``16``. However, when you actually try you will see that
they all return ``16``::
>>> squares[2]()
16
>>> squares[4]()
16
This happens because ``x`` is not local to the lambdas, but is defined in
the outer scope, and it is accessed when the lambda is called --- not when it
is defined. At the end of the loop, the value of ``x`` is ``4``, so all the
functions now return ``4**2``, i.e. ``16``. You can also verify this by
changing the value of ``x`` and see how the results of the lambdas change::
>>> x = 8
>>> squares[2]()
64
In order to avoid this, you need to save the values in variables local to the
lambdas, so that they don't rely on the value of the global ``x``::
>>> squares = []
>>> for x in range(5):
... squares.append(lambda n=x: n**2)
Here, ``n=x`` creates a new variable ``n`` local to the lambda and computed
when the lambda is defined so that it has the same value that ``x`` had at
that point in the loop. This means that the value of ``n`` will be ``0``
in the first lambda, ``1`` in the second, ``2`` in the third, and so on.
Therefore each lambda will now return the correct result::
>>> squares[2]()
4
>>> squares[4]()
16
Note that this behaviour is not peculiar to lambdas, but applies to regular
functions too.
How do I share global variables across modules?
------------------------------------------------
The canonical way to share information across modules within a single program is
to create a special module (often called config or cfg). Just import the config
module in all modules of your application; the module then becomes available as
a global name. Because there is only one instance of each module, any changes
made to the module object get reflected everywhere. For example:
config.py::
x = 0 # Default value of the 'x' configuration setting
mod.py::
import config
config.x = 1
main.py::
import config
import mod
print config.x
Note that using a module is also the basis for implementing the Singleton design
pattern, for the same reason.
What are the "best practices" for using import in a module?
-----------------------------------------------------------
In general, don't use ``from modulename import *``. Doing so clutters the
importer's namespace, and makes it much harder for linters to detect undefined
names.
Import modules at the top of a file. Doing so makes it clear what other modules
your code requires and avoids questions of whether the module name is in scope.
Using one import per line makes it easy to add and delete module imports, but
using multiple imports per line uses less screen space.
It's good practice if you import modules in the following order:
1. standard library modules -- e.g. ``sys``, ``os``, ``getopt``, ``re``
2. third-party library modules (anything installed in Python's site-packages
directory) -- e.g. mx.DateTime, ZODB, PIL.Image, etc.
3. locally-developed modules
Only use explicit relative package imports. If you're writing code that's in
the ``package.sub.m1`` module and want to import ``package.sub.m2``, do not just
write ``import m2``, even though it's legal. Write ``from package.sub import
m2`` or ``from . import m2`` instead.
It is sometimes necessary to move imports to a function or class to avoid
problems with circular imports. Gordon McMillan says:
Circular imports are fine where both modules use the "import <module>" form
of import. They fail when the 2nd module wants to grab a name out of the
first ("from module import name") and the import is at the top level. That's
because names in the 1st are not yet available, because the first module is
busy importing the 2nd.
In this case, if the second module is only used in one function, then the import
can easily be moved into that function. By the time the import is called, the
first module will have finished initializing, and the second module can do its
import.
It may also be necessary to move imports out of the top level of code if some of
the modules are platform-specific. In that case, it may not even be possible to
import all of the modules at the top of the file. In this case, importing the
correct modules in the corresponding platform-specific code is a good option.
Only move imports into a local scope, such as inside a function definition, if
it's necessary to solve a problem such as avoiding a circular import or are
trying to reduce the initialization time of a module. This technique is
especially helpful if many of the imports are unnecessary depending on how the
program executes. You may also want to move imports into a function if the
modules are only ever used in that function. Note that loading a module the
first time may be expensive because of the one time initialization of the
module, but loading a module multiple times is virtually free, costing only a
couple of dictionary lookups. Even if the module name has gone out of scope,
the module is probably available in :data:`sys.modules`.
Why are default values shared between objects?
----------------------------------------------
This type of bug commonly bites neophyte programmers. Consider this function::
def foo(mydict={}): # Danger: shared reference to one dict for all calls
... compute something ...
mydict[key] = value
return mydict
The first time you call this function, ``mydict`` contains a single item. The
second time, ``mydict`` contains two items because when ``foo()`` begins
executing, ``mydict`` starts out with an item already in it.
It is often expected that a function call creates new objects for default
values. This is not what happens. Default values are created exactly once, when
the function is defined. If that object is changed, like the dictionary in this
example, subsequent calls to the function will refer to this changed object.
By definition, immutable objects such as numbers, strings, tuples, and ``None``,
are safe from change. Changes to mutable objects such as dictionaries, lists,
and class instances can lead to confusion.
Because of this feature, it is good programming practice to not use mutable
objects as default values. Instead, use ``None`` as the default value and
inside the function, check if the parameter is ``None`` and create a new
list/dictionary/whatever if it is. For example, don't write::
def foo(mydict={}):
...
but::
def foo(mydict=None):
if mydict is None:
mydict = {} # create a new dict for local namespace
This feature can be useful. When you have a function that's time-consuming to
compute, a common technique is to cache the parameters and the resulting value
of each call to the function, and return the cached value if the same value is
requested again. This is called "memoizing", and can be implemented like this::
# Callers will never provide a third parameter for this function.
def expensive(arg1, arg2, _cache={}):
if (arg1, arg2) in _cache:
return _cache[(arg1, arg2)]
# Calculate the value
result = ... expensive computation ...
_cache[(arg1, arg2)] = result # Store result in the cache
return result
You could use a global variable containing a dictionary instead of the default
value; it's a matter of taste.
How can I pass optional or keyword parameters from one function to another?
---------------------------------------------------------------------------
Collect the arguments using the ``*`` and ``**`` specifiers in the function's
parameter list; this gives you the positional arguments as a tuple and the
keyword arguments as a dictionary. You can then pass these arguments when
calling another function by using ``*`` and ``**``::
def f(x, *args, **kwargs):
...
kwargs['width'] = '14.3c'
...
g(x, *args, **kwargs)
In the unlikely case that you care about Python versions older than 2.0, use
:func:`apply`::
def f(x, *args, **kwargs):
...
kwargs['width'] = '14.3c'
...
apply(g, (x,)+args, kwargs)
.. index::
single: argument; difference from parameter
single: parameter; difference from argument
.. _faq-argument-vs-parameter:
What is the difference between arguments and parameters?
--------------------------------------------------------
:term:`Parameters <parameter>` are defined by the names that appear in a
function definition, whereas :term:`arguments <argument>` are the values
actually passed to a function when calling it. Parameters define what types of
arguments a function can accept. For example, given the function definition::
def func(foo, bar=None, **kwargs):
pass
*foo*, *bar* and *kwargs* are parameters of ``func``. However, when calling
``func``, for example::
func(42, bar=314, extra=somevar)
the values ``42``, ``314``, and ``somevar`` are arguments.
Why did changing list 'y' also change list 'x'?
------------------------------------------------
If you wrote code like::
>>> x = []
>>> y = x
>>> y.append(10)
>>> y
[10]
>>> x
[10]
you might be wondering why appending an element to ``y`` changed ``x`` too.
There are two factors that produce this result:
1) Variables are simply names that refer to objects. Doing ``y = x`` doesn't
create a copy of the list -- it creates a new variable ``y`` that refers to
the same object ``x`` refers to. This means that there is only one object
(the list), and both ``x`` and ``y`` refer to it.
2) Lists are :term:`mutable`, which means that you can change their content.
After the call to :meth:`~list.append`, the content of the mutable object has
changed from ``[]`` to ``[10]``. Since both the variables refer to the same
object, using either name accesses the modified value ``[10]``.
If we instead assign an immutable object to ``x``::
>>> x = 5 # ints are immutable
>>> y = x
>>> x = x + 1 # 5 can't be mutated, we are creating a new object here
>>> x
6
>>> y
5
we can see that in this case ``x`` and ``y`` are not equal anymore. This is
because integers are :term:`immutable`, and when we do ``x = x + 1`` we are not
mutating the int ``5`` by incrementing its value; instead, we are creating a
new object (the int ``6``) and assigning it to ``x`` (that is, changing which
object ``x`` refers to). After this assignment we have two objects (the ints
``6`` and ``5``) and two variables that refer to them (``x`` now refers to
``6`` but ``y`` still refers to ``5``).
Some operations (for example ``y.append(10)`` and ``y.sort()``) mutate the
object, whereas superficially similar operations (for example ``y = y + [10]``
and ``sorted(y)``) create a new object. In general in Python (and in all cases
in the standard library) a method that mutates an object will return ``None``
to help avoid getting the two types of operations confused. So if you
mistakenly write ``y.sort()`` thinking it will give you a sorted copy of ``y``,
you'll instead end up with ``None``, which will likely cause your program to
generate an easily diagnosed error.
However, there is one class of operations where the same operation sometimes
has different behaviors with different types: the augmented assignment
operators. For example, ``+=`` mutates lists but not tuples or ints (``a_list
+= [1, 2, 3]`` is equivalent to ``a_list.extend([1, 2, 3])`` and mutates
``a_list``, whereas ``some_tuple += (1, 2, 3)`` and ``some_int += 1`` create
new objects).
In other words:
* If we have a mutable object (:class:`list`, :class:`dict`, :class:`set`,
etc.), we can use some specific operations to mutate it and all the variables
that refer to it will see the change.
* If we have an immutable object (:class:`str`, :class:`int`, :class:`tuple`,
etc.), all the variables that refer to it will always see the same value,
but operations that transform that value into a new value always return a new
object.
If you want to know if two variables refer to the same object or not, you can
use the :keyword:`is` operator, or the built-in function :func:`id`.
How do I write a function with output parameters (call by reference)?
---------------------------------------------------------------------
Remember that arguments are passed by assignment in Python. Since assignment
just creates references to objects, there's no alias between an argument name in
the caller and callee, and so no call-by-reference per se. You can achieve the
desired effect in a number of ways.
1) By returning a tuple of the results::
def func2(a, b):
a = 'new-value' # a and b are local names
b = b + 1 # assigned to new objects
return a, b # return new values
x, y = 'old-value', 99
x, y = func2(x, y)
print x, y # output: new-value 100
This is almost always the clearest solution.
2) By using global variables. This isn't thread-safe, and is not recommended.
3) By passing a mutable (changeable in-place) object::
def func1(a):
a[0] = 'new-value' # 'a' references a mutable list
a[1] = a[1] + 1 # changes a shared object
args = ['old-value', 99]
func1(args)
print args[0], args[1] # output: new-value 100
4) By passing in a dictionary that gets mutated::
def func3(args):
args['a'] = 'new-value' # args is a mutable dictionary
args['b'] = args['b'] + 1 # change it in-place
args = {'a': 'old-value', 'b': 99}
func3(args)
print args['a'], args['b']
5) Or bundle up values in a class instance::
class callByRef:
def __init__(self, **args):
for (key, value) in args.items():
setattr(self, key, value)
def func4(args):
args.a = 'new-value' # args is a mutable callByRef
args.b = args.b + 1 # change object in-place
args = callByRef(a='old-value', b=99)
func4(args)
print args.a, args.b
There's almost never a good reason to get this complicated.
Your best choice is to return a tuple containing the multiple results.
How do you make a higher order function in Python?
--------------------------------------------------
You have two choices: you can use nested scopes or you can use callable objects.
For example, suppose you wanted to define ``linear(a,b)`` which returns a
function ``f(x)`` that computes the value ``a*x+b``. Using nested scopes::
def linear(a, b):
def result(x):
return a * x + b
return result
Or using a callable object::
class linear:
def __init__(self, a, b):
self.a, self.b = a, b
def __call__(self, x):
return self.a * x + self.b
In both cases, ::
taxes = linear(0.3, 2)
gives a callable object where ``taxes(10e6) == 0.3 * 10e6 + 2``.
The callable object approach has the disadvantage that it is a bit slower and
results in slightly longer code. However, note that a collection of callables
can share their signature via inheritance::
class exponential(linear):
# __init__ inherited
def __call__(self, x):
return self.a * (x ** self.b)
Object can encapsulate state for several methods::
class counter:
value = 0
def set(self, x):
self.value = x
def up(self):
self.value = self.value + 1
def down(self):
self.value = self.value - 1
count = counter()
inc, dec, reset = count.up, count.down, count.set
Here ``inc()``, ``dec()`` and ``reset()`` act like functions which share the
same counting variable.
How do I copy an object in Python?
----------------------------------
In general, try :func:`copy.copy` or :func:`copy.deepcopy` for the general case.
Not all objects can be copied, but most can.
Some objects can be copied more easily. Dictionaries have a :meth:`~dict.copy`
method::
newdict = olddict.copy()
Sequences can be copied by slicing::
new_l = l[:]
How can I find the methods or attributes of an object?
------------------------------------------------------
For an instance x of a user-defined class, ``dir(x)`` returns an alphabetized
list of the names containing the instance attributes and methods and attributes
defined by its class.
How can my code discover the name of an object?
-----------------------------------------------
Generally speaking, it can't, because objects don't really have names.
Essentially, assignment always binds a name to a value; The same is true of
``def`` and ``class`` statements, but in that case the value is a
callable. Consider the following code::
>>> class A:
... pass
...
>>> B = A
>>> a = B()
>>> b = a
>>> print b
<__main__.A instance at 0x16D07CC>
>>> print a
<__main__.A instance at 0x16D07CC>
Arguably the class has a name: even though it is bound to two names and invoked
through the name B the created instance is still reported as an instance of
class A. However, it is impossible to say whether the instance's name is a or
b, since both names are bound to the same value.
Generally speaking it should not be necessary for your code to "know the names"
of particular values. Unless you are deliberately writing introspective
programs, this is usually an indication that a change of approach might be
beneficial.
In comp.lang.python, Fredrik Lundh once gave an excellent analogy in answer to
this question:
The same way as you get the name of that cat you found on your porch: the cat
(object) itself cannot tell you its name, and it doesn't really care -- so
the only way to find out what it's called is to ask all your neighbours
(namespaces) if it's their cat (object)...
....and don't be surprised if you'll find that it's known by many names, or
no name at all!
What's up with the comma operator's precedence?
-----------------------------------------------
Comma is not an operator in Python. Consider this session::
>>> "a" in "b", "a"
(False, 'a')
Since the comma is not an operator, but a separator between expressions the
above is evaluated as if you had entered::
("a" in "b"), "a"
not::
"a" in ("b", "a")
The same is true of the various assignment operators (``=``, ``+=`` etc). They
are not truly operators but syntactic delimiters in assignment statements.
Is there an equivalent of C's "?:" ternary operator?
----------------------------------------------------
Yes, this feature was added in Python 2.5. The syntax would be as follows::
[on_true] if [expression] else [on_false]
x, y = 50, 25
small = x if x < y else y
For versions previous to 2.5 the answer would be 'No'.
Is it possible to write obfuscated one-liners in Python?
--------------------------------------------------------
Yes. Usually this is done by nesting :keyword:`lambda` within
:keyword:`lambda`. See the following three examples, due to Ulf Bartelt::
# Primes < 1000
print filter(None,map(lambda y:y*reduce(lambda x,y:x*y!=0,
map(lambda x,y=y:y%x,range(2,int(pow(y,0.5)+1))),1),range(2,1000)))
# First 10 Fibonacci numbers
print map(lambda x,f=lambda x,f:(f(x-1,f)+f(x-2,f)) if x>1 else 1: f(x,f),
range(10))
# Mandelbrot set
print (lambda Ru,Ro,Iu,Io,IM,Sx,Sy:reduce(lambda x,y:x+y,map(lambda y,
Iu=Iu,Io=Io,Ru=Ru,Ro=Ro,Sy=Sy,L=lambda yc,Iu=Iu,Io=Io,Ru=Ru,Ro=Ro,i=IM,
Sx=Sx,Sy=Sy:reduce(lambda x,y:x+y,map(lambda x,xc=Ru,yc=yc,Ru=Ru,Ro=Ro,
i=i,Sx=Sx,F=lambda xc,yc,x,y,k,f=lambda xc,yc,x,y,k,f:(k<=0)or (x*x+y*y
>=4.0) or 1+f(xc,yc,x*x-y*y+xc,2.0*x*y+yc,k-1,f):f(xc,yc,x,y,k,f):chr(
64+F(Ru+x*(Ro-Ru)/Sx,yc,0,0,i)),range(Sx))):L(Iu+y*(Io-Iu)/Sy),range(Sy
))))(-2.1, 0.7, -1.2, 1.2, 30, 80, 24)
# \___ ___/ \___ ___/ | | |__ lines on screen
# V V | |______ columns on screen
# | | |__________ maximum of "iterations"
# | |_________________ range on y axis
# |____________________________ range on x axis
Don't try this at home, kids!
Numbers and strings
===================
How do I specify hexadecimal and octal integers?
------------------------------------------------
To specify an octal digit, precede the octal value with a zero, and then a lower
or uppercase "o". For example, to set the variable "a" to the octal value "10"
(8 in decimal), type::
>>> a = 0o10
>>> a
8
Hexadecimal is just as easy. Simply precede the hexadecimal number with a zero,
and then a lower or uppercase "x". Hexadecimal digits can be specified in lower
or uppercase. For example, in the Python interpreter::
>>> a = 0xa5
>>> a
165
>>> b = 0XB2
>>> b
178
Why does -22 // 10 return -3?
-----------------------------
It's primarily driven by the desire that ``i % j`` have the same sign as ``j``.
If you want that, and also want::
i == (i // j) * j + (i % j)
then integer division has to return the floor. C also requires that identity to
hold, and then compilers that truncate ``i // j`` need to make ``i % j`` have
the same sign as ``i``.
There are few real use cases for ``i % j`` when ``j`` is negative. When ``j``
is positive, there are many, and in virtually all of them it's more useful for
``i % j`` to be ``>= 0``. If the clock says 10 now, what did it say 200 hours
ago? ``-190 % 12 == 2`` is useful; ``-190 % 12 == -10`` is a bug waiting to
bite.
.. note::
On Python 2, ``a / b`` returns the same as ``a // b`` if
``__future__.division`` is not in effect. This is also known as "classic"
division.
How do I convert a string to a number?
--------------------------------------
For integers, use the built-in :func:`int` type constructor, e.g. ``int('144')
== 144``. Similarly, :func:`float` converts to floating-point,
e.g. ``float('144') == 144.0``.
By default, these interpret the number as decimal, so that ``int('0144') ==
144`` and ``int('0x144')`` raises :exc:`ValueError`. ``int(string, base)`` takes
the base to convert from as a second optional argument, so ``int('0x144', 16) ==
324``. If the base is specified as 0, the number is interpreted using Python's
rules: a leading '0' indicates octal, and '0x' indicates a hex number.
Do not use the built-in function :func:`eval` if all you need is to convert
strings to numbers. :func:`eval` will be significantly slower and it presents a
security risk: someone could pass you a Python expression that might have
unwanted side effects. For example, someone could pass
``__import__('os').system("rm -rf $HOME")`` which would erase your home
directory.
:func:`eval` also has the effect of interpreting numbers as Python expressions,
so that e.g. ``eval('09')`` gives a syntax error because Python regards numbers
starting with '0' as octal (base 8).
How do I convert a number to a string?
--------------------------------------
To convert, e.g., the number 144 to the string '144', use the built-in type
constructor :func:`str`. If you want a hexadecimal or octal representation, use
the built-in functions :func:`hex` or :func:`oct`. For fancy formatting, see
the :ref:`formatstrings` section, e.g. ``"{:04d}".format(144)`` yields
``'0144'`` and ``"{:.3f}".format(1/3)`` yields ``'0.333'``. You may also use
:ref:`the % operator <string-formatting>` on strings. See the library reference
manual for details.
How do I modify a string in place?
----------------------------------
You can't, because strings are immutable. If you need an object with this
ability, try converting the string to a list or use the array module::
>>> import io
>>> s = "Hello, world"
>>> a = list(s)
>>> print a
['H', 'e', 'l', 'l', 'o', ',', ' ', 'w', 'o', 'r', 'l', 'd']
>>> a[7:] = list("there!")
>>> ''.join(a)
'Hello, there!'
>>> import array
>>> a = array.array('c', s)
>>> print a
array('c', 'Hello, world')
>>> a[0] = 'y'; print a
array('c', 'yello, world')
>>> a.tostring()
'yello, world'
How do I use strings to call functions/methods?
-----------------------------------------------
There are various techniques.
* The best is to use a dictionary that maps strings to functions. The primary
advantage of this technique is that the strings do not need to match the names
of the functions. This is also the primary technique used to emulate a case
construct::
def a():
pass
def b():
pass
dispatch = {'go': a, 'stop': b} # Note lack of parens for funcs
dispatch[get_input()]() # Note trailing parens to call function
* Use the built-in function :func:`getattr`::
import foo
getattr(foo, 'bar')()
Note that :func:`getattr` works on any object, including classes, class
instances, modules, and so on.
This is used in several places in the standard library, like this::
class Foo:
def do_foo(self):
...
def do_bar(self):
...
f = getattr(foo_instance, 'do_' + opname)
f()
* Use :func:`locals` or :func:`eval` to resolve the function name::
def myFunc():
print "hello"
fname = "myFunc"
f = locals()[fname]
f()
f = eval(fname)
f()
Note: Using :func:`eval` is slow and dangerous. If you don't have absolute
control over the contents of the string, someone could pass a string that
resulted in an arbitrary function being executed.
Is there an equivalent to Perl's chomp() for removing trailing newlines from strings?
-------------------------------------------------------------------------------------
Starting with Python 2.2, you can use ``S.rstrip("\r\n")`` to remove all
occurrences of any line terminator from the end of the string ``S`` without
removing other trailing whitespace. If the string ``S`` represents more than
one line, with several empty lines at the end, the line terminators for all the
blank lines will be removed::
>>> lines = ("line 1 \r\n"
... "\r\n"
... "\r\n")
>>> lines.rstrip("\n\r")
'line 1 '
Since this is typically only desired when reading text one line at a time, using
``S.rstrip()`` this way works well.
For older versions of Python, there are two partial substitutes:
- If you want to remove all trailing whitespace, use the ``rstrip()`` method of
string objects. This removes all trailing whitespace, not just a single
newline.
- Otherwise, if there is only one line in the string ``S``, use
``S.splitlines()[0]``.
Is there a scanf() or sscanf() equivalent?
------------------------------------------
Not as such.
For simple input parsing, the easiest approach is usually to split the line into
whitespace-delimited words using the :meth:`~str.split` method of string objects
and then convert decimal strings to numeric values using :func:`int` or
:func:`float`. ``split()`` supports an optional "sep" parameter which is useful
if the line uses something other than whitespace as a separator.
For more complicated input parsing, regular expressions are more powerful
than C's :c:func:`sscanf` and better suited for the task.
What does 'UnicodeError: ASCII [decoding,encoding] error: ordinal not in range(128)' mean?
------------------------------------------------------------------------------------------
This error indicates that your Python installation can handle only 7-bit ASCII
strings. There are a couple ways to fix or work around the problem.
If your programs must handle data in arbitrary character set encodings, the
environment the application runs in will generally identify the encoding of the
data it is handing you. You need to convert the input to Unicode data using
that encoding. For example, a program that handles email or web input will
typically find character set encoding information in Content-Type headers. This
can then be used to properly convert input data to Unicode. Assuming the string
referred to by ``value`` is encoded as UTF-8::
value = unicode(value, "utf-8")
will return a Unicode object. If the data is not correctly encoded as UTF-8,
the above call will raise a :exc:`UnicodeError` exception.
If you only want strings converted to Unicode which have non-ASCII data, you can
try converting them first assuming an ASCII encoding, and then generate Unicode
objects if that fails::
try:
x = unicode(value, "ascii")
except UnicodeError:
value = unicode(value, "utf-8")
else:
# value was valid ASCII data
pass
It's possible to set a default encoding in a file called ``sitecustomize.py``
that's part of the Python library. However, this isn't recommended because
changing the Python-wide default encoding may cause third-party extension
modules to fail.
Note that on Windows, there is an encoding known as "mbcs", which uses an
encoding specific to your current locale. In many cases, and particularly when
working with COM, this may be an appropriate default encoding to use.
Sequences (Tuples/Lists)
========================
How do I convert between tuples and lists?
------------------------------------------
The type constructor ``tuple(seq)`` converts any sequence (actually, any
iterable) into a tuple with the same items in the same order.
For example, ``tuple([1, 2, 3])`` yields ``(1, 2, 3)`` and ``tuple('abc')``
yields ``('a', 'b', 'c')``. If the argument is a tuple, it does not make a copy
but returns the same object, so it is cheap to call :func:`tuple` when you
aren't sure that an object is already a tuple.
The type constructor ``list(seq)`` converts any sequence or iterable into a list
with the same items in the same order. For example, ``list((1, 2, 3))`` yields
``[1, 2, 3]`` and ``list('abc')`` yields ``['a', 'b', 'c']``. If the argument
is a list, it makes a copy just like ``seq[:]`` would.
What's a negative index?
------------------------
Python sequences are indexed with positive numbers and negative numbers. For
positive numbers 0 is the first index 1 is the second index and so forth. For
negative indices -1 is the last index and -2 is the penultimate (next to last)
index and so forth. Think of ``seq[-n]`` as the same as ``seq[len(seq)-n]``.
Using negative indices can be very convenient. For example ``S[:-1]`` is all of
the string except for its last character, which is useful for removing the
trailing newline from a string.
How do I iterate over a sequence in reverse order?
--------------------------------------------------
Use the :func:`reversed` built-in function, which is new in Python 2.4::
for x in reversed(sequence):
... # do something with x ...
This won't touch your original sequence, but build a new copy with reversed
order to iterate over.
With Python 2.3, you can use an extended slice syntax::
for x in sequence[::-1]:
... # do something with x ...
How do you remove duplicates from a list?
-----------------------------------------
See the Python Cookbook for a long discussion of many ways to do this:
https://code.activestate.com/recipes/52560/
If you don't mind reordering the list, sort it and then scan from the end of the
list, deleting duplicates as you go::
if mylist:
mylist.sort()
last = mylist[-1]
for i in range(len(mylist)-2, -1, -1):
if last == mylist[i]:
del mylist[i]
else:
last = mylist[i]
If all elements of the list may be used as dictionary keys (i.e. they are all
hashable) this is often faster ::
d = {}
for x in mylist:
d[x] = 1
mylist = list(d.keys())
In Python 2.5 and later, the following is possible instead::
mylist = list(set(mylist))
This converts the list into a set, thereby removing duplicates, and then back
into a list.
How do you make an array in Python?
-----------------------------------
Use a list::
["this", 1, "is", "an", "array"]
Lists are equivalent to C or Pascal arrays in their time complexity; the primary
difference is that a Python list can contain objects of many different types.
The ``array`` module also provides methods for creating arrays of fixed types
with compact representations, but they are slower to index than lists. Also
note that the Numeric extensions and others define array-like structures with
various characteristics as well.
To get Lisp-style linked lists, you can emulate cons cells using tuples::
lisp_list = ("like", ("this", ("example", None) ) )
If mutability is desired, you could use lists instead of tuples. Here the
analogue of lisp car is ``lisp_list[0]`` and the analogue of cdr is
``lisp_list[1]``. Only do this if you're sure you really need to, because it's
usually a lot slower than using Python lists.
.. _faq-multidimensional-list:
How do I create a multidimensional list?
----------------------------------------
You probably tried to make a multidimensional array like this::
>>> A = [[None] * 2] * 3
This looks correct if you print it::
>>> A
[[None, None], [None, None], [None, None]]
But when you assign a value, it shows up in multiple places:
>>> A[0][0] = 5
>>> A
[[5, None], [5, None], [5, None]]
The reason is that replicating a list with ``*`` doesn't create copies, it only
creates references to the existing objects. The ``*3`` creates a list
containing 3 references to the same list of length two. Changes to one row will
show in all rows, which is almost certainly not what you want.
The suggested approach is to create a list of the desired length first and then
fill in each element with a newly created list::
A = [None] * 3
for i in range(3):
A[i] = [None] * 2
This generates a list containing 3 different lists of length two. You can also
use a list comprehension::
w, h = 2, 3
A = [[None] * w for i in range(h)]
Or, you can use an extension that provides a matrix datatype; `NumPy
<http://www.numpy.org/>`_ is the best known.
How do I apply a method to a sequence of objects?
-------------------------------------------------
Use a list comprehension::
result = [obj.method() for obj in mylist]
More generically, you can try the following function::
def method_map(objects, method, arguments):
"""method_map([a,b], "meth", (1,2)) gives [a.meth(1,2), b.meth(1,2)]"""
nobjects = len(objects)
methods = map(getattr, objects, [method]*nobjects)
return map(apply, methods, [arguments]*nobjects)
Why does a_tuple[i] += ['item'] raise an exception when the addition works?
---------------------------------------------------------------------------
This is because of a combination of the fact that augmented assignment
operators are *assignment* operators, and the difference between mutable and
immutable objects in Python.
This discussion applies in general when augmented assignment operators are
applied to elements of a tuple that point to mutable objects, but we'll use
a ``list`` and ``+=`` as our exemplar.
If you wrote::
>>> a_tuple = (1, 2)
>>> a_tuple[0] += 1
Traceback (most recent call last):
...
TypeError: 'tuple' object does not support item assignment
The reason for the exception should be immediately clear: ``1`` is added to the
object ``a_tuple[0]`` points to (``1``), producing the result object, ``2``,
but when we attempt to assign the result of the computation, ``2``, to element
``0`` of the tuple, we get an error because we can't change what an element of
a tuple points to.
Under the covers, what this augmented assignment statement is doing is
approximately this::
>>> result = a_tuple[0] + 1
>>> a_tuple[0] = result
Traceback (most recent call last):
...
TypeError: 'tuple' object does not support item assignment
It is the assignment part of the operation that produces the error, since a
tuple is immutable.
When you write something like::
>>> a_tuple = (['foo'], 'bar')
>>> a_tuple[0] += ['item']
Traceback (most recent call last):
...
TypeError: 'tuple' object does not support item assignment
The exception is a bit more surprising, and even more surprising is the fact
that even though there was an error, the append worked::
>>> a_tuple[0]
['foo', 'item']
To see why this happens, you need to know that (a) if an object implements an
``__iadd__`` magic method, it gets called when the ``+=`` augmented assignment
is executed, and its return value is what gets used in the assignment statement;
and (b) for lists, ``__iadd__`` is equivalent to calling ``extend`` on the list
and returning the list. That's why we say that for lists, ``+=`` is a
"shorthand" for ``list.extend``::
>>> a_list = []
>>> a_list += [1]
>>> a_list
[1]
This is equivalent to::
>>> result = a_list.__iadd__([1])
>>> a_list = result
The object pointed to by a_list has been mutated, and the pointer to the
mutated object is assigned back to ``a_list``. The end result of the
assignment is a no-op, since it is a pointer to the same object that ``a_list``
was previously pointing to, but the assignment still happens.
Thus, in our tuple example what is happening is equivalent to::
>>> result = a_tuple[0].__iadd__(['item'])
>>> a_tuple[0] = result
Traceback (most recent call last):
...
TypeError: 'tuple' object does not support item assignment
The ``__iadd__`` succeeds, and thus the list is extended, but even though
``result`` points to the same object that ``a_tuple[0]`` already points to,
that final assignment still results in an error, because tuples are immutable.
Dictionaries
============
How can I get a dictionary to display its keys in a consistent order?
---------------------------------------------------------------------
You can't. Dictionaries store their keys in an unpredictable order, so the
display order of a dictionary's elements will be similarly unpredictable.
This can be frustrating if you want to save a printable version to a file, make
some changes and then compare it with some other printed dictionary. In this
case, use the ``pprint`` module to pretty-print the dictionary; the items will
be presented in order sorted by the key.
A more complicated solution is to subclass ``dict`` to create a
``SortedDict`` class that prints itself in a predictable order. Here's one
simpleminded implementation of such a class::
class SortedDict(dict):
def __repr__(self):
keys = sorted(self.keys())
result = ("{!r}: {!r}".format(k, self[k]) for k in keys)
return "{{{}}}".format(", ".join(result))
__str__ = __repr__
This will work for many common situations you might encounter, though it's far
from a perfect solution. The largest flaw is that if some values in the
dictionary are also dictionaries, their values won't be presented in any
particular order.
I want to do a complicated sort: can you do a Schwartzian Transform in Python?
------------------------------------------------------------------------------
The technique, attributed to Randal Schwartz of the Perl community, sorts the
elements of a list by a metric which maps each element to its "sort value". In
Python, use the ``key`` argument for the :func:`sort()` function::
Isorted = L[:]
Isorted.sort(key=lambda s: int(s[10:15]))
How can I sort one list by values from another list?
----------------------------------------------------
Merge them into a single list of tuples, sort the resulting list, and then pick
out the element you want. ::
>>> list1 = ["what", "I'm", "sorting", "by"]
>>> list2 = ["something", "else", "to", "sort"]
>>> pairs = zip(list1, list2)
>>> pairs
[('what', 'something'), ("I'm", 'else'), ('sorting', 'to'), ('by', 'sort')]
>>> pairs.sort()
>>> result = [ x[1] for x in pairs ]
>>> result
['else', 'sort', 'to', 'something']
An alternative for the last step is::
>>> result = []
>>> for p in pairs: result.append(p[1])
If you find this more legible, you might prefer to use this instead of the final
list comprehension. However, it is almost twice as slow for long lists. Why?
First, the ``append()`` operation has to reallocate memory, and while it uses
some tricks to avoid doing that each time, it still has to do it occasionally,
and that costs quite a bit. Second, the expression "result.append" requires an
extra attribute lookup, and third, there's a speed reduction from having to make
all those function calls.
Objects
=======
What is a class?
----------------
A class is the particular object type created by executing a class statement.
Class objects are used as templates to create instance objects, which embody
both the data (attributes) and code (methods) specific to a datatype.
A class can be based on one or more other classes, called its base class(es). It
then inherits the attributes and methods of its base classes. This allows an
object model to be successively refined by inheritance. You might have a
generic ``Mailbox`` class that provides basic accessor methods for a mailbox,
and subclasses such as ``MboxMailbox``, ``MaildirMailbox``, ``OutlookMailbox``
that handle various specific mailbox formats.
What is a method?
-----------------
A method is a function on some object ``x`` that you normally call as
``x.name(arguments...)``. Methods are defined as functions inside the class
definition::
class C:
def meth(self, arg):
return arg * 2 + self.attribute
What is self?
-------------
Self is merely a conventional name for the first argument of a method. A method
defined as ``meth(self, a, b, c)`` should be called as ``x.meth(a, b, c)`` for
some instance ``x`` of the class in which the definition occurs; the called
method will think it is called as ``meth(x, a, b, c)``.
See also :ref:`why-self`.
How do I check if an object is an instance of a given class or of a subclass of it?
-----------------------------------------------------------------------------------
Use the built-in function ``isinstance(obj, cls)``. You can check if an object
is an instance of any of a number of classes by providing a tuple instead of a
single class, e.g. ``isinstance(obj, (class1, class2, ...))``, and can also
check whether an object is one of Python's built-in types, e.g.
``isinstance(obj, str)`` or ``isinstance(obj, (int, long, float, complex))``.
Note that most programs do not use :func:`isinstance` on user-defined classes
very often. If you are developing the classes yourself, a more proper
object-oriented style is to define methods on the classes that encapsulate a
particular behaviour, instead of checking the object's class and doing a
different thing based on what class it is. For example, if you have a function
that does something::
def search(obj):
if isinstance(obj, Mailbox):
... # code to search a mailbox
elif isinstance(obj, Document):
... # code to search a document
elif ...
A better approach is to define a ``search()`` method on all the classes and just
call it::
class Mailbox:
def search(self):
... # code to search a mailbox
class Document:
def search(self):
... # code to search a document
obj.search()
What is delegation?
-------------------
Delegation is an object oriented technique (also called a design pattern).
Let's say you have an object ``x`` and want to change the behaviour of just one
of its methods. You can create a new class that provides a new implementation
of the method you're interested in changing and delegates all other methods to
the corresponding method of ``x``.
Python programmers can easily implement delegation. For example, the following
class implements a class that behaves like a file but converts all written data
to uppercase::
class UpperOut:
def __init__(self, outfile):
self._outfile = outfile
def write(self, s):
self._outfile.write(s.upper())
def __getattr__(self, name):
return getattr(self._outfile, name)
Here the ``UpperOut`` class redefines the ``write()`` method to convert the
argument string to uppercase before calling the underlying
``self.__outfile.write()`` method. All other methods are delegated to the
underlying ``self.__outfile`` object. The delegation is accomplished via the
``__getattr__`` method; consult :ref:`the language reference <attribute-access>`
for more information about controlling attribute access.
Note that for more general cases delegation can get trickier. When attributes
must be set as well as retrieved, the class must define a :meth:`__setattr__`
method too, and it must do so carefully. The basic implementation of
:meth:`__setattr__` is roughly equivalent to the following::
class X:
...
def __setattr__(self, name, value):
self.__dict__[name] = value
...
Most :meth:`__setattr__` implementations must modify ``self.__dict__`` to store
local state for self without causing an infinite recursion.
How do I call a method defined in a base class from a derived class that overrides it?
--------------------------------------------------------------------------------------
If you're using new-style classes, use the built-in :func:`super` function::
class Derived(Base):
def meth(self):
super(Derived, self).meth()
If you're using classic classes: For a class definition such as ``class
Derived(Base): ...`` you can call method ``meth()`` defined in ``Base`` (or one
of ``Base``'s base classes) as ``Base.meth(self, arguments...)``. Here,
``Base.meth`` is an unbound method, so you need to provide the ``self``
argument.
How can I organize my code to make it easier to change the base class?
----------------------------------------------------------------------
You could define an alias for the base class, assign the real base class to it
before your class definition, and use the alias throughout your class. Then all
you have to change is the value assigned to the alias. Incidentally, this trick
is also handy if you want to decide dynamically (e.g. depending on availability
of resources) which base class to use. Example::
BaseAlias = <real base class>
class Derived(BaseAlias):
def meth(self):
BaseAlias.meth(self)
...
How do I create static class data and static class methods?
-----------------------------------------------------------
Both static data and static methods (in the sense of C++ or Java) are supported
in Python.
For static data, simply define a class attribute. To assign a new value to the
attribute, you have to explicitly use the class name in the assignment::
class C:
count = 0 # number of times C.__init__ called
def __init__(self):
C.count = C.count + 1
def getcount(self):
return C.count # or return self.count
``c.count`` also refers to ``C.count`` for any ``c`` such that ``isinstance(c,
C)`` holds, unless overridden by ``c`` itself or by some class on the base-class
search path from ``c.__class__`` back to ``C``.
Caution: within a method of C, an assignment like ``self.count = 42`` creates a
new and unrelated instance named "count" in ``self``'s own dict. Rebinding of a
class-static data name must always specify the class whether inside a method or
not::
C.count = 314
Static methods are possible since Python 2.2::
class C:
def static(arg1, arg2, arg3):
# No 'self' parameter!
...
static = staticmethod(static)
With Python 2.4's decorators, this can also be written as ::
class C:
@staticmethod
def static(arg1, arg2, arg3):
# No 'self' parameter!
...
However, a far more straightforward way to get the effect of a static method is
via a simple module-level function::
def getcount():
return C.count
If your code is structured so as to define one class (or tightly related class
hierarchy) per module, this supplies the desired encapsulation.
How can I overload constructors (or methods) in Python?
-------------------------------------------------------
This answer actually applies to all methods, but the question usually comes up
first in the context of constructors.
In C++ you'd write
.. code-block:: c
class C {
C() { cout << "No arguments\n"; }
C(int i) { cout << "Argument is " << i << "\n"; }
}
In Python you have to write a single constructor that catches all cases using
default arguments. For example::
class C:
def __init__(self, i=None):
if i is None:
print "No arguments"
else:
print "Argument is", i
This is not entirely equivalent, but close enough in practice.
You could also try a variable-length argument list, e.g. ::
def __init__(self, *args):
...
The same approach works for all method definitions.
I try to use __spam and I get an error about _SomeClassName__spam.
------------------------------------------------------------------
Variable names with double leading underscores are "mangled" to provide a simple
but effective way to define class private variables. Any identifier of the form
``__spam`` (at least two leading underscores, at most one trailing underscore)
is textually replaced with ``_classname__spam``, where ``classname`` is the
current class name with any leading underscores stripped.
This doesn't guarantee privacy: an outside user can still deliberately access
the "_classname__spam" attribute, and private values are visible in the object's
``__dict__``. Many Python programmers never bother to use private variable
names at all.
My class defines __del__ but it is not called when I delete the object.
-----------------------------------------------------------------------
There are several possible reasons for this.
The del statement does not necessarily call :meth:`__del__` -- it simply
decrements the object's reference count, and if this reaches zero
:meth:`__del__` is called.
If your data structures contain circular links (e.g. a tree where each child has
a parent reference and each parent has a list of children) the reference counts
will never go back to zero. Once in a while Python runs an algorithm to detect
such cycles, but the garbage collector might run some time after the last
reference to your data structure vanishes, so your :meth:`__del__` method may be
called at an inconvenient and random time. This is inconvenient if you're trying
to reproduce a problem. Worse, the order in which object's :meth:`__del__`
methods are executed is arbitrary. You can run :func:`gc.collect` to force a
collection, but there *are* pathological cases where objects will never be
collected.
Despite the cycle collector, it's still a good idea to define an explicit
``close()`` method on objects to be called whenever you're done with them. The
``close()`` method can then remove attributes that refer to subobjecs. Don't
call :meth:`__del__` directly -- :meth:`__del__` should call ``close()`` and
``close()`` should make sure that it can be called more than once for the same
object.
Another way to avoid cyclical references is to use the :mod:`weakref` module,
which allows you to point to objects without incrementing their reference count.
Tree data structures, for instance, should use weak references for their parent
and sibling references (if they need them!).
If the object has ever been a local variable in a function that caught an
expression in an except clause, chances are that a reference to the object still
exists in that function's stack frame as contained in the stack trace.
Normally, calling :func:`sys.exc_clear` will take care of this by clearing the
last recorded exception.
Finally, if your :meth:`__del__` method raises an exception, a warning message
is printed to :data:`sys.stderr`.
How do I get a list of all instances of a given class?
------------------------------------------------------
Python does not keep track of all instances of a class (or of a built-in type).
You can program the class's constructor to keep track of all instances by
keeping a list of weak references to each instance.
Why does the result of ``id()`` appear to be not unique?
--------------------------------------------------------
The :func:`id` builtin returns an integer that is guaranteed to be unique during
the lifetime of the object. Since in CPython, this is the object's memory
address, it happens frequently that after an object is deleted from memory, the
next freshly created object is allocated at the same position in memory. This
is illustrated by this example:
>>> id(1000)
13901272
>>> id(2000)
13901272
The two ids belong to different integer objects that are created before, and
deleted immediately after execution of the ``id()`` call. To be sure that
objects whose id you want to examine are still alive, create another reference
to the object:
>>> a = 1000; b = 2000
>>> id(a)
13901272
>>> id(b)
13891296
Modules
=======
How do I create a .pyc file?
----------------------------
When a module is imported for the first time (or when the source is more recent
than the current compiled file) a ``.pyc`` file containing the compiled code
should be created in the same directory as the ``.py`` file.
One reason that a ``.pyc`` file may not be created is permissions problems with
the directory. This can happen, for example, if you develop as one user but run
as another, such as if you are testing with a web server. Creation of a .pyc
file is automatic if you're importing a module and Python has the ability
(permissions, free space, etc...) to write the compiled module back to the
directory.
Running Python on a top level script is not considered an import and no
``.pyc`` will be created. For example, if you have a top-level module
``foo.py`` that imports another module ``xyz.py``, when you run ``foo``,
``xyz.pyc`` will be created since ``xyz`` is imported, but no ``foo.pyc`` file
will be created since ``foo.py`` isn't being imported.
If you need to create ``foo.pyc`` -- that is, to create a ``.pyc`` file for a module
that is not imported -- you can, using the :mod:`py_compile` and
:mod:`compileall` modules.
The :mod:`py_compile` module can manually compile any module. One way is to use
the ``compile()`` function in that module interactively::
>>> import py_compile
>>> py_compile.compile('foo.py') # doctest: +SKIP
This will write the ``.pyc`` to the same location as ``foo.py`` (or you can
override that with the optional parameter ``cfile``).
You can also automatically compile all files in a directory or directories using
the :mod:`compileall` module. You can do it from the shell prompt by running
``compileall.py`` and providing the path of a directory containing Python files
to compile::
python -m compileall .
How do I find the current module name?
--------------------------------------
A module can find out its own module name by looking at the predefined global
variable ``__name__``. If this has the value ``'__main__'``, the program is
running as a script. Many modules that are usually used by importing them also
provide a command-line interface or a self-test, and only execute this code
after checking ``__name__``::
def main():
print 'Running test...'
...
if __name__ == '__main__':
main()
How can I have modules that mutually import each other?
-------------------------------------------------------
Suppose you have the following modules:
foo.py::
from bar import bar_var
foo_var = 1
bar.py::
from foo import foo_var
bar_var = 2
The problem is that the interpreter will perform the following steps:
* main imports foo
* Empty globals for foo are created
* foo is compiled and starts executing
* foo imports bar
* Empty globals for bar are created
* bar is compiled and starts executing
* bar imports foo (which is a no-op since there already is a module named foo)
* bar.foo_var = foo.foo_var
The last step fails, because Python isn't done with interpreting ``foo`` yet and
the global symbol dictionary for ``foo`` is still empty.
The same thing happens when you use ``import foo``, and then try to access
``foo.foo_var`` in global code.
There are (at least) three possible workarounds for this problem.
Guido van Rossum recommends avoiding all uses of ``from <module> import ...``,
and placing all code inside functions. Initializations of global variables and
class variables should use constants or built-in functions only. This means
everything from an imported module is referenced as ``<module>.<name>``.
Jim Roskind suggests performing steps in the following order in each module:
* exports (globals, functions, and classes that don't need imported base
classes)
* ``import`` statements
* active code (including globals that are initialized from imported values).
van Rossum doesn't like this approach much because the imports appear in a
strange place, but it does work.
Matthias Urlichs recommends restructuring your code so that the recursive import
is not necessary in the first place.
These solutions are not mutually exclusive.
__import__('x.y.z') returns <module 'x'>; how do I get z?
---------------------------------------------------------
Consider using the convenience function :func:`~importlib.import_module` from
:mod:`importlib` instead::
z = importlib.import_module('x.y.z')
When I edit an imported module and reimport it, the changes don't show up. Why does this happen?
-------------------------------------------------------------------------------------------------
For reasons of efficiency as well as consistency, Python only reads the module
file on the first time a module is imported. If it didn't, in a program
consisting of many modules where each one imports the same basic module, the
basic module would be parsed and re-parsed many times. To force rereading of a
changed module, do this::
import modname
reload(modname)
Warning: this technique is not 100% fool-proof. In particular, modules
containing statements like ::
from modname import some_objects
will continue to work with the old version of the imported objects. If the
module contains class definitions, existing class instances will *not* be
updated to use the new class definition. This can result in the following
paradoxical behaviour:
>>> import cls
>>> c = cls.C() # Create an instance of C
>>> reload(cls)
<module 'cls' from 'cls.pyc'>
>>> isinstance(c, cls.C) # isinstance is false?!?
False
The nature of the problem is made clear if you print out the class objects:
>>> c.__class__
<class cls.C at 0x7352a0>
>>> cls.C
<class cls.C at 0x4198d0>
PK %�\���6 �6 ! html/_sources/faq/windows.rst.txtnu �[��� :tocdepth: 2
.. _windows-faq:
=====================
Python on Windows FAQ
=====================
.. only:: html
.. contents::
How do I run a Python program under Windows?
--------------------------------------------
This is not necessarily a straightforward question. If you are already familiar
with running programs from the Windows command line then everything will seem
obvious; otherwise, you might need a little more guidance.
Unless you use some sort of integrated development environment, you will end up
*typing* Windows commands into what is variously referred to as a "DOS window"
or "Command prompt window". Usually you can create such a window from your
Start menu; under Windows 7 the menu selection is :menuselection:`Start -->
Programs --> Accessories --> Command Prompt`. You should be able to recognize
when you have started such a window because you will see a Windows "command
prompt", which usually looks like this::
C:\>
The letter may be different, and there might be other things after it, so you
might just as easily see something like::
D:\YourName\Projects\Python>
depending on how your computer has been set up and what else you have recently
done with it. Once you have started such a window, you are well on the way to
running Python programs.
You need to realize that your Python scripts have to be processed by another
program called the Python *interpreter*. The interpreter reads your script,
compiles it into bytecodes, and then executes the bytecodes to run your
program. So, how do you arrange for the interpreter to handle your Python?
First, you need to make sure that your command window recognises the word
"python" as an instruction to start the interpreter. If you have opened a
command window, you should try entering the command ``python`` and hitting
return.::
C:\Users\YourName> python
You should then see something like::
Python 2.7.3 (default, Apr 10 2012, 22.71:26) [MSC v.1500 32 bit (Intel)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>>
You have started the interpreter in "interactive mode". That means you can enter
Python statements or expressions interactively and have them executed or
evaluated while you wait. This is one of Python's strongest features. Check it
by entering a few expressions of your choice and seeing the results::
>>> print "Hello"
Hello
>>> "Hello" * 3
'HelloHelloHello'
Many people use the interactive mode as a convenient yet highly programmable
calculator. When you want to end your interactive Python session, hold the :kbd:`Ctrl`
key down while you enter a :kbd:`Z`, then hit the ":kbd:`Enter`" key to get back to your
Windows command prompt.
You may also find that you have a Start-menu entry such as :menuselection:`Start
--> Programs --> Python 2.7 --> Python (command line)` that results in you
seeing the ``>>>`` prompt in a new window. If so, the window will disappear
after you enter the :kbd:`Ctrl-Z` character; Windows is running a single "python"
command in the window, and closes it when you terminate the interpreter.
If the ``python`` command, instead of displaying the interpreter prompt ``>>>``,
gives you a message like::
'python' is not recognized as an internal or external command, operable program or batch file.
or::
Bad command or filename
then you need to make sure that your computer knows where to find the Python
interpreter. To do this you will have to modify a setting called PATH, which is
a list of directories where Windows will look for programs.
You should arrange for Python's installation directory to be added to the PATH
of every command window as it starts. If you installed Python fairly recently
then the command ::
dir C:\py*
will probably tell you where it is installed; the usual location is something
like ``C:\Python27``. Otherwise you will be reduced to a search of your whole
disk ... use :menuselection:`Tools --> Find` or hit the :guilabel:`Search`
button and look for "python.exe". Supposing you discover that Python is
installed in the ``C:\Python27`` directory (the default at the time of writing),
you should make sure that entering the command ::
c:\Python27\python
starts up the interpreter as above (and don't forget you'll need a ":kbd:`Ctrl-Z`" and
an ":kbd:`Enter`" to get out of it). Once you have verified the directory, you can
add it to the system path to make it easier to start Python by just running
the ``python`` command. This is currently an option in the installer as of
CPython 2.7.
More information about environment variables can be found on the
:ref:`Using Python on Windows <setting-envvars>` page.
How do I make Python scripts executable?
----------------------------------------
On Windows, the standard Python installer already associates the .py
extension with a file type (Python.File) and gives that file type an open
command that runs the interpreter (``D:\Program Files\Python\python.exe "%1"
%*``). This is enough to make scripts executable from the command prompt as
'foo.py'. If you'd rather be able to execute the script by simple typing 'foo'
with no extension you need to add .py to the PATHEXT environment variable.
Why does Python sometimes take so long to start?
------------------------------------------------
Usually Python starts very quickly on Windows, but occasionally there are bug
reports that Python suddenly begins to take a long time to start up. This is
made even more puzzling because Python will work fine on other Windows systems
which appear to be configured identically.
The problem may be caused by a misconfiguration of virus checking software on
the problem machine. Some virus scanners have been known to introduce startup
overhead of two orders of magnitude when the scanner is configured to monitor
all reads from the filesystem. Try checking the configuration of virus scanning
software on your systems to ensure that they are indeed configured identically.
McAfee, when configured to scan all file system read activity, is a particular
offender.
How do I make an executable from a Python script?
-------------------------------------------------
See http://www.py2exe.org/ for a distutils extension that allows you
to create console and GUI executables from Python code.
Is a ``*.pyd`` file the same as a DLL?
--------------------------------------
.. XXX update for py3k (PyInit_foo)
Yes, .pyd files are dll's, but there are a few differences. If you have a DLL
named ``foo.pyd``, then it must have a function ``initfoo()``. You can then
write Python "import foo", and Python will search for foo.pyd (as well as
foo.py, foo.pyc) and if it finds it, will attempt to call ``initfoo()`` to
initialize it. You do not link your .exe with foo.lib, as that would cause
Windows to require the DLL to be present.
Note that the search path for foo.pyd is PYTHONPATH, not the same as the path
that Windows uses to search for foo.dll. Also, foo.pyd need not be present to
run your program, whereas if you linked your program with a dll, the dll is
required. Of course, foo.pyd is required if you want to say ``import foo``. In
a DLL, linkage is declared in the source code with ``__declspec(dllexport)``.
In a .pyd, linkage is defined in a list of available functions.
How can I embed Python into a Windows application?
--------------------------------------------------
Embedding the Python interpreter in a Windows app can be summarized as follows:
1. Do _not_ build Python into your .exe file directly. On Windows, Python must
be a DLL to handle importing modules that are themselves DLL's. (This is the
first key undocumented fact.) Instead, link to :file:`python{NN}.dll`; it is
typically installed in ``C:\Windows\System``. *NN* is the Python version, a
number such as "27" for Python 2.7.
You can link to Python in two different ways. Load-time linking means
linking against :file:`python{NN}.lib`, while run-time linking means linking
against :file:`python{NN}.dll`. (General note: :file:`python{NN}.lib` is the
so-called "import lib" corresponding to :file:`python{NN}.dll`. It merely
defines symbols for the linker.)
Run-time linking greatly simplifies link options; everything happens at run
time. Your code must load :file:`python{NN}.dll` using the Windows
``LoadLibraryEx()`` routine. The code must also use access routines and data
in :file:`python{NN}.dll` (that is, Python's C API's) using pointers obtained
by the Windows ``GetProcAddress()`` routine. Macros can make using these
pointers transparent to any C code that calls routines in Python's C API.
Borland note: convert :file:`python{NN}.lib` to OMF format using Coff2Omf.exe
first.
.. XXX what about static linking?
2. If you use SWIG, it is easy to create a Python "extension module" that will
make the app's data and methods available to Python. SWIG will handle just
about all the grungy details for you. The result is C code that you link
*into* your .exe file (!) You do _not_ have to create a DLL file, and this
also simplifies linking.
3. SWIG will create an init function (a C function) whose name depends on the
name of the extension module. For example, if the name of the module is leo,
the init function will be called initleo(). If you use SWIG shadow classes,
as you should, the init function will be called initleoc(). This initializes
a mostly hidden helper class used by the shadow class.
The reason you can link the C code in step 2 into your .exe file is that
calling the initialization function is equivalent to importing the module
into Python! (This is the second key undocumented fact.)
4. In short, you can use the following code to initialize the Python interpreter
with your extension module.
.. code-block:: c
#include "python.h"
...
Py_Initialize(); // Initialize Python.
initmyAppc(); // Initialize (import) the helper class.
PyRun_SimpleString("import myApp"); // Import the shadow class.
5. There are two problems with Python's C API which will become apparent if you
use a compiler other than MSVC, the compiler used to build pythonNN.dll.
Problem 1: The so-called "Very High Level" functions that take FILE *
arguments will not work in a multi-compiler environment because each
compiler's notion of a struct FILE will be different. From an implementation
standpoint these are very _low_ level functions.
Problem 2: SWIG generates the following code when generating wrappers to void
functions:
.. code-block:: c
Py_INCREF(Py_None);
_resultobj = Py_None;
return _resultobj;
Alas, Py_None is a macro that expands to a reference to a complex data
structure called _Py_NoneStruct inside pythonNN.dll. Again, this code will
fail in a mult-compiler environment. Replace such code by:
.. code-block:: c
return Py_BuildValue("");
It may be possible to use SWIG's ``%typemap`` command to make the change
automatically, though I have not been able to get this to work (I'm a
complete SWIG newbie).
6. Using a Python shell script to put up a Python interpreter window from inside
your Windows app is not a good idea; the resulting window will be independent
of your app's windowing system. Rather, you (or the wxPythonWindow class)
should create a "native" interpreter window. It is easy to connect that
window to the Python interpreter. You can redirect Python's i/o to _any_
object that supports read and write, so all you need is a Python object
(defined in your extension module) that contains read() and write() methods.
How do I keep editors from inserting tabs into my Python source?
----------------------------------------------------------------
The FAQ does not recommend using tabs, and the Python style guide, :pep:`8`,
recommends 4 spaces for distributed Python code; this is also the Emacs
python-mode default.
Under any editor, mixing tabs and spaces is a bad idea. MSVC is no different in
this respect, and is easily configured to use spaces: Take :menuselection:`Tools
--> Options --> Tabs`, and for file type "Default" set "Tab size" and "Indent
size" to 4, and select the "Insert spaces" radio button.
If you suspect mixed tabs and spaces are causing problems in leading whitespace,
run Python with the :option:`-t` switch or run the :mod:`tabnanny` module to
check a directory tree in batch mode.
How do I check for a keypress without blocking?
-----------------------------------------------
Use the msvcrt module. This is a standard Windows-specific extension module.
It defines a function ``kbhit()`` which checks whether a keyboard hit is
present, and ``getch()`` which gets one character without echoing it.
How do I emulate os.kill() in Windows?
--------------------------------------
Prior to Python 2.7 and 3.2, to terminate a process, you can use :mod:`ctypes`::
import ctypes
def kill(pid):
"""kill function for Win32"""
kernel32 = ctypes.windll.kernel32
handle = kernel32.OpenProcess(1, 0, pid)
return (0 != kernel32.TerminateProcess(handle, 0))
In 2.7 and 3.2, :func:`os.kill` is implemented similar to the above function,
with the additional feature of being able to send :kbd:`Ctrl+C` and :kbd:`Ctrl+Break`
to console subprocesses which are designed to handle those signals. See
:func:`os.kill` for further details.
How do I extract the downloaded documentation on Windows?
---------------------------------------------------------
Sometimes, when you download the documentation package to a Windows machine
using a web browser, the file extension of the saved file ends up being .EXE.
This is a mistake; the extension should be .TGZ.
Simply rename the downloaded file to have the .TGZ extension, and WinZip will be
able to handle it. (If your copy of WinZip doesn't, get a newer one from
https://www.winzip.com.)
PK %�\���\ �\ $ html/_sources/howto/argparse.rst.txtnu �[��� *****************
Argparse Tutorial
*****************
:author: Tshepang Lekhonkhobe
.. _argparse-tutorial:
This tutorial is intended to be a gentle introduction to :mod:`argparse`, the
recommended command-line parsing module in the Python standard library.
This was written for argparse in Python 3. A few details are different in 2.x,
especially some exception messages, which were improved in 3.x.
.. note::
There are two other modules that fulfill the same task, namely
:mod:`getopt` (an equivalent for :c:func:`getopt` from the C
language) and the deprecated :mod:`optparse`.
Note also that :mod:`argparse` is based on :mod:`optparse`,
and therefore very similar in terms of usage.
Concepts
========
Let's show the sort of functionality that we are going to explore in this
introductory tutorial by making use of the :command:`ls` command:
.. code-block:: sh
$ ls
cpython devguide prog.py pypy rm-unused-function.patch
$ ls pypy
ctypes_configure demo dotviewer include lib_pypy lib-python ...
$ ls -l
total 20
drwxr-xr-x 19 wena wena 4096 Feb 18 18:51 cpython
drwxr-xr-x 4 wena wena 4096 Feb 8 12:04 devguide
-rwxr-xr-x 1 wena wena 535 Feb 19 00:05 prog.py
drwxr-xr-x 14 wena wena 4096 Feb 7 00:59 pypy
-rw-r--r-- 1 wena wena 741 Feb 18 01:01 rm-unused-function.patch
$ ls --help
Usage: ls [OPTION]... [FILE]...
List information about the FILEs (the current directory by default).
Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.
...
A few concepts we can learn from the four commands:
* The :command:`ls` command is useful when run without any options at all. It defaults
to displaying the contents of the current directory.
* If we want beyond what it provides by default, we tell it a bit more. In
this case, we want it to display a different directory, ``pypy``.
What we did is specify what is known as a positional argument. It's named so
because the program should know what to do with the value, solely based on
where it appears on the command line. This concept is more relevant
to a command like :command:`cp`, whose most basic usage is ``cp SRC DEST``.
The first position is *what you want copied,* and the second
position is *where you want it copied to*.
* Now, say we want to change behaviour of the program. In our example,
we display more info for each file instead of just showing the file names.
The ``-l`` in that case is known as an optional argument.
* That's a snippet of the help text. It's very useful in that you can
come across a program you have never used before, and can figure out
how it works simply by reading its help text.
The basics
==========
Let us start with a very simple example which does (almost) nothing::
import argparse
parser = argparse.ArgumentParser()
parser.parse_args()
Following is a result of running the code:
.. code-block:: sh
$ python prog.py
$ python prog.py --help
usage: prog.py [-h]
optional arguments:
-h, --help show this help message and exit
$ python prog.py --verbose
usage: prog.py [-h]
prog.py: error: unrecognized arguments: --verbose
$ python prog.py foo
usage: prog.py [-h]
prog.py: error: unrecognized arguments: foo
Here is what is happening:
* Running the script without any options results in nothing displayed to
stdout. Not so useful.
* The second one starts to display the usefulness of the :mod:`argparse`
module. We have done almost nothing, but already we get a nice help message.
* The ``--help`` option, which can also be shortened to ``-h``, is the only
option we get for free (i.e. no need to specify it). Specifying anything
else results in an error. But even then, we do get a useful usage message,
also for free.
Introducing Positional arguments
================================
An example::
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("echo")
args = parser.parse_args()
print args.echo
And running the code:
.. code-block:: sh
$ python prog.py
usage: prog.py [-h] echo
prog.py: error: the following arguments are required: echo
$ python prog.py --help
usage: prog.py [-h] echo
positional arguments:
echo
optional arguments:
-h, --help show this help message and exit
$ python prog.py foo
foo
Here is what's happening:
* We've added the :meth:`add_argument` method, which is what we use to specify
which command-line options the program is willing to accept. In this case,
I've named it ``echo`` so that it's in line with its function.
* Calling our program now requires us to specify an option.
* The :meth:`parse_args` method actually returns some data from the
options specified, in this case, ``echo``.
* The variable is some form of 'magic' that :mod:`argparse` performs for free
(i.e. no need to specify which variable that value is stored in).
You will also notice that its name matches the string argument given
to the method, ``echo``.
Note however that, although the help display looks nice and all, it currently
is not as helpful as it can be. For example we see that we got ``echo`` as a
positional argument, but we don't know what it does, other than by guessing or
by reading the source code. So, let's make it a bit more useful::
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("echo", help="echo the string you use here")
args = parser.parse_args()
print args.echo
And we get:
.. code-block:: sh
$ python prog.py -h
usage: prog.py [-h] echo
positional arguments:
echo echo the string you use here
optional arguments:
-h, --help show this help message and exit
Now, how about doing something even more useful::
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", help="display a square of a given number")
args = parser.parse_args()
print args.square**2
Following is a result of running the code:
.. code-block:: sh
$ python prog.py 4
Traceback (most recent call last):
File "prog.py", line 5, in <module>
print args.square**2
TypeError: unsupported operand type(s) for ** or pow(): 'str' and 'int'
That didn't go so well. That's because :mod:`argparse` treats the options we
give it as strings, unless we tell it otherwise. So, let's tell
:mod:`argparse` to treat that input as an integer::
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", help="display a square of a given number",
type=int)
args = parser.parse_args()
print args.square**2
Following is a result of running the code:
.. code-block:: sh
$ python prog.py 4
16
$ python prog.py four
usage: prog.py [-h] square
prog.py: error: argument square: invalid int value: 'four'
That went well. The program now even helpfully quits on bad illegal input
before proceeding.
Introducing Optional arguments
==============================
So far we have been playing with positional arguments. Let us
have a look on how to add optional ones::
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("--verbosity", help="increase output verbosity")
args = parser.parse_args()
if args.verbosity:
print "verbosity turned on"
And the output:
.. code-block:: sh
$ python prog.py --verbosity 1
verbosity turned on
$ python prog.py
$ python prog.py --help
usage: prog.py [-h] [--verbosity VERBOSITY]
optional arguments:
-h, --help show this help message and exit
--verbosity VERBOSITY
increase output verbosity
$ python prog.py --verbosity
usage: prog.py [-h] [--verbosity VERBOSITY]
prog.py: error: argument --verbosity: expected one argument
Here is what is happening:
* The program is written so as to display something when ``--verbosity`` is
specified and display nothing when not.
* To show that the option is actually optional, there is no error when running
the program without it. Note that by default, if an optional argument isn't
used, the relevant variable, in this case :attr:`args.verbosity`, is
given ``None`` as a value, which is the reason it fails the truth
test of the :keyword:`if` statement.
* The help message is a bit different.
* When using the ``--verbosity`` option, one must also specify some value,
any value.
The above example accepts arbitrary integer values for ``--verbosity``, but for
our simple program, only two values are actually useful, ``True`` or ``False``.
Let's modify the code accordingly::
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("--verbose", help="increase output verbosity",
action="store_true")
args = parser.parse_args()
if args.verbose:
print "verbosity turned on"
And the output:
.. code-block:: sh
$ python prog.py --verbose
verbosity turned on
$ python prog.py --verbose 1
usage: prog.py [-h] [--verbose]
prog.py: error: unrecognized arguments: 1
$ python prog.py --help
usage: prog.py [-h] [--verbose]
optional arguments:
-h, --help show this help message and exit
--verbose increase output verbosity
Here is what is happening:
* The option is now more of a flag than something that requires a value.
We even changed the name of the option to match that idea.
Note that we now specify a new keyword, ``action``, and give it the value
``"store_true"``. This means that, if the option is specified,
assign the value ``True`` to :data:`args.verbose`.
Not specifying it implies ``False``.
* It complains when you specify a value, in true spirit of what flags
actually are.
* Notice the different help text.
Short options
-------------
If you are familiar with command line usage,
you will notice that I haven't yet touched on the topic of short
versions of the options. It's quite simple::
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("-v", "--verbose", help="increase output verbosity",
action="store_true")
args = parser.parse_args()
if args.verbose:
print "verbosity turned on"
And here goes:
.. code-block:: sh
$ python prog.py -v
verbosity turned on
$ python prog.py --help
usage: prog.py [-h] [-v]
optional arguments:
-h, --help show this help message and exit
-v, --verbose increase output verbosity
Note that the new ability is also reflected in the help text.
Combining Positional and Optional arguments
===========================================
Our program keeps growing in complexity::
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", type=int,
help="display a square of a given number")
parser.add_argument("-v", "--verbose", action="store_true",
help="increase output verbosity")
args = parser.parse_args()
answer = args.square**2
if args.verbose:
print "the square of {} equals {}".format(args.square, answer)
else:
print answer
And now the output:
.. code-block:: sh
$ python prog.py
usage: prog.py [-h] [-v] square
prog.py: error: the following arguments are required: square
$ python prog.py 4
16
$ python prog.py 4 --verbose
the square of 4 equals 16
$ python prog.py --verbose 4
the square of 4 equals 16
* We've brought back a positional argument, hence the complaint.
* Note that the order does not matter.
How about we give this program of ours back the ability to have
multiple verbosity values, and actually get to use them::
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", type=int,
help="display a square of a given number")
parser.add_argument("-v", "--verbosity", type=int,
help="increase output verbosity")
args = parser.parse_args()
answer = args.square**2
if args.verbosity == 2:
print "the square of {} equals {}".format(args.square, answer)
elif args.verbosity == 1:
print "{}^2 == {}".format(args.square, answer)
else:
print answer
And the output:
.. code-block:: sh
$ python prog.py 4
16
$ python prog.py 4 -v
usage: prog.py [-h] [-v VERBOSITY] square
prog.py: error: argument -v/--verbosity: expected one argument
$ python prog.py 4 -v 1
4^2 == 16
$ python prog.py 4 -v 2
the square of 4 equals 16
$ python prog.py 4 -v 3
16
These all look good except the last one, which exposes a bug in our program.
Let's fix it by restricting the values the ``--verbosity`` option can accept::
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", type=int,
help="display a square of a given number")
parser.add_argument("-v", "--verbosity", type=int, choices=[0, 1, 2],
help="increase output verbosity")
args = parser.parse_args()
answer = args.square**2
if args.verbosity == 2:
print "the square of {} equals {}".format(args.square, answer)
elif args.verbosity == 1:
print "{}^2 == {}".format(args.square, answer)
else:
print answer
And the output:
.. code-block:: sh
$ python prog.py 4 -v 3
usage: prog.py [-h] [-v {0,1,2}] square
prog.py: error: argument -v/--verbosity: invalid choice: 3 (choose from 0, 1, 2)
$ python prog.py 4 -h
usage: prog.py [-h] [-v {0,1,2}] square
positional arguments:
square display a square of a given number
optional arguments:
-h, --help show this help message and exit
-v {0,1,2}, --verbosity {0,1,2}
increase output verbosity
Note that the change also reflects both in the error message as well as the
help string.
Now, let's use a different approach of playing with verbosity, which is pretty
common. It also matches the way the CPython executable handles its own
verbosity argument (check the output of ``python --help``)::
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", type=int,
help="display the square of a given number")
parser.add_argument("-v", "--verbosity", action="count",
help="increase output verbosity")
args = parser.parse_args()
answer = args.square**2
if args.verbosity == 2:
print "the square of {} equals {}".format(args.square, answer)
elif args.verbosity == 1:
print "{}^2 == {}".format(args.square, answer)
else:
print answer
We have introduced another action, "count",
to count the number of occurrences of a specific optional arguments:
.. code-block:: sh
$ python prog.py 4
16
$ python prog.py 4 -v
4^2 == 16
$ python prog.py 4 -vv
the square of 4 equals 16
$ python prog.py 4 --verbosity --verbosity
the square of 4 equals 16
$ python prog.py 4 -v 1
usage: prog.py [-h] [-v] square
prog.py: error: unrecognized arguments: 1
$ python prog.py 4 -h
usage: prog.py [-h] [-v] square
positional arguments:
square display a square of a given number
optional arguments:
-h, --help show this help message and exit
-v, --verbosity increase output verbosity
$ python prog.py 4 -vvv
16
* Yes, it's now more of a flag (similar to ``action="store_true"``) in the
previous version of our script. That should explain the complaint.
* It also behaves similar to "store_true" action.
* Now here's a demonstration of what the "count" action gives. You've probably
seen this sort of usage before.
* And, just like the "store_true" action, if you don't specify the ``-v`` flag,
that flag is considered to have ``None`` value.
* As should be expected, specifying the long form of the flag, we should get
the same output.
* Sadly, our help output isn't very informative on the new ability our script
has acquired, but that can always be fixed by improving the documentation for
our script (e.g. via the ``help`` keyword argument).
* That last output exposes a bug in our program.
Let's fix::
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", type=int,
help="display a square of a given number")
parser.add_argument("-v", "--verbosity", action="count",
help="increase output verbosity")
args = parser.parse_args()
answer = args.square**2
# bugfix: replace == with >=
if args.verbosity >= 2:
print "the square of {} equals {}".format(args.square, answer)
elif args.verbosity >= 1:
print "{}^2 == {}".format(args.square, answer)
else:
print answer
And this is what it gives:
.. code-block:: sh
$ python prog.py 4 -vvv
the square of 4 equals 16
$ python prog.py 4 -vvvv
the square of 4 equals 16
$ python prog.py 4
Traceback (most recent call last):
File "prog.py", line 11, in <module>
if args.verbosity >= 2:
TypeError: unorderable types: NoneType() >= int()
* First output went well, and fixes the bug we had before.
That is, we want any value >= 2 to be as verbose as possible.
* Third output not so good.
Let's fix that bug::
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("square", type=int,
help="display a square of a given number")
parser.add_argument("-v", "--verbosity", action="count", default=0,
help="increase output verbosity")
args = parser.parse_args()
answer = args.square**2
if args.verbosity >= 2:
print "the square of {} equals {}".format(args.square, answer)
elif args.verbosity >= 1:
print "{}^2 == {}".format(args.square, answer)
else:
print answer
We've just introduced yet another keyword, ``default``.
We've set it to ``0`` in order to make it comparable to the other int values.
Remember that by default,
if an optional argument isn't specified,
it gets the ``None`` value, and that cannot be compared to an int value
(hence the :exc:`TypeError` exception).
And:
.. code-block:: sh
$ python prog.py 4
16
You can go quite far just with what we've learned so far,
and we have only scratched the surface.
The :mod:`argparse` module is very powerful,
and we'll explore a bit more of it before we end this tutorial.
Getting a little more advanced
==============================
What if we wanted to expand our tiny program to perform other powers,
not just squares::
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("x", type=int, help="the base")
parser.add_argument("y", type=int, help="the exponent")
parser.add_argument("-v", "--verbosity", action="count", default=0)
args = parser.parse_args()
answer = args.x**args.y
if args.verbosity >= 2:
print "{} to the power {} equals {}".format(args.x, args.y, answer)
elif args.verbosity >= 1:
print "{}^{} == {}".format(args.x, args.y, answer)
else:
print answer
Output:
.. code-block:: sh
$ python prog.py
usage: prog.py [-h] [-v] x y
prog.py: error: the following arguments are required: x, y
$ python prog.py -h
usage: prog.py [-h] [-v] x y
positional arguments:
x the base
y the exponent
optional arguments:
-h, --help show this help message and exit
-v, --verbosity
$ python prog.py 4 2 -v
4^2 == 16
Notice that so far we've been using verbosity level to *change* the text
that gets displayed. The following example instead uses verbosity level
to display *more* text instead::
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("x", type=int, help="the base")
parser.add_argument("y", type=int, help="the exponent")
parser.add_argument("-v", "--verbosity", action="count", default=0)
args = parser.parse_args()
answer = args.x**args.y
if args.verbosity >= 2:
print "Running '{}'".format(__file__)
if args.verbosity >= 1:
print "{}^{} ==".format(args.x, args.y),
print answer
Output:
.. code-block:: sh
$ python prog.py 4 2
16
$ python prog.py 4 2 -v
4^2 == 16
$ python prog.py 4 2 -vv
Running 'prog.py'
4^2 == 16
Conflicting options
-------------------
So far, we have been working with two methods of an
:class:`argparse.ArgumentParser` instance. Let's introduce a third one,
:meth:`add_mutually_exclusive_group`. It allows for us to specify options that
conflict with each other. Let's also change the rest of the program so that
the new functionality makes more sense:
we'll introduce the ``--quiet`` option,
which will be the opposite of the ``--verbose`` one::
import argparse
parser = argparse.ArgumentParser()
group = parser.add_mutually_exclusive_group()
group.add_argument("-v", "--verbose", action="store_true")
group.add_argument("-q", "--quiet", action="store_true")
parser.add_argument("x", type=int, help="the base")
parser.add_argument("y", type=int, help="the exponent")
args = parser.parse_args()
answer = args.x**args.y
if args.quiet:
print answer
elif args.verbose:
print "{} to the power {} equals {}".format(args.x, args.y, answer)
else:
print "{}^{} == {}".format(args.x, args.y, answer)
Our program is now simpler, and we've lost some functionality for the sake of
demonstration. Anyways, here's the output:
.. code-block:: sh
$ python prog.py 4 2
4^2 == 16
$ python prog.py 4 2 -q
16
$ python prog.py 4 2 -v
4 to the power 2 equals 16
$ python prog.py 4 2 -vq
usage: prog.py [-h] [-v | -q] x y
prog.py: error: argument -q/--quiet: not allowed with argument -v/--verbose
$ python prog.py 4 2 -v --quiet
usage: prog.py [-h] [-v | -q] x y
prog.py: error: argument -q/--quiet: not allowed with argument -v/--verbose
That should be easy to follow. I've added that last output so you can see the
sort of flexibility you get, i.e. mixing long form options with short form
ones.
Before we conclude, you probably want to tell your users the main purpose of
your program, just in case they don't know::
import argparse
parser = argparse.ArgumentParser(description="calculate X to the power of Y")
group = parser.add_mutually_exclusive_group()
group.add_argument("-v", "--verbose", action="store_true")
group.add_argument("-q", "--quiet", action="store_true")
parser.add_argument("x", type=int, help="the base")
parser.add_argument("y", type=int, help="the exponent")
args = parser.parse_args()
answer = args.x**args.y
if args.quiet:
print answer
elif args.verbose:
print "{} to the power {} equals {}".format(args.x, args.y, answer)
else:
print "{}^{} == {}".format(args.x, args.y, answer)
Note that slight difference in the usage text. Note the ``[-v | -q]``,
which tells us that we can either use ``-v`` or ``-q``,
but not both at the same time:
.. code-block:: sh
$ python prog.py --help
usage: prog.py [-h] [-v | -q] x y
calculate X to the power of Y
positional arguments:
x the base
y the exponent
optional arguments:
-h, --help show this help message and exit
-v, --verbose
-q, --quiet
Conclusion
==========
The :mod:`argparse` module offers a lot more than shown here.
Its docs are quite detailed and thorough, and full of examples.
Having gone through this tutorial, you should easily digest them
without feeling overwhelmed.
PK %�\�%` $ html/_sources/howto/cporting.rst.txtnu �[��� .. highlightlang:: c
.. _cporting-howto:
*************************************
Porting Extension Modules to Python 3
*************************************
:author: Benjamin Peterson
.. topic:: Abstract
Although changing the C-API was not one of Python 3's objectives,
the many Python-level changes made leaving Python 2's API intact
impossible. In fact, some changes such as :func:`int` and
:func:`long` unification are more obvious on the C level. This
document endeavors to document incompatibilities and how they can
be worked around.
Conditional compilation
=======================
The easiest way to compile only some code for Python 3 is to check
if :c:macro:`PY_MAJOR_VERSION` is greater than or equal to 3. ::
#if PY_MAJOR_VERSION >= 3
#define IS_PY3K
#endif
API functions that are not present can be aliased to their equivalents within
conditional blocks.
Changes to Object APIs
======================
Python 3 merged together some types with similar functions while cleanly
separating others.
str/unicode Unification
-----------------------
Python 3's :func:`str` type is equivalent to Python 2's :func:`unicode`; the C
functions are called ``PyUnicode_*`` for both. The old 8-bit string type has become
:func:`bytes`, with C functions called ``PyBytes_*``. Python 2.6 and later provide a compatibility header,
:file:`bytesobject.h`, mapping ``PyBytes`` names to ``PyString`` ones. For best
compatibility with Python 3, :c:type:`PyUnicode` should be used for textual data and
:c:type:`PyBytes` for binary data. It's also important to remember that
:c:type:`PyBytes` and :c:type:`PyUnicode` in Python 3 are not interchangeable like
:c:type:`PyString` and :c:type:`PyUnicode` are in Python 2. The following example
shows best practices with regards to :c:type:`PyUnicode`, :c:type:`PyString`,
and :c:type:`PyBytes`. ::
#include "stdlib.h"
#include "Python.h"
#include "bytesobject.h"
/* text example */
static PyObject *
say_hello(PyObject *self, PyObject *args) {
PyObject *name, *result;
if (!PyArg_ParseTuple(args, "U:say_hello", &name))
return NULL;
result = PyUnicode_FromFormat("Hello, %S!", name);
return result;
}
/* just a forward */
static char * do_encode(PyObject *);
/* bytes example */
static PyObject *
encode_object(PyObject *self, PyObject *args) {
char *encoded;
PyObject *result, *myobj;
if (!PyArg_ParseTuple(args, "O:encode_object", &myobj))
return NULL;
encoded = do_encode(myobj);
if (encoded == NULL)
return NULL;
result = PyBytes_FromString(encoded);
free(encoded);
return result;
}
long/int Unification
--------------------
Python 3 has only one integer type, :func:`int`. But it actually
corresponds to Python 2's :func:`long` type—the :func:`int` type
used in Python 2 was removed. In the C-API, ``PyInt_*`` functions
are replaced by their ``PyLong_*`` equivalents.
Module initialization and state
===============================
Python 3 has a revamped extension module initialization system. (See
:pep:`3121`.) Instead of storing module state in globals, they should
be stored in an interpreter specific structure. Creating modules that
act correctly in both Python 2 and Python 3 is tricky. The following
simple example demonstrates how. ::
#include "Python.h"
struct module_state {
PyObject *error;
};
#if PY_MAJOR_VERSION >= 3
#define GETSTATE(m) ((struct module_state*)PyModule_GetState(m))
#else
#define GETSTATE(m) (&_state)
static struct module_state _state;
#endif
static PyObject *
error_out(PyObject *m) {
struct module_state *st = GETSTATE(m);
PyErr_SetString(st->error, "something bad happened");
return NULL;
}
static PyMethodDef myextension_methods[] = {
{"error_out", (PyCFunction)error_out, METH_NOARGS, NULL},
{NULL, NULL}
};
#if PY_MAJOR_VERSION >= 3
static int myextension_traverse(PyObject *m, visitproc visit, void *arg) {
Py_VISIT(GETSTATE(m)->error);
return 0;
}
static int myextension_clear(PyObject *m) {
Py_CLEAR(GETSTATE(m)->error);
return 0;
}
static struct PyModuleDef moduledef = {
PyModuleDef_HEAD_INIT,
"myextension",
NULL,
sizeof(struct module_state),
myextension_methods,
NULL,
myextension_traverse,
myextension_clear,
NULL
};
#define INITERROR return NULL
PyMODINIT_FUNC
PyInit_myextension(void)
#else
#define INITERROR return
void
initmyextension(void)
#endif
{
#if PY_MAJOR_VERSION >= 3
PyObject *module = PyModule_Create(&moduledef);
#else
PyObject *module = Py_InitModule("myextension", myextension_methods);
#endif
if (module == NULL)
INITERROR;
struct module_state *st = GETSTATE(module);
st->error = PyErr_NewException("myextension.Error", NULL, NULL);
if (st->error == NULL) {
Py_DECREF(module);
INITERROR;
}
#if PY_MAJOR_VERSION >= 3
return module;
#endif
}
CObject replaced with Capsule
=============================
The :c:type:`Capsule` object was introduced in Python 3.1 and 2.7 to replace
:c:type:`CObject`. CObjects were useful,
but the :c:type:`CObject` API was problematic: it didn't permit distinguishing
between valid CObjects, which allowed mismatched CObjects to crash the
interpreter, and some of its APIs relied on undefined behavior in C.
(For further reading on the rationale behind Capsules, please see :issue:`5630`.)
If you're currently using CObjects, and you want to migrate to 3.1 or newer,
you'll need to switch to Capsules.
:c:type:`CObject` was deprecated in 3.1 and 2.7 and completely removed in
Python 3.2. If you only support 2.7, or 3.1 and above, you
can simply switch to :c:type:`Capsule`. If you need to support Python 3.0,
or versions of Python earlier than 2.7,
you'll have to support both CObjects and Capsules.
(Note that Python 3.0 is no longer supported, and it is not recommended
for production use.)
The following example header file :file:`capsulethunk.h` may
solve the problem for you. Simply write your code against the
:c:type:`Capsule` API and include this header file after
:file:`Python.h`. Your code will automatically use Capsules
in versions of Python with Capsules, and switch to CObjects
when Capsules are unavailable.
:file:`capsulethunk.h` simulates Capsules using CObjects. However,
:c:type:`CObject` provides no place to store the capsule's "name". As a
result the simulated :c:type:`Capsule` objects created by :file:`capsulethunk.h`
behave slightly differently from real Capsules. Specifically:
* The name parameter passed in to :c:func:`PyCapsule_New` is ignored.
* The name parameter passed in to :c:func:`PyCapsule_IsValid` and
:c:func:`PyCapsule_GetPointer` is ignored, and no error checking
of the name is performed.
* :c:func:`PyCapsule_GetName` always returns NULL.
* :c:func:`PyCapsule_SetName` always raises an exception and
returns failure. (Since there's no way to store a name
in a CObject, noisy failure of :c:func:`PyCapsule_SetName`
was deemed preferable to silent failure here. If this is
inconvenient, feel free to modify your local
copy as you see fit.)
You can find :file:`capsulethunk.h` in the Python source distribution
as :source:`Doc/includes/capsulethunk.h`. We also include it here for
your convenience:
.. literalinclude:: ../includes/capsulethunk.h
Other options
=============
If you are writing a new extension module, you might consider `Cython
<http://cython.org/>`_. It translates a Python-like language to C. The
extension modules it creates are compatible with Python 3 and Python 2.
PK %�\a0���U �U " html/_sources/howto/curses.rst.txtnu �[��� .. _curses-howto:
**********************************
Curses Programming with Python
**********************************
:Author: A.M. Kuchling, Eric S. Raymond
:Release: 2.03
.. topic:: Abstract
This document describes how to write text-mode programs with Python 2.x, using
the :mod:`curses` extension module to control the display.
What is curses?
===============
The curses library supplies a terminal-independent screen-painting and
keyboard-handling facility for text-based terminals; such terminals include
VT100s, the Linux console, and the simulated terminal provided by X11 programs
such as xterm and rxvt. Display terminals support various control codes to
perform common operations such as moving the cursor, scrolling the screen, and
erasing areas. Different terminals use widely differing codes, and often have
their own minor quirks.
In a world of X displays, one might ask "why bother"? It's true that
character-cell display terminals are an obsolete technology, but there are
niches in which being able to do fancy things with them are still valuable. One
is on small-footprint or embedded Unixes that don't carry an X server. Another
is for tools like OS installers and kernel configurators that may have to run
before X is available.
The curses library hides all the details of different terminals, and provides
the programmer with an abstraction of a display, containing multiple
non-overlapping windows. The contents of a window can be changed in various
ways---adding text, erasing it, changing its appearance---and the curses library
will automagically figure out what control codes need to be sent to the terminal
to produce the right output.
The curses library was originally written for BSD Unix; the later System V
versions of Unix from AT&T added many enhancements and new functions. BSD curses
is no longer maintained, having been replaced by ncurses, which is an
open-source implementation of the AT&T interface. If you're using an
open-source Unix such as Linux or FreeBSD, your system almost certainly uses
ncurses. Since most current commercial Unix versions are based on System V
code, all the functions described here will probably be available. The older
versions of curses carried by some proprietary Unixes may not support
everything, though.
No one has made a Windows port of the curses module. On a Windows platform, try
the Console module written by Fredrik Lundh. The Console module provides
cursor-addressable text output, plus full support for mouse and keyboard input,
and is available from http://effbot.org/zone/console-index.htm.
The Python curses module
------------------------
Thy Python module is a fairly simple wrapper over the C functions provided by
curses; if you're already familiar with curses programming in C, it's really
easy to transfer that knowledge to Python. The biggest difference is that the
Python interface makes things simpler, by merging different C functions such as
:func:`addstr`, :func:`mvaddstr`, :func:`mvwaddstr`, into a single
:meth:`addstr` method. You'll see this covered in more detail later.
This HOWTO is simply an introduction to writing text-mode programs with curses
and Python. It doesn't attempt to be a complete guide to the curses API; for
that, see the Python library guide's section on ncurses, and the C manual pages
for ncurses. It will, however, give you the basic ideas.
Starting and ending a curses application
========================================
Before doing anything, curses must be initialized. This is done by calling the
:func:`initscr` function, which will determine the terminal type, send any
required setup codes to the terminal, and create various internal data
structures. If successful, :func:`initscr` returns a window object representing
the entire screen; this is usually called ``stdscr``, after the name of the
corresponding C variable. ::
import curses
stdscr = curses.initscr()
Usually curses applications turn off automatic echoing of keys to the screen, in
order to be able to read keys and only display them under certain circumstances.
This requires calling the :func:`noecho` function. ::
curses.noecho()
Applications will also commonly need to react to keys instantly, without
requiring the Enter key to be pressed; this is called cbreak mode, as opposed to
the usual buffered input mode. ::
curses.cbreak()
Terminals usually return special keys, such as the cursor keys or navigation
keys such as Page Up and Home, as a multibyte escape sequence. While you could
write your application to expect such sequences and process them accordingly,
curses can do it for you, returning a special value such as
:const:`curses.KEY_LEFT`. To get curses to do the job, you'll have to enable
keypad mode. ::
stdscr.keypad(1)
Terminating a curses application is much easier than starting one. You'll need
to call ::
curses.nocbreak(); stdscr.keypad(0); curses.echo()
to reverse the curses-friendly terminal settings. Then call the :func:`endwin`
function to restore the terminal to its original operating mode. ::
curses.endwin()
A common problem when debugging a curses application is to get your terminal
messed up when the application dies without restoring the terminal to its
previous state. In Python this commonly happens when your code is buggy and
raises an uncaught exception. Keys are no longer echoed to the screen when
you type them, for example, which makes using the shell difficult.
In Python you can avoid these complications and make debugging much easier by
importing the :func:`curses.wrapper` function. It takes a callable and does
the initializations described above, also initializing colors if color support
is present. It then runs your provided callable and finally deinitializes
appropriately. The callable is called inside a try-catch clause which catches
exceptions, performs curses deinitialization, and then passes the exception
upwards. Thus, your terminal won't be left in a funny state on exception.
Windows and Pads
================
Windows are the basic abstraction in curses. A window object represents a
rectangular area of the screen, and supports various methods to display text,
erase it, allow the user to input strings, and so forth.
The ``stdscr`` object returned by the :func:`initscr` function is a window
object that covers the entire screen. Many programs may need only this single
window, but you might wish to divide the screen into smaller windows, in order
to redraw or clear them separately. The :func:`newwin` function creates a new
window of a given size, returning the new window object. ::
begin_x = 20; begin_y = 7
height = 5; width = 40
win = curses.newwin(height, width, begin_y, begin_x)
A word about the coordinate system used in curses: coordinates are always passed
in the order *y,x*, and the top-left corner of a window is coordinate (0,0).
This breaks a common convention for handling coordinates, where the *x*
coordinate usually comes first. This is an unfortunate difference from most
other computer applications, but it's been part of curses since it was first
written, and it's too late to change things now.
When you call a method to display or erase text, the effect doesn't immediately
show up on the display. This is because curses was originally written with slow
300-baud terminal connections in mind; with these terminals, minimizing the time
required to redraw the screen is very important. This lets curses accumulate
changes to the screen, and display them in the most efficient manner. For
example, if your program displays some characters in a window, and then clears
the window, there's no need to send the original characters because they'd never
be visible.
Accordingly, curses requires that you explicitly tell it to redraw windows,
using the :func:`refresh` method of window objects. In practice, this doesn't
really complicate programming with curses much. Most programs go into a flurry
of activity, and then pause waiting for a keypress or some other action on the
part of the user. All you have to do is to be sure that the screen has been
redrawn before pausing to wait for user input, by simply calling
``stdscr.refresh()`` or the :func:`refresh` method of some other relevant
window.
A pad is a special case of a window; it can be larger than the actual display
screen, and only a portion of it displayed at a time. Creating a pad simply
requires the pad's height and width, while refreshing a pad requires giving the
coordinates of the on-screen area where a subsection of the pad will be
displayed. ::
pad = curses.newpad(100, 100)
# These loops fill the pad with letters; this is
# explained in the next section
for y in range(0, 100):
for x in range(0, 100):
try:
pad.addch(y,x, ord('a') + (x*x+y*y) % 26)
except curses.error:
pass
# Displays a section of the pad in the middle of the screen
pad.refresh(0,0, 5,5, 20,75)
The :func:`refresh` call displays a section of the pad in the rectangle
extending from coordinate (5,5) to coordinate (20,75) on the screen; the upper
left corner of the displayed section is coordinate (0,0) on the pad. Beyond
that difference, pads are exactly like ordinary windows and support the same
methods.
If you have multiple windows and pads on screen there is a more efficient way to
go, which will prevent annoying screen flicker at refresh time. Use the
:meth:`noutrefresh` method of each window to update the data structure
representing the desired state of the screen; then change the physical screen to
match the desired state in one go with the function :func:`doupdate`. The
normal :meth:`refresh` method calls :func:`doupdate` as its last act.
Displaying Text
===============
From a C programmer's point of view, curses may sometimes look like a twisty
maze of functions, all subtly different. For example, :func:`addstr` displays a
string at the current cursor location in the ``stdscr`` window, while
:func:`mvaddstr` moves to a given y,x coordinate first before displaying the
string. :func:`waddstr` is just like :func:`addstr`, but allows specifying a
window to use, instead of using ``stdscr`` by default. :func:`mvwaddstr` follows
similarly.
Fortunately the Python interface hides all these details; ``stdscr`` is a window
object like any other, and methods like :func:`addstr` accept multiple argument
forms. Usually there are four different forms.
+---------------------------------+-----------------------------------------------+
| Form | Description |
+=================================+===============================================+
| *str* or *ch* | Display the string *str* or character *ch* at |
| | the current position |
+---------------------------------+-----------------------------------------------+
| *str* or *ch*, *attr* | Display the string *str* or character *ch*, |
| | using attribute *attr* at the current |
| | position |
+---------------------------------+-----------------------------------------------+
| *y*, *x*, *str* or *ch* | Move to position *y,x* within the window, and |
| | display *str* or *ch* |
+---------------------------------+-----------------------------------------------+
| *y*, *x*, *str* or *ch*, *attr* | Move to position *y,x* within the window, and |
| | display *str* or *ch*, using attribute *attr* |
+---------------------------------+-----------------------------------------------+
Attributes allow displaying text in highlighted forms, such as in boldface,
underline, reverse code, or in color. They'll be explained in more detail in
the next subsection.
The :func:`addstr` function takes a Python string as the value to be displayed,
while the :func:`addch` functions take a character, which can be either a Python
string of length 1 or an integer. If it's a string, you're limited to
displaying characters between 0 and 255. SVr4 curses provides constants for
extension characters; these constants are integers greater than 255. For
example, :const:`ACS_PLMINUS` is a +/- symbol, and :const:`ACS_ULCORNER` is the
upper left corner of a box (handy for drawing borders).
Windows remember where the cursor was left after the last operation, so if you
leave out the *y,x* coordinates, the string or character will be displayed
wherever the last operation left off. You can also move the cursor with the
``move(y,x)`` method. Because some terminals always display a flashing cursor,
you may want to ensure that the cursor is positioned in some location where it
won't be distracting; it can be confusing to have the cursor blinking at some
apparently random location.
If your application doesn't need a blinking cursor at all, you can call
``curs_set(0)`` to make it invisible. Equivalently, and for compatibility with
older curses versions, there's a ``leaveok(bool)`` function. When *bool* is
true, the curses library will attempt to suppress the flashing cursor, and you
won't need to worry about leaving it in odd locations.
Attributes and Color
--------------------
Characters can be displayed in different ways. Status lines in a text-based
application are commonly shown in reverse video; a text viewer may need to
highlight certain words. curses supports this by allowing you to specify an
attribute for each cell on the screen.
An attribute is an integer, each bit representing a different attribute. You can
try to display text with multiple attribute bits set, but curses doesn't
guarantee that all the possible combinations are available, or that they're all
visually distinct. That depends on the ability of the terminal being used, so
it's safest to stick to the most commonly available attributes, listed here.
+----------------------+--------------------------------------+
| Attribute | Description |
+======================+======================================+
| :const:`A_BLINK` | Blinking text |
+----------------------+--------------------------------------+
| :const:`A_BOLD` | Extra bright or bold text |
+----------------------+--------------------------------------+
| :const:`A_DIM` | Half bright text |
+----------------------+--------------------------------------+
| :const:`A_REVERSE` | Reverse-video text |
+----------------------+--------------------------------------+
| :const:`A_STANDOUT` | The best highlighting mode available |
+----------------------+--------------------------------------+
| :const:`A_UNDERLINE` | Underlined text |
+----------------------+--------------------------------------+
So, to display a reverse-video status line on the top line of the screen, you
could code::
stdscr.addstr(0, 0, "Current mode: Typing mode",
curses.A_REVERSE)
stdscr.refresh()
The curses library also supports color on those terminals that provide it. The
most common such terminal is probably the Linux console, followed by color
xterms.
To use color, you must call the :func:`start_color` function soon after calling
:func:`initscr`, to initialize the default color set (the
:func:`curses.wrapper.wrapper` function does this automatically). Once that's
done, the :func:`has_colors` function returns TRUE if the terminal in use can
actually display color. (Note: curses uses the American spelling 'color',
instead of the Canadian/British spelling 'colour'. If you're used to the
British spelling, you'll have to resign yourself to misspelling it for the sake
of these functions.)
The curses library maintains a finite number of color pairs, containing a
foreground (or text) color and a background color. You can get the attribute
value corresponding to a color pair with the :func:`color_pair` function; this
can be bitwise-OR'ed with other attributes such as :const:`A_REVERSE`, but
again, such combinations are not guaranteed to work on all terminals.
An example, which displays a line of text using color pair 1::
stdscr.addstr("Pretty text", curses.color_pair(1))
stdscr.refresh()
As I said before, a color pair consists of a foreground and background color.
:func:`start_color` initializes 8 basic colors when it activates color mode.
They are: 0:black, 1:red, 2:green, 3:yellow, 4:blue, 5:magenta, 6:cyan, and
7:white. The curses module defines named constants for each of these colors:
:const:`curses.COLOR_BLACK`, :const:`curses.COLOR_RED`, and so forth.
The ``init_pair(n, f, b)`` function changes the definition of color pair *n*, to
foreground color f and background color b. Color pair 0 is hard-wired to white
on black, and cannot be changed.
Let's put all this together. To change color 1 to red text on a white
background, you would call::
curses.init_pair(1, curses.COLOR_RED, curses.COLOR_WHITE)
When you change a color pair, any text already displayed using that color pair
will change to the new colors. You can also display new text in this color
with::
stdscr.addstr(0,0, "RED ALERT!", curses.color_pair(1))
Very fancy terminals can change the definitions of the actual colors to a given
RGB value. This lets you change color 1, which is usually red, to purple or
blue or any other color you like. Unfortunately, the Linux console doesn't
support this, so I'm unable to try it out, and can't provide any examples. You
can check if your terminal can do this by calling :func:`can_change_color`,
which returns TRUE if the capability is there. If you're lucky enough to have
such a talented terminal, consult your system's man pages for more information.
User Input
==========
The curses library itself offers only very simple input mechanisms. Python's
support adds a text-input widget that makes up some of the lack.
The most common way to get input to a window is to use its :meth:`getch` method.
:meth:`getch` pauses and waits for the user to hit a key, displaying it if
:func:`echo` has been called earlier. You can optionally specify a coordinate
to which the cursor should be moved before pausing.
It's possible to change this behavior with the method :meth:`nodelay`. After
``nodelay(1)``, :meth:`getch` for the window becomes non-blocking and returns
``curses.ERR`` (a value of -1) when no input is ready. There's also a
:func:`halfdelay` function, which can be used to (in effect) set a timer on each
:meth:`getch`; if no input becomes available within a specified
delay (measured in tenths of a second), curses raises an exception.
The :meth:`getch` method returns an integer; if it's between 0 and 255, it
represents the ASCII code of the key pressed. Values greater than 255 are
special keys such as Page Up, Home, or the cursor keys. You can compare the
value returned to constants such as :const:`curses.KEY_PPAGE`,
:const:`curses.KEY_HOME`, or :const:`curses.KEY_LEFT`. Usually the main loop of
your program will look something like this::
while 1:
c = stdscr.getch()
if c == ord('p'):
PrintDocument()
elif c == ord('q'):
break # Exit the while()
elif c == curses.KEY_HOME:
x = y = 0
The :mod:`curses.ascii` module supplies ASCII class membership functions that
take either integer or 1-character-string arguments; these may be useful in
writing more readable tests for your command interpreters. It also supplies
conversion functions that take either integer or 1-character-string arguments
and return the same type. For example, :func:`curses.ascii.ctrl` returns the
control character corresponding to its argument.
There's also a method to retrieve an entire string, :const:`getstr()`. It isn't
used very often, because its functionality is quite limited; the only editing
keys available are the backspace key and the Enter key, which terminates the
string. It can optionally be limited to a fixed number of characters. ::
curses.echo() # Enable echoing of characters
# Get a 15-character string, with the cursor on the top line
s = stdscr.getstr(0,0, 15)
The Python :mod:`curses.textpad` module supplies something better. With it, you
can turn a window into a text box that supports an Emacs-like set of
keybindings. Various methods of :class:`Textbox` class support editing with
input validation and gathering the edit results either with or without trailing
spaces. See the library documentation on :mod:`curses.textpad` for the
details.
For More Information
====================
This HOWTO didn't cover some advanced topics, such as screen-scraping or
capturing mouse events from an xterm instance. But the Python library page for
the curses modules is now pretty complete. You should browse it next.
If you're in doubt about the detailed behavior of any of the ncurses entry
points, consult the manual pages for your curses implementation, whether it's
ncurses or a proprietary Unix vendor's. The manual pages will document any
quirks, and provide complete lists of all the functions, attributes, and
:const:`ACS_\*` characters available to you.
Because the curses API is so large, some functions aren't supported in the
Python interface, not because they're difficult to implement, but because no one
has needed them yet. Feel free to add them and then submit a patch. Also, we
don't yet have support for the menu library associated with
ncurses; feel free to add that.
If you write an interesting little program, feel free to contribute it as
another demo. We can always use more of them!
The ncurses FAQ: http://invisible-island.net/ncurses/ncurses.faq.html
PK %�\�X�KID ID & html/_sources/howto/descriptor.rst.txtnu �[��� ======================
Descriptor HowTo Guide
======================
:Author: Raymond Hettinger
:Contact: <python at rcn dot com>
.. Contents::
Abstract
--------
Defines descriptors, summarizes the protocol, and shows how descriptors are
called. Examines a custom descriptor and several built-in python descriptors
including functions, properties, static methods, and class methods. Shows how
each works by giving a pure Python equivalent and a sample application.
Learning about descriptors not only provides access to a larger toolset, it
creates a deeper understanding of how Python works and an appreciation for the
elegance of its design.
Definition and Introduction
---------------------------
In general, a descriptor is an object attribute with "binding behavior", one
whose attribute access has been overridden by methods in the descriptor
protocol. Those methods are :meth:`__get__`, :meth:`__set__`, and
:meth:`__delete__`. If any of those methods are defined for an object, it is
said to be a descriptor.
The default behavior for attribute access is to get, set, or delete the
attribute from an object's dictionary. For instance, ``a.x`` has a lookup chain
starting with ``a.__dict__['x']``, then ``type(a).__dict__['x']``, and
continuing through the base classes of ``type(a)`` excluding metaclasses. If the
looked-up value is an object defining one of the descriptor methods, then Python
may override the default behavior and invoke the descriptor method instead.
Where this occurs in the precedence chain depends on which descriptor methods
were defined. Note that descriptors are only invoked for new style objects or
classes (a class is new style if it inherits from :class:`object` or
:class:`type`).
Descriptors are a powerful, general purpose protocol. They are the mechanism
behind properties, methods, static methods, class methods, and :func:`super()`.
They are used throughout Python itself to implement the new style classes
introduced in version 2.2. Descriptors simplify the underlying C-code and offer
a flexible set of new tools for everyday Python programs.
Descriptor Protocol
-------------------
``descr.__get__(self, obj, type=None) --> value``
``descr.__set__(self, obj, value) --> None``
``descr.__delete__(self, obj) --> None``
That is all there is to it. Define any of these methods and an object is
considered a descriptor and can override default behavior upon being looked up
as an attribute.
If an object defines both :meth:`__get__` and :meth:`__set__`, it is considered
a data descriptor. Descriptors that only define :meth:`__get__` are called
non-data descriptors (they are typically used for methods but other uses are
possible).
Data and non-data descriptors differ in how overrides are calculated with
respect to entries in an instance's dictionary. If an instance's dictionary
has an entry with the same name as a data descriptor, the data descriptor
takes precedence. If an instance's dictionary has an entry with the same
name as a non-data descriptor, the dictionary entry takes precedence.
To make a read-only data descriptor, define both :meth:`__get__` and
:meth:`__set__` with the :meth:`__set__` raising an :exc:`AttributeError` when
called. Defining the :meth:`__set__` method with an exception raising
placeholder is enough to make it a data descriptor.
Invoking Descriptors
--------------------
A descriptor can be called directly by its method name. For example,
``d.__get__(obj)``.
Alternatively, it is more common for a descriptor to be invoked automatically
upon attribute access. For example, ``obj.d`` looks up ``d`` in the dictionary
of ``obj``. If ``d`` defines the method :meth:`__get__`, then ``d.__get__(obj)``
is invoked according to the precedence rules listed below.
The details of invocation depend on whether ``obj`` is an object or a class.
Either way, descriptors only work for new style objects and classes. A class is
new style if it is a subclass of :class:`object`.
For objects, the machinery is in :meth:`object.__getattribute__` which
transforms ``b.x`` into ``type(b).__dict__['x'].__get__(b, type(b))``. The
implementation works through a precedence chain that gives data descriptors
priority over instance variables, instance variables priority over non-data
descriptors, and assigns lowest priority to :meth:`__getattr__` if provided.
The full C implementation can be found in :c:func:`PyObject_GenericGetAttr()` in
:source:`Objects/object.c`.
For classes, the machinery is in :meth:`type.__getattribute__` which transforms
``B.x`` into ``B.__dict__['x'].__get__(None, B)``. In pure Python, it looks
like::
def __getattribute__(self, key):
"Emulate type_getattro() in Objects/typeobject.c"
v = object.__getattribute__(self, key)
if hasattr(v, '__get__'):
return v.__get__(None, self)
return v
The important points to remember are:
* descriptors are invoked by the :meth:`__getattribute__` method
* overriding :meth:`__getattribute__` prevents automatic descriptor calls
* :meth:`__getattribute__` is only available with new style classes and objects
* :meth:`object.__getattribute__` and :meth:`type.__getattribute__` make
different calls to :meth:`__get__`.
* data descriptors always override instance dictionaries.
* non-data descriptors may be overridden by instance dictionaries.
The object returned by ``super()`` also has a custom :meth:`__getattribute__`
method for invoking descriptors. The call ``super(B, obj).m()`` searches
``obj.__class__.__mro__`` for the base class ``A`` immediately following ``B``
and then returns ``A.__dict__['m'].__get__(obj, B)``. If not a descriptor,
``m`` is returned unchanged. If not in the dictionary, ``m`` reverts to a
search using :meth:`object.__getattribute__`.
Note, in Python 2.2, ``super(B, obj).m()`` would only invoke :meth:`__get__` if
``m`` was a data descriptor. In Python 2.3, non-data descriptors also get
invoked unless an old-style class is involved. The implementation details are
in :c:func:`super_getattro()` in :source:`Objects/typeobject.c`.
.. _`Guido's Tutorial`: https://www.python.org/download/releases/2.2.3/descrintro/#cooperation
The details above show that the mechanism for descriptors is embedded in the
:meth:`__getattribute__()` methods for :class:`object`, :class:`type`, and
:func:`super`. Classes inherit this machinery when they derive from
:class:`object` or if they have a meta-class providing similar functionality.
Likewise, classes can turn-off descriptor invocation by overriding
:meth:`__getattribute__()`.
Descriptor Example
------------------
The following code creates a class whose objects are data descriptors which
print a message for each get or set. Overriding :meth:`__getattribute__` is
alternate approach that could do this for every attribute. However, this
descriptor is useful for monitoring just a few chosen attributes::
class RevealAccess(object):
"""A data descriptor that sets and returns values
normally and prints a message logging their access.
"""
def __init__(self, initval=None, name='var'):
self.val = initval
self.name = name
def __get__(self, obj, objtype):
print 'Retrieving', self.name
return self.val
def __set__(self, obj, val):
print 'Updating', self.name
self.val = val
>>> class MyClass(object):
... x = RevealAccess(10, 'var "x"')
... y = 5
...
>>> m = MyClass()
>>> m.x
Retrieving var "x"
10
>>> m.x = 20
Updating var "x"
>>> m.x
Retrieving var "x"
20
>>> m.y
5
The protocol is simple and offers exciting possibilities. Several use cases are
so common that they have been packaged into individual function calls.
Properties, bound and unbound methods, static methods, and class methods are all
based on the descriptor protocol.
Properties
----------
Calling :func:`property` is a succinct way of building a data descriptor that
triggers function calls upon access to an attribute. Its signature is::
property(fget=None, fset=None, fdel=None, doc=None) -> property attribute
The documentation shows a typical use to define a managed attribute ``x``::
class C(object):
def getx(self): return self.__x
def setx(self, value): self.__x = value
def delx(self): del self.__x
x = property(getx, setx, delx, "I'm the 'x' property.")
To see how :func:`property` is implemented in terms of the descriptor protocol,
here is a pure Python equivalent::
class Property(object):
"Emulate PyProperty_Type() in Objects/descrobject.c"
def __init__(self, fget=None, fset=None, fdel=None, doc=None):
self.fget = fget
self.fset = fset
self.fdel = fdel
if doc is None and fget is not None:
doc = fget.__doc__
self.__doc__ = doc
def __get__(self, obj, objtype=None):
if obj is None:
return self
if self.fget is None:
raise AttributeError("unreadable attribute")
return self.fget(obj)
def __set__(self, obj, value):
if self.fset is None:
raise AttributeError("can't set attribute")
self.fset(obj, value)
def __delete__(self, obj):
if self.fdel is None:
raise AttributeError("can't delete attribute")
self.fdel(obj)
def getter(self, fget):
return type(self)(fget, self.fset, self.fdel, self.__doc__)
def setter(self, fset):
return type(self)(self.fget, fset, self.fdel, self.__doc__)
def deleter(self, fdel):
return type(self)(self.fget, self.fset, fdel, self.__doc__)
The :func:`property` builtin helps whenever a user interface has granted
attribute access and then subsequent changes require the intervention of a
method.
For instance, a spreadsheet class may grant access to a cell value through
``Cell('b10').value``. Subsequent improvements to the program require the cell
to be recalculated on every access; however, the programmer does not want to
affect existing client code accessing the attribute directly. The solution is
to wrap access to the value attribute in a property data descriptor::
class Cell(object):
. . .
def getvalue(self):
"Recalculate the cell before returning value"
self.recalc()
return self._value
value = property(getvalue)
Functions and Methods
---------------------
Python's object oriented features are built upon a function based environment.
Using non-data descriptors, the two are merged seamlessly.
Class dictionaries store methods as functions. In a class definition, methods
are written using :keyword:`def` and :keyword:`lambda`, the usual tools for
creating functions. The only difference from regular functions is that the
first argument is reserved for the object instance. By Python convention, the
instance reference is called *self* but may be called *this* or any other
variable name.
To support method calls, functions include the :meth:`__get__` method for
binding methods during attribute access. This means that all functions are
non-data descriptors which return bound or unbound methods depending whether
they are invoked from an object or a class. In pure python, it works like
this::
class Function(object):
. . .
def __get__(self, obj, objtype=None):
"Simulate func_descr_get() in Objects/funcobject.c"
return types.MethodType(self, obj, objtype)
Running the interpreter shows how the function descriptor works in practice::
>>> class D(object):
... def f(self, x):
... return x
...
>>> d = D()
>>> D.__dict__['f'] # Stored internally as a function
<function f at 0x00C45070>
>>> D.f # Get from a class becomes an unbound method
<unbound method D.f>
>>> d.f # Get from an instance becomes a bound method
<bound method D.f of <__main__.D object at 0x00B18C90>>
The output suggests that bound and unbound methods are two different types.
While they could have been implemented that way, the actual C implementation of
:c:type:`PyMethod_Type` in :source:`Objects/classobject.c` is a single object
with two different representations depending on whether the :attr:`im_self`
field is set or is *NULL* (the C equivalent of ``None``).
Likewise, the effects of calling a method object depend on the :attr:`im_self`
field. If set (meaning bound), the original function (stored in the
:attr:`im_func` field) is called as expected with the first argument set to the
instance. If unbound, all of the arguments are passed unchanged to the original
function. The actual C implementation of :func:`instancemethod_call()` is only
slightly more complex in that it includes some type checking.
Static Methods and Class Methods
--------------------------------
Non-data descriptors provide a simple mechanism for variations on the usual
patterns of binding functions into methods.
To recap, functions have a :meth:`__get__` method so that they can be converted
to a method when accessed as attributes. The non-data descriptor transforms an
``obj.f(*args)`` call into ``f(obj, *args)``. Calling ``klass.f(*args)``
becomes ``f(*args)``.
This chart summarizes the binding and its two most useful variants:
+-----------------+----------------------+------------------+
| Transformation | Called from an | Called from a |
| | Object | Class |
+=================+======================+==================+
| function | f(obj, \*args) | f(\*args) |
+-----------------+----------------------+------------------+
| staticmethod | f(\*args) | f(\*args) |
+-----------------+----------------------+------------------+
| classmethod | f(type(obj), \*args) | f(klass, \*args) |
+-----------------+----------------------+------------------+
Static methods return the underlying function without changes. Calling either
``c.f`` or ``C.f`` is the equivalent of a direct lookup into
``object.__getattribute__(c, "f")`` or ``object.__getattribute__(C, "f")``. As a
result, the function becomes identically accessible from either an object or a
class.
Good candidates for static methods are methods that do not reference the
``self`` variable.
For instance, a statistics package may include a container class for
experimental data. The class provides normal methods for computing the average,
mean, median, and other descriptive statistics that depend on the data. However,
there may be useful functions which are conceptually related but do not depend
on the data. For instance, ``erf(x)`` is handy conversion routine that comes up
in statistical work but does not directly depend on a particular dataset.
It can be called either from an object or the class: ``s.erf(1.5) --> .9332`` or
``Sample.erf(1.5) --> .9332``.
Since staticmethods return the underlying function with no changes, the example
calls are unexciting::
>>> class E(object):
... def f(x):
... print x
... f = staticmethod(f)
...
>>> print E.f(3)
3
>>> print E().f(3)
3
Using the non-data descriptor protocol, a pure Python version of
:func:`staticmethod` would look like this::
class StaticMethod(object):
"Emulate PyStaticMethod_Type() in Objects/funcobject.c"
def __init__(self, f):
self.f = f
def __get__(self, obj, objtype=None):
return self.f
Unlike static methods, class methods prepend the class reference to the
argument list before calling the function. This format is the same
for whether the caller is an object or a class::
>>> class E(object):
... def f(klass, x):
... return klass.__name__, x
... f = classmethod(f)
...
>>> print E.f(3)
('E', 3)
>>> print E().f(3)
('E', 3)
This behavior is useful whenever the function only needs to have a class
reference and does not care about any underlying data. One use for classmethods
is to create alternate class constructors. In Python 2.3, the classmethod
:func:`dict.fromkeys` creates a new dictionary from a list of keys. The pure
Python equivalent is::
class Dict(object):
. . .
def fromkeys(klass, iterable, value=None):
"Emulate dict_fromkeys() in Objects/dictobject.c"
d = klass()
for key in iterable:
d[key] = value
return d
fromkeys = classmethod(fromkeys)
Now a new dictionary of unique keys can be constructed like this::
>>> Dict.fromkeys('abracadabra')
{'a': None, 'r': None, 'b': None, 'c': None, 'd': None}
Using the non-data descriptor protocol, a pure Python version of
:func:`classmethod` would look like this::
class ClassMethod(object):
"Emulate PyClassMethod_Type() in Objects/funcobject.c"
def __init__(self, f):
self.f = f
def __get__(self, obj, klass=None):
if klass is None:
klass = type(obj)
def newfunc(*args):
return self.f(klass, *args)
return newfunc
PK %�\�N �w, w, % html/_sources/howto/doanddont.rst.txtnu �[��� ************************************
Idioms and Anti-Idioms in Python
************************************
:Author: Moshe Zadka
This document is placed in the public domain.
.. topic:: Abstract
This document can be considered a companion to the tutorial. It shows how to use
Python, and even more importantly, how *not* to use Python.
Language Constructs You Should Not Use
======================================
While Python has relatively few gotchas compared to other languages, it still
has some constructs which are only useful in corner cases, or are plain
dangerous.
from module import \*
---------------------
Inside Function Definitions
^^^^^^^^^^^^^^^^^^^^^^^^^^^
``from module import *`` is *invalid* inside function definitions. While many
versions of Python do not check for the invalidity, it does not make it more
valid, no more than having a smart lawyer makes a man innocent. Do not use it
like that ever. Even in versions where it was accepted, it made the function
execution slower, because the compiler could not be certain which names were
local and which were global. In Python 2.1 this construct causes warnings, and
sometimes even errors.
At Module Level
^^^^^^^^^^^^^^^
While it is valid to use ``from module import *`` at module level it is usually
a bad idea. For one, this loses an important property Python otherwise has ---
you can know where each toplevel name is defined by a simple "search" function
in your favourite editor. You also open yourself to trouble in the future, if
some module grows additional functions or classes.
One of the most awful questions asked on the newsgroup is why this code::
f = open("www")
f.read()
does not work. Of course, it works just fine (assuming you have a file called
"www".) But it does not work if somewhere in the module, the statement ``from
os import *`` is present. The :mod:`os` module has a function called
:func:`open` which returns an integer. While it is very useful, shadowing a
builtin is one of its least useful properties.
Remember, you can never know for sure what names a module exports, so either
take what you need --- ``from module import name1, name2``, or keep them in the
module and access on a per-need basis --- ``import module;print module.name``.
When It Is Just Fine
^^^^^^^^^^^^^^^^^^^^
There are situations in which ``from module import *`` is just fine:
* The interactive prompt. For example, ``from math import *`` makes Python an
amazing scientific calculator.
* When extending a module in C with a module in Python.
* When the module advertises itself as ``from import *`` safe.
Unadorned :keyword:`exec`, :func:`execfile` and friends
-------------------------------------------------------
The word "unadorned" refers to the use without an explicit dictionary, in which
case those constructs evaluate code in the *current* environment. This is
dangerous for the same reasons ``from import *`` is dangerous --- it might step
over variables you are counting on and mess up things for the rest of your code.
Simply do not do that.
Bad examples::
>>> for name in sys.argv[1:]:
>>> exec "%s=1" % name
>>> def func(s, **kw):
>>> for var, val in kw.items():
>>> exec "s.%s=val" % var # invalid!
>>> execfile("handler.py")
>>> handle()
Good examples::
>>> d = {}
>>> for name in sys.argv[1:]:
>>> d[name] = 1
>>> def func(s, **kw):
>>> for var, val in kw.items():
>>> setattr(s, var, val)
>>> d={}
>>> execfile("handle.py", d, d)
>>> handle = d['handle']
>>> handle()
from module import name1, name2
-------------------------------
This is a "don't" which is much weaker than the previous "don't"s but is still
something you should not do if you don't have good reasons to do that. The
reason it is usually a bad idea is because you suddenly have an object which lives
in two separate namespaces. When the binding in one namespace changes, the
binding in the other will not, so there will be a discrepancy between them. This
happens when, for example, one module is reloaded, or changes the definition of
a function at runtime.
Bad example::
# foo.py
a = 1
# bar.py
from foo import a
if something():
a = 2 # danger: foo.a != a
Good example::
# foo.py
a = 1
# bar.py
import foo
if something():
foo.a = 2
except:
-------
Python has the ``except:`` clause, which catches all exceptions. Since *every*
error in Python raises an exception, using ``except:`` can make many
programming errors look like runtime problems, which hinders the debugging
process.
The following code shows a great example of why this is bad::
try:
foo = opne("file") # misspelled "open"
except:
sys.exit("could not open file!")
The second line triggers a :exc:`NameError`, which is caught by the except
clause. The program will exit, and the error message the program prints will
make you think the problem is the readability of ``"file"`` when in fact
the real error has nothing to do with ``"file"``.
A better way to write the above is ::
try:
foo = opne("file")
except IOError:
sys.exit("could not open file")
When this is run, Python will produce a traceback showing the :exc:`NameError`,
and it will be immediately apparent what needs to be fixed.
.. index:: bare except, except; bare
Because ``except:`` catches *all* exceptions, including :exc:`SystemExit`,
:exc:`KeyboardInterrupt`, and :exc:`GeneratorExit` (which is not an error and
should not normally be caught by user code), using a bare ``except:`` is almost
never a good idea. In situations where you need to catch all "normal" errors,
such as in a framework that runs callbacks, you can catch the base class for
all normal exceptions, :exc:`Exception`. Unfortunately in Python 2.x it is
possible for third-party code to raise exceptions that do not inherit from
:exc:`Exception`, so in Python 2.x there are some cases where you may have to
use a bare ``except:`` and manually re-raise the exceptions you don't want
to catch.
Exceptions
==========
Exceptions are a useful feature of Python. You should learn to raise them
whenever something unexpected occurs, and catch them only where you can do
something about them.
The following is a very popular anti-idiom ::
def get_status(file):
if not os.path.exists(file):
print "file not found"
sys.exit(1)
return open(file).readline()
Consider the case where the file gets deleted between the time the call to
:func:`os.path.exists` is made and the time :func:`open` is called. In that
case the last line will raise an :exc:`IOError`. The same thing would happen
if *file* exists but has no read permission. Since testing this on a normal
machine on existent and non-existent files makes it seem bugless, the test
results will seem fine, and the code will get shipped. Later an unhandled
:exc:`IOError` (or perhaps some other :exc:`EnvironmentError`) escapes to the
user, who gets to watch the ugly traceback.
Here is a somewhat better way to do it. ::
def get_status(file):
try:
return open(file).readline()
except EnvironmentError as err:
print "Unable to open file: {}".format(err)
sys.exit(1)
In this version, *either* the file gets opened and the line is read (so it
works even on flaky NFS or SMB connections), or an error message is printed
that provides all the available information on why the open failed, and the
application is aborted.
However, even this version of :func:`get_status` makes too many assumptions ---
that it will only be used in a short running script, and not, say, in a long
running server. Sure, the caller could do something like ::
try:
status = get_status(log)
except SystemExit:
status = None
But there is a better way. You should try to use as few ``except`` clauses in
your code as you can --- the ones you do use will usually be inside calls which
should always succeed, or a catch-all in a main function.
So, an even better version of :func:`get_status()` is probably ::
def get_status(file):
return open(file).readline()
The caller can deal with the exception if it wants (for example, if it tries
several files in a loop), or just let the exception filter upwards to *its*
caller.
But the last version still has a serious problem --- due to implementation
details in CPython, the file would not be closed when an exception is raised
until the exception handler finishes; and, worse, in other implementations
(e.g., Jython) it might not be closed at all regardless of whether or not
an exception is raised.
The best version of this function uses the ``open()`` call as a context
manager, which will ensure that the file gets closed as soon as the
function returns::
def get_status(file):
with open(file) as fp:
return fp.readline()
Using the Batteries
===================
Every so often, people seem to be writing stuff in the Python library again,
usually poorly. While the occasional module has a poor interface, it is usually
much better to use the rich standard library and data types that come with
Python than inventing your own.
A useful module very few people know about is :mod:`os.path`. It always has the
correct path arithmetic for your operating system, and will usually be much
better than whatever you come up with yourself.
Compare::
# ugh!
return dir+"/"+file
# better
return os.path.join(dir, file)
More useful functions in :mod:`os.path`: :func:`basename`, :func:`dirname` and
:func:`splitext`.
There are also many useful built-in functions people seem not to be aware of
for some reason: :func:`min` and :func:`max` can find the minimum/maximum of
any sequence with comparable semantics, for example, yet many people write
their own :func:`max`/:func:`min`. Another highly useful function is
:func:`reduce` which can be used to repeatedly apply a binary operation to a
sequence, reducing it to a single value. For example, compute a factorial
with a series of multiply operations::
>>> n = 4
>>> import operator
>>> reduce(operator.mul, range(1, n+1))
24
When it comes to parsing numbers, note that :func:`float`, :func:`int` and
:func:`long` all accept string arguments and will reject ill-formed strings
by raising an :exc:`ValueError`.
Using Backslash to Continue Statements
======================================
Since Python treats a newline as a statement terminator, and since statements
are often more than is comfortable to put in one line, many people do::
if foo.bar()['first'][0] == baz.quux(1, 2)[5:9] and \
calculate_number(10, 20) != forbulate(500, 360):
pass
You should realize that this is dangerous: a stray space after the ``\`` would
make this line wrong, and stray spaces are notoriously hard to see in editors.
In this case, at least it would be a syntax error, but if the code was::
value = foo.bar()['first'][0]*baz.quux(1, 2)[5:9] \
+ calculate_number(10, 20)*forbulate(500, 360)
then it would just be subtly wrong.
It is usually much better to use the implicit continuation inside parenthesis:
This version is bulletproof::
value = (foo.bar()['first'][0]*baz.quux(1, 2)[5:9]
+ calculate_number(10, 20)*forbulate(500, 360))
PK %�\<��� � & html/_sources/howto/functional.rst.txtnu �[��� ********************************
Functional Programming HOWTO
********************************
:Author: A. M. Kuchling
:Release: 0.31
In this document, we'll take a tour of Python's features suitable for
implementing programs in a functional style. After an introduction to the
concepts of functional programming, we'll look at language features such as
:term:`iterator`\s and :term:`generator`\s and relevant library modules such as
:mod:`itertools` and :mod:`functools`.
Introduction
============
This section explains the basic concept of functional programming; if you're
just interested in learning about Python language features, skip to the next
section.
Programming languages support decomposing problems in several different ways:
* Most programming languages are **procedural**: programs are lists of
instructions that tell the computer what to do with the program's input. C,
Pascal, and even Unix shells are procedural languages.
* In **declarative** languages, you write a specification that describes the
problem to be solved, and the language implementation figures out how to
perform the computation efficiently. SQL is the declarative language you're
most likely to be familiar with; a SQL query describes the data set you want
to retrieve, and the SQL engine decides whether to scan tables or use indexes,
which subclauses should be performed first, etc.
* **Object-oriented** programs manipulate collections of objects. Objects have
internal state and support methods that query or modify this internal state in
some way. Smalltalk and Java are object-oriented languages. C++ and Python
are languages that support object-oriented programming, but don't force the
use of object-oriented features.
* **Functional** programming decomposes a problem into a set of functions.
Ideally, functions only take inputs and produce outputs, and don't have any
internal state that affects the output produced for a given input. Well-known
functional languages include the ML family (Standard ML, OCaml, and other
variants) and Haskell.
The designers of some computer languages choose to emphasize one particular
approach to programming. This often makes it difficult to write programs that
use a different approach. Other languages are multi-paradigm languages that
support several different approaches. Lisp, C++, and Python are
multi-paradigm; you can write programs or libraries that are largely
procedural, object-oriented, or functional in all of these languages. In a
large program, different sections might be written using different approaches;
the GUI might be object-oriented while the processing logic is procedural or
functional, for example.
In a functional program, input flows through a set of functions. Each function
operates on its input and produces some output. Functional style discourages
functions with side effects that modify internal state or make other changes
that aren't visible in the function's return value. Functions that have no side
effects at all are called **purely functional**. Avoiding side effects means
not using data structures that get updated as a program runs; every function's
output must only depend on its input.
Some languages are very strict about purity and don't even have assignment
statements such as ``a=3`` or ``c = a + b``, but it's difficult to avoid all
side effects. Printing to the screen or writing to a disk file are side
effects, for example. For example, in Python a ``print`` statement or a
``time.sleep(1)`` both return no useful value; they're only called for their
side effects of sending some text to the screen or pausing execution for a
second.
Python programs written in functional style usually won't go to the extreme of
avoiding all I/O or all assignments; instead, they'll provide a
functional-appearing interface but will use non-functional features internally.
For example, the implementation of a function will still use assignments to
local variables, but won't modify global variables or have other side effects.
Functional programming can be considered the opposite of object-oriented
programming. Objects are little capsules containing some internal state along
with a collection of method calls that let you modify this state, and programs
consist of making the right set of state changes. Functional programming wants
to avoid state changes as much as possible and works with data flowing between
functions. In Python you might combine the two approaches by writing functions
that take and return instances representing objects in your application (e-mail
messages, transactions, etc.).
Functional design may seem like an odd constraint to work under. Why should you
avoid objects and side effects? There are theoretical and practical advantages
to the functional style:
* Formal provability.
* Modularity.
* Composability.
* Ease of debugging and testing.
Formal provability
------------------
A theoretical benefit is that it's easier to construct a mathematical proof that
a functional program is correct.
For a long time researchers have been interested in finding ways to
mathematically prove programs correct. This is different from testing a program
on numerous inputs and concluding that its output is usually correct, or reading
a program's source code and concluding that the code looks right; the goal is
instead a rigorous proof that a program produces the right result for all
possible inputs.
The technique used to prove programs correct is to write down **invariants**,
properties of the input data and of the program's variables that are always
true. For each line of code, you then show that if invariants X and Y are true
**before** the line is executed, the slightly different invariants X' and Y' are
true **after** the line is executed. This continues until you reach the end of
the program, at which point the invariants should match the desired conditions
on the program's output.
Functional programming's avoidance of assignments arose because assignments are
difficult to handle with this technique; assignments can break invariants that
were true before the assignment without producing any new invariants that can be
propagated onward.
Unfortunately, proving programs correct is largely impractical and not relevant
to Python software. Even trivial programs require proofs that are several pages
long; the proof of correctness for a moderately complicated program would be
enormous, and few or none of the programs you use daily (the Python interpreter,
your XML parser, your web browser) could be proven correct. Even if you wrote
down or generated a proof, there would then be the question of verifying the
proof; maybe there's an error in it, and you wrongly believe you've proved the
program correct.
Modularity
----------
A more practical benefit of functional programming is that it forces you to
break apart your problem into small pieces. Programs are more modular as a
result. It's easier to specify and write a small function that does one thing
than a large function that performs a complicated transformation. Small
functions are also easier to read and to check for errors.
Ease of debugging and testing
-----------------------------
Testing and debugging a functional-style program is easier.
Debugging is simplified because functions are generally small and clearly
specified. When a program doesn't work, each function is an interface point
where you can check that the data are correct. You can look at the intermediate
inputs and outputs to quickly isolate the function that's responsible for a bug.
Testing is easier because each function is a potential subject for a unit test.
Functions don't depend on system state that needs to be replicated before
running a test; instead you only have to synthesize the right input and then
check that the output matches expectations.
Composability
-------------
As you work on a functional-style program, you'll write a number of functions
with varying inputs and outputs. Some of these functions will be unavoidably
specialized to a particular application, but others will be useful in a wide
variety of programs. For example, a function that takes a directory path and
returns all the XML files in the directory, or a function that takes a filename
and returns its contents, can be applied to many different situations.
Over time you'll form a personal library of utilities. Often you'll assemble
new programs by arranging existing functions in a new configuration and writing
a few functions specialized for the current task.
Iterators
=========
I'll start by looking at a Python language feature that's an important
foundation for writing functional-style programs: iterators.
An iterator is an object representing a stream of data; this object returns the
data one element at a time. A Python iterator must support a method called
``next()`` that takes no arguments and always returns the next element of the
stream. If there are no more elements in the stream, ``next()`` must raise the
``StopIteration`` exception. Iterators don't have to be finite, though; it's
perfectly reasonable to write an iterator that produces an infinite stream of
data.
The built-in :func:`iter` function takes an arbitrary object and tries to return
an iterator that will return the object's contents or elements, raising
:exc:`TypeError` if the object doesn't support iteration. Several of Python's
built-in data types support iteration, the most common being lists and
dictionaries. An object is called an **iterable** object if you can get an
iterator for it.
You can experiment with the iteration interface manually:
>>> L = [1,2,3]
>>> it = iter(L)
>>> print it
<...iterator object at ...>
>>> it.next()
1
>>> it.next()
2
>>> it.next()
3
>>> it.next()
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
StopIteration
>>>
Python expects iterable objects in several different contexts, the most
important being the ``for`` statement. In the statement ``for X in Y``, Y must
be an iterator or some object for which ``iter()`` can create an iterator.
These two statements are equivalent::
for i in iter(obj):
print i
for i in obj:
print i
Iterators can be materialized as lists or tuples by using the :func:`list` or
:func:`tuple` constructor functions:
>>> L = [1,2,3]
>>> iterator = iter(L)
>>> t = tuple(iterator)
>>> t
(1, 2, 3)
Sequence unpacking also supports iterators: if you know an iterator will return
N elements, you can unpack them into an N-tuple:
>>> L = [1,2,3]
>>> iterator = iter(L)
>>> a,b,c = iterator
>>> a,b,c
(1, 2, 3)
Built-in functions such as :func:`max` and :func:`min` can take a single
iterator argument and will return the largest or smallest element. The ``"in"``
and ``"not in"`` operators also support iterators: ``X in iterator`` is true if
X is found in the stream returned by the iterator. You'll run into obvious
problems if the iterator is infinite; ``max()``, ``min()``
will never return, and if the element X never appears in the stream, the
``"in"`` and ``"not in"`` operators won't return either.
Note that you can only go forward in an iterator; there's no way to get the
previous element, reset the iterator, or make a copy of it. Iterator objects
can optionally provide these additional capabilities, but the iterator protocol
only specifies the ``next()`` method. Functions may therefore consume all of
the iterator's output, and if you need to do something different with the same
stream, you'll have to create a new iterator.
Data Types That Support Iterators
---------------------------------
We've already seen how lists and tuples support iterators. In fact, any Python
sequence type, such as strings, will automatically support creation of an
iterator.
Calling :func:`iter` on a dictionary returns an iterator that will loop over the
dictionary's keys:
.. not a doctest since dict ordering varies across Pythons
::
>>> m = {'Jan': 1, 'Feb': 2, 'Mar': 3, 'Apr': 4, 'May': 5, 'Jun': 6,
... 'Jul': 7, 'Aug': 8, 'Sep': 9, 'Oct': 10, 'Nov': 11, 'Dec': 12}
>>> for key in m:
... print key, m[key]
Mar 3
Feb 2
Aug 8
Sep 9
Apr 4
Jun 6
Jul 7
Jan 1
May 5
Nov 11
Dec 12
Oct 10
Note that the order is essentially random, because it's based on the hash
ordering of the objects in the dictionary.
Applying ``iter()`` to a dictionary always loops over the keys, but dictionaries
have methods that return other iterators. If you want to iterate over keys,
values, or key/value pairs, you can explicitly call the ``iterkeys()``,
``itervalues()``, or ``iteritems()`` methods to get an appropriate iterator.
The :func:`dict` constructor can accept an iterator that returns a finite stream
of ``(key, value)`` tuples:
>>> L = [('Italy', 'Rome'), ('France', 'Paris'), ('US', 'Washington DC')]
>>> dict(iter(L))
{'Italy': 'Rome', 'US': 'Washington DC', 'France': 'Paris'}
Files also support iteration by calling the ``readline()`` method until there
are no more lines in the file. This means you can read each line of a file like
this::
for line in file:
# do something for each line
...
Sets can take their contents from an iterable and let you iterate over the set's
elements::
S = set((2, 3, 5, 7, 11, 13))
for i in S:
print i
Generator expressions and list comprehensions
=============================================
Two common operations on an iterator's output are 1) performing some operation
for every element, 2) selecting a subset of elements that meet some condition.
For example, given a list of strings, you might want to strip off trailing
whitespace from each line or extract all the strings containing a given
substring.
List comprehensions and generator expressions (short form: "listcomps" and
"genexps") are a concise notation for such operations, borrowed from the
functional programming language Haskell (https://www.haskell.org/). You can strip
all the whitespace from a stream of strings with the following code::
line_list = [' line 1\n', 'line 2 \n', ...]
# Generator expression -- returns iterator
stripped_iter = (line.strip() for line in line_list)
# List comprehension -- returns list
stripped_list = [line.strip() for line in line_list]
You can select only certain elements by adding an ``"if"`` condition::
stripped_list = [line.strip() for line in line_list
if line != ""]
With a list comprehension, you get back a Python list; ``stripped_list`` is a
list containing the resulting lines, not an iterator. Generator expressions
return an iterator that computes the values as necessary, not needing to
materialize all the values at once. This means that list comprehensions aren't
useful if you're working with iterators that return an infinite stream or a very
large amount of data. Generator expressions are preferable in these situations.
Generator expressions are surrounded by parentheses ("()") and list
comprehensions are surrounded by square brackets ("[]"). Generator expressions
have the form::
( expression for expr in sequence1
if condition1
for expr2 in sequence2
if condition2
for expr3 in sequence3 ...
if condition3
for exprN in sequenceN
if conditionN )
Again, for a list comprehension only the outside brackets are different (square
brackets instead of parentheses).
The elements of the generated output will be the successive values of
``expression``. The ``if`` clauses are all optional; if present, ``expression``
is only evaluated and added to the result when ``condition`` is true.
Generator expressions always have to be written inside parentheses, but the
parentheses signalling a function call also count. If you want to create an
iterator that will be immediately passed to a function you can write::
obj_total = sum(obj.count for obj in list_all_objects())
The ``for...in`` clauses contain the sequences to be iterated over. The
sequences do not have to be the same length, because they are iterated over from
left to right, **not** in parallel. For each element in ``sequence1``,
``sequence2`` is looped over from the beginning. ``sequence3`` is then looped
over for each resulting pair of elements from ``sequence1`` and ``sequence2``.
To put it another way, a list comprehension or generator expression is
equivalent to the following Python code::
for expr1 in sequence1:
if not (condition1):
continue # Skip this element
for expr2 in sequence2:
if not (condition2):
continue # Skip this element
...
for exprN in sequenceN:
if not (conditionN):
continue # Skip this element
# Output the value of
# the expression.
This means that when there are multiple ``for...in`` clauses but no ``if``
clauses, the length of the resulting output will be equal to the product of the
lengths of all the sequences. If you have two lists of length 3, the output
list is 9 elements long:
.. doctest::
:options: +NORMALIZE_WHITESPACE
>>> seq1 = 'abc'
>>> seq2 = (1,2,3)
>>> [(x,y) for x in seq1 for y in seq2]
[('a', 1), ('a', 2), ('a', 3),
('b', 1), ('b', 2), ('b', 3),
('c', 1), ('c', 2), ('c', 3)]
To avoid introducing an ambiguity into Python's grammar, if ``expression`` is
creating a tuple, it must be surrounded with parentheses. The first list
comprehension below is a syntax error, while the second one is correct::
# Syntax error
[ x,y for x in seq1 for y in seq2]
# Correct
[ (x,y) for x in seq1 for y in seq2]
Generators
==========
Generators are a special class of functions that simplify the task of writing
iterators. Regular functions compute a value and return it, but generators
return an iterator that returns a stream of values.
You're doubtless familiar with how regular function calls work in Python or C.
When you call a function, it gets a private namespace where its local variables
are created. When the function reaches a ``return`` statement, the local
variables are destroyed and the value is returned to the caller. A later call
to the same function creates a new private namespace and a fresh set of local
variables. But, what if the local variables weren't thrown away on exiting a
function? What if you could later resume the function where it left off? This
is what generators provide; they can be thought of as resumable functions.
Here's the simplest example of a generator function:
.. testcode::
def generate_ints(N):
for i in range(N):
yield i
Any function containing a ``yield`` keyword is a generator function; this is
detected by Python's :term:`bytecode` compiler which compiles the function
specially as a result.
When you call a generator function, it doesn't return a single value; instead it
returns a generator object that supports the iterator protocol. On executing
the ``yield`` expression, the generator outputs the value of ``i``, similar to a
``return`` statement. The big difference between ``yield`` and a ``return``
statement is that on reaching a ``yield`` the generator's state of execution is
suspended and local variables are preserved. On the next call to the
generator's ``.next()`` method, the function will resume executing.
Here's a sample usage of the ``generate_ints()`` generator:
>>> gen = generate_ints(3)
>>> gen
<generator object generate_ints at ...>
>>> gen.next()
0
>>> gen.next()
1
>>> gen.next()
2
>>> gen.next()
Traceback (most recent call last):
File "stdin", line 1, in <module>
File "stdin", line 2, in generate_ints
StopIteration
You could equally write ``for i in generate_ints(5)``, or ``a,b,c =
generate_ints(3)``.
Inside a generator function, the ``return`` statement can only be used without a
value, and signals the end of the procession of values; after executing a
``return`` the generator cannot return any further values. ``return`` with a
value, such as ``return 5``, is a syntax error inside a generator function. The
end of the generator's results can also be indicated by raising
``StopIteration`` manually, or by just letting the flow of execution fall off
the bottom of the function.
You could achieve the effect of generators manually by writing your own class
and storing all the local variables of the generator as instance variables. For
example, returning a list of integers could be done by setting ``self.count`` to
0, and having the ``next()`` method increment ``self.count`` and return it.
However, for a moderately complicated generator, writing a corresponding class
can be much messier.
The test suite included with Python's library, ``test_generators.py``, contains
a number of more interesting examples. Here's one generator that implements an
in-order traversal of a tree using generators recursively. ::
# A recursive generator that generates Tree leaves in in-order.
def inorder(t):
if t:
for x in inorder(t.left):
yield x
yield t.label
for x in inorder(t.right):
yield x
Two other examples in ``test_generators.py`` produce solutions for the N-Queens
problem (placing N queens on an NxN chess board so that no queen threatens
another) and the Knight's Tour (finding a route that takes a knight to every
square of an NxN chessboard without visiting any square twice).
Passing values into a generator
-------------------------------
In Python 2.4 and earlier, generators only produced output. Once a generator's
code was invoked to create an iterator, there was no way to pass any new
information into the function when its execution is resumed. You could hack
together this ability by making the generator look at a global variable or by
passing in some mutable object that callers then modify, but these approaches
are messy.
In Python 2.5 there's a simple way to pass values into a generator.
:keyword:`yield` became an expression, returning a value that can be assigned to
a variable or otherwise operated on::
val = (yield i)
I recommend that you **always** put parentheses around a ``yield`` expression
when you're doing something with the returned value, as in the above example.
The parentheses aren't always necessary, but it's easier to always add them
instead of having to remember when they're needed.
(PEP 342 explains the exact rules, which are that a ``yield``-expression must
always be parenthesized except when it occurs at the top-level expression on the
right-hand side of an assignment. This means you can write ``val = yield i``
but have to use parentheses when there's an operation, as in ``val = (yield i)
+ 12``.)
Values are sent into a generator by calling its ``send(value)`` method. This
method resumes the generator's code and the ``yield`` expression returns the
specified value. If the regular ``next()`` method is called, the ``yield``
returns ``None``.
Here's a simple counter that increments by 1 and allows changing the value of
the internal counter.
.. testcode::
def counter (maximum):
i = 0
while i < maximum:
val = (yield i)
# If value provided, change counter
if val is not None:
i = val
else:
i += 1
And here's an example of changing the counter:
>>> it = counter(10)
>>> print it.next()
0
>>> print it.next()
1
>>> print it.send(8)
8
>>> print it.next()
9
>>> print it.next()
Traceback (most recent call last):
File "t.py", line 15, in <module>
print it.next()
StopIteration
Because ``yield`` will often be returning ``None``, you should always check for
this case. Don't just use its value in expressions unless you're sure that the
``send()`` method will be the only method used to resume your generator
function.
In addition to ``send()``, there are two other new methods on generators:
* ``throw(type, value=None, traceback=None)`` is used to raise an exception
inside the generator; the exception is raised by the ``yield`` expression
where the generator's execution is paused.
* ``close()`` raises a :exc:`GeneratorExit` exception inside the generator to
terminate the iteration. On receiving this exception, the generator's code
must either raise :exc:`GeneratorExit` or :exc:`StopIteration`; catching the
exception and doing anything else is illegal and will trigger a
:exc:`RuntimeError`. ``close()`` will also be called by Python's garbage
collector when the generator is garbage-collected.
If you need to run cleanup code when a :exc:`GeneratorExit` occurs, I suggest
using a ``try: ... finally:`` suite instead of catching :exc:`GeneratorExit`.
The cumulative effect of these changes is to turn generators from one-way
producers of information into both producers and consumers.
Generators also become **coroutines**, a more generalized form of subroutines.
Subroutines are entered at one point and exited at another point (the top of the
function, and a ``return`` statement), but coroutines can be entered, exited,
and resumed at many different points (the ``yield`` statements).
Built-in functions
==================
Let's look in more detail at built-in functions often used with iterators.
Two of Python's built-in functions, :func:`map` and :func:`filter`, are somewhat
obsolete; they duplicate the features of list comprehensions but return actual
lists instead of iterators.
``map(f, iterA, iterB, ...)`` returns a list containing ``f(iterA[0], iterB[0]),
f(iterA[1], iterB[1]), f(iterA[2], iterB[2]), ...``.
>>> def upper(s):
... return s.upper()
>>> map(upper, ['sentence', 'fragment'])
['SENTENCE', 'FRAGMENT']
>>> [upper(s) for s in ['sentence', 'fragment']]
['SENTENCE', 'FRAGMENT']
As shown above, you can achieve the same effect with a list comprehension. The
:func:`itertools.imap` function does the same thing but can handle infinite
iterators; it'll be discussed later, in the section on the :mod:`itertools` module.
``filter(predicate, iter)`` returns a list that contains all the sequence
elements that meet a certain condition, and is similarly duplicated by list
comprehensions. A **predicate** is a function that returns the truth value of
some condition; for use with :func:`filter`, the predicate must take a single
value.
>>> def is_even(x):
... return (x % 2) == 0
>>> filter(is_even, range(10))
[0, 2, 4, 6, 8]
This can also be written as a list comprehension:
>>> [x for x in range(10) if is_even(x)]
[0, 2, 4, 6, 8]
:func:`filter` also has a counterpart in the :mod:`itertools` module,
:func:`itertools.ifilter`, that returns an iterator and can therefore handle
infinite sequences just as :func:`itertools.imap` can.
``reduce(func, iter, [initial_value])`` doesn't have a counterpart in the
:mod:`itertools` module because it cumulatively performs an operation on all the
iterable's elements and therefore can't be applied to infinite iterables.
``func`` must be a function that takes two elements and returns a single value.
:func:`reduce` takes the first two elements A and B returned by the iterator and
calculates ``func(A, B)``. It then requests the third element, C, calculates
``func(func(A, B), C)``, combines this result with the fourth element returned,
and continues until the iterable is exhausted. If the iterable returns no
values at all, a :exc:`TypeError` exception is raised. If the initial value is
supplied, it's used as a starting point and ``func(initial_value, A)`` is the
first calculation.
>>> import operator
>>> reduce(operator.concat, ['A', 'BB', 'C'])
'ABBC'
>>> reduce(operator.concat, [])
Traceback (most recent call last):
...
TypeError: reduce() of empty sequence with no initial value
>>> reduce(operator.mul, [1,2,3], 1)
6
>>> reduce(operator.mul, [], 1)
1
If you use :func:`operator.add` with :func:`reduce`, you'll add up all the
elements of the iterable. This case is so common that there's a special
built-in called :func:`sum` to compute it:
>>> reduce(operator.add, [1,2,3,4], 0)
10
>>> sum([1,2,3,4])
10
>>> sum([])
0
For many uses of :func:`reduce`, though, it can be clearer to just write the
obvious :keyword:`for` loop::
# Instead of:
product = reduce(operator.mul, [1,2,3], 1)
# You can write:
product = 1
for i in [1,2,3]:
product *= i
``enumerate(iter)`` counts off the elements in the iterable, returning 2-tuples
containing the count and each element.
>>> for item in enumerate(['subject', 'verb', 'object']):
... print item
(0, 'subject')
(1, 'verb')
(2, 'object')
:func:`enumerate` is often used when looping through a list and recording the
indexes at which certain conditions are met::
f = open('data.txt', 'r')
for i, line in enumerate(f):
if line.strip() == '':
print 'Blank line at line #%i' % i
``sorted(iterable, [cmp=None], [key=None], [reverse=False])`` collects all the
elements of the iterable into a list, sorts the list, and returns the sorted
result. The ``cmp``, ``key``, and ``reverse`` arguments are passed through to
the constructed list's ``.sort()`` method. ::
>>> import random
>>> # Generate 8 random numbers between [0, 10000)
>>> rand_list = random.sample(range(10000), 8)
>>> rand_list
[769, 7953, 9828, 6431, 8442, 9878, 6213, 2207]
>>> sorted(rand_list)
[769, 2207, 6213, 6431, 7953, 8442, 9828, 9878]
>>> sorted(rand_list, reverse=True)
[9878, 9828, 8442, 7953, 6431, 6213, 2207, 769]
(For a more detailed discussion of sorting, see the Sorting mini-HOWTO in the
Python wiki at https://wiki.python.org/moin/HowTo/Sorting.)
The ``any(iter)`` and ``all(iter)`` built-ins look at the truth values of an
iterable's contents. :func:`any` returns ``True`` if any element in the iterable is
a true value, and :func:`all` returns ``True`` if all of the elements are true
values:
>>> any([0,1,0])
True
>>> any([0,0,0])
False
>>> any([1,1,1])
True
>>> all([0,1,0])
False
>>> all([0,0,0])
False
>>> all([1,1,1])
True
Small functions and the lambda expression
=========================================
When writing functional-style programs, you'll often need little functions that
act as predicates or that combine elements in some way.
If there's a Python built-in or a module function that's suitable, you don't
need to define a new function at all::
stripped_lines = [line.strip() for line in lines]
existing_files = filter(os.path.exists, file_list)
If the function you need doesn't exist, you need to write it. One way to write
small functions is to use the ``lambda`` statement. ``lambda`` takes a number
of parameters and an expression combining these parameters, and creates a small
function that returns the value of the expression::
lowercase = lambda x: x.lower()
print_assign = lambda name, value: name + '=' + str(value)
adder = lambda x, y: x+y
An alternative is to just use the ``def`` statement and define a function in the
usual way::
def lowercase(x):
return x.lower()
def print_assign(name, value):
return name + '=' + str(value)
def adder(x,y):
return x + y
Which alternative is preferable? That's a style question; my usual course is to
avoid using ``lambda``.
One reason for my preference is that ``lambda`` is quite limited in the
functions it can define. The result has to be computable as a single
expression, which means you can't have multiway ``if... elif... else``
comparisons or ``try... except`` statements. If you try to do too much in a
``lambda`` statement, you'll end up with an overly complicated expression that's
hard to read. Quick, what's the following code doing?
::
total = reduce(lambda a, b: (0, a[1] + b[1]), items)[1]
You can figure it out, but it takes time to disentangle the expression to figure
out what's going on. Using a short nested ``def`` statements makes things a
little bit better::
def combine (a, b):
return 0, a[1] + b[1]
total = reduce(combine, items)[1]
But it would be best of all if I had simply used a ``for`` loop::
total = 0
for a, b in items:
total += b
Or the :func:`sum` built-in and a generator expression::
total = sum(b for a,b in items)
Many uses of :func:`reduce` are clearer when written as ``for`` loops.
Fredrik Lundh once suggested the following set of rules for refactoring uses of
``lambda``:
1) Write a lambda function.
2) Write a comment explaining what the heck that lambda does.
3) Study the comment for a while, and think of a name that captures the essence
of the comment.
4) Convert the lambda to a def statement, using that name.
5) Remove the comment.
I really like these rules, but you're free to disagree
about whether this lambda-free style is better.
The itertools module
====================
The :mod:`itertools` module contains a number of commonly-used iterators as well
as functions for combining several iterators. This section will introduce the
module's contents by showing small examples.
The module's functions fall into a few broad classes:
* Functions that create a new iterator based on an existing iterator.
* Functions for treating an iterator's elements as function arguments.
* Functions for selecting portions of an iterator's output.
* A function for grouping an iterator's output.
Creating new iterators
----------------------
``itertools.count(n)`` returns an infinite stream of integers, increasing by 1
each time. You can optionally supply the starting number, which defaults to 0::
itertools.count() =>
0, 1, 2, 3, 4, 5, 6, 7, 8, 9, ...
itertools.count(10) =>
10, 11, 12, 13, 14, 15, 16, 17, 18, 19, ...
``itertools.cycle(iter)`` saves a copy of the contents of a provided iterable
and returns a new iterator that returns its elements from first to last. The
new iterator will repeat these elements infinitely. ::
itertools.cycle([1,2,3,4,5]) =>
1, 2, 3, 4, 5, 1, 2, 3, 4, 5, ...
``itertools.repeat(elem, [n])`` returns the provided element ``n`` times, or
returns the element endlessly if ``n`` is not provided. ::
itertools.repeat('abc') =>
abc, abc, abc, abc, abc, abc, abc, abc, abc, abc, ...
itertools.repeat('abc', 5) =>
abc, abc, abc, abc, abc
``itertools.chain(iterA, iterB, ...)`` takes an arbitrary number of iterables as
input, and returns all the elements of the first iterator, then all the elements
of the second, and so on, until all of the iterables have been exhausted. ::
itertools.chain(['a', 'b', 'c'], (1, 2, 3)) =>
a, b, c, 1, 2, 3
``itertools.izip(iterA, iterB, ...)`` takes one element from each iterable and
returns them in a tuple::
itertools.izip(['a', 'b', 'c'], (1, 2, 3)) =>
('a', 1), ('b', 2), ('c', 3)
It's similar to the built-in :func:`zip` function, but doesn't construct an
in-memory list and exhaust all the input iterators before returning; instead
tuples are constructed and returned only if they're requested. (The technical
term for this behaviour is `lazy evaluation
<http://en.wikipedia.org/wiki/Lazy_evaluation>`__.)
This iterator is intended to be used with iterables that are all of the same
length. If the iterables are of different lengths, the resulting stream will be
the same length as the shortest iterable. ::
itertools.izip(['a', 'b'], (1, 2, 3)) =>
('a', 1), ('b', 2)
You should avoid doing this, though, because an element may be taken from the
longer iterators and discarded. This means you can't go on to use the iterators
further because you risk skipping a discarded element.
``itertools.islice(iter, [start], stop, [step])`` returns a stream that's a
slice of the iterator. With a single ``stop`` argument, it will return the
first ``stop`` elements. If you supply a starting index, you'll get
``stop-start`` elements, and if you supply a value for ``step``, elements will
be skipped accordingly. Unlike Python's string and list slicing, you can't use
negative values for ``start``, ``stop``, or ``step``. ::
itertools.islice(range(10), 8) =>
0, 1, 2, 3, 4, 5, 6, 7
itertools.islice(range(10), 2, 8) =>
2, 3, 4, 5, 6, 7
itertools.islice(range(10), 2, 8, 2) =>
2, 4, 6
``itertools.tee(iter, [n])`` replicates an iterator; it returns ``n``
independent iterators that will all return the contents of the source iterator.
If you don't supply a value for ``n``, the default is 2. Replicating iterators
requires saving some of the contents of the source iterator, so this can consume
significant memory if the iterator is large and one of the new iterators is
consumed more than the others. ::
itertools.tee( itertools.count() ) =>
iterA, iterB
where iterA ->
0, 1, 2, 3, 4, 5, 6, 7, 8, 9, ...
and iterB ->
0, 1, 2, 3, 4, 5, 6, 7, 8, 9, ...
Calling functions on elements
-----------------------------
Two functions are used for calling other functions on the contents of an
iterable.
``itertools.imap(f, iterA, iterB, ...)`` returns a stream containing
``f(iterA[0], iterB[0]), f(iterA[1], iterB[1]), f(iterA[2], iterB[2]), ...``::
itertools.imap(operator.add, [5, 6, 5], [1, 2, 3]) =>
6, 8, 8
The ``operator`` module contains a set of functions corresponding to Python's
operators. Some examples are ``operator.add(a, b)`` (adds two values),
``operator.ne(a, b)`` (same as ``a!=b``), and ``operator.attrgetter('id')``
(returns a callable that fetches the ``"id"`` attribute).
``itertools.starmap(func, iter)`` assumes that the iterable will return a stream
of tuples, and calls ``f()`` using these tuples as the arguments::
itertools.starmap(os.path.join,
[('/usr', 'bin', 'java'), ('/bin', 'python'),
('/usr', 'bin', 'perl'),('/usr', 'bin', 'ruby')])
=>
/usr/bin/java, /bin/python, /usr/bin/perl, /usr/bin/ruby
Selecting elements
------------------
Another group of functions chooses a subset of an iterator's elements based on a
predicate.
``itertools.ifilter(predicate, iter)`` returns all the elements for which the
predicate returns true::
def is_even(x):
return (x % 2) == 0
itertools.ifilter(is_even, itertools.count()) =>
0, 2, 4, 6, 8, 10, 12, 14, ...
``itertools.ifilterfalse(predicate, iter)`` is the opposite, returning all
elements for which the predicate returns false::
itertools.ifilterfalse(is_even, itertools.count()) =>
1, 3, 5, 7, 9, 11, 13, 15, ...
``itertools.takewhile(predicate, iter)`` returns elements for as long as the
predicate returns true. Once the predicate returns false, the iterator will
signal the end of its results.
::
def less_than_10(x):
return (x < 10)
itertools.takewhile(less_than_10, itertools.count()) =>
0, 1, 2, 3, 4, 5, 6, 7, 8, 9
itertools.takewhile(is_even, itertools.count()) =>
0
``itertools.dropwhile(predicate, iter)`` discards elements while the predicate
returns true, and then returns the rest of the iterable's results.
::
itertools.dropwhile(less_than_10, itertools.count()) =>
10, 11, 12, 13, 14, 15, 16, 17, 18, 19, ...
itertools.dropwhile(is_even, itertools.count()) =>
1, 2, 3, 4, 5, 6, 7, 8, 9, 10, ...
Grouping elements
-----------------
The last function I'll discuss, ``itertools.groupby(iter, key_func=None)``, is
the most complicated. ``key_func(elem)`` is a function that can compute a key
value for each element returned by the iterable. If you don't supply a key
function, the key is simply each element itself.
``groupby()`` collects all the consecutive elements from the underlying iterable
that have the same key value, and returns a stream of 2-tuples containing a key
value and an iterator for the elements with that key.
::
city_list = [('Decatur', 'AL'), ('Huntsville', 'AL'), ('Selma', 'AL'),
('Anchorage', 'AK'), ('Nome', 'AK'),
('Flagstaff', 'AZ'), ('Phoenix', 'AZ'), ('Tucson', 'AZ'),
...
]
def get_state ((city, state)):
return state
itertools.groupby(city_list, get_state) =>
('AL', iterator-1),
('AK', iterator-2),
('AZ', iterator-3), ...
where
iterator-1 =>
('Decatur', 'AL'), ('Huntsville', 'AL'), ('Selma', 'AL')
iterator-2 =>
('Anchorage', 'AK'), ('Nome', 'AK')
iterator-3 =>
('Flagstaff', 'AZ'), ('Phoenix', 'AZ'), ('Tucson', 'AZ')
``groupby()`` assumes that the underlying iterable's contents will already be
sorted based on the key. Note that the returned iterators also use the
underlying iterable, so you have to consume the results of iterator-1 before
requesting iterator-2 and its corresponding key.
The functools module
====================
The :mod:`functools` module in Python 2.5 contains some higher-order functions.
A **higher-order function** takes one or more functions as input and returns a
new function. The most useful tool in this module is the
:func:`functools.partial` function.
For programs written in a functional style, you'll sometimes want to construct
variants of existing functions that have some of the parameters filled in.
Consider a Python function ``f(a, b, c)``; you may wish to create a new function
``g(b, c)`` that's equivalent to ``f(1, b, c)``; you're filling in a value for
one of ``f()``'s parameters. This is called "partial function application".
The constructor for ``partial`` takes the arguments ``(function, arg1, arg2,
... kwarg1=value1, kwarg2=value2)``. The resulting object is callable, so you
can just call it to invoke ``function`` with the filled-in arguments.
Here's a small but realistic example::
import functools
def log (message, subsystem):
"Write the contents of 'message' to the specified subsystem."
print '%s: %s' % (subsystem, message)
...
server_log = functools.partial(log, subsystem='server')
server_log('Unable to open socket')
The operator module
-------------------
The :mod:`operator` module was mentioned earlier. It contains a set of
functions corresponding to Python's operators. These functions are often useful
in functional-style code because they save you from writing trivial functions
that perform a single operation.
Some of the functions in this module are:
* Math operations: ``add()``, ``sub()``, ``mul()``, ``div()``, ``floordiv()``,
``abs()``, ...
* Logical operations: ``not_()``, ``truth()``.
* Bitwise operations: ``and_()``, ``or_()``, ``invert()``.
* Comparisons: ``eq()``, ``ne()``, ``lt()``, ``le()``, ``gt()``, and ``ge()``.
* Object identity: ``is_()``, ``is_not()``.
Consult the operator module's documentation for a complete list.
Revision History and Acknowledgements
=====================================
The author would like to thank the following people for offering suggestions,
corrections and assistance with various drafts of this article: Ian Bicking,
Nick Coghlan, Nick Efford, Raymond Hettinger, Jim Jewett, Mike Krell, Leandro
Lameiro, Jussi Salmela, Collin Winter, Blake Winton.
Version 0.1: posted June 30 2006.
Version 0.11: posted July 1 2006. Typo fixes.
Version 0.2: posted July 10 2006. Merged genexp and listcomp sections into one.
Typo fixes.
Version 0.21: Added more references suggested on the tutor mailing list.
Version 0.30: Adds a section on the ``functional`` module written by Collin
Winter; adds short section on the operator module; a few other edits.
References
==========
General
-------
**Structure and Interpretation of Computer Programs**, by Harold Abelson and
Gerald Jay Sussman with Julie Sussman. Full text at
https://mitpress.mit.edu/sicp/. In this classic textbook of computer science,
chapters 2 and 3 discuss the use of sequences and streams to organize the data
flow inside a program. The book uses Scheme for its examples, but many of the
design approaches described in these chapters are applicable to functional-style
Python code.
http://www.defmacro.org/ramblings/fp.html: A general introduction to functional
programming that uses Java examples and has a lengthy historical introduction.
https://en.wikipedia.org/wiki/Functional_programming: General Wikipedia entry
describing functional programming.
https://en.wikipedia.org/wiki/Coroutine: Entry for coroutines.
https://en.wikipedia.org/wiki/Currying: Entry for the concept of currying.
Python-specific
---------------
http://gnosis.cx/TPiP/: The first chapter of David Mertz's book
:title-reference:`Text Processing in Python` discusses functional programming
for text processing, in the section titled "Utilizing Higher-Order Functions in
Text Processing".
Mertz also wrote a 3-part series of articles on functional programming
for IBM's DeveloperWorks site; see
`part 1 <https://www.ibm.com/developerworks/linux/library/l-prog/index.html>`__,
`part 2 <https://www.ibm.com/developerworks/linux/library/l-prog2/index.html>`__, and
`part 3 <https://www.ibm.com/developerworks/linux/library/l-prog3/index.html>`__,
Python documentation
--------------------
Documentation for the :mod:`itertools` module.
Documentation for the :mod:`operator` module.
:pep:`289`: "Generator Expressions"
:pep:`342`: "Coroutines via Enhanced Generators" describes the new generator
features in Python 2.5.
.. comment
Topics to place
-----------------------------
XXX os.walk()
XXX Need a large example.
But will an example add much? I'll post a first draft and see
what the comments say.
.. comment
Original outline:
Introduction
Idea of FP
Programs built out of functions
Functions are strictly input-output, no internal state
Opposed to OO programming, where objects have state
Why FP?
Formal provability
Assignment is difficult to reason about
Not very relevant to Python
Modularity
Small functions that do one thing
Debuggability:
Easy to test due to lack of state
Easy to verify output from intermediate steps
Composability
You assemble a toolbox of functions that can be mixed
Tackling a problem
Need a significant example
Iterators
Generators
The itertools module
List comprehensions
Small functions and the lambda statement
Built-in functions
map
filter
reduce
.. comment
Handy little function for printing part of an iterator -- used
while writing this document.
import itertools
def print_iter(it):
slice = itertools.islice(it, 10)
for elem in slice[:-1]:
sys.stdout.write(str(elem))
sys.stdout.write(', ')
print elem[-1]
PK %�\iO�{ { ! html/_sources/howto/index.rst.txtnu �[��� ***************
Python HOWTOs
***************
Python HOWTOs are documents that cover a single, specific topic,
and attempt to cover it fairly completely. Modelled on the Linux
Documentation Project's HOWTO collection, this collection is an
effort to foster documentation that's more detailed than the
Python Library Reference.
Currently, the HOWTOs are:
.. toctree::
:maxdepth: 1
pyporting.rst
cporting.rst
curses.rst
descriptor.rst
doanddont.rst
functional.rst
logging.rst
logging-cookbook.rst
regex.rst
sockets.rst
sorting.rst
unicode.rst
urllib2.rst
webservers.rst
argparse.rst
PK %�\a��`� `� , html/_sources/howto/logging-cookbook.rst.txtnu �[��� .. _logging-cookbook:
================
Logging Cookbook
================
:Author: Vinay Sajip <vinay_sajip at red-dove dot com>
This page contains a number of recipes related to logging, which have been found
useful in the past.
.. currentmodule:: logging
Using logging in multiple modules
---------------------------------
Multiple calls to ``logging.getLogger('someLogger')`` return a reference to the
same logger object. This is true not only within the same module, but also
across modules as long as it is in the same Python interpreter process. It is
true for references to the same object; additionally, application code can
define and configure a parent logger in one module and create (but not
configure) a child logger in a separate module, and all logger calls to the
child will pass up to the parent. Here is a main module::
import logging
import auxiliary_module
# create logger with 'spam_application'
logger = logging.getLogger('spam_application')
logger.setLevel(logging.DEBUG)
# create file handler which logs even debug messages
fh = logging.FileHandler('spam.log')
fh.setLevel(logging.DEBUG)
# create console handler with a higher log level
ch = logging.StreamHandler()
ch.setLevel(logging.ERROR)
# create formatter and add it to the handlers
formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
fh.setFormatter(formatter)
ch.setFormatter(formatter)
# add the handlers to the logger
logger.addHandler(fh)
logger.addHandler(ch)
logger.info('creating an instance of auxiliary_module.Auxiliary')
a = auxiliary_module.Auxiliary()
logger.info('created an instance of auxiliary_module.Auxiliary')
logger.info('calling auxiliary_module.Auxiliary.do_something')
a.do_something()
logger.info('finished auxiliary_module.Auxiliary.do_something')
logger.info('calling auxiliary_module.some_function()')
auxiliary_module.some_function()
logger.info('done with auxiliary_module.some_function()')
Here is the auxiliary module::
import logging
# create logger
module_logger = logging.getLogger('spam_application.auxiliary')
class Auxiliary:
def __init__(self):
self.logger = logging.getLogger('spam_application.auxiliary.Auxiliary')
self.logger.info('creating an instance of Auxiliary')
def do_something(self):
self.logger.info('doing something')
a = 1 + 1
self.logger.info('done doing something')
def some_function():
module_logger.info('received a call to "some_function"')
The output looks like this::
2005-03-23 23:47:11,663 - spam_application - INFO -
creating an instance of auxiliary_module.Auxiliary
2005-03-23 23:47:11,665 - spam_application.auxiliary.Auxiliary - INFO -
creating an instance of Auxiliary
2005-03-23 23:47:11,665 - spam_application - INFO -
created an instance of auxiliary_module.Auxiliary
2005-03-23 23:47:11,668 - spam_application - INFO -
calling auxiliary_module.Auxiliary.do_something
2005-03-23 23:47:11,668 - spam_application.auxiliary.Auxiliary - INFO -
doing something
2005-03-23 23:47:11,669 - spam_application.auxiliary.Auxiliary - INFO -
done doing something
2005-03-23 23:47:11,670 - spam_application - INFO -
finished auxiliary_module.Auxiliary.do_something
2005-03-23 23:47:11,671 - spam_application - INFO -
calling auxiliary_module.some_function()
2005-03-23 23:47:11,672 - spam_application.auxiliary - INFO -
received a call to 'some_function'
2005-03-23 23:47:11,673 - spam_application - INFO -
done with auxiliary_module.some_function()
Logging from multiple threads
-----------------------------
Logging from multiple threads requires no special effort. The following example
shows logging from the main (initIal) thread and another thread::
import logging
import threading
import time
def worker(arg):
while not arg['stop']:
logging.debug('Hi from myfunc')
time.sleep(0.5)
def main():
logging.basicConfig(level=logging.DEBUG, format='%(relativeCreated)6d %(threadName)s %(message)s')
info = {'stop': False}
thread = threading.Thread(target=worker, args=(info,))
thread.start()
while True:
try:
logging.debug('Hello from main')
time.sleep(0.75)
except KeyboardInterrupt:
info['stop'] = True
break
thread.join()
if __name__ == '__main__':
main()
When run, the script should print something like the following::
0 Thread-1 Hi from myfunc
3 MainThread Hello from main
505 Thread-1 Hi from myfunc
755 MainThread Hello from main
1007 Thread-1 Hi from myfunc
1507 MainThread Hello from main
1508 Thread-1 Hi from myfunc
2010 Thread-1 Hi from myfunc
2258 MainThread Hello from main
2512 Thread-1 Hi from myfunc
3009 MainThread Hello from main
3013 Thread-1 Hi from myfunc
3515 Thread-1 Hi from myfunc
3761 MainThread Hello from main
4017 Thread-1 Hi from myfunc
4513 MainThread Hello from main
4518 Thread-1 Hi from myfunc
This shows the logging output interspersed as one might expect. This approach
works for more threads than shown here, of course.
Multiple handlers and formatters
--------------------------------
Loggers are plain Python objects. The :meth:`~Logger.addHandler` method has no
minimum or maximum quota for the number of handlers you may add. Sometimes it
will be beneficial for an application to log all messages of all severities to a
text file while simultaneously logging errors or above to the console. To set
this up, simply configure the appropriate handlers. The logging calls in the
application code will remain unchanged. Here is a slight modification to the
previous simple module-based configuration example::
import logging
logger = logging.getLogger('simple_example')
logger.setLevel(logging.DEBUG)
# create file handler which logs even debug messages
fh = logging.FileHandler('spam.log')
fh.setLevel(logging.DEBUG)
# create console handler with a higher log level
ch = logging.StreamHandler()
ch.setLevel(logging.ERROR)
# create formatter and add it to the handlers
formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
ch.setFormatter(formatter)
fh.setFormatter(formatter)
# add the handlers to logger
logger.addHandler(ch)
logger.addHandler(fh)
# 'application' code
logger.debug('debug message')
logger.info('info message')
logger.warn('warn message')
logger.error('error message')
logger.critical('critical message')
Notice that the 'application' code does not care about multiple handlers. All
that changed was the addition and configuration of a new handler named *fh*.
The ability to create new handlers with higher- or lower-severity filters can be
very helpful when writing and testing an application. Instead of using many
``print`` statements for debugging, use ``logger.debug``: Unlike the print
statements, which you will have to delete or comment out later, the logger.debug
statements can remain intact in the source code and remain dormant until you
need them again. At that time, the only change that needs to happen is to
modify the severity level of the logger and/or handler to debug.
.. _multiple-destinations:
Logging to multiple destinations
--------------------------------
Let's say you want to log to console and file with different message formats and
in differing circumstances. Say you want to log messages with levels of DEBUG
and higher to file, and those messages at level INFO and higher to the console.
Let's also assume that the file should contain timestamps, but the console
messages should not. Here's how you can achieve this::
import logging
# set up logging to file - see previous section for more details
logging.basicConfig(level=logging.DEBUG,
format='%(asctime)s %(name)-12s %(levelname)-8s %(message)s',
datefmt='%m-%d %H:%M',
filename='/temp/myapp.log',
filemode='w')
# define a Handler which writes INFO messages or higher to the sys.stderr
console = logging.StreamHandler()
console.setLevel(logging.INFO)
# set a format which is simpler for console use
formatter = logging.Formatter('%(name)-12s: %(levelname)-8s %(message)s')
# tell the handler to use this format
console.setFormatter(formatter)
# add the handler to the root logger
logging.getLogger('').addHandler(console)
# Now, we can log to the root logger, or any other logger. First the root...
logging.info('Jackdaws love my big sphinx of quartz.')
# Now, define a couple of other loggers which might represent areas in your
# application:
logger1 = logging.getLogger('myapp.area1')
logger2 = logging.getLogger('myapp.area2')
logger1.debug('Quick zephyrs blow, vexing daft Jim.')
logger1.info('How quickly daft jumping zebras vex.')
logger2.warning('Jail zesty vixen who grabbed pay from quack.')
logger2.error('The five boxing wizards jump quickly.')
When you run this, on the console you will see ::
root : INFO Jackdaws love my big sphinx of quartz.
myapp.area1 : INFO How quickly daft jumping zebras vex.
myapp.area2 : WARNING Jail zesty vixen who grabbed pay from quack.
myapp.area2 : ERROR The five boxing wizards jump quickly.
and in the file you will see something like ::
10-22 22:19 root INFO Jackdaws love my big sphinx of quartz.
10-22 22:19 myapp.area1 DEBUG Quick zephyrs blow, vexing daft Jim.
10-22 22:19 myapp.area1 INFO How quickly daft jumping zebras vex.
10-22 22:19 myapp.area2 WARNING Jail zesty vixen who grabbed pay from quack.
10-22 22:19 myapp.area2 ERROR The five boxing wizards jump quickly.
As you can see, the DEBUG message only shows up in the file. The other messages
are sent to both destinations.
This example uses console and file handlers, but you can use any number and
combination of handlers you choose.
Configuration server example
----------------------------
Here is an example of a module using the logging configuration server::
import logging
import logging.config
import time
import os
# read initial config file
logging.config.fileConfig('logging.conf')
# create and start listener on port 9999
t = logging.config.listen(9999)
t.start()
logger = logging.getLogger('simpleExample')
try:
# loop through logging calls to see the difference
# new configurations make, until Ctrl+C is pressed
while True:
logger.debug('debug message')
logger.info('info message')
logger.warn('warn message')
logger.error('error message')
logger.critical('critical message')
time.sleep(5)
except KeyboardInterrupt:
# cleanup
logging.config.stopListening()
t.join()
And here is a script that takes a filename and sends that file to the server,
properly preceded with the binary-encoded length, as the new logging
configuration::
#!/usr/bin/env python
import socket, sys, struct
with open(sys.argv[1], 'rb') as f:
data_to_send = f.read()
HOST = 'localhost'
PORT = 9999
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
print('connecting...')
s.connect((HOST, PORT))
print('sending config...')
s.send(struct.pack('>L', len(data_to_send)))
s.send(data_to_send)
s.close()
print('complete')
.. _network-logging:
Sending and receiving logging events across a network
-----------------------------------------------------
Let's say you want to send logging events across a network, and handle them at
the receiving end. A simple way of doing this is attaching a
:class:`SocketHandler` instance to the root logger at the sending end::
import logging, logging.handlers
rootLogger = logging.getLogger('')
rootLogger.setLevel(logging.DEBUG)
socketHandler = logging.handlers.SocketHandler('localhost',
logging.handlers.DEFAULT_TCP_LOGGING_PORT)
# don't bother with a formatter, since a socket handler sends the event as
# an unformatted pickle
rootLogger.addHandler(socketHandler)
# Now, we can log to the root logger, or any other logger. First the root...
logging.info('Jackdaws love my big sphinx of quartz.')
# Now, define a couple of other loggers which might represent areas in your
# application:
logger1 = logging.getLogger('myapp.area1')
logger2 = logging.getLogger('myapp.area2')
logger1.debug('Quick zephyrs blow, vexing daft Jim.')
logger1.info('How quickly daft jumping zebras vex.')
logger2.warning('Jail zesty vixen who grabbed pay from quack.')
logger2.error('The five boxing wizards jump quickly.')
At the receiving end, you can set up a receiver using the :mod:`SocketServer`
module. Here is a basic working example::
import pickle
import logging
import logging.handlers
import SocketServer
import struct
class LogRecordStreamHandler(SocketServer.StreamRequestHandler):
"""Handler for a streaming logging request.
This basically logs the record using whatever logging policy is
configured locally.
"""
def handle(self):
"""
Handle multiple requests - each expected to be a 4-byte length,
followed by the LogRecord in pickle format. Logs the record
according to whatever policy is configured locally.
"""
while True:
chunk = self.connection.recv(4)
if len(chunk) < 4:
break
slen = struct.unpack('>L', chunk)[0]
chunk = self.connection.recv(slen)
while len(chunk) < slen:
chunk = chunk + self.connection.recv(slen - len(chunk))
obj = self.unPickle(chunk)
record = logging.makeLogRecord(obj)
self.handleLogRecord(record)
def unPickle(self, data):
return pickle.loads(data)
def handleLogRecord(self, record):
# if a name is specified, we use the named logger rather than the one
# implied by the record.
if self.server.logname is not None:
name = self.server.logname
else:
name = record.name
logger = logging.getLogger(name)
# N.B. EVERY record gets logged. This is because Logger.handle
# is normally called AFTER logger-level filtering. If you want
# to do filtering, do it at the client end to save wasting
# cycles and network bandwidth!
logger.handle(record)
class LogRecordSocketReceiver(SocketServer.ThreadingTCPServer):
"""
Simple TCP socket-based logging receiver suitable for testing.
"""
allow_reuse_address = 1
def __init__(self, host='localhost',
port=logging.handlers.DEFAULT_TCP_LOGGING_PORT,
handler=LogRecordStreamHandler):
SocketServer.ThreadingTCPServer.__init__(self, (host, port), handler)
self.abort = 0
self.timeout = 1
self.logname = None
def serve_until_stopped(self):
import select
abort = 0
while not abort:
rd, wr, ex = select.select([self.socket.fileno()],
[], [],
self.timeout)
if rd:
self.handle_request()
abort = self.abort
def main():
logging.basicConfig(
format='%(relativeCreated)5d %(name)-15s %(levelname)-8s %(message)s')
tcpserver = LogRecordSocketReceiver()
print('About to start TCP server...')
tcpserver.serve_until_stopped()
if __name__ == '__main__':
main()
First run the server, and then the client. On the client side, nothing is
printed on the console; on the server side, you should see something like::
About to start TCP server...
59 root INFO Jackdaws love my big sphinx of quartz.
59 myapp.area1 DEBUG Quick zephyrs blow, vexing daft Jim.
69 myapp.area1 INFO How quickly daft jumping zebras vex.
69 myapp.area2 WARNING Jail zesty vixen who grabbed pay from quack.
69 myapp.area2 ERROR The five boxing wizards jump quickly.
Note that there are some security issues with pickle in some scenarios. If
these affect you, you can use an alternative serialization scheme by overriding
the :meth:`~handlers.SocketHandler.makePickle` method and implementing your
alternative there, as well as adapting the above script to use your alternative
serialization.
.. _context-info:
Adding contextual information to your logging output
----------------------------------------------------
.. currentmodule:: logging
Sometimes you want logging output to contain contextual information in
addition to the parameters passed to the logging call. For example, in a
networked application, it may be desirable to log client-specific information
in the log (e.g. remote client's username, or IP address). Although you could
use the *extra* parameter to achieve this, it's not always convenient to pass
the information in this way. While it might be tempting to create
:class:`Logger` instances on a per-connection basis, this is not a good idea
because these instances are not garbage collected. While this is not a problem
in practice, when the number of :class:`Logger` instances is dependent on the
level of granularity you want to use in logging an application, it could
be hard to manage if the number of :class:`Logger` instances becomes
effectively unbounded.
Using LoggerAdapters to impart contextual information
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
An easy way in which you can pass contextual information to be output along
with logging event information is to use the :class:`LoggerAdapter` class.
This class is designed to look like a :class:`Logger`, so that you can call
:meth:`debug`, :meth:`info`, :meth:`warning`, :meth:`error`,
:meth:`exception`, :meth:`critical` and :meth:`log`. These methods have the
same signatures as their counterparts in :class:`Logger`, so you can use the
two types of instances interchangeably.
When you create an instance of :class:`LoggerAdapter`, you pass it a
:class:`Logger` instance and a dict-like object which contains your contextual
information. When you call one of the logging methods on an instance of
:class:`LoggerAdapter`, it delegates the call to the underlying instance of
:class:`Logger` passed to its constructor, and arranges to pass the contextual
information in the delegated call. Here's a snippet from the code of
:class:`LoggerAdapter`::
def debug(self, msg, *args, **kwargs):
"""
Delegate a debug call to the underlying logger, after adding
contextual information from this adapter instance.
"""
msg, kwargs = self.process(msg, kwargs)
self.logger.debug(msg, *args, **kwargs)
The :meth:`~LoggerAdapter.process` method of :class:`LoggerAdapter` is where the
contextual information is added to the logging output. It's passed the message
and keyword arguments of the logging call, and it passes back (potentially)
modified versions of these to use in the call to the underlying logger. The
default implementation of this method leaves the message alone, but inserts
an 'extra' key in the keyword argument whose value is the dict-like object
passed to the constructor. Of course, if you had passed an 'extra' keyword
argument in the call to the adapter, it will be silently overwritten.
The advantage of using 'extra' is that the values in the dict-like object are
merged into the :class:`LogRecord` instance's __dict__, allowing you to use
customized strings with your :class:`Formatter` instances which know about
the keys of the dict-like object. If you need a different method, e.g. if you
want to prepend or append the contextual information to the message string,
you just need to subclass :class:`LoggerAdapter` and override
:meth:`~LoggerAdapter.process` to do what you need. Here is a simple example::
class CustomAdapter(logging.LoggerAdapter):
"""
This example adapter expects the passed in dict-like object to have a
'connid' key, whose value in brackets is prepended to the log message.
"""
def process(self, msg, kwargs):
return '[%s] %s' % (self.extra['connid'], msg), kwargs
which you can use like this::
logger = logging.getLogger(__name__)
adapter = CustomAdapter(logger, {'connid': some_conn_id})
Then any events that you log to the adapter will have the value of
``some_conn_id`` prepended to the log messages.
Using objects other than dicts to pass contextual information
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You don't need to pass an actual dict to a :class:`LoggerAdapter` - you could
pass an instance of a class which implements ``__getitem__`` and ``__iter__`` so
that it looks like a dict to logging. This would be useful if you want to
generate values dynamically (whereas the values in a dict would be constant).
.. _filters-contextual:
Using Filters to impart contextual information
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You can also add contextual information to log output using a user-defined
:class:`Filter`. ``Filter`` instances are allowed to modify the ``LogRecords``
passed to them, including adding additional attributes which can then be output
using a suitable format string, or if needed a custom :class:`Formatter`.
For example in a web application, the request being processed (or at least,
the interesting parts of it) can be stored in a threadlocal
(:class:`threading.local`) variable, and then accessed from a ``Filter`` to
add, say, information from the request - say, the remote IP address and remote
user's username - to the ``LogRecord``, using the attribute names 'ip' and
'user' as in the ``LoggerAdapter`` example above. In that case, the same format
string can be used to get similar output to that shown above. Here's an example
script::
import logging
from random import choice
class ContextFilter(logging.Filter):
"""
This is a filter which injects contextual information into the log.
Rather than use actual contextual information, we just use random
data in this demo.
"""
USERS = ['jim', 'fred', 'sheila']
IPS = ['123.231.231.123', '127.0.0.1', '192.168.0.1']
def filter(self, record):
record.ip = choice(ContextFilter.IPS)
record.user = choice(ContextFilter.USERS)
return True
if __name__ == '__main__':
levels = (logging.DEBUG, logging.INFO, logging.WARNING, logging.ERROR, logging.CRITICAL)
logging.basicConfig(level=logging.DEBUG,
format='%(asctime)-15s %(name)-5s %(levelname)-8s IP: %(ip)-15s User: %(user)-8s %(message)s')
a1 = logging.getLogger('a.b.c')
a2 = logging.getLogger('d.e.f')
f = ContextFilter()
a1.addFilter(f)
a2.addFilter(f)
a1.debug('A debug message')
a1.info('An info message with %s', 'some parameters')
for x in range(10):
lvl = choice(levels)
lvlname = logging.getLevelName(lvl)
a2.log(lvl, 'A message at %s level with %d %s', lvlname, 2, 'parameters')
which, when run, produces something like::
2010-09-06 22:38:15,292 a.b.c DEBUG IP: 123.231.231.123 User: fred A debug message
2010-09-06 22:38:15,300 a.b.c INFO IP: 192.168.0.1 User: sheila An info message with some parameters
2010-09-06 22:38:15,300 d.e.f CRITICAL IP: 127.0.0.1 User: sheila A message at CRITICAL level with 2 parameters
2010-09-06 22:38:15,300 d.e.f ERROR IP: 127.0.0.1 User: jim A message at ERROR level with 2 parameters
2010-09-06 22:38:15,300 d.e.f DEBUG IP: 127.0.0.1 User: sheila A message at DEBUG level with 2 parameters
2010-09-06 22:38:15,300 d.e.f ERROR IP: 123.231.231.123 User: fred A message at ERROR level with 2 parameters
2010-09-06 22:38:15,300 d.e.f CRITICAL IP: 192.168.0.1 User: jim A message at CRITICAL level with 2 parameters
2010-09-06 22:38:15,300 d.e.f CRITICAL IP: 127.0.0.1 User: sheila A message at CRITICAL level with 2 parameters
2010-09-06 22:38:15,300 d.e.f DEBUG IP: 192.168.0.1 User: jim A message at DEBUG level with 2 parameters
2010-09-06 22:38:15,301 d.e.f ERROR IP: 127.0.0.1 User: sheila A message at ERROR level with 2 parameters
2010-09-06 22:38:15,301 d.e.f DEBUG IP: 123.231.231.123 User: fred A message at DEBUG level with 2 parameters
2010-09-06 22:38:15,301 d.e.f INFO IP: 123.231.231.123 User: fred A message at INFO level with 2 parameters
.. _multiple-processes:
Logging to a single file from multiple processes
------------------------------------------------
Although logging is thread-safe, and logging to a single file from multiple
threads in a single process *is* supported, logging to a single file from
*multiple processes* is *not* supported, because there is no standard way to
serialize access to a single file across multiple processes in Python. If you
need to log to a single file from multiple processes, one way of doing this is
to have all the processes log to a :class:`~handlers.SocketHandler`, and have a
separate process which implements a socket server which reads from the socket
and logs to file. (If you prefer, you can dedicate one thread in one of the
existing processes to perform this function.)
:ref:`This section <network-logging>` documents this approach in more detail and
includes a working socket receiver which can be used as a starting point for you
to adapt in your own applications.
If you are using a recent version of Python which includes the
:mod:`multiprocessing` module, you could write your own handler which uses the
:class:`~multiprocessing.Lock` class from this module to serialize access to the
file from your processes. The existing :class:`FileHandler` and subclasses do
not make use of :mod:`multiprocessing` at present, though they may do so in the
future. Note that at present, the :mod:`multiprocessing` module does not provide
working lock functionality on all platforms (see
https://bugs.python.org/issue3770).
Using file rotation
-------------------
.. sectionauthor:: Doug Hellmann, Vinay Sajip (changes)
.. (see <https://pymotw.com/3/logging/>)
Sometimes you want to let a log file grow to a certain size, then open a new
file and log to that. You may want to keep a certain number of these files, and
when that many files have been created, rotate the files so that the number of
files and the size of the files both remain bounded. For this usage pattern, the
logging package provides a :class:`~handlers.RotatingFileHandler`::
import glob
import logging
import logging.handlers
LOG_FILENAME = 'logging_rotatingfile_example.out'
# Set up a specific logger with our desired output level
my_logger = logging.getLogger('MyLogger')
my_logger.setLevel(logging.DEBUG)
# Add the log message handler to the logger
handler = logging.handlers.RotatingFileHandler(
LOG_FILENAME, maxBytes=20, backupCount=5)
my_logger.addHandler(handler)
# Log some messages
for i in range(20):
my_logger.debug('i = %d' % i)
# See what files are created
logfiles = glob.glob('%s*' % LOG_FILENAME)
for filename in logfiles:
print(filename)
The result should be 6 separate files, each with part of the log history for the
application::
logging_rotatingfile_example.out
logging_rotatingfile_example.out.1
logging_rotatingfile_example.out.2
logging_rotatingfile_example.out.3
logging_rotatingfile_example.out.4
logging_rotatingfile_example.out.5
The most current file is always :file:`logging_rotatingfile_example.out`,
and each time it reaches the size limit it is renamed with the suffix
``.1``. Each of the existing backup files is renamed to increment the suffix
(``.1`` becomes ``.2``, etc.) and the ``.6`` file is erased.
Obviously this example sets the log length much too small as an extreme
example. You would want to set *maxBytes* to an appropriate value.
An example dictionary-based configuration
-----------------------------------------
Below is an example of a logging configuration dictionary - it's taken from
the `documentation on the Django project <https://docs.djangoproject.com/en/1.9/topics/logging/#configuring-logging>`_.
This dictionary is passed to :func:`~config.dictConfig` to put the configuration into effect::
LOGGING = {
'version': 1,
'disable_existing_loggers': True,
'formatters': {
'verbose': {
'format': '%(levelname)s %(asctime)s %(module)s %(process)d %(thread)d %(message)s'
},
'simple': {
'format': '%(levelname)s %(message)s'
},
},
'filters': {
'special': {
'()': 'project.logging.SpecialFilter',
'foo': 'bar',
}
},
'handlers': {
'null': {
'level':'DEBUG',
'class':'django.utils.log.NullHandler',
},
'console':{
'level':'DEBUG',
'class':'logging.StreamHandler',
'formatter': 'simple'
},
'mail_admins': {
'level': 'ERROR',
'class': 'django.utils.log.AdminEmailHandler',
'filters': ['special']
}
},
'loggers': {
'django': {
'handlers':['null'],
'propagate': True,
'level':'INFO',
},
'django.request': {
'handlers': ['mail_admins'],
'level': 'ERROR',
'propagate': False,
},
'myproject.custom': {
'handlers': ['console', 'mail_admins'],
'level': 'INFO',
'filters': ['special']
}
}
}
For more information about this configuration, you can see the `relevant
section <https://docs.djangoproject.com/en/1.9/topics/logging/#configuring-logging>`_
of the Django documentation.
Inserting a BOM into messages sent to a SysLogHandler
-----------------------------------------------------
`RFC 5424 <https://tools.ietf.org/html/rfc5424>`_ requires that a
Unicode message be sent to a syslog daemon as a set of bytes which have the
following structure: an optional pure-ASCII component, followed by a UTF-8 Byte
Order Mark (BOM), followed by Unicode encoded using UTF-8. (See the `relevant
section of the specification <https://tools.ietf.org/html/rfc5424#section-6>`_.)
In Python 2.6 and 2.7, code was added to
:class:`~logging.handlers.SysLogHandler` to insert a BOM into the message, but
unfortunately, it was implemented incorrectly, with the BOM appearing at the
beginning of the message and hence not allowing any pure-ASCII component to
appear before it.
As this behaviour is broken, the incorrect BOM insertion code is being removed
from Python 2.7.4 and later. However, it is not being replaced, and if you
want to produce RFC 5424-compliant messages which include a BOM, an optional
pure-ASCII sequence before it and arbitrary Unicode after it, encoded using
UTF-8, then you need to do the following:
#. Attach a :class:`~logging.Formatter` instance to your
:class:`~logging.handlers.SysLogHandler` instance, with a format string
such as::
u'ASCII section\ufeffUnicode section'
The Unicode code point ``u'\ufeff'``, when encoded using UTF-8, will be
encoded as a UTF-8 BOM -- the byte-string ``'\xef\xbb\xbf'``.
#. Replace the ASCII section with whatever placeholders you like, but make sure
that the data that appears in there after substitution is always ASCII (that
way, it will remain unchanged after UTF-8 encoding).
#. Replace the Unicode section with whatever placeholders you like; if the data
which appears there after substitution contains characters outside the ASCII
range, that's fine -- it will be encoded using UTF-8.
If the formatted message is Unicode, it *will* be encoded using UTF-8 encoding
by ``SysLogHandler``. If you follow the above rules, you should be able to
produce RFC 5424-compliant messages. If you don't, logging may not complain,
but your messages will not be RFC 5424-compliant, and your syslog daemon may
complain.
Implementing structured logging
-------------------------------
Although most logging messages are intended for reading by humans, and thus not
readily machine-parseable, there might be circumstances where you want to output
messages in a structured format which *is* capable of being parsed by a program
(without needing complex regular expressions to parse the log message). This is
straightforward to achieve using the logging package. There are a number of
ways in which this could be achieved, but the following is a simple approach
which uses JSON to serialise the event in a machine-parseable manner::
import json
import logging
class StructuredMessage(object):
def __init__(self, message, **kwargs):
self.message = message
self.kwargs = kwargs
def __str__(self):
return '%s >>> %s' % (self.message, json.dumps(self.kwargs))
_ = StructuredMessage # optional, to improve readability
logging.basicConfig(level=logging.INFO, format='%(message)s')
logging.info(_('message 1', foo='bar', bar='baz', num=123, fnum=123.456))
If the above script is run, it prints::
message 1 >>> {"fnum": 123.456, "num": 123, "bar": "baz", "foo": "bar"}
Note that the order of items might be different according to the version of
Python used.
If you need more specialised processing, you can use a custom JSON encoder,
as in the following complete example::
from __future__ import unicode_literals
import json
import logging
# This next bit is to ensure the script runs unchanged on 2.x and 3.x
try:
unicode
except NameError:
unicode = str
class Encoder(json.JSONEncoder):
def default(self, o):
if isinstance(o, set):
return tuple(o)
elif isinstance(o, unicode):
return o.encode('unicode_escape').decode('ascii')
return super(Encoder, self).default(o)
class StructuredMessage(object):
def __init__(self, message, **kwargs):
self.message = message
self.kwargs = kwargs
def __str__(self):
s = Encoder().encode(self.kwargs)
return '%s >>> %s' % (self.message, s)
_ = StructuredMessage # optional, to improve readability
def main():
logging.basicConfig(level=logging.INFO, format='%(message)s')
logging.info(_('message 1', set_value=set([1, 2, 3]), snowman='\u2603'))
if __name__ == '__main__':
main()
When the above script is run, it prints::
message 1 >>> {"snowman": "\u2603", "set_value": [1, 2, 3]}
Note that the order of items might be different according to the version of
Python used.
.. _custom-handlers:
.. currentmodule:: logging.config
Customizing handlers with :func:`dictConfig`
--------------------------------------------
There are times when you want to customize logging handlers in particular ways,
and if you use :func:`dictConfig` you may be able to do this without
subclassing. As an example, consider that you may want to set the ownership of a
log file. On POSIX, this is easily done using :func:`os.chown`, but the file
handlers in the stdlib don't offer built-in support. You can customize handler
creation using a plain function such as::
def owned_file_handler(filename, mode='a', encoding=None, owner=None):
if owner:
import os, pwd, grp
# convert user and group names to uid and gid
uid = pwd.getpwnam(owner[0]).pw_uid
gid = grp.getgrnam(owner[1]).gr_gid
owner = (uid, gid)
if not os.path.exists(filename):
open(filename, 'a').close()
os.chown(filename, *owner)
return logging.FileHandler(filename, mode, encoding)
You can then specify, in a logging configuration passed to :func:`dictConfig`,
that a logging handler be created by calling this function::
LOGGING = {
'version': 1,
'disable_existing_loggers': False,
'formatters': {
'default': {
'format': '%(asctime)s %(levelname)s %(name)s %(message)s'
},
},
'handlers': {
'file':{
# The values below are popped from this dictionary and
# used to create the handler, set the handler's level and
# its formatter.
'()': owned_file_handler,
'level':'DEBUG',
'formatter': 'default',
# The values below are passed to the handler creator callable
# as keyword arguments.
'owner': ['pulse', 'pulse'],
'filename': 'chowntest.log',
'mode': 'w',
'encoding': 'utf-8',
},
},
'root': {
'handlers': ['file'],
'level': 'DEBUG',
},
}
In this example I am setting the ownership using the ``pulse`` user and group,
just for the purposes of illustration. Putting it together into a working
script, ``chowntest.py``::
import logging, logging.config, os, shutil
def owned_file_handler(filename, mode='a', encoding=None, owner=None):
if owner:
if not os.path.exists(filename):
open(filename, 'a').close()
shutil.chown(filename, *owner)
return logging.FileHandler(filename, mode, encoding)
LOGGING = {
'version': 1,
'disable_existing_loggers': False,
'formatters': {
'default': {
'format': '%(asctime)s %(levelname)s %(name)s %(message)s'
},
},
'handlers': {
'file':{
# The values below are popped from this dictionary and
# used to create the handler, set the handler's level and
# its formatter.
'()': owned_file_handler,
'level':'DEBUG',
'formatter': 'default',
# The values below are passed to the handler creator callable
# as keyword arguments.
'owner': ['pulse', 'pulse'],
'filename': 'chowntest.log',
'mode': 'w',
'encoding': 'utf-8',
},
},
'root': {
'handlers': ['file'],
'level': 'DEBUG',
},
}
logging.config.dictConfig(LOGGING)
logger = logging.getLogger('mylogger')
logger.debug('A debug message')
To run this, you will probably need to run as ``root``:
.. code-block:: shell-session
$ sudo python3.3 chowntest.py
$ cat chowntest.log
2013-11-05 09:34:51,128 DEBUG mylogger A debug message
$ ls -l chowntest.log
-rw-r--r-- 1 pulse pulse 55 2013-11-05 09:34 chowntest.log
Note that this example uses Python 3.3 because that's where :func:`shutil.chown`
makes an appearance. This approach should work with any Python version that
supports :func:`dictConfig` - namely, Python 2.7, 3.2 or later. With pre-3.3
versions, you would need to implement the actual ownership change using e.g.
:func:`os.chown`.
In practice, the handler-creating function may be in a utility module somewhere
in your project. Instead of the line in the configuration::
'()': owned_file_handler,
you could use e.g.::
'()': 'ext://project.util.owned_file_handler',
where ``project.util`` can be replaced with the actual name of the package
where the function resides. In the above working script, using
``'ext://__main__.owned_file_handler'`` should work. Here, the actual callable
is resolved by :func:`dictConfig` from the ``ext://`` specification.
This example hopefully also points the way to how you could implement other
types of file change - e.g. setting specific POSIX permission bits - in the
same way, using :func:`os.chmod`.
Of course, the approach could also be extended to types of handler other than a
:class:`~logging.FileHandler` - for example, one of the rotating file handlers,
or a different type of handler altogether.
.. _filters-dictconfig:
Configuring filters with :func:`dictConfig`
-------------------------------------------
You *can* configure filters using :func:`~logging.config.dictConfig`, though it
might not be obvious at first glance how to do it (hence this recipe). Since
:class:`~logging.Filter` is the only filter class included in the standard
library, and it is unlikely to cater to many requirements (it's only there as a
base class), you will typically need to define your own :class:`~logging.Filter`
subclass with an overridden :meth:`~logging.Filter.filter` method. To do this,
specify the ``()`` key in the configuration dictionary for the filter,
specifying a callable which will be used to create the filter (a class is the
most obvious, but you can provide any callable which returns a
:class:`~logging.Filter` instance). Here is a complete example::
import logging
import logging.config
import sys
class MyFilter(logging.Filter):
def __init__(self, param=None):
self.param = param
def filter(self, record):
if self.param is None:
allow = True
else:
allow = self.param not in record.msg
if allow:
record.msg = 'changed: ' + record.msg
return allow
LOGGING = {
'version': 1,
'filters': {
'myfilter': {
'()': MyFilter,
'param': 'noshow',
}
},
'handlers': {
'console': {
'class': 'logging.StreamHandler',
'filters': ['myfilter']
}
},
'root': {
'level': 'DEBUG',
'handlers': ['console']
},
}
if __name__ == '__main__':
logging.config.dictConfig(LOGGING)
logging.debug('hello')
logging.debug('hello - noshow')
This example shows how you can pass configuration data to the callable which
constructs the instance, in the form of keyword parameters. When run, the above
script will print::
changed: hello
which shows that the filter is working as configured.
A couple of extra points to note:
* If you can't refer to the callable directly in the configuration (e.g. if it
lives in a different module, and you can't import it directly where the
configuration dictionary is), you can use the form ``ext://...`` as described
in :ref:`logging-config-dict-externalobj`. For example, you could have used
the text ``'ext://__main__.MyFilter'`` instead of ``MyFilter`` in the above
example.
* As well as for filters, this technique can also be used to configure custom
handlers and formatters. See :ref:`logging-config-dict-userdef` for more
information on how logging supports using user-defined objects in its
configuration, and see the other cookbook recipe :ref:`custom-handlers` above.
.. _custom-format-exception:
Customized exception formatting
-------------------------------
There might be times when you want to do customized exception formatting - for
argument's sake, let's say you want exactly one line per logged event, even
when exception information is present. You can do this with a custom formatter
class, as shown in the following example::
import logging
class OneLineExceptionFormatter(logging.Formatter):
def formatException(self, exc_info):
"""
Format an exception so that it prints on a single line.
"""
result = super(OneLineExceptionFormatter, self).formatException(exc_info)
return repr(result) # or format into one line however you want to
def format(self, record):
s = super(OneLineExceptionFormatter, self).format(record)
if record.exc_text:
s = s.replace('\n', '') + '|'
return s
def configure_logging():
fh = logging.FileHandler('output.txt', 'w')
f = OneLineExceptionFormatter('%(asctime)s|%(levelname)s|%(message)s|',
'%d/%m/%Y %H:%M:%S')
fh.setFormatter(f)
root = logging.getLogger()
root.setLevel(logging.DEBUG)
root.addHandler(fh)
def main():
configure_logging()
logging.info('Sample message')
try:
x = 1 / 0
except ZeroDivisionError as e:
logging.exception('ZeroDivisionError: %s', e)
if __name__ == '__main__':
main()
When run, this produces a file with exactly two lines::
28/01/2015 07:21:23|INFO|Sample message|
28/01/2015 07:21:23|ERROR|ZeroDivisionError: integer division or modulo by zero|'Traceback (most recent call last):\n File "logtest7.py", line 30, in main\n x = 1 / 0\nZeroDivisionError: integer division or modulo by zero'|
While the above treatment is simplistic, it points the way to how exception
information can be formatted to your liking. The :mod:`traceback` module may be
helpful for more specialized needs.
.. _spoken-messages:
Speaking logging messages
-------------------------
There might be situations when it is desirable to have logging messages rendered
in an audible rather than a visible format. This is easy to do if you have
text-to-speech (TTS) functionality available in your system, even if it doesn't have
a Python binding. Most TTS systems have a command line program you can run, and
this can be invoked from a handler using :mod:`subprocess`. It's assumed here
that TTS command line programs won't expect to interact with users or take a
long time to complete, and that the frequency of logged messages will be not so
high as to swamp the user with messages, and that it's acceptable to have the
messages spoken one at a time rather than concurrently, The example implementation
below waits for one message to be spoken before the next is processed, and this
might cause other handlers to be kept waiting. Here is a short example showing
the approach, which assumes that the ``espeak`` TTS package is available::
import logging
import subprocess
import sys
class TTSHandler(logging.Handler):
def emit(self, record):
msg = self.format(record)
# Speak slowly in a female English voice
cmd = ['espeak', '-s150', '-ven+f3', msg]
p = subprocess.Popen(cmd, stdout=subprocess.PIPE,
stderr=subprocess.STDOUT)
# wait for the program to finish
p.communicate()
def configure_logging():
h = TTSHandler()
root = logging.getLogger()
root.addHandler(h)
# the default formatter just returns the message
root.setLevel(logging.DEBUG)
def main():
logging.info('Hello')
logging.debug('Goodbye')
if __name__ == '__main__':
configure_logging()
sys.exit(main())
When run, this script should say "Hello" and then "Goodbye" in a female voice.
The above approach can, of course, be adapted to other TTS systems and even
other systems altogether which can process messages via external programs run
from a command line.
.. _buffered-logging:
Buffering logging messages and outputting them conditionally
------------------------------------------------------------
There might be situations where you want to log messages in a temporary area
and only output them if a certain condition occurs. For example, you may want to
start logging debug events in a function, and if the function completes without
errors, you don't want to clutter the log with the collected debug information,
but if there is an error, you want all the debug information to be output as well
as the error.
Here is an example which shows how you could do this using a decorator for your
functions where you want logging to behave this way. It makes use of the
:class:`logging.handlers.MemoryHandler`, which allows buffering of logged events
until some condition occurs, at which point the buffered events are ``flushed``
- passed to another handler (the ``target`` handler) for processing. By default,
the ``MemoryHandler`` flushed when its buffer gets filled up or an event whose
level is greater than or equal to a specified threshold is seen. You can use this
recipe with a more specialised subclass of ``MemoryHandler`` if you want custom
flushing behavior.
The example script has a simple function, ``foo``, which just cycles through
all the logging levels, writing to ``sys.stderr`` to say what level it's about
to log at, and then actually logging a message at that level. You can pass a
parameter to ``foo`` which, if true, will log at ERROR and CRITICAL levels -
otherwise, it only logs at DEBUG, INFO and WARNING levels.
The script just arranges to decorate ``foo`` with a decorator which will do the
conditional logging that's required. The decorator takes a logger as a parameter
and attaches a memory handler for the duration of the call to the decorated
function. The decorator can be additionally parameterised using a target handler,
a level at which flushing should occur, and a capacity for the buffer. These
default to a :class:`~logging.StreamHandler` which writes to ``sys.stderr``,
``logging.ERROR`` and ``100`` respectively.
Here's the script::
import logging
from logging.handlers import MemoryHandler
import sys
logger = logging.getLogger(__name__)
logger.addHandler(logging.NullHandler())
def log_if_errors(logger, target_handler=None, flush_level=None, capacity=None):
if target_handler is None:
target_handler = logging.StreamHandler()
if flush_level is None:
flush_level = logging.ERROR
if capacity is None:
capacity = 100
handler = MemoryHandler(capacity, flushLevel=flush_level, target=target_handler)
def decorator(fn):
def wrapper(*args, **kwargs):
logger.addHandler(handler)
try:
return fn(*args, **kwargs)
except Exception:
logger.exception('call failed')
raise
finally:
super(MemoryHandler, handler).flush()
logger.removeHandler(handler)
return wrapper
return decorator
def write_line(s):
sys.stderr.write('%s\n' % s)
def foo(fail=False):
write_line('about to log at DEBUG ...')
logger.debug('Actually logged at DEBUG')
write_line('about to log at INFO ...')
logger.info('Actually logged at INFO')
write_line('about to log at WARNING ...')
logger.warning('Actually logged at WARNING')
if fail:
write_line('about to log at ERROR ...')
logger.error('Actually logged at ERROR')
write_line('about to log at CRITICAL ...')
logger.critical('Actually logged at CRITICAL')
return fail
decorated_foo = log_if_errors(logger)(foo)
if __name__ == '__main__':
logger.setLevel(logging.DEBUG)
write_line('Calling undecorated foo with False')
assert not foo(False)
write_line('Calling undecorated foo with True')
assert foo(True)
write_line('Calling decorated foo with False')
assert not decorated_foo(False)
write_line('Calling decorated foo with True')
assert decorated_foo(True)
When this script is run, the following output should be observed::
Calling undecorated foo with False
about to log at DEBUG ...
about to log at INFO ...
about to log at WARNING ...
Calling undecorated foo with True
about to log at DEBUG ...
about to log at INFO ...
about to log at WARNING ...
about to log at ERROR ...
about to log at CRITICAL ...
Calling decorated foo with False
about to log at DEBUG ...
about to log at INFO ...
about to log at WARNING ...
Calling decorated foo with True
about to log at DEBUG ...
about to log at INFO ...
about to log at WARNING ...
about to log at ERROR ...
Actually logged at DEBUG
Actually logged at INFO
Actually logged at WARNING
Actually logged at ERROR
about to log at CRITICAL ...
Actually logged at CRITICAL
As you can see, actual logging output only occurs when an event is logged whose
severity is ERROR or greater, but in that case, any previous events at lower
severities are also logged.
You can of course use the conventional means of decoration::
@log_if_errors(logger)
def foo(fail=False):
...
.. _utc-formatting:
Formatting times using UTC (GMT) via configuration
--------------------------------------------------
Sometimes you want to format times using UTC, which can be done using a class
such as `UTCFormatter`, shown below::
import logging
import time
class UTCFormatter(logging.Formatter):
converter = time.gmtime
and you can then use the ``UTCFormatter`` in your code instead of
:class:`~logging.Formatter`. If you want to do that via configuration, you can
use the :func:`~logging.config.dictConfig` API with an approach illustrated by
the following complete example::
import logging
import logging.config
import time
class UTCFormatter(logging.Formatter):
converter = time.gmtime
LOGGING = {
'version': 1,
'disable_existing_loggers': False,
'formatters': {
'utc': {
'()': UTCFormatter,
'format': '%(asctime)s %(message)s',
},
'local': {
'format': '%(asctime)s %(message)s',
}
},
'handlers': {
'console1': {
'class': 'logging.StreamHandler',
'formatter': 'utc',
},
'console2': {
'class': 'logging.StreamHandler',
'formatter': 'local',
},
},
'root': {
'handlers': ['console1', 'console2'],
}
}
if __name__ == '__main__':
logging.config.dictConfig(LOGGING)
logging.warning('The local time is %s', time.asctime())
When this script is run, it should print something like::
2015-10-17 12:53:29,501 The local time is Sat Oct 17 13:53:29 2015
2015-10-17 13:53:29,501 The local time is Sat Oct 17 13:53:29 2015
showing how the time is formatted both as local time and UTC, one for each
handler.
.. _context-manager:
Using a context manager for selective logging
---------------------------------------------
There are times when it would be useful to temporarily change the logging
configuration and revert it back after doing something. For this, a context
manager is the most obvious way of saving and restoring the logging context.
Here is a simple example of such a context manager, which allows you to
optionally change the logging level and add a logging handler purely in the
scope of the context manager::
import logging
import sys
class LoggingContext(object):
def __init__(self, logger, level=None, handler=None, close=True):
self.logger = logger
self.level = level
self.handler = handler
self.close = close
def __enter__(self):
if self.level is not None:
self.old_level = self.logger.level
self.logger.setLevel(self.level)
if self.handler:
self.logger.addHandler(self.handler)
def __exit__(self, et, ev, tb):
if self.level is not None:
self.logger.setLevel(self.old_level)
if self.handler:
self.logger.removeHandler(self.handler)
if self.handler and self.close:
self.handler.close()
# implicit return of None => don't swallow exceptions
If you specify a level value, the logger's level is set to that value in the
scope of the with block covered by the context manager. If you specify a
handler, it is added to the logger on entry to the block and removed on exit
from the block. You can also ask the manager to close the handler for you on
block exit - you could do this if you don't need the handler any more.
To illustrate how it works, we can add the following block of code to the
above::
if __name__ == '__main__':
logger = logging.getLogger('foo')
logger.addHandler(logging.StreamHandler())
logger.setLevel(logging.INFO)
logger.info('1. This should appear just once on stderr.')
logger.debug('2. This should not appear.')
with LoggingContext(logger, level=logging.DEBUG):
logger.debug('3. This should appear once on stderr.')
logger.debug('4. This should not appear.')
h = logging.StreamHandler(sys.stdout)
with LoggingContext(logger, level=logging.DEBUG, handler=h, close=True):
logger.debug('5. This should appear twice - once on stderr and once on stdout.')
logger.info('6. This should appear just once on stderr.')
logger.debug('7. This should not appear.')
We initially set the logger's level to ``INFO``, so message #1 appears and
message #2 doesn't. We then change the level to ``DEBUG`` temporarily in the
following ``with`` block, and so message #3 appears. After the block exits, the
logger's level is restored to ``INFO`` and so message #4 doesn't appear. In the
next ``with`` block, we set the level to ``DEBUG`` again but also add a handler
writing to ``sys.stdout``. Thus, message #5 appears twice on the console (once
via ``stderr`` and once via ``stdout``). After the ``with`` statement's
completion, the status is as it was before so message #6 appears (like message
#1) whereas message #7 doesn't (just like message #2).
If we run the resulting script, the result is as follows:
.. code-block:: shell-session
$ python logctx.py
1. This should appear just once on stderr.
3. This should appear once on stderr.
5. This should appear twice - once on stderr and once on stdout.
5. This should appear twice - once on stderr and once on stdout.
6. This should appear just once on stderr.
If we run it again, but pipe ``stderr`` to ``/dev/null``, we see the following,
which is the only message written to ``stdout``:
.. code-block:: shell-session
$ python logctx.py 2>/dev/null
5. This should appear twice - once on stderr and once on stdout.
Once again, but piping ``stdout`` to ``/dev/null``, we get:
.. code-block:: shell-session
$ python logctx.py >/dev/null
1. This should appear just once on stderr.
3. This should appear once on stderr.
5. This should appear twice - once on stderr and once on stdout.
6. This should appear just once on stderr.
In this case, the message #5 printed to ``stdout`` doesn't appear, as expected.
Of course, the approach described here can be generalised, for example to attach
logging filters temporarily. Note that the above code works in Python 2 as well
as Python 3.
PK %�\X���� �� # html/_sources/howto/logging.rst.txtnu �[��� =============
Logging HOWTO
=============
:Author: Vinay Sajip <vinay_sajip at red-dove dot com>
.. _logging-basic-tutorial:
.. currentmodule:: logging
Basic Logging Tutorial
----------------------
Logging is a means of tracking events that happen when some software runs. The
software's developer adds logging calls to their code to indicate that certain
events have occurred. An event is described by a descriptive message which can
optionally contain variable data (i.e. data that is potentially different for
each occurrence of the event). Events also have an importance which the
developer ascribes to the event; the importance can also be called the *level*
or *severity*.
When to use logging
^^^^^^^^^^^^^^^^^^^
Logging provides a set of convenience functions for simple logging usage. These
are :func:`debug`, :func:`info`, :func:`warning`, :func:`error` and
:func:`critical`. To determine when to use logging, see the table below, which
states, for each of a set of common tasks, the best tool to use for it.
+-------------------------------------+--------------------------------------+
| Task you want to perform | The best tool for the task |
+=====================================+======================================+
| Display console output for ordinary | :func:`print` |
| usage of a command line script or | |
| program | |
+-------------------------------------+--------------------------------------+
| Report events that occur during | :func:`logging.info` (or |
| normal operation of a program (e.g. | :func:`logging.debug` for very |
| for status monitoring or fault | detailed output for diagnostic |
| investigation) | purposes) |
+-------------------------------------+--------------------------------------+
| Issue a warning regarding a | :func:`warnings.warn` in library |
| particular runtime event | code if the issue is avoidable and |
| | the client application should be |
| | modified to eliminate the warning |
| | |
| | :func:`logging.warning` if there is |
| | nothing the client application can do|
| | about the situation, but the event |
| | should still be noted |
+-------------------------------------+--------------------------------------+
| Report an error regarding a | Raise an exception |
| particular runtime event | |
+-------------------------------------+--------------------------------------+
| Report suppression of an error | :func:`logging.error`, |
| without raising an exception (e.g. | :func:`logging.exception` or |
| error handler in a long-running | :func:`logging.critical` as |
| server process) | appropriate for the specific error |
| | and application domain |
+-------------------------------------+--------------------------------------+
The logging functions are named after the level or severity of the events
they are used to track. The standard levels and their applicability are
described below (in increasing order of severity):
.. tabularcolumns:: |l|L|
+--------------+---------------------------------------------+
| Level | When it's used |
+==============+=============================================+
| ``DEBUG`` | Detailed information, typically of interest |
| | only when diagnosing problems. |
+--------------+---------------------------------------------+
| ``INFO`` | Confirmation that things are working as |
| | expected. |
+--------------+---------------------------------------------+
| ``WARNING`` | An indication that something unexpected |
| | happened, or indicative of some problem in |
| | the near future (e.g. 'disk space low'). |
| | The software is still working as expected. |
+--------------+---------------------------------------------+
| ``ERROR`` | Due to a more serious problem, the software |
| | has not been able to perform some function. |
+--------------+---------------------------------------------+
| ``CRITICAL`` | A serious error, indicating that the program|
| | itself may be unable to continue running. |
+--------------+---------------------------------------------+
The default level is ``WARNING``, which means that only events of this level
and above will be tracked, unless the logging package is configured to do
otherwise.
Events that are tracked can be handled in different ways. The simplest way of
handling tracked events is to print them to the console. Another common way
is to write them to a disk file.
.. _howto-minimal-example:
A simple example
^^^^^^^^^^^^^^^^
A very simple example is::
import logging
logging.warning('Watch out!') # will print a message to the console
logging.info('I told you so') # will not print anything
If you type these lines into a script and run it, you'll see:
.. code-block:: none
WARNING:root:Watch out!
printed out on the console. The ``INFO`` message doesn't appear because the
default level is ``WARNING``. The printed message includes the indication of
the level and the description of the event provided in the logging call, i.e.
'Watch out!'. Don't worry about the 'root' part for now: it will be explained
later. The actual output can be formatted quite flexibly if you need that;
formatting options will also be explained later.
Logging to a file
^^^^^^^^^^^^^^^^^
A very common situation is that of recording logging events in a file, so let's
look at that next. Be sure to try the following in a newly-started Python
interpreter, and don't just continue from the session described above::
import logging
logging.basicConfig(filename='example.log',level=logging.DEBUG)
logging.debug('This message should go to the log file')
logging.info('So should this')
logging.warning('And this, too')
And now if we open the file and look at what we have, we should find the log
messages::
DEBUG:root:This message should go to the log file
INFO:root:So should this
WARNING:root:And this, too
This example also shows how you can set the logging level which acts as the
threshold for tracking. In this case, because we set the threshold to
``DEBUG``, all of the messages were printed.
If you want to set the logging level from a command-line option such as::
--log=INFO
and you have the value of the parameter passed for ``--log`` in some variable
*loglevel*, you can use::
getattr(logging, loglevel.upper())
to get the value which you'll pass to :func:`basicConfig` via the *level*
argument. You may want to error check any user input value, perhaps as in the
following example::
# assuming loglevel is bound to the string value obtained from the
# command line argument. Convert to upper case to allow the user to
# specify --log=DEBUG or --log=debug
numeric_level = getattr(logging, loglevel.upper(), None)
if not isinstance(numeric_level, int):
raise ValueError('Invalid log level: %s' % loglevel)
logging.basicConfig(level=numeric_level, ...)
The call to :func:`basicConfig` should come *before* any calls to :func:`debug`,
:func:`info` etc. As it's intended as a one-off simple configuration facility,
only the first call will actually do anything: subsequent calls are effectively
no-ops.
If you run the above script several times, the messages from successive runs
are appended to the file *example.log*. If you want each run to start afresh,
not remembering the messages from earlier runs, you can specify the *filemode*
argument, by changing the call in the above example to::
logging.basicConfig(filename='example.log', filemode='w', level=logging.DEBUG)
The output will be the same as before, but the log file is no longer appended
to, so the messages from earlier runs are lost.
Logging from multiple modules
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If your program consists of multiple modules, here's an example of how you
could organize logging in it::
# myapp.py
import logging
import mylib
def main():
logging.basicConfig(filename='myapp.log', level=logging.INFO)
logging.info('Started')
mylib.do_something()
logging.info('Finished')
if __name__ == '__main__':
main()
::
# mylib.py
import logging
def do_something():
logging.info('Doing something')
If you run *myapp.py*, you should see this in *myapp.log*::
INFO:root:Started
INFO:root:Doing something
INFO:root:Finished
which is hopefully what you were expecting to see. You can generalize this to
multiple modules, using the pattern in *mylib.py*. Note that for this simple
usage pattern, you won't know, by looking in the log file, *where* in your
application your messages came from, apart from looking at the event
description. If you want to track the location of your messages, you'll need
to refer to the documentation beyond the tutorial level -- see
:ref:`logging-advanced-tutorial`.
Logging variable data
^^^^^^^^^^^^^^^^^^^^^
To log variable data, use a format string for the event description message and
append the variable data as arguments. For example::
import logging
logging.warning('%s before you %s', 'Look', 'leap!')
will display:
.. code-block:: none
WARNING:root:Look before you leap!
As you can see, merging of variable data into the event description message
uses the old, %-style of string formatting. This is for backwards
compatibility: the logging package pre-dates newer formatting options such as
:meth:`str.format` and :class:`string.Template`. These newer formatting
options *are* supported, but exploring them is outside the scope of this
tutorial.
Changing the format of displayed messages
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To change the format which is used to display messages, you need to
specify the format you want to use::
import logging
logging.basicConfig(format='%(levelname)s:%(message)s', level=logging.DEBUG)
logging.debug('This message should appear on the console')
logging.info('So should this')
logging.warning('And this, too')
which would print::
DEBUG:This message should appear on the console
INFO:So should this
WARNING:And this, too
Notice that the 'root' which appeared in earlier examples has disappeared. For
a full set of things that can appear in format strings, you can refer to the
documentation for :ref:`logrecord-attributes`, but for simple usage, you just
need the *levelname* (severity), *message* (event description, including
variable data) and perhaps to display when the event occurred. This is
described in the next section.
Displaying the date/time in messages
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To display the date and time of an event, you would place '%(asctime)s' in
your format string::
import logging
logging.basicConfig(format='%(asctime)s %(message)s')
logging.warning('is when this event was logged.')
which should print something like this::
2010-12-12 11:41:42,612 is when this event was logged.
The default format for date/time display (shown above) is ISO8601. If you need
more control over the formatting of the date/time, provide a *datefmt*
argument to ``basicConfig``, as in this example::
import logging
logging.basicConfig(format='%(asctime)s %(message)s', datefmt='%m/%d/%Y %I:%M:%S %p')
logging.warning('is when this event was logged.')
which would display something like this::
12/12/2010 11:46:36 AM is when this event was logged.
The format of the *datefmt* argument is the same as supported by
:func:`time.strftime`.
Next Steps
^^^^^^^^^^
That concludes the basic tutorial. It should be enough to get you up and
running with logging. There's a lot more that the logging package offers, but
to get the best out of it, you'll need to invest a little more of your time in
reading the following sections. If you're ready for that, grab some of your
favourite beverage and carry on.
If your logging needs are simple, then use the above examples to incorporate
logging into your own scripts, and if you run into problems or don't
understand something, please post a question on the comp.lang.python Usenet
group (available at https://groups.google.com/group/comp.lang.python) and you
should receive help before too long.
Still here? You can carry on reading the next few sections, which provide a
slightly more advanced/in-depth tutorial than the basic one above. After that,
you can take a look at the :ref:`logging-cookbook`.
.. _logging-advanced-tutorial:
Advanced Logging Tutorial
-------------------------
The logging library takes a modular approach and offers several categories
of components: loggers, handlers, filters, and formatters.
* Loggers expose the interface that application code directly uses.
* Handlers send the log records (created by loggers) to the appropriate
destination.
* Filters provide a finer grained facility for determining which log records
to output.
* Formatters specify the layout of log records in the final output.
Log event information is passed between loggers, handlers, filters and
formatters in a :class:`LogRecord` instance.
Logging is performed by calling methods on instances of the :class:`Logger`
class (hereafter called :dfn:`loggers`). Each instance has a name, and they are
conceptually arranged in a namespace hierarchy using dots (periods) as
separators. For example, a logger named 'scan' is the parent of loggers
'scan.text', 'scan.html' and 'scan.pdf'. Logger names can be anything you want,
and indicate the area of an application in which a logged message originates.
A good convention to use when naming loggers is to use a module-level logger,
in each module which uses logging, named as follows::
logger = logging.getLogger(__name__)
This means that logger names track the package/module hierarchy, and it's
intuitively obvious where events are logged just from the logger name.
The root of the hierarchy of loggers is called the root logger. That's the
logger used by the functions :func:`debug`, :func:`info`, :func:`warning`,
:func:`error` and :func:`critical`, which just call the same-named method of
the root logger. The functions and the methods have the same signatures. The
root logger's name is printed as 'root' in the logged output.
It is, of course, possible to log messages to different destinations. Support
is included in the package for writing log messages to files, HTTP GET/POST
locations, email via SMTP, generic sockets, or OS-specific logging mechanisms
such as syslog or the Windows NT event log. Destinations are served by
:dfn:`handler` classes. You can create your own log destination class if you
have special requirements not met by any of the built-in handler classes.
By default, no destination is set for any logging messages. You can specify
a destination (such as console or file) by using :func:`basicConfig` as in the
tutorial examples. If you call the functions :func:`debug`, :func:`info`,
:func:`warning`, :func:`error` and :func:`critical`, they will check to see
if no destination is set; and if one is not set, they will set a destination
of the console (``sys.stderr``) and a default format for the displayed
message before delegating to the root logger to do the actual message output.
The default format set by :func:`basicConfig` for messages is::
severity:logger name:message
You can change this by passing a format string to :func:`basicConfig` with the
*format* keyword argument. For all options regarding how a format string is
constructed, see :ref:`formatter-objects`.
Logging Flow
^^^^^^^^^^^^
The flow of log event information in loggers and handlers is illustrated in the
following diagram.
.. image:: logging_flow.png
Loggers
^^^^^^^
:class:`Logger` objects have a threefold job. First, they expose several
methods to application code so that applications can log messages at runtime.
Second, logger objects determine which log messages to act upon based upon
severity (the default filtering facility) or filter objects. Third, logger
objects pass along relevant log messages to all interested log handlers.
The most widely used methods on logger objects fall into two categories:
configuration and message sending.
These are the most common configuration methods:
* :meth:`Logger.setLevel` specifies the lowest-severity log message a logger
will handle, where debug is the lowest built-in severity level and critical
is the highest built-in severity. For example, if the severity level is
INFO, the logger will handle only INFO, WARNING, ERROR, and CRITICAL messages
and will ignore DEBUG messages.
* :meth:`Logger.addHandler` and :meth:`Logger.removeHandler` add and remove
handler objects from the logger object. Handlers are covered in more detail
in :ref:`handler-basic`.
* :meth:`Logger.addFilter` and :meth:`Logger.removeFilter` add and remove filter
objects from the logger object. Filters are covered in more detail in
:ref:`filter`.
You don't need to always call these methods on every logger you create. See the
last two paragraphs in this section.
With the logger object configured, the following methods create log messages:
* :meth:`Logger.debug`, :meth:`Logger.info`, :meth:`Logger.warning`,
:meth:`Logger.error`, and :meth:`Logger.critical` all create log records with
a message and a level that corresponds to their respective method names. The
message is actually a format string, which may contain the standard string
substitution syntax of :const:`%s`, :const:`%d`, :const:`%f`, and so on. The
rest of their arguments is a list of objects that correspond with the
substitution fields in the message. With regard to :const:`**kwargs`, the
logging methods care only about a keyword of :const:`exc_info` and use it to
determine whether to log exception information.
* :meth:`Logger.exception` creates a log message similar to
:meth:`Logger.error`. The difference is that :meth:`Logger.exception` dumps a
stack trace along with it. Call this method only from an exception handler.
* :meth:`Logger.log` takes a log level as an explicit argument. This is a
little more verbose for logging messages than using the log level convenience
methods listed above, but this is how to log at custom log levels.
:func:`getLogger` returns a reference to a logger instance with the specified
name if it is provided, or ``root`` if not. The names are period-separated
hierarchical structures. Multiple calls to :func:`getLogger` with the same name
will return a reference to the same logger object. Loggers that are further
down in the hierarchical list are children of loggers higher up in the list.
For example, given a logger with a name of ``foo``, loggers with names of
``foo.bar``, ``foo.bar.baz``, and ``foo.bam`` are all descendants of ``foo``.
Loggers have a concept of *effective level*. If a level is not explicitly set
on a logger, the level of its parent is used instead as its effective level.
If the parent has no explicit level set, *its* parent is examined, and so on -
all ancestors are searched until an explicitly set level is found. The root
logger always has an explicit level set (``WARNING`` by default). When deciding
whether to process an event, the effective level of the logger is used to
determine whether the event is passed to the logger's handlers.
Child loggers propagate messages up to the handlers associated with their
ancestor loggers. Because of this, it is unnecessary to define and configure
handlers for all the loggers an application uses. It is sufficient to
configure handlers for a top-level logger and create child loggers as needed.
(You can, however, turn off propagation by setting the *propagate*
attribute of a logger to ``False``.)
.. _handler-basic:
Handlers
^^^^^^^^
:class:`~logging.Handler` objects are responsible for dispatching the
appropriate log messages (based on the log messages' severity) to the handler's
specified destination. :class:`Logger` objects can add zero or more handler
objects to themselves with an :meth:`~Logger.addHandler` method. As an example
scenario, an application may want to send all log messages to a log file, all
log messages of error or higher to stdout, and all messages of critical to an
email address. This scenario requires three individual handlers where each
handler is responsible for sending messages of a specific severity to a specific
location.
The standard library includes quite a few handler types (see
:ref:`useful-handlers`); the tutorials use mainly :class:`StreamHandler` and
:class:`FileHandler` in its examples.
There are very few methods in a handler for application developers to concern
themselves with. The only handler methods that seem relevant for application
developers who are using the built-in handler objects (that is, not creating
custom handlers) are the following configuration methods:
* The :meth:`~Handler.setLevel` method, just as in logger objects, specifies the
lowest severity that will be dispatched to the appropriate destination. Why
are there two :func:`setLevel` methods? The level set in the logger
determines which severity of messages it will pass to its handlers. The level
set in each handler determines which messages that handler will send on.
* :meth:`~Handler.setFormatter` selects a Formatter object for this handler to
use.
* :meth:`~Handler.addFilter` and :meth:`~Handler.removeFilter` respectively
configure and deconfigure filter objects on handlers.
Application code should not directly instantiate and use instances of
:class:`Handler`. Instead, the :class:`Handler` class is a base class that
defines the interface that all handlers should have and establishes some
default behavior that child classes can use (or override).
Formatters
^^^^^^^^^^
Formatter objects configure the final order, structure, and contents of the log
message. Unlike the base :class:`logging.Handler` class, application code may
instantiate formatter classes, although you could likely subclass the formatter
if your application needs special behavior. The constructor takes two
optional arguments -- a message format string and a date format string.
.. method:: logging.Formatter.__init__(fmt=None, datefmt=None)
If there is no message format string, the default is to use the
raw message. If there is no date format string, the default date format is::
%Y-%m-%d %H:%M:%S
with the milliseconds tacked on at the end.
The message format string uses ``%(<dictionary key>)s`` styled string
substitution; the possible keys are documented in :ref:`logrecord-attributes`.
The following message format string will log the time in a human-readable
format, the severity of the message, and the contents of the message, in that
order::
'%(asctime)s - %(levelname)s - %(message)s'
Formatters use a user-configurable function to convert the creation time of a
record to a tuple. By default, :func:`time.localtime` is used; to change this
for a particular formatter instance, set the ``converter`` attribute of the
instance to a function with the same signature as :func:`time.localtime` or
:func:`time.gmtime`. To change it for all formatters, for example if you want
all logging times to be shown in GMT, set the ``converter`` attribute in the
Formatter class (to ``time.gmtime`` for GMT display).
Configuring Logging
^^^^^^^^^^^^^^^^^^^
.. currentmodule:: logging.config
Programmers can configure logging in three ways:
1. Creating loggers, handlers, and formatters explicitly using Python
code that calls the configuration methods listed above.
2. Creating a logging config file and reading it using the :func:`fileConfig`
function.
3. Creating a dictionary of configuration information and passing it
to the :func:`dictConfig` function.
For the reference documentation on the last two options, see
:ref:`logging-config-api`. The following example configures a very simple
logger, a console handler, and a simple formatter using Python code::
import logging
# create logger
logger = logging.getLogger('simple_example')
logger.setLevel(logging.DEBUG)
# create console handler and set level to debug
ch = logging.StreamHandler()
ch.setLevel(logging.DEBUG)
# create formatter
formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
# add formatter to ch
ch.setFormatter(formatter)
# add ch to logger
logger.addHandler(ch)
# 'application' code
logger.debug('debug message')
logger.info('info message')
logger.warn('warn message')
logger.error('error message')
logger.critical('critical message')
Running this module from the command line produces the following output:
.. code-block:: shell-session
$ python simple_logging_module.py
2005-03-19 15:10:26,618 - simple_example - DEBUG - debug message
2005-03-19 15:10:26,620 - simple_example - INFO - info message
2005-03-19 15:10:26,695 - simple_example - WARNING - warn message
2005-03-19 15:10:26,697 - simple_example - ERROR - error message
2005-03-19 15:10:26,773 - simple_example - CRITICAL - critical message
The following Python module creates a logger, handler, and formatter nearly
identical to those in the example listed above, with the only difference being
the names of the objects::
import logging
import logging.config
logging.config.fileConfig('logging.conf')
# create logger
logger = logging.getLogger('simpleExample')
# 'application' code
logger.debug('debug message')
logger.info('info message')
logger.warn('warn message')
logger.error('error message')
logger.critical('critical message')
Here is the logging.conf file::
[loggers]
keys=root,simpleExample
[handlers]
keys=consoleHandler
[formatters]
keys=simpleFormatter
[logger_root]
level=DEBUG
handlers=consoleHandler
[logger_simpleExample]
level=DEBUG
handlers=consoleHandler
qualname=simpleExample
propagate=0
[handler_consoleHandler]
class=StreamHandler
level=DEBUG
formatter=simpleFormatter
args=(sys.stdout,)
[formatter_simpleFormatter]
format=%(asctime)s - %(name)s - %(levelname)s - %(message)s
datefmt=
The output is nearly identical to that of the non-config-file-based example:
.. code-block:: shell-session
$ python simple_logging_config.py
2005-03-19 15:38:55,977 - simpleExample - DEBUG - debug message
2005-03-19 15:38:55,979 - simpleExample - INFO - info message
2005-03-19 15:38:56,054 - simpleExample - WARNING - warn message
2005-03-19 15:38:56,055 - simpleExample - ERROR - error message
2005-03-19 15:38:56,130 - simpleExample - CRITICAL - critical message
You can see that the config file approach has a few advantages over the Python
code approach, mainly separation of configuration and code and the ability of
noncoders to easily modify the logging properties.
.. warning:: The :func:`fileConfig` function takes a default parameter,
``disable_existing_loggers``, which defaults to ``True`` for reasons of
backward compatibility. This may or may not be what you want, since it
will cause any loggers existing before the :func:`fileConfig` call to
be disabled unless they (or an ancestor) are explicitly named in the
configuration. Please refer to the reference documentation for more
information, and specify ``False`` for this parameter if you wish.
The dictionary passed to :func:`dictConfig` can also specify a Boolean
value with key ``disable_existing_loggers``, which if not specified
explicitly in the dictionary also defaults to being interpreted as
``True``. This leads to the logger-disabling behaviour described above,
which may not be what you want - in which case, provide the key
explicitly with a value of ``False``.
.. currentmodule:: logging
Note that the class names referenced in config files need to be either relative
to the logging module, or absolute values which can be resolved using normal
import mechanisms. Thus, you could use either
:class:`~logging.handlers.WatchedFileHandler` (relative to the logging module) or
``mypackage.mymodule.MyHandler`` (for a class defined in package ``mypackage``
and module ``mymodule``, where ``mypackage`` is available on the Python import
path).
In Python 2.7, a new means of configuring logging has been introduced, using
dictionaries to hold configuration information. This provides a superset of the
functionality of the config-file-based approach outlined above, and is the
recommended configuration method for new applications and deployments. Because
a Python dictionary is used to hold configuration information, and since you
can populate that dictionary using different means, you have more options for
configuration. For example, you can use a configuration file in JSON format,
or, if you have access to YAML processing functionality, a file in YAML
format, to populate the configuration dictionary. Or, of course, you can
construct the dictionary in Python code, receive it in pickled form over a
socket, or use whatever approach makes sense for your application.
Here's an example of the same configuration as above, in YAML format for
the new dictionary-based approach::
version: 1
formatters:
simple:
format: '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
handlers:
console:
class: logging.StreamHandler
level: DEBUG
formatter: simple
stream: ext://sys.stdout
loggers:
simpleExample:
level: DEBUG
handlers: [console]
propagate: no
root:
level: DEBUG
handlers: [console]
For more information about logging using a dictionary, see
:ref:`logging-config-api`.
What happens if no configuration is provided
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If no logging configuration is provided, it is possible to have a situation
where a logging event needs to be output, but no handlers can be found to
output the event. The behaviour of the logging package in these
circumstances is dependent on the Python version.
For Python 2.x, the behaviour is as follows:
* If *logging.raiseExceptions* is ``False`` (production mode), the event is
silently dropped.
* If *logging.raiseExceptions* is ``True`` (development mode), a message
'No handlers could be found for logger X.Y.Z' is printed once.
.. _library-config:
Configuring Logging for a Library
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When developing a library which uses logging, you should take care to
document how the library uses logging - for example, the names of loggers
used. Some consideration also needs to be given to its logging configuration.
If the using application does not configure logging, and library code makes
logging calls, then (as described in the previous section) an error message
will be printed to ``sys.stderr``.
If for some reason you *don't* want this message printed in the absence of
any logging configuration, you can attach a do-nothing handler to the top-level
logger for your library. This avoids the message being printed, since a handler
will be always be found for the library's events: it just doesn't produce any
output. If the library user configures logging for application use, presumably
that configuration will add some handlers, and if levels are suitably
configured then logging calls made in library code will send output to those
handlers, as normal.
A do-nothing handler is included in the logging package:
:class:`~logging.NullHandler` (since Python 2.7). An instance of this handler
could be added to the top-level logger of the logging namespace used by the
library (*if* you want to prevent an error message being output to
``sys.stderr`` in the absence of logging configuration). If all logging by a
library *foo* is done using loggers with names matching 'foo.x', 'foo.x.y',
etc. then the code::
import logging
logging.getLogger('foo').addHandler(logging.NullHandler())
should have the desired effect. If an organisation produces a number of
libraries, then the logger name specified can be 'orgname.foo' rather than
just 'foo'.
.. note:: It is strongly advised that you *do not add any handlers other
than* :class:`~logging.NullHandler` *to your library's loggers*. This is
because the configuration of handlers is the prerogative of the application
developer who uses your library. The application developer knows their
target audience and what handlers are most appropriate for their
application: if you add handlers 'under the hood', you might well interfere
with their ability to carry out unit tests and deliver logs which suit their
requirements.
Logging Levels
--------------
The numeric values of logging levels are given in the following table. These are
primarily of interest if you want to define your own levels, and need them to
have specific values relative to the predefined levels. If you define a level
with the same numeric value, it overwrites the predefined value; the predefined
name is lost.
+--------------+---------------+
| Level | Numeric value |
+==============+===============+
| ``CRITICAL`` | 50 |
+--------------+---------------+
| ``ERROR`` | 40 |
+--------------+---------------+
| ``WARNING`` | 30 |
+--------------+---------------+
| ``INFO`` | 20 |
+--------------+---------------+
| ``DEBUG`` | 10 |
+--------------+---------------+
| ``NOTSET`` | 0 |
+--------------+---------------+
Levels can also be associated with loggers, being set either by the developer or
through loading a saved logging configuration. When a logging method is called
on a logger, the logger compares its own level with the level associated with
the method call. If the logger's level is higher than the method call's, no
logging message is actually generated. This is the basic mechanism controlling
the verbosity of logging output.
Logging messages are encoded as instances of the :class:`~logging.LogRecord`
class. When a logger decides to actually log an event, a
:class:`~logging.LogRecord` instance is created from the logging message.
Logging messages are subjected to a dispatch mechanism through the use of
:dfn:`handlers`, which are instances of subclasses of the :class:`Handler`
class. Handlers are responsible for ensuring that a logged message (in the form
of a :class:`LogRecord`) ends up in a particular location (or set of locations)
which is useful for the target audience for that message (such as end users,
support desk staff, system administrators, developers). Handlers are passed
:class:`LogRecord` instances intended for particular destinations. Each logger
can have zero, one or more handlers associated with it (via the
:meth:`~Logger.addHandler` method of :class:`Logger`). In addition to any
handlers directly associated with a logger, *all handlers associated with all
ancestors of the logger* are called to dispatch the message (unless the
*propagate* flag for a logger is set to a false value, at which point the
passing to ancestor handlers stops).
Just as for loggers, handlers can have levels associated with them. A handler's
level acts as a filter in the same way as a logger's level does. If a handler
decides to actually dispatch an event, the :meth:`~Handler.emit` method is used
to send the message to its destination. Most user-defined subclasses of
:class:`Handler` will need to override this :meth:`~Handler.emit`.
.. _custom-levels:
Custom Levels
^^^^^^^^^^^^^
Defining your own levels is possible, but should not be necessary, as the
existing levels have been chosen on the basis of practical experience.
However, if you are convinced that you need custom levels, great care should
be exercised when doing this, and it is possibly *a very bad idea to define
custom levels if you are developing a library*. That's because if multiple
library authors all define their own custom levels, there is a chance that
the logging output from such multiple libraries used together will be
difficult for the using developer to control and/or interpret, because a
given numeric value might mean different things for different libraries.
.. _useful-handlers:
Useful Handlers
---------------
In addition to the base :class:`Handler` class, many useful subclasses are
provided:
#. :class:`StreamHandler` instances send messages to streams (file-like
objects).
#. :class:`FileHandler` instances send messages to disk files.
#. :class:`~handlers.BaseRotatingHandler` is the base class for handlers that
rotate log files at a certain point. It is not meant to be instantiated
directly. Instead, use :class:`~handlers.RotatingFileHandler` or
:class:`~handlers.TimedRotatingFileHandler`.
#. :class:`~handlers.RotatingFileHandler` instances send messages to disk
files, with support for maximum log file sizes and log file rotation.
#. :class:`~handlers.TimedRotatingFileHandler` instances send messages to
disk files, rotating the log file at certain timed intervals.
#. :class:`~handlers.SocketHandler` instances send messages to TCP/IP
sockets.
#. :class:`~handlers.DatagramHandler` instances send messages to UDP
sockets.
#. :class:`~handlers.SMTPHandler` instances send messages to a designated
email address.
#. :class:`~handlers.SysLogHandler` instances send messages to a Unix
syslog daemon, possibly on a remote machine.
#. :class:`~handlers.NTEventLogHandler` instances send messages to a
Windows NT/2000/XP event log.
#. :class:`~handlers.MemoryHandler` instances send messages to a buffer
in memory, which is flushed whenever specific criteria are met.
#. :class:`~handlers.HTTPHandler` instances send messages to an HTTP
server using either ``GET`` or ``POST`` semantics.
#. :class:`~handlers.WatchedFileHandler` instances watch the file they are
logging to. If the file changes, it is closed and reopened using the file
name. This handler is only useful on Unix-like systems; Windows does not
support the underlying mechanism used.
#. :class:`NullHandler` instances do nothing with error messages. They are used
by library developers who want to use logging, but want to avoid the 'No
handlers could be found for logger XXX' message which can be displayed if
the library user has not configured logging. See :ref:`library-config` for
more information.
.. versionadded:: 2.7
The :class:`NullHandler` class.
The :class:`NullHandler`, :class:`StreamHandler` and :class:`FileHandler`
classes are defined in the core logging package. The other handlers are
defined in a sub- module, :mod:`logging.handlers`. (There is also another
sub-module, :mod:`logging.config`, for configuration functionality.)
Logged messages are formatted for presentation through instances of the
:class:`Formatter` class. They are initialized with a format string suitable for
use with the % operator and a dictionary.
For formatting multiple messages in a batch, instances of
:class:`~handlers.BufferingFormatter` can be used. In addition to the format
string (which is applied to each message in the batch), there is provision for
header and trailer format strings.
When filtering based on logger level and/or handler level is not enough,
instances of :class:`Filter` can be added to both :class:`Logger` and
:class:`Handler` instances (through their :meth:`~Handler.addFilter` method).
Before deciding to process a message further, both loggers and handlers consult
all their filters for permission. If any filter returns a false value, the
message is not processed further.
The basic :class:`Filter` functionality allows filtering by specific logger
name. If this feature is used, messages sent to the named logger and its
children are allowed through the filter, and all others dropped.
.. _logging-exceptions:
Exceptions raised during logging
--------------------------------
The logging package is designed to swallow exceptions which occur while logging
in production. This is so that errors which occur while handling logging events
- such as logging misconfiguration, network or other similar errors - do not
cause the application using logging to terminate prematurely.
:class:`SystemExit` and :class:`KeyboardInterrupt` exceptions are never
swallowed. Other exceptions which occur during the :meth:`~Handler.emit` method
of a :class:`Handler` subclass are passed to its :meth:`~Handler.handleError`
method.
The default implementation of :meth:`~Handler.handleError` in :class:`Handler`
checks to see if a module-level variable, :data:`raiseExceptions`, is set. If
set, a traceback is printed to :data:`sys.stderr`. If not set, the exception is
swallowed.
.. note:: The default value of :data:`raiseExceptions` is ``True``. This is
because during development, you typically want to be notified of any
exceptions that occur. It's advised that you set :data:`raiseExceptions` to
``False`` for production usage.
.. _arbitrary-object-messages:
Using arbitrary objects as messages
-----------------------------------
In the preceding sections and examples, it has been assumed that the message
passed when logging the event is a string. However, this is not the only
possibility. You can pass an arbitrary object as a message, and its
:meth:`~object.__str__` method will be called when the logging system needs to
convert it to a string representation. In fact, if you want to, you can avoid
computing a string representation altogether - for example, the
:class:`~handlers.SocketHandler` emits an event by pickling it and sending it
over the wire.
Optimization
------------
Formatting of message arguments is deferred until it cannot be avoided.
However, computing the arguments passed to the logging method can also be
expensive, and you may want to avoid doing it if the logger will just throw
away your event. To decide what to do, you can call the
:meth:`~Logger.isEnabledFor` method which takes a level argument and returns
true if the event would be created by the Logger for that level of call.
You can write code like this::
if logger.isEnabledFor(logging.DEBUG):
logger.debug('Message with %s, %s', expensive_func1(),
expensive_func2())
so that if the logger's threshold is set above ``DEBUG``, the calls to
:func:`expensive_func1` and :func:`expensive_func2` are never made.
.. note:: In some cases, :meth:`~Logger.isEnabledFor` can itself be more
expensive than you'd like (e.g. for deeply nested loggers where an explicit
level is only set high up in the logger hierarchy). In such cases (or if you
want to avoid calling a method in tight loops), you can cache the result of a
call to :meth:`~Logger.isEnabledFor` in a local or instance variable, and use
that instead of calling the method each time. Such a cached value would only
need to be recomputed when the logging configuration changes dynamically
while the application is running (which is not all that common).
There are other optimizations which can be made for specific applications which
need more precise control over what logging information is collected. Here's a
list of things you can do to avoid processing during logging which you don't
need:
+-----------------------------------------------+----------------------------------------+
| What you don't want to collect | How to avoid collecting it |
+===============================================+========================================+
| Information about where calls were made from. | Set ``logging._srcfile`` to ``None``. |
| | This avoids calling |
| | :func:`sys._getframe`, which may help |
| | to speed up your code in environments |
| | like PyPy (which can't speed up code |
| | that uses :func:`sys._getframe`). |
+-----------------------------------------------+----------------------------------------+
| Threading information. | Set ``logging.logThreads`` to ``0``. |
+-----------------------------------------------+----------------------------------------+
| Process information. | Set ``logging.logProcesses`` to ``0``. |
+-----------------------------------------------+----------------------------------------+
Also note that the core logging module only includes the basic handlers. If
you don't import :mod:`logging.handlers` and :mod:`logging.config`, they won't
take up any memory.
.. seealso::
Module :mod:`logging`
API reference for the logging module.
Module :mod:`logging.config`
Configuration API for the logging module.
Module :mod:`logging.handlers`
Useful handlers included with the logging module.
:ref:`A logging cookbook <logging-cookbook>`
PK %�\�,x@�W �W % html/_sources/howto/pyporting.rst.txtnu �[��� .. _pyporting-howto:
*********************************
Porting Python 2 Code to Python 3
*********************************
:author: Brett Cannon
.. topic:: Abstract
With Python 3 being the future of Python while Python 2 is still in active
use, it is good to have your project available for both major releases of
Python. This guide is meant to help you figure out how best to support both
Python 2 & 3 simultaneously.
If you are looking to port an extension module instead of pure Python code,
please see :ref:`cporting-howto`.
If you would like to read one core Python developer's take on why Python 3
came into existence, you can read Nick Coghlan's `Python 3 Q & A`_ or
Brett Cannon's `Why Python 3 exists`_.
For help with porting, you can email the python-porting_ mailing list with
questions.
The Short Explanation
=====================
To make your project be single-source Python 2/3 compatible, the basic steps
are:
#. Only worry about supporting Python 2.7
#. Make sure you have good test coverage (coverage.py_ can help;
``pip install coverage``)
#. Learn the differences between Python 2 & 3
#. Use Futurize_ (or Modernize_) to update your code (e.g. ``pip install future``)
#. Use Pylint_ to help make sure you don't regress on your Python 3 support
(``pip install pylint``)
#. Use caniusepython3_ to find out which of your dependencies are blocking your
use of Python 3 (``pip install caniusepython3``)
#. Once your dependencies are no longer blocking you, use continuous integration
to make sure you stay compatible with Python 2 & 3 (tox_ can help test
against multiple versions of Python; ``pip install tox``)
#. Consider using optional static type checking to make sure your type usage
works in both Python 2 & 3 (e.g. use mypy_ to check your typing under both
Python 2 & Python 3).
Details
=======
A key point about supporting Python 2 & 3 simultaneously is that you can start
**today**! Even if your dependencies are not supporting Python 3 yet that does
not mean you can't modernize your code **now** to support Python 3. Most changes
required to support Python 3 lead to cleaner code using newer practices even in
Python 2 code.
Another key point is that modernizing your Python 2 code to also support
Python 3 is largely automated for you. While you might have to make some API
decisions thanks to Python 3 clarifying text data versus binary data, the
lower-level work is now mostly done for you and thus can at least benefit from
the automated changes immediately.
Keep those key points in mind while you read on about the details of porting
your code to support Python 2 & 3 simultaneously.
Drop support for Python 2.6 and older
-------------------------------------
While you can make Python 2.5 work with Python 3, it is **much** easier if you
only have to work with Python 2.7. If dropping Python 2.5 is not an
option then the six_ project can help you support Python 2.5 & 3 simultaneously
(``pip install six``). Do realize, though, that nearly all the projects listed
in this HOWTO will not be available to you.
If you are able to skip Python 2.5 and older, then the required changes
to your code should continue to look and feel like idiomatic Python code. At
worst you will have to use a function instead of a method in some instances or
have to import a function instead of using a built-in one, but otherwise the
overall transformation should not feel foreign to you.
But you should aim for only supporting Python 2.7. Python 2.6 is no longer
freely supported and thus is not receiving bugfixes. This means **you** will have
to work around any issues you come across with Python 2.6. There are also some
tools mentioned in this HOWTO which do not support Python 2.6 (e.g., Pylint_),
and this will become more commonplace as time goes on. It will simply be easier
for you if you only support the versions of Python that you have to support.
Make sure you specify the proper version support in your ``setup.py`` file
--------------------------------------------------------------------------
In your ``setup.py`` file you should have the proper `trove classifier`_
specifying what versions of Python you support. As your project does not support
Python 3 yet you should at least have
``Programming Language :: Python :: 2 :: Only`` specified. Ideally you should
also specify each major/minor version of Python that you do support, e.g.
``Programming Language :: Python :: 2.7``.
Have good test coverage
-----------------------
Once you have your code supporting the oldest version of Python 2 you want it
to, you will want to make sure your test suite has good coverage. A good rule of
thumb is that if you want to be confident enough in your test suite that any
failures that appear after having tools rewrite your code are actual bugs in the
tools and not in your code. If you want a number to aim for, try to get over 80%
coverage (and don't feel bad if you find it hard to get better than 90%
coverage). If you don't already have a tool to measure test coverage then
coverage.py_ is recommended.
Learn the differences between Python 2 & 3
-------------------------------------------
Once you have your code well-tested you are ready to begin porting your code to
Python 3! But to fully understand how your code is going to change and what
you want to look out for while you code, you will want to learn what changes
Python 3 makes in terms of Python 2. Typically the two best ways of doing that
is reading the `"What's New"`_ doc for each release of Python 3 and the
`Porting to Python 3`_ book (which is free online). There is also a handy
`cheat sheet`_ from the Python-Future project.
Update your code
----------------
Once you feel like you know what is different in Python 3 compared to Python 2,
it's time to update your code! You have a choice between two tools in porting
your code automatically: Futurize_ and Modernize_. Which tool you choose will
depend on how much like Python 3 you want your code to be. Futurize_ does its
best to make Python 3 idioms and practices exist in Python 2, e.g. backporting
the ``bytes`` type from Python 3 so that you have semantic parity between the
major versions of Python. Modernize_,
on the other hand, is more conservative and targets a Python 2/3 subset of
Python, directly relying on six_ to help provide compatibility. As Python 3 is
the future, it might be best to consider Futurize to begin adjusting to any new
practices that Python 3 introduces which you are not accustomed to yet.
Regardless of which tool you choose, they will update your code to run under
Python 3 while staying compatible with the version of Python 2 you started with.
Depending on how conservative you want to be, you may want to run the tool over
your test suite first and visually inspect the diff to make sure the
transformation is accurate. After you have transformed your test suite and
verified that all the tests still pass as expected, then you can transform your
application code knowing that any tests which fail is a translation failure.
Unfortunately the tools can't automate everything to make your code work under
Python 3 and so there are a handful of things you will need to update manually
to get full Python 3 support (which of these steps are necessary vary between
the tools). Read the documentation for the tool you choose to use to see what it
fixes by default and what it can do optionally to know what will (not) be fixed
for you and what you may have to fix on your own (e.g. using ``io.open()`` over
the built-in ``open()`` function is off by default in Modernize). Luckily,
though, there are only a couple of things to watch out for which can be
considered large issues that may be hard to debug if not watched for.
Division
++++++++
In Python 3, ``5 / 2 == 2.5`` and not ``2``; all division between ``int`` values
result in a ``float``. This change has actually been planned since Python 2.2
which was released in 2002. Since then users have been encouraged to add
``from __future__ import division`` to any and all files which use the ``/`` and
``//`` operators or to be running the interpreter with the ``-Q`` flag. If you
have not been doing this then you will need to go through your code and do two
things:
#. Add ``from __future__ import division`` to your files
#. Update any division operator as necessary to either use ``//`` to use floor
division or continue using ``/`` and expect a float
The reason that ``/`` isn't simply translated to ``//`` automatically is that if
an object defines a ``__truediv__`` method but not ``__floordiv__`` then your
code would begin to fail (e.g. a user-defined class that uses ``/`` to
signify some operation but not ``//`` for the same thing or at all).
Text versus binary data
+++++++++++++++++++++++
In Python 2 you could use the ``str`` type for both text and binary data.
Unfortunately this confluence of two different concepts could lead to brittle
code which sometimes worked for either kind of data, sometimes not. It also
could lead to confusing APIs if people didn't explicitly state that something
that accepted ``str`` accepted either text or binary data instead of one
specific type. This complicated the situation especially for anyone supporting
multiple languages as APIs wouldn't bother explicitly supporting ``unicode``
when they claimed text data support.
To make the distinction between text and binary data clearer and more
pronounced, Python 3 did what most languages created in the age of the internet
have done and made text and binary data distinct types that cannot blindly be
mixed together (Python predates widespread access to the internet). For any code
that deals only with text or only binary data, this separation doesn't pose an
issue. But for code that has to deal with both, it does mean you might have to
now care about when you are using text compared to binary data, which is why
this cannot be entirely automated.
To start, you will need to decide which APIs take text and which take binary
(it is **highly** recommended you don't design APIs that can take both due to
the difficulty of keeping the code working; as stated earlier it is difficult to
do well). In Python 2 this means making sure the APIs that take text can work
with ``unicode`` and those that work with binary data work with the
``bytes`` type from Python 3 (which is a subset of ``str`` in Python 2 and acts
as an alias for ``bytes`` type in Python 2). Usually the biggest issue is
realizing which methods exist on which types in Python 2 & 3 simultaneously
(for text that's ``unicode`` in Python 2 and ``str`` in Python 3, for binary
that's ``str``/``bytes`` in Python 2 and ``bytes`` in Python 3). The following
table lists the **unique** methods of each data type across Python 2 & 3
(e.g., the ``decode()`` method is usable on the equivalent binary data type in
either Python 2 or 3, but it can't be used by the textual data type consistently
between Python 2 and 3 because ``str`` in Python 3 doesn't have the method). Do
note that as of Python 3.5 the ``__mod__`` method was added to the bytes type.
======================== =====================
**Text data** **Binary data**
------------------------ ---------------------
\ decode
------------------------ ---------------------
encode
------------------------ ---------------------
format
------------------------ ---------------------
isdecimal
------------------------ ---------------------
isnumeric
======================== =====================
Making the distinction easier to handle can be accomplished by encoding and
decoding between binary data and text at the edge of your code. This means that
when you receive text in binary data, you should immediately decode it. And if
your code needs to send text as binary data then encode it as late as possible.
This allows your code to work with only text internally and thus eliminates
having to keep track of what type of data you are working with.
The next issue is making sure you know whether the string literals in your code
represent text or binary data. You should add a ``b`` prefix to any
literal that presents binary data. For text you should add a ``u`` prefix to
the text literal. (there is a :mod:`__future__` import to force all unspecified
literals to be Unicode, but usage has shown it isn't as effective as adding a
``b`` or ``u`` prefix to all literals explicitly)
As part of this dichotomy you also need to be careful about opening files.
Unless you have been working on Windows, there is a chance you have not always
bothered to add the ``b`` mode when opening a binary file (e.g., ``rb`` for
binary reading). Under Python 3, binary files and text files are clearly
distinct and mutually incompatible; see the :mod:`io` module for details.
Therefore, you **must** make a decision of whether a file will be used for
binary access (allowing binary data to be read and/or written) or textual access
(allowing text data to be read and/or written). You should also use :func:`io.open`
for opening files instead of the built-in :func:`open` function as the :mod:`io`
module is consistent from Python 2 to 3 while the built-in :func:`open` function
is not (in Python 3 it's actually :func:`io.open`). Do not bother with the
outdated practice of using :func:`codecs.open` as that's only necessary for
keeping compatibility with Python 2.5.
The constructors of both ``str`` and ``bytes`` have different semantics for the
same arguments between Python 2 & 3. Passing an integer to ``bytes`` in Python 2
will give you the string representation of the integer: ``bytes(3) == '3'``.
But in Python 3, an integer argument to ``bytes`` will give you a bytes object
as long as the integer specified, filled with null bytes:
``bytes(3) == b'\x00\x00\x00'``. A similar worry is necessary when passing a
bytes object to ``str``. In Python 2 you just get the bytes object back:
``str(b'3') == b'3'``. But in Python 3 you get the string representation of the
bytes object: ``str(b'3') == "b'3'"``.
Finally, the indexing of binary data requires careful handling (slicing does
**not** require any special handling). In Python 2,
``b'123'[1] == b'2'`` while in Python 3 ``b'123'[1] == 50``. Because binary data
is simply a collection of binary numbers, Python 3 returns the integer value for
the byte you index on. But in Python 2 because ``bytes == str``, indexing
returns a one-item slice of bytes. The six_ project has a function
named ``six.indexbytes()`` which will return an integer like in Python 3:
``six.indexbytes(b'123', 1)``.
To summarize:
#. Decide which of your APIs take text and which take binary data
#. Make sure that your code that works with text also works with ``unicode`` and
code for binary data works with ``bytes`` in Python 2 (see the table above
for what methods you cannot use for each type)
#. Mark all binary literals with a ``b`` prefix, textual literals with a ``u``
prefix
#. Decode binary data to text as soon as possible, encode text as binary data as
late as possible
#. Open files using :func:`io.open` and make sure to specify the ``b`` mode when
appropriate
#. Be careful when indexing into binary data
Use feature detection instead of version detection
++++++++++++++++++++++++++++++++++++++++++++++++++
Inevitably you will have code that has to choose what to do based on what
version of Python is running. The best way to do this is with feature detection
of whether the version of Python you're running under supports what you need.
If for some reason that doesn't work then you should make the version check be
against Python 2 and not Python 3. To help explain this, let's look at an
example.
Let's pretend that you need access to a feature of importlib_ that
is available in Python's standard library since Python 3.3 and available for
Python 2 through importlib2_ on PyPI. You might be tempted to write code to
access e.g. the ``importlib.abc`` module by doing the following::
import sys
if sys.version_info[0] == 3:
from importlib import abc
else:
from importlib2 import abc
The problem with this code is what happens when Python 4 comes out? It would
be better to treat Python 2 as the exceptional case instead of Python 3 and
assume that future Python versions will be more compatible with Python 3 than
Python 2::
import sys
if sys.version_info[0] > 2:
from importlib import abc
else:
from importlib2 import abc
The best solution, though, is to do no version detection at all and instead rely
on feature detection. That avoids any potential issues of getting the version
detection wrong and helps keep you future-compatible::
try:
from importlib import abc
except ImportError:
from importlib2 import abc
Prevent compatibility regressions
---------------------------------
Once you have fully translated your code to be compatible with Python 3, you
will want to make sure your code doesn't regress and stop working under
Python 3. This is especially true if you have a dependency which is blocking you
from actually running under Python 3 at the moment.
To help with staying compatible, any new modules you create should have
at least the following block of code at the top of it::
from __future__ import absolute_import
from __future__ import division
from __future__ import print_function
You can also run Python 2 with the ``-3`` flag to be warned about various
compatibility issues your code triggers during execution. If you turn warnings
into errors with ``-Werror`` then you can make sure that you don't accidentally
miss a warning.
You can also use the Pylint_ project and its ``--py3k`` flag to lint your code
to receive warnings when your code begins to deviate from Python 3
compatibility. This also prevents you from having to run Modernize_ or Futurize_
over your code regularly to catch compatibility regressions. This does require
you only support Python 2.7 and Python 3.4 or newer as that is Pylint's
minimum Python version support.
Check which dependencies block your transition
----------------------------------------------
**After** you have made your code compatible with Python 3 you should begin to
care about whether your dependencies have also been ported. The caniusepython3_
project was created to help you determine which projects
-- directly or indirectly -- are blocking you from supporting Python 3. There
is both a command-line tool as well as a web interface at
https://caniusepython3.com.
The project also provides code which you can integrate into your test suite so
that you will have a failing test when you no longer have dependencies blocking
you from using Python 3. This allows you to avoid having to manually check your
dependencies and to be notified quickly when you can start running on Python 3.
Update your ``setup.py`` file to denote Python 3 compatibility
--------------------------------------------------------------
Once your code works under Python 3, you should update the classifiers in
your ``setup.py`` to contain ``Programming Language :: Python :: 3`` and to not
specify sole Python 2 support. This will tell anyone using your code that you
support Python 2 **and** 3. Ideally you will also want to add classifiers for
each major/minor version of Python you now support.
Use continuous integration to stay compatible
---------------------------------------------
Once you are able to fully run under Python 3 you will want to make sure your
code always works under both Python 2 & 3. Probably the best tool for running
your tests under multiple Python interpreters is tox_. You can then integrate
tox with your continuous integration system so that you never accidentally break
Python 2 or 3 support.
You may also want to use the ``-bb`` flag with the Python 3 interpreter to
trigger an exception when you are comparing bytes to strings or bytes to an int
(the latter is available starting in Python 3.5). By default type-differing
comparisons simply return ``False``, but if you made a mistake in your
separation of text/binary data handling or indexing on bytes you wouldn't easily
find the mistake. This flag will raise an exception when these kinds of
comparisons occur, making the mistake much easier to track down.
And that's mostly it! At this point your code base is compatible with both
Python 2 and 3 simultaneously. Your testing will also be set up so that you
don't accidentally break Python 2 or 3 compatibility regardless of which version
you typically run your tests under while developing.
Consider using optional static type checking
--------------------------------------------
Another way to help port your code is to use a static type checker like
mypy_ or pytype_ on your code. These tools can be used to analyze your code as
if it's being run under Python 2, then you can run the tool a second time as if
your code is running under Python 3. By running a static type checker twice like
this you can discover if you're e.g. misusing binary data type in one version
of Python compared to another. If you add optional type hints to your code you
can also explicitly state whether your APIs use textual or binary data, helping
to make sure everything functions as expected in both versions of Python.
.. _2to3: https://docs.python.org/3/library/2to3.html
.. _caniusepython3: https://pypi.org/project/caniusepython3
.. _cheat sheet: http://python-future.org/compatible_idioms.html
.. _coverage.py: https://pypi.org/project/coverage
.. _Futurize: http://python-future.org/automatic_conversion.html
.. _importlib: https://docs.python.org/3/library/importlib.html#module-importlib
.. _importlib2: https://pypi.org/project/importlib2
.. _Modernize: https://python-modernize.readthedocs.org/en/latest/
.. _mypy: http://mypy-lang.org/
.. _Porting to Python 3: http://python3porting.com/
.. _Pylint: https://pypi.org/project/pylint
.. _Python 3 Q & A: https://ncoghlan-devs-python-notes.readthedocs.org/en/latest/python3/questions_and_answers.html
.. _pytype: https://github.com/google/pytype
.. _python-future: http://python-future.org/
.. _python-porting: https://mail.python.org/mailman/listinfo/python-porting
.. _six: https://pypi.org/project/six
.. _tox: https://pypi.org/project/tox
.. _trove classifier: https://pypi.org/classifiers
.. _"What's New": https://docs.python.org/3/whatsnew/index.html
.. _Why Python 3 exists: http://www.snarky.ca/why-python-3-exists
PK %�\?5�� �� ! html/_sources/howto/regex.rst.txtnu �[��� .. _regex-howto:
****************************
Regular Expression HOWTO
****************************
:Author: A.M. Kuchling <amk@amk.ca>
.. TODO:
Document lookbehind assertions
Better way of displaying a RE, a string, and what it matches
Mention optional argument to match.groups()
Unicode (at least a reference)
.. topic:: Abstract
This document is an introductory tutorial to using regular expressions in Python
with the :mod:`re` module. It provides a gentler introduction than the
corresponding section in the Library Reference.
Introduction
============
The :mod:`re` module was added in Python 1.5, and provides Perl-style regular
expression patterns. Earlier versions of Python came with the :mod:`regex`
module, which provided Emacs-style patterns. The :mod:`regex` module was
removed completely in Python 2.5.
Regular expressions (called REs, or regexes, or regex patterns) are essentially
a tiny, highly specialized programming language embedded inside Python and made
available through the :mod:`re` module. Using this little language, you specify
the rules for the set of possible strings that you want to match; this set might
contain English sentences, or e-mail addresses, or TeX commands, or anything you
like. You can then ask questions such as "Does this string match the pattern?",
or "Is there a match for the pattern anywhere in this string?". You can also
use REs to modify a string or to split it apart in various ways.
Regular expression patterns are compiled into a series of bytecodes which are
then executed by a matching engine written in C. For advanced use, it may be
necessary to pay careful attention to how the engine will execute a given RE,
and write the RE in a certain way in order to produce bytecode that runs faster.
Optimization isn't covered in this document, because it requires that you have a
good understanding of the matching engine's internals.
The regular expression language is relatively small and restricted, so not all
possible string processing tasks can be done using regular expressions. There
are also tasks that *can* be done with regular expressions, but the expressions
turn out to be very complicated. In these cases, you may be better off writing
Python code to do the processing; while Python code will be slower than an
elaborate regular expression, it will also probably be more understandable.
Simple Patterns
===============
We'll start by learning about the simplest possible regular expressions. Since
regular expressions are used to operate on strings, we'll begin with the most
common task: matching characters.
For a detailed explanation of the computer science underlying regular
expressions (deterministic and non-deterministic finite automata), you can refer
to almost any textbook on writing compilers.
Matching Characters
-------------------
Most letters and characters will simply match themselves. For example, the
regular expression ``test`` will match the string ``test`` exactly. (You can
enable a case-insensitive mode that would let this RE match ``Test`` or ``TEST``
as well; more about this later.)
There are exceptions to this rule; some characters are special
:dfn:`metacharacters`, and don't match themselves. Instead, they signal that
some out-of-the-ordinary thing should be matched, or they affect other portions
of the RE by repeating them or changing their meaning. Much of this document is
devoted to discussing various metacharacters and what they do.
Here's a complete list of the metacharacters; their meanings will be discussed
in the rest of this HOWTO.
.. code-block:: none
. ^ $ * + ? { } [ ] \ | ( )
The first metacharacters we'll look at are ``[`` and ``]``. They're used for
specifying a character class, which is a set of characters that you wish to
match. Characters can be listed individually, or a range of characters can be
indicated by giving two characters and separating them by a ``'-'``. For
example, ``[abc]`` will match any of the characters ``a``, ``b``, or ``c``; this
is the same as ``[a-c]``, which uses a range to express the same set of
characters. If you wanted to match only lowercase letters, your RE would be
``[a-z]``.
Metacharacters are not active inside classes. For example, ``[akm$]`` will
match any of the characters ``'a'``, ``'k'``, ``'m'``, or ``'$'``; ``'$'`` is
usually a metacharacter, but inside a character class it's stripped of its
special nature.
You can match the characters not listed within the class by :dfn:`complementing`
the set. This is indicated by including a ``'^'`` as the first character of the
class; ``'^'`` outside a character class will simply match the ``'^'``
character. For example, ``[^5]`` will match any character except ``'5'``.
Perhaps the most important metacharacter is the backslash, ``\``. As in Python
string literals, the backslash can be followed by various characters to signal
various special sequences. It's also used to escape all the metacharacters so
you can still match them in patterns; for example, if you need to match a ``[``
or ``\``, you can precede them with a backslash to remove their special
meaning: ``\[`` or ``\\``.
Some of the special sequences beginning with ``'\'`` represent predefined sets
of characters that are often useful, such as the set of digits, the set of
letters, or the set of anything that isn't whitespace. The following predefined
special sequences are a subset of those available. The equivalent classes are
for byte string patterns. For a complete list of sequences and expanded class
definitions for Unicode string patterns, see the last part of
:ref:`Regular Expression Syntax <re-syntax>`.
``\d``
Matches any decimal digit; this is equivalent to the class ``[0-9]``.
``\D``
Matches any non-digit character; this is equivalent to the class ``[^0-9]``.
``\s``
Matches any whitespace character; this is equivalent to the class ``[
\t\n\r\f\v]``.
``\S``
Matches any non-whitespace character; this is equivalent to the class ``[^
\t\n\r\f\v]``.
``\w``
Matches any alphanumeric character; this is equivalent to the class
``[a-zA-Z0-9_]``.
``\W``
Matches any non-alphanumeric character; this is equivalent to the class
``[^a-zA-Z0-9_]``.
These sequences can be included inside a character class. For example,
``[\s,.]`` is a character class that will match any whitespace character, or
``','`` or ``'.'``.
The final metacharacter in this section is ``.``. It matches anything except a
newline character, and there's an alternate mode (``re.DOTALL``) where it will
match even a newline. ``'.'`` is often used where you want to match "any
character".
Repeating Things
----------------
Being able to match varying sets of characters is the first thing regular
expressions can do that isn't already possible with the methods available on
strings. However, if that was the only additional capability of regexes, they
wouldn't be much of an advance. Another capability is that you can specify that
portions of the RE must be repeated a certain number of times.
The first metacharacter for repeating things that we'll look at is ``*``. ``*``
doesn't match the literal character ``*``; instead, it specifies that the
previous character can be matched zero or more times, instead of exactly once.
For example, ``ca*t`` will match ``ct`` (0 ``a`` characters), ``cat`` (1 ``a``),
``caaat`` (3 ``a`` characters), and so forth. The RE engine has various
internal limitations stemming from the size of C's ``int`` type that will
prevent it from matching over 2 billion ``a`` characters; you probably don't
have enough memory to construct a string that large, so you shouldn't run into
that limit.
Repetitions such as ``*`` are :dfn:`greedy`; when repeating a RE, the matching
engine will try to repeat it as many times as possible. If later portions of the
pattern don't match, the matching engine will then back up and try again with
fewer repetitions.
A step-by-step example will make this more obvious. Let's consider the
expression ``a[bcd]*b``. This matches the letter ``'a'``, zero or more letters
from the class ``[bcd]``, and finally ends with a ``'b'``. Now imagine matching
this RE against the string ``abcbd``.
+------+-----------+---------------------------------+
| Step | Matched | Explanation |
+======+===========+=================================+
| 1 | ``a`` | The ``a`` in the RE matches. |
+------+-----------+---------------------------------+
| 2 | ``abcbd`` | The engine matches ``[bcd]*``, |
| | | going as far as it can, which |
| | | is to the end of the string. |
+------+-----------+---------------------------------+
| 3 | *Failure* | The engine tries to match |
| | | ``b``, but the current position |
| | | is at the end of the string, so |
| | | it fails. |
+------+-----------+---------------------------------+
| 4 | ``abcb`` | Back up, so that ``[bcd]*`` |
| | | matches one less character. |
+------+-----------+---------------------------------+
| 5 | *Failure* | Try ``b`` again, but the |
| | | current position is at the last |
| | | character, which is a ``'d'``. |
+------+-----------+---------------------------------+
| 6 | ``abc`` | Back up again, so that |
| | | ``[bcd]*`` is only matching |
| | | ``bc``. |
+------+-----------+---------------------------------+
| 6 | ``abcb`` | Try ``b`` again. This time |
| | | the character at the |
| | | current position is ``'b'``, so |
| | | it succeeds. |
+------+-----------+---------------------------------+
The end of the RE has now been reached, and it has matched ``abcb``. This
demonstrates how the matching engine goes as far as it can at first, and if no
match is found it will then progressively back up and retry the rest of the RE
again and again. It will back up until it has tried zero matches for
``[bcd]*``, and if that subsequently fails, the engine will conclude that the
string doesn't match the RE at all.
Another repeating metacharacter is ``+``, which matches one or more times. Pay
careful attention to the difference between ``*`` and ``+``; ``*`` matches
*zero* or more times, so whatever's being repeated may not be present at all,
while ``+`` requires at least *one* occurrence. To use a similar example,
``ca+t`` will match ``cat`` (1 ``a``), ``caaat`` (3 ``a``'s), but won't match
``ct``.
There are two more repeating qualifiers. The question mark character, ``?``,
matches either once or zero times; you can think of it as marking something as
being optional. For example, ``home-?brew`` matches either ``homebrew`` or
``home-brew``.
The most complicated repeated qualifier is ``{m,n}``, where *m* and *n* are
decimal integers. This qualifier means there must be at least *m* repetitions,
and at most *n*. For example, ``a/{1,3}b`` will match ``a/b``, ``a//b``, and
``a///b``. It won't match ``ab``, which has no slashes, or ``a////b``, which
has four.
You can omit either *m* or *n*; in that case, a reasonable value is assumed for
the missing value. Omitting *m* is interpreted as a lower limit of 0, while
omitting *n* results in an upper bound of infinity --- actually, the upper bound
is the 2-billion limit mentioned earlier, but that might as well be infinity.
Readers of a reductionist bent may notice that the three other qualifiers can
all be expressed using this notation. ``{0,}`` is the same as ``*``, ``{1,}``
is equivalent to ``+``, and ``{0,1}`` is the same as ``?``. It's better to use
``*``, ``+``, or ``?`` when you can, simply because they're shorter and easier
to read.
Using Regular Expressions
=========================
Now that we've looked at some simple regular expressions, how do we actually use
them in Python? The :mod:`re` module provides an interface to the regular
expression engine, allowing you to compile REs into objects and then perform
matches with them.
Compiling Regular Expressions
-----------------------------
Regular expressions are compiled into pattern objects, which have
methods for various operations such as searching for pattern matches or
performing string substitutions. ::
>>> import re
>>> p = re.compile('ab*')
>>> p #doctest: +ELLIPSIS
<_sre.SRE_Pattern object at 0x...>
:func:`re.compile` also accepts an optional *flags* argument, used to enable
various special features and syntax variations. We'll go over the available
settings later, but for now a single example will do::
>>> p = re.compile('ab*', re.IGNORECASE)
The RE is passed to :func:`re.compile` as a string. REs are handled as strings
because regular expressions aren't part of the core Python language, and no
special syntax was created for expressing them. (There are applications that
don't need REs at all, so there's no need to bloat the language specification by
including them.) Instead, the :mod:`re` module is simply a C extension module
included with Python, just like the :mod:`socket` or :mod:`zlib` modules.
Putting REs in strings keeps the Python language simpler, but has one
disadvantage which is the topic of the next section.
The Backslash Plague
--------------------
As stated earlier, regular expressions use the backslash character (``'\'``) to
indicate special forms or to allow special characters to be used without
invoking their special meaning. This conflicts with Python's usage of the same
character for the same purpose in string literals.
Let's say you want to write a RE that matches the string ``\section``, which
might be found in a LaTeX file. To figure out what to write in the program
code, start with the desired string to be matched. Next, you must escape any
backslashes and other metacharacters by preceding them with a backslash,
resulting in the string ``\\section``. The resulting string that must be passed
to :func:`re.compile` must be ``\\section``. However, to express this as a
Python string literal, both backslashes must be escaped *again*.
+-------------------+------------------------------------------+
| Characters | Stage |
+===================+==========================================+
| ``\section`` | Text string to be matched |
+-------------------+------------------------------------------+
| ``\\section`` | Escaped backslash for :func:`re.compile` |
+-------------------+------------------------------------------+
| ``"\\\\section"`` | Escaped backslashes for a string literal |
+-------------------+------------------------------------------+
In short, to match a literal backslash, one has to write ``'\\\\'`` as the RE
string, because the regular expression must be ``\\``, and each backslash must
be expressed as ``\\`` inside a regular Python string literal. In REs that
feature backslashes repeatedly, this leads to lots of repeated backslashes and
makes the resulting strings difficult to understand.
The solution is to use Python's raw string notation for regular expressions;
backslashes are not handled in any special way in a string literal prefixed with
``'r'``, so ``r"\n"`` is a two-character string containing ``'\'`` and ``'n'``,
while ``"\n"`` is a one-character string containing a newline. Regular
expressions will often be written in Python code using this raw string notation.
+-------------------+------------------+
| Regular String | Raw string |
+===================+==================+
| ``"ab*"`` | ``r"ab*"`` |
+-------------------+------------------+
| ``"\\\\section"`` | ``r"\\section"`` |
+-------------------+------------------+
| ``"\\w+\\s+\\1"`` | ``r"\w+\s+\1"`` |
+-------------------+------------------+
Performing Matches
------------------
Once you have an object representing a compiled regular expression, what do you
do with it? Pattern objects have several methods and attributes.
Only the most significant ones will be covered here; consult the :mod:`re` docs
for a complete listing.
+------------------+-----------------------------------------------+
| Method/Attribute | Purpose |
+==================+===============================================+
| ``match()`` | Determine if the RE matches at the beginning |
| | of the string. |
+------------------+-----------------------------------------------+
| ``search()`` | Scan through a string, looking for any |
| | location where this RE matches. |
+------------------+-----------------------------------------------+
| ``findall()`` | Find all substrings where the RE matches, and |
| | returns them as a list. |
+------------------+-----------------------------------------------+
| ``finditer()`` | Find all substrings where the RE matches, and |
| | returns them as an :term:`iterator`. |
+------------------+-----------------------------------------------+
:meth:`match` and :meth:`search` return ``None`` if no match can be found. If
they're successful, a :ref:`match object <match-objects>` instance is returned,
containing information about the match: where it starts and ends, the substring
it matched, and more.
You can learn about this by interactively experimenting with the :mod:`re`
module. If you have Tkinter available, you may also want to look at
:source:`Tools/scripts/redemo.py`, a demonstration program included with the
Python distribution. It allows you to enter REs and strings, and displays
whether the RE matches or fails. :file:`redemo.py` can be quite useful when
trying to debug a complicated RE. Phil Schwartz's `Kodos
<http://kodos.sourceforge.net/>`_ is also an interactive tool for developing and
testing RE patterns.
This HOWTO uses the standard Python interpreter for its examples. First, run the
Python interpreter, import the :mod:`re` module, and compile a RE::
Python 2.2.2 (#1, Feb 10 2003, 12:57:01)
>>> import re
>>> p = re.compile('[a-z]+')
>>> p #doctest: +ELLIPSIS
<_sre.SRE_Pattern object at 0x...>
Now, you can try matching various strings against the RE ``[a-z]+``. An empty
string shouldn't match at all, since ``+`` means 'one or more repetitions'.
:meth:`match` should return ``None`` in this case, which will cause the
interpreter to print no output. You can explicitly print the result of
:meth:`match` to make this clear. ::
>>> p.match("")
>>> print p.match("")
None
Now, let's try it on a string that it should match, such as ``tempo``. In this
case, :meth:`match` will return a :ref:`match object <match-objects>`, so you
should store the result in a variable for later use. ::
>>> m = p.match('tempo')
>>> m #doctest: +ELLIPSIS
<_sre.SRE_Match object at 0x...>
Now you can query the :ref:`match object <match-objects>` for information
about the matching string. :ref:`match object <match-objects>` instances
also have several methods and attributes; the most important ones are:
+------------------+--------------------------------------------+
| Method/Attribute | Purpose |
+==================+============================================+
| ``group()`` | Return the string matched by the RE |
+------------------+--------------------------------------------+
| ``start()`` | Return the starting position of the match |
+------------------+--------------------------------------------+
| ``end()`` | Return the ending position of the match |
+------------------+--------------------------------------------+
| ``span()`` | Return a tuple containing the (start, end) |
| | positions of the match |
+------------------+--------------------------------------------+
Trying these methods will soon clarify their meaning::
>>> m.group()
'tempo'
>>> m.start(), m.end()
(0, 5)
>>> m.span()
(0, 5)
:meth:`group` returns the substring that was matched by the RE. :meth:`start`
and :meth:`end` return the starting and ending index of the match. :meth:`span`
returns both start and end indexes in a single tuple. Since the :meth:`match`
method only checks if the RE matches at the start of a string, :meth:`start`
will always be zero. However, the :meth:`search` method of patterns
scans through the string, so the match may not start at zero in that
case. ::
>>> print p.match('::: message')
None
>>> m = p.search('::: message'); print m #doctest: +ELLIPSIS
<_sre.SRE_Match object at 0x...>
>>> m.group()
'message'
>>> m.span()
(4, 11)
In actual programs, the most common style is to store the
:ref:`match object <match-objects>` in a variable, and then check if it was
``None``. This usually looks like::
p = re.compile( ... )
m = p.match( 'string goes here' )
if m:
print 'Match found: ', m.group()
else:
print 'No match'
Two pattern methods return all of the matches for a pattern.
:meth:`findall` returns a list of matching strings::
>>> p = re.compile('\d+')
>>> p.findall('12 drummers drumming, 11 pipers piping, 10 lords a-leaping')
['12', '11', '10']
:meth:`findall` has to create the entire list before it can be returned as the
result. The :meth:`finditer` method returns a sequence of
:ref:`match object <match-objects>` instances as an :term:`iterator`. [#]_ ::
>>> iterator = p.finditer('12 drummers drumming, 11 ... 10 ...')
>>> iterator #doctest: +ELLIPSIS
<callable-iterator object at 0x...>
>>> for match in iterator:
... print match.span()
...
(0, 2)
(22, 24)
(29, 31)
Module-Level Functions
----------------------
You don't have to create a pattern object and call its methods; the
:mod:`re` module also provides top-level functions called :func:`match`,
:func:`search`, :func:`findall`, :func:`sub`, and so forth. These functions
take the same arguments as the corresponding pattern method, with
the RE string added as the first argument, and still return either ``None`` or a
:ref:`match object <match-objects>` instance. ::
>>> print re.match(r'From\s+', 'Fromage amk')
None
>>> re.match(r'From\s+', 'From amk Thu May 14 19:12:10 1998') #doctest: +ELLIPSIS
<_sre.SRE_Match object at 0x...>
Under the hood, these functions simply create a pattern object for you
and call the appropriate method on it. They also store the compiled object in a
cache, so future calls using the same RE are faster.
Should you use these module-level functions, or should you get the
pattern and call its methods yourself? That choice depends on how
frequently the RE will be used, and on your personal coding style. If the RE is
being used at only one point in the code, then the module functions are probably
more convenient. If a program contains a lot of regular expressions, or re-uses
the same ones in several locations, then it might be worthwhile to collect all
the definitions in one place, in a section of code that compiles all the REs
ahead of time. To take an example from the standard library, here's an extract
from the deprecated :mod:`xmllib` module::
ref = re.compile( ... )
entityref = re.compile( ... )
charref = re.compile( ... )
starttagopen = re.compile( ... )
I generally prefer to work with the compiled object, even for one-time uses, but
few people will be as much of a purist about this as I am.
Compilation Flags
-----------------
Compilation flags let you modify some aspects of how regular expressions work.
Flags are available in the :mod:`re` module under two names, a long name such as
:const:`IGNORECASE` and a short, one-letter form such as :const:`I`. (If you're
familiar with Perl's pattern modifiers, the one-letter forms use the same
letters; the short form of :const:`re.VERBOSE` is :const:`re.X`, for example.)
Multiple flags can be specified by bitwise OR-ing them; ``re.I | re.M`` sets
both the :const:`I` and :const:`M` flags, for example.
Here's a table of the available flags, followed by a more detailed explanation
of each one.
+---------------------------------+--------------------------------------------+
| Flag | Meaning |
+=================================+============================================+
| :const:`DOTALL`, :const:`S` | Make ``.`` match any character, including |
| | newlines |
+---------------------------------+--------------------------------------------+
| :const:`IGNORECASE`, :const:`I` | Do case-insensitive matches |
+---------------------------------+--------------------------------------------+
| :const:`LOCALE`, :const:`L` | Do a locale-aware match |
+---------------------------------+--------------------------------------------+
| :const:`MULTILINE`, :const:`M` | Multi-line matching, affecting ``^`` and |
| | ``$`` |
+---------------------------------+--------------------------------------------+
| :const:`VERBOSE`, :const:`X` | Enable verbose REs, which can be organized |
| | more cleanly and understandably. |
+---------------------------------+--------------------------------------------+
| :const:`UNICODE`, :const:`U` | Makes several escapes like ``\w``, ``\b``, |
| | ``\s`` and ``\d`` dependent on the Unicode |
| | character database. |
+---------------------------------+--------------------------------------------+
.. data:: I
IGNORECASE
:noindex:
Perform case-insensitive matching; character class and literal strings will
match letters by ignoring case. For example, ``[A-Z]`` will match lowercase
letters, too, and ``Spam`` will match ``Spam``, ``spam``, or ``spAM``. This
lowercasing doesn't take the current locale into account; it will if you also
set the :const:`LOCALE` flag.
.. data:: L
LOCALE
:noindex:
Make ``\w``, ``\W``, ``\b``, and ``\B``, dependent on the current locale.
Locales are a feature of the C library intended to help in writing programs that
take account of language differences. For example, if you're processing French
text, you'd want to be able to write ``\w+`` to match words, but ``\w`` only
matches the character class ``[A-Za-z]``; it won't match ``'é'`` or ``'ç'``. If
your system is configured properly and a French locale is selected, certain C
functions will tell the program that ``'é'`` should also be considered a letter.
Setting the :const:`LOCALE` flag when compiling a regular expression will cause
the resulting compiled object to use these C functions for ``\w``; this is
slower, but also enables ``\w+`` to match French words as you'd expect.
.. data:: M
MULTILINE
:noindex:
(``^`` and ``$`` haven't been explained yet; they'll be introduced in section
:ref:`more-metacharacters`.)
Usually ``^`` matches only at the beginning of the string, and ``$`` matches
only at the end of the string and immediately before the newline (if any) at the
end of the string. When this flag is specified, ``^`` matches at the beginning
of the string and at the beginning of each line within the string, immediately
following each newline. Similarly, the ``$`` metacharacter matches either at
the end of the string and at the end of each line (immediately preceding each
newline).
.. data:: S
DOTALL
:noindex:
Makes the ``'.'`` special character match any character at all, including a
newline; without this flag, ``'.'`` will match anything *except* a newline.
.. data:: U
UNICODE
:noindex:
Make ``\w``, ``\W``, ``\b``, ``\B``, ``\d``, ``\D``, ``\s`` and ``\S``
dependent on the Unicode character properties database.
.. data:: X
VERBOSE
:noindex:
This flag allows you to write regular expressions that are more readable by
granting you more flexibility in how you can format them. When this flag has
been specified, whitespace within the RE string is ignored, except when the
whitespace is in a character class or preceded by an unescaped backslash; this
lets you organize and indent the RE more clearly. This flag also lets you put
comments within a RE that will be ignored by the engine; comments are marked by
a ``'#'`` that's neither in a character class or preceded by an unescaped
backslash.
For example, here's a RE that uses :const:`re.VERBOSE`; see how much easier it
is to read? ::
charref = re.compile(r"""
&[#] # Start of a numeric entity reference
(
0[0-7]+ # Octal form
| [0-9]+ # Decimal form
| x[0-9a-fA-F]+ # Hexadecimal form
)
; # Trailing semicolon
""", re.VERBOSE)
Without the verbose setting, the RE would look like this::
charref = re.compile("&#(0[0-7]+"
"|[0-9]+"
"|x[0-9a-fA-F]+);")
In the above example, Python's automatic concatenation of string literals has
been used to break up the RE into smaller pieces, but it's still more difficult
to understand than the version using :const:`re.VERBOSE`.
More Pattern Power
==================
So far we've only covered a part of the features of regular expressions. In
this section, we'll cover some new metacharacters, and how to use groups to
retrieve portions of the text that was matched.
.. _more-metacharacters:
More Metacharacters
-------------------
There are some metacharacters that we haven't covered yet. Most of them will be
covered in this section.
Some of the remaining metacharacters to be discussed are :dfn:`zero-width
assertions`. They don't cause the engine to advance through the string;
instead, they consume no characters at all, and simply succeed or fail. For
example, ``\b`` is an assertion that the current position is located at a word
boundary; the position isn't changed by the ``\b`` at all. This means that
zero-width assertions should never be repeated, because if they match once at a
given location, they can obviously be matched an infinite number of times.
``|``
Alternation, or the "or" operator. If A and B are regular expressions,
``A|B`` will match any string that matches either ``A`` or ``B``. ``|`` has very
low precedence in order to make it work reasonably when you're alternating
multi-character strings. ``Crow|Servo`` will match either ``Crow`` or ``Servo``,
not ``Cro``, a ``'w'`` or an ``'S'``, and ``ervo``.
To match a literal ``'|'``, use ``\|``, or enclose it inside a character class,
as in ``[|]``.
``^``
Matches at the beginning of lines. Unless the :const:`MULTILINE` flag has been
set, this will only match at the beginning of the string. In :const:`MULTILINE`
mode, this also matches immediately after each newline within the string.
For example, if you wish to match the word ``From`` only at the beginning of a
line, the RE to use is ``^From``. ::
>>> print re.search('^From', 'From Here to Eternity') #doctest: +ELLIPSIS
<_sre.SRE_Match object at 0x...>
>>> print re.search('^From', 'Reciting From Memory')
None
.. To match a literal \character{\^}, use \regexp{\e\^} or enclose it
.. inside a character class, as in \regexp{[{\e}\^]}.
``$``
Matches at the end of a line, which is defined as either the end of the string,
or any location followed by a newline character. ::
>>> print re.search('}$', '{block}') #doctest: +ELLIPSIS
<_sre.SRE_Match object at 0x...>
>>> print re.search('}$', '{block} ')
None
>>> print re.search('}$', '{block}\n') #doctest: +ELLIPSIS
<_sre.SRE_Match object at 0x...>
To match a literal ``'$'``, use ``\$`` or enclose it inside a character class,
as in ``[$]``.
``\A``
Matches only at the start of the string. When not in :const:`MULTILINE` mode,
``\A`` and ``^`` are effectively the same. In :const:`MULTILINE` mode, they're
different: ``\A`` still matches only at the beginning of the string, but ``^``
may match at any location inside the string that follows a newline character.
``\Z``
Matches only at the end of the string.
``\b``
Word boundary. This is a zero-width assertion that matches only at the
beginning or end of a word. A word is defined as a sequence of alphanumeric
characters, so the end of a word is indicated by whitespace or a
non-alphanumeric character.
The following example matches ``class`` only when it's a complete word; it won't
match when it's contained inside another word. ::
>>> p = re.compile(r'\bclass\b')
>>> print p.search('no class at all') #doctest: +ELLIPSIS
<_sre.SRE_Match object at 0x...>
>>> print p.search('the declassified algorithm')
None
>>> print p.search('one subclass is')
None
There are two subtleties you should remember when using this special sequence.
First, this is the worst collision between Python's string literals and regular
expression sequences. In Python's string literals, ``\b`` is the backspace
character, ASCII value 8. If you're not using raw strings, then Python will
convert the ``\b`` to a backspace, and your RE won't match as you expect it to.
The following example looks the same as our previous RE, but omits the ``'r'``
in front of the RE string. ::
>>> p = re.compile('\bclass\b')
>>> print p.search('no class at all')
None
>>> print p.search('\b' + 'class' + '\b') #doctest: +ELLIPSIS
<_sre.SRE_Match object at 0x...>
Second, inside a character class, where there's no use for this assertion,
``\b`` represents the backspace character, for compatibility with Python's
string literals.
``\B``
Another zero-width assertion, this is the opposite of ``\b``, only matching when
the current position is not at a word boundary.
Grouping
--------
Frequently you need to obtain more information than just whether the RE matched
or not. Regular expressions are often used to dissect strings by writing a RE
divided into several subgroups which match different components of interest.
For example, an RFC-822 header line is divided into a header name and a value,
separated by a ``':'``, like this::
From: author@example.com
User-Agent: Thunderbird 1.5.0.9 (X11/20061227)
MIME-Version: 1.0
To: editor@example.com
This can be handled by writing a regular expression which matches an entire
header line, and has one group which matches the header name, and another group
which matches the header's value.
Groups are marked by the ``'('``, ``')'`` metacharacters. ``'('`` and ``')'``
have much the same meaning as they do in mathematical expressions; they group
together the expressions contained inside them, and you can repeat the contents
of a group with a repeating qualifier, such as ``*``, ``+``, ``?``, or
``{m,n}``. For example, ``(ab)*`` will match zero or more repetitions of
``ab``. ::
>>> p = re.compile('(ab)*')
>>> print p.match('ababababab').span()
(0, 10)
Groups indicated with ``'('``, ``')'`` also capture the starting and ending
index of the text that they match; this can be retrieved by passing an argument
to :meth:`group`, :meth:`start`, :meth:`end`, and :meth:`span`. Groups are
numbered starting with 0. Group 0 is always present; it's the whole RE, so
:ref:`match object <match-objects>` methods all have group 0 as their default
argument. Later we'll see how to express groups that don't capture the span
of text that they match. ::
>>> p = re.compile('(a)b')
>>> m = p.match('ab')
>>> m.group()
'ab'
>>> m.group(0)
'ab'
Subgroups are numbered from left to right, from 1 upward. Groups can be nested;
to determine the number, just count the opening parenthesis characters, going
from left to right. ::
>>> p = re.compile('(a(b)c)d')
>>> m = p.match('abcd')
>>> m.group(0)
'abcd'
>>> m.group(1)
'abc'
>>> m.group(2)
'b'
:meth:`group` can be passed multiple group numbers at a time, in which case it
will return a tuple containing the corresponding values for those groups. ::
>>> m.group(2,1,2)
('b', 'abc', 'b')
The :meth:`groups` method returns a tuple containing the strings for all the
subgroups, from 1 up to however many there are. ::
>>> m.groups()
('abc', 'b')
Backreferences in a pattern allow you to specify that the contents of an earlier
capturing group must also be found at the current location in the string. For
example, ``\1`` will succeed if the exact contents of group 1 can be found at
the current position, and fails otherwise. Remember that Python's string
literals also use a backslash followed by numbers to allow including arbitrary
characters in a string, so be sure to use a raw string when incorporating
backreferences in a RE.
For example, the following RE detects doubled words in a string. ::
>>> p = re.compile(r'\b(\w+)\s+\1\b')
>>> p.search('Paris in the the spring').group()
'the the'
Backreferences like this aren't often useful for just searching through a string
--- there are few text formats which repeat data in this way --- but you'll soon
find out that they're *very* useful when performing string substitutions.
Non-capturing and Named Groups
------------------------------
Elaborate REs may use many groups, both to capture substrings of interest, and
to group and structure the RE itself. In complex REs, it becomes difficult to
keep track of the group numbers. There are two features which help with this
problem. Both of them use a common syntax for regular expression extensions, so
we'll look at that first.
Perl 5 added several additional features to standard regular expressions, and
the Python :mod:`re` module supports most of them. It would have been
difficult to choose new single-keystroke metacharacters or new special sequences
beginning with ``\`` to represent the new features without making Perl's regular
expressions confusingly different from standard REs. If you chose ``&`` as a
new metacharacter, for example, old expressions would be assuming that ``&`` was
a regular character and wouldn't have escaped it by writing ``\&`` or ``[&]``.
The solution chosen by the Perl developers was to use ``(?...)`` as the
extension syntax. ``?`` immediately after a parenthesis was a syntax error
because the ``?`` would have nothing to repeat, so this didn't introduce any
compatibility problems. The characters immediately after the ``?`` indicate
what extension is being used, so ``(?=foo)`` is one thing (a positive lookahead
assertion) and ``(?:foo)`` is something else (a non-capturing group containing
the subexpression ``foo``).
Python adds an extension syntax to Perl's extension syntax. If the first
character after the question mark is a ``P``, you know that it's an extension
that's specific to Python. Currently there are two such extensions:
``(?P<name>...)`` defines a named group, and ``(?P=name)`` is a backreference to
a named group. If future versions of Perl 5 add similar features using a
different syntax, the :mod:`re` module will be changed to support the new
syntax, while preserving the Python-specific syntax for compatibility's sake.
Now that we've looked at the general extension syntax, we can return to the
features that simplify working with groups in complex REs. Since groups are
numbered from left to right and a complex expression may use many groups, it can
become difficult to keep track of the correct numbering. Modifying such a
complex RE is annoying, too: insert a new group near the beginning and you
change the numbers of everything that follows it.
Sometimes you'll want to use a group to collect a part of a regular expression,
but aren't interested in retrieving the group's contents. You can make this fact
explicit by using a non-capturing group: ``(?:...)``, where you can replace the
``...`` with any other regular expression. ::
>>> m = re.match("([abc])+", "abc")
>>> m.groups()
('c',)
>>> m = re.match("(?:[abc])+", "abc")
>>> m.groups()
()
Except for the fact that you can't retrieve the contents of what the group
matched, a non-capturing group behaves exactly the same as a capturing group;
you can put anything inside it, repeat it with a repetition metacharacter such
as ``*``, and nest it within other groups (capturing or non-capturing).
``(?:...)`` is particularly useful when modifying an existing pattern, since you
can add new groups without changing how all the other groups are numbered. It
should be mentioned that there's no performance difference in searching between
capturing and non-capturing groups; neither form is any faster than the other.
A more significant feature is named groups: instead of referring to them by
numbers, groups can be referenced by a name.
The syntax for a named group is one of the Python-specific extensions:
``(?P<name>...)``. *name* is, obviously, the name of the group. Named groups
also behave exactly like capturing groups, and additionally associate a name
with a group. The :ref:`match object <match-objects>` methods that deal with
capturing groups all accept either integers that refer to the group by number
or strings that contain the desired group's name. Named groups are still
given numbers, so you can retrieve information about a group in two ways::
>>> p = re.compile(r'(?P<word>\b\w+\b)')
>>> m = p.search( '(((( Lots of punctuation )))' )
>>> m.group('word')
'Lots'
>>> m.group(1)
'Lots'
Named groups are handy because they let you use easily-remembered names, instead
of having to remember numbers. Here's an example RE from the :mod:`imaplib`
module::
InternalDate = re.compile(r'INTERNALDATE "'
r'(?P<day>[ 123][0-9])-(?P<mon>[A-Z][a-z][a-z])-'
r'(?P<year>[0-9][0-9][0-9][0-9])'
r' (?P<hour>[0-9][0-9]):(?P<min>[0-9][0-9]):(?P<sec>[0-9][0-9])'
r' (?P<zonen>[-+])(?P<zoneh>[0-9][0-9])(?P<zonem>[0-9][0-9])'
r'"')
It's obviously much easier to retrieve ``m.group('zonem')``, instead of having
to remember to retrieve group 9.
The syntax for backreferences in an expression such as ``(...)\1`` refers to the
number of the group. There's naturally a variant that uses the group name
instead of the number. This is another Python extension: ``(?P=name)`` indicates
that the contents of the group called *name* should again be matched at the
current point. The regular expression for finding doubled words,
``\b(\w+)\s+\1\b`` can also be written as ``\b(?P<word>\w+)\s+(?P=word)\b``::
>>> p = re.compile(r'\b(?P<word>\w+)\s+(?P=word)\b')
>>> p.search('Paris in the the spring').group()
'the the'
Lookahead Assertions
--------------------
Another zero-width assertion is the lookahead assertion. Lookahead assertions
are available in both positive and negative form, and look like this:
``(?=...)``
Positive lookahead assertion. This succeeds if the contained regular
expression, represented here by ``...``, successfully matches at the current
location, and fails otherwise. But, once the contained expression has been
tried, the matching engine doesn't advance at all; the rest of the pattern is
tried right where the assertion started.
``(?!...)``
Negative lookahead assertion. This is the opposite of the positive assertion;
it succeeds if the contained expression *doesn't* match at the current position
in the string.
To make this concrete, let's look at a case where a lookahead is useful.
Consider a simple pattern to match a filename and split it apart into a base
name and an extension, separated by a ``.``. For example, in ``news.rc``,
``news`` is the base name, and ``rc`` is the filename's extension.
The pattern to match this is quite simple:
``.*[.].*$``
Notice that the ``.`` needs to be treated specially because it's a
metacharacter; I've put it inside a character class. Also notice the trailing
``$``; this is added to ensure that all the rest of the string must be included
in the extension. This regular expression matches ``foo.bar`` and
``autoexec.bat`` and ``sendmail.cf`` and ``printers.conf``.
Now, consider complicating the problem a bit; what if you want to match
filenames where the extension is not ``bat``? Some incorrect attempts:
``.*[.][^b].*$`` The first attempt above tries to exclude ``bat`` by requiring
that the first character of the extension is not a ``b``. This is wrong,
because the pattern also doesn't match ``foo.bar``.
``.*[.]([^b]..|.[^a].|..[^t])$``
The expression gets messier when you try to patch up the first solution by
requiring one of the following cases to match: the first character of the
extension isn't ``b``; the second character isn't ``a``; or the third character
isn't ``t``. This accepts ``foo.bar`` and rejects ``autoexec.bat``, but it
requires a three-letter extension and won't accept a filename with a two-letter
extension such as ``sendmail.cf``. We'll complicate the pattern again in an
effort to fix it.
``.*[.]([^b].?.?|.[^a]?.?|..?[^t]?)$``
In the third attempt, the second and third letters are all made optional in
order to allow matching extensions shorter than three characters, such as
``sendmail.cf``.
The pattern's getting really complicated now, which makes it hard to read and
understand. Worse, if the problem changes and you want to exclude both ``bat``
and ``exe`` as extensions, the pattern would get even more complicated and
confusing.
A negative lookahead cuts through all this confusion:
``.*[.](?!bat$)[^.]*$`` The negative lookahead means: if the expression ``bat``
doesn't match at this point, try the rest of the pattern; if ``bat$`` does
match, the whole pattern will fail. The trailing ``$`` is required to ensure
that something like ``sample.batch``, where the extension only starts with
``bat``, will be allowed. The ``[^.]*`` makes sure that the pattern works
when there are multiple dots in the filename.
Excluding another filename extension is now easy; simply add it as an
alternative inside the assertion. The following pattern excludes filenames that
end in either ``bat`` or ``exe``:
``.*[.](?!bat$|exe$)[^.]*$``
Modifying Strings
=================
Up to this point, we've simply performed searches against a static string.
Regular expressions are also commonly used to modify strings in various ways,
using the following pattern methods:
+------------------+-----------------------------------------------+
| Method/Attribute | Purpose |
+==================+===============================================+
| ``split()`` | Split the string into a list, splitting it |
| | wherever the RE matches |
+------------------+-----------------------------------------------+
| ``sub()`` | Find all substrings where the RE matches, and |
| | replace them with a different string |
+------------------+-----------------------------------------------+
| ``subn()`` | Does the same thing as :meth:`sub`, but |
| | returns the new string and the number of |
| | replacements |
+------------------+-----------------------------------------------+
Splitting Strings
-----------------
The :meth:`split` method of a pattern splits a string apart
wherever the RE matches, returning a list of the pieces. It's similar to the
:meth:`split` method of strings but provides much more generality in the
delimiters that you can split by; :meth:`split` only supports splitting by
whitespace or by a fixed string. As you'd expect, there's a module-level
:func:`re.split` function, too.
.. method:: .split(string [, maxsplit=0])
:noindex:
Split *string* by the matches of the regular expression. If capturing
parentheses are used in the RE, then their contents will also be returned as
part of the resulting list. If *maxsplit* is nonzero, at most *maxsplit* splits
are performed.
You can limit the number of splits made, by passing a value for *maxsplit*.
When *maxsplit* is nonzero, at most *maxsplit* splits will be made, and the
remainder of the string is returned as the final element of the list. In the
following example, the delimiter is any sequence of non-alphanumeric characters.
::
>>> p = re.compile(r'\W+')
>>> p.split('This is a test, short and sweet, of split().')
['This', 'is', 'a', 'test', 'short', 'and', 'sweet', 'of', 'split', '']
>>> p.split('This is a test, short and sweet, of split().', 3)
['This', 'is', 'a', 'test, short and sweet, of split().']
Sometimes you're not only interested in what the text between delimiters is, but
also need to know what the delimiter was. If capturing parentheses are used in
the RE, then their values are also returned as part of the list. Compare the
following calls::
>>> p = re.compile(r'\W+')
>>> p2 = re.compile(r'(\W+)')
>>> p.split('This... is a test.')
['This', 'is', 'a', 'test', '']
>>> p2.split('This... is a test.')
['This', '... ', 'is', ' ', 'a', ' ', 'test', '.', '']
The module-level function :func:`re.split` adds the RE to be used as the first
argument, but is otherwise the same. ::
>>> re.split('[\W]+', 'Words, words, words.')
['Words', 'words', 'words', '']
>>> re.split('([\W]+)', 'Words, words, words.')
['Words', ', ', 'words', ', ', 'words', '.', '']
>>> re.split('[\W]+', 'Words, words, words.', 1)
['Words', 'words, words.']
Search and Replace
------------------
Another common task is to find all the matches for a pattern, and replace them
with a different string. The :meth:`sub` method takes a replacement value,
which can be either a string or a function, and the string to be processed.
.. method:: .sub(replacement, string[, count=0])
:noindex:
Returns the string obtained by replacing the leftmost non-overlapping
occurrences of the RE in *string* by the replacement *replacement*. If the
pattern isn't found, *string* is returned unchanged.
The optional argument *count* is the maximum number of pattern occurrences to be
replaced; *count* must be a non-negative integer. The default value of 0 means
to replace all occurrences.
Here's a simple example of using the :meth:`sub` method. It replaces colour
names with the word ``colour``::
>>> p = re.compile('(blue|white|red)')
>>> p.sub('colour', 'blue socks and red shoes')
'colour socks and colour shoes'
>>> p.sub('colour', 'blue socks and red shoes', count=1)
'colour socks and red shoes'
The :meth:`subn` method does the same work, but returns a 2-tuple containing the
new string value and the number of replacements that were performed::
>>> p = re.compile('(blue|white|red)')
>>> p.subn('colour', 'blue socks and red shoes')
('colour socks and colour shoes', 2)
>>> p.subn('colour', 'no colours at all')
('no colours at all', 0)
Empty matches are replaced only when they're not adjacent to a previous match.
::
>>> p = re.compile('x*')
>>> p.sub('-', 'abxd')
'-a-b-d-'
If *replacement* is a string, any backslash escapes in it are processed. That
is, ``\n`` is converted to a single newline character, ``\r`` is converted to a
carriage return, and so forth. Unknown escapes such as ``\j`` are left alone.
Backreferences, such as ``\6``, are replaced with the substring matched by the
corresponding group in the RE. This lets you incorporate portions of the
original text in the resulting replacement string.
This example matches the word ``section`` followed by a string enclosed in
``{``, ``}``, and changes ``section`` to ``subsection``::
>>> p = re.compile('section{ ( [^}]* ) }', re.VERBOSE)
>>> p.sub(r'subsection{\1}','section{First} section{second}')
'subsection{First} subsection{second}'
There's also a syntax for referring to named groups as defined by the
``(?P<name>...)`` syntax. ``\g<name>`` will use the substring matched by the
group named ``name``, and ``\g<number>`` uses the corresponding group number.
``\g<2>`` is therefore equivalent to ``\2``, but isn't ambiguous in a
replacement string such as ``\g<2>0``. (``\20`` would be interpreted as a
reference to group 20, not a reference to group 2 followed by the literal
character ``'0'``.) The following substitutions are all equivalent, but use all
three variations of the replacement string. ::
>>> p = re.compile('section{ (?P<name> [^}]* ) }', re.VERBOSE)
>>> p.sub(r'subsection{\1}','section{First}')
'subsection{First}'
>>> p.sub(r'subsection{\g<1>}','section{First}')
'subsection{First}'
>>> p.sub(r'subsection{\g<name>}','section{First}')
'subsection{First}'
*replacement* can also be a function, which gives you even more control. If
*replacement* is a function, the function is called for every non-overlapping
occurrence of *pattern*. On each call, the function is passed a
:ref:`match object <match-objects>` argument for the match and can use this
information to compute the desired replacement string and return it.
In the following example, the replacement function translates decimals into
hexadecimal::
>>> def hexrepl(match):
... "Return the hex string for a decimal number"
... value = int(match.group())
... return hex(value)
...
>>> p = re.compile(r'\d+')
>>> p.sub(hexrepl, 'Call 65490 for printing, 49152 for user code.')
'Call 0xffd2 for printing, 0xc000 for user code.'
When using the module-level :func:`re.sub` function, the pattern is passed as
the first argument. The pattern may be provided as an object or as a string; if
you need to specify regular expression flags, you must either use a
pattern object as the first parameter, or use embedded modifiers in the
pattern string, e.g. ``sub("(?i)b+", "x", "bbbb BBBB")`` returns ``'x x'``.
Common Problems
===============
Regular expressions are a powerful tool for some applications, but in some ways
their behaviour isn't intuitive and at times they don't behave the way you may
expect them to. This section will point out some of the most common pitfalls.
Use String Methods
------------------
Sometimes using the :mod:`re` module is a mistake. If you're matching a fixed
string, or a single character class, and you're not using any :mod:`re` features
such as the :const:`IGNORECASE` flag, then the full power of regular expressions
may not be required. Strings have several methods for performing operations with
fixed strings and they're usually much faster, because the implementation is a
single small C loop that's been optimized for the purpose, instead of the large,
more generalized regular expression engine.
One example might be replacing a single fixed string with another one; for
example, you might replace ``word`` with ``deed``. ``re.sub()`` seems like the
function to use for this, but consider the :meth:`replace` method. Note that
:func:`replace` will also replace ``word`` inside words, turning ``swordfish``
into ``sdeedfish``, but the naive RE ``word`` would have done that, too. (To
avoid performing the substitution on parts of words, the pattern would have to
be ``\bword\b``, in order to require that ``word`` have a word boundary on
either side. This takes the job beyond :meth:`replace`'s abilities.)
Another common task is deleting every occurrence of a single character from a
string or replacing it with another single character. You might do this with
something like ``re.sub('\n', ' ', S)``, but :meth:`translate` is capable of
doing both tasks and will be faster than any regular expression operation can
be.
In short, before turning to the :mod:`re` module, consider whether your problem
can be solved with a faster and simpler string method.
match() versus search()
-----------------------
The :func:`match` function only checks if the RE matches at the beginning of the
string while :func:`search` will scan forward through the string for a match.
It's important to keep this distinction in mind. Remember, :func:`match` will
only report a successful match which will start at 0; if the match wouldn't
start at zero, :func:`match` will *not* report it. ::
>>> print re.match('super', 'superstition').span()
(0, 5)
>>> print re.match('super', 'insuperable')
None
On the other hand, :func:`search` will scan forward through the string,
reporting the first match it finds. ::
>>> print re.search('super', 'superstition').span()
(0, 5)
>>> print re.search('super', 'insuperable').span()
(2, 7)
Sometimes you'll be tempted to keep using :func:`re.match`, and just add ``.*``
to the front of your RE. Resist this temptation and use :func:`re.search`
instead. The regular expression compiler does some analysis of REs in order to
speed up the process of looking for a match. One such analysis figures out what
the first character of a match must be; for example, a pattern starting with
``Crow`` must match starting with a ``'C'``. The analysis lets the engine
quickly scan through the string looking for the starting character, only trying
the full match if a ``'C'`` is found.
Adding ``.*`` defeats this optimization, requiring scanning to the end of the
string and then backtracking to find a match for the rest of the RE. Use
:func:`re.search` instead.
Greedy versus Non-Greedy
------------------------
When repeating a regular expression, as in ``a*``, the resulting action is to
consume as much of the pattern as possible. This fact often bites you when
you're trying to match a pair of balanced delimiters, such as the angle brackets
surrounding an HTML tag. The naive pattern for matching a single HTML tag
doesn't work because of the greedy nature of ``.*``. ::
>>> s = '<html><head><title>Title</title>'
>>> len(s)
32
>>> print re.match('<.*>', s).span()
(0, 32)
>>> print re.match('<.*>', s).group()
<html><head><title>Title</title>
The RE matches the ``'<'`` in ``<html>``, and the ``.*`` consumes the rest of
the string. There's still more left in the RE, though, and the ``>`` can't
match at the end of the string, so the regular expression engine has to
backtrack character by character until it finds a match for the ``>``. The
final match extends from the ``'<'`` in ``<html>`` to the ``'>'`` in
``</title>``, which isn't what you want.
In this case, the solution is to use the non-greedy qualifiers ``*?``, ``+?``,
``??``, or ``{m,n}?``, which match as *little* text as possible. In the above
example, the ``'>'`` is tried immediately after the first ``'<'`` matches, and
when it fails, the engine advances a character at a time, retrying the ``'>'``
at every step. This produces just the right result::
>>> print re.match('<.*?>', s).group()
<html>
(Note that parsing HTML or XML with regular expressions is painful.
Quick-and-dirty patterns will handle common cases, but HTML and XML have special
cases that will break the obvious regular expression; by the time you've written
a regular expression that handles all of the possible cases, the patterns will
be *very* complicated. Use an HTML or XML parser module for such tasks.)
Using re.VERBOSE
--------------------
By now you've probably noticed that regular expressions are a very compact
notation, but they're not terribly readable. REs of moderate complexity can
become lengthy collections of backslashes, parentheses, and metacharacters,
making them difficult to read and understand.
For such REs, specifying the ``re.VERBOSE`` flag when compiling the regular
expression can be helpful, because it allows you to format the regular
expression more clearly.
The ``re.VERBOSE`` flag has several effects. Whitespace in the regular
expression that *isn't* inside a character class is ignored. This means that an
expression such as ``dog | cat`` is equivalent to the less readable ``dog|cat``,
but ``[a b]`` will still match the characters ``'a'``, ``'b'``, or a space. In
addition, you can also put comments inside a RE; comments extend from a ``#``
character to the next newline. When used with triple-quoted strings, this
enables REs to be formatted more neatly::
pat = re.compile(r"""
\s* # Skip leading whitespace
(?P<header>[^:]+) # Header name
\s* : # Whitespace, and a colon
(?P<value>.*?) # The header's value -- *? used to
# lose the following trailing whitespace
\s*$ # Trailing whitespace to end-of-line
""", re.VERBOSE)
This is far more readable than::
pat = re.compile(r"\s*(?P<header>[^:]+)\s*:(?P<value>.*?)\s*$")
Feedback
========
Regular expressions are a complicated topic. Did this document help you
understand them? Were there parts that were unclear, or Problems you
encountered that weren't covered here? If so, please send suggestions for
improvements to the author.
The most complete book on regular expressions is almost certainly Jeffrey
Friedl's Mastering Regular Expressions, published by O'Reilly. Unfortunately,
it exclusively concentrates on Perl and Java's flavours of regular expressions,
and doesn't contain any Python material at all, so it won't be useful as a
reference for programming in Python. (The first edition covered Python's
now-removed :mod:`regex` module, which won't help you much.) Consider checking
it out from your library.
.. rubric:: Footnotes
.. [#] Introduced in Python 2.2.2.
PK %�\��*��O �O # html/_sources/howto/sockets.rst.txtnu �[��� .. _socket-howto:
****************************
Socket Programming HOWTO
****************************
:Author: Gordon McMillan
.. topic:: Abstract
Sockets are used nearly everywhere, but are one of the most severely
misunderstood technologies around. This is a 10,000 foot overview of sockets.
It's not really a tutorial - you'll still have work to do in getting things
operational. It doesn't cover the fine points (and there are a lot of them), but
I hope it will give you enough background to begin using them decently.
Sockets
=======
I'm only going to talk about INET sockets, but they account for at least 99% of
the sockets in use. And I'll only talk about STREAM sockets - unless you really
know what you're doing (in which case this HOWTO isn't for you!), you'll get
better behavior and performance from a STREAM socket than anything else. I will
try to clear up the mystery of what a socket is, as well as some hints on how to
work with blocking and non-blocking sockets. But I'll start by talking about
blocking sockets. You'll need to know how they work before dealing with
non-blocking sockets.
Part of the trouble with understanding these things is that "socket" can mean a
number of subtly different things, depending on context. So first, let's make a
distinction between a "client" socket - an endpoint of a conversation, and a
"server" socket, which is more like a switchboard operator. The client
application (your browser, for example) uses "client" sockets exclusively; the
web server it's talking to uses both "server" sockets and "client" sockets.
History
-------
Of the various forms of :abbr:`IPC (Inter Process Communication)`,
sockets are by far the most popular. On any given platform, there are
likely to be other forms of IPC that are faster, but for
cross-platform communication, sockets are about the only game in town.
They were invented in Berkeley as part of the BSD flavor of Unix. They spread
like wildfire with the Internet. With good reason --- the combination of sockets
with INET makes talking to arbitrary machines around the world unbelievably easy
(at least compared to other schemes).
Creating a Socket
=================
Roughly speaking, when you clicked on the link that brought you to this page,
your browser did something like the following::
#create an INET, STREAMing socket
s = socket.socket(
socket.AF_INET, socket.SOCK_STREAM)
#now connect to the web server on port 80
# - the normal http port
s.connect(("www.mcmillan-inc.com", 80))
When the ``connect`` completes, the socket ``s`` can be used to send
in a request for the text of the page. The same socket will read the
reply, and then be destroyed. That's right, destroyed. Client sockets
are normally only used for one exchange (or a small set of sequential
exchanges).
What happens in the web server is a bit more complex. First, the web server
creates a "server socket"::
#create an INET, STREAMing socket
serversocket = socket.socket(
socket.AF_INET, socket.SOCK_STREAM)
#bind the socket to a public host,
# and a well-known port
serversocket.bind((socket.gethostname(), 80))
#become a server socket
serversocket.listen(5)
A couple things to notice: we used ``socket.gethostname()`` so that the socket
would be visible to the outside world. If we had used ``s.bind(('localhost',
80))`` or ``s.bind(('127.0.0.1', 80))`` we would still have a "server" socket,
but one that was only visible within the same machine. ``s.bind(('', 80))``
specifies that the socket is reachable by any address the machine happens to
have.
A second thing to note: low number ports are usually reserved for "well known"
services (HTTP, SNMP etc). If you're playing around, use a nice high number (4
digits).
Finally, the argument to ``listen`` tells the socket library that we want it to
queue up as many as 5 connect requests (the normal max) before refusing outside
connections. If the rest of the code is written properly, that should be plenty.
Now that we have a "server" socket, listening on port 80, we can enter the
mainloop of the web server::
while 1:
#accept connections from outside
(clientsocket, address) = serversocket.accept()
#now do something with the clientsocket
#in this case, we'll pretend this is a threaded server
ct = client_thread(clientsocket)
ct.run()
There's actually 3 general ways in which this loop could work - dispatching a
thread to handle ``clientsocket``, create a new process to handle
``clientsocket``, or restructure this app to use non-blocking sockets, and
multiplex between our "server" socket and any active ``clientsocket``\ s using
``select``. More about that later. The important thing to understand now is
this: this is *all* a "server" socket does. It doesn't send any data. It doesn't
receive any data. It just produces "client" sockets. Each ``clientsocket`` is
created in response to some *other* "client" socket doing a ``connect()`` to the
host and port we're bound to. As soon as we've created that ``clientsocket``, we
go back to listening for more connections. The two "clients" are free to chat it
up - they are using some dynamically allocated port which will be recycled when
the conversation ends.
IPC
---
If you need fast IPC between two processes on one machine, you should look into
whatever form of shared memory the platform offers. A simple protocol based
around shared memory and locks or semaphores is by far the fastest technique.
If you do decide to use sockets, bind the "server" socket to ``'localhost'``. On
most platforms, this will take a shortcut around a couple of layers of network
code and be quite a bit faster.
Using a Socket
==============
The first thing to note, is that the web browser's "client" socket and the web
server's "client" socket are identical beasts. That is, this is a "peer to peer"
conversation. Or to put it another way, *as the designer, you will have to
decide what the rules of etiquette are for a conversation*. Normally, the
``connect``\ ing socket starts the conversation, by sending in a request, or
perhaps a signon. But that's a design decision - it's not a rule of sockets.
Now there are two sets of verbs to use for communication. You can use ``send``
and ``recv``, or you can transform your client socket into a file-like beast and
use ``read`` and ``write``. The latter is the way Java presents its sockets.
I'm not going to talk about it here, except to warn you that you need to use
``flush`` on sockets. These are buffered "files", and a common mistake is to
``write`` something, and then ``read`` for a reply. Without a ``flush`` in
there, you may wait forever for the reply, because the request may still be in
your output buffer.
Now we come to the major stumbling block of sockets - ``send`` and ``recv`` operate
on the network buffers. They do not necessarily handle all the bytes you hand
them (or expect from them), because their major focus is handling the network
buffers. In general, they return when the associated network buffers have been
filled (``send``) or emptied (``recv``). They then tell you how many bytes they
handled. It is *your* responsibility to call them again until your message has
been completely dealt with.
When a ``recv`` returns 0 bytes, it means the other side has closed (or is in
the process of closing) the connection. You will not receive any more data on
this connection. Ever. You may be able to send data successfully; I'll talk
more about this later.
A protocol like HTTP uses a socket for only one transfer. The client sends a
request, then reads a reply. That's it. The socket is discarded. This means that
a client can detect the end of the reply by receiving 0 bytes.
But if you plan to reuse your socket for further transfers, you need to realize
that *there is no* :abbr:`EOT (End of Transfer)` *on a socket.* I repeat: if a socket
``send`` or ``recv`` returns after handling 0 bytes, the connection has been
broken. If the connection has *not* been broken, you may wait on a ``recv``
forever, because the socket will *not* tell you that there's nothing more to
read (for now). Now if you think about that a bit, you'll come to realize a
fundamental truth of sockets: *messages must either be fixed length* (yuck), *or
be delimited* (shrug), *or indicate how long they are* (much better), *or end by
shutting down the connection*. The choice is entirely yours, (but some ways are
righter than others).
Assuming you don't want to end the connection, the simplest solution is a fixed
length message::
class mysocket:
'''demonstration class only
- coded for clarity, not efficiency
'''
def __init__(self, sock=None):
if sock is None:
self.sock = socket.socket(
socket.AF_INET, socket.SOCK_STREAM)
else:
self.sock = sock
def connect(self, host, port):
self.sock.connect((host, port))
def mysend(self, msg):
totalsent = 0
while totalsent < MSGLEN:
sent = self.sock.send(msg[totalsent:])
if sent == 0:
raise RuntimeError("socket connection broken")
totalsent = totalsent + sent
def myreceive(self):
chunks = []
bytes_recd = 0
while bytes_recd < MSGLEN:
chunk = self.sock.recv(min(MSGLEN - bytes_recd, 2048))
if chunk == '':
raise RuntimeError("socket connection broken")
chunks.append(chunk)
bytes_recd = bytes_recd + len(chunk)
return ''.join(chunks)
The sending code here is usable for almost any messaging scheme - in Python you
send strings, and you can use ``len()`` to determine its length (even if it has
embedded ``\0`` characters). It's mostly the receiving code that gets more
complex. (And in C, it's not much worse, except you can't use ``strlen`` if the
message has embedded ``\0``\ s.)
The easiest enhancement is to make the first character of the message an
indicator of message type, and have the type determine the length. Now you have
two ``recv``\ s - the first to get (at least) that first character so you can
look up the length, and the second in a loop to get the rest. If you decide to
go the delimited route, you'll be receiving in some arbitrary chunk size, (4096
or 8192 is frequently a good match for network buffer sizes), and scanning what
you've received for a delimiter.
One complication to be aware of: if your conversational protocol allows multiple
messages to be sent back to back (without some kind of reply), and you pass
``recv`` an arbitrary chunk size, you may end up reading the start of a
following message. You'll need to put that aside and hold onto it, until it's
needed.
Prefixing the message with its length (say, as 5 numeric characters) gets more
complex, because (believe it or not), you may not get all 5 characters in one
``recv``. In playing around, you'll get away with it; but in high network loads,
your code will very quickly break unless you use two ``recv`` loops - the first
to determine the length, the second to get the data part of the message. Nasty.
This is also when you'll discover that ``send`` does not always manage to get
rid of everything in one pass. And despite having read this, you will eventually
get bit by it!
In the interests of space, building your character, (and preserving my
competitive position), these enhancements are left as an exercise for the
reader. Lets move on to cleaning up.
Binary Data
-----------
It is perfectly possible to send binary data over a socket. The major problem is
that not all machines use the same formats for binary data. For example, a
Motorola chip will represent a 16 bit integer with the value 1 as the two hex
bytes 00 01. Intel and DEC, however, are byte-reversed - that same 1 is 01 00.
Socket libraries have calls for converting 16 and 32 bit integers - ``ntohl,
htonl, ntohs, htons`` where "n" means *network* and "h" means *host*, "s" means
*short* and "l" means *long*. Where network order is host order, these do
nothing, but where the machine is byte-reversed, these swap the bytes around
appropriately.
In these days of 32 bit machines, the ascii representation of binary data is
frequently smaller than the binary representation. That's because a surprising
amount of the time, all those longs have the value 0, or maybe 1. The string "0"
would be two bytes, while binary is four. Of course, this doesn't fit well with
fixed-length messages. Decisions, decisions.
Disconnecting
=============
Strictly speaking, you're supposed to use ``shutdown`` on a socket before you
``close`` it. The ``shutdown`` is an advisory to the socket at the other end.
Depending on the argument you pass it, it can mean "I'm not going to send
anymore, but I'll still listen", or "I'm not listening, good riddance!". Most
socket libraries, however, are so used to programmers neglecting to use this
piece of etiquette that normally a ``close`` is the same as ``shutdown();
close()``. So in most situations, an explicit ``shutdown`` is not needed.
One way to use ``shutdown`` effectively is in an HTTP-like exchange. The client
sends a request and then does a ``shutdown(1)``. This tells the server "This
client is done sending, but can still receive." The server can detect "EOF" by
a receive of 0 bytes. It can assume it has the complete request. The server
sends a reply. If the ``send`` completes successfully then, indeed, the client
was still receiving.
Python takes the automatic shutdown a step further, and says that when a socket
is garbage collected, it will automatically do a ``close`` if it's needed. But
relying on this is a very bad habit. If your socket just disappears without
doing a ``close``, the socket at the other end may hang indefinitely, thinking
you're just being slow. *Please* ``close`` your sockets when you're done.
When Sockets Die
----------------
Probably the worst thing about using blocking sockets is what happens when the
other side comes down hard (without doing a ``close``). Your socket is likely to
hang. SOCKSTREAM is a reliable protocol, and it will wait a long, long time
before giving up on a connection. If you're using threads, the entire thread is
essentially dead. There's not much you can do about it. As long as you aren't
doing something dumb, like holding a lock while doing a blocking read, the
thread isn't really consuming much in the way of resources. Do *not* try to kill
the thread - part of the reason that threads are more efficient than processes
is that they avoid the overhead associated with the automatic recycling of
resources. In other words, if you do manage to kill the thread, your whole
process is likely to be screwed up.
Non-blocking Sockets
====================
If you've understood the preceding, you already know most of what you need to
know about the mechanics of using sockets. You'll still use the same calls, in
much the same ways. It's just that, if you do it right, your app will be almost
inside-out.
In Python, you use ``socket.setblocking(0)`` to make it non-blocking. In C, it's
more complex, (for one thing, you'll need to choose between the BSD flavor
``O_NONBLOCK`` and the almost indistinguishable Posix flavor ``O_NDELAY``, which
is completely different from ``TCP_NODELAY``), but it's the exact same idea. You
do this after creating the socket, but before using it. (Actually, if you're
nuts, you can switch back and forth.)
The major mechanical difference is that ``send``, ``recv``, ``connect`` and
``accept`` can return without having done anything. You have (of course) a
number of choices. You can check return code and error codes and generally drive
yourself crazy. If you don't believe me, try it sometime. Your app will grow
large, buggy and suck CPU. So let's skip the brain-dead solutions and do it
right.
Use ``select``.
In C, coding ``select`` is fairly complex. In Python, it's a piece of cake, but
it's close enough to the C version that if you understand ``select`` in Python,
you'll have little trouble with it in C::
ready_to_read, ready_to_write, in_error = \
select.select(
potential_readers,
potential_writers,
potential_errs,
timeout)
You pass ``select`` three lists: the first contains all sockets that you might
want to try reading; the second all the sockets you might want to try writing
to, and the last (normally left empty) those that you want to check for errors.
You should note that a socket can go into more than one list. The ``select``
call is blocking, but you can give it a timeout. This is generally a sensible
thing to do - give it a nice long timeout (say a minute) unless you have good
reason to do otherwise.
In return, you will get three lists. They contain the sockets that are actually
readable, writable and in error. Each of these lists is a subset (possibly
empty) of the corresponding list you passed in.
If a socket is in the output readable list, you can be
as-close-to-certain-as-we-ever-get-in-this-business that a ``recv`` on that
socket will return *something*. Same idea for the writable list. You'll be able
to send *something*. Maybe not all you want to, but *something* is better than
nothing. (Actually, any reasonably healthy socket will return as writable - it
just means outbound network buffer space is available.)
If you have a "server" socket, put it in the potential_readers list. If it comes
out in the readable list, your ``accept`` will (almost certainly) work. If you
have created a new socket to ``connect`` to someone else, put it in the
potential_writers list. If it shows up in the writable list, you have a decent
chance that it has connected.
One very nasty problem with ``select``: if somewhere in those input lists of
sockets is one which has died a nasty death, the ``select`` will fail. You then
need to loop through every single damn socket in all those lists and do a
``select([sock],[],[],0)`` until you find the bad one. That timeout of 0 means
it won't take long, but it's ugly.
Actually, ``select`` can be handy even with blocking sockets. It's one way of
determining whether you will block - the socket returns as readable when there's
something in the buffers. However, this still doesn't help with the problem of
determining whether the other end is done, or just busy with something else.
**Portability alert**: On Unix, ``select`` works both with the sockets and
files. Don't try this on Windows. On Windows, ``select`` works with sockets
only. Also note that in C, many of the more advanced socket options are done
differently on Windows. In fact, on Windows I usually use threads (which work
very, very well) with my sockets. Face it, if you want any kind of performance,
your code will look very different on Windows than on Unix.
Performance
-----------
There's no question that the fastest sockets code uses non-blocking sockets and
select to multiplex them. You can put together something that will saturate a
LAN connection without putting any strain on the CPU. The trouble is that an app
written this way can't do much of anything else - it needs to be ready to
shuffle bytes around at all times.
Assuming that your app is actually supposed to do something more than that,
threading is the optimal solution, (and using non-blocking sockets will be
faster than using blocking sockets). Unfortunately, threading support in Unixes
varies both in API and quality. So the normal Unix solution is to fork a
subprocess to deal with each connection. The overhead for this is significant
(and don't do this on Windows - the overhead of process creation is enormous
there). It also means that unless each subprocess is completely independent,
you'll need to use another form of IPC, say a pipe, or shared memory and
semaphores, to communicate between the parent and child processes.
Finally, remember that even though blocking sockets are somewhat slower than
non-blocking, in many cases they are the "right" solution. After all, if your
app is driven by the data it receives over a socket, there's not much sense in
complicating the logic just so your app can wait on ``select`` instead of
``recv``.
PK %�\�X20 20 # html/_sources/howto/sorting.rst.txtnu �[��� .. _sortinghowto:
Sorting HOW TO
**************
:Author: Andrew Dalke and Raymond Hettinger
:Release: 0.1
Python lists have a built-in :meth:`list.sort` method that modifies the list
in-place. There is also a :func:`sorted` built-in function that builds a new
sorted list from an iterable.
In this document, we explore the various techniques for sorting data using Python.
Sorting Basics
==============
A simple ascending sort is very easy: just call the :func:`sorted` function. It
returns a new sorted list::
>>> sorted([5, 2, 3, 1, 4])
[1, 2, 3, 4, 5]
You can also use the :meth:`list.sort` method of a list. It modifies the list
in-place (and returns ``None`` to avoid confusion). Usually it's less convenient
than :func:`sorted` - but if you don't need the original list, it's slightly
more efficient.
>>> a = [5, 2, 3, 1, 4]
>>> a.sort()
>>> a
[1, 2, 3, 4, 5]
Another difference is that the :meth:`list.sort` method is only defined for
lists. In contrast, the :func:`sorted` function accepts any iterable.
>>> sorted({1: 'D', 2: 'B', 3: 'B', 4: 'E', 5: 'A'})
[1, 2, 3, 4, 5]
Key Functions
=============
Starting with Python 2.4, both :meth:`list.sort` and :func:`sorted` added a
*key* parameter to specify a function to be called on each list element prior to
making comparisons.
For example, here's a case-insensitive string comparison:
>>> sorted("This is a test string from Andrew".split(), key=str.lower)
['a', 'Andrew', 'from', 'is', 'string', 'test', 'This']
The value of the *key* parameter should be a function that takes a single argument
and returns a key to use for sorting purposes. This technique is fast because
the key function is called exactly once for each input record.
A common pattern is to sort complex objects using some of the object's indices
as keys. For example:
>>> student_tuples = [
... ('john', 'A', 15),
... ('jane', 'B', 12),
... ('dave', 'B', 10),
... ]
>>> sorted(student_tuples, key=lambda student: student[2]) # sort by age
[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]
The same technique works for objects with named attributes. For example:
>>> class Student:
... def __init__(self, name, grade, age):
... self.name = name
... self.grade = grade
... self.age = age
... def __repr__(self):
... return repr((self.name, self.grade, self.age))
>>> student_objects = [
... Student('john', 'A', 15),
... Student('jane', 'B', 12),
... Student('dave', 'B', 10),
... ]
>>> sorted(student_objects, key=lambda student: student.age) # sort by age
[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]
Operator Module Functions
=========================
The key-function patterns shown above are very common, so Python provides
convenience functions to make accessor functions easier and faster. The operator
module has :func:`operator.itemgetter`, :func:`operator.attrgetter`, and
starting in Python 2.5 an :func:`operator.methodcaller` function.
Using those functions, the above examples become simpler and faster:
>>> from operator import itemgetter, attrgetter
>>> sorted(student_tuples, key=itemgetter(2))
[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]
>>> sorted(student_objects, key=attrgetter('age'))
[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]
The operator module functions allow multiple levels of sorting. For example, to
sort by *grade* then by *age*:
>>> sorted(student_tuples, key=itemgetter(1,2))
[('john', 'A', 15), ('dave', 'B', 10), ('jane', 'B', 12)]
>>> sorted(student_objects, key=attrgetter('grade', 'age'))
[('john', 'A', 15), ('dave', 'B', 10), ('jane', 'B', 12)]
The :func:`operator.methodcaller` function makes method calls with fixed
parameters for each object being sorted. For example, the :meth:`str.count`
method could be used to compute message priority by counting the
number of exclamation marks in a message:
>>> from operator import methodcaller
>>> messages = ['critical!!!', 'hurry!', 'standby', 'immediate!!']
>>> sorted(messages, key=methodcaller('count', '!'))
['standby', 'hurry!', 'immediate!!', 'critical!!!']
Ascending and Descending
========================
Both :meth:`list.sort` and :func:`sorted` accept a *reverse* parameter with a
boolean value. This is used to flag descending sorts. For example, to get the
student data in reverse *age* order:
>>> sorted(student_tuples, key=itemgetter(2), reverse=True)
[('john', 'A', 15), ('jane', 'B', 12), ('dave', 'B', 10)]
>>> sorted(student_objects, key=attrgetter('age'), reverse=True)
[('john', 'A', 15), ('jane', 'B', 12), ('dave', 'B', 10)]
Sort Stability and Complex Sorts
================================
Starting with Python 2.2, sorts are guaranteed to be `stable
<https://en.wikipedia.org/wiki/Sorting_algorithm#Stability>`_\. That means that
when multiple records have the same key, their original order is preserved.
>>> data = [('red', 1), ('blue', 1), ('red', 2), ('blue', 2)]
>>> sorted(data, key=itemgetter(0))
[('blue', 1), ('blue', 2), ('red', 1), ('red', 2)]
Notice how the two records for *blue* retain their original order so that
``('blue', 1)`` is guaranteed to precede ``('blue', 2)``.
This wonderful property lets you build complex sorts in a series of sorting
steps. For example, to sort the student data by descending *grade* and then
ascending *age*, do the *age* sort first and then sort again using *grade*:
>>> s = sorted(student_objects, key=attrgetter('age')) # sort on secondary key
>>> sorted(s, key=attrgetter('grade'), reverse=True) # now sort on primary key, descending
[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]
The `Timsort <https://en.wikipedia.org/wiki/Timsort>`_ algorithm used in Python
does multiple sorts efficiently because it can take advantage of any ordering
already present in a dataset.
The Old Way Using Decorate-Sort-Undecorate
==========================================
This idiom is called Decorate-Sort-Undecorate after its three steps:
* First, the initial list is decorated with new values that control the sort order.
* Second, the decorated list is sorted.
* Finally, the decorations are removed, creating a list that contains only the
initial values in the new order.
For example, to sort the student data by *grade* using the DSU approach:
>>> decorated = [(student.grade, i, student) for i, student in enumerate(student_objects)]
>>> decorated.sort()
>>> [student for grade, i, student in decorated] # undecorate
[('john', 'A', 15), ('jane', 'B', 12), ('dave', 'B', 10)]
This idiom works because tuples are compared lexicographically; the first items
are compared; if they are the same then the second items are compared, and so
on.
It is not strictly necessary in all cases to include the index *i* in the
decorated list, but including it gives two benefits:
* The sort is stable -- if two items have the same key, their order will be
preserved in the sorted list.
* The original items do not have to be comparable because the ordering of the
decorated tuples will be determined by at most the first two items. So for
example the original list could contain complex numbers which cannot be sorted
directly.
Another name for this idiom is
`Schwartzian transform <https://en.wikipedia.org/wiki/Schwartzian_transform>`_\,
after Randal L. Schwartz, who popularized it among Perl programmers.
For large lists and lists where the comparison information is expensive to
calculate, and Python versions before 2.4, DSU is likely to be the fastest way
to sort the list. For 2.4 and later, key functions provide the same
functionality.
The Old Way Using the *cmp* Parameter
=====================================
Many constructs given in this HOWTO assume Python 2.4 or later. Before that,
there was no :func:`sorted` builtin and :meth:`list.sort` took no keyword
arguments. Instead, all of the Py2.x versions supported a *cmp* parameter to
handle user specified comparison functions.
In Python 3, the *cmp* parameter was removed entirely (as part of a larger effort to
simplify and unify the language, eliminating the conflict between rich
comparisons and the :meth:`__cmp__` magic method).
In Python 2, :meth:`~list.sort` allowed an optional function which can be called for doing the
comparisons. That function should take two arguments to be compared and then
return a negative value for less-than, return zero if they are equal, or return
a positive value for greater-than. For example, we can do:
>>> def numeric_compare(x, y):
... return x - y
>>> sorted([5, 2, 4, 1, 3], cmp=numeric_compare) # doctest: +SKIP
[1, 2, 3, 4, 5]
Or you can reverse the order of comparison with:
>>> def reverse_numeric(x, y):
... return y - x
>>> sorted([5, 2, 4, 1, 3], cmp=reverse_numeric) # doctest: +SKIP
[5, 4, 3, 2, 1]
When porting code from Python 2.x to 3.x, the situation can arise when you have
the user supplying a comparison function and you need to convert that to a key
function. The following wrapper makes that easy to do::
def cmp_to_key(mycmp):
'Convert a cmp= function into a key= function'
class K(object):
def __init__(self, obj, *args):
self.obj = obj
def __lt__(self, other):
return mycmp(self.obj, other.obj) < 0
def __gt__(self, other):
return mycmp(self.obj, other.obj) > 0
def __eq__(self, other):
return mycmp(self.obj, other.obj) == 0
def __le__(self, other):
return mycmp(self.obj, other.obj) <= 0
def __ge__(self, other):
return mycmp(self.obj, other.obj) >= 0
def __ne__(self, other):
return mycmp(self.obj, other.obj) != 0
return K
To convert to a key function, just wrap the old comparison function:
.. testsetup::
from functools import cmp_to_key
.. doctest::
>>> sorted([5, 2, 4, 1, 3], key=cmp_to_key(reverse_numeric))
[5, 4, 3, 2, 1]
In Python 2.7, the :func:`functools.cmp_to_key` function was added to the
functools module.
Odd and Ends
============
* For locale aware sorting, use :func:`locale.strxfrm` for a key function or
:func:`locale.strcoll` for a comparison function.
* The *reverse* parameter still maintains sort stability (so that records with
equal keys retain their original order). Interestingly, that effect can be
simulated without the parameter by using the builtin :func:`reversed` function
twice:
>>> data = [('red', 1), ('blue', 1), ('red', 2), ('blue', 2)]
>>> standard_way = sorted(data, key=itemgetter(0), reverse=True)
>>> double_reversed = list(reversed(sorted(reversed(data), key=itemgetter(0))))
>>> assert standard_way == double_reversed
>>> standard_way
[('red', 1), ('red', 2), ('blue', 1), ('blue', 2)]
* To create a standard sort order for a class, just add the appropriate rich
comparison methods:
>>> Student.__eq__ = lambda self, other: self.age == other.age
>>> Student.__ne__ = lambda self, other: self.age != other.age
>>> Student.__lt__ = lambda self, other: self.age < other.age
>>> Student.__le__ = lambda self, other: self.age <= other.age
>>> Student.__gt__ = lambda self, other: self.age > other.age
>>> Student.__ge__ = lambda self, other: self.age >= other.age
>>> sorted(student_objects)
[('dave', 'B', 10), ('jane', 'B', 12), ('john', 'A', 15)]
For general purpose comparisons, the recommended approach is to define all six
rich comparison operators. The :func:`functools.total_ordering` class
decorator makes this easy to implement.
* Key functions need not depend directly on the objects being sorted. A key
function can also access external resources. For instance, if the student grades
are stored in a dictionary, they can be used to sort a separate list of student
names:
>>> students = ['dave', 'john', 'jane']
>>> grades = {'john': 'F', 'jane':'A', 'dave': 'C'}
>>> sorted(students, key=grades.__getitem__)
['jane', 'dave', 'john']
PK %�\�x'�� �� # html/_sources/howto/unicode.rst.txtnu �[��� *****************
Unicode HOWTO
*****************
:Release: 1.03
This HOWTO discusses Python 2.x's support for Unicode, and explains
various problems that people commonly encounter when trying to work
with Unicode. For the Python 3 version, see
<https://docs.python.org/3/howto/unicode.html>.
Introduction to Unicode
=======================
History of Character Codes
--------------------------
In 1968, the American Standard Code for Information Interchange, better known by
its acronym ASCII, was standardized. ASCII defined numeric codes for various
characters, with the numeric values running from 0 to
127. For example, the lowercase letter 'a' is assigned 97 as its code
value.
ASCII was an American-developed standard, so it only defined unaccented
characters. There was an 'e', but no 'é' or 'Í'. This meant that languages
which required accented characters couldn't be faithfully represented in ASCII.
(Actually the missing accents matter for English, too, which contains words such
as 'naïve' and 'café', and some publications have house styles which require
spellings such as 'coöperate'.)
For a while people just wrote programs that didn't display accents. I remember
looking at Apple ][ BASIC programs, published in French-language publications in
the mid-1980s, that had lines like these::
PRINT "MISE A JOUR TERMINEE"
PRINT "PARAMETRES ENREGISTRES"
Those messages should contain accents, and they just look wrong to someone who
can read French.
In the 1980s, almost all personal computers were 8-bit, meaning that bytes could
hold values ranging from 0 to 255. ASCII codes only went up to 127, so some
machines assigned values between 128 and 255 to accented characters. Different
machines had different codes, however, which led to problems exchanging files.
Eventually various commonly used sets of values for the 128--255 range emerged.
Some were true standards, defined by the International Organization for
Standardization, and some were *de facto* conventions that were invented by one
company or another and managed to catch on.
255 characters aren't very many. For example, you can't fit both the accented
characters used in Western Europe and the Cyrillic alphabet used for Russian
into the 128--255 range because there are more than 128 such characters.
You could write files using different codes (all your Russian files in a coding
system called KOI8, all your French files in a different coding system called
Latin1), but what if you wanted to write a French document that quotes some
Russian text? In the 1980s people began to want to solve this problem, and the
Unicode standardization effort began.
Unicode started out using 16-bit characters instead of 8-bit characters. 16
bits means you have 2^16 = 65,536 distinct values available, making it possible
to represent many different characters from many different alphabets; an initial
goal was to have Unicode contain the alphabets for every single human language.
It turns out that even 16 bits isn't enough to meet that goal, and the modern
Unicode specification uses a wider range of codes, 0--1,114,111 (0x10ffff in
base-16).
There's a related ISO standard, ISO 10646. Unicode and ISO 10646 were
originally separate efforts, but the specifications were merged with the 1.1
revision of Unicode.
(This discussion of Unicode's history is highly simplified. I don't think the
average Python programmer needs to worry about the historical details; consult
the Unicode consortium site listed in the References for more information.)
Definitions
-----------
A **character** is the smallest possible component of a text. 'A', 'B', 'C',
etc., are all different characters. So are 'È' and 'Í'. Characters are
abstractions, and vary depending on the language or context you're talking
about. For example, the symbol for ohms (Ω) is usually drawn much like the
capital letter omega (Ω) in the Greek alphabet (they may even be the same in
some fonts), but these are two different characters that have different
meanings.
The Unicode standard describes how characters are represented by **code
points**. A code point is an integer value, usually denoted in base 16. In the
standard, a code point is written using the notation U+12ca to mean the
character with value 0x12ca (4810 decimal). The Unicode standard contains a lot
of tables listing characters and their corresponding code points::
0061 'a'; LATIN SMALL LETTER A
0062 'b'; LATIN SMALL LETTER B
0063 'c'; LATIN SMALL LETTER C
...
007B '{'; LEFT CURLY BRACKET
Strictly, these definitions imply that it's meaningless to say 'this is
character U+12ca'. U+12ca is a code point, which represents some particular
character; in this case, it represents the character 'ETHIOPIC SYLLABLE WI'. In
informal contexts, this distinction between code points and characters will
sometimes be forgotten.
A character is represented on a screen or on paper by a set of graphical
elements that's called a **glyph**. The glyph for an uppercase A, for example,
is two diagonal strokes and a horizontal stroke, though the exact details will
depend on the font being used. Most Python code doesn't need to worry about
glyphs; figuring out the correct glyph to display is generally the job of a GUI
toolkit or a terminal's font renderer.
Encodings
---------
To summarize the previous section: a Unicode string is a sequence of code
points, which are numbers from 0 to 0x10ffff. This sequence needs to be
represented as a set of bytes (meaning, values from 0--255) in memory. The rules
for translating a Unicode string into a sequence of bytes are called an
**encoding**.
The first encoding you might think of is an array of 32-bit integers. In this
representation, the string "Python" would look like this::
P y t h o n
0x50 00 00 00 79 00 00 00 74 00 00 00 68 00 00 00 6f 00 00 00 6e 00 00 00
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
This representation is straightforward but using it presents a number of
problems.
1. It's not portable; different processors order the bytes differently.
2. It's very wasteful of space. In most texts, the majority of the code points
are less than 127, or less than 255, so a lot of space is occupied by zero
bytes. The above string takes 24 bytes compared to the 6 bytes needed for an
ASCII representation. Increased RAM usage doesn't matter too much (desktop
computers have megabytes of RAM, and strings aren't usually that large), but
expanding our usage of disk and network bandwidth by a factor of 4 is
intolerable.
3. It's not compatible with existing C functions such as ``strlen()``, so a new
family of wide string functions would need to be used.
4. Many Internet standards are defined in terms of textual data, and can't
handle content with embedded zero bytes.
Generally people don't use this encoding, instead choosing other
encodings that are more efficient and convenient. UTF-8 is probably
the most commonly supported encoding; it will be discussed below.
Encodings don't have to handle every possible Unicode character, and most
encodings don't. For example, Python's default encoding is the 'ascii'
encoding. The rules for converting a Unicode string into the ASCII encoding are
simple; for each code point:
1. If the code point is < 128, each byte is the same as the value of the code
point.
2. If the code point is 128 or greater, the Unicode string can't be represented
in this encoding. (Python raises a :exc:`UnicodeEncodeError` exception in this
case.)
Latin-1, also known as ISO-8859-1, is a similar encoding. Unicode code points
0--255 are identical to the Latin-1 values, so converting to this encoding simply
requires converting code points to byte values; if a code point larger than 255
is encountered, the string can't be encoded into Latin-1.
Encodings don't have to be simple one-to-one mappings like Latin-1. Consider
IBM's EBCDIC, which was used on IBM mainframes. Letter values weren't in one
block: 'a' through 'i' had values from 129 to 137, but 'j' through 'r' were 145
through 153. If you wanted to use EBCDIC as an encoding, you'd probably use
some sort of lookup table to perform the conversion, but this is largely an
internal detail.
UTF-8 is one of the most commonly used encodings. UTF stands for "Unicode
Transformation Format", and the '8' means that 8-bit numbers are used in the
encoding. (There's also a UTF-16 encoding, but it's less frequently used than
UTF-8.) UTF-8 uses the following rules:
1. If the code point is <128, it's represented by the corresponding byte value.
2. If the code point is between 128 and 0x7ff, it's turned into two byte values
between 128 and 255.
3. Code points >0x7ff are turned into three- or four-byte sequences, where each
byte of the sequence is between 128 and 255.
UTF-8 has several convenient properties:
1. It can handle any Unicode code point.
2. A Unicode string is turned into a string of bytes containing no embedded zero
bytes. This avoids byte-ordering issues, and means UTF-8 strings can be
processed by C functions such as ``strcpy()`` and sent through protocols that
can't handle zero bytes.
3. A string of ASCII text is also valid UTF-8 text.
4. UTF-8 is fairly compact; the majority of code points are turned into two
bytes, and values less than 128 occupy only a single byte.
5. If bytes are corrupted or lost, it's possible to determine the start of the
next UTF-8-encoded code point and resynchronize. It's also unlikely that
random 8-bit data will look like valid UTF-8.
References
----------
The Unicode Consortium site at <http://www.unicode.org> has character charts, a
glossary, and PDF versions of the Unicode specification. Be prepared for some
difficult reading. <http://www.unicode.org/history/> is a chronology of the
origin and development of Unicode.
To help understand the standard, Jukka Korpela has written an introductory guide
to reading the Unicode character tables, available at
<https://www.cs.tut.fi/~jkorpela/unicode/guide.html>.
Another good introductory article was written by Joel Spolsky
<http://www.joelonsoftware.com/articles/Unicode.html>.
If this introduction didn't make things clear to you, you should try reading this
alternate article before continuing.
.. Jason Orendorff XXX http://www.jorendorff.com/articles/unicode/ is broken
Wikipedia entries are often helpful; see the entries for "character encoding"
<http://en.wikipedia.org/wiki/Character_encoding> and UTF-8
<http://en.wikipedia.org/wiki/UTF-8>, for example.
Python 2.x's Unicode Support
============================
Now that you've learned the rudiments of Unicode, we can look at Python's
Unicode features.
The Unicode Type
----------------
Unicode strings are expressed as instances of the :class:`unicode` type, one of
Python's repertoire of built-in types. It derives from an abstract type called
:class:`basestring`, which is also an ancestor of the :class:`str` type; you can
therefore check if a value is a string type with ``isinstance(value,
basestring)``. Under the hood, Python represents Unicode strings as either 16-
or 32-bit integers, depending on how the Python interpreter was compiled.
The :func:`unicode` constructor has the signature ``unicode(string[, encoding,
errors])``. All of its arguments should be 8-bit strings. The first argument
is converted to Unicode using the specified encoding; if you leave off the
``encoding`` argument, the ASCII encoding is used for the conversion, so
characters greater than 127 will be treated as errors::
>>> unicode('abcdef')
u'abcdef'
>>> s = unicode('abcdef')
>>> type(s)
<type 'unicode'>
>>> unicode('abcdef' + chr(255)) #doctest: +NORMALIZE_WHITESPACE
Traceback (most recent call last):
...
UnicodeDecodeError: 'ascii' codec can't decode byte 0xff in position 6:
ordinal not in range(128)
The ``errors`` argument specifies the response when the input string can't be
converted according to the encoding's rules. Legal values for this argument are
'strict' (raise a ``UnicodeDecodeError`` exception), 'replace' (add U+FFFD,
'REPLACEMENT CHARACTER'), or 'ignore' (just leave the character out of the
Unicode result). The following examples show the differences::
>>> unicode('\x80abc', errors='strict') #doctest: +NORMALIZE_WHITESPACE
Traceback (most recent call last):
...
UnicodeDecodeError: 'ascii' codec can't decode byte 0x80 in position 0:
ordinal not in range(128)
>>> unicode('\x80abc', errors='replace')
u'\ufffdabc'
>>> unicode('\x80abc', errors='ignore')
u'abc'
Encodings are specified as strings containing the encoding's name. Python 2.7
comes with roughly 100 different encodings; see the Python Library Reference at
:ref:`standard-encodings` for a list. Some encodings
have multiple names; for example, 'latin-1', 'iso_8859_1' and '8859' are all
synonyms for the same encoding.
One-character Unicode strings can also be created with the :func:`unichr`
built-in function, which takes integers and returns a Unicode string of length 1
that contains the corresponding code point. The reverse operation is the
built-in :func:`ord` function that takes a one-character Unicode string and
returns the code point value::
>>> unichr(40960)
u'\ua000'
>>> ord(u'\ua000')
40960
Instances of the :class:`unicode` type have many of the same methods as the
8-bit string type for operations such as searching and formatting::
>>> s = u'Was ever feather so lightly blown to and fro as this multitude?'
>>> s.count('e')
5
>>> s.find('feather')
9
>>> s.find('bird')
-1
>>> s.replace('feather', 'sand')
u'Was ever sand so lightly blown to and fro as this multitude?'
>>> s.upper()
u'WAS EVER FEATHER SO LIGHTLY BLOWN TO AND FRO AS THIS MULTITUDE?'
Note that the arguments to these methods can be Unicode strings or 8-bit
strings. 8-bit strings will be converted to Unicode before carrying out the
operation; Python's default ASCII encoding will be used, so characters greater
than 127 will cause an exception::
>>> s.find('Was\x9f') #doctest: +NORMALIZE_WHITESPACE
Traceback (most recent call last):
...
UnicodeDecodeError: 'ascii' codec can't decode byte 0x9f in position 3:
ordinal not in range(128)
>>> s.find(u'Was\x9f')
-1
Much Python code that operates on strings will therefore work with Unicode
strings without requiring any changes to the code. (Input and output code needs
more updating for Unicode; more on this later.)
Another important method is ``.encode([encoding], [errors='strict'])``, which
returns an 8-bit string version of the Unicode string, encoded in the requested
encoding. The ``errors`` parameter is the same as the parameter of the
``unicode()`` constructor, with one additional possibility; as well as 'strict',
'ignore', and 'replace', you can also pass 'xmlcharrefreplace' which uses XML's
character references. The following example shows the different results::
>>> u = unichr(40960) + u'abcd' + unichr(1972)
>>> u.encode('utf-8')
'\xea\x80\x80abcd\xde\xb4'
>>> u.encode('ascii') #doctest: +NORMALIZE_WHITESPACE
Traceback (most recent call last):
...
UnicodeEncodeError: 'ascii' codec can't encode character u'\ua000' in
position 0: ordinal not in range(128)
>>> u.encode('ascii', 'ignore')
'abcd'
>>> u.encode('ascii', 'replace')
'?abcd?'
>>> u.encode('ascii', 'xmlcharrefreplace')
'ꀀabcd޴'
Python's 8-bit strings have a ``.decode([encoding], [errors])`` method that
interprets the string using the given encoding::
>>> u = unichr(40960) + u'abcd' + unichr(1972) # Assemble a string
>>> utf8_version = u.encode('utf-8') # Encode as UTF-8
>>> type(utf8_version), utf8_version
(<type 'str'>, '\xea\x80\x80abcd\xde\xb4')
>>> u2 = utf8_version.decode('utf-8') # Decode using UTF-8
>>> u == u2 # The two strings match
True
The low-level routines for registering and accessing the available encodings are
found in the :mod:`codecs` module. However, the encoding and decoding functions
returned by this module are usually more low-level than is comfortable, so I'm
not going to describe the :mod:`codecs` module here. If you need to implement a
completely new encoding, you'll need to learn about the :mod:`codecs` module
interfaces, but implementing encodings is a specialized task that also won't be
covered here. Consult the Python documentation to learn more about this module.
The most commonly used part of the :mod:`codecs` module is the
:func:`codecs.open` function which will be discussed in the section on input and
output.
Unicode Literals in Python Source Code
--------------------------------------
In Python source code, Unicode literals are written as strings prefixed with the
'u' or 'U' character: ``u'abcdefghijk'``. Specific code points can be written
using the ``\u`` escape sequence, which is followed by four hex digits giving
the code point. The ``\U`` escape sequence is similar, but expects 8 hex
digits, not 4.
Unicode literals can also use the same escape sequences as 8-bit strings,
including ``\x``, but ``\x`` only takes two hex digits so it can't express an
arbitrary code point. Octal escapes can go up to U+01ff, which is octal 777.
::
>>> s = u"a\xac\u1234\u20ac\U00008000"
... # ^^^^ two-digit hex escape
... # ^^^^^^ four-digit Unicode escape
... # ^^^^^^^^^^ eight-digit Unicode escape
>>> for c in s: print ord(c),
...
97 172 4660 8364 32768
Using escape sequences for code points greater than 127 is fine in small doses,
but becomes an annoyance if you're using many accented characters, as you would
in a program with messages in French or some other accent-using language. You
can also assemble strings using the :func:`unichr` built-in function, but this is
even more tedious.
Ideally, you'd want to be able to write literals in your language's natural
encoding. You could then edit Python source code with your favorite editor
which would display the accented characters naturally, and have the right
characters used at runtime.
Python supports writing Unicode literals in any encoding, but you have to
declare the encoding being used. This is done by including a special comment as
either the first or second line of the source file::
#!/usr/bin/env python
# -*- coding: latin-1 -*-
u = u'abcdé'
print ord(u[-1])
The syntax is inspired by Emacs's notation for specifying variables local to a
file. Emacs supports many different variables, but Python only supports
'coding'. The ``-*-`` symbols indicate to Emacs that the comment is special;
they have no significance to Python but are a convention. Python looks for
``coding: name`` or ``coding=name`` in the comment.
If you don't include such a comment, the default encoding used will be ASCII.
Versions of Python before 2.4 were Euro-centric and assumed Latin-1 as a default
encoding for string literals; in Python 2.4, characters greater than 127 still
work but result in a warning. For example, the following program has no
encoding declaration::
#!/usr/bin/env python
u = u'abcdé'
print ord(u[-1])
When you run it with Python 2.4, it will output the following warning::
amk:~$ python2.4 p263.py
sys:1: DeprecationWarning: Non-ASCII character '\xe9'
in file p263.py on line 2, but no encoding declared;
see https://www.python.org/peps/pep-0263.html for details
Python 2.5 and higher are stricter and will produce a syntax error::
amk:~$ python2.5 p263.py
File "/tmp/p263.py", line 2
SyntaxError: Non-ASCII character '\xc3' in file /tmp/p263.py
on line 2, but no encoding declared; see
https://www.python.org/peps/pep-0263.html for details
Unicode Properties
------------------
The Unicode specification includes a database of information about code points.
For each code point that's defined, the information includes the character's
name, its category, the numeric value if applicable (Unicode has characters
representing the Roman numerals and fractions such as one-third and
four-fifths). There are also properties related to the code point's use in
bidirectional text and other display-related properties.
The following program displays some information about several characters, and
prints the numeric value of one particular character::
import unicodedata
u = unichr(233) + unichr(0x0bf2) + unichr(3972) + unichr(6000) + unichr(13231)
for i, c in enumerate(u):
print i, '%04x' % ord(c), unicodedata.category(c),
print unicodedata.name(c)
# Get numeric value of second character
print unicodedata.numeric(u[1])
When run, this prints::
0 00e9 Ll LATIN SMALL LETTER E WITH ACUTE
1 0bf2 No TAMIL NUMBER ONE THOUSAND
2 0f84 Mn TIBETAN MARK HALANTA
3 1770 Lo TAGBANWA LETTER SA
4 33af So SQUARE RAD OVER S SQUARED
1000.0
The category codes are abbreviations describing the nature of the character.
These are grouped into categories such as "Letter", "Number", "Punctuation", or
"Symbol", which in turn are broken up into subcategories. To take the codes
from the above output, ``'Ll'`` means 'Letter, lowercase', ``'No'`` means
"Number, other", ``'Mn'`` is "Mark, nonspacing", and ``'So'`` is "Symbol,
other". See
<http://www.unicode.org/reports/tr44/#General_Category_Values> for a
list of category codes.
References
----------
The Unicode and 8-bit string types are described in the Python library reference
at :ref:`typesseq`.
The documentation for the :mod:`unicodedata` module.
The documentation for the :mod:`codecs` module.
Marc-André Lemburg gave a presentation at EuroPython 2002 titled "Python and
Unicode". A PDF version of his slides is available at
<https://downloads.egenix.com/python/Unicode-EPC2002-Talk.pdf>, and is an
excellent overview of the design of Python's Unicode features.
Reading and Writing Unicode Data
================================
Once you've written some code that works with Unicode data, the next problem is
input/output. How do you get Unicode strings into your program, and how do you
convert Unicode into a form suitable for storage or transmission?
It's possible that you may not need to do anything depending on your input
sources and output destinations; you should check whether the libraries used in
your application support Unicode natively. XML parsers often return Unicode
data, for example. Many relational databases also support Unicode-valued
columns and can return Unicode values from an SQL query.
Unicode data is usually converted to a particular encoding before it gets
written to disk or sent over a socket. It's possible to do all the work
yourself: open a file, read an 8-bit string from it, and convert the string with
``unicode(str, encoding)``. However, the manual approach is not recommended.
One problem is the multi-byte nature of encodings; one Unicode character can be
represented by several bytes. If you want to read the file in arbitrary-sized
chunks (say, 1K or 4K), you need to write error-handling code to catch the case
where only part of the bytes encoding a single Unicode character are read at the
end of a chunk. One solution would be to read the entire file into memory and
then perform the decoding, but that prevents you from working with files that
are extremely large; if you need to read a 2Gb file, you need 2Gb of RAM.
(More, really, since for at least a moment you'd need to have both the encoded
string and its Unicode version in memory.)
The solution would be to use the low-level decoding interface to catch the case
of partial coding sequences. The work of implementing this has already been
done for you: the :mod:`codecs` module includes a version of the :func:`open`
function that returns a file-like object that assumes the file's contents are in
a specified encoding and accepts Unicode parameters for methods such as
``.read()`` and ``.write()``.
The function's parameters are ``open(filename, mode='rb', encoding=None,
errors='strict', buffering=1)``. ``mode`` can be ``'r'``, ``'w'``, or ``'a'``,
just like the corresponding parameter to the regular built-in ``open()``
function; add a ``'+'`` to update the file. ``buffering`` is similarly parallel
to the standard function's parameter. ``encoding`` is a string giving the
encoding to use; if it's left as ``None``, a regular Python file object that
accepts 8-bit strings is returned. Otherwise, a wrapper object is returned, and
data written to or read from the wrapper object will be converted as needed.
``errors`` specifies the action for encoding errors and can be one of the usual
values of 'strict', 'ignore', and 'replace'.
Reading Unicode from a file is therefore simple::
import codecs
f = codecs.open('unicode.rst', encoding='utf-8')
for line in f:
print repr(line)
It's also possible to open files in update mode, allowing both reading and
writing::
f = codecs.open('test', encoding='utf-8', mode='w+')
f.write(u'\u4500 blah blah blah\n')
f.seek(0)
print repr(f.readline()[:1])
f.close()
Unicode character U+FEFF is used as a byte-order mark (BOM), and is often
written as the first character of a file in order to assist with autodetection
of the file's byte ordering. Some encodings, such as UTF-16, expect a BOM to be
present at the start of a file; when such an encoding is used, the BOM will be
automatically written as the first character and will be silently dropped when
the file is read. There are variants of these encodings, such as 'utf-16-le'
and 'utf-16-be' for little-endian and big-endian encodings, that specify one
particular byte ordering and don't skip the BOM.
Unicode filenames
-----------------
Most of the operating systems in common use today support filenames that contain
arbitrary Unicode characters. Usually this is implemented by converting the
Unicode string into some encoding that varies depending on the system. For
example, Mac OS X uses UTF-8 while Windows uses a configurable encoding; on
Windows, Python uses the name "mbcs" to refer to whatever the currently
configured encoding is. On Unix systems, there will only be a filesystem
encoding if you've set the ``LANG`` or ``LC_CTYPE`` environment variables; if
you haven't, the default encoding is ASCII.
The :func:`sys.getfilesystemencoding` function returns the encoding to use on
your current system, in case you want to do the encoding manually, but there's
not much reason to bother. When opening a file for reading or writing, you can
usually just provide the Unicode string as the filename, and it will be
automatically converted to the right encoding for you::
filename = u'filename\u4500abc'
f = open(filename, 'w')
f.write('blah\n')
f.close()
Functions in the :mod:`os` module such as :func:`os.stat` will also accept Unicode
filenames.
:func:`os.listdir`, which returns filenames, raises an issue: should it return
the Unicode version of filenames, or should it return 8-bit strings containing
the encoded versions? :func:`os.listdir` will do both, depending on whether you
provided the directory path as an 8-bit string or a Unicode string. If you pass
a Unicode string as the path, filenames will be decoded using the filesystem's
encoding and a list of Unicode strings will be returned, while passing an 8-bit
path will return the 8-bit versions of the filenames. For example, assuming the
default filesystem encoding is UTF-8, running the following program::
fn = u'filename\u4500abc'
f = open(fn, 'w')
f.close()
import os
print os.listdir('.')
print os.listdir(u'.')
will produce the following output:
.. code-block:: shell-session
amk:~$ python t.py
['.svn', 'filename\xe4\x94\x80abc', ...]
[u'.svn', u'filename\u4500abc', ...]
The first list contains UTF-8-encoded filenames, and the second list contains
the Unicode versions.
Tips for Writing Unicode-aware Programs
---------------------------------------
This section provides some suggestions on writing software that deals with
Unicode.
The most important tip is:
Software should only work with Unicode strings internally, converting to a
particular encoding on output.
If you attempt to write processing functions that accept both Unicode and 8-bit
strings, you will find your program vulnerable to bugs wherever you combine the
two different kinds of strings. Python's default encoding is ASCII, so whenever
a character with an ASCII value > 127 is in the input data, you'll get a
:exc:`UnicodeDecodeError` because that character can't be handled by the ASCII
encoding.
It's easy to miss such problems if you only test your software with data that
doesn't contain any accents; everything will seem to work, but there's actually
a bug in your program waiting for the first user who attempts to use characters
> 127. A second tip, therefore, is:
Include characters > 127 and, even better, characters > 255 in your test
data.
When using data coming from a web browser or some other untrusted source, a
common technique is to check for illegal characters in a string before using the
string in a generated command line or storing it in a database. If you're doing
this, be careful to check the string once it's in the form that will be used or
stored; it's possible for encodings to be used to disguise characters. This is
especially true if the input data also specifies the encoding; many encodings
leave the commonly checked-for characters alone, but Python includes some
encodings such as ``'base64'`` that modify every single character.
For example, let's say you have a content management system that takes a Unicode
filename, and you want to disallow paths with a '/' character. You might write
this code::
def read_file (filename, encoding):
if '/' in filename:
raise ValueError("'/' not allowed in filenames")
unicode_name = filename.decode(encoding)
f = open(unicode_name, 'r')
# ... return contents of file ...
However, if an attacker could specify the ``'base64'`` encoding, they could pass
``'L2V0Yy9wYXNzd2Q='``, which is the base-64 encoded form of the string
``'/etc/passwd'``, to read a system file. The above code looks for ``'/'``
characters in the encoded form and misses the dangerous character in the
resulting decoded form.
References
----------
The PDF slides for Marc-André Lemburg's presentation "Writing Unicode-aware
Applications in Python" are available at
<https://downloads.egenix.com/python/LSM2005-Developing-Unicode-aware-applications-in-Python.pdf>
and discuss questions of character encodings as well as how to internationalize
and localize an application.
Revision History and Acknowledgements
=====================================
Thanks to the following people who have noted errors or offered suggestions on
this article: Nicholas Bastin, Marius Gedminas, Kent Johnson, Ken Krugler,
Marc-André Lemburg, Martin von Löwis, Chad Whitacre.
Version 1.0: posted August 5 2005.
Version 1.01: posted August 7 2005. Corrects factual and markup errors; adds
several links.
Version 1.02: posted August 16 2005. Corrects factual errors.
Version 1.03: posted June 20 2010. Notes that Python 3.x is not covered,
and that the HOWTO only covers 2.x.
.. comment Describe Python 3.x support (new section? new document?)
.. comment Additional topic: building Python w/ UCS2 or UCS4 support
.. comment Describe obscure -U switch somewhere?
.. comment Describe use of codecs.StreamRecoder and StreamReaderWriter
.. comment
Original outline:
- [ ] Unicode introduction
- [ ] ASCII
- [ ] Terms
- [ ] Character
- [ ] Code point
- [ ] Encodings
- [ ] Common encodings: ASCII, Latin-1, UTF-8
- [ ] Unicode Python type
- [ ] Writing unicode literals
- [ ] Obscurity: -U switch
- [ ] Built-ins
- [ ] unichr()
- [ ] ord()
- [ ] unicode() constructor
- [ ] Unicode type
- [ ] encode(), decode() methods
- [ ] Unicodedata module for character properties
- [ ] I/O
- [ ] Reading/writing Unicode data into files
- [ ] Byte-order marks
- [ ] Unicode filenames
- [ ] Writing Unicode programs
- [ ] Do everything in Unicode
- [ ] Declaring source code encodings (PEP 263)
- [ ] Other issues
- [ ] Building Python (UCS2, UCS4)
PK %�\0��[ �[ # html/_sources/howto/urllib2.rst.txtnu �[��� .. _urllib-howto:
************************************************
HOWTO Fetch Internet Resources Using urllib2
************************************************
:Author: `Michael Foord <http://www.voidspace.org.uk/python/index.shtml>`_
.. note::
There is a French translation of an earlier revision of this
HOWTO, available at `urllib2 - Le Manuel manquant
<http://www.voidspace.org.uk/python/articles/urllib2_francais.shtml>`_.
Introduction
============
.. sidebar:: Related Articles
You may also find useful the following article on fetching web resources
with Python:
* `Basic Authentication <http://www.voidspace.org.uk/python/articles/authentication.shtml>`_
A tutorial on *Basic Authentication*, with examples in Python.
**urllib2** is a Python module for fetching URLs
(Uniform Resource Locators). It offers a very simple interface, in the form of
the *urlopen* function. This is capable of fetching URLs using a variety of
different protocols. It also offers a slightly more complex interface for
handling common situations - like basic authentication, cookies, proxies and so
on. These are provided by objects called handlers and openers.
urllib2 supports fetching URLs for many "URL schemes" (identified by the string
before the ``":"`` in URL - for example ``"ftp"`` is the URL scheme of
``"ftp://python.org/"``) using their associated network protocols (e.g. FTP, HTTP).
This tutorial focuses on the most common case, HTTP.
For straightforward situations *urlopen* is very easy to use. But as soon as you
encounter errors or non-trivial cases when opening HTTP URLs, you will need some
understanding of the HyperText Transfer Protocol. The most comprehensive and
authoritative reference to HTTP is :rfc:`2616`. This is a technical document and
not intended to be easy to read. This HOWTO aims to illustrate using *urllib2*,
with enough detail about HTTP to help you through. It is not intended to replace
the :mod:`urllib2` docs, but is supplementary to them.
Fetching URLs
=============
The simplest way to use urllib2 is as follows::
import urllib2
response = urllib2.urlopen('http://python.org/')
html = response.read()
Many uses of urllib2 will be that simple (note that instead of an 'http:' URL we
could have used a URL starting with 'ftp:', 'file:', etc.). However, it's the
purpose of this tutorial to explain the more complicated cases, concentrating on
HTTP.
HTTP is based on requests and responses - the client makes requests and servers
send responses. urllib2 mirrors this with a ``Request`` object which represents
the HTTP request you are making. In its simplest form you create a Request
object that specifies the URL you want to fetch. Calling ``urlopen`` with this
Request object returns a response object for the URL requested. This response is
a file-like object, which means you can for example call ``.read()`` on the
response::
import urllib2
req = urllib2.Request('http://www.voidspace.org.uk')
response = urllib2.urlopen(req)
the_page = response.read()
Note that urllib2 makes use of the same Request interface to handle all URL
schemes. For example, you can make an FTP request like so::
req = urllib2.Request('ftp://example.com/')
In the case of HTTP, there are two extra things that Request objects allow you
to do: First, you can pass data to be sent to the server. Second, you can pass
extra information ("metadata") *about* the data or the about request itself, to
the server - this information is sent as HTTP "headers". Let's look at each of
these in turn.
Data
----
Sometimes you want to send data to a URL (often the URL will refer to a CGI
(Common Gateway Interface) script [#]_ or other web application). With HTTP,
this is often done using what's known as a **POST** request. This is often what
your browser does when you submit a HTML form that you filled in on the web. Not
all POSTs have to come from forms: you can use a POST to transmit arbitrary data
to your own application. In the common case of HTML forms, the data needs to be
encoded in a standard way, and then passed to the Request object as the ``data``
argument. The encoding is done using a function from the ``urllib`` library
*not* from ``urllib2``. ::
import urllib
import urllib2
url = 'http://www.someserver.com/cgi-bin/register.cgi'
values = {'name' : 'Michael Foord',
'location' : 'Northampton',
'language' : 'Python' }
data = urllib.urlencode(values)
req = urllib2.Request(url, data)
response = urllib2.urlopen(req)
the_page = response.read()
Note that other encodings are sometimes required (e.g. for file upload from HTML
forms - see `HTML Specification, Form Submission
<https://www.w3.org/TR/REC-html40/interact/forms.html#h-17.13>`_ for more
details).
If you do not pass the ``data`` argument, urllib2 uses a **GET** request. One
way in which GET and POST requests differ is that POST requests often have
"side-effects": they change the state of the system in some way (for example by
placing an order with the website for a hundredweight of tinned spam to be
delivered to your door). Though the HTTP standard makes it clear that POSTs are
intended to *always* cause side-effects, and GET requests *never* to cause
side-effects, nothing prevents a GET request from having side-effects, nor a
POST requests from having no side-effects. Data can also be passed in an HTTP
GET request by encoding it in the URL itself.
This is done as follows::
>>> import urllib2
>>> import urllib
>>> data = {}
>>> data['name'] = 'Somebody Here'
>>> data['location'] = 'Northampton'
>>> data['language'] = 'Python'
>>> url_values = urllib.urlencode(data)
>>> print url_values # The order may differ. #doctest: +SKIP
name=Somebody+Here&language=Python&location=Northampton
>>> url = 'http://www.example.com/example.cgi'
>>> full_url = url + '?' + url_values
>>> data = urllib2.urlopen(full_url)
Notice that the full URL is created by adding a ``?`` to the URL, followed by
the encoded values.
Headers
-------
We'll discuss here one particular HTTP header, to illustrate how to add headers
to your HTTP request.
Some websites [#]_ dislike being browsed by programs, or send different versions
to different browsers [#]_. By default urllib2 identifies itself as
``Python-urllib/x.y`` (where ``x`` and ``y`` are the major and minor version
numbers of the Python release,
e.g. ``Python-urllib/2.5``), which may confuse the site, or just plain
not work. The way a browser identifies itself is through the
``User-Agent`` header [#]_. When you create a Request object you can
pass a dictionary of headers in. The following example makes the same
request as above, but identifies itself as a version of Internet
Explorer [#]_. ::
import urllib
import urllib2
url = 'http://www.someserver.com/cgi-bin/register.cgi'
user_agent = 'Mozilla/5.0 (Windows NT 6.1; Win64; x64)'
values = {'name': 'Michael Foord',
'location': 'Northampton',
'language': 'Python' }
headers = {'User-Agent': user_agent}
data = urllib.urlencode(values)
req = urllib2.Request(url, data, headers)
response = urllib2.urlopen(req)
the_page = response.read()
The response also has two useful methods. See the section on `info and geturl`_
which comes after we have a look at what happens when things go wrong.
Handling Exceptions
===================
*urlopen* raises :exc:`URLError` when it cannot handle a response (though as
usual with Python APIs, built-in exceptions such as :exc:`ValueError`,
:exc:`TypeError` etc. may also be raised).
:exc:`HTTPError` is the subclass of :exc:`URLError` raised in the specific case of
HTTP URLs.
URLError
--------
Often, URLError is raised because there is no network connection (no route to
the specified server), or the specified server doesn't exist. In this case, the
exception raised will have a 'reason' attribute, which is a tuple containing an
error code and a text error message.
e.g. ::
>>> req = urllib2.Request('http://www.pretend_server.org')
>>> try: urllib2.urlopen(req)
... except urllib2.URLError as e:
... print e.reason #doctest: +SKIP
...
(4, 'getaddrinfo failed')
HTTPError
---------
Every HTTP response from the server contains a numeric "status code". Sometimes
the status code indicates that the server is unable to fulfil the request. The
default handlers will handle some of these responses for you (for example, if
the response is a "redirection" that requests the client fetch the document from
a different URL, urllib2 will handle that for you). For those it can't handle,
urlopen will raise an :exc:`HTTPError`. Typical errors include '404' (page not
found), '403' (request forbidden), and '401' (authentication required).
See section 10 of RFC 2616 for a reference on all the HTTP error codes.
The :exc:`HTTPError` instance raised will have an integer 'code' attribute, which
corresponds to the error sent by the server.
Error Codes
~~~~~~~~~~~
Because the default handlers handle redirects (codes in the 300 range), and
codes in the 100--299 range indicate success, you will usually only see error
codes in the 400--599 range.
``BaseHTTPServer.BaseHTTPRequestHandler.responses`` is a useful dictionary of
response codes in that shows all the response codes used by RFC 2616. The
dictionary is reproduced here for convenience ::
# Table mapping response codes to messages; entries have the
# form {code: (shortmessage, longmessage)}.
responses = {
100: ('Continue', 'Request received, please continue'),
101: ('Switching Protocols',
'Switching to new protocol; obey Upgrade header'),
200: ('OK', 'Request fulfilled, document follows'),
201: ('Created', 'Document created, URL follows'),
202: ('Accepted',
'Request accepted, processing continues off-line'),
203: ('Non-Authoritative Information', 'Request fulfilled from cache'),
204: ('No Content', 'Request fulfilled, nothing follows'),
205: ('Reset Content', 'Clear input form for further input.'),
206: ('Partial Content', 'Partial content follows.'),
300: ('Multiple Choices',
'Object has several resources -- see URI list'),
301: ('Moved Permanently', 'Object moved permanently -- see URI list'),
302: ('Found', 'Object moved temporarily -- see URI list'),
303: ('See Other', 'Object moved -- see Method and URL list'),
304: ('Not Modified',
'Document has not changed since given time'),
305: ('Use Proxy',
'You must use proxy specified in Location to access this '
'resource.'),
307: ('Temporary Redirect',
'Object moved temporarily -- see URI list'),
400: ('Bad Request',
'Bad request syntax or unsupported method'),
401: ('Unauthorized',
'No permission -- see authorization schemes'),
402: ('Payment Required',
'No payment -- see charging schemes'),
403: ('Forbidden',
'Request forbidden -- authorization will not help'),
404: ('Not Found', 'Nothing matches the given URI'),
405: ('Method Not Allowed',
'Specified method is invalid for this server.'),
406: ('Not Acceptable', 'URI not available in preferred format.'),
407: ('Proxy Authentication Required', 'You must authenticate with '
'this proxy before proceeding.'),
408: ('Request Timeout', 'Request timed out; try again later.'),
409: ('Conflict', 'Request conflict.'),
410: ('Gone',
'URI no longer exists and has been permanently removed.'),
411: ('Length Required', 'Client must specify Content-Length.'),
412: ('Precondition Failed', 'Precondition in headers is false.'),
413: ('Request Entity Too Large', 'Entity is too large.'),
414: ('Request-URI Too Long', 'URI is too long.'),
415: ('Unsupported Media Type', 'Entity body in unsupported format.'),
416: ('Requested Range Not Satisfiable',
'Cannot satisfy request range.'),
417: ('Expectation Failed',
'Expect condition could not be satisfied.'),
500: ('Internal Server Error', 'Server got itself in trouble'),
501: ('Not Implemented',
'Server does not support this operation'),
502: ('Bad Gateway', 'Invalid responses from another server/proxy.'),
503: ('Service Unavailable',
'The server cannot process the request due to a high load'),
504: ('Gateway Timeout',
'The gateway server did not receive a timely response'),
505: ('HTTP Version Not Supported', 'Cannot fulfill request.'),
}
When an error is raised the server responds by returning an HTTP error code
*and* an error page. You can use the :exc:`HTTPError` instance as a response on the
page returned. This means that as well as the code attribute, it also has read,
geturl, and info, methods. ::
>>> req = urllib2.Request('http://www.python.org/fish.html')
>>> try:
... urllib2.urlopen(req)
... except urllib2.HTTPError as e:
... print e.code
... print e.read() #doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
...
404
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
...
<title>Page Not Found</title>
...
Wrapping it Up
--------------
So if you want to be prepared for :exc:`HTTPError` *or* :exc:`URLError` there are two
basic approaches. I prefer the second approach.
Number 1
~~~~~~~~
::
from urllib2 import Request, urlopen, URLError, HTTPError
req = Request(someurl)
try:
response = urlopen(req)
except HTTPError as e:
print 'The server couldn\'t fulfill the request.'
print 'Error code: ', e.code
except URLError as e:
print 'We failed to reach a server.'
print 'Reason: ', e.reason
else:
# everything is fine
.. note::
The ``except HTTPError`` *must* come first, otherwise ``except URLError``
will *also* catch an :exc:`HTTPError`.
Number 2
~~~~~~~~
::
from urllib2 import Request, urlopen, URLError
req = Request(someurl)
try:
response = urlopen(req)
except URLError as e:
if hasattr(e, 'reason'):
print 'We failed to reach a server.'
print 'Reason: ', e.reason
elif hasattr(e, 'code'):
print 'The server couldn\'t fulfill the request.'
print 'Error code: ', e.code
else:
# everything is fine
info and geturl
===============
The response returned by urlopen (or the :exc:`HTTPError` instance) has two useful
methods :meth:`info` and :meth:`geturl`.
**geturl** - this returns the real URL of the page fetched. This is useful
because ``urlopen`` (or the opener object used) may have followed a
redirect. The URL of the page fetched may not be the same as the URL requested.
**info** - this returns a dictionary-like object that describes the page
fetched, particularly the headers sent by the server. It is currently an
``httplib.HTTPMessage`` instance.
Typical headers include 'Content-length', 'Content-type', and so on. See the
`Quick Reference to HTTP Headers <https://www.cs.tut.fi/~jkorpela/http.html>`_
for a useful listing of HTTP headers with brief explanations of their meaning
and use.
Openers and Handlers
====================
When you fetch a URL you use an opener (an instance of the perhaps
confusingly-named :class:`urllib2.OpenerDirector`). Normally we have been using
the default opener - via ``urlopen`` - but you can create custom
openers. Openers use handlers. All the "heavy lifting" is done by the
handlers. Each handler knows how to open URLs for a particular URL scheme (http,
ftp, etc.), or how to handle an aspect of URL opening, for example HTTP
redirections or HTTP cookies.
You will want to create openers if you want to fetch URLs with specific handlers
installed, for example to get an opener that handles cookies, or to get an
opener that does not handle redirections.
To create an opener, instantiate an ``OpenerDirector``, and then call
``.add_handler(some_handler_instance)`` repeatedly.
Alternatively, you can use ``build_opener``, which is a convenience function for
creating opener objects with a single function call. ``build_opener`` adds
several handlers by default, but provides a quick way to add more and/or
override the default handlers.
Other sorts of handlers you might want to can handle proxies, authentication,
and other common but slightly specialised situations.
``install_opener`` can be used to make an ``opener`` object the (global) default
opener. This means that calls to ``urlopen`` will use the opener you have
installed.
Opener objects have an ``open`` method, which can be called directly to fetch
urls in the same way as the ``urlopen`` function: there's no need to call
``install_opener``, except as a convenience.
Basic Authentication
====================
To illustrate creating and installing a handler we will use the
``HTTPBasicAuthHandler``. For a more detailed discussion of this subject --
including an explanation of how Basic Authentication works - see the `Basic
Authentication Tutorial
<http://www.voidspace.org.uk/python/articles/authentication.shtml>`_.
When authentication is required, the server sends a header (as well as the 401
error code) requesting authentication. This specifies the authentication scheme
and a 'realm'. The header looks like: ``WWW-Authenticate: SCHEME
realm="REALM"``.
e.g. ::
WWW-Authenticate: Basic realm="cPanel Users"
The client should then retry the request with the appropriate name and password
for the realm included as a header in the request. This is 'basic
authentication'. In order to simplify this process we can create an instance of
``HTTPBasicAuthHandler`` and an opener to use this handler.
The ``HTTPBasicAuthHandler`` uses an object called a password manager to handle
the mapping of URLs and realms to passwords and usernames. If you know what the
realm is (from the authentication header sent by the server), then you can use a
``HTTPPasswordMgr``. Frequently one doesn't care what the realm is. In that
case, it is convenient to use ``HTTPPasswordMgrWithDefaultRealm``. This allows
you to specify a default username and password for a URL. This will be supplied
in the absence of you providing an alternative combination for a specific
realm. We indicate this by providing ``None`` as the realm argument to the
``add_password`` method.
The top-level URL is the first URL that requires authentication. URLs "deeper"
than the URL you pass to .add_password() will also match. ::
# create a password manager
password_mgr = urllib2.HTTPPasswordMgrWithDefaultRealm()
# Add the username and password.
# If we knew the realm, we could use it instead of None.
top_level_url = "http://example.com/foo/"
password_mgr.add_password(None, top_level_url, username, password)
handler = urllib2.HTTPBasicAuthHandler(password_mgr)
# create "opener" (OpenerDirector instance)
opener = urllib2.build_opener(handler)
# use the opener to fetch a URL
opener.open(a_url)
# Install the opener.
# Now all calls to urllib2.urlopen use our opener.
urllib2.install_opener(opener)
.. note::
In the above example we only supplied our ``HTTPBasicAuthHandler`` to
``build_opener``. By default openers have the handlers for normal situations
-- ``ProxyHandler`` (if a proxy setting such as an :envvar:`http_proxy`
environment variable is set), ``UnknownHandler``, ``HTTPHandler``,
``HTTPDefaultErrorHandler``, ``HTTPRedirectHandler``, ``FTPHandler``,
``FileHandler``, ``HTTPErrorProcessor``.
``top_level_url`` is in fact *either* a full URL (including the 'http:' scheme
component and the hostname and optionally the port number)
e.g. ``"http://example.com/"`` *or* an "authority" (i.e. the hostname,
optionally including the port number) e.g. ``"example.com"`` or ``"example.com:8080"``
(the latter example includes a port number). The authority, if present, must
NOT contain the "userinfo" component - for example ``"joe:password@example.com"`` is
not correct.
Proxies
=======
**urllib2** will auto-detect your proxy settings and use those. This is through
the ``ProxyHandler``, which is part of the normal handler chain when a proxy
setting is detected. Normally that's a good thing, but there are occasions
when it may not be helpful [#]_. One way to do this is to setup our own
``ProxyHandler``, with no proxies defined. This is done using similar steps to
setting up a `Basic Authentication`_ handler: ::
>>> proxy_support = urllib2.ProxyHandler({})
>>> opener = urllib2.build_opener(proxy_support)
>>> urllib2.install_opener(opener)
.. note::
Currently ``urllib2`` *does not* support fetching of ``https`` locations
through a proxy. However, this can be enabled by extending urllib2 as
shown in the recipe [#]_.
.. note::
``HTTP_PROXY`` will be ignored if a variable ``REQUEST_METHOD`` is set; see
the documentation on :func:`~urllib.getproxies`.
Sockets and Layers
==================
The Python support for fetching resources from the web is layered. urllib2 uses
the httplib library, which in turn uses the socket library.
As of Python 2.3 you can specify how long a socket should wait for a response
before timing out. This can be useful in applications which have to fetch web
pages. By default the socket module has *no timeout* and can hang. Currently,
the socket timeout is not exposed at the httplib or urllib2 levels. However,
you can set the default timeout globally for all sockets using ::
import socket
import urllib2
# timeout in seconds
timeout = 10
socket.setdefaulttimeout(timeout)
# this call to urllib2.urlopen now uses the default timeout
# we have set in the socket module
req = urllib2.Request('http://www.voidspace.org.uk')
response = urllib2.urlopen(req)
-------
Footnotes
=========
This document was reviewed and revised by John Lee.
.. [#] For an introduction to the CGI protocol see
`Writing Web Applications in Python <http://www.pyzine.com/Issue008/Section_Articles/article_CGIOne.html>`_.
.. [#] Google for example.
.. [#] Browser sniffing is a very bad practice for website design - building
sites using web standards is much more sensible. Unfortunately a lot of
sites still send different versions to different browsers.
.. [#] The user agent for MSIE 6 is
*'Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1; .NET CLR 1.1.4322)'*
.. [#] For details of more HTTP request headers, see
`Quick Reference to HTTP Headers`_.
.. [#] In my case I have to use a proxy to access the internet at work. If you
attempt to fetch *localhost* URLs through this proxy it blocks them. IE
is set to use the proxy, which urllib2 picks up on. In order to test
scripts with a localhost server, I have to prevent urllib2 from using
the proxy.
.. [#] urllib2 opener for SSL proxy (CONNECT method): `ASPN Cookbook Recipe
<https://code.activestate.com/recipes/456195/>`_.
PK %�\��YjC� C� & html/_sources/howto/webservers.rst.txtnu �[��� *******************************
HOWTO Use Python in the web
*******************************
:Author: Marek Kubica
.. topic:: Abstract
This document shows how Python fits into the web. It presents some ways
to integrate Python with a web server, and general practices useful for
developing web sites.
Programming for the Web has become a hot topic since the rise of "Web 2.0",
which focuses on user-generated content on web sites. It has always been
possible to use Python for creating web sites, but it was a rather tedious task.
Therefore, many frameworks and helper tools have been created to assist
developers in creating faster and more robust sites. This HOWTO describes
some of the methods used to combine Python with a web server to create
dynamic content. It is not meant as a complete introduction, as this topic is
far too broad to be covered in one single document. However, a short overview
of the most popular libraries is provided.
.. seealso::
While this HOWTO tries to give an overview of Python in the web, it cannot
always be as up to date as desired. Web development in Python is rapidly
moving forward, so the wiki page on `Web Programming
<https://wiki.python.org/moin/WebProgramming>`_ may be more in sync with
recent development.
The Low-Level View
==================
When a user enters a web site, their browser makes a connection to the site's
web server (this is called the *request*). The server looks up the file in the
file system and sends it back to the user's browser, which displays it (this is
the *response*). This is roughly how the underlying protocol, HTTP, works.
Dynamic web sites are not based on files in the file system, but rather on
programs which are run by the web server when a request comes in, and which
*generate* the content that is returned to the user. They can do all sorts of
useful things, like display the postings of a bulletin board, show your email,
configure software, or just display the current time. These programs can be
written in any programming language the server supports. Since most servers
support Python, it is easy to use Python to create dynamic web sites.
Most HTTP servers are written in C or C++, so they cannot execute Python code
directly -- a bridge is needed between the server and the program. These
bridges, or rather interfaces, define how programs interact with the server.
There have been numerous attempts to create the best possible interface, but
there are only a few worth mentioning.
Not every web server supports every interface. Many web servers only support
old, now-obsolete interfaces; however, they can often be extended using
third-party modules to support newer ones.
Common Gateway Interface
------------------------
This interface, most commonly referred to as "CGI", is the oldest, and is
supported by nearly every web server out of the box. Programs using CGI to
communicate with their web server need to be started by the server for every
request. So, every request starts a new Python interpreter -- which takes some
time to start up -- thus making the whole interface only usable for low load
situations.
The upside of CGI is that it is simple -- writing a Python program which uses
CGI is a matter of about three lines of code. This simplicity comes at a
price: it does very few things to help the developer.
Writing CGI programs, while still possible, is no longer recommended. With
:ref:`WSGI <WSGI>`, a topic covered later in this document, it is possible to write
programs that emulate CGI, so they can be run as CGI if no better option is
available.
.. seealso::
The Python standard library includes some modules that are helpful for
creating plain CGI programs:
* :mod:`cgi` -- Handling of user input in CGI scripts
* :mod:`cgitb` -- Displays nice tracebacks when errors happen in CGI
applications, instead of presenting a "500 Internal Server Error" message
The Python wiki features a page on `CGI scripts
<https://wiki.python.org/moin/CgiScripts>`_ with some additional information
about CGI in Python.
Simple script for testing CGI
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To test whether your web server works with CGI, you can use this short and
simple CGI program::
#!/usr/bin/env python
# -*- coding: UTF-8 -*-
# enable debugging
import cgitb
cgitb.enable()
print "Content-Type: text/plain;charset=utf-8"
print
print "Hello World!"
Depending on your web server configuration, you may need to save this code with
a ``.py`` or ``.cgi`` extension. Additionally, this file may also need to be
in a ``cgi-bin`` folder, for security reasons.
You might wonder what the ``cgitb`` line is about. This line makes it possible
to display a nice traceback instead of just crashing and displaying an "Internal
Server Error" in the user's browser. This is useful for debugging, but it might
risk exposing some confidential data to the user. You should not use ``cgitb``
in production code for this reason. You should *always* catch exceptions, and
display proper error pages -- end-users don't like to see nondescript "Internal
Server Errors" in their browsers.
Setting up CGI on your own server
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you don't have your own web server, this does not apply to you. You can
check whether it works as-is, and if not you will need to talk to the
administrator of your web server. If it is a big host, you can try filing a
ticket asking for Python support.
If you are your own administrator or want to set up CGI for testing purposes on
your own computers, you have to configure it by yourself. There is no single
way to configure CGI, as there are many web servers with different
configuration options. Currently the most widely used free web server is
`Apache HTTPd <http://httpd.apache.org/>`_, or Apache for short. Apache can be
easily installed on nearly every system using the system's package management
tool. `lighttpd <http://www.lighttpd.net>`_ is another alternative and is
said to have better performance. On many systems this server can also be
installed using the package management tool, so manually compiling the web
server may not be needed.
* On Apache you can take a look at the `Dynamic Content with CGI
<http://httpd.apache.org/docs/2.2/howto/cgi.html>`_ tutorial, where everything
is described. Most of the time it is enough just to set ``+ExecCGI``. The
tutorial also describes the most common gotchas that might arise.
* On lighttpd you need to use the `CGI module
<http://redmine.lighttpd.net/projects/lighttpd/wiki/Docs_ModCGI>`_\ , which can be configured
in a straightforward way. It boils down to setting ``cgi.assign`` properly.
Common problems with CGI scripts
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Using CGI sometimes leads to small annoyances while trying to get these
scripts to run. Sometimes a seemingly correct script does not work as
expected, the cause being some small hidden problem that's difficult to spot.
Some of these potential problems are:
* The Python script is not marked as executable. When CGI scripts are not
executable most web servers will let the user download it, instead of
running it and sending the output to the user. For CGI scripts to run
properly on Unix-like operating systems, the ``+x`` bit needs to be set.
Using ``chmod a+x your_script.py`` may solve this problem.
* On a Unix-like system, The line endings in the program file must be Unix
style line endings. This is important because the web server checks the
first line of the script (called shebang) and tries to run the program
specified there. It gets easily confused by Windows line endings (Carriage
Return & Line Feed, also called CRLF), so you have to convert the file to
Unix line endings (only Line Feed, LF). This can be done automatically by
uploading the file via FTP in text mode instead of binary mode, but the
preferred way is just telling your editor to save the files with Unix line
endings. Most editors support this.
* Your web server must be able to read the file, and you need to make sure the
permissions are correct. On unix-like systems, the server often runs as user
and group ``www-data``, so it might be worth a try to change the file
ownership, or making the file world readable by using ``chmod a+r
your_script.py``.
* The web server must know that the file you're trying to access is a CGI script.
Check the configuration of your web server, as it may be configured
to expect a specific file extension for CGI scripts.
* On Unix-like systems, the path to the interpreter in the shebang
(``#!/usr/bin/env python``) must be correct. This line calls
``/usr/bin/env`` to find Python, but it will fail if there is no
``/usr/bin/env``, or if Python is not in the web server's path. If you know
where your Python is installed, you can also use that full path. The
commands ``whereis python`` and ``type -p python`` could help you find
where it is installed. Once you know the path, you can change the shebang
accordingly: ``#!/usr/bin/python``.
* The file must not contain a BOM (Byte Order Mark). The BOM is meant for
determining the byte order of UTF-16 and UTF-32 encodings, but some editors
write this also into UTF-8 files. The BOM interferes with the shebang line,
so be sure to tell your editor not to write the BOM.
* If the web server is using :ref:`mod-python`, ``mod_python`` may be having
problems. ``mod_python`` is able to handle CGI scripts by itself, but it can
also be a source of issues.
.. _mod-python:
mod_python
----------
People coming from PHP often find it hard to grasp how to use Python in the web.
Their first thought is mostly `mod_python <http://modpython.org/>`_\ ,
because they think that this is the equivalent to ``mod_php``. Actually, there
are many differences. What ``mod_python`` does is embed the interpreter into
the Apache process, thus speeding up requests by not having to start a Python
interpreter for each request. On the other hand, it is not "Python intermixed
with HTML" in the way that PHP is often intermixed with HTML. The Python
equivalent of that is a template engine. ``mod_python`` itself is much more
powerful and provides more access to Apache internals. It can emulate CGI,
work in a "Python Server Pages" mode (similar to JSP) which is "HTML
intermingled with Python", and it has a "Publisher" which designates one file
to accept all requests and decide what to do with them.
``mod_python`` does have some problems. Unlike the PHP interpreter, the Python
interpreter uses caching when executing files, so changes to a file will
require the web server to be restarted. Another problem is the basic concept
-- Apache starts child processes to handle the requests, and unfortunately
every child process needs to load the whole Python interpreter even if it does
not use it. This makes the whole web server slower. Another problem is that,
because ``mod_python`` is linked against a specific version of ``libpython``,
it is not possible to switch from an older version to a newer (e.g. 2.4 to 2.5)
without recompiling ``mod_python``. ``mod_python`` is also bound to the Apache
web server, so programs written for ``mod_python`` cannot easily run on other
web servers.
These are the reasons why ``mod_python`` should be avoided when writing new
programs. In some circumstances it still might be a good idea to use
``mod_python`` for deployment, but WSGI makes it possible to run WSGI programs
under ``mod_python`` as well.
FastCGI and SCGI
----------------
FastCGI and SCGI try to solve the performance problem of CGI in another way.
Instead of embedding the interpreter into the web server, they create
long-running background processes. There is still a module in the web server
which makes it possible for the web server to "speak" with the background
process. As the background process is independent of the server, it can be
written in any language, including Python. The language just needs to have a
library which handles the communication with the webserver.
The difference between FastCGI and SCGI is very small, as SCGI is essentially
just a "simpler FastCGI". As the web server support for SCGI is limited,
most people use FastCGI instead, which works the same way. Almost everything
that applies to SCGI also applies to FastCGI as well, so we'll only cover
the latter.
These days, FastCGI is never used directly. Just like ``mod_python``, it is only
used for the deployment of WSGI applications.
Setting up FastCGI
^^^^^^^^^^^^^^^^^^
Each web server requires a specific module.
* Apache has both `mod_fastcgi <http://www.fastcgi.com/drupal/>`_ and `mod_fcgid
<https://httpd.apache.org/mod_fcgid/>`_. ``mod_fastcgi`` is the original one, but it
has some licensing issues, which is why it is sometimes considered non-free.
``mod_fcgid`` is a smaller, compatible alternative. One of these modules needs
to be loaded by Apache.
* lighttpd ships its own `FastCGI module
<http://redmine.lighttpd.net/projects/lighttpd/wiki/Docs_ModFastCGI>`_ as well as an
`SCGI module <http://redmine.lighttpd.net/projects/lighttpd/wiki/Docs_ModSCGI>`_.
* `nginx <http://nginx.org/>`_ also supports `FastCGI
<https://www.nginx.com/resources/wiki/start/topics/examples/simplepythonfcgi/>`_.
Once you have installed and configured the module, you can test it with the
following WSGI-application::
#!/usr/bin/env python
# -*- coding: UTF-8 -*-
from cgi import escape
import sys, os
from flup.server.fcgi import WSGIServer
def app(environ, start_response):
start_response('200 OK', [('Content-Type', 'text/html')])
yield '<h1>FastCGI Environment</h1>'
yield '<table>'
for k, v in sorted(environ.items()):
yield '<tr><th>%s</th><td>%s</td></tr>' % (escape(k), escape(v))
yield '</table>'
WSGIServer(app).run()
This is a simple WSGI application, but you need to install `flup
<https://pypi.org/project/flup/1.0>`_ first, as flup handles the low level
FastCGI access.
.. seealso::
There is some documentation on `setting up Django with WSGI
<https://docs.djangoproject.com/en/dev/howto/deployment/wsgi/>`_, most of
which can be reused for other WSGI-compliant frameworks and libraries.
Only the ``manage.py`` part has to be changed, the example used here can be
used instead. Django does more or less the exact same thing.
mod_wsgi
--------
`mod_wsgi <http://code.google.com/p/modwsgi/>`_ is an attempt to get rid of the
low level gateways. Given that FastCGI, SCGI, and mod_python are mostly used to
deploy WSGI applications, mod_wsgi was started to directly embed WSGI applications
into the Apache web server. mod_wsgi is specifically designed to host WSGI
applications. It makes the deployment of WSGI applications much easier than
deployment using other low level methods, which need glue code. The downside
is that mod_wsgi is limited to the Apache web server; other servers would need
their own implementations of mod_wsgi.
mod_wsgi supports two modes: embedded mode, in which it integrates with the
Apache process, and daemon mode, which is more FastCGI-like. Unlike FastCGI,
mod_wsgi handles the worker-processes by itself, which makes administration
easier.
.. _WSGI:
Step back: WSGI
===============
WSGI has already been mentioned several times, so it has to be something
important. In fact it really is, and now it is time to explain it.
The *Web Server Gateway Interface*, or WSGI for short, is defined in
:pep:`333` and is currently the best way to do Python web programming. While
it is great for programmers writing frameworks, a normal web developer does not
need to get in direct contact with it. When choosing a framework for web
development it is a good idea to choose one which supports WSGI.
The big benefit of WSGI is the unification of the application programming
interface. When your program is compatible with WSGI -- which at the outer
level means that the framework you are using has support for WSGI -- your
program can be deployed via any web server interface for which there are WSGI
wrappers. You do not need to care about whether the application user uses
mod_python or FastCGI or mod_wsgi -- with WSGI your application will work on
any gateway interface. The Python standard library contains its own WSGI
server, :mod:`wsgiref`, which is a small web server that can be used for
testing.
A really great WSGI feature is middleware. Middleware is a layer around your
program which can add various functionality to it. There is quite a bit of
`middleware <https://wsgi.readthedocs.org/en/latest/libraries.html>`_ already
available. For example, instead of writing your own session management (HTTP
is a stateless protocol, so to associate multiple HTTP requests with a single
user your application must create and manage such state via a session), you can
just download middleware which does that, plug it in, and get on with coding
the unique parts of your application. The same thing with compression -- there
is existing middleware which handles compressing your HTML using gzip to save
on your server's bandwidth. Authentication is another problem that is easily
solved using existing middleware.
Although WSGI may seem complex, the initial phase of learning can be very
rewarding because WSGI and the associated middleware already have solutions to
many problems that might arise while developing web sites.
WSGI Servers
------------
The code that is used to connect to various low level gateways like CGI or
mod_python is called a *WSGI server*. One of these servers is ``flup``, which
supports FastCGI and SCGI, as well as `AJP
<https://en.wikipedia.org/wiki/Apache_JServ_Protocol>`_. Some of these servers
are written in Python, as ``flup`` is, but there also exist others which are
written in C and can be used as drop-in replacements.
There are many servers already available, so a Python web application
can be deployed nearly anywhere. This is one big advantage that Python has
compared with other web technologies.
.. seealso::
A good overview of WSGI-related code can be found in the `WSGI homepage
<https://wsgi.readthedocs.org/>`_, which contains an extensive list of `WSGI servers
<https://wsgi.readthedocs.org/en/latest/servers.html>`_ which can be used by *any* application
supporting WSGI.
You might be interested in some WSGI-supporting modules already contained in
the standard library, namely:
* :mod:`wsgiref` -- some tiny utilities and servers for WSGI
Case study: MoinMoin
--------------------
What does WSGI give the web application developer? Let's take a look at
an application that's been around for a while, which was written in
Python without using WSGI.
One of the most widely used wiki software packages is `MoinMoin
<https://moinmo.in/>`_. It was created in 2000, so it predates WSGI by about
three years. Older versions needed separate code to run on CGI, mod_python,
FastCGI and standalone.
It now includes support for WSGI. Using WSGI, it is possible to deploy
MoinMoin on any WSGI compliant server, with no additional glue code.
Unlike the pre-WSGI versions, this could include WSGI servers that the
authors of MoinMoin know nothing about.
Model-View-Controller
=====================
The term *MVC* is often encountered in statements such as "framework *foo*
supports MVC". MVC is more about the overall organization of code, rather than
any particular API. Many web frameworks use this model to help the developer
bring structure to their program. Bigger web applications can have lots of
code, so it is a good idea to have an effective structure right from the beginning.
That way, even users of other frameworks (or even other languages, since MVC is
not Python-specific) can easily understand the code, given that they are
already familiar with the MVC structure.
MVC stands for three components:
* The *model*. This is the data that will be displayed and modified. In
Python frameworks, this component is often represented by the classes used by
an object-relational mapper.
* The *view*. This component's job is to display the data of the model to the
user. Typically this component is implemented via templates.
* The *controller*. This is the layer between the user and the model. The
controller reacts to user actions (like opening some specific URL), tells
the model to modify the data if necessary, and tells the view code what to
display,
While one might think that MVC is a complex design pattern, in fact it is not.
It is used in Python because it has turned out to be useful for creating clean,
maintainable web sites.
.. note::
While not all Python frameworks explicitly support MVC, it is often trivial
to create a web site which uses the MVC pattern by separating the data logic
(the model) from the user interaction logic (the controller) and the
templates (the view). That's why it is important not to write unnecessary
Python code in the templates -- it works against the MVC model and creates
chaos in the code base, making it harder to understand and modify.
.. seealso::
The English Wikipedia has an article about the `Model-View-Controller pattern
<https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller>`_. It includes a long
list of web frameworks for various programming languages.
Ingredients for Websites
========================
Websites are complex constructs, so tools have been created to help web
developers make their code easier to write and more maintainable. Tools like
these exist for all web frameworks in all languages. Developers are not forced
to use these tools, and often there is no "best" tool. It is worth learning
about the available tools because they can greatly simplify the process of
developing a web site.
.. seealso::
There are far more components than can be presented here. The Python wiki
has a page about these components, called
`Web Components <https://wiki.python.org/moin/WebComponents>`_.
Templates
---------
Mixing of HTML and Python code is made possible by a few libraries. While
convenient at first, it leads to horribly unmaintainable code. That's why
templates exist. Templates are, in the simplest case, just HTML files with
placeholders. The HTML is sent to the user's browser after filling in the
placeholders.
Python already includes two ways to build simple templates::
>>> template = "<html><body><h1>Hello %s!</h1></body></html>"
>>> print template % "Reader"
<html><body><h1>Hello Reader!</h1></body></html>
>>> from string import Template
>>> template = Template("<html><body><h1>Hello ${name}</h1></body></html>")
>>> print template.substitute(dict(name='Dinsdale'))
<html><body><h1>Hello Dinsdale!</h1></body></html>
To generate complex HTML based on non-trivial model data, conditional
and looping constructs like Python's *for* and *if* are generally needed.
*Template engines* support templates of this complexity.
There are a lot of template engines available for Python which can be used with
or without a `framework`_. Some of these define a plain-text programming
language which is easy to learn, partly because it is limited in scope.
Others use XML, and the template output is guaranteed to be always be valid
XML. There are many other variations.
Some `frameworks`_ ship their own template engine or recommend one in
particular. In the absence of a reason to use a different template engine,
using the one provided by or recommended by the framework is a good idea.
Popular template engines include:
* `Mako <http://www.makotemplates.org/>`_
* `Genshi <http://genshi.edgewall.org/>`_
* `Jinja <http://jinja.pocoo.org/>`_
.. seealso::
There are many template engines competing for attention, because it is
pretty easy to create them in Python. The page `Templating
<https://wiki.python.org/moin/Templating>`_ in the wiki lists a big,
ever-growing number of these. The three listed above are considered "second
generation" template engines and are a good place to start.
Data persistence
----------------
*Data persistence*, while sounding very complicated, is just about storing data.
This data might be the text of blog entries, the postings on a bulletin board or
the text of a wiki page. There are, of course, a number of different ways to store
information on a web server.
Often, relational database engines like `MySQL <http://www.mysql.com/>`_ or
`PostgreSQL <http://www.postgresql.org/>`_ are used because of their good
performance when handling very large databases consisting of millions of
entries. There is also a small database engine called `SQLite
<http://www.sqlite.org/>`_, which is bundled with Python in the :mod:`sqlite3`
module, and which uses only one file. It has no other dependencies. For
smaller sites SQLite is just enough.
Relational databases are *queried* using a language called `SQL
<https://en.wikipedia.org/wiki/SQL>`_. Python programmers in general do not
like SQL too much, as they prefer to work with objects. It is possible to save
Python objects into a database using a technology called `ORM
<https://en.wikipedia.org/wiki/Object-relational_mapping>`_ (Object Relational
Mapping). ORM translates all object-oriented access into SQL code under the
hood, so the developer does not need to think about it. Most `frameworks`_ use
ORMs, and it works quite well.
A second possibility is storing data in normal, plain text files (some
times called "flat files"). This is very easy for simple sites,
but can be difficult to get right if the web site is performing many
updates to the stored data.
A third possibility are object oriented databases (also called "object
databases"). These databases store the object data in a form that closely
parallels the way the objects are structured in memory during program
execution. (By contrast, ORMs store the object data as rows of data in tables
and relations between those rows.) Storing the objects directly has the
advantage that nearly all objects can be saved in a straightforward way, unlike
in relational databases where some objects are very hard to represent.
`Frameworks`_ often give hints on which data storage method to choose. It is
usually a good idea to stick to the data store recommended by the framework
unless the application has special requirements better satisfied by an
alternate storage mechanism.
.. seealso::
* `Persistence Tools <https://wiki.python.org/moin/PersistenceTools>`_ lists
possibilities on how to save data in the file system. Some of these
modules are part of the standard library
* `Database Programming <https://wiki.python.org/moin/DatabaseProgramming>`_
helps with choosing a method for saving data
* `SQLAlchemy <http://www.sqlalchemy.org/>`_, the most powerful OR-Mapper
for Python, and `Elixir <https://pypi.org/project/Elixir>`_, which makes
SQLAlchemy easier to use
* `SQLObject <http://www.sqlobject.org/>`_, another popular OR-Mapper
* `ZODB <https://launchpad.net/zodb>`_ and `Durus
<https://www.mems-exchange.org/software/>`_, two object oriented
databases
.. _framework:
Frameworks
==========
The process of creating code to run web sites involves writing code to provide
various services. The code to provide a particular service often works the
same way regardless of the complexity or purpose of the web site in question.
Abstracting these common solutions into reusable code produces what are called
"frameworks" for web development. Perhaps the most well-known framework for
web development is Ruby on Rails, but Python has its own frameworks. Some of
these were partly inspired by Rails, or borrowed ideas from Rails, but many
existed a long time before Rails.
Originally Python web frameworks tended to incorporate all of the services
needed to develop web sites as a giant, integrated set of tools. No two web
frameworks were interoperable: a program developed for one could not be
deployed on a different one without considerable re-engineering work. This led
to the development of "minimalist" web frameworks that provided just the tools
to communicate between the Python code and the http protocol, with all other
services to be added on top via separate components. Some ad hoc standards
were developed that allowed for limited interoperability between frameworks,
such as a standard that allowed different template engines to be used
interchangeably.
Since the advent of WSGI, the Python web framework world has been evolving
toward interoperability based on the WSGI standard. Now many web frameworks,
whether "full stack" (providing all the tools one needs to deploy the most
complex web sites) or minimalist, or anything in between, are built from
collections of reusable components that can be used with more than one
framework.
The majority of users will probably want to select a "full stack" framework
that has an active community. These frameworks tend to be well documented,
and provide the easiest path to producing a fully functional web site in
minimal time.
Some notable frameworks
-----------------------
There are an incredible number of frameworks, so they cannot all be covered
here. Instead we will briefly touch on some of the most popular.
Django
^^^^^^
`Django <https://www.djangoproject.com/>`_ is a framework consisting of several
tightly coupled elements which were written from scratch and work together very
well. It includes an ORM which is quite powerful while being simple to use,
and has a great online administration interface which makes it possible to edit
the data in the database with a browser. The template engine is text-based and
is designed to be usable for page designers who cannot write Python. It
supports template inheritance and filters (which work like Unix pipes). Django
has many handy features bundled, such as creation of RSS feeds or generic views,
which make it possible to create web sites almost without writing any Python code.
It has a big, international community, the members of which have created many
web sites. There are also a lot of add-on projects which extend Django's normal
functionality. This is partly due to Django's well written `online
documentation <https://docs.djangoproject.com/>`_ and the `Django book
<http://www.djangobook.com/>`_.
.. note::
Although Django is an MVC-style framework, it names the elements
differently, which is described in the `Django FAQ
<https://docs.djangoproject.com/en/dev/faq/general/#django-appears-to-be-a-mvc-framework-but-you-call-the-controller-the-view-and-the-view-the-template-how-come-you-don-t-use-the-standard-names>`_.
TurboGears
^^^^^^^^^^
Another popular web framework for Python is `TurboGears
<http://www.turbogears.org/>`_. TurboGears takes the approach of using already
existing components and combining them with glue code to create a seamless
experience. TurboGears gives the user flexibility in choosing components. For
example the ORM and template engine can be changed to use packages different
from those used by default.
The documentation can be found in the `TurboGears documentation
<https://turbogears.readthedocs.org/>`_, where links to screencasts can be found.
TurboGears has also an active user community which can respond to most related
questions. There is also a `TurboGears book <http://turbogears.org/1.0/docs/TGBooks.html>`_
published, which is a good starting point.
The newest version of TurboGears, version 2.0, moves even further in direction
of WSGI support and a component-based architecture. TurboGears 2 is based on
the WSGI stack of another popular component-based web framework, `Pylons
<http://www.pylonsproject.org/>`_.
Zope
^^^^
The Zope framework is one of the "old original" frameworks. Its current
incarnation in Zope2 is a tightly integrated full-stack framework. One of its
most interesting feature is its tight integration with a powerful object
database called the `ZODB <https://launchpad.net/zodb>`_ (Zope Object Database).
Because of its highly integrated nature, Zope wound up in a somewhat isolated
ecosystem: code written for Zope wasn't very usable outside of Zope, and
vice-versa. To solve this problem the Zope 3 effort was started. Zope 3
re-engineers Zope as a set of more cleanly isolated components. This effort
was started before the advent of the WSGI standard, but there is WSGI support
for Zope 3 from the `Repoze <http://repoze.org/>`_ project. Zope components
have many years of production use behind them, and the Zope 3 project gives
access to these components to the wider Python community. There is even a
separate framework based on the Zope components: `Grok
<http://grok.zope.org/>`_.
Zope is also the infrastructure used by the `Plone <https://plone.org/>`_ content
management system, one of the most powerful and popular content management
systems available.
Other notable frameworks
^^^^^^^^^^^^^^^^^^^^^^^^
Of course these are not the only frameworks that are available. There are
many other frameworks worth mentioning.
Another framework that's already been mentioned is `Pylons`_. Pylons is much
like TurboGears, but with an even stronger emphasis on flexibility, which comes
at the cost of being more difficult to use. Nearly every component can be
exchanged, which makes it necessary to use the documentation of every single
component, of which there are many. Pylons builds upon `Paste
<http://pythonpaste.org/>`_, an extensive set of tools which are handy for WSGI.
And that's still not everything. The most up-to-date information can always be
found in the Python wiki.
.. seealso::
The Python wiki contains an extensive list of `web frameworks
<https://wiki.python.org/moin/WebFrameworks>`_.
Most frameworks also have their own mailing lists and IRC channels, look out
for these on the projects' web sites.
PK %�\4g9� � # html/_sources/install/index.rst.txtnu �[��� .. highlightlang:: none
.. _install-index:
********************************************
Installing Python Modules (Legacy version)
********************************************
:Author: Greg Ward
.. TODO: Fill in XXX comments
.. seealso::
:ref:`installing-index`
The up to date module installation documentations
.. The audience for this document includes people who don't know anything
about Python and aren't about to learn the language just in order to
install and maintain it for their users, i.e. system administrators.
Thus, I have to be sure to explain the basics at some point:
sys.path and PYTHONPATH at least. Should probably give pointers to
other docs on "import site", PYTHONSTARTUP, PYTHONHOME, etc.
Finally, it might be useful to include all the material from my "Care
and Feeding of a Python Installation" talk in here somewhere. Yow!
This document describes the Python Distribution Utilities ("Distutils") from the
end-user's point-of-view, describing how to extend the capabilities of a
standard Python installation by building and installing third-party Python
modules and extensions.
.. note::
This guide only covers the basic tools for building and distributing
extensions that are provided as part of this version of Python. Third party
tools offer easier to use and more secure alternatives. Refer to the `quick
recommendations section <https://packaging.python.org/en/latest/current/>`__
in the Python Packaging User Guide for more information.
.. _inst-intro:
Introduction
============
Although Python's extensive standard library covers many programming needs,
there often comes a time when you need to add some new functionality to your
Python installation in the form of third-party modules. This might be necessary
to support your own programming, or to support an application that you want to
use and that happens to be written in Python.
In the past, there has been little support for adding third-party modules to an
existing Python installation. With the introduction of the Python Distribution
Utilities (Distutils for short) in Python 2.0, this changed.
This document is aimed primarily at the people who need to install third-party
Python modules: end-users and system administrators who just need to get some
Python application running, and existing Python programmers who want to add some
new goodies to their toolbox. You don't need to know Python to read this
document; there will be some brief forays into using Python's interactive mode
to explore your installation, but that's it. If you're looking for information
on how to distribute your own Python modules so that others may use them, see
the :ref:`distutils-index` manual. :ref:`debug-setup-script` may also be of
interest.
.. _inst-trivial-install:
Best case: trivial installation
-------------------------------
In the best case, someone will have prepared a special version of the module
distribution you want to install that is targeted specifically at your platform
and is installed just like any other software on your platform. For example,
the module developer might make an executable installer available for Windows
users, an RPM package for users of RPM-based Linux systems (Red Hat, SuSE,
Mandrake, and many others), a Debian package for users of Debian-based Linux
systems, and so forth.
In that case, you would download the installer appropriate to your platform and
do the obvious thing with it: run it if it's an executable installer, ``rpm
--install`` it if it's an RPM, etc. You don't need to run Python or a setup
script, you don't need to compile anything---you might not even need to read any
instructions (although it's always a good idea to do so anyway).
Of course, things will not always be that easy. You might be interested in a
module distribution that doesn't have an easy-to-use installer for your
platform. In that case, you'll have to start with the source distribution
released by the module's author/maintainer. Installing from a source
distribution is not too hard, as long as the modules are packaged in the
standard way. The bulk of this document is about building and installing
modules from standard source distributions.
.. _inst-new-standard:
The new standard: Distutils
---------------------------
If you download a module source distribution, you can tell pretty quickly if it
was packaged and distributed in the standard way, i.e. using the Distutils.
First, the distribution's name and version number will be featured prominently
in the name of the downloaded archive, e.g. :file:`foo-1.0.tar.gz` or
:file:`widget-0.9.7.zip`. Next, the archive will unpack into a similarly-named
directory: :file:`foo-1.0` or :file:`widget-0.9.7`. Additionally, the
distribution will contain a setup script :file:`setup.py`, and a file named
:file:`README.txt` or possibly just :file:`README`, which should explain that
building and installing the module distribution is a simple matter of running
one command from a terminal::
python setup.py install
For Windows, this command should be run from a command prompt window
(:menuselection:`Start --> Accessories`)::
setup.py install
If all these things are true, then you already know how to build and install the
modules you've just downloaded: Run the command above. Unless you need to
install things in a non-standard way or customize the build process, you don't
really need this manual. Or rather, the above command is everything you need to
get out of this manual.
.. _inst-standard-install:
Standard Build and Install
==========================
As described in section :ref:`inst-new-standard`, building and installing a module
distribution using the Distutils is usually one simple command to run from a
terminal::
python setup.py install
.. _inst-platform-variations:
Platform variations
-------------------
You should always run the setup command from the distribution root directory,
i.e. the top-level subdirectory that the module source distribution unpacks
into. For example, if you've just downloaded a module source distribution
:file:`foo-1.0.tar.gz` onto a Unix system, the normal thing to do is::
gunzip -c foo-1.0.tar.gz | tar xf - # unpacks into directory foo-1.0
cd foo-1.0
python setup.py install
On Windows, you'd probably download :file:`foo-1.0.zip`. If you downloaded the
archive file to :file:`C:\\Temp`, then it would unpack into
:file:`C:\\Temp\\foo-1.0`; you can use either an archive manipulator with a
graphical user interface (such as WinZip) or a command-line tool (such as
:program:`unzip` or :program:`pkunzip`) to unpack the archive. Then, open a
command prompt window and run::
cd c:\Temp\foo-1.0
python setup.py install
.. _inst-splitting-up:
Splitting the job up
--------------------
Running ``setup.py install`` builds and installs all modules in one run. If you
prefer to work incrementally---especially useful if you want to customize the
build process, or if things are going wrong---you can use the setup script to do
one thing at a time. This is particularly helpful when the build and install
will be done by different users---for example, you might want to build a module
distribution and hand it off to a system administrator for installation (or do
it yourself, with super-user privileges).
For example, you can build everything in one step, and then install everything
in a second step, by invoking the setup script twice::
python setup.py build
python setup.py install
If you do this, you will notice that running the :command:`install` command
first runs the :command:`build` command, which---in this case---quickly notices
that it has nothing to do, since everything in the :file:`build` directory is
up-to-date.
You may not need this ability to break things down often if all you do is
install modules downloaded off the 'net, but it's very handy for more advanced
tasks. If you get into distributing your own Python modules and extensions,
you'll run lots of individual Distutils commands on their own.
.. _inst-how-build-works:
How building works
------------------
As implied above, the :command:`build` command is responsible for putting the
files to install into a *build directory*. By default, this is :file:`build`
under the distribution root; if you're excessively concerned with speed, or want
to keep the source tree pristine, you can change the build directory with the
:option:`!--build-base` option. For example::
python setup.py build --build-base=/path/to/pybuild/foo-1.0
(Or you could do this permanently with a directive in your system or personal
Distutils configuration file; see section :ref:`inst-config-files`.) Normally, this
isn't necessary.
The default layout for the build tree is as follows::
--- build/ --- lib/
or
--- build/ --- lib.<plat>/
temp.<plat>/
where ``<plat>`` expands to a brief description of the current OS/hardware
platform and Python version. The first form, with just a :file:`lib` directory,
is used for "pure module distributions"---that is, module distributions that
include only pure Python modules. If a module distribution contains any
extensions (modules written in C/C++), then the second form, with two ``<plat>``
directories, is used. In that case, the :file:`temp.{plat}` directory holds
temporary files generated by the compile/link process that don't actually get
installed. In either case, the :file:`lib` (or :file:`lib.{plat}`) directory
contains all Python modules (pure Python and extensions) that will be installed.
In the future, more directories will be added to handle Python scripts,
documentation, binary executables, and whatever else is needed to handle the job
of installing Python modules and applications.
.. _inst-how-install-works:
How installation works
----------------------
After the :command:`build` command runs (whether you run it explicitly, or the
:command:`install` command does it for you), the work of the :command:`install`
command is relatively simple: all it has to do is copy everything under
:file:`build/lib` (or :file:`build/lib.{plat}`) to your chosen installation
directory.
If you don't choose an installation directory---i.e., if you just run ``setup.py
install``\ ---then the :command:`install` command installs to the standard
location for third-party Python modules. This location varies by platform and
by how you built/installed Python itself. On Unix (and Mac OS X, which is also
Unix-based), it also depends on whether the module distribution being installed
is pure Python or contains extensions ("non-pure"):
.. tabularcolumns:: |l|l|l|l|
+-----------------+-----------------------------------------------------+--------------------------------------------------+-------+
| Platform | Standard installation location | Default value | Notes |
+=================+=====================================================+==================================================+=======+
| Unix (pure) | :file:`{prefix}/lib/python{X.Y}/site-packages` | :file:`/usr/local/lib/python{X.Y}/site-packages` | \(1) |
+-----------------+-----------------------------------------------------+--------------------------------------------------+-------+
| Unix (non-pure) | :file:`{exec-prefix}/lib/python{X.Y}/site-packages` | :file:`/usr/local/lib/python{X.Y}/site-packages` | \(1) |
+-----------------+-----------------------------------------------------+--------------------------------------------------+-------+
| Windows | :file:`{prefix}\\Lib\\site-packages` | :file:`C:\\Python{XY}\\Lib\\site-packages` | \(2) |
+-----------------+-----------------------------------------------------+--------------------------------------------------+-------+
Notes:
(1)
Most Linux distributions include Python as a standard part of the system, so
:file:`{prefix}` and :file:`{exec-prefix}` are usually both :file:`/usr` on
Linux. If you build Python yourself on Linux (or any Unix-like system), the
default :file:`{prefix}` and :file:`{exec-prefix}` are :file:`/usr/local`.
(2)
The default installation directory on Windows was :file:`C:\\Program
Files\\Python` under Python 1.6a1, 1.5.2, and earlier.
:file:`{prefix}` and :file:`{exec-prefix}` stand for the directories that Python
is installed to, and where it finds its libraries at run-time. They are always
the same under Windows, and very often the same under Unix and Mac OS X. You
can find out what your Python installation uses for :file:`{prefix}` and
:file:`{exec-prefix}` by running Python in interactive mode and typing a few
simple commands. Under Unix, just type ``python`` at the shell prompt. Under
Windows, choose :menuselection:`Start --> Programs --> Python X.Y -->
Python (command line)`. Once the interpreter is started, you type Python code
at the prompt. For example, on my Linux system, I type the three Python
statements shown below, and get the output as shown, to find out my
:file:`{prefix}` and :file:`{exec-prefix}`::
Python 2.4 (#26, Aug 7 2004, 17:19:02)
Type "help", "copyright", "credits" or "license" for more information.
>>> import sys
>>> sys.prefix
'/usr'
>>> sys.exec_prefix
'/usr'
A few other placeholders are used in this document: :file:`{X.Y}` stands for the
version of Python, for example ``2.7``; :file:`{distname}` will be replaced by
the name of the module distribution being installed. Dots and capitalization
are important in the paths; for example, a value that uses ``python2.7`` on UNIX
will typically use ``Python27`` on Windows.
If you don't want to install modules to the standard location, or if you don't
have permission to write there, then you need to read about alternate
installations in section :ref:`inst-alt-install`. If you want to customize your
installation directories more heavily, see section :ref:`inst-custom-install` on
custom installations.
.. _inst-alt-install:
Alternate Installation
======================
Often, it is necessary or desirable to install modules to a location other than
the standard location for third-party Python modules. For example, on a Unix
system you might not have permission to write to the standard third-party module
directory. Or you might wish to try out a module before making it a standard
part of your local Python installation. This is especially true when upgrading
a distribution already present: you want to make sure your existing base of
scripts still works with the new version before actually upgrading.
The Distutils :command:`install` command is designed to make installing module
distributions to an alternate location simple and painless. The basic idea is
that you supply a base directory for the installation, and the
:command:`install` command picks a set of directories (called an *installation
scheme*) under this base directory in which to install files. The details
differ across platforms, so read whichever of the following sections applies to
you.
Note that the various alternate installation schemes are mutually exclusive: you
can pass ``--user``, or ``--home``, or ``--prefix`` and ``--exec-prefix``, or
``--install-base`` and ``--install-platbase``, but you can't mix from these
groups.
.. _inst-alt-install-user:
Alternate installation: the user scheme
---------------------------------------
This scheme is designed to be the most convenient solution for users that don't
have write permission to the global site-packages directory or don't want to
install into it. It is enabled with a simple option::
python setup.py install --user
Files will be installed into subdirectories of :data:`site.USER_BASE` (written
as :file:`{userbase}` hereafter). This scheme installs pure Python modules and
extension modules in the same location (also known as :data:`site.USER_SITE`).
Here are the values for UNIX, including Mac OS X:
=============== ===========================================================
Type of file Installation directory
=============== ===========================================================
modules :file:`{userbase}/lib/python{X.Y}/site-packages`
scripts :file:`{userbase}/bin`
data :file:`{userbase}`
C headers :file:`{userbase}/include/python{X.Y}/{distname}`
=============== ===========================================================
And here are the values used on Windows:
=============== ===========================================================
Type of file Installation directory
=============== ===========================================================
modules :file:`{userbase}\\Python{XY}\\site-packages`
scripts :file:`{userbase}\\Scripts`
data :file:`{userbase}`
C headers :file:`{userbase}\\Python{XY}\\Include\\{distname}`
=============== ===========================================================
The advantage of using this scheme compared to the other ones described below is
that the user site-packages directory is under normal conditions always included
in :data:`sys.path` (see :mod:`site` for more information), which means that
there is no additional step to perform after running the :file:`setup.py` script
to finalize the installation.
The :command:`build_ext` command also has a ``--user`` option to add
:file:`{userbase}/include` to the compiler search path for header files and
:file:`{userbase}/lib` to the compiler search path for libraries as well as to
the runtime search path for shared C libraries (rpath).
.. _inst-alt-install-home:
Alternate installation: the home scheme
---------------------------------------
The idea behind the "home scheme" is that you build and maintain a personal
stash of Python modules. This scheme's name is derived from the idea of a
"home" directory on Unix, since it's not unusual for a Unix user to make their
home directory have a layout similar to :file:`/usr/` or :file:`/usr/local/`.
This scheme can be used by anyone, regardless of the operating system they
are installing for.
Installing a new module distribution is as simple as ::
python setup.py install --home=<dir>
where you can supply any directory you like for the :option:`!--home` option. On
Unix, lazy typists can just type a tilde (``~``); the :command:`install` command
will expand this to your home directory::
python setup.py install --home=~
To make Python find the distributions installed with this scheme, you may have
to :ref:`modify Python's search path <inst-search-path>` or edit
:mod:`sitecustomize` (see :mod:`site`) to call :func:`site.addsitedir` or edit
:data:`sys.path`.
The :option:`!--home` option defines the installation base directory. Files are
installed to the following directories under the installation base as follows:
=============== ===========================================================
Type of file Installation directory
=============== ===========================================================
modules :file:`{home}/lib/python`
scripts :file:`{home}/bin`
data :file:`{home}`
C headers :file:`{home}/include/python/{distname}`
=============== ===========================================================
(Mentally replace slashes with backslashes if you're on Windows.)
.. versionchanged:: 2.4
The :option:`!--home` option used to be supported only on Unix.
.. _inst-alt-install-prefix-unix:
Alternate installation: Unix (the prefix scheme)
------------------------------------------------
The "prefix scheme" is useful when you wish to use one Python installation to
perform the build/install (i.e., to run the setup script), but install modules
into the third-party module directory of a different Python installation (or
something that looks like a different Python installation). If this sounds a
trifle unusual, it is---that's why the user and home schemes come before. However,
there are at least two known cases where the prefix scheme will be useful.
First, consider that many Linux distributions put Python in :file:`/usr`, rather
than the more traditional :file:`/usr/local`. This is entirely appropriate,
since in those cases Python is part of "the system" rather than a local add-on.
However, if you are installing Python modules from source, you probably want
them to go in :file:`/usr/local/lib/python2.{X}` rather than
:file:`/usr/lib/python2.{X}`. This can be done with ::
/usr/bin/python setup.py install --prefix=/usr/local
Another possibility is a network filesystem where the name used to write to a
remote directory is different from the name used to read it: for example, the
Python interpreter accessed as :file:`/usr/local/bin/python` might search for
modules in :file:`/usr/local/lib/python2.{X}`, but those modules would have to
be installed to, say, :file:`/mnt/{@server}/export/lib/python2.{X}`. This could
be done with ::
/usr/local/bin/python setup.py install --prefix=/mnt/@server/export
In either case, the :option:`!--prefix` option defines the installation base, and
the :option:`!--exec-prefix` option defines the platform-specific installation
base, which is used for platform-specific files. (Currently, this just means
non-pure module distributions, but could be expanded to C libraries, binary
executables, etc.) If :option:`!--exec-prefix` is not supplied, it defaults to
:option:`!--prefix`. Files are installed as follows:
================= ==========================================================
Type of file Installation directory
================= ==========================================================
Python modules :file:`{prefix}/lib/python{X.Y}/site-packages`
extension modules :file:`{exec-prefix}/lib/python{X.Y}/site-packages`
scripts :file:`{prefix}/bin`
data :file:`{prefix}`
C headers :file:`{prefix}/include/python{X.Y}/{distname}`
================= ==========================================================
There is no requirement that :option:`!--prefix` or :option:`!--exec-prefix`
actually point to an alternate Python installation; if the directories listed
above do not already exist, they are created at installation time.
Incidentally, the real reason the prefix scheme is important is simply that a
standard Unix installation uses the prefix scheme, but with :option:`!--prefix`
and :option:`!--exec-prefix` supplied by Python itself as ``sys.prefix`` and
``sys.exec_prefix``. Thus, you might think you'll never use the prefix scheme,
but every time you run ``python setup.py install`` without any other options,
you're using it.
Note that installing extensions to an alternate Python installation has no
effect on how those extensions are built: in particular, the Python header files
(:file:`Python.h` and friends) installed with the Python interpreter used to run
the setup script will be used in compiling extensions. It is your
responsibility to ensure that the interpreter used to run extensions installed
in this way is compatible with the interpreter used to build them. The best way
to do this is to ensure that the two interpreters are the same version of Python
(possibly different builds, or possibly copies of the same build). (Of course,
if your :option:`!--prefix` and :option:`!--exec-prefix` don't even point to an
alternate Python installation, this is immaterial.)
.. _inst-alt-install-prefix-windows:
Alternate installation: Windows (the prefix scheme)
---------------------------------------------------
Windows has no concept of a user's home directory, and since the standard Python
installation under Windows is simpler than under Unix, the :option:`!--prefix`
option has traditionally been used to install additional packages in separate
locations on Windows. ::
python setup.py install --prefix="\Temp\Python"
to install modules to the :file:`\\Temp\\Python` directory on the current drive.
The installation base is defined by the :option:`!--prefix` option; the
:option:`!--exec-prefix` option is not supported under Windows, which means that
pure Python modules and extension modules are installed into the same location.
Files are installed as follows:
=============== ==========================================================
Type of file Installation directory
=============== ==========================================================
modules :file:`{prefix}\\Lib\\site-packages`
scripts :file:`{prefix}\\Scripts`
data :file:`{prefix}`
C headers :file:`{prefix}\\Include\\{distname}`
=============== ==========================================================
.. _inst-custom-install:
Custom Installation
===================
Sometimes, the alternate installation schemes described in section
:ref:`inst-alt-install` just don't do what you want. You might want to tweak just
one or two directories while keeping everything under the same base directory,
or you might want to completely redefine the installation scheme. In either
case, you're creating a *custom installation scheme*.
To create a custom installation scheme, you start with one of the alternate
schemes and override some of the installation directories used for the various
types of files, using these options:
====================== =======================
Type of file Override option
====================== =======================
Python modules ``--install-purelib``
extension modules ``--install-platlib``
all modules ``--install-lib``
scripts ``--install-scripts``
data ``--install-data``
C headers ``--install-headers``
====================== =======================
These override options can be relative, absolute,
or explicitly defined in terms of one of the installation base directories.
(There are two installation base directories, and they are normally the same---
they only differ when you use the Unix "prefix scheme" and supply different
``--prefix`` and ``--exec-prefix`` options; using ``--install-lib`` will
override values computed or given for ``--install-purelib`` and
``--install-platlib``, and is recommended for schemes that don't make a
difference between Python and extension modules.)
For example, say you're installing a module distribution to your home directory
under Unix---but you want scripts to go in :file:`~/scripts` rather than
:file:`~/bin`. As you might expect, you can override this directory with the
:option:`!--install-scripts` option; in this case, it makes most sense to supply
a relative path, which will be interpreted relative to the installation base
directory (your home directory, in this case)::
python setup.py install --home=~ --install-scripts=scripts
Another Unix example: suppose your Python installation was built and installed
with a prefix of :file:`/usr/local/python`, so under a standard installation
scripts will wind up in :file:`/usr/local/python/bin`. If you want them in
:file:`/usr/local/bin` instead, you would supply this absolute directory for the
:option:`!--install-scripts` option::
python setup.py install --install-scripts=/usr/local/bin
(This performs an installation using the "prefix scheme," where the prefix is
whatever your Python interpreter was installed with--- :file:`/usr/local/python`
in this case.)
If you maintain Python on Windows, you might want third-party modules to live in
a subdirectory of :file:`{prefix}`, rather than right in :file:`{prefix}`
itself. This is almost as easy as customizing the script installation directory
---you just have to remember that there are two types of modules to worry about,
Python and extension modules, which can conveniently be both controlled by one
option::
python setup.py install --install-lib=Site
The specified installation directory is relative to :file:`{prefix}`. Of
course, you also have to ensure that this directory is in Python's module
search path, such as by putting a :file:`.pth` file in a site directory (see
:mod:`site`). See section :ref:`inst-search-path` to find out how to modify
Python's search path.
If you want to define an entire installation scheme, you just have to supply all
of the installation directory options. The recommended way to do this is to
supply relative paths; for example, if you want to maintain all Python
module-related files under :file:`python` in your home directory, and you want a
separate directory for each platform that you use your home directory from, you
might define the following installation scheme::
python setup.py install --home=~ \
--install-purelib=python/lib \
--install-platlib=python/lib.$PLAT \
--install-scripts=python/scripts
--install-data=python/data
or, equivalently, ::
python setup.py install --home=~/python \
--install-purelib=lib \
--install-platlib='lib.$PLAT' \
--install-scripts=scripts
--install-data=data
``$PLAT`` is not (necessarily) an environment variable---it will be expanded by
the Distutils as it parses your command line options, just as it does when
parsing your configuration file(s).
Obviously, specifying the entire installation scheme every time you install a
new module distribution would be very tedious. Thus, you can put these options
into your Distutils config file (see section :ref:`inst-config-files`)::
[install]
install-base=$HOME
install-purelib=python/lib
install-platlib=python/lib.$PLAT
install-scripts=python/scripts
install-data=python/data
or, equivalently, ::
[install]
install-base=$HOME/python
install-purelib=lib
install-platlib=lib.$PLAT
install-scripts=scripts
install-data=data
Note that these two are *not* equivalent if you supply a different installation
base directory when you run the setup script. For example, ::
python setup.py install --install-base=/tmp
would install pure modules to :file:`/tmp/python/lib` in the first case, and
to :file:`/tmp/lib` in the second case. (For the second case, you probably
want to supply an installation base of :file:`/tmp/python`.)
You probably noticed the use of ``$HOME`` and ``$PLAT`` in the sample
configuration file input. These are Distutils configuration variables, which
bear a strong resemblance to environment variables. In fact, you can use
environment variables in config files on platforms that have such a notion but
the Distutils additionally define a few extra variables that may not be in your
environment, such as ``$PLAT``. (And of course, on systems that don't have
environment variables, such as Mac OS 9, the configuration variables supplied by
the Distutils are the only ones you can use.) See section :ref:`inst-config-files`
for details.
.. XXX need some Windows examples---when would custom installation schemes be
needed on those platforms?
.. XXX Move this to Doc/using
.. _inst-search-path:
Modifying Python's Search Path
------------------------------
When the Python interpreter executes an :keyword:`import` statement, it searches
for both Python code and extension modules along a search path. A default value
for the path is configured into the Python binary when the interpreter is built.
You can determine the path by importing the :mod:`sys` module and printing the
value of ``sys.path``. ::
$ python
Python 2.2 (#11, Oct 3 2002, 13:31:27)
[GCC 2.96 20000731 (Red Hat Linux 7.3 2.96-112)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import sys
>>> sys.path
['', '/usr/local/lib/python2.3', '/usr/local/lib/python2.3/plat-linux2',
'/usr/local/lib/python2.3/lib-tk', '/usr/local/lib/python2.3/lib-dynload',
'/usr/local/lib/python2.3/site-packages']
>>>
The null string in ``sys.path`` represents the current working directory.
The expected convention for locally installed packages is to put them in the
:file:`{...}/site-packages/` directory, but you may want to install Python
modules into some arbitrary directory. For example, your site may have a
convention of keeping all software related to the web server under :file:`/www`.
Add-on Python modules might then belong in :file:`/www/python`, and in order to
import them, this directory must be added to ``sys.path``. There are several
different ways to add the directory.
The most convenient way is to add a path configuration file to a directory
that's already on Python's path, usually to the :file:`.../site-packages/`
directory. Path configuration files have an extension of :file:`.pth`, and each
line must contain a single path that will be appended to ``sys.path``. (Because
the new paths are appended to ``sys.path``, modules in the added directories
will not override standard modules. This means you can't use this mechanism for
installing fixed versions of standard modules.)
Paths can be absolute or relative, in which case they're relative to the
directory containing the :file:`.pth` file. See the documentation of
the :mod:`site` module for more information.
A slightly less convenient way is to edit the :file:`site.py` file in Python's
standard library, and modify ``sys.path``. :file:`site.py` is automatically
imported when the Python interpreter is executed, unless the :option:`-S` switch
is supplied to suppress this behaviour. So you could simply edit
:file:`site.py` and add two lines to it::
import sys
sys.path.append('/www/python/')
However, if you reinstall the same major version of Python (perhaps when
upgrading from 2.2 to 2.2.2, for example) :file:`site.py` will be overwritten by
the stock version. You'd have to remember that it was modified and save a copy
before doing the installation.
There are two environment variables that can modify ``sys.path``.
:envvar:`PYTHONHOME` sets an alternate value for the prefix of the Python
installation. For example, if :envvar:`PYTHONHOME` is set to ``/www/python``,
the search path will be set to ``['', '/www/python/lib/pythonX.Y/',
'/www/python/lib/pythonX.Y/plat-linux2', ...]``.
The :envvar:`PYTHONPATH` variable can be set to a list of paths that will be
added to the beginning of ``sys.path``. For example, if :envvar:`PYTHONPATH` is
set to ``/www/python:/opt/py``, the search path will begin with
``['/www/python', '/opt/py']``. (Note that directories must exist in order to
be added to ``sys.path``; the :mod:`site` module removes paths that don't
exist.)
Finally, ``sys.path`` is just a regular Python list, so any Python application
can modify it by adding or removing entries.
.. _inst-config-files:
Distutils Configuration Files
=============================
As mentioned above, you can use Distutils configuration files to record personal
or site preferences for any Distutils options. That is, any option to any
command can be stored in one of two or three (depending on your platform)
configuration files, which will be consulted before the command-line is parsed.
This means that configuration files will override default values, and the
command-line will in turn override configuration files. Furthermore, if
multiple configuration files apply, values from "earlier" files are overridden
by "later" files.
.. _inst-config-filenames:
Location and names of config files
----------------------------------
The names and locations of the configuration files vary slightly across
platforms. On Unix and Mac OS X, the three configuration files (in the order
they are processed) are:
+--------------+----------------------------------------------------------+-------+
| Type of file | Location and filename | Notes |
+==============+==========================================================+=======+
| system | :file:`{prefix}/lib/python{ver}/distutils/distutils.cfg` | \(1) |
+--------------+----------------------------------------------------------+-------+
| personal | :file:`$HOME/.pydistutils.cfg` | \(2) |
+--------------+----------------------------------------------------------+-------+
| local | :file:`setup.cfg` | \(3) |
+--------------+----------------------------------------------------------+-------+
And on Windows, the configuration files are:
+--------------+-------------------------------------------------+-------+
| Type of file | Location and filename | Notes |
+==============+=================================================+=======+
| system | :file:`{prefix}\\Lib\\distutils\\distutils.cfg` | \(4) |
+--------------+-------------------------------------------------+-------+
| personal | :file:`%HOME%\\pydistutils.cfg` | \(5) |
+--------------+-------------------------------------------------+-------+
| local | :file:`setup.cfg` | \(3) |
+--------------+-------------------------------------------------+-------+
On all platforms, the "personal" file can be temporarily disabled by
passing the `--no-user-cfg` option.
Notes:
(1)
Strictly speaking, the system-wide configuration file lives in the directory
where the Distutils are installed; under Python 1.6 and later on Unix, this is
as shown. For Python 1.5.2, the Distutils will normally be installed to
:file:`{prefix}/lib/python1.5/site-packages/distutils`, so the system
configuration file should be put there under Python 1.5.2.
(2)
On Unix, if the :envvar:`HOME` environment variable is not defined, the user's
home directory will be determined with the :func:`getpwuid` function from the
standard :mod:`pwd` module. This is done by the :func:`os.path.expanduser`
function used by Distutils.
(3)
I.e., in the current directory (usually the location of the setup script).
(4)
(See also note (1).) Under Python 1.6 and later, Python's default "installation
prefix" is :file:`C:\\Python`, so the system configuration file is normally
:file:`C:\\Python\\Lib\\distutils\\distutils.cfg`. Under Python 1.5.2, the
default prefix was :file:`C:\\Program Files\\Python`, and the Distutils were not
part of the standard library---so the system configuration file would be
:file:`C:\\Program Files\\Python\\distutils\\distutils.cfg` in a standard Python
1.5.2 installation under Windows.
(5)
On Windows, if the :envvar:`HOME` environment variable is not defined,
:envvar:`USERPROFILE` then :envvar:`HOMEDRIVE` and :envvar:`HOMEPATH` will
be tried. This is done by the :func:`os.path.expanduser` function used
by Distutils.
.. _inst-config-syntax:
Syntax of config files
----------------------
The Distutils configuration files all have the same syntax. The config files
are grouped into sections. There is one section for each Distutils command,
plus a ``global`` section for global options that affect every command. Each
section consists of one option per line, specified as ``option=value``.
For example, the following is a complete config file that just forces all
commands to run quietly by default::
[global]
verbose=0
If this is installed as the system config file, it will affect all processing of
any Python module distribution by any user on the current system. If it is
installed as your personal config file (on systems that support them), it will
affect only module distributions processed by you. And if it is used as the
:file:`setup.cfg` for a particular module distribution, it affects only that
distribution.
You could override the default "build base" directory and make the
:command:`build\*` commands always forcibly rebuild all files with the
following::
[build]
build-base=blib
force=1
which corresponds to the command-line arguments ::
python setup.py build --build-base=blib --force
except that including the :command:`build` command on the command-line means
that command will be run. Including a particular command in config files has no
such implication; it only means that if the command is run, the options in the
config file will apply. (Or if other commands that derive values from it are
run, they will use the values in the config file.)
You can find out the complete list of options for any command using the
:option:`!--help` option, e.g.::
python setup.py build --help
and you can find out the complete list of global options by using
:option:`!--help` without a command::
python setup.py --help
See also the "Reference" section of the "Distributing Python Modules" manual.
.. _inst-building-ext:
Building Extensions: Tips and Tricks
====================================
Whenever possible, the Distutils try to use the configuration information made
available by the Python interpreter used to run the :file:`setup.py` script.
For example, the same compiler and linker flags used to compile Python will also
be used for compiling extensions. Usually this will work well, but in
complicated situations this might be inappropriate. This section discusses how
to override the usual Distutils behaviour.
.. _inst-tweak-flags:
Tweaking compiler/linker flags
------------------------------
Compiling a Python extension written in C or C++ will sometimes require
specifying custom flags for the compiler and linker in order to use a particular
library or produce a special kind of object code. This is especially true if the
extension hasn't been tested on your platform, or if you're trying to
cross-compile Python.
In the most general case, the extension author might have foreseen that
compiling the extensions would be complicated, and provided a :file:`Setup` file
for you to edit. This will likely only be done if the module distribution
contains many separate extension modules, or if they often require elaborate
sets of compiler flags in order to work.
A :file:`Setup` file, if present, is parsed in order to get a list of extensions
to build. Each line in a :file:`Setup` describes a single module. Lines have
the following structure::
module ... [sourcefile ...] [cpparg ...] [library ...]
Let's examine each of the fields in turn.
* *module* is the name of the extension module to be built, and should be a
valid Python identifier. You can't just change this in order to rename a module
(edits to the source code would also be needed), so this should be left alone.
* *sourcefile* is anything that's likely to be a source code file, at least
judging by the filename. Filenames ending in :file:`.c` are assumed to be
written in C, filenames ending in :file:`.C`, :file:`.cc`, and :file:`.c++` are
assumed to be C++, and filenames ending in :file:`.m` or :file:`.mm` are assumed
to be in Objective C.
* *cpparg* is an argument for the C preprocessor, and is anything starting with
:option:`!-I`, :option:`!-D`, :option:`!-U` or :option:`!-C`.
* *library* is anything ending in :file:`.a` or beginning with :option:`!-l` or
:option:`!-L`.
If a particular platform requires a special library on your platform, you can
add it by editing the :file:`Setup` file and running ``python setup.py build``.
For example, if the module defined by the line ::
foo foomodule.c
must be linked with the math library :file:`libm.a` on your platform, simply add
:option:`!-lm` to the line::
foo foomodule.c -lm
Arbitrary switches intended for the compiler or the linker can be supplied with
the :option:`!-Xcompiler` *arg* and :option:`!-Xlinker` *arg* options::
foo foomodule.c -Xcompiler -o32 -Xlinker -shared -lm
The next option after :option:`!-Xcompiler` and :option:`!-Xlinker` will be
appended to the proper command line, so in the above example the compiler will
be passed the :option:`!-o32` option, and the linker will be passed
:option:`!-shared`. If a compiler option requires an argument, you'll have to
supply multiple :option:`!-Xcompiler` options; for example, to pass ``-x c++``
the :file:`Setup` file would have to contain ``-Xcompiler -x -Xcompiler c++``.
Compiler flags can also be supplied through setting the :envvar:`CFLAGS`
environment variable. If set, the contents of :envvar:`CFLAGS` will be added to
the compiler flags specified in the :file:`Setup` file.
.. _inst-non-ms-compilers:
Using non-Microsoft compilers on Windows
----------------------------------------
.. sectionauthor:: Rene Liebscher <R.Liebscher@gmx.de>
Borland/CodeGear C++
^^^^^^^^^^^^^^^^^^^^
This subsection describes the necessary steps to use Distutils with the Borland
C++ compiler version 5.5. First you have to know that Borland's object file
format (OMF) is different from the format used by the Python version you can
download from the Python or ActiveState Web site. (Python is built with
Microsoft Visual C++, which uses COFF as the object file format.) For this
reason you have to convert Python's library :file:`python25.lib` into the
Borland format. You can do this as follows:
.. Should we mention that users have to create cfg-files for the compiler?
.. see also http://community.borland.com/article/0,1410,21205,00.html
::
coff2omf python25.lib python25_bcpp.lib
The :file:`coff2omf` program comes with the Borland compiler. The file
:file:`python25.lib` is in the :file:`Libs` directory of your Python
installation. If your extension uses other libraries (zlib, ...) you have to
convert them too.
The converted files have to reside in the same directories as the normal
libraries.
How does Distutils manage to use these libraries with their changed names? If
the extension needs a library (eg. :file:`foo`) Distutils checks first if it
finds a library with suffix :file:`_bcpp` (eg. :file:`foo_bcpp.lib`) and then
uses this library. In the case it doesn't find such a special library it uses
the default name (:file:`foo.lib`.) [#]_
To let Distutils compile your extension with Borland C++ you now have to type::
python setup.py build --compiler=bcpp
If you want to use the Borland C++ compiler as the default, you could specify
this in your personal or system-wide configuration file for Distutils (see
section :ref:`inst-config-files`.)
.. seealso::
`C++Builder Compiler <https://www.embarcadero.com/products>`_
Information about the free C++ compiler from Borland, including links to the
download pages.
`Creating Python Extensions Using Borland's Free Compiler <http://www.cyberus.ca/~g_will/pyExtenDL.shtml>`_
Document describing how to use Borland's free command-line C++ compiler to build
Python.
GNU C / Cygwin / MinGW
^^^^^^^^^^^^^^^^^^^^^^
This section describes the necessary steps to use Distutils with the GNU C/C++
compilers in their Cygwin and MinGW distributions. [#]_ For a Python interpreter
that was built with Cygwin, everything should work without any of these
following steps.
Not all extensions can be built with MinGW or Cygwin, but many can. Extensions
most likely to not work are those that use C++ or depend on Microsoft Visual C
extensions.
To let Distutils compile your extension with Cygwin you have to type::
python setup.py build --compiler=cygwin
and for Cygwin in no-cygwin mode [#]_ or for MinGW type::
python setup.py build --compiler=mingw32
If you want to use any of these options/compilers as default, you should
consider writing it in your personal or system-wide configuration file for
Distutils (see section :ref:`inst-config-files`.)
Older Versions of Python and MinGW
""""""""""""""""""""""""""""""""""
The following instructions only apply if you're using a version of Python
inferior to 2.4.1 with a MinGW inferior to 3.0.0 (with
binutils-2.13.90-20030111-1).
These compilers require some special libraries. This task is more complex than
for Borland's C++, because there is no program to convert the library. First
you have to create a list of symbols which the Python DLL exports. (You can find
a good program for this task at
https://sourceforge.net/projects/mingw/files/MinGW/Extension/pexports/).
.. I don't understand what the next line means. --amk
.. (inclusive the references on data structures.)
::
pexports python25.dll >python25.def
The location of an installed :file:`python25.dll` will depend on the
installation options and the version and language of Windows. In a "just for
me" installation, it will appear in the root of the installation directory. In
a shared installation, it will be located in the system directory.
Then you can create from these information an import library for gcc. ::
/cygwin/bin/dlltool --dllname python25.dll --def python25.def --output-lib libpython25.a
The resulting library has to be placed in the same directory as
:file:`python25.lib`. (Should be the :file:`libs` directory under your Python
installation directory.)
If your extension uses other libraries (zlib,...) you might have to convert
them too. The converted files have to reside in the same directories as the
normal libraries do.
.. seealso::
`Building Python modules on MS Windows platform with MinGW <http://old.zope.org/Members/als/tips/win32_mingw_modules>`_
Information about building the required libraries for the MinGW environment.
.. rubric:: Footnotes
.. [#] This also means you could replace all existing COFF-libraries with OMF-libraries
of the same name.
.. [#] Check https://www.sourceware.org/cygwin/ and http://www.mingw.org/ for more
information
.. [#] Then you have no POSIX emulation available, but you also don't need
:file:`cygwin1.dll`.
PK %�\ ����" �" & html/_sources/installing/index.rst.txtnu �[��� .. highlightlang:: none
.. _installing-index:
*****************************
Installing Python Modules
*****************************
:Email: distutils-sig@python.org
As a popular open source development project, Python has an active
supporting community of contributors and users that also make their software
available for other Python developers to use under open source license terms.
This allows Python users to share and collaborate effectively, benefiting
from the solutions others have already created to common (and sometimes
even rare!) problems, as well as potentially contributing their own
solutions to the common pool.
This guide covers the installation part of the process. For a guide to
creating and sharing your own Python projects, refer to the
:ref:`distribution guide <distributing-index>`.
.. note::
For corporate and other institutional users, be aware that many
organisations have their own policies around using and contributing to
open source software. Please take such policies into account when making
use of the distribution and installation tools provided with Python.
Key terms
=========
* ``pip`` is the preferred installer program. Starting with Python 2.7.9, it
is included by default with the Python binary installers.
* a virtual environment is a semi-isolated Python environment that allows
packages to be installed for use by a particular application, rather than
being installed system wide
* ``virtualenv`` is a third party tools for creating virtual environments, it
is defaults to installing ``pip`` into all created virtual environments.
* the `Python Packaging Index <https://pypi.org>`__ is a public repository of
open source licensed packages made available for use by other Python users
* the `Python Packaging Authority
<https://www.pypa.io/en/latest/>`__ are the group of
developers and documentation authors responsible for the maintenance and
evolution of the standard packaging tools and the associated metadata and
file format standards. They maintain a variety of tools, documentation
and issue trackers on both `GitHub <https://github.com/pypa>`__ and
`BitBucket <https://bitbucket.org/pypa/>`__.
* ``distutils`` is the original build and distribution system first added to
the Python standard library in 1998. While direct use of ``distutils`` is
being phased out, it still laid the foundation for the current packaging
and distribution infrastructure, and it not only remains part of the
standard library, but its name lives on in other ways (such as the name
of the mailing list used to coordinate Python packaging standards
development).
Basic usage
===========
The standard packaging tools are all designed to be used from the command
line.
The following command will install the latest version of a module and its
dependencies from the Python Packaging Index::
python -m pip install SomePackage
.. note::
For POSIX users (including Mac OS X and Linux users), the examples in
this guide assume the use of a :term:`virtual environment`. You may install
``virtualenv`` to provide such environments using either pip
(``pip install virtualenv``) or through your system package manager
(commonly called ``virtualenv`` or ``python-virtualenv``).
For Windows users, the examples in this guide assume that the option to
adjust the system PATH environment variable was selected when installing
Python.
It's also possible to specify an exact or minimum version directly on the
command line. When using comparator operators such as ``>``, ``<`` or some other
special character which get interpreted by shell, the package name and the
version should be enclosed within double quotes::
python -m pip install SomePackage==1.0.4 # specific version
python -m pip install "SomePackage>=1.0.4" # minimum version
Normally, if a suitable module is already installed, attempting to install
it again will have no effect. Upgrading existing modules must be requested
explicitly::
python -m pip install --upgrade SomePackage
More information and resources regarding ``pip`` and its capabilities can be
found in the `Python Packaging User Guide <https://packaging.python.org>`__.
.. seealso::
`Python Packaging User Guide: Installing Python Distribution Packages
<https://packaging.python.org/en/latest/installing/>`__
How do I ...?
=============
These are quick answers or links for some common tasks.
... install ``pip`` in versions of Python prior to Python 2.7.9?
----------------------------------------------------------------
Python only started bundling ``pip`` with Python 2.7.9. For earlier versions,
``pip`` needs to be "bootstrapped" as described in the Python Packaging
User Guide.
.. seealso::
`Python Packaging User Guide: Requirements for Installing Packages
<https://packaging.python.org/en/latest/installing/#requirements-for-installing-packages>`__
.. installing-per-user-installation:
... install packages just for the current user?
-----------------------------------------------
Passing the ``--user`` option to ``python -m pip install`` will install a
package just for the current user, rather than for all users of the system.
... install scientific Python packages?
---------------------------------------
A number of scientific Python packages have complex binary dependencies, and
aren't currently easy to install using ``pip`` directly. At this point in
time, it will often be easier for users to install these packages by
`other means
<https://packaging.python.org/en/latest/science/>`__
rather than attempting to install them with ``pip``.
.. seealso::
`Python Packaging User Guide: Installing Scientific Packages
<https://packaging.python.org/en/latest/science/>`__
... work with multiple versions of Python installed in parallel?
----------------------------------------------------------------
On Linux, Mac OS X and other POSIX systems, use the versioned Python commands
in combination with the ``-m`` switch to run the appropriate copy of
``pip``::
python2 -m pip install SomePackage # default Python 2
python2.7 -m pip install SomePackage # specifically Python 2.7
python3 -m pip install SomePackage # default Python 3
python3.4 -m pip install SomePackage # specifically Python 3.4
(appropriately versioned ``pip`` commands may also be available)
On Windows, use the ``py`` Python launcher in combination with the ``-m``
switch::
py -2 -m pip install SomePackage # default Python 2
py -2.7 -m pip install SomePackage # specifically Python 2.7
py -3 -m pip install SomePackage # default Python 3
py -3.4 -m pip install SomePackage # specifically Python 3.4
.. other questions:
Once the Development & Deployment part of PPUG is fleshed out, some of
those sections should be linked from new questions here (most notably,
we should have a question about avoiding depending on PyPI that links to
https://packaging.python.org/en/latest/mirrors/)
Common installation issues
==========================
Installing into the system Python on Linux
------------------------------------------
On Linux systems, a Python installation will typically be included as part
of the distribution. Installing into this Python installation requires
root access to the system, and may interfere with the operation of the
system package manager and other components of the system if a component
is unexpectedly upgraded using ``pip``.
On such systems, it is often better to use a virtual environment or a
per-user installation when installing packages with ``pip``.
Pip not installed
-----------------
It is possible that ``pip`` does not get installed by default. One potential fix is::
python -m ensurepip --default-pip
There are also additional resources for `installing pip.
<https://packaging.python.org/tutorials/installing-packages/#install-pip-setuptools-and-wheel>`__
Installing binary extensions
----------------------------
Python has typically relied heavily on source based distribution, with end
users being expected to compile extension modules from source as part of
the installation process.
With the introduction of support for the binary ``wheel`` format, and the
ability to publish wheels for at least Windows and Mac OS X through the
Python Packaging Index, this problem is expected to diminish over time,
as users are more regularly able to install pre-built extensions rather
than needing to build them themselves.
Some of the solutions for installing `scientific software
<https://packaging.python.org/en/latest/science/>`__
that is not yet available as pre-built ``wheel`` files may also help with
obtaining other binary extensions without needing to build them locally.
.. seealso::
`Python Packaging User Guide: Binary Extensions
<https://packaging.python.org/en/latest/extensions/>`__
PK %�\M�J�� � ) html/_sources/library/__builtin__.rst.txtnu �[���
:mod:`__builtin__` --- Built-in objects
=======================================
.. module:: __builtin__
:synopsis: The module that provides the built-in namespace.
This module provides direct access to all 'built-in' identifiers of Python; for
example, ``__builtin__.open`` is the full name for the built-in function
:func:`open`. See :ref:`built-in-funcs` and :ref:`built-in-consts` for
documentation.
This module is not normally accessed explicitly by most applications, but can be
useful in modules that provide objects with the same name as a built-in value,
but in which the built-in of that name is also needed. For example, in a module
that wants to implement an :func:`open` function that wraps the built-in
:func:`open`, this module can be used directly::
import __builtin__
def open(path):
f = __builtin__.open(path, 'r')
return UpperCaser(f)
class UpperCaser:
'''Wrapper around a file that converts output to upper-case.'''
def __init__(self, f):
self._f = f
def read(self, count=-1):
return self._f.read(count).upper()
# ...
.. impl-detail::
Most modules have the name ``__builtins__`` (note the ``'s'``) made available
as part of their globals. The value of ``__builtins__`` is normally either
this module or the value of this modules's :attr:`~object.__dict__` attribute. Since
this is an implementation detail, it may not be used by alternate
implementations of Python.
PK %�\�I�X X ( html/_sources/library/__future__.rst.txtnu �[��� :mod:`__future__` --- Future statement definitions
==================================================
.. module:: __future__
:synopsis: Future statement definitions
**Source code:** :source:`Lib/__future__.py`
--------------
:mod:`__future__` is a real module, and serves three purposes:
* To avoid confusing existing tools that analyze import statements and expect to
find the modules they're importing.
* To ensure that :ref:`future statements <future>` run under releases prior to
2.1 at least yield runtime exceptions (the import of :mod:`__future__` will
fail, because there was no module of that name prior to 2.1).
* To document when incompatible changes were introduced, and when they will be
--- or were --- made mandatory. This is a form of executable documentation, and
can be inspected programmatically via importing :mod:`__future__` and examining
its contents.
Each statement in :file:`__future__.py` is of the form::
FeatureName = _Feature(OptionalRelease, MandatoryRelease,
CompilerFlag)
where, normally, *OptionalRelease* is less than *MandatoryRelease*, and both are
5-tuples of the same form as ``sys.version_info``::
(PY_MAJOR_VERSION, # the 2 in 2.1.0a3; an int
PY_MINOR_VERSION, # the 1; an int
PY_MICRO_VERSION, # the 0; an int
PY_RELEASE_LEVEL, # "alpha", "beta", "candidate" or "final"; string
PY_RELEASE_SERIAL # the 3; an int
)
*OptionalRelease* records the first release in which the feature was accepted.
In the case of a *MandatoryRelease* that has not yet occurred,
*MandatoryRelease* predicts the release in which the feature will become part of
the language.
Else *MandatoryRelease* records when the feature became part of the language; in
releases at or after that, modules no longer need a future statement to use the
feature in question, but may continue to use such imports.
*MandatoryRelease* may also be ``None``, meaning that a planned feature got
dropped.
Instances of class :class:`_Feature` have two corresponding methods,
:meth:`getOptionalRelease` and :meth:`getMandatoryRelease`.
*CompilerFlag* is the (bitfield) flag that should be passed in the fourth
argument to the built-in function :func:`compile` to enable the feature in
dynamically compiled code. This flag is stored in the :attr:`compiler_flag`
attribute on :class:`_Feature` instances.
No feature description will ever be deleted from :mod:`__future__`. Since its
introduction in Python 2.1 the following features have found their way into the
language using this mechanism:
+------------------+-------------+--------------+---------------------------------------------+
| feature | optional in | mandatory in | effect |
+==================+=============+==============+=============================================+
| nested_scopes | 2.1.0b1 | 2.2 | :pep:`227`: |
| | | | *Statically Nested Scopes* |
+------------------+-------------+--------------+---------------------------------------------+
| generators | 2.2.0a1 | 2.3 | :pep:`255`: |
| | | | *Simple Generators* |
+------------------+-------------+--------------+---------------------------------------------+
| division | 2.2.0a2 | 3.0 | :pep:`238`: |
| | | | *Changing the Division Operator* |
+------------------+-------------+--------------+---------------------------------------------+
| absolute_import | 2.5.0a1 | 3.0 | :pep:`328`: |
| | | | *Imports: Multi-Line and Absolute/Relative* |
+------------------+-------------+--------------+---------------------------------------------+
| with_statement | 2.5.0a1 | 2.6 | :pep:`343`: |
| | | | *The "with" Statement* |
+------------------+-------------+--------------+---------------------------------------------+
| print_function | 2.6.0a2 | 3.0 | :pep:`3105`: |
| | | | *Make print a function* |
+------------------+-------------+--------------+---------------------------------------------+
| unicode_literals | 2.6.0a2 | 3.0 | :pep:`3112`: |
| | | | *Bytes literals in Python 3000* |
+------------------+-------------+--------------+---------------------------------------------+
.. seealso::
:ref:`future`
How the compiler treats future imports.
PK %�\B��� & html/_sources/library/__main__.rst.txtnu �[���
:mod:`__main__` --- Top-level script environment
================================================
.. module:: __main__
:synopsis: The environment where the top-level script is run.
This module represents the (otherwise anonymous) scope in which the
interpreter's main program executes --- commands read either from standard
input, from a script file, or from an interactive prompt. It is this
environment in which the idiomatic "conditional script" stanza causes a script
to run::
if __name__ == "__main__":
main()
PK %�\�� [ [ % html/_sources/library/_winreg.rst.txtnu �[��� :mod:`_winreg` --- Windows registry access
==========================================
.. module:: _winreg
:platform: Windows
:synopsis: Routines and objects for manipulating the Windows registry.
.. sectionauthor:: Mark Hammond <MarkH@ActiveState.com>
.. note::
The :mod:`_winreg` module has been renamed to :mod:`winreg` in Python 3.
The :term:`2to3` tool will automatically adapt imports when converting your
sources to Python 3.
.. versionadded:: 2.0
These functions expose the Windows registry API to Python. Instead of using an
integer as the registry handle, a :ref:`handle object <handle-object>` is used
to ensure that the handles are closed correctly, even if the programmer neglects
to explicitly close them.
This module offers the following functions:
.. function:: CloseKey(hkey)
Closes a previously opened registry key. The *hkey* argument specifies a
previously opened key.
.. note::
If *hkey* is not closed using this method (or via :meth:`hkey.Close() <PyHKEY.Close>`),
it is closed when the *hkey* object is destroyed by Python.
.. function:: ConnectRegistry(computer_name, key)
Establishes a connection to a predefined registry handle on another computer,
and returns a :ref:`handle object <handle-object>`.
*computer_name* is the name of the remote computer, of the form
``r"\\computername"``. If ``None``, the local computer is used.
*key* is the predefined handle to connect to.
The return value is the handle of the opened key. If the function fails, a
:exc:`WindowsError` exception is raised.
.. function:: CreateKey(key, sub_key)
Creates or opens the specified key, returning a
:ref:`handle object <handle-object>`.
*key* is an already open key, or one of the predefined
:ref:`HKEY_* constants <hkey-constants>`.
*sub_key* is a string that names the key this method opens or creates.
If *key* is one of the predefined keys, *sub_key* may be ``None``. In that
case, the handle returned is the same key handle passed in to the function.
If the key already exists, this function opens the existing key.
The return value is the handle of the opened key. If the function fails, a
:exc:`WindowsError` exception is raised.
.. function:: CreateKeyEx(key, sub_key[, res[, sam]])
Creates or opens the specified key, returning a
:ref:`handle object <handle-object>`.
*key* is an already open key, or one of the predefined
:ref:`HKEY_* constants <hkey-constants>`.
*sub_key* is a string that names the key this method opens or creates.
*res* is a reserved integer, and must be zero. The default is zero.
*sam* is an integer that specifies an access mask that describes the desired
security access for the key. Default is :const:`KEY_ALL_ACCESS`. See
:ref:`Access Rights <access-rights>` for other allowed values.
If *key* is one of the predefined keys, *sub_key* may be ``None``. In that
case, the handle returned is the same key handle passed in to the function.
If the key already exists, this function opens the existing key.
The return value is the handle of the opened key. If the function fails, a
:exc:`WindowsError` exception is raised.
.. versionadded:: 2.7
.. function:: DeleteKey(key, sub_key)
Deletes the specified key.
*key* is an already open key, or any one of the predefined
:ref:`HKEY_* constants <hkey-constants>`.
*sub_key* is a string that must be a subkey of the key identified by the *key*
parameter. This value must not be ``None``, and the key may not have subkeys.
*This method can not delete keys with subkeys.*
If the method succeeds, the entire key, including all of its values, is removed.
If the method fails, a :exc:`WindowsError` exception is raised.
.. function:: DeleteKeyEx(key, sub_key[, sam[, res]])
Deletes the specified key.
.. note::
The :func:`DeleteKeyEx` function is implemented with the RegDeleteKeyEx
Windows API function, which is specific to 64-bit versions of Windows.
See the `RegDeleteKeyEx documentation
<http://msdn.microsoft.com/en-us/library/ms724847%28VS.85%29.aspx>`__.
*key* is an already open key, or any one of the predefined
:ref:`HKEY_* constants <hkey-constants>`.
*sub_key* is a string that must be a subkey of the key identified by the
*key* parameter. This value must not be ``None``, and the key may not have
subkeys.
*res* is a reserved integer, and must be zero. The default is zero.
*sam* is an integer that specifies an access mask that describes the desired
security access for the key. Default is :const:`KEY_WOW64_64KEY`. See
:ref:`Access Rights <access-rights>` for other allowed values.
*This method can not delete keys with subkeys.*
If the method succeeds, the entire key, including all of its values, is
removed. If the method fails, a :exc:`WindowsError` exception is raised.
On unsupported Windows versions, :exc:`NotImplementedError` is raised.
.. versionadded:: 2.7
.. function:: DeleteValue(key, value)
Removes a named value from a registry key.
*key* is an already open key, or one of the predefined
:ref:`HKEY_* constants <hkey-constants>`.
*value* is a string that identifies the value to remove.
.. function:: EnumKey(key, index)
Enumerates subkeys of an open registry key, returning a string.
*key* is an already open key, or any one of the predefined
:ref:`HKEY_* constants <hkey-constants>`.
*index* is an integer that identifies the index of the key to retrieve.
The function retrieves the name of one subkey each time it is called. It is
typically called repeatedly until a :exc:`WindowsError` exception is
raised, indicating, no more values are available.
.. function:: EnumValue(key, index)
Enumerates values of an open registry key, returning a tuple.
*key* is an already open key, or any one of the predefined
:ref:`HKEY_* constants <hkey-constants>`.
*index* is an integer that identifies the index of the value to retrieve.
The function retrieves the name of one subkey each time it is called. It is
typically called repeatedly, until a :exc:`WindowsError` exception is
raised, indicating no more values.
The result is a tuple of 3 items:
+-------+--------------------------------------------+
| Index | Meaning |
+=======+============================================+
| ``0`` | A string that identifies the value name |
+-------+--------------------------------------------+
| ``1`` | An object that holds the value data, and |
| | whose type depends on the underlying |
| | registry type |
+-------+--------------------------------------------+
| ``2`` | An integer that identifies the type of the |
| | value data (see table in docs for |
| | :meth:`SetValueEx`) |
+-------+--------------------------------------------+
.. function:: ExpandEnvironmentStrings(unicode)
Expands environment variable placeholders ``%NAME%`` in unicode strings like
:const:`REG_EXPAND_SZ`::
>>> ExpandEnvironmentStrings(u"%windir%")
u"C:\\Windows"
.. versionadded:: 2.6
.. function:: FlushKey(key)
Writes all the attributes of a key to the registry.
*key* is an already open key, or one of the predefined
:ref:`HKEY_* constants <hkey-constants>`.
It is not necessary to call :func:`FlushKey` to change a key. Registry changes are
flushed to disk by the registry using its lazy flusher. Registry changes are
also flushed to disk at system shutdown. Unlike :func:`CloseKey`, the
:func:`FlushKey` method returns only when all the data has been written to the
registry. An application should only call :func:`FlushKey` if it requires
absolute certainty that registry changes are on disk.
.. note::
If you don't know whether a :func:`FlushKey` call is required, it probably
isn't.
.. function:: LoadKey(key, sub_key, file_name)
Creates a subkey under the specified key and stores registration information
from a specified file into that subkey.
*key* is a handle returned by :func:`ConnectRegistry` or one of the constants
:const:`HKEY_USERS` or :const:`HKEY_LOCAL_MACHINE`.
*sub_key* is a string that identifies the subkey to load.
*file_name* is the name of the file to load registry data from. This file must
have been created with the :func:`SaveKey` function. Under the file allocation
table (FAT) file system, the filename may not have an extension.
A call to :func:`LoadKey` fails if the calling process does not have the
:const:`SE_RESTORE_PRIVILEGE` privilege. Note that privileges are different
from permissions -- see the `RegLoadKey documentation
<http://msdn.microsoft.com/en-us/library/ms724889%28v=VS.85%29.aspx>`__ for
more details.
If *key* is a handle returned by :func:`ConnectRegistry`, then the path
specified in *file_name* is relative to the remote computer.
.. function:: OpenKey(key, sub_key[, res[, sam]])
Opens the specified key, returning a :ref:`handle object <handle-object>`.
*key* is an already open key, or any one of the predefined
:ref:`HKEY_* constants <hkey-constants>`.
*sub_key* is a string that identifies the sub_key to open.
*res* is a reserved integer, and must be zero. The default is zero.
*sam* is an integer that specifies an access mask that describes the desired
security access for the key. Default is :const:`KEY_READ`. See
:ref:`Access Rights <access-rights>` for other allowed values.
The result is a new handle to the specified key.
If the function fails, :exc:`WindowsError` is raised.
.. function:: OpenKeyEx()
The functionality of :func:`OpenKeyEx` is provided via :func:`OpenKey`,
by the use of default arguments.
.. function:: QueryInfoKey(key)
Returns information about a key, as a tuple.
*key* is an already open key, or one of the predefined
:ref:`HKEY_* constants <hkey-constants>`.
The result is a tuple of 3 items:
+-------+---------------------------------------------+
| Index | Meaning |
+=======+=============================================+
| ``0`` | An integer giving the number of sub keys |
| | this key has. |
+-------+---------------------------------------------+
| ``1`` | An integer giving the number of values this |
| | key has. |
+-------+---------------------------------------------+
| ``2`` | A long integer giving when the key was last |
| | modified (if available) as 100's of |
| | nanoseconds since Jan 1, 1601. |
+-------+---------------------------------------------+
.. function:: QueryValue(key, sub_key)
Retrieves the unnamed value for a key, as a string.
*key* is an already open key, or one of the predefined
:ref:`HKEY_* constants <hkey-constants>`.
*sub_key* is a string that holds the name of the subkey with which the value is
associated. If this parameter is ``None`` or empty, the function retrieves the
value set by the :func:`SetValue` method for the key identified by *key*.
Values in the registry have name, type, and data components. This method
retrieves the data for a key's first value that has a NULL name. But the
underlying API call doesn't return the type, so always use
:func:`QueryValueEx` if possible.
.. function:: QueryValueEx(key, value_name)
Retrieves the type and data for a specified value name associated with
an open registry key.
*key* is an already open key, or one of the predefined
:ref:`HKEY_* constants <hkey-constants>`.
*value_name* is a string indicating the value to query.
The result is a tuple of 2 items:
+-------+-----------------------------------------+
| Index | Meaning |
+=======+=========================================+
| ``0`` | The value of the registry item. |
+-------+-----------------------------------------+
| ``1`` | An integer giving the registry type for |
| | this value (see table in docs for |
| | :meth:`SetValueEx`) |
+-------+-----------------------------------------+
.. function:: SaveKey(key, file_name)
Saves the specified key, and all its subkeys to the specified file.
*key* is an already open key, or one of the predefined
:ref:`HKEY_* constants <hkey-constants>`.
*file_name* is the name of the file to save registry data to. This file
cannot already exist. If this filename includes an extension, it cannot be
used on file allocation table (FAT) file systems by the :meth:`LoadKey`
method.
If *key* represents a key on a remote computer, the path described by
*file_name* is relative to the remote computer. The caller of this method must
possess the :const:`SeBackupPrivilege` security privilege. Note that
privileges are different than permissions -- see the
`Conflicts Between User Rights and Permissions documentation
<http://msdn.microsoft.com/en-us/library/ms724878%28v=VS.85%29.aspx>`__
for more details.
This function passes NULL for *security_attributes* to the API.
.. function:: SetValue(key, sub_key, type, value)
Associates a value with a specified key.
*key* is an already open key, or one of the predefined
:ref:`HKEY_* constants <hkey-constants>`.
*sub_key* is a string that names the subkey with which the value is associated.
*type* is an integer that specifies the type of the data. Currently this must be
:const:`REG_SZ`, meaning only strings are supported. Use the :func:`SetValueEx`
function for support for other data types.
*value* is a string that specifies the new value.
If the key specified by the *sub_key* parameter does not exist, the SetValue
function creates it.
Value lengths are limited by available memory. Long values (more than 2048
bytes) should be stored as files with the filenames stored in the configuration
registry. This helps the registry perform efficiently.
The key identified by the *key* parameter must have been opened with
:const:`KEY_SET_VALUE` access.
.. function:: SetValueEx(key, value_name, reserved, type, value)
Stores data in the value field of an open registry key.
*key* is an already open key, or one of the predefined
:ref:`HKEY_* constants <hkey-constants>`.
*value_name* is a string that names the subkey with which the value is
associated.
*type* is an integer that specifies the type of the data. See
:ref:`Value Types <value-types>` for the available types.
*reserved* can be anything -- zero is always passed to the API.
*value* is a string that specifies the new value.
This method can also set additional value and type information for the specified
key. The key identified by the key parameter must have been opened with
:const:`KEY_SET_VALUE` access.
To open the key, use the :func:`CreateKey` or :func:`OpenKey` methods.
Value lengths are limited by available memory. Long values (more than 2048
bytes) should be stored as files with the filenames stored in the configuration
registry. This helps the registry perform efficiently.
.. function:: DisableReflectionKey(key)
Disables registry reflection for 32-bit processes running on a 64-bit
operating system.
*key* is an already open key, or one of the predefined
:ref:`HKEY_* constants <hkey-constants>`.
Will generally raise :exc:`NotImplemented` if executed on a 32-bit
operating system.
If the key is not on the reflection list, the function succeeds but has no
effect. Disabling reflection for a key does not affect reflection of any
subkeys.
.. function:: EnableReflectionKey(key)
Restores registry reflection for the specified disabled key.
*key* is an already open key, or one of the predefined
:ref:`HKEY_* constants <hkey-constants>`.
Will generally raise :exc:`NotImplemented` if executed on a 32-bit
operating system.
Restoring reflection for a key does not affect reflection of any subkeys.
.. function:: QueryReflectionKey(key)
Determines the reflection state for the specified key.
*key* is an already open key, or one of the predefined
:ref:`HKEY_* constants <hkey-constants>`.
Returns ``True`` if reflection is disabled.
Will generally raise :exc:`NotImplemented` if executed on a 32-bit
operating system.
.. _constants:
Constants
------------------
The following constants are defined for use in many :mod:`_winreg` functions.
.. _hkey-constants:
HKEY_* Constants
++++++++++++++++
.. data:: HKEY_CLASSES_ROOT
Registry entries subordinate to this key define types (or classes) of
documents and the properties associated with those types. Shell and
COM applications use the information stored under this key.
.. data:: HKEY_CURRENT_USER
Registry entries subordinate to this key define the preferences of
the current user. These preferences include the settings of
environment variables, data about program groups, colors, printers,
network connections, and application preferences.
.. data:: HKEY_LOCAL_MACHINE
Registry entries subordinate to this key define the physical state
of the computer, including data about the bus type, system memory,
and installed hardware and software.
.. data:: HKEY_USERS
Registry entries subordinate to this key define the default user
configuration for new users on the local computer and the user
configuration for the current user.
.. data:: HKEY_PERFORMANCE_DATA
Registry entries subordinate to this key allow you to access
performance data. The data is not actually stored in the registry;
the registry functions cause the system to collect the data from
its source.
.. data:: HKEY_CURRENT_CONFIG
Contains information about the current hardware profile of the
local computer system.
.. data:: HKEY_DYN_DATA
This key is not used in versions of Windows after 98.
.. _access-rights:
Access Rights
+++++++++++++
For more information, see `Registry Key Security and Access
<http://msdn.microsoft.com/en-us/library/ms724878%28v=VS.85%29.aspx>`__.
.. data:: KEY_ALL_ACCESS
Combines the STANDARD_RIGHTS_REQUIRED, :const:`KEY_QUERY_VALUE`,
:const:`KEY_SET_VALUE`, :const:`KEY_CREATE_SUB_KEY`,
:const:`KEY_ENUMERATE_SUB_KEYS`, :const:`KEY_NOTIFY`,
and :const:`KEY_CREATE_LINK` access rights.
.. data:: KEY_WRITE
Combines the STANDARD_RIGHTS_WRITE, :const:`KEY_SET_VALUE`, and
:const:`KEY_CREATE_SUB_KEY` access rights.
.. data:: KEY_READ
Combines the STANDARD_RIGHTS_READ, :const:`KEY_QUERY_VALUE`,
:const:`KEY_ENUMERATE_SUB_KEYS`, and :const:`KEY_NOTIFY` values.
.. data:: KEY_EXECUTE
Equivalent to :const:`KEY_READ`.
.. data:: KEY_QUERY_VALUE
Required to query the values of a registry key.
.. data:: KEY_SET_VALUE
Required to create, delete, or set a registry value.
.. data:: KEY_CREATE_SUB_KEY
Required to create a subkey of a registry key.
.. data:: KEY_ENUMERATE_SUB_KEYS
Required to enumerate the subkeys of a registry key.
.. data:: KEY_NOTIFY
Required to request change notifications for a registry key or for
subkeys of a registry key.
.. data:: KEY_CREATE_LINK
Reserved for system use.
.. _64-bit-access-rights:
64-bit Specific
***************
For more information, see `Accessing an Alternate Registry View
<http://msdn.microsoft.com/en-us/library/aa384129(v=VS.85).aspx>`__.
.. data:: KEY_WOW64_64KEY
Indicates that an application on 64-bit Windows should operate on
the 64-bit registry view.
.. data:: KEY_WOW64_32KEY
Indicates that an application on 64-bit Windows should operate on
the 32-bit registry view.
.. _value-types:
Value Types
+++++++++++
For more information, see `Registry Value Types
<http://msdn.microsoft.com/en-us/library/ms724884%28v=VS.85%29.aspx>`__.
.. data:: REG_BINARY
Binary data in any form.
.. data:: REG_DWORD
32-bit number.
.. data:: REG_DWORD_LITTLE_ENDIAN
A 32-bit number in little-endian format.
.. data:: REG_DWORD_BIG_ENDIAN
A 32-bit number in big-endian format.
.. data:: REG_EXPAND_SZ
Null-terminated string containing references to environment
variables (``%PATH%``).
.. data:: REG_LINK
A Unicode symbolic link.
.. data:: REG_MULTI_SZ
A sequence of null-terminated strings, terminated by two null characters.
(Python handles this termination automatically.)
.. data:: REG_NONE
No defined value type.
.. data:: REG_RESOURCE_LIST
A device-driver resource list.
.. data:: REG_FULL_RESOURCE_DESCRIPTOR
A hardware setting.
.. data:: REG_RESOURCE_REQUIREMENTS_LIST
A hardware resource list.
.. data:: REG_SZ
A null-terminated string.
.. _handle-object:
Registry Handle Objects
-----------------------
This object wraps a Windows HKEY object, automatically closing it when the
object is destroyed. To guarantee cleanup, you can call either the
:meth:`~PyHKEY.Close` method on the object, or the :func:`CloseKey` function.
All registry functions in this module return one of these objects.
All registry functions in this module which accept a handle object also accept
an integer, however, use of the handle object is encouraged.
Handle objects provide semantics for :meth:`__nonzero__` -- thus::
if handle:
print "Yes"
will print ``Yes`` if the handle is currently valid (has not been closed or
detached).
The object also support comparison semantics, so handle objects will compare
true if they both reference the same underlying Windows handle value.
Handle objects can be converted to an integer (e.g., using the built-in
:func:`int` function), in which case the underlying Windows handle value is
returned. You can also use the :meth:`~PyHKEY.Detach` method to return the
integer handle, and also disconnect the Windows handle from the handle object.
.. method:: PyHKEY.Close()
Closes the underlying Windows handle.
If the handle is already closed, no error is raised.
.. method:: PyHKEY.Detach()
Detaches the Windows handle from the handle object.
The result is an integer (or long on 64 bit Windows) that holds the value of the
handle before it is detached. If the handle is already detached or closed, this
will return zero.
After calling this function, the handle is effectively invalidated, but the
handle is not closed. You would call this function when you need the
underlying Win32 handle to exist beyond the lifetime of the handle object.
.. method:: PyHKEY.__enter__()
PyHKEY.__exit__(\*exc_info)
The HKEY object implements :meth:`~object.__enter__` and
:meth:`~object.__exit__` and thus supports the context protocol for the
:keyword:`with` statement::
with OpenKey(HKEY_LOCAL_MACHINE, "foo") as key:
... # work with key
will automatically close *key* when control leaves the :keyword:`with` block.
.. versionadded:: 2.6
PK %�\��l3 3 ! html/_sources/library/abc.rst.txtnu �[��� :mod:`abc` --- Abstract Base Classes
====================================
.. module:: abc
:synopsis: Abstract base classes according to PEP 3119.
.. moduleauthor:: Guido van Rossum
.. sectionauthor:: Georg Brandl
.. much of the content adapted from docstrings
.. versionadded:: 2.6
**Source code:** :source:`Lib/abc.py`
--------------
This module provides the infrastructure for defining :term:`abstract base
classes <abstract base class>` (ABCs) in Python, as outlined in :pep:`3119`; see the PEP for why this
was added to Python. (See also :pep:`3141` and the :mod:`numbers` module
regarding a type hierarchy for numbers based on ABCs.)
The :mod:`collections` module has some concrete classes that derive from
ABCs; these can, of course, be further derived. In addition, the
:mod:`collections` module has some ABCs that can be used to test whether
a class or instance provides a particular interface, for example, if it is
hashable or if it is a mapping.
This module provides the following class:
.. class:: ABCMeta
Metaclass for defining Abstract Base Classes (ABCs).
Use this metaclass to create an ABC. An ABC can be subclassed directly, and
then acts as a mix-in class. You can also register unrelated concrete
classes (even built-in classes) and unrelated ABCs as "virtual subclasses" --
these and their descendants will be considered subclasses of the registering
ABC by the built-in :func:`issubclass` function, but the registering ABC
won't show up in their MRO (Method Resolution Order) nor will method
implementations defined by the registering ABC be callable (not even via
:func:`super`). [#]_
Classes created with a metaclass of :class:`ABCMeta` have the following method:
.. method:: register(subclass)
Register *subclass* as a "virtual subclass" of this ABC. For
example::
from abc import ABCMeta
class MyABC:
__metaclass__ = ABCMeta
MyABC.register(tuple)
assert issubclass(tuple, MyABC)
assert isinstance((), MyABC)
You can also override this method in an abstract base class:
.. method:: __subclasshook__(subclass)
(Must be defined as a class method.)
Check whether *subclass* is considered a subclass of this ABC. This means
that you can customize the behavior of ``issubclass`` further without the
need to call :meth:`register` on every class you want to consider a
subclass of the ABC. (This class method is called from the
:meth:`__subclasscheck__` method of the ABC.)
This method should return ``True``, ``False`` or ``NotImplemented``. If
it returns ``True``, the *subclass* is considered a subclass of this ABC.
If it returns ``False``, the *subclass* is not considered a subclass of
this ABC, even if it would normally be one. If it returns
``NotImplemented``, the subclass check is continued with the usual
mechanism.
.. XXX explain the "usual mechanism"
For a demonstration of these concepts, look at this example ABC definition::
class Foo(object):
def __getitem__(self, index):
...
def __len__(self):
...
def get_iterator(self):
return iter(self)
class MyIterable:
__metaclass__ = ABCMeta
@abstractmethod
def __iter__(self):
while False:
yield None
def get_iterator(self):
return self.__iter__()
@classmethod
def __subclasshook__(cls, C):
if cls is MyIterable:
if any("__iter__" in B.__dict__ for B in C.__mro__):
return True
return NotImplemented
MyIterable.register(Foo)
The ABC ``MyIterable`` defines the standard iterable method,
:meth:`~iterator.__iter__`, as an abstract method. The implementation given
here can still be called from subclasses. The :meth:`get_iterator` method
is also part of the ``MyIterable`` abstract base class, but it does not have
to be overridden in non-abstract derived classes.
The :meth:`__subclasshook__` class method defined here says that any class
that has an :meth:`~iterator.__iter__` method in its
:attr:`~object.__dict__` (or in that of one of its base classes, accessed
via the :attr:`~class.__mro__` list) is considered a ``MyIterable`` too.
Finally, the last line makes ``Foo`` a virtual subclass of ``MyIterable``,
even though it does not define an :meth:`~iterator.__iter__` method (it uses
the old-style iterable protocol, defined in terms of :meth:`__len__` and
:meth:`__getitem__`). Note that this will not make ``get_iterator``
available as a method of ``Foo``, so it is provided separately.
It also provides the following decorators:
.. function:: abstractmethod(function)
A decorator indicating abstract methods.
Using this decorator requires that the class's metaclass is :class:`ABCMeta` or
is derived from it.
A class that has a metaclass derived from :class:`ABCMeta`
cannot be instantiated unless all of its abstract methods and
properties are overridden.
The abstract methods can be called using any of the normal 'super' call
mechanisms.
Dynamically adding abstract methods to a class, or attempting to modify the
abstraction status of a method or class once it is created, are not
supported. The :func:`abstractmethod` only affects subclasses derived using
regular inheritance; "virtual subclasses" registered with the ABC's
:meth:`register` method are not affected.
Usage::
class C:
__metaclass__ = ABCMeta
@abstractmethod
def my_abstract_method(self, ...):
...
.. note::
Unlike Java abstract methods, these abstract
methods may have an implementation. This implementation can be
called via the :func:`super` mechanism from the class that
overrides it. This could be useful as an end-point for a
super-call in a framework that uses cooperative
multiple-inheritance.
.. function:: abstractproperty([fget[, fset[, fdel[, doc]]]])
A subclass of the built-in :func:`property`, indicating an abstract property.
Using this function requires that the class's metaclass is :class:`ABCMeta` or
is derived from it.
A class that has a metaclass derived from :class:`ABCMeta` cannot be
instantiated unless all of its abstract methods and properties are overridden.
The abstract properties can be called using any of the normal
'super' call mechanisms.
Usage::
class C:
__metaclass__ = ABCMeta
@abstractproperty
def my_abstract_property(self):
...
This defines a read-only property; you can also define a read-write abstract
property using the 'long' form of property declaration::
class C:
__metaclass__ = ABCMeta
def getx(self): ...
def setx(self, value): ...
x = abstractproperty(getx, setx)
.. rubric:: Footnotes
.. [#] C++ programmers should note that Python's virtual base class
concept is not the same as C++'s.
PK %�\ny�*� � $ html/_sources/library/aepack.rst.txtnu �[���
:mod:`aepack` --- Conversion between Python variables and AppleEvent data containers
====================================================================================
.. module:: aepack
:platform: Mac
:synopsis: Conversion between Python variables and AppleEvent data containers.
:deprecated:
.. sectionauthor:: Vincent Marchetti <vincem@en.com>
.. moduleauthor:: Jack Jansen
The :mod:`aepack` module defines functions for converting (packing) Python
variables to AppleEvent descriptors and back (unpacking). Within Python the
AppleEvent descriptor is handled by Python objects of built-in type
:class:`AEDesc`, defined in module :mod:`Carbon.AE`.
.. note::
This module has been removed in Python 3.x.
The :mod:`aepack` module defines the following functions:
.. function:: pack(x[, forcetype])
Returns an :class:`AEDesc` object containing a conversion of Python value x. If
*forcetype* is provided it specifies the descriptor type of the result.
Otherwise, a default mapping of Python types to Apple Event descriptor types is
used, as follows:
+-----------------+-----------------------------------+
| Python type | descriptor type |
+=================+===================================+
| :class:`FSSpec` | typeFSS |
+-----------------+-----------------------------------+
| :class:`FSRef` | typeFSRef |
+-----------------+-----------------------------------+
| :class:`Alias` | typeAlias |
+-----------------+-----------------------------------+
| integer | typeLong (32 bit integer) |
+-----------------+-----------------------------------+
| float | typeFloat (64 bit floating point) |
+-----------------+-----------------------------------+
| string | typeText |
+-----------------+-----------------------------------+
| unicode | typeUnicodeText |
+-----------------+-----------------------------------+
| list | typeAEList |
+-----------------+-----------------------------------+
| dictionary | typeAERecord |
+-----------------+-----------------------------------+
| instance | *see below* |
+-----------------+-----------------------------------+
If *x* is a Python instance then this function attempts to call an
:meth:`__aepack__` method. This method should return an :class:`AEDesc` object.
If the conversion *x* is not defined above, this function returns the Python
string representation of a value (the repr() function) encoded as a text
descriptor.
.. function:: unpack(x[, formodulename])
*x* must be an object of type :class:`AEDesc`. This function returns a Python
object representation of the data in the Apple Event descriptor *x*. Simple
AppleEvent data types (integer, text, float) are returned as their obvious
Python counterparts. Apple Event lists are returned as Python lists, and the
list elements are recursively unpacked. Object references (ex. ``line 3 of
document 1``) are returned as instances of :class:`aetypes.ObjectSpecifier`,
unless ``formodulename`` is specified. AppleEvent descriptors with descriptor
type typeFSS are returned as :class:`FSSpec` objects. AppleEvent record
descriptors are returned as Python dictionaries, with 4-character string keys
and elements recursively unpacked.
The optional ``formodulename`` argument is used by the stub packages generated
by :mod:`gensuitemodule`, and ensures that the OSA classes for object specifiers
are looked up in the correct module. This ensures that if, say, the Finder
returns an object specifier for a window you get an instance of
``Finder.Window`` and not a generic ``aetypes.Window``. The former knows about
all the properties and elements a window has in the Finder, while the latter
knows no such things.
.. seealso::
Module :mod:`Carbon.AE`
Built-in access to Apple Event Manager routines.
Module :mod:`aetypes`
Python definitions of codes for Apple Event descriptor types.
PK %�\�#e��
�
% html/_sources/library/aetools.rst.txtnu �[���
:mod:`aetools` --- OSA client support
=====================================
.. module:: aetools
:platform: Mac
:synopsis: Basic support for sending Apple Events
:deprecated:
.. sectionauthor:: Jack Jansen <Jack.Jansen@cwi.nl>
.. moduleauthor:: Jack Jansen
The :mod:`aetools` module contains the basic functionality on which Python
AppleScript client support is built. It also imports and re-exports the core
functionality of the :mod:`aetypes` and :mod:`aepack` modules. The stub packages
generated by :mod:`gensuitemodule` import the relevant portions of
:mod:`aetools`, so usually you do not need to import it yourself. The exception
to this is when you cannot use a generated suite package and need lower-level
access to scripting.
The :mod:`aetools` module itself uses the AppleEvent support provided by the
:mod:`Carbon.AE` module. This has one drawback: you need access to the window
manager, see section :ref:`osx-gui-scripts` for details. This restriction may be
lifted in future releases.
.. note::
This module has been removed in Python 3.x.
The :mod:`aetools` module defines the following functions:
.. function:: packevent(ae, parameters, attributes)
Stores parameters and attributes in a pre-created ``Carbon.AE.AEDesc`` object.
``parameters`` and ``attributes`` are dictionaries mapping 4-character OSA
parameter keys to Python objects. The objects are packed using
``aepack.pack()``.
.. function:: unpackevent(ae[, formodulename])
Recursively unpacks a ``Carbon.AE.AEDesc`` event to Python objects. The function
returns the parameter dictionary and the attribute dictionary. The
``formodulename`` argument is used by generated stub packages to control where
AppleScript classes are looked up.
.. function:: keysubst(arguments, keydict)
Converts a Python keyword argument dictionary ``arguments`` to the format
required by ``packevent`` by replacing the keys, which are Python identifiers,
by the four-character OSA keys according to the mapping specified in
``keydict``. Used by the generated suite packages.
.. function:: enumsubst(arguments, key, edict)
If the ``arguments`` dictionary contains an entry for ``key`` convert the value
for that entry according to dictionary ``edict``. This converts human-readable
Python enumeration names to the OSA 4-character codes. Used by the generated
suite packages.
The :mod:`aetools` module defines the following class:
.. class:: TalkTo([signature=None, start=0, timeout=0])
Base class for the proxy used to talk to an application. ``signature`` overrides
the class attribute ``_signature`` (which is usually set by subclasses) and is
the 4-char creator code defining the application to talk to. ``start`` can be
set to true to enable running the application on class instantiation.
``timeout`` can be specified to change the default timeout used while waiting
for an AppleEvent reply.
.. method:: TalkTo._start()
Test whether the application is running, and attempt to start it if not.
.. method:: TalkTo.send(code, subcode[, parameters, attributes])
Create the AppleEvent ``Carbon.AE.AEDesc`` for the verb with the OSA designation
``code, subcode`` (which are the usual 4-character strings), pack the
``parameters`` and ``attributes`` into it, send it to the target application,
wait for the reply, unpack the reply with ``unpackevent`` and return the reply
appleevent, the unpacked return values as a dictionary and the return
attributes.
PK %�\G`�Q� � % html/_sources/library/aetypes.rst.txtnu �[���
:mod:`aetypes` --- AppleEvent objects
=====================================
.. module:: aetypes
:platform: Mac
:synopsis: Python representation of the Apple Event Object Model.
:deprecated:
.. sectionauthor:: Vincent Marchetti <vincem@en.com>
.. moduleauthor:: Jack Jansen
The :mod:`aetypes` defines classes used to represent Apple Event data
descriptors and Apple Event object specifiers.
Apple Event data is contained in descriptors, and these descriptors are typed.
For many descriptors the Python representation is simply the corresponding
Python type: ``typeText`` in OSA is a Python string, ``typeFloat`` is a float,
etc. For OSA types that have no direct Python counterpart this module declares
classes. Packing and unpacking instances of these classes is handled
automatically by :mod:`aepack`.
An object specifier is essentially an address of an object implemented in an
Apple Event server. An Apple Event specifier is used as the direct object for an
Apple Event or as the argument of an optional parameter. The :mod:`aetypes`
module contains the base classes for OSA classes and properties, which are used
by the packages generated by :mod:`gensuitemodule` to populate the classes and
properties in a given suite.
For reasons of backward compatibility, and for cases where you need to script an
application for which you have not generated the stub package this module also
contains object specifiers for a number of common OSA classes such as
``Document``, ``Window``, ``Character``, etc.
.. note::
This module has been removed in Python 3.x.
The :mod:`AEObjects` module defines the following classes to represent Apple
Event descriptor data:
.. class:: Unknown(type, data)
The representation of OSA descriptor data for which the :mod:`aepack` and
:mod:`aetypes` modules have no support, i.e. anything that is not represented by
the other classes here and that is not equivalent to a simple Python value.
.. class:: Enum(enum)
An enumeration value with the given 4-character string value.
.. class:: InsertionLoc(of, pos)
Position ``pos`` in object ``of``.
.. class:: Boolean(bool)
A boolean.
.. class:: StyledText(style, text)
Text with style information (font, face, etc) included.
.. class:: AEText(script, style, text)
Text with script system and style information included.
.. class:: IntlText(script, language, text)
Text with script system and language information included.
.. class:: IntlWritingCode(script, language)
Script system and language information.
.. class:: QDPoint(v, h)
A quickdraw point.
.. class:: QDRectangle(v0, h0, v1, h1)
A quickdraw rectangle.
.. class:: RGBColor(r, g, b)
A color.
.. class:: Type(type)
An OSA type value with the given 4-character name.
.. class:: Keyword(name)
An OSA keyword with the given 4-character name.
.. class:: Range(start, stop)
A range.
.. class:: Ordinal(abso)
Non-numeric absolute positions, such as ``"firs"``, first, or ``"midd"``,
middle.
.. class:: Logical(logc, term)
The logical expression of applying operator ``logc`` to ``term``.
.. class:: Comparison(obj1, relo, obj2)
The comparison ``relo`` of ``obj1`` to ``obj2``.
The following classes are used as base classes by the generated stub packages to
represent AppleScript classes and properties in Python:
.. class:: ComponentItem(which[, fr])
Abstract baseclass for an OSA class. The subclass should set the class attribute
``want`` to the 4-character OSA class code. Instances of subclasses of this
class are equivalent to AppleScript Object Specifiers. Upon instantiation you
should pass a selector in ``which``, and optionally a parent object in ``fr``.
.. class:: NProperty(fr)
Abstract baseclass for an OSA property. The subclass should set the class
attributes ``want`` and ``which`` to designate which property we are talking
about. Instances of subclasses of this class are Object Specifiers.
.. class:: ObjectSpecifier(want, form, seld[, fr])
Base class of ``ComponentItem`` and ``NProperty``, a general OSA Object
Specifier. See the Apple Open Scripting Architecture documentation for the
parameters. Note that this class is not abstract.
PK %�\�
� � " html/_sources/library/aifc.rst.txtnu �[��� :mod:`aifc` --- Read and write AIFF and AIFC files
==================================================
.. module:: aifc
:synopsis: Read and write audio files in AIFF or AIFC format.
.. index::
single: Audio Interchange File Format
single: AIFF
single: AIFF-C
**Source code:** :source:`Lib/aifc.py`
--------------
This module provides support for reading and writing AIFF and AIFF-C files.
AIFF is Audio Interchange File Format, a format for storing digital audio
samples in a file. AIFF-C is a newer version of the format that includes the
ability to compress the audio data.
.. note::
Some operations may only work under IRIX; these will raise :exc:`ImportError`
when attempting to import the :mod:`cl` module, which is only available on
IRIX.
Audio files have a number of parameters that describe the audio data. The
sampling rate or frame rate is the number of times per second the sound is
sampled. The number of channels indicate if the audio is mono, stereo, or
quadro. Each frame consists of one sample per channel. The sample size is the
size in bytes of each sample. Thus a frame consists of
*nchannels*\*\ *samplesize* bytes, and a second's worth of audio consists of
*nchannels*\*\ *samplesize*\*\ *framerate* bytes.
For example, CD quality audio has a sample size of two bytes (16 bits), uses two
channels (stereo) and has a frame rate of 44,100 frames/second. This gives a
frame size of 4 bytes (2\*2), and a second's worth occupies 2\*2\*44100 bytes
(176,400 bytes).
Module :mod:`aifc` defines the following function:
.. function:: open(file[, mode])
Open an AIFF or AIFF-C file and return an object instance with methods that are
described below. The argument *file* is either a string naming a file or a file
object. *mode* must be ``'r'`` or ``'rb'`` when the file must be opened for
reading, or ``'w'`` or ``'wb'`` when the file must be opened for writing. If
omitted, ``file.mode`` is used if it exists, otherwise ``'rb'`` is used. When
used for writing, the file object should be seekable, unless you know ahead of
time how many samples you are going to write in total and use
:meth:`writeframesraw` and :meth:`setnframes`.
Objects returned by :func:`.open` when a file is opened for reading have the
following methods:
.. method:: aifc.getnchannels()
Return the number of audio channels (1 for mono, 2 for stereo).
.. method:: aifc.getsampwidth()
Return the size in bytes of individual samples.
.. method:: aifc.getframerate()
Return the sampling rate (number of audio frames per second).
.. method:: aifc.getnframes()
Return the number of audio frames in the file.
.. method:: aifc.getcomptype()
Return a four-character string describing the type of compression used in the
audio file. For AIFF files, the returned value is ``'NONE'``.
.. method:: aifc.getcompname()
Return a human-readable description of the type of compression used in the audio
file. For AIFF files, the returned value is ``'not compressed'``.
.. method:: aifc.getparams()
Return a tuple consisting of all of the above values in the above order.
.. method:: aifc.getmarkers()
Return a list of markers in the audio file. A marker consists of a tuple of
three elements. The first is the mark ID (an integer), the second is the mark
position in frames from the beginning of the data (an integer), the third is the
name of the mark (a string).
.. method:: aifc.getmark(id)
Return the tuple as described in :meth:`getmarkers` for the mark with the given
*id*.
.. method:: aifc.readframes(nframes)
Read and return the next *nframes* frames from the audio file. The returned
data is a string containing for each frame the uncompressed samples of all
channels.
.. method:: aifc.rewind()
Rewind the read pointer. The next :meth:`readframes` will start from the
beginning.
.. method:: aifc.setpos(pos)
Seek to the specified frame number.
.. method:: aifc.tell()
Return the current frame number.
.. method:: aifc.close()
Close the AIFF file. After calling this method, the object can no longer be
used.
Objects returned by :func:`.open` when a file is opened for writing have all the
above methods, except for :meth:`readframes` and :meth:`setpos`. In addition
the following methods exist. The :meth:`get\*` methods can only be called after
the corresponding :meth:`set\*` methods have been called. Before the first
:meth:`writeframes` or :meth:`writeframesraw`, all parameters except for the
number of frames must be filled in.
.. method:: aifc.aiff()
Create an AIFF file. The default is that an AIFF-C file is created, unless the
name of the file ends in ``'.aiff'`` in which case the default is an AIFF file.
.. method:: aifc.aifc()
Create an AIFF-C file. The default is that an AIFF-C file is created, unless
the name of the file ends in ``'.aiff'`` in which case the default is an AIFF
file.
.. method:: aifc.setnchannels(nchannels)
Specify the number of channels in the audio file.
.. method:: aifc.setsampwidth(width)
Specify the size in bytes of audio samples.
.. method:: aifc.setframerate(rate)
Specify the sampling frequency in frames per second.
.. method:: aifc.setnframes(nframes)
Specify the number of frames that are to be written to the audio file. If this
parameter is not set, or not set correctly, the file needs to support seeking.
.. method:: aifc.setcomptype(type, name)
.. index::
single: u-LAW
single: A-LAW
single: G.722
Specify the compression type. If not specified, the audio data will not be
compressed. In AIFF files, compression is not possible. The name parameter
should be a human-readable description of the compression type, the type
parameter should be a four-character string. Currently the following
compression types are supported: NONE, ULAW, ALAW, G722.
.. method:: aifc.setparams(nchannels, sampwidth, framerate, comptype, compname)
Set all the above parameters at once. The argument is a tuple consisting of the
various parameters. This means that it is possible to use the result of a
:meth:`getparams` call as argument to :meth:`setparams`.
.. method:: aifc.setmark(id, pos, name)
Add a mark with the given id (larger than 0), and the given name at the given
position. This method can be called at any time before :meth:`close`.
.. method:: aifc.tell()
Return the current write position in the output file. Useful in combination
with :meth:`setmark`.
.. method:: aifc.writeframes(data)
Write data to the output file. This method can only be called after the audio
file parameters have been set.
.. method:: aifc.writeframesraw(data)
Like :meth:`writeframes`, except that the header of the audio file is not
updated.
.. method:: aifc.close()
Close the AIFF file. The header of the file is updated to reflect the actual
size of the audio data. After calling this method, the object can no longer be
used.
PK %�\��T� � html/_sources/library/al.rst.txtnu �[���
:mod:`al` --- Audio functions on the SGI
========================================
.. module:: al
:platform: IRIX
:synopsis: Audio functions on the SGI.
:deprecated:
.. deprecated:: 2.6
The :mod:`al` module has been removed in Python 3.
This module provides access to the audio facilities of the SGI Indy and Indigo
workstations. See section 3A of the IRIX man pages for details. You'll need to
read those man pages to understand what these functions do! Some of the
functions are not available in IRIX releases before 4.0.5. Again, see the
manual to check whether a specific function is available on your platform.
All functions and methods defined in this module are equivalent to the C
functions with ``AL`` prefixed to their name.
.. index:: module: AL
Symbolic constants from the C header file ``<audio.h>`` are defined in the
standard module :mod:`AL`, see below.
.. warning::
The current version of the audio library may dump core when bad argument values
are passed rather than returning an error status. Unfortunately, since the
precise circumstances under which this may happen are undocumented and hard to
check, the Python interface can provide no protection against this kind of
problems. (One example is specifying an excessive queue size --- there is no
documented upper limit.)
The module defines the following functions:
.. function:: openport(name, direction[, config])
The name and direction arguments are strings. The optional *config* argument is
a configuration object as returned by :func:`newconfig`. The return value is an
:dfn:`audio port object`; methods of audio port objects are described below.
.. function:: newconfig()
The return value is a new :dfn:`audio configuration object`; methods of audio
configuration objects are described below.
.. function:: queryparams(device)
The device argument is an integer. The return value is a list of integers
containing the data returned by :c:func:`ALqueryparams`.
.. function:: getparams(device, list)
The *device* argument is an integer. The list argument is a list such as
returned by :func:`queryparams`; it is modified in place (!).
.. function:: setparams(device, list)
The *device* argument is an integer. The *list* argument is a list such as
returned by :func:`queryparams`.
.. _al-config-objects:
Configuration Objects
---------------------
Configuration objects returned by :func:`newconfig` have the following methods:
.. method:: audio configuration.getqueuesize()
Return the queue size.
.. method:: audio configuration.setqueuesize(size)
Set the queue size.
.. method:: audio configuration.getwidth()
Get the sample width.
.. method:: audio configuration.setwidth(width)
Set the sample width.
.. method:: audio configuration.getchannels()
Get the channel count.
.. method:: audio configuration.setchannels(nchannels)
Set the channel count.
.. method:: audio configuration.getsampfmt()
Get the sample format.
.. method:: audio configuration.setsampfmt(sampfmt)
Set the sample format.
.. method:: audio configuration.getfloatmax()
Get the maximum value for floating sample formats.
.. method:: audio configuration.setfloatmax(floatmax)
Set the maximum value for floating sample formats.
.. _al-port-objects:
Port Objects
------------
Port objects, as returned by :func:`openport`, have the following methods:
.. method:: audio port.closeport()
Close the port.
.. method:: audio port.getfd()
Return the file descriptor as an int.
.. method:: audio port.getfilled()
Return the number of filled samples.
.. method:: audio port.getfillable()
Return the number of fillable samples.
.. method:: audio port.readsamps(nsamples)
Read a number of samples from the queue, blocking if necessary. Return the data
as a string containing the raw data, (e.g., 2 bytes per sample in big-endian
byte order (high byte, low byte) if you have set the sample width to 2 bytes).
.. method:: audio port.writesamps(samples)
Write samples into the queue, blocking if necessary. The samples are encoded as
described for the :meth:`readsamps` return value.
.. method:: audio port.getfillpoint()
Return the 'fill point'.
.. method:: audio port.setfillpoint(fillpoint)
Set the 'fill point'.
.. method:: audio port.getconfig()
Return a configuration object containing the current configuration of the port.
.. method:: audio port.setconfig(config)
Set the configuration from the argument, a configuration object.
.. method:: audio port.getstatus(list)
Get status information on last error.
:mod:`AL` --- Constants used with the :mod:`al` module
======================================================
.. module:: AL
:platform: IRIX
:synopsis: Constants used with the al module.
:deprecated:
.. deprecated:: 2.6
The :mod:`AL` module has been removed in Python 3.
This module defines symbolic constants needed to use the built-in module
:mod:`al` (see above); they are equivalent to those defined in the C header file
``<audio.h>`` except that the name prefix ``AL_`` is omitted. Read the module
source for a complete list of the defined names. Suggested use::
import al
from AL import *
PK %�\c�#�� � # html/_sources/library/allos.rst.txtnu �[���
.. _allos:
*********************************
Generic Operating System Services
*********************************
The modules described in this chapter provide interfaces to operating system
features that are available on (almost) all operating systems, such as files and
a clock. The interfaces are generally modeled after the Unix or C interfaces,
but they are available on most other systems as well. Here's an overview:
.. toctree::
os.rst
io.rst
time.rst
argparse.rst
optparse.rst
getopt.rst
logging.rst
logging.config.rst
logging.handlers.rst
getpass.rst
curses.rst
curses.ascii.rst
curses.panel.rst
platform.rst
errno.rst
ctypes.rst
PK %�\�vy. $ html/_sources/library/anydbm.rst.txtnu �[��� :mod:`anydbm` --- Generic access to DBM-style databases
=======================================================
.. module:: anydbm
:synopsis: Generic interface to DBM-style database modules.
.. note::
The :mod:`anydbm` module has been renamed to :mod:`dbm` in Python 3. The
:term:`2to3` tool will automatically adapt imports when converting your
sources to Python 3.
.. index::
module: dbhash
module: bsddb
module: gdbm
module: dbm
module: dumbdbm
:mod:`anydbm` is a generic interface to variants of the DBM database ---
:mod:`dbhash` (requires :mod:`bsddb`), :mod:`gdbm`, or :mod:`dbm`. If none of
these modules is installed, the slow-but-simple implementation in module
:mod:`dumbdbm` will be used.
.. function:: open(filename[, flag[, mode]])
Open the database file *filename* and return a corresponding object.
If the database file already exists, the :mod:`whichdb` module is used to
determine its type and the appropriate module is used; if it does not exist,
the first module listed above that can be imported is used.
The optional *flag* argument must be one of these values:
+---------+-------------------------------------------+
| Value | Meaning |
+=========+===========================================+
| ``'r'`` | Open existing database for reading only |
| | (default) |
+---------+-------------------------------------------+
| ``'w'`` | Open existing database for reading and |
| | writing |
+---------+-------------------------------------------+
| ``'c'`` | Open database for reading and writing, |
| | creating it if it doesn't exist |
+---------+-------------------------------------------+
| ``'n'`` | Always create a new, empty database, open |
| | for reading and writing |
+---------+-------------------------------------------+
If not specified, the default value is ``'r'``.
The optional *mode* argument is the Unix mode of the file, used only when the
database has to be created. It defaults to octal ``0666`` (and will be
modified by the prevailing umask).
.. exception:: error
A tuple containing the exceptions that can be raised by each of the supported
modules, with a unique exception also named :exc:`anydbm.error` as the first
item --- the latter is used when :exc:`anydbm.error` is raised.
The object returned by :func:`.open` supports most of the same functionality as
dictionaries; keys and their corresponding values can be stored, retrieved, and
deleted, and the :meth:`has_key` and :meth:`keys` methods are available. Keys
and values must always be strings.
The following example records some hostnames and a corresponding title, and
then prints out the contents of the database::
import anydbm
# Open database, creating it if necessary.
db = anydbm.open('cache', 'c')
# Record some values
db['www.python.org'] = 'Python Website'
db['www.cnn.com'] = 'Cable News Network'
# Loop through contents. Other dictionary methods
# such as .keys(), .values() also work.
for k, v in db.iteritems():
print k, '\t', v
# Storing a non-string key or value will raise an exception (most
# likely a TypeError).
db['www.yahoo.com'] = 4
# Close when done.
db.close()
In addition to the dictionary-like methods, ``anydbm`` objects
provide the following method:
.. function:: close()
Close the ``anydbm`` database.
.. seealso::
Module :mod:`dbhash`
BSD ``db`` database interface.
Module :mod:`dbm`
Standard Unix database interface.
Module :mod:`dumbdbm`
Portable implementation of the ``dbm`` interface.
Module :mod:`gdbm`
GNU database interface, based on the ``dbm`` interface.
Module :mod:`shelve`
General object persistence built on top of the Python ``dbm`` interface.
Module :mod:`whichdb`
Utility module used to determine the type of an existing database.
PK %�\To��� � ' html/_sources/library/archiving.rst.txtnu �[���
.. _archiving:
******************************
Data Compression and Archiving
******************************
The modules described in this chapter support data compression with the zlib,
gzip, and bzip2 algorithms, and the creation of ZIP- and tar-format archives.
See also :ref:`archiving-operations` provided by the :mod:`shutil` module.
.. toctree::
zlib.rst
gzip.rst
bz2.rst
zipfile.rst
tarfile.rst
PK %�\քv��# �# & html/_sources/library/argparse.rst.txtnu �[��� :mod:`argparse` --- Parser for command-line options, arguments and sub-commands
===============================================================================
.. module:: argparse
:synopsis: Command-line option and argument parsing library.
.. moduleauthor:: Steven Bethard <steven.bethard@gmail.com>
.. sectionauthor:: Steven Bethard <steven.bethard@gmail.com>
.. versionadded:: 2.7
**Source code:** :source:`Lib/argparse.py`
--------------
.. sidebar:: Tutorial
This page contains the API reference information. For a more gentle
introduction to Python command-line parsing, have a look at the
:ref:`argparse tutorial <argparse-tutorial>`.
The :mod:`argparse` module makes it easy to write user-friendly command-line
interfaces. The program defines what arguments it requires, and :mod:`argparse`
will figure out how to parse those out of :data:`sys.argv`. The :mod:`argparse`
module also automatically generates help and usage messages and issues errors
when users give the program invalid arguments.
Example
-------
The following code is a Python program that takes a list of integers and
produces either the sum or the max::
import argparse
parser = argparse.ArgumentParser(description='Process some integers.')
parser.add_argument('integers', metavar='N', type=int, nargs='+',
help='an integer for the accumulator')
parser.add_argument('--sum', dest='accumulate', action='store_const',
const=sum, default=max,
help='sum the integers (default: find the max)')
args = parser.parse_args()
print args.accumulate(args.integers)
Assuming the Python code above is saved into a file called ``prog.py``, it can
be run at the command line and provides useful help messages:
.. code-block:: shell-session
$ python prog.py -h
usage: prog.py [-h] [--sum] N [N ...]
Process some integers.
positional arguments:
N an integer for the accumulator
optional arguments:
-h, --help show this help message and exit
--sum sum the integers (default: find the max)
When run with the appropriate arguments, it prints either the sum or the max of
the command-line integers:
.. code-block:: shell-session
$ python prog.py 1 2 3 4
4
$ python prog.py 1 2 3 4 --sum
10
If invalid arguments are passed in, it will issue an error:
.. code-block:: shell-session
$ python prog.py a b c
usage: prog.py [-h] [--sum] N [N ...]
prog.py: error: argument N: invalid int value: 'a'
The following sections walk you through this example.
Creating a parser
^^^^^^^^^^^^^^^^^
The first step in using the :mod:`argparse` is creating an
:class:`ArgumentParser` object::
>>> parser = argparse.ArgumentParser(description='Process some integers.')
The :class:`ArgumentParser` object will hold all the information necessary to
parse the command line into Python data types.
Adding arguments
^^^^^^^^^^^^^^^^
Filling an :class:`ArgumentParser` with information about program arguments is
done by making calls to the :meth:`~ArgumentParser.add_argument` method.
Generally, these calls tell the :class:`ArgumentParser` how to take the strings
on the command line and turn them into objects. This information is stored and
used when :meth:`~ArgumentParser.parse_args` is called. For example::
>>> parser.add_argument('integers', metavar='N', type=int, nargs='+',
... help='an integer for the accumulator')
>>> parser.add_argument('--sum', dest='accumulate', action='store_const',
... const=sum, default=max,
... help='sum the integers (default: find the max)')
Later, calling :meth:`~ArgumentParser.parse_args` will return an object with
two attributes, ``integers`` and ``accumulate``. The ``integers`` attribute
will be a list of one or more ints, and the ``accumulate`` attribute will be
either the :func:`sum` function, if ``--sum`` was specified at the command line,
or the :func:`max` function if it was not.
Parsing arguments
^^^^^^^^^^^^^^^^^
:class:`ArgumentParser` parses arguments through the
:meth:`~ArgumentParser.parse_args` method. This will inspect the command line,
convert each argument to the appropriate type and then invoke the appropriate action.
In most cases, this means a simple :class:`Namespace` object will be built up from
attributes parsed out of the command line::
>>> parser.parse_args(['--sum', '7', '-1', '42'])
Namespace(accumulate=<built-in function sum>, integers=[7, -1, 42])
In a script, :meth:`~ArgumentParser.parse_args` will typically be called with no
arguments, and the :class:`ArgumentParser` will automatically determine the
command-line arguments from :data:`sys.argv`.
ArgumentParser objects
----------------------
.. class:: ArgumentParser(prog=None, usage=None, description=None, \
epilog=None, parents=[], \
formatter_class=argparse.HelpFormatter, \
prefix_chars='-', fromfile_prefix_chars=None, \
argument_default=None, conflict_handler='error', \
add_help=True)
Create a new :class:`ArgumentParser` object. All parameters should be passed
as keyword arguments. Each parameter has its own more detailed description
below, but in short they are:
* prog_ - The name of the program (default: ``sys.argv[0]``)
* usage_ - The string describing the program usage (default: generated from
arguments added to parser)
* description_ - Text to display before the argument help (default: none)
* epilog_ - Text to display after the argument help (default: none)
* parents_ - A list of :class:`ArgumentParser` objects whose arguments should
also be included
* formatter_class_ - A class for customizing the help output
* prefix_chars_ - The set of characters that prefix optional arguments
(default: '-')
* fromfile_prefix_chars_ - The set of characters that prefix files from
which additional arguments should be read (default: ``None``)
* argument_default_ - The global default value for arguments
(default: ``None``)
* conflict_handler_ - The strategy for resolving conflicting optionals
(usually unnecessary)
* add_help_ - Add a ``-h/--help`` option to the parser (default: ``True``)
The following sections describe how each of these are used.
prog
^^^^
By default, :class:`ArgumentParser` objects use ``sys.argv[0]`` to determine
how to display the name of the program in help messages. This default is almost
always desirable because it will make the help messages match how the program was
invoked on the command line. For example, consider a file named
``myprogram.py`` with the following code::
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--foo', help='foo help')
args = parser.parse_args()
The help for this program will display ``myprogram.py`` as the program name
(regardless of where the program was invoked from):
.. code-block:: shell-session
$ python myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]
optional arguments:
-h, --help show this help message and exit
--foo FOO foo help
$ cd ..
$ python subdir/myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]
optional arguments:
-h, --help show this help message and exit
--foo FOO foo help
To change this default behavior, another value can be supplied using the
``prog=`` argument to :class:`ArgumentParser`::
>>> parser = argparse.ArgumentParser(prog='myprogram')
>>> parser.print_help()
usage: myprogram [-h]
optional arguments:
-h, --help show this help message and exit
Note that the program name, whether determined from ``sys.argv[0]`` or from the
``prog=`` argument, is available to help messages using the ``%(prog)s`` format
specifier.
::
>>> parser = argparse.ArgumentParser(prog='myprogram')
>>> parser.add_argument('--foo', help='foo of the %(prog)s program')
>>> parser.print_help()
usage: myprogram [-h] [--foo FOO]
optional arguments:
-h, --help show this help message and exit
--foo FOO foo of the myprogram program
usage
^^^^^
By default, :class:`ArgumentParser` calculates the usage message from the
arguments it contains::
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo', nargs='?', help='foo help')
>>> parser.add_argument('bar', nargs='+', help='bar help')
>>> parser.print_help()
usage: PROG [-h] [--foo [FOO]] bar [bar ...]
positional arguments:
bar bar help
optional arguments:
-h, --help show this help message and exit
--foo [FOO] foo help
The default message can be overridden with the ``usage=`` keyword argument::
>>> parser = argparse.ArgumentParser(prog='PROG', usage='%(prog)s [options]')
>>> parser.add_argument('--foo', nargs='?', help='foo help')
>>> parser.add_argument('bar', nargs='+', help='bar help')
>>> parser.print_help()
usage: PROG [options]
positional arguments:
bar bar help
optional arguments:
-h, --help show this help message and exit
--foo [FOO] foo help
The ``%(prog)s`` format specifier is available to fill in the program name in
your usage messages.
description
^^^^^^^^^^^
Most calls to the :class:`ArgumentParser` constructor will use the
``description=`` keyword argument. This argument gives a brief description of
what the program does and how it works. In help messages, the description is
displayed between the command-line usage string and the help messages for the
various arguments::
>>> parser = argparse.ArgumentParser(description='A foo that bars')
>>> parser.print_help()
usage: argparse.py [-h]
A foo that bars
optional arguments:
-h, --help show this help message and exit
By default, the description will be line-wrapped so that it fits within the
given space. To change this behavior, see the formatter_class_ argument.
epilog
^^^^^^
Some programs like to display additional description of the program after the
description of the arguments. Such text can be specified using the ``epilog=``
argument to :class:`ArgumentParser`::
>>> parser = argparse.ArgumentParser(
... description='A foo that bars',
... epilog="And that's how you'd foo a bar")
>>> parser.print_help()
usage: argparse.py [-h]
A foo that bars
optional arguments:
-h, --help show this help message and exit
And that's how you'd foo a bar
As with the description_ argument, the ``epilog=`` text is by default
line-wrapped, but this behavior can be adjusted with the formatter_class_
argument to :class:`ArgumentParser`.
parents
^^^^^^^
Sometimes, several parsers share a common set of arguments. Rather than
repeating the definitions of these arguments, a single parser with all the
shared arguments and passed to ``parents=`` argument to :class:`ArgumentParser`
can be used. The ``parents=`` argument takes a list of :class:`ArgumentParser`
objects, collects all the positional and optional actions from them, and adds
these actions to the :class:`ArgumentParser` object being constructed::
>>> parent_parser = argparse.ArgumentParser(add_help=False)
>>> parent_parser.add_argument('--parent', type=int)
>>> foo_parser = argparse.ArgumentParser(parents=[parent_parser])
>>> foo_parser.add_argument('foo')
>>> foo_parser.parse_args(['--parent', '2', 'XXX'])
Namespace(foo='XXX', parent=2)
>>> bar_parser = argparse.ArgumentParser(parents=[parent_parser])
>>> bar_parser.add_argument('--bar')
>>> bar_parser.parse_args(['--bar', 'YYY'])
Namespace(bar='YYY', parent=None)
Note that most parent parsers will specify ``add_help=False``. Otherwise, the
:class:`ArgumentParser` will see two ``-h/--help`` options (one in the parent
and one in the child) and raise an error.
.. note::
You must fully initialize the parsers before passing them via ``parents=``.
If you change the parent parsers after the child parser, those changes will
not be reflected in the child.
formatter_class
^^^^^^^^^^^^^^^
:class:`ArgumentParser` objects allow the help formatting to be customized by
specifying an alternate formatting class. Currently, there are three such
classes:
.. class:: RawDescriptionHelpFormatter
RawTextHelpFormatter
ArgumentDefaultsHelpFormatter
The first two allow more control over how textual descriptions are displayed,
while the last automatically adds information about argument default values.
By default, :class:`ArgumentParser` objects line-wrap the description_ and
epilog_ texts in command-line help messages::
>>> parser = argparse.ArgumentParser(
... prog='PROG',
... description='''this description
... was indented weird
... but that is okay''',
... epilog='''
... likewise for this epilog whose whitespace will
... be cleaned up and whose words will be wrapped
... across a couple lines''')
>>> parser.print_help()
usage: PROG [-h]
this description was indented weird but that is okay
optional arguments:
-h, --help show this help message and exit
likewise for this epilog whose whitespace will be cleaned up and whose words
will be wrapped across a couple lines
Passing :class:`RawDescriptionHelpFormatter` as ``formatter_class=``
indicates that description_ and epilog_ are already correctly formatted and
should not be line-wrapped::
>>> parser = argparse.ArgumentParser(
... prog='PROG',
... formatter_class=argparse.RawDescriptionHelpFormatter,
... description=textwrap.dedent('''\
... Please do not mess up this text!
... --------------------------------
... I have indented it
... exactly the way
... I want it
... '''))
>>> parser.print_help()
usage: PROG [-h]
Please do not mess up this text!
--------------------------------
I have indented it
exactly the way
I want it
optional arguments:
-h, --help show this help message and exit
:class:`RawTextHelpFormatter` maintains whitespace for all sorts of help text,
including argument descriptions. However, multiple new lines are replaced with
one. If you wish to preserve multiple blank lines, add spaces between the
newlines.
The other formatter class available, :class:`ArgumentDefaultsHelpFormatter`,
will add information about the default value of each of the arguments::
>>> parser = argparse.ArgumentParser(
... prog='PROG',
... formatter_class=argparse.ArgumentDefaultsHelpFormatter)
>>> parser.add_argument('--foo', type=int, default=42, help='FOO!')
>>> parser.add_argument('bar', nargs='*', default=[1, 2, 3], help='BAR!')
>>> parser.print_help()
usage: PROG [-h] [--foo FOO] [bar [bar ...]]
positional arguments:
bar BAR! (default: [1, 2, 3])
optional arguments:
-h, --help show this help message and exit
--foo FOO FOO! (default: 42)
prefix_chars
^^^^^^^^^^^^
Most command-line options will use ``-`` as the prefix, e.g. ``-f/--foo``.
Parsers that need to support different or additional prefix
characters, e.g. for options
like ``+f`` or ``/foo``, may specify them using the ``prefix_chars=`` argument
to the ArgumentParser constructor::
>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='-+')
>>> parser.add_argument('+f')
>>> parser.add_argument('++bar')
>>> parser.parse_args('+f X ++bar Y'.split())
Namespace(bar='Y', f='X')
The ``prefix_chars=`` argument defaults to ``'-'``. Supplying a set of
characters that does not include ``-`` will cause ``-f/--foo`` options to be
disallowed.
fromfile_prefix_chars
^^^^^^^^^^^^^^^^^^^^^
Sometimes, for example when dealing with a particularly long argument lists, it
may make sense to keep the list of arguments in a file rather than typing it out
at the command line. If the ``fromfile_prefix_chars=`` argument is given to the
:class:`ArgumentParser` constructor, then arguments that start with any of the
specified characters will be treated as files, and will be replaced by the
arguments they contain. For example::
>>> with open('args.txt', 'w') as fp:
... fp.write('-f\nbar')
>>> parser = argparse.ArgumentParser(fromfile_prefix_chars='@')
>>> parser.add_argument('-f')
>>> parser.parse_args(['-f', 'foo', '@args.txt'])
Namespace(f='bar')
Arguments read from a file must by default be one per line (but see also
:meth:`~ArgumentParser.convert_arg_line_to_args`) and are treated as if they
were in the same place as the original file referencing argument on the command
line. So in the example above, the expression ``['-f', 'foo', '@args.txt']``
is considered equivalent to the expression ``['-f', 'foo', '-f', 'bar']``.
The ``fromfile_prefix_chars=`` argument defaults to ``None``, meaning that
arguments will never be treated as file references.
argument_default
^^^^^^^^^^^^^^^^
Generally, argument defaults are specified either by passing a default to
:meth:`~ArgumentParser.add_argument` or by calling the
:meth:`~ArgumentParser.set_defaults` methods with a specific set of name-value
pairs. Sometimes however, it may be useful to specify a single parser-wide
default for arguments. This can be accomplished by passing the
``argument_default=`` keyword argument to :class:`ArgumentParser`. For example,
to globally suppress attribute creation on :meth:`~ArgumentParser.parse_args`
calls, we supply ``argument_default=SUPPRESS``::
>>> parser = argparse.ArgumentParser(argument_default=argparse.SUPPRESS)
>>> parser.add_argument('--foo')
>>> parser.add_argument('bar', nargs='?')
>>> parser.parse_args(['--foo', '1', 'BAR'])
Namespace(bar='BAR', foo='1')
>>> parser.parse_args([])
Namespace()
conflict_handler
^^^^^^^^^^^^^^^^
:class:`ArgumentParser` objects do not allow two actions with the same option
string. By default, :class:`ArgumentParser` objects raise an exception if an
attempt is made to create an argument with an option string that is already in
use::
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-f', '--foo', help='old foo help')
>>> parser.add_argument('--foo', help='new foo help')
Traceback (most recent call last):
..
ArgumentError: argument --foo: conflicting option string(s): --foo
Sometimes (e.g. when using parents_) it may be useful to simply override any
older arguments with the same option string. To get this behavior, the value
``'resolve'`` can be supplied to the ``conflict_handler=`` argument of
:class:`ArgumentParser`::
>>> parser = argparse.ArgumentParser(prog='PROG', conflict_handler='resolve')
>>> parser.add_argument('-f', '--foo', help='old foo help')
>>> parser.add_argument('--foo', help='new foo help')
>>> parser.print_help()
usage: PROG [-h] [-f FOO] [--foo FOO]
optional arguments:
-h, --help show this help message and exit
-f FOO old foo help
--foo FOO new foo help
Note that :class:`ArgumentParser` objects only remove an action if all of its
option strings are overridden. So, in the example above, the old ``-f/--foo``
action is retained as the ``-f`` action, because only the ``--foo`` option
string was overridden.
add_help
^^^^^^^^
By default, ArgumentParser objects add an option which simply displays
the parser's help message. For example, consider a file named
``myprogram.py`` containing the following code::
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--foo', help='foo help')
args = parser.parse_args()
If ``-h`` or ``--help`` is supplied at the command line, the ArgumentParser
help will be printed:
.. code-block:: shell-session
$ python myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]
optional arguments:
-h, --help show this help message and exit
--foo FOO foo help
Occasionally, it may be useful to disable the addition of this help option.
This can be achieved by passing ``False`` as the ``add_help=`` argument to
:class:`ArgumentParser`::
>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
>>> parser.add_argument('--foo', help='foo help')
>>> parser.print_help()
usage: PROG [--foo FOO]
optional arguments:
--foo FOO foo help
The help option is typically ``-h/--help``. The exception to this is
if the ``prefix_chars=`` is specified and does not include ``-``, in
which case ``-h`` and ``--help`` are not valid options. In
this case, the first character in ``prefix_chars`` is used to prefix
the help options::
>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='+/')
>>> parser.print_help()
usage: PROG [+h]
optional arguments:
+h, ++help show this help message and exit
The add_argument() method
-------------------------
.. method:: ArgumentParser.add_argument(name or flags..., [action], [nargs], \
[const], [default], [type], [choices], [required], \
[help], [metavar], [dest])
Define how a single command-line argument should be parsed. Each parameter
has its own more detailed description below, but in short they are:
* `name or flags`_ - Either a name or a list of option strings, e.g. ``foo``
or ``-f, --foo``.
* action_ - The basic type of action to be taken when this argument is
encountered at the command line.
* nargs_ - The number of command-line arguments that should be consumed.
* const_ - A constant value required by some action_ and nargs_ selections.
* default_ - The value produced if the argument is absent from the
command line.
* type_ - The type to which the command-line argument should be converted.
* choices_ - A container of the allowable values for the argument.
* required_ - Whether or not the command-line option may be omitted
(optionals only).
* help_ - A brief description of what the argument does.
* metavar_ - A name for the argument in usage messages.
* dest_ - The name of the attribute to be added to the object returned by
:meth:`parse_args`.
The following sections describe how each of these are used.
name or flags
^^^^^^^^^^^^^
The :meth:`~ArgumentParser.add_argument` method must know whether an optional
argument, like ``-f`` or ``--foo``, or a positional argument, like a list of
filenames, is expected. The first arguments passed to
:meth:`~ArgumentParser.add_argument` must therefore be either a series of
flags, or a simple argument name. For example, an optional argument could
be created like::
>>> parser.add_argument('-f', '--foo')
while a positional argument could be created like::
>>> parser.add_argument('bar')
When :meth:`~ArgumentParser.parse_args` is called, optional arguments will be
identified by the ``-`` prefix, and the remaining arguments will be assumed to
be positional::
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-f', '--foo')
>>> parser.add_argument('bar')
>>> parser.parse_args(['BAR'])
Namespace(bar='BAR', foo=None)
>>> parser.parse_args(['BAR', '--foo', 'FOO'])
Namespace(bar='BAR', foo='FOO')
>>> parser.parse_args(['--foo', 'FOO'])
usage: PROG [-h] [-f FOO] bar
PROG: error: too few arguments
action
^^^^^^
:class:`ArgumentParser` objects associate command-line arguments with actions. These
actions can do just about anything with the command-line arguments associated with
them, though most actions simply add an attribute to the object returned by
:meth:`~ArgumentParser.parse_args`. The ``action`` keyword argument specifies
how the command-line arguments should be handled. The supplied actions are:
* ``'store'`` - This just stores the argument's value. This is the default
action. For example::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.parse_args('--foo 1'.split())
Namespace(foo='1')
* ``'store_const'`` - This stores the value specified by the const_ keyword
argument. The ``'store_const'`` action is most commonly used with
optional arguments that specify some sort of flag. For example::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='store_const', const=42)
>>> parser.parse_args(['--foo'])
Namespace(foo=42)
* ``'store_true'`` and ``'store_false'`` - These are special cases of
``'store_const'`` using for storing the values ``True`` and ``False``
respectively. In addition, they create default values of ``False`` and ``True``
respectively. For example::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='store_true')
>>> parser.add_argument('--bar', action='store_false')
>>> parser.add_argument('--baz', action='store_false')
>>> parser.parse_args('--foo --bar'.split())
Namespace(bar=False, baz=True, foo=True)
* ``'append'`` - This stores a list, and appends each argument value to the
list. This is useful to allow an option to be specified multiple times.
Example usage::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='append')
>>> parser.parse_args('--foo 1 --foo 2'.split())
Namespace(foo=['1', '2'])
* ``'append_const'`` - This stores a list, and appends the value specified by
the const_ keyword argument to the list. (Note that the const_ keyword
argument defaults to ``None``.) The ``'append_const'`` action is typically
useful when multiple arguments need to store constants to the same list. For
example::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--str', dest='types', action='append_const', const=str)
>>> parser.add_argument('--int', dest='types', action='append_const', const=int)
>>> parser.parse_args('--str --int'.split())
Namespace(types=[<type 'str'>, <type 'int'>])
* ``'count'`` - This counts the number of times a keyword argument occurs. For
example, this is useful for increasing verbosity levels::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--verbose', '-v', action='count')
>>> parser.parse_args(['-vvv'])
Namespace(verbose=3)
* ``'help'`` - This prints a complete help message for all the options in the
current parser and then exits. By default a help action is automatically
added to the parser. See :class:`ArgumentParser` for details of how the
output is created.
* ``'version'`` - This expects a ``version=`` keyword argument in the
:meth:`~ArgumentParser.add_argument` call, and prints version information
and exits when invoked::
>>> import argparse
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--version', action='version', version='%(prog)s 2.0')
>>> parser.parse_args(['--version'])
PROG 2.0
You may also specify an arbitrary action by passing an Action subclass or
other object that implements the same interface. The recommended way to do
this is to extend :class:`Action`, overriding the ``__call__`` method
and optionally the ``__init__`` method.
An example of a custom action::
>>> class FooAction(argparse.Action):
... def __init__(self, option_strings, dest, nargs=None, **kwargs):
... if nargs is not None:
... raise ValueError("nargs not allowed")
... super(FooAction, self).__init__(option_strings, dest, **kwargs)
... def __call__(self, parser, namespace, values, option_string=None):
... print '%r %r %r' % (namespace, values, option_string)
... setattr(namespace, self.dest, values)
...
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action=FooAction)
>>> parser.add_argument('bar', action=FooAction)
>>> args = parser.parse_args('1 --foo 2'.split())
Namespace(bar=None, foo=None) '1' None
Namespace(bar='1', foo=None) '2' '--foo'
>>> args
Namespace(bar='1', foo='2')
For more details, see :class:`Action`.
nargs
^^^^^
ArgumentParser objects usually associate a single command-line argument with a
single action to be taken. The ``nargs`` keyword argument associates a
different number of command-line arguments with a single action. The supported
values are:
* ``N`` (an integer). ``N`` arguments from the command line will be gathered
together into a list. For example::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', nargs=2)
>>> parser.add_argument('bar', nargs=1)
>>> parser.parse_args('c --foo a b'.split())
Namespace(bar=['c'], foo=['a', 'b'])
Note that ``nargs=1`` produces a list of one item. This is different from
the default, in which the item is produced by itself.
* ``'?'``. One argument will be consumed from the command line if possible, and
produced as a single item. If no command-line argument is present, the value from
default_ will be produced. Note that for optional arguments, there is an
additional case - the option string is present but not followed by a
command-line argument. In this case the value from const_ will be produced. Some
examples to illustrate this::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', nargs='?', const='c', default='d')
>>> parser.add_argument('bar', nargs='?', default='d')
>>> parser.parse_args(['XX', '--foo', 'YY'])
Namespace(bar='XX', foo='YY')
>>> parser.parse_args(['XX', '--foo'])
Namespace(bar='XX', foo='c')
>>> parser.parse_args([])
Namespace(bar='d', foo='d')
One of the more common uses of ``nargs='?'`` is to allow optional input and
output files::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('infile', nargs='?', type=argparse.FileType('r'),
... default=sys.stdin)
>>> parser.add_argument('outfile', nargs='?', type=argparse.FileType('w'),
... default=sys.stdout)
>>> parser.parse_args(['input.txt', 'output.txt'])
Namespace(infile=<open file 'input.txt', mode 'r' at 0x...>,
outfile=<open file 'output.txt', mode 'w' at 0x...>)
>>> parser.parse_args([])
Namespace(infile=<open file '<stdin>', mode 'r' at 0x...>,
outfile=<open file '<stdout>', mode 'w' at 0x...>)
* ``'*'``. All command-line arguments present are gathered into a list. Note that
it generally doesn't make much sense to have more than one positional argument
with ``nargs='*'``, but multiple optional arguments with ``nargs='*'`` is
possible. For example::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', nargs='*')
>>> parser.add_argument('--bar', nargs='*')
>>> parser.add_argument('baz', nargs='*')
>>> parser.parse_args('a b --foo x y --bar 1 2'.split())
Namespace(bar=['1', '2'], baz=['a', 'b'], foo=['x', 'y'])
* ``'+'``. Just like ``'*'``, all command-line args present are gathered into a
list. Additionally, an error message will be generated if there wasn't at
least one command-line argument present. For example::
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('foo', nargs='+')
>>> parser.parse_args(['a', 'b'])
Namespace(foo=['a', 'b'])
>>> parser.parse_args([])
usage: PROG [-h] foo [foo ...]
PROG: error: too few arguments
.. _`argparse.REMAINDER`:
* ``argparse.REMAINDER``. All the remaining command-line arguments are gathered
into a list. This is commonly useful for command line utilities that dispatch
to other command line utilities::
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo')
>>> parser.add_argument('command')
>>> parser.add_argument('args', nargs=argparse.REMAINDER)
>>> print parser.parse_args('--foo B cmd --arg1 XX ZZ'.split())
Namespace(args=['--arg1', 'XX', 'ZZ'], command='cmd', foo='B')
If the ``nargs`` keyword argument is not provided, the number of arguments consumed
is determined by the action_. Generally this means a single command-line argument
will be consumed and a single item (not a list) will be produced.
const
^^^^^
The ``const`` argument of :meth:`~ArgumentParser.add_argument` is used to hold
constant values that are not read from the command line but are required for
the various :class:`ArgumentParser` actions. The two most common uses of it are:
* When :meth:`~ArgumentParser.add_argument` is called with
``action='store_const'`` or ``action='append_const'``. These actions add the
``const`` value to one of the attributes of the object returned by
:meth:`~ArgumentParser.parse_args`. See the action_ description for examples.
* When :meth:`~ArgumentParser.add_argument` is called with option strings
(like ``-f`` or ``--foo``) and ``nargs='?'``. This creates an optional
argument that can be followed by zero or one command-line arguments.
When parsing the command line, if the option string is encountered with no
command-line argument following it, the value of ``const`` will be assumed instead.
See the nargs_ description for examples.
With the ``'store_const'`` and ``'append_const'`` actions, the ``const``
keyword argument must be given. For other actions, it defaults to ``None``.
default
^^^^^^^
All optional arguments and some positional arguments may be omitted at the
command line. The ``default`` keyword argument of
:meth:`~ArgumentParser.add_argument`, whose value defaults to ``None``,
specifies what value should be used if the command-line argument is not present.
For optional arguments, the ``default`` value is used when the option string
was not present at the command line::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=42)
>>> parser.parse_args(['--foo', '2'])
Namespace(foo='2')
>>> parser.parse_args([])
Namespace(foo=42)
If the ``default`` value is a string, the parser parses the value as if it
were a command-line argument. In particular, the parser applies any type_
conversion argument, if provided, before setting the attribute on the
:class:`Namespace` return value. Otherwise, the parser uses the value as is::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--length', default='10', type=int)
>>> parser.add_argument('--width', default=10.5, type=int)
>>> parser.parse_args()
Namespace(length=10, width=10.5)
For positional arguments with nargs_ equal to ``?`` or ``*``, the ``default`` value
is used when no command-line argument was present::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('foo', nargs='?', default=42)
>>> parser.parse_args(['a'])
Namespace(foo='a')
>>> parser.parse_args([])
Namespace(foo=42)
Providing ``default=argparse.SUPPRESS`` causes no attribute to be added if the
command-line argument was not present.::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=argparse.SUPPRESS)
>>> parser.parse_args([])
Namespace()
>>> parser.parse_args(['--foo', '1'])
Namespace(foo='1')
type
^^^^
By default, :class:`ArgumentParser` objects read command-line arguments in as simple
strings. However, quite often the command-line string should instead be
interpreted as another type, like a :class:`float` or :class:`int`. The
``type`` keyword argument of :meth:`~ArgumentParser.add_argument` allows any
necessary type-checking and type conversions to be performed. Common built-in
types and functions can be used directly as the value of the ``type`` argument::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('foo', type=int)
>>> parser.add_argument('bar', type=file)
>>> parser.parse_args('2 temp.txt'.split())
Namespace(bar=<open file 'temp.txt', mode 'r' at 0x...>, foo=2)
See the section on the default_ keyword argument for information on when the
``type`` argument is applied to default arguments.
To ease the use of various types of files, the argparse module provides the
factory FileType which takes the ``mode=`` and ``bufsize=`` arguments of the
``file`` object. For example, ``FileType('w')`` can be used to create a
writable file::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('bar', type=argparse.FileType('w'))
>>> parser.parse_args(['out.txt'])
Namespace(bar=<open file 'out.txt', mode 'w' at 0x...>)
``type=`` can take any callable that takes a single string argument and returns
the converted value::
>>> def perfect_square(string):
... value = int(string)
... sqrt = math.sqrt(value)
... if sqrt != int(sqrt):
... msg = "%r is not a perfect square" % string
... raise argparse.ArgumentTypeError(msg)
... return value
...
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('foo', type=perfect_square)
>>> parser.parse_args(['9'])
Namespace(foo=9)
>>> parser.parse_args(['7'])
usage: PROG [-h] foo
PROG: error: argument foo: '7' is not a perfect square
The choices_ keyword argument may be more convenient for type checkers that
simply check against a range of values::
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('foo', type=int, choices=xrange(5, 10))
>>> parser.parse_args(['7'])
Namespace(foo=7)
>>> parser.parse_args(['11'])
usage: PROG [-h] {5,6,7,8,9}
PROG: error: argument foo: invalid choice: 11 (choose from 5, 6, 7, 8, 9)
See the choices_ section for more details.
choices
^^^^^^^
Some command-line arguments should be selected from a restricted set of values.
These can be handled by passing a container object as the *choices* keyword
argument to :meth:`~ArgumentParser.add_argument`. When the command line is
parsed, argument values will be checked, and an error message will be displayed
if the argument was not one of the acceptable values::
>>> parser = argparse.ArgumentParser(prog='game.py')
>>> parser.add_argument('move', choices=['rock', 'paper', 'scissors'])
>>> parser.parse_args(['rock'])
Namespace(move='rock')
>>> parser.parse_args(['fire'])
usage: game.py [-h] {rock,paper,scissors}
game.py: error: argument move: invalid choice: 'fire' (choose from 'rock',
'paper', 'scissors')
Note that inclusion in the *choices* container is checked after any type_
conversions have been performed, so the type of the objects in the *choices*
container should match the type_ specified::
>>> parser = argparse.ArgumentParser(prog='doors.py')
>>> parser.add_argument('door', type=int, choices=range(1, 4))
>>> print(parser.parse_args(['3']))
Namespace(door=3)
>>> parser.parse_args(['4'])
usage: doors.py [-h] {1,2,3}
doors.py: error: argument door: invalid choice: 4 (choose from 1, 2, 3)
Any object that supports the ``in`` operator can be passed as the *choices*
value, so :class:`dict` objects, :class:`set` objects, custom containers,
etc. are all supported.
required
^^^^^^^^
In general, the :mod:`argparse` module assumes that flags like ``-f`` and ``--bar``
indicate *optional* arguments, which can always be omitted at the command line.
To make an option *required*, ``True`` can be specified for the ``required=``
keyword argument to :meth:`~ArgumentParser.add_argument`::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', required=True)
>>> parser.parse_args(['--foo', 'BAR'])
Namespace(foo='BAR')
>>> parser.parse_args([])
usage: argparse.py [-h] [--foo FOO]
argparse.py: error: option --foo is required
As the example shows, if an option is marked as ``required``,
:meth:`~ArgumentParser.parse_args` will report an error if that option is not
present at the command line.
.. note::
Required options are generally considered bad form because users expect
*options* to be *optional*, and thus they should be avoided when possible.
help
^^^^
The ``help`` value is a string containing a brief description of the argument.
When a user requests help (usually by using ``-h`` or ``--help`` at the
command line), these ``help`` descriptions will be displayed with each
argument::
>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('--foo', action='store_true',
... help='foo the bars before frobbling')
>>> parser.add_argument('bar', nargs='+',
... help='one of the bars to be frobbled')
>>> parser.parse_args(['-h'])
usage: frobble [-h] [--foo] bar [bar ...]
positional arguments:
bar one of the bars to be frobbled
optional arguments:
-h, --help show this help message and exit
--foo foo the bars before frobbling
The ``help`` strings can include various format specifiers to avoid repetition
of things like the program name or the argument default_. The available
specifiers include the program name, ``%(prog)s`` and most keyword arguments to
:meth:`~ArgumentParser.add_argument`, e.g. ``%(default)s``, ``%(type)s``, etc.::
>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('bar', nargs='?', type=int, default=42,
... help='the bar to %(prog)s (default: %(default)s)')
>>> parser.print_help()
usage: frobble [-h] [bar]
positional arguments:
bar the bar to frobble (default: 42)
optional arguments:
-h, --help show this help message and exit
:mod:`argparse` supports silencing the help entry for certain options, by
setting the ``help`` value to ``argparse.SUPPRESS``::
>>> parser = argparse.ArgumentParser(prog='frobble')
>>> parser.add_argument('--foo', help=argparse.SUPPRESS)
>>> parser.print_help()
usage: frobble [-h]
optional arguments:
-h, --help show this help message and exit
metavar
^^^^^^^
When :class:`ArgumentParser` generates help messages, it needs some way to refer
to each expected argument. By default, ArgumentParser objects use the dest_
value as the "name" of each object. By default, for positional argument
actions, the dest_ value is used directly, and for optional argument actions,
the dest_ value is uppercased. So, a single positional argument with
``dest='bar'`` will be referred to as ``bar``. A single
optional argument ``--foo`` that should be followed by a single command-line argument
will be referred to as ``FOO``. An example::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.add_argument('bar')
>>> parser.parse_args('X --foo Y'.split())
Namespace(bar='X', foo='Y')
>>> parser.print_help()
usage: [-h] [--foo FOO] bar
positional arguments:
bar
optional arguments:
-h, --help show this help message and exit
--foo FOO
An alternative name can be specified with ``metavar``::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', metavar='YYY')
>>> parser.add_argument('bar', metavar='XXX')
>>> parser.parse_args('X --foo Y'.split())
Namespace(bar='X', foo='Y')
>>> parser.print_help()
usage: [-h] [--foo YYY] XXX
positional arguments:
XXX
optional arguments:
-h, --help show this help message and exit
--foo YYY
Note that ``metavar`` only changes the *displayed* name - the name of the
attribute on the :meth:`~ArgumentParser.parse_args` object is still determined
by the dest_ value.
Different values of ``nargs`` may cause the metavar to be used multiple times.
Providing a tuple to ``metavar`` specifies a different display for each of the
arguments::
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x', nargs=2)
>>> parser.add_argument('--foo', nargs=2, metavar=('bar', 'baz'))
>>> parser.print_help()
usage: PROG [-h] [-x X X] [--foo bar baz]
optional arguments:
-h, --help show this help message and exit
-x X X
--foo bar baz
dest
^^^^
Most :class:`ArgumentParser` actions add some value as an attribute of the
object returned by :meth:`~ArgumentParser.parse_args`. The name of this
attribute is determined by the ``dest`` keyword argument of
:meth:`~ArgumentParser.add_argument`. For positional argument actions,
``dest`` is normally supplied as the first argument to
:meth:`~ArgumentParser.add_argument`::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('bar')
>>> parser.parse_args(['XXX'])
Namespace(bar='XXX')
For optional argument actions, the value of ``dest`` is normally inferred from
the option strings. :class:`ArgumentParser` generates the value of ``dest`` by
taking the first long option string and stripping away the initial ``--``
string. If no long option strings were supplied, ``dest`` will be derived from
the first short option string by stripping the initial ``-`` character. Any
internal ``-`` characters will be converted to ``_`` characters to make sure
the string is a valid attribute name. The examples below illustrate this
behavior::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('-f', '--foo-bar', '--foo')
>>> parser.add_argument('-x', '-y')
>>> parser.parse_args('-f 1 -x 2'.split())
Namespace(foo_bar='1', x='2')
>>> parser.parse_args('--foo 1 -y 2'.split())
Namespace(foo_bar='1', x='2')
``dest`` allows a custom attribute name to be provided::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', dest='bar')
>>> parser.parse_args('--foo XXX'.split())
Namespace(bar='XXX')
Action classes
^^^^^^^^^^^^^^
Action classes implement the Action API, a callable which returns a callable
which processes arguments from the command-line. Any object which follows this
API may be passed as the ``action`` parameter to :meth:`add_argument`.
.. class:: Action(option_strings, dest, nargs=None, const=None, default=None, \
type=None, choices=None, required=False, help=None, \
metavar=None)
Action objects are used by an ArgumentParser to represent the information needed
to parse a single argument from one or more strings from the command line. The
Action class must accept the two positional arguments plus any keyword arguments
passed to :meth:`ArgumentParser.add_argument` except for the ``action`` itself.
Instances of Action (or return value of any callable to the ``action``
parameter) should have attributes "dest", "option_strings", "default", "type",
"required", "help", etc. defined. The easiest way to ensure these attributes
are defined is to call ``Action.__init__``.
Action instances should be callable, so subclasses must override the
``__call__`` method, which should accept four parameters:
* ``parser`` - The ArgumentParser object which contains this action.
* ``namespace`` - The :class:`Namespace` object that will be returned by
:meth:`~ArgumentParser.parse_args`. Most actions add an attribute to this
object using :func:`setattr`.
* ``values`` - The associated command-line arguments, with any type conversions
applied. Type conversions are specified with the type_ keyword argument to
:meth:`~ArgumentParser.add_argument`.
* ``option_string`` - The option string that was used to invoke this action.
The ``option_string`` argument is optional, and will be absent if the action
is associated with a positional argument.
The ``__call__`` method may perform arbitrary actions, but will typically set
attributes on the ``namespace`` based on ``dest`` and ``values``.
The parse_args() method
-----------------------
.. method:: ArgumentParser.parse_args(args=None, namespace=None)
Convert argument strings to objects and assign them as attributes of the
namespace. Return the populated namespace.
Previous calls to :meth:`add_argument` determine exactly what objects are
created and how they are assigned. See the documentation for
:meth:`add_argument` for details.
* args_ - List of strings to parse. The default is taken from
:data:`sys.argv`.
* namespace_ - An object to take the attributes. The default is a new empty
:class:`Namespace` object.
Option value syntax
^^^^^^^^^^^^^^^^^^^
The :meth:`~ArgumentParser.parse_args` method supports several ways of
specifying the value of an option (if it takes one). In the simplest case, the
option and its value are passed as two separate arguments::
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x')
>>> parser.add_argument('--foo')
>>> parser.parse_args(['-x', 'X'])
Namespace(foo=None, x='X')
>>> parser.parse_args(['--foo', 'FOO'])
Namespace(foo='FOO', x=None)
For long options (options with names longer than a single character), the option
and value can also be passed as a single command-line argument, using ``=`` to
separate them::
>>> parser.parse_args(['--foo=FOO'])
Namespace(foo='FOO', x=None)
For short options (options only one character long), the option and its value
can be concatenated::
>>> parser.parse_args(['-xX'])
Namespace(foo=None, x='X')
Several short options can be joined together, using only a single ``-`` prefix,
as long as only the last option (or none of them) requires a value::
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x', action='store_true')
>>> parser.add_argument('-y', action='store_true')
>>> parser.add_argument('-z')
>>> parser.parse_args(['-xyzZ'])
Namespace(x=True, y=True, z='Z')
Invalid arguments
^^^^^^^^^^^^^^^^^
While parsing the command line, :meth:`~ArgumentParser.parse_args` checks for a
variety of errors, including ambiguous options, invalid types, invalid options,
wrong number of positional arguments, etc. When it encounters such an error,
it exits and prints the error along with a usage message::
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo', type=int)
>>> parser.add_argument('bar', nargs='?')
>>> # invalid type
>>> parser.parse_args(['--foo', 'spam'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: argument --foo: invalid int value: 'spam'
>>> # invalid option
>>> parser.parse_args(['--bar'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: no such option: --bar
>>> # wrong number of arguments
>>> parser.parse_args(['spam', 'badger'])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: extra arguments found: badger
Arguments containing ``-``
^^^^^^^^^^^^^^^^^^^^^^^^^^
The :meth:`~ArgumentParser.parse_args` method attempts to give errors whenever
the user has clearly made a mistake, but some situations are inherently
ambiguous. For example, the command-line argument ``-1`` could either be an
attempt to specify an option or an attempt to provide a positional argument.
The :meth:`~ArgumentParser.parse_args` method is cautious here: positional
arguments may only begin with ``-`` if they look like negative numbers and
there are no options in the parser that look like negative numbers::
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-x')
>>> parser.add_argument('foo', nargs='?')
>>> # no negative number options, so -1 is a positional argument
>>> parser.parse_args(['-x', '-1'])
Namespace(foo=None, x='-1')
>>> # no negative number options, so -1 and -5 are positional arguments
>>> parser.parse_args(['-x', '-1', '-5'])
Namespace(foo='-5', x='-1')
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-1', dest='one')
>>> parser.add_argument('foo', nargs='?')
>>> # negative number options present, so -1 is an option
>>> parser.parse_args(['-1', 'X'])
Namespace(foo=None, one='X')
>>> # negative number options present, so -2 is an option
>>> parser.parse_args(['-2'])
usage: PROG [-h] [-1 ONE] [foo]
PROG: error: no such option: -2
>>> # negative number options present, so both -1s are options
>>> parser.parse_args(['-1', '-1'])
usage: PROG [-h] [-1 ONE] [foo]
PROG: error: argument -1: expected one argument
If you have positional arguments that must begin with ``-`` and don't look
like negative numbers, you can insert the pseudo-argument ``'--'`` which tells
:meth:`~ArgumentParser.parse_args` that everything after that is a positional
argument::
>>> parser.parse_args(['--', '-f'])
Namespace(foo='-f', one=None)
.. _prefix-matching:
Argument abbreviations (prefix matching)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The :meth:`~ArgumentParser.parse_args` method allows long options to be
abbreviated to a prefix, if the abbreviation is unambiguous (the prefix matches
a unique option)::
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('-bacon')
>>> parser.add_argument('-badger')
>>> parser.parse_args('-bac MMM'.split())
Namespace(bacon='MMM', badger=None)
>>> parser.parse_args('-bad WOOD'.split())
Namespace(bacon=None, badger='WOOD')
>>> parser.parse_args('-ba BA'.split())
usage: PROG [-h] [-bacon BACON] [-badger BADGER]
PROG: error: ambiguous option: -ba could match -badger, -bacon
An error is produced for arguments that could produce more than one options.
.. _args:
Beyond ``sys.argv``
^^^^^^^^^^^^^^^^^^^
Sometimes it may be useful to have an ArgumentParser parse arguments other than those
of :data:`sys.argv`. This can be accomplished by passing a list of strings to
:meth:`~ArgumentParser.parse_args`. This is useful for testing at the
interactive prompt::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument(
... 'integers', metavar='int', type=int, choices=xrange(10),
... nargs='+', help='an integer in the range 0..9')
>>> parser.add_argument(
... '--sum', dest='accumulate', action='store_const', const=sum,
... default=max, help='sum the integers (default: find the max)')
>>> parser.parse_args(['1', '2', '3', '4'])
Namespace(accumulate=<built-in function max>, integers=[1, 2, 3, 4])
>>> parser.parse_args(['1', '2', '3', '4', '--sum'])
Namespace(accumulate=<built-in function sum>, integers=[1, 2, 3, 4])
.. _namespace:
The Namespace object
^^^^^^^^^^^^^^^^^^^^
.. class:: Namespace
Simple class used by default by :meth:`~ArgumentParser.parse_args` to create
an object holding attributes and return it.
This class is deliberately simple, just an :class:`object` subclass with a
readable string representation. If you prefer to have dict-like view of the
attributes, you can use the standard Python idiom, :func:`vars`::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> args = parser.parse_args(['--foo', 'BAR'])
>>> vars(args)
{'foo': 'BAR'}
It may also be useful to have an :class:`ArgumentParser` assign attributes to an
already existing object, rather than a new :class:`Namespace` object. This can
be achieved by specifying the ``namespace=`` keyword argument::
>>> class C(object):
... pass
...
>>> c = C()
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo')
>>> parser.parse_args(args=['--foo', 'BAR'], namespace=c)
>>> c.foo
'BAR'
Other utilities
---------------
Sub-commands
^^^^^^^^^^^^
.. method:: ArgumentParser.add_subparsers([title], [description], [prog], \
[parser_class], [action], \
[option_string], [dest], [help], \
[metavar])
Many programs split up their functionality into a number of sub-commands,
for example, the ``svn`` program can invoke sub-commands like ``svn
checkout``, ``svn update``, and ``svn commit``. Splitting up functionality
this way can be a particularly good idea when a program performs several
different functions which require different kinds of command-line arguments.
:class:`ArgumentParser` supports the creation of such sub-commands with the
:meth:`add_subparsers` method. The :meth:`add_subparsers` method is normally
called with no arguments and returns a special action object. This object
has a single method, :meth:`~ArgumentParser.add_parser`, which takes a
command name and any :class:`ArgumentParser` constructor arguments, and
returns an :class:`ArgumentParser` object that can be modified as usual.
Description of parameters:
* title - title for the sub-parser group in help output; by default
"subcommands" if description is provided, otherwise uses title for
positional arguments
* description - description for the sub-parser group in help output, by
default ``None``
* prog - usage information that will be displayed with sub-command help,
by default the name of the program and any positional arguments before the
subparser argument
* parser_class - class which will be used to create sub-parser instances, by
default the class of the current parser (e.g. ArgumentParser)
* action_ - the basic type of action to be taken when this argument is
encountered at the command line
* dest_ - name of the attribute under which sub-command name will be
stored; by default ``None`` and no value is stored
* help_ - help for sub-parser group in help output, by default ``None``
* metavar_ - string presenting available sub-commands in help; by default it
is ``None`` and presents sub-commands in form {cmd1, cmd2, ..}
Some example usage::
>>> # create the top-level parser
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> parser.add_argument('--foo', action='store_true', help='foo help')
>>> subparsers = parser.add_subparsers(help='sub-command help')
>>>
>>> # create the parser for the "a" command
>>> parser_a = subparsers.add_parser('a', help='a help')
>>> parser_a.add_argument('bar', type=int, help='bar help')
>>>
>>> # create the parser for the "b" command
>>> parser_b = subparsers.add_parser('b', help='b help')
>>> parser_b.add_argument('--baz', choices='XYZ', help='baz help')
>>>
>>> # parse some argument lists
>>> parser.parse_args(['a', '12'])
Namespace(bar=12, foo=False)
>>> parser.parse_args(['--foo', 'b', '--baz', 'Z'])
Namespace(baz='Z', foo=True)
Note that the object returned by :meth:`parse_args` will only contain
attributes for the main parser and the subparser that was selected by the
command line (and not any other subparsers). So in the example above, when
the ``a`` command is specified, only the ``foo`` and ``bar`` attributes are
present, and when the ``b`` command is specified, only the ``foo`` and
``baz`` attributes are present.
Similarly, when a help message is requested from a subparser, only the help
for that particular parser will be printed. The help message will not
include parent parser or sibling parser messages. (A help message for each
subparser command, however, can be given by supplying the ``help=`` argument
to :meth:`add_parser` as above.)
::
>>> parser.parse_args(['--help'])
usage: PROG [-h] [--foo] {a,b} ...
positional arguments:
{a,b} sub-command help
a a help
b b help
optional arguments:
-h, --help show this help message and exit
--foo foo help
>>> parser.parse_args(['a', '--help'])
usage: PROG a [-h] bar
positional arguments:
bar bar help
optional arguments:
-h, --help show this help message and exit
>>> parser.parse_args(['b', '--help'])
usage: PROG b [-h] [--baz {X,Y,Z}]
optional arguments:
-h, --help show this help message and exit
--baz {X,Y,Z} baz help
The :meth:`add_subparsers` method also supports ``title`` and ``description``
keyword arguments. When either is present, the subparser's commands will
appear in their own group in the help output. For example::
>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers(title='subcommands',
... description='valid subcommands',
... help='additional help')
>>> subparsers.add_parser('foo')
>>> subparsers.add_parser('bar')
>>> parser.parse_args(['-h'])
usage: [-h] {foo,bar} ...
optional arguments:
-h, --help show this help message and exit
subcommands:
valid subcommands
{foo,bar} additional help
One particularly effective way of handling sub-commands is to combine the use
of the :meth:`add_subparsers` method with calls to :meth:`set_defaults` so
that each subparser knows which Python function it should execute. For
example::
>>> # sub-command functions
>>> def foo(args):
... print args.x * args.y
...
>>> def bar(args):
... print '((%s))' % args.z
...
>>> # create the top-level parser
>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers()
>>>
>>> # create the parser for the "foo" command
>>> parser_foo = subparsers.add_parser('foo')
>>> parser_foo.add_argument('-x', type=int, default=1)
>>> parser_foo.add_argument('y', type=float)
>>> parser_foo.set_defaults(func=foo)
>>>
>>> # create the parser for the "bar" command
>>> parser_bar = subparsers.add_parser('bar')
>>> parser_bar.add_argument('z')
>>> parser_bar.set_defaults(func=bar)
>>>
>>> # parse the args and call whatever function was selected
>>> args = parser.parse_args('foo 1 -x 2'.split())
>>> args.func(args)
2.0
>>>
>>> # parse the args and call whatever function was selected
>>> args = parser.parse_args('bar XYZYX'.split())
>>> args.func(args)
((XYZYX))
This way, you can let :meth:`parse_args` do the job of calling the
appropriate function after argument parsing is complete. Associating
functions with actions like this is typically the easiest way to handle the
different actions for each of your subparsers. However, if it is necessary
to check the name of the subparser that was invoked, the ``dest`` keyword
argument to the :meth:`add_subparsers` call will work::
>>> parser = argparse.ArgumentParser()
>>> subparsers = parser.add_subparsers(dest='subparser_name')
>>> subparser1 = subparsers.add_parser('1')
>>> subparser1.add_argument('-x')
>>> subparser2 = subparsers.add_parser('2')
>>> subparser2.add_argument('y')
>>> parser.parse_args(['2', 'frobble'])
Namespace(subparser_name='2', y='frobble')
FileType objects
^^^^^^^^^^^^^^^^
.. class:: FileType(mode='r', bufsize=None)
The :class:`FileType` factory creates objects that can be passed to the type
argument of :meth:`ArgumentParser.add_argument`. Arguments that have
:class:`FileType` objects as their type will open command-line arguments as files
with the requested modes and buffer sizes::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--output', type=argparse.FileType('wb', 0))
>>> parser.parse_args(['--output', 'out'])
Namespace(output=<open file 'out', mode 'wb' at 0x...>)
FileType objects understand the pseudo-argument ``'-'`` and automatically
convert this into ``sys.stdin`` for readable :class:`FileType` objects and
``sys.stdout`` for writable :class:`FileType` objects::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('infile', type=argparse.FileType('r'))
>>> parser.parse_args(['-'])
Namespace(infile=<open file '<stdin>', mode 'r' at 0x...>)
Argument groups
^^^^^^^^^^^^^^^
.. method:: ArgumentParser.add_argument_group(title=None, description=None)
By default, :class:`ArgumentParser` groups command-line arguments into
"positional arguments" and "optional arguments" when displaying help
messages. When there is a better conceptual grouping of arguments than this
default one, appropriate groups can be created using the
:meth:`add_argument_group` method::
>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
>>> group = parser.add_argument_group('group')
>>> group.add_argument('--foo', help='foo help')
>>> group.add_argument('bar', help='bar help')
>>> parser.print_help()
usage: PROG [--foo FOO] bar
group:
bar bar help
--foo FOO foo help
The :meth:`add_argument_group` method returns an argument group object which
has an :meth:`~ArgumentParser.add_argument` method just like a regular
:class:`ArgumentParser`. When an argument is added to the group, the parser
treats it just like a normal argument, but displays the argument in a
separate group for help messages. The :meth:`add_argument_group` method
accepts *title* and *description* arguments which can be used to
customize this display::
>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
>>> group1 = parser.add_argument_group('group1', 'group1 description')
>>> group1.add_argument('foo', help='foo help')
>>> group2 = parser.add_argument_group('group2', 'group2 description')
>>> group2.add_argument('--bar', help='bar help')
>>> parser.print_help()
usage: PROG [--bar BAR] foo
group1:
group1 description
foo foo help
group2:
group2 description
--bar BAR bar help
Note that any arguments not in your user-defined groups will end up back
in the usual "positional arguments" and "optional arguments" sections.
Mutual exclusion
^^^^^^^^^^^^^^^^
.. method:: ArgumentParser.add_mutually_exclusive_group(required=False)
Create a mutually exclusive group. :mod:`argparse` will make sure that only
one of the arguments in the mutually exclusive group was present on the
command line::
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> group = parser.add_mutually_exclusive_group()
>>> group.add_argument('--foo', action='store_true')
>>> group.add_argument('--bar', action='store_false')
>>> parser.parse_args(['--foo'])
Namespace(bar=True, foo=True)
>>> parser.parse_args(['--bar'])
Namespace(bar=False, foo=False)
>>> parser.parse_args(['--foo', '--bar'])
usage: PROG [-h] [--foo | --bar]
PROG: error: argument --bar: not allowed with argument --foo
The :meth:`add_mutually_exclusive_group` method also accepts a *required*
argument, to indicate that at least one of the mutually exclusive arguments
is required::
>>> parser = argparse.ArgumentParser(prog='PROG')
>>> group = parser.add_mutually_exclusive_group(required=True)
>>> group.add_argument('--foo', action='store_true')
>>> group.add_argument('--bar', action='store_false')
>>> parser.parse_args([])
usage: PROG [-h] (--foo | --bar)
PROG: error: one of the arguments --foo --bar is required
Note that currently mutually exclusive argument groups do not support the
*title* and *description* arguments of
:meth:`~ArgumentParser.add_argument_group`.
Parser defaults
^^^^^^^^^^^^^^^
.. method:: ArgumentParser.set_defaults(**kwargs)
Most of the time, the attributes of the object returned by :meth:`parse_args`
will be fully determined by inspecting the command-line arguments and the argument
actions. :meth:`set_defaults` allows some additional
attributes that are determined without any inspection of the command line to
be added::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('foo', type=int)
>>> parser.set_defaults(bar=42, baz='badger')
>>> parser.parse_args(['736'])
Namespace(bar=42, baz='badger', foo=736)
Note that parser-level defaults always override argument-level defaults::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default='bar')
>>> parser.set_defaults(foo='spam')
>>> parser.parse_args([])
Namespace(foo='spam')
Parser-level defaults can be particularly useful when working with multiple
parsers. See the :meth:`~ArgumentParser.add_subparsers` method for an
example of this type.
.. method:: ArgumentParser.get_default(dest)
Get the default value for a namespace attribute, as set by either
:meth:`~ArgumentParser.add_argument` or by
:meth:`~ArgumentParser.set_defaults`::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default='badger')
>>> parser.get_default('foo')
'badger'
Printing help
^^^^^^^^^^^^^
In most typical applications, :meth:`~ArgumentParser.parse_args` will take
care of formatting and printing any usage or error messages. However, several
formatting methods are available:
.. method:: ArgumentParser.print_usage(file=None)
Print a brief description of how the :class:`ArgumentParser` should be
invoked on the command line. If *file* is ``None``, :data:`sys.stdout` is
assumed.
.. method:: ArgumentParser.print_help(file=None)
Print a help message, including the program usage and information about the
arguments registered with the :class:`ArgumentParser`. If *file* is
``None``, :data:`sys.stdout` is assumed.
There are also variants of these methods that simply return a string instead of
printing it:
.. method:: ArgumentParser.format_usage()
Return a string containing a brief description of how the
:class:`ArgumentParser` should be invoked on the command line.
.. method:: ArgumentParser.format_help()
Return a string containing a help message, including the program usage and
information about the arguments registered with the :class:`ArgumentParser`.
Partial parsing
^^^^^^^^^^^^^^^
.. method:: ArgumentParser.parse_known_args(args=None, namespace=None)
Sometimes a script may only parse a few of the command-line arguments, passing
the remaining arguments on to another script or program. In these cases, the
:meth:`~ArgumentParser.parse_known_args` method can be useful. It works much like
:meth:`~ArgumentParser.parse_args` except that it does not produce an error when
extra arguments are present. Instead, it returns a two item tuple containing
the populated namespace and the list of remaining argument strings.
::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='store_true')
>>> parser.add_argument('bar')
>>> parser.parse_known_args(['--foo', '--badger', 'BAR', 'spam'])
(Namespace(bar='BAR', foo=True), ['--badger', 'spam'])
.. warning::
:ref:`Prefix matching <prefix-matching>` rules apply to
:meth:`parse_known_args`. The parser may consume an option even if it's just
a prefix of one of its known options, instead of leaving it in the remaining
arguments list.
Customizing file parsing
^^^^^^^^^^^^^^^^^^^^^^^^
.. method:: ArgumentParser.convert_arg_line_to_args(arg_line)
Arguments that are read from a file (see the *fromfile_prefix_chars*
keyword argument to the :class:`ArgumentParser` constructor) are read one
argument per line. :meth:`convert_arg_line_to_args` can be overridden for
fancier reading.
This method takes a single argument *arg_line* which is a string read from
the argument file. It returns a list of arguments parsed from this string.
The method is called once per line read from the argument file, in order.
A useful override of this method is one that treats each space-separated word
as an argument::
def convert_arg_line_to_args(self, arg_line):
return arg_line.split()
Exiting methods
^^^^^^^^^^^^^^^
.. method:: ArgumentParser.exit(status=0, message=None)
This method terminates the program, exiting with the specified *status*
and, if given, it prints a *message* before that.
.. method:: ArgumentParser.error(message)
This method prints a usage message including the *message* to the
standard error and terminates the program with a status code of 2.
.. _argparse-from-optparse:
Upgrading optparse code
-----------------------
Originally, the :mod:`argparse` module had attempted to maintain compatibility
with :mod:`optparse`. However, :mod:`optparse` was difficult to extend
transparently, particularly with the changes required to support the new
``nargs=`` specifiers and better usage messages. When most everything in
:mod:`optparse` had either been copy-pasted over or monkey-patched, it no
longer seemed practical to try to maintain the backwards compatibility.
The :mod:`argparse` module improves on the standard library :mod:`optparse`
module in a number of ways including:
* Handling positional arguments.
* Supporting sub-commands.
* Allowing alternative option prefixes like ``+`` and ``/``.
* Handling zero-or-more and one-or-more style arguments.
* Producing more informative usage messages.
* Providing a much simpler interface for custom ``type`` and ``action``.
A partial upgrade path from :mod:`optparse` to :mod:`argparse`:
* Replace all :meth:`optparse.OptionParser.add_option` calls with
:meth:`ArgumentParser.add_argument` calls.
* Replace ``(options, args) = parser.parse_args()`` with ``args =
parser.parse_args()`` and add additional :meth:`ArgumentParser.add_argument`
calls for the positional arguments. Keep in mind that what was previously
called ``options``, now in the :mod:`argparse` context is called ``args``.
* Replace :meth:`optparse.OptionParser.disable_interspersed_args`
by setting ``nargs`` of a positional argument to `argparse.REMAINDER`_, or
use :meth:`~ArgumentParser.parse_known_args` to collect unparsed argument
strings in a separate list.
* Replace callback actions and the ``callback_*`` keyword arguments with
``type`` or ``action`` arguments.
* Replace string names for ``type`` keyword arguments with the corresponding
type objects (e.g. int, float, complex, etc).
* Replace :class:`optparse.Values` with :class:`Namespace` and
:exc:`optparse.OptionError` and :exc:`optparse.OptionValueError` with
:exc:`ArgumentError`.
* Replace strings with implicit arguments such as ``%default`` or ``%prog`` with
the standard Python syntax to use dictionaries to format strings, that is,
``%(default)s`` and ``%(prog)s``.
* Replace the OptionParser constructor ``version`` argument with a call to
``parser.add_argument('--version', action='version', version='<the version>')``.
PK %�\ �k ) ) # html/_sources/library/array.rst.txtnu �[���
:mod:`array` --- Efficient arrays of numeric values
===================================================
.. module:: array
:synopsis: Space efficient arrays of uniformly typed numeric values.
.. index:: single: arrays
This module defines an object type which can compactly represent an array of
basic values: characters, integers, floating point numbers. Arrays are sequence
types and behave very much like lists, except that the type of objects stored in
them is constrained. The type is specified at object creation time by using a
:dfn:`type code`, which is a single character. The following type codes are
defined:
+-----------+----------------+-------------------+-----------------------+
| Type code | C Type | Python Type | Minimum size in bytes |
+===========+================+===================+=======================+
| ``'c'`` | char | character | 1 |
+-----------+----------------+-------------------+-----------------------+
| ``'b'`` | signed char | int | 1 |
+-----------+----------------+-------------------+-----------------------+
| ``'B'`` | unsigned char | int | 1 |
+-----------+----------------+-------------------+-----------------------+
| ``'u'`` | Py_UNICODE | Unicode character | 2 (see note) |
+-----------+----------------+-------------------+-----------------------+
| ``'h'`` | signed short | int | 2 |
+-----------+----------------+-------------------+-----------------------+
| ``'H'`` | unsigned short | int | 2 |
+-----------+----------------+-------------------+-----------------------+
| ``'i'`` | signed int | int | 2 |
+-----------+----------------+-------------------+-----------------------+
| ``'I'`` | unsigned int | long | 2 |
+-----------+----------------+-------------------+-----------------------+
| ``'l'`` | signed long | int | 4 |
+-----------+----------------+-------------------+-----------------------+
| ``'L'`` | unsigned long | long | 4 |
+-----------+----------------+-------------------+-----------------------+
| ``'f'`` | float | float | 4 |
+-----------+----------------+-------------------+-----------------------+
| ``'d'`` | double | float | 8 |
+-----------+----------------+-------------------+-----------------------+
.. note::
The ``'u'`` typecode corresponds to Python's unicode character. On narrow
Unicode builds this is 2-bytes, on wide builds this is 4-bytes.
The actual representation of values is determined by the machine architecture
(strictly speaking, by the C implementation). The actual size can be accessed
through the :attr:`itemsize` attribute. The values stored for ``'L'`` and
``'I'`` items will be represented as Python long integers when retrieved,
because Python's plain integer type cannot represent the full range of C's
unsigned (long) integers.
The module defines the following type:
.. class:: array(typecode[, initializer])
A new array whose items are restricted by *typecode*, and initialized
from the optional *initializer* value, which must be a list, string, or iterable
over elements of the appropriate type.
.. versionchanged:: 2.4
Formerly, only lists or strings were accepted.
If given a list or string, the initializer is passed to the new array's
:meth:`fromlist`, :meth:`fromstring`, or :meth:`fromunicode` method (see below)
to add initial items to the array. Otherwise, the iterable initializer is
passed to the :meth:`extend` method.
.. data:: ArrayType
Obsolete alias for :class:`~array.array`.
Array objects support the ordinary sequence operations of indexing, slicing,
concatenation, and multiplication. When using slice assignment, the assigned
value must be an array object with the same type code; in all other cases,
:exc:`TypeError` is raised. Array objects also implement the buffer interface,
and may be used wherever buffer objects are supported.
The following data items and methods are also supported:
.. attribute:: array.typecode
The typecode character used to create the array.
.. attribute:: array.itemsize
The length in bytes of one array item in the internal representation.
.. method:: array.append(x)
Append a new item with value *x* to the end of the array.
.. method:: array.buffer_info()
Return a tuple ``(address, length)`` giving the current memory address and the
length in elements of the buffer used to hold array's contents. The size of the
memory buffer in bytes can be computed as ``array.buffer_info()[1] *
array.itemsize``. This is occasionally useful when working with low-level (and
inherently unsafe) I/O interfaces that require memory addresses, such as certain
:c:func:`ioctl` operations. The returned numbers are valid as long as the array
exists and no length-changing operations are applied to it.
.. note::
When using array objects from code written in C or C++ (the only way to
effectively make use of this information), it makes more sense to use the buffer
interface supported by array objects. This method is maintained for backward
compatibility and should be avoided in new code. The buffer interface is
documented in :ref:`bufferobjects`.
.. method:: array.byteswap()
"Byteswap" all items of the array. This is only supported for values which are
1, 2, 4, or 8 bytes in size; for other types of values, :exc:`RuntimeError` is
raised. It is useful when reading data from a file written on a machine with a
different byte order.
.. method:: array.count(x)
Return the number of occurrences of *x* in the array.
.. method:: array.extend(iterable)
Append items from *iterable* to the end of the array. If *iterable* is another
array, it must have *exactly* the same type code; if not, :exc:`TypeError` will
be raised. If *iterable* is not an array, it must be iterable and its elements
must be the right type to be appended to the array.
.. versionchanged:: 2.4
Formerly, the argument could only be another array.
.. method:: array.fromfile(f, n)
Read *n* items (as machine values) from the file object *f* and append them to
the end of the array. If less than *n* items are available, :exc:`EOFError` is
raised, but the items that were available are still inserted into the array.
*f* must be a real built-in file object; something else with a :meth:`read`
method won't do.
.. method:: array.fromlist(list)
Append items from the list. This is equivalent to ``for x in list:
a.append(x)`` except that if there is a type error, the array is unchanged.
.. method:: array.fromstring(s)
Appends items from the string, interpreting the string as an array of machine
values (as if it had been read from a file using the :meth:`fromfile` method).
.. method:: array.fromunicode(s)
Extends this array with data from the given unicode string. The array must
be a type ``'u'`` array; otherwise a :exc:`ValueError` is raised. Use
``array.fromstring(unicodestring.encode(enc))`` to append Unicode data to an
array of some other type.
.. method:: array.index(x)
Return the smallest *i* such that *i* is the index of the first occurrence of
*x* in the array.
.. method:: array.insert(i, x)
Insert a new item with value *x* in the array before position *i*. Negative
values are treated as being relative to the end of the array.
.. method:: array.pop([i])
Removes the item with the index *i* from the array and returns it. The optional
argument defaults to ``-1``, so that by default the last item is removed and
returned.
.. method:: array.read(f, n)
.. deprecated:: 1.5.1
Use the :meth:`fromfile` method.
Read *n* items (as machine values) from the file object *f* and append them to
the end of the array. If less than *n* items are available, :exc:`EOFError` is
raised, but the items that were available are still inserted into the array.
*f* must be a real built-in file object; something else with a :meth:`read`
method won't do.
.. method:: array.remove(x)
Remove the first occurrence of *x* from the array.
.. method:: array.reverse()
Reverse the order of the items in the array.
.. method:: array.tofile(f)
Write all items (as machine values) to the file object *f*.
.. method:: array.tolist()
Convert the array to an ordinary list with the same items.
.. method:: array.tostring()
Convert the array to an array of machine values and return the string
representation (the same sequence of bytes that would be written to a file by
the :meth:`tofile` method.)
.. method:: array.tounicode()
Convert the array to a unicode string. The array must be a type ``'u'`` array;
otherwise a :exc:`ValueError` is raised. Use ``array.tostring().decode(enc)`` to
obtain a unicode string from an array of some other type.
.. method:: array.write(f)
.. deprecated:: 1.5.1
Use the :meth:`tofile` method.
Write all items (as machine values) to the file object *f*.
When an array object is printed or converted to a string, it is represented as
``array(typecode, initializer)``. The *initializer* is omitted if the array is
empty, otherwise it is a string if the *typecode* is ``'c'``, otherwise it is a
list of numbers. The string is guaranteed to be able to be converted back to an
array with the same type and value using :func:`eval`, so long as the
:class:`~array.array` class has been imported using ``from array import array``.
Examples::
array('l')
array('c', 'hello world')
array('u', u'hello \u2641')
array('l', [1, 2, 3, 4, 5])
array('d', [1.0, 2.0, 3.14])
.. seealso::
Module :mod:`struct`
Packing and unpacking of heterogeneous binary data.
Module :mod:`xdrlib`
Packing and unpacking of External Data Representation (XDR) data as used in some
remote procedure call systems.
`The Numerical Python Documentation <https://docs.scipy.org/doc/>`_
The Numeric Python extension (NumPy) defines another array type; see
http://www.numpy.org/ for further information about Numerical Python.
PK %�\?��' ' ! html/_sources/library/ast.rst.txtnu �[��� :mod:`ast` --- Abstract Syntax Trees
====================================
.. module:: ast
:synopsis: Abstract Syntax Tree classes and manipulation.
.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
.. sectionauthor:: Georg Brandl <georg@python.org>
.. versionadded:: 2.5
The low-level ``_ast`` module containing only the node classes.
.. versionadded:: 2.6
The high-level ``ast`` module containing all helpers.
**Source code:** :source:`Lib/ast.py`
--------------
The :mod:`ast` module helps Python applications to process trees of the Python
abstract syntax grammar. The abstract syntax itself might change with each
Python release; this module helps to find out programmatically what the current
grammar looks like.
An abstract syntax tree can be generated by passing :data:`ast.PyCF_ONLY_AST` as
a flag to the :func:`compile` built-in function, or using the :func:`parse`
helper provided in this module. The result will be a tree of objects whose
classes all inherit from :class:`ast.AST`. An abstract syntax tree can be
compiled into a Python code object using the built-in :func:`compile` function.
Node classes
------------
.. class:: AST
This is the base of all AST node classes. The actual node classes are
derived from the :file:`Parser/Python.asdl` file, which is reproduced
:ref:`below <abstract-grammar>`. They are defined in the :mod:`_ast` C
module and re-exported in :mod:`ast`.
There is one class defined for each left-hand side symbol in the abstract
grammar (for example, :class:`ast.stmt` or :class:`ast.expr`). In addition,
there is one class defined for each constructor on the right-hand side; these
classes inherit from the classes for the left-hand side trees. For example,
:class:`ast.BinOp` inherits from :class:`ast.expr`. For production rules
with alternatives (aka "sums"), the left-hand side class is abstract: only
instances of specific constructor nodes are ever created.
.. attribute:: _fields
Each concrete class has an attribute :attr:`_fields` which gives the names
of all child nodes.
Each instance of a concrete class has one attribute for each child node,
of the type as defined in the grammar. For example, :class:`ast.BinOp`
instances have an attribute :attr:`left` of type :class:`ast.expr`.
If these attributes are marked as optional in the grammar (using a
question mark), the value might be ``None``. If the attributes can have
zero-or-more values (marked with an asterisk), the values are represented
as Python lists. All possible attributes must be present and have valid
values when compiling an AST with :func:`compile`.
.. attribute:: lineno
col_offset
Instances of :class:`ast.expr` and :class:`ast.stmt` subclasses have
:attr:`lineno` and :attr:`col_offset` attributes. The :attr:`lineno` is
the line number of source text (1-indexed so the first line is line 1) and
the :attr:`col_offset` is the UTF-8 byte offset of the first token that
generated the node. The UTF-8 offset is recorded because the parser uses
UTF-8 internally.
The constructor of a class :class:`ast.T` parses its arguments as follows:
* If there are positional arguments, there must be as many as there are items
in :attr:`T._fields`; they will be assigned as attributes of these names.
* If there are keyword arguments, they will set the attributes of the same
names to the given values.
For example, to create and populate an :class:`ast.UnaryOp` node, you could
use ::
node = ast.UnaryOp()
node.op = ast.USub()
node.operand = ast.Num()
node.operand.n = 5
node.operand.lineno = 0
node.operand.col_offset = 0
node.lineno = 0
node.col_offset = 0
or the more compact ::
node = ast.UnaryOp(ast.USub(), ast.Num(5, lineno=0, col_offset=0),
lineno=0, col_offset=0)
.. versionadded:: 2.6
The constructor as explained above was added. In Python 2.5 nodes had
to be created by calling the class constructor without arguments and
setting the attributes afterwards.
.. _abstract-grammar:
Abstract Grammar
----------------
The module defines a string constant ``__version__`` which is the decimal
Subversion revision number of the file shown below.
The abstract grammar is currently defined as follows:
.. literalinclude:: ../../Parser/Python.asdl
:language: none
:mod:`ast` Helpers
------------------
.. versionadded:: 2.6
Apart from the node classes, :mod:`ast` module defines these utility functions
and classes for traversing abstract syntax trees:
.. function:: parse(source, filename='<unknown>', mode='exec')
Parse the source into an AST node. Equivalent to ``compile(source,
filename, mode, ast.PyCF_ONLY_AST)``.
.. function:: literal_eval(node_or_string)
Safely evaluate an expression node or a Unicode or *Latin-1* encoded string
containing a Python literal or container display. The string or node
provided may only consist of the following Python literal structures:
strings, numbers, tuples, lists, dicts, booleans, and ``None``.
This can be used for safely evaluating strings containing Python values from
untrusted sources without the need to parse the values oneself. It is not
capable of evaluating arbitrarily complex expressions, for example involving
operators or indexing.
.. function:: get_docstring(node, clean=True)
Return the docstring of the given *node* (which must be a
:class:`FunctionDef`, :class:`ClassDef` or :class:`Module` node), or ``None``
if it has no docstring. If *clean* is true, clean up the docstring's
indentation with :func:`inspect.cleandoc`.
.. function:: fix_missing_locations(node)
When you compile a node tree with :func:`compile`, the compiler expects
:attr:`lineno` and :attr:`col_offset` attributes for every node that supports
them. This is rather tedious to fill in for generated nodes, so this helper
adds these attributes recursively where not already set, by setting them to
the values of the parent node. It works recursively starting at *node*.
.. function:: increment_lineno(node, n=1)
Increment the line number of each node in the tree starting at *node* by *n*.
This is useful to "move code" to a different location in a file.
.. function:: copy_location(new_node, old_node)
Copy source location (:attr:`lineno` and :attr:`col_offset`) from *old_node*
to *new_node* if possible, and return *new_node*.
.. function:: iter_fields(node)
Yield a tuple of ``(fieldname, value)`` for each field in ``node._fields``
that is present on *node*.
.. function:: iter_child_nodes(node)
Yield all direct child nodes of *node*, that is, all fields that are nodes
and all items of fields that are lists of nodes.
.. function:: walk(node)
Recursively yield all descendant nodes in the tree starting at *node*
(including *node* itself), in no specified order. This is useful if you only
want to modify nodes in place and don't care about the context.
.. class:: NodeVisitor()
A node visitor base class that walks the abstract syntax tree and calls a
visitor function for every node found. This function may return a value
which is forwarded by the :meth:`visit` method.
This class is meant to be subclassed, with the subclass adding visitor
methods.
.. method:: visit(node)
Visit a node. The default implementation calls the method called
:samp:`self.visit_{classname}` where *classname* is the name of the node
class, or :meth:`generic_visit` if that method doesn't exist.
.. method:: generic_visit(node)
This visitor calls :meth:`visit` on all children of the node.
Note that child nodes of nodes that have a custom visitor method won't be
visited unless the visitor calls :meth:`generic_visit` or visits them
itself.
Don't use the :class:`NodeVisitor` if you want to apply changes to nodes
during traversal. For this a special visitor exists
(:class:`NodeTransformer`) that allows modifications.
.. class:: NodeTransformer()
A :class:`NodeVisitor` subclass that walks the abstract syntax tree and
allows modification of nodes.
The :class:`NodeTransformer` will walk the AST and use the return value of
the visitor methods to replace or remove the old node. If the return value
of the visitor method is ``None``, the node will be removed from its
location, otherwise it is replaced with the return value. The return value
may be the original node in which case no replacement takes place.
Here is an example transformer that rewrites all occurrences of name lookups
(``foo``) to ``data['foo']``::
class RewriteName(NodeTransformer):
def visit_Name(self, node):
return copy_location(Subscript(
value=Name(id='data', ctx=Load()),
slice=Index(value=Str(s=node.id)),
ctx=node.ctx
), node)
Keep in mind that if the node you're operating on has child nodes you must
either transform the child nodes yourself or call the :meth:`generic_visit`
method for the node first.
For nodes that were part of a collection of statements (that applies to all
statement nodes), the visitor may also return a list of nodes rather than
just a single node.
Usually you use the transformer like this::
node = YourTransformer().visit(node)
.. function:: dump(node, annotate_fields=True, include_attributes=False)
Return a formatted dump of the tree in *node*. This is mainly useful for
debugging purposes. The returned string will show the names and the values
for fields. This makes the code impossible to evaluate, so if evaluation is
wanted *annotate_fields* must be set to ``False``. Attributes such as line
numbers and column offsets are not dumped by default. If this is wanted,
*include_attributes* can be set to ``True``.
PK %�\S�`h�# �# & html/_sources/library/asynchat.rst.txtnu �[��� :mod:`asynchat` --- Asynchronous socket command/response handler
================================================================
.. module:: asynchat
:synopsis: Support for asynchronous command/response protocols.
.. moduleauthor:: Sam Rushing <rushing@nightmare.com>
.. sectionauthor:: Steve Holden <sholden@holdenweb.com>
**Source code:** :source:`Lib/asynchat.py`
--------------
This module builds on the :mod:`asyncore` infrastructure, simplifying
asynchronous clients and servers and making it easier to handle protocols
whose elements are terminated by arbitrary strings, or are of variable length.
:mod:`asynchat` defines the abstract class :class:`async_chat` that you
subclass, providing implementations of the :meth:`collect_incoming_data` and
:meth:`found_terminator` methods. It uses the same asynchronous loop as
:mod:`asyncore`, and the two types of channel, :class:`asyncore.dispatcher`
and :class:`asynchat.async_chat`, can freely be mixed in the channel map.
Typically an :class:`asyncore.dispatcher` server channel generates new
:class:`asynchat.async_chat` channel objects as it receives incoming
connection requests.
.. class:: async_chat()
This class is an abstract subclass of :class:`asyncore.dispatcher`. To make
practical use of the code you must subclass :class:`async_chat`, providing
meaningful :meth:`collect_incoming_data` and :meth:`found_terminator`
methods.
The :class:`asyncore.dispatcher` methods can be used, although not all make
sense in a message/response context.
Like :class:`asyncore.dispatcher`, :class:`async_chat` defines a set of
events that are generated by an analysis of socket conditions after a
:c:func:`select` call. Once the polling loop has been started the
:class:`async_chat` object's methods are called by the event-processing
framework with no action on the part of the programmer.
Two class attributes can be modified, to improve performance, or possibly
even to conserve memory.
.. data:: ac_in_buffer_size
The asynchronous input buffer size (default ``4096``).
.. data:: ac_out_buffer_size
The asynchronous output buffer size (default ``4096``).
Unlike :class:`asyncore.dispatcher`, :class:`async_chat` allows you to
define a first-in-first-out queue (fifo) of *producers*. A producer need
have only one method, :meth:`more`, which should return data to be
transmitted on the channel.
The producer indicates exhaustion (*i.e.* that it contains no more data) by
having its :meth:`more` method return the empty string. At this point the
:class:`async_chat` object removes the producer from the fifo and starts
using the next producer, if any. When the producer fifo is empty the
:meth:`handle_write` method does nothing. You use the channel object's
:meth:`set_terminator` method to describe how to recognize the end of, or
an important breakpoint in, an incoming transmission from the remote
endpoint.
To build a functioning :class:`async_chat` subclass your input methods
:meth:`collect_incoming_data` and :meth:`found_terminator` must handle the
data that the channel receives asynchronously. The methods are described
below.
.. method:: async_chat.close_when_done()
Pushes a ``None`` on to the producer fifo. When this producer is popped off
the fifo it causes the channel to be closed.
.. method:: async_chat.collect_incoming_data(data)
Called with *data* holding an arbitrary amount of received data. The
default method, which must be overridden, raises a
:exc:`NotImplementedError` exception.
.. method:: async_chat.discard_buffers()
In emergencies this method will discard any data held in the input and/or
output buffers and the producer fifo.
.. method:: async_chat.found_terminator()
Called when the incoming data stream matches the termination condition set
by :meth:`set_terminator`. The default method, which must be overridden,
raises a :exc:`NotImplementedError` exception. The buffered input data
should be available via an instance attribute.
.. method:: async_chat.get_terminator()
Returns the current terminator for the channel.
.. method:: async_chat.push(data)
Pushes data on to the channel's fifo to ensure its transmission.
This is all you need to do to have the channel write the data out to the
network, although it is possible to use your own producers in more complex
schemes to implement encryption and chunking, for example.
.. method:: async_chat.push_with_producer(producer)
Takes a producer object and adds it to the producer fifo associated with
the channel. When all currently-pushed producers have been exhausted the
channel will consume this producer's data by calling its :meth:`more`
method and send the data to the remote endpoint.
.. method:: async_chat.set_terminator(term)
Sets the terminating condition to be recognized on the channel. ``term``
may be any of three types of value, corresponding to three different ways
to handle incoming protocol data.
+-----------+---------------------------------------------+
| term | Description |
+===========+=============================================+
| *string* | Will call :meth:`found_terminator` when the |
| | string is found in the input stream |
+-----------+---------------------------------------------+
| *integer* | Will call :meth:`found_terminator` when the |
| | indicated number of characters have been |
| | received |
+-----------+---------------------------------------------+
| ``None`` | The channel continues to collect data |
| | forever |
+-----------+---------------------------------------------+
Note that any data following the terminator will be available for reading
by the channel after :meth:`found_terminator` is called.
asynchat - Auxiliary Classes
------------------------------------------
.. class:: fifo([list=None])
A :class:`fifo` holding data which has been pushed by the application but
not yet popped for writing to the channel. A :class:`fifo` is a list used
to hold data and/or producers until they are required. If the *list*
argument is provided then it should contain producers or data items to be
written to the channel.
.. method:: is_empty()
Returns ``True`` if and only if the fifo is empty.
.. method:: first()
Returns the least-recently :meth:`push`\ ed item from the fifo.
.. method:: push(data)
Adds the given data (which may be a string or a producer object) to the
producer fifo.
.. method:: pop()
If the fifo is not empty, returns ``True, first()``, deleting the popped
item. Returns ``False, None`` for an empty fifo.
.. _asynchat-example:
asynchat Example
----------------
The following partial example shows how HTTP requests can be read with
:class:`async_chat`. A web server might create an
:class:`http_request_handler` object for each incoming client connection.
Notice that initially the channel terminator is set to match the blank line at
the end of the HTTP headers, and a flag indicates that the headers are being
read.
Once the headers have been read, if the request is of type POST (indicating
that further data are present in the input stream) then the
``Content-Length:`` header is used to set a numeric terminator to read the
right amount of data from the channel.
The :meth:`handle_request` method is called once all relevant input has been
marshalled, after setting the channel terminator to ``None`` to ensure that
any extraneous data sent by the web client are ignored. ::
class http_request_handler(asynchat.async_chat):
def __init__(self, sock, addr, sessions, log):
asynchat.async_chat.__init__(self, sock=sock)
self.addr = addr
self.sessions = sessions
self.ibuffer = []
self.obuffer = ""
self.set_terminator("\r\n\r\n")
self.reading_headers = True
self.handling = False
self.cgi_data = None
self.log = log
def collect_incoming_data(self, data):
"""Buffer the data"""
self.ibuffer.append(data)
def found_terminator(self):
if self.reading_headers:
self.reading_headers = False
self.parse_headers("".join(self.ibuffer))
self.ibuffer = []
if self.op.upper() == "POST":
clen = self.headers.getheader("content-length")
self.set_terminator(int(clen))
else:
self.handling = True
self.set_terminator(None)
self.handle_request()
elif not self.handling:
self.set_terminator(None) # browsers sometimes over-send
self.cgi_data = parse(self.headers, "".join(self.ibuffer))
self.handling = True
self.ibuffer = []
self.handle_request()
PK %�\� j{�2 �2 & html/_sources/library/asyncore.rst.txtnu �[��� :mod:`asyncore` --- Asynchronous socket handler
===============================================
.. module:: asyncore
:synopsis: A base class for developing asynchronous socket handling
services.
.. moduleauthor:: Sam Rushing <rushing@nightmare.com>
.. sectionauthor:: Christopher Petrilli <petrilli@amber.org>
.. sectionauthor:: Steve Holden <sholden@holdenweb.com>
.. heavily adapted from original documentation by Sam Rushing
**Source code:** :source:`Lib/asyncore.py`
--------------
This module provides the basic infrastructure for writing asynchronous socket
service clients and servers.
There are only two ways to have a program on a single processor do "more than
one thing at a time." Multi-threaded programming is the simplest and most
popular way to do it, but there is another very different technique, that lets
you have nearly all the advantages of multi-threading, without actually using
multiple threads. It's really only practical if your program is largely I/O
bound. If your program is processor bound, then pre-emptive scheduled threads
are probably what you really need. Network servers are rarely processor
bound, however.
If your operating system supports the :c:func:`select` system call in its I/O
library (and nearly all do), then you can use it to juggle multiple
communication channels at once; doing other work while your I/O is taking
place in the "background." Although this strategy can seem strange and
complex, especially at first, it is in many ways easier to understand and
control than multi-threaded programming. The :mod:`asyncore` module solves
many of the difficult problems for you, making the task of building
sophisticated high-performance network servers and clients a snap. For
"conversational" applications and protocols the companion :mod:`asynchat`
module is invaluable.
The basic idea behind both modules is to create one or more network
*channels*, instances of class :class:`asyncore.dispatcher` and
:class:`asynchat.async_chat`. Creating the channels adds them to a global
map, used by the :func:`loop` function if you do not provide it with your own
*map*.
Once the initial channel(s) is(are) created, calling the :func:`loop` function
activates channel service, which continues until the last channel (including
any that have been added to the map during asynchronous service) is closed.
.. function:: loop([timeout[, use_poll[, map[,count]]]])
Enter a polling loop that terminates after count passes or all open
channels have been closed. All arguments are optional. The *count*
parameter defaults to ``None``, resulting in the loop terminating only when all
channels have been closed. The *timeout* argument sets the timeout
parameter for the appropriate :func:`~select.select` or :func:`~select.poll`
call, measured in seconds; the default is 30 seconds. The *use_poll*
parameter, if true, indicates that :func:`~select.poll` should be used in
preference to :func:`~select.select` (the default is ``False``).
The *map* parameter is a dictionary whose items are the channels to watch.
As channels are closed they are deleted from their map. If *map* is
omitted, a global map is used. Channels (instances of
:class:`asyncore.dispatcher`, :class:`asynchat.async_chat` and subclasses
thereof) can freely be mixed in the map.
.. class:: dispatcher()
The :class:`dispatcher` class is a thin wrapper around a low-level socket
object. To make it more useful, it has a few methods for event-handling
which are called from the asynchronous loop. Otherwise, it can be treated
as a normal non-blocking socket object.
The firing of low-level events at certain times or in certain connection
states tells the asynchronous loop that certain higher-level events have
taken place. For example, if we have asked for a socket to connect to
another host, we know that the connection has been made when the socket
becomes writable for the first time (at this point you know that you may
write to it with the expectation of success). The implied higher-level
events are:
+----------------------+----------------------------------------+
| Event | Description |
+======================+========================================+
| ``handle_connect()`` | Implied by the first read or write |
| | event |
+----------------------+----------------------------------------+
| ``handle_close()`` | Implied by a read event with no data |
| | available |
+----------------------+----------------------------------------+
| ``handle_accept()`` | Implied by a read event on a listening |
| | socket |
+----------------------+----------------------------------------+
During asynchronous processing, each mapped channel's :meth:`readable` and
:meth:`writable` methods are used to determine whether the channel's socket
should be added to the list of channels :c:func:`select`\ ed or
:c:func:`poll`\ ed for read and write events.
Thus, the set of channel events is larger than the basic socket events. The
full set of methods that can be overridden in your subclass follows:
.. method:: handle_read()
Called when the asynchronous loop detects that a :meth:`read` call on the
channel's socket will succeed.
.. method:: handle_write()
Called when the asynchronous loop detects that a writable socket can be
written. Often this method will implement the necessary buffering for
performance. For example::
def handle_write(self):
sent = self.send(self.buffer)
self.buffer = self.buffer[sent:]
.. method:: handle_expt()
Called when there is out of band (OOB) data for a socket connection. This
will almost never happen, as OOB is tenuously supported and rarely used.
.. method:: handle_connect()
Called when the active opener's socket actually makes a connection. Might
send a "welcome" banner, or initiate a protocol negotiation with the
remote endpoint, for example.
.. method:: handle_close()
Called when the socket is closed.
.. method:: handle_error()
Called when an exception is raised and not otherwise handled. The default
version prints a condensed traceback.
.. method:: handle_accept()
Called on listening channels (passive openers) when a connection can be
established with a new remote endpoint that has issued a :meth:`connect`
call for the local endpoint.
.. method:: readable()
Called each time around the asynchronous loop to determine whether a
channel's socket should be added to the list on which read events can
occur. The default method simply returns ``True``, indicating that by
default, all channels will be interested in read events.
.. method:: writable()
Called each time around the asynchronous loop to determine whether a
channel's socket should be added to the list on which write events can
occur. The default method simply returns ``True``, indicating that by
default, all channels will be interested in write events.
In addition, each channel delegates or extends many of the socket methods.
Most of these are nearly identical to their socket partners.
.. method:: create_socket(family, type)
This is identical to the creation of a normal socket, and will use the
same options for creation. Refer to the :mod:`socket` documentation for
information on creating sockets.
.. method:: connect(address)
As with the normal socket object, *address* is a tuple with the first
element the host to connect to, and the second the port number.
.. method:: send(data)
Send *data* to the remote end-point of the socket.
.. method:: recv(buffer_size)
Read at most *buffer_size* bytes from the socket's remote end-point. An
empty string implies that the channel has been closed from the other end.
Note that :meth:`recv` may raise :exc:`socket.error` with
:data:`~errno.EAGAIN` or :data:`~errno.EWOULDBLOCK`, even though
:func:`select.select` or :func:`select.poll` has reported the socket
ready for reading.
.. method:: listen(backlog)
Listen for connections made to the socket. The *backlog* argument
specifies the maximum number of queued connections and should be at least
1; the maximum value is system-dependent (usually 5).
.. method:: bind(address)
Bind the socket to *address*. The socket must not already be bound. (The
format of *address* depends on the address family --- refer to the
:mod:`socket` documentation for more information.) To mark
the socket as re-usable (setting the :const:`SO_REUSEADDR` option), call
the :class:`dispatcher` object's :meth:`set_reuse_addr` method.
.. method:: accept()
Accept a connection. The socket must be bound to an address and listening
for connections. The return value can be either ``None`` or a pair
``(conn, address)`` where *conn* is a *new* socket object usable to send
and receive data on the connection, and *address* is the address bound to
the socket on the other end of the connection.
When ``None`` is returned it means the connection didn't take place, in
which case the server should just ignore this event and keep listening
for further incoming connections.
.. method:: close()
Close the socket. All future operations on the socket object will fail.
The remote end-point will receive no more data (after queued data is
flushed). Sockets are automatically closed when they are
garbage-collected.
.. class:: dispatcher_with_send()
A :class:`dispatcher` subclass which adds simple buffered output capability,
useful for simple clients. For more sophisticated usage use
:class:`asynchat.async_chat`.
.. class:: file_dispatcher()
A file_dispatcher takes a file descriptor or file object along with an
optional map argument and wraps it for use with the :c:func:`poll` or
:c:func:`loop` functions. If provided a file object or anything with a
:c:func:`fileno` method, that method will be called and passed to the
:class:`file_wrapper` constructor. Availability: UNIX.
.. class:: file_wrapper()
A file_wrapper takes an integer file descriptor and calls :func:`os.dup` to
duplicate the handle so that the original handle may be closed independently
of the file_wrapper. This class implements sufficient methods to emulate a
socket for use by the :class:`file_dispatcher` class. Availability: UNIX.
.. _asyncore-example-1:
asyncore Example basic HTTP client
----------------------------------
Here is a very basic HTTP client that uses the :class:`dispatcher` class to
implement its socket handling::
import asyncore, socket
class HTTPClient(asyncore.dispatcher):
def __init__(self, host, path):
asyncore.dispatcher.__init__(self)
self.create_socket(socket.AF_INET, socket.SOCK_STREAM)
self.connect( (host, 80) )
self.buffer = 'GET %s HTTP/1.0\r\n\r\n' % path
def handle_connect(self):
pass
def handle_close(self):
self.close()
def handle_read(self):
print self.recv(8192)
def writable(self):
return (len(self.buffer) > 0)
def handle_write(self):
sent = self.send(self.buffer)
self.buffer = self.buffer[sent:]
client = HTTPClient('www.python.org', '/')
asyncore.loop()
.. _asyncore-example-2:
asyncore Example basic echo server
----------------------------------
Here is a basic echo server that uses the :class:`dispatcher` class to accept
connections and dispatches the incoming connections to a handler::
import asyncore
import socket
class EchoHandler(asyncore.dispatcher_with_send):
def handle_read(self):
data = self.recv(8192)
if data:
self.send(data)
class EchoServer(asyncore.dispatcher):
def __init__(self, host, port):
asyncore.dispatcher.__init__(self)
self.create_socket(socket.AF_INET, socket.SOCK_STREAM)
self.set_reuse_addr()
self.bind((host, port))
self.listen(5)
def handle_accept(self):
pair = self.accept()
if pair is not None:
sock, addr = pair
print 'Incoming connection from %s' % repr(addr)
handler = EchoHandler(sock)
server = EchoServer('localhost', 8080)
asyncore.loop()
PK %�\|��F F $ html/_sources/library/atexit.rst.txtnu �[��� :mod:`atexit` --- Exit handlers
===============================
.. module:: atexit
:synopsis: Register and execute cleanup functions.
.. moduleauthor:: Skip Montanaro <skip@pobox.com>
.. sectionauthor:: Skip Montanaro <skip@pobox.com>
.. versionadded:: 2.0
**Source code:** :source:`Lib/atexit.py`
--------------
The :mod:`atexit` module defines a single function to register cleanup
functions. Functions thus registered are automatically executed upon normal
interpreter termination. :mod:`atexit` runs these functions in the *reverse*
order in which they were registered; if you register ``A``, ``B``, and ``C``,
at interpreter termination time they will be run in the order ``C``, ``B``,
``A``.
**Note:** The functions registered via this module are not called when the
program is killed by a signal not handled by Python, when a Python fatal
internal error is detected, or when :func:`os._exit` is called.
.. index:: single: exitfunc (in sys)
This is an alternate interface to the functionality provided by the
:func:`sys.exitfunc` variable.
Note: This module is unlikely to work correctly when used with other code that
sets ``sys.exitfunc``. In particular, other core Python modules are free to use
:mod:`atexit` without the programmer's knowledge. Authors who use
``sys.exitfunc`` should convert their code to use :mod:`atexit` instead. The
simplest way to convert code that sets ``sys.exitfunc`` is to import
:mod:`atexit` and register the function that had been bound to ``sys.exitfunc``.
.. function:: register(func[, *args[, **kwargs]])
Register *func* as a function to be executed at termination. Any optional
arguments that are to be passed to *func* must be passed as arguments to
:func:`register`. It is possible to register the same function and arguments
more than once.
At normal program termination (for instance, if :func:`sys.exit` is called or
the main module's execution completes), all functions registered are called in
last in, first out order. The assumption is that lower level modules will
normally be imported before higher level modules and thus must be cleaned up
later.
If an exception is raised during execution of the exit handlers, a traceback is
printed (unless :exc:`SystemExit` is raised) and the exception information is
saved. After all exit handlers have had a chance to run the last exception to
be raised is re-raised.
.. versionchanged:: 2.6
This function now returns *func*, which makes it possible to use it as a
decorator.
.. seealso::
Module :mod:`readline`
Useful example of :mod:`atexit` to read and write :mod:`readline` history files.
.. _atexit-example:
:mod:`atexit` Example
---------------------
The following simple example demonstrates how a module can initialize a counter
from a file when it is imported and save the counter's updated value
automatically when the program terminates without relying on the application
making an explicit call into this module at termination. ::
try:
_count = int(open("counter").read())
except IOError:
_count = 0
def incrcounter(n):
global _count
_count = _count + n
def savecounter():
open("counter", "w").write("%d" % _count)
import atexit
atexit.register(savecounter)
Positional and keyword arguments may also be passed to :func:`register` to be
passed along to the registered function when it is called::
def goodbye(name, adjective):
print 'Goodbye, %s, it was %s to meet you.' % (name, adjective)
import atexit
atexit.register(goodbye, 'Donny', 'nice')
# or:
atexit.register(goodbye, adjective='nice', name='Donny')
Usage as a :term:`decorator`::
import atexit
@atexit.register
def goodbye():
print "You are now leaving the Python sector."
This only works with functions that can be called without arguments.
PK %�\��~�( �( % html/_sources/library/audioop.rst.txtnu �[���
:mod:`audioop` --- Manipulate raw audio data
============================================
.. module:: audioop
:synopsis: Manipulate raw audio data.
The :mod:`audioop` module contains some useful operations on sound fragments.
It operates on sound fragments consisting of signed integer samples 8, 16 or 32
bits wide, stored in Python strings. This is the same format as used by the
:mod:`al` and :mod:`sunaudiodev` modules. All scalar items are integers, unless
specified otherwise.
.. index::
single: Intel/DVI ADPCM
single: ADPCM, Intel/DVI
single: a-LAW
single: u-LAW
This module provides support for a-LAW, u-LAW and Intel/DVI ADPCM encodings.
.. This para is mostly here to provide an excuse for the index entries...
A few of the more complicated operations only take 16-bit samples, otherwise the
sample size (in bytes) is always a parameter of the operation.
The module defines the following variables and functions:
.. exception:: error
This exception is raised on all errors, such as unknown number of bytes per
sample, etc.
.. function:: add(fragment1, fragment2, width)
Return a fragment which is the addition of the two samples passed as parameters.
*width* is the sample width in bytes, either ``1``, ``2`` or ``4``. Both
fragments should have the same length. Samples are truncated in case of overflow.
.. function:: adpcm2lin(adpcmfragment, width, state)
Decode an Intel/DVI ADPCM coded fragment to a linear fragment. See the
description of :func:`lin2adpcm` for details on ADPCM coding. Return a tuple
``(sample, newstate)`` where the sample has the width specified in *width*.
.. function:: alaw2lin(fragment, width)
Convert sound fragments in a-LAW encoding to linearly encoded sound fragments.
a-LAW encoding always uses 8 bits samples, so *width* refers only to the sample
width of the output fragment here.
.. versionadded:: 2.5
.. function:: avg(fragment, width)
Return the average over all samples in the fragment.
.. function:: avgpp(fragment, width)
Return the average peak-peak value over all samples in the fragment. No
filtering is done, so the usefulness of this routine is questionable.
.. function:: bias(fragment, width, bias)
Return a fragment that is the original fragment with a bias added to each
sample. Samples wrap around in case of overflow.
.. function:: cross(fragment, width)
Return the number of zero crossings in the fragment passed as an argument.
.. function:: findfactor(fragment, reference)
Return a factor *F* such that ``rms(add(fragment, mul(reference, -F)))`` is
minimal, i.e., return the factor with which you should multiply *reference* to
make it match as well as possible to *fragment*. The fragments should both
contain 2-byte samples.
The time taken by this routine is proportional to ``len(fragment)``.
.. function:: findfit(fragment, reference)
Try to match *reference* as well as possible to a portion of *fragment* (which
should be the longer fragment). This is (conceptually) done by taking slices
out of *fragment*, using :func:`findfactor` to compute the best match, and
minimizing the result. The fragments should both contain 2-byte samples.
Return a tuple ``(offset, factor)`` where *offset* is the (integer) offset into
*fragment* where the optimal match started and *factor* is the (floating-point)
factor as per :func:`findfactor`.
.. function:: findmax(fragment, length)
Search *fragment* for a slice of length *length* samples (not bytes!) with
maximum energy, i.e., return *i* for which ``rms(fragment[i*2:(i+length)*2])``
is maximal. The fragments should both contain 2-byte samples.
The routine takes time proportional to ``len(fragment)``.
.. function:: getsample(fragment, width, index)
Return the value of sample *index* from the fragment.
.. function:: lin2adpcm(fragment, width, state)
Convert samples to 4 bit Intel/DVI ADPCM encoding. ADPCM coding is an adaptive
coding scheme, whereby each 4 bit number is the difference between one sample
and the next, divided by a (varying) step. The Intel/DVI ADPCM algorithm has
been selected for use by the IMA, so it may well become a standard.
*state* is a tuple containing the state of the coder. The coder returns a tuple
``(adpcmfrag, newstate)``, and the *newstate* should be passed to the next call
of :func:`lin2adpcm`. In the initial call, ``None`` can be passed as the state.
*adpcmfrag* is the ADPCM coded fragment packed 2 4-bit values per byte.
.. function:: lin2alaw(fragment, width)
Convert samples in the audio fragment to a-LAW encoding and return this as a
Python string. a-LAW is an audio encoding format whereby you get a dynamic
range of about 13 bits using only 8 bit samples. It is used by the Sun audio
hardware, among others.
.. versionadded:: 2.5
.. function:: lin2lin(fragment, width, newwidth)
Convert samples between 1-, 2- and 4-byte formats.
.. note::
In some audio formats, such as .WAV files, 16 and 32 bit samples are
signed, but 8 bit samples are unsigned. So when converting to 8 bit wide
samples for these formats, you need to also add 128 to the result::
new_frames = audioop.lin2lin(frames, old_width, 1)
new_frames = audioop.bias(new_frames, 1, 128)
The same, in reverse, has to be applied when converting from 8 to 16 or 32
bit width samples.
.. function:: lin2ulaw(fragment, width)
Convert samples in the audio fragment to u-LAW encoding and return this as a
Python string. u-LAW is an audio encoding format whereby you get a dynamic
range of about 14 bits using only 8 bit samples. It is used by the Sun audio
hardware, among others.
.. function:: max(fragment, width)
Return the maximum of the *absolute value* of all samples in a fragment.
.. function:: maxpp(fragment, width)
Return the maximum peak-peak value in the sound fragment.
.. function:: minmax(fragment, width)
Return a tuple consisting of the minimum and maximum values of all samples in
the sound fragment.
.. function:: mul(fragment, width, factor)
Return a fragment that has all samples in the original fragment multiplied by
the floating-point value *factor*. Samples are truncated in case of overflow.
.. function:: ratecv(fragment, width, nchannels, inrate, outrate, state[, weightA[, weightB]])
Convert the frame rate of the input fragment.
*state* is a tuple containing the state of the converter. The converter returns
a tuple ``(newfragment, newstate)``, and *newstate* should be passed to the next
call of :func:`ratecv`. The initial call should pass ``None`` as the state.
The *weightA* and *weightB* arguments are parameters for a simple digital filter
and default to ``1`` and ``0`` respectively.
.. function:: reverse(fragment, width)
Reverse the samples in a fragment and returns the modified fragment.
.. function:: rms(fragment, width)
Return the root-mean-square of the fragment, i.e. ``sqrt(sum(S_i^2)/n)``.
This is a measure of the power in an audio signal.
.. function:: tomono(fragment, width, lfactor, rfactor)
Convert a stereo fragment to a mono fragment. The left channel is multiplied by
*lfactor* and the right channel by *rfactor* before adding the two channels to
give a mono signal.
.. function:: tostereo(fragment, width, lfactor, rfactor)
Generate a stereo fragment from a mono fragment. Each pair of samples in the
stereo fragment are computed from the mono sample, whereby left channel samples
are multiplied by *lfactor* and right channel samples by *rfactor*.
.. function:: ulaw2lin(fragment, width)
Convert sound fragments in u-LAW encoding to linearly encoded sound fragments.
u-LAW encoding always uses 8 bits samples, so *width* refers only to the sample
width of the output fragment here.
Note that operations such as :func:`.mul` or :func:`.max` make no distinction
between mono and stereo fragments, i.e. all samples are treated equal. If this
is a problem the stereo fragment should be split into two mono fragments first
and recombined later. Here is an example of how to do that::
def mul_stereo(sample, width, lfactor, rfactor):
lsample = audioop.tomono(sample, width, 1, 0)
rsample = audioop.tomono(sample, width, 0, 1)
lsample = audioop.mul(lsample, width, lfactor)
rsample = audioop.mul(rsample, width, rfactor)
lsample = audioop.tostereo(lsample, width, 1, 0)
rsample = audioop.tostereo(rsample, width, 0, 1)
return audioop.add(lsample, rsample, width)
If you use the ADPCM coder to build network packets and you want your protocol
to be stateless (i.e. to be able to tolerate packet loss) you should not only
transmit the data but also the state. Note that you should send the *initial*
state (the one you passed to :func:`lin2adpcm`) along to the decoder, not the
final state (as returned by the coder). If you want to use
:class:`struct.Struct` to store the state in binary you can code the first
element (the predicted value) in 16 bits and the second (the delta index) in 8.
The ADPCM coders have never been tried against other ADPCM coders, only against
themselves. It could well be that I misinterpreted the standards in which case
they will not be interoperable with the respective standards.
The :func:`find\*` routines might look a bit funny at first sight. They are
primarily meant to do echo cancellation. A reasonably fast way to do this is to
pick the most energetic piece of the output sample, locate that in the input
sample and subtract the whole output sample from the input sample::
def echocancel(outputdata, inputdata):
pos = audioop.findmax(outputdata, 800) # one tenth second
out_test = outputdata[pos*2:]
in_test = inputdata[pos*2:]
ipos, factor = audioop.findfit(in_test, out_test)
# Optional (for better cancellation):
# factor = audioop.findfactor(in_test[ipos*2:ipos*2+len(out_test)],
# out_test)
prefill = '\0'*(pos+ipos)*2
postfill = '\0'*(len(inputdata)-len(prefill)-len(outputdata))
outputdata = prefill + audioop.mul(outputdata, 2, -factor) + postfill
return audioop.add(inputdata, outputdata, 2)
PK %�\ ��V� � % html/_sources/library/autogil.rst.txtnu �[���
:mod:`autoGIL` --- Global Interpreter Lock handling in event loops
==================================================================
.. module:: autoGIL
:platform: Mac
:synopsis: Global Interpreter Lock handling in event loops.
:deprecated:
.. moduleauthor:: Just van Rossum <just@letterror.com>
The :mod:`autoGIL` module provides a function :func:`installAutoGIL` that
automatically locks and unlocks Python's :term:`Global Interpreter Lock` when
running an event loop.
.. note::
This module has been removed in Python 3.x.
.. exception:: AutoGILError
Raised if the observer callback cannot be installed, for example because the
current thread does not have a run loop.
.. function:: installAutoGIL()
Install an observer callback in the event loop (CFRunLoop) for the current
thread, that will lock and unlock the Global Interpreter Lock (GIL) at
appropriate times, allowing other Python threads to run while the event loop is
idle.
Availability: OSX 10.1 or later.
PK %�\Q�{l l $ html/_sources/library/base64.rst.txtnu �[��� :mod:`base64` --- RFC 3548: Base16, Base32, Base64 Data Encodings
=================================================================
.. module:: base64
:synopsis: RFC 3548: Base16, Base32, Base64 Data Encodings
.. index::
pair: base64; encoding
single: MIME; base64 encoding
This module provides data encoding and decoding as specified in :rfc:`3548`.
This standard defines the Base16, Base32, and Base64 algorithms for encoding and
decoding arbitrary binary strings into text strings that can be safely sent by
email, used as parts of URLs, or included as part of an HTTP POST request. The
encoding algorithm is not the same as the :program:`uuencode` program.
There are two interfaces provided by this module. The modern interface supports
encoding and decoding string objects using both base-64 alphabets defined
in :rfc:`3548` (normal, and URL- and filesystem-safe). The legacy
interface provides for encoding and decoding to and from file-like objects as
well as strings, but only using the Base64 standard alphabet.
The modern interface, which was introduced in Python 2.4, provides:
.. function:: b64encode(s[, altchars])
Encode a string using Base64.
*s* is the string to encode. Optional *altchars* must be a string of at least
length 2 (additional characters are ignored) which specifies an alternative
alphabet for the ``+`` and ``/`` characters. This allows an application to e.g.
generate URL or filesystem safe Base64 strings. The default is ``None``, for
which the standard Base64 alphabet is used.
The encoded string is returned.
.. function:: b64decode(s[, altchars])
Decode a Base64 encoded string.
*s* is the string to decode. Optional *altchars* must be a string of at least
length 2 (additional characters are ignored) which specifies the alternative
alphabet used instead of the ``+`` and ``/`` characters.
The decoded string is returned. A :exc:`TypeError` is raised if *s* is
incorrectly padded. Characters that are neither
in the normal base-64 alphabet nor the alternative alphabet are
discarded prior to the padding check.
.. function:: standard_b64encode(s)
Encode string *s* using the standard Base64 alphabet.
.. function:: standard_b64decode(s)
Decode string *s* using the standard Base64 alphabet.
.. function:: urlsafe_b64encode(s)
Encode string *s* using the URL- and filesystem-safe
alphabet, which substitutes ``-`` instead of
``+`` and ``_`` instead of ``/`` in the standard Base64 alphabet. The result
can still contain ``=``.
.. function:: urlsafe_b64decode(s)
Decode string *s* using the URL- and filesystem-safe
alphabet, which substitutes ``-`` instead of
``+`` and ``_`` instead of ``/`` in the standard Base64 alphabet.
.. function:: b32encode(s)
Encode a string using Base32. *s* is the string to encode. The encoded string
is returned.
.. function:: b32decode(s[, casefold[, map01]])
Decode a Base32 encoded string.
*s* is the string to decode. Optional *casefold* is a flag specifying whether a
lowercase alphabet is acceptable as input. For security purposes, the default
is ``False``.
:rfc:`3548` allows for optional mapping of the digit 0 (zero) to the letter O
(oh), and for optional mapping of the digit 1 (one) to either the letter I (eye)
or letter L (el). The optional argument *map01* when not ``None``, specifies
which letter the digit 1 should be mapped to (when *map01* is not ``None``, the
digit 0 is always mapped to the letter O). For security purposes the default is
``None``, so that 0 and 1 are not allowed in the input.
The decoded string is returned. A :exc:`TypeError` is raised if *s* is
incorrectly padded or if there are non-alphabet characters present in the
string.
.. function:: b16encode(s)
Encode a string using Base16.
*s* is the string to encode. The encoded string is returned.
.. function:: b16decode(s[, casefold])
Decode a Base16 encoded string.
*s* is the string to decode. Optional *casefold* is a flag specifying whether a
lowercase alphabet is acceptable as input. For security purposes, the default
is ``False``.
The decoded string is returned. A :exc:`TypeError` is raised if *s* were
incorrectly padded or if there are non-alphabet characters present in the
string.
The legacy interface:
.. function:: decode(input, output)
Decode the contents of the *input* file and write the resulting binary data to
the *output* file. *input* and *output* must either be file objects or objects
that mimic the file object interface. *input* will be read until
``input.read()`` returns an empty string.
.. function:: decodestring(s)
Decode the string *s*, which must contain one or more lines of base64 encoded
data, and return a string containing the resulting binary data.
.. function:: encode(input, output)
Encode the contents of the *input* file and write the resulting base64 encoded
data to the *output* file. *input* and *output* must either be file objects or
objects that mimic the file object interface. *input* will be read until
``input.read()`` returns an empty string. :func:`encode` returns the encoded
data plus a trailing newline character (``'\n'``).
.. function:: encodestring(s)
Encode the string *s*, which can contain arbitrary binary data, and return a
string containing one or more lines of base64-encoded data.
:func:`encodestring` returns a string containing one or more lines of
base64-encoded data always including an extra trailing newline (``'\n'``).
An example usage of the module:
>>> import base64
>>> encoded = base64.b64encode('data to be encoded')
>>> encoded
'ZGF0YSB0byBiZSBlbmNvZGVk'
>>> data = base64.b64decode(encoded)
>>> data
'data to be encoded'
.. seealso::
Module :mod:`binascii`
Support module containing ASCII-to-binary and binary-to-ASCII conversions.
:rfc:`1521` - MIME (Multipurpose Internet Mail Extensions) Part One: Mechanisms for Specifying and Describing the Format of Internet Message Bodies
Section 5.2, "Base64 Content-Transfer-Encoding," provides the definition of the
base64 encoding.
PK %�\�Q�^�( �( , html/_sources/library/basehttpserver.rst.txtnu �[��� :mod:`BaseHTTPServer` --- Basic HTTP server
===========================================
.. module:: BaseHTTPServer
:synopsis: Basic HTTP server (base class for SimpleHTTPServer and CGIHTTPServer).
.. note::
The :mod:`BaseHTTPServer` module has been merged into :mod:`http.server` in
Python 3. The :term:`2to3` tool will automatically adapt imports when
converting your sources to Python 3.
.. index::
pair: WWW; server
pair: HTTP; protocol
single: URL
single: httpd
module: SimpleHTTPServer
module: CGIHTTPServer
**Source code:** :source:`Lib/BaseHTTPServer.py`
--------------
This module defines two classes for implementing HTTP servers (Web servers).
Usually, this module isn't used directly, but is used as a basis for building
functioning Web servers. See the :mod:`SimpleHTTPServer` and
:mod:`CGIHTTPServer` modules.
The first class, :class:`HTTPServer`, is a :class:`SocketServer.TCPServer`
subclass, and therefore implements the :class:`SocketServer.BaseServer`
interface. It creates and listens at the HTTP socket, dispatching the requests
to a handler. Code to create and run the server looks like this::
def run(server_class=BaseHTTPServer.HTTPServer,
handler_class=BaseHTTPServer.BaseHTTPRequestHandler):
server_address = ('', 8000)
httpd = server_class(server_address, handler_class)
httpd.serve_forever()
.. class:: HTTPServer(server_address, RequestHandlerClass)
This class builds on the :class:`TCPServer` class by storing the server
address as instance variables named :attr:`server_name` and
:attr:`server_port`. The server is accessible by the handler, typically
through the handler's :attr:`server` instance variable.
.. class:: BaseHTTPRequestHandler(request, client_address, server)
This class is used to handle the HTTP requests that arrive at the server. By
itself, it cannot respond to any actual HTTP requests; it must be subclassed
to handle each request method (e.g. GET or
POST). :class:`BaseHTTPRequestHandler` provides a number of class and
instance variables, and methods for use by subclasses.
The handler will parse the request and the headers, then call a method
specific to the request type. The method name is constructed from the
request. For example, for the request method ``SPAM``, the :meth:`do_SPAM`
method will be called with no arguments. All of the relevant information is
stored in instance variables of the handler. Subclasses should not need to
override or extend the :meth:`__init__` method.
:class:`BaseHTTPRequestHandler` has the following instance variables:
.. attribute:: client_address
Contains a tuple of the form ``(host, port)`` referring to the client's
address.
.. attribute:: server
Contains the server instance.
.. attribute:: command
Contains the command (request type). For example, ``'GET'``.
.. attribute:: path
Contains the request path.
.. attribute:: request_version
Contains the version string from the request. For example, ``'HTTP/1.0'``.
.. attribute:: headers
Holds an instance of the class specified by the :attr:`MessageClass` class
variable. This instance parses and manages the headers in the HTTP
request.
.. attribute:: rfile
Contains an input stream, positioned at the start of the optional input
data.
.. attribute:: wfile
Contains the output stream for writing a response back to the
client. Proper adherence to the HTTP protocol must be used when writing to
this stream.
:class:`BaseHTTPRequestHandler` has the following class variables:
.. attribute:: server_version
Specifies the server software version. You may want to override this. The
format is multiple whitespace-separated strings, where each string is of
the form name[/version]. For example, ``'BaseHTTP/0.2'``.
.. attribute:: sys_version
Contains the Python system version, in a form usable by the
:attr:`version_string` method and the :attr:`server_version` class
variable. For example, ``'Python/1.4'``.
.. attribute:: error_message_format
Specifies a format string for building an error response to the client. It
uses parenthesized, keyed format specifiers, so the format operand must be
a dictionary. The *code* key should be an integer, specifying the numeric
HTTP error code value. *message* should be a string containing a
(detailed) error message of what occurred, and *explain* should be an
explanation of the error code number. Default *message* and *explain*
values can found in the *responses* class variable.
.. attribute:: error_content_type
Specifies the Content-Type HTTP header of error responses sent to the
client. The default value is ``'text/html'``.
.. versionadded:: 2.6
Previously, the content type was always ``'text/html'``.
.. attribute:: protocol_version
This specifies the HTTP protocol version used in responses. If set to
``'HTTP/1.1'``, the server will permit HTTP persistent connections;
however, your server *must* then include an accurate ``Content-Length``
header (using :meth:`send_header`) in all of its responses to clients.
For backwards compatibility, the setting defaults to ``'HTTP/1.0'``.
.. attribute:: MessageClass
.. index:: single: Message (in module mimetools)
Specifies a :class:`rfc822.Message`\ -like class to parse HTTP headers.
Typically, this is not overridden, and it defaults to
:class:`mimetools.Message`.
.. attribute:: responses
This variable contains a mapping of error code integers to two-element tuples
containing a short and long message. For example, ``{code: (shortmessage,
longmessage)}``. The *shortmessage* is usually used as the *message* key in an
error response, and *longmessage* as the *explain* key (see the
:attr:`error_message_format` class variable).
A :class:`BaseHTTPRequestHandler` instance has the following methods:
.. method:: handle()
Calls :meth:`handle_one_request` once (or, if persistent connections are
enabled, multiple times) to handle incoming HTTP requests. You should
never need to override it; instead, implement appropriate :meth:`do_\*`
methods.
.. method:: handle_one_request()
This method will parse and dispatch the request to the appropriate
:meth:`do_\*` method. You should never need to override it.
.. method:: send_error(code[, message])
Sends and logs a complete error reply to the client. The numeric *code*
specifies the HTTP error code, with *message* as optional, more specific text. A
complete set of headers is sent, followed by text composed using the
:attr:`error_message_format` class variable. The body will be empty
if the method is HEAD or the response code is one of the following:
``1xx``, ``204 No Content``, ``205 Reset Content``,
``304 Not Modified``.
.. method:: send_response(code[, message])
Sends a response header and logs the accepted request. The HTTP response
line is sent, followed by *Server* and *Date* headers. The values for
these two headers are picked up from the :meth:`version_string` and
:meth:`date_time_string` methods, respectively.
.. method:: send_header(keyword, value)
Writes a specific HTTP header to the output stream. *keyword* should
specify the header keyword, with *value* specifying its value.
.. method:: end_headers()
Sends a blank line, indicating the end of the HTTP headers in the
response.
.. method:: log_request([code[, size]])
Logs an accepted (successful) request. *code* should specify the numeric
HTTP code associated with the response. If a size of the response is
available, then it should be passed as the *size* parameter.
.. method:: log_error(...)
Logs an error when a request cannot be fulfilled. By default, it passes
the message to :meth:`log_message`, so it takes the same arguments
(*format* and additional values).
.. method:: log_message(format, ...)
Logs an arbitrary message to ``sys.stderr``. This is typically overridden
to create custom error logging mechanisms. The *format* argument is a
standard printf-style format string, where the additional arguments to
:meth:`log_message` are applied as inputs to the formatting. The client
ip address and current date and time are prefixed to every message logged.
.. method:: version_string()
Returns the server software's version string. This is a combination of the
:attr:`server_version` and :attr:`sys_version` class variables.
.. method:: date_time_string([timestamp])
Returns the date and time given by *timestamp* (which must be in the
format returned by :func:`time.time`), formatted for a message header. If
*timestamp* is omitted, it uses the current date and time.
The result looks like ``'Sun, 06 Nov 1994 08:49:37 GMT'``.
.. versionadded:: 2.5
The *timestamp* parameter.
.. method:: log_date_time_string()
Returns the current date and time, formatted for logging.
.. method:: address_string()
Returns the client address, formatted for logging. A name lookup is
performed on the client's IP address.
More examples
-------------
To create a server that doesn't run forever, but until some condition is
fulfilled::
def run_while_true(server_class=BaseHTTPServer.HTTPServer,
handler_class=BaseHTTPServer.BaseHTTPRequestHandler):
"""
This assumes that keep_running() is a function of no arguments which
is tested initially and after each request. If its return value
is true, the server continues.
"""
server_address = ('', 8000)
httpd = server_class(server_address, handler_class)
while keep_running():
httpd.handle_request()
.. seealso::
Module :mod:`CGIHTTPServer`
Extended request handler that supports CGI scripts.
Module :mod:`SimpleHTTPServer`
Basic request handler that limits response to files actually under the
document root.
PK %�\a�3
3
% html/_sources/library/bastion.rst.txtnu �[���
:mod:`Bastion` --- Restricting access to objects
================================================
.. module:: Bastion
:synopsis: Providing restricted access to objects.
:deprecated:
.. deprecated:: 2.6
The :mod:`Bastion` module has been removed in Python 3.
.. moduleauthor:: Barry Warsaw <bwarsaw@python.org>
.. versionchanged:: 2.3
Disabled module.
.. note::
The documentation has been left in place to help in reading old code that uses
the module.
According to the dictionary, a bastion is "a fortified area or position", or
"something that is considered a stronghold." It's a suitable name for this
module, which provides a way to forbid access to certain attributes of an
object. It must always be used with the :mod:`rexec` module, in order to allow
restricted-mode programs access to certain safe attributes of an object, while
denying access to other, unsafe attributes.
.. I'm concerned that the word 'bastion' won't be understood by people
.. for whom English is a second language, making the module name
.. somewhat mysterious. Thus, the brief definition... --amk
.. I've punted on the issue of documenting keyword arguments for now.
.. function:: Bastion(object[, filter[, name[, class]]])
Protect the object *object*, returning a bastion for the object. Any attempt to
access one of the object's attributes will have to be approved by the *filter*
function; if the access is denied an :exc:`AttributeError` exception will be
raised.
If present, *filter* must be a function that accepts a string containing an
attribute name, and returns true if access to that attribute will be permitted;
if *filter* returns false, the access is denied. The default filter denies
access to any function beginning with an underscore (``'_'``). The bastion's
string representation will be ``<Bastion for name>`` if a value for *name* is
provided; otherwise, ``repr(object)`` will be used.
*class*, if present, should be a subclass of :class:`BastionClass`; see the
code in :file:`bastion.py` for the details. Overriding the default
:class:`BastionClass` will rarely be required.
.. class:: BastionClass(getfunc, name)
Class which actually implements bastion objects. This is the default class used
by :func:`Bastion`. The *getfunc* parameter is a function which returns the
value of an attribute which should be exposed to the restricted execution
environment when called with the name of the attribute as the only parameter.
*name* is used to construct the :func:`repr` of the :class:`BastionClass`
instance.
PK %�\��N�0 �0 ! html/_sources/library/bdb.rst.txtnu �[��� :mod:`bdb` --- Debugger framework
=================================
.. module:: bdb
:synopsis: Debugger framework.
**Source code:** :source:`Lib/bdb.py`
--------------
The :mod:`bdb` module handles basic debugger functions, like setting breakpoints
or managing execution via the debugger.
The following exception is defined:
.. exception:: BdbQuit
Exception raised by the :class:`Bdb` class for quitting the debugger.
The :mod:`bdb` module also defines two classes:
.. class:: Breakpoint(self, file, line, temporary=0, cond=None, funcname=None)
This class implements temporary breakpoints, ignore counts, disabling and
(re-)enabling, and conditionals.
Breakpoints are indexed by number through a list called :attr:`bpbynumber`
and by ``(file, line)`` pairs through :attr:`bplist`. The former points to a
single instance of class :class:`Breakpoint`. The latter points to a list of
such instances since there may be more than one breakpoint per line.
When creating a breakpoint, its associated filename should be in canonical
form. If a *funcname* is defined, a breakpoint hit will be counted when the
first line of that function is executed. A conditional breakpoint always
counts a hit.
:class:`Breakpoint` instances have the following methods:
.. method:: deleteMe()
Delete the breakpoint from the list associated to a file/line. If it is
the last breakpoint in that position, it also deletes the entry for the
file/line.
.. method:: enable()
Mark the breakpoint as enabled.
.. method:: disable()
Mark the breakpoint as disabled.
.. method:: pprint([out])
Print all the information about the breakpoint:
* The breakpoint number.
* If it is temporary or not.
* Its file,line position.
* The condition that causes a break.
* If it must be ignored the next N times.
* The breakpoint hit count.
.. class:: Bdb(skip=None)
The :class:`Bdb` class acts as a generic Python debugger base class.
This class takes care of the details of the trace facility; a derived class
should implement user interaction. The standard debugger class
(:class:`pdb.Pdb`) is an example.
The *skip* argument, if given, must be an iterable of glob-style
module name patterns. The debugger will not step into frames that
originate in a module that matches one of these patterns. Whether a
frame is considered to originate in a certain module is determined
by the ``__name__`` in the frame globals.
.. versionadded:: 2.7
The *skip* argument.
The following methods of :class:`Bdb` normally don't need to be overridden.
.. method:: canonic(filename)
Auxiliary method for getting a filename in a canonical form, that is, as a
case-normalized (on case-insensitive filesystems) absolute path, stripped
of surrounding angle brackets.
.. method:: reset()
Set the :attr:`botframe`, :attr:`stopframe`, :attr:`returnframe` and
:attr:`quitting` attributes with values ready to start debugging.
.. method:: trace_dispatch(frame, event, arg)
This function is installed as the trace function of debugged frames. Its
return value is the new trace function (in most cases, that is, itself).
The default implementation decides how to dispatch a frame, depending on
the type of event (passed as a string) that is about to be executed.
*event* can be one of the following:
* ``"line"``: A new line of code is going to be executed.
* ``"call"``: A function is about to be called, or another code block
entered.
* ``"return"``: A function or other code block is about to return.
* ``"exception"``: An exception has occurred.
* ``"c_call"``: A C function is about to be called.
* ``"c_return"``: A C function has returned.
* ``"c_exception"``: A C function has raised an exception.
For the Python events, specialized functions (see below) are called. For
the C events, no action is taken.
The *arg* parameter depends on the previous event.
See the documentation for :func:`sys.settrace` for more information on the
trace function. For more information on code and frame objects, refer to
:ref:`types`.
.. method:: dispatch_line(frame)
If the debugger should stop on the current line, invoke the
:meth:`user_line` method (which should be overridden in subclasses).
Raise a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set
(which can be set from :meth:`user_line`). Return a reference to the
:meth:`trace_dispatch` method for further tracing in that scope.
.. method:: dispatch_call(frame, arg)
If the debugger should stop on this function call, invoke the
:meth:`user_call` method (which should be overridden in subclasses).
Raise a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set
(which can be set from :meth:`user_call`). Return a reference to the
:meth:`trace_dispatch` method for further tracing in that scope.
.. method:: dispatch_return(frame, arg)
If the debugger should stop on this function return, invoke the
:meth:`user_return` method (which should be overridden in subclasses).
Raise a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set
(which can be set from :meth:`user_return`). Return a reference to the
:meth:`trace_dispatch` method for further tracing in that scope.
.. method:: dispatch_exception(frame, arg)
If the debugger should stop at this exception, invokes the
:meth:`user_exception` method (which should be overridden in subclasses).
Raise a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set
(which can be set from :meth:`user_exception`). Return a reference to the
:meth:`trace_dispatch` method for further tracing in that scope.
Normally derived classes don't override the following methods, but they may
if they want to redefine the definition of stopping and breakpoints.
.. method:: stop_here(frame)
This method checks if the *frame* is somewhere below :attr:`botframe` in
the call stack. :attr:`botframe` is the frame in which debugging started.
.. method:: break_here(frame)
This method checks if there is a breakpoint in the filename and line
belonging to *frame* or, at least, in the current function. If the
breakpoint is a temporary one, this method deletes it.
.. method:: break_anywhere(frame)
This method checks if there is a breakpoint in the filename of the current
frame.
Derived classes should override these methods to gain control over debugger
operation.
.. method:: user_call(frame, argument_list)
This method is called from :meth:`dispatch_call` when there is the
possibility that a break might be necessary anywhere inside the called
function.
.. method:: user_line(frame)
This method is called from :meth:`dispatch_line` when either
:meth:`stop_here` or :meth:`break_here` yields ``True``.
.. method:: user_return(frame, return_value)
This method is called from :meth:`dispatch_return` when :meth:`stop_here`
yields ``True``.
.. method:: user_exception(frame, exc_info)
This method is called from :meth:`dispatch_exception` when
:meth:`stop_here` yields ``True``.
.. method:: do_clear(arg)
Handle how a breakpoint must be removed when it is a temporary one.
This method must be implemented by derived classes.
Derived classes and clients can call the following methods to affect the
stepping state.
.. method:: set_step()
Stop after one line of code.
.. method:: set_next(frame)
Stop on the next line in or below the given frame.
.. method:: set_return(frame)
Stop when returning from the given frame.
.. method:: set_until(frame)
Stop when the line with the line no greater than the current one is
reached or when returning from current frame.
.. method:: set_trace([frame])
Start debugging from *frame*. If *frame* is not specified, debugging
starts from caller's frame.
.. method:: set_continue()
Stop only at breakpoints or when finished. If there are no breakpoints,
set the system trace function to ``None``.
.. method:: set_quit()
Set the :attr:`quitting` attribute to ``True``. This raises :exc:`BdbQuit` in
the next call to one of the :meth:`dispatch_\*` methods.
Derived classes and clients can call the following methods to manipulate
breakpoints. These methods return a string containing an error message if
something went wrong, or ``None`` if all is well.
.. method:: set_break(filename, lineno, temporary=0, cond=None, funcname=None)
Set a new breakpoint. If the *lineno* line doesn't exist for the
*filename* passed as argument, return an error message. The *filename*
should be in canonical form, as described in the :meth:`canonic` method.
.. method:: clear_break(filename, lineno)
Delete the breakpoints in *filename* and *lineno*. If none were set, an
error message is returned.
.. method:: clear_bpbynumber(arg)
Delete the breakpoint which has the index *arg* in the
:attr:`Breakpoint.bpbynumber`. If *arg* is not numeric or out of range,
return an error message.
.. method:: clear_all_file_breaks(filename)
Delete all breakpoints in *filename*. If none were set, an error message
is returned.
.. method:: clear_all_breaks()
Delete all existing breakpoints.
.. method:: get_break(filename, lineno)
Check if there is a breakpoint for *lineno* of *filename*.
.. method:: get_breaks(filename, lineno)
Return all breakpoints for *lineno* in *filename*, or an empty list if
none are set.
.. method:: get_file_breaks(filename)
Return all breakpoints in *filename*, or an empty list if none are set.
.. method:: get_all_breaks()
Return all breakpoints that are set.
Derived classes and clients can call the following methods to get a data
structure representing a stack trace.
.. method:: get_stack(f, t)
Get a list of records for a frame and all higher (calling) and lower
frames, and the size of the higher part.
.. method:: format_stack_entry(frame_lineno, [lprefix=': '])
Return a string with information about a stack entry, identified by a
``(frame, lineno)`` tuple:
* The canonical form of the filename which contains the frame.
* The function name, or ``"<lambda>"``.
* The input arguments.
* The return value.
* The line of code (if it exists).
The following two methods can be called by clients to use a debugger to debug
a :term:`statement`, given as a string.
.. method:: run(cmd, [globals, [locals]])
Debug a statement executed via the :keyword:`exec` statement. *globals*
defaults to :attr:`__main__.__dict__`, *locals* defaults to *globals*.
.. method:: runeval(expr, [globals, [locals]])
Debug an expression executed via the :func:`eval` function. *globals* and
*locals* have the same meaning as in :meth:`run`.
.. method:: runctx(cmd, globals, locals)
For backwards compatibility. Calls the :meth:`run` method.
.. method:: runcall(func, *args, **kwds)
Debug a single function call, and return its result.
Finally, the module defines the following functions:
.. function:: checkfuncname(b, frame)
Check whether we should break here, depending on the way the breakpoint *b*
was set.
If it was set via line number, it checks if ``b.line`` is the same as the one
in the frame also passed as argument. If the breakpoint was set via function
name, we have to check we are in the right frame (the right function) and if
we are in its first executable line.
.. function:: effective(file, line, frame)
Determine if there is an effective (active) breakpoint at this line of code.
Return a tuple of the breakpoint and a boolean that indicates if it is ok
to delete a temporary breakpoint. Return ``(None, None)`` if there is no
matching breakpoint.
.. function:: set_trace()
Start debugging with a :class:`Bdb` instance from caller's frame.
PK %�\����l l & html/_sources/library/binascii.rst.txtnu �[���
:mod:`binascii` --- Convert between binary and ASCII
====================================================
.. module:: binascii
:synopsis: Tools for converting between binary and various ASCII-encoded binary
representations.
.. index::
module: uu
module: base64
module: binhex
The :mod:`binascii` module contains a number of methods to convert between
binary and various ASCII-encoded binary representations. Normally, you will not
use these functions directly but use wrapper modules like :mod:`uu`,
:mod:`base64`, or :mod:`binhex` instead. The :mod:`binascii` module contains
low-level functions written in C for greater speed that are used by the
higher-level modules.
The :mod:`binascii` module defines the following functions:
.. function:: a2b_uu(string)
Convert a single line of uuencoded data back to binary and return the binary
data. Lines normally contain 45 (binary) bytes, except for the last line. Line
data may be followed by whitespace.
.. function:: b2a_uu(data)
Convert binary data to a line of ASCII characters, the return value is the
converted line, including a newline char. The length of *data* should be at most
45.
.. function:: a2b_base64(string)
Convert a block of base64 data back to binary and return the binary data. More
than one line may be passed at a time.
.. function:: b2a_base64(data)
Convert binary data to a line of ASCII characters in base64 coding. The return
value is the converted line, including a newline char. The newline is
added because the original use case for this function was to feed it a
series of 57 byte input lines to get output lines that conform to the
MIME-base64 standard. Otherwise the output conforms to :rfc:`3548`.
.. function:: a2b_qp(string[, header])
Convert a block of quoted-printable data back to binary and return the binary
data. More than one line may be passed at a time. If the optional argument
*header* is present and true, underscores will be decoded as spaces.
.. function:: b2a_qp(data[, quotetabs, istext, header])
Convert binary data to a line(s) of ASCII characters in quoted-printable
encoding. The return value is the converted line(s). If the optional argument
*quotetabs* is present and true, all tabs and spaces will be encoded. If the
optional argument *istext* is present and true, newlines are not encoded but
trailing whitespace will be encoded. If the optional argument *header* is
present and true, spaces will be encoded as underscores per RFC1522. If the
optional argument *header* is present and false, newline characters will be
encoded as well; otherwise linefeed conversion might corrupt the binary data
stream.
.. function:: a2b_hqx(string)
Convert binhex4 formatted ASCII data to binary, without doing RLE-decompression.
The string should contain a complete number of binary bytes, or (in case of the
last portion of the binhex4 data) have the remaining bits zero.
.. function:: rledecode_hqx(data)
Perform RLE-decompression on the data, as per the binhex4 standard. The
algorithm uses ``0x90`` after a byte as a repeat indicator, followed by a count.
A count of ``0`` specifies a byte value of ``0x90``. The routine returns the
decompressed data, unless data input data ends in an orphaned repeat indicator,
in which case the :exc:`Incomplete` exception is raised.
.. function:: rlecode_hqx(data)
Perform binhex4 style RLE-compression on *data* and return the result.
.. function:: b2a_hqx(data)
Perform hexbin4 binary-to-ASCII translation and return the resulting string. The
argument should already be RLE-coded, and have a length divisible by 3 (except
possibly the last fragment).
.. function:: crc_hqx(data, crc)
Compute a 16-bit CRC value of *data*, starting with an initial *crc* and
returning the result. This uses the CRC-CCITT polynomial
*x*:sup:`16` + *x*:sup:`12` + *x*:sup:`5` + 1, often represented as
0x1021. This CRC is used in the binhex4 format.
.. function:: crc32(data[, crc])
Compute CRC-32, the 32-bit checksum of data, starting with an initial crc. This
is consistent with the ZIP file checksum. Since the algorithm is designed for
use as a checksum algorithm, it is not suitable for use as a general hash
algorithm. Use as follows::
print binascii.crc32("hello world")
# Or, in two pieces:
crc = binascii.crc32("hello")
crc = binascii.crc32(" world", crc) & 0xffffffff
print 'crc32 = 0x%08x' % crc
.. note::
To generate the same numeric value across all Python versions and
platforms use crc32(data) & 0xffffffff. If you are only using
the checksum in packed binary format this is not necessary as the
return value is the correct 32bit binary representation
regardless of sign.
.. versionchanged:: 2.6
The return value is in the range [-2**31, 2**31-1]
regardless of platform. In the past the value would be signed on
some platforms and unsigned on others. Use & 0xffffffff on the
value if you want it to match Python 3 behavior.
.. versionchanged:: 3.0
The return value is unsigned and in the range [0, 2**32-1]
regardless of platform.
.. function:: b2a_hex(data)
hexlify(data)
Return the hexadecimal representation of the binary *data*. Every byte of
*data* is converted into the corresponding 2-digit hex representation. The
resulting string is therefore twice as long as the length of *data*.
.. function:: a2b_hex(hexstr)
unhexlify(hexstr)
Return the binary data represented by the hexadecimal string *hexstr*. This
function is the inverse of :func:`b2a_hex`. *hexstr* must contain an even number
of hexadecimal digits (which can be upper or lower case), otherwise a
:exc:`TypeError` is raised.
.. exception:: Error
Exception raised on errors. These are usually programming errors.
.. exception:: Incomplete
Exception raised on incomplete data. These are usually not programming errors,
but may be handled by reading a little more data and trying again.
.. seealso::
Module :mod:`base64`
Support for RFC compliant base64-style encoding in base 16, 32, and 64.
Module :mod:`binhex`
Support for the binhex format used on the Macintosh.
Module :mod:`uu`
Support for UU encoding used on Unix.
Module :mod:`quopri`
Support for quoted-printable encoding used in MIME email messages.
PK %�\�ؗv v $ html/_sources/library/binhex.rst.txtnu �[��� :mod:`binhex` --- Encode and decode binhex4 files
=================================================
.. module:: binhex
:synopsis: Encode and decode files in binhex4 format.
This module encodes and decodes files in binhex4 format, a format allowing
representation of Macintosh files in ASCII. On the Macintosh, both forks of a
file and the finder information are encoded (or decoded), on other platforms
only the data fork is handled.
.. note::
In Python 3.x, special Macintosh support has been removed.
The :mod:`binhex` module defines the following functions:
.. function:: binhex(input, output)
Convert a binary file with filename *input* to binhex file *output*. The
*output* parameter can either be a filename or a file-like object (any object
supporting a :meth:`write` and :meth:`close` method).
.. function:: hexbin(input[, output])
Decode a binhex file *input*. *input* may be a filename or a file-like object
supporting :meth:`read` and :meth:`close` methods. The resulting file is written
to a file named *output*, unless the argument is omitted in which case the
output filename is read from the binhex file.
The following exception is also defined:
.. exception:: Error
Exception raised when something can't be encoded using the binhex format (for
example, a filename is too long to fit in the filename field), or when input is
not properly encoded binhex data.
.. seealso::
Module :mod:`binascii`
Support module containing ASCII-to-binary and binary-to-ASCII conversions.
.. _binhex-notes:
Notes
-----
There is an alternative, more powerful interface to the coder and decoder, see
the source for details.
If you code or decode textfiles on non-Macintosh platforms they will still use
the old Macintosh newline convention (carriage-return as end of line).
As of this writing, :func:`hexbin` appears to not work in all cases.
PK %�\�U,�' ' $ html/_sources/library/bisect.rst.txtnu �[��� :mod:`bisect` --- Array bisection algorithm
===========================================
.. module:: bisect
:synopsis: Array bisection algorithms for binary searching.
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
.. sectionauthor:: Raymond Hettinger <python at rcn.com>
.. example based on the PyModules FAQ entry by Aaron Watters <arw@pythonpros.com>
.. versionadded:: 2.1
**Source code:** :source:`Lib/bisect.py`
--------------
This module provides support for maintaining a list in sorted order without
having to sort the list after each insertion. For long lists of items with
expensive comparison operations, this can be an improvement over the more common
approach. The module is called :mod:`bisect` because it uses a basic bisection
algorithm to do its work. The source code may be most useful as a working
example of the algorithm (the boundary conditions are already right!).
The following functions are provided:
.. function:: bisect_left(a, x, lo=0, hi=len(a))
Locate the insertion point for *x* in *a* to maintain sorted order.
The parameters *lo* and *hi* may be used to specify a subset of the list
which should be considered; by default the entire list is used. If *x* is
already present in *a*, the insertion point will be before (to the left of)
any existing entries. The return value is suitable for use as the first
parameter to ``list.insert()`` assuming that *a* is already sorted.
The returned insertion point *i* partitions the array *a* into two halves so
that ``all(val < x for val in a[lo:i])`` for the left side and
``all(val >= x for val in a[i:hi])`` for the right side.
.. function:: bisect_right(a, x, lo=0, hi=len(a))
bisect(a, x, lo=0, hi=len(a))
Similar to :func:`bisect_left`, but returns an insertion point which comes
after (to the right of) any existing entries of *x* in *a*.
The returned insertion point *i* partitions the array *a* into two halves so
that ``all(val <= x for val in a[lo:i])`` for the left side and
``all(val > x for val in a[i:hi])`` for the right side.
.. function:: insort_left(a, x, lo=0, hi=len(a))
Insert *x* in *a* in sorted order. This is equivalent to
``a.insert(bisect.bisect_left(a, x, lo, hi), x)`` assuming that *a* is
already sorted. Keep in mind that the O(log n) search is dominated by
the slow O(n) insertion step.
.. function:: insort_right(a, x, lo=0, hi=len(a))
insort(a, x, lo=0, hi=len(a))
Similar to :func:`insort_left`, but inserting *x* in *a* after any existing
entries of *x*.
.. seealso::
`SortedCollection recipe
<https://code.activestate.com/recipes/577197-sortedcollection/>`_ that uses
bisect to build a full-featured collection class with straight-forward search
methods and support for a key-function. The keys are precomputed to save
unnecessary calls to the key function during searches.
Searching Sorted Lists
----------------------
The above :func:`bisect` functions are useful for finding insertion points but
can be tricky or awkward to use for common searching tasks. The following five
functions show how to transform them into the standard lookups for sorted
lists::
def index(a, x):
'Locate the leftmost value exactly equal to x'
i = bisect_left(a, x)
if i != len(a) and a[i] == x:
return i
raise ValueError
def find_lt(a, x):
'Find rightmost value less than x'
i = bisect_left(a, x)
if i:
return a[i-1]
raise ValueError
def find_le(a, x):
'Find rightmost value less than or equal to x'
i = bisect_right(a, x)
if i:
return a[i-1]
raise ValueError
def find_gt(a, x):
'Find leftmost value greater than x'
i = bisect_right(a, x)
if i != len(a):
return a[i]
raise ValueError
def find_ge(a, x):
'Find leftmost item greater than or equal to x'
i = bisect_left(a, x)
if i != len(a):
return a[i]
raise ValueError
Other Examples
--------------
.. _bisect-example:
The :func:`bisect` function can be useful for numeric table lookups. This
example uses :func:`bisect` to look up a letter grade for an exam score (say)
based on a set of ordered numeric breakpoints: 90 and up is an 'A', 80 to 89 is
a 'B', and so on::
>>> def grade(score, breakpoints=[60, 70, 80, 90], grades='FDCBA'):
i = bisect(breakpoints, score)
return grades[i]
>>> [grade(score) for score in [33, 99, 77, 70, 89, 90, 100]]
['F', 'A', 'C', 'C', 'B', 'A', 'A']
Unlike the :func:`sorted` function, it does not make sense for the :func:`bisect`
functions to have *key* or *reversed* arguments because that would lead to an
inefficient design (successive calls to bisect functions would not "remember"
all of the previous key lookups).
Instead, it is better to search a list of precomputed keys to find the index
of the record in question::
>>> data = [('red', 5), ('blue', 1), ('yellow', 8), ('black', 0)]
>>> data.sort(key=lambda r: r[1])
>>> keys = [r[1] for r in data] # precomputed list of keys
>>> data[bisect_left(keys, 0)]
('black', 0)
>>> data[bisect_left(keys, 1)]
('blue', 1)
>>> data[bisect_left(keys, 5)]
('red', 5)
>>> data[bisect_left(keys, 8)]
('yellow', 8)
PK %�\Je�� � # html/_sources/library/bsddb.rst.txtnu �[���
:mod:`bsddb` --- Interface to Berkeley DB library
=================================================
.. module:: bsddb
:synopsis: Interface to Berkeley DB database library
.. sectionauthor:: Skip Montanaro <skip@pobox.com>
.. deprecated:: 2.6
The :mod:`bsddb` module has been removed in Python 3.
The :mod:`bsddb` module provides an interface to the Berkeley DB library. Users
can create hash, btree or record based library files using the appropriate open
call. Bsddb objects behave generally like dictionaries. Keys and values must be
strings, however, so to use other objects as keys or to store other kinds of
objects the user must serialize them somehow, typically using
:func:`marshal.dumps` or :func:`pickle.dumps`.
The :mod:`bsddb` module requires a Berkeley DB library version from 4.0 thru
4.7.
.. seealso::
http://www.jcea.es/programacion/pybsddb.htm
The website with documentation for the :mod:`bsddb.db` Python Berkeley DB
interface that closely mirrors the object oriented interface provided in
Berkeley DB 4.x itself.
http://www.oracle.com/database/berkeley-db/
The Berkeley DB library.
A more modern DB, DBEnv and DBSequence object interface is available in the
:mod:`bsddb.db` module which closely matches the Berkeley DB C API documented at
the above URLs. Additional features provided by the :mod:`bsddb.db` API include
fine tuning, transactions, logging, and multiprocess concurrent database access.
The following is a description of the legacy :mod:`bsddb` interface compatible
with the old Python bsddb module. Starting in Python 2.5 this interface should
be safe for multithreaded access. The :mod:`bsddb.db` API is recommended for
threading users as it provides better control.
The :mod:`bsddb` module defines the following functions that create objects that
access the appropriate type of Berkeley DB file. The first two arguments of
each function are the same. For ease of portability, only the first two
arguments should be used in most instances.
.. function:: hashopen(filename[, flag[, mode[, pgsize[, ffactor[, nelem[, cachesize[, lorder[, hflags]]]]]]]])
Open the hash format file named *filename*. Files never intended to be
preserved on disk may be created by passing ``None`` as the *filename*. The
optional *flag* identifies the mode used to open the file. It may be ``'r'``
(read only), ``'w'`` (read-write), ``'c'`` (read-write - create if necessary;
the default) or ``'n'`` (read-write - truncate to zero length). The other
arguments are rarely used and are just passed to the low-level :c:func:`dbopen`
function. Consult the Berkeley DB documentation for their use and
interpretation.
.. function:: btopen(filename[, flag[, mode[, btflags[, cachesize[, maxkeypage[, minkeypage[, pgsize[, lorder]]]]]]]])
Open the btree format file named *filename*. Files never intended to be
preserved on disk may be created by passing ``None`` as the *filename*. The
optional *flag* identifies the mode used to open the file. It may be ``'r'``
(read only), ``'w'`` (read-write), ``'c'`` (read-write - create if necessary;
the default) or ``'n'`` (read-write - truncate to zero length). The other
arguments are rarely used and are just passed to the low-level dbopen function.
Consult the Berkeley DB documentation for their use and interpretation.
.. function:: rnopen(filename[, flag[, mode[, rnflags[, cachesize[, pgsize[, lorder[, rlen[, delim[, source[, pad]]]]]]]]]])
Open a DB record format file named *filename*. Files never intended to be
preserved on disk may be created by passing ``None`` as the *filename*. The
optional *flag* identifies the mode used to open the file. It may be ``'r'``
(read only), ``'w'`` (read-write), ``'c'`` (read-write - create if necessary;
the default) or ``'n'`` (read-write - truncate to zero length). The other
arguments are rarely used and are just passed to the low-level dbopen function.
Consult the Berkeley DB documentation for their use and interpretation.
.. note::
Beginning in 2.3 some Unix versions of Python may have a :mod:`bsddb185` module.
This is present *only* to allow backwards compatibility with systems which ship
with the old Berkeley DB 1.85 database library. The :mod:`bsddb185` module
should never be used directly in new code. The module has been removed in
Python 3. If you find you still need it look in PyPI.
.. seealso::
Module :mod:`dbhash`
DBM-style interface to the :mod:`bsddb`
.. _bsddb-objects:
Hash, BTree and Record Objects
------------------------------
Once instantiated, hash, btree and record objects support the same methods as
dictionaries. In addition, they support the methods listed below.
.. versionchanged:: 2.3.1
Added dictionary methods.
.. method:: bsddbobject.close()
Close the underlying file. The object can no longer be accessed. Since there
is no open :meth:`open` method for these objects, to open the file again a new
:mod:`bsddb` module open function must be called.
.. method:: bsddbobject.keys()
Return the list of keys contained in the DB file. The order of the list is
unspecified and should not be relied on. In particular, the order of the list
returned is different for different file formats.
.. method:: bsddbobject.has_key(key)
Return ``1`` if the DB file contains the argument as a key.
.. method:: bsddbobject.set_location(key)
Set the cursor to the item indicated by *key* and return a tuple containing the
key and its value. For binary tree databases (opened using :func:`btopen`), if
*key* does not actually exist in the database, the cursor will point to the next
item in sorted order and return that key and value. For other databases,
:exc:`KeyError` will be raised if *key* is not found in the database.
.. method:: bsddbobject.first()
Set the cursor to the first item in the DB file and return it. The order of
keys in the file is unspecified, except in the case of B-Tree databases. This
method raises :exc:`bsddb.error` if the database is empty.
.. method:: bsddbobject.next()
Set the cursor to the next item in the DB file and return it. The order of
keys in the file is unspecified, except in the case of B-Tree databases.
.. method:: bsddbobject.previous()
Set the cursor to the previous item in the DB file and return it. The order of
keys in the file is unspecified, except in the case of B-Tree databases. This
is not supported on hashtable databases (those opened with :func:`hashopen`).
.. method:: bsddbobject.last()
Set the cursor to the last item in the DB file and return it. The order of keys
in the file is unspecified. This is not supported on hashtable databases (those
opened with :func:`hashopen`). This method raises :exc:`bsddb.error` if the
database is empty.
.. method:: bsddbobject.sync()
Synchronize the database on disk.
Example::
>>> import bsddb
>>> db = bsddb.btopen('spam.db', 'c')
>>> for i in range(10): db['%d'%i] = '%d'% (i*i)
...
>>> db['3']
'9'
>>> db.keys()
['0', '1', '2', '3', '4', '5', '6', '7', '8', '9']
>>> db.first()
('0', '0')
>>> db.next()
('1', '1')
>>> db.last()
('9', '81')
>>> db.set_location('2')
('2', '4')
>>> db.previous()
('1', '1')
>>> for k, v in db.iteritems():
... print k, v
0 0
1 1
2 4
3 9
4 16
5 25
6 36
7 49
8 64
9 81
>>> '8' in db
True
>>> db.sync()
0
PK %�\�v��� � ! html/_sources/library/bz2.rst.txtnu �[���
:mod:`bz2` --- Compression compatible with :program:`bzip2`
===========================================================
.. module:: bz2
:synopsis: Interface to compression and decompression routines compatible with bzip2.
.. moduleauthor:: Gustavo Niemeyer <niemeyer@conectiva.com>
.. sectionauthor:: Gustavo Niemeyer <niemeyer@conectiva.com>
.. versionadded:: 2.3
This module provides a comprehensive interface for the bz2 compression library.
It implements a complete file interface, one-shot (de)compression functions, and
types for sequential (de)compression.
Here is a summary of the features offered by the bz2 module:
* :class:`BZ2File` class implements a complete file interface, including
:meth:`~BZ2File.readline`, :meth:`~BZ2File.readlines`,
:meth:`~BZ2File.writelines`, :meth:`~BZ2File.seek`, etc;
* :class:`BZ2File` class implements emulated :meth:`~BZ2File.seek` support;
* :class:`BZ2File` class implements universal newline support;
* :class:`BZ2File` class offers an optimized line iteration using the readahead
algorithm borrowed from file objects;
* Sequential (de)compression supported by :class:`BZ2Compressor` and
:class:`BZ2Decompressor` classes;
* One-shot (de)compression supported by :func:`compress` and :func:`decompress`
functions;
* Thread safety uses individual locking mechanism.
.. note::
Handling of multi-stream bzip2 files is not supported. Modules such as
`bz2file <https://github.com/nvawda/bz2file>`_ let you overcome this.
(De)compression of files
------------------------
Handling of compressed files is offered by the :class:`BZ2File` class.
.. index::
single: universal newlines; bz2.BZ2File class
.. class:: BZ2File(filename[, mode[, buffering[, compresslevel]]])
Open a bz2 file. Mode can be either ``'r'`` or ``'w'``, for reading (default)
or writing. When opened for writing, the file will be created if it doesn't
exist, and truncated otherwise. If *buffering* is given, ``0`` means
unbuffered, and larger numbers specify the buffer size; the default is
``0``. If *compresslevel* is given, it must be a number between ``1`` and
``9``; the default is ``9``. Add a ``'U'`` to mode to open the file for input
in :term:`universal newlines` mode. Any line ending in the input file will be
seen as a ``'\n'`` in Python. Also, a file so opened gains the attribute
:attr:`newlines`; the value for this attribute is one of ``None`` (no newline
read yet), ``'\r'``, ``'\n'``, ``'\r\n'`` or a tuple containing all the
newline types seen. Universal newlines are available only when
reading. Instances support iteration in the same way as normal :class:`file`
instances.
:class:`BZ2File` supports the :keyword:`with` statement.
.. versionchanged:: 2.7
Support for the :keyword:`with` statement was added.
.. note::
This class does not support input files containing multiple streams (such
as those produced by the :program:`pbzip2` tool). When reading such an
input file, only the first stream will be accessible. If you require
support for multi-stream files, consider using the third-party
:mod:`bz2file` module (available from
`PyPI <https://pypi.org/project/bz2file>`_). This module provides a
backport of Python 3.3's :class:`BZ2File` class, which does support
multi-stream files.
.. method:: close()
Close the file. Sets data attribute :attr:`closed` to true. A closed file
cannot be used for further I/O operations. :meth:`close` may be called
more than once without error.
.. method:: read([size])
Read at most *size* uncompressed bytes, returned as a string. If the
*size* argument is negative or omitted, read until EOF is reached.
.. method:: readline([size])
Return the next line from the file, as a string, retaining newline. A
non-negative *size* argument limits the maximum number of bytes to return
(an incomplete line may be returned then). Return an empty string at EOF.
.. method:: readlines([size])
Return a list of lines read. The optional *size* argument, if given, is an
approximate bound on the total number of bytes in the lines returned.
.. method:: xreadlines()
For backward compatibility. :class:`BZ2File` objects now include the
performance optimizations previously implemented in the :mod:`xreadlines`
module.
.. deprecated:: 2.3
This exists only for compatibility with the method by this name on
:class:`file` objects, which is deprecated. Use ``for line in file``
instead.
.. method:: seek(offset[, whence])
Move to new file position. Argument *offset* is a byte count. Optional
argument *whence* defaults to ``os.SEEK_SET`` or ``0`` (offset from start
of file; offset should be ``>= 0``); other values are ``os.SEEK_CUR`` or
``1`` (move relative to current position; offset can be positive or
negative), and ``os.SEEK_END`` or ``2`` (move relative to end of file;
offset is usually negative, although many platforms allow seeking beyond
the end of a file).
Note that seeking of bz2 files is emulated, and depending on the
parameters the operation may be extremely slow.
.. method:: tell()
Return the current file position, an integer (may be a long integer).
.. method:: write(data)
Write string *data* to file. Note that due to buffering, :meth:`close` may
be needed before the file on disk reflects the data written.
.. method:: writelines(sequence_of_strings)
Write the sequence of strings to the file. Note that newlines are not
added. The sequence can be any iterable object producing strings. This is
equivalent to calling write() for each string.
Sequential (de)compression
--------------------------
Sequential compression and decompression is done using the classes
:class:`BZ2Compressor` and :class:`BZ2Decompressor`.
.. class:: BZ2Compressor([compresslevel])
Create a new compressor object. This object may be used to compress data
sequentially. If you want to compress data in one shot, use the
:func:`compress` function instead. The *compresslevel* parameter, if given,
must be a number between ``1`` and ``9``; the default is ``9``.
.. method:: compress(data)
Provide more data to the compressor object. It will return chunks of
compressed data whenever possible. When you've finished providing data to
compress, call the :meth:`flush` method to finish the compression process,
and return what is left in internal buffers.
.. method:: flush()
Finish the compression process and return what is left in internal
buffers. You must not use the compressor object after calling this method.
.. class:: BZ2Decompressor()
Create a new decompressor object. This object may be used to decompress data
sequentially. If you want to decompress data in one shot, use the
:func:`decompress` function instead.
.. method:: decompress(data)
Provide more data to the decompressor object. It will return chunks of
decompressed data whenever possible. If you try to decompress data after
the end of stream is found, :exc:`EOFError` will be raised. If any data
was found after the end of stream, it'll be ignored and saved in
:attr:`unused_data` attribute.
One-shot (de)compression
------------------------
One-shot compression and decompression is provided through the :func:`compress`
and :func:`decompress` functions.
.. function:: compress(data[, compresslevel])
Compress *data* in one shot. If you want to compress data sequentially, use
an instance of :class:`BZ2Compressor` instead. The *compresslevel* parameter,
if given, must be a number between ``1`` and ``9``; the default is ``9``.
.. function:: decompress(data)
Decompress *data* in one shot. If you want to decompress data sequentially,
use an instance of :class:`BZ2Decompressor` instead.
PK %�\_z��, , & html/_sources/library/calendar.rst.txtnu �[��� :mod:`calendar` --- General calendar-related functions
======================================================
.. module:: calendar
:synopsis: Functions for working with calendars, including some emulation of the Unix cal
program.
.. sectionauthor:: Drew Csillag <drew_csillag@geocities.com>
**Source code:** :source:`Lib/calendar.py`
--------------
This module allows you to output calendars like the Unix :program:`cal` program,
and provides additional useful functions related to the calendar. By default,
these calendars have Monday as the first day of the week, and Sunday as the last
(the European convention). Use :func:`setfirstweekday` to set the first day of
the week to Sunday (6) or to any other weekday. Parameters that specify dates
are given as integers. For related
functionality, see also the :mod:`datetime` and :mod:`time` modules.
Most of these functions and classes rely on the :mod:`datetime` module which
uses an idealized calendar, the current Gregorian calendar indefinitely extended
in both directions. This matches the definition of the "proleptic Gregorian"
calendar in Dershowitz and Reingold's book "Calendrical Calculations", where
it's the base calendar for all computations.
.. class:: Calendar([firstweekday])
Creates a :class:`Calendar` object. *firstweekday* is an integer specifying the
first day of the week. ``0`` is Monday (the default), ``6`` is Sunday.
A :class:`Calendar` object provides several methods that can be used for
preparing the calendar data for formatting. This class doesn't do any formatting
itself. This is the job of subclasses.
.. versionadded:: 2.5
:class:`Calendar` instances have the following methods:
.. method:: iterweekdays()
Return an iterator for the week day numbers that will be used for one
week. The first value from the iterator will be the same as the value of
the :attr:`firstweekday` property.
.. method:: itermonthdates(year, month)
Return an iterator for the month *month* (1--12) in the year *year*. This
iterator will return all days (as :class:`datetime.date` objects) for the
month and all days before the start of the month or after the end of the
month that are required to get a complete week.
.. method:: itermonthdays2(year, month)
Return an iterator for the month *month* in the year *year* similar to
:meth:`itermonthdates`. Days returned will be tuples consisting of a day
number and a week day number.
.. method:: itermonthdays(year, month)
Return an iterator for the month *month* in the year *year* similar to
:meth:`itermonthdates`. Days returned will simply be day numbers.
.. method:: monthdatescalendar(year, month)
Return a list of the weeks in the month *month* of the *year* as full
weeks. Weeks are lists of seven :class:`datetime.date` objects.
.. method:: monthdays2calendar(year, month)
Return a list of the weeks in the month *month* of the *year* as full
weeks. Weeks are lists of seven tuples of day numbers and weekday
numbers.
.. method:: monthdayscalendar(year, month)
Return a list of the weeks in the month *month* of the *year* as full
weeks. Weeks are lists of seven day numbers.
.. method:: yeardatescalendar(year[, width])
Return the data for the specified year ready for formatting. The return
value is a list of month rows. Each month row contains up to *width*
months (defaulting to 3). Each month contains between 4 and 6 weeks and
each week contains 1--7 days. Days are :class:`datetime.date` objects.
.. method:: yeardays2calendar(year[, width])
Return the data for the specified year ready for formatting (similar to
:meth:`yeardatescalendar`). Entries in the week lists are tuples of day
numbers and weekday numbers. Day numbers outside this month are zero.
.. method:: yeardayscalendar(year[, width])
Return the data for the specified year ready for formatting (similar to
:meth:`yeardatescalendar`). Entries in the week lists are day numbers. Day
numbers outside this month are zero.
.. class:: TextCalendar([firstweekday])
This class can be used to generate plain text calendars.
.. versionadded:: 2.5
:class:`TextCalendar` instances have the following methods:
.. method:: formatmonth(theyear, themonth[, w[, l]])
Return a month's calendar in a multi-line string. If *w* is provided, it
specifies the width of the date columns, which are centered. If *l* is
given, it specifies the number of lines that each week will use. Depends
on the first weekday as specified in the constructor or set by the
:meth:`setfirstweekday` method.
.. method:: prmonth(theyear, themonth[, w[, l]])
Print a month's calendar as returned by :meth:`formatmonth`.
.. method:: formatyear(theyear[, w[, l[, c[, m]]]])
Return a *m*-column calendar for an entire year as a multi-line string.
Optional parameters *w*, *l*, and *c* are for date column width, lines per
week, and number of spaces between month columns, respectively. Depends on
the first weekday as specified in the constructor or set by the
:meth:`setfirstweekday` method. The earliest year for which a calendar
can be generated is platform-dependent.
.. method:: pryear(theyear[, w[, l[, c[, m]]]])
Print the calendar for an entire year as returned by :meth:`formatyear`.
.. class:: HTMLCalendar([firstweekday])
This class can be used to generate HTML calendars.
.. versionadded:: 2.5
:class:`HTMLCalendar` instances have the following methods:
.. method:: formatmonth(theyear, themonth[, withyear])
Return a month's calendar as an HTML table. If *withyear* is true the year
will be included in the header, otherwise just the month name will be
used.
.. method:: formatyear(theyear[, width])
Return a year's calendar as an HTML table. *width* (defaulting to 3)
specifies the number of months per row.
.. method:: formatyearpage(theyear[, width[, css[, encoding]]])
Return a year's calendar as a complete HTML page. *width* (defaulting to
3) specifies the number of months per row. *css* is the name for the
cascading style sheet to be used. :const:`None` can be passed if no style
sheet should be used. *encoding* specifies the encoding to be used for the
output (defaulting to the system default encoding).
.. class:: LocaleTextCalendar([firstweekday[, locale]])
This subclass of :class:`TextCalendar` can be passed a locale name in the
constructor and will return month and weekday names in the specified locale.
If this locale includes an encoding all strings containing month and weekday
names will be returned as unicode.
.. versionadded:: 2.5
.. class:: LocaleHTMLCalendar([firstweekday[, locale]])
This subclass of :class:`HTMLCalendar` can be passed a locale name in the
constructor and will return month and weekday names in the specified
locale. If this locale includes an encoding all strings containing month and
weekday names will be returned as unicode.
.. versionadded:: 2.5
.. note::
The :meth:`formatweekday` and :meth:`formatmonthname` methods of these two
classes temporarily change the current locale to the given *locale*. Because
the current locale is a process-wide setting, they are not thread-safe.
For simple text calendars this module provides the following functions.
.. function:: setfirstweekday(weekday)
Sets the weekday (``0`` is Monday, ``6`` is Sunday) to start each week. The
values :const:`MONDAY`, :const:`TUESDAY`, :const:`WEDNESDAY`, :const:`THURSDAY`,
:const:`FRIDAY`, :const:`SATURDAY`, and :const:`SUNDAY` are provided for
convenience. For example, to set the first weekday to Sunday::
import calendar
calendar.setfirstweekday(calendar.SUNDAY)
.. versionadded:: 2.0
.. function:: firstweekday()
Returns the current setting for the weekday to start each week.
.. versionadded:: 2.0
.. function:: isleap(year)
Returns :const:`True` if *year* is a leap year, otherwise :const:`False`.
.. function:: leapdays(y1, y2)
Returns the number of leap years in the range from *y1* to *y2* (exclusive),
where *y1* and *y2* are years.
.. versionchanged:: 2.0
This function didn't work for ranges spanning a century change in Python
1.5.2.
.. function:: weekday(year, month, day)
Returns the day of the week (``0`` is Monday) for *year* (``1970``--...),
*month* (``1``--``12``), *day* (``1``--``31``).
.. function:: weekheader(n)
Return a header containing abbreviated weekday names. *n* specifies the width in
characters for one weekday.
.. function:: monthrange(year, month)
Returns weekday of first day of the month and number of days in month, for the
specified *year* and *month*.
.. function:: monthcalendar(year, month)
Returns a matrix representing a month's calendar. Each row represents a week;
days outside of the month a represented by zeros. Each week begins with Monday
unless set by :func:`setfirstweekday`.
.. function:: prmonth(theyear, themonth[, w[, l]])
Prints a month's calendar as returned by :func:`month`.
.. function:: month(theyear, themonth[, w[, l]])
Returns a month's calendar in a multi-line string using the :meth:`formatmonth`
of the :class:`TextCalendar` class.
.. versionadded:: 2.0
.. function:: prcal(year[, w[, l[c]]])
Prints the calendar for an entire year as returned by :func:`calendar`.
.. function:: calendar(year[, w[, l[c]]])
Returns a 3-column calendar for an entire year as a multi-line string using the
:meth:`formatyear` of the :class:`TextCalendar` class.
.. versionadded:: 2.0
.. function:: timegm(tuple)
An unrelated but handy function that takes a time tuple such as returned by
the :func:`~time.gmtime` function in the :mod:`time` module, and returns the
corresponding Unix timestamp value, assuming an epoch of 1970, and the POSIX
encoding. In fact, :func:`time.gmtime` and :func:`timegm` are each others'
inverse.
.. versionadded:: 2.0
The :mod:`calendar` module exports the following data attributes:
.. data:: day_name
An array that represents the days of the week in the current locale.
.. data:: day_abbr
An array that represents the abbreviated days of the week in the current locale.
.. data:: month_name
An array that represents the months of the year in the current locale. This
follows normal convention of January being month number 1, so it has a length of
13 and ``month_name[0]`` is the empty string.
.. data:: month_abbr
An array that represents the abbreviated months of the year in the current
locale. This follows normal convention of January being month number 1, so it
has a length of 13 and ``month_abbr[0]`` is the empty string.
.. seealso::
Module :mod:`datetime`
Object-oriented interface to dates and times with similar functionality to the
:mod:`time` module.
Module :mod:`time`
Low-level time related functions.
PK %�\�n�T> T> $ html/_sources/library/carbon.rst.txtnu �[���
.. _toolbox:
**********************
Mac OS Toolbox Modules
**********************
These are a set of modules that provide interfaces to various legacy Mac OS toolboxes.
If applicable the module will define a number of Python objects for the various
structures declared by the toolbox, and operations will be implemented as
methods of the object. Other operations will be implemented as functions in the
module. Not all operations possible in C will also be possible in Python
(callbacks are often a problem), and parameters will occasionally be different
in Python (input and output buffers, especially). All methods and functions
have a :attr:`__doc__` string describing their arguments and return values, and
for additional description you are referred to `Inside Macintosh
<http://developer.apple.com/legacy/mac/library/#documentation/macos8/mac8.html>`_ or similar works.
These modules all live in a package called :mod:`Carbon`. Despite that name they
are not all part of the Carbon framework: CF is really in the CoreFoundation
framework and Qt is in the QuickTime framework. The normal use pattern is ::
from Carbon import AE
.. note::
Most of the OS X APIs that these modules use are deprecated or removed
in recent versions of OS X. Many are not available when Python is
executing in 64-bit mode. The Carbon modules have been removed in
Python 3. You should avoid using them in Python 2.
:mod:`Carbon.AE` --- Apple Events
=================================
.. module:: Carbon.AE
:platform: Mac
:synopsis: Interface to the Apple Events toolbox.
:deprecated:
:mod:`Carbon.AH` --- Apple Help
===============================
.. module:: Carbon.AH
:platform: Mac
:synopsis: Interface to the Apple Help manager.
:deprecated:
:mod:`Carbon.App` --- Appearance Manager
========================================
.. module:: Carbon.App
:platform: Mac
:synopsis: Interface to the Appearance Manager.
:deprecated:
:mod:`Carbon.Appearance` --- Appearance Manager constants
=========================================================
.. module:: Carbon.Appearance
:platform: Mac
:synopsis: Constant definitions for the interface to the Appearance Manager.
:deprecated:
:mod:`Carbon.CF` --- Core Foundation
====================================
.. module:: Carbon.CF
:platform: Mac
:synopsis: Interface to the Core Foundation.
:deprecated:
The ``CFBase``, ``CFArray``, ``CFData``, ``CFDictionary``, ``CFString`` and
``CFURL`` objects are supported, some only partially.
:mod:`Carbon.CG` --- Core Graphics
==================================
.. module:: Carbon.CG
:platform: Mac
:synopsis: Interface to Core Graphics.
:deprecated:
:mod:`Carbon.CarbonEvt` --- Carbon Event Manager
================================================
.. module:: Carbon.CarbonEvt
:platform: Mac
:synopsis: Interface to the Carbon Event Manager.
:deprecated:
:mod:`Carbon.CarbonEvents` --- Carbon Event Manager constants
=============================================================
.. module:: Carbon.CarbonEvents
:platform: Mac
:synopsis: Constants for the interface to the Carbon Event Manager.
:deprecated:
:mod:`Carbon.Cm` --- Component Manager
======================================
.. module:: Carbon.Cm
:platform: Mac
:synopsis: Interface to the Component Manager.
:deprecated:
:mod:`Carbon.Components` --- Component Manager constants
========================================================
.. module:: Carbon.Components
:platform: Mac
:synopsis: Constants for the interface to the Component Manager.
:deprecated:
:mod:`Carbon.ControlAccessor` --- Control Manager accssors
===========================================================
.. module:: Carbon.ControlAccessor
:platform: Mac
:synopsis: Accessor functions for the interface to the Control Manager.
:deprecated:
:mod:`Carbon.Controls` --- Control Manager constants
====================================================
.. module:: Carbon.Controls
:platform: Mac
:synopsis: Constants for the interface to the Control Manager.
:deprecated:
:mod:`Carbon.CoreFounation` --- CoreFounation constants
=======================================================
.. module:: Carbon.CoreFounation
:platform: Mac
:synopsis: Constants for the interface to CoreFoundation.
:deprecated:
:mod:`Carbon.CoreGraphics` --- CoreGraphics constants
=======================================================
.. module:: Carbon.CoreGraphics
:platform: Mac
:synopsis: Constants for the interface to CoreGraphics.
:deprecated:
:mod:`Carbon.Ctl` --- Control Manager
=====================================
.. module:: Carbon.Ctl
:platform: Mac
:synopsis: Interface to the Control Manager.
:deprecated:
:mod:`Carbon.Dialogs` --- Dialog Manager constants
==================================================
.. module:: Carbon.Dialogs
:platform: Mac
:synopsis: Constants for the interface to the Dialog Manager.
:deprecated:
:mod:`Carbon.Dlg` --- Dialog Manager
====================================
.. module:: Carbon.Dlg
:platform: Mac
:synopsis: Interface to the Dialog Manager.
:deprecated:
:mod:`Carbon.Drag` --- Drag and Drop Manager
=============================================
.. module:: Carbon.Drag
:platform: Mac
:synopsis: Interface to the Drag and Drop Manager.
:deprecated:
:mod:`Carbon.Dragconst` --- Drag and Drop Manager constants
===========================================================
.. module:: Carbon.Dragconst
:platform: Mac
:synopsis: Constants for the interface to the Drag and Drop Manager.
:deprecated:
:mod:`Carbon.Events` --- Event Manager constants
================================================
.. module:: Carbon.Events
:platform: Mac
:synopsis: Constants for the interface to the classic Event Manager.
:deprecated:
:mod:`Carbon.Evt` --- Event Manager
===================================
.. module:: Carbon.Evt
:platform: Mac
:synopsis: Interface to the classic Event Manager.
:deprecated:
:mod:`Carbon.File` --- File Manager
===================================
.. module:: Carbon.File
:platform: Mac
:synopsis: Interface to the File Manager.
:deprecated:
:mod:`Carbon.Files` --- File Manager constants
==============================================
.. module:: Carbon.Files
:platform: Mac
:synopsis: Constants for the interface to the File Manager.
:deprecated:
:mod:`Carbon.Fm` --- Font Manager
=================================
.. module:: Carbon.Fm
:platform: Mac
:synopsis: Interface to the Font Manager.
:deprecated:
:mod:`Carbon.Folder` --- Folder Manager
=======================================
.. module:: Carbon.Folder
:platform: Mac
:synopsis: Interface to the Folder Manager.
:deprecated:
:mod:`Carbon.Folders` --- Folder Manager constants
==================================================
.. module:: Carbon.Folders
:platform: Mac
:synopsis: Constants for the interface to the Folder Manager.
:deprecated:
:mod:`Carbon.Fonts` --- Font Manager constants
==================================================
.. module:: Carbon.Fonts
:platform: Mac
:synopsis: Constants for the interface to the Font Manager.
:deprecated:
:mod:`Carbon.Help` --- Help Manager
===================================
.. module:: Carbon.Help
:platform: Mac
:synopsis: Interface to the Carbon Help Manager.
:deprecated:
:mod:`Carbon.IBCarbon` --- Carbon InterfaceBuilder
==================================================
.. module:: Carbon.IBCarbon
:platform: Mac
:synopsis: Interface to the Carbon InterfaceBuilder support libraries.
:deprecated:
:mod:`Carbon.IBCarbonRuntime` --- Carbon InterfaceBuilder constants
===================================================================
.. module:: Carbon.IBCarbonRuntime
:platform: Mac
:synopsis: Constants for the interface to the Carbon InterfaceBuilder support libraries.
:deprecated:
:mod:`Carbon.Icn` --- Carbon Icon Manager
=========================================
.. module:: Carbon.Icns
:platform: Mac
:synopsis: Interface to the Carbon Icon Manager
:deprecated:
:mod:`Carbon.Icons` --- Carbon Icon Manager constants
=====================================================
.. module:: Carbon.Icons
:platform: Mac
:synopsis: Constants for the interface to the Carbon Icon Manager
:deprecated:
:mod:`Carbon.Launch` --- Carbon Launch Services
===============================================
.. module:: Carbon.Launch
:platform: Mac
:synopsis: Interface to the Carbon Launch Services.
:deprecated:
:mod:`Carbon.LaunchServices` --- Carbon Launch Services constants
=================================================================
.. module:: Carbon.LaunchServices
:platform: Mac
:synopsis: Constants for the interface to the Carbon Launch Services.
:deprecated:
:mod:`Carbon.List` --- List Manager
===================================
.. module:: Carbon.List
:platform: Mac
:synopsis: Interface to the List Manager.
:deprecated:
:mod:`Carbon.Lists` --- List Manager constants
==============================================
.. module:: Carbon.Lists
:platform: Mac
:synopsis: Constants for the interface to the List Manager.
:deprecated:
:mod:`Carbon.MacHelp` --- Help Manager constants
================================================
.. module:: Carbon.MacHelp
:platform: Mac
:synopsis: Constants for the interface to the Carbon Help Manager.
:deprecated:
:mod:`Carbon.MediaDescr` --- Parsers and generators for Quicktime Media descriptors
===================================================================================
.. module:: Carbon.MediaDescr
:platform: Mac
:synopsis: Parsers and generators for Quicktime Media descriptors
:deprecated:
:mod:`Carbon.Menu` --- Menu Manager
===================================
.. module:: Carbon.Menu
:platform: Mac
:synopsis: Interface to the Menu Manager.
:deprecated:
:mod:`Carbon.Menus` --- Menu Manager constants
==============================================
.. module:: Carbon.Menus
:platform: Mac
:synopsis: Constants for the interface to the Menu Manager.
:deprecated:
:mod:`Carbon.Mlte` --- MultiLingual Text Editor
===============================================
.. module:: Carbon.Mlte
:platform: Mac
:synopsis: Interface to the MultiLingual Text Editor.
:deprecated:
:mod:`Carbon.OSA` --- Carbon OSA Interface
==========================================
.. module:: Carbon.OSA
:platform: Mac
:synopsis: Interface to the Carbon OSA Library.
:deprecated:
:mod:`Carbon.OSAconst` --- Carbon OSA Interface constants
=========================================================
.. module:: Carbon.OSAconst
:platform: Mac
:synopsis: Constants for the interface to the Carbon OSA Library.
:deprecated:
:mod:`Carbon.QDOffscreen` --- QuickDraw Offscreen constants
===========================================================
.. module:: Carbon.QDOffscreen
:platform: Mac
:synopsis: Constants for the interface to the QuickDraw Offscreen APIs.
:deprecated:
:mod:`Carbon.Qd` --- QuickDraw
==============================
.. module:: Carbon.Qd
:platform: Mac
:synopsis: Interface to the QuickDraw toolbox.
:deprecated:
:mod:`Carbon.Qdoffs` --- QuickDraw Offscreen
============================================
.. module:: Carbon.Qdoffs
:platform: Mac
:synopsis: Interface to the QuickDraw Offscreen APIs.
:deprecated:
:mod:`Carbon.Qt` --- QuickTime
==============================
.. module:: Carbon.Qt
:platform: Mac
:synopsis: Interface to the QuickTime toolbox.
:deprecated:
:mod:`Carbon.QuickDraw` --- QuickDraw constants
===============================================
.. module:: Carbon.QuickDraw
:platform: Mac
:synopsis: Constants for the interface to the QuickDraw toolbox.
:deprecated:
:mod:`Carbon.QuickTime` --- QuickTime constants
===============================================
.. module:: Carbon.QuickTime
:platform: Mac
:synopsis: Constants for the interface to the QuickTime toolbox.
:deprecated:
:mod:`Carbon.Res` --- Resource Manager and Handles
==================================================
.. module:: Carbon.Res
:platform: Mac
:synopsis: Interface to the Resource Manager and Handles.
:deprecated:
:mod:`Carbon.Resources` --- Resource Manager and Handles constants
==================================================================
.. module:: Carbon.Resources
:platform: Mac
:synopsis: Constants for the interface to the Resource Manager and Handles.
:deprecated:
:mod:`Carbon.Scrap` --- Scrap Manager
=====================================
.. module:: Carbon.Scrap
:platform: Mac
:synopsis: The Scrap Manager provides basic services for implementing cut & paste and
clipboard operations.
:deprecated:
This module is only fully available on Mac OS 9 and earlier under classic PPC
MacPython. Very limited functionality is available under Carbon MacPython.
.. index:: single: Scrap Manager
The Scrap Manager supports the simplest form of cut & paste operations on the
Macintosh. It can be use for both inter- and intra-application clipboard
operations.
The :mod:`Scrap` module provides low-level access to the functions of the Scrap
Manager. It contains the following functions:
.. function:: InfoScrap()
Return current information about the scrap. The information is encoded as a
tuple containing the fields ``(size, handle, count, state, path)``.
+----------+---------------------------------------------+
| Field | Meaning |
+==========+=============================================+
| *size* | Size of the scrap in bytes. |
+----------+---------------------------------------------+
| *handle* | Resource object representing the scrap. |
+----------+---------------------------------------------+
| *count* | Serial number of the scrap contents. |
+----------+---------------------------------------------+
| *state* | Integer; positive if in memory, ``0`` if on |
| | disk, negative if uninitialized. |
+----------+---------------------------------------------+
| *path* | Filename of the scrap when stored on disk. |
+----------+---------------------------------------------+
.. seealso::
`Scrap Manager <http://developer.apple.com/legacy/mac/library/documentation/mac/MoreToolbox/MoreToolbox-109.html>`_
Apple's documentation for the Scrap Manager gives a lot of useful information
about using the Scrap Manager in applications.
:mod:`Carbon.Snd` --- Sound Manager
===================================
.. module:: Carbon.Snd
:platform: Mac
:synopsis: Interface to the Sound Manager.
:deprecated:
:mod:`Carbon.Sound` --- Sound Manager constants
===============================================
.. module:: Carbon.Sound
:platform: Mac
:synopsis: Constants for the interface to the Sound Manager.
:deprecated:
:mod:`Carbon.TE` --- TextEdit
=============================
.. module:: Carbon.TE
:platform: Mac
:synopsis: Interface to TextEdit.
:deprecated:
:mod:`Carbon.TextEdit` --- TextEdit constants
=============================================
.. module:: Carbon.TextEdit
:platform: Mac
:synopsis: Constants for the interface to TextEdit.
:deprecated:
:mod:`Carbon.Win` --- Window Manager
====================================
.. module:: Carbon.Win
:platform: Mac
:synopsis: Interface to the Window Manager.
:deprecated:
:mod:`Carbon.Windows` --- Window Manager constants
==================================================
.. module:: Carbon.Windows
:platform: Mac
:synopsis: Constants for the interface to the Window Manager.
:deprecated:
PK %�\?Ҿ��. �. html/_sources/library/cd.rst.txtnu �[���
:mod:`cd` --- CD-ROM access on SGI systems
==========================================
.. module:: cd
:platform: IRIX
:synopsis: Interface to the CD-ROM on Silicon Graphics systems.
:deprecated:
.. deprecated:: 2.6
The :mod:`cd` module has been removed in Python 3.
This module provides an interface to the Silicon Graphics CD library. It is
available only on Silicon Graphics systems.
The way the library works is as follows. A program opens the CD-ROM device with
:func:`.open` and creates a parser to parse the data from the CD with
:func:`createparser`. The object returned by :func:`.open` can be used to read
data from the CD, but also to get status information for the CD-ROM device, and
to get information about the CD, such as the table of contents. Data from the
CD is passed to the parser, which parses the frames, and calls any callback
functions that have previously been added.
An audio CD is divided into :dfn:`tracks` or :dfn:`programs` (the terms are used
interchangeably). Tracks can be subdivided into :dfn:`indices`. An audio CD
contains a :dfn:`table of contents` which gives the starts of the tracks on the
CD. Index 0 is usually the pause before the start of a track. The start of the
track as given by the table of contents is normally the start of index 1.
Positions on a CD can be represented in two ways. Either a frame number or a
tuple of three values, minutes, seconds and frames. Most functions use the
latter representation. Positions can be both relative to the beginning of the
CD, and to the beginning of the track.
Module :mod:`cd` defines the following functions and constants:
.. function:: createparser()
Create and return an opaque parser object. The methods of the parser object are
described below.
.. function:: msftoframe(minutes, seconds, frames)
Converts a ``(minutes, seconds, frames)`` triple representing time in absolute
time code into the corresponding CD frame number.
.. function:: open([device[, mode]])
Open the CD-ROM device. The return value is an opaque player object; methods of
the player object are described below. The device is the name of the SCSI
device file, e.g. ``'/dev/scsi/sc0d4l0'``, or ``None``. If omitted or ``None``,
the hardware inventory is consulted to locate a CD-ROM drive. The *mode*, if
not omitted, should be the string ``'r'``.
The module defines the following variables:
.. exception:: error
Exception raised on various errors.
.. data:: DATASIZE
The size of one frame's worth of audio data. This is the size of the audio data
as passed to the callback of type ``audio``.
.. data:: BLOCKSIZE
The size of one uninterpreted frame of audio data.
The following variables are states as returned by :func:`getstatus`:
.. data:: READY
The drive is ready for operation loaded with an audio CD.
.. data:: NODISC
The drive does not have a CD loaded.
.. data:: CDROM
The drive is loaded with a CD-ROM. Subsequent play or read operations will
return I/O errors.
.. data:: ERROR
An error occurred while trying to read the disc or its table of contents.
.. data:: PLAYING
The drive is in CD player mode playing an audio CD through its audio jacks.
.. data:: PAUSED
The drive is in CD layer mode with play paused.
.. data:: STILL
The equivalent of :const:`PAUSED` on older (non 3301) model Toshiba CD-ROM
drives. Such drives have never been shipped by SGI.
.. data:: audio
pnum
index
ptime
atime
catalog
ident
control
Integer constants describing the various types of parser callbacks that can be
set by the :meth:`addcallback` method of CD parser objects (see below).
.. _player-objects:
Player Objects
--------------
Player objects (returned by :func:`.open`) have the following methods:
.. method:: CD player.allowremoval()
Unlocks the eject button on the CD-ROM drive permitting the user to eject the
caddy if desired.
.. method:: CD player.bestreadsize()
Returns the best value to use for the *num_frames* parameter of the
:meth:`readda` method. Best is defined as the value that permits a continuous
flow of data from the CD-ROM drive.
.. method:: CD player.close()
Frees the resources associated with the player object. After calling
:meth:`close`, the methods of the object should no longer be used.
.. method:: CD player.eject()
Ejects the caddy from the CD-ROM drive.
.. method:: CD player.getstatus()
Returns information pertaining to the current state of the CD-ROM drive. The
returned information is a tuple with the following values: *state*, *track*,
*rtime*, *atime*, *ttime*, *first*, *last*, *scsi_audio*, *cur_block*. *rtime*
is the time relative to the start of the current track; *atime* is the time
relative to the beginning of the disc; *ttime* is the total time on the disc.
For more information on the meaning of the values, see the man page
:manpage:`CDgetstatus(3dm)`. The value of *state* is one of the following:
:const:`ERROR`, :const:`NODISC`, :const:`READY`, :const:`PLAYING`,
:const:`PAUSED`, :const:`STILL`, or :const:`CDROM`.
.. method:: CD player.gettrackinfo(track)
Returns information about the specified track. The returned information is a
tuple consisting of two elements, the start time of the track and the duration
of the track.
.. method:: CD player.msftoblock(min, sec, frame)
Converts a minutes, seconds, frames triple representing a time in absolute time
code into the corresponding logical block number for the given CD-ROM drive.
You should use :func:`msftoframe` rather than :meth:`msftoblock` for comparing
times. The logical block number differs from the frame number by an offset
required by certain CD-ROM drives.
.. method:: CD player.play(start, play)
Starts playback of an audio CD in the CD-ROM drive at the specified track. The
audio output appears on the CD-ROM drive's headphone and audio jacks (if
fitted). Play stops at the end of the disc. *start* is the number of the track
at which to start playing the CD; if *play* is 0, the CD will be set to an
initial paused state. The method :meth:`togglepause` can then be used to
commence play.
.. method:: CD player.playabs(minutes, seconds, frames, play)
Like :meth:`play`, except that the start is given in minutes, seconds, and
frames instead of a track number.
.. method:: CD player.playtrack(start, play)
Like :meth:`play`, except that playing stops at the end of the track.
.. method:: CD player.playtrackabs(track, minutes, seconds, frames, play)
Like :meth:`play`, except that playing begins at the specified absolute time and
ends at the end of the specified track.
.. method:: CD player.preventremoval()
Locks the eject button on the CD-ROM drive thus preventing the user from
arbitrarily ejecting the caddy.
.. method:: CD player.readda(num_frames)
Reads the specified number of frames from an audio CD mounted in the CD-ROM
drive. The return value is a string representing the audio frames. This string
can be passed unaltered to the :meth:`parseframe` method of the parser object.
.. method:: CD player.seek(minutes, seconds, frames)
Sets the pointer that indicates the starting point of the next read of digital
audio data from a CD-ROM. The pointer is set to an absolute time code location
specified in *minutes*, *seconds*, and *frames*. The return value is the
logical block number to which the pointer has been set.
.. method:: CD player.seekblock(block)
Sets the pointer that indicates the starting point of the next read of digital
audio data from a CD-ROM. The pointer is set to the specified logical block
number. The return value is the logical block number to which the pointer has
been set.
.. method:: CD player.seektrack(track)
Sets the pointer that indicates the starting point of the next read of digital
audio data from a CD-ROM. The pointer is set to the specified track. The
return value is the logical block number to which the pointer has been set.
.. method:: CD player.stop()
Stops the current playing operation.
.. method:: CD player.togglepause()
Pauses the CD if it is playing, and makes it play if it is paused.
.. _cd-parser-objects:
Parser Objects
--------------
Parser objects (returned by :func:`createparser`) have the following methods:
.. method:: CD parser.addcallback(type, func, arg)
Adds a callback for the parser. The parser has callbacks for eight different
types of data in the digital audio data stream. Constants for these types are
defined at the :mod:`cd` module level (see above). The callback is called as
follows: ``func(arg, type, data)``, where *arg* is the user supplied argument,
*type* is the particular type of callback, and *data* is the data returned for
this *type* of callback. The type of the data depends on the *type* of callback
as follows:
+-------------+---------------------------------------------+
| Type | Value |
+=============+=============================================+
| ``audio`` | String which can be passed unmodified to |
| | :func:`al.writesamps`. |
+-------------+---------------------------------------------+
| ``pnum`` | Integer giving the program (track) number. |
+-------------+---------------------------------------------+
| ``index`` | Integer giving the index number. |
+-------------+---------------------------------------------+
| ``ptime`` | Tuple consisting of the program time in |
| | minutes, seconds, and frames. |
+-------------+---------------------------------------------+
| ``atime`` | Tuple consisting of the absolute time in |
| | minutes, seconds, and frames. |
+-------------+---------------------------------------------+
| ``catalog`` | String of 13 characters, giving the catalog |
| | number of the CD. |
+-------------+---------------------------------------------+
| ``ident`` | String of 12 characters, giving the ISRC |
| | identification number of the recording. |
| | The string consists of two characters |
| | country code, three characters owner code, |
| | two characters giving the year, and five |
| | characters giving a serial number. |
+-------------+---------------------------------------------+
| ``control`` | Integer giving the control bits from the CD |
| | subcode data |
+-------------+---------------------------------------------+
.. method:: CD parser.deleteparser()
Deletes the parser and frees the memory it was using. The object should not be
used after this call. This call is done automatically when the last reference
to the object is removed.
.. method:: CD parser.parseframe(frame)
Parses one or more frames of digital audio data from a CD such as returned by
:meth:`readda`. It determines which subcodes are present in the data. If these
subcodes have changed since the last frame, then :meth:`parseframe` executes a
callback of the appropriate type passing to it the subcode data found in the
frame. Unlike the C function, more than one frame of digital audio data can be
passed to this method.
.. method:: CD parser.removecallback(type)
Removes the callback for the given *type*.
.. method:: CD parser.resetparser()
Resets the fields of the parser used for tracking subcodes to an initial state.
:meth:`resetparser` should be called after the disc has been changed.
PK %�\=��EY EY ! html/_sources/library/cgi.rst.txtnu �[��� :mod:`cgi` --- Common Gateway Interface support
===============================================
.. module:: cgi
:synopsis: Helpers for running Python scripts via the Common Gateway Interface.
.. index::
pair: WWW; server
pair: CGI; protocol
pair: HTTP; protocol
pair: MIME; headers
single: URL
single: Common Gateway Interface
**Source code:** :source:`Lib/cgi.py`
--------------
Support module for Common Gateway Interface (CGI) scripts.
This module defines a number of utilities for use by CGI scripts written in
Python.
Introduction
------------
.. _cgi-intro:
A CGI script is invoked by an HTTP server, usually to process user input
submitted through an HTML ``<FORM>`` or ``<ISINDEX>`` element.
Most often, CGI scripts live in the server's special :file:`cgi-bin` directory.
The HTTP server places all sorts of information about the request (such as the
client's hostname, the requested URL, the query string, and lots of other
goodies) in the script's shell environment, executes the script, and sends the
script's output back to the client.
The script's input is connected to the client too, and sometimes the form data
is read this way; at other times the form data is passed via the "query string"
part of the URL. This module is intended to take care of the different cases
and provide a simpler interface to the Python script. It also provides a number
of utilities that help in debugging scripts, and the latest addition is support
for file uploads from a form (if your browser supports it).
The output of a CGI script should consist of two sections, separated by a blank
line. The first section contains a number of headers, telling the client what
kind of data is following. Python code to generate a minimal header section
looks like this::
print "Content-Type: text/html" # HTML is following
print # blank line, end of headers
The second section is usually HTML, which allows the client software to display
nicely formatted text with header, in-line images, etc. Here's Python code that
prints a simple piece of HTML::
print "<TITLE>CGI script output</TITLE>"
print "<H1>This is my first CGI script</H1>"
print "Hello, world!"
.. _using-the-cgi-module:
Using the cgi module
--------------------
Begin by writing ``import cgi``. Do not use ``from cgi import *`` --- the
module defines all sorts of names for its own use or for backward compatibility
that you don't want in your namespace.
When you write a new script, consider adding these lines::
import cgitb
cgitb.enable()
This activates a special exception handler that will display detailed reports in
the Web browser if any errors occur. If you'd rather not show the guts of your
program to users of your script, you can have the reports saved to files
instead, with code like this::
import cgitb
cgitb.enable(display=0, logdir="/path/to/logdir")
It's very helpful to use this feature during script development. The reports
produced by :mod:`cgitb` provide information that can save you a lot of time in
tracking down bugs. You can always remove the ``cgitb`` line later when you
have tested your script and are confident that it works correctly.
To get at submitted form data, it's best to use the :class:`FieldStorage` class.
The other classes defined in this module are provided mostly for backward
compatibility. Instantiate it exactly once, without arguments. This reads the
form contents from standard input or the environment (depending on the value of
various environment variables set according to the CGI standard). Since it may
consume standard input, it should be instantiated only once.
The :class:`FieldStorage` instance can be indexed like a Python dictionary.
It allows membership testing with the :keyword:`in` operator, and also supports
the standard dictionary method :meth:`~dict.keys` and the built-in function
:func:`len`. Form fields containing empty strings are ignored and do not appear
in the dictionary; to keep such values, provide a true value for the optional
*keep_blank_values* keyword parameter when creating the :class:`FieldStorage`
instance.
For instance, the following code (which assumes that the
:mailheader:`Content-Type` header and blank line have already been printed)
checks that the fields ``name`` and ``addr`` are both set to a non-empty
string::
form = cgi.FieldStorage()
if "name" not in form or "addr" not in form:
print "<H1>Error</H1>"
print "Please fill in the name and addr fields."
return
print "<p>name:", form["name"].value
print "<p>addr:", form["addr"].value
...further form processing here...
Here the fields, accessed through ``form[key]``, are themselves instances of
:class:`FieldStorage` (or :class:`MiniFieldStorage`, depending on the form
encoding). The :attr:`~FieldStorage.value` attribute of the instance yields
the string value of the field. The :meth:`~FieldStorage.getvalue` method
returns this string value directly; it also accepts an optional second argument
as a default to return if the requested key is not present.
If the submitted form data contains more than one field with the same name, the
object retrieved by ``form[key]`` is not a :class:`FieldStorage` or
:class:`MiniFieldStorage` instance but a list of such instances. Similarly, in
this situation, ``form.getvalue(key)`` would return a list of strings. If you
expect this possibility (when your HTML form contains multiple fields with the
same name), use the :meth:`~FieldStorage.getlist` method, which always returns
a list of values (so that you do not need to special-case the single item
case). For example, this code concatenates any number of username fields,
separated by commas::
value = form.getlist("username")
usernames = ",".join(value)
If a field represents an uploaded file, accessing the value via the
:attr:`~FieldStorage.value` attribute or the :func:`~FieldStorage.getvalue`
method reads the entire file in memory as a string. This may not be what you
want. You can test for an uploaded file by testing either the
:attr:`~FieldStorage.filename` attribute or the :attr:`~FieldStorage.file`
attribute. You can then read the data at leisure from the :attr:`!file`
attribute::
fileitem = form["userfile"]
if fileitem.file:
# It's an uploaded file; count lines
linecount = 0
while 1:
line = fileitem.file.readline()
if not line: break
linecount = linecount + 1
If an error is encountered when obtaining the contents of an uploaded file
(for example, when the user interrupts the form submission by clicking on
a Back or Cancel button) the :attr:`~FieldStorage.done` attribute of the
object for the field will be set to the value -1.
The file upload draft standard entertains the possibility of uploading multiple
files from one field (using a recursive :mimetype:`multipart/\*` encoding).
When this occurs, the item will be a dictionary-like :class:`FieldStorage` item.
This can be determined by testing its :attr:`!type` attribute, which should be
:mimetype:`multipart/form-data` (or perhaps another MIME type matching
:mimetype:`multipart/\*`). In this case, it can be iterated over recursively
just like the top-level form object.
When a form is submitted in the "old" format (as the query string or as a single
data part of type :mimetype:`application/x-www-form-urlencoded`), the items will
actually be instances of the class :class:`MiniFieldStorage`. In this case, the
:attr:`!list`, :attr:`!file`, and :attr:`filename` attributes are always ``None``.
A form submitted via POST that also has a query string will contain both
:class:`FieldStorage` and :class:`MiniFieldStorage` items.
Higher Level Interface
----------------------
.. versionadded:: 2.2
The previous section explains how to read CGI form data using the
:class:`FieldStorage` class. This section describes a higher level interface
which was added to this class to allow one to do it in a more readable and
intuitive way. The interface doesn't make the techniques described in previous
sections obsolete --- they are still useful to process file uploads efficiently,
for example.
.. XXX: Is this true ?
The interface consists of two simple methods. Using the methods you can process
form data in a generic way, without the need to worry whether only one or more
values were posted under one name.
In the previous section, you learned to write following code anytime you
expected a user to post more than one value under one name::
item = form.getvalue("item")
if isinstance(item, list):
# The user is requesting more than one item.
else:
# The user is requesting only one item.
This situation is common for example when a form contains a group of multiple
checkboxes with the same name::
<input type="checkbox" name="item" value="1" />
<input type="checkbox" name="item" value="2" />
In most situations, however, there's only one form control with a particular
name in a form and then you expect and need only one value associated with this
name. So you write a script containing for example this code::
user = form.getvalue("user").upper()
The problem with the code is that you should never expect that a client will
provide valid input to your scripts. For example, if a curious user appends
another ``user=foo`` pair to the query string, then the script would crash,
because in this situation the ``getvalue("user")`` method call returns a list
instead of a string. Calling the :meth:`~str.upper` method on a list is not valid
(since lists do not have a method of this name) and results in an
:exc:`AttributeError` exception.
Therefore, the appropriate way to read form data values was to always use the
code which checks whether the obtained value is a single value or a list of
values. That's annoying and leads to less readable scripts.
A more convenient approach is to use the methods :meth:`~FieldStorage.getfirst`
and :meth:`~FieldStorage.getlist` provided by this higher level interface.
.. method:: FieldStorage.getfirst(name[, default])
This method always returns only one value associated with form field *name*.
The method returns only the first value in case that more values were posted
under such name. Please note that the order in which the values are received
may vary from browser to browser and should not be counted on. [#]_ If no such
form field or value exists then the method returns the value specified by the
optional parameter *default*. This parameter defaults to ``None`` if not
specified.
.. method:: FieldStorage.getlist(name)
This method always returns a list of values associated with form field *name*.
The method returns an empty list if no such form field or value exists for
*name*. It returns a list consisting of one item if only one such value exists.
Using these methods you can write nice compact code::
import cgi
form = cgi.FieldStorage()
user = form.getfirst("user", "").upper() # This way it's safe.
for item in form.getlist("item"):
do_something(item)
Old classes
-----------
.. deprecated:: 2.6
These classes, present in earlier versions of the :mod:`cgi` module, are
still supported for backward compatibility. New applications should use the
:class:`FieldStorage` class.
:class:`SvFormContentDict` stores single value form content as dictionary; it
assumes each field name occurs in the form only once.
:class:`FormContentDict` stores multiple value form content as a dictionary (the
form items are lists of values). Useful if your form contains multiple fields
with the same name.
Other classes (:class:`FormContent`, :class:`InterpFormContentDict`) are present
for backwards compatibility with really old applications only.
.. _functions-in-cgi-module:
Functions
---------
These are useful if you want more control, or if you want to employ some of the
algorithms implemented in this module in other circumstances.
.. function:: parse(fp[, environ[, keep_blank_values[, strict_parsing]]])
Parse a query in the environment or from a file (the file defaults to
``sys.stdin`` and environment defaults to ``os.environ``). The *keep_blank_values* and *strict_parsing* parameters are
passed to :func:`urlparse.parse_qs` unchanged.
.. function:: parse_qs(qs[, keep_blank_values[, strict_parsing[, max_num_fields]]])
This function is deprecated in this module. Use :func:`urlparse.parse_qs`
instead. It is maintained here only for backward compatibility.
.. function:: parse_qsl(qs[, keep_blank_values[, strict_parsing[, max_num_fields]]])
This function is deprecated in this module. Use :func:`urlparse.parse_qsl`
instead. It is maintained here only for backward compatibility.
.. function:: parse_multipart(fp, pdict)
Parse input of type :mimetype:`multipart/form-data` (for file uploads).
Arguments are *fp* for the input file and *pdict* for a dictionary containing
other parameters in the :mailheader:`Content-Type` header.
Returns a dictionary just like :func:`urlparse.parse_qs` keys are the field names, each
value is a list of values for that field. This is easy to use but not much good
if you are expecting megabytes to be uploaded --- in that case, use the
:class:`FieldStorage` class instead which is much more flexible.
Note that this does not parse nested multipart parts --- use
:class:`FieldStorage` for that.
.. function:: parse_header(string)
Parse a MIME header (such as :mailheader:`Content-Type`) into a main value and a
dictionary of parameters.
.. function:: test()
Robust test CGI script, usable as main program. Writes minimal HTTP headers and
formats all information provided to the script in HTML form.
.. function:: print_environ()
Format the shell environment in HTML.
.. function:: print_form(form)
Format a form in HTML.
.. function:: print_directory()
Format the current directory in HTML.
.. function:: print_environ_usage()
Print a list of useful (used by CGI) environment variables in HTML.
.. function:: escape(s[, quote])
Convert the characters ``'&'``, ``'<'`` and ``'>'`` in string *s* to HTML-safe
sequences. Use this if you need to display text that might contain such
characters in HTML. If the optional flag *quote* is true, the quotation mark
character (``"``) is also translated; this helps for inclusion in an HTML
attribute value delimited by double quotes, as in ``<a href="...">``. Note
that single quotes are never translated.
If the value to be quoted might include single- or double-quote characters,
or both, consider using the :func:`~xml.sax.saxutils.quoteattr` function in the
:mod:`xml.sax.saxutils` module instead.
.. _cgi-security:
Caring about security
---------------------
.. index:: pair: CGI; security
There's one important rule: if you invoke an external program (via the
:func:`os.system` or :func:`os.popen` functions. or others with similar
functionality), make very sure you don't pass arbitrary strings received from
the client to the shell. This is a well-known security hole whereby clever
hackers anywhere on the Web can exploit a gullible CGI script to invoke
arbitrary shell commands. Even parts of the URL or field names cannot be
trusted, since the request doesn't have to come from your form!
To be on the safe side, if you must pass a string gotten from a form to a shell
command, you should make sure the string contains only alphanumeric characters,
dashes, underscores, and periods.
Installing your CGI script on a Unix system
-------------------------------------------
Read the documentation for your HTTP server and check with your local system
administrator to find the directory where CGI scripts should be installed;
usually this is in a directory :file:`cgi-bin` in the server tree.
Make sure that your script is readable and executable by "others"; the Unix file
mode should be ``0755`` octal (use ``chmod 0755 filename``). Make sure that the
first line of the script contains ``#!`` starting in column 1 followed by the
pathname of the Python interpreter, for instance::
#!/usr/local/bin/python
Make sure the Python interpreter exists and is executable by "others".
Make sure that any files your script needs to read or write are readable or
writable, respectively, by "others" --- their mode should be ``0644`` for
readable and ``0666`` for writable. This is because, for security reasons, the
HTTP server executes your script as user "nobody", without any special
privileges. It can only read (write, execute) files that everybody can read
(write, execute). The current directory at execution time is also different (it
is usually the server's cgi-bin directory) and the set of environment variables
is also different from what you get when you log in. In particular, don't count
on the shell's search path for executables (:envvar:`PATH`) or the Python module
search path (:envvar:`PYTHONPATH`) to be set to anything interesting.
If you need to load modules from a directory which is not on Python's default
module search path, you can change the path in your script, before importing
other modules. For example::
import sys
sys.path.insert(0, "/usr/home/joe/lib/python")
sys.path.insert(0, "/usr/local/lib/python")
(This way, the directory inserted last will be searched first!)
Instructions for non-Unix systems will vary; check your HTTP server's
documentation (it will usually have a section on CGI scripts).
Testing your CGI script
-----------------------
Unfortunately, a CGI script will generally not run when you try it from the
command line, and a script that works perfectly from the command line may fail
mysteriously when run from the server. There's one reason why you should still
test your script from the command line: if it contains a syntax error, the
Python interpreter won't execute it at all, and the HTTP server will most likely
send a cryptic error to the client.
Assuming your script has no syntax errors, yet it does not work, you have no
choice but to read the next section.
Debugging CGI scripts
---------------------
.. index:: pair: CGI; debugging
First of all, check for trivial installation errors --- reading the section
above on installing your CGI script carefully can save you a lot of time. If
you wonder whether you have understood the installation procedure correctly, try
installing a copy of this module file (:file:`cgi.py`) as a CGI script. When
invoked as a script, the file will dump its environment and the contents of the
form in HTML form. Give it the right mode etc, and send it a request. If it's
installed in the standard :file:`cgi-bin` directory, it should be possible to
send it a request by entering a URL into your browser of the form:
.. code-block:: none
http://yourhostname/cgi-bin/cgi.py?name=Joe+Blow&addr=At+Home
If this gives an error of type 404, the server cannot find the script -- perhaps
you need to install it in a different directory. If it gives another error,
there's an installation problem that you should fix before trying to go any
further. If you get a nicely formatted listing of the environment and form
content (in this example, the fields should be listed as "addr" with value "At
Home" and "name" with value "Joe Blow"), the :file:`cgi.py` script has been
installed correctly. If you follow the same procedure for your own script, you
should now be able to debug it.
The next step could be to call the :mod:`cgi` module's :func:`test` function
from your script: replace its main code with the single statement ::
cgi.test()
This should produce the same results as those gotten from installing the
:file:`cgi.py` file itself.
When an ordinary Python script raises an unhandled exception (for whatever
reason: of a typo in a module name, a file that can't be opened, etc.), the
Python interpreter prints a nice traceback and exits. While the Python
interpreter will still do this when your CGI script raises an exception, most
likely the traceback will end up in one of the HTTP server's log files, or be
discarded altogether.
Fortunately, once you have managed to get your script to execute *some* code,
you can easily send tracebacks to the Web browser using the :mod:`cgitb` module.
If you haven't done so already, just add the lines::
import cgitb
cgitb.enable()
to the top of your script. Then try running it again; when a problem occurs,
you should see a detailed report that will likely make apparent the cause of the
crash.
If you suspect that there may be a problem in importing the :mod:`cgitb` module,
you can use an even more robust approach (which only uses built-in modules)::
import sys
sys.stderr = sys.stdout
print "Content-Type: text/plain"
print
...your code here...
This relies on the Python interpreter to print the traceback. The content type
of the output is set to plain text, which disables all HTML processing. If your
script works, the raw HTML will be displayed by your client. If it raises an
exception, most likely after the first two lines have been printed, a traceback
will be displayed. Because no HTML interpretation is going on, the traceback
will be readable.
Common problems and solutions
-----------------------------
* Most HTTP servers buffer the output from CGI scripts until the script is
completed. This means that it is not possible to display a progress report on
the client's display while the script is running.
* Check the installation instructions above.
* Check the HTTP server's log files. (``tail -f logfile`` in a separate window
may be useful!)
* Always check a script for syntax errors first, by doing something like
``python script.py``.
* If your script does not have any syntax errors, try adding ``import cgitb;
cgitb.enable()`` to the top of the script.
* When invoking external programs, make sure they can be found. Usually, this
means using absolute path names --- :envvar:`PATH` is usually not set to a very
useful value in a CGI script.
* When reading or writing external files, make sure they can be read or written
by the userid under which your CGI script will be running: this is typically the
userid under which the web server is running, or some explicitly specified
userid for a web server's ``suexec`` feature.
* Don't try to give a CGI script a set-uid mode. This doesn't work on most
systems, and is a security liability as well.
.. rubric:: Footnotes
.. [#] Note that some recent versions of the HTML specification do state what order the
field values should be supplied in, but knowing whether a request was
received from a conforming browser, or even from a browser at all, is tedious
and error-prone.
PK %�\�6gE�
�
+ html/_sources/library/cgihttpserver.rst.txtnu �[��� :mod:`CGIHTTPServer` --- CGI-capable HTTP request handler
=========================================================
.. module:: CGIHTTPServer
:synopsis: This module provides a request handler for HTTP servers which can run CGI
scripts.
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
.. note::
The :mod:`CGIHTTPServer` module has been merged into :mod:`http.server` in
Python 3. The :term:`2to3` tool will automatically adapt imports when
converting your sources to Python 3.
The :mod:`CGIHTTPServer` module defines a request-handler class, interface
compatible with :class:`BaseHTTPServer.BaseHTTPRequestHandler` and inherits
behavior from :class:`SimpleHTTPServer.SimpleHTTPRequestHandler` but can also
run CGI scripts.
.. note::
This module can run CGI scripts on Unix and Windows systems.
.. note::
CGI scripts run by the :class:`CGIHTTPRequestHandler` class cannot execute
redirects (HTTP code 302), because code 200 (script output follows) is sent
prior to execution of the CGI script. This pre-empts the status code.
The :mod:`CGIHTTPServer` module defines the following class:
.. class:: CGIHTTPRequestHandler(request, client_address, server)
This class is used to serve either files or output of CGI scripts from the
current directory and below. Note that mapping HTTP hierarchic structure to
local directory structure is exactly as in
:class:`SimpleHTTPServer.SimpleHTTPRequestHandler`.
The class will however, run the CGI script, instead of serving it as a file, if
it guesses it to be a CGI script. Only directory-based CGI are used --- the
other common server configuration is to treat special extensions as denoting CGI
scripts.
The :func:`do_GET` and :func:`do_HEAD` functions are modified to run CGI scripts
and serve the output, instead of serving files, if the request leads to
somewhere below the ``cgi_directories`` path.
The :class:`CGIHTTPRequestHandler` defines the following data member:
.. attribute:: cgi_directories
This defaults to ``['/cgi-bin', '/htbin']`` and describes directories to
treat as containing CGI scripts.
The :class:`CGIHTTPRequestHandler` defines the following methods:
.. method:: do_POST()
This method serves the ``'POST'`` request type, only allowed for CGI
scripts. Error 501, "Can only POST to CGI scripts", is output when trying
to POST to a non-CGI url.
Note that CGI scripts will be run with UID of user nobody, for security reasons.
Problems with the CGI script will be translated to error 403.
For example usage, see the implementation of the :func:`test` function.
.. seealso::
Module :mod:`BaseHTTPServer`
Base class implementation for Web server and request handler.
PK %�\{��: : # html/_sources/library/cgitb.rst.txtnu �[���
:mod:`cgitb` --- Traceback manager for CGI scripts
==================================================
.. module:: cgitb
:synopsis: Configurable traceback handler for CGI scripts.
.. moduleauthor:: Ka-Ping Yee <ping@lfw.org>
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
.. versionadded:: 2.2
.. index::
single: CGI; exceptions
single: CGI; tracebacks
single: exceptions; in CGI scripts
single: tracebacks; in CGI scripts
The :mod:`cgitb` module provides a special exception handler for Python scripts.
(Its name is a bit misleading. It was originally designed to display extensive
traceback information in HTML for CGI scripts. It was later generalized to also
display this information in plain text.) After this module is activated, if an
uncaught exception occurs, a detailed, formatted report will be displayed. The
report includes a traceback showing excerpts of the source code for each level,
as well as the values of the arguments and local variables to currently running
functions, to help you debug the problem. Optionally, you can save this
information to a file instead of sending it to the browser.
To enable this feature, simply add this to the top of your CGI script::
import cgitb
cgitb.enable()
The options to the :func:`enable` function control whether the report is
displayed in the browser and whether the report is logged to a file for later
analysis.
.. function:: enable([display[, logdir[, context[, format]]]])
.. index:: single: excepthook() (in module sys)
This function causes the :mod:`cgitb` module to take over the interpreter's
default handling for exceptions by setting the value of :attr:`sys.excepthook`.
The optional argument *display* defaults to ``1`` and can be set to ``0`` to
suppress sending the traceback to the browser. If the argument *logdir* is
present, the traceback reports are written to files. The value of *logdir*
should be a directory where these files will be placed. The optional argument
*context* is the number of lines of context to display around the current line
of source code in the traceback; this defaults to ``5``. If the optional
argument *format* is ``"html"``, the output is formatted as HTML. Any other
value forces plain text output. The default value is ``"html"``.
.. function:: handler([info])
This function handles an exception using the default settings (that is, show a
report in the browser, but don't log to a file). This can be used when you've
caught an exception and want to report it using :mod:`cgitb`. The optional
*info* argument should be a 3-tuple containing an exception type, exception
value, and traceback object, exactly like the tuple returned by
:func:`sys.exc_info`. If the *info* argument is not supplied, the current
exception is obtained from :func:`sys.exc_info`.
PK %�\�;N[ [ # html/_sources/library/chunk.rst.txtnu �[���
:mod:`chunk` --- Read IFF chunked data
======================================
.. module:: chunk
:synopsis: Module to read IFF chunks.
.. moduleauthor:: Sjoerd Mullender <sjoerd@acm.org>
.. sectionauthor:: Sjoerd Mullender <sjoerd@acm.org>
.. index::
single: Audio Interchange File Format
single: AIFF
single: AIFF-C
single: Real Media File Format
single: RMFF
This module provides an interface for reading files that use EA IFF 85 chunks.
[#]_ This format is used in at least the Audio Interchange File Format
(AIFF/AIFF-C) and the Real Media File Format (RMFF). The WAVE audio file format
is closely related and can also be read using this module.
A chunk has the following structure:
+---------+--------+-------------------------------+
| Offset | Length | Contents |
+=========+========+===============================+
| 0 | 4 | Chunk ID |
+---------+--------+-------------------------------+
| 4 | 4 | Size of chunk in big-endian |
| | | byte order, not including the |
| | | header |
+---------+--------+-------------------------------+
| 8 | *n* | Data bytes, where *n* is the |
| | | size given in the preceding |
| | | field |
+---------+--------+-------------------------------+
| 8 + *n* | 0 or 1 | Pad byte needed if *n* is odd |
| | | and chunk alignment is used |
+---------+--------+-------------------------------+
The ID is a 4-byte string which identifies the type of chunk.
The size field (a 32-bit value, encoded using big-endian byte order) gives the
size of the chunk data, not including the 8-byte header.
Usually an IFF-type file consists of one or more chunks. The proposed usage of
the :class:`Chunk` class defined here is to instantiate an instance at the start
of each chunk and read from the instance until it reaches the end, after which a
new instance can be instantiated. At the end of the file, creating a new
instance will fail with an :exc:`EOFError` exception.
.. class:: Chunk(file[, align, bigendian, inclheader])
Class which represents a chunk. The *file* argument is expected to be a
file-like object. An instance of this class is specifically allowed. The
only method that is needed is :meth:`~file.read`. If the methods
:meth:`~file.seek` and :meth:`~file.tell` are present and don't
raise an exception, they are also used.
If these methods are present and raise an exception, they are expected to not
have altered the object. If the optional argument *align* is true, chunks
are assumed to be aligned on 2-byte boundaries. If *align* is false, no
alignment is assumed. The default value is true. If the optional argument
*bigendian* is false, the chunk size is assumed to be in little-endian order.
This is needed for WAVE audio files. The default value is true. If the
optional argument *inclheader* is true, the size given in the chunk header
includes the size of the header. The default value is false.
A :class:`Chunk` object supports the following methods:
.. method:: getname()
Returns the name (ID) of the chunk. This is the first 4 bytes of the
chunk.
.. method:: getsize()
Returns the size of the chunk.
.. method:: close()
Close and skip to the end of the chunk. This does not close the
underlying file.
The remaining methods will raise :exc:`IOError` if called after the
:meth:`close` method has been called.
.. method:: isatty()
Returns ``False``.
.. method:: seek(pos[, whence])
Set the chunk's current position. The *whence* argument is optional and
defaults to ``0`` (absolute file positioning); other values are ``1``
(seek relative to the current position) and ``2`` (seek relative to the
file's end). There is no return value. If the underlying file does not
allow seek, only forward seeks are allowed.
.. method:: tell()
Return the current position into the chunk.
.. method:: read([size])
Read at most *size* bytes from the chunk (less if the read hits the end of
the chunk before obtaining *size* bytes). If the *size* argument is
negative or omitted, read all data until the end of the chunk. The bytes
are returned as a string object. An empty string is returned when the end
of the chunk is encountered immediately.
.. method:: skip()
Skip to the end of the chunk. All further calls to :meth:`read` for the
chunk will return ``''``. If you are not interested in the contents of
the chunk, this method should be called so that the file points to the
start of the next chunk.
.. rubric:: Footnotes
.. [#] "EA IFF 85" Standard for Interchange Format Files, Jerry Morrison, Electronic
Arts, January 1985.
PK %�\ʼQ.� � # html/_sources/library/cmath.rst.txtnu �[��� :mod:`cmath` --- Mathematical functions for complex numbers
===========================================================
.. module:: cmath
:synopsis: Mathematical functions for complex numbers.
This module is always available. It provides access to mathematical functions
for complex numbers. The functions in this module accept integers,
floating-point numbers or complex numbers as arguments. They will also accept
any Python object that has either a :meth:`__complex__` or a :meth:`__float__`
method: these methods are used to convert the object to a complex or
floating-point number, respectively, and the function is then applied to the
result of the conversion.
.. note::
On platforms with hardware and system-level support for signed
zeros, functions involving branch cuts are continuous on *both*
sides of the branch cut: the sign of the zero distinguishes one
side of the branch cut from the other. On platforms that do not
support signed zeros the continuity is as specified below.
Conversions to and from polar coordinates
-----------------------------------------
A Python complex number ``z`` is stored internally using *rectangular*
or *Cartesian* coordinates. It is completely determined by its *real
part* ``z.real`` and its *imaginary part* ``z.imag``. In other
words::
z == z.real + z.imag*1j
*Polar coordinates* give an alternative way to represent a complex
number. In polar coordinates, a complex number *z* is defined by the
modulus *r* and the phase angle *phi*. The modulus *r* is the distance
from *z* to the origin, while the phase *phi* is the counterclockwise
angle, measured in radians, from the positive x-axis to the line
segment that joins the origin to *z*.
The following functions can be used to convert from the native
rectangular coordinates to polar coordinates and back.
.. function:: phase(x)
Return the phase of *x* (also known as the *argument* of *x*), as a
float. ``phase(x)`` is equivalent to ``math.atan2(x.imag,
x.real)``. The result lies in the range [-π, π], and the branch
cut for this operation lies along the negative real axis,
continuous from above. On systems with support for signed zeros
(which includes most systems in current use), this means that the
sign of the result is the same as the sign of ``x.imag``, even when
``x.imag`` is zero::
>>> phase(complex(-1.0, 0.0))
3.1415926535897931
>>> phase(complex(-1.0, -0.0))
-3.1415926535897931
.. versionadded:: 2.6
.. note::
The modulus (absolute value) of a complex number *x* can be
computed using the built-in :func:`abs` function. There is no
separate :mod:`cmath` module function for this operation.
.. function:: polar(x)
Return the representation of *x* in polar coordinates. Returns a
pair ``(r, phi)`` where *r* is the modulus of *x* and phi is the
phase of *x*. ``polar(x)`` is equivalent to ``(abs(x),
phase(x))``.
.. versionadded:: 2.6
.. function:: rect(r, phi)
Return the complex number *x* with polar coordinates *r* and *phi*.
Equivalent to ``r * (math.cos(phi) + math.sin(phi)*1j)``.
.. versionadded:: 2.6
Power and logarithmic functions
-------------------------------
.. function:: exp(x)
Return the exponential value ``e**x``.
.. function:: log(x[, base])
Returns the logarithm of *x* to the given *base*. If the *base* is not
specified, returns the natural logarithm of *x*. There is one branch cut, from 0
along the negative real axis to -∞, continuous from above.
.. versionchanged:: 2.4
*base* argument added.
.. function:: log10(x)
Return the base-10 logarithm of *x*. This has the same branch cut as
:func:`log`.
.. function:: sqrt(x)
Return the square root of *x*. This has the same branch cut as :func:`log`.
Trigonometric functions
-----------------------
.. function:: acos(x)
Return the arc cosine of *x*. There are two branch cuts: One extends right from
1 along the real axis to ∞, continuous from below. The other extends left from
-1 along the real axis to -∞, continuous from above.
.. function:: asin(x)
Return the arc sine of *x*. This has the same branch cuts as :func:`acos`.
.. function:: atan(x)
Return the arc tangent of *x*. There are two branch cuts: One extends from
``1j`` along the imaginary axis to ``∞j``, continuous from the right. The
other extends from ``-1j`` along the imaginary axis to ``-∞j``, continuous
from the left.
.. versionchanged:: 2.6
direction of continuity of upper cut reversed
.. function:: cos(x)
Return the cosine of *x*.
.. function:: sin(x)
Return the sine of *x*.
.. function:: tan(x)
Return the tangent of *x*.
Hyperbolic functions
--------------------
.. function:: acosh(x)
Return the inverse hyperbolic cosine of *x*. There is one branch cut,
extending left from 1 along the real axis to -∞, continuous from above.
.. function:: asinh(x)
Return the inverse hyperbolic sine of *x*. There are two branch cuts:
One extends from ``1j`` along the imaginary axis to ``∞j``,
continuous from the right. The other extends from ``-1j`` along
the imaginary axis to ``-∞j``, continuous from the left.
.. versionchanged:: 2.6
branch cuts moved to match those recommended by the C99 standard
.. function:: atanh(x)
Return the inverse hyperbolic tangent of *x*. There are two branch cuts: One
extends from ``1`` along the real axis to ``∞``, continuous from below. The
other extends from ``-1`` along the real axis to ``-∞``, continuous from
above.
.. versionchanged:: 2.6
direction of continuity of right cut reversed
.. function:: cosh(x)
Return the hyperbolic cosine of *x*.
.. function:: sinh(x)
Return the hyperbolic sine of *x*.
.. function:: tanh(x)
Return the hyperbolic tangent of *x*.
Classification functions
------------------------
.. function:: isinf(x)
Return ``True`` if the real or the imaginary part of x is positive
or negative infinity.
.. versionadded:: 2.6
.. function:: isnan(x)
Return ``True`` if the real or imaginary part of x is not a number (NaN).
.. versionadded:: 2.6
Constants
---------
.. data:: pi
The mathematical constant *π*, as a float.
.. data:: e
The mathematical constant *e*, as a float.
.. index:: module: math
Note that the selection of functions is similar, but not identical, to that in
module :mod:`math`. The reason for having two modules is that some users aren't
interested in complex numbers, and perhaps don't even know what they are. They
would rather have ``math.sqrt(-1)`` raise an exception than return a complex
number. Also note that the functions defined in :mod:`cmath` always return a
complex number, even if the answer can be expressed as a real number (in which
case the complex number has an imaginary part of zero).
A note on branch cuts: They are curves along which the given function fails to
be continuous. They are a necessary feature of many complex functions. It is
assumed that if you need to compute with complex functions, you will understand
about branch cuts. Consult almost any (not too elementary) book on complex
variables for enlightenment. For information of the proper choice of branch
cuts for numerical purposes, a good reference should be the following:
.. seealso::
Kahan, W: Branch cuts for complex elementary functions; or, Much ado about
nothing's sign bit. In Iserles, A., and Powell, M. (eds.), The state of the art
in numerical analysis. Clarendon Press (1987) pp165--211.
PK %�\��u! u! ! html/_sources/library/cmd.rst.txtnu �[��� :mod:`cmd` --- Support for line-oriented command interpreters
=============================================================
.. module:: cmd
:synopsis: Build line-oriented command interpreters.
.. sectionauthor:: Eric S. Raymond <esr@snark.thyrsus.com>
**Source code:** :source:`Lib/cmd.py`
--------------
The :class:`Cmd` class provides a simple framework for writing line-oriented
command interpreters. These are often useful for test harnesses, administrative
tools, and prototypes that will later be wrapped in a more sophisticated
interface.
.. class:: Cmd([completekey[, stdin[, stdout]]])
A :class:`Cmd` instance or subclass instance is a line-oriented interpreter
framework. There is no good reason to instantiate :class:`Cmd` itself; rather,
it's useful as a superclass of an interpreter class you define yourself in order
to inherit :class:`Cmd`'s methods and encapsulate action methods.
The optional argument *completekey* is the :mod:`readline` name of a completion
key; it defaults to :kbd:`Tab`. If *completekey* is not :const:`None` and
:mod:`readline` is available, command completion is done automatically.
The optional arguments *stdin* and *stdout* specify the input and output file
objects that the Cmd instance or subclass instance will use for input and
output. If not specified, they will default to :data:`sys.stdin` and
:data:`sys.stdout`.
If you want a given *stdin* to be used, make sure to set the instance's
:attr:`use_rawinput` attribute to ``False``, otherwise *stdin* will be
ignored.
.. versionchanged:: 2.3
The *stdin* and *stdout* parameters were added.
.. _cmd-objects:
Cmd Objects
-----------
A :class:`Cmd` instance has the following methods:
.. method:: Cmd.cmdloop([intro])
Repeatedly issue a prompt, accept input, parse an initial prefix off the
received input, and dispatch to action methods, passing them the remainder of
the line as argument.
The optional argument is a banner or intro string to be issued before the first
prompt (this overrides the :attr:`intro` class attribute).
If the :mod:`readline` module is loaded, input will automatically inherit
:program:`bash`\ -like history-list editing (e.g. :kbd:`Control-P` scrolls back
to the last command, :kbd:`Control-N` forward to the next one, :kbd:`Control-F`
moves the cursor to the right non-destructively, :kbd:`Control-B` moves the
cursor to the left non-destructively, etc.).
An end-of-file on input is passed back as the string ``'EOF'``.
An interpreter instance will recognize a command name ``foo`` if and only if it
has a method :meth:`do_foo`. As a special case, a line beginning with the
character ``'?'`` is dispatched to the method :meth:`do_help`. As another
special case, a line beginning with the character ``'!'`` is dispatched to the
method :meth:`do_shell` (if such a method is defined).
This method will return when the :meth:`postcmd` method returns a true value.
The *stop* argument to :meth:`postcmd` is the return value from the command's
corresponding :meth:`do_\*` method.
If completion is enabled, completing commands will be done automatically, and
completing of commands args is done by calling :meth:`complete_foo` with
arguments *text*, *line*, *begidx*, and *endidx*. *text* is the string prefix
we are attempting to match: all returned matches must begin with it. *line* is
the current input line with leading whitespace removed, *begidx* and *endidx*
are the beginning and ending indexes of the prefix text, which could be used to
provide different completion depending upon which position the argument is in.
All subclasses of :class:`Cmd` inherit a predefined :meth:`do_help`. This
method, called with an argument ``'bar'``, invokes the corresponding method
:meth:`help_bar`, and if that is not present, prints the docstring of
:meth:`do_bar`, if available. With no argument, :meth:`do_help` lists all
available help topics (that is, all commands with corresponding
:meth:`help_\*` methods or commands that have docstrings), and also lists any
undocumented commands.
.. method:: Cmd.onecmd(str)
Interpret the argument as though it had been typed in response to the prompt.
This may be overridden, but should not normally need to be; see the
:meth:`precmd` and :meth:`postcmd` methods for useful execution hooks. The
return value is a flag indicating whether interpretation of commands by the
interpreter should stop. If there is a :meth:`do_\*` method for the command
*str*, the return value of that method is returned, otherwise the return value
from the :meth:`default` method is returned.
.. method:: Cmd.emptyline()
Method called when an empty line is entered in response to the prompt. If this
method is not overridden, it repeats the last nonempty command entered.
.. method:: Cmd.default(line)
Method called on an input line when the command prefix is not recognized. If
this method is not overridden, it prints an error message and returns.
.. method:: Cmd.completedefault(text, line, begidx, endidx)
Method called to complete an input line when no command-specific
:meth:`complete_\*` method is available. By default, it returns an empty list.
.. method:: Cmd.precmd(line)
Hook method executed just before the command line *line* is interpreted, but
after the input prompt is generated and issued. This method is a stub in
:class:`Cmd`; it exists to be overridden by subclasses. The return value is
used as the command which will be executed by the :meth:`onecmd` method; the
:meth:`precmd` implementation may re-write the command or simply return *line*
unchanged.
.. method:: Cmd.postcmd(stop, line)
Hook method executed just after a command dispatch is finished. This method is
a stub in :class:`Cmd`; it exists to be overridden by subclasses. *line* is the
command line which was executed, and *stop* is a flag which indicates whether
execution will be terminated after the call to :meth:`postcmd`; this will be the
return value of the :meth:`onecmd` method. The return value of this method will
be used as the new value for the internal flag which corresponds to *stop*;
returning false will cause interpretation to continue.
.. method:: Cmd.preloop()
Hook method executed once when :meth:`cmdloop` is called. This method is a stub
in :class:`Cmd`; it exists to be overridden by subclasses.
.. method:: Cmd.postloop()
Hook method executed once when :meth:`cmdloop` is about to return. This method
is a stub in :class:`Cmd`; it exists to be overridden by subclasses.
Instances of :class:`Cmd` subclasses have some public instance variables:
.. attribute:: Cmd.prompt
The prompt issued to solicit input.
.. attribute:: Cmd.identchars
The string of characters accepted for the command prefix.
.. attribute:: Cmd.lastcmd
The last nonempty command prefix seen.
.. attribute:: Cmd.cmdqueue
A list of queued input lines. The cmdqueue list is checked in
:meth:`cmdloop` when new input is needed; if it is nonempty, its elements
will be processed in order, as if entered at the prompt.
.. attribute:: Cmd.intro
A string to issue as an intro or banner. May be overridden by giving the
:meth:`cmdloop` method an argument.
.. attribute:: Cmd.doc_header
The header to issue if the help output has a section for documented commands.
.. attribute:: Cmd.misc_header
The header to issue if the help output has a section for miscellaneous help
topics (that is, there are :meth:`help_\*` methods without corresponding
:meth:`do_\*` methods).
.. attribute:: Cmd.undoc_header
The header to issue if the help output has a section for undocumented commands
(that is, there are :meth:`do_\*` methods without corresponding :meth:`help_\*`
methods).
.. attribute:: Cmd.ruler
The character used to draw separator lines under the help-message headers. If
empty, no ruler line is drawn. It defaults to ``'='``.
.. attribute:: Cmd.use_rawinput
A flag, defaulting to true. If true, :meth:`cmdloop` uses :func:`raw_input` to
display a prompt and read the next command; if false, :meth:`sys.stdout.write`
and :meth:`sys.stdin.readline` are used. (This means that by importing
:mod:`readline`, on systems that support it, the interpreter will automatically
support :program:`Emacs`\ -like line editing and command-history keystrokes.)
PK %�\�r.b� � " html/_sources/library/code.rst.txtnu �[���
:mod:`code` --- Interpreter base classes
========================================
.. module:: code
:synopsis: Facilities to implement read-eval-print loops.
The ``code`` module provides facilities to implement read-eval-print loops in
Python. Two classes and convenience functions are included which can be used to
build applications which provide an interactive interpreter prompt.
.. class:: InteractiveInterpreter([locals])
This class deals with parsing and interpreter state (the user's namespace); it
does not deal with input buffering or prompting or input file naming (the
filename is always passed in explicitly). The optional *locals* argument
specifies the dictionary in which code will be executed; it defaults to a newly
created dictionary with key ``'__name__'`` set to ``'__console__'`` and key
``'__doc__'`` set to ``None``.
.. class:: InteractiveConsole([locals[, filename]])
Closely emulate the behavior of the interactive Python interpreter. This class
builds on :class:`InteractiveInterpreter` and adds prompting using the familiar
``sys.ps1`` and ``sys.ps2``, and input buffering.
.. function:: interact([banner[, readfunc[, local]]])
Convenience function to run a read-eval-print loop. This creates a new instance
of :class:`InteractiveConsole` and sets *readfunc* to be used as the
:meth:`InteractiveConsole.raw_input` method, if provided. If *local* is
provided, it is passed to the :class:`InteractiveConsole` constructor for
use as the default namespace for the interpreter loop. The :meth:`interact`
method of the instance is then run with *banner* passed as the banner to
use, if provided. The console object is discarded after use.
.. function:: compile_command(source[, filename[, symbol]])
This function is useful for programs that want to emulate Python's interpreter
main loop (a.k.a. the read-eval-print loop). The tricky part is to determine
when the user has entered an incomplete command that can be completed by
entering more text (as opposed to a complete command or a syntax error). This
function *almost* always makes the same decision as the real interpreter main
loop.
*source* is the source string; *filename* is the optional filename from which
source was read, defaulting to ``'<input>'``; and *symbol* is the optional
grammar start symbol, which should be either ``'single'`` (the default) or
``'eval'``.
Returns a code object (the same as ``compile(source, filename, symbol)``) if the
command is complete and valid; ``None`` if the command is incomplete; raises
:exc:`SyntaxError` if the command is complete and contains a syntax error, or
raises :exc:`OverflowError` or :exc:`ValueError` if the command contains an
invalid literal.
.. _interpreter-objects:
Interactive Interpreter Objects
-------------------------------
.. method:: InteractiveInterpreter.runsource(source[, filename[, symbol]])
Compile and run some source in the interpreter. Arguments are the same as for
:func:`compile_command`; the default for *filename* is ``'<input>'``, and for
*symbol* is ``'single'``. One several things can happen:
* The input is incorrect; :func:`compile_command` raised an exception
(:exc:`SyntaxError` or :exc:`OverflowError`). A syntax traceback will be
printed by calling the :meth:`showsyntaxerror` method. :meth:`runsource`
returns ``False``.
* The input is incomplete, and more input is required; :func:`compile_command`
returned ``None``. :meth:`runsource` returns ``True``.
* The input is complete; :func:`compile_command` returned a code object. The
code is executed by calling the :meth:`runcode` (which also handles run-time
exceptions, except for :exc:`SystemExit`). :meth:`runsource` returns ``False``.
The return value can be used to decide whether to use ``sys.ps1`` or ``sys.ps2``
to prompt the next line.
.. method:: InteractiveInterpreter.runcode(code)
Execute a code object. When an exception occurs, :meth:`showtraceback` is called
to display a traceback. All exceptions are caught except :exc:`SystemExit`,
which is allowed to propagate.
A note about :exc:`KeyboardInterrupt`: this exception may occur elsewhere in
this code, and may not always be caught. The caller should be prepared to deal
with it.
.. method:: InteractiveInterpreter.showsyntaxerror([filename])
Display the syntax error that just occurred. This does not display a stack
trace because there isn't one for syntax errors. If *filename* is given, it is
stuffed into the exception instead of the default filename provided by Python's
parser, because it always uses ``'<string>'`` when reading from a string. The
output is written by the :meth:`write` method.
.. method:: InteractiveInterpreter.showtraceback()
Display the exception that just occurred. We remove the first stack item
because it is within the interpreter object implementation. The output is
written by the :meth:`write` method.
.. method:: InteractiveInterpreter.write(data)
Write a string to the standard error stream (``sys.stderr``). Derived classes
should override this to provide the appropriate output handling as needed.
.. _console-objects:
Interactive Console Objects
---------------------------
The :class:`InteractiveConsole` class is a subclass of
:class:`InteractiveInterpreter`, and so offers all the methods of the
interpreter objects as well as the following additions.
.. method:: InteractiveConsole.interact([banner])
Closely emulate the interactive Python console. The optional banner argument
specify the banner to print before the first interaction; by default it prints a
banner similar to the one printed by the standard Python interpreter, followed
by the class name of the console object in parentheses (so as not to confuse
this with the real interpreter -- since it's so close!).
.. method:: InteractiveConsole.push(line)
Push a line of source text to the interpreter. The line should not have a
trailing newline; it may have internal newlines. The line is appended to a
buffer and the interpreter's :meth:`runsource` method is called with the
concatenated contents of the buffer as source. If this indicates that the
command was executed or invalid, the buffer is reset; otherwise, the command is
incomplete, and the buffer is left as it was after the line was appended. The
return value is ``True`` if more input is required, ``False`` if the line was
dealt with in some way (this is the same as :meth:`runsource`).
.. method:: InteractiveConsole.resetbuffer()
Remove any unhandled source text from the input buffer.
.. method:: InteractiveConsole.raw_input([prompt])
Write a prompt and read a line. The returned line does not include the trailing
newline. When the user enters the EOF key sequence, :exc:`EOFError` is raised.
The base implementation uses the built-in function :func:`raw_input`; a subclass
may replace this with a different implementation.
PK %�\_�Zl� � $ html/_sources/library/codecs.rst.txtnu �[���
:mod:`codecs` --- Codec registry and base classes
=================================================
.. module:: codecs
:synopsis: Encode and decode data and streams.
.. moduleauthor:: Marc-Andre Lemburg <mal@lemburg.com>
.. sectionauthor:: Marc-Andre Lemburg <mal@lemburg.com>
.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
.. index::
single: Unicode
single: Codecs
pair: Codecs; encode
pair: Codecs; decode
single: streams
pair: stackable; streams
This module defines base classes for standard Python codecs (encoders and
decoders) and provides access to the internal Python codec registry which
manages the codec and error handling lookup process.
It defines the following functions:
.. function:: encode(obj, [encoding[, errors]])
Encodes *obj* using the codec registered for *encoding*. The default
encoding is ``'ascii'``.
*Errors* may be given to set the desired error handling scheme. The
default error handler is ``'strict'`` meaning that encoding errors raise
:exc:`ValueError` (or a more codec specific subclass, such as
:exc:`UnicodeEncodeError`). Refer to :ref:`codec-base-classes` for more
information on codec error handling.
.. versionadded:: 2.4
.. function:: decode(obj, [encoding[, errors]])
Decodes *obj* using the codec registered for *encoding*. The default
encoding is ``'ascii'``.
*Errors* may be given to set the desired error handling scheme. The
default error handler is ``'strict'`` meaning that decoding errors raise
:exc:`ValueError` (or a more codec specific subclass, such as
:exc:`UnicodeDecodeError`). Refer to :ref:`codec-base-classes` for more
information on codec error handling.
.. versionadded:: 2.4
.. function:: register(search_function)
Register a codec search function. Search functions are expected to take one
argument, the encoding name in all lower case letters, and return a
:class:`CodecInfo` object having the following attributes:
* ``name`` The name of the encoding;
* ``encode`` The stateless encoding function;
* ``decode`` The stateless decoding function;
* ``incrementalencoder`` An incremental encoder class or factory function;
* ``incrementaldecoder`` An incremental decoder class or factory function;
* ``streamwriter`` A stream writer class or factory function;
* ``streamreader`` A stream reader class or factory function.
The various functions or classes take the following arguments:
*encode* and *decode*: These must be functions or methods which have the same
interface as the :meth:`~Codec.encode`/:meth:`~Codec.decode` methods of Codec
instances (see :ref:`Codec Interface <codec-objects>`). The functions/methods
are expected to work in a stateless mode.
*incrementalencoder* and *incrementaldecoder*: These have to be factory
functions providing the following interface:
``factory(errors='strict')``
The factory functions must return objects providing the interfaces defined by
the base classes :class:`IncrementalEncoder` and :class:`IncrementalDecoder`,
respectively. Incremental codecs can maintain state.
*streamreader* and *streamwriter*: These have to be factory functions providing
the following interface:
``factory(stream, errors='strict')``
The factory functions must return objects providing the interfaces defined by
the base classes :class:`StreamReader` and :class:`StreamWriter`, respectively.
Stream codecs can maintain state.
Possible values for errors are
* ``'strict'``: raise an exception in case of an encoding error
* ``'replace'``: replace malformed data with a suitable replacement marker,
such as ``'?'`` or ``'\ufffd'``
* ``'ignore'``: ignore malformed data and continue without further notice
* ``'xmlcharrefreplace'``: replace with the appropriate XML character
reference (for encoding only)
* ``'backslashreplace'``: replace with backslashed escape sequences (for
encoding only)
as well as any other error handling name defined via :func:`register_error`.
In case a search function cannot find a given encoding, it should return
``None``.
.. function:: lookup(encoding)
Looks up the codec info in the Python codec registry and returns a
:class:`CodecInfo` object as defined above.
Encodings are first looked up in the registry's cache. If not found, the list of
registered search functions is scanned. If no :class:`CodecInfo` object is
found, a :exc:`LookupError` is raised. Otherwise, the :class:`CodecInfo` object
is stored in the cache and returned to the caller.
To simplify access to the various codecs, the module provides these additional
functions which use :func:`lookup` for the codec lookup:
.. function:: getencoder(encoding)
Look up the codec for the given encoding and return its encoder function.
Raises a :exc:`LookupError` in case the encoding cannot be found.
.. function:: getdecoder(encoding)
Look up the codec for the given encoding and return its decoder function.
Raises a :exc:`LookupError` in case the encoding cannot be found.
.. function:: getincrementalencoder(encoding)
Look up the codec for the given encoding and return its incremental encoder
class or factory function.
Raises a :exc:`LookupError` in case the encoding cannot be found or the codec
doesn't support an incremental encoder.
.. versionadded:: 2.5
.. function:: getincrementaldecoder(encoding)
Look up the codec for the given encoding and return its incremental decoder
class or factory function.
Raises a :exc:`LookupError` in case the encoding cannot be found or the codec
doesn't support an incremental decoder.
.. versionadded:: 2.5
.. function:: getreader(encoding)
Look up the codec for the given encoding and return its StreamReader class or
factory function.
Raises a :exc:`LookupError` in case the encoding cannot be found.
.. function:: getwriter(encoding)
Look up the codec for the given encoding and return its StreamWriter class or
factory function.
Raises a :exc:`LookupError` in case the encoding cannot be found.
.. function:: register_error(name, error_handler)
Register the error handling function *error_handler* under the name *name*.
*error_handler* will be called during encoding and decoding in case of an error,
when *name* is specified as the errors parameter.
For encoding *error_handler* will be called with a :exc:`UnicodeEncodeError`
instance, which contains information about the location of the error. The error
handler must either raise this or a different exception or return a tuple with a
replacement for the unencodable part of the input and a position where encoding
should continue. The encoder will encode the replacement and continue encoding
the original input at the specified position. Negative position values will be
treated as being relative to the end of the input string. If the resulting
position is out of bound an :exc:`IndexError` will be raised.
Decoding and translating works similar, except :exc:`UnicodeDecodeError` or
:exc:`UnicodeTranslateError` will be passed to the handler and that the
replacement from the error handler will be put into the output directly.
.. function:: lookup_error(name)
Return the error handler previously registered under the name *name*.
Raises a :exc:`LookupError` in case the handler cannot be found.
.. function:: strict_errors(exception)
Implements the ``strict`` error handling: each encoding or decoding error
raises a :exc:`UnicodeError`.
.. function:: replace_errors(exception)
Implements the ``replace`` error handling: malformed data is replaced with a
suitable replacement character such as ``'?'`` in bytestrings and
``'\ufffd'`` in Unicode strings.
.. function:: ignore_errors(exception)
Implements the ``ignore`` error handling: malformed data is ignored and
encoding or decoding is continued without further notice.
.. function:: xmlcharrefreplace_errors(exception)
Implements the ``xmlcharrefreplace`` error handling (for encoding only): the
unencodable character is replaced by an appropriate XML character reference.
.. function:: backslashreplace_errors(exception)
Implements the ``backslashreplace`` error handling (for encoding only): the
unencodable character is replaced by a backslashed escape sequence.
To simplify working with encoded files or stream, the module also defines these
utility functions:
.. function:: open(filename, mode[, encoding[, errors[, buffering]]])
Open an encoded file using the given *mode* and return a wrapped version
providing transparent encoding/decoding. The default file mode is ``'r'``
meaning to open the file in read mode.
.. note::
The wrapped version will only accept the object format defined by the codecs,
i.e. Unicode objects for most built-in codecs. Output is also codec-dependent
and will usually be Unicode as well.
.. note::
Files are always opened in binary mode, even if no binary mode was
specified. This is done to avoid data loss due to encodings using 8-bit
values. This means that no automatic conversion of ``'\n'`` is done
on reading and writing.
*encoding* specifies the encoding which is to be used for the file.
*errors* may be given to define the error handling. It defaults to ``'strict'``
which causes a :exc:`ValueError` to be raised in case an encoding error occurs.
*buffering* has the same meaning as for the built-in :func:`open` function. It
defaults to line buffered.
.. function:: EncodedFile(file, input[, output[, errors]])
Return a wrapped version of file which provides transparent encoding
translation.
Strings written to the wrapped file are interpreted according to the given
*input* encoding and then written to the original file as strings using the
*output* encoding. The intermediate encoding will usually be Unicode but depends
on the specified codecs.
If *output* is not given, it defaults to *input*.
*errors* may be given to define the error handling. It defaults to ``'strict'``,
which causes :exc:`ValueError` to be raised in case an encoding error occurs.
.. function:: iterencode(iterable, encoding[, errors])
Uses an incremental encoder to iteratively encode the input provided by
*iterable*. This function is a :term:`generator`. *errors* (as well as any
other keyword argument) is passed through to the incremental encoder.
.. versionadded:: 2.5
.. function:: iterdecode(iterable, encoding[, errors])
Uses an incremental decoder to iteratively decode the input provided by
*iterable*. This function is a :term:`generator`. *errors* (as well as any
other keyword argument) is passed through to the incremental decoder.
.. versionadded:: 2.5
The module also provides the following constants which are useful for reading
and writing to platform dependent files:
.. data:: BOM
BOM_BE
BOM_LE
BOM_UTF8
BOM_UTF16
BOM_UTF16_BE
BOM_UTF16_LE
BOM_UTF32
BOM_UTF32_BE
BOM_UTF32_LE
These constants define various encodings of the Unicode byte order mark (BOM)
used in UTF-16 and UTF-32 data streams to indicate the byte order used in the
stream or file and in UTF-8 as a Unicode signature. :const:`BOM_UTF16` is either
:const:`BOM_UTF16_BE` or :const:`BOM_UTF16_LE` depending on the platform's
native byte order, :const:`BOM` is an alias for :const:`BOM_UTF16`,
:const:`BOM_LE` for :const:`BOM_UTF16_LE` and :const:`BOM_BE` for
:const:`BOM_UTF16_BE`. The others represent the BOM in UTF-8 and UTF-32
encodings.
.. _codec-base-classes:
Codec Base Classes
------------------
The :mod:`codecs` module defines a set of base classes which define the
interface and can also be used to easily write your own codecs for use in
Python.
Each codec has to define four interfaces to make it usable as codec in Python:
stateless encoder, stateless decoder, stream reader and stream writer. The
stream reader and writers typically reuse the stateless encoder/decoder to
implement the file protocols.
The :class:`Codec` class defines the interface for stateless encoders/decoders.
To simplify and standardize error handling, the :meth:`~Codec.encode` and
:meth:`~Codec.decode` methods may implement different error handling schemes by
providing the *errors* string argument. The following string values are defined
and implemented by all standard Python codecs:
.. tabularcolumns:: |l|L|
+-------------------------+-----------------------------------------------+
| Value | Meaning |
+=========================+===============================================+
| ``'strict'`` | Raise :exc:`UnicodeError` (or a subclass); |
| | this is the default. |
+-------------------------+-----------------------------------------------+
| ``'ignore'`` | Ignore the character and continue with the |
| | next. |
+-------------------------+-----------------------------------------------+
| ``'replace'`` | Replace with a suitable replacement |
| | character; Python will use the official |
| | U+FFFD REPLACEMENT CHARACTER for the built-in |
| | Unicode codecs on decoding and '?' on |
| | encoding. |
+-------------------------+-----------------------------------------------+
| ``'xmlcharrefreplace'`` | Replace with the appropriate XML character |
| | reference (only for encoding). |
+-------------------------+-----------------------------------------------+
| ``'backslashreplace'`` | Replace with backslashed escape sequences |
| | (only for encoding). |
+-------------------------+-----------------------------------------------+
The set of allowed values can be extended via :meth:`register_error`.
.. _codec-objects:
Codec Objects
^^^^^^^^^^^^^
The :class:`Codec` class defines these methods which also define the function
interfaces of the stateless encoder and decoder:
.. method:: Codec.encode(input[, errors])
Encodes the object *input* and returns a tuple (output object, length consumed).
While codecs are not restricted to use with Unicode, in a Unicode context,
encoding converts a Unicode object to a plain string using a particular
character set encoding (e.g., ``cp1252`` or ``iso-8859-1``).
*errors* defines the error handling to apply. It defaults to ``'strict'``
handling.
The method may not store state in the :class:`Codec` instance. Use
:class:`StreamWriter` for codecs which have to keep state in order to make
encoding efficient.
The encoder must be able to handle zero length input and return an empty object
of the output object type in this situation.
.. method:: Codec.decode(input[, errors])
Decodes the object *input* and returns a tuple (output object, length consumed).
In a Unicode context, decoding converts a plain string encoded using a
particular character set encoding to a Unicode object.
*input* must be an object which provides the ``bf_getreadbuf`` buffer slot.
Python strings, buffer objects and memory mapped files are examples of objects
providing this slot.
*errors* defines the error handling to apply. It defaults to ``'strict'``
handling.
The method may not store state in the :class:`Codec` instance. Use
:class:`StreamReader` for codecs which have to keep state in order to make
decoding efficient.
The decoder must be able to handle zero length input and return an empty object
of the output object type in this situation.
The :class:`IncrementalEncoder` and :class:`IncrementalDecoder` classes provide
the basic interface for incremental encoding and decoding. Encoding/decoding the
input isn't done with one call to the stateless encoder/decoder function, but
with multiple calls to the
:meth:`~IncrementalEncoder.encode`/:meth:`~IncrementalDecoder.decode` method of
the incremental encoder/decoder. The incremental encoder/decoder keeps track of
the encoding/decoding process during method calls.
The joined output of calls to the
:meth:`~IncrementalEncoder.encode`/:meth:`~IncrementalDecoder.decode` method is
the same as if all the single inputs were joined into one, and this input was
encoded/decoded with the stateless encoder/decoder.
.. _incremental-encoder-objects:
IncrementalEncoder Objects
^^^^^^^^^^^^^^^^^^^^^^^^^^
.. versionadded:: 2.5
The :class:`IncrementalEncoder` class is used for encoding an input in multiple
steps. It defines the following methods which every incremental encoder must
define in order to be compatible with the Python codec registry.
.. class:: IncrementalEncoder([errors])
Constructor for an :class:`IncrementalEncoder` instance.
All incremental encoders must provide this constructor interface. They are free
to add additional keyword arguments, but only the ones defined here are used by
the Python codec registry.
The :class:`IncrementalEncoder` may implement different error handling schemes
by providing the *errors* keyword argument. These parameters are predefined:
* ``'strict'`` Raise :exc:`ValueError` (or a subclass); this is the default.
* ``'ignore'`` Ignore the character and continue with the next.
* ``'replace'`` Replace with a suitable replacement character
* ``'xmlcharrefreplace'`` Replace with the appropriate XML character reference
* ``'backslashreplace'`` Replace with backslashed escape sequences.
The *errors* argument will be assigned to an attribute of the same name.
Assigning to this attribute makes it possible to switch between different error
handling strategies during the lifetime of the :class:`IncrementalEncoder`
object.
The set of allowed values for the *errors* argument can be extended with
:func:`register_error`.
.. method:: encode(object[, final])
Encodes *object* (taking the current state of the encoder into account)
and returns the resulting encoded object. If this is the last call to
:meth:`encode` *final* must be true (the default is false).
.. method:: reset()
Reset the encoder to the initial state.
.. _incremental-decoder-objects:
IncrementalDecoder Objects
^^^^^^^^^^^^^^^^^^^^^^^^^^
The :class:`IncrementalDecoder` class is used for decoding an input in multiple
steps. It defines the following methods which every incremental decoder must
define in order to be compatible with the Python codec registry.
.. class:: IncrementalDecoder([errors])
Constructor for an :class:`IncrementalDecoder` instance.
All incremental decoders must provide this constructor interface. They are free
to add additional keyword arguments, but only the ones defined here are used by
the Python codec registry.
The :class:`IncrementalDecoder` may implement different error handling schemes
by providing the *errors* keyword argument. These parameters are predefined:
* ``'strict'`` Raise :exc:`ValueError` (or a subclass); this is the default.
* ``'ignore'`` Ignore the character and continue with the next.
* ``'replace'`` Replace with a suitable replacement character.
The *errors* argument will be assigned to an attribute of the same name.
Assigning to this attribute makes it possible to switch between different error
handling strategies during the lifetime of the :class:`IncrementalDecoder`
object.
The set of allowed values for the *errors* argument can be extended with
:func:`register_error`.
.. method:: decode(object[, final])
Decodes *object* (taking the current state of the decoder into account)
and returns the resulting decoded object. If this is the last call to
:meth:`decode` *final* must be true (the default is false). If *final* is
true the decoder must decode the input completely and must flush all
buffers. If this isn't possible (e.g. because of incomplete byte sequences
at the end of the input) it must initiate error handling just like in the
stateless case (which might raise an exception).
.. method:: reset()
Reset the decoder to the initial state.
The :class:`StreamWriter` and :class:`StreamReader` classes provide generic
working interfaces which can be used to implement new encoding submodules very
easily. See :mod:`encodings.utf_8` for an example of how this is done.
.. _stream-writer-objects:
StreamWriter Objects
^^^^^^^^^^^^^^^^^^^^
The :class:`StreamWriter` class is a subclass of :class:`Codec` and defines the
following methods which every stream writer must define in order to be
compatible with the Python codec registry.
.. class:: StreamWriter(stream[, errors])
Constructor for a :class:`StreamWriter` instance.
All stream writers must provide this constructor interface. They are free to add
additional keyword arguments, but only the ones defined here are used by the
Python codec registry.
*stream* must be a file-like object open for writing binary data.
The :class:`StreamWriter` may implement different error handling schemes by
providing the *errors* keyword argument. These parameters are predefined:
* ``'strict'`` Raise :exc:`ValueError` (or a subclass); this is the default.
* ``'ignore'`` Ignore the character and continue with the next.
* ``'replace'`` Replace with a suitable replacement character
* ``'xmlcharrefreplace'`` Replace with the appropriate XML character reference
* ``'backslashreplace'`` Replace with backslashed escape sequences.
The *errors* argument will be assigned to an attribute of the same name.
Assigning to this attribute makes it possible to switch between different error
handling strategies during the lifetime of the :class:`StreamWriter` object.
The set of allowed values for the *errors* argument can be extended with
:func:`register_error`.
.. method:: write(object)
Writes the object's contents encoded to the stream.
.. method:: writelines(list)
Writes the concatenated list of strings to the stream (possibly by reusing
the :meth:`write` method).
.. method:: reset()
Flushes and resets the codec buffers used for keeping state.
Calling this method should ensure that the data on the output is put into
a clean state that allows appending of new fresh data without having to
rescan the whole stream to recover state.
In addition to the above methods, the :class:`StreamWriter` must also inherit
all other methods and attributes from the underlying stream.
.. _stream-reader-objects:
StreamReader Objects
^^^^^^^^^^^^^^^^^^^^
The :class:`StreamReader` class is a subclass of :class:`Codec` and defines the
following methods which every stream reader must define in order to be
compatible with the Python codec registry.
.. class:: StreamReader(stream[, errors])
Constructor for a :class:`StreamReader` instance.
All stream readers must provide this constructor interface. They are free to add
additional keyword arguments, but only the ones defined here are used by the
Python codec registry.
*stream* must be a file-like object open for reading (binary) data.
The :class:`StreamReader` may implement different error handling schemes by
providing the *errors* keyword argument. These parameters are defined:
* ``'strict'`` Raise :exc:`ValueError` (or a subclass); this is the default.
* ``'ignore'`` Ignore the character and continue with the next.
* ``'replace'`` Replace with a suitable replacement character.
The *errors* argument will be assigned to an attribute of the same name.
Assigning to this attribute makes it possible to switch between different error
handling strategies during the lifetime of the :class:`StreamReader` object.
The set of allowed values for the *errors* argument can be extended with
:func:`register_error`.
.. method:: read([size[, chars, [firstline]]])
Decodes data from the stream and returns the resulting object.
*chars* indicates the number of characters to read from the
stream. :func:`read` will never return more than *chars* characters, but
it might return less, if there are not enough characters available.
*size* indicates the approximate maximum number of bytes to read from the
stream for decoding purposes. The decoder can modify this setting as
appropriate. The default value -1 indicates to read and decode as much as
possible. *size* is intended to prevent having to decode huge files in
one step.
*firstline* indicates that it would be sufficient to only return the first
line, if there are decoding errors on later lines.
The method should use a greedy read strategy meaning that it should read
as much data as is allowed within the definition of the encoding and the
given size, e.g. if optional encoding endings or state markers are
available on the stream, these should be read too.
.. versionchanged:: 2.4
*chars* argument added.
.. versionchanged:: 2.4.2
*firstline* argument added.
.. method:: readline([size[, keepends]])
Read one line from the input stream and return the decoded data.
*size*, if given, is passed as size argument to the stream's
:meth:`read` method.
If *keepends* is false line-endings will be stripped from the lines
returned.
.. versionchanged:: 2.4
*keepends* argument added.
.. method:: readlines([sizehint[, keepends]])
Read all lines available on the input stream and return them as a list of
lines.
Line-endings are implemented using the codec's decoder method and are
included in the list entries if *keepends* is true.
*sizehint*, if given, is passed as the *size* argument to the stream's
:meth:`read` method.
.. method:: reset()
Resets the codec buffers used for keeping state.
Note that no stream repositioning should take place. This method is
primarily intended to be able to recover from decoding errors.
In addition to the above methods, the :class:`StreamReader` must also inherit
all other methods and attributes from the underlying stream.
The next two base classes are included for convenience. They are not needed by
the codec registry, but may provide useful in practice.
.. _stream-reader-writer:
StreamReaderWriter Objects
^^^^^^^^^^^^^^^^^^^^^^^^^^
The :class:`StreamReaderWriter` allows wrapping streams which work in both read
and write modes.
The design is such that one can use the factory functions returned by the
:func:`lookup` function to construct the instance.
.. class:: StreamReaderWriter(stream, Reader, Writer, errors)
Creates a :class:`StreamReaderWriter` instance. *stream* must be a file-like
object. *Reader* and *Writer* must be factory functions or classes providing the
:class:`StreamReader` and :class:`StreamWriter` interface resp. Error handling
is done in the same way as defined for the stream readers and writers.
:class:`StreamReaderWriter` instances define the combined interfaces of
:class:`StreamReader` and :class:`StreamWriter` classes. They inherit all other
methods and attributes from the underlying stream.
.. _stream-recoder-objects:
StreamRecoder Objects
^^^^^^^^^^^^^^^^^^^^^
The :class:`StreamRecoder` provide a frontend - backend view of encoding data
which is sometimes useful when dealing with different encoding environments.
The design is such that one can use the factory functions returned by the
:func:`lookup` function to construct the instance.
.. class:: StreamRecoder(stream, encode, decode, Reader, Writer, errors)
Creates a :class:`StreamRecoder` instance which implements a two-way conversion:
*encode* and *decode* work on the frontend (the input to :meth:`read` and output
of :meth:`write`) while *Reader* and *Writer* work on the backend (reading and
writing to the stream).
You can use these objects to do transparent direct recodings from e.g. Latin-1
to UTF-8 and back.
*stream* must be a file-like object.
*encode*, *decode* must adhere to the :class:`Codec` interface. *Reader*,
*Writer* must be factory functions or classes providing objects of the
:class:`StreamReader` and :class:`StreamWriter` interface respectively.
*encode* and *decode* are needed for the frontend translation, *Reader* and
*Writer* for the backend translation. The intermediate format used is
determined by the two sets of codecs, e.g. the Unicode codecs will use Unicode
as the intermediate encoding.
Error handling is done in the same way as defined for the stream readers and
writers.
:class:`StreamRecoder` instances define the combined interfaces of
:class:`StreamReader` and :class:`StreamWriter` classes. They inherit all other
methods and attributes from the underlying stream.
.. _encodings-overview:
Encodings and Unicode
---------------------
Unicode strings are stored internally as sequences of code points (to be precise
as :c:type:`Py_UNICODE` arrays). Depending on the way Python is compiled (either
via ``--enable-unicode=ucs2`` or ``--enable-unicode=ucs4``, with the
former being the default) :c:type:`Py_UNICODE` is either a 16-bit or 32-bit data
type. Once a Unicode object is used outside of CPU and memory, CPU endianness
and how these arrays are stored as bytes become an issue. Transforming a
unicode object into a sequence of bytes is called encoding and recreating the
unicode object from the sequence of bytes is known as decoding. There are many
different methods for how this transformation can be done (these methods are
also called encodings). The simplest method is to map the code points 0--255 to
the bytes ``0x0``--``0xff``. This means that a unicode object that contains
code points above ``U+00FF`` can't be encoded with this method (which is called
``'latin-1'`` or ``'iso-8859-1'``). :func:`unicode.encode` will raise a
:exc:`UnicodeEncodeError` that looks like this: ``UnicodeEncodeError: 'latin-1'
codec can't encode character u'\u1234' in position 3: ordinal not in
range(256)``.
There's another group of encodings (the so called charmap encodings) that choose
a different subset of all unicode code points and how these code points are
mapped to the bytes ``0x0``--``0xff``. To see how this is done simply open
e.g. :file:`encodings/cp1252.py` (which is an encoding that is used primarily on
Windows). There's a string constant with 256 characters that shows you which
character is mapped to which byte value.
All of these encodings can only encode 256 of the 1114112 code points
defined in unicode. A simple and straightforward way that can store each Unicode
code point, is to store each code point as four consecutive bytes. There are two
possibilities: store the bytes in big endian or in little endian order. These
two encodings are called ``UTF-32-BE`` and ``UTF-32-LE`` respectively. Their
disadvantage is that if e.g. you use ``UTF-32-BE`` on a little endian machine you
will always have to swap bytes on encoding and decoding. ``UTF-32`` avoids this
problem: bytes will always be in natural endianness. When these bytes are read
by a CPU with a different endianness, then bytes have to be swapped though. To
be able to detect the endianness of a ``UTF-16`` or ``UTF-32`` byte sequence,
there's the so called BOM ("Byte Order Mark"). This is the Unicode character
``U+FEFF``. This character can be prepended to every ``UTF-16`` or ``UTF-32``
byte sequence. The byte swapped version of this character (``0xFFFE``) is an
illegal character that may not appear in a Unicode text. So when the
first character in an ``UTF-16`` or ``UTF-32`` byte sequence
appears to be a ``U+FFFE`` the bytes have to be swapped on decoding.
Unfortunately the character ``U+FEFF`` had a second purpose as
a ``ZERO WIDTH NO-BREAK SPACE``: a character that has no width and doesn't allow
a word to be split. It can e.g. be used to give hints to a ligature algorithm.
With Unicode 4.0 using ``U+FEFF`` as a ``ZERO WIDTH NO-BREAK SPACE`` has been
deprecated (with ``U+2060`` (``WORD JOINER``) assuming this role). Nevertheless
Unicode software still must be able to handle ``U+FEFF`` in both roles: as a BOM
it's a device to determine the storage layout of the encoded bytes, and vanishes
once the byte sequence has been decoded into a Unicode string; as a ``ZERO WIDTH
NO-BREAK SPACE`` it's a normal character that will be decoded like any other.
There's another encoding that is able to encoding the full range of Unicode
characters: UTF-8. UTF-8 is an 8-bit encoding, which means there are no issues
with byte order in UTF-8. Each byte in a UTF-8 byte sequence consists of two
parts: marker bits (the most significant bits) and payload bits. The marker bits
are a sequence of zero to four ``1`` bits followed by a ``0`` bit. Unicode characters are
encoded like this (with x being payload bits, which when concatenated give the
Unicode character):
+-----------------------------------+----------------------------------------------+
| Range | Encoding |
+===================================+==============================================+
| ``U-00000000`` ... ``U-0000007F`` | 0xxxxxxx |
+-----------------------------------+----------------------------------------------+
| ``U-00000080`` ... ``U-000007FF`` | 110xxxxx 10xxxxxx |
+-----------------------------------+----------------------------------------------+
| ``U-00000800`` ... ``U-0000FFFF`` | 1110xxxx 10xxxxxx 10xxxxxx |
+-----------------------------------+----------------------------------------------+
| ``U-00010000`` ... ``U-0010FFFF`` | 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx |
+-----------------------------------+----------------------------------------------+
The least significant bit of the Unicode character is the rightmost x bit.
As UTF-8 is an 8-bit encoding no BOM is required and any ``U+FEFF`` character in
the decoded Unicode string (even if it's the first character) is treated as a
``ZERO WIDTH NO-BREAK SPACE``.
Without external information it's impossible to reliably determine which
encoding was used for encoding a Unicode string. Each charmap encoding can
decode any random byte sequence. However that's not possible with UTF-8, as
UTF-8 byte sequences have a structure that doesn't allow arbitrary byte
sequences. To increase the reliability with which a UTF-8 encoding can be
detected, Microsoft invented a variant of UTF-8 (that Python 2.5 calls
``"utf-8-sig"``) for its Notepad program: Before any of the Unicode characters
is written to the file, a UTF-8 encoded BOM (which looks like this as a byte
sequence: ``0xef``, ``0xbb``, ``0xbf``) is written. As it's rather improbable
that any charmap encoded file starts with these byte values (which would e.g.
map to
| LATIN SMALL LETTER I WITH DIAERESIS
| RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK
| INVERTED QUESTION MARK
in iso-8859-1), this increases the probability that a ``utf-8-sig`` encoding can be
correctly guessed from the byte sequence. So here the BOM is not used to be able
to determine the byte order used for generating the byte sequence, but as a
signature that helps in guessing the encoding. On encoding the utf-8-sig codec
will write ``0xef``, ``0xbb``, ``0xbf`` as the first three bytes to the file. On
decoding ``utf-8-sig`` will skip those three bytes if they appear as the first
three bytes in the file. In UTF-8, the use of the BOM is discouraged and
should generally be avoided.
.. _standard-encodings:
Standard Encodings
------------------
Python comes with a number of codecs built-in, either implemented as C functions
or with dictionaries as mapping tables. The following table lists the codecs by
name, together with a few common aliases, and the languages for which the
encoding is likely used. Neither the list of aliases nor the list of languages
is meant to be exhaustive. Notice that spelling alternatives that only differ in
case or use a hyphen instead of an underscore are also valid aliases; therefore,
e.g. ``'utf-8'`` is a valid alias for the ``'utf_8'`` codec.
Many of the character sets support the same languages. They vary in individual
characters (e.g. whether the EURO SIGN is supported or not), and in the
assignment of characters to code positions. For the European languages in
particular, the following variants typically exist:
* an ISO 8859 codeset
* a Microsoft Windows code page, which is typically derived from an 8859 codeset,
but replaces control characters with additional graphic characters
* an IBM EBCDIC code page
* an IBM PC code page, which is ASCII compatible
.. tabularcolumns:: |l|p{0.3\linewidth}|p{0.3\linewidth}|
+-----------------+--------------------------------+--------------------------------+
| Codec | Aliases | Languages |
+=================+================================+================================+
| ascii | 646, us-ascii | English |
+-----------------+--------------------------------+--------------------------------+
| big5 | big5-tw, csbig5 | Traditional Chinese |
+-----------------+--------------------------------+--------------------------------+
| big5hkscs | big5-hkscs, hkscs | Traditional Chinese |
+-----------------+--------------------------------+--------------------------------+
| cp037 | IBM037, IBM039 | English |
+-----------------+--------------------------------+--------------------------------+
| cp424 | EBCDIC-CP-HE, IBM424 | Hebrew |
+-----------------+--------------------------------+--------------------------------+
| cp437 | 437, IBM437 | English |
+-----------------+--------------------------------+--------------------------------+
| cp500 | EBCDIC-CP-BE, EBCDIC-CP-CH, | Western Europe |
| | IBM500 | |
+-----------------+--------------------------------+--------------------------------+
| cp720 | | Arabic |
+-----------------+--------------------------------+--------------------------------+
| cp737 | | Greek |
+-----------------+--------------------------------+--------------------------------+
| cp775 | IBM775 | Baltic languages |
+-----------------+--------------------------------+--------------------------------+
| cp850 | 850, IBM850 | Western Europe |
+-----------------+--------------------------------+--------------------------------+
| cp852 | 852, IBM852 | Central and Eastern Europe |
+-----------------+--------------------------------+--------------------------------+
| cp855 | 855, IBM855 | Bulgarian, Byelorussian, |
| | | Macedonian, Russian, Serbian |
+-----------------+--------------------------------+--------------------------------+
| cp856 | | Hebrew |
+-----------------+--------------------------------+--------------------------------+
| cp857 | 857, IBM857 | Turkish |
+-----------------+--------------------------------+--------------------------------+
| cp858 | 858, IBM858 | Western Europe |
+-----------------+--------------------------------+--------------------------------+
| cp860 | 860, IBM860 | Portuguese |
+-----------------+--------------------------------+--------------------------------+
| cp861 | 861, CP-IS, IBM861 | Icelandic |
+-----------------+--------------------------------+--------------------------------+
| cp862 | 862, IBM862 | Hebrew |
+-----------------+--------------------------------+--------------------------------+
| cp863 | 863, IBM863 | Canadian |
+-----------------+--------------------------------+--------------------------------+
| cp864 | IBM864 | Arabic |
+-----------------+--------------------------------+--------------------------------+
| cp865 | 865, IBM865 | Danish, Norwegian |
+-----------------+--------------------------------+--------------------------------+
| cp866 | 866, IBM866 | Russian |
+-----------------+--------------------------------+--------------------------------+
| cp869 | 869, CP-GR, IBM869 | Greek |
+-----------------+--------------------------------+--------------------------------+
| cp874 | | Thai |
+-----------------+--------------------------------+--------------------------------+
| cp875 | | Greek |
+-----------------+--------------------------------+--------------------------------+
| cp932 | 932, ms932, mskanji, ms-kanji | Japanese |
+-----------------+--------------------------------+--------------------------------+
| cp949 | 949, ms949, uhc | Korean |
+-----------------+--------------------------------+--------------------------------+
| cp950 | 950, ms950 | Traditional Chinese |
+-----------------+--------------------------------+--------------------------------+
| cp1006 | | Urdu |
+-----------------+--------------------------------+--------------------------------+
| cp1026 | ibm1026 | Turkish |
+-----------------+--------------------------------+--------------------------------+
| cp1140 | ibm1140 | Western Europe |
+-----------------+--------------------------------+--------------------------------+
| cp1250 | windows-1250 | Central and Eastern Europe |
+-----------------+--------------------------------+--------------------------------+
| cp1251 | windows-1251 | Bulgarian, Byelorussian, |
| | | Macedonian, Russian, Serbian |
+-----------------+--------------------------------+--------------------------------+
| cp1252 | windows-1252 | Western Europe |
+-----------------+--------------------------------+--------------------------------+
| cp1253 | windows-1253 | Greek |
+-----------------+--------------------------------+--------------------------------+
| cp1254 | windows-1254 | Turkish |
+-----------------+--------------------------------+--------------------------------+
| cp1255 | windows-1255 | Hebrew |
+-----------------+--------------------------------+--------------------------------+
| cp1256 | windows-1256 | Arabic |
+-----------------+--------------------------------+--------------------------------+
| cp1257 | windows-1257 | Baltic languages |
+-----------------+--------------------------------+--------------------------------+
| cp1258 | windows-1258 | Vietnamese |
+-----------------+--------------------------------+--------------------------------+
| euc_jp | eucjp, ujis, u-jis | Japanese |
+-----------------+--------------------------------+--------------------------------+
| euc_jis_2004 | jisx0213, eucjis2004 | Japanese |
+-----------------+--------------------------------+--------------------------------+
| euc_jisx0213 | eucjisx0213 | Japanese |
+-----------------+--------------------------------+--------------------------------+
| euc_kr | euckr, korean, ksc5601, | Korean |
| | ks_c-5601, ks_c-5601-1987, | |
| | ksx1001, ks_x-1001 | |
+-----------------+--------------------------------+--------------------------------+
| gb2312 | chinese, csiso58gb231280, euc- | Simplified Chinese |
| | cn, euccn, eucgb2312-cn, | |
| | gb2312-1980, gb2312-80, iso- | |
| | ir-58 | |
+-----------------+--------------------------------+--------------------------------+
| gbk | 936, cp936, ms936 | Unified Chinese |
+-----------------+--------------------------------+--------------------------------+
| gb18030 | gb18030-2000 | Unified Chinese |
+-----------------+--------------------------------+--------------------------------+
| hz | hzgb, hz-gb, hz-gb-2312 | Simplified Chinese |
+-----------------+--------------------------------+--------------------------------+
| iso2022_jp | csiso2022jp, iso2022jp, | Japanese |
| | iso-2022-jp | |
+-----------------+--------------------------------+--------------------------------+
| iso2022_jp_1 | iso2022jp-1, iso-2022-jp-1 | Japanese |
+-----------------+--------------------------------+--------------------------------+
| iso2022_jp_2 | iso2022jp-2, iso-2022-jp-2 | Japanese, Korean, Simplified |
| | | Chinese, Western Europe, Greek |
+-----------------+--------------------------------+--------------------------------+
| iso2022_jp_2004 | iso2022jp-2004, | Japanese |
| | iso-2022-jp-2004 | |
+-----------------+--------------------------------+--------------------------------+
| iso2022_jp_3 | iso2022jp-3, iso-2022-jp-3 | Japanese |
+-----------------+--------------------------------+--------------------------------+
| iso2022_jp_ext | iso2022jp-ext, iso-2022-jp-ext | Japanese |
+-----------------+--------------------------------+--------------------------------+
| iso2022_kr | csiso2022kr, iso2022kr, | Korean |
| | iso-2022-kr | |
+-----------------+--------------------------------+--------------------------------+
| latin_1 | iso-8859-1, iso8859-1, 8859, | West Europe |
| | cp819, latin, latin1, L1 | |
+-----------------+--------------------------------+--------------------------------+
| iso8859_2 | iso-8859-2, latin2, L2 | Central and Eastern Europe |
+-----------------+--------------------------------+--------------------------------+
| iso8859_3 | iso-8859-3, latin3, L3 | Esperanto, Maltese |
+-----------------+--------------------------------+--------------------------------+
| iso8859_4 | iso-8859-4, latin4, L4 | Baltic languages |
+-----------------+--------------------------------+--------------------------------+
| iso8859_5 | iso-8859-5, cyrillic | Bulgarian, Byelorussian, |
| | | Macedonian, Russian, Serbian |
+-----------------+--------------------------------+--------------------------------+
| iso8859_6 | iso-8859-6, arabic | Arabic |
+-----------------+--------------------------------+--------------------------------+
| iso8859_7 | iso-8859-7, greek, greek8 | Greek |
+-----------------+--------------------------------+--------------------------------+
| iso8859_8 | iso-8859-8, hebrew | Hebrew |
+-----------------+--------------------------------+--------------------------------+
| iso8859_9 | iso-8859-9, latin5, L5 | Turkish |
+-----------------+--------------------------------+--------------------------------+
| iso8859_10 | iso-8859-10, latin6, L6 | Nordic languages |
+-----------------+--------------------------------+--------------------------------+
| iso8859_11 | iso-8859-11, thai | Thai languages |
+-----------------+--------------------------------+--------------------------------+
| iso8859_13 | iso-8859-13, latin7, L7 | Baltic languages |
+-----------------+--------------------------------+--------------------------------+
| iso8859_14 | iso-8859-14, latin8, L8 | Celtic languages |
+-----------------+--------------------------------+--------------------------------+
| iso8859_15 | iso-8859-15, latin9, L9 | Western Europe |
+-----------------+--------------------------------+--------------------------------+
| iso8859_16 | iso-8859-16, latin10, L10 | South-Eastern Europe |
+-----------------+--------------------------------+--------------------------------+
| johab | cp1361, ms1361 | Korean |
+-----------------+--------------------------------+--------------------------------+
| koi8_r | | Russian |
+-----------------+--------------------------------+--------------------------------+
| koi8_u | | Ukrainian |
+-----------------+--------------------------------+--------------------------------+
| mac_cyrillic | maccyrillic | Bulgarian, Byelorussian, |
| | | Macedonian, Russian, Serbian |
+-----------------+--------------------------------+--------------------------------+
| mac_greek | macgreek | Greek |
+-----------------+--------------------------------+--------------------------------+
| mac_iceland | maciceland | Icelandic |
+-----------------+--------------------------------+--------------------------------+
| mac_latin2 | maclatin2, maccentraleurope | Central and Eastern Europe |
+-----------------+--------------------------------+--------------------------------+
| mac_roman | macroman | Western Europe |
+-----------------+--------------------------------+--------------------------------+
| mac_turkish | macturkish | Turkish |
+-----------------+--------------------------------+--------------------------------+
| ptcp154 | csptcp154, pt154, cp154, | Kazakh |
| | cyrillic-asian | |
+-----------------+--------------------------------+--------------------------------+
| shift_jis | csshiftjis, shiftjis, sjis, | Japanese |
| | s_jis | |
+-----------------+--------------------------------+--------------------------------+
| shift_jis_2004 | shiftjis2004, sjis_2004, | Japanese |
| | sjis2004 | |
+-----------------+--------------------------------+--------------------------------+
| shift_jisx0213 | shiftjisx0213, sjisx0213, | Japanese |
| | s_jisx0213 | |
+-----------------+--------------------------------+--------------------------------+
| utf_32 | U32, utf32 | all languages |
+-----------------+--------------------------------+--------------------------------+
| utf_32_be | UTF-32BE | all languages |
+-----------------+--------------------------------+--------------------------------+
| utf_32_le | UTF-32LE | all languages |
+-----------------+--------------------------------+--------------------------------+
| utf_16 | U16, utf16 | all languages |
+-----------------+--------------------------------+--------------------------------+
| utf_16_be | UTF-16BE | all languages (BMP only) |
+-----------------+--------------------------------+--------------------------------+
| utf_16_le | UTF-16LE | all languages (BMP only) |
+-----------------+--------------------------------+--------------------------------+
| utf_7 | U7, unicode-1-1-utf-7 | all languages |
+-----------------+--------------------------------+--------------------------------+
| utf_8 | U8, UTF, utf8 | all languages |
+-----------------+--------------------------------+--------------------------------+
| utf_8_sig | | all languages |
+-----------------+--------------------------------+--------------------------------+
Python Specific Encodings
-------------------------
A number of predefined codecs are specific to Python, so their codec names have
no meaning outside Python. These are listed in the tables below based on the
expected input and output types (note that while text encodings are the most
common use case for codecs, the underlying codec infrastructure supports
arbitrary data transforms rather than just text encodings). For asymmetric
codecs, the stated purpose describes the encoding direction.
The following codecs provide unicode-to-str encoding [#encoding-note]_ and
str-to-unicode decoding [#decoding-note]_, similar to the Unicode text
encodings.
.. tabularcolumns:: |l|L|L|
+--------------------+---------------------------+---------------------------+
| Codec | Aliases | Purpose |
+====================+===========================+===========================+
| idna | | Implements :rfc:`3490`, |
| | | see also |
| | | :mod:`encodings.idna` |
+--------------------+---------------------------+---------------------------+
| mbcs | dbcs | Windows only: Encode |
| | | operand according to the |
| | | ANSI codepage (CP_ACP) |
+--------------------+---------------------------+---------------------------+
| palmos | | Encoding of PalmOS 3.5 |
+--------------------+---------------------------+---------------------------+
| punycode | | Implements :rfc:`3492` |
+--------------------+---------------------------+---------------------------+
| raw_unicode_escape | | Produce a string that is |
| | | suitable as raw Unicode |
| | | literal in Python source |
| | | code |
+--------------------+---------------------------+---------------------------+
| rot_13 | rot13 | Returns the Caesar-cypher |
| | | encryption of the operand |
+--------------------+---------------------------+---------------------------+
| undefined | | Raise an exception for |
| | | all conversions. Can be |
| | | used as the system |
| | | encoding if no automatic |
| | | :term:`coercion` between |
| | | byte and Unicode strings |
| | | is desired. |
+--------------------+---------------------------+---------------------------+
| unicode_escape | | Produce a string that is |
| | | suitable as Unicode |
| | | literal in Python source |
| | | code |
+--------------------+---------------------------+---------------------------+
| unicode_internal | | Return the internal |
| | | representation of the |
| | | operand |
+--------------------+---------------------------+---------------------------+
.. versionadded:: 2.3
The ``idna`` and ``punycode`` encodings.
The following codecs provide str-to-str encoding and decoding
[#decoding-note]_.
.. tabularcolumns:: |l|L|L|L|
+--------------------+---------------------------+---------------------------+------------------------------+
| Codec | Aliases | Purpose | Encoder/decoder |
+====================+===========================+===========================+==============================+
| base64_codec | base64, base-64 | Convert operand to | :meth:`base64.encodestring`, |
| | | multiline MIME base64 (the| :meth:`base64.decodestring` |
| | | result always includes a | |
| | | trailing ``'\n'``) | |
+--------------------+---------------------------+---------------------------+------------------------------+
| bz2_codec | bz2 | Compress the operand | :meth:`bz2.compress`, |
| | | using bz2 | :meth:`bz2.decompress` |
+--------------------+---------------------------+---------------------------+------------------------------+
| hex_codec | hex | Convert operand to | :meth:`binascii.b2a_hex`, |
| | | hexadecimal | :meth:`binascii.a2b_hex` |
| | | representation, with two | |
| | | digits per byte | |
+--------------------+---------------------------+---------------------------+------------------------------+
| quopri_codec | quopri, quoted-printable, | Convert operand to MIME | :meth:`quopri.encode` with |
| | quotedprintable | quoted printable | ``quotetabs=True``, |
| | | | :meth:`quopri.decode` |
+--------------------+---------------------------+---------------------------+------------------------------+
| string_escape | | Produce a string that is | |
| | | suitable as string | |
| | | literal in Python source | |
| | | code | |
+--------------------+---------------------------+---------------------------+------------------------------+
| uu_codec | uu | Convert the operand using | :meth:`uu.encode`, |
| | | uuencode | :meth:`uu.decode` |
+--------------------+---------------------------+---------------------------+------------------------------+
| zlib_codec | zip, zlib | Compress the operand | :meth:`zlib.compress`, |
| | | using gzip | :meth:`zlib.decompress` |
+--------------------+---------------------------+---------------------------+------------------------------+
.. [#encoding-note] str objects are also accepted as input in place of unicode
objects. They are implicitly converted to unicode by decoding them using
the default encoding. If this conversion fails, it may lead to encoding
operations raising :exc:`UnicodeDecodeError`.
.. [#decoding-note] unicode objects are also accepted as input in place of str
objects. They are implicitly converted to str by encoding them using the
default encoding. If this conversion fails, it may lead to decoding
operations raising :exc:`UnicodeEncodeError`.
:mod:`encodings.idna` --- Internationalized Domain Names in Applications
------------------------------------------------------------------------
.. module:: encodings.idna
:synopsis: Internationalized Domain Names implementation
.. moduleauthor:: Martin v. Löwis
.. versionadded:: 2.3
This module implements :rfc:`3490` (Internationalized Domain Names in
Applications) and :rfc:`3492` (Nameprep: A Stringprep Profile for
Internationalized Domain Names (IDN)). It builds upon the ``punycode`` encoding
and :mod:`stringprep`.
These RFCs together define a protocol to support non-ASCII characters in domain
names. A domain name containing non-ASCII characters (such as
``www.Alliancefrançaise.nu``) is converted into an ASCII-compatible encoding
(ACE, such as ``www.xn--alliancefranaise-npb.nu``). The ACE form of the domain
name is then used in all places where arbitrary characters are not allowed by
the protocol, such as DNS queries, HTTP :mailheader:`Host` fields, and so
on. This conversion is carried out in the application; if possible invisible to
the user: The application should transparently convert Unicode domain labels to
IDNA on the wire, and convert back ACE labels to Unicode before presenting them
to the user.
Python supports this conversion in several ways: the ``idna`` codec performs
conversion between Unicode and ACE, separating an input string into labels
based on the separator characters defined in `section 3.1`_ (1) of :rfc:`3490`
and converting each label to ACE as required, and conversely separating an input
byte string into labels based on the ``.`` separator and converting any ACE
labels found into unicode. Furthermore, the :mod:`socket` module
transparently converts Unicode host names to ACE, so that applications need not
be concerned about converting host names themselves when they pass them to the
socket module. On top of that, modules that have host names as function
parameters, such as :mod:`httplib` and :mod:`ftplib`, accept Unicode host names
(:mod:`httplib` then also transparently sends an IDNA hostname in the
:mailheader:`Host` field if it sends that field at all).
.. _section 3.1: https://tools.ietf.org/html/rfc3490#section-3.1
When receiving host names from the wire (such as in reverse name lookup), no
automatic conversion to Unicode is performed: Applications wishing to present
such host names to the user should decode them to Unicode.
The module :mod:`encodings.idna` also implements the nameprep procedure, which
performs certain normalizations on host names, to achieve case-insensitivity of
international domain names, and to unify similar characters. The nameprep
functions can be used directly if desired.
.. function:: nameprep(label)
Return the nameprepped version of *label*. The implementation currently assumes
query strings, so ``AllowUnassigned`` is true.
.. function:: ToASCII(label)
Convert a label to ASCII, as specified in :rfc:`3490`. ``UseSTD3ASCIIRules`` is
assumed to be false.
.. function:: ToUnicode(label)
Convert a label to Unicode, as specified in :rfc:`3490`.
:mod:`encodings.utf_8_sig` --- UTF-8 codec with BOM signature
-------------------------------------------------------------
.. module:: encodings.utf_8_sig
:synopsis: UTF-8 codec with BOM signature
.. moduleauthor:: Walter Dörwald
.. versionadded:: 2.5
This module implements a variant of the UTF-8 codec: On encoding a UTF-8 encoded
BOM will be prepended to the UTF-8 encoded bytes. For the stateful encoder this
is only done once (on the first write to the byte stream). For decoding an
optional UTF-8 encoded BOM at the start of the data will be skipped.
PK %�\��xʾ � $ html/_sources/library/codeop.rst.txtnu �[���
:mod:`codeop` --- Compile Python code
=====================================
.. module:: codeop
:synopsis: Compile (possibly incomplete) Python code.
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
.. sectionauthor:: Michael Hudson <mwh@python.net>
The :mod:`codeop` module provides utilities upon which the Python
read-eval-print loop can be emulated, as is done in the :mod:`code` module. As
a result, you probably don't want to use the module directly; if you want to
include such a loop in your program you probably want to use the :mod:`code`
module instead.
There are two parts to this job:
#. Being able to tell if a line of input completes a Python statement: in
short, telling whether to print '``>>>``' or '``...``' next.
#. Remembering which future statements the user has entered, so subsequent
input can be compiled with these in effect.
The :mod:`codeop` module provides a way of doing each of these things, and a way
of doing them both.
To do just the former:
.. function:: compile_command(source[, filename[, symbol]])
Tries to compile *source*, which should be a string of Python code and return a
code object if *source* is valid Python code. In that case, the filename
attribute of the code object will be *filename*, which defaults to
``'<input>'``. Returns ``None`` if *source* is *not* valid Python code, but is a
prefix of valid Python code.
If there is a problem with *source*, an exception will be raised.
:exc:`SyntaxError` is raised if there is invalid Python syntax, and
:exc:`OverflowError` or :exc:`ValueError` if there is an invalid literal.
The *symbol* argument determines whether *source* is compiled as a statement
(``'single'``, the default) or as an :term:`expression` (``'eval'``). Any
other value will cause :exc:`ValueError` to be raised.
.. note::
It is possible (but not likely) that the parser stops parsing with a
successful outcome before reaching the end of the source; in this case,
trailing symbols may be ignored instead of causing an error. For example,
a backslash followed by two newlines may be followed by arbitrary garbage.
This will be fixed once the API for the parser is better.
.. class:: Compile()
Instances of this class have :meth:`__call__` methods identical in signature to
the built-in function :func:`compile`, but with the difference that if the
instance compiles program text containing a :mod:`__future__` statement, the
instance 'remembers' and compiles all subsequent program texts with the
statement in force.
.. class:: CommandCompiler()
Instances of this class have :meth:`__call__` methods identical in signature to
:func:`compile_command`; the difference is that if the instance compiles program
text containing a ``__future__`` statement, the instance 'remembers' and
compiles all subsequent program texts with the statement in force.
A note on version compatibility: the :class:`Compile` and
:class:`CommandCompiler` are new in Python 2.2. If you want to enable the
future-tracking features of 2.2 but also retain compatibility with 2.1 and
earlier versions of Python you can either write ::
try:
from codeop import CommandCompiler
compile_command = CommandCompiler()
del CommandCompiler
except ImportError:
from codeop import compile_command
which is a low-impact change, but introduces possibly unwanted global state into
your program, or you can write::
try:
from codeop import CommandCompiler
except ImportError:
def CommandCompiler():
from codeop import compile_command
return compile_command
and then call ``CommandCompiler`` every time you need a fresh compiler object.
PK %�\�@��� � ) html/_sources/library/collections.rst.txtnu �[��� :mod:`collections` --- High-performance container datatypes
===========================================================
.. module:: collections
:synopsis: High-performance datatypes
.. moduleauthor:: Raymond Hettinger <python@rcn.com>
.. sectionauthor:: Raymond Hettinger <python@rcn.com>
.. versionadded:: 2.4
.. testsetup:: *
from collections import *
import itertools
__name__ = '<doctest>'
**Source code:** :source:`Lib/collections.py` and :source:`Lib/_abcoll.py`
--------------
This module implements specialized container datatypes providing alternatives to
Python's general purpose built-in containers, :class:`dict`, :class:`list`,
:class:`set`, and :class:`tuple`.
===================== ==================================================================== ===========================
:func:`namedtuple` factory function for creating tuple subclasses with named fields .. versionadded:: 2.6
:class:`deque` list-like container with fast appends and pops on either end .. versionadded:: 2.4
:class:`Counter` dict subclass for counting hashable objects .. versionadded:: 2.7
:class:`OrderedDict` dict subclass that remembers the order entries were added .. versionadded:: 2.7
:class:`defaultdict` dict subclass that calls a factory function to supply missing values .. versionadded:: 2.5
===================== ==================================================================== ===========================
In addition to the concrete container classes, the collections module provides
:ref:`abstract base classes <collections-abstract-base-classes>` that can be
used to test whether a class provides a particular interface, for example,
whether it is hashable or a mapping.
:class:`Counter` objects
------------------------
A counter tool is provided to support convenient and rapid tallies.
For example::
>>> # Tally occurrences of words in a list
>>> cnt = Counter()
>>> for word in ['red', 'blue', 'red', 'green', 'blue', 'blue']:
... cnt[word] += 1
>>> cnt
Counter({'blue': 3, 'red': 2, 'green': 1})
>>> # Find the ten most common words in Hamlet
>>> import re
>>> words = re.findall(r'\w+', open('hamlet.txt').read().lower())
>>> Counter(words).most_common(10)
[('the', 1143), ('and', 966), ('to', 762), ('of', 669), ('i', 631),
('you', 554), ('a', 546), ('my', 514), ('hamlet', 471), ('in', 451)]
.. class:: Counter([iterable-or-mapping])
A :class:`Counter` is a :class:`dict` subclass for counting hashable objects.
It is an unordered collection where elements are stored as dictionary keys
and their counts are stored as dictionary values. Counts are allowed to be
any integer value including zero or negative counts. The :class:`Counter`
class is similar to bags or multisets in other languages.
Elements are counted from an *iterable* or initialized from another
*mapping* (or counter):
>>> c = Counter() # a new, empty counter
>>> c = Counter('gallahad') # a new counter from an iterable
>>> c = Counter({'red': 4, 'blue': 2}) # a new counter from a mapping
>>> c = Counter(cats=4, dogs=8) # a new counter from keyword args
Counter objects have a dictionary interface except that they return a zero
count for missing items instead of raising a :exc:`KeyError`:
>>> c = Counter(['eggs', 'ham'])
>>> c['bacon'] # count of a missing element is zero
0
Setting a count to zero does not remove an element from a counter.
Use ``del`` to remove it entirely:
>>> c['sausage'] = 0 # counter entry with a zero count
>>> del c['sausage'] # del actually removes the entry
.. versionadded:: 2.7
Counter objects support three methods beyond those available for all
dictionaries:
.. method:: elements()
Return an iterator over elements repeating each as many times as its
count. Elements are returned in arbitrary order. If an element's count
is less than one, :meth:`elements` will ignore it.
>>> c = Counter(a=4, b=2, c=0, d=-2)
>>> list(c.elements())
['a', 'a', 'a', 'a', 'b', 'b']
.. method:: most_common([n])
Return a list of the *n* most common elements and their counts from the
most common to the least. If *n* is omitted or ``None``,
:func:`most_common` returns *all* elements in the counter.
Elements with equal counts are ordered arbitrarily:
>>> Counter('abracadabra').most_common(3)
[('a', 5), ('r', 2), ('b', 2)]
.. method:: subtract([iterable-or-mapping])
Elements are subtracted from an *iterable* or from another *mapping*
(or counter). Like :meth:`dict.update` but subtracts counts instead
of replacing them. Both inputs and outputs may be zero or negative.
>>> c = Counter(a=4, b=2, c=0, d=-2)
>>> d = Counter(a=1, b=2, c=3, d=4)
>>> c.subtract(d)
>>> c
Counter({'a': 3, 'b': 0, 'c': -3, 'd': -6})
The usual dictionary methods are available for :class:`Counter` objects
except for two which work differently for counters.
.. method:: fromkeys(iterable)
This class method is not implemented for :class:`Counter` objects.
.. method:: update([iterable-or-mapping])
Elements are counted from an *iterable* or added-in from another
*mapping* (or counter). Like :meth:`dict.update` but adds counts
instead of replacing them. Also, the *iterable* is expected to be a
sequence of elements, not a sequence of ``(key, value)`` pairs.
Common patterns for working with :class:`Counter` objects::
sum(c.values()) # total of all counts
c.clear() # reset all counts
list(c) # list unique elements
set(c) # convert to a set
dict(c) # convert to a regular dictionary
c.items() # convert to a list of (elem, cnt) pairs
Counter(dict(list_of_pairs)) # convert from a list of (elem, cnt) pairs
c.most_common()[:-n-1:-1] # n least common elements
c += Counter() # remove zero and negative counts
Several mathematical operations are provided for combining :class:`Counter`
objects to produce multisets (counters that have counts greater than zero).
Addition and subtraction combine counters by adding or subtracting the counts
of corresponding elements. Intersection and union return the minimum and
maximum of corresponding counts. Each operation can accept inputs with signed
counts, but the output will exclude results with counts of zero or less.
>>> c = Counter(a=3, b=1)
>>> d = Counter(a=1, b=2)
>>> c + d # add two counters together: c[x] + d[x]
Counter({'a': 4, 'b': 3})
>>> c - d # subtract (keeping only positive counts)
Counter({'a': 2})
>>> c & d # intersection: min(c[x], d[x])
Counter({'a': 1, 'b': 1})
>>> c | d # union: max(c[x], d[x])
Counter({'a': 3, 'b': 2})
.. note::
Counters were primarily designed to work with positive integers to represent
running counts; however, care was taken to not unnecessarily preclude use
cases needing other types or negative values. To help with those use cases,
this section documents the minimum range and type restrictions.
* The :class:`Counter` class itself is a dictionary subclass with no
restrictions on its keys and values. The values are intended to be numbers
representing counts, but you *could* store anything in the value field.
* The :meth:`most_common` method requires only that the values be orderable.
* For in-place operations such as ``c[key] += 1``, the value type need only
support addition and subtraction. So fractions, floats, and decimals would
work and negative values are supported. The same is also true for
:meth:`update` and :meth:`subtract` which allow negative and zero values
for both inputs and outputs.
* The multiset methods are designed only for use cases with positive values.
The inputs may be negative or zero, but only outputs with positive values
are created. There are no type restrictions, but the value type needs to
support addition, subtraction, and comparison.
* The :meth:`elements` method requires integer counts. It ignores zero and
negative counts.
.. seealso::
* `Counter class <https://code.activestate.com/recipes/576611/>`_
adapted for Python 2.5 and an early `Bag recipe
<https://code.activestate.com/recipes/259174/>`_ for Python 2.4.
* `Bag class <https://www.gnu.org/software/smalltalk/manual-base/html_node/Bag.html>`_
in Smalltalk.
* Wikipedia entry for `Multisets <https://en.wikipedia.org/wiki/Multiset>`_.
* `C++ multisets <http://www.java2s.com/Tutorial/Cpp/0380__set-multiset/Catalog0380__set-multiset.htm>`_
tutorial with examples.
* For mathematical operations on multisets and their use cases, see
*Knuth, Donald. The Art of Computer Programming Volume II,
Section 4.6.3, Exercise 19*.
* To enumerate all distinct multisets of a given size over a given set of
elements, see :func:`itertools.combinations_with_replacement`.
map(Counter, combinations_with_replacement('ABC', 2)) --> AA AB AC BB BC CC
:class:`deque` objects
----------------------
.. class:: deque([iterable[, maxlen]])
Returns a new deque object initialized left-to-right (using :meth:`append`) with
data from *iterable*. If *iterable* is not specified, the new deque is empty.
Deques are a generalization of stacks and queues (the name is pronounced "deck"
and is short for "double-ended queue"). Deques support thread-safe, memory
efficient appends and pops from either side of the deque with approximately the
same O(1) performance in either direction.
Though :class:`list` objects support similar operations, they are optimized for
fast fixed-length operations and incur O(n) memory movement costs for
``pop(0)`` and ``insert(0, v)`` operations which change both the size and
position of the underlying data representation.
.. versionadded:: 2.4
If *maxlen* is not specified or is ``None``, deques may grow to an
arbitrary length. Otherwise, the deque is bounded to the specified maximum
length. Once a bounded length deque is full, when new items are added, a
corresponding number of items are discarded from the opposite end. Bounded
length deques provide functionality similar to the ``tail`` filter in
Unix. They are also useful for tracking transactions and other pools of data
where only the most recent activity is of interest.
.. versionchanged:: 2.6
Added *maxlen* parameter.
Deque objects support the following methods:
.. method:: append(x)
Add *x* to the right side of the deque.
.. method:: appendleft(x)
Add *x* to the left side of the deque.
.. method:: clear()
Remove all elements from the deque leaving it with length 0.
.. method:: count(x)
Count the number of deque elements equal to *x*.
.. versionadded:: 2.7
.. method:: extend(iterable)
Extend the right side of the deque by appending elements from the iterable
argument.
.. method:: extendleft(iterable)
Extend the left side of the deque by appending elements from *iterable*.
Note, the series of left appends results in reversing the order of
elements in the iterable argument.
.. method:: pop()
Remove and return an element from the right side of the deque. If no
elements are present, raises an :exc:`IndexError`.
.. method:: popleft()
Remove and return an element from the left side of the deque. If no
elements are present, raises an :exc:`IndexError`.
.. method:: remove(value)
Remove the first occurrence of *value*. If not found, raises a
:exc:`ValueError`.
.. versionadded:: 2.5
.. method:: reverse()
Reverse the elements of the deque in-place and then return ``None``.
.. versionadded:: 2.7
.. method:: rotate(n=1)
Rotate the deque *n* steps to the right. If *n* is negative, rotate to
the left.
When the deque is not empty, rotating one step to the right is equivalent to
``d.appendleft(d.pop())``, and rotating one step to the left is
equivalent to ``d.append(d.popleft())``.
Deque objects also provide one read-only attribute:
.. attribute:: maxlen
Maximum size of a deque or ``None`` if unbounded.
.. versionadded:: 2.7
In addition to the above, deques support iteration, pickling, ``len(d)``,
``reversed(d)``, ``copy.copy(d)``, ``copy.deepcopy(d)``, membership testing with
the :keyword:`in` operator, and subscript references such as ``d[-1]``. Indexed
access is O(1) at both ends but slows to O(n) in the middle. For fast random
access, use lists instead.
Example:
.. doctest::
>>> from collections import deque
>>> d = deque('ghi') # make a new deque with three items
>>> for elem in d: # iterate over the deque's elements
... print elem.upper()
G
H
I
>>> d.append('j') # add a new entry to the right side
>>> d.appendleft('f') # add a new entry to the left side
>>> d # show the representation of the deque
deque(['f', 'g', 'h', 'i', 'j'])
>>> d.pop() # return and remove the rightmost item
'j'
>>> d.popleft() # return and remove the leftmost item
'f'
>>> list(d) # list the contents of the deque
['g', 'h', 'i']
>>> d[0] # peek at leftmost item
'g'
>>> d[-1] # peek at rightmost item
'i'
>>> list(reversed(d)) # list the contents of a deque in reverse
['i', 'h', 'g']
>>> 'h' in d # search the deque
True
>>> d.extend('jkl') # add multiple elements at once
>>> d
deque(['g', 'h', 'i', 'j', 'k', 'l'])
>>> d.rotate(1) # right rotation
>>> d
deque(['l', 'g', 'h', 'i', 'j', 'k'])
>>> d.rotate(-1) # left rotation
>>> d
deque(['g', 'h', 'i', 'j', 'k', 'l'])
>>> deque(reversed(d)) # make a new deque in reverse order
deque(['l', 'k', 'j', 'i', 'h', 'g'])
>>> d.clear() # empty the deque
>>> d.pop() # cannot pop from an empty deque
Traceback (most recent call last):
File "<pyshell#6>", line 1, in -toplevel-
d.pop()
IndexError: pop from an empty deque
>>> d.extendleft('abc') # extendleft() reverses the input order
>>> d
deque(['c', 'b', 'a'])
:class:`deque` Recipes
^^^^^^^^^^^^^^^^^^^^^^
This section shows various approaches to working with deques.
Bounded length deques provide functionality similar to the ``tail`` filter
in Unix::
def tail(filename, n=10):
'Return the last n lines of a file'
return deque(open(filename), n)
Another approach to using deques is to maintain a sequence of recently
added elements by appending to the right and popping to the left::
def moving_average(iterable, n=3):
# moving_average([40, 30, 50, 46, 39, 44]) --> 40.0 42.0 45.0 43.0
# http://en.wikipedia.org/wiki/Moving_average
it = iter(iterable)
d = deque(itertools.islice(it, n-1))
d.appendleft(0)
s = sum(d)
for elem in it:
s += elem - d.popleft()
d.append(elem)
yield s / float(n)
The :meth:`rotate` method provides a way to implement :class:`deque` slicing and
deletion. For example, a pure Python implementation of ``del d[n]`` relies on
the :meth:`rotate` method to position elements to be popped::
def delete_nth(d, n):
d.rotate(-n)
d.popleft()
d.rotate(n)
To implement :class:`deque` slicing, use a similar approach applying
:meth:`rotate` to bring a target element to the left side of the deque. Remove
old entries with :meth:`popleft`, add new entries with :meth:`extend`, and then
reverse the rotation.
With minor variations on that approach, it is easy to implement Forth style
stack manipulations such as ``dup``, ``drop``, ``swap``, ``over``, ``pick``,
``rot``, and ``roll``.
:class:`defaultdict` objects
----------------------------
.. class:: defaultdict([default_factory[, ...]])
Returns a new dictionary-like object. :class:`defaultdict` is a subclass of the
built-in :class:`dict` class. It overrides one method and adds one writable
instance variable. The remaining functionality is the same as for the
:class:`dict` class and is not documented here.
The first argument provides the initial value for the :attr:`default_factory`
attribute; it defaults to ``None``. All remaining arguments are treated the same
as if they were passed to the :class:`dict` constructor, including keyword
arguments.
.. versionadded:: 2.5
:class:`defaultdict` objects support the following method in addition to the
standard :class:`dict` operations:
.. method:: __missing__(key)
If the :attr:`default_factory` attribute is ``None``, this raises a
:exc:`KeyError` exception with the *key* as argument.
If :attr:`default_factory` is not ``None``, it is called without arguments
to provide a default value for the given *key*, this value is inserted in
the dictionary for the *key*, and returned.
If calling :attr:`default_factory` raises an exception this exception is
propagated unchanged.
This method is called by the :meth:`__getitem__` method of the
:class:`dict` class when the requested key is not found; whatever it
returns or raises is then returned or raised by :meth:`__getitem__`.
Note that :meth:`__missing__` is *not* called for any operations besides
:meth:`__getitem__`. This means that :meth:`get` will, like normal
dictionaries, return ``None`` as a default rather than using
:attr:`default_factory`.
:class:`defaultdict` objects support the following instance variable:
.. attribute:: default_factory
This attribute is used by the :meth:`__missing__` method; it is
initialized from the first argument to the constructor, if present, or to
``None``, if absent.
:class:`defaultdict` Examples
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Using :class:`list` as the :attr:`default_factory`, it is easy to group a
sequence of key-value pairs into a dictionary of lists:
>>> s = [('yellow', 1), ('blue', 2), ('yellow', 3), ('blue', 4), ('red', 1)]
>>> d = defaultdict(list)
>>> for k, v in s:
... d[k].append(v)
...
>>> d.items()
[('blue', [2, 4]), ('red', [1]), ('yellow', [1, 3])]
When each key is encountered for the first time, it is not already in the
mapping; so an entry is automatically created using the :attr:`default_factory`
function which returns an empty :class:`list`. The :meth:`list.append`
operation then attaches the value to the new list. When keys are encountered
again, the look-up proceeds normally (returning the list for that key) and the
:meth:`list.append` operation adds another value to the list. This technique is
simpler and faster than an equivalent technique using :meth:`dict.setdefault`:
>>> d = {}
>>> for k, v in s:
... d.setdefault(k, []).append(v)
...
>>> d.items()
[('blue', [2, 4]), ('red', [1]), ('yellow', [1, 3])]
Setting the :attr:`default_factory` to :class:`int` makes the
:class:`defaultdict` useful for counting (like a bag or multiset in other
languages):
>>> s = 'mississippi'
>>> d = defaultdict(int)
>>> for k in s:
... d[k] += 1
...
>>> d.items()
[('i', 4), ('p', 2), ('s', 4), ('m', 1)]
When a letter is first encountered, it is missing from the mapping, so the
:attr:`default_factory` function calls :func:`int` to supply a default count of
zero. The increment operation then builds up the count for each letter.
The function :func:`int` which always returns zero is just a special case of
constant functions. A faster and more flexible way to create constant functions
is to use :func:`itertools.repeat` which can supply any constant value (not just
zero):
>>> def constant_factory(value):
... return itertools.repeat(value).next
>>> d = defaultdict(constant_factory('<missing>'))
>>> d.update(name='John', action='ran')
>>> '%(name)s %(action)s to %(object)s' % d
'John ran to <missing>'
Setting the :attr:`default_factory` to :class:`set` makes the
:class:`defaultdict` useful for building a dictionary of sets:
>>> s = [('red', 1), ('blue', 2), ('red', 3), ('blue', 4), ('red', 1), ('blue', 4)]
>>> d = defaultdict(set)
>>> for k, v in s:
... d[k].add(v)
...
>>> d.items()
[('blue', set([2, 4])), ('red', set([1, 3]))]
:func:`namedtuple` Factory Function for Tuples with Named Fields
----------------------------------------------------------------
Named tuples assign meaning to each position in a tuple and allow for more readable,
self-documenting code. They can be used wherever regular tuples are used, and
they add the ability to access fields by name instead of position index.
.. function:: namedtuple(typename, field_names, [verbose=False], [rename=False])
Returns a new tuple subclass named *typename*. The new subclass is used to
create tuple-like objects that have fields accessible by attribute lookup as
well as being indexable and iterable. Instances of the subclass also have a
helpful docstring (with typename and field_names) and a helpful :meth:`__repr__`
method which lists the tuple contents in a ``name=value`` format.
The *field_names* are a sequence of strings such as ``['x', 'y']``.
Alternatively, *field_names* can be a single string with each fieldname
separated by whitespace and/or commas, for example ``'x y'`` or ``'x, y'``.
Any valid Python identifier may be used for a fieldname except for names
starting with an underscore. Valid identifiers consist of letters, digits,
and underscores but do not start with a digit or underscore and cannot be
a :mod:`keyword` such as *class*, *for*, *return*, *global*, *pass*, *print*,
or *raise*.
If *rename* is true, invalid fieldnames are automatically replaced
with positional names. For example, ``['abc', 'def', 'ghi', 'abc']`` is
converted to ``['abc', '_1', 'ghi', '_3']``, eliminating the keyword
``def`` and the duplicate fieldname ``abc``.
If *verbose* is true, the class definition is printed just before being built.
Named tuple instances do not have per-instance dictionaries, so they are
lightweight and require no more memory than regular tuples.
.. versionadded:: 2.6
.. versionchanged:: 2.7
added support for *rename*.
Example:
.. doctest::
:options: +NORMALIZE_WHITESPACE
>>> Point = namedtuple('Point', ['x', 'y'], verbose=True)
class Point(tuple):
'Point(x, y)'
<BLANKLINE>
__slots__ = ()
<BLANKLINE>
_fields = ('x', 'y')
<BLANKLINE>
def __new__(_cls, x, y):
'Create new instance of Point(x, y)'
return _tuple.__new__(_cls, (x, y))
<BLANKLINE>
@classmethod
def _make(cls, iterable, new=tuple.__new__, len=len):
'Make a new Point object from a sequence or iterable'
result = new(cls, iterable)
if len(result) != 2:
raise TypeError('Expected 2 arguments, got %d' % len(result))
return result
<BLANKLINE>
def __repr__(self):
'Return a nicely formatted representation string'
return 'Point(x=%r, y=%r)' % self
<BLANKLINE>
def _asdict(self):
'Return a new OrderedDict which maps field names to their values'
return OrderedDict(zip(self._fields, self))
<BLANKLINE>
def _replace(_self, **kwds):
'Return a new Point object replacing specified fields with new values'
result = _self._make(map(kwds.pop, ('x', 'y'), _self))
if kwds:
raise ValueError('Got unexpected field names: %r' % kwds.keys())
return result
<BLANKLINE>
def __getnewargs__(self):
'Return self as a plain tuple. Used by copy and pickle.'
return tuple(self)
<BLANKLINE>
__dict__ = _property(_asdict)
<BLANKLINE>
def __getstate__(self):
'Exclude the OrderedDict from pickling'
pass
<BLANKLINE>
x = _property(_itemgetter(0), doc='Alias for field number 0')
<BLANKLINE>
y = _property(_itemgetter(1), doc='Alias for field number 1')
<BLANKLINE>
<BLANKLINE>
>>> p = Point(11, y=22) # instantiate with positional or keyword arguments
>>> p[0] + p[1] # indexable like the plain tuple (11, 22)
33
>>> x, y = p # unpack like a regular tuple
>>> x, y
(11, 22)
>>> p.x + p.y # fields also accessible by name
33
>>> p # readable __repr__ with a name=value style
Point(x=11, y=22)
Named tuples are especially useful for assigning field names to result tuples returned
by the :mod:`csv` or :mod:`sqlite3` modules::
EmployeeRecord = namedtuple('EmployeeRecord', 'name, age, title, department, paygrade')
import csv
for emp in map(EmployeeRecord._make, csv.reader(open("employees.csv", "rb"))):
print emp.name, emp.title
import sqlite3
conn = sqlite3.connect('/companydata')
cursor = conn.cursor()
cursor.execute('SELECT name, age, title, department, paygrade FROM employees')
for emp in map(EmployeeRecord._make, cursor.fetchall()):
print emp.name, emp.title
In addition to the methods inherited from tuples, named tuples support
three additional methods and one attribute. To prevent conflicts with
field names, the method and attribute names start with an underscore.
.. classmethod:: somenamedtuple._make(iterable)
Class method that makes a new instance from an existing sequence or iterable.
.. doctest::
>>> t = [11, 22]
>>> Point._make(t)
Point(x=11, y=22)
.. method:: somenamedtuple._asdict()
Return a new :class:`OrderedDict` which maps field names to their corresponding
values::
>>> p = Point(x=11, y=22)
>>> p._asdict()
OrderedDict([('x', 11), ('y', 22)])
.. versionchanged:: 2.7
Returns an :class:`OrderedDict` instead of a regular :class:`dict`.
.. method:: somenamedtuple._replace(**kwargs)
Return a new instance of the named tuple replacing specified fields with new
values::
>>> p = Point(x=11, y=22)
>>> p._replace(x=33)
Point(x=33, y=22)
>>> for partnum, record in inventory.items():
... inventory[partnum] = record._replace(price=newprices[partnum], timestamp=time.now())
.. attribute:: somenamedtuple._fields
Tuple of strings listing the field names. Useful for introspection
and for creating new named tuple types from existing named tuples.
.. doctest::
>>> p._fields # view the field names
('x', 'y')
>>> Color = namedtuple('Color', 'red green blue')
>>> Pixel = namedtuple('Pixel', Point._fields + Color._fields)
>>> Pixel(11, 22, 128, 255, 0)
Pixel(x=11, y=22, red=128, green=255, blue=0)
To retrieve a field whose name is stored in a string, use the :func:`getattr`
function:
>>> getattr(p, 'x')
11
To convert a dictionary to a named tuple, use the double-star-operator
(as described in :ref:`tut-unpacking-arguments`):
>>> d = {'x': 11, 'y': 22}
>>> Point(**d)
Point(x=11, y=22)
Since a named tuple is a regular Python class, it is easy to add or change
functionality with a subclass. Here is how to add a calculated field and
a fixed-width print format:
>>> class Point(namedtuple('Point', 'x y')):
... __slots__ = ()
... @property
... def hypot(self):
... return (self.x ** 2 + self.y ** 2) ** 0.5
... def __str__(self):
... return 'Point: x=%6.3f y=%6.3f hypot=%6.3f' % (self.x, self.y, self.hypot)
...
>>> for p in Point(3, 4), Point(14, 5/7.):
... print p
Point: x= 3.000 y= 4.000 hypot= 5.000
Point: x=14.000 y= 0.714 hypot=14.018
The subclass shown above sets ``__slots__`` to an empty tuple. This helps
keep memory requirements low by preventing the creation of instance dictionaries.
Subclassing is not useful for adding new, stored fields. Instead, simply
create a new named tuple type from the :attr:`_fields` attribute:
>>> Point3D = namedtuple('Point3D', Point._fields + ('z',))
Default values can be implemented by using :meth:`_replace` to
customize a prototype instance:
>>> Account = namedtuple('Account', 'owner balance transaction_count')
>>> default_account = Account('<owner name>', 0.0, 0)
>>> johns_account = default_account._replace(owner='John')
Enumerated constants can be implemented with named tuples, but it is simpler
and more efficient to use a simple class declaration:
>>> Status = namedtuple('Status', 'open pending closed')._make(range(3))
>>> Status.open, Status.pending, Status.closed
(0, 1, 2)
>>> class Status:
... open, pending, closed = range(3)
.. seealso::
`Named tuple recipe <https://code.activestate.com/recipes/500261/>`_
adapted for Python 2.4.
:class:`OrderedDict` objects
----------------------------
Ordered dictionaries are just like regular dictionaries but they remember the
order that items were inserted. When iterating over an ordered dictionary,
the items are returned in the order their keys were first added.
.. class:: OrderedDict([items])
Return an instance of a dict subclass, supporting the usual :class:`dict`
methods. An *OrderedDict* is a dict that remembers the order that keys
were first inserted. If a new entry overwrites an existing entry, the
original insertion position is left unchanged. Deleting an entry and
reinserting it will move it to the end.
.. versionadded:: 2.7
.. method:: OrderedDict.popitem(last=True)
The :meth:`popitem` method for ordered dictionaries returns and removes
a (key, value) pair. The pairs are returned in LIFO order if *last* is
true or FIFO order if false.
In addition to the usual mapping methods, ordered dictionaries also support
reverse iteration using :func:`reversed`.
Equality tests between :class:`OrderedDict` objects are order-sensitive
and are implemented as ``list(od1.items())==list(od2.items())``.
Equality tests between :class:`OrderedDict` objects and other
:class:`Mapping` objects are order-insensitive like regular
dictionaries. This allows :class:`OrderedDict` objects to be substituted
anywhere a regular dictionary is used.
The :class:`OrderedDict` constructor and :meth:`update` method both accept
keyword arguments, but their order is lost because Python's function call
semantics pass-in keyword arguments using a regular unordered dictionary.
.. seealso::
`Equivalent OrderedDict recipe <https://code.activestate.com/recipes/576693/>`_
that runs on Python 2.4 or later.
:class:`OrderedDict` Examples and Recipes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Since an ordered dictionary remembers its insertion order, it can be used
in conjunction with sorting to make a sorted dictionary::
>>> # regular unsorted dictionary
>>> d = {'banana': 3, 'apple': 4, 'pear': 1, 'orange': 2}
>>> # dictionary sorted by key
>>> OrderedDict(sorted(d.items(), key=lambda t: t[0]))
OrderedDict([('apple', 4), ('banana', 3), ('orange', 2), ('pear', 1)])
>>> # dictionary sorted by value
>>> OrderedDict(sorted(d.items(), key=lambda t: t[1]))
OrderedDict([('pear', 1), ('orange', 2), ('banana', 3), ('apple', 4)])
>>> # dictionary sorted by length of the key string
>>> OrderedDict(sorted(d.items(), key=lambda t: len(t[0])))
OrderedDict([('pear', 1), ('apple', 4), ('orange', 2), ('banana', 3)])
The new sorted dictionaries maintain their sort order when entries
are deleted. But when new keys are added, the keys are appended
to the end and the sort is not maintained.
It is also straight-forward to create an ordered dictionary variant
that remembers the order the keys were *last* inserted.
If a new entry overwrites an existing entry, the
original insertion position is changed and moved to the end::
class LastUpdatedOrderedDict(OrderedDict):
'Store items in the order the keys were last added'
def __setitem__(self, key, value):
if key in self:
del self[key]
OrderedDict.__setitem__(self, key, value)
An ordered dictionary can be combined with the :class:`Counter` class
so that the counter remembers the order elements are first encountered::
class OrderedCounter(Counter, OrderedDict):
'Counter that remembers the order elements are first encountered'
def __repr__(self):
return '%s(%r)' % (self.__class__.__name__, OrderedDict(self))
def __reduce__(self):
return self.__class__, (OrderedDict(self),)
.. _collections-abstract-base-classes:
Collections Abstract Base Classes
---------------------------------
The collections module offers the following :term:`ABCs <abstract base class>`:
========================= ===================== ====================== ====================================================
ABC Inherits from Abstract Methods Mixin Methods
========================= ===================== ====================== ====================================================
:class:`Container` ``__contains__``
:class:`Hashable` ``__hash__``
:class:`Iterable` ``__iter__``
:class:`Iterator` :class:`Iterable` ``next`` ``__iter__``
:class:`Sized` ``__len__``
:class:`Callable` ``__call__``
:class:`Sequence` :class:`Sized`, ``__getitem__``, ``__contains__``, ``__iter__``, ``__reversed__``,
:class:`Iterable`, ``__len__`` ``index``, and ``count``
:class:`Container`
:class:`MutableSequence` :class:`Sequence` ``__getitem__``, Inherited :class:`Sequence` methods and
``__setitem__``, ``append``, ``reverse``, ``extend``, ``pop``,
``__delitem__``, ``remove``, and ``__iadd__``
``__len__``,
``insert``
:class:`Set` :class:`Sized`, ``__contains__``, ``__le__``, ``__lt__``, ``__eq__``, ``__ne__``,
:class:`Iterable`, ``__iter__``, ``__gt__``, ``__ge__``, ``__and__``, ``__or__``,
:class:`Container` ``__len__`` ``__sub__``, ``__xor__``, and ``isdisjoint``
:class:`MutableSet` :class:`Set` ``__contains__``, Inherited :class:`Set` methods and
``__iter__``, ``clear``, ``pop``, ``remove``, ``__ior__``,
``__len__``, ``__iand__``, ``__ixor__``, and ``__isub__``
``add``,
``discard``
:class:`Mapping` :class:`Sized`, ``__getitem__``, ``__contains__``, ``keys``, ``items``, ``values``,
:class:`Iterable`, ``__iter__``, ``get``, ``__eq__``, and ``__ne__``
:class:`Container` ``__len__``
:class:`MutableMapping` :class:`Mapping` ``__getitem__``, Inherited :class:`Mapping` methods and
``__setitem__``, ``pop``, ``popitem``, ``clear``, ``update``,
``__delitem__``, and ``setdefault``
``__iter__``,
``__len__``
:class:`MappingView` :class:`Sized` ``__len__``
:class:`ItemsView` :class:`MappingView`, ``__contains__``,
:class:`Set` ``__iter__``
:class:`KeysView` :class:`MappingView`, ``__contains__``,
:class:`Set` ``__iter__``
:class:`ValuesView` :class:`MappingView` ``__contains__``, ``__iter__``
========================= ===================== ====================== ====================================================
.. class:: Container
Hashable
Sized
Callable
ABCs for classes that provide respectively the methods :meth:`__contains__`,
:meth:`__hash__`, :meth:`__len__`, and :meth:`__call__`.
.. class:: Iterable
ABC for classes that provide the :meth:`__iter__` method.
See also the definition of :term:`iterable`.
.. class:: Iterator
ABC for classes that provide the :meth:`~iterator.__iter__` and
:meth:`~iterator.next` methods. See also the definition of :term:`iterator`.
.. class:: Sequence
MutableSequence
ABCs for read-only and mutable :term:`sequences <sequence>`.
.. class:: Set
MutableSet
ABCs for read-only and mutable sets.
.. class:: Mapping
MutableMapping
ABCs for read-only and mutable :term:`mappings <mapping>`.
.. class:: MappingView
ItemsView
KeysView
ValuesView
ABCs for mapping, items, keys, and values :term:`views <dictionary view>`.
These ABCs allow us to ask classes or instances if they provide
particular functionality, for example::
size = None
if isinstance(myvar, collections.Sized):
size = len(myvar)
Several of the ABCs are also useful as mixins that make it easier to develop
classes supporting container APIs. For example, to write a class supporting
the full :class:`Set` API, it only necessary to supply the three underlying
abstract methods: :meth:`__contains__`, :meth:`__iter__`, and :meth:`__len__`.
The ABC supplies the remaining methods such as :meth:`__and__` and
:meth:`isdisjoint` ::
class ListBasedSet(collections.Set):
''' Alternate set implementation favoring space over speed
and not requiring the set elements to be hashable. '''
def __init__(self, iterable):
self.elements = lst = []
for value in iterable:
if value not in lst:
lst.append(value)
def __iter__(self):
return iter(self.elements)
def __contains__(self, value):
return value in self.elements
def __len__(self):
return len(self.elements)
s1 = ListBasedSet('abcdef')
s2 = ListBasedSet('defghi')
overlap = s1 & s2 # The __and__() method is supported automatically
Notes on using :class:`Set` and :class:`MutableSet` as a mixin:
(1)
Since some set operations create new sets, the default mixin methods need
a way to create new instances from an iterable. The class constructor is
assumed to have a signature in the form ``ClassName(iterable)``.
That assumption is factored-out to an internal classmethod called
:meth:`_from_iterable` which calls ``cls(iterable)`` to produce a new set.
If the :class:`Set` mixin is being used in a class with a different
constructor signature, you will need to override :meth:`_from_iterable`
with a classmethod that can construct new instances from
an iterable argument.
(2)
To override the comparisons (presumably for speed, as the
semantics are fixed), redefine :meth:`__le__` and :meth:`__ge__`,
then the other operations will automatically follow suit.
(3)
The :class:`Set` mixin provides a :meth:`_hash` method to compute a hash value
for the set; however, :meth:`__hash__` is not defined because not all sets
are hashable or immutable. To add set hashability using mixins,
inherit from both :meth:`Set` and :meth:`Hashable`, then define
``__hash__ = Set._hash``.
.. seealso::
* `OrderedSet recipe <https://code.activestate.com/recipes/576694/>`_ for an
example built on :class:`MutableSet`.
* For more about ABCs, see the :mod:`abc` module and :pep:`3119`.
PK %�\��� � � ) html/_sources/library/colorpicker.rst.txtnu �[���
:mod:`ColorPicker` --- Color selection dialog
=============================================
.. module:: ColorPicker
:platform: Mac
:synopsis: Interface to the standard color selection dialog.
:deprecated:
.. moduleauthor:: Just van Rossum <just@letterror.com>
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
The :mod:`ColorPicker` module provides access to the standard color picker
dialog.
.. note::
This module has been removed in Python 3.x.
.. function:: GetColor(prompt, rgb)
Show a standard color selection dialog and allow the user to select a color.
The user is given instruction by the *prompt* string, and the default color is
set to *rgb*. *rgb* must be a tuple giving the red, green, and blue components
of the color. :func:`GetColor` returns a tuple giving the user's selected color
and a flag indicating whether they accepted the selection of cancelled.
PK %�\9�B< & html/_sources/library/colorsys.rst.txtnu �[��� :mod:`colorsys` --- Conversions between color systems
=====================================================
.. module:: colorsys
:synopsis: Conversion functions between RGB and other color systems.
.. sectionauthor:: David Ascher <da@python.net>
**Source code:** :source:`Lib/colorsys.py`
--------------
The :mod:`colorsys` module defines bidirectional conversions of color values
between colors expressed in the RGB (Red Green Blue) color space used in
computer monitors and three other coordinate systems: YIQ, HLS (Hue Lightness
Saturation) and HSV (Hue Saturation Value). Coordinates in all of these color
spaces are floating point values. In the YIQ space, the Y coordinate is between
0 and 1, but the I and Q coordinates can be positive or negative. In all other
spaces, the coordinates are all between 0 and 1.
.. seealso::
More information about color spaces can be found at
http://www.poynton.com/ColorFAQ.html and
https://www.cambridgeincolour.com/tutorials/color-spaces.htm.
The :mod:`colorsys` module defines the following functions:
.. function:: rgb_to_yiq(r, g, b)
Convert the color from RGB coordinates to YIQ coordinates.
.. function:: yiq_to_rgb(y, i, q)
Convert the color from YIQ coordinates to RGB coordinates.
.. function:: rgb_to_hls(r, g, b)
Convert the color from RGB coordinates to HLS coordinates.
.. function:: hls_to_rgb(h, l, s)
Convert the color from HLS coordinates to RGB coordinates.
.. function:: rgb_to_hsv(r, g, b)
Convert the color from RGB coordinates to HSV coordinates.
.. function:: hsv_to_rgb(h, s, v)
Convert the color from HSV coordinates to RGB coordinates.
Example::
>>> import colorsys
>>> colorsys.rgb_to_hsv(0.2, 0.4, 0.4)
(0.5, 0.5, 0.4)
>>> colorsys.hsv_to_rgb(0.5, 0.5, 0.4)
(0.2, 0.4, 0.4)
PK %�\K�@w#
#
& html/_sources/library/commands.rst.txtnu �[���
:mod:`commands` --- Utilities for running commands
==================================================
.. module:: commands
:platform: Unix
:synopsis: Utility functions for running external commands.
:deprecated:
.. deprecated:: 2.6
The :mod:`commands` module has been removed in Python 3. Use the
:mod:`subprocess` module instead.
.. sectionauthor:: Sue Williams <sbw@provis.com>
The :mod:`commands` module contains wrapper functions for :func:`os.popen` which
take a system command as a string and return any output generated by the command
and, optionally, the exit status.
The :mod:`subprocess` module provides more powerful facilities for spawning new
processes and retrieving their results. Using the :mod:`subprocess` module is
preferable to using the :mod:`commands` module.
.. note::
In Python 3.x, :func:`getstatus` and two undocumented functions
(:func:`mk2arg` and :func:`mkarg`) have been removed. Also,
:func:`getstatusoutput` and :func:`getoutput` have been moved to the
:mod:`subprocess` module.
The :mod:`commands` module defines the following functions:
.. function:: getstatusoutput(cmd)
Execute the string *cmd* in a shell with :func:`os.popen` and return a 2-tuple
``(status, output)``. *cmd* is actually run as ``{ cmd ; } 2>&1``, so that the
returned output will contain output or error messages. A trailing newline is
stripped from the output. The exit status for the command can be interpreted
according to the rules for the C function :c:func:`wait`.
.. function:: getoutput(cmd)
Like :func:`getstatusoutput`, except the exit status is ignored and the return
value is a string containing the command's output.
.. function:: getstatus(file)
Return the output of ``ls -ld file`` as a string. This function uses the
:func:`getoutput` function, and properly escapes backslashes and dollar signs in
the argument.
.. deprecated:: 2.6
This function is nonobvious and useless. The name is also misleading in the
presence of :func:`getstatusoutput`.
Example::
>>> import commands
>>> commands.getstatusoutput('ls /bin/ls')
(0, '/bin/ls')
>>> commands.getstatusoutput('cat /bin/junk')
(256, 'cat: /bin/junk: No such file or directory')
>>> commands.getstatusoutput('/bin/junk')
(256, 'sh: /bin/junk: not found')
>>> commands.getoutput('ls /bin/ls')
'/bin/ls'
>>> commands.getstatus('/bin/ls')
'-rwxr-xr-x 1 root 13352 Oct 14 1994 /bin/ls'
.. seealso::
Module :mod:`subprocess`
Module for spawning and managing subprocesses.
PK %�\���>F F ( html/_sources/library/compileall.rst.txtnu �[��� :mod:`compileall` --- Byte-compile Python libraries
===================================================
.. module:: compileall
:synopsis: Tools for byte-compiling all Python source files in a directory tree.
**Source code:** :source:`Lib/compileall.py`
--------------
This module provides some utility functions to support installing Python
libraries. These functions compile Python source files in a directory tree.
This module can be used to create the cached byte-code files at library
installation time, which makes them available for use even by users who don't
have write permission to the library directories.
Command-line use
----------------
This module can work as a script (using :program:`python -m compileall`) to
compile Python sources.
.. program:: compileall
.. cmdoption:: directory ...
file ...
Positional arguments are files to compile or directories that contain
source files, traversed recursively. If no argument is given, behave as if
the command line was ``-l <directories from sys.path>``.
.. cmdoption:: -l
Do not recurse into subdirectories, only compile source code files directly
contained in the named or implied directories.
.. cmdoption:: -f
Force rebuild even if timestamps are up-to-date.
.. cmdoption:: -q
Do not print the list of files compiled, print only error messages.
.. cmdoption:: -d destdir
Directory prepended to the path to each file being compiled. This will
appear in compilation time tracebacks, and is also compiled in to the
byte-code file, where it will be used in tracebacks and other messages in
cases where the source file does not exist at the time the byte-code file is
executed.
.. cmdoption:: -x regex
regex is used to search the full path to each file considered for
compilation, and if the regex produces a match, the file is skipped.
.. cmdoption:: -i list
Read the file ``list`` and add each line that it contains to the list of
files and directories to compile. If ``list`` is ``-``, read lines from
``stdin``.
.. versionchanged:: 2.7
Added the ``-i`` option.
Public functions
----------------
.. function:: compile_dir(dir[, maxlevels[, ddir[, force[, rx[, quiet]]]]])
Recursively descend the directory tree named by *dir*, compiling all :file:`.py`
files along the way.
The *maxlevels* parameter is used to limit the depth of the recursion; it
defaults to ``10``.
If *ddir* is given, it is prepended to the path to each file being compiled
for use in compilation time tracebacks, and is also compiled in to the
byte-code file, where it will be used in tracebacks and other messages in
cases where the source file does not exist at the time the byte-code file is
executed.
If *force* is true, modules are re-compiled even if the timestamps are up to
date.
If *rx* is given, its search method is called on the complete path to each
file considered for compilation, and if it returns a true value, the file
is skipped.
If *quiet* is true, nothing is printed to the standard output unless errors
occur.
.. function:: compile_file(fullname[, ddir[, force[, rx[, quiet]]]])
Compile the file with path *fullname*.
If *ddir* is given, it is prepended to the path to the file being compiled
for use in compilation time tracebacks, and is also compiled in to the
byte-code file, where it will be used in tracebacks and other messages in
cases where the source file does not exist at the time the byte-code file is
executed.
If *rx* is given, its search method is passed the full path name to the
file being compiled, and if it returns a true value, the file is not
compiled and ``True`` is returned.
If *quiet* is true, nothing is printed to the standard output unless errors
occur.
.. versionadded:: 2.7
.. function:: compile_path([skip_curdir[, maxlevels[, force]]])
Byte-compile all the :file:`.py` files found along ``sys.path``. If
*skip_curdir* is true (the default), the current directory is not included
in the search. All other parameters are passed to the :func:`compile_dir`
function. Note that unlike the other compile functions, ``maxlevels``
defaults to ``0``.
To force a recompile of all the :file:`.py` files in the :file:`Lib/`
subdirectory and all its subdirectories::
import compileall
compileall.compile_dir('Lib/', force=True)
# Perform same compilation, excluding files in .svn directories.
import re
compileall.compile_dir('Lib/', rx=re.compile(r'[/\\][.]svn'), force=True)
.. seealso::
Module :mod:`py_compile`
Byte-compile a single source file.
PK %�\u�� X� X� & html/_sources/library/compiler.rst.txtnu �[���
.. _compiler:
***********************
Python compiler package
***********************
.. deprecated:: 2.6
The :mod:`compiler` package has been removed in Python 3.
.. sectionauthor:: Jeremy Hylton <jeremy@zope.com>
The Python compiler package is a tool for analyzing Python source code and
generating Python bytecode. The compiler contains libraries to generate an
abstract syntax tree from Python source code and to generate Python
:term:`bytecode` from the tree.
The :mod:`compiler` package is a Python source to bytecode translator written in
Python. It uses the built-in parser and standard :mod:`parser` module to
generate a concrete syntax tree. This tree is used to generate an abstract
syntax tree (AST) and then Python bytecode.
The full functionality of the package duplicates the built-in compiler provided
with the Python interpreter. It is intended to match its behavior almost
exactly. Why implement another compiler that does the same thing? The package
is useful for a variety of purposes. It can be modified more easily than the
built-in compiler. The AST it generates is useful for analyzing Python source
code.
This chapter explains how the various components of the :mod:`compiler` package
work. It blends reference material with a tutorial.
The basic interface
===================
.. module:: compiler
:synopsis: Python code compiler written in Python.
:deprecated:
The top-level of the package defines four functions. If you import
:mod:`compiler`, you will get these functions and a collection of modules
contained in the package.
.. function:: parse(buf)
Returns an abstract syntax tree for the Python source code in *buf*. The
function raises :exc:`SyntaxError` if there is an error in the source code. The
return value is a :class:`compiler.ast.Module` instance that contains the tree.
.. function:: parseFile(path)
Return an abstract syntax tree for the Python source code in the file specified
by *path*. It is equivalent to ``parse(open(path).read())``.
.. function:: walk(ast, visitor[, verbose])
Do a pre-order walk over the abstract syntax tree *ast*. Call the appropriate
method on the *visitor* instance for each node encountered.
.. function:: compile(source, filename, mode, flags=None, dont_inherit=None)
Compile the string *source*, a Python module, statement or expression, into a
code object that can be executed by the exec statement or :func:`eval`. This
function is a replacement for the built-in :func:`compile` function.
The *filename* will be used for run-time error messages.
The *mode* must be 'exec' to compile a module, 'single' to compile a single
(interactive) statement, or 'eval' to compile an expression.
The *flags* and *dont_inherit* arguments affect future-related statements, but
are not supported yet.
.. function:: compileFile(source)
Compiles the file *source* and generates a .pyc file.
The :mod:`compiler` package contains the following modules: :mod:`ast`,
:mod:`consts`, :mod:`future`, :mod:`misc`, :mod:`pyassem`, :mod:`pycodegen`,
:mod:`symbols`, :mod:`transformer`, and :mod:`visitor`.
Limitations
===========
There are some problems with the error checking of the compiler package. The
interpreter detects syntax errors in two distinct phases. One set of errors is
detected by the interpreter's parser, the other set by the compiler. The
compiler package relies on the interpreter's parser, so it get the first phases
of error checking for free. It implements the second phase itself, and that
implementation is incomplete. For example, the compiler package does not raise
an error if a name appears more than once in an argument list: ``def f(x, x):
...``
A future version of the compiler should fix these problems.
Python Abstract Syntax
======================
The :mod:`compiler.ast` module defines an abstract syntax for Python. In the
abstract syntax tree, each node represents a syntactic construct. The root of
the tree is :class:`Module` object.
The abstract syntax offers a higher level interface to parsed Python source
code. The :mod:`parser` module and the compiler written in C for the Python
interpreter use a concrete syntax tree. The concrete syntax is tied closely to
the grammar description used for the Python parser. Instead of a single node
for a construct, there are often several levels of nested nodes that are
introduced by Python's precedence rules.
The abstract syntax tree is created by the :mod:`compiler.transformer` module.
The transformer relies on the built-in Python parser to generate a concrete
syntax tree. It generates an abstract syntax tree from the concrete tree.
.. index::
single: Stein, Greg
single: Tutt, Bill
The :mod:`transformer` module was created by Greg Stein and Bill Tutt for an
experimental Python-to-C compiler. The current version contains a number of
modifications and improvements, but the basic form of the abstract syntax and of
the transformer are due to Stein and Tutt.
AST Nodes
---------
.. module:: compiler.ast
The :mod:`compiler.ast` module is generated from a text file that describes each
node type and its elements. Each node type is represented as a class that
inherits from the abstract base class :class:`compiler.ast.Node` and defines a
set of named attributes for child nodes.
.. class:: Node()
The :class:`Node` instances are created automatically by the parser generator.
The recommended interface for specific :class:`Node` instances is to use the
public attributes to access child nodes. A public attribute may be bound to a
single node or to a sequence of nodes, depending on the :class:`Node` type. For
example, the :attr:`bases` attribute of the :class:`Class` node, is bound to a
list of base class nodes, and the :attr:`doc` attribute is bound to a single
node.
Each :class:`Node` instance has a :attr:`lineno` attribute which may be
``None``. XXX Not sure what the rules are for which nodes will have a useful
lineno.
All :class:`Node` objects offer the following methods:
.. method:: getChildren()
Returns a flattened list of the child nodes and objects in the order they
occur. Specifically, the order of the nodes is the order in which they
appear in the Python grammar. Not all of the children are :class:`Node`
instances. The names of functions and classes, for example, are plain
strings.
.. method:: getChildNodes()
Returns a flattened list of the child nodes in the order they occur. This
method is like :meth:`getChildren`, except that it only returns those
children that are :class:`Node` instances.
Two examples illustrate the general structure of :class:`Node` classes. The
:keyword:`while` statement is defined by the following grammar production::
while_stmt: "while" expression ":" suite
["else" ":" suite]
The :class:`While` node has three attributes: :attr:`test`, :attr:`body`, and
:attr:`else_`. (If the natural name for an attribute is also a Python reserved
word, it can't be used as an attribute name. An underscore is appended to the
word to make it a legal identifier, hence :attr:`else_` instead of
:keyword:`else`.)
The :keyword:`if` statement is more complicated because it can include several
tests. ::
if_stmt: 'if' test ':' suite ('elif' test ':' suite)* ['else' ':' suite]
The :class:`If` node only defines two attributes: :attr:`tests` and
:attr:`else_`. The :attr:`tests` attribute is a sequence of test expression,
consequent body pairs. There is one pair for each :keyword:`if`/:keyword:`elif`
clause. The first element of the pair is the test expression. The second
elements is a :class:`Stmt` node that contains the code to execute if the test
is true.
The :meth:`getChildren` method of :class:`If` returns a flat list of child
nodes. If there are three :keyword:`if`/:keyword:`elif` clauses and no
:keyword:`else` clause, then :meth:`getChildren` will return a list of six
elements: the first test expression, the first :class:`Stmt`, the second text
expression, etc.
The following table lists each of the :class:`Node` subclasses defined in
:mod:`compiler.ast` and each of the public attributes available on their
instances. The values of most of the attributes are themselves :class:`Node`
instances or sequences of instances. When the value is something other than an
instance, the type is noted in the comment. The attributes are listed in the
order in which they are returned by :meth:`getChildren` and
:meth:`getChildNodes`.
+-----------------------+--------------------+---------------------------------+
| Node type | Attribute | Value |
+=======================+====================+=================================+
| :class:`Add` | :attr:`left` | left operand |
+-----------------------+--------------------+---------------------------------+
| | :attr:`right` | right operand |
+-----------------------+--------------------+---------------------------------+
| :class:`And` | :attr:`nodes` | list of operands |
+-----------------------+--------------------+---------------------------------+
| :class:`AssAttr` | | *attribute as target of |
| | | assignment* |
+-----------------------+--------------------+---------------------------------+
| | :attr:`expr` | expression on the left-hand |
| | | side of the dot |
+-----------------------+--------------------+---------------------------------+
| | :attr:`attrname` | the attribute name, a string |
+-----------------------+--------------------+---------------------------------+
| | :attr:`flags` | XXX |
+-----------------------+--------------------+---------------------------------+
| :class:`AssList` | :attr:`nodes` | list of list elements being |
| | | assigned to |
+-----------------------+--------------------+---------------------------------+
| :class:`AssName` | :attr:`name` | name being assigned to |
+-----------------------+--------------------+---------------------------------+
| | :attr:`flags` | XXX |
+-----------------------+--------------------+---------------------------------+
| :class:`AssTuple` | :attr:`nodes` | list of tuple elements being |
| | | assigned to |
+-----------------------+--------------------+---------------------------------+
| :class:`Assert` | :attr:`test` | the expression to be tested |
+-----------------------+--------------------+---------------------------------+
| | :attr:`fail` | the value of the |
| | | :exc:`AssertionError` |
+-----------------------+--------------------+---------------------------------+
| :class:`Assign` | :attr:`nodes` | a list of assignment targets, |
| | | one per equal sign |
+-----------------------+--------------------+---------------------------------+
| | :attr:`expr` | the value being assigned |
+-----------------------+--------------------+---------------------------------+
| :class:`AugAssign` | :attr:`node` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`op` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`expr` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Backquote` | :attr:`expr` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Bitand` | :attr:`nodes` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Bitor` | :attr:`nodes` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Bitxor` | :attr:`nodes` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Break` | | |
+-----------------------+--------------------+---------------------------------+
| :class:`CallFunc` | :attr:`node` | expression for the callee |
+-----------------------+--------------------+---------------------------------+
| | :attr:`args` | a list of arguments |
+-----------------------+--------------------+---------------------------------+
| | :attr:`star_args` | the extended \*-arg value |
+-----------------------+--------------------+---------------------------------+
| | :attr:`dstar_args` | the extended \*\*-arg value |
+-----------------------+--------------------+---------------------------------+
| :class:`Class` | :attr:`name` | the name of the class, a string |
+-----------------------+--------------------+---------------------------------+
| | :attr:`bases` | a list of base classes |
+-----------------------+--------------------+---------------------------------+
| | :attr:`doc` | doc string, a string or |
| | | ``None`` |
+-----------------------+--------------------+---------------------------------+
| | :attr:`code` | the body of the class statement |
+-----------------------+--------------------+---------------------------------+
| :class:`Compare` | :attr:`expr` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`ops` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Const` | :attr:`value` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Continue` | | |
+-----------------------+--------------------+---------------------------------+
| :class:`Decorators` | :attr:`nodes` | List of function decorator |
| | | expressions |
+-----------------------+--------------------+---------------------------------+
| :class:`Dict` | :attr:`items` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Discard` | :attr:`expr` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Div` | :attr:`left` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`right` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Ellipsis` | | |
+-----------------------+--------------------+---------------------------------+
| :class:`Expression` | :attr:`node` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Exec` | :attr:`expr` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`locals` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`globals` | |
+-----------------------+--------------------+---------------------------------+
| :class:`FloorDiv` | :attr:`left` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`right` | |
+-----------------------+--------------------+---------------------------------+
| :class:`For` | :attr:`assign` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`list` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`body` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`else_` | |
+-----------------------+--------------------+---------------------------------+
| :class:`From` | :attr:`modname` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`names` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Function` | :attr:`decorators` | :class:`Decorators` or ``None`` |
+-----------------------+--------------------+---------------------------------+
| | :attr:`name` | name used in def, a string |
+-----------------------+--------------------+---------------------------------+
| | :attr:`argnames` | list of argument names, as |
| | | strings |
+-----------------------+--------------------+---------------------------------+
| | :attr:`defaults` | list of default values |
+-----------------------+--------------------+---------------------------------+
| | :attr:`flags` | xxx |
+-----------------------+--------------------+---------------------------------+
| | :attr:`doc` | doc string, a string or |
| | | ``None`` |
+-----------------------+--------------------+---------------------------------+
| | :attr:`code` | the body of the function |
+-----------------------+--------------------+---------------------------------+
| :class:`GenExpr` | :attr:`code` | |
+-----------------------+--------------------+---------------------------------+
| :class:`GenExprFor` | :attr:`assign` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`iter` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`ifs` | |
+-----------------------+--------------------+---------------------------------+
| :class:`GenExprIf` | :attr:`test` | |
+-----------------------+--------------------+---------------------------------+
| :class:`GenExprInner` | :attr:`expr` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`quals` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Getattr` | :attr:`expr` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`attrname` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Global` | :attr:`names` | |
+-----------------------+--------------------+---------------------------------+
| :class:`If` | :attr:`tests` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`else_` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Import` | :attr:`names` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Invert` | :attr:`expr` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Keyword` | :attr:`name` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`expr` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Lambda` | :attr:`argnames` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`defaults` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`flags` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`code` | |
+-----------------------+--------------------+---------------------------------+
| :class:`LeftShift` | :attr:`left` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`right` | |
+-----------------------+--------------------+---------------------------------+
| :class:`List` | :attr:`nodes` | |
+-----------------------+--------------------+---------------------------------+
| :class:`ListComp` | :attr:`expr` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`quals` | |
+-----------------------+--------------------+---------------------------------+
| :class:`ListCompFor` | :attr:`assign` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`list` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`ifs` | |
+-----------------------+--------------------+---------------------------------+
| :class:`ListCompIf` | :attr:`test` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Mod` | :attr:`left` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`right` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Module` | :attr:`doc` | doc string, a string or |
| | | ``None`` |
+-----------------------+--------------------+---------------------------------+
| | :attr:`node` | body of the module, a |
| | | :class:`Stmt` |
+-----------------------+--------------------+---------------------------------+
| :class:`Mul` | :attr:`left` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`right` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Name` | :attr:`name` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Not` | :attr:`expr` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Or` | :attr:`nodes` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Pass` | | |
+-----------------------+--------------------+---------------------------------+
| :class:`Power` | :attr:`left` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`right` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Print` | :attr:`nodes` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`dest` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Printnl` | :attr:`nodes` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`dest` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Raise` | :attr:`expr1` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`expr2` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`expr3` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Return` | :attr:`value` | |
+-----------------------+--------------------+---------------------------------+
| :class:`RightShift` | :attr:`left` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`right` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Slice` | :attr:`expr` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`flags` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`lower` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`upper` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Sliceobj` | :attr:`nodes` | list of statements |
+-----------------------+--------------------+---------------------------------+
| :class:`Stmt` | :attr:`nodes` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Sub` | :attr:`left` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`right` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Subscript` | :attr:`expr` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`flags` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`subs` | |
+-----------------------+--------------------+---------------------------------+
| :class:`TryExcept` | :attr:`body` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`handlers` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`else_` | |
+-----------------------+--------------------+---------------------------------+
| :class:`TryFinally` | :attr:`body` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`final` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Tuple` | :attr:`nodes` | |
+-----------------------+--------------------+---------------------------------+
| :class:`UnaryAdd` | :attr:`expr` | |
+-----------------------+--------------------+---------------------------------+
| :class:`UnarySub` | :attr:`expr` | |
+-----------------------+--------------------+---------------------------------+
| :class:`While` | :attr:`test` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`body` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`else_` | |
+-----------------------+--------------------+---------------------------------+
| :class:`With` | :attr:`expr` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`vars` | |
+-----------------------+--------------------+---------------------------------+
| | :attr:`body` | |
+-----------------------+--------------------+---------------------------------+
| :class:`Yield` | :attr:`value` | |
+-----------------------+--------------------+---------------------------------+
Assignment nodes
----------------
There is a collection of nodes used to represent assignments. Each assignment
statement in the source code becomes a single :class:`Assign` node in the AST.
The :attr:`nodes` attribute is a list that contains a node for each assignment
target. This is necessary because assignment can be chained, e.g. ``a = b =
2``. Each :class:`Node` in the list will be one of the following classes:
:class:`AssAttr`, :class:`AssList`, :class:`AssName`, or :class:`AssTuple`.
Each target assignment node will describe the kind of object being assigned to:
:class:`AssName` for a simple name, e.g. ``a = 1``. :class:`AssAttr` for an
attribute assigned, e.g. ``a.x = 1``. :class:`AssList` and :class:`AssTuple` for
list and tuple expansion respectively, e.g. ``a, b, c = a_tuple``.
The target assignment nodes also have a :attr:`flags` attribute that indicates
whether the node is being used for assignment or in a delete statement. The
:class:`AssName` is also used to represent a delete statement, e.g. :class:`del
x`.
When an expression contains several attribute references, an assignment or
delete statement will contain only one :class:`AssAttr` node -- for the final
attribute reference. The other attribute references will be represented as
:class:`Getattr` nodes in the :attr:`expr` attribute of the :class:`AssAttr`
instance.
Examples
--------
This section shows several simple examples of ASTs for Python source code. The
examples demonstrate how to use the :func:`parse` function, what the repr of an
AST looks like, and how to access attributes of an AST node.
The first module defines a single function. Assume it is stored in
:file:`doublelib.py`. ::
"""This is an example module.
This is the docstring.
"""
def double(x):
"Return twice the argument"
return x * 2
In the interactive interpreter session below, I have reformatted the long AST
reprs for readability. The AST reprs use unqualified class names. If you want
to create an instance from a repr, you must import the class names from the
:mod:`compiler.ast` module. ::
>>> import compiler
>>> mod = compiler.parseFile("doublelib.py")
>>> mod
Module('This is an example module.\n\nThis is the docstring.\n',
Stmt([Function(None, 'double', ['x'], [], 0,
'Return twice the argument',
Stmt([Return(Mul((Name('x'), Const(2))))]))]))
>>> from compiler.ast import *
>>> Module('This is an example module.\n\nThis is the docstring.\n',
... Stmt([Function(None, 'double', ['x'], [], 0,
... 'Return twice the argument',
... Stmt([Return(Mul((Name('x'), Const(2))))]))]))
Module('This is an example module.\n\nThis is the docstring.\n',
Stmt([Function(None, 'double', ['x'], [], 0,
'Return twice the argument',
Stmt([Return(Mul((Name('x'), Const(2))))]))]))
>>> mod.doc
'This is an example module.\n\nThis is the docstring.\n'
>>> for node in mod.node.nodes:
... print node
...
Function(None, 'double', ['x'], [], 0, 'Return twice the argument',
Stmt([Return(Mul((Name('x'), Const(2))))]))
>>> func = mod.node.nodes[0]
>>> func.code
Stmt([Return(Mul((Name('x'), Const(2))))])
Using Visitors to Walk ASTs
===========================
.. module:: compiler.visitor
The visitor pattern is ... The :mod:`compiler` package uses a variant on the
visitor pattern that takes advantage of Python's introspection features to
eliminate the need for much of the visitor's infrastructure.
The classes being visited do not need to be programmed to accept visitors. The
visitor need only define visit methods for classes it is specifically interested
in; a default visit method can handle the rest.
XXX The magic :meth:`visit` method for visitors.
.. function:: walk(tree, visitor[, verbose])
.. class:: ASTVisitor()
The :class:`ASTVisitor` is responsible for walking over the tree in the correct
order. A walk begins with a call to :meth:`preorder`. For each node, it checks
the *visitor* argument to :meth:`preorder` for a method named 'visitNodeType,'
where NodeType is the name of the node's class, e.g. for a :class:`While` node a
:meth:`visitWhile` would be called. If the method exists, it is called with the
node as its first argument.
The visitor method for a particular node type can control how child nodes are
visited during the walk. The :class:`ASTVisitor` modifies the visitor argument
by adding a visit method to the visitor; this method can be used to visit a
particular child node. If no visitor is found for a particular node type, the
:meth:`default` method is called.
:class:`ASTVisitor` objects have the following methods:
XXX describe extra arguments
.. method:: default(node[, ...])
.. method:: dispatch(node[, ...])
.. method:: preorder(tree, visitor)
Bytecode Generation
===================
The code generator is a visitor that emits bytecodes. Each visit method can
call the :meth:`emit` method to emit a new bytecode. The basic code generator
is specialized for modules, classes, and functions. An assembler converts that
emitted instructions to the low-level bytecode format. It handles things like
generation of constant lists of code objects and calculation of jump offsets.
PK %�\$s�r�L �L * html/_sources/library/configparser.rst.txtnu �[��� :mod:`ConfigParser` --- Configuration file parser
=================================================
.. module:: ConfigParser
:synopsis: Configuration file parser.
.. moduleauthor:: Ken Manheimer <klm@zope.com>
.. moduleauthor:: Barry Warsaw <bwarsaw@python.org>
.. moduleauthor:: Eric S. Raymond <esr@thyrsus.com>
.. sectionauthor:: Christopher G. Petrilli <petrilli@amber.org>
.. note::
The :mod:`ConfigParser` module has been renamed to :mod:`configparser` in
Python 3. The :term:`2to3` tool will automatically adapt imports when
converting your sources to Python 3.
.. index::
pair: .ini; file
pair: configuration; file
single: ini file
single: Windows ini file
This module defines the class :class:`~ConfigParser.ConfigParser`. The :class:`~ConfigParser.ConfigParser`
class implements a basic configuration file parser language which provides a
structure similar to what you would find on Microsoft Windows INI files. You
can use this to write Python programs which can be customized by end users
easily.
.. note::
This library does *not* interpret or write the value-type prefixes used in
the Windows Registry extended version of INI syntax.
.. seealso::
Module :mod:`shlex`
Support for creating Unix shell-like mini-languages which can be used as
an alternate format for application configuration files.
Module :mod:`json`
The json module implements a subset of JavaScript syntax which can also
be used for this purpose.
The configuration file consists of sections, led by a ``[section]`` header and
followed by ``name: value`` entries, with continuations in the style of
:rfc:`822` (see section 3.1.1, "LONG HEADER FIELDS"); ``name=value`` is also
accepted. Note that leading whitespace is removed from values. The optional
values can contain format strings which refer to other values in the same
section, or values in a special ``DEFAULT`` section. Additional defaults can be
provided on initialization and retrieval. Lines beginning with ``'#'`` or
``';'`` are ignored and may be used to provide comments.
Configuration files may include comments, prefixed by specific characters (``#``
and ``;``). Comments may appear on their own in an otherwise empty line, or may
be entered in lines holding values or section names. In the latter case, they
need to be preceded by a whitespace character to be recognized as a comment.
(For backwards compatibility, only ``;`` starts an inline comment, while ``#``
does not.)
On top of the core functionality, :class:`SafeConfigParser` supports
interpolation. This means values can contain format strings which refer to
other values in the same section, or values in a special ``DEFAULT`` section.
Additional defaults can be provided on initialization.
For example::
[My Section]
foodir: %(dir)s/whatever
dir=frob
long: this value continues
in the next line
would resolve the ``%(dir)s`` to the value of ``dir`` (``frob`` in this case).
All reference expansions are done on demand.
Default values can be specified by passing them into the :class:`~ConfigParser.ConfigParser`
constructor as a dictionary. Additional defaults may be passed into the
:meth:`get` method which will override all others.
Sections are normally stored in a built-in dictionary. An alternative dictionary
type can be passed to the :class:`~ConfigParser.ConfigParser` constructor. For example, if a
dictionary type is passed that sorts its keys, the sections will be sorted on
write-back, as will be the keys within each section.
.. class:: RawConfigParser([defaults[, dict_type[, allow_no_value]]])
The basic configuration object. When *defaults* is given, it is initialized
into the dictionary of intrinsic defaults. When *dict_type* is given, it will
be used to create the dictionary objects for the list of sections, for the
options within a section, and for the default values. When *allow_no_value*
is true (default: ``False``), options without values are accepted; the value
presented for these is ``None``.
This class does not
support the magical interpolation behavior.
All option names are passed through the :meth:`optionxform` method. Its
default implementation converts option names to lower case.
.. versionadded:: 2.3
.. versionchanged:: 2.6
*dict_type* was added.
.. versionchanged:: 2.7
The default *dict_type* is :class:`collections.OrderedDict`.
*allow_no_value* was added.
.. class:: ConfigParser([defaults[, dict_type[, allow_no_value]]])
Derived class of :class:`RawConfigParser` that implements the magical
interpolation feature and adds optional arguments to the :meth:`get` and
:meth:`items` methods. The values in *defaults* must be appropriate for the
``%()s`` string interpolation. Note that *__name__* is an intrinsic default;
its value is the section name, and will override any value provided in
*defaults*.
All option names used in interpolation will be passed through the
:meth:`optionxform` method just like any other option name reference. Using
the default implementation of :meth:`optionxform`, the values ``foo %(bar)s``
and ``foo %(BAR)s`` are equivalent.
.. versionadded:: 2.3
.. versionchanged:: 2.6
*dict_type* was added.
.. versionchanged:: 2.7
The default *dict_type* is :class:`collections.OrderedDict`.
*allow_no_value* was added.
.. class:: SafeConfigParser([defaults[, dict_type[, allow_no_value]]])
Derived class of :class:`~ConfigParser.ConfigParser` that implements a more-sane variant of
the magical interpolation feature. This implementation is more predictable as
well. New applications should prefer this version if they don't need to be
compatible with older versions of Python.
.. XXX Need to explain what's safer/more predictable about it.
.. versionadded:: 2.3
.. versionchanged:: 2.6
*dict_type* was added.
.. versionchanged:: 2.7
The default *dict_type* is :class:`collections.OrderedDict`.
*allow_no_value* was added.
.. exception:: Error
Base class for all other configparser exceptions.
.. exception:: NoSectionError
Exception raised when a specified section is not found.
.. exception:: DuplicateSectionError
Exception raised if :meth:`add_section` is called with the name of a section
that is already present.
.. exception:: NoOptionError
Exception raised when a specified option is not found in the specified section.
.. exception:: InterpolationError
Base class for exceptions raised when problems occur performing string
interpolation.
.. exception:: InterpolationDepthError
Exception raised when string interpolation cannot be completed because the
number of iterations exceeds :const:`MAX_INTERPOLATION_DEPTH`. Subclass of
:exc:`InterpolationError`.
.. exception:: InterpolationMissingOptionError
Exception raised when an option referenced from a value does not exist. Subclass
of :exc:`InterpolationError`.
.. versionadded:: 2.3
.. exception:: InterpolationSyntaxError
Exception raised when the source text into which substitutions are made does not
conform to the required syntax. Subclass of :exc:`InterpolationError`.
.. versionadded:: 2.3
.. exception:: MissingSectionHeaderError
Exception raised when attempting to parse a file which has no section headers.
.. exception:: ParsingError
Exception raised when errors occur attempting to parse a file.
.. data:: MAX_INTERPOLATION_DEPTH
The maximum depth for recursive interpolation for :meth:`get` when the *raw*
parameter is false. This is relevant only for the :class:`~ConfigParser.ConfigParser` class.
.. seealso::
Module :mod:`shlex`
Support for a creating Unix shell-like mini-languages which can be used as an
alternate format for application configuration files.
.. _rawconfigparser-objects:
RawConfigParser Objects
-----------------------
:class:`RawConfigParser` instances have the following methods:
.. method:: RawConfigParser.defaults()
Return a dictionary containing the instance-wide defaults.
.. method:: RawConfigParser.sections()
Return a list of the sections available; ``DEFAULT`` is not included in the
list.
.. method:: RawConfigParser.add_section(section)
Add a section named *section* to the instance. If a section by the given name
already exists, :exc:`DuplicateSectionError` is raised. If the name
``DEFAULT`` (or any of it's case-insensitive variants) is passed,
:exc:`ValueError` is raised.
.. method:: RawConfigParser.has_section(section)
Indicates whether the named section is present in the configuration. The
``DEFAULT`` section is not acknowledged.
.. method:: RawConfigParser.options(section)
Returns a list of options available in the specified *section*.
.. method:: RawConfigParser.has_option(section, option)
If the given section exists, and contains the given option, return
:const:`True`; otherwise return :const:`False`.
.. versionadded:: 1.6
.. method:: RawConfigParser.read(filenames)
Attempt to read and parse a list of filenames, returning a list of filenames
which were successfully parsed. If *filenames* is a string or Unicode string,
it is treated as a single filename. If a file named in *filenames* cannot be
opened, that file will be ignored. This is designed so that you can specify a
list of potential configuration file locations (for example, the current
directory, the user's home directory, and some system-wide directory), and all
existing configuration files in the list will be read. If none of the named
files exist, the :class:`~ConfigParser.ConfigParser` instance will contain an empty dataset.
An application which requires initial values to be loaded from a file should
load the required file or files using :meth:`readfp` before calling :meth:`read`
for any optional files::
import ConfigParser, os
config = ConfigParser.ConfigParser()
config.readfp(open('defaults.cfg'))
config.read(['site.cfg', os.path.expanduser('~/.myapp.cfg')])
.. versionchanged:: 2.4
Returns list of successfully parsed filenames.
.. method:: RawConfigParser.readfp(fp[, filename])
Read and parse configuration data from the file or file-like object in *fp*
(only the :meth:`readline` method is used). If *filename* is omitted and *fp*
has a :attr:`name` attribute, that is used for *filename*; the default is
``<???>``.
.. method:: RawConfigParser.get(section, option)
Get an *option* value for the named *section*.
.. method:: RawConfigParser.getint(section, option)
A convenience method which coerces the *option* in the specified *section* to an
integer.
.. method:: RawConfigParser.getfloat(section, option)
A convenience method which coerces the *option* in the specified *section* to a
floating point number.
.. method:: RawConfigParser.getboolean(section, option)
A convenience method which coerces the *option* in the specified *section* to a
Boolean value. Note that the accepted values for the option are ``"1"``,
``"yes"``, ``"true"``, and ``"on"``, which cause this method to return ``True``,
and ``"0"``, ``"no"``, ``"false"``, and ``"off"``, which cause it to return
``False``. These string values are checked in a case-insensitive manner. Any
other value will cause it to raise :exc:`ValueError`.
.. method:: RawConfigParser.items(section)
Return a list of ``(name, value)`` pairs for each option in the given *section*.
.. method:: RawConfigParser.set(section, option, value)
If the given section exists, set the given option to the specified value;
otherwise raise :exc:`NoSectionError`. While it is possible to use
:class:`RawConfigParser` (or :class:`~ConfigParser.ConfigParser` with *raw* parameters set to
true) for *internal* storage of non-string values, full functionality (including
interpolation and output to files) can only be achieved using string values.
.. versionadded:: 1.6
.. method:: RawConfigParser.write(fileobject)
Write a representation of the configuration to the specified file object. This
representation can be parsed by a future :meth:`read` call.
.. versionadded:: 1.6
.. method:: RawConfigParser.remove_option(section, option)
Remove the specified *option* from the specified *section*. If the section does
not exist, raise :exc:`NoSectionError`. If the option existed to be removed,
return :const:`True`; otherwise return :const:`False`.
.. versionadded:: 1.6
.. method:: RawConfigParser.remove_section(section)
Remove the specified *section* from the configuration. If the section in fact
existed, return ``True``. Otherwise return ``False``.
.. method:: RawConfigParser.optionxform(option)
Transforms the option name *option* as found in an input file or as passed in
by client code to the form that should be used in the internal structures.
The default implementation returns a lower-case version of *option*;
subclasses may override this or client code can set an attribute of this name
on instances to affect this behavior.
You don't necessarily need to subclass a ConfigParser to use this method, you
can also re-set it on an instance, to a function that takes a string
argument. Setting it to ``str``, for example, would make option names case
sensitive::
cfgparser = ConfigParser()
...
cfgparser.optionxform = str
Note that when reading configuration files, whitespace around the
option names are stripped before :meth:`optionxform` is called.
.. _configparser-objects:
ConfigParser Objects
--------------------
The :class:`~ConfigParser.ConfigParser` class extends some methods of the
:class:`RawConfigParser` interface, adding some optional arguments.
.. method:: ConfigParser.get(section, option[, raw[, vars]])
Get an *option* value for the named *section*. If *vars* is provided, it
must be a dictionary. The *option* is looked up in *vars* (if provided),
*section*, and in *defaults* in that order.
All the ``'%'`` interpolations are expanded in the return values, unless the
*raw* argument is true. Values for interpolation keys are looked up in the
same manner as the option.
.. method:: ConfigParser.items(section[, raw[, vars]])
Return a list of ``(name, value)`` pairs for each option in the given *section*.
Optional arguments have the same meaning as for the :meth:`get` method.
.. versionadded:: 2.3
.. _safeconfigparser-objects:
SafeConfigParser Objects
------------------------
The :class:`SafeConfigParser` class implements the same extended interface as
:class:`~ConfigParser.ConfigParser`, with the following addition:
.. method:: SafeConfigParser.set(section, option, value)
If the given section exists, set the given option to the specified value;
otherwise raise :exc:`NoSectionError`. *value* must be a string (:class:`str`
or :class:`unicode`); if not, :exc:`TypeError` is raised.
.. versionadded:: 2.4
Examples
--------
An example of writing to a configuration file::
import ConfigParser
config = ConfigParser.RawConfigParser()
# When adding sections or items, add them in the reverse order of
# how you want them to be displayed in the actual file.
# In addition, please note that using RawConfigParser's and the raw
# mode of ConfigParser's respective set functions, you can assign
# non-string values to keys internally, but will receive an error
# when attempting to write to a file or when you get it in non-raw
# mode. SafeConfigParser does not allow such assignments to take place.
config.add_section('Section1')
config.set('Section1', 'an_int', '15')
config.set('Section1', 'a_bool', 'true')
config.set('Section1', 'a_float', '3.1415')
config.set('Section1', 'baz', 'fun')
config.set('Section1', 'bar', 'Python')
config.set('Section1', 'foo', '%(bar)s is %(baz)s!')
# Writing our configuration file to 'example.cfg'
with open('example.cfg', 'wb') as configfile:
config.write(configfile)
An example of reading the configuration file again::
import ConfigParser
config = ConfigParser.RawConfigParser()
config.read('example.cfg')
# getfloat() raises an exception if the value is not a float
# getint() and getboolean() also do this for their respective types
a_float = config.getfloat('Section1', 'a_float')
an_int = config.getint('Section1', 'an_int')
print a_float + an_int
# Notice that the next output does not interpolate '%(bar)s' or '%(baz)s'.
# This is because we are using a RawConfigParser().
if config.getboolean('Section1', 'a_bool'):
print config.get('Section1', 'foo')
To get interpolation, you will need to use a :class:`~ConfigParser.ConfigParser` or
:class:`SafeConfigParser`::
import ConfigParser
config = ConfigParser.ConfigParser()
config.read('example.cfg')
# Set the third, optional argument of get to 1 if you wish to use raw mode.
print config.get('Section1', 'foo', 0) # -> "Python is fun!"
print config.get('Section1', 'foo', 1) # -> "%(bar)s is %(baz)s!"
# The optional fourth argument is a dict with members that will take
# precedence in interpolation.
print config.get('Section1', 'foo', 0, {'bar': 'Documentation',
'baz': 'evil'})
Defaults are available in all three types of ConfigParsers. They are used in
interpolation if an option used is not defined elsewhere. ::
import ConfigParser
# New instance with 'bar' and 'baz' defaulting to 'Life' and 'hard' each
config = ConfigParser.SafeConfigParser({'bar': 'Life', 'baz': 'hard'})
config.read('example.cfg')
print config.get('Section1', 'foo') # -> "Python is fun!"
config.remove_option('Section1', 'bar')
config.remove_option('Section1', 'baz')
print config.get('Section1', 'foo') # -> "Life is hard!"
The function ``opt_move`` below can be used to move options between sections::
def opt_move(config, section1, section2, option):
try:
config.set(section2, option, config.get(section1, option, 1))
except ConfigParser.NoSectionError:
# Create non-existent section
config.add_section(section2)
opt_move(config, section1, section2, option)
else:
config.remove_option(section1, option)
Some configuration files are known to include settings without values, but which
otherwise conform to the syntax supported by :mod:`ConfigParser`. The
*allow_no_value* parameter to the constructor can be used to indicate that such
values should be accepted:
.. doctest::
>>> import ConfigParser
>>> import io
>>> sample_config = """
... [mysqld]
... user = mysql
... pid-file = /var/run/mysqld/mysqld.pid
... skip-external-locking
... old_passwords = 1
... skip-bdb
... skip-innodb
... """
>>> config = ConfigParser.RawConfigParser(allow_no_value=True)
>>> config.readfp(io.BytesIO(sample_config))
>>> # Settings with values are treated as before:
>>> config.get("mysqld", "user")
'mysql'
>>> # Settings without values provide None:
>>> config.get("mysqld", "skip-bdb")
>>> # Settings which aren't specified still raise an error:
>>> config.get("mysqld", "does-not-exist")
Traceback (most recent call last):
...
ConfigParser.NoOptionError: No option 'does-not-exist' in section: 'mysqld'
PK %�\"G�3 ' html/_sources/library/constants.rst.txtnu �[��� .. _built-in-consts:
Built-in Constants
==================
A small number of constants live in the built-in namespace. They are:
.. data:: False
The false value of the :class:`bool` type.
.. versionadded:: 2.3
.. data:: True
The true value of the :class:`bool` type.
.. versionadded:: 2.3
.. data:: None
The sole value of :attr:`types.NoneType`. ``None`` is frequently used to
represent the absence of a value, as when default arguments are not passed to a
function.
.. versionchanged:: 2.4
Assignments to ``None`` are illegal and raise a :exc:`SyntaxError`.
.. data:: NotImplemented
Special value which can be returned by the "rich comparison" special methods
(:meth:`__eq__`, :meth:`__lt__`, and friends), to indicate that the comparison
is not implemented with respect to the other type.
.. data:: Ellipsis
Special value used in conjunction with extended slicing syntax.
.. data:: __debug__
This constant is true if Python was not started with an :option:`-O` option.
See also the :keyword:`assert` statement.
.. note::
The names :data:`None` and :data:`__debug__` cannot be reassigned
(assignments to them, even as an attribute name, raise :exc:`SyntaxError`),
so they can be considered "true" constants.
.. versionchanged:: 2.7
Assignments to ``__debug__`` as an attribute became illegal.
Constants added by the :mod:`site` module
-----------------------------------------
The :mod:`site` module (which is imported automatically during startup, except
if the :option:`-S` command-line option is given) adds several constants to the
built-in namespace. They are useful for the interactive interpreter shell and
should not be used in programs.
.. data:: quit([code=None])
exit([code=None])
Objects that when printed, print a message like "Use quit() or Ctrl-D
(i.e. EOF) to exit", and when called, raise :exc:`SystemExit` with the
specified exit code.
.. data:: copyright
credits
Objects that when printed or called, print the text of copyright or
credits, respectively.
.. data:: license
Object that when printed, prints the message "Type license() to see the
full license text", and when called, displays the full license text in a
pager-like fashion (one screen at a time).
PK %�\;?L | | ( html/_sources/library/contextlib.rst.txtnu �[��� :mod:`contextlib` --- Utilities for :keyword:`with`\ -statement contexts
========================================================================
.. module:: contextlib
:synopsis: Utilities for with-statement contexts.
.. versionadded:: 2.5
**Source code:** :source:`Lib/contextlib.py`
--------------
This module provides utilities for common tasks involving the :keyword:`with`
statement. For more information see also :ref:`typecontextmanager` and
:ref:`context-managers`.
Functions provided:
.. function:: contextmanager(func)
This function is a :term:`decorator` that can be used to define a factory
function for :keyword:`with` statement context managers, without needing to
create a class or separate :meth:`__enter__` and :meth:`__exit__` methods.
While many objects natively support use in with statements, sometimes a
resource needs to be managed that isn't a context manager in its own right,
and doesn't implement a ``close()`` method for use with ``contextlib.closing``
An abstract example would be the following to ensure correct resource
management::
from contextlib import contextmanager
@contextmanager
def managed_resource(*args, **kwds):
# Code to acquire resource, e.g.:
resource = acquire_resource(*args, **kwds)
try:
yield resource
finally:
# Code to release resource, e.g.:
release_resource(resource)
>>> with managed_resource(timeout=3600) as resource:
... # Resource is released at the end of this block,
... # even if code in the block raises an exception
The function being decorated must return a :term:`generator`-iterator when
called. This iterator must yield exactly one value, which will be bound to
the targets in the :keyword:`with` statement's :keyword:`as` clause, if any.
At the point where the generator yields, the block nested in the :keyword:`with`
statement is executed. The generator is then resumed after the block is exited.
If an unhandled exception occurs in the block, it is reraised inside the
generator at the point where the yield occurred. Thus, you can use a
:keyword:`try`...\ :keyword:`except`...\ :keyword:`finally` statement to trap
the error (if any), or ensure that some cleanup takes place. If an exception is
trapped merely in order to log it or to perform some action (rather than to
suppress it entirely), the generator must reraise that exception. Otherwise the
generator context manager will indicate to the :keyword:`with` statement that
the exception has been handled, and execution will resume with the statement
immediately following the :keyword:`with` statement.
.. function:: nested(mgr1[, mgr2[, ...]])
Combine multiple context managers into a single nested context manager.
This function has been deprecated in favour of the multiple manager form
of the :keyword:`with` statement.
The one advantage of this function over the multiple manager form of the
:keyword:`with` statement is that argument unpacking allows it to be
used with a variable number of context managers as follows::
from contextlib import nested
with nested(*managers):
do_something()
Note that if the :meth:`__exit__` method of one of the nested context managers
indicates an exception should be suppressed, no exception information will be
passed to any remaining outer context managers. Similarly, if the
:meth:`__exit__` method of one of the nested managers raises an exception, any
previous exception state will be lost; the new exception will be passed to the
:meth:`__exit__` methods of any remaining outer context managers. In general,
:meth:`__exit__` methods should avoid raising exceptions, and in particular they
should not re-raise a passed-in exception.
This function has two major quirks that have led to it being deprecated. Firstly,
as the context managers are all constructed before the function is invoked, the
:meth:`__new__` and :meth:`__init__` methods of the inner context managers are
not actually covered by the scope of the outer context managers. That means, for
example, that using :func:`nested` to open two files is a programming error as the
first file will not be closed promptly if an exception is thrown when opening
the second file.
Secondly, if the :meth:`__enter__` method of one of the inner context managers
raises an exception that is caught and suppressed by the :meth:`__exit__` method
of one of the outer context managers, this construct will raise
:exc:`RuntimeError` rather than skipping the body of the :keyword:`with`
statement.
Developers that need to support nesting of a variable number of context managers
can either use the :mod:`warnings` module to suppress the DeprecationWarning
raised by this function or else use this function as a model for an application
specific implementation.
.. deprecated:: 2.7
The with-statement now supports this functionality directly (without the
confusing error prone quirks).
.. function:: closing(thing)
Return a context manager that closes *thing* upon completion of the block. This
is basically equivalent to::
from contextlib import contextmanager
@contextmanager
def closing(thing):
try:
yield thing
finally:
thing.close()
And lets you write code like this::
from contextlib import closing
import urllib
with closing(urllib.urlopen('http://www.python.org')) as page:
for line in page:
print line
without needing to explicitly close ``page``. Even if an error occurs,
``page.close()`` will be called when the :keyword:`with` block is exited.
.. seealso::
:pep:`343` - The "with" statement
The specification, background, and examples for the Python :keyword:`with`
statement.
PK %�\�e4�G% G% $ html/_sources/library/cookie.rst.txtnu �[��� :mod:`Cookie` --- HTTP state management
=======================================
.. module:: Cookie
:synopsis: Support for HTTP state management (cookies).
.. moduleauthor:: Timothy O'Malley <timo@alum.mit.edu>
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
.. note::
The :mod:`Cookie` module has been renamed to :mod:`http.cookies` in Python
3. The :term:`2to3` tool will automatically adapt imports when converting
your sources to Python 3.
**Source code:** :source:`Lib/Cookie.py`
--------------
The :mod:`Cookie` module defines classes for abstracting the concept of
cookies, an HTTP state management mechanism. It supports both simple string-only
cookies, and provides an abstraction for having any serializable data-type as
cookie value.
The module formerly strictly applied the parsing rules described in the
:rfc:`2109` and :rfc:`2068` specifications. It has since been discovered that
MSIE 3.0x doesn't follow the character rules outlined in those specs and also
many current day browsers and servers have relaxed parsing rules when comes to
Cookie handling. As a result, the parsing rules used are a bit less strict.
The character set, :data:`string.ascii_letters`, :data:`string.digits` and
``!#$%&'*+-.^_`|~`` denote the set of valid characters allowed by this module
in Cookie name (as :attr:`~Morsel.key`).
.. note::
On encountering an invalid cookie, :exc:`CookieError` is raised, so if your
cookie data comes from a browser you should always prepare for invalid data
and catch :exc:`CookieError` on parsing.
.. exception:: CookieError
Exception failing because of :rfc:`2109` invalidity: incorrect attributes,
incorrect :mailheader:`Set-Cookie` header, etc.
.. class:: BaseCookie([input])
This class is a dictionary-like object whose keys are strings and whose values
are :class:`Morsel` instances. Note that upon setting a key to a value, the
value is first converted to a :class:`Morsel` containing the key and the value.
If *input* is given, it is passed to the :meth:`load` method.
.. class:: SimpleCookie([input])
This class derives from :class:`BaseCookie` and overrides :meth:`value_decode`
and :meth:`value_encode` to be the identity and :func:`str` respectively.
.. class:: SerialCookie([input])
This class derives from :class:`BaseCookie` and overrides :meth:`value_decode`
and :meth:`value_encode` to be the :func:`pickle.loads` and
:func:`pickle.dumps`.
.. deprecated:: 2.3
Reading pickled values from untrusted cookie data is a huge security hole, as
pickle strings can be crafted to cause arbitrary code to execute on your server.
It is supported for backwards compatibility only, and may eventually go away.
.. class:: SmartCookie([input])
This class derives from :class:`BaseCookie`. It overrides :meth:`value_decode`
to be :func:`pickle.loads` if it is a valid pickle, and otherwise the value
itself. It overrides :meth:`value_encode` to be :func:`pickle.dumps` unless it
is a string, in which case it returns the value itself.
.. deprecated:: 2.3
The same security warning from :class:`SerialCookie` applies here.
A further security note is warranted. For backwards compatibility, the
:mod:`Cookie` module exports a class named :class:`~Cookie.Cookie` which is
just an alias for :class:`SmartCookie`. This is probably a mistake and will
likely be removed in a future version. You should not use the
:class:`~Cookie.Cookie` class in your applications, for the same reason why
you should not use the :class:`SerialCookie` class.
.. seealso::
Module :mod:`cookielib`
HTTP cookie handling for web *clients*. The :mod:`cookielib` and :mod:`Cookie`
modules do not depend on each other.
:rfc:`2109` - HTTP State Management Mechanism
This is the state management specification implemented by this module.
.. _cookie-objects:
Cookie Objects
--------------
.. method:: BaseCookie.value_decode(val)
Return a decoded value from a string representation. Return value can be any
type. This method does nothing in :class:`BaseCookie` --- it exists so it can be
overridden.
.. method:: BaseCookie.value_encode(val)
Return an encoded value. *val* can be any type, but return value must be a
string. This method does nothing in :class:`BaseCookie` --- it exists so it can
be overridden.
In general, it should be the case that :meth:`value_encode` and
:meth:`value_decode` are inverses on the range of *value_decode*.
.. method:: BaseCookie.output([attrs[, header[, sep]]])
Return a string representation suitable to be sent as HTTP headers. *attrs* and
*header* are sent to each :class:`Morsel`'s :meth:`output` method. *sep* is used
to join the headers together, and is by default the combination ``'\r\n'``
(CRLF).
.. versionchanged:: 2.5
The default separator has been changed from ``'\n'`` to match the cookie
specification.
.. method:: BaseCookie.js_output([attrs])
Return an embeddable JavaScript snippet, which, if run on a browser which
supports JavaScript, will act the same as if the HTTP headers was sent.
The meaning for *attrs* is the same as in :meth:`output`.
.. method:: BaseCookie.load(rawdata)
If *rawdata* is a string, parse it as an ``HTTP_COOKIE`` and add the values
found there as :class:`Morsel`\ s. If it is a dictionary, it is equivalent to::
for k, v in rawdata.items():
cookie[k] = v
.. _morsel-objects:
Morsel Objects
--------------
.. class:: Morsel
Abstract a key/value pair, which has some :rfc:`2109` attributes.
Morsels are dictionary-like objects, whose set of keys is constant --- the valid
:rfc:`2109` attributes, which are
* ``expires``
* ``path``
* ``comment``
* ``domain``
* ``max-age``
* ``secure``
* ``version``
* ``httponly``
The attribute :attr:`httponly` specifies that the cookie is only transferred
in HTTP requests, and is not accessible through JavaScript. This is intended
to mitigate some forms of cross-site scripting.
The keys are case-insensitive.
.. versionadded:: 2.6
The :attr:`httponly` attribute was added.
.. attribute:: Morsel.value
The value of the cookie.
.. attribute:: Morsel.coded_value
The encoded value of the cookie --- this is what should be sent.
.. attribute:: Morsel.key
The name of the cookie.
.. method:: Morsel.set(key, value, coded_value)
Set the *key*, *value* and *coded_value* attributes.
.. method:: Morsel.isReservedKey(K)
Whether *K* is a member of the set of keys of a :class:`Morsel`.
.. method:: Morsel.output([attrs[, header]])
Return a string representation of the Morsel, suitable to be sent as an HTTP
header. By default, all the attributes are included, unless *attrs* is given, in
which case it should be a list of attributes to use. *header* is by default
``"Set-Cookie:"``.
.. method:: Morsel.js_output([attrs])
Return an embeddable JavaScript snippet, which, if run on a browser which
supports JavaScript, will act the same as if the HTTP header was sent.
The meaning for *attrs* is the same as in :meth:`output`.
.. method:: Morsel.OutputString([attrs])
Return a string representing the Morsel, without any surrounding HTTP or
JavaScript.
The meaning for *attrs* is the same as in :meth:`output`.
.. _cookie-example:
Example
-------
The following example demonstrates how to use the :mod:`Cookie` module.
.. doctest::
:options: +NORMALIZE_WHITESPACE
>>> import Cookie
>>> C = Cookie.SimpleCookie()
>>> C["fig"] = "newton"
>>> C["sugar"] = "wafer"
>>> print C # generate HTTP headers
Set-Cookie: fig=newton
Set-Cookie: sugar=wafer
>>> print C.output() # same thing
Set-Cookie: fig=newton
Set-Cookie: sugar=wafer
>>> C = Cookie.SimpleCookie()
>>> C["rocky"] = "road"
>>> C["rocky"]["path"] = "/cookie"
>>> print C.output(header="Cookie:")
Cookie: rocky=road; Path=/cookie
>>> print C.output(attrs=[], header="Cookie:")
Cookie: rocky=road
>>> C = Cookie.SimpleCookie()
>>> C.load("chips=ahoy; vienna=finger") # load from a string (HTTP header)
>>> print C
Set-Cookie: chips=ahoy
Set-Cookie: vienna=finger
>>> C = Cookie.SimpleCookie()
>>> C.load('keebler="E=everybody; L=\\"Loves\\"; fudge=\\012;";')
>>> print C
Set-Cookie: keebler="E=everybody; L=\"Loves\"; fudge=\012;"
>>> C = Cookie.SimpleCookie()
>>> C["oreo"] = "doublestuff"
>>> C["oreo"]["path"] = "/"
>>> print C
Set-Cookie: oreo=doublestuff; Path=/
>>> C["twix"] = "none for you"
>>> C["twix"].value
'none for you'
>>> C = Cookie.SimpleCookie()
>>> C["number"] = 7 # equivalent to C["number"] = str(7)
>>> C["string"] = "seven"
>>> C["number"].value
'7'
>>> C["string"].value
'seven'
>>> print C
Set-Cookie: number=7
Set-Cookie: string=seven
>>> # SerialCookie and SmartCookie are deprecated
>>> # using it can cause security loopholes in your code.
>>> C = Cookie.SerialCookie()
>>> C["number"] = 7
>>> C["string"] = "seven"
>>> C["number"].value
7
>>> C["string"].value
'seven'
>>> print C
Set-Cookie: number="I7\012."
Set-Cookie: string="S'seven'\012p1\012."
>>> C = Cookie.SmartCookie()
>>> C["number"] = 7
>>> C["string"] = "seven"
>>> C["number"].value
7
>>> C["string"].value
'seven'
>>> print C
Set-Cookie: number="I7\012."
Set-Cookie: string=seven
PK %�\�r��l �l ' html/_sources/library/cookielib.rst.txtnu �[��� :mod:`cookielib` --- Cookie handling for HTTP clients
=====================================================
.. module:: cookielib
:synopsis: Classes for automatic handling of HTTP cookies.
.. moduleauthor:: John J. Lee <jjl@pobox.com>
.. sectionauthor:: John J. Lee <jjl@pobox.com>
.. note::
The :mod:`cookielib` module has been renamed to :mod:`http.cookiejar` in
Python 3. The :term:`2to3` tool will automatically adapt imports when
converting your sources to Python 3.
.. versionadded:: 2.4
**Source code:** :source:`Lib/cookielib.py`
--------------
The :mod:`cookielib` module defines classes for automatic handling of HTTP
cookies. It is useful for accessing web sites that require small pieces of data
-- :dfn:`cookies` -- to be set on the client machine by an HTTP response from a
web server, and then returned to the server in later HTTP requests.
Both the regular Netscape cookie protocol and the protocol defined by
:rfc:`2965` are handled. RFC 2965 handling is switched off by default.
:rfc:`2109` cookies are parsed as Netscape cookies and subsequently treated
either as Netscape or RFC 2965 cookies according to the 'policy' in effect.
Note that the great majority of cookies on the Internet are Netscape cookies.
:mod:`cookielib` attempts to follow the de-facto Netscape cookie protocol (which
differs substantially from that set out in the original Netscape specification),
including taking note of the ``max-age`` and ``port`` cookie-attributes
introduced with RFC 2965.
.. note::
The various named parameters found in :mailheader:`Set-Cookie` and
:mailheader:`Set-Cookie2` headers (eg. ``domain`` and ``expires``) are
conventionally referred to as :dfn:`attributes`. To distinguish them from
Python attributes, the documentation for this module uses the term
:dfn:`cookie-attribute` instead.
The module defines the following exception:
.. exception:: LoadError
Instances of :class:`FileCookieJar` raise this exception on failure to load
cookies from a file.
.. note::
For backwards-compatibility with Python 2.4 (which raised an :exc:`IOError`),
:exc:`LoadError` is a subclass of :exc:`IOError`.
The following classes are provided:
.. class:: CookieJar(policy=None)
*policy* is an object implementing the :class:`CookiePolicy` interface.
The :class:`CookieJar` class stores HTTP cookies. It extracts cookies from HTTP
requests, and returns them in HTTP responses. :class:`CookieJar` instances
automatically expire contained cookies when necessary. Subclasses are also
responsible for storing and retrieving cookies from a file or database.
.. class:: FileCookieJar(filename, delayload=None, policy=None)
*policy* is an object implementing the :class:`CookiePolicy` interface. For the
other arguments, see the documentation for the corresponding attributes.
A :class:`CookieJar` which can load cookies from, and perhaps save cookies to, a
file on disk. Cookies are **NOT** loaded from the named file until either the
:meth:`load` or :meth:`revert` method is called. Subclasses of this class are
documented in section :ref:`file-cookie-jar-classes`.
.. class:: CookiePolicy()
This class is responsible for deciding whether each cookie should be accepted
from / returned to the server.
.. class:: DefaultCookiePolicy( blocked_domains=None, allowed_domains=None, netscape=True, rfc2965=False, rfc2109_as_netscape=None, hide_cookie2=False, strict_domain=False, strict_rfc2965_unverifiable=True, strict_ns_unverifiable=False, strict_ns_domain=DefaultCookiePolicy.DomainLiberal, strict_ns_set_initial_dollar=False, strict_ns_set_path=False )
Constructor arguments should be passed as keyword arguments only.
*blocked_domains* is a sequence of domain names that we never accept cookies
from, nor return cookies to. *allowed_domains* if not :const:`None`, this is a
sequence of the only domains for which we accept and return cookies. For all
other arguments, see the documentation for :class:`CookiePolicy` and
:class:`DefaultCookiePolicy` objects.
:class:`DefaultCookiePolicy` implements the standard accept / reject rules for
Netscape and RFC 2965 cookies. By default, RFC 2109 cookies (ie. cookies
received in a :mailheader:`Set-Cookie` header with a version cookie-attribute of
1) are treated according to the RFC 2965 rules. However, if RFC 2965 handling
is turned off or :attr:`rfc2109_as_netscape` is ``True``, RFC 2109 cookies are
'downgraded' by the :class:`CookieJar` instance to Netscape cookies, by
setting the :attr:`version` attribute of the :class:`~cookielib.Cookie` instance to 0.
:class:`DefaultCookiePolicy` also provides some parameters to allow some
fine-tuning of policy.
.. class:: Cookie()
This class represents Netscape, RFC 2109 and RFC 2965 cookies. It is not
expected that users of :mod:`cookielib` construct their own :class:`~cookielib.Cookie`
instances. Instead, if necessary, call :meth:`make_cookies` on a
:class:`CookieJar` instance.
.. seealso::
Module :mod:`urllib2`
URL opening with automatic cookie handling.
Module :mod:`Cookie`
HTTP cookie classes, principally useful for server-side code. The
:mod:`cookielib` and :mod:`Cookie` modules do not depend on each other.
https://curl.haxx.se/rfc/cookie_spec.html
The specification of the original Netscape cookie protocol. Though this is
still the dominant protocol, the 'Netscape cookie protocol' implemented by all
the major browsers (and :mod:`cookielib`) only bears a passing resemblance to
the one sketched out in ``cookie_spec.html``.
:rfc:`2109` - HTTP State Management Mechanism
Obsoleted by RFC 2965. Uses :mailheader:`Set-Cookie` with version=1.
:rfc:`2965` - HTTP State Management Mechanism
The Netscape protocol with the bugs fixed. Uses :mailheader:`Set-Cookie2` in
place of :mailheader:`Set-Cookie`. Not widely used.
http://kristol.org/cookie/errata.html
Unfinished errata to RFC 2965.
:rfc:`2964` - Use of HTTP State Management
.. _cookie-jar-objects:
CookieJar and FileCookieJar Objects
-----------------------------------
:class:`CookieJar` objects support the :term:`iterator` protocol for iterating over
contained :class:`~cookielib.Cookie` objects.
:class:`CookieJar` has the following methods:
.. method:: CookieJar.add_cookie_header(request)
Add correct :mailheader:`Cookie` header to *request*.
If policy allows (ie. the :attr:`rfc2965` and :attr:`hide_cookie2` attributes of
the :class:`CookieJar`'s :class:`CookiePolicy` instance are true and false
respectively), the :mailheader:`Cookie2` header is also added when appropriate.
The *request* object (usually a :class:`urllib2.Request` instance) must support
the methods :meth:`get_full_url`, :meth:`get_host`, :meth:`get_type`,
:meth:`unverifiable`, :meth:`get_origin_req_host`, :meth:`has_header`,
:meth:`get_header`, :meth:`header_items`, and :meth:`add_unredirected_header`,as
documented by :mod:`urllib2`.
.. method:: CookieJar.extract_cookies(response, request)
Extract cookies from HTTP *response* and store them in the :class:`CookieJar`,
where allowed by policy.
The :class:`CookieJar` will look for allowable :mailheader:`Set-Cookie` and
:mailheader:`Set-Cookie2` headers in the *response* argument, and store cookies
as appropriate (subject to the :meth:`CookiePolicy.set_ok` method's approval).
The *response* object (usually the result of a call to :meth:`urllib2.urlopen`,
or similar) should support an :meth:`info` method, which returns an object with
a :meth:`getallmatchingheaders` method (usually a :class:`mimetools.Message`
instance).
The *request* object (usually a :class:`urllib2.Request` instance) must support
the methods :meth:`get_full_url`, :meth:`get_host`, :meth:`unverifiable`, and
:meth:`get_origin_req_host`, as documented by :mod:`urllib2`. The request is
used to set default values for cookie-attributes as well as for checking that
the cookie is allowed to be set.
.. method:: CookieJar.set_policy(policy)
Set the :class:`CookiePolicy` instance to be used.
.. method:: CookieJar.make_cookies(response, request)
Return sequence of :class:`~cookielib.Cookie` objects extracted from *response* object.
See the documentation for :meth:`extract_cookies` for the interfaces required of
the *response* and *request* arguments.
.. method:: CookieJar.set_cookie_if_ok(cookie, request)
Set a :class:`~cookielib.Cookie` if policy says it's OK to do so.
.. method:: CookieJar.set_cookie(cookie)
Set a :class:`~cookielib.Cookie`, without checking with policy to see whether or not it
should be set.
.. method:: CookieJar.clear([domain[, path[, name]]])
Clear some cookies.
If invoked without arguments, clear all cookies. If given a single argument,
only cookies belonging to that *domain* will be removed. If given two arguments,
cookies belonging to the specified *domain* and URL *path* are removed. If
given three arguments, then the cookie with the specified *domain*, *path* and
*name* is removed.
Raises :exc:`KeyError` if no matching cookie exists.
.. method:: CookieJar.clear_session_cookies()
Discard all session cookies.
Discards all contained cookies that have a true :attr:`discard` attribute
(usually because they had either no ``max-age`` or ``expires`` cookie-attribute,
or an explicit ``discard`` cookie-attribute). For interactive browsers, the end
of a session usually corresponds to closing the browser window.
Note that the :meth:`save` method won't save session cookies anyway, unless you
ask otherwise by passing a true *ignore_discard* argument.
:class:`FileCookieJar` implements the following additional methods:
.. method:: FileCookieJar.save(filename=None, ignore_discard=False, ignore_expires=False)
Save cookies to a file.
This base class raises :exc:`NotImplementedError`. Subclasses may leave this
method unimplemented.
*filename* is the name of file in which to save cookies. If *filename* is not
specified, :attr:`self.filename` is used (whose default is the value passed to
the constructor, if any); if :attr:`self.filename` is :const:`None`,
:exc:`ValueError` is raised.
*ignore_discard*: save even cookies set to be discarded. *ignore_expires*: save
even cookies that have expired
The file is overwritten if it already exists, thus wiping all the cookies it
contains. Saved cookies can be restored later using the :meth:`load` or
:meth:`revert` methods.
.. method:: FileCookieJar.load(filename=None, ignore_discard=False, ignore_expires=False)
Load cookies from a file.
Old cookies are kept unless overwritten by newly loaded ones.
Arguments are as for :meth:`save`.
The named file must be in the format understood by the class, or
:exc:`LoadError` will be raised. Also, :exc:`IOError` may be raised, for
example if the file does not exist.
.. note::
For backwards-compatibility with Python 2.4 (which raised an :exc:`IOError`),
:exc:`LoadError` is a subclass of :exc:`IOError`.
.. method:: FileCookieJar.revert(filename=None, ignore_discard=False, ignore_expires=False)
Clear all cookies and reload cookies from a saved file.
:meth:`revert` can raise the same exceptions as :meth:`load`. If there is a
failure, the object's state will not be altered.
:class:`FileCookieJar` instances have the following public attributes:
.. attribute:: FileCookieJar.filename
Filename of default file in which to keep cookies. This attribute may be
assigned to.
.. attribute:: FileCookieJar.delayload
If true, load cookies lazily from disk. This attribute should not be assigned
to. This is only a hint, since this only affects performance, not behaviour
(unless the cookies on disk are changing). A :class:`CookieJar` object may
ignore it. None of the :class:`FileCookieJar` classes included in the standard
library lazily loads cookies.
.. _file-cookie-jar-classes:
FileCookieJar subclasses and co-operation with web browsers
-----------------------------------------------------------
The following :class:`CookieJar` subclasses are provided for reading and
writing.
.. class:: MozillaCookieJar(filename, delayload=None, policy=None)
A :class:`FileCookieJar` that can load from and save cookies to disk in the
Mozilla ``cookies.txt`` file format (which is also used by the Lynx and Netscape
browsers).
.. note::
Version 3 of the Firefox web browser no longer writes cookies in the
``cookies.txt`` file format.
.. note::
This loses information about RFC 2965 cookies, and also about newer or
non-standard cookie-attributes such as ``port``.
.. warning::
Back up your cookies before saving if you have cookies whose loss / corruption
would be inconvenient (there are some subtleties which may lead to slight
changes in the file over a load / save round-trip).
Also note that cookies saved while Mozilla is running will get clobbered by
Mozilla.
.. class:: LWPCookieJar(filename, delayload=None, policy=None)
A :class:`FileCookieJar` that can load from and save cookies to disk in format
compatible with the libwww-perl library's ``Set-Cookie3`` file format. This is
convenient if you want to store cookies in a human-readable file.
.. _cookie-policy-objects:
CookiePolicy Objects
--------------------
Objects implementing the :class:`CookiePolicy` interface have the following
methods:
.. method:: CookiePolicy.set_ok(cookie, request)
Return boolean value indicating whether cookie should be accepted from server.
*cookie* is a :class:`cookielib.Cookie` instance. *request* is an object
implementing the interface defined by the documentation for
:meth:`CookieJar.extract_cookies`.
.. method:: CookiePolicy.return_ok(cookie, request)
Return boolean value indicating whether cookie should be returned to server.
*cookie* is a :class:`cookielib.Cookie` instance. *request* is an object
implementing the interface defined by the documentation for
:meth:`CookieJar.add_cookie_header`.
.. method:: CookiePolicy.domain_return_ok(domain, request)
Return false if cookies should not be returned, given cookie domain.
This method is an optimization. It removes the need for checking every cookie
with a particular domain (which might involve reading many files). Returning
true from :meth:`domain_return_ok` and :meth:`path_return_ok` leaves all the
work to :meth:`return_ok`.
If :meth:`domain_return_ok` returns true for the cookie domain,
:meth:`path_return_ok` is called for the cookie path. Otherwise,
:meth:`path_return_ok` and :meth:`return_ok` are never called for that cookie
domain. If :meth:`path_return_ok` returns true, :meth:`return_ok` is called
with the :class:`~cookielib.Cookie` object itself for a full check. Otherwise,
:meth:`return_ok` is never called for that cookie path.
Note that :meth:`domain_return_ok` is called for every *cookie* domain, not just
for the *request* domain. For example, the function might be called with both
``".example.com"`` and ``"www.example.com"`` if the request domain is
``"www.example.com"``. The same goes for :meth:`path_return_ok`.
The *request* argument is as documented for :meth:`return_ok`.
.. method:: CookiePolicy.path_return_ok(path, request)
Return false if cookies should not be returned, given cookie path.
See the documentation for :meth:`domain_return_ok`.
In addition to implementing the methods above, implementations of the
:class:`CookiePolicy` interface must also supply the following attributes,
indicating which protocols should be used, and how. All of these attributes may
be assigned to.
.. attribute:: CookiePolicy.netscape
Implement Netscape protocol.
.. attribute:: CookiePolicy.rfc2965
Implement RFC 2965 protocol.
.. attribute:: CookiePolicy.hide_cookie2
Don't add :mailheader:`Cookie2` header to requests (the presence of this header
indicates to the server that we understand RFC 2965 cookies).
The most useful way to define a :class:`CookiePolicy` class is by subclassing
from :class:`DefaultCookiePolicy` and overriding some or all of the methods
above. :class:`CookiePolicy` itself may be used as a 'null policy' to allow
setting and receiving any and all cookies (this is unlikely to be useful).
.. _default-cookie-policy-objects:
DefaultCookiePolicy Objects
---------------------------
Implements the standard rules for accepting and returning cookies.
Both RFC 2965 and Netscape cookies are covered. RFC 2965 handling is switched
off by default.
The easiest way to provide your own policy is to override this class and call
its methods in your overridden implementations before adding your own additional
checks::
import cookielib
class MyCookiePolicy(cookielib.DefaultCookiePolicy):
def set_ok(self, cookie, request):
if not cookielib.DefaultCookiePolicy.set_ok(self, cookie, request):
return False
if i_dont_want_to_store_this_cookie(cookie):
return False
return True
In addition to the features required to implement the :class:`CookiePolicy`
interface, this class allows you to block and allow domains from setting and
receiving cookies. There are also some strictness switches that allow you to
tighten up the rather loose Netscape protocol rules a little bit (at the cost of
blocking some benign cookies).
A domain blacklist and whitelist is provided (both off by default). Only domains
not in the blacklist and present in the whitelist (if the whitelist is active)
participate in cookie setting and returning. Use the *blocked_domains*
constructor argument, and :meth:`blocked_domains` and
:meth:`set_blocked_domains` methods (and the corresponding argument and methods
for *allowed_domains*). If you set a whitelist, you can turn it off again by
setting it to :const:`None`.
Domains in block or allow lists that do not start with a dot must equal the
cookie domain to be matched. For example, ``"example.com"`` matches a blacklist
entry of ``"example.com"``, but ``"www.example.com"`` does not. Domains that do
start with a dot are matched by more specific domains too. For example, both
``"www.example.com"`` and ``"www.coyote.example.com"`` match ``".example.com"``
(but ``"example.com"`` itself does not). IP addresses are an exception, and
must match exactly. For example, if blocked_domains contains ``"192.168.1.2"``
and ``".168.1.2"``, 192.168.1.2 is blocked, but 193.168.1.2 is not.
:class:`DefaultCookiePolicy` implements the following additional methods:
.. method:: DefaultCookiePolicy.blocked_domains()
Return the sequence of blocked domains (as a tuple).
.. method:: DefaultCookiePolicy.set_blocked_domains(blocked_domains)
Set the sequence of blocked domains.
.. method:: DefaultCookiePolicy.is_blocked(domain)
Return whether *domain* is on the blacklist for setting or receiving cookies.
.. method:: DefaultCookiePolicy.allowed_domains()
Return :const:`None`, or the sequence of allowed domains (as a tuple).
.. method:: DefaultCookiePolicy.set_allowed_domains(allowed_domains)
Set the sequence of allowed domains, or :const:`None`.
.. method:: DefaultCookiePolicy.is_not_allowed(domain)
Return whether *domain* is not on the whitelist for setting or receiving
cookies.
:class:`DefaultCookiePolicy` instances have the following attributes, which are
all initialised from the constructor arguments of the same name, and which may
all be assigned to.
.. attribute:: DefaultCookiePolicy.rfc2109_as_netscape
If true, request that the :class:`CookieJar` instance downgrade RFC 2109 cookies
(ie. cookies received in a :mailheader:`Set-Cookie` header with a version
cookie-attribute of 1) to Netscape cookies by setting the version attribute of
the :class:`~cookielib.Cookie` instance to 0. The default value is :const:`None`, in which
case RFC 2109 cookies are downgraded if and only if RFC 2965 handling is turned
off. Therefore, RFC 2109 cookies are downgraded by default.
.. versionadded:: 2.5
General strictness switches:
.. attribute:: DefaultCookiePolicy.strict_domain
Don't allow sites to set two-component domains with country-code top-level
domains like ``.co.uk``, ``.gov.uk``, ``.co.nz``.etc. This is far from perfect
and isn't guaranteed to work!
RFC 2965 protocol strictness switches:
.. attribute:: DefaultCookiePolicy.strict_rfc2965_unverifiable
Follow RFC 2965 rules on unverifiable transactions (usually, an unverifiable
transaction is one resulting from a redirect or a request for an image hosted on
another site). If this is false, cookies are *never* blocked on the basis of
verifiability
Netscape protocol strictness switches:
.. attribute:: DefaultCookiePolicy.strict_ns_unverifiable
Apply RFC 2965 rules on unverifiable transactions even to Netscape cookies.
.. attribute:: DefaultCookiePolicy.strict_ns_domain
Flags indicating how strict to be with domain-matching rules for Netscape
cookies. See below for acceptable values.
.. attribute:: DefaultCookiePolicy.strict_ns_set_initial_dollar
Ignore cookies in Set-Cookie: headers that have names starting with ``'$'``.
.. attribute:: DefaultCookiePolicy.strict_ns_set_path
Don't allow setting cookies whose path doesn't path-match request URI.
:attr:`strict_ns_domain` is a collection of flags. Its value is constructed by
or-ing together (for example, ``DomainStrictNoDots|DomainStrictNonDomain`` means
both flags are set).
.. attribute:: DefaultCookiePolicy.DomainStrictNoDots
When setting cookies, the 'host prefix' must not contain a dot (eg.
``www.foo.bar.com`` can't set a cookie for ``.bar.com``, because ``www.foo``
contains a dot).
.. attribute:: DefaultCookiePolicy.DomainStrictNonDomain
Cookies that did not explicitly specify a ``domain`` cookie-attribute can only
be returned to a domain equal to the domain that set the cookie (eg.
``spam.example.com`` won't be returned cookies from ``example.com`` that had no
``domain`` cookie-attribute).
.. attribute:: DefaultCookiePolicy.DomainRFC2965Match
When setting cookies, require a full RFC 2965 domain-match.
The following attributes are provided for convenience, and are the most useful
combinations of the above flags:
.. attribute:: DefaultCookiePolicy.DomainLiberal
Equivalent to 0 (ie. all of the above Netscape domain strictness flags switched
off).
.. attribute:: DefaultCookiePolicy.DomainStrict
Equivalent to ``DomainStrictNoDots|DomainStrictNonDomain``.
.. _cookielib-cookie-objects:
Cookie Objects
--------------
:class:`~cookielib.Cookie` instances have Python attributes roughly corresponding to the
standard cookie-attributes specified in the various cookie standards. The
correspondence is not one-to-one, because there are complicated rules for
assigning default values, because the ``max-age`` and ``expires``
cookie-attributes contain equivalent information, and because RFC 2109 cookies
may be 'downgraded' by :mod:`cookielib` from version 1 to version 0 (Netscape)
cookies.
Assignment to these attributes should not be necessary other than in rare
circumstances in a :class:`CookiePolicy` method. The class does not enforce
internal consistency, so you should know what you're doing if you do that.
.. attribute:: Cookie.version
Integer or :const:`None`. Netscape cookies have :attr:`version` 0. RFC 2965 and
RFC 2109 cookies have a ``version`` cookie-attribute of 1. However, note that
:mod:`cookielib` may 'downgrade' RFC 2109 cookies to Netscape cookies, in which
case :attr:`version` is 0.
.. attribute:: Cookie.name
Cookie name (a string).
.. attribute:: Cookie.value
Cookie value (a string), or :const:`None`.
.. attribute:: Cookie.port
String representing a port or a set of ports (eg. '80', or '80,8080'), or
:const:`None`.
.. attribute:: Cookie.path
Cookie path (a string, eg. ``'/acme/rocket_launchers'``).
.. attribute:: Cookie.secure
``True`` if cookie should only be returned over a secure connection.
.. attribute:: Cookie.expires
Integer expiry date in seconds since epoch, or :const:`None`. See also the
:meth:`is_expired` method.
.. attribute:: Cookie.discard
``True`` if this is a session cookie.
.. attribute:: Cookie.comment
String comment from the server explaining the function of this cookie, or
:const:`None`.
.. attribute:: Cookie.comment_url
URL linking to a comment from the server explaining the function of this cookie,
or :const:`None`.
.. attribute:: Cookie.rfc2109
``True`` if this cookie was received as an RFC 2109 cookie (ie. the cookie
arrived in a :mailheader:`Set-Cookie` header, and the value of the Version
cookie-attribute in that header was 1). This attribute is provided because
:mod:`cookielib` may 'downgrade' RFC 2109 cookies to Netscape cookies, in
which case :attr:`version` is 0.
.. versionadded:: 2.5
.. attribute:: Cookie.port_specified
``True`` if a port or set of ports was explicitly specified by the server (in the
:mailheader:`Set-Cookie` / :mailheader:`Set-Cookie2` header).
.. attribute:: Cookie.domain_specified
``True`` if a domain was explicitly specified by the server.
.. attribute:: Cookie.domain_initial_dot
``True`` if the domain explicitly specified by the server began with a dot
(``'.'``).
Cookies may have additional non-standard cookie-attributes. These may be
accessed using the following methods:
.. method:: Cookie.has_nonstandard_attr(name)
Return true if cookie has the named cookie-attribute.
.. method:: Cookie.get_nonstandard_attr(name, default=None)
If cookie has the named cookie-attribute, return its value. Otherwise, return
*default*.
.. method:: Cookie.set_nonstandard_attr(name, value)
Set the value of the named cookie-attribute.
The :class:`~cookielib.Cookie` class also defines the following method:
.. method:: Cookie.is_expired([now=None])
``True`` if cookie has passed the time at which the server requested it should
expire. If *now* is given (in seconds since the epoch), return whether the
cookie has expired at the specified time.
.. _cookielib-examples:
Examples
--------
The first example shows the most common usage of :mod:`cookielib`::
import cookielib, urllib2
cj = cookielib.CookieJar()
opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj))
r = opener.open("http://example.com/")
This example illustrates how to open a URL using your Netscape, Mozilla, or Lynx
cookies (assumes Unix/Netscape convention for location of the cookies file)::
import os, cookielib, urllib2
cj = cookielib.MozillaCookieJar()
cj.load(os.path.join(os.path.expanduser("~"), ".netscape", "cookies.txt"))
opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj))
r = opener.open("http://example.com/")
The next example illustrates the use of :class:`DefaultCookiePolicy`. Turn on
RFC 2965 cookies, be more strict about domains when setting and returning
Netscape cookies, and block some domains from setting cookies or having them
returned::
import urllib2
from cookielib import CookieJar, DefaultCookiePolicy
policy = DefaultCookiePolicy(
rfc2965=True, strict_ns_domain=DefaultCookiePolicy.DomainStrict,
blocked_domains=["ads.net", ".ads.net"])
cj = CookieJar(policy)
opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj))
r = opener.open("http://example.com/")
PK %�\�`R�
" html/_sources/library/copy.rst.txtnu �[��� :mod:`copy` --- Shallow and deep copy operations
================================================
.. module:: copy
:synopsis: Shallow and deep copy operations.
Assignment statements in Python do not copy objects, they create bindings
between a target and an object. For collections that are mutable or contain
mutable items, a copy is sometimes needed so one can change one copy without
changing the other. This module provides generic shallow and deep copy
operations (explained below).
Interface summary:
.. function:: copy(x)
Return a shallow copy of *x*.
.. function:: deepcopy(x)
Return a deep copy of *x*.
.. exception:: error
Raised for module specific errors.
The difference between shallow and deep copying is only relevant for compound
objects (objects that contain other objects, like lists or class instances):
* A *shallow copy* constructs a new compound object and then (to the extent
possible) inserts *references* into it to the objects found in the original.
* A *deep copy* constructs a new compound object and then, recursively, inserts
*copies* into it of the objects found in the original.
Two problems often exist with deep copy operations that don't exist with shallow
copy operations:
* Recursive objects (compound objects that, directly or indirectly, contain a
reference to themselves) may cause a recursive loop.
* Because deep copy copies everything it may copy too much, such as data
which is intended to be shared between copies.
The :func:`deepcopy` function avoids these problems by:
* keeping a "memo" dictionary of objects already copied during the current
copying pass; and
* letting user-defined classes override the copying operation or the set of
components copied.
This module does not copy types like module, method, stack trace, stack frame,
file, socket, window, array, or any similar types. It does "copy" functions and
classes (shallow and deeply), by returning the original object unchanged; this
is compatible with the way these are treated by the :mod:`pickle` module.
Shallow copies of dictionaries can be made using :meth:`dict.copy`, and
of lists by assigning a slice of the entire list, for example,
``copied_list = original_list[:]``.
.. versionchanged:: 2.5
Added copying functions.
.. index:: module: pickle
Classes can use the same interfaces to control copying that they use to control
pickling. See the description of module :mod:`pickle` for information on these
methods. The :mod:`copy` module does not use the :mod:`copy_reg` registration
module.
.. index::
single: __copy__() (copy protocol)
single: __deepcopy__() (copy protocol)
In order for a class to define its own copy implementation, it can define
special methods :meth:`__copy__` and :meth:`__deepcopy__`. The former is called
to implement the shallow copy operation; no additional arguments are passed.
The latter is called to implement the deep copy operation; it is passed one
argument, the memo dictionary. If the :meth:`__deepcopy__` implementation needs
to make a deep copy of a component, it should call the :func:`deepcopy` function
with the component as first argument and the memo dictionary as second argument.
.. seealso::
Module :mod:`pickle`
Discussion of the special methods used to support object state retrieval and
restoration.
PK %�\�� & html/_sources/library/copy_reg.rst.txtnu �[��� :mod:`copy_reg` --- Register :mod:`pickle` support functions
============================================================
.. module:: copy_reg
:synopsis: Register pickle support functions.
.. note::
The :mod:`copy_reg` module has been renamed to :mod:`copyreg` in Python 3.
The :term:`2to3` tool will automatically adapt imports when converting your
sources to Python 3.
.. index::
module: pickle
module: cPickle
module: copy
The :mod:`copy_reg` module offers a way to define functions used while pickling
specific objects. The :mod:`pickle`, :mod:`cPickle`, and :mod:`copy` modules
use those functions when pickling/copying those objects. The module provides
configuration information about object constructors which are not classes.
Such constructors may be factory functions or class instances.
.. function:: constructor(object)
Declares *object* to be a valid constructor. If *object* is not callable (and
hence not valid as a constructor), raises :exc:`TypeError`.
.. function:: pickle(type, function[, constructor])
Declares that *function* should be used as a "reduction" function for objects of
type *type*; *type* must not be a "classic" class object. (Classic classes are
handled differently; see the documentation for the :mod:`pickle` module for
details.) *function* should return either a string or a tuple containing two or
three elements.
The optional *constructor* parameter, if provided, is a callable object which
can be used to reconstruct the object when called with the tuple of arguments
returned by *function* at pickling time. :exc:`TypeError` will be raised if
*object* is a class or *constructor* is not callable.
See the :mod:`pickle` module for more details on the interface expected of
*function* and *constructor*.
Example
-------
The example below would like to show how to register a pickle function and how
it will be used:
>>> import copy_reg, copy, pickle
>>> class C(object):
... def __init__(self, a):
... self.a = a
...
>>> def pickle_c(c):
... print("pickling a C instance...")
... return C, (c.a,)
...
>>> copy_reg.pickle(C, pickle_c)
>>> c = C(1)
>>> d = copy.copy(c)
pickling a C instance...
>>> p = pickle.dumps(c)
pickling a C instance...
PK %�\�w �� � # html/_sources/library/crypt.rst.txtnu �[���
:mod:`crypt` --- Function to check Unix passwords
=================================================
.. module:: crypt
:platform: Unix
:synopsis: The crypt() function used to check Unix passwords.
.. moduleauthor:: Steven D. Majewski <sdm7g@virginia.edu>
.. sectionauthor:: Steven D. Majewski <sdm7g@virginia.edu>
.. sectionauthor:: Peter Funk <pf@artcom-gmbh.de>
.. index::
single: crypt(3)
pair: cipher; DES
This module implements an interface to the :manpage:`crypt(3)` routine, which is
a one-way hash function based upon a modified DES algorithm; see the Unix man
page for further details. Possible uses include allowing Python scripts to
accept typed passwords from the user, or attempting to crack Unix passwords with
a dictionary.
.. index:: single: crypt(3)
Notice that the behavior of this module depends on the actual implementation of
the :manpage:`crypt(3)` routine in the running system. Therefore, any
extensions available on the current implementation will also be available on
this module.
.. function:: crypt(word, salt)
*word* will usually be a user's password as typed at a prompt or in a graphical
interface. *salt* is usually a random two-character string which will be used
to perturb the DES algorithm in one of 4096 ways. The characters in *salt* must
be in the set ``[./a-zA-Z0-9]``. Returns the hashed password as a string, which
will be composed of characters from the same alphabet as the salt (the first two
characters represent the salt itself).
.. index:: single: crypt(3)
Since a few :manpage:`crypt(3)` extensions allow different values, with
different sizes in the *salt*, it is recommended to use the full crypted
password as salt when checking for a password.
A simple example illustrating typical use::
import crypt, getpass, pwd
def login():
username = raw_input('Python login:')
cryptedpasswd = pwd.getpwnam(username)[1]
if cryptedpasswd:
if cryptedpasswd == 'x' or cryptedpasswd == '*':
raise NotImplementedError(
"Sorry, currently no support for shadow passwords")
cleartext = getpass.getpass()
return crypt.crypt(cleartext, cryptedpasswd) == cryptedpasswd
else:
return 1
PK %�\ñ�&c c $ html/_sources/library/crypto.rst.txtnu �[���
.. _crypto:
**********************
Cryptographic Services
**********************
.. index:: single: cryptography
The modules described in this chapter implement various algorithms of a
cryptographic nature. They are available at the discretion of the installation.
Here's an overview:
.. toctree::
hashlib.rst
hmac.rst
md5.rst
sha.rst
PK %�\�V�~�X �X ! html/_sources/library/csv.rst.txtnu �[���
:mod:`csv` --- CSV File Reading and Writing
===========================================
.. module:: csv
:synopsis: Write and read tabular data to and from delimited files.
.. sectionauthor:: Skip Montanaro <skip@pobox.com>
.. versionadded:: 2.3
.. index::
single: csv
pair: data; tabular
The so-called CSV (Comma Separated Values) format is the most common import and
export format for spreadsheets and databases. There is no "CSV standard", so
the format is operationally defined by the many applications which read and
write it. The lack of a standard means that subtle differences often exist in
the data produced and consumed by different applications. These differences can
make it annoying to process CSV files from multiple sources. Still, while the
delimiters and quoting characters vary, the overall format is similar enough
that it is possible to write a single module which can efficiently manipulate
such data, hiding the details of reading and writing the data from the
programmer.
The :mod:`csv` module implements classes to read and write tabular data in CSV
format. It allows programmers to say, "write this data in the format preferred
by Excel," or "read data from this file which was generated by Excel," without
knowing the precise details of the CSV format used by Excel. Programmers can
also describe the CSV formats understood by other applications or define their
own special-purpose CSV formats.
The :mod:`csv` module's :class:`reader` and :class:`writer` objects read and
write sequences. Programmers can also read and write data in dictionary form
using the :class:`DictReader` and :class:`DictWriter` classes.
.. note::
This version of the :mod:`csv` module doesn't support Unicode input. Also,
there are currently some issues regarding ASCII NUL characters. Accordingly,
all input should be UTF-8 or printable ASCII to be safe; see the examples in
section :ref:`csv-examples`.
.. seealso::
:pep:`305` - CSV File API
The Python Enhancement Proposal which proposed this addition to Python.
.. _csv-contents:
Module Contents
---------------
The :mod:`csv` module defines the following functions:
.. function:: reader(csvfile, dialect='excel', **fmtparams)
Return a reader object which will iterate over lines in the given *csvfile*.
*csvfile* can be any object which supports the :term:`iterator` protocol and returns a
string each time its :meth:`!next` method is called --- file objects and list
objects are both suitable. If *csvfile* is a file object, it must be opened
with the 'b' flag on platforms where that makes a difference. An optional
*dialect* parameter can be given which is used to define a set of parameters
specific to a particular CSV dialect. It may be an instance of a subclass of
the :class:`Dialect` class or one of the strings returned by the
:func:`list_dialects` function. The other optional *fmtparams* keyword arguments
can be given to override individual formatting parameters in the current
dialect. For full details about the dialect and formatting parameters, see
section :ref:`csv-fmt-params`.
Each row read from the csv file is returned as a list of strings. No
automatic data type conversion is performed.
A short usage example::
>>> import csv
>>> with open('eggs.csv', 'rb') as csvfile:
... spamreader = csv.reader(csvfile, delimiter=' ', quotechar='|')
... for row in spamreader:
... print ', '.join(row)
Spam, Spam, Spam, Spam, Spam, Baked Beans
Spam, Lovely Spam, Wonderful Spam
.. versionchanged:: 2.5
The parser is now stricter with respect to multi-line quoted fields. Previously,
if a line ended within a quoted field without a terminating newline character, a
newline would be inserted into the returned field. This behavior caused problems
when reading files which contained carriage return characters within fields.
The behavior was changed to return the field without inserting newlines. As a
consequence, if newlines embedded within fields are important, the input should
be split into lines in a manner which preserves the newline characters.
.. function:: writer(csvfile, dialect='excel', **fmtparams)
Return a writer object responsible for converting the user's data into delimited
strings on the given file-like object. *csvfile* can be any object with a
:func:`write` method. If *csvfile* is a file object, it must be opened with the
'b' flag on platforms where that makes a difference. An optional *dialect*
parameter can be given which is used to define a set of parameters specific to a
particular CSV dialect. It may be an instance of a subclass of the
:class:`Dialect` class or one of the strings returned by the
:func:`list_dialects` function. The other optional *fmtparams* keyword arguments
can be given to override individual formatting parameters in the current
dialect. For full details about the dialect and formatting parameters, see
section :ref:`csv-fmt-params`. To make it
as easy as possible to interface with modules which implement the DB API, the
value :const:`None` is written as the empty string. While this isn't a
reversible transformation, it makes it easier to dump SQL NULL data values to
CSV files without preprocessing the data returned from a ``cursor.fetch*`` call.
Floats are stringified with :func:`repr` before being written.
All other non-string data are stringified with :func:`str` before being written.
A short usage example::
import csv
with open('eggs.csv', 'wb') as csvfile:
spamwriter = csv.writer(csvfile, delimiter=' ',
quotechar='|', quoting=csv.QUOTE_MINIMAL)
spamwriter.writerow(['Spam'] * 5 + ['Baked Beans'])
spamwriter.writerow(['Spam', 'Lovely Spam', 'Wonderful Spam'])
.. function:: register_dialect(name[, dialect], **fmtparams)
Associate *dialect* with *name*. *name* must be a string or Unicode object. The
dialect can be specified either by passing a sub-class of :class:`Dialect`, or
by *fmtparams* keyword arguments, or both, with keyword arguments overriding
parameters of the dialect. For full details about the dialect and formatting
parameters, see section :ref:`csv-fmt-params`.
.. function:: unregister_dialect(name)
Delete the dialect associated with *name* from the dialect registry. An
:exc:`Error` is raised if *name* is not a registered dialect name.
.. function:: get_dialect(name)
Return the dialect associated with *name*. An :exc:`Error` is raised if *name*
is not a registered dialect name.
.. versionchanged:: 2.5
This function now returns an immutable :class:`Dialect`. Previously an
instance of the requested dialect was returned. Users could modify the
underlying class, changing the behavior of active readers and writers.
.. function:: list_dialects()
Return the names of all registered dialects.
.. function:: field_size_limit([new_limit])
Returns the current maximum field size allowed by the parser. If *new_limit* is
given, this becomes the new limit.
.. versionadded:: 2.5
The :mod:`csv` module defines the following classes:
.. class:: DictReader(f, fieldnames=None, restkey=None, restval=None, \
dialect='excel', *args, **kwds)
Create an object which operates like a regular reader but maps the
information read into a dict whose keys are given by the optional
*fieldnames* parameter. The *fieldnames* parameter is a :ref:`sequence
<collections-abstract-base-classes>` whose elements are associated with the
fields of the input data in order. These elements become the keys of the
resulting dictionary. If the *fieldnames* parameter is omitted, the values
in the first row of the file *f* will be used as the fieldnames. If the
row read has more fields than the fieldnames sequence, the remaining data is
added as a sequence keyed by the value of *restkey*. If the row read has
fewer fields than the fieldnames sequence, the remaining keys take the value
of the optional *restval* parameter. Any other optional or keyword
arguments are passed to the underlying :class:`reader` instance.
A short usage example::
>>> import csv
>>> with open('names.csv') as csvfile:
... reader = csv.DictReader(csvfile)
... for row in reader:
... print(row['first_name'], row['last_name'])
...
Baked Beans
Lovely Spam
Wonderful Spam
.. class:: DictWriter(f, fieldnames, restval='', extrasaction='raise', \
dialect='excel', *args, **kwds)
Create an object which operates like a regular writer but maps dictionaries
onto output rows. The *fieldnames* parameter is a :ref:`sequence
<collections-abstract-base-classes>` of keys that identify the order in
which values in the dictionary passed to the :meth:`writerow` method are
written to the file *f*. The optional *restval* parameter specifies the
value to be written if the dictionary is missing a key in *fieldnames*. If
the dictionary passed to the :meth:`writerow` method contains a key not
found in *fieldnames*, the optional *extrasaction* parameter indicates what
action to take. If it is set to ``'raise'`` a :exc:`ValueError` is raised.
If it is set to ``'ignore'``, extra values in the dictionary are ignored.
Any other optional or keyword arguments are passed to the underlying
:class:`writer` instance.
Note that unlike the :class:`DictReader` class, the *fieldnames* parameter
of the :class:`DictWriter` is not optional. Since Python's :class:`dict`
objects are not ordered, there is not enough information available to deduce
the order in which the row should be written to the file *f*.
A short usage example::
import csv
with open('names.csv', 'w') as csvfile:
fieldnames = ['first_name', 'last_name']
writer = csv.DictWriter(csvfile, fieldnames=fieldnames)
writer.writeheader()
writer.writerow({'first_name': 'Baked', 'last_name': 'Beans'})
writer.writerow({'first_name': 'Lovely', 'last_name': 'Spam'})
writer.writerow({'first_name': 'Wonderful', 'last_name': 'Spam'})
.. class:: Dialect
The :class:`Dialect` class is a container class relied on primarily for its
attributes, which are used to define the parameters for a specific
:class:`reader` or :class:`writer` instance.
.. class:: excel()
The :class:`excel` class defines the usual properties of an Excel-generated CSV
file. It is registered with the dialect name ``'excel'``.
.. class:: excel_tab()
The :class:`excel_tab` class defines the usual properties of an Excel-generated
TAB-delimited file. It is registered with the dialect name ``'excel-tab'``.
.. class:: Sniffer()
The :class:`Sniffer` class is used to deduce the format of a CSV file.
The :class:`Sniffer` class provides two methods:
.. method:: sniff(sample, delimiters=None)
Analyze the given *sample* and return a :class:`Dialect` subclass
reflecting the parameters found. If the optional *delimiters* parameter
is given, it is interpreted as a string containing possible valid
delimiter characters.
.. method:: has_header(sample)
Analyze the sample text (presumed to be in CSV format) and return
:const:`True` if the first row appears to be a series of column headers.
An example for :class:`Sniffer` use::
with open('example.csv', 'rb') as csvfile:
dialect = csv.Sniffer().sniff(csvfile.read(1024))
csvfile.seek(0)
reader = csv.reader(csvfile, dialect)
# ... process CSV file contents here ...
The :mod:`csv` module defines the following constants:
.. data:: QUOTE_ALL
Instructs :class:`writer` objects to quote all fields.
.. data:: QUOTE_MINIMAL
Instructs :class:`writer` objects to only quote those fields which contain
special characters such as *delimiter*, *quotechar* or any of the characters in
*lineterminator*.
.. data:: QUOTE_NONNUMERIC
Instructs :class:`writer` objects to quote all non-numeric fields.
Instructs the reader to convert all non-quoted fields to type *float*.
.. data:: QUOTE_NONE
Instructs :class:`writer` objects to never quote fields. When the current
*delimiter* occurs in output data it is preceded by the current *escapechar*
character. If *escapechar* is not set, the writer will raise :exc:`Error` if
any characters that require escaping are encountered.
Instructs :class:`reader` to perform no special processing of quote characters.
The :mod:`csv` module defines the following exception:
.. exception:: Error
Raised by any of the functions when an error is detected.
.. _csv-fmt-params:
Dialects and Formatting Parameters
----------------------------------
To make it easier to specify the format of input and output records, specific
formatting parameters are grouped together into dialects. A dialect is a
subclass of the :class:`Dialect` class having a set of specific methods and a
single :meth:`validate` method. When creating :class:`reader` or
:class:`writer` objects, the programmer can specify a string or a subclass of
the :class:`Dialect` class as the dialect parameter. In addition to, or instead
of, the *dialect* parameter, the programmer can also specify individual
formatting parameters, which have the same names as the attributes defined below
for the :class:`Dialect` class.
Dialects support the following attributes:
.. attribute:: Dialect.delimiter
A one-character string used to separate fields. It defaults to ``','``.
.. attribute:: Dialect.doublequote
Controls how instances of *quotechar* appearing inside a field should
themselves be quoted. When :const:`True`, the character is doubled. When
:const:`False`, the *escapechar* is used as a prefix to the *quotechar*. It
defaults to :const:`True`.
On output, if *doublequote* is :const:`False` and no *escapechar* is set,
:exc:`Error` is raised if a *quotechar* is found in a field.
.. attribute:: Dialect.escapechar
A one-character string used by the writer to escape the *delimiter* if *quoting*
is set to :const:`QUOTE_NONE` and the *quotechar* if *doublequote* is
:const:`False`. On reading, the *escapechar* removes any special meaning from
the following character. It defaults to :const:`None`, which disables escaping.
.. attribute:: Dialect.lineterminator
The string used to terminate lines produced by the :class:`writer`. It defaults
to ``'\r\n'``.
.. note::
The :class:`reader` is hard-coded to recognise either ``'\r'`` or ``'\n'`` as
end-of-line, and ignores *lineterminator*. This behavior may change in the
future.
.. attribute:: Dialect.quotechar
A one-character string used to quote fields containing special characters, such
as the *delimiter* or *quotechar*, or which contain new-line characters. It
defaults to ``'"'``.
.. attribute:: Dialect.quoting
Controls when quotes should be generated by the writer and recognised by the
reader. It can take on any of the :const:`QUOTE_\*` constants (see section
:ref:`csv-contents`) and defaults to :const:`QUOTE_MINIMAL`.
.. attribute:: Dialect.skipinitialspace
When :const:`True`, whitespace immediately following the *delimiter* is ignored.
The default is :const:`False`.
.. attribute:: Dialect.strict
When ``True``, raise exception :exc:`Error` on bad CSV input.
The default is ``False``.
Reader Objects
--------------
Reader objects (:class:`DictReader` instances and objects returned by the
:func:`reader` function) have the following public methods:
.. method:: csvreader.next()
Return the next row of the reader's iterable object as a list, parsed according
to the current dialect.
Reader objects have the following public attributes:
.. attribute:: csvreader.dialect
A read-only description of the dialect in use by the parser.
.. attribute:: csvreader.line_num
The number of lines read from the source iterator. This is not the same as the
number of records returned, as records can span multiple lines.
.. versionadded:: 2.5
DictReader objects have the following public attribute:
.. attribute:: csvreader.fieldnames
If not passed as a parameter when creating the object, this attribute is
initialized upon first access or when the first record is read from the
file.
.. versionchanged:: 2.6
Writer Objects
--------------
:class:`Writer` objects (:class:`DictWriter` instances and objects returned by
the :func:`writer` function) have the following public methods. A *row* must be
a sequence of strings or numbers for :class:`Writer` objects and a dictionary
mapping fieldnames to strings or numbers (by passing them through :func:`str`
first) for :class:`DictWriter` objects. Note that complex numbers are written
out surrounded by parens. This may cause some problems for other programs which
read CSV files (assuming they support complex numbers at all).
.. method:: csvwriter.writerow(row)
Write the *row* parameter to the writer's file object, formatted according to
the current dialect.
.. method:: csvwriter.writerows(rows)
Write all elements in *rows* (an iterable of *row* objects as described
above) to the writer's file object, formatted according to the current
dialect.
Writer objects have the following public attribute:
.. attribute:: csvwriter.dialect
A read-only description of the dialect in use by the writer.
DictWriter objects have the following public method:
.. method:: DictWriter.writeheader()
Write a row with the field names (as specified in the constructor).
.. versionadded:: 2.7
.. _csv-examples:
Examples
--------
The simplest example of reading a CSV file::
import csv
with open('some.csv', 'rb') as f:
reader = csv.reader(f)
for row in reader:
print row
Reading a file with an alternate format::
import csv
with open('passwd', 'rb') as f:
reader = csv.reader(f, delimiter=':', quoting=csv.QUOTE_NONE)
for row in reader:
print row
The corresponding simplest possible writing example is::
import csv
with open('some.csv', 'wb') as f:
writer = csv.writer(f)
writer.writerows(someiterable)
Registering a new dialect::
import csv
csv.register_dialect('unixpwd', delimiter=':', quoting=csv.QUOTE_NONE)
with open('passwd', 'rb') as f:
reader = csv.reader(f, 'unixpwd')
A slightly more advanced use of the reader --- catching and reporting errors::
import csv, sys
filename = 'some.csv'
with open(filename, 'rb') as f:
reader = csv.reader(f)
try:
for row in reader:
print row
except csv.Error as e:
sys.exit('file %s, line %d: %s' % (filename, reader.line_num, e))
And while the module doesn't directly support parsing strings, it can easily be
done::
import csv
for row in csv.reader(['one,two,three']):
print row
The :mod:`csv` module doesn't directly support reading and writing Unicode, but
it is 8-bit-clean save for some problems with ASCII NUL characters. So you can
write functions or classes that handle the encoding and decoding for you as long
as you avoid encodings like UTF-16 that use NULs. UTF-8 is recommended.
:func:`unicode_csv_reader` below is a :term:`generator` that wraps :class:`csv.reader`
to handle Unicode CSV data (a list of Unicode strings). :func:`utf_8_encoder`
is a :term:`generator` that encodes the Unicode strings as UTF-8, one string (or row) at
a time. The encoded strings are parsed by the CSV reader, and
:func:`unicode_csv_reader` decodes the UTF-8-encoded cells back into Unicode::
import csv
def unicode_csv_reader(unicode_csv_data, dialect=csv.excel, **kwargs):
# csv.py doesn't do Unicode; encode temporarily as UTF-8:
csv_reader = csv.reader(utf_8_encoder(unicode_csv_data),
dialect=dialect, **kwargs)
for row in csv_reader:
# decode UTF-8 back to Unicode, cell by cell:
yield [unicode(cell, 'utf-8') for cell in row]
def utf_8_encoder(unicode_csv_data):
for line in unicode_csv_data:
yield line.encode('utf-8')
For all other encodings the following :class:`UnicodeReader` and
:class:`UnicodeWriter` classes can be used. They take an additional *encoding*
parameter in their constructor and make sure that the data passes the real
reader or writer encoded as UTF-8::
import csv, codecs, cStringIO
class UTF8Recoder:
"""
Iterator that reads an encoded stream and reencodes the input to UTF-8
"""
def __init__(self, f, encoding):
self.reader = codecs.getreader(encoding)(f)
def __iter__(self):
return self
def next(self):
return self.reader.next().encode("utf-8")
class UnicodeReader:
"""
A CSV reader which will iterate over lines in the CSV file "f",
which is encoded in the given encoding.
"""
def __init__(self, f, dialect=csv.excel, encoding="utf-8", **kwds):
f = UTF8Recoder(f, encoding)
self.reader = csv.reader(f, dialect=dialect, **kwds)
def next(self):
row = self.reader.next()
return [unicode(s, "utf-8") for s in row]
def __iter__(self):
return self
class UnicodeWriter:
"""
A CSV writer which will write rows to CSV file "f",
which is encoded in the given encoding.
"""
def __init__(self, f, dialect=csv.excel, encoding="utf-8", **kwds):
# Redirect output to a queue
self.queue = cStringIO.StringIO()
self.writer = csv.writer(self.queue, dialect=dialect, **kwds)
self.stream = f
self.encoder = codecs.getincrementalencoder(encoding)()
def writerow(self, row):
self.writer.writerow([s.encode("utf-8") for s in row])
# Fetch UTF-8 output from the queue ...
data = self.queue.getvalue()
data = data.decode("utf-8")
# ... and reencode it into the target encoding
data = self.encoder.encode(data)
# write to the target stream
self.stream.write(data)
# empty queue
self.queue.truncate(0)
def writerows(self, rows):
for row in rows:
self.writerow(row)
PK %�\�� ��a �a $ html/_sources/library/ctypes.rst.txtnu �[��� :mod:`ctypes` --- A foreign function library for Python
=======================================================
.. module:: ctypes
:synopsis: A foreign function library for Python.
.. moduleauthor:: Thomas Heller <theller@python.net>
.. versionadded:: 2.5
:mod:`ctypes` is a foreign function library for Python. It provides C compatible
data types, and allows calling functions in DLLs or shared libraries. It can be
used to wrap these libraries in pure Python.
.. _ctypes-ctypes-tutorial:
ctypes tutorial
---------------
Note: The code samples in this tutorial use :mod:`doctest` to make sure that
they actually work. Since some code samples behave differently under Linux,
Windows, or Mac OS X, they contain doctest directives in comments.
Note: Some code samples reference the ctypes :class:`c_int` type. This type is
an alias for the :class:`c_long` type on 32-bit systems. So, you should not be
confused if :class:`c_long` is printed if you would expect :class:`c_int` ---
they are actually the same type.
.. _ctypes-loading-dynamic-link-libraries:
Loading dynamic link libraries
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
:mod:`ctypes` exports the *cdll*, and on Windows *windll* and *oledll*
objects, for loading dynamic link libraries.
You load libraries by accessing them as attributes of these objects. *cdll*
loads libraries which export functions using the standard ``cdecl`` calling
convention, while *windll* libraries call functions using the ``stdcall``
calling convention. *oledll* also uses the ``stdcall`` calling convention, and
assumes the functions return a Windows :c:type:`HRESULT` error code. The error
code is used to automatically raise a :class:`WindowsError` exception when the
function call fails.
Here are some examples for Windows. Note that ``msvcrt`` is the MS standard C
library containing most standard C functions, and uses the cdecl calling
convention::
>>> from ctypes import *
>>> print windll.kernel32 # doctest: +WINDOWS
<WinDLL 'kernel32', handle ... at ...>
>>> print cdll.msvcrt # doctest: +WINDOWS
<CDLL 'msvcrt', handle ... at ...>
>>> libc = cdll.msvcrt # doctest: +WINDOWS
>>>
Windows appends the usual ``.dll`` file suffix automatically.
On Linux, it is required to specify the filename *including* the extension to
load a library, so attribute access can not be used to load libraries. Either the
:meth:`LoadLibrary` method of the dll loaders should be used, or you should load
the library by creating an instance of CDLL by calling the constructor::
>>> cdll.LoadLibrary("libc.so.6") # doctest: +LINUX
<CDLL 'libc.so.6', handle ... at ...>
>>> libc = CDLL("libc.so.6") # doctest: +LINUX
>>> libc # doctest: +LINUX
<CDLL 'libc.so.6', handle ... at ...>
>>>
.. XXX Add section for Mac OS X.
.. _ctypes-accessing-functions-from-loaded-dlls:
Accessing functions from loaded dlls
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Functions are accessed as attributes of dll objects::
>>> from ctypes import *
>>> libc.printf
<_FuncPtr object at 0x...>
>>> print windll.kernel32.GetModuleHandleA # doctest: +WINDOWS
<_FuncPtr object at 0x...>
>>> print windll.kernel32.MyOwnFunction # doctest: +WINDOWS
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "ctypes.py", line 239, in __getattr__
func = _StdcallFuncPtr(name, self)
AttributeError: function 'MyOwnFunction' not found
>>>
Note that win32 system dlls like ``kernel32`` and ``user32`` often export ANSI
as well as UNICODE versions of a function. The UNICODE version is exported with
an ``W`` appended to the name, while the ANSI version is exported with an ``A``
appended to the name. The win32 ``GetModuleHandle`` function, which returns a
*module handle* for a given module name, has the following C prototype, and a
macro is used to expose one of them as ``GetModuleHandle`` depending on whether
UNICODE is defined or not::
/* ANSI version */
HMODULE GetModuleHandleA(LPCSTR lpModuleName);
/* UNICODE version */
HMODULE GetModuleHandleW(LPCWSTR lpModuleName);
*windll* does not try to select one of them by magic, you must access the
version you need by specifying ``GetModuleHandleA`` or ``GetModuleHandleW``
explicitly, and then call it with strings or unicode strings
respectively.
Sometimes, dlls export functions with names which aren't valid Python
identifiers, like ``"??2@YAPAXI@Z"``. In this case you have to use
:func:`getattr` to retrieve the function::
>>> getattr(cdll.msvcrt, "??2@YAPAXI@Z") # doctest: +WINDOWS
<_FuncPtr object at 0x...>
>>>
On Windows, some dlls export functions not by name but by ordinal. These
functions can be accessed by indexing the dll object with the ordinal number::
>>> cdll.kernel32[1] # doctest: +WINDOWS
<_FuncPtr object at 0x...>
>>> cdll.kernel32[0] # doctest: +WINDOWS
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "ctypes.py", line 310, in __getitem__
func = _StdcallFuncPtr(name, self)
AttributeError: function ordinal 0 not found
>>>
.. _ctypes-calling-functions:
Calling functions
^^^^^^^^^^^^^^^^^
You can call these functions like any other Python callable. This example uses
the ``time()`` function, which returns system time in seconds since the Unix
epoch, and the ``GetModuleHandleA()`` function, which returns a win32 module
handle.
This example calls both functions with a NULL pointer (``None`` should be used
as the NULL pointer)::
>>> print libc.time(None) # doctest: +SKIP
1150640792
>>> print hex(windll.kernel32.GetModuleHandleA(None)) # doctest: +WINDOWS
0x1d000000
>>>
:mod:`ctypes` tries to protect you from calling functions with the wrong number
of arguments or the wrong calling convention. Unfortunately this only works on
Windows. It does this by examining the stack after the function returns, so
although an error is raised the function *has* been called::
>>> windll.kernel32.GetModuleHandleA() # doctest: +WINDOWS
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ValueError: Procedure probably called with not enough arguments (4 bytes missing)
>>> windll.kernel32.GetModuleHandleA(0, 0) # doctest: +WINDOWS
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ValueError: Procedure probably called with too many arguments (4 bytes in excess)
>>>
The same exception is raised when you call an ``stdcall`` function with the
``cdecl`` calling convention, or vice versa::
>>> cdll.kernel32.GetModuleHandleA(None) # doctest: +WINDOWS
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ValueError: Procedure probably called with not enough arguments (4 bytes missing)
>>>
>>> windll.msvcrt.printf("spam") # doctest: +WINDOWS
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ValueError: Procedure probably called with too many arguments (4 bytes in excess)
>>>
To find out the correct calling convention you have to look into the C header
file or the documentation for the function you want to call.
On Windows, :mod:`ctypes` uses win32 structured exception handling to prevent
crashes from general protection faults when functions are called with invalid
argument values::
>>> windll.kernel32.GetModuleHandleA(32) # doctest: +WINDOWS
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
WindowsError: exception: access violation reading 0x00000020
>>>
There are, however, enough ways to crash Python with :mod:`ctypes`, so you
should be careful anyway.
``None``, integers, longs, byte strings and unicode strings are the only native
Python objects that can directly be used as parameters in these function calls.
``None`` is passed as a C ``NULL`` pointer, byte strings and unicode strings are
passed as pointer to the memory block that contains their data (:c:type:`char *`
or :c:type:`wchar_t *`). Python integers and Python longs are passed as the
platforms default C :c:type:`int` type, their value is masked to fit into the C
type.
Before we move on calling functions with other parameter types, we have to learn
more about :mod:`ctypes` data types.
.. _ctypes-fundamental-data-types:
Fundamental data types
^^^^^^^^^^^^^^^^^^^^^^
:mod:`ctypes` defines a number of primitive C compatible data types:
+----------------------+------------------------------------------+----------------------------+
| ctypes type | C type | Python type |
+======================+==========================================+============================+
| :class:`c_bool` | :c:type:`_Bool` | bool (1) |
+----------------------+------------------------------------------+----------------------------+
| :class:`c_char` | :c:type:`char` | 1-character string |
+----------------------+------------------------------------------+----------------------------+
| :class:`c_wchar` | :c:type:`wchar_t` | 1-character unicode string |
+----------------------+------------------------------------------+----------------------------+
| :class:`c_byte` | :c:type:`char` | int/long |
+----------------------+------------------------------------------+----------------------------+
| :class:`c_ubyte` | :c:type:`unsigned char` | int/long |
+----------------------+------------------------------------------+----------------------------+
| :class:`c_short` | :c:type:`short` | int/long |
+----------------------+------------------------------------------+----------------------------+
| :class:`c_ushort` | :c:type:`unsigned short` | int/long |
+----------------------+------------------------------------------+----------------------------+
| :class:`c_int` | :c:type:`int` | int/long |
+----------------------+------------------------------------------+----------------------------+
| :class:`c_uint` | :c:type:`unsigned int` | int/long |
+----------------------+------------------------------------------+----------------------------+
| :class:`c_long` | :c:type:`long` | int/long |
+----------------------+------------------------------------------+----------------------------+
| :class:`c_ulong` | :c:type:`unsigned long` | int/long |
+----------------------+------------------------------------------+----------------------------+
| :class:`c_longlong` | :c:type:`__int64` or :c:type:`long long` | int/long |
+----------------------+------------------------------------------+----------------------------+
| :class:`c_ulonglong` | :c:type:`unsigned __int64` or | int/long |
| | :c:type:`unsigned long long` | |
+----------------------+------------------------------------------+----------------------------+
| :class:`c_float` | :c:type:`float` | float |
+----------------------+------------------------------------------+----------------------------+
| :class:`c_double` | :c:type:`double` | float |
+----------------------+------------------------------------------+----------------------------+
| :class:`c_longdouble`| :c:type:`long double` | float |
+----------------------+------------------------------------------+----------------------------+
| :class:`c_char_p` | :c:type:`char *` (NUL terminated) | string or ``None`` |
+----------------------+------------------------------------------+----------------------------+
| :class:`c_wchar_p` | :c:type:`wchar_t *` (NUL terminated) | unicode or ``None`` |
+----------------------+------------------------------------------+----------------------------+
| :class:`c_void_p` | :c:type:`void *` | int/long or ``None`` |
+----------------------+------------------------------------------+----------------------------+
(1)
The constructor accepts any object with a truth value.
All these types can be created by calling them with an optional initializer of
the correct type and value::
>>> c_int()
c_long(0)
>>> c_char_p("Hello, World")
c_char_p('Hello, World')
>>> c_ushort(-3)
c_ushort(65533)
>>>
Since these types are mutable, their value can also be changed afterwards::
>>> i = c_int(42)
>>> print i
c_long(42)
>>> print i.value
42
>>> i.value = -99
>>> print i.value
-99
>>>
Assigning a new value to instances of the pointer types :class:`c_char_p`,
:class:`c_wchar_p`, and :class:`c_void_p` changes the *memory location* they
point to, *not the contents* of the memory block (of course not, because Python
strings are immutable)::
>>> s = "Hello, World"
>>> c_s = c_char_p(s)
>>> print c_s
c_char_p('Hello, World')
>>> c_s.value = "Hi, there"
>>> print c_s
c_char_p('Hi, there')
>>> print s # first string is unchanged
Hello, World
>>>
You should be careful, however, not to pass them to functions expecting pointers
to mutable memory. If you need mutable memory blocks, ctypes has a
:func:`create_string_buffer` function which creates these in various ways. The
current memory block contents can be accessed (or changed) with the ``raw``
property; if you want to access it as NUL terminated string, use the ``value``
property::
>>> from ctypes import *
>>> p = create_string_buffer(3) # create a 3 byte buffer, initialized to NUL bytes
>>> print sizeof(p), repr(p.raw)
3 '\x00\x00\x00'
>>> p = create_string_buffer("Hello") # create a buffer containing a NUL terminated string
>>> print sizeof(p), repr(p.raw)
6 'Hello\x00'
>>> print repr(p.value)
'Hello'
>>> p = create_string_buffer("Hello", 10) # create a 10 byte buffer
>>> print sizeof(p), repr(p.raw)
10 'Hello\x00\x00\x00\x00\x00'
>>> p.value = "Hi"
>>> print sizeof(p), repr(p.raw)
10 'Hi\x00lo\x00\x00\x00\x00\x00'
>>>
The :func:`create_string_buffer` function replaces the :func:`c_buffer` function
(which is still available as an alias), as well as the :func:`c_string` function
from earlier ctypes releases. To create a mutable memory block containing
unicode characters of the C type :c:type:`wchar_t` use the
:func:`create_unicode_buffer` function.
.. _ctypes-calling-functions-continued:
Calling functions, continued
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Note that printf prints to the real standard output channel, *not* to
:data:`sys.stdout`, so these examples will only work at the console prompt, not
from within *IDLE* or *PythonWin*::
>>> printf = libc.printf
>>> printf("Hello, %s\n", "World!")
Hello, World!
14
>>> printf("Hello, %S\n", u"World!")
Hello, World!
14
>>> printf("%d bottles of beer\n", 42)
42 bottles of beer
19
>>> printf("%f bottles of beer\n", 42.5)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ArgumentError: argument 2: exceptions.TypeError: Don't know how to convert parameter 2
>>>
As has been mentioned before, all Python types except integers, strings, and
unicode strings have to be wrapped in their corresponding :mod:`ctypes` type, so
that they can be converted to the required C data type::
>>> printf("An int %d, a double %f\n", 1234, c_double(3.14))
An int 1234, a double 3.140000
31
>>>
.. _ctypes-calling-functions-with-own-custom-data-types:
Calling functions with your own custom data types
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You can also customize :mod:`ctypes` argument conversion to allow instances of
your own classes be used as function arguments. :mod:`ctypes` looks for an
:attr:`_as_parameter_` attribute and uses this as the function argument. Of
course, it must be one of integer, string, or unicode::
>>> class Bottles(object):
... def __init__(self, number):
... self._as_parameter_ = number
...
>>> bottles = Bottles(42)
>>> printf("%d bottles of beer\n", bottles)
42 bottles of beer
19
>>>
If you don't want to store the instance's data in the :attr:`_as_parameter_`
instance variable, you could define a :func:`property` which makes the data
available.
.. _ctypes-specifying-required-argument-types:
Specifying the required argument types (function prototypes)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
It is possible to specify the required argument types of functions exported from
DLLs by setting the :attr:`argtypes` attribute.
:attr:`argtypes` must be a sequence of C data types (the ``printf`` function is
probably not a good example here, because it takes a variable number and
different types of parameters depending on the format string, on the other hand
this is quite handy to experiment with this feature)::
>>> printf.argtypes = [c_char_p, c_char_p, c_int, c_double]
>>> printf("String '%s', Int %d, Double %f\n", "Hi", 10, 2.2)
String 'Hi', Int 10, Double 2.200000
37
>>>
Specifying a format protects against incompatible argument types (just as a
prototype for a C function), and tries to convert the arguments to valid types::
>>> printf("%d %d %d", 1, 2, 3)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ArgumentError: argument 2: exceptions.TypeError: wrong type
>>> printf("%s %d %f\n", "X", 2, 3)
X 2 3.000000
13
>>>
If you have defined your own classes which you pass to function calls, you have
to implement a :meth:`from_param` class method for them to be able to use them
in the :attr:`argtypes` sequence. The :meth:`from_param` class method receives
the Python object passed to the function call, it should do a typecheck or
whatever is needed to make sure this object is acceptable, and then return the
object itself, its :attr:`_as_parameter_` attribute, or whatever you want to
pass as the C function argument in this case. Again, the result should be an
integer, string, unicode, a :mod:`ctypes` instance, or an object with an
:attr:`_as_parameter_` attribute.
.. _ctypes-return-types:
Return types
^^^^^^^^^^^^
By default functions are assumed to return the C :c:type:`int` type. Other
return types can be specified by setting the :attr:`restype` attribute of the
function object.
Here is a more advanced example, it uses the ``strchr`` function, which expects
a string pointer and a char, and returns a pointer to a string::
>>> strchr = libc.strchr
>>> strchr("abcdef", ord("d")) # doctest: +SKIP
8059983
>>> strchr.restype = c_char_p # c_char_p is a pointer to a string
>>> strchr("abcdef", ord("d"))
'def'
>>> print strchr("abcdef", ord("x"))
None
>>>
If you want to avoid the ``ord("x")`` calls above, you can set the
:attr:`argtypes` attribute, and the second argument will be converted from a
single character Python string into a C char::
>>> strchr.restype = c_char_p
>>> strchr.argtypes = [c_char_p, c_char]
>>> strchr("abcdef", "d")
'def'
>>> strchr("abcdef", "def")
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ArgumentError: argument 2: exceptions.TypeError: one character string expected
>>> print strchr("abcdef", "x")
None
>>> strchr("abcdef", "d")
'def'
>>>
You can also use a callable Python object (a function or a class for example) as
the :attr:`restype` attribute, if the foreign function returns an integer. The
callable will be called with the *integer* the C function returns, and the
result of this call will be used as the result of your function call. This is
useful to check for error return values and automatically raise an exception::
>>> GetModuleHandle = windll.kernel32.GetModuleHandleA # doctest: +WINDOWS
>>> def ValidHandle(value):
... if value == 0:
... raise WinError()
... return value
...
>>>
>>> GetModuleHandle.restype = ValidHandle # doctest: +WINDOWS
>>> GetModuleHandle(None) # doctest: +WINDOWS
486539264
>>> GetModuleHandle("something silly") # doctest: +WINDOWS
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "<stdin>", line 3, in ValidHandle
WindowsError: [Errno 126] The specified module could not be found.
>>>
``WinError`` is a function which will call Windows ``FormatMessage()`` api to
get the string representation of an error code, and *returns* an exception.
``WinError`` takes an optional error code parameter, if no one is used, it calls
:func:`GetLastError` to retrieve it.
Please note that a much more powerful error checking mechanism is available
through the :attr:`errcheck` attribute; see the reference manual for details.
.. _ctypes-passing-pointers:
Passing pointers (or: passing parameters by reference)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Sometimes a C api function expects a *pointer* to a data type as parameter,
probably to write into the corresponding location, or if the data is too large
to be passed by value. This is also known as *passing parameters by reference*.
:mod:`ctypes` exports the :func:`byref` function which is used to pass
parameters by reference. The same effect can be achieved with the
:func:`pointer` function, although :func:`pointer` does a lot more work since it
constructs a real pointer object, so it is faster to use :func:`byref` if you
don't need the pointer object in Python itself::
>>> i = c_int()
>>> f = c_float()
>>> s = create_string_buffer('\000' * 32)
>>> print i.value, f.value, repr(s.value)
0 0.0 ''
>>> libc.sscanf("1 3.14 Hello", "%d %f %s",
... byref(i), byref(f), s)
3
>>> print i.value, f.value, repr(s.value)
1 3.1400001049 'Hello'
>>>
.. _ctypes-structures-unions:
Structures and unions
^^^^^^^^^^^^^^^^^^^^^
Structures and unions must derive from the :class:`Structure` and :class:`Union`
base classes which are defined in the :mod:`ctypes` module. Each subclass must
define a :attr:`_fields_` attribute. :attr:`_fields_` must be a list of
*2-tuples*, containing a *field name* and a *field type*.
The field type must be a :mod:`ctypes` type like :class:`c_int`, or any other
derived :mod:`ctypes` type: structure, union, array, pointer.
Here is a simple example of a POINT structure, which contains two integers named
*x* and *y*, and also shows how to initialize a structure in the constructor::
>>> from ctypes import *
>>> class POINT(Structure):
... _fields_ = [("x", c_int),
... ("y", c_int)]
...
>>> point = POINT(10, 20)
>>> print point.x, point.y
10 20
>>> point = POINT(y=5)
>>> print point.x, point.y
0 5
>>> POINT(1, 2, 3)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ValueError: too many initializers
>>>
You can, however, build much more complicated structures. A structure can
itself contain other structures by using a structure as a field type.
Here is a RECT structure which contains two POINTs named *upperleft* and
*lowerright*::
>>> class RECT(Structure):
... _fields_ = [("upperleft", POINT),
... ("lowerright", POINT)]
...
>>> rc = RECT(point)
>>> print rc.upperleft.x, rc.upperleft.y
0 5
>>> print rc.lowerright.x, rc.lowerright.y
0 0
>>>
Nested structures can also be initialized in the constructor in several ways::
>>> r = RECT(POINT(1, 2), POINT(3, 4))
>>> r = RECT((1, 2), (3, 4))
Field :term:`descriptor`\s can be retrieved from the *class*, they are useful
for debugging because they can provide useful information::
>>> print POINT.x
<Field type=c_long, ofs=0, size=4>
>>> print POINT.y
<Field type=c_long, ofs=4, size=4>
>>>
.. _ctypes-structureunion-alignment-byte-order:
.. warning::
:mod:`ctypes` does not support passing unions or structures with bit-fields
to functions by value. While this may work on 32-bit x86, it's not
guaranteed by the library to work in the general case. Unions and
structures with bit-fields should always be passed to functions by pointer.
Structure/union alignment and byte order
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
By default, Structure and Union fields are aligned in the same way the C
compiler does it. It is possible to override this behavior be specifying a
:attr:`_pack_` class attribute in the subclass definition. This must be set to a
positive integer and specifies the maximum alignment for the fields. This is
what ``#pragma pack(n)`` also does in MSVC.
:mod:`ctypes` uses the native byte order for Structures and Unions. To build
structures with non-native byte order, you can use one of the
:class:`BigEndianStructure`, :class:`LittleEndianStructure`,
:class:`BigEndianUnion`, and :class:`LittleEndianUnion` base classes. These
classes cannot contain pointer fields.
.. _ctypes-bit-fields-in-structures-unions:
Bit fields in structures and unions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
It is possible to create structures and unions containing bit fields. Bit fields
are only possible for integer fields, the bit width is specified as the third
item in the :attr:`_fields_` tuples::
>>> class Int(Structure):
... _fields_ = [("first_16", c_int, 16),
... ("second_16", c_int, 16)]
...
>>> print Int.first_16
<Field type=c_long, ofs=0:0, bits=16>
>>> print Int.second_16
<Field type=c_long, ofs=0:16, bits=16>
>>>
.. _ctypes-arrays:
Arrays
^^^^^^
Arrays are sequences, containing a fixed number of instances of the same type.
The recommended way to create array types is by multiplying a data type with a
positive integer::
TenPointsArrayType = POINT * 10
Here is an example of a somewhat artificial data type, a structure containing 4
POINTs among other stuff::
>>> from ctypes import *
>>> class POINT(Structure):
... _fields_ = ("x", c_int), ("y", c_int)
...
>>> class MyStruct(Structure):
... _fields_ = [("a", c_int),
... ("b", c_float),
... ("point_array", POINT * 4)]
>>>
>>> print len(MyStruct().point_array)
4
>>>
Instances are created in the usual way, by calling the class::
arr = TenPointsArrayType()
for pt in arr:
print pt.x, pt.y
The above code print a series of ``0 0`` lines, because the array contents is
initialized to zeros.
Initializers of the correct type can also be specified::
>>> from ctypes import *
>>> TenIntegers = c_int * 10
>>> ii = TenIntegers(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
>>> print ii
<c_long_Array_10 object at 0x...>
>>> for i in ii: print i,
...
1 2 3 4 5 6 7 8 9 10
>>>
.. _ctypes-pointers:
Pointers
^^^^^^^^
Pointer instances are created by calling the :func:`pointer` function on a
:mod:`ctypes` type::
>>> from ctypes import *
>>> i = c_int(42)
>>> pi = pointer(i)
>>>
Pointer instances have a :attr:`~_Pointer.contents` attribute which
returns the object to which the pointer points, the ``i`` object above::
>>> pi.contents
c_long(42)
>>>
Note that :mod:`ctypes` does not have OOR (original object return), it constructs a
new, equivalent object each time you retrieve an attribute::
>>> pi.contents is i
False
>>> pi.contents is pi.contents
False
>>>
Assigning another :class:`c_int` instance to the pointer's contents attribute
would cause the pointer to point to the memory location where this is stored::
>>> i = c_int(99)
>>> pi.contents = i
>>> pi.contents
c_long(99)
>>>
.. XXX Document dereferencing pointers, and that it is preferred over the
.contents attribute.
Pointer instances can also be indexed with integers::
>>> pi[0]
99
>>>
Assigning to an integer index changes the pointed to value::
>>> print i
c_long(99)
>>> pi[0] = 22
>>> print i
c_long(22)
>>>
It is also possible to use indexes different from 0, but you must know what
you're doing, just as in C: You can access or change arbitrary memory locations.
Generally you only use this feature if you receive a pointer from a C function,
and you *know* that the pointer actually points to an array instead of a single
item.
Behind the scenes, the :func:`pointer` function does more than simply create
pointer instances, it has to create pointer *types* first. This is done with
the :func:`POINTER` function, which accepts any :mod:`ctypes` type, and returns
a new type::
>>> PI = POINTER(c_int)
>>> PI
<class 'ctypes.LP_c_long'>
>>> PI(42)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: expected c_long instead of int
>>> PI(c_int(42))
<ctypes.LP_c_long object at 0x...>
>>>
Calling the pointer type without an argument creates a ``NULL`` pointer.
``NULL`` pointers have a ``False`` boolean value::
>>> null_ptr = POINTER(c_int)()
>>> print bool(null_ptr)
False
>>>
:mod:`ctypes` checks for ``NULL`` when dereferencing pointers (but dereferencing
invalid non-\ ``NULL`` pointers would crash Python)::
>>> null_ptr[0]
Traceback (most recent call last):
....
ValueError: NULL pointer access
>>>
>>> null_ptr[0] = 1234
Traceback (most recent call last):
....
ValueError: NULL pointer access
>>>
.. _ctypes-type-conversions:
Type conversions
^^^^^^^^^^^^^^^^
Usually, ctypes does strict type checking. This means, if you have
``POINTER(c_int)`` in the :attr:`argtypes` list of a function or as the type of
a member field in a structure definition, only instances of exactly the same
type are accepted. There are some exceptions to this rule, where ctypes accepts
other objects. For example, you can pass compatible array instances instead of
pointer types. So, for ``POINTER(c_int)``, ctypes accepts an array of c_int::
>>> class Bar(Structure):
... _fields_ = [("count", c_int), ("values", POINTER(c_int))]
...
>>> bar = Bar()
>>> bar.values = (c_int * 3)(1, 2, 3)
>>> bar.count = 3
>>> for i in range(bar.count):
... print bar.values[i]
...
1
2
3
>>>
In addition, if a function argument is explicitly declared to be a pointer type
(such as ``POINTER(c_int)``) in :attr:`argtypes`, an object of the pointed
type (``c_int`` in this case) can be passed to the function. ctypes will apply
the required :func:`byref` conversion in this case automatically.
To set a POINTER type field to ``NULL``, you can assign ``None``::
>>> bar.values = None
>>>
.. XXX list other conversions...
Sometimes you have instances of incompatible types. In C, you can cast one type
into another type. :mod:`ctypes` provides a :func:`cast` function which can be
used in the same way. The ``Bar`` structure defined above accepts
``POINTER(c_int)`` pointers or :class:`c_int` arrays for its ``values`` field,
but not instances of other types::
>>> bar.values = (c_byte * 4)()
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: incompatible types, c_byte_Array_4 instance instead of LP_c_long instance
>>>
For these cases, the :func:`cast` function is handy.
The :func:`cast` function can be used to cast a ctypes instance into a pointer
to a different ctypes data type. :func:`cast` takes two parameters, a ctypes
object that is or can be converted to a pointer of some kind, and a ctypes
pointer type. It returns an instance of the second argument, which references
the same memory block as the first argument::
>>> a = (c_byte * 4)()
>>> cast(a, POINTER(c_int))
<ctypes.LP_c_long object at ...>
>>>
So, :func:`cast` can be used to assign to the ``values`` field of ``Bar`` the
structure::
>>> bar = Bar()
>>> bar.values = cast((c_byte * 4)(), POINTER(c_int))
>>> print bar.values[0]
0
>>>
.. _ctypes-incomplete-types:
Incomplete Types
^^^^^^^^^^^^^^^^
*Incomplete Types* are structures, unions or arrays whose members are not yet
specified. In C, they are specified by forward declarations, which are defined
later::
struct cell; /* forward declaration */
struct cell {
char *name;
struct cell *next;
};
The straightforward translation into ctypes code would be this, but it does not
work::
>>> class cell(Structure):
... _fields_ = [("name", c_char_p),
... ("next", POINTER(cell))]
...
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "<stdin>", line 2, in cell
NameError: name 'cell' is not defined
>>>
because the new ``class cell`` is not available in the class statement itself.
In :mod:`ctypes`, we can define the ``cell`` class and set the :attr:`_fields_`
attribute later, after the class statement::
>>> from ctypes import *
>>> class cell(Structure):
... pass
...
>>> cell._fields_ = [("name", c_char_p),
... ("next", POINTER(cell))]
>>>
Lets try it. We create two instances of ``cell``, and let them point to each
other, and finally follow the pointer chain a few times::
>>> c1 = cell()
>>> c1.name = "foo"
>>> c2 = cell()
>>> c2.name = "bar"
>>> c1.next = pointer(c2)
>>> c2.next = pointer(c1)
>>> p = c1
>>> for i in range(8):
... print p.name,
... p = p.next[0]
...
foo bar foo bar foo bar foo bar
>>>
.. _ctypes-callback-functions:
Callback functions
^^^^^^^^^^^^^^^^^^
:mod:`ctypes` allows creating C callable function pointers from Python callables.
These are sometimes called *callback functions*.
First, you must create a class for the callback function, the class knows the
calling convention, the return type, and the number and types of arguments this
function will receive.
The CFUNCTYPE factory function creates types for callback functions using the
normal cdecl calling convention, and, on Windows, the WINFUNCTYPE factory
function creates types for callback functions using the stdcall calling
convention.
Both of these factory functions are called with the result type as first
argument, and the callback functions expected argument types as the remaining
arguments.
I will present an example here which uses the standard C library's :func:`qsort`
function, this is used to sort items with the help of a callback function.
:func:`qsort` will be used to sort an array of integers::
>>> IntArray5 = c_int * 5
>>> ia = IntArray5(5, 1, 7, 33, 99)
>>> qsort = libc.qsort
>>> qsort.restype = None
>>>
:func:`qsort` must be called with a pointer to the data to sort, the number of
items in the data array, the size of one item, and a pointer to the comparison
function, the callback. The callback will then be called with two pointers to
items, and it must return a negative integer if the first item is smaller than
the second, a zero if they are equal, and a positive integer else.
So our callback function receives pointers to integers, and must return an
integer. First we create the ``type`` for the callback function::
>>> CMPFUNC = CFUNCTYPE(c_int, POINTER(c_int), POINTER(c_int))
>>>
For the first implementation of the callback function, we simply print the
arguments we get, and return 0 (incremental development ;-)::
>>> def py_cmp_func(a, b):
... print "py_cmp_func", a, b
... return 0
...
>>>
Create the C callable callback::
>>> cmp_func = CMPFUNC(py_cmp_func)
>>>
And we're ready to go::
>>> qsort(ia, len(ia), sizeof(c_int), cmp_func) # doctest: +WINDOWS
py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...>
py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...>
py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...>
py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...>
py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...>
py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...>
py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...>
py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...>
py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...>
py_cmp_func <ctypes.LP_c_long object at 0x00...> <ctypes.LP_c_long object at 0x00...>
>>>
We know how to access the contents of a pointer, so lets redefine our callback::
>>> def py_cmp_func(a, b):
... print "py_cmp_func", a[0], b[0]
... return 0
...
>>> cmp_func = CMPFUNC(py_cmp_func)
>>>
Here is what we get on Windows::
>>> qsort(ia, len(ia), sizeof(c_int), cmp_func) # doctest: +WINDOWS
py_cmp_func 7 1
py_cmp_func 33 1
py_cmp_func 99 1
py_cmp_func 5 1
py_cmp_func 7 5
py_cmp_func 33 5
py_cmp_func 99 5
py_cmp_func 7 99
py_cmp_func 33 99
py_cmp_func 7 33
>>>
It is funny to see that on linux the sort function seems to work much more
efficiently, it is doing less comparisons::
>>> qsort(ia, len(ia), sizeof(c_int), cmp_func) # doctest: +LINUX
py_cmp_func 5 1
py_cmp_func 33 99
py_cmp_func 7 33
py_cmp_func 5 7
py_cmp_func 1 7
>>>
Ah, we're nearly done! The last step is to actually compare the two items and
return a useful result::
>>> def py_cmp_func(a, b):
... print "py_cmp_func", a[0], b[0]
... return a[0] - b[0]
...
>>>
Final run on Windows::
>>> qsort(ia, len(ia), sizeof(c_int), CMPFUNC(py_cmp_func)) # doctest: +WINDOWS
py_cmp_func 33 7
py_cmp_func 99 33
py_cmp_func 5 99
py_cmp_func 1 99
py_cmp_func 33 7
py_cmp_func 1 33
py_cmp_func 5 33
py_cmp_func 5 7
py_cmp_func 1 7
py_cmp_func 5 1
>>>
and on Linux::
>>> qsort(ia, len(ia), sizeof(c_int), CMPFUNC(py_cmp_func)) # doctest: +LINUX
py_cmp_func 5 1
py_cmp_func 33 99
py_cmp_func 7 33
py_cmp_func 1 7
py_cmp_func 5 7
>>>
It is quite interesting to see that the Windows :func:`qsort` function needs
more comparisons than the linux version!
As we can easily check, our array is sorted now::
>>> for i in ia: print i,
...
1 5 7 33 99
>>>
.. note::
Make sure you keep references to :func:`CFUNCTYPE` objects as long as they
are used from C code. :mod:`ctypes` doesn't, and if you don't, they may be
garbage collected, crashing your program when a callback is made.
Also, note that if the callback function is called in a thread created
outside of Python's control (e.g. by the foreign code that calls the
callback), ctypes creates a new dummy Python thread on every invocation. This
behavior is correct for most purposes, but it means that values stored with
:class:`threading.local` will *not* survive across different callbacks, even when
those calls are made from the same C thread.
.. _ctypes-accessing-values-exported-from-dlls:
Accessing values exported from dlls
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Some shared libraries not only export functions, they also export variables. An
example in the Python library itself is the ``Py_OptimizeFlag``, an integer set
to 0, 1, or 2, depending on the :option:`-O` or :option:`-OO` flag given on
startup.
:mod:`ctypes` can access values like this with the :meth:`in_dll` class methods of
the type. *pythonapi* is a predefined symbol giving access to the Python C
api::
>>> opt_flag = c_int.in_dll(pythonapi, "Py_OptimizeFlag")
>>> print opt_flag
c_long(0)
>>>
If the interpreter would have been started with :option:`-O`, the sample would
have printed ``c_long(1)``, or ``c_long(2)`` if :option:`-OO` would have been
specified.
An extended example which also demonstrates the use of pointers accesses the
``PyImport_FrozenModules`` pointer exported by Python.
Quoting the Python docs: *This pointer is initialized to point to an array of
"struct _frozen" records, terminated by one whose members are all NULL or zero.
When a frozen module is imported, it is searched in this table. Third-party code
could play tricks with this to provide a dynamically created collection of
frozen modules.*
So manipulating this pointer could even prove useful. To restrict the example
size, we show only how this table can be read with :mod:`ctypes`::
>>> from ctypes import *
>>>
>>> class struct_frozen(Structure):
... _fields_ = [("name", c_char_p),
... ("code", POINTER(c_ubyte)),
... ("size", c_int)]
...
>>>
We have defined the ``struct _frozen`` data type, so we can get the pointer to
the table::
>>> FrozenTable = POINTER(struct_frozen)
>>> table = FrozenTable.in_dll(pythonapi, "PyImport_FrozenModules")
>>>
Since ``table`` is a ``pointer`` to the array of ``struct_frozen`` records, we
can iterate over it, but we just have to make sure that our loop terminates,
because pointers have no size. Sooner or later it would probably crash with an
access violation or whatever, so it's better to break out of the loop when we
hit the NULL entry::
>>> for item in table:
... print item.name, item.size
... if item.name is None:
... break
...
__hello__ 104
__phello__ -104
__phello__.spam 104
None 0
>>>
The fact that standard Python has a frozen module and a frozen package
(indicated by the negative size member) is not well known, it is only used for
testing. Try it out with ``import __hello__`` for example.
.. _ctypes-surprises:
Surprises
^^^^^^^^^
There are some edge cases in :mod:`ctypes` where you might expect something
other than what actually happens.
Consider the following example::
>>> from ctypes import *
>>> class POINT(Structure):
... _fields_ = ("x", c_int), ("y", c_int)
...
>>> class RECT(Structure):
... _fields_ = ("a", POINT), ("b", POINT)
...
>>> p1 = POINT(1, 2)
>>> p2 = POINT(3, 4)
>>> rc = RECT(p1, p2)
>>> print rc.a.x, rc.a.y, rc.b.x, rc.b.y
1 2 3 4
>>> # now swap the two points
>>> rc.a, rc.b = rc.b, rc.a
>>> print rc.a.x, rc.a.y, rc.b.x, rc.b.y
3 4 3 4
>>>
Hm. We certainly expected the last statement to print ``3 4 1 2``. What
happened? Here are the steps of the ``rc.a, rc.b = rc.b, rc.a`` line above::
>>> temp0, temp1 = rc.b, rc.a
>>> rc.a = temp0
>>> rc.b = temp1
>>>
Note that ``temp0`` and ``temp1`` are objects still using the internal buffer of
the ``rc`` object above. So executing ``rc.a = temp0`` copies the buffer
contents of ``temp0`` into ``rc`` 's buffer. This, in turn, changes the
contents of ``temp1``. So, the last assignment ``rc.b = temp1``, doesn't have
the expected effect.
Keep in mind that retrieving sub-objects from Structure, Unions, and Arrays
doesn't *copy* the sub-object, instead it retrieves a wrapper object accessing
the root-object's underlying buffer.
Another example that may behave different from what one would expect is this::
>>> s = c_char_p()
>>> s.value = "abc def ghi"
>>> s.value
'abc def ghi'
>>> s.value is s.value
False
>>>
Why is it printing ``False``? ctypes instances are objects containing a memory
block plus some :term:`descriptor`\s accessing the contents of the memory.
Storing a Python object in the memory block does not store the object itself,
instead the ``contents`` of the object is stored. Accessing the contents again
constructs a new Python object each time!
.. _ctypes-variable-sized-data-types:
Variable-sized data types
^^^^^^^^^^^^^^^^^^^^^^^^^
:mod:`ctypes` provides some support for variable-sized arrays and structures.
The :func:`resize` function can be used to resize the memory buffer of an
existing ctypes object. The function takes the object as first argument, and
the requested size in bytes as the second argument. The memory block cannot be
made smaller than the natural memory block specified by the objects type, a
:exc:`ValueError` is raised if this is tried::
>>> short_array = (c_short * 4)()
>>> print sizeof(short_array)
8
>>> resize(short_array, 4)
Traceback (most recent call last):
...
ValueError: minimum size is 8
>>> resize(short_array, 32)
>>> sizeof(short_array)
32
>>> sizeof(type(short_array))
8
>>>
This is nice and fine, but how would one access the additional elements
contained in this array? Since the type still only knows about 4 elements, we
get errors accessing other elements::
>>> short_array[:]
[0, 0, 0, 0]
>>> short_array[7]
Traceback (most recent call last):
...
IndexError: invalid index
>>>
Another way to use variable-sized data types with :mod:`ctypes` is to use the
dynamic nature of Python, and (re-)define the data type after the required size
is already known, on a case by case basis.
.. _ctypes-ctypes-reference:
ctypes reference
----------------
.. _ctypes-finding-shared-libraries:
Finding shared libraries
^^^^^^^^^^^^^^^^^^^^^^^^
When programming in a compiled language, shared libraries are accessed when
compiling/linking a program, and when the program is run.
The purpose of the :func:`find_library` function is to locate a library in a way
similar to what the compiler does (on platforms with several versions of a
shared library the most recent should be loaded), while the ctypes library
loaders act like when a program is run, and call the runtime loader directly.
The :mod:`ctypes.util` module provides a function which can help to determine the
library to load.
.. data:: find_library(name)
:module: ctypes.util
:noindex:
Try to find a library and return a pathname. *name* is the library name without
any prefix like *lib*, suffix like ``.so``, ``.dylib`` or version number (this
is the form used for the posix linker option :option:`!-l`). If no library can
be found, returns ``None``.
The exact functionality is system dependent.
On Linux, :func:`find_library` tries to run external programs
(``/sbin/ldconfig``, ``gcc``, and ``objdump``) to find the library file. It
returns the filename of the library file. Here are some examples::
>>> from ctypes.util import find_library
>>> find_library("m")
'libm.so.6'
>>> find_library("c")
'libc.so.6'
>>> find_library("bz2")
'libbz2.so.1.0'
>>>
On OS X, :func:`find_library` tries several predefined naming schemes and paths
to locate the library, and returns a full pathname if successful::
>>> from ctypes.util import find_library
>>> find_library("c")
'/usr/lib/libc.dylib'
>>> find_library("m")
'/usr/lib/libm.dylib'
>>> find_library("bz2")
'/usr/lib/libbz2.dylib'
>>> find_library("AGL")
'/System/Library/Frameworks/AGL.framework/AGL'
>>>
On Windows, :func:`find_library` searches along the system search path, and
returns the full pathname, but since there is no predefined naming scheme a call
like ``find_library("c")`` will fail and return ``None``.
If wrapping a shared library with :mod:`ctypes`, it *may* be better to determine
the shared library name at development time, and hardcode that into the wrapper
module instead of using :func:`find_library` to locate the library at runtime.
.. _ctypes-loading-shared-libraries:
Loading shared libraries
^^^^^^^^^^^^^^^^^^^^^^^^
There are several ways to load shared libraries into the Python process. One
way is to instantiate one of the following classes:
.. class:: CDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False)
Instances of this class represent loaded shared libraries. Functions in these
libraries use the standard C calling convention, and are assumed to return
:c:type:`int`.
.. class:: OleDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False)
Windows only: Instances of this class represent loaded shared libraries,
functions in these libraries use the ``stdcall`` calling convention, and are
assumed to return the windows specific :class:`HRESULT` code. :class:`HRESULT`
values contain information specifying whether the function call failed or
succeeded, together with additional error code. If the return value signals a
failure, an :class:`WindowsError` is automatically raised.
.. class:: WinDLL(name, mode=DEFAULT_MODE, handle=None, use_errno=False, use_last_error=False)
Windows only: Instances of this class represent loaded shared libraries,
functions in these libraries use the ``stdcall`` calling convention, and are
assumed to return :c:type:`int` by default.
On Windows CE only the standard calling convention is used, for convenience the
:class:`WinDLL` and :class:`OleDLL` use the standard calling convention on this
platform.
The Python :term:`global interpreter lock` is released before calling any
function exported by these libraries, and reacquired afterwards.
.. class:: PyDLL(name, mode=DEFAULT_MODE, handle=None)
Instances of this class behave like :class:`CDLL` instances, except that the
Python GIL is *not* released during the function call, and after the function
execution the Python error flag is checked. If the error flag is set, a Python
exception is raised.
Thus, this is only useful to call Python C api functions directly.
All these classes can be instantiated by calling them with at least one
argument, the pathname of the shared library. If you have an existing handle to
an already loaded shared library, it can be passed as the ``handle`` named
parameter, otherwise the underlying platforms ``dlopen`` or ``LoadLibrary``
function is used to load the library into the process, and to get a handle to
it.
The *mode* parameter can be used to specify how the library is loaded. For
details, consult the :manpage:`dlopen(3)` manpage. On Windows, *mode* is
ignored. On posix systems, RTLD_NOW is always added, and is not
configurable.
The *use_errno* parameter, when set to true, enables a ctypes mechanism that
allows accessing the system :data:`errno` error number in a safe way.
:mod:`ctypes` maintains a thread-local copy of the systems :data:`errno`
variable; if you call foreign functions created with ``use_errno=True`` then the
:data:`errno` value before the function call is swapped with the ctypes private
copy, the same happens immediately after the function call.
The function :func:`ctypes.get_errno` returns the value of the ctypes private
copy, and the function :func:`ctypes.set_errno` changes the ctypes private copy
to a new value and returns the former value.
The *use_last_error* parameter, when set to true, enables the same mechanism for
the Windows error code which is managed by the :func:`GetLastError` and
:func:`SetLastError` Windows API functions; :func:`ctypes.get_last_error` and
:func:`ctypes.set_last_error` are used to request and change the ctypes private
copy of the windows error code.
.. versionadded:: 2.6
The *use_last_error* and *use_errno* optional parameters were added.
.. data:: RTLD_GLOBAL
:noindex:
Flag to use as *mode* parameter. On platforms where this flag is not available,
it is defined as the integer zero.
.. data:: RTLD_LOCAL
:noindex:
Flag to use as *mode* parameter. On platforms where this is not available, it
is the same as *RTLD_GLOBAL*.
.. data:: DEFAULT_MODE
:noindex:
The default mode which is used to load shared libraries. On OSX 10.3, this is
*RTLD_GLOBAL*, otherwise it is the same as *RTLD_LOCAL*.
Instances of these classes have no public methods. Functions exported by the
shared library can be accessed as attributes or by index. Please note that
accessing the function through an attribute caches the result and therefore
accessing it repeatedly returns the same object each time. On the other hand,
accessing it through an index returns a new object each time:
>>> libc.time == libc.time
True
>>> libc['time'] == libc['time']
False
The following public attributes are available, their name starts with an
underscore to not clash with exported function names:
.. attribute:: PyDLL._handle
The system handle used to access the library.
.. attribute:: PyDLL._name
The name of the library passed in the constructor.
Shared libraries can also be loaded by using one of the prefabricated objects,
which are instances of the :class:`LibraryLoader` class, either by calling the
:meth:`LoadLibrary` method, or by retrieving the library as attribute of the
loader instance.
.. class:: LibraryLoader(dlltype)
Class which loads shared libraries. *dlltype* should be one of the
:class:`CDLL`, :class:`PyDLL`, :class:`WinDLL`, or :class:`OleDLL` types.
:meth:`__getattr__` has special behavior: It allows loading a shared library by
accessing it as attribute of a library loader instance. The result is cached,
so repeated attribute accesses return the same library each time.
.. method:: LoadLibrary(name)
Load a shared library into the process and return it. This method always
returns a new instance of the library.
These prefabricated library loaders are available:
.. data:: cdll
:noindex:
Creates :class:`CDLL` instances.
.. data:: windll
:noindex:
Windows only: Creates :class:`WinDLL` instances.
.. data:: oledll
:noindex:
Windows only: Creates :class:`OleDLL` instances.
.. data:: pydll
:noindex:
Creates :class:`PyDLL` instances.
For accessing the C Python api directly, a ready-to-use Python shared library
object is available:
.. data:: pythonapi
:noindex:
An instance of :class:`PyDLL` that exposes Python C API functions as
attributes. Note that all these functions are assumed to return C
:c:type:`int`, which is of course not always the truth, so you have to assign
the correct :attr:`restype` attribute to use these functions.
.. _ctypes-foreign-functions:
Foreign functions
^^^^^^^^^^^^^^^^^
As explained in the previous section, foreign functions can be accessed as
attributes of loaded shared libraries. The function objects created in this way
by default accept any number of arguments, accept any ctypes data instances as
arguments, and return the default result type specified by the library loader.
They are instances of a private class:
.. class:: _FuncPtr
Base class for C callable foreign functions.
Instances of foreign functions are also C compatible data types; they
represent C function pointers.
This behavior can be customized by assigning to special attributes of the
foreign function object.
.. attribute:: restype
Assign a ctypes type to specify the result type of the foreign function.
Use ``None`` for :c:type:`void`, a function not returning anything.
It is possible to assign a callable Python object that is not a ctypes
type, in this case the function is assumed to return a C :c:type:`int`, and
the callable will be called with this integer, allowing further
processing or error checking. Using this is deprecated, for more flexible
post processing or error checking use a ctypes data type as
:attr:`restype` and assign a callable to the :attr:`errcheck` attribute.
.. attribute:: argtypes
Assign a tuple of ctypes types to specify the argument types that the
function accepts. Functions using the ``stdcall`` calling convention can
only be called with the same number of arguments as the length of this
tuple; functions using the C calling convention accept additional,
unspecified arguments as well.
When a foreign function is called, each actual argument is passed to the
:meth:`from_param` class method of the items in the :attr:`argtypes`
tuple, this method allows adapting the actual argument to an object that
the foreign function accepts. For example, a :class:`c_char_p` item in
the :attr:`argtypes` tuple will convert a unicode string passed as
argument into a byte string using ctypes conversion rules.
New: It is now possible to put items in argtypes which are not ctypes
types, but each item must have a :meth:`from_param` method which returns a
value usable as argument (integer, string, ctypes instance). This allows
defining adapters that can adapt custom objects as function parameters.
.. attribute:: errcheck
Assign a Python function or another callable to this attribute. The
callable will be called with three or more arguments:
.. function:: callable(result, func, arguments)
:noindex:
*result* is what the foreign function returns, as specified by the
:attr:`restype` attribute.
*func* is the foreign function object itself, this allows reusing the
same callable object to check or post process the results of several
functions.
*arguments* is a tuple containing the parameters originally passed to
the function call, this allows specializing the behavior on the
arguments used.
The object that this function returns will be returned from the
foreign function call, but it can also check the result value
and raise an exception if the foreign function call failed.
.. exception:: ArgumentError()
This exception is raised when a foreign function call cannot convert one of the
passed arguments.
.. _ctypes-function-prototypes:
Function prototypes
^^^^^^^^^^^^^^^^^^^
Foreign functions can also be created by instantiating function prototypes.
Function prototypes are similar to function prototypes in C; they describe a
function (return type, argument types, calling convention) without defining an
implementation. The factory functions must be called with the desired result
type and the argument types of the function.
.. function:: CFUNCTYPE(restype, *argtypes, use_errno=False, use_last_error=False)
The returned function prototype creates functions that use the standard C
calling convention. The function will release the GIL during the call. If
*use_errno* is set to true, the ctypes private copy of the system
:data:`errno` variable is exchanged with the real :data:`errno` value before
and after the call; *use_last_error* does the same for the Windows error
code.
.. versionchanged:: 2.6
The optional *use_errno* and *use_last_error* parameters were added.
.. function:: WINFUNCTYPE(restype, *argtypes, use_errno=False, use_last_error=False)
Windows only: The returned function prototype creates functions that use the
``stdcall`` calling convention, except on Windows CE where
:func:`WINFUNCTYPE` is the same as :func:`CFUNCTYPE`. The function will
release the GIL during the call. *use_errno* and *use_last_error* have the
same meaning as above.
.. function:: PYFUNCTYPE(restype, *argtypes)
The returned function prototype creates functions that use the Python calling
convention. The function will *not* release the GIL during the call.
Function prototypes created by these factory functions can be instantiated in
different ways, depending on the type and number of the parameters in the call:
.. function:: prototype(address)
:noindex:
:module:
Returns a foreign function at the specified address which must be an integer.
.. function:: prototype(callable)
:noindex:
:module:
Create a C callable function (a callback function) from a Python *callable*.
.. function:: prototype(func_spec[, paramflags])
:noindex:
:module:
Returns a foreign function exported by a shared library. *func_spec* must be a
2-tuple ``(name_or_ordinal, library)``. The first item is the name of the
exported function as string, or the ordinal of the exported function as small
integer. The second item is the shared library instance.
.. function:: prototype(vtbl_index, name[, paramflags[, iid]])
:noindex:
:module:
Returns a foreign function that will call a COM method. *vtbl_index* is the
index into the virtual function table, a small non-negative integer. *name* is
name of the COM method. *iid* is an optional pointer to the interface identifier
which is used in extended error reporting.
COM methods use a special calling convention: They require a pointer to the COM
interface as first argument, in addition to those parameters that are specified
in the :attr:`argtypes` tuple.
The optional *paramflags* parameter creates foreign function wrappers with much
more functionality than the features described above.
*paramflags* must be a tuple of the same length as :attr:`argtypes`.
Each item in this tuple contains further information about a parameter, it must
be a tuple containing one, two, or three items.
The first item is an integer containing a combination of direction
flags for the parameter:
1
Specifies an input parameter to the function.
2
Output parameter. The foreign function fills in a value.
4
Input parameter which defaults to the integer zero.
The optional second item is the parameter name as string. If this is specified,
the foreign function can be called with named parameters.
The optional third item is the default value for this parameter.
This example demonstrates how to wrap the Windows ``MessageBoxA`` function so
that it supports default parameters and named arguments. The C declaration from
the windows header file is this::
WINUSERAPI int WINAPI
MessageBoxA(
HWND hWnd,
LPCSTR lpText,
LPCSTR lpCaption,
UINT uType);
Here is the wrapping with :mod:`ctypes`::
>>> from ctypes import c_int, WINFUNCTYPE, windll
>>> from ctypes.wintypes import HWND, LPCSTR, UINT
>>> prototype = WINFUNCTYPE(c_int, HWND, LPCSTR, LPCSTR, UINT)
>>> paramflags = (1, "hwnd", 0), (1, "text", "Hi"), (1, "caption", None), (1, "flags", 0)
>>> MessageBox = prototype(("MessageBoxA", windll.user32), paramflags)
>>>
The MessageBox foreign function can now be called in these ways::
>>> MessageBox()
>>> MessageBox(text="Spam, spam, spam")
>>> MessageBox(flags=2, text="foo bar")
>>>
A second example demonstrates output parameters. The win32 ``GetWindowRect``
function retrieves the dimensions of a specified window by copying them into
``RECT`` structure that the caller has to supply. Here is the C declaration::
WINUSERAPI BOOL WINAPI
GetWindowRect(
HWND hWnd,
LPRECT lpRect);
Here is the wrapping with :mod:`ctypes`::
>>> from ctypes import POINTER, WINFUNCTYPE, windll, WinError
>>> from ctypes.wintypes import BOOL, HWND, RECT
>>> prototype = WINFUNCTYPE(BOOL, HWND, POINTER(RECT))
>>> paramflags = (1, "hwnd"), (2, "lprect")
>>> GetWindowRect = prototype(("GetWindowRect", windll.user32), paramflags)
>>>
Functions with output parameters will automatically return the output parameter
value if there is a single one, or a tuple containing the output parameter
values when there are more than one, so the GetWindowRect function now returns a
RECT instance, when called.
Output parameters can be combined with the :attr:`errcheck` protocol to do
further output processing and error checking. The win32 ``GetWindowRect`` api
function returns a ``BOOL`` to signal success or failure, so this function could
do the error checking, and raises an exception when the api call failed::
>>> def errcheck(result, func, args):
... if not result:
... raise WinError()
... return args
...
>>> GetWindowRect.errcheck = errcheck
>>>
If the :attr:`errcheck` function returns the argument tuple it receives
unchanged, :mod:`ctypes` continues the normal processing it does on the output
parameters. If you want to return a tuple of window coordinates instead of a
``RECT`` instance, you can retrieve the fields in the function and return them
instead, the normal processing will no longer take place::
>>> def errcheck(result, func, args):
... if not result:
... raise WinError()
... rc = args[1]
... return rc.left, rc.top, rc.bottom, rc.right
...
>>> GetWindowRect.errcheck = errcheck
>>>
.. _ctypes-utility-functions:
Utility functions
^^^^^^^^^^^^^^^^^
.. function:: addressof(obj)
Returns the address of the memory buffer as integer. *obj* must be an
instance of a ctypes type.
.. function:: alignment(obj_or_type)
Returns the alignment requirements of a ctypes type. *obj_or_type* must be a
ctypes type or instance.
.. function:: byref(obj[, offset])
Returns a light-weight pointer to *obj*, which must be an instance of a
ctypes type. *offset* defaults to zero, and must be an integer that will be
added to the internal pointer value.
``byref(obj, offset)`` corresponds to this C code::
(((char *)&obj) + offset)
The returned object can only be used as a foreign function call
parameter. It behaves similar to ``pointer(obj)``, but the
construction is a lot faster.
.. versionadded:: 2.6
The *offset* optional argument was added.
.. function:: cast(obj, type)
This function is similar to the cast operator in C. It returns a new
instance of *type* which points to the same memory block as *obj*. *type*
must be a pointer type, and *obj* must be an object that can be interpreted
as a pointer.
.. function:: create_string_buffer(init_or_size[, size])
This function creates a mutable character buffer. The returned object is a
ctypes array of :class:`c_char`.
*init_or_size* must be an integer which specifies the size of the array, or a
string which will be used to initialize the array items.
If a string is specified as first argument, the buffer is made one item larger
than the length of the string so that the last element in the array is a NUL
termination character. An integer can be passed as second argument which allows
specifying the size of the array if the length of the string should not be used.
If the first parameter is a unicode string, it is converted into an 8-bit string
according to ctypes conversion rules.
.. function:: create_unicode_buffer(init_or_size[, size])
This function creates a mutable unicode character buffer. The returned object is
a ctypes array of :class:`c_wchar`.
*init_or_size* must be an integer which specifies the size of the array, or a
unicode string which will be used to initialize the array items.
If a unicode string is specified as first argument, the buffer is made one item
larger than the length of the string so that the last element in the array is a
NUL termination character. An integer can be passed as second argument which
allows specifying the size of the array if the length of the string should not
be used.
If the first parameter is an 8-bit string, it is converted into a unicode string
according to ctypes conversion rules.
.. function:: DllCanUnloadNow()
Windows only: This function is a hook which allows implementing in-process
COM servers with ctypes. It is called from the DllCanUnloadNow function that
the _ctypes extension dll exports.
.. function:: DllGetClassObject()
Windows only: This function is a hook which allows implementing in-process
COM servers with ctypes. It is called from the DllGetClassObject function
that the ``_ctypes`` extension dll exports.
.. function:: find_library(name)
:module: ctypes.util
Try to find a library and return a pathname. *name* is the library name
without any prefix like ``lib``, suffix like ``.so``, ``.dylib`` or version
number (this is the form used for the posix linker option :option:`!-l`). If
no library can be found, returns ``None``.
The exact functionality is system dependent.
.. versionchanged:: 2.6
Windows only: ``find_library("m")`` or ``find_library("c")`` return the
result of a call to ``find_msvcrt()``.
.. function:: find_msvcrt()
:module: ctypes.util
Windows only: return the filename of the VC runtime library used by Python,
and by the extension modules. If the name of the library cannot be
determined, ``None`` is returned.
If you need to free memory, for example, allocated by an extension module
with a call to the ``free(void *)``, it is important that you use the
function in the same library that allocated the memory.
.. versionadded:: 2.6
.. function:: FormatError([code])
Windows only: Returns a textual description of the error code *code*. If no
error code is specified, the last error code is used by calling the Windows
api function GetLastError.
.. function:: GetLastError()
Windows only: Returns the last error code set by Windows in the calling thread.
This function calls the Windows `GetLastError()` function directly,
it does not return the ctypes-private copy of the error code.
.. function:: get_errno()
Returns the current value of the ctypes-private copy of the system
:data:`errno` variable in the calling thread.
.. versionadded:: 2.6
.. function:: get_last_error()
Windows only: returns the current value of the ctypes-private copy of the system
:data:`LastError` variable in the calling thread.
.. versionadded:: 2.6
.. function:: memmove(dst, src, count)
Same as the standard C memmove library function: copies *count* bytes from
*src* to *dst*. *dst* and *src* must be integers or ctypes instances that can
be converted to pointers.
.. function:: memset(dst, c, count)
Same as the standard C memset library function: fills the memory block at
address *dst* with *count* bytes of value *c*. *dst* must be an integer
specifying an address, or a ctypes instance.
.. function:: POINTER(type)
This factory function creates and returns a new ctypes pointer type. Pointer
types are cached and reused internally, so calling this function repeatedly is
cheap. *type* must be a ctypes type.
.. function:: pointer(obj)
This function creates a new pointer instance, pointing to *obj*. The returned
object is of the type ``POINTER(type(obj))``.
Note: If you just want to pass a pointer to an object to a foreign function
call, you should use ``byref(obj)`` which is much faster.
.. function:: resize(obj, size)
This function resizes the internal memory buffer of *obj*, which must be an
instance of a ctypes type. It is not possible to make the buffer smaller
than the native size of the objects type, as given by ``sizeof(type(obj))``,
but it is possible to enlarge the buffer.
.. function:: set_conversion_mode(encoding, errors)
This function sets the rules that ctypes objects use when converting between
8-bit strings and unicode strings. *encoding* must be a string specifying an
encoding, like ``'utf-8'`` or ``'mbcs'``, *errors* must be a string
specifying the error handling on encoding/decoding errors. Examples of
possible values are ``"strict"``, ``"replace"``, or ``"ignore"``.
:func:`set_conversion_mode` returns a 2-tuple containing the previous
conversion rules. On windows, the initial conversion rules are ``('mbcs',
'ignore')``, on other systems ``('ascii', 'strict')``.
.. function:: set_errno(value)
Set the current value of the ctypes-private copy of the system :data:`errno`
variable in the calling thread to *value* and return the previous value.
.. versionadded:: 2.6
.. function:: set_last_error(value)
Windows only: set the current value of the ctypes-private copy of the system
:data:`LastError` variable in the calling thread to *value* and return the
previous value.
.. versionadded:: 2.6
.. function:: sizeof(obj_or_type)
Returns the size in bytes of a ctypes type or instance memory buffer.
Does the same as the C ``sizeof`` operator.
.. function:: string_at(address[, size])
This function returns the string starting at memory address *address*. If size
is specified, it is used as size, otherwise the string is assumed to be
zero-terminated.
.. function:: WinError(code=None, descr=None)
Windows only: this function is probably the worst-named thing in ctypes. It
creates an instance of WindowsError. If *code* is not specified,
``GetLastError`` is called to determine the error code. If ``descr`` is not
specified, :func:`FormatError` is called to get a textual description of the
error.
.. function:: wstring_at(address[, size])
This function returns the wide character string starting at memory address
*address* as unicode string. If *size* is specified, it is used as the
number of characters of the string, otherwise the string is assumed to be
zero-terminated.
.. _ctypes-data-types:
Data types
^^^^^^^^^^
.. class:: _CData
This non-public class is the common base class of all ctypes data types.
Among other things, all ctypes type instances contain a memory block that
hold C compatible data; the address of the memory block is returned by the
:func:`addressof` helper function. Another instance variable is exposed as
:attr:`_objects`; this contains other Python objects that need to be kept
alive in case the memory block contains pointers.
Common methods of ctypes data types, these are all class methods (to be
exact, they are methods of the :term:`metaclass`):
.. method:: _CData.from_buffer(source[, offset])
This method returns a ctypes instance that shares the buffer of the
*source* object. The *source* object must support the writeable buffer
interface. The optional *offset* parameter specifies an offset into the
source buffer in bytes; the default is zero. If the source buffer is not
large enough a :exc:`ValueError` is raised.
.. versionadded:: 2.6
.. method:: _CData.from_buffer_copy(source[, offset])
This method creates a ctypes instance, copying the buffer from the
*source* object buffer which must be readable. The optional *offset*
parameter specifies an offset into the source buffer in bytes; the default
is zero. If the source buffer is not large enough a :exc:`ValueError` is
raised.
.. versionadded:: 2.6
.. method:: from_address(address)
This method returns a ctypes type instance using the memory specified by
*address* which must be an integer.
.. method:: from_param(obj)
This method adapts *obj* to a ctypes type. It is called with the actual
object used in a foreign function call when the type is present in the
foreign function's :attr:`argtypes` tuple; it must return an object that
can be used as a function call parameter.
All ctypes data types have a default implementation of this classmethod
that normally returns *obj* if that is an instance of the type. Some
types accept other objects as well.
.. method:: in_dll(library, name)
This method returns a ctypes type instance exported by a shared
library. *name* is the name of the symbol that exports the data, *library*
is the loaded shared library.
Common instance variables of ctypes data types:
.. attribute:: _b_base_
Sometimes ctypes data instances do not own the memory block they contain,
instead they share part of the memory block of a base object. The
:attr:`_b_base_` read-only member is the root ctypes object that owns the
memory block.
.. attribute:: _b_needsfree_
This read-only variable is true when the ctypes data instance has
allocated the memory block itself, false otherwise.
.. attribute:: _objects
This member is either ``None`` or a dictionary containing Python objects
that need to be kept alive so that the memory block contents is kept
valid. This object is only exposed for debugging; never modify the
contents of this dictionary.
.. _ctypes-fundamental-data-types-2:
Fundamental data types
^^^^^^^^^^^^^^^^^^^^^^
.. class:: _SimpleCData
This non-public class is the base class of all fundamental ctypes data
types. It is mentioned here because it contains the common attributes of the
fundamental ctypes data types. :class:`_SimpleCData` is a subclass of
:class:`_CData`, so it inherits their methods and attributes.
.. versionchanged:: 2.6
ctypes data types that are not and do not contain pointers can now be
pickled.
Instances have a single attribute:
.. attribute:: value
This attribute contains the actual value of the instance. For integer and
pointer types, it is an integer, for character types, it is a single
character string, for character pointer types it is a Python string or
unicode string.
When the ``value`` attribute is retrieved from a ctypes instance, usually
a new object is returned each time. :mod:`ctypes` does *not* implement
original object return, always a new object is constructed. The same is
true for all other ctypes object instances.
Fundamental data types, when returned as foreign function call results, or, for
example, by retrieving structure field members or array items, are transparently
converted to native Python types. In other words, if a foreign function has a
:attr:`restype` of :class:`c_char_p`, you will always receive a Python string,
*not* a :class:`c_char_p` instance.
Subclasses of fundamental data types do *not* inherit this behavior. So, if a
foreign functions :attr:`restype` is a subclass of :class:`c_void_p`, you will
receive an instance of this subclass from the function call. Of course, you can
get the value of the pointer by accessing the ``value`` attribute.
These are the fundamental ctypes data types:
.. class:: c_byte
Represents the C :c:type:`signed char` datatype, and interprets the value as
small integer. The constructor accepts an optional integer initializer; no
overflow checking is done.
.. class:: c_char
Represents the C :c:type:`char` datatype, and interprets the value as a single
character. The constructor accepts an optional string initializer, the
length of the string must be exactly one character.
.. class:: c_char_p
Represents the C :c:type:`char *` datatype when it points to a zero-terminated
string. For a general character pointer that may also point to binary data,
``POINTER(c_char)`` must be used. The constructor accepts an integer
address, or a string.
.. class:: c_double
Represents the C :c:type:`double` datatype. The constructor accepts an
optional float initializer.
.. class:: c_longdouble
Represents the C :c:type:`long double` datatype. The constructor accepts an
optional float initializer. On platforms where ``sizeof(long double) ==
sizeof(double)`` it is an alias to :class:`c_double`.
.. versionadded:: 2.6
.. class:: c_float
Represents the C :c:type:`float` datatype. The constructor accepts an
optional float initializer.
.. class:: c_int
Represents the C :c:type:`signed int` datatype. The constructor accepts an
optional integer initializer; no overflow checking is done. On platforms
where ``sizeof(int) == sizeof(long)`` it is an alias to :class:`c_long`.
.. class:: c_int8
Represents the C 8-bit :c:type:`signed int` datatype. Usually an alias for
:class:`c_byte`.
.. class:: c_int16
Represents the C 16-bit :c:type:`signed int` datatype. Usually an alias for
:class:`c_short`.
.. class:: c_int32
Represents the C 32-bit :c:type:`signed int` datatype. Usually an alias for
:class:`c_int`.
.. class:: c_int64
Represents the C 64-bit :c:type:`signed int` datatype. Usually an alias for
:class:`c_longlong`.
.. class:: c_long
Represents the C :c:type:`signed long` datatype. The constructor accepts an
optional integer initializer; no overflow checking is done.
.. class:: c_longlong
Represents the C :c:type:`signed long long` datatype. The constructor accepts
an optional integer initializer; no overflow checking is done.
.. class:: c_short
Represents the C :c:type:`signed short` datatype. The constructor accepts an
optional integer initializer; no overflow checking is done.
.. class:: c_size_t
Represents the C :c:type:`size_t` datatype.
.. class:: c_ssize_t
Represents the C :c:type:`ssize_t` datatype.
.. versionadded:: 2.7
.. class:: c_ubyte
Represents the C :c:type:`unsigned char` datatype, it interprets the value as
small integer. The constructor accepts an optional integer initializer; no
overflow checking is done.
.. class:: c_uint
Represents the C :c:type:`unsigned int` datatype. The constructor accepts an
optional integer initializer; no overflow checking is done. On platforms
where ``sizeof(int) == sizeof(long)`` it is an alias for :class:`c_ulong`.
.. class:: c_uint8
Represents the C 8-bit :c:type:`unsigned int` datatype. Usually an alias for
:class:`c_ubyte`.
.. class:: c_uint16
Represents the C 16-bit :c:type:`unsigned int` datatype. Usually an alias for
:class:`c_ushort`.
.. class:: c_uint32
Represents the C 32-bit :c:type:`unsigned int` datatype. Usually an alias for
:class:`c_uint`.
.. class:: c_uint64
Represents the C 64-bit :c:type:`unsigned int` datatype. Usually an alias for
:class:`c_ulonglong`.
.. class:: c_ulong
Represents the C :c:type:`unsigned long` datatype. The constructor accepts an
optional integer initializer; no overflow checking is done.
.. class:: c_ulonglong
Represents the C :c:type:`unsigned long long` datatype. The constructor
accepts an optional integer initializer; no overflow checking is done.
.. class:: c_ushort
Represents the C :c:type:`unsigned short` datatype. The constructor accepts
an optional integer initializer; no overflow checking is done.
.. class:: c_void_p
Represents the C :c:type:`void *` type. The value is represented as integer.
The constructor accepts an optional integer initializer.
.. class:: c_wchar
Represents the C :c:type:`wchar_t` datatype, and interprets the value as a
single character unicode string. The constructor accepts an optional string
initializer, the length of the string must be exactly one character.
.. class:: c_wchar_p
Represents the C :c:type:`wchar_t *` datatype, which must be a pointer to a
zero-terminated wide character string. The constructor accepts an integer
address, or a string.
.. class:: c_bool
Represent the C :c:type:`bool` datatype (more accurately, :c:type:`_Bool` from
C99). Its value can be ``True`` or ``False``, and the constructor accepts any object
that has a truth value.
.. versionadded:: 2.6
.. class:: HRESULT
Windows only: Represents a :c:type:`HRESULT` value, which contains success or
error information for a function or method call.
.. class:: py_object
Represents the C :c:type:`PyObject *` datatype. Calling this without an
argument creates a ``NULL`` :c:type:`PyObject *` pointer.
The :mod:`ctypes.wintypes` module provides quite some other Windows specific
data types, for example :c:type:`HWND`, :c:type:`WPARAM`, or :c:type:`DWORD`. Some
useful structures like :c:type:`MSG` or :c:type:`RECT` are also defined.
.. _ctypes-structured-data-types:
Structured data types
^^^^^^^^^^^^^^^^^^^^^
.. class:: Union(*args, **kw)
Abstract base class for unions in native byte order.
.. class:: BigEndianStructure(*args, **kw)
Abstract base class for structures in *big endian* byte order.
.. class:: LittleEndianStructure(*args, **kw)
Abstract base class for structures in *little endian* byte order.
Structures with non-native byte order cannot contain pointer type fields, or any
other data types containing pointer type fields.
.. class:: Structure(*args, **kw)
Abstract base class for structures in *native* byte order.
Concrete structure and union types must be created by subclassing one of these
types, and at least define a :attr:`_fields_` class variable. :mod:`ctypes` will
create :term:`descriptor`\s which allow reading and writing the fields by direct
attribute accesses. These are the
.. attribute:: _fields_
A sequence defining the structure fields. The items must be 2-tuples or
3-tuples. The first item is the name of the field, the second item
specifies the type of the field; it can be any ctypes data type.
For integer type fields like :class:`c_int`, a third optional item can be
given. It must be a small positive integer defining the bit width of the
field.
Field names must be unique within one structure or union. This is not
checked, only one field can be accessed when names are repeated.
It is possible to define the :attr:`_fields_` class variable *after* the
class statement that defines the Structure subclass, this allows creating
data types that directly or indirectly reference themselves::
class List(Structure):
pass
List._fields_ = [("pnext", POINTER(List)),
...
]
The :attr:`_fields_` class variable must, however, be defined before the
type is first used (an instance is created, ``sizeof()`` is called on it,
and so on). Later assignments to the :attr:`_fields_` class variable will
raise an AttributeError.
It is possible to defined sub-subclasses of structure types, they inherit
the fields of the base class plus the :attr:`_fields_` defined in the
sub-subclass, if any.
.. attribute:: _pack_
An optional small integer that allows overriding the alignment of
structure fields in the instance. :attr:`_pack_` must already be defined
when :attr:`_fields_` is assigned, otherwise it will have no effect.
.. attribute:: _anonymous_
An optional sequence that lists the names of unnamed (anonymous) fields.
:attr:`_anonymous_` must be already defined when :attr:`_fields_` is
assigned, otherwise it will have no effect.
The fields listed in this variable must be structure or union type fields.
:mod:`ctypes` will create descriptors in the structure type that allow
accessing the nested fields directly, without the need to create the
structure or union field.
Here is an example type (Windows)::
class _U(Union):
_fields_ = [("lptdesc", POINTER(TYPEDESC)),
("lpadesc", POINTER(ARRAYDESC)),
("hreftype", HREFTYPE)]
class TYPEDESC(Structure):
_anonymous_ = ("u",)
_fields_ = [("u", _U),
("vt", VARTYPE)]
The ``TYPEDESC`` structure describes a COM data type, the ``vt`` field
specifies which one of the union fields is valid. Since the ``u`` field
is defined as anonymous field, it is now possible to access the members
directly off the TYPEDESC instance. ``td.lptdesc`` and ``td.u.lptdesc``
are equivalent, but the former is faster since it does not need to create
a temporary union instance::
td = TYPEDESC()
td.vt = VT_PTR
td.lptdesc = POINTER(some_type)
td.u.lptdesc = POINTER(some_type)
It is possible to defined sub-subclasses of structures, they inherit the
fields of the base class. If the subclass definition has a separate
:attr:`_fields_` variable, the fields specified in this are appended to the
fields of the base class.
Structure and union constructors accept both positional and keyword
arguments. Positional arguments are used to initialize member fields in the
same order as they are appear in :attr:`_fields_`. Keyword arguments in the
constructor are interpreted as attribute assignments, so they will initialize
:attr:`_fields_` with the same name, or create new attributes for names not
present in :attr:`_fields_`.
.. _ctypes-arrays-pointers:
Arrays and pointers
^^^^^^^^^^^^^^^^^^^
.. class:: Array(\*args)
Abstract base class for arrays.
The recommended way to create concrete array types is by multiplying any
:mod:`ctypes` data type with a positive integer. Alternatively, you can subclass
this type and define :attr:`_length_` and :attr:`_type_` class variables.
Array elements can be read and written using standard
subscript and slice accesses; for slice reads, the resulting object is
*not* itself an :class:`Array`.
.. attribute:: _length_
A positive integer specifying the number of elements in the array.
Out-of-range subscripts result in an :exc:`IndexError`. Will be
returned by :func:`len`.
.. attribute:: _type_
Specifies the type of each element in the array.
Array subclass constructors accept positional arguments, used to
initialize the elements in order.
.. class:: _Pointer
Private, abstract base class for pointers.
Concrete pointer types are created by calling :func:`POINTER` with the
type that will be pointed to; this is done automatically by
:func:`pointer`.
If a pointer points to an array, its elements can be read and
written using standard subscript and slice accesses. Pointer objects
have no size, so :func:`len` will raise :exc:`TypeError`. Negative
subscripts will read from the memory *before* the pointer (as in C), and
out-of-range subscripts will probably crash with an access violation (if
you're lucky).
.. attribute:: _type_
Specifies the type pointed to.
.. attribute:: contents
Returns the object to which to pointer points. Assigning to this
attribute changes the pointer to point to the assigned object.
PK %�\��zV# V# * html/_sources/library/curses.ascii.rst.txtnu �[���
:mod:`curses.ascii` --- Utilities for ASCII characters
======================================================
.. module:: curses.ascii
:synopsis: Constants and set-membership functions for ASCII characters.
.. moduleauthor:: Eric S. Raymond <esr@thyrsus.com>
.. sectionauthor:: Eric S. Raymond <esr@thyrsus.com>
.. versionadded:: 1.6
The :mod:`curses.ascii` module supplies name constants for ASCII characters and
functions to test membership in various ASCII character classes. The constants
supplied are names for control characters as follows:
+--------------+----------------------------------------------+
| Name | Meaning |
+==============+==============================================+
| :const:`NUL` | |
+--------------+----------------------------------------------+
| :const:`SOH` | Start of heading, console interrupt |
+--------------+----------------------------------------------+
| :const:`STX` | Start of text |
+--------------+----------------------------------------------+
| :const:`ETX` | End of text |
+--------------+----------------------------------------------+
| :const:`EOT` | End of transmission |
+--------------+----------------------------------------------+
| :const:`ENQ` | Enquiry, goes with :const:`ACK` flow control |
+--------------+----------------------------------------------+
| :const:`ACK` | Acknowledgement |
+--------------+----------------------------------------------+
| :const:`BEL` | Bell |
+--------------+----------------------------------------------+
| :const:`BS` | Backspace |
+--------------+----------------------------------------------+
| :const:`TAB` | Tab |
+--------------+----------------------------------------------+
| :const:`HT` | Alias for :const:`TAB`: "Horizontal tab" |
+--------------+----------------------------------------------+
| :const:`LF` | Line feed |
+--------------+----------------------------------------------+
| :const:`NL` | Alias for :const:`LF`: "New line" |
+--------------+----------------------------------------------+
| :const:`VT` | Vertical tab |
+--------------+----------------------------------------------+
| :const:`FF` | Form feed |
+--------------+----------------------------------------------+
| :const:`CR` | Carriage return |
+--------------+----------------------------------------------+
| :const:`SO` | Shift-out, begin alternate character set |
+--------------+----------------------------------------------+
| :const:`SI` | Shift-in, resume default character set |
+--------------+----------------------------------------------+
| :const:`DLE` | Data-link escape |
+--------------+----------------------------------------------+
| :const:`DC1` | XON, for flow control |
+--------------+----------------------------------------------+
| :const:`DC2` | Device control 2, block-mode flow control |
+--------------+----------------------------------------------+
| :const:`DC3` | XOFF, for flow control |
+--------------+----------------------------------------------+
| :const:`DC4` | Device control 4 |
+--------------+----------------------------------------------+
| :const:`NAK` | Negative acknowledgement |
+--------------+----------------------------------------------+
| :const:`SYN` | Synchronous idle |
+--------------+----------------------------------------------+
| :const:`ETB` | End transmission block |
+--------------+----------------------------------------------+
| :const:`CAN` | Cancel |
+--------------+----------------------------------------------+
| :const:`EM` | End of medium |
+--------------+----------------------------------------------+
| :const:`SUB` | Substitute |
+--------------+----------------------------------------------+
| :const:`ESC` | Escape |
+--------------+----------------------------------------------+
| :const:`FS` | File separator |
+--------------+----------------------------------------------+
| :const:`GS` | Group separator |
+--------------+----------------------------------------------+
| :const:`RS` | Record separator, block-mode terminator |
+--------------+----------------------------------------------+
| :const:`US` | Unit separator |
+--------------+----------------------------------------------+
| :const:`SP` | Space |
+--------------+----------------------------------------------+
| :const:`DEL` | Delete |
+--------------+----------------------------------------------+
Note that many of these have little practical significance in modern usage. The
mnemonics derive from teleprinter conventions that predate digital computers.
The module supplies the following functions, patterned on those in the standard
C library:
.. function:: isalnum(c)
Checks for an ASCII alphanumeric character; it is equivalent to ``isalpha(c) or
isdigit(c)``.
.. function:: isalpha(c)
Checks for an ASCII alphabetic character; it is equivalent to ``isupper(c) or
islower(c)``.
.. function:: isascii(c)
Checks for a character value that fits in the 7-bit ASCII set.
.. function:: isblank(c)
Checks for an ASCII whitespace character; space or horizontal tab.
.. function:: iscntrl(c)
Checks for an ASCII control character (in the range 0x00 to 0x1f or 0x7f).
.. function:: isdigit(c)
Checks for an ASCII decimal digit, ``'0'`` through ``'9'``. This is equivalent
to ``c in string.digits``.
.. function:: isgraph(c)
Checks for ASCII any printable character except space.
.. function:: islower(c)
Checks for an ASCII lower-case character.
.. function:: isprint(c)
Checks for any ASCII printable character including space.
.. function:: ispunct(c)
Checks for any printable ASCII character which is not a space or an alphanumeric
character.
.. function:: isspace(c)
Checks for ASCII white-space characters; space, line feed, carriage return, form
feed, horizontal tab, vertical tab.
.. function:: isupper(c)
Checks for an ASCII uppercase letter.
.. function:: isxdigit(c)
Checks for an ASCII hexadecimal digit. This is equivalent to ``c in
string.hexdigits``.
.. function:: isctrl(c)
Checks for an ASCII control character (ordinal values 0 to 31).
.. function:: ismeta(c)
Checks for a non-ASCII character (ordinal values 0x80 and above).
These functions accept either integers or strings; when the argument is a
string, it is first converted using the built-in function :func:`ord`.
Note that all these functions check ordinal bit values derived from the first
character of the string you pass in; they do not actually know anything about
the host machine's character encoding. For functions that know about the
character encoding (and handle internationalization properly) see the
:mod:`string` module.
The following two functions take either a single-character string or integer
byte value; they return a value of the same type.
.. function:: ascii(c)
Return the ASCII value corresponding to the low 7 bits of *c*.
.. function:: ctrl(c)
Return the control character corresponding to the given character (the character
bit value is bitwise-anded with 0x1f).
.. function:: alt(c)
Return the 8-bit character corresponding to the given ASCII character (the
character bit value is bitwise-ored with 0x80).
The following function takes either a single-character string or integer value;
it returns a string.
.. function:: unctrl(c)
Return a string representation of the ASCII character *c*. If *c* is printable,
this string is the character itself. If the character is a control character
(0x00--0x1f) the string consists of a caret (``'^'``) followed by the
corresponding uppercase letter. If the character is an ASCII delete (0x7f) the
string is ``'^?'``. If the character has its meta bit (0x80) set, the meta bit
is stripped, the preceding rules applied, and ``'!'`` prepended to the result.
.. data:: controlnames
A 33-element string array that contains the ASCII mnemonics for the thirty-two
ASCII control characters from 0 (NUL) to 0x1f (US), in order, plus the mnemonic
``SP`` for the space character.
PK %�\��XR�
�
* html/_sources/library/curses.panel.rst.txtnu �[��� :mod:`curses.panel` --- A panel stack extension for curses
==========================================================
.. module:: curses.panel
:synopsis: A panel stack extension that adds depth to curses windows.
.. sectionauthor:: A.M. Kuchling <amk@amk.ca>
Panels are windows with the added feature of depth, so they can be stacked on
top of each other, and only the visible portions of each window will be
displayed. Panels can be added, moved up or down in the stack, and removed.
.. _cursespanel-functions:
Functions
---------
The module :mod:`curses.panel` defines the following functions:
.. function:: bottom_panel()
Returns the bottom panel in the panel stack.
.. function:: new_panel(win)
Returns a panel object, associating it with the given window *win*. Be aware
that you need to keep the returned panel object referenced explicitly. If you
don't, the panel object is garbage collected and removed from the panel stack.
.. function:: top_panel()
Returns the top panel in the panel stack.
.. function:: update_panels()
Updates the virtual screen after changes in the panel stack. This does not call
:func:`curses.doupdate`, so you'll have to do this yourself.
.. _curses-panel-objects:
Panel Objects
-------------
Panel objects, as returned by :func:`new_panel` above, are windows with a
stacking order. There's always a window associated with a panel which determines
the content, while the panel methods are responsible for the window's depth in
the panel stack.
Panel objects have the following methods:
.. method:: Panel.above()
Returns the panel above the current panel.
.. method:: Panel.below()
Returns the panel below the current panel.
.. method:: Panel.bottom()
Push the panel to the bottom of the stack.
.. method:: Panel.hidden()
Returns true if the panel is hidden (not visible), false otherwise.
.. method:: Panel.hide()
Hide the panel. This does not delete the object, it just makes the window on
screen invisible.
.. method:: Panel.move(y, x)
Move the panel to the screen coordinates ``(y, x)``.
.. method:: Panel.replace(win)
Change the window associated with the panel to the window *win*.
.. method:: Panel.set_userptr(obj)
Set the panel's user pointer to *obj*. This is used to associate an arbitrary
piece of data with the panel, and can be any Python object.
.. method:: Panel.show()
Display the panel (which might have been hidden).
.. method:: Panel.top()
Push panel to the top of the stack.
.. method:: Panel.userptr()
Returns the user pointer for the panel. This might be any Python object.
.. method:: Panel.window()
Returns the window object associated with the panel.
PK %�\�00�}$ }$ $ html/_sources/library/curses.rst.txtnu �[��� :mod:`curses` --- Terminal handling for character-cell displays
===============================================================
.. module:: curses
:synopsis: An interface to the curses library, providing portable terminal
handling.
:platform: Unix
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
.. sectionauthor:: Eric Raymond <esr@thyrsus.com>
.. versionchanged:: 1.6
Added support for the ``ncurses`` library and converted to a package.
The :mod:`curses` module provides an interface to the curses library, the
de-facto standard for portable advanced terminal handling.
While curses is most widely used in the Unix environment, versions are available
for DOS, OS/2, and possibly other systems as well. This extension module is
designed to match the API of ncurses, an open-source curses library hosted on
Linux and the BSD variants of Unix.
.. note::
Since version 5.4, the ncurses library decides how to interpret non-ASCII data
using the ``nl_langinfo`` function. That means that you have to call
:func:`locale.setlocale` in the application and encode Unicode strings
using one of the system's available encodings. This example uses the
system's default encoding::
import locale
locale.setlocale(locale.LC_ALL, '')
code = locale.getpreferredencoding()
Then use *code* as the encoding for :meth:`str.encode` calls.
.. seealso::
Module :mod:`curses.ascii`
Utilities for working with ASCII characters, regardless of your locale settings.
Module :mod:`curses.panel`
A panel stack extension that adds depth to curses windows.
Module :mod:`curses.textpad`
Editable text widget for curses supporting :program:`Emacs`\ -like bindings.
:ref:`curses-howto`
Tutorial material on using curses with Python, by Andrew Kuchling and Eric
Raymond.
The :source:`Demo/curses/` directory in the Python source distribution contains
some example programs using the curses bindings provided by this module.
.. _curses-functions:
Functions
---------
The module :mod:`curses` defines the following exception:
.. exception:: error
Exception raised when a curses library function returns an error.
.. note::
Whenever *x* or *y* arguments to a function or a method are optional, they
default to the current cursor location. Whenever *attr* is optional, it defaults
to :const:`A_NORMAL`.
The module :mod:`curses` defines the following functions:
.. function:: baudrate()
Return the output speed of the terminal in bits per second. On software
terminal emulators it will have a fixed high value. Included for historical
reasons; in former times, it was used to write output loops for time delays and
occasionally to change interfaces depending on the line speed.
.. function:: beep()
Emit a short attention sound.
.. function:: can_change_color()
Return ``True`` or ``False``, depending on whether the programmer can change the colors
displayed by the terminal.
.. function:: cbreak()
Enter cbreak mode. In cbreak mode (sometimes called "rare" mode) normal tty
line buffering is turned off and characters are available to be read one by one.
However, unlike raw mode, special characters (interrupt, quit, suspend, and flow
control) retain their effects on the tty driver and calling program. Calling
first :func:`raw` then :func:`cbreak` leaves the terminal in cbreak mode.
.. function:: color_content(color_number)
Return the intensity of the red, green, and blue (RGB) components in the color
*color_number*, which must be between ``0`` and :const:`COLORS`. A 3-tuple is
returned, containing the R,G,B values for the given color, which will be between
``0`` (no component) and ``1000`` (maximum amount of component).
.. function:: color_pair(color_number)
Return the attribute value for displaying text in the specified color. This
attribute value can be combined with :const:`A_STANDOUT`, :const:`A_REVERSE`,
and the other :const:`A_\*` attributes. :func:`pair_number` is the counterpart
to this function.
.. function:: curs_set(visibility)
Set the cursor state. *visibility* can be set to 0, 1, or 2, for invisible,
normal, or very visible. If the terminal supports the visibility requested, the
previous cursor state is returned; otherwise, an exception is raised. On many
terminals, the "visible" mode is an underline cursor and the "very visible" mode
is a block cursor.
.. function:: def_prog_mode()
Save the current terminal mode as the "program" mode, the mode when the running
program is using curses. (Its counterpart is the "shell" mode, for when the
program is not in curses.) Subsequent calls to :func:`reset_prog_mode` will
restore this mode.
.. function:: def_shell_mode()
Save the current terminal mode as the "shell" mode, the mode when the running
program is not using curses. (Its counterpart is the "program" mode, when the
program is using curses capabilities.) Subsequent calls to
:func:`reset_shell_mode` will restore this mode.
.. function:: delay_output(ms)
Insert an *ms* millisecond pause in output.
.. function:: doupdate()
Update the physical screen. The curses library keeps two data structures, one
representing the current physical screen contents and a virtual screen
representing the desired next state. The :func:`doupdate` ground updates the
physical screen to match the virtual screen.
The virtual screen may be updated by a :meth:`noutrefresh` call after write
operations such as :meth:`addstr` have been performed on a window. The normal
:meth:`refresh` call is simply :meth:`noutrefresh` followed by :func:`doupdate`;
if you have to update multiple windows, you can speed performance and perhaps
reduce screen flicker by issuing :meth:`noutrefresh` calls on all windows,
followed by a single :func:`doupdate`.
.. function:: echo()
Enter echo mode. In echo mode, each character input is echoed to the screen as
it is entered.
.. function:: endwin()
De-initialize the library, and return terminal to normal status.
.. function:: erasechar()
Return the user's current erase character. Under Unix operating systems this
is a property of the controlling tty of the curses program, and is not set by
the curses library itself.
.. function:: filter()
The :func:`.filter` routine, if used, must be called before :func:`initscr` is
called. The effect is that, during those calls, :envvar:`LINES` is set to 1; the
capabilities clear, cup, cud, cud1, cuu1, cuu, vpa are disabled; and the home
string is set to the value of cr. The effect is that the cursor is confined to
the current line, and so are screen updates. This may be used for enabling
character-at-a-time line editing without touching the rest of the screen.
.. function:: flash()
Flash the screen. That is, change it to reverse-video and then change it back
in a short interval. Some people prefer such as 'visible bell' to the audible
attention signal produced by :func:`beep`.
.. function:: flushinp()
Flush all input buffers. This throws away any typeahead that has been typed
by the user and has not yet been processed by the program.
.. function:: getmouse()
After :meth:`getch` returns :const:`KEY_MOUSE` to signal a mouse event, this
method should be call to retrieve the queued mouse event, represented as a
5-tuple ``(id, x, y, z, bstate)``. *id* is an ID value used to distinguish
multiple devices, and *x*, *y*, *z* are the event's coordinates. (*z* is
currently unused.) *bstate* is an integer value whose bits will be set to
indicate the type of event, and will be the bitwise OR of one or more of the
following constants, where *n* is the button number from 1 to 4:
:const:`BUTTONn_PRESSED`, :const:`BUTTONn_RELEASED`, :const:`BUTTONn_CLICKED`,
:const:`BUTTONn_DOUBLE_CLICKED`, :const:`BUTTONn_TRIPLE_CLICKED`,
:const:`BUTTON_SHIFT`, :const:`BUTTON_CTRL`, :const:`BUTTON_ALT`.
.. function:: getsyx()
Return the current coordinates of the virtual screen cursor in y and x. If
leaveok is currently true, then -1,-1 is returned.
.. function:: getwin(file)
Read window related data stored in the file by an earlier :func:`putwin` call.
The routine then creates and initializes a new window using that data, returning
the new window object.
.. function:: has_colors()
Return ``True`` if the terminal can display colors; otherwise, return ``False``.
.. function:: has_ic()
Return ``True`` if the terminal has insert- and delete-character capabilities.
This function is included for historical reasons only, as all modern software
terminal emulators have such capabilities.
.. function:: has_il()
Return ``True`` if the terminal has insert- and delete-line capabilities, or can
simulate them using scrolling regions. This function is included for
historical reasons only, as all modern software terminal emulators have such
capabilities.
.. function:: has_key(ch)
Take a key value *ch*, and return ``True`` if the current terminal type recognizes
a key with that value.
.. function:: halfdelay(tenths)
Used for half-delay mode, which is similar to cbreak mode in that characters
typed by the user are immediately available to the program. However, after
blocking for *tenths* tenths of seconds, an exception is raised if nothing has
been typed. The value of *tenths* must be a number between ``1`` and ``255``. Use
:func:`nocbreak` to leave half-delay mode.
.. function:: init_color(color_number, r, g, b)
Change the definition of a color, taking the number of the color to be changed
followed by three RGB values (for the amounts of red, green, and blue
components). The value of *color_number* must be between ``0`` and
:const:`COLORS`. Each of *r*, *g*, *b*, must be a value between ``0`` and
``1000``. When :func:`init_color` is used, all occurrences of that color on the
screen immediately change to the new definition. This function is a no-op on
most terminals; it is active only if :func:`can_change_color` returns ``1``.
.. function:: init_pair(pair_number, fg, bg)
Change the definition of a color-pair. It takes three arguments: the number of
the color-pair to be changed, the foreground color number, and the background
color number. The value of *pair_number* must be between ``1`` and
``COLOR_PAIRS - 1`` (the ``0`` color pair is wired to white on black and cannot
be changed). The value of *fg* and *bg* arguments must be between ``0`` and
:const:`COLORS`. If the color-pair was previously initialized, the screen is
refreshed and all occurrences of that color-pair are changed to the new
definition.
.. function:: initscr()
Initialize the library. Return a :class:`WindowObject` which represents the
whole screen.
.. note::
If there is an error opening the terminal, the underlying curses library may
cause the interpreter to exit.
.. function:: is_term_resized(nlines, ncols)
Return ``True`` if :func:`resize_term` would modify the window structure,
``False`` otherwise.
.. function:: isendwin()
Return ``True`` if :func:`endwin` has been called (that is, the curses library has
been deinitialized).
.. function:: keyname(k)
Return the name of the key numbered *k*. The name of a key generating printable
ASCII character is the key's character. The name of a control-key combination
is a two-character string consisting of a caret followed by the corresponding
printable ASCII character. The name of an alt-key combination (128--255) is a
string consisting of the prefix 'M-' followed by the name of the corresponding
ASCII character.
.. function:: killchar()
Return the user's current line kill character. Under Unix operating systems
this is a property of the controlling tty of the curses program, and is not set
by the curses library itself.
.. function:: longname()
Return a string containing the terminfo long name field describing the current
terminal. The maximum length of a verbose description is 128 characters. It is
defined only after the call to :func:`initscr`.
.. function:: meta(yes)
If *yes* is 1, allow 8-bit characters to be input. If *yes* is 0, allow only
7-bit chars.
.. function:: mouseinterval(interval)
Set the maximum time in milliseconds that can elapse between press and release
events in order for them to be recognized as a click, and return the previous
interval value. The default value is 200 msec, or one fifth of a second.
.. function:: mousemask(mousemask)
Set the mouse events to be reported, and return a tuple ``(availmask,
oldmask)``. *availmask* indicates which of the specified mouse events can be
reported; on complete failure it returns 0. *oldmask* is the previous value of
the given window's mouse event mask. If this function is never called, no mouse
events are ever reported.
.. function:: napms(ms)
Sleep for *ms* milliseconds.
.. function:: newpad(nlines, ncols)
Create and return a pointer to a new pad data structure with the given number
of lines and columns. A pad is returned as a window object.
A pad is like a window, except that it is not restricted by the screen size, and
is not necessarily associated with a particular part of the screen. Pads can be
used when a large window is needed, and only a part of the window will be on the
screen at one time. Automatic refreshes of pads (such as from scrolling or
echoing of input) do not occur. The :meth:`refresh` and :meth:`noutrefresh`
methods of a pad require 6 arguments to specify the part of the pad to be
displayed and the location on the screen to be used for the display. The
arguments are *pminrow*, *pmincol*, *sminrow*, *smincol*, *smaxrow*, *smaxcol*; the *p*
arguments refer to the upper left corner of the pad region to be displayed and
the *s* arguments define a clipping box on the screen within which the pad region
is to be displayed.
.. function:: newwin(nlines, ncols)
newwin(nlines, ncols, begin_y, begin_x)
Return a new window, whose left-upper corner is at ``(begin_y, begin_x)``, and
whose height/width is *nlines*/*ncols*.
By default, the window will extend from the specified position to the lower
right corner of the screen.
.. function:: nl()
Enter newline mode. This mode translates the return key into newline on input,
and translates newline into return and line-feed on output. Newline mode is
initially on.
.. function:: nocbreak()
Leave cbreak mode. Return to normal "cooked" mode with line buffering.
.. function:: noecho()
Leave echo mode. Echoing of input characters is turned off.
.. function:: nonl()
Leave newline mode. Disable translation of return into newline on input, and
disable low-level translation of newline into newline/return on output (but this
does not change the behavior of ``addch('\n')``, which always does the
equivalent of return and line feed on the virtual screen). With translation
off, curses can sometimes speed up vertical motion a little; also, it will be
able to detect the return key on input.
.. function:: noqiflush()
When the :func:`noqiflush` routine is used, normal flush of input and output queues
associated with the INTR, QUIT and SUSP characters will not be done. You may
want to call :func:`noqiflush` in a signal handler if you want output to
continue as though the interrupt had not occurred, after the handler exits.
.. function:: noraw()
Leave raw mode. Return to normal "cooked" mode with line buffering.
.. function:: pair_content(pair_number)
Return a tuple ``(fg, bg)`` containing the colors for the requested color pair.
The value of *pair_number* must be between ``1`` and ``COLOR_PAIRS - 1``.
.. function:: pair_number(attr)
Return the number of the color-pair set by the attribute value *attr*.
:func:`color_pair` is the counterpart to this function.
.. function:: putp(string)
Equivalent to ``tputs(str, 1, putchar)``; emit the value of a specified
terminfo capability for the current terminal. Note that the output of :func:`putp`
always goes to standard output.
.. function:: qiflush( [flag] )
If *flag* is ``False``, the effect is the same as calling :func:`noqiflush`. If
*flag* is ``True``, or no argument is provided, the queues will be flushed when
these control characters are read.
.. function:: raw()
Enter raw mode. In raw mode, normal line buffering and processing of
interrupt, quit, suspend, and flow control keys are turned off; characters are
presented to curses input functions one by one.
.. function:: reset_prog_mode()
Restore the terminal to "program" mode, as previously saved by
:func:`def_prog_mode`.
.. function:: reset_shell_mode()
Restore the terminal to "shell" mode, as previously saved by
:func:`def_shell_mode`.
.. function:: resetty()
Restore the state of the terminal modes to what it was at the last call to
:func:`savetty`.
.. function:: resize_term(nlines, ncols)
Backend function used by :func:`resizeterm`, performing most of the work;
when resizing the windows, :func:`resize_term` blank-fills the areas that are
extended. The calling application should fill in these areas with
appropriate data. The :func:`resize_term` function attempts to resize all
windows. However, due to the calling convention of pads, it is not possible
to resize these without additional interaction with the application.
.. function:: resizeterm(nlines, ncols)
Resize the standard and current windows to the specified dimensions, and
adjusts other bookkeeping data used by the curses library that record the
window dimensions (in particular the SIGWINCH handler).
.. function:: savetty()
Save the current state of the terminal modes in a buffer, usable by
:func:`resetty`.
.. function:: setsyx(y, x)
Set the virtual screen cursor to *y*, *x*. If *y* and *x* are both -1, then
leaveok is set.
.. function:: setupterm([termstr, fd])
Initialize the terminal. *termstr* is a string giving the terminal name; if
omitted, the value of the :envvar:`TERM` environment variable will be used. *fd* is the
file descriptor to which any initialization sequences will be sent; if not
supplied, the file descriptor for ``sys.stdout`` will be used.
.. function:: start_color()
Must be called if the programmer wants to use colors, and before any other color
manipulation routine is called. It is good practice to call this routine right
after :func:`initscr`.
:func:`start_color` initializes eight basic colors (black, red, green, yellow,
blue, magenta, cyan, and white), and two global variables in the :mod:`curses`
module, :const:`COLORS` and :const:`COLOR_PAIRS`, containing the maximum number
of colors and color-pairs the terminal can support. It also restores the colors
on the terminal to the values they had when the terminal was just turned on.
.. function:: termattrs()
Return a logical OR of all video attributes supported by the terminal. This
information is useful when a curses program needs complete control over the
appearance of the screen.
.. function:: termname()
Return the value of the environment variable :envvar:`TERM`, truncated to 14 characters.
.. function:: tigetflag(capname)
Return the value of the Boolean capability corresponding to the terminfo
capability name *capname*. The value ``-1`` is returned if *capname* is not a
Boolean capability, or ``0`` if it is canceled or absent from the terminal
description.
.. function:: tigetnum(capname)
Return the value of the numeric capability corresponding to the terminfo
capability name *capname*. The value ``-2`` is returned if *capname* is not a
numeric capability, or ``-1`` if it is canceled or absent from the terminal
description.
.. function:: tigetstr(capname)
Return the value of the string capability corresponding to the terminfo
capability name *capname*. ``None`` is returned if *capname* is not a string
capability, or is canceled or absent from the terminal description.
.. function:: tparm(str[,...])
Instantiate the string *str* with the supplied parameters, where *str* should
be a parameterized string obtained from the terminfo database. E.g.
``tparm(tigetstr("cup"), 5, 3)`` could result in ``'\033[6;4H'``, the exact
result depending on terminal type.
.. function:: typeahead(fd)
Specify that the file descriptor *fd* be used for typeahead checking. If *fd*
is ``-1``, then no typeahead checking is done.
The curses library does "line-breakout optimization" by looking for typeahead
periodically while updating the screen. If input is found, and it is coming
from a tty, the current update is postponed until refresh or doupdate is called
again, allowing faster response to commands typed in advance. This function
allows specifying a different file descriptor for typeahead checking.
.. function:: unctrl(ch)
Return a string which is a printable representation of the character *ch*.
Control characters are displayed as a caret followed by the character, for
example as ``^C``. Printing characters are left as they are.
.. function:: ungetch(ch)
Push *ch* so the next :meth:`getch` will return it.
.. note::
Only one *ch* can be pushed before :meth:`getch` is called.
.. function:: ungetmouse(id, x, y, z, bstate)
Push a :const:`KEY_MOUSE` event onto the input queue, associating the given
state data with it.
.. function:: use_env(flag)
If used, this function should be called before :func:`initscr` or newterm are
called. When *flag* is ``False``, the values of lines and columns specified in the
terminfo database will be used, even if environment variables :envvar:`LINES`
and :envvar:`COLUMNS` (used by default) are set, or if curses is running in a
window (in which case default behavior would be to use the window size if
:envvar:`LINES` and :envvar:`COLUMNS` are not set).
.. function:: use_default_colors()
Allow use of default values for colors on terminals supporting this feature. Use
this to support transparency in your application. The default color is assigned
to the color number -1. After calling this function, ``init_pair(x,
curses.COLOR_RED, -1)`` initializes, for instance, color pair *x* to a red
foreground color on the default background.
.. function:: wrapper(func, ...)
Initialize curses and call another callable object, *func*, which should be the
rest of your curses-using application. If the application raises an exception,
this function will restore the terminal to a sane state before re-raising the
exception and generating a traceback. The callable object *func* is then passed
the main window 'stdscr' as its first argument, followed by any other arguments
passed to :func:`wrapper`. Before calling *func*, :func:`wrapper` turns on
cbreak mode, turns off echo, enables the terminal keypad, and initializes colors
if the terminal has color support. On exit (whether normally or by exception)
it restores cooked mode, turns on echo, and disables the terminal keypad.
.. _curses-window-objects:
Window Objects
--------------
Window objects, as returned by :func:`initscr` and :func:`newwin` above, have
the following methods:
.. method:: window.addch(ch[, attr])
window.addch(y, x, ch[, attr])
.. note::
A *character* means a C character (an ASCII code), rather than a Python
character (a string of length 1). (This note is true whenever the
documentation mentions a character.) The built-in :func:`ord` is handy for
conveying strings to codes.
Paint character *ch* at ``(y, x)`` with attributes *attr*, overwriting any
character previously painter at that location. By default, the character
position and attributes are the current settings for the window object.
.. note::
Writing outside the window, subwindow, or pad raises a :exc:`curses.error`.
Attempting to write to the lower right corner of a window, subwindow,
or pad will cause an exception to be raised after the character is printed.
.. method:: window.addnstr(str, n[, attr])
window.addnstr(y, x, str, n[, attr])
Paint at most *n* characters of the string *str* at ``(y, x)`` with attributes
*attr*, overwriting anything previously on the display.
.. method:: window.addstr(str[, attr])
window.addstr(y, x, str[, attr])
Paint the string *str* at ``(y, x)`` with attributes *attr*, overwriting
anything previously on the display.
.. note::
Writing outside the window, subwindow, or pad raises :exc:`curses.error`.
Attempting to write to the lower right corner of a window, subwindow,
or pad will cause an exception to be raised after the string is printed.
.. method:: window.attroff(attr)
Remove attribute *attr* from the "background" set applied to all writes to the
current window.
.. method:: window.attron(attr)
Add attribute *attr* from the "background" set applied to all writes to the
current window.
.. method:: window.attrset(attr)
Set the "background" set of attributes to *attr*. This set is initially 0 (no
attributes).
.. method:: window.bkgd(ch[, attr])
Set the background property of the window to the character *ch*, with
attributes *attr*. The change is then applied to every character position in
that window:
* The attribute of every character in the window is changed to the new
background attribute.
* Wherever the former background character appears, it is changed to the new
background character.
.. method:: window.bkgdset(ch[, attr])
Set the window's background. A window's background consists of a character and
any combination of attributes. The attribute part of the background is combined
(OR'ed) with all non-blank characters that are written into the window. Both
the character and attribute parts of the background are combined with the blank
characters. The background becomes a property of the character and moves with
the character through any scrolling and insert/delete line/character operations.
.. method:: window.border([ls[, rs[, ts[, bs[, tl[, tr[, bl[, br]]]]]]]])
Draw a border around the edges of the window. Each parameter specifies the
character to use for a specific part of the border; see the table below for more
details. The characters can be specified as integers or as one-character
strings.
.. note::
A ``0`` value for any parameter will cause the default character to be used for
that parameter. Keyword parameters can *not* be used. The defaults are listed
in this table:
+-----------+---------------------+-----------------------+
| Parameter | Description | Default value |
+===========+=====================+=======================+
| *ls* | Left side | :const:`ACS_VLINE` |
+-----------+---------------------+-----------------------+
| *rs* | Right side | :const:`ACS_VLINE` |
+-----------+---------------------+-----------------------+
| *ts* | Top | :const:`ACS_HLINE` |
+-----------+---------------------+-----------------------+
| *bs* | Bottom | :const:`ACS_HLINE` |
+-----------+---------------------+-----------------------+
| *tl* | Upper-left corner | :const:`ACS_ULCORNER` |
+-----------+---------------------+-----------------------+
| *tr* | Upper-right corner | :const:`ACS_URCORNER` |
+-----------+---------------------+-----------------------+
| *bl* | Bottom-left corner | :const:`ACS_LLCORNER` |
+-----------+---------------------+-----------------------+
| *br* | Bottom-right corner | :const:`ACS_LRCORNER` |
+-----------+---------------------+-----------------------+
.. method:: window.box([vertch, horch])
Similar to :meth:`border`, but both *ls* and *rs* are *vertch* and both *ts* and
*bs* are *horch*. The default corner characters are always used by this function.
.. method:: window.chgat(attr)
window.chgat(num, attr)
window.chgat(y, x, attr)
window.chgat(y, x, num, attr)
Set the attributes of *num* characters at the current cursor position, or at
position ``(y, x)`` if supplied. If *num* is not given or is ``-1``,
the attribute will be set on all the characters to the end of the line. This
function moves cursor to position ``(y, x)`` if supplied. The changed line
will be touched using the :meth:`touchline` method so that the contents will
be redisplayed by the next window refresh.
.. method:: window.clear()
Like :meth:`erase`, but also cause the whole window to be repainted upon next
call to :meth:`refresh`.
.. method:: window.clearok(yes)
If *yes* is 1, the next call to :meth:`refresh` will clear the window
completely.
.. method:: window.clrtobot()
Erase from cursor to the end of the window: all lines below the cursor are
deleted, and then the equivalent of :meth:`clrtoeol` is performed.
.. method:: window.clrtoeol()
Erase from cursor to the end of the line.
.. method:: window.cursyncup()
Update the current cursor position of all the ancestors of the window to
reflect the current cursor position of the window.
.. method:: window.delch([y, x])
Delete any character at ``(y, x)``.
.. method:: window.deleteln()
Delete the line under the cursor. All following lines are moved up by one line.
.. method:: window.derwin(begin_y, begin_x)
window.derwin(nlines, ncols, begin_y, begin_x)
An abbreviation for "derive window", :meth:`derwin` is the same as calling
:meth:`subwin`, except that *begin_y* and *begin_x* are relative to the origin
of the window, rather than relative to the entire screen. Return a window
object for the derived window.
.. method:: window.echochar(ch[, attr])
Add character *ch* with attribute *attr*, and immediately call :meth:`refresh`
on the window.
.. method:: window.enclose(y, x)
Test whether the given pair of screen-relative character-cell coordinates are
enclosed by the given window, returning ``True`` or ``False``. It is useful for
determining what subset of the screen windows enclose the location of a mouse
event.
.. method:: window.erase()
Clear the window.
.. method:: window.getbegyx()
Return a tuple ``(y, x)`` of co-ordinates of upper-left corner.
.. method:: window.getbkgd()
Return the given window's current background character/attribute pair.
.. method:: window.getch([y, x])
Get a character. Note that the integer returned does *not* have to be in ASCII
range: function keys, keypad keys and so on return numbers higher than 256. In
no-delay mode, -1 is returned if there is no input, else :func:`getch` waits
until a key is pressed.
.. method:: window.getkey([y, x])
Get a character, returning a string instead of an integer, as :meth:`getch`
does. Function keys, keypad keys and so on return a multibyte string containing
the key name. In no-delay mode, an exception is raised if there is no input.
.. method:: window.getmaxyx()
Return a tuple ``(y, x)`` of the height and width of the window.
.. method:: window.getparyx()
Return the beginning coordinates of this window relative to its parent window
into two integer variables y and x. Return ``-1, -1`` if this window has no
parent.
.. method:: window.getstr([y, x])
Read a string from the user, with primitive line editing capacity.
.. method:: window.getyx()
Return a tuple ``(y, x)`` of current cursor position relative to the window's
upper-left corner.
.. method:: window.hline(ch, n)
window.hline(y, x, ch, n)
Display a horizontal line starting at ``(y, x)`` with length *n* consisting of
the character *ch*.
.. method:: window.idcok(flag)
If *flag* is ``False``, curses no longer considers using the hardware insert/delete
character feature of the terminal; if *flag* is ``True``, use of character insertion
and deletion is enabled. When curses is first initialized, use of character
insert/delete is enabled by default.
.. method:: window.idlok(yes)
If called with *yes* equal to 1, :mod:`curses` will try and use hardware line
editing facilities. Otherwise, line insertion/deletion are disabled.
.. method:: window.immedok(flag)
If *flag* is ``True``, any change in the window image automatically causes the
window to be refreshed; you no longer have to call :meth:`refresh` yourself.
However, it may degrade performance considerably, due to repeated calls to
wrefresh. This option is disabled by default.
.. method:: window.inch([y, x])
Return the character at the given position in the window. The bottom 8 bits are
the character proper, and upper bits are the attributes.
.. method:: window.insch(ch[, attr])
window.insch(y, x, ch[, attr])
Paint character *ch* at ``(y, x)`` with attributes *attr*, moving the line from
position *x* right by one character.
.. method:: window.insdelln(nlines)
Insert *nlines* lines into the specified window above the current line. The
*nlines* bottom lines are lost. For negative *nlines*, delete *nlines* lines
starting with the one under the cursor, and move the remaining lines up. The
bottom *nlines* lines are cleared. The current cursor position remains the
same.
.. method:: window.insertln()
Insert a blank line under the cursor. All following lines are moved down by one
line.
.. method:: window.insnstr(str, n[, attr])
window.insnstr(y, x, str, n[, attr])
Insert a character string (as many characters as will fit on the line) before
the character under the cursor, up to *n* characters. If *n* is zero or
negative, the entire string is inserted. All characters to the right of the
cursor are shifted right, with the rightmost characters on the line being lost.
The cursor position does not change (after moving to *y*, *x*, if specified).
.. method:: window.insstr(str[, attr])
window.insstr(y, x, str[, attr])
Insert a character string (as many characters as will fit on the line) before
the character under the cursor. All characters to the right of the cursor are
shifted right, with the rightmost characters on the line being lost. The cursor
position does not change (after moving to *y*, *x*, if specified).
.. method:: window.instr([n])
window.instr(y, x[, n])
Return a string of characters, extracted from the window starting at the
current cursor position, or at *y*, *x* if specified. Attributes are stripped
from the characters. If *n* is specified, :meth:`instr` returns a string
at most *n* characters long (exclusive of the trailing NUL).
.. method:: window.is_linetouched(line)
Return ``True`` if the specified line was modified since the last call to
:meth:`refresh`; otherwise return ``False``. Raise a :exc:`curses.error`
exception if *line* is not valid for the given window.
.. method:: window.is_wintouched()
Return ``True`` if the specified window was modified since the last call to
:meth:`refresh`; otherwise return ``False``.
.. method:: window.keypad(yes)
If *yes* is 1, escape sequences generated by some keys (keypad, function keys)
will be interpreted by :mod:`curses`. If *yes* is 0, escape sequences will be
left as is in the input stream.
.. method:: window.leaveok(yes)
If *yes* is 1, cursor is left where it is on update, instead of being at "cursor
position." This reduces cursor movement where possible. If possible the cursor
will be made invisible.
If *yes* is 0, cursor will always be at "cursor position" after an update.
.. method:: window.move(new_y, new_x)
Move cursor to ``(new_y, new_x)``.
.. method:: window.mvderwin(y, x)
Move the window inside its parent window. The screen-relative parameters of
the window are not changed. This routine is used to display different parts of
the parent window at the same physical position on the screen.
.. method:: window.mvwin(new_y, new_x)
Move the window so its upper-left corner is at ``(new_y, new_x)``.
.. method:: window.nodelay(yes)
If *yes* is ``1``, :meth:`getch` will be non-blocking.
.. method:: window.notimeout(yes)
If *yes* is ``1``, escape sequences will not be timed out.
If *yes* is ``0``, after a few milliseconds, an escape sequence will not be
interpreted, and will be left in the input stream as is.
.. method:: window.noutrefresh()
Mark for refresh but wait. This function updates the data structure
representing the desired state of the window, but does not force an update of
the physical screen. To accomplish that, call :func:`doupdate`.
.. method:: window.overlay(destwin[, sminrow, smincol, dminrow, dmincol, dmaxrow, dmaxcol])
Overlay the window on top of *destwin*. The windows need not be the same size,
only the overlapping region is copied. This copy is non-destructive, which means
that the current background character does not overwrite the old contents of
*destwin*.
To get fine-grained control over the copied region, the second form of
:meth:`overlay` can be used. *sminrow* and *smincol* are the upper-left
coordinates of the source window, and the other variables mark a rectangle in
the destination window.
.. method:: window.overwrite(destwin[, sminrow, smincol, dminrow, dmincol, dmaxrow, dmaxcol])
Overwrite the window on top of *destwin*. The windows need not be the same size,
in which case only the overlapping region is copied. This copy is destructive,
which means that the current background character overwrites the old contents of
*destwin*.
To get fine-grained control over the copied region, the second form of
:meth:`overwrite` can be used. *sminrow* and *smincol* are the upper-left
coordinates of the source window, the other variables mark a rectangle in the
destination window.
.. method:: window.putwin(file)
Write all data associated with the window into the provided file object. This
information can be later retrieved using the :func:`getwin` function.
.. method:: window.redrawln(beg, num)
Indicate that the *num* screen lines, starting at line *beg*, are corrupted and
should be completely redrawn on the next :meth:`refresh` call.
.. method:: window.redrawwin()
Touch the entire window, causing it to be completely redrawn on the next
:meth:`refresh` call.
.. method:: window.refresh([pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol])
Update the display immediately (sync actual screen with previous
drawing/deleting methods).
The 6 optional arguments can only be specified when the window is a pad created
with :func:`newpad`. The additional parameters are needed to indicate what part
of the pad and screen are involved. *pminrow* and *pmincol* specify the upper
left-hand corner of the rectangle to be displayed in the pad. *sminrow*,
*smincol*, *smaxrow*, and *smaxcol* specify the edges of the rectangle to be
displayed on the screen. The lower right-hand corner of the rectangle to be
displayed in the pad is calculated from the screen coordinates, since the
rectangles must be the same size. Both rectangles must be entirely contained
within their respective structures. Negative values of *pminrow*, *pmincol*,
*sminrow*, or *smincol* are treated as if they were zero.
.. method:: window.resize(nlines, ncols)
Reallocate storage for a curses window to adjust its dimensions to the
specified values. If either dimension is larger than the current values, the
window's data is filled with blanks that have the current background
rendition (as set by :meth:`bkgdset`) merged into them.
.. method:: window.scroll([lines=1])
Scroll the screen or scrolling region upward by *lines* lines.
.. method:: window.scrollok(flag)
Control what happens when the cursor of a window is moved off the edge of the
window or scrolling region, either as a result of a newline action on the bottom
line, or typing the last character of the last line. If *flag* is false, the
cursor is left on the bottom line. If *flag* is true, the window is scrolled up
one line. Note that in order to get the physical scrolling effect on the
terminal, it is also necessary to call :meth:`idlok`.
.. method:: window.setscrreg(top, bottom)
Set the scrolling region from line *top* to line *bottom*. All scrolling actions
will take place in this region.
.. method:: window.standend()
Turn off the standout attribute. On some terminals this has the side effect of
turning off all attributes.
.. method:: window.standout()
Turn on attribute *A_STANDOUT*.
.. method:: window.subpad(begin_y, begin_x)
window.subpad(nlines, ncols, begin_y, begin_x)
Return a sub-window, whose upper-left corner is at ``(begin_y, begin_x)``, and
whose width/height is *ncols*/*nlines*.
.. method:: window.subwin(begin_y, begin_x)
window.subwin(nlines, ncols, begin_y, begin_x)
Return a sub-window, whose upper-left corner is at ``(begin_y, begin_x)``, and
whose width/height is *ncols*/*nlines*.
By default, the sub-window will extend from the specified position to the lower
right corner of the window.
.. method:: window.syncdown()
Touch each location in the window that has been touched in any of its ancestor
windows. This routine is called by :meth:`refresh`, so it should almost never
be necessary to call it manually.
.. method:: window.syncok(flag)
If called with *flag* set to ``True``, then :meth:`syncup` is called automatically
whenever there is a change in the window.
.. method:: window.syncup()
Touch all locations in ancestors of the window that have been changed in the
window.
.. method:: window.timeout(delay)
Set blocking or non-blocking read behavior for the window. If *delay* is
negative, blocking read is used (which will wait indefinitely for input). If
*delay* is zero, then non-blocking read is used, and -1 will be returned by
:meth:`getch` if no input is waiting. If *delay* is positive, then
:meth:`getch` will block for *delay* milliseconds, and return -1 if there is
still no input at the end of that time.
.. method:: window.touchline(start, count[, changed])
Pretend *count* lines have been changed, starting with line *start*. If
*changed* is supplied, it specifies whether the affected lines are marked as
having been changed (*changed*\ =1) or unchanged (*changed*\ =0).
.. method:: window.touchwin()
Pretend the whole window has been changed, for purposes of drawing
optimizations.
.. method:: window.untouchwin()
Mark all lines in the window as unchanged since the last call to
:meth:`refresh`.
.. method:: window.vline(ch, n)
window.vline(y, x, ch, n)
Display a vertical line starting at ``(y, x)`` with length *n* consisting of the
character *ch*.
Constants
---------
The :mod:`curses` module defines the following data members:
.. data:: ERR
Some curses routines that return an integer, such as :func:`getch`, return
:const:`ERR` upon failure.
.. data:: OK
Some curses routines that return an integer, such as :func:`napms`, return
:const:`OK` upon success.
.. data:: version
A string representing the current version of the module. Also available as
:const:`__version__`.
Some constants are available to specify character cell attributes.
The exact constants available are system dependent.
+------------------+-------------------------------+
| Attribute | Meaning |
+==================+===============================+
| ``A_ALTCHARSET`` | Alternate character set mode |
+------------------+-------------------------------+
| ``A_BLINK`` | Blink mode |
+------------------+-------------------------------+
| ``A_BOLD`` | Bold mode |
+------------------+-------------------------------+
| ``A_DIM`` | Dim mode |
+------------------+-------------------------------+
| ``A_INVIS`` | Invisible or blank mode |
+------------------+-------------------------------+
| ``A_NORMAL`` | Normal attribute |
+------------------+-------------------------------+
| ``A_PROTECT`` | Protected mode |
+------------------+-------------------------------+
| ``A_REVERSE`` | Reverse background and |
| | foreground colors |
+------------------+-------------------------------+
| ``A_STANDOUT`` | Standout mode |
+------------------+-------------------------------+
| ``A_UNDERLINE`` | Underline mode |
+------------------+-------------------------------+
| ``A_HORIZONTAL`` | Horizontal highlight |
+------------------+-------------------------------+
| ``A_LEFT`` | Left highlight |
+------------------+-------------------------------+
| ``A_LOW`` | Low highlight |
+------------------+-------------------------------+
| ``A_RIGHT`` | Right highlight |
+------------------+-------------------------------+
| ``A_TOP`` | Top highlight |
+------------------+-------------------------------+
| ``A_VERTICAL`` | Vertical highlight |
+------------------+-------------------------------+
| ``A_CHARTEXT`` | Bit-mask to extract a |
| | character |
+------------------+-------------------------------+
Several constants are available to extract corresponding attributes returned
by some methods.
+------------------+-------------------------------+
| Bit-mask | Meaning |
+==================+===============================+
| ``A_ATTRIBUTES`` | Bit-mask to extract |
| | attributes |
+------------------+-------------------------------+
| ``A_CHARTEXT`` | Bit-mask to extract a |
| | character |
+------------------+-------------------------------+
| ``A_COLOR`` | Bit-mask to extract |
| | color-pair field information |
+------------------+-------------------------------+
Keys are referred to by integer constants with names starting with ``KEY_``.
The exact keycaps available are system dependent.
.. XXX this table is far too large! should it be alphabetized?
+-------------------+--------------------------------------------+
| Key constant | Key |
+===================+============================================+
| ``KEY_MIN`` | Minimum key value |
+-------------------+--------------------------------------------+
| ``KEY_BREAK`` | Break key (unreliable) |
+-------------------+--------------------------------------------+
| ``KEY_DOWN`` | Down-arrow |
+-------------------+--------------------------------------------+
| ``KEY_UP`` | Up-arrow |
+-------------------+--------------------------------------------+
| ``KEY_LEFT`` | Left-arrow |
+-------------------+--------------------------------------------+
| ``KEY_RIGHT`` | Right-arrow |
+-------------------+--------------------------------------------+
| ``KEY_HOME`` | Home key (upward+left arrow) |
+-------------------+--------------------------------------------+
| ``KEY_BACKSPACE`` | Backspace (unreliable) |
+-------------------+--------------------------------------------+
| ``KEY_F0`` | Function keys. Up to 64 function keys are |
| | supported. |
+-------------------+--------------------------------------------+
| ``KEY_Fn`` | Value of function key *n* |
+-------------------+--------------------------------------------+
| ``KEY_DL`` | Delete line |
+-------------------+--------------------------------------------+
| ``KEY_IL`` | Insert line |
+-------------------+--------------------------------------------+
| ``KEY_DC`` | Delete character |
+-------------------+--------------------------------------------+
| ``KEY_IC`` | Insert char or enter insert mode |
+-------------------+--------------------------------------------+
| ``KEY_EIC`` | Exit insert char mode |
+-------------------+--------------------------------------------+
| ``KEY_CLEAR`` | Clear screen |
+-------------------+--------------------------------------------+
| ``KEY_EOS`` | Clear to end of screen |
+-------------------+--------------------------------------------+
| ``KEY_EOL`` | Clear to end of line |
+-------------------+--------------------------------------------+
| ``KEY_SF`` | Scroll 1 line forward |
+-------------------+--------------------------------------------+
| ``KEY_SR`` | Scroll 1 line backward (reverse) |
+-------------------+--------------------------------------------+
| ``KEY_NPAGE`` | Next page |
+-------------------+--------------------------------------------+
| ``KEY_PPAGE`` | Previous page |
+-------------------+--------------------------------------------+
| ``KEY_STAB`` | Set tab |
+-------------------+--------------------------------------------+
| ``KEY_CTAB`` | Clear tab |
+-------------------+--------------------------------------------+
| ``KEY_CATAB`` | Clear all tabs |
+-------------------+--------------------------------------------+
| ``KEY_ENTER`` | Enter or send (unreliable) |
+-------------------+--------------------------------------------+
| ``KEY_SRESET`` | Soft (partial) reset (unreliable) |
+-------------------+--------------------------------------------+
| ``KEY_RESET`` | Reset or hard reset (unreliable) |
+-------------------+--------------------------------------------+
| ``KEY_PRINT`` | Print |
+-------------------+--------------------------------------------+
| ``KEY_LL`` | Home down or bottom (lower left) |
+-------------------+--------------------------------------------+
| ``KEY_A1`` | Upper left of keypad |
+-------------------+--------------------------------------------+
| ``KEY_A3`` | Upper right of keypad |
+-------------------+--------------------------------------------+
| ``KEY_B2`` | Center of keypad |
+-------------------+--------------------------------------------+
| ``KEY_C1`` | Lower left of keypad |
+-------------------+--------------------------------------------+
| ``KEY_C3`` | Lower right of keypad |
+-------------------+--------------------------------------------+
| ``KEY_BTAB`` | Back tab |
+-------------------+--------------------------------------------+
| ``KEY_BEG`` | Beg (beginning) |
+-------------------+--------------------------------------------+
| ``KEY_CANCEL`` | Cancel |
+-------------------+--------------------------------------------+
| ``KEY_CLOSE`` | Close |
+-------------------+--------------------------------------------+
| ``KEY_COMMAND`` | Cmd (command) |
+-------------------+--------------------------------------------+
| ``KEY_COPY`` | Copy |
+-------------------+--------------------------------------------+
| ``KEY_CREATE`` | Create |
+-------------------+--------------------------------------------+
| ``KEY_END`` | End |
+-------------------+--------------------------------------------+
| ``KEY_EXIT`` | Exit |
+-------------------+--------------------------------------------+
| ``KEY_FIND`` | Find |
+-------------------+--------------------------------------------+
| ``KEY_HELP`` | Help |
+-------------------+--------------------------------------------+
| ``KEY_MARK`` | Mark |
+-------------------+--------------------------------------------+
| ``KEY_MESSAGE`` | Message |
+-------------------+--------------------------------------------+
| ``KEY_MOVE`` | Move |
+-------------------+--------------------------------------------+
| ``KEY_NEXT`` | Next |
+-------------------+--------------------------------------------+
| ``KEY_OPEN`` | Open |
+-------------------+--------------------------------------------+
| ``KEY_OPTIONS`` | Options |
+-------------------+--------------------------------------------+
| ``KEY_PREVIOUS`` | Prev (previous) |
+-------------------+--------------------------------------------+
| ``KEY_REDO`` | Redo |
+-------------------+--------------------------------------------+
| ``KEY_REFERENCE`` | Ref (reference) |
+-------------------+--------------------------------------------+
| ``KEY_REFRESH`` | Refresh |
+-------------------+--------------------------------------------+
| ``KEY_REPLACE`` | Replace |
+-------------------+--------------------------------------------+
| ``KEY_RESTART`` | Restart |
+-------------------+--------------------------------------------+
| ``KEY_RESUME`` | Resume |
+-------------------+--------------------------------------------+
| ``KEY_SAVE`` | Save |
+-------------------+--------------------------------------------+
| ``KEY_SBEG`` | Shifted Beg (beginning) |
+-------------------+--------------------------------------------+
| ``KEY_SCANCEL`` | Shifted Cancel |
+-------------------+--------------------------------------------+
| ``KEY_SCOMMAND`` | Shifted Command |
+-------------------+--------------------------------------------+
| ``KEY_SCOPY`` | Shifted Copy |
+-------------------+--------------------------------------------+
| ``KEY_SCREATE`` | Shifted Create |
+-------------------+--------------------------------------------+
| ``KEY_SDC`` | Shifted Delete char |
+-------------------+--------------------------------------------+
| ``KEY_SDL`` | Shifted Delete line |
+-------------------+--------------------------------------------+
| ``KEY_SELECT`` | Select |
+-------------------+--------------------------------------------+
| ``KEY_SEND`` | Shifted End |
+-------------------+--------------------------------------------+
| ``KEY_SEOL`` | Shifted Clear line |
+-------------------+--------------------------------------------+
| ``KEY_SEXIT`` | Shifted Exit |
+-------------------+--------------------------------------------+
| ``KEY_SFIND`` | Shifted Find |
+-------------------+--------------------------------------------+
| ``KEY_SHELP`` | Shifted Help |
+-------------------+--------------------------------------------+
| ``KEY_SHOME`` | Shifted Home |
+-------------------+--------------------------------------------+
| ``KEY_SIC`` | Shifted Input |
+-------------------+--------------------------------------------+
| ``KEY_SLEFT`` | Shifted Left arrow |
+-------------------+--------------------------------------------+
| ``KEY_SMESSAGE`` | Shifted Message |
+-------------------+--------------------------------------------+
| ``KEY_SMOVE`` | Shifted Move |
+-------------------+--------------------------------------------+
| ``KEY_SNEXT`` | Shifted Next |
+-------------------+--------------------------------------------+
| ``KEY_SOPTIONS`` | Shifted Options |
+-------------------+--------------------------------------------+
| ``KEY_SPREVIOUS`` | Shifted Prev |
+-------------------+--------------------------------------------+
| ``KEY_SPRINT`` | Shifted Print |
+-------------------+--------------------------------------------+
| ``KEY_SREDO`` | Shifted Redo |
+-------------------+--------------------------------------------+
| ``KEY_SREPLACE`` | Shifted Replace |
+-------------------+--------------------------------------------+
| ``KEY_SRIGHT`` | Shifted Right arrow |
+-------------------+--------------------------------------------+
| ``KEY_SRSUME`` | Shifted Resume |
+-------------------+--------------------------------------------+
| ``KEY_SSAVE`` | Shifted Save |
+-------------------+--------------------------------------------+
| ``KEY_SSUSPEND`` | Shifted Suspend |
+-------------------+--------------------------------------------+
| ``KEY_SUNDO`` | Shifted Undo |
+-------------------+--------------------------------------------+
| ``KEY_SUSPEND`` | Suspend |
+-------------------+--------------------------------------------+
| ``KEY_UNDO`` | Undo |
+-------------------+--------------------------------------------+
| ``KEY_MOUSE`` | Mouse event has occurred |
+-------------------+--------------------------------------------+
| ``KEY_RESIZE`` | Terminal resize event |
+-------------------+--------------------------------------------+
| ``KEY_MAX`` | Maximum key value |
+-------------------+--------------------------------------------+
On VT100s and their software emulations, such as X terminal emulators, there are
normally at least four function keys (:const:`KEY_F1`, :const:`KEY_F2`,
:const:`KEY_F3`, :const:`KEY_F4`) available, and the arrow keys mapped to
:const:`KEY_UP`, :const:`KEY_DOWN`, :const:`KEY_LEFT` and :const:`KEY_RIGHT` in
the obvious way. If your machine has a PC keyboard, it is safe to expect arrow
keys and twelve function keys (older PC keyboards may have only ten function
keys); also, the following keypad mappings are standard:
+------------------+-----------+
| Keycap | Constant |
+==================+===========+
| :kbd:`Insert` | KEY_IC |
+------------------+-----------+
| :kbd:`Delete` | KEY_DC |
+------------------+-----------+
| :kbd:`Home` | KEY_HOME |
+------------------+-----------+
| :kbd:`End` | KEY_END |
+------------------+-----------+
| :kbd:`Page Up` | KEY_PPAGE |
+------------------+-----------+
| :kbd:`Page Down` | KEY_NPAGE |
+------------------+-----------+
The following table lists characters from the alternate character set. These are
inherited from the VT100 terminal, and will generally be available on software
emulations such as X terminals. When there is no graphic available, curses
falls back on a crude printable ASCII approximation.
.. note::
These are available only after :func:`initscr` has been called.
+------------------+------------------------------------------+
| ACS code | Meaning |
+==================+==========================================+
| ``ACS_BBSS`` | alternate name for upper right corner |
+------------------+------------------------------------------+
| ``ACS_BLOCK`` | solid square block |
+------------------+------------------------------------------+
| ``ACS_BOARD`` | board of squares |
+------------------+------------------------------------------+
| ``ACS_BSBS`` | alternate name for horizontal line |
+------------------+------------------------------------------+
| ``ACS_BSSB`` | alternate name for upper left corner |
+------------------+------------------------------------------+
| ``ACS_BSSS`` | alternate name for top tee |
+------------------+------------------------------------------+
| ``ACS_BTEE`` | bottom tee |
+------------------+------------------------------------------+
| ``ACS_BULLET`` | bullet |
+------------------+------------------------------------------+
| ``ACS_CKBOARD`` | checker board (stipple) |
+------------------+------------------------------------------+
| ``ACS_DARROW`` | arrow pointing down |
+------------------+------------------------------------------+
| ``ACS_DEGREE`` | degree symbol |
+------------------+------------------------------------------+
| ``ACS_DIAMOND`` | diamond |
+------------------+------------------------------------------+
| ``ACS_GEQUAL`` | greater-than-or-equal-to |
+------------------+------------------------------------------+
| ``ACS_HLINE`` | horizontal line |
+------------------+------------------------------------------+
| ``ACS_LANTERN`` | lantern symbol |
+------------------+------------------------------------------+
| ``ACS_LARROW`` | left arrow |
+------------------+------------------------------------------+
| ``ACS_LEQUAL`` | less-than-or-equal-to |
+------------------+------------------------------------------+
| ``ACS_LLCORNER`` | lower left-hand corner |
+------------------+------------------------------------------+
| ``ACS_LRCORNER`` | lower right-hand corner |
+------------------+------------------------------------------+
| ``ACS_LTEE`` | left tee |
+------------------+------------------------------------------+
| ``ACS_NEQUAL`` | not-equal sign |
+------------------+------------------------------------------+
| ``ACS_PI`` | letter pi |
+------------------+------------------------------------------+
| ``ACS_PLMINUS`` | plus-or-minus sign |
+------------------+------------------------------------------+
| ``ACS_PLUS`` | big plus sign |
+------------------+------------------------------------------+
| ``ACS_RARROW`` | right arrow |
+------------------+------------------------------------------+
| ``ACS_RTEE`` | right tee |
+------------------+------------------------------------------+
| ``ACS_S1`` | scan line 1 |
+------------------+------------------------------------------+
| ``ACS_S3`` | scan line 3 |
+------------------+------------------------------------------+
| ``ACS_S7`` | scan line 7 |
+------------------+------------------------------------------+
| ``ACS_S9`` | scan line 9 |
+------------------+------------------------------------------+
| ``ACS_SBBS`` | alternate name for lower right corner |
+------------------+------------------------------------------+
| ``ACS_SBSB`` | alternate name for vertical line |
+------------------+------------------------------------------+
| ``ACS_SBSS`` | alternate name for right tee |
+------------------+------------------------------------------+
| ``ACS_SSBB`` | alternate name for lower left corner |
+------------------+------------------------------------------+
| ``ACS_SSBS`` | alternate name for bottom tee |
+------------------+------------------------------------------+
| ``ACS_SSSB`` | alternate name for left tee |
+------------------+------------------------------------------+
| ``ACS_SSSS`` | alternate name for crossover or big plus |
+------------------+------------------------------------------+
| ``ACS_STERLING`` | pound sterling |
+------------------+------------------------------------------+
| ``ACS_TTEE`` | top tee |
+------------------+------------------------------------------+
| ``ACS_UARROW`` | up arrow |
+------------------+------------------------------------------+
| ``ACS_ULCORNER`` | upper left corner |
+------------------+------------------------------------------+
| ``ACS_URCORNER`` | upper right corner |
+------------------+------------------------------------------+
| ``ACS_VLINE`` | vertical line |
+------------------+------------------------------------------+
The following table lists the predefined colors:
+-------------------+----------------------------+
| Constant | Color |
+===================+============================+
| ``COLOR_BLACK`` | Black |
+-------------------+----------------------------+
| ``COLOR_BLUE`` | Blue |
+-------------------+----------------------------+
| ``COLOR_CYAN`` | Cyan (light greenish blue) |
+-------------------+----------------------------+
| ``COLOR_GREEN`` | Green |
+-------------------+----------------------------+
| ``COLOR_MAGENTA`` | Magenta (purplish red) |
+-------------------+----------------------------+
| ``COLOR_RED`` | Red |
+-------------------+----------------------------+
| ``COLOR_WHITE`` | White |
+-------------------+----------------------------+
| ``COLOR_YELLOW`` | Yellow |
+-------------------+----------------------------+
:mod:`curses.textpad` --- Text input widget for curses programs
===============================================================
.. module:: curses.textpad
:synopsis: Emacs-like input editing in a curses window.
.. moduleauthor:: Eric Raymond <esr@thyrsus.com>
.. sectionauthor:: Eric Raymond <esr@thyrsus.com>
.. versionadded:: 1.6
The :mod:`curses.textpad` module provides a :class:`Textbox` class that handles
elementary text editing in a curses window, supporting a set of keybindings
resembling those of Emacs (thus, also of Netscape Navigator, BBedit 6.x,
FrameMaker, and many other programs). The module also provides a
rectangle-drawing function useful for framing text boxes or for other purposes.
The module :mod:`curses.textpad` defines the following function:
.. function:: rectangle(win, uly, ulx, lry, lrx)
Draw a rectangle. The first argument must be a window object; the remaining
arguments are coordinates relative to that window. The second and third
arguments are the y and x coordinates of the upper left hand corner of the
rectangle to be drawn; the fourth and fifth arguments are the y and x
coordinates of the lower right hand corner. The rectangle will be drawn using
VT100/IBM PC forms characters on terminals that make this possible (including
xterm and most other software terminal emulators). Otherwise it will be drawn
with ASCII dashes, vertical bars, and plus signs.
.. _curses-textpad-objects:
Textbox objects
---------------
You can instantiate a :class:`Textbox` object as follows:
.. class:: Textbox(win)
Return a textbox widget object. The *win* argument should be a curses
:class:`WindowObject` in which the textbox is to be contained. The edit cursor
of the textbox is initially located at the upper left hand corner of the
containing window, with coordinates ``(0, 0)``. The instance's
:attr:`stripspaces` flag is initially on.
:class:`Textbox` objects have the following methods:
.. method:: edit([validator])
This is the entry point you will normally use. It accepts editing
keystrokes until one of the termination keystrokes is entered. If
*validator* is supplied, it must be a function. It will be called for
each keystroke entered with the keystroke as a parameter; command dispatch
is done on the result. This method returns the window contents as a
string; whether blanks in the window are included is affected by the
:attr:`stripspaces` attribute.
.. method:: do_command(ch)
Process a single command keystroke. Here are the supported special
keystrokes:
+------------------+-------------------------------------------+
| Keystroke | Action |
+==================+===========================================+
| :kbd:`Control-A` | Go to left edge of window. |
+------------------+-------------------------------------------+
| :kbd:`Control-B` | Cursor left, wrapping to previous line if |
| | appropriate. |
+------------------+-------------------------------------------+
| :kbd:`Control-D` | Delete character under cursor. |
+------------------+-------------------------------------------+
| :kbd:`Control-E` | Go to right edge (stripspaces off) or end |
| | of line (stripspaces on). |
+------------------+-------------------------------------------+
| :kbd:`Control-F` | Cursor right, wrapping to next line when |
| | appropriate. |
+------------------+-------------------------------------------+
| :kbd:`Control-G` | Terminate, returning the window contents. |
+------------------+-------------------------------------------+
| :kbd:`Control-H` | Delete character backward. |
+------------------+-------------------------------------------+
| :kbd:`Control-J` | Terminate if the window is 1 line, |
| | otherwise insert newline. |
+------------------+-------------------------------------------+
| :kbd:`Control-K` | If line is blank, delete it, otherwise |
| | clear to end of line. |
+------------------+-------------------------------------------+
| :kbd:`Control-L` | Refresh screen. |
+------------------+-------------------------------------------+
| :kbd:`Control-N` | Cursor down; move down one line. |
+------------------+-------------------------------------------+
| :kbd:`Control-O` | Insert a blank line at cursor location. |
+------------------+-------------------------------------------+
| :kbd:`Control-P` | Cursor up; move up one line. |
+------------------+-------------------------------------------+
Move operations do nothing if the cursor is at an edge where the movement
is not possible. The following synonyms are supported where possible:
+------------------------+------------------+
| Constant | Keystroke |
+========================+==================+
| :const:`KEY_LEFT` | :kbd:`Control-B` |
+------------------------+------------------+
| :const:`KEY_RIGHT` | :kbd:`Control-F` |
+------------------------+------------------+
| :const:`KEY_UP` | :kbd:`Control-P` |
+------------------------+------------------+
| :const:`KEY_DOWN` | :kbd:`Control-N` |
+------------------------+------------------+
| :const:`KEY_BACKSPACE` | :kbd:`Control-h` |
+------------------------+------------------+
All other keystrokes are treated as a command to insert the given
character and move right (with line wrapping).
.. method:: gather()
Return the window contents as a string; whether blanks in the
window are included is affected by the :attr:`stripspaces` member.
.. attribute:: stripspaces
This attribute is a flag which controls the interpretation of blanks in
the window. When it is on, trailing blanks on each line are ignored; any
cursor motion that would land the cursor on a trailing blank goes to the
end of that line instead, and trailing blanks are stripped when the window
contents are gathered.
PK %�\�`�: : * html/_sources/library/custominterp.rst.txtnu �[���
.. _custominterp:
**************************
Custom Python Interpreters
**************************
The modules described in this chapter allow writing interfaces similar to
Python's interactive interpreter. If you want a Python interpreter that
supports some special feature in addition to the Python language, you should
look at the :mod:`code` module. (The :mod:`codeop` module is lower-level, used
to support compiling a possibly-incomplete chunk of Python code.)
The full list of modules described in this chapter is:
.. toctree::
code.rst
codeop.rst
PK %�\���g` ` ' html/_sources/library/datatypes.rst.txtnu �[���
.. _datatypes:
**********
Data Types
**********
The modules described in this chapter provide a variety of specialized data
types such as dates and times, fixed-type arrays, heap queues, synchronized
queues, and sets.
Python also provides some built-in data types, in particular,
:class:`dict`, :class:`list`, :class:`set` (which along with
:class:`frozenset`, replaces the deprecated :mod:`sets` module), and
:class:`tuple`. The :class:`str` class can be used to handle binary data
and 8-bit text, and the :class:`unicode` class to handle Unicode text.
The following modules are documented in this chapter:
.. toctree::
datetime.rst
calendar.rst
collections.rst
heapq.rst
bisect.rst
array.rst
sets.rst
sched.rst
mutex.rst
queue.rst
weakref.rst
userdict.rst
types.rst
new.rst
copy.rst
pprint.rst
repr.rst
PK %�\
�v��# �# & html/_sources/library/datetime.rst.txtnu �[��� :mod:`datetime` --- Basic date and time types
=============================================
.. module:: datetime
:synopsis: Basic date and time types.
.. moduleauthor:: Tim Peters <tim@zope.com>
.. sectionauthor:: Tim Peters <tim@zope.com>
.. sectionauthor:: A.M. Kuchling <amk@amk.ca>
.. XXX what order should the types be discussed in?
.. versionadded:: 2.3
The :mod:`datetime` module supplies classes for manipulating dates and times in
both simple and complex ways. While date and time arithmetic is supported, the
focus of the implementation is on efficient attribute extraction for output
formatting and manipulation. For related functionality, see also the
:mod:`time` and :mod:`calendar` modules.
There are two kinds of date and time objects: "naive" and "aware".
An aware object has sufficient knowledge of applicable algorithmic and
political time adjustments, such as time zone and daylight saving time
information, to locate itself relative to other aware objects. An aware object
is used to represent a specific moment in time that is not open to
interpretation [#]_.
A naive object does not contain enough information to unambiguously locate
itself relative to other date/time objects. Whether a naive object represents
Coordinated Universal Time (UTC), local time, or time in some other timezone is
purely up to the program, just like it's up to the program whether a particular
number represents metres, miles, or mass. Naive objects are easy to understand
and to work with, at the cost of ignoring some aspects of reality.
For applications requiring aware objects, :class:`.datetime` and :class:`.time`
objects have an optional time zone information attribute, :attr:`!tzinfo`, that
can be set to an instance of a subclass of the abstract :class:`tzinfo` class.
These :class:`tzinfo` objects capture information about the offset from UTC
time, the time zone name, and whether Daylight Saving Time is in effect. Note
that no concrete :class:`tzinfo` classes are supplied by the :mod:`datetime`
module. Supporting timezones at whatever level of detail is required is up to
the application. The rules for time adjustment across the world are more
political than rational, and there is no standard suitable for every
application.
The :mod:`datetime` module exports the following constants:
.. data:: MINYEAR
The smallest year number allowed in a :class:`date` or :class:`.datetime` object.
:const:`MINYEAR` is ``1``.
.. data:: MAXYEAR
The largest year number allowed in a :class:`date` or :class:`.datetime` object.
:const:`MAXYEAR` is ``9999``.
.. seealso::
Module :mod:`calendar`
General calendar related functions.
Module :mod:`time`
Time access and conversions.
Available Types
---------------
.. class:: date
:noindex:
An idealized naive date, assuming the current Gregorian calendar always was, and
always will be, in effect. Attributes: :attr:`year`, :attr:`month`, and
:attr:`day`.
.. class:: time
:noindex:
An idealized time, independent of any particular day, assuming that every day
has exactly 24\*60\*60 seconds (there is no notion of "leap seconds" here).
Attributes: :attr:`hour`, :attr:`minute`, :attr:`second`, :attr:`microsecond`,
and :attr:`.tzinfo`.
.. class:: datetime
:noindex:
A combination of a date and a time. Attributes: :attr:`year`, :attr:`month`,
:attr:`day`, :attr:`hour`, :attr:`minute`, :attr:`second`, :attr:`microsecond`,
and :attr:`.tzinfo`.
.. class:: timedelta
:noindex:
A duration expressing the difference between two :class:`date`, :class:`.time`,
or :class:`.datetime` instances to microsecond resolution.
.. class:: tzinfo
:noindex:
An abstract base class for time zone information objects. These are used by the
:class:`.datetime` and :class:`.time` classes to provide a customizable notion of
time adjustment (for example, to account for time zone and/or daylight saving
time).
Objects of these types are immutable.
Objects of the :class:`date` type are always naive.
An object of type :class:`.time` or :class:`.datetime` may be naive or aware.
A :class:`.datetime` object *d* is aware if ``d.tzinfo`` is not ``None`` and
``d.tzinfo.utcoffset(d)`` does not return ``None``. If ``d.tzinfo`` is
``None``, or if ``d.tzinfo`` is not ``None`` but ``d.tzinfo.utcoffset(d)``
returns ``None``, *d* is naive. A :class:`.time` object *t* is aware
if ``t.tzinfo`` is not ``None`` and ``t.tzinfo.utcoffset(None)`` does not return
``None``. Otherwise, *t* is naive.
The distinction between naive and aware doesn't apply to :class:`timedelta`
objects.
Subclass relationships::
object
timedelta
tzinfo
time
date
datetime
.. _datetime-timedelta:
:class:`timedelta` Objects
--------------------------
A :class:`timedelta` object represents a duration, the difference between two
dates or times.
.. class:: timedelta([days[, seconds[, microseconds[, milliseconds[, minutes[, hours[, weeks]]]]]]])
All arguments are optional and default to ``0``. Arguments may be ints, longs,
or floats, and may be positive or negative.
Only *days*, *seconds* and *microseconds* are stored internally. Arguments are
converted to those units:
* A millisecond is converted to 1000 microseconds.
* A minute is converted to 60 seconds.
* An hour is converted to 3600 seconds.
* A week is converted to 7 days.
and days, seconds and microseconds are then normalized so that the
representation is unique, with
* ``0 <= microseconds < 1000000``
* ``0 <= seconds < 3600*24`` (the number of seconds in one day)
* ``-999999999 <= days <= 999999999``
If any argument is a float and there are fractional microseconds, the fractional
microseconds left over from all arguments are combined and their sum is rounded
to the nearest microsecond. If no argument is a float, the conversion and
normalization processes are exact (no information is lost).
If the normalized value of days lies outside the indicated range,
:exc:`OverflowError` is raised.
Note that normalization of negative values may be surprising at first. For
example,
>>> from datetime import timedelta
>>> d = timedelta(microseconds=-1)
>>> (d.days, d.seconds, d.microseconds)
(-1, 86399, 999999)
Class attributes are:
.. attribute:: timedelta.min
The most negative :class:`timedelta` object, ``timedelta(-999999999)``.
.. attribute:: timedelta.max
The most positive :class:`timedelta` object, ``timedelta(days=999999999,
hours=23, minutes=59, seconds=59, microseconds=999999)``.
.. attribute:: timedelta.resolution
The smallest possible difference between non-equal :class:`timedelta` objects,
``timedelta(microseconds=1)``.
Note that, because of normalization, ``timedelta.max`` > ``-timedelta.min``.
``-timedelta.max`` is not representable as a :class:`timedelta` object.
Instance attributes (read-only):
+------------------+--------------------------------------------+
| Attribute | Value |
+==================+============================================+
| ``days`` | Between -999999999 and 999999999 inclusive |
+------------------+--------------------------------------------+
| ``seconds`` | Between 0 and 86399 inclusive |
+------------------+--------------------------------------------+
| ``microseconds`` | Between 0 and 999999 inclusive |
+------------------+--------------------------------------------+
Supported operations:
.. XXX this table is too wide!
+--------------------------------+-----------------------------------------------+
| Operation | Result |
+================================+===============================================+
| ``t1 = t2 + t3`` | Sum of *t2* and *t3*. Afterwards *t1*-*t2* == |
| | *t3* and *t1*-*t3* == *t2* are true. (1) |
+--------------------------------+-----------------------------------------------+
| ``t1 = t2 - t3`` | Difference of *t2* and *t3*. Afterwards *t1* |
| | == *t2* - *t3* and *t2* == *t1* + *t3* are |
| | true. (1) |
+--------------------------------+-----------------------------------------------+
| ``t1 = t2 * i or t1 = i * t2`` | Delta multiplied by an integer or long. |
| | Afterwards *t1* // i == *t2* is true, |
| | provided ``i != 0``. |
+--------------------------------+-----------------------------------------------+
| | In general, *t1* \* i == *t1* \* (i-1) + *t1* |
| | is true. (1) |
+--------------------------------+-----------------------------------------------+
| ``t1 = t2 // i`` | The floor is computed and the remainder (if |
| | any) is thrown away. (3) |
+--------------------------------+-----------------------------------------------+
| ``+t1`` | Returns a :class:`timedelta` object with the |
| | same value. (2) |
+--------------------------------+-----------------------------------------------+
| ``-t1`` | equivalent to :class:`timedelta`\ |
| | (-*t1.days*, -*t1.seconds*, |
| | -*t1.microseconds*), and to *t1*\* -1. (1)(4) |
+--------------------------------+-----------------------------------------------+
| ``abs(t)`` | equivalent to +\ *t* when ``t.days >= 0``, and|
| | to -*t* when ``t.days < 0``. (2) |
+--------------------------------+-----------------------------------------------+
| ``str(t)`` | Returns a string in the form |
| | ``[D day[s], ][H]H:MM:SS[.UUUUUU]``, where D |
| | is negative for negative ``t``. (5) |
+--------------------------------+-----------------------------------------------+
| ``repr(t)`` | Returns a string in the form |
| | ``datetime.timedelta(D[, S[, U]])``, where D |
| | is negative for negative ``t``. (5) |
+--------------------------------+-----------------------------------------------+
Notes:
(1)
This is exact, but may overflow.
(2)
This is exact, and cannot overflow.
(3)
Division by 0 raises :exc:`ZeroDivisionError`.
(4)
-*timedelta.max* is not representable as a :class:`timedelta` object.
(5)
String representations of :class:`timedelta` objects are normalized
similarly to their internal representation. This leads to somewhat
unusual results for negative timedeltas. For example:
>>> timedelta(hours=-5)
datetime.timedelta(-1, 68400)
>>> print(_)
-1 day, 19:00:00
In addition to the operations listed above :class:`timedelta` objects support
certain additions and subtractions with :class:`date` and :class:`.datetime`
objects (see below).
Comparisons of :class:`timedelta` objects are supported with the
:class:`timedelta` object representing the smaller duration considered to be the
smaller timedelta. In order to stop mixed-type comparisons from falling back to
the default comparison by object address, when a :class:`timedelta` object is
compared to an object of a different type, :exc:`TypeError` is raised unless the
comparison is ``==`` or ``!=``. The latter cases return :const:`False` or
:const:`True`, respectively.
:class:`timedelta` objects are :term:`hashable` (usable as dictionary keys), support
efficient pickling, and in Boolean contexts, a :class:`timedelta` object is
considered to be true if and only if it isn't equal to ``timedelta(0)``.
Instance methods:
.. method:: timedelta.total_seconds()
Return the total number of seconds contained in the duration.
Equivalent to ``(td.microseconds + (td.seconds + td.days * 24 *
3600) * 10**6) / 10**6`` computed with true division enabled.
Note that for very large time intervals (greater than 270 years on
most platforms) this method will lose microsecond accuracy.
.. versionadded:: 2.7
Example usage:
>>> from datetime import timedelta
>>> year = timedelta(days=365)
>>> another_year = timedelta(weeks=40, days=84, hours=23,
... minutes=50, seconds=600) # adds up to 365 days
>>> year.total_seconds()
31536000.0
>>> year == another_year
True
>>> ten_years = 10 * year
>>> ten_years, ten_years.days // 365
(datetime.timedelta(3650), 10)
>>> nine_years = ten_years - year
>>> nine_years, nine_years.days // 365
(datetime.timedelta(3285), 9)
>>> three_years = nine_years // 3;
>>> three_years, three_years.days // 365
(datetime.timedelta(1095), 3)
>>> abs(three_years - ten_years) == 2 * three_years + year
True
.. _datetime-date:
:class:`date` Objects
---------------------
A :class:`date` object represents a date (year, month and day) in an idealized
calendar, the current Gregorian calendar indefinitely extended in both
directions. January 1 of year 1 is called day number 1, January 2 of year 1 is
called day number 2, and so on. This matches the definition of the "proleptic
Gregorian" calendar in Dershowitz and Reingold's book Calendrical Calculations,
where it's the base calendar for all computations. See the book for algorithms
for converting between proleptic Gregorian ordinals and many other calendar
systems.
.. class:: date(year, month, day)
All arguments are required. Arguments may be ints or longs, in the following
ranges:
* ``MINYEAR <= year <= MAXYEAR``
* ``1 <= month <= 12``
* ``1 <= day <= number of days in the given month and year``
If an argument outside those ranges is given, :exc:`ValueError` is raised.
Other constructors, all class methods:
.. classmethod:: date.today()
Return the current local date. This is equivalent to
``date.fromtimestamp(time.time())``.
.. classmethod:: date.fromtimestamp(timestamp)
Return the local date corresponding to the POSIX timestamp, such as is returned
by :func:`time.time`. This may raise :exc:`ValueError`, if the timestamp is out
of the range of values supported by the platform C :c:func:`localtime` function.
It's common for this to be restricted to years from 1970 through 2038. Note
that on non-POSIX systems that include leap seconds in their notion of a
timestamp, leap seconds are ignored by :meth:`fromtimestamp`.
.. classmethod:: date.fromordinal(ordinal)
Return the date corresponding to the proleptic Gregorian ordinal, where January
1 of year 1 has ordinal 1. :exc:`ValueError` is raised unless ``1 <= ordinal <=
date.max.toordinal()``. For any date *d*, ``date.fromordinal(d.toordinal()) ==
d``.
Class attributes:
.. attribute:: date.min
The earliest representable date, ``date(MINYEAR, 1, 1)``.
.. attribute:: date.max
The latest representable date, ``date(MAXYEAR, 12, 31)``.
.. attribute:: date.resolution
The smallest possible difference between non-equal date objects,
``timedelta(days=1)``.
Instance attributes (read-only):
.. attribute:: date.year
Between :const:`MINYEAR` and :const:`MAXYEAR` inclusive.
.. attribute:: date.month
Between 1 and 12 inclusive.
.. attribute:: date.day
Between 1 and the number of days in the given month of the given year.
Supported operations:
+-------------------------------+----------------------------------------------+
| Operation | Result |
+===============================+==============================================+
| ``date2 = date1 + timedelta`` | *date2* is ``timedelta.days`` days removed |
| | from *date1*. (1) |
+-------------------------------+----------------------------------------------+
| ``date2 = date1 - timedelta`` | Computes *date2* such that ``date2 + |
| | timedelta == date1``. (2) |
+-------------------------------+----------------------------------------------+
| ``timedelta = date1 - date2`` | \(3) |
+-------------------------------+----------------------------------------------+
| ``date1 < date2`` | *date1* is considered less than *date2* when |
| | *date1* precedes *date2* in time. (4) |
+-------------------------------+----------------------------------------------+
Notes:
(1)
*date2* is moved forward in time if ``timedelta.days > 0``, or backward if
``timedelta.days < 0``. Afterward ``date2 - date1 == timedelta.days``.
``timedelta.seconds`` and ``timedelta.microseconds`` are ignored.
:exc:`OverflowError` is raised if ``date2.year`` would be smaller than
:const:`MINYEAR` or larger than :const:`MAXYEAR`.
(2)
This isn't quite equivalent to date1 + (-timedelta), because -timedelta in
isolation can overflow in cases where date1 - timedelta does not.
``timedelta.seconds`` and ``timedelta.microseconds`` are ignored.
(3)
This is exact, and cannot overflow. timedelta.seconds and
timedelta.microseconds are 0, and date2 + timedelta == date1 after.
(4)
In other words, ``date1 < date2`` if and only if ``date1.toordinal() <
date2.toordinal()``. In order to stop comparison from falling back to the
default scheme of comparing object addresses, date comparison normally raises
:exc:`TypeError` if the other comparand isn't also a :class:`date` object.
However, ``NotImplemented`` is returned instead if the other comparand has a
:meth:`timetuple` attribute. This hook gives other kinds of date objects a
chance at implementing mixed-type comparison. If not, when a :class:`date`
object is compared to an object of a different type, :exc:`TypeError` is raised
unless the comparison is ``==`` or ``!=``. The latter cases return
:const:`False` or :const:`True`, respectively.
Dates can be used as dictionary keys. In Boolean contexts, all :class:`date`
objects are considered to be true.
Instance methods:
.. method:: date.replace(year, month, day)
Return a date with the same value, except for those parameters given new
values by whichever keyword arguments are specified. For example, if ``d ==
date(2002, 12, 31)``, then ``d.replace(day=26) == date(2002, 12, 26)``.
.. method:: date.timetuple()
Return a :class:`time.struct_time` such as returned by :func:`time.localtime`.
The hours, minutes and seconds are 0, and the DST flag is -1. ``d.timetuple()``
is equivalent to ``time.struct_time((d.year, d.month, d.day, 0, 0, 0,
d.weekday(), yday, -1))``, where ``yday = d.toordinal() - date(d.year, 1,
1).toordinal() + 1`` is the day number within the current year starting with
``1`` for January 1st.
.. method:: date.toordinal()
Return the proleptic Gregorian ordinal of the date, where January 1 of year 1
has ordinal 1. For any :class:`date` object *d*,
``date.fromordinal(d.toordinal()) == d``.
.. method:: date.weekday()
Return the day of the week as an integer, where Monday is 0 and Sunday is 6.
For example, ``date(2002, 12, 4).weekday() == 2``, a Wednesday. See also
:meth:`isoweekday`.
.. method:: date.isoweekday()
Return the day of the week as an integer, where Monday is 1 and Sunday is 7.
For example, ``date(2002, 12, 4).isoweekday() == 3``, a Wednesday. See also
:meth:`weekday`, :meth:`isocalendar`.
.. method:: date.isocalendar()
Return a 3-tuple, (ISO year, ISO week number, ISO weekday).
The ISO calendar is a widely used variant of the Gregorian calendar. See
https://www.staff.science.uu.nl/~gent0113/calendar/isocalendar.htm for a good
explanation.
The ISO year consists of 52 or 53 full weeks, and where a week starts on a
Monday and ends on a Sunday. The first week of an ISO year is the first
(Gregorian) calendar week of a year containing a Thursday. This is called week
number 1, and the ISO year of that Thursday is the same as its Gregorian year.
For example, 2004 begins on a Thursday, so the first week of ISO year 2004
begins on Monday, 29 Dec 2003 and ends on Sunday, 4 Jan 2004, so that
``date(2003, 12, 29).isocalendar() == (2004, 1, 1)`` and ``date(2004, 1,
4).isocalendar() == (2004, 1, 7)``.
.. method:: date.isoformat()
Return a string representing the date in ISO 8601 format, 'YYYY-MM-DD'. For
example, ``date(2002, 12, 4).isoformat() == '2002-12-04'``.
.. method:: date.__str__()
For a date *d*, ``str(d)`` is equivalent to ``d.isoformat()``.
.. method:: date.ctime()
Return a string representing the date, for example ``date(2002, 12,
4).ctime() == 'Wed Dec 4 00:00:00 2002'``. ``d.ctime()`` is equivalent to
``time.ctime(time.mktime(d.timetuple()))`` on platforms where the native C
:c:func:`ctime` function (which :func:`time.ctime` invokes, but which
:meth:`date.ctime` does not invoke) conforms to the C standard.
.. method:: date.strftime(format)
Return a string representing the date, controlled by an explicit format string.
Format codes referring to hours, minutes or seconds will see 0 values. For a
complete list of formatting directives, see section
:ref:`strftime-strptime-behavior`.
.. method:: date.__format__(format)
Same as :meth:`.date.strftime`. This makes it possible to specify a format
string for a :class:`.date` object when using :meth:`str.format`.
See section :ref:`strftime-strptime-behavior`.
Example of counting days to an event::
>>> import time
>>> from datetime import date
>>> today = date.today()
>>> today
datetime.date(2007, 12, 5)
>>> today == date.fromtimestamp(time.time())
True
>>> my_birthday = date(today.year, 6, 24)
>>> if my_birthday < today:
... my_birthday = my_birthday.replace(year=today.year + 1)
>>> my_birthday
datetime.date(2008, 6, 24)
>>> time_to_birthday = abs(my_birthday - today)
>>> time_to_birthday.days
202
Example of working with :class:`date`:
.. doctest::
>>> from datetime import date
>>> d = date.fromordinal(730920) # 730920th day after 1. 1. 0001
>>> d
datetime.date(2002, 3, 11)
>>> t = d.timetuple()
>>> for i in t: # doctest: +SKIP
... print i
2002 # year
3 # month
11 # day
0
0
0
0 # weekday (0 = Monday)
70 # 70th day in the year
-1
>>> ic = d.isocalendar()
>>> for i in ic: # doctest: +SKIP
... print i
2002 # ISO year
11 # ISO week number
1 # ISO day number ( 1 = Monday )
>>> d.isoformat()
'2002-03-11'
>>> d.strftime("%d/%m/%y")
'11/03/02'
>>> d.strftime("%A %d. %B %Y")
'Monday 11. March 2002'
>>> 'The {1} is {0:%d}, the {2} is {0:%B}.'.format(d, "day", "month")
'The day is 11, the month is March.'
.. _datetime-datetime:
:class:`.datetime` Objects
--------------------------
A :class:`.datetime` object is a single object containing all the information
from a :class:`date` object and a :class:`.time` object. Like a :class:`date`
object, :class:`.datetime` assumes the current Gregorian calendar extended in
both directions; like a time object, :class:`.datetime` assumes there are exactly
3600\*24 seconds in every day.
Constructor:
.. class:: datetime(year, month, day[, hour[, minute[, second[, microsecond[, tzinfo]]]]])
The year, month and day arguments are required. *tzinfo* may be ``None``, or an
instance of a :class:`tzinfo` subclass. The remaining arguments may be ints or
longs, in the following ranges:
* ``MINYEAR <= year <= MAXYEAR``
* ``1 <= month <= 12``
* ``1 <= day <= number of days in the given month and year``
* ``0 <= hour < 24``
* ``0 <= minute < 60``
* ``0 <= second < 60``
* ``0 <= microsecond < 1000000``
If an argument outside those ranges is given, :exc:`ValueError` is raised.
Other constructors, all class methods:
.. classmethod:: datetime.today()
Return the current local datetime, with :attr:`.tzinfo` ``None``. This is
equivalent to ``datetime.fromtimestamp(time.time())``. See also :meth:`now`,
:meth:`fromtimestamp`.
.. classmethod:: datetime.now([tz])
Return the current local date and time. If optional argument *tz* is ``None``
or not specified, this is like :meth:`today`, but, if possible, supplies more
precision than can be gotten from going through a :func:`time.time` timestamp
(for example, this may be possible on platforms supplying the C
:c:func:`gettimeofday` function).
If *tz* is not ``None``, it must be an instance of a :class:`tzinfo` subclass, and the
current date and time are converted to *tz*’s time zone. In this case the
result is equivalent to ``tz.fromutc(datetime.utcnow().replace(tzinfo=tz))``.
See also :meth:`today`, :meth:`utcnow`.
.. classmethod:: datetime.utcnow()
Return the current UTC date and time, with :attr:`.tzinfo` ``None``. This is like
:meth:`now`, but returns the current UTC date and time, as a naive
:class:`.datetime` object. See also :meth:`now`.
.. classmethod:: datetime.fromtimestamp(timestamp[, tz])
Return the local date and time corresponding to the POSIX timestamp, such as is
returned by :func:`time.time`. If optional argument *tz* is ``None`` or not
specified, the timestamp is converted to the platform's local date and time, and
the returned :class:`.datetime` object is naive.
If *tz* is not ``None``, it must be an instance of a :class:`tzinfo` subclass, and the
timestamp is converted to *tz*’s time zone. In this case the result is
equivalent to
``tz.fromutc(datetime.utcfromtimestamp(timestamp).replace(tzinfo=tz))``.
:meth:`fromtimestamp` may raise :exc:`ValueError`, if the timestamp is out of
the range of values supported by the platform C :c:func:`localtime` or
:c:func:`gmtime` functions. It's common for this to be restricted to years in
1970 through 2038. Note that on non-POSIX systems that include leap seconds in
their notion of a timestamp, leap seconds are ignored by :meth:`fromtimestamp`,
and then it's possible to have two timestamps differing by a second that yield
identical :class:`.datetime` objects. See also :meth:`utcfromtimestamp`.
.. classmethod:: datetime.utcfromtimestamp(timestamp)
Return the UTC :class:`.datetime` corresponding to the POSIX timestamp, with
:attr:`.tzinfo` ``None``. This may raise :exc:`ValueError`, if the timestamp is
out of the range of values supported by the platform C :c:func:`gmtime` function.
It's common for this to be restricted to years in 1970 through 2038. See also
:meth:`fromtimestamp`.
.. classmethod:: datetime.fromordinal(ordinal)
Return the :class:`.datetime` corresponding to the proleptic Gregorian ordinal,
where January 1 of year 1 has ordinal 1. :exc:`ValueError` is raised unless ``1
<= ordinal <= datetime.max.toordinal()``. The hour, minute, second and
microsecond of the result are all 0, and :attr:`.tzinfo` is ``None``.
.. classmethod:: datetime.combine(date, time)
Return a new :class:`.datetime` object whose date components are equal to the
given :class:`date` object's, and whose time components and :attr:`.tzinfo`
attributes are equal to the given :class:`.time` object's. For any
:class:`.datetime` object *d*,
``d == datetime.combine(d.date(), d.timetz())``. If date is a
:class:`.datetime` object, its time components and :attr:`.tzinfo` attributes
are ignored.
.. classmethod:: datetime.strptime(date_string, format)
Return a :class:`.datetime` corresponding to *date_string*, parsed according to
*format*. This is equivalent to ``datetime(*(time.strptime(date_string,
format)[0:6]))``. :exc:`ValueError` is raised if the date_string and format
can't be parsed by :func:`time.strptime` or if it returns a value which isn't a
time tuple. For a complete list of formatting directives, see section
:ref:`strftime-strptime-behavior`.
.. versionadded:: 2.5
Class attributes:
.. attribute:: datetime.min
The earliest representable :class:`.datetime`, ``datetime(MINYEAR, 1, 1,
tzinfo=None)``.
.. attribute:: datetime.max
The latest representable :class:`.datetime`, ``datetime(MAXYEAR, 12, 31, 23, 59,
59, 999999, tzinfo=None)``.
.. attribute:: datetime.resolution
The smallest possible difference between non-equal :class:`.datetime` objects,
``timedelta(microseconds=1)``.
Instance attributes (read-only):
.. attribute:: datetime.year
Between :const:`MINYEAR` and :const:`MAXYEAR` inclusive.
.. attribute:: datetime.month
Between 1 and 12 inclusive.
.. attribute:: datetime.day
Between 1 and the number of days in the given month of the given year.
.. attribute:: datetime.hour
In ``range(24)``.
.. attribute:: datetime.minute
In ``range(60)``.
.. attribute:: datetime.second
In ``range(60)``.
.. attribute:: datetime.microsecond
In ``range(1000000)``.
.. attribute:: datetime.tzinfo
The object passed as the *tzinfo* argument to the :class:`.datetime` constructor,
or ``None`` if none was passed.
Supported operations:
+---------------------------------------+--------------------------------+
| Operation | Result |
+=======================================+================================+
| ``datetime2 = datetime1 + timedelta`` | \(1) |
+---------------------------------------+--------------------------------+
| ``datetime2 = datetime1 - timedelta`` | \(2) |
+---------------------------------------+--------------------------------+
| ``timedelta = datetime1 - datetime2`` | \(3) |
+---------------------------------------+--------------------------------+
| ``datetime1 < datetime2`` | Compares :class:`.datetime` to |
| | :class:`.datetime`. (4) |
+---------------------------------------+--------------------------------+
(1)
datetime2 is a duration of timedelta removed from datetime1, moving forward in
time if ``timedelta.days`` > 0, or backward if ``timedelta.days`` < 0. The
result has the same :attr:`~.datetime.tzinfo` attribute as the input datetime, and
datetime2 - datetime1 == timedelta after. :exc:`OverflowError` is raised if
datetime2.year would be smaller than :const:`MINYEAR` or larger than
:const:`MAXYEAR`. Note that no time zone adjustments are done even if the
input is an aware object.
(2)
Computes the datetime2 such that datetime2 + timedelta == datetime1. As for
addition, the result has the same :attr:`~.datetime.tzinfo` attribute as the input
datetime, and no time zone adjustments are done even if the input is aware.
This isn't quite equivalent to datetime1 + (-timedelta), because -timedelta
in isolation can overflow in cases where datetime1 - timedelta does not.
(3)
Subtraction of a :class:`.datetime` from a :class:`.datetime` is defined only if
both operands are naive, or if both are aware. If one is aware and the other is
naive, :exc:`TypeError` is raised.
If both are naive, or both are aware and have the same :attr:`~.datetime.tzinfo` attribute,
the :attr:`~.datetime.tzinfo` attributes are ignored, and the result is a :class:`timedelta`
object *t* such that ``datetime2 + t == datetime1``. No time zone adjustments
are done in this case.
If both are aware and have different :attr:`~.datetime.tzinfo` attributes, ``a-b`` acts
as if *a* and *b* were first converted to naive UTC datetimes first. The
result is ``(a.replace(tzinfo=None) - a.utcoffset()) - (b.replace(tzinfo=None)
- b.utcoffset())`` except that the implementation never overflows.
(4)
*datetime1* is considered less than *datetime2* when *datetime1* precedes
*datetime2* in time.
If one comparand is naive and the other is aware, :exc:`TypeError` is raised.
If both comparands are aware, and have the same :attr:`~.datetime.tzinfo` attribute, the
common :attr:`~.datetime.tzinfo` attribute is ignored and the base datetimes are
compared. If both comparands are aware and have different :attr:`~.datetime.tzinfo`
attributes, the comparands are first adjusted by subtracting their UTC
offsets (obtained from ``self.utcoffset()``).
.. note::
In order to stop comparison from falling back to the default scheme of comparing
object addresses, datetime comparison normally raises :exc:`TypeError` if the
other comparand isn't also a :class:`.datetime` object. However,
``NotImplemented`` is returned instead if the other comparand has a
:meth:`timetuple` attribute. This hook gives other kinds of date objects a
chance at implementing mixed-type comparison. If not, when a :class:`.datetime`
object is compared to an object of a different type, :exc:`TypeError` is raised
unless the comparison is ``==`` or ``!=``. The latter cases return
:const:`False` or :const:`True`, respectively.
:class:`.datetime` objects can be used as dictionary keys. In Boolean contexts,
all :class:`.datetime` objects are considered to be true.
Instance methods:
.. method:: datetime.date()
Return :class:`date` object with same year, month and day.
.. method:: datetime.time()
Return :class:`.time` object with same hour, minute, second and microsecond.
:attr:`.tzinfo` is ``None``. See also method :meth:`timetz`.
.. method:: datetime.timetz()
Return :class:`.time` object with same hour, minute, second, microsecond, and
tzinfo attributes. See also method :meth:`time`.
.. method:: datetime.replace([year[, month[, day[, hour[, minute[, second[, microsecond[, tzinfo]]]]]]]])
Return a datetime with the same attributes, except for those attributes given
new values by whichever keyword arguments are specified. Note that
``tzinfo=None`` can be specified to create a naive datetime from an aware
datetime with no conversion of date and time data.
.. method:: datetime.astimezone(tz)
Return a :class:`.datetime` object with new :attr:`.tzinfo` attribute *tz*,
adjusting the date and time data so the result is the same UTC time as
*self*, but in *tz*'s local time.
*tz* must be an instance of a :class:`tzinfo` subclass, and its
:meth:`utcoffset` and :meth:`dst` methods must not return ``None``. *self* must
be aware (``self.tzinfo`` must not be ``None``, and ``self.utcoffset()`` must
not return ``None``).
If ``self.tzinfo`` is *tz*, ``self.astimezone(tz)`` is equal to *self*: no
adjustment of date or time data is performed. Else the result is local
time in time zone *tz*, representing the same UTC time as *self*: after
``astz = dt.astimezone(tz)``, ``astz - astz.utcoffset()`` will usually have
the same date and time data as ``dt - dt.utcoffset()``. The discussion
of class :class:`tzinfo` explains the cases at Daylight Saving Time transition
boundaries where this cannot be achieved (an issue only if *tz* models both
standard and daylight time).
If you merely want to attach a time zone object *tz* to a datetime *dt* without
adjustment of date and time data, use ``dt.replace(tzinfo=tz)``. If you
merely want to remove the time zone object from an aware datetime *dt* without
conversion of date and time data, use ``dt.replace(tzinfo=None)``.
Note that the default :meth:`tzinfo.fromutc` method can be overridden in a
:class:`tzinfo` subclass to affect the result returned by :meth:`astimezone`.
Ignoring error cases, :meth:`astimezone` acts like::
def astimezone(self, tz):
if self.tzinfo is tz:
return self
# Convert self to UTC, and attach the new time zone object.
utc = (self - self.utcoffset()).replace(tzinfo=tz)
# Convert from UTC to tz's local time.
return tz.fromutc(utc)
.. method:: datetime.utcoffset()
If :attr:`.tzinfo` is ``None``, returns ``None``, else returns
``self.tzinfo.utcoffset(self)``, and raises an exception if the latter doesn't
return ``None``, or a :class:`timedelta` object representing a whole number of
minutes with magnitude less than one day.
.. method:: datetime.dst()
If :attr:`.tzinfo` is ``None``, returns ``None``, else returns
``self.tzinfo.dst(self)``, and raises an exception if the latter doesn't return
``None``, or a :class:`timedelta` object representing a whole number of minutes
with magnitude less than one day.
.. method:: datetime.tzname()
If :attr:`.tzinfo` is ``None``, returns ``None``, else returns
``self.tzinfo.tzname(self)``, raises an exception if the latter doesn't return
``None`` or a string object,
.. method:: datetime.timetuple()
Return a :class:`time.struct_time` such as returned by :func:`time.localtime`.
``d.timetuple()`` is equivalent to ``time.struct_time((d.year, d.month, d.day,
d.hour, d.minute, d.second, d.weekday(), yday, dst))``, where ``yday =
d.toordinal() - date(d.year, 1, 1).toordinal() + 1`` is the day number within
the current year starting with ``1`` for January 1st. The :attr:`tm_isdst` flag
of the result is set according to the :meth:`dst` method: :attr:`.tzinfo` is
``None`` or :meth:`dst` returns ``None``, :attr:`tm_isdst` is set to ``-1``;
else if :meth:`dst` returns a non-zero value, :attr:`tm_isdst` is set to ``1``;
else :attr:`tm_isdst` is set to ``0``.
.. method:: datetime.utctimetuple()
If :class:`.datetime` instance *d* is naive, this is the same as
``d.timetuple()`` except that :attr:`tm_isdst` is forced to 0 regardless of what
``d.dst()`` returns. DST is never in effect for a UTC time.
If *d* is aware, *d* is normalized to UTC time, by subtracting
``d.utcoffset()``, and a :class:`time.struct_time` for the normalized time is
returned. :attr:`tm_isdst` is forced to 0. Note that the result's
:attr:`tm_year` member may be :const:`MINYEAR`\ -1 or :const:`MAXYEAR`\ +1, if
*d*.year was ``MINYEAR`` or ``MAXYEAR`` and UTC adjustment spills over a year
boundary.
.. method:: datetime.toordinal()
Return the proleptic Gregorian ordinal of the date. The same as
``self.date().toordinal()``.
.. method:: datetime.weekday()
Return the day of the week as an integer, where Monday is 0 and Sunday is 6.
The same as ``self.date().weekday()``. See also :meth:`isoweekday`.
.. method:: datetime.isoweekday()
Return the day of the week as an integer, where Monday is 1 and Sunday is 7.
The same as ``self.date().isoweekday()``. See also :meth:`weekday`,
:meth:`isocalendar`.
.. method:: datetime.isocalendar()
Return a 3-tuple, (ISO year, ISO week number, ISO weekday). The same as
``self.date().isocalendar()``.
.. method:: datetime.isoformat([sep])
Return a string representing the date and time in ISO 8601 format,
YYYY-MM-DDTHH:MM:SS.mmmmmm or, if :attr:`microsecond` is 0,
YYYY-MM-DDTHH:MM:SS
If :meth:`utcoffset` does not return ``None``, a 6-character string is
appended, giving the UTC offset in (signed) hours and minutes:
YYYY-MM-DDTHH:MM:SS.mmmmmm+HH:MM or, if :attr:`microsecond` is 0
YYYY-MM-DDTHH:MM:SS+HH:MM
The optional argument *sep* (default ``'T'``) is a one-character separator,
placed between the date and time portions of the result. For example,
>>> from datetime import tzinfo, timedelta, datetime
>>> class TZ(tzinfo):
... def utcoffset(self, dt): return timedelta(minutes=-399)
...
>>> datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ')
'2002-12-25 00:00:00-06:39'
.. method:: datetime.__str__()
For a :class:`.datetime` instance *d*, ``str(d)`` is equivalent to
``d.isoformat(' ')``.
.. method:: datetime.ctime()
Return a string representing the date and time, for example ``datetime(2002, 12,
4, 20, 30, 40).ctime() == 'Wed Dec 4 20:30:40 2002'``. ``d.ctime()`` is
equivalent to ``time.ctime(time.mktime(d.timetuple()))`` on platforms where the
native C :c:func:`ctime` function (which :func:`time.ctime` invokes, but which
:meth:`datetime.ctime` does not invoke) conforms to the C standard.
.. method:: datetime.strftime(format)
Return a string representing the date and time, controlled by an explicit format
string. For a complete list of formatting directives, see section
:ref:`strftime-strptime-behavior`.
.. method:: datetime.__format__(format)
Same as :meth:`.datetime.strftime`. This makes it possible to specify a format
string for a :class:`.datetime` object when using :meth:`str.format`.
See section :ref:`strftime-strptime-behavior`.
Examples of working with datetime objects:
.. doctest::
>>> from datetime import datetime, date, time
>>> # Using datetime.combine()
>>> d = date(2005, 7, 14)
>>> t = time(12, 30)
>>> datetime.combine(d, t)
datetime.datetime(2005, 7, 14, 12, 30)
>>> # Using datetime.now() or datetime.utcnow()
>>> datetime.now() # doctest: +SKIP
datetime.datetime(2007, 12, 6, 16, 29, 43, 79043) # GMT +1
>>> datetime.utcnow() # doctest: +SKIP
datetime.datetime(2007, 12, 6, 15, 29, 43, 79060)
>>> # Using datetime.strptime()
>>> dt = datetime.strptime("21/11/06 16:30", "%d/%m/%y %H:%M")
>>> dt
datetime.datetime(2006, 11, 21, 16, 30)
>>> # Using datetime.timetuple() to get tuple of all attributes
>>> tt = dt.timetuple()
>>> for it in tt: # doctest: +SKIP
... print it
...
2006 # year
11 # month
21 # day
16 # hour
30 # minute
0 # second
1 # weekday (0 = Monday)
325 # number of days since 1st January
-1 # dst - method tzinfo.dst() returned None
>>> # Date in ISO format
>>> ic = dt.isocalendar()
>>> for it in ic: # doctest: +SKIP
... print it
...
2006 # ISO year
47 # ISO week
2 # ISO weekday
>>> # Formatting datetime
>>> dt.strftime("%A, %d. %B %Y %I:%M%p")
'Tuesday, 21. November 2006 04:30PM'
>>> 'The {1} is {0:%d}, the {2} is {0:%B}, the {3} is {0:%I:%M%p}.'.format(dt, "day", "month", "time")
'The day is 21, the month is November, the time is 04:30PM.'
Using datetime with tzinfo:
>>> from datetime import timedelta, datetime, tzinfo
>>> class GMT1(tzinfo):
... def utcoffset(self, dt):
... return timedelta(hours=1) + self.dst(dt)
... def dst(self, dt):
... # DST starts last Sunday in March
... d = datetime(dt.year, 4, 1) # ends last Sunday in October
... self.dston = d - timedelta(days=d.weekday() + 1)
... d = datetime(dt.year, 11, 1)
... self.dstoff = d - timedelta(days=d.weekday() + 1)
... if self.dston <= dt.replace(tzinfo=None) < self.dstoff:
... return timedelta(hours=1)
... else:
... return timedelta(0)
... def tzname(self,dt):
... return "GMT +1"
...
>>> class GMT2(tzinfo):
... def utcoffset(self, dt):
... return timedelta(hours=2) + self.dst(dt)
... def dst(self, dt):
... d = datetime(dt.year, 4, 1)
... self.dston = d - timedelta(days=d.weekday() + 1)
... d = datetime(dt.year, 11, 1)
... self.dstoff = d - timedelta(days=d.weekday() + 1)
... if self.dston <= dt.replace(tzinfo=None) < self.dstoff:
... return timedelta(hours=1)
... else:
... return timedelta(0)
... def tzname(self,dt):
... return "GMT +2"
...
>>> gmt1 = GMT1()
>>> # Daylight Saving Time
>>> dt1 = datetime(2006, 11, 21, 16, 30, tzinfo=gmt1)
>>> dt1.dst()
datetime.timedelta(0)
>>> dt1.utcoffset()
datetime.timedelta(0, 3600)
>>> dt2 = datetime(2006, 6, 14, 13, 0, tzinfo=gmt1)
>>> dt2.dst()
datetime.timedelta(0, 3600)
>>> dt2.utcoffset()
datetime.timedelta(0, 7200)
>>> # Convert datetime to another time zone
>>> dt3 = dt2.astimezone(GMT2())
>>> dt3 # doctest: +ELLIPSIS
datetime.datetime(2006, 6, 14, 14, 0, tzinfo=<GMT2 object at 0x...>)
>>> dt2 # doctest: +ELLIPSIS
datetime.datetime(2006, 6, 14, 13, 0, tzinfo=<GMT1 object at 0x...>)
>>> dt2.utctimetuple() == dt3.utctimetuple()
True
.. _datetime-time:
:class:`.time` Objects
----------------------
A time object represents a (local) time of day, independent of any particular
day, and subject to adjustment via a :class:`tzinfo` object.
.. class:: time([hour[, minute[, second[, microsecond[, tzinfo]]]]])
All arguments are optional. *tzinfo* may be ``None``, or an instance of a
:class:`tzinfo` subclass. The remaining arguments may be ints or longs, in the
following ranges:
* ``0 <= hour < 24``
* ``0 <= minute < 60``
* ``0 <= second < 60``
* ``0 <= microsecond < 1000000``.
If an argument outside those ranges is given, :exc:`ValueError` is raised. All
default to ``0`` except *tzinfo*, which defaults to :const:`None`.
Class attributes:
.. attribute:: time.min
The earliest representable :class:`.time`, ``time(0, 0, 0, 0)``.
.. attribute:: time.max
The latest representable :class:`.time`, ``time(23, 59, 59, 999999)``.
.. attribute:: time.resolution
The smallest possible difference between non-equal :class:`.time` objects,
``timedelta(microseconds=1)``, although note that arithmetic on
:class:`.time` objects is not supported.
Instance attributes (read-only):
.. attribute:: time.hour
In ``range(24)``.
.. attribute:: time.minute
In ``range(60)``.
.. attribute:: time.second
In ``range(60)``.
.. attribute:: time.microsecond
In ``range(1000000)``.
.. attribute:: time.tzinfo
The object passed as the tzinfo argument to the :class:`.time` constructor, or
``None`` if none was passed.
Supported operations:
* comparison of :class:`.time` to :class:`.time`, where *a* is considered less
than *b* when *a* precedes *b* in time. If one comparand is naive and the other
is aware, :exc:`TypeError` is raised. If both comparands are aware, and have
the same :attr:`~time.tzinfo` attribute, the common :attr:`~time.tzinfo` attribute is
ignored and the base times are compared. If both comparands are aware and
have different :attr:`~time.tzinfo` attributes, the comparands are first adjusted by
subtracting their UTC offsets (obtained from ``self.utcoffset()``). In order
to stop mixed-type comparisons from falling back to the default comparison by
object address, when a :class:`.time` object is compared to an object of a
different type, :exc:`TypeError` is raised unless the comparison is ``==`` or
``!=``. The latter cases return :const:`False` or :const:`True`, respectively.
* hash, use as dict key
* efficient pickling
* in Boolean contexts, a :class:`.time` object is considered to be true if and
only if, after converting it to minutes and subtracting :meth:`utcoffset` (or
``0`` if that's ``None``), the result is non-zero.
Instance methods:
.. method:: time.replace([hour[, minute[, second[, microsecond[, tzinfo]]]]])
Return a :class:`.time` with the same value, except for those attributes given
new values by whichever keyword arguments are specified. Note that
``tzinfo=None`` can be specified to create a naive :class:`.time` from an
aware :class:`.time`, without conversion of the time data.
.. method:: time.isoformat()
Return a string representing the time in ISO 8601 format, HH:MM:SS.mmmmmm or, if
self.microsecond is 0, HH:MM:SS If :meth:`utcoffset` does not return ``None``, a
6-character string is appended, giving the UTC offset in (signed) hours and
minutes: HH:MM:SS.mmmmmm+HH:MM or, if self.microsecond is 0, HH:MM:SS+HH:MM
.. method:: time.__str__()
For a time *t*, ``str(t)`` is equivalent to ``t.isoformat()``.
.. method:: time.strftime(format)
Return a string representing the time, controlled by an explicit format string.
For a complete list of formatting directives, see section
:ref:`strftime-strptime-behavior`.
.. method:: time.__format__(format)
Same as :meth:`.time.strftime`. This makes it possible to specify a format string
for a :class:`.time` object when using :meth:`str.format`.
See section :ref:`strftime-strptime-behavior`.
.. method:: time.utcoffset()
If :attr:`.tzinfo` is ``None``, returns ``None``, else returns
``self.tzinfo.utcoffset(None)``, and raises an exception if the latter doesn't
return ``None`` or a :class:`timedelta` object representing a whole number of
minutes with magnitude less than one day.
.. method:: time.dst()
If :attr:`.tzinfo` is ``None``, returns ``None``, else returns
``self.tzinfo.dst(None)``, and raises an exception if the latter doesn't return
``None``, or a :class:`timedelta` object representing a whole number of minutes
with magnitude less than one day.
.. method:: time.tzname()
If :attr:`.tzinfo` is ``None``, returns ``None``, else returns
``self.tzinfo.tzname(None)``, or raises an exception if the latter doesn't
return ``None`` or a string object.
Example:
>>> from datetime import time, tzinfo, timedelta
>>> class GMT1(tzinfo):
... def utcoffset(self, dt):
... return timedelta(hours=1)
... def dst(self, dt):
... return timedelta(0)
... def tzname(self,dt):
... return "Europe/Prague"
...
>>> t = time(12, 10, 30, tzinfo=GMT1())
>>> t # doctest: +ELLIPSIS
datetime.time(12, 10, 30, tzinfo=<GMT1 object at 0x...>)
>>> gmt = GMT1()
>>> t.isoformat()
'12:10:30+01:00'
>>> t.dst()
datetime.timedelta(0)
>>> t.tzname()
'Europe/Prague'
>>> t.strftime("%H:%M:%S %Z")
'12:10:30 Europe/Prague'
>>> 'The {} is {:%H:%M}.'.format("time", t)
'The time is 12:10.'
.. _datetime-tzinfo:
:class:`tzinfo` Objects
-----------------------
.. class:: tzinfo()
This is an abstract base class, meaning that this class should not be
instantiated directly. You need to derive a concrete subclass, and (at least)
supply implementations of the standard :class:`tzinfo` methods needed by the
:class:`.datetime` methods you use. The :mod:`datetime` module does not supply
any concrete subclasses of :class:`tzinfo`.
An instance of (a concrete subclass of) :class:`tzinfo` can be passed to the
constructors for :class:`.datetime` and :class:`.time` objects. The latter objects
view their attributes as being in local time, and the :class:`tzinfo` object
supports methods revealing offset of local time from UTC, the name of the time
zone, and DST offset, all relative to a date or time object passed to them.
Special requirement for pickling: A :class:`tzinfo` subclass must have an
:meth:`__init__` method that can be called with no arguments, else it can be
pickled but possibly not unpickled again. This is a technical requirement that
may be relaxed in the future.
A concrete subclass of :class:`tzinfo` may need to implement the following
methods. Exactly which methods are needed depends on the uses made of aware
:mod:`datetime` objects. If in doubt, simply implement all of them.
.. method:: tzinfo.utcoffset(self, dt)
Return offset of local time from UTC, in minutes east of UTC. If local time is
west of UTC, this should be negative. Note that this is intended to be the
total offset from UTC; for example, if a :class:`tzinfo` object represents both
time zone and DST adjustments, :meth:`utcoffset` should return their sum. If
the UTC offset isn't known, return ``None``. Else the value returned must be a
:class:`timedelta` object specifying a whole number of minutes in the range
-1439 to 1439 inclusive (1440 = 24\*60; the magnitude of the offset must be less
than one day). Most implementations of :meth:`utcoffset` will probably look
like one of these two::
return CONSTANT # fixed-offset class
return CONSTANT + self.dst(dt) # daylight-aware class
If :meth:`utcoffset` does not return ``None``, :meth:`dst` should not return
``None`` either.
The default implementation of :meth:`utcoffset` raises
:exc:`NotImplementedError`.
.. method:: tzinfo.dst(self, dt)
Return the daylight saving time (DST) adjustment, in minutes east of UTC, or
``None`` if DST information isn't known. Return ``timedelta(0)`` if DST is not
in effect. If DST is in effect, return the offset as a :class:`timedelta` object
(see :meth:`utcoffset` for details). Note that DST offset, if applicable, has
already been added to the UTC offset returned by :meth:`utcoffset`, so there's
no need to consult :meth:`dst` unless you're interested in obtaining DST info
separately. For example, :meth:`datetime.timetuple` calls its :attr:`~.datetime.tzinfo`
attribute's :meth:`dst` method to determine how the :attr:`tm_isdst` flag
should be set, and :meth:`tzinfo.fromutc` calls :meth:`dst` to account for
DST changes when crossing time zones.
An instance *tz* of a :class:`tzinfo` subclass that models both standard and
daylight times must be consistent in this sense:
``tz.utcoffset(dt) - tz.dst(dt)``
must return the same result for every :class:`.datetime` *dt* with ``dt.tzinfo ==
tz`` For sane :class:`tzinfo` subclasses, this expression yields the time
zone's "standard offset", which should not depend on the date or the time, but
only on geographic location. The implementation of :meth:`datetime.astimezone`
relies on this, but cannot detect violations; it's the programmer's
responsibility to ensure it. If a :class:`tzinfo` subclass cannot guarantee
this, it may be able to override the default implementation of
:meth:`tzinfo.fromutc` to work correctly with :meth:`astimezone` regardless.
Most implementations of :meth:`dst` will probably look like one of these two::
def dst(self, dt):
# a fixed-offset class: doesn't account for DST
return timedelta(0)
or ::
def dst(self, dt):
# Code to set dston and dstoff to the time zone's DST
# transition times based on the input dt.year, and expressed
# in standard local time. Then
if dston <= dt.replace(tzinfo=None) < dstoff:
return timedelta(hours=1)
else:
return timedelta(0)
The default implementation of :meth:`dst` raises :exc:`NotImplementedError`.
.. method:: tzinfo.tzname(self, dt)
Return the time zone name corresponding to the :class:`.datetime` object *dt*, as
a string. Nothing about string names is defined by the :mod:`datetime` module,
and there's no requirement that it mean anything in particular. For example,
"GMT", "UTC", "-500", "-5:00", "EDT", "US/Eastern", "America/New York" are all
valid replies. Return ``None`` if a string name isn't known. Note that this is
a method rather than a fixed string primarily because some :class:`tzinfo`
subclasses will wish to return different names depending on the specific value
of *dt* passed, especially if the :class:`tzinfo` class is accounting for
daylight time.
The default implementation of :meth:`tzname` raises :exc:`NotImplementedError`.
These methods are called by a :class:`.datetime` or :class:`.time` object, in
response to their methods of the same names. A :class:`.datetime` object passes
itself as the argument, and a :class:`.time` object passes ``None`` as the
argument. A :class:`tzinfo` subclass's methods should therefore be prepared to
accept a *dt* argument of ``None``, or of class :class:`.datetime`.
When ``None`` is passed, it's up to the class designer to decide the best
response. For example, returning ``None`` is appropriate if the class wishes to
say that time objects don't participate in the :class:`tzinfo` protocols. It
may be more useful for ``utcoffset(None)`` to return the standard UTC offset, as
there is no other convention for discovering the standard offset.
When a :class:`.datetime` object is passed in response to a :class:`.datetime`
method, ``dt.tzinfo`` is the same object as *self*. :class:`tzinfo` methods can
rely on this, unless user code calls :class:`tzinfo` methods directly. The
intent is that the :class:`tzinfo` methods interpret *dt* as being in local
time, and not need worry about objects in other timezones.
There is one more :class:`tzinfo` method that a subclass may wish to override:
.. method:: tzinfo.fromutc(self, dt)
This is called from the default :class:`datetime.astimezone()`
implementation. When called from that, ``dt.tzinfo`` is *self*, and *dt*'s
date and time data are to be viewed as expressing a UTC time. The purpose
of :meth:`fromutc` is to adjust the date and time data, returning an
equivalent datetime in *self*'s local time.
Most :class:`tzinfo` subclasses should be able to inherit the default
:meth:`fromutc` implementation without problems. It's strong enough to handle
fixed-offset time zones, and time zones accounting for both standard and
daylight time, and the latter even if the DST transition times differ in
different years. An example of a time zone the default :meth:`fromutc`
implementation may not handle correctly in all cases is one where the standard
offset (from UTC) depends on the specific date and time passed, which can happen
for political reasons. The default implementations of :meth:`astimezone` and
:meth:`fromutc` may not produce the result you want if the result is one of the
hours straddling the moment the standard offset changes.
Skipping code for error cases, the default :meth:`fromutc` implementation acts
like::
def fromutc(self, dt):
# raise ValueError error if dt.tzinfo is not self
dtoff = dt.utcoffset()
dtdst = dt.dst()
# raise ValueError if dtoff is None or dtdst is None
delta = dtoff - dtdst # this is self's standard offset
if delta:
dt += delta # convert to standard local time
dtdst = dt.dst()
# raise ValueError if dtdst is None
if dtdst:
return dt + dtdst
else:
return dt
Example :class:`tzinfo` classes:
.. literalinclude:: ../includes/tzinfo-examples.py
Note that there are unavoidable subtleties twice per year in a :class:`tzinfo`
subclass accounting for both standard and daylight time, at the DST transition
points. For concreteness, consider US Eastern (UTC -0500), where EDT begins the
minute after 1:59 (EST) on the second Sunday in March, and ends the minute after
1:59 (EDT) on the first Sunday in November::
UTC 3:MM 4:MM 5:MM 6:MM 7:MM 8:MM
EST 22:MM 23:MM 0:MM 1:MM 2:MM 3:MM
EDT 23:MM 0:MM 1:MM 2:MM 3:MM 4:MM
start 22:MM 23:MM 0:MM 1:MM 3:MM 4:MM
end 23:MM 0:MM 1:MM 1:MM 2:MM 3:MM
When DST starts (the "start" line), the local wall clock leaps from 1:59 to
3:00. A wall time of the form 2:MM doesn't really make sense on that day, so
``astimezone(Eastern)`` won't deliver a result with ``hour == 2`` on the day DST
begins. In order for :meth:`astimezone` to make this guarantee, the
:meth:`rzinfo.dst` method must consider times in the "missing hour" (2:MM for
Eastern) to be in daylight time.
When DST ends (the "end" line), there's a potentially worse problem: there's an
hour that can't be spelled unambiguously in local wall time: the last hour of
daylight time. In Eastern, that's times of the form 5:MM UTC on the day
daylight time ends. The local wall clock leaps from 1:59 (daylight time) back
to 1:00 (standard time) again. Local times of the form 1:MM are ambiguous.
:meth:`astimezone` mimics the local clock's behavior by mapping two adjacent UTC
hours into the same local hour then. In the Eastern example, UTC times of the
form 5:MM and 6:MM both map to 1:MM when converted to Eastern. In order for
:meth:`astimezone` to make this guarantee, the :meth:`tzinfo.dst` method must
consider times in the "repeated hour" to be in standard time. This is easily
arranged, as in the example, by expressing DST switch times in the time zone's
standard local time.
Applications that can't bear such ambiguities should avoid using hybrid
:class:`tzinfo` subclasses; there are no ambiguities when using UTC, or any
other fixed-offset :class:`tzinfo` subclass (such as a class representing only
EST (fixed offset -5 hours), or only EDT (fixed offset -4 hours)).
.. seealso::
`pytz <https://pypi.org/project/pytz/>`_
The standard library has no :class:`tzinfo` instances, but
there exists a third-party library which brings the *IANA timezone
database* (also known as the Olson database) to Python: *pytz*.
*pytz* contains up-to-date information and its usage is recommended.
`IANA timezone database <https://www.iana.org/time-zones>`_
The Time Zone Database (often called tz or zoneinfo) contains code and
data that represent the history of local time for many representative
locations around the globe. It is updated periodically to reflect changes
made by political bodies to time zone boundaries, UTC offsets, and
daylight-saving rules.
.. _strftime-strptime-behavior:
:meth:`strftime` and :meth:`strptime` Behavior
----------------------------------------------
:class:`date`, :class:`.datetime`, and :class:`.time` objects all support a
``strftime(format)`` method, to create a string representing the time under the
control of an explicit format string. Broadly speaking, ``d.strftime(fmt)``
acts like the :mod:`time` module's ``time.strftime(fmt, d.timetuple())``
although not all objects support a :meth:`timetuple` method.
Conversely, the :meth:`datetime.strptime` class method creates a
:class:`.datetime` object from a string representing a date and time and a
corresponding format string. ``datetime.strptime(date_string, format)`` is
equivalent to ``datetime(*(time.strptime(date_string, format)[0:6]))``, except
when the format includes sub-second components or timezone offset information,
which are supported in ``datetime.strptime`` but are discarded by ``time.strptime``.
For :class:`.time` objects, the format codes for year, month, and day should not
be used, as time objects have no such values. If they're used anyway, ``1900``
is substituted for the year, and ``1`` for the month and day.
For :class:`date` objects, the format codes for hours, minutes, seconds, and
microseconds should not be used, as :class:`date` objects have no such
values. If they're used anyway, ``0`` is substituted for them.
The full set of format codes supported varies across platforms, because Python
calls the platform C library's :func:`strftime` function, and platform
variations are common. To see the full set of format codes supported on your
platform, consult the :manpage:`strftime(3)` documentation.
For the same reason, handling of format strings containing Unicode code points
that can't be represented in the charset of the current locale is also
platform-dependent. On some platforms such code points are preserved intact in
the output, while on others ``strftime`` may raise :exc:`UnicodeError` or return
an empty string instead.
The following is a list of all the format codes that the C standard (1989
version) requires, and these work on all platforms with a standard C
implementation. Note that the 1999 version of the C standard added additional
format codes.
The exact range of years for which :meth:`strftime` works also varies across
platforms. Regardless of platform, years before 1900 cannot be used.
+-----------+--------------------------------+------------------------+-------+
| Directive | Meaning | Example | Notes |
+===========+================================+========================+=======+
| ``%a`` | Weekday as locale's || Sun, Mon, ..., Sat | \(1) |
| | abbreviated name. | (en_US); | |
| | || So, Mo, ..., Sa | |
| | | (de_DE) | |
+-----------+--------------------------------+------------------------+-------+
| ``%A`` | Weekday as locale's full name. || Sunday, Monday, ..., | \(1) |
| | | Saturday (en_US); | |
| | || Sonntag, Montag, ..., | |
| | | Samstag (de_DE) | |
+-----------+--------------------------------+------------------------+-------+
| ``%w`` | Weekday as a decimal number, | 0, 1, ..., 6 | |
| | where 0 is Sunday and 6 is | | |
| | Saturday. | | |
+-----------+--------------------------------+------------------------+-------+
| ``%d`` | Day of the month as a | 01, 02, ..., 31 | |
| | zero-padded decimal number. | | |
+-----------+--------------------------------+------------------------+-------+
| ``%b`` | Month as locale's abbreviated || Jan, Feb, ..., Dec | \(1) |
| | name. | (en_US); | |
| | || Jan, Feb, ..., Dez | |
| | | (de_DE) | |
+-----------+--------------------------------+------------------------+-------+
| ``%B`` | Month as locale's full name. || January, February, | \(1) |
| | | ..., December (en_US);| |
| | || Januar, Februar, ..., | |
| | | Dezember (de_DE) | |
+-----------+--------------------------------+------------------------+-------+
| ``%m`` | Month as a zero-padded | 01, 02, ..., 12 | |
| | decimal number. | | |
+-----------+--------------------------------+------------------------+-------+
| ``%y`` | Year without century as a | 00, 01, ..., 99 | |
| | zero-padded decimal number. | | |
+-----------+--------------------------------+------------------------+-------+
| ``%Y`` | Year with century as a decimal | 1970, 1988, 2001, 2013 | |
| | number. | | |
+-----------+--------------------------------+------------------------+-------+
| ``%H`` | Hour (24-hour clock) as a | 00, 01, ..., 23 | |
| | zero-padded decimal number. | | |
+-----------+--------------------------------+------------------------+-------+
| ``%I`` | Hour (12-hour clock) as a | 01, 02, ..., 12 | |
| | zero-padded decimal number. | | |
+-----------+--------------------------------+------------------------+-------+
| ``%p`` | Locale's equivalent of either || AM, PM (en_US); | \(1), |
| | AM or PM. || am, pm (de_DE) | \(2) |
+-----------+--------------------------------+------------------------+-------+
| ``%M`` | Minute as a zero-padded | 00, 01, ..., 59 | |
| | decimal number. | | |
+-----------+--------------------------------+------------------------+-------+
| ``%S`` | Second as a zero-padded | 00, 01, ..., 59 | \(3) |
| | decimal number. | | |
+-----------+--------------------------------+------------------------+-------+
| ``%f`` | Microsecond as a decimal | 000000, 000001, ..., | \(4) |
| | number, zero-padded on the | 999999 | |
| | left. | | |
+-----------+--------------------------------+------------------------+-------+
| ``%z`` | UTC offset in the form +HHMM | (empty), +0000, -0400, | \(5) |
| | or -HHMM (empty string if the | +1030 | |
| | the object is naive). | | |
+-----------+--------------------------------+------------------------+-------+
| ``%Z`` | Time zone name (empty string | (empty), UTC, EST, CST | |
| | if the object is naive). | | |
+-----------+--------------------------------+------------------------+-------+
| ``%j`` | Day of the year as a | 001, 002, ..., 366 | |
| | zero-padded decimal number. | | |
+-----------+--------------------------------+------------------------+-------+
| ``%U`` | Week number of the year | 00, 01, ..., 53 | \(6) |
| | (Sunday as the first day of | | |
| | the week) as a zero padded | | |
| | decimal number. All days in a | | |
| | new year preceding the first | | |
| | Sunday are considered to be in | | |
| | week 0. | | |
+-----------+--------------------------------+------------------------+-------+
| ``%W`` | Week number of the year | 00, 01, ..., 53 | \(6) |
| | (Monday as the first day of | | |
| | the week) as a decimal number. | | |
| | All days in a new year | | |
| | preceding the first Monday | | |
| | are considered to be in | | |
| | week 0. | | |
+-----------+--------------------------------+------------------------+-------+
| ``%c`` | Locale's appropriate date and || Tue Aug 16 21:30:00 | \(1) |
| | time representation. | 1988 (en_US); | |
| | || Di 16 Aug 21:30:00 | |
| | | 1988 (de_DE) | |
+-----------+--------------------------------+------------------------+-------+
| ``%x`` | Locale's appropriate date || 08/16/88 (None); | \(1) |
| | representation. || 08/16/1988 (en_US); | |
| | || 16.08.1988 (de_DE) | |
+-----------+--------------------------------+------------------------+-------+
| ``%X`` | Locale's appropriate time || 21:30:00 (en_US); | \(1) |
| | representation. || 21:30:00 (de_DE) | |
+-----------+--------------------------------+------------------------+-------+
| ``%%`` | A literal ``'%'`` character. | % | |
+-----------+--------------------------------+------------------------+-------+
Notes:
(1)
Because the format depends on the current locale, care should be taken when
making assumptions about the output value. Field orderings will vary (for
example, "month/day/year" versus "day/month/year"), and the output may
contain Unicode characters encoded using the locale's default encoding (for
example, if the current locale is ``ja_JP``, the default encoding could be
any one of ``eucJP``, ``SJIS``, or ``utf-8``; use :meth:`locale.getlocale`
to determine the current locale's encoding).
(2)
When used with the :meth:`strptime` method, the ``%p`` directive only affects
the output hour field if the ``%I`` directive is used to parse the hour.
(3)
Unlike the :mod:`time` module, the :mod:`datetime` module does not support
leap seconds.
(4)
``%f`` is an extension to the set of format characters in the C standard
(but implemented separately in datetime objects, and therefore always
available). When used with the :meth:`strptime` method, the ``%f``
directive accepts from one to six digits and zero pads on the right.
.. versionadded:: 2.6
(5)
For a naive object, the ``%z`` and ``%Z`` format codes are replaced by empty
strings.
For an aware object:
``%z``
:meth:`utcoffset` is transformed into a 5-character string of the form
+HHMM or -HHMM, where HH is a 2-digit string giving the number of UTC
offset hours, and MM is a 2-digit string giving the number of UTC offset
minutes. For example, if :meth:`utcoffset` returns
``timedelta(hours=-3, minutes=-30)``, ``%z`` is replaced with the string
``'-0330'``.
``%Z``
If :meth:`tzname` returns ``None``, ``%Z`` is replaced by an empty
string. Otherwise ``%Z`` is replaced by the returned value, which must
be a string.
(6)
When used with the :meth:`strptime` method, ``%U`` and ``%W`` are only used
in calculations when the day of the week and the year are specified.
.. rubric:: Footnotes
.. [#] If, that is, we ignore the effects of Relativity
PK %�\�/�Y $ html/_sources/library/dbhash.rst.txtnu �[��� :mod:`dbhash` --- DBM-style interface to the BSD database library
=================================================================
.. module:: dbhash
:synopsis: DBM-style interface to the BSD database library.
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
.. deprecated:: 2.6
The :mod:`dbhash` module has been removed in Python 3.
.. index:: module: bsddb
The :mod:`dbhash` module provides a function to open databases using the BSD
``db`` library. This module mirrors the interface of the other Python database
modules that provide access to DBM-style databases. The :mod:`bsddb` module is
required to use :mod:`dbhash`.
This module provides an exception and a function:
.. exception:: error
Exception raised on database errors other than :exc:`KeyError`. It is a synonym
for :exc:`bsddb.error`.
.. function:: open(path[, flag[, mode]])
Open a ``db`` database and return the database object. The *path* argument is
the name of the database file.
The *flag* argument can be:
+---------+-------------------------------------------+
| Value | Meaning |
+=========+===========================================+
| ``'r'`` | Open existing database for reading only |
| | (default) |
+---------+-------------------------------------------+
| ``'w'`` | Open existing database for reading and |
| | writing |
+---------+-------------------------------------------+
| ``'c'`` | Open database for reading and writing, |
| | creating it if it doesn't exist |
+---------+-------------------------------------------+
| ``'n'`` | Always create a new, empty database, open |
| | for reading and writing |
+---------+-------------------------------------------+
For platforms on which the BSD ``db`` library supports locking, an ``'l'``
can be appended to indicate that locking should be used.
The optional *mode* parameter is used to indicate the Unix permission bits that
should be set if a new database must be created; this will be masked by the
current umask value for the process.
.. seealso::
Module :mod:`anydbm`
Generic interface to ``dbm``\ -style databases.
Module :mod:`bsddb`
Lower-level interface to the BSD ``db`` library.
Module :mod:`whichdb`
Utility module used to determine the type of an existing database.
.. _dbhash-objects:
Database Objects
----------------
The database objects returned by :func:`.open` provide the methods common to all
the DBM-style databases and mapping objects. The following methods are
available in addition to the standard methods.
.. method:: dbhash.first()
It's possible to loop over every key/value pair in the database using this
method and the :meth:`!next` method. The traversal is ordered by the databases
internal hash values, and won't be sorted by the key values. This method
returns the starting key.
.. method:: dbhash.last()
Return the last key/value pair in a database traversal. This may be used to
begin a reverse-order traversal; see :meth:`previous`.
.. method:: dbhash.next()
Returns the key next key/value pair in a database traversal. The following code
prints every key in the database ``db``, without having to create a list in
memory that contains them all::
print db.first()
for i in xrange(1, len(db)):
print db.next()
.. method:: dbhash.previous()
Returns the previous key/value pair in a forward-traversal of the database. In
conjunction with :meth:`last`, this may be used to implement a reverse-order
traversal.
.. method:: dbhash.sync()
This method forces any unwritten data to be written to the disk.
PK %�\�J��- - ! html/_sources/library/dbm.rst.txtnu �[��� :mod:`dbm` --- Simple "database" interface
==========================================
.. module:: dbm
:platform: Unix
:synopsis: The standard "database" interface, based on ndbm.
.. note::
The :mod:`dbm` module has been renamed to :mod:`dbm.ndbm` in Python 3. The
:term:`2to3` tool will automatically adapt imports when converting your
sources to Python 3.
The :mod:`dbm` module provides an interface to the Unix "(n)dbm" library. Dbm
objects behave like mappings (dictionaries), except that keys and values are
always strings. Printing a dbm object doesn't print the keys and values, and the
:meth:`items` and :meth:`values` methods are not supported.
This module can be used with the "classic" ndbm interface, the BSD DB
compatibility interface, or the GNU GDBM compatibility interface. On Unix, the
:program:`configure` script will attempt to locate the appropriate header file
to simplify building this module.
The module defines the following:
.. exception:: error
Raised on dbm-specific errors, such as I/O errors. :exc:`KeyError` is raised for
general mapping errors like specifying an incorrect key.
.. data:: library
Name of the ``ndbm`` implementation library used.
.. function:: open(filename[, flag[, mode]])
Open a dbm database and return a dbm object. The *filename* argument is the
name of the database file (without the :file:`.dir` or :file:`.pag` extensions;
note that the BSD DB implementation of the interface will append the extension
:file:`.db` and only create one file).
The optional *flag* argument must be one of these values:
+---------+-------------------------------------------+
| Value | Meaning |
+=========+===========================================+
| ``'r'`` | Open existing database for reading only |
| | (default) |
+---------+-------------------------------------------+
| ``'w'`` | Open existing database for reading and |
| | writing |
+---------+-------------------------------------------+
| ``'c'`` | Open database for reading and writing, |
| | creating it if it doesn't exist |
+---------+-------------------------------------------+
| ``'n'`` | Always create a new, empty database, open |
| | for reading and writing |
+---------+-------------------------------------------+
The optional *mode* argument is the Unix mode of the file, used only when the
database has to be created. It defaults to octal ``0666`` (and will be
modified by the prevailing umask).
In addition to the dictionary-like methods, ``dbm`` objects
provide the following method:
.. function:: close()
Close the ``dbm`` database.
.. seealso::
Module :mod:`anydbm`
Generic interface to ``dbm``\ -style databases.
Module :mod:`gdbm`
Similar interface to the GNU GDBM library.
Module :mod:`whichdb`
Utility module used to determine the type of an existing database.
PK %�\�J��� � # html/_sources/library/debug.rst.txtnu �[��� ***********************
Debugging and Profiling
***********************
These libraries help you with Python development: the debugger enables you to
step through code, analyze stack frames and set breakpoints etc., and the
profilers run code and give you a detailed breakdown of execution times,
allowing you to identify bottlenecks in your programs.
.. toctree::
bdb.rst
pdb.rst
profile.rst
hotshot.rst
timeit.rst
trace.rstPK %�\�� % html/_sources/library/decimal.rst.txtnu �[���
:mod:`decimal` --- Decimal fixed point and floating point arithmetic
====================================================================
.. module:: decimal
:synopsis: Implementation of the General Decimal Arithmetic Specification.
.. moduleauthor:: Eric Price <eprice at tjhsst.edu>
.. moduleauthor:: Facundo Batista <facundo at taniquetil.com.ar>
.. moduleauthor:: Raymond Hettinger <python at rcn.com>
.. moduleauthor:: Aahz <aahz at pobox.com>
.. moduleauthor:: Tim Peters <tim.one at comcast.net>
.. sectionauthor:: Raymond D. Hettinger <python at rcn.com>
.. versionadded:: 2.4
.. import modules for testing inline doctests with the Sphinx doctest builder
.. testsetup:: *
import decimal
import math
from decimal import *
# make sure each group gets a fresh context
setcontext(Context())
The :mod:`decimal` module provides support for decimal floating point
arithmetic. It offers several advantages over the :class:`float` datatype:
* Decimal "is based on a floating-point model which was designed with people
in mind, and necessarily has a paramount guiding principle -- computers must
provide an arithmetic that works in the same way as the arithmetic that
people learn at school." -- excerpt from the decimal arithmetic specification.
* Decimal numbers can be represented exactly. In contrast, numbers like
:const:`1.1` and :const:`2.2` do not have exact representations in binary
floating point. End users typically would not expect ``1.1 + 2.2`` to display
as :const:`3.3000000000000003` as it does with binary floating point.
* The exactness carries over into arithmetic. In decimal floating point, ``0.1
+ 0.1 + 0.1 - 0.3`` is exactly equal to zero. In binary floating point, the result
is :const:`5.5511151231257827e-017`. While near to zero, the differences
prevent reliable equality testing and differences can accumulate. For this
reason, decimal is preferred in accounting applications which have strict
equality invariants.
* The decimal module incorporates a notion of significant places so that ``1.30
+ 1.20`` is :const:`2.50`. The trailing zero is kept to indicate significance.
This is the customary presentation for monetary applications. For
multiplication, the "schoolbook" approach uses all the figures in the
multiplicands. For instance, ``1.3 * 1.2`` gives :const:`1.56` while ``1.30 *
1.20`` gives :const:`1.5600`.
* Unlike hardware based binary floating point, the decimal module has a user
alterable precision (defaulting to 28 places) which can be as large as needed for
a given problem:
>>> from decimal import *
>>> getcontext().prec = 6
>>> Decimal(1) / Decimal(7)
Decimal('0.142857')
>>> getcontext().prec = 28
>>> Decimal(1) / Decimal(7)
Decimal('0.1428571428571428571428571429')
* Both binary and decimal floating point are implemented in terms of published
standards. While the built-in float type exposes only a modest portion of its
capabilities, the decimal module exposes all required parts of the standard.
When needed, the programmer has full control over rounding and signal handling.
This includes an option to enforce exact arithmetic by using exceptions
to block any inexact operations.
* The decimal module was designed to support "without prejudice, both exact
unrounded decimal arithmetic (sometimes called fixed-point arithmetic)
and rounded floating-point arithmetic." -- excerpt from the decimal
arithmetic specification.
The module design is centered around three concepts: the decimal number, the
context for arithmetic, and signals.
A decimal number is immutable. It has a sign, coefficient digits, and an
exponent. To preserve significance, the coefficient digits do not truncate
trailing zeros. Decimals also include special values such as
:const:`Infinity`, :const:`-Infinity`, and :const:`NaN`. The standard also
differentiates :const:`-0` from :const:`+0`.
The context for arithmetic is an environment specifying precision, rounding
rules, limits on exponents, flags indicating the results of operations, and trap
enablers which determine whether signals are treated as exceptions. Rounding
options include :const:`ROUND_CEILING`, :const:`ROUND_DOWN`,
:const:`ROUND_FLOOR`, :const:`ROUND_HALF_DOWN`, :const:`ROUND_HALF_EVEN`,
:const:`ROUND_HALF_UP`, :const:`ROUND_UP`, and :const:`ROUND_05UP`.
Signals are groups of exceptional conditions arising during the course of
computation. Depending on the needs of the application, signals may be ignored,
considered as informational, or treated as exceptions. The signals in the
decimal module are: :const:`Clamped`, :const:`InvalidOperation`,
:const:`DivisionByZero`, :const:`Inexact`, :const:`Rounded`, :const:`Subnormal`,
:const:`Overflow`, and :const:`Underflow`.
For each signal there is a flag and a trap enabler. When a signal is
encountered, its flag is set to one, then, if the trap enabler is
set to one, an exception is raised. Flags are sticky, so the user needs to
reset them before monitoring a calculation.
.. seealso::
* IBM's General Decimal Arithmetic Specification, `The General Decimal Arithmetic
Specification <http://speleotrove.com/decimal/>`_.
.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
.. _decimal-tutorial:
Quick-start Tutorial
--------------------
The usual start to using decimals is importing the module, viewing the current
context with :func:`getcontext` and, if necessary, setting new values for
precision, rounding, or enabled traps::
>>> from decimal import *
>>> getcontext()
Context(prec=28, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999,
capitals=1, flags=[], traps=[Overflow, DivisionByZero,
InvalidOperation])
>>> getcontext().prec = 7 # Set a new precision
Decimal instances can be constructed from integers, strings, floats, or tuples.
Construction from an integer or a float performs an exact conversion of the
value of that integer or float. Decimal numbers include special values such as
:const:`NaN` which stands for "Not a number", positive and negative
:const:`Infinity`, and :const:`-0`.
>>> getcontext().prec = 28
>>> Decimal(10)
Decimal('10')
>>> Decimal('3.14')
Decimal('3.14')
>>> Decimal(3.14)
Decimal('3.140000000000000124344978758017532527446746826171875')
>>> Decimal((0, (3, 1, 4), -2))
Decimal('3.14')
>>> Decimal(str(2.0 ** 0.5))
Decimal('1.41421356237')
>>> Decimal(2) ** Decimal('0.5')
Decimal('1.414213562373095048801688724')
>>> Decimal('NaN')
Decimal('NaN')
>>> Decimal('-Infinity')
Decimal('-Infinity')
The significance of a new Decimal is determined solely by the number of digits
input. Context precision and rounding only come into play during arithmetic
operations.
.. doctest:: newcontext
>>> getcontext().prec = 6
>>> Decimal('3.0')
Decimal('3.0')
>>> Decimal('3.1415926535')
Decimal('3.1415926535')
>>> Decimal('3.1415926535') + Decimal('2.7182818285')
Decimal('5.85987')
>>> getcontext().rounding = ROUND_UP
>>> Decimal('3.1415926535') + Decimal('2.7182818285')
Decimal('5.85988')
Decimals interact well with much of the rest of Python. Here is a small decimal
floating point flying circus:
.. doctest::
:options: +NORMALIZE_WHITESPACE
>>> data = map(Decimal, '1.34 1.87 3.45 2.35 1.00 0.03 9.25'.split())
>>> max(data)
Decimal('9.25')
>>> min(data)
Decimal('0.03')
>>> sorted(data)
[Decimal('0.03'), Decimal('1.00'), Decimal('1.34'), Decimal('1.87'),
Decimal('2.35'), Decimal('3.45'), Decimal('9.25')]
>>> sum(data)
Decimal('19.29')
>>> a,b,c = data[:3]
>>> str(a)
'1.34'
>>> float(a)
1.34
>>> round(a, 1) # round() first converts to binary floating point
1.3
>>> int(a)
1
>>> a * 5
Decimal('6.70')
>>> a * b
Decimal('2.5058')
>>> c % a
Decimal('0.77')
And some mathematical functions are also available to Decimal:
>>> getcontext().prec = 28
>>> Decimal(2).sqrt()
Decimal('1.414213562373095048801688724')
>>> Decimal(1).exp()
Decimal('2.718281828459045235360287471')
>>> Decimal('10').ln()
Decimal('2.302585092994045684017991455')
>>> Decimal('10').log10()
Decimal('1')
The :meth:`quantize` method rounds a number to a fixed exponent. This method is
useful for monetary applications that often round results to a fixed number of
places:
>>> Decimal('7.325').quantize(Decimal('.01'), rounding=ROUND_DOWN)
Decimal('7.32')
>>> Decimal('7.325').quantize(Decimal('1.'), rounding=ROUND_UP)
Decimal('8')
As shown above, the :func:`getcontext` function accesses the current context and
allows the settings to be changed. This approach meets the needs of most
applications.
For more advanced work, it may be useful to create alternate contexts using the
Context() constructor. To make an alternate active, use the :func:`setcontext`
function.
In accordance with the standard, the :mod:`decimal` module provides two ready to
use standard contexts, :const:`BasicContext` and :const:`ExtendedContext`. The
former is especially useful for debugging because many of the traps are
enabled:
.. doctest:: newcontext
:options: +NORMALIZE_WHITESPACE
>>> myothercontext = Context(prec=60, rounding=ROUND_HALF_DOWN)
>>> setcontext(myothercontext)
>>> Decimal(1) / Decimal(7)
Decimal('0.142857142857142857142857142857142857142857142857142857142857')
>>> ExtendedContext
Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999,
capitals=1, flags=[], traps=[])
>>> setcontext(ExtendedContext)
>>> Decimal(1) / Decimal(7)
Decimal('0.142857143')
>>> Decimal(42) / Decimal(0)
Decimal('Infinity')
>>> setcontext(BasicContext)
>>> Decimal(42) / Decimal(0)
Traceback (most recent call last):
File "<pyshell#143>", line 1, in -toplevel-
Decimal(42) / Decimal(0)
DivisionByZero: x / 0
Contexts also have signal flags for monitoring exceptional conditions
encountered during computations. The flags remain set until explicitly cleared,
so it is best to clear the flags before each set of monitored computations by
using the :meth:`clear_flags` method. ::
>>> setcontext(ExtendedContext)
>>> getcontext().clear_flags()
>>> Decimal(355) / Decimal(113)
Decimal('3.14159292')
>>> getcontext()
Context(prec=9, rounding=ROUND_HALF_EVEN, Emin=-999999999, Emax=999999999,
capitals=1, flags=[Rounded, Inexact], traps=[])
The *flags* entry shows that the rational approximation to :const:`Pi` was
rounded (digits beyond the context precision were thrown away) and that the
result is inexact (some of the discarded digits were non-zero).
Individual traps are set using the dictionary in the :attr:`traps` field of a
context:
.. doctest:: newcontext
>>> setcontext(ExtendedContext)
>>> Decimal(1) / Decimal(0)
Decimal('Infinity')
>>> getcontext().traps[DivisionByZero] = 1
>>> Decimal(1) / Decimal(0)
Traceback (most recent call last):
File "<pyshell#112>", line 1, in -toplevel-
Decimal(1) / Decimal(0)
DivisionByZero: x / 0
Most programs adjust the current context only once, at the beginning of the
program. And, in many applications, data is converted to :class:`Decimal` with
a single cast inside a loop. With context set and decimals created, the bulk of
the program manipulates the data no differently than with other Python numeric
types.
.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
.. _decimal-decimal:
Decimal objects
---------------
.. class:: Decimal([value [, context]])
Construct a new :class:`Decimal` object based from *value*.
*value* can be an integer, string, tuple, :class:`float`, or another :class:`Decimal`
object. If no *value* is given, returns ``Decimal('0')``. If *value* is a
string, it should conform to the decimal numeric string syntax after leading
and trailing whitespace characters are removed::
sign ::= '+' | '-'
digit ::= '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9'
indicator ::= 'e' | 'E'
digits ::= digit [digit]...
decimal-part ::= digits '.' [digits] | ['.'] digits
exponent-part ::= indicator [sign] digits
infinity ::= 'Infinity' | 'Inf'
nan ::= 'NaN' [digits] | 'sNaN' [digits]
numeric-value ::= decimal-part [exponent-part] | infinity
numeric-string ::= [sign] numeric-value | [sign] nan
If *value* is a unicode string then other Unicode decimal digits
are also permitted where ``digit`` appears above. These include
decimal digits from various other alphabets (for example,
Arabic-Indic and Devanāgarī digits) along with the fullwidth digits
``u'\uff10'`` through ``u'\uff19'``.
If *value* is a :class:`tuple`, it should have three components, a sign
(:const:`0` for positive or :const:`1` for negative), a :class:`tuple` of
digits, and an integer exponent. For example, ``Decimal((0, (1, 4, 1, 4), -3))``
returns ``Decimal('1.414')``.
If *value* is a :class:`float`, the binary floating point value is losslessly
converted to its exact decimal equivalent. This conversion can often require
53 or more digits of precision. For example, ``Decimal(float('1.1'))``
converts to
``Decimal('1.100000000000000088817841970012523233890533447265625')``.
The *context* precision does not affect how many digits are stored. That is
determined exclusively by the number of digits in *value*. For example,
``Decimal('3.00000')`` records all five zeros even if the context precision is
only three.
The purpose of the *context* argument is determining what to do if *value* is a
malformed string. If the context traps :const:`InvalidOperation`, an exception
is raised; otherwise, the constructor returns a new Decimal with the value of
:const:`NaN`.
Once constructed, :class:`Decimal` objects are immutable.
.. versionchanged:: 2.6
leading and trailing whitespace characters are permitted when
creating a Decimal instance from a string.
.. versionchanged:: 2.7
The argument to the constructor is now permitted to be a :class:`float` instance.
Decimal floating point objects share many properties with the other built-in
numeric types such as :class:`float` and :class:`int`. All of the usual math
operations and special methods apply. Likewise, decimal objects can be
copied, pickled, printed, used as dictionary keys, used as set elements,
compared, sorted, and coerced to another type (such as :class:`float` or
:class:`long`).
There are some small differences between arithmetic on Decimal objects and
arithmetic on integers and floats. When the remainder operator ``%`` is
applied to Decimal objects, the sign of the result is the sign of the
*dividend* rather than the sign of the divisor::
>>> (-7) % 4
1
>>> Decimal(-7) % Decimal(4)
Decimal('-3')
The integer division operator ``//`` behaves analogously, returning the
integer part of the true quotient (truncating towards zero) rather than its
floor, so as to preserve the usual identity ``x == (x // y) * y + x % y``::
>>> -7 // 4
-2
>>> Decimal(-7) // Decimal(4)
Decimal('-1')
The ``%`` and ``//`` operators implement the ``remainder`` and
``divide-integer`` operations (respectively) as described in the
specification.
Decimal objects cannot generally be combined with floats in
arithmetic operations: an attempt to add a :class:`Decimal` to a
:class:`float`, for example, will raise a :exc:`TypeError`.
There's one exception to this rule: it's possible to use Python's
comparison operators to compare a :class:`float` instance ``x``
with a :class:`Decimal` instance ``y``. Without this exception,
comparisons between :class:`Decimal` and :class:`float` instances
would follow the general rules for comparing objects of different
types described in the :ref:`expressions` section of the reference
manual, leading to confusing results.
.. versionchanged:: 2.7
A comparison between a :class:`float` instance ``x`` and a
:class:`Decimal` instance ``y`` now returns a result based on
the values of ``x`` and ``y``. In earlier versions ``x < y``
returned the same (arbitrary) result for any :class:`Decimal`
instance ``x`` and any :class:`float` instance ``y``.
In addition to the standard numeric properties, decimal floating point
objects also have a number of specialized methods:
.. method:: adjusted()
Return the adjusted exponent after shifting out the coefficient's
rightmost digits until only the lead digit remains:
``Decimal('321e+5').adjusted()`` returns seven. Used for determining the
position of the most significant digit with respect to the decimal point.
.. method:: as_tuple()
Return a :term:`named tuple` representation of the number:
``DecimalTuple(sign, digits, exponent)``.
.. versionchanged:: 2.6
Use a named tuple.
.. method:: canonical()
Return the canonical encoding of the argument. Currently, the encoding of
a :class:`Decimal` instance is always canonical, so this operation returns
its argument unchanged.
.. versionadded:: 2.6
.. method:: compare(other[, context])
Compare the values of two Decimal instances. This operation behaves in
the same way as the usual comparison method :meth:`__cmp__`, except that
:meth:`compare` returns a Decimal instance rather than an integer, and if
either operand is a NaN then the result is a NaN::
a or b is a NaN ==> Decimal('NaN')
a < b ==> Decimal('-1')
a == b ==> Decimal('0')
a > b ==> Decimal('1')
.. method:: compare_signal(other[, context])
This operation is identical to the :meth:`compare` method, except that all
NaNs signal. That is, if neither operand is a signaling NaN then any
quiet NaN operand is treated as though it were a signaling NaN.
.. versionadded:: 2.6
.. method:: compare_total(other)
Compare two operands using their abstract representation rather than their
numerical value. Similar to the :meth:`compare` method, but the result
gives a total ordering on :class:`Decimal` instances. Two
:class:`Decimal` instances with the same numeric value but different
representations compare unequal in this ordering:
>>> Decimal('12.0').compare_total(Decimal('12'))
Decimal('-1')
Quiet and signaling NaNs are also included in the total ordering. The
result of this function is ``Decimal('0')`` if both operands have the same
representation, ``Decimal('-1')`` if the first operand is lower in the
total order than the second, and ``Decimal('1')`` if the first operand is
higher in the total order than the second operand. See the specification
for details of the total order.
.. versionadded:: 2.6
.. method:: compare_total_mag(other)
Compare two operands using their abstract representation rather than their
value as in :meth:`compare_total`, but ignoring the sign of each operand.
``x.compare_total_mag(y)`` is equivalent to
``x.copy_abs().compare_total(y.copy_abs())``.
.. versionadded:: 2.6
.. method:: conjugate()
Just returns self, this method is only to comply with the Decimal
Specification.
.. versionadded:: 2.6
.. method:: copy_abs()
Return the absolute value of the argument. This operation is unaffected
by the context and is quiet: no flags are changed and no rounding is
performed.
.. versionadded:: 2.6
.. method:: copy_negate()
Return the negation of the argument. This operation is unaffected by the
context and is quiet: no flags are changed and no rounding is performed.
.. versionadded:: 2.6
.. method:: copy_sign(other)
Return a copy of the first operand with the sign set to be the same as the
sign of the second operand. For example:
>>> Decimal('2.3').copy_sign(Decimal('-1.5'))
Decimal('-2.3')
This operation is unaffected by the context and is quiet: no flags are
changed and no rounding is performed.
.. versionadded:: 2.6
.. method:: exp([context])
Return the value of the (natural) exponential function ``e**x`` at the
given number. The result is correctly rounded using the
:const:`ROUND_HALF_EVEN` rounding mode.
>>> Decimal(1).exp()
Decimal('2.718281828459045235360287471')
>>> Decimal(321).exp()
Decimal('2.561702493119680037517373933E+139')
.. versionadded:: 2.6
.. method:: from_float(f)
Classmethod that converts a float to a decimal number, exactly.
Note `Decimal.from_float(0.1)` is not the same as `Decimal('0.1')`.
Since 0.1 is not exactly representable in binary floating point, the
value is stored as the nearest representable value which is
`0x1.999999999999ap-4`. That equivalent value in decimal is
`0.1000000000000000055511151231257827021181583404541015625`.
.. note:: From Python 2.7 onwards, a :class:`Decimal` instance
can also be constructed directly from a :class:`float`.
.. doctest::
>>> Decimal.from_float(0.1)
Decimal('0.1000000000000000055511151231257827021181583404541015625')
>>> Decimal.from_float(float('nan'))
Decimal('NaN')
>>> Decimal.from_float(float('inf'))
Decimal('Infinity')
>>> Decimal.from_float(float('-inf'))
Decimal('-Infinity')
.. versionadded:: 2.7
.. method:: fma(other, third[, context])
Fused multiply-add. Return self*other+third with no rounding of the
intermediate product self*other.
>>> Decimal(2).fma(3, 5)
Decimal('11')
.. versionadded:: 2.6
.. method:: is_canonical()
Return :const:`True` if the argument is canonical and :const:`False`
otherwise. Currently, a :class:`Decimal` instance is always canonical, so
this operation always returns :const:`True`.
.. versionadded:: 2.6
.. method:: is_finite()
Return :const:`True` if the argument is a finite number, and
:const:`False` if the argument is an infinity or a NaN.
.. versionadded:: 2.6
.. method:: is_infinite()
Return :const:`True` if the argument is either positive or negative
infinity and :const:`False` otherwise.
.. versionadded:: 2.6
.. method:: is_nan()
Return :const:`True` if the argument is a (quiet or signaling) NaN and
:const:`False` otherwise.
.. versionadded:: 2.6
.. method:: is_normal()
Return :const:`True` if the argument is a *normal* finite non-zero
number with an adjusted exponent greater than or equal to *Emin*.
Return :const:`False` if the argument is zero, subnormal, infinite or a
NaN. Note, the term *normal* is used here in a different sense with
the :meth:`normalize` method which is used to create canonical values.
.. versionadded:: 2.6
.. method:: is_qnan()
Return :const:`True` if the argument is a quiet NaN, and
:const:`False` otherwise.
.. versionadded:: 2.6
.. method:: is_signed()
Return :const:`True` if the argument has a negative sign and
:const:`False` otherwise. Note that zeros and NaNs can both carry signs.
.. versionadded:: 2.6
.. method:: is_snan()
Return :const:`True` if the argument is a signaling NaN and :const:`False`
otherwise.
.. versionadded:: 2.6
.. method:: is_subnormal()
Return :const:`True` if the argument is subnormal, and :const:`False`
otherwise. A number is subnormal is if it is nonzero, finite, and has an
adjusted exponent less than *Emin*.
.. versionadded:: 2.6
.. method:: is_zero()
Return :const:`True` if the argument is a (positive or negative) zero and
:const:`False` otherwise.
.. versionadded:: 2.6
.. method:: ln([context])
Return the natural (base e) logarithm of the operand. The result is
correctly rounded using the :const:`ROUND_HALF_EVEN` rounding mode.
.. versionadded:: 2.6
.. method:: log10([context])
Return the base ten logarithm of the operand. The result is correctly
rounded using the :const:`ROUND_HALF_EVEN` rounding mode.
.. versionadded:: 2.6
.. method:: logb([context])
For a nonzero number, return the adjusted exponent of its operand as a
:class:`Decimal` instance. If the operand is a zero then
``Decimal('-Infinity')`` is returned and the :const:`DivisionByZero` flag
is raised. If the operand is an infinity then ``Decimal('Infinity')`` is
returned.
.. versionadded:: 2.6
.. method:: logical_and(other[, context])
:meth:`logical_and` is a logical operation which takes two *logical
operands* (see :ref:`logical_operands_label`). The result is the
digit-wise ``and`` of the two operands.
.. versionadded:: 2.6
.. method:: logical_invert([context])
:meth:`logical_invert` is a logical operation. The
result is the digit-wise inversion of the operand.
.. versionadded:: 2.6
.. method:: logical_or(other[, context])
:meth:`logical_or` is a logical operation which takes two *logical
operands* (see :ref:`logical_operands_label`). The result is the
digit-wise ``or`` of the two operands.
.. versionadded:: 2.6
.. method:: logical_xor(other[, context])
:meth:`logical_xor` is a logical operation which takes two *logical
operands* (see :ref:`logical_operands_label`). The result is the
digit-wise exclusive or of the two operands.
.. versionadded:: 2.6
.. method:: max(other[, context])
Like ``max(self, other)`` except that the context rounding rule is applied
before returning and that :const:`NaN` values are either signaled or
ignored (depending on the context and whether they are signaling or
quiet).
.. method:: max_mag(other[, context])
Similar to the :meth:`.max` method, but the comparison is done using the
absolute values of the operands.
.. versionadded:: 2.6
.. method:: min(other[, context])
Like ``min(self, other)`` except that the context rounding rule is applied
before returning and that :const:`NaN` values are either signaled or
ignored (depending on the context and whether they are signaling or
quiet).
.. method:: min_mag(other[, context])
Similar to the :meth:`.min` method, but the comparison is done using the
absolute values of the operands.
.. versionadded:: 2.6
.. method:: next_minus([context])
Return the largest number representable in the given context (or in the
current thread's context if no context is given) that is smaller than the
given operand.
.. versionadded:: 2.6
.. method:: next_plus([context])
Return the smallest number representable in the given context (or in the
current thread's context if no context is given) that is larger than the
given operand.
.. versionadded:: 2.6
.. method:: next_toward(other[, context])
If the two operands are unequal, return the number closest to the first
operand in the direction of the second operand. If both operands are
numerically equal, return a copy of the first operand with the sign set to
be the same as the sign of the second operand.
.. versionadded:: 2.6
.. method:: normalize([context])
Normalize the number by stripping the rightmost trailing zeros and
converting any result equal to :const:`Decimal('0')` to
:const:`Decimal('0e0')`. Used for producing canonical values for attributes
of an equivalence class. For example, ``Decimal('32.100')`` and
``Decimal('0.321000e+2')`` both normalize to the equivalent value
``Decimal('32.1')``.
.. method:: number_class([context])
Return a string describing the *class* of the operand. The returned value
is one of the following ten strings.
* ``"-Infinity"``, indicating that the operand is negative infinity.
* ``"-Normal"``, indicating that the operand is a negative normal number.
* ``"-Subnormal"``, indicating that the operand is negative and subnormal.
* ``"-Zero"``, indicating that the operand is a negative zero.
* ``"+Zero"``, indicating that the operand is a positive zero.
* ``"+Subnormal"``, indicating that the operand is positive and subnormal.
* ``"+Normal"``, indicating that the operand is a positive normal number.
* ``"+Infinity"``, indicating that the operand is positive infinity.
* ``"NaN"``, indicating that the operand is a quiet NaN (Not a Number).
* ``"sNaN"``, indicating that the operand is a signaling NaN.
.. versionadded:: 2.6
.. method:: quantize(exp[, rounding[, context[, watchexp]]])
Return a value equal to the first operand after rounding and having the
exponent of the second operand.
>>> Decimal('1.41421356').quantize(Decimal('1.000'))
Decimal('1.414')
Unlike other operations, if the length of the coefficient after the
quantize operation would be greater than precision, then an
:const:`InvalidOperation` is signaled. This guarantees that, unless there
is an error condition, the quantized exponent is always equal to that of
the right-hand operand.
Also unlike other operations, quantize never signals Underflow, even if
the result is subnormal and inexact.
If the exponent of the second operand is larger than that of the first
then rounding may be necessary. In this case, the rounding mode is
determined by the ``rounding`` argument if given, else by the given
``context`` argument; if neither argument is given the rounding mode of
the current thread's context is used.
If *watchexp* is set (default), then an error is returned whenever the
resulting exponent is greater than :attr:`Emax` or less than
:attr:`Etiny`.
.. method:: radix()
Return ``Decimal(10)``, the radix (base) in which the :class:`Decimal`
class does all its arithmetic. Included for compatibility with the
specification.
.. versionadded:: 2.6
.. method:: remainder_near(other[, context])
Return the remainder from dividing *self* by *other*. This differs from
``self % other`` in that the sign of the remainder is chosen so as to
minimize its absolute value. More precisely, the return value is
``self - n * other`` where ``n`` is the integer nearest to the exact
value of ``self / other``, and if two integers are equally near then the
even one is chosen.
If the result is zero then its sign will be the sign of *self*.
>>> Decimal(18).remainder_near(Decimal(10))
Decimal('-2')
>>> Decimal(25).remainder_near(Decimal(10))
Decimal('5')
>>> Decimal(35).remainder_near(Decimal(10))
Decimal('-5')
.. method:: rotate(other[, context])
Return the result of rotating the digits of the first operand by an amount
specified by the second operand. The second operand must be an integer in
the range -precision through precision. The absolute value of the second
operand gives the number of places to rotate. If the second operand is
positive then rotation is to the left; otherwise rotation is to the right.
The coefficient of the first operand is padded on the left with zeros to
length precision if necessary. The sign and exponent of the first operand
are unchanged.
.. versionadded:: 2.6
.. method:: same_quantum(other[, context])
Test whether self and other have the same exponent or whether both are
:const:`NaN`.
.. method:: scaleb(other[, context])
Return the first operand with exponent adjusted by the second.
Equivalently, return the first operand multiplied by ``10**other``. The
second operand must be an integer.
.. versionadded:: 2.6
.. method:: shift(other[, context])
Return the result of shifting the digits of the first operand by an amount
specified by the second operand. The second operand must be an integer in
the range -precision through precision. The absolute value of the second
operand gives the number of places to shift. If the second operand is
positive then the shift is to the left; otherwise the shift is to the
right. Digits shifted into the coefficient are zeros. The sign and
exponent of the first operand are unchanged.
.. versionadded:: 2.6
.. method:: sqrt([context])
Return the square root of the argument to full precision.
.. method:: to_eng_string([context])
Convert to a string, using engineering notation if an exponent is needed.
Engineering notation has an exponent which is a multiple of 3. This
can leave up to 3 digits to the left of the decimal place and may
require the addition of either one or two trailing zeros.
For example, this converts ``Decimal('123E+1')`` to ``Decimal('1.23E+3')``.
.. method:: to_integral([rounding[, context]])
Identical to the :meth:`to_integral_value` method. The ``to_integral``
name has been kept for compatibility with older versions.
.. method:: to_integral_exact([rounding[, context]])
Round to the nearest integer, signaling :const:`Inexact` or
:const:`Rounded` as appropriate if rounding occurs. The rounding mode is
determined by the ``rounding`` parameter if given, else by the given
``context``. If neither parameter is given then the rounding mode of the
current context is used.
.. versionadded:: 2.6
.. method:: to_integral_value([rounding[, context]])
Round to the nearest integer without signaling :const:`Inexact` or
:const:`Rounded`. If given, applies *rounding*; otherwise, uses the
rounding method in either the supplied *context* or the current context.
.. versionchanged:: 2.6
renamed from ``to_integral`` to ``to_integral_value``. The old name
remains valid for compatibility.
.. _logical_operands_label:
Logical operands
^^^^^^^^^^^^^^^^
The :meth:`logical_and`, :meth:`logical_invert`, :meth:`logical_or`,
and :meth:`logical_xor` methods expect their arguments to be *logical
operands*. A *logical operand* is a :class:`Decimal` instance whose
exponent and sign are both zero, and whose digits are all either
:const:`0` or :const:`1`.
.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
.. _decimal-context:
Context objects
---------------
Contexts are environments for arithmetic operations. They govern precision, set
rules for rounding, determine which signals are treated as exceptions, and limit
the range for exponents.
Each thread has its own current context which is accessed or changed using the
:func:`getcontext` and :func:`setcontext` functions:
.. function:: getcontext()
Return the current context for the active thread.
.. function:: setcontext(c)
Set the current context for the active thread to *c*.
Beginning with Python 2.5, you can also use the :keyword:`with` statement and
the :func:`localcontext` function to temporarily change the active context.
.. function:: localcontext([c])
Return a context manager that will set the current context for the active thread
to a copy of *c* on entry to the with-statement and restore the previous context
when exiting the with-statement. If no context is specified, a copy of the
current context is used.
.. versionadded:: 2.5
For example, the following code sets the current decimal precision to 42 places,
performs a calculation, and then automatically restores the previous context::
from decimal import localcontext
with localcontext() as ctx:
ctx.prec = 42 # Perform a high precision calculation
s = calculate_something()
s = +s # Round the final result back to the default precision
with localcontext(BasicContext): # temporarily use the BasicContext
print Decimal(1) / Decimal(7)
print Decimal(355) / Decimal(113)
New contexts can also be created using the :class:`Context` constructor
described below. In addition, the module provides three pre-made contexts:
.. class:: BasicContext
This is a standard context defined by the General Decimal Arithmetic
Specification. Precision is set to nine. Rounding is set to
:const:`ROUND_HALF_UP`. All flags are cleared. All traps are enabled (treated
as exceptions) except :const:`Inexact`, :const:`Rounded`, and
:const:`Subnormal`.
Because many of the traps are enabled, this context is useful for debugging.
.. class:: ExtendedContext
This is a standard context defined by the General Decimal Arithmetic
Specification. Precision is set to nine. Rounding is set to
:const:`ROUND_HALF_EVEN`. All flags are cleared. No traps are enabled (so that
exceptions are not raised during computations).
Because the traps are disabled, this context is useful for applications that
prefer to have result value of :const:`NaN` or :const:`Infinity` instead of
raising exceptions. This allows an application to complete a run in the
presence of conditions that would otherwise halt the program.
.. class:: DefaultContext
This context is used by the :class:`Context` constructor as a prototype for new
contexts. Changing a field (such a precision) has the effect of changing the
default for new contexts created by the :class:`Context` constructor.
This context is most useful in multi-threaded environments. Changing one of the
fields before threads are started has the effect of setting system-wide
defaults. Changing the fields after threads have started is not recommended as
it would require thread synchronization to prevent race conditions.
In single threaded environments, it is preferable to not use this context at
all. Instead, simply create contexts explicitly as described below.
The default values are precision=28, rounding=ROUND_HALF_EVEN, and enabled traps
for Overflow, InvalidOperation, and DivisionByZero.
In addition to the three supplied contexts, new contexts can be created with the
:class:`Context` constructor.
.. class:: Context(prec=None, rounding=None, traps=None, flags=None, Emin=None, Emax=None, capitals=1)
Creates a new context. If a field is not specified or is :const:`None`, the
default values are copied from the :const:`DefaultContext`. If the *flags*
field is not specified or is :const:`None`, all flags are cleared.
The *prec* field is a positive integer that sets the precision for arithmetic
operations in the context.
The *rounding* option is one of:
* :const:`ROUND_CEILING` (towards :const:`Infinity`),
* :const:`ROUND_DOWN` (towards zero),
* :const:`ROUND_FLOOR` (towards :const:`-Infinity`),
* :const:`ROUND_HALF_DOWN` (to nearest with ties going towards zero),
* :const:`ROUND_HALF_EVEN` (to nearest with ties going to nearest even integer),
* :const:`ROUND_HALF_UP` (to nearest with ties going away from zero), or
* :const:`ROUND_UP` (away from zero).
* :const:`ROUND_05UP` (away from zero if last digit after rounding towards zero
would have been 0 or 5; otherwise towards zero)
The *traps* and *flags* fields list any signals to be set. Generally, new
contexts should only set traps and leave the flags clear.
The *Emin* and *Emax* fields are integers specifying the outer limits allowable
for exponents.
The *capitals* field is either :const:`0` or :const:`1` (the default). If set to
:const:`1`, exponents are printed with a capital :const:`E`; otherwise, a
lowercase :const:`e` is used: :const:`Decimal('6.02e+23')`.
.. versionchanged:: 2.6
The :const:`ROUND_05UP` rounding mode was added.
The :class:`Context` class defines several general purpose methods as well as
a large number of methods for doing arithmetic directly in a given context.
In addition, for each of the :class:`Decimal` methods described above (with
the exception of the :meth:`adjusted` and :meth:`as_tuple` methods) there is
a corresponding :class:`Context` method. For example, for a :class:`Context`
instance ``C`` and :class:`Decimal` instance ``x``, ``C.exp(x)`` is
equivalent to ``x.exp(context=C)``. Each :class:`Context` method accepts a
Python integer (an instance of :class:`int` or :class:`long`) anywhere that a
Decimal instance is accepted.
.. method:: clear_flags()
Resets all of the flags to :const:`0`.
.. method:: copy()
Return a duplicate of the context.
.. method:: copy_decimal(num)
Return a copy of the Decimal instance num.
.. method:: create_decimal(num)
Creates a new Decimal instance from *num* but using *self* as
context. Unlike the :class:`Decimal` constructor, the context precision,
rounding method, flags, and traps are applied to the conversion.
This is useful because constants are often given to a greater precision
than is needed by the application. Another benefit is that rounding
immediately eliminates unintended effects from digits beyond the current
precision. In the following example, using unrounded inputs means that
adding zero to a sum can change the result:
.. doctest:: newcontext
>>> getcontext().prec = 3
>>> Decimal('3.4445') + Decimal('1.0023')
Decimal('4.45')
>>> Decimal('3.4445') + Decimal(0) + Decimal('1.0023')
Decimal('4.44')
This method implements the to-number operation of the IBM specification.
If the argument is a string, no leading or trailing whitespace is
permitted.
.. method:: create_decimal_from_float(f)
Creates a new Decimal instance from a float *f* but rounding using *self*
as the context. Unlike the :meth:`Decimal.from_float` class method,
the context precision, rounding method, flags, and traps are applied to
the conversion.
.. doctest::
>>> context = Context(prec=5, rounding=ROUND_DOWN)
>>> context.create_decimal_from_float(math.pi)
Decimal('3.1415')
>>> context = Context(prec=5, traps=[Inexact])
>>> context.create_decimal_from_float(math.pi)
Traceback (most recent call last):
...
Inexact: None
.. versionadded:: 2.7
.. method:: Etiny()
Returns a value equal to ``Emin - prec + 1`` which is the minimum exponent
value for subnormal results. When underflow occurs, the exponent is set
to :const:`Etiny`.
.. method:: Etop()
Returns a value equal to ``Emax - prec + 1``.
The usual approach to working with decimals is to create :class:`Decimal`
instances and then apply arithmetic operations which take place within the
current context for the active thread. An alternative approach is to use
context methods for calculating within a specific context. The methods are
similar to those for the :class:`Decimal` class and are only briefly
recounted here.
.. method:: abs(x)
Returns the absolute value of *x*.
.. method:: add(x, y)
Return the sum of *x* and *y*.
.. method:: canonical(x)
Returns the same Decimal object *x*.
.. method:: compare(x, y)
Compares *x* and *y* numerically.
.. method:: compare_signal(x, y)
Compares the values of the two operands numerically.
.. method:: compare_total(x, y)
Compares two operands using their abstract representation.
.. method:: compare_total_mag(x, y)
Compares two operands using their abstract representation, ignoring sign.
.. method:: copy_abs(x)
Returns a copy of *x* with the sign set to 0.
.. method:: copy_negate(x)
Returns a copy of *x* with the sign inverted.
.. method:: copy_sign(x, y)
Copies the sign from *y* to *x*.
.. method:: divide(x, y)
Return *x* divided by *y*.
.. method:: divide_int(x, y)
Return *x* divided by *y*, truncated to an integer.
.. method:: divmod(x, y)
Divides two numbers and returns the integer part of the result.
.. method:: exp(x)
Returns `e ** x`.
.. method:: fma(x, y, z)
Returns *x* multiplied by *y*, plus *z*.
.. method:: is_canonical(x)
Returns ``True`` if *x* is canonical; otherwise returns ``False``.
.. method:: is_finite(x)
Returns ``True`` if *x* is finite; otherwise returns ``False``.
.. method:: is_infinite(x)
Returns ``True`` if *x* is infinite; otherwise returns ``False``.
.. method:: is_nan(x)
Returns ``True`` if *x* is a qNaN or sNaN; otherwise returns ``False``.
.. method:: is_normal(x)
Returns ``True`` if *x* is a normal number; otherwise returns ``False``.
.. method:: is_qnan(x)
Returns ``True`` if *x* is a quiet NaN; otherwise returns ``False``.
.. method:: is_signed(x)
Returns ``True`` if *x* is negative; otherwise returns ``False``.
.. method:: is_snan(x)
Returns ``True`` if *x* is a signaling NaN; otherwise returns ``False``.
.. method:: is_subnormal(x)
Returns ``True`` if *x* is subnormal; otherwise returns ``False``.
.. method:: is_zero(x)
Returns ``True`` if *x* is a zero; otherwise returns ``False``.
.. method:: ln(x)
Returns the natural (base e) logarithm of *x*.
.. method:: log10(x)
Returns the base 10 logarithm of *x*.
.. method:: logb(x)
Returns the exponent of the magnitude of the operand's MSD.
.. method:: logical_and(x, y)
Applies the logical operation *and* between each operand's digits.
.. method:: logical_invert(x)
Invert all the digits in *x*.
.. method:: logical_or(x, y)
Applies the logical operation *or* between each operand's digits.
.. method:: logical_xor(x, y)
Applies the logical operation *xor* between each operand's digits.
.. method:: max(x, y)
Compares two values numerically and returns the maximum.
.. method:: max_mag(x, y)
Compares the values numerically with their sign ignored.
.. method:: min(x, y)
Compares two values numerically and returns the minimum.
.. method:: min_mag(x, y)
Compares the values numerically with their sign ignored.
.. method:: minus(x)
Minus corresponds to the unary prefix minus operator in Python.
.. method:: multiply(x, y)
Return the product of *x* and *y*.
.. method:: next_minus(x)
Returns the largest representable number smaller than *x*.
.. method:: next_plus(x)
Returns the smallest representable number larger than *x*.
.. method:: next_toward(x, y)
Returns the number closest to *x*, in direction towards *y*.
.. method:: normalize(x)
Reduces *x* to its simplest form.
.. method:: number_class(x)
Returns an indication of the class of *x*.
.. method:: plus(x)
Plus corresponds to the unary prefix plus operator in Python. This
operation applies the context precision and rounding, so it is *not* an
identity operation.
.. method:: power(x, y[, modulo])
Return ``x`` to the power of ``y``, reduced modulo ``modulo`` if given.
With two arguments, compute ``x**y``. If ``x`` is negative then ``y``
must be integral. The result will be inexact unless ``y`` is integral and
the result is finite and can be expressed exactly in 'precision' digits.
The result should always be correctly rounded, using the rounding mode of
the current thread's context.
With three arguments, compute ``(x**y) % modulo``. For the three argument
form, the following restrictions on the arguments hold:
- all three arguments must be integral
- ``y`` must be nonnegative
- at least one of ``x`` or ``y`` must be nonzero
- ``modulo`` must be nonzero and have at most 'precision' digits
The value resulting from ``Context.power(x, y, modulo)`` is
equal to the value that would be obtained by computing ``(x**y)
% modulo`` with unbounded precision, but is computed more
efficiently. The exponent of the result is zero, regardless of
the exponents of ``x``, ``y`` and ``modulo``. The result is
always exact.
.. versionchanged:: 2.6
``y`` may now be nonintegral in ``x**y``.
Stricter requirements for the three-argument version.
.. method:: quantize(x, y)
Returns a value equal to *x* (rounded), having the exponent of *y*.
.. method:: radix()
Just returns 10, as this is Decimal, :)
.. method:: remainder(x, y)
Returns the remainder from integer division.
The sign of the result, if non-zero, is the same as that of the original
dividend.
.. method:: remainder_near(x, y)
Returns ``x - y * n``, where *n* is the integer nearest the exact value
of ``x / y`` (if the result is 0 then its sign will be the sign of *x*).
.. method:: rotate(x, y)
Returns a rotated copy of *x*, *y* times.
.. method:: same_quantum(x, y)
Returns ``True`` if the two operands have the same exponent.
.. method:: scaleb (x, y)
Returns the first operand after adding the second value its exp.
.. method:: shift(x, y)
Returns a shifted copy of *x*, *y* times.
.. method:: sqrt(x)
Square root of a non-negative number to context precision.
.. method:: subtract(x, y)
Return the difference between *x* and *y*.
.. method:: to_eng_string(x)
Convert to a string, using engineering notation if an exponent is needed.
Engineering notation has an exponent which is a multiple of 3. This
can leave up to 3 digits to the left of the decimal place and may
require the addition of either one or two trailing zeros.
.. method:: to_integral_exact(x)
Rounds to an integer.
.. method:: to_sci_string(x)
Converts a number to a string using scientific notation.
.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
.. _decimal-signals:
Signals
-------
Signals represent conditions that arise during computation. Each corresponds to
one context flag and one context trap enabler.
The context flag is set whenever the condition is encountered. After the
computation, flags may be checked for informational purposes (for instance, to
determine whether a computation was exact). After checking the flags, be sure to
clear all flags before starting the next computation.
If the context's trap enabler is set for the signal, then the condition causes a
Python exception to be raised. For example, if the :class:`DivisionByZero` trap
is set, then a :exc:`DivisionByZero` exception is raised upon encountering the
condition.
.. class:: Clamped
Altered an exponent to fit representation constraints.
Typically, clamping occurs when an exponent falls outside the context's
:attr:`Emin` and :attr:`Emax` limits. If possible, the exponent is reduced to
fit by adding zeros to the coefficient.
.. class:: DecimalException
Base class for other signals and a subclass of :exc:`ArithmeticError`.
.. class:: DivisionByZero
Signals the division of a non-infinite number by zero.
Can occur with division, modulo division, or when raising a number to a negative
power. If this signal is not trapped, returns :const:`Infinity` or
:const:`-Infinity` with the sign determined by the inputs to the calculation.
.. class:: Inexact
Indicates that rounding occurred and the result is not exact.
Signals when non-zero digits were discarded during rounding. The rounded result
is returned. The signal flag or trap is used to detect when results are
inexact.
.. class:: InvalidOperation
An invalid operation was performed.
Indicates that an operation was requested that does not make sense. If not
trapped, returns :const:`NaN`. Possible causes include::
Infinity - Infinity
0 * Infinity
Infinity / Infinity
x % 0
Infinity % x
x._rescale( non-integer )
sqrt(-x) and x > 0
0 ** 0
x ** (non-integer)
x ** Infinity
.. class:: Overflow
Numerical overflow.
Indicates the exponent is larger than :attr:`Emax` after rounding has
occurred. If not trapped, the result depends on the rounding mode, either
pulling inward to the largest representable finite number or rounding outward
to :const:`Infinity`. In either case, :class:`Inexact` and :class:`Rounded`
are also signaled.
.. class:: Rounded
Rounding occurred though possibly no information was lost.
Signaled whenever rounding discards digits; even if those digits are zero
(such as rounding :const:`5.00` to :const:`5.0`). If not trapped, returns
the result unchanged. This signal is used to detect loss of significant
digits.
.. class:: Subnormal
Exponent was lower than :attr:`Emin` prior to rounding.
Occurs when an operation result is subnormal (the exponent is too small). If
not trapped, returns the result unchanged.
.. class:: Underflow
Numerical underflow with result rounded to zero.
Occurs when a subnormal result is pushed to zero by rounding. :class:`Inexact`
and :class:`Subnormal` are also signaled.
The following table summarizes the hierarchy of signals::
exceptions.ArithmeticError(exceptions.StandardError)
DecimalException
Clamped
DivisionByZero(DecimalException, exceptions.ZeroDivisionError)
Inexact
Overflow(Inexact, Rounded)
Underflow(Inexact, Rounded, Subnormal)
InvalidOperation
Rounded
Subnormal
.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
.. _decimal-notes:
Floating Point Notes
--------------------
Mitigating round-off error with increased precision
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The use of decimal floating point eliminates decimal representation error
(making it possible to represent :const:`0.1` exactly); however, some operations
can still incur round-off error when non-zero digits exceed the fixed precision.
The effects of round-off error can be amplified by the addition or subtraction
of nearly offsetting quantities resulting in loss of significance. Knuth
provides two instructive examples where rounded floating point arithmetic with
insufficient precision causes the breakdown of the associative and distributive
properties of addition:
.. doctest:: newcontext
# Examples from Seminumerical Algorithms, Section 4.2.2.
>>> from decimal import Decimal, getcontext
>>> getcontext().prec = 8
>>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111')
>>> (u + v) + w
Decimal('9.5111111')
>>> u + (v + w)
Decimal('10')
>>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003')
>>> (u*v) + (u*w)
Decimal('0.01')
>>> u * (v+w)
Decimal('0.0060000')
The :mod:`decimal` module makes it possible to restore the identities by
expanding the precision sufficiently to avoid loss of significance:
.. doctest:: newcontext
>>> getcontext().prec = 20
>>> u, v, w = Decimal(11111113), Decimal(-11111111), Decimal('7.51111111')
>>> (u + v) + w
Decimal('9.51111111')
>>> u + (v + w)
Decimal('9.51111111')
>>>
>>> u, v, w = Decimal(20000), Decimal(-6), Decimal('6.0000003')
>>> (u*v) + (u*w)
Decimal('0.0060000')
>>> u * (v+w)
Decimal('0.0060000')
Special values
^^^^^^^^^^^^^^
The number system for the :mod:`decimal` module provides special values
including :const:`NaN`, :const:`sNaN`, :const:`-Infinity`, :const:`Infinity`,
and two zeros, :const:`+0` and :const:`-0`.
Infinities can be constructed directly with: ``Decimal('Infinity')``. Also,
they can arise from dividing by zero when the :exc:`DivisionByZero` signal is
not trapped. Likewise, when the :exc:`Overflow` signal is not trapped, infinity
can result from rounding beyond the limits of the largest representable number.
The infinities are signed (affine) and can be used in arithmetic operations
where they get treated as very large, indeterminate numbers. For instance,
adding a constant to infinity gives another infinite result.
Some operations are indeterminate and return :const:`NaN`, or if the
:exc:`InvalidOperation` signal is trapped, raise an exception. For example,
``0/0`` returns :const:`NaN` which means "not a number". This variety of
:const:`NaN` is quiet and, once created, will flow through other computations
always resulting in another :const:`NaN`. This behavior can be useful for a
series of computations that occasionally have missing inputs --- it allows the
calculation to proceed while flagging specific results as invalid.
A variant is :const:`sNaN` which signals rather than remaining quiet after every
operation. This is a useful return value when an invalid result needs to
interrupt a calculation for special handling.
The behavior of Python's comparison operators can be a little surprising where a
:const:`NaN` is involved. A test for equality where one of the operands is a
quiet or signaling :const:`NaN` always returns :const:`False` (even when doing
``Decimal('NaN')==Decimal('NaN')``), while a test for inequality always returns
:const:`True`. An attempt to compare two Decimals using any of the ``<``,
``<=``, ``>`` or ``>=`` operators will raise the :exc:`InvalidOperation` signal
if either operand is a :const:`NaN`, and return :const:`False` if this signal is
not trapped. Note that the General Decimal Arithmetic specification does not
specify the behavior of direct comparisons; these rules for comparisons
involving a :const:`NaN` were taken from the IEEE 854 standard (see Table 3 in
section 5.7). To ensure strict standards-compliance, use the :meth:`compare`
and :meth:`compare-signal` methods instead.
The signed zeros can result from calculations that underflow. They keep the sign
that would have resulted if the calculation had been carried out to greater
precision. Since their magnitude is zero, both positive and negative zeros are
treated as equal and their sign is informational.
In addition to the two signed zeros which are distinct yet equal, there are
various representations of zero with differing precisions yet equivalent in
value. This takes a bit of getting used to. For an eye accustomed to
normalized floating point representations, it is not immediately obvious that
the following calculation returns a value equal to zero:
>>> 1 / Decimal('Infinity')
Decimal('0E-1000000026')
.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
.. _decimal-threads:
Working with threads
--------------------
The :func:`getcontext` function accesses a different :class:`Context` object for
each thread. Having separate thread contexts means that threads may make
changes (such as ``getcontext.prec=10``) without interfering with other threads.
Likewise, the :func:`setcontext` function automatically assigns its target to
the current thread.
If :func:`setcontext` has not been called before :func:`getcontext`, then
:func:`getcontext` will automatically create a new context for use in the
current thread.
The new context is copied from a prototype context called *DefaultContext*. To
control the defaults so that each thread will use the same values throughout the
application, directly modify the *DefaultContext* object. This should be done
*before* any threads are started so that there won't be a race condition between
threads calling :func:`getcontext`. For example::
# Set applicationwide defaults for all threads about to be launched
DefaultContext.prec = 12
DefaultContext.rounding = ROUND_DOWN
DefaultContext.traps = ExtendedContext.traps.copy()
DefaultContext.traps[InvalidOperation] = 1
setcontext(DefaultContext)
# Afterwards, the threads can be started
t1.start()
t2.start()
t3.start()
. . .
.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
.. _decimal-recipes:
Recipes
-------
Here are a few recipes that serve as utility functions and that demonstrate ways
to work with the :class:`Decimal` class::
def moneyfmt(value, places=2, curr='', sep=',', dp='.',
pos='', neg='-', trailneg=''):
"""Convert Decimal to a money formatted string.
places: required number of places after the decimal point
curr: optional currency symbol before the sign (may be blank)
sep: optional grouping separator (comma, period, space, or blank)
dp: decimal point indicator (comma or period)
only specify as blank when places is zero
pos: optional sign for positive numbers: '+', space or blank
neg: optional sign for negative numbers: '-', '(', space or blank
trailneg:optional trailing minus indicator: '-', ')', space or blank
>>> d = Decimal('-1234567.8901')
>>> moneyfmt(d, curr='$')
'-$1,234,567.89'
>>> moneyfmt(d, places=0, sep='.', dp='', neg='', trailneg='-')
'1.234.568-'
>>> moneyfmt(d, curr='$', neg='(', trailneg=')')
'($1,234,567.89)'
>>> moneyfmt(Decimal(123456789), sep=' ')
'123 456 789.00'
>>> moneyfmt(Decimal('-0.02'), neg='<', trailneg='>')
'<0.02>'
"""
q = Decimal(10) ** -places # 2 places --> '0.01'
sign, digits, exp = value.quantize(q).as_tuple()
result = []
digits = map(str, digits)
build, next = result.append, digits.pop
if sign:
build(trailneg)
for i in range(places):
build(next() if digits else '0')
build(dp)
if not digits:
build('0')
i = 0
while digits:
build(next())
i += 1
if i == 3 and digits:
i = 0
build(sep)
build(curr)
build(neg if sign else pos)
return ''.join(reversed(result))
def pi():
"""Compute Pi to the current precision.
>>> print pi()
3.141592653589793238462643383
"""
getcontext().prec += 2 # extra digits for intermediate steps
three = Decimal(3) # substitute "three=3.0" for regular floats
lasts, t, s, n, na, d, da = 0, three, 3, 1, 0, 0, 24
while s != lasts:
lasts = s
n, na = n+na, na+8
d, da = d+da, da+32
t = (t * n) / d
s += t
getcontext().prec -= 2
return +s # unary plus applies the new precision
def exp(x):
"""Return e raised to the power of x. Result type matches input type.
>>> print exp(Decimal(1))
2.718281828459045235360287471
>>> print exp(Decimal(2))
7.389056098930650227230427461
>>> print exp(2.0)
7.38905609893
>>> print exp(2+0j)
(7.38905609893+0j)
"""
getcontext().prec += 2
i, lasts, s, fact, num = 0, 0, 1, 1, 1
while s != lasts:
lasts = s
i += 1
fact *= i
num *= x
s += num / fact
getcontext().prec -= 2
return +s
def cos(x):
"""Return the cosine of x as measured in radians.
>>> print cos(Decimal('0.5'))
0.8775825618903727161162815826
>>> print cos(0.5)
0.87758256189
>>> print cos(0.5+0j)
(0.87758256189+0j)
"""
getcontext().prec += 2
i, lasts, s, fact, num, sign = 0, 0, 1, 1, 1, 1
while s != lasts:
lasts = s
i += 2
fact *= i * (i-1)
num *= x * x
sign *= -1
s += num / fact * sign
getcontext().prec -= 2
return +s
def sin(x):
"""Return the sine of x as measured in radians.
>>> print sin(Decimal('0.5'))
0.4794255386042030002732879352
>>> print sin(0.5)
0.479425538604
>>> print sin(0.5+0j)
(0.479425538604+0j)
"""
getcontext().prec += 2
i, lasts, s, fact, num, sign = 1, 0, x, 1, x, 1
while s != lasts:
lasts = s
i += 2
fact *= i * (i-1)
num *= x * x
sign *= -1
s += num / fact * sign
getcontext().prec -= 2
return +s
.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
.. _decimal-faq:
Decimal FAQ
-----------
Q. It is cumbersome to type ``decimal.Decimal('1234.5')``. Is there a way to
minimize typing when using the interactive interpreter?
A. Some users abbreviate the constructor to just a single letter:
>>> D = decimal.Decimal
>>> D('1.23') + D('3.45')
Decimal('4.68')
Q. In a fixed-point application with two decimal places, some inputs have many
places and need to be rounded. Others are not supposed to have excess digits
and need to be validated. What methods should be used?
A. The :meth:`quantize` method rounds to a fixed number of decimal places. If
the :const:`Inexact` trap is set, it is also useful for validation:
>>> TWOPLACES = Decimal(10) ** -2 # same as Decimal('0.01')
>>> # Round to two places
>>> Decimal('3.214').quantize(TWOPLACES)
Decimal('3.21')
>>> # Validate that a number does not exceed two places
>>> Decimal('3.21').quantize(TWOPLACES, context=Context(traps=[Inexact]))
Decimal('3.21')
>>> Decimal('3.214').quantize(TWOPLACES, context=Context(traps=[Inexact]))
Traceback (most recent call last):
...
Inexact: None
Q. Once I have valid two place inputs, how do I maintain that invariant
throughout an application?
A. Some operations like addition, subtraction, and multiplication by an integer
will automatically preserve fixed point. Others operations, like division and
non-integer multiplication, will change the number of decimal places and need to
be followed-up with a :meth:`quantize` step:
>>> a = Decimal('102.72') # Initial fixed-point values
>>> b = Decimal('3.17')
>>> a + b # Addition preserves fixed-point
Decimal('105.89')
>>> a - b
Decimal('99.55')
>>> a * 42 # So does integer multiplication
Decimal('4314.24')
>>> (a * b).quantize(TWOPLACES) # Must quantize non-integer multiplication
Decimal('325.62')
>>> (b / a).quantize(TWOPLACES) # And quantize division
Decimal('0.03')
In developing fixed-point applications, it is convenient to define functions
to handle the :meth:`quantize` step:
>>> def mul(x, y, fp=TWOPLACES):
... return (x * y).quantize(fp)
>>> def div(x, y, fp=TWOPLACES):
... return (x / y).quantize(fp)
>>> mul(a, b) # Automatically preserve fixed-point
Decimal('325.62')
>>> div(b, a)
Decimal('0.03')
Q. There are many ways to express the same value. The numbers :const:`200`,
:const:`200.000`, :const:`2E2`, and :const:`.02E+4` all have the same value at
various precisions. Is there a way to transform them to a single recognizable
canonical value?
A. The :meth:`normalize` method maps all equivalent values to a single
representative:
>>> values = map(Decimal, '200 200.000 2E2 .02E+4'.split())
>>> [v.normalize() for v in values]
[Decimal('2E+2'), Decimal('2E+2'), Decimal('2E+2'), Decimal('2E+2')]
Q. Some decimal values always print with exponential notation. Is there a way
to get a non-exponential representation?
A. For some values, exponential notation is the only way to express the number
of significant places in the coefficient. For example, expressing
:const:`5.0E+3` as :const:`5000` keeps the value constant but cannot show the
original's two-place significance.
If an application does not care about tracking significance, it is easy to
remove the exponent and trailing zeros, losing significance, but keeping the
value unchanged::
def remove_exponent(d):
'''Remove exponent and trailing zeros.
>>> remove_exponent(Decimal('5E+3'))
Decimal('5000')
'''
return d.quantize(Decimal(1)) if d == d.to_integral() else d.normalize()
Q. Is there a way to convert a regular float to a :class:`Decimal`?
A. Yes, any binary floating point number can be exactly expressed as a
Decimal though an exact conversion may take more precision than intuition would
suggest:
.. doctest::
>>> Decimal(math.pi)
Decimal('3.141592653589793115997963468544185161590576171875')
Q. Within a complex calculation, how can I make sure that I haven't gotten a
spurious result because of insufficient precision or rounding anomalies.
A. The decimal module makes it easy to test results. A best practice is to
re-run calculations using greater precision and with various rounding modes.
Widely differing results indicate insufficient precision, rounding mode issues,
ill-conditioned inputs, or a numerically unstable algorithm.
Q. I noticed that context precision is applied to the results of operations but
not to the inputs. Is there anything to watch out for when mixing values of
different precisions?
A. Yes. The principle is that all values are considered to be exact and so is
the arithmetic on those values. Only the results are rounded. The advantage
for inputs is that "what you type is what you get". A disadvantage is that the
results can look odd if you forget that the inputs haven't been rounded:
.. doctest:: newcontext
>>> getcontext().prec = 3
>>> Decimal('3.104') + Decimal('2.104')
Decimal('5.21')
>>> Decimal('3.104') + Decimal('0.000') + Decimal('2.104')
Decimal('5.20')
The solution is either to increase precision or to force rounding of inputs
using the unary plus operation:
.. doctest:: newcontext
>>> getcontext().prec = 3
>>> +Decimal('1.23456789') # unary plus triggers rounding
Decimal('1.23')
Alternatively, inputs can be rounded upon creation using the
:meth:`Context.create_decimal` method:
>>> Context(prec=5, rounding=ROUND_DOWN).create_decimal('1.2345678')
Decimal('1.2345')
PK %�\A\ER� � ) html/_sources/library/development.rst.txtnu �[���
.. _development:
*****************
Development Tools
*****************
The modules described in this chapter help you write software. For example, the
:mod:`pydoc` module takes a module and generates documentation based on the
module's contents. The :mod:`doctest` and :mod:`unittest` modules contains
frameworks for writing unit tests that automatically exercise code and verify
that the expected output is produced. :program:`2to3` can translate Python 2.x
source code into valid Python 3.x code.
The list of modules described in this chapter is:
.. toctree::
pydoc.rst
doctest.rst
unittest.rst
2to3.rst
test.rst
PK %�\�}wo�w �w % html/_sources/library/difflib.rst.txtnu �[��� :mod:`difflib` --- Helpers for computing deltas
===============================================
.. module:: difflib
:synopsis: Helpers for computing differences between objects.
.. moduleauthor:: Tim Peters <tim_one@users.sourceforge.net>
.. sectionauthor:: Tim Peters <tim_one@users.sourceforge.net>
.. Markup by Fred L. Drake, Jr. <fdrake@acm.org>
.. testsetup::
import sys
from difflib import *
.. versionadded:: 2.1
This module provides classes and functions for comparing sequences. It
can be used for example, for comparing files, and can produce difference
information in various formats, including HTML and context and unified
diffs. For comparing directories and files, see also, the :mod:`filecmp` module.
.. class:: SequenceMatcher
This is a flexible class for comparing pairs of sequences of any type, so long
as the sequence elements are :term:`hashable`. The basic algorithm predates, and is a
little fancier than, an algorithm published in the late 1980's by Ratcliff and
Obershelp under the hyperbolic name "gestalt pattern matching." The idea is to
find the longest contiguous matching subsequence that contains no "junk"
elements (the Ratcliff and Obershelp algorithm doesn't address junk). The same
idea is then applied recursively to the pieces of the sequences to the left and
to the right of the matching subsequence. This does not yield minimal edit
sequences, but does tend to yield matches that "look right" to people.
**Timing:** The basic Ratcliff-Obershelp algorithm is cubic time in the worst
case and quadratic time in the expected case. :class:`SequenceMatcher` is
quadratic time for the worst case and has expected-case behavior dependent in a
complicated way on how many elements the sequences have in common; best case
time is linear.
**Automatic junk heuristic:** :class:`SequenceMatcher` supports a heuristic that
automatically treats certain sequence items as junk. The heuristic counts how many
times each individual item appears in the sequence. If an item's duplicates (after
the first one) account for more than 1% of the sequence and the sequence is at least
200 items long, this item is marked as "popular" and is treated as junk for
the purpose of sequence matching. This heuristic can be turned off by setting
the ``autojunk`` argument to ``False`` when creating the :class:`SequenceMatcher`.
.. versionadded:: 2.7.1
The *autojunk* parameter.
.. class:: Differ
This is a class for comparing sequences of lines of text, and producing
human-readable differences or deltas. Differ uses :class:`SequenceMatcher`
both to compare sequences of lines, and to compare sequences of characters
within similar (near-matching) lines.
Each line of a :class:`Differ` delta begins with a two-letter code:
+----------+-------------------------------------------+
| Code | Meaning |
+==========+===========================================+
| ``'- '`` | line unique to sequence 1 |
+----------+-------------------------------------------+
| ``'+ '`` | line unique to sequence 2 |
+----------+-------------------------------------------+
| ``' '`` | line common to both sequences |
+----------+-------------------------------------------+
| ``'? '`` | line not present in either input sequence |
+----------+-------------------------------------------+
Lines beginning with '``?``' attempt to guide the eye to intraline differences,
and were not present in either input sequence. These lines can be confusing if
the sequences contain tab characters.
.. class:: HtmlDiff
This class can be used to create an HTML table (or a complete HTML file
containing the table) showing a side by side, line by line comparison of text
with inter-line and intra-line change highlights. The table can be generated in
either full or contextual difference mode.
The constructor for this class is:
.. function:: __init__(tabsize=8, wrapcolumn=None, linejunk=None, charjunk=IS_CHARACTER_JUNK)
Initializes instance of :class:`HtmlDiff`.
*tabsize* is an optional keyword argument to specify tab stop spacing and
defaults to ``8``.
*wrapcolumn* is an optional keyword to specify column number where lines are
broken and wrapped, defaults to ``None`` where lines are not wrapped.
*linejunk* and *charjunk* are optional keyword arguments passed into :func:`ndiff`
(used by :class:`HtmlDiff` to generate the side by side HTML differences). See
:func:`ndiff` documentation for argument default values and descriptions.
The following methods are public:
.. function:: make_file(fromlines, tolines [, fromdesc][, todesc][, context][, numlines])
Compares *fromlines* and *tolines* (lists of strings) and returns a string which
is a complete HTML file containing a table showing line by line differences with
inter-line and intra-line changes highlighted.
*fromdesc* and *todesc* are optional keyword arguments to specify from/to file
column header strings (both default to an empty string).
*context* and *numlines* are both optional keyword arguments. Set *context* to
``True`` when contextual differences are to be shown, else the default is
``False`` to show the full files. *numlines* defaults to ``5``. When *context*
is ``True`` *numlines* controls the number of context lines which surround the
difference highlights. When *context* is ``False`` *numlines* controls the
number of lines which are shown before a difference highlight when using the
"next" hyperlinks (setting to zero would cause the "next" hyperlinks to place
the next difference highlight at the top of the browser without any leading
context).
.. function:: make_table(fromlines, tolines [, fromdesc][, todesc][, context][, numlines])
Compares *fromlines* and *tolines* (lists of strings) and returns a string which
is a complete HTML table showing line by line differences with inter-line and
intra-line changes highlighted.
The arguments for this method are the same as those for the :meth:`make_file`
method.
:file:`Tools/scripts/diff.py` is a command-line front-end to this class and
contains a good example of its use.
.. versionadded:: 2.4
.. function:: context_diff(a, b[, fromfile][, tofile][, fromfiledate][, tofiledate][, n][, lineterm])
Compare *a* and *b* (lists of strings); return a delta (a :term:`generator`
generating the delta lines) in context diff format.
Context diffs are a compact way of showing just the lines that have changed plus
a few lines of context. The changes are shown in a before/after style. The
number of context lines is set by *n* which defaults to three.
By default, the diff control lines (those with ``***`` or ``---``) are created
with a trailing newline. This is helpful so that inputs created from
:func:`file.readlines` result in diffs that are suitable for use with
:func:`file.writelines` since both the inputs and outputs have trailing
newlines.
For inputs that do not have trailing newlines, set the *lineterm* argument to
``""`` so that the output will be uniformly newline free.
The context diff format normally has a header for filenames and modification
times. Any or all of these may be specified using strings for *fromfile*,
*tofile*, *fromfiledate*, and *tofiledate*. The modification times are normally
expressed in the ISO 8601 format. If not specified, the
strings default to blanks.
>>> s1 = ['bacon\n', 'eggs\n', 'ham\n', 'guido\n']
>>> s2 = ['python\n', 'eggy\n', 'hamster\n', 'guido\n']
>>> for line in context_diff(s1, s2, fromfile='before.py', tofile='after.py'):
... sys.stdout.write(line) # doctest: +NORMALIZE_WHITESPACE
*** before.py
--- after.py
***************
*** 1,4 ****
! bacon
! eggs
! ham
guido
--- 1,4 ----
! python
! eggy
! hamster
guido
See :ref:`difflib-interface` for a more detailed example.
.. versionadded:: 2.3
.. function:: get_close_matches(word, possibilities[, n][, cutoff])
Return a list of the best "good enough" matches. *word* is a sequence for which
close matches are desired (typically a string), and *possibilities* is a list of
sequences against which to match *word* (typically a list of strings).
Optional argument *n* (default ``3``) is the maximum number of close matches to
return; *n* must be greater than ``0``.
Optional argument *cutoff* (default ``0.6``) is a float in the range [0, 1].
Possibilities that don't score at least that similar to *word* are ignored.
The best (no more than *n*) matches among the possibilities are returned in a
list, sorted by similarity score, most similar first.
>>> get_close_matches('appel', ['ape', 'apple', 'peach', 'puppy'])
['apple', 'ape']
>>> import keyword
>>> get_close_matches('wheel', keyword.kwlist)
['while']
>>> get_close_matches('apple', keyword.kwlist)
[]
>>> get_close_matches('accept', keyword.kwlist)
['except']
.. function:: ndiff(a, b[, linejunk][, charjunk])
Compare *a* and *b* (lists of strings); return a :class:`Differ`\ -style
delta (a :term:`generator` generating the delta lines).
Optional keyword parameters *linejunk* and *charjunk* are for filter functions
(or ``None``):
*linejunk*: A function that accepts a single string argument, and returns true
if the string is junk, or false if not. The default is (``None``), starting with
Python 2.3. Before then, the default was the module-level function
:func:`IS_LINE_JUNK`, which filters out lines without visible characters, except
for at most one pound character (``'#'``). As of Python 2.3, the underlying
:class:`SequenceMatcher` class does a dynamic analysis of which lines are so
frequent as to constitute noise, and this usually works better than the pre-2.3
default.
*charjunk*: A function that accepts a character (a string of length 1), and
returns if the character is junk, or false if not. The default is module-level
function :func:`IS_CHARACTER_JUNK`, which filters out whitespace characters (a
blank or tab; note: bad idea to include newline in this!).
:file:`Tools/scripts/ndiff.py` is a command-line front-end to this function.
>>> diff = ndiff('one\ntwo\nthree\n'.splitlines(1),
... 'ore\ntree\nemu\n'.splitlines(1))
>>> print ''.join(diff),
- one
? ^
+ ore
? ^
- two
- three
? -
+ tree
+ emu
.. function:: restore(sequence, which)
Return one of the two sequences that generated a delta.
Given a *sequence* produced by :meth:`Differ.compare` or :func:`ndiff`, extract
lines originating from file 1 or 2 (parameter *which*), stripping off line
prefixes.
Example:
>>> diff = ndiff('one\ntwo\nthree\n'.splitlines(1),
... 'ore\ntree\nemu\n'.splitlines(1))
>>> diff = list(diff) # materialize the generated delta into a list
>>> print ''.join(restore(diff, 1)),
one
two
three
>>> print ''.join(restore(diff, 2)),
ore
tree
emu
.. function:: unified_diff(a, b[, fromfile][, tofile][, fromfiledate][, tofiledate][, n][, lineterm])
Compare *a* and *b* (lists of strings); return a delta (a :term:`generator`
generating the delta lines) in unified diff format.
Unified diffs are a compact way of showing just the lines that have changed plus
a few lines of context. The changes are shown in an inline style (instead of
separate before/after blocks). The number of context lines is set by *n* which
defaults to three.
By default, the diff control lines (those with ``---``, ``+++``, or ``@@``) are
created with a trailing newline. This is helpful so that inputs created from
:func:`file.readlines` result in diffs that are suitable for use with
:func:`file.writelines` since both the inputs and outputs have trailing
newlines.
For inputs that do not have trailing newlines, set the *lineterm* argument to
``""`` so that the output will be uniformly newline free.
The context diff format normally has a header for filenames and modification
times. Any or all of these may be specified using strings for *fromfile*,
*tofile*, *fromfiledate*, and *tofiledate*. The modification times are normally
expressed in the ISO 8601 format. If not specified, the
strings default to blanks.
>>> s1 = ['bacon\n', 'eggs\n', 'ham\n', 'guido\n']
>>> s2 = ['python\n', 'eggy\n', 'hamster\n', 'guido\n']
>>> for line in unified_diff(s1, s2, fromfile='before.py', tofile='after.py'):
... sys.stdout.write(line) # doctest: +NORMALIZE_WHITESPACE
--- before.py
+++ after.py
@@ -1,4 +1,4 @@
-bacon
-eggs
-ham
+python
+eggy
+hamster
guido
See :ref:`difflib-interface` for a more detailed example.
.. versionadded:: 2.3
.. function:: IS_LINE_JUNK(line)
Return true for ignorable lines. The line *line* is ignorable if *line* is
blank or contains a single ``'#'``, otherwise it is not ignorable. Used as a
default for parameter *linejunk* in :func:`ndiff` before Python 2.3.
.. function:: IS_CHARACTER_JUNK(ch)
Return true for ignorable characters. The character *ch* is ignorable if *ch*
is a space or tab, otherwise it is not ignorable. Used as a default for
parameter *charjunk* in :func:`ndiff`.
.. seealso::
`Pattern Matching: The Gestalt Approach <http://www.drdobbs.com/database/pattern-matching-the-gestalt-approach/184407970>`_
Discussion of a similar algorithm by John W. Ratcliff and D. E. Metzener. This
was published in `Dr. Dobb's Journal <http://www.drdobbs.com/>`_ in July, 1988.
.. _sequence-matcher:
SequenceMatcher Objects
-----------------------
The :class:`SequenceMatcher` class has this constructor:
.. class:: SequenceMatcher(isjunk=None, a='', b='', autojunk=True)
Optional argument *isjunk* must be ``None`` (the default) or a one-argument
function that takes a sequence element and returns true if and only if the
element is "junk" and should be ignored. Passing ``None`` for *isjunk* is
equivalent to passing ``lambda x: 0``; in other words, no elements are ignored.
For example, pass::
lambda x: x in " \t"
if you're comparing lines as sequences of characters, and don't want to synch up
on blanks or hard tabs.
The optional arguments *a* and *b* are sequences to be compared; both default to
empty strings. The elements of both sequences must be :term:`hashable`.
The optional argument *autojunk* can be used to disable the automatic junk
heuristic.
.. versionadded:: 2.7.1
The *autojunk* parameter.
:class:`SequenceMatcher` objects have the following methods:
.. method:: set_seqs(a, b)
Set the two sequences to be compared.
:class:`SequenceMatcher` computes and caches detailed information about the
second sequence, so if you want to compare one sequence against many
sequences, use :meth:`set_seq2` to set the commonly used sequence once and
call :meth:`set_seq1` repeatedly, once for each of the other sequences.
.. method:: set_seq1(a)
Set the first sequence to be compared. The second sequence to be compared
is not changed.
.. method:: set_seq2(b)
Set the second sequence to be compared. The first sequence to be compared
is not changed.
.. method:: find_longest_match(alo, ahi, blo, bhi)
Find longest matching block in ``a[alo:ahi]`` and ``b[blo:bhi]``.
If *isjunk* was omitted or ``None``, :meth:`find_longest_match` returns
``(i, j, k)`` such that ``a[i:i+k]`` is equal to ``b[j:j+k]``, where ``alo
<= i <= i+k <= ahi`` and ``blo <= j <= j+k <= bhi``. For all ``(i', j',
k')`` meeting those conditions, the additional conditions ``k >= k'``, ``i
<= i'``, and if ``i == i'``, ``j <= j'`` are also met. In other words, of
all maximal matching blocks, return one that starts earliest in *a*, and
of all those maximal matching blocks that start earliest in *a*, return
the one that starts earliest in *b*.
>>> s = SequenceMatcher(None, " abcd", "abcd abcd")
>>> s.find_longest_match(0, 5, 0, 9)
Match(a=0, b=4, size=5)
If *isjunk* was provided, first the longest matching block is determined
as above, but with the additional restriction that no junk element appears
in the block. Then that block is extended as far as possible by matching
(only) junk elements on both sides. So the resulting block never matches
on junk except as identical junk happens to be adjacent to an interesting
match.
Here's the same example as before, but considering blanks to be junk. That
prevents ``' abcd'`` from matching the ``' abcd'`` at the tail end of the
second sequence directly. Instead only the ``'abcd'`` can match, and
matches the leftmost ``'abcd'`` in the second sequence:
>>> s = SequenceMatcher(lambda x: x==" ", " abcd", "abcd abcd")
>>> s.find_longest_match(0, 5, 0, 9)
Match(a=1, b=0, size=4)
If no blocks match, this returns ``(alo, blo, 0)``.
.. versionchanged:: 2.6
This method returns a :term:`named tuple` ``Match(a, b, size)``.
.. method:: get_matching_blocks()
Return list of triples describing non-overlapping matching subsequences.
Each triple is of the form ``(i, j, n)``,
and means that ``a[i:i+n] == b[j:j+n]``. The
triples are monotonically increasing in *i* and *j*.
The last triple is a dummy, and has the value ``(len(a), len(b), 0)``. It
is the only triple with ``n == 0``. If ``(i, j, n)`` and ``(i', j', n')``
are adjacent triples in the list, and the second is not the last triple in
the list, then ``i+n < i'`` or ``j+n < j'``; in other words, adjacent
triples always describe non-adjacent equal blocks.
.. XXX Explain why a dummy is used!
.. versionchanged:: 2.5
The guarantee that adjacent triples always describe non-adjacent blocks
was implemented.
.. doctest::
>>> s = SequenceMatcher(None, "abxcd", "abcd")
>>> s.get_matching_blocks()
[Match(a=0, b=0, size=2), Match(a=3, b=2, size=2), Match(a=5, b=4, size=0)]
.. method:: get_opcodes()
Return list of 5-tuples describing how to turn *a* into *b*. Each tuple is
of the form ``(tag, i1, i2, j1, j2)``. The first tuple has ``i1 == j1 ==
0``, and remaining tuples have *i1* equal to the *i2* from the preceding
tuple, and, likewise, *j1* equal to the previous *j2*.
The *tag* values are strings, with these meanings:
+---------------+---------------------------------------------+
| Value | Meaning |
+===============+=============================================+
| ``'replace'`` | ``a[i1:i2]`` should be replaced by |
| | ``b[j1:j2]``. |
+---------------+---------------------------------------------+
| ``'delete'`` | ``a[i1:i2]`` should be deleted. Note that |
| | ``j1 == j2`` in this case. |
+---------------+---------------------------------------------+
| ``'insert'`` | ``b[j1:j2]`` should be inserted at |
| | ``a[i1:i1]``. Note that ``i1 == i2`` in |
| | this case. |
+---------------+---------------------------------------------+
| ``'equal'`` | ``a[i1:i2] == b[j1:j2]`` (the sub-sequences |
| | are equal). |
+---------------+---------------------------------------------+
For example:
>>> a = "qabxcd"
>>> b = "abycdf"
>>> s = SequenceMatcher(None, a, b)
>>> for tag, i1, i2, j1, j2 in s.get_opcodes():
... print ("%7s a[%d:%d] (%s) b[%d:%d] (%s)" %
... (tag, i1, i2, a[i1:i2], j1, j2, b[j1:j2]))
delete a[0:1] (q) b[0:0] ()
equal a[1:3] (ab) b[0:2] (ab)
replace a[3:4] (x) b[2:3] (y)
equal a[4:6] (cd) b[3:5] (cd)
insert a[6:6] () b[5:6] (f)
.. method:: get_grouped_opcodes([n])
Return a :term:`generator` of groups with up to *n* lines of context.
Starting with the groups returned by :meth:`get_opcodes`, this method
splits out smaller change clusters and eliminates intervening ranges which
have no changes.
The groups are returned in the same format as :meth:`get_opcodes`.
.. versionadded:: 2.3
.. method:: ratio()
Return a measure of the sequences' similarity as a float in the range [0,
1].
Where T is the total number of elements in both sequences, and M is the
number of matches, this is 2.0\*M / T. Note that this is ``1.0`` if the
sequences are identical, and ``0.0`` if they have nothing in common.
This is expensive to compute if :meth:`get_matching_blocks` or
:meth:`get_opcodes` hasn't already been called, in which case you may want
to try :meth:`quick_ratio` or :meth:`real_quick_ratio` first to get an
upper bound.
.. method:: quick_ratio()
Return an upper bound on :meth:`ratio` relatively quickly.
.. method:: real_quick_ratio()
Return an upper bound on :meth:`ratio` very quickly.
The three methods that return the ratio of matching to total characters can give
different results due to differing levels of approximation, although
:meth:`quick_ratio` and :meth:`real_quick_ratio` are always at least as large as
:meth:`ratio`:
>>> s = SequenceMatcher(None, "abcd", "bcde")
>>> s.ratio()
0.75
>>> s.quick_ratio()
0.75
>>> s.real_quick_ratio()
1.0
.. _sequencematcher-examples:
SequenceMatcher Examples
------------------------
This example compares two strings, considering blanks to be "junk:"
>>> s = SequenceMatcher(lambda x: x == " ",
... "private Thread currentThread;",
... "private volatile Thread currentThread;")
:meth:`ratio` returns a float in [0, 1], measuring the similarity of the
sequences. As a rule of thumb, a :meth:`ratio` value over 0.6 means the
sequences are close matches:
>>> print round(s.ratio(), 3)
0.866
If you're only interested in where the sequences match,
:meth:`get_matching_blocks` is handy:
>>> for block in s.get_matching_blocks():
... print "a[%d] and b[%d] match for %d elements" % block
a[0] and b[0] match for 8 elements
a[8] and b[17] match for 21 elements
a[29] and b[38] match for 0 elements
Note that the last tuple returned by :meth:`get_matching_blocks` is always a
dummy, ``(len(a), len(b), 0)``, and this is the only case in which the last
tuple element (number of elements matched) is ``0``.
If you want to know how to change the first sequence into the second, use
:meth:`get_opcodes`:
>>> for opcode in s.get_opcodes():
... print "%6s a[%d:%d] b[%d:%d]" % opcode
equal a[0:8] b[0:8]
insert a[8:8] b[8:17]
equal a[8:29] b[17:38]
.. seealso::
* The :func:`get_close_matches` function in this module which shows how
simple code building on :class:`SequenceMatcher` can be used to do useful
work.
* `Simple version control recipe
<https://code.activestate.com/recipes/576729/>`_ for a small application
built with :class:`SequenceMatcher`.
.. _differ-objects:
Differ Objects
--------------
Note that :class:`Differ`\ -generated deltas make no claim to be **minimal**
diffs. To the contrary, minimal diffs are often counter-intuitive, because they
synch up anywhere possible, sometimes accidental matches 100 pages apart.
Restricting synch points to contiguous matches preserves some notion of
locality, at the occasional cost of producing a longer diff.
The :class:`Differ` class has this constructor:
.. class:: Differ([linejunk[, charjunk]])
Optional keyword parameters *linejunk* and *charjunk* are for filter functions
(or ``None``):
*linejunk*: A function that accepts a single string argument, and returns true
if the string is junk. The default is ``None``, meaning that no line is
considered junk.
*charjunk*: A function that accepts a single character argument (a string of
length 1), and returns true if the character is junk. The default is ``None``,
meaning that no character is considered junk.
:class:`Differ` objects are used (deltas generated) via a single method:
.. method:: Differ.compare(a, b)
Compare two sequences of lines, and generate the delta (a sequence of lines).
Each sequence must contain individual single-line strings ending with
newlines. Such sequences can be obtained from the
:meth:`~file.readlines` method of file-like objects. The delta
generated also consists of newline-terminated strings, ready to be
printed as-is via the :meth:`~file.writelines` method of a
file-like object.
.. _differ-examples:
Differ Example
--------------
This example compares two texts. First we set up the texts, sequences of
individual single-line strings ending with newlines (such sequences can also be
obtained from the :meth:`~file.readlines` method of file-like objects):
>>> text1 = ''' 1. Beautiful is better than ugly.
... 2. Explicit is better than implicit.
... 3. Simple is better than complex.
... 4. Complex is better than complicated.
... '''.splitlines(1)
>>> len(text1)
4
>>> text1[0][-1]
'\n'
>>> text2 = ''' 1. Beautiful is better than ugly.
... 3. Simple is better than complex.
... 4. Complicated is better than complex.
... 5. Flat is better than nested.
... '''.splitlines(1)
Next we instantiate a Differ object:
>>> d = Differ()
Note that when instantiating a :class:`Differ` object we may pass functions to
filter out line and character "junk." See the :meth:`Differ` constructor for
details.
Finally, we compare the two:
>>> result = list(d.compare(text1, text2))
``result`` is a list of strings, so let's pretty-print it:
>>> from pprint import pprint
>>> pprint(result)
[' 1. Beautiful is better than ugly.\n',
'- 2. Explicit is better than implicit.\n',
'- 3. Simple is better than complex.\n',
'+ 3. Simple is better than complex.\n',
'? ++\n',
'- 4. Complex is better than complicated.\n',
'? ^ ---- ^\n',
'+ 4. Complicated is better than complex.\n',
'? ++++ ^ ^\n',
'+ 5. Flat is better than nested.\n']
As a single multi-line string it looks like this:
>>> import sys
>>> sys.stdout.writelines(result)
1. Beautiful is better than ugly.
- 2. Explicit is better than implicit.
- 3. Simple is better than complex.
+ 3. Simple is better than complex.
? ++
- 4. Complex is better than complicated.
? ^ ---- ^
+ 4. Complicated is better than complex.
? ++++ ^ ^
+ 5. Flat is better than nested.
.. _difflib-interface:
A command-line interface to difflib
-----------------------------------
This example shows how to use difflib to create a ``diff``-like utility.
It is also contained in the Python source distribution, as
:file:`Tools/scripts/diff.py`.
.. testcode::
""" Command line interface to difflib.py providing diffs in four formats:
* ndiff: lists every line and highlights interline changes.
* context: highlights clusters of changes in a before/after format.
* unified: highlights clusters of changes in an inline format.
* html: generates side by side comparison with change highlights.
"""
import sys, os, time, difflib, optparse
def main():
# Configure the option parser
usage = "usage: %prog [options] fromfile tofile"
parser = optparse.OptionParser(usage)
parser.add_option("-c", action="store_true", default=False,
help='Produce a context format diff (default)')
parser.add_option("-u", action="store_true", default=False,
help='Produce a unified format diff')
hlp = 'Produce HTML side by side diff (can use -c and -l in conjunction)'
parser.add_option("-m", action="store_true", default=False, help=hlp)
parser.add_option("-n", action="store_true", default=False,
help='Produce a ndiff format diff')
parser.add_option("-l", "--lines", type="int", default=3,
help='Set number of context lines (default 3)')
(options, args) = parser.parse_args()
if len(args) == 0:
parser.print_help()
sys.exit(1)
if len(args) != 2:
parser.error("need to specify both a fromfile and tofile")
n = options.lines
fromfile, tofile = args # as specified in the usage string
# we're passing these as arguments to the diff function
fromdate = time.ctime(os.stat(fromfile).st_mtime)
todate = time.ctime(os.stat(tofile).st_mtime)
with open(fromfile, 'U') as f:
fromlines = f.readlines()
with open(tofile, 'U') as f:
tolines = f.readlines()
if options.u:
diff = difflib.unified_diff(fromlines, tolines, fromfile, tofile,
fromdate, todate, n=n)
elif options.n:
diff = difflib.ndiff(fromlines, tolines)
elif options.m:
diff = difflib.HtmlDiff().make_file(fromlines, tolines, fromfile,
tofile, context=options.c,
numlines=n)
else:
diff = difflib.context_diff(fromlines, tolines, fromfile, tofile,
fromdate, todate, n=n)
# we're using writelines because diff is a generator
sys.stdout.writelines(diff)
if __name__ == '__main__':
main()
PK %�\�$� & html/_sources/library/dircache.rst.txtnu �[���
:mod:`dircache` --- Cached directory listings
=============================================
.. module:: dircache
:synopsis: Return directory listing, with cache mechanism.
:deprecated:
.. deprecated:: 2.6
The :mod:`dircache` module has been removed in Python 3.
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
The :mod:`dircache` module defines a function for reading directory listing
using a cache, and cache invalidation using the *mtime* of the directory.
Additionally, it defines a function to annotate directories by appending a
slash.
The :mod:`dircache` module defines the following functions:
.. function:: reset()
Resets the directory cache.
.. function:: listdir(path)
Return a directory listing of *path*, as gotten from :func:`os.listdir`. Note
that unless *path* changes, further call to :func:`listdir` will not re-read the
directory structure.
Note that the list returned should be regarded as read-only. (Perhaps a future
version should change it to return a tuple?)
.. function:: opendir(path)
Same as :func:`listdir`. Defined for backwards compatibility.
.. function:: annotate(head, list)
Assume *list* is a list of paths relative to *head*, and append, in place, a
``'/'`` to each path which points to a directory.
::
>>> import dircache
>>> a = dircache.listdir('/')
>>> a = a[:] # Copy the return value so we can change 'a'
>>> a
['bin', 'boot', 'cdrom', 'dev', 'etc', 'floppy', 'home', 'initrd', 'lib', 'lost+
found', 'mnt', 'proc', 'root', 'sbin', 'tmp', 'usr', 'var', 'vmlinuz']
>>> dircache.annotate('/', a)
>>> a
['bin/', 'boot/', 'cdrom/', 'dev/', 'etc/', 'floppy/', 'home/', 'initrd/', 'lib/
', 'lost+found/', 'mnt/', 'proc/', 'root/', 'sbin/', 'tmp/', 'usr/', 'var/', 'vm
linuz']
PK %�\: 4f�Z �Z ! html/_sources/library/dis.rst.txtnu �[��� :mod:`dis` --- Disassembler for Python bytecode
===============================================
.. module:: dis
:synopsis: Disassembler for Python bytecode.
**Source code:** :source:`Lib/dis.py`
--------------
The :mod:`dis` module supports the analysis of CPython :term:`bytecode` by
disassembling it. The CPython bytecode which this module takes as an input is
defined in the file :file:`Include/opcode.h` and used by the compiler and the
interpreter.
.. impl-detail::
Bytecode is an implementation detail of the CPython interpreter! No
guarantees are made that bytecode will not be added, removed, or changed
between versions of Python. Use of this module should not be considered to
work across Python VMs or Python releases.
Example: Given the function :func:`myfunc`::
def myfunc(alist):
return len(alist)
the following command can be used to get the disassembly of :func:`myfunc`::
>>> dis.dis(myfunc)
2 0 LOAD_GLOBAL 0 (len)
3 LOAD_FAST 0 (alist)
6 CALL_FUNCTION 1
9 RETURN_VALUE
(The "2" is a line number).
The :mod:`dis` module defines the following functions and constants:
.. function:: dis([bytesource])
Disassemble the *bytesource* object. *bytesource* can denote either a module,
a class, a method, a function, or a code object. For a module, it
disassembles all functions. For a class, it disassembles all methods. For a
single code sequence, it prints one line per bytecode instruction. If no
object is provided, it disassembles the last traceback.
.. function:: distb([tb])
Disassembles the top-of-stack function of a traceback, using the last
traceback if none was passed. The instruction causing the exception is
indicated.
.. function:: disassemble(code[, lasti])
Disassembles a code object, indicating the last instruction if *lasti* was
provided. The output is divided in the following columns:
#. the line number, for the first instruction of each line
#. the current instruction, indicated as ``-->``,
#. a labelled instruction, indicated with ``>>``,
#. the address of the instruction,
#. the operation code name,
#. operation parameters, and
#. interpretation of the parameters in parentheses.
The parameter interpretation recognizes local and global variable names,
constant values, branch targets, and compare operators.
.. function:: disco(code[, lasti])
A synonym for :func:`disassemble`. It is more convenient to type, and kept
for compatibility with earlier Python releases.
.. function:: findlinestarts(code)
This generator function uses the ``co_firstlineno`` and ``co_lnotab``
attributes of the code object *code* to find the offsets which are starts of
lines in the source code. They are generated as ``(offset, lineno)`` pairs.
.. function:: findlabels(code)
Detect all offsets in the code object *code* which are jump targets, and
return a list of these offsets.
.. data:: opname
Sequence of operation names, indexable using the bytecode.
.. data:: opmap
Dictionary mapping operation names to bytecodes.
.. data:: cmp_op
Sequence of all compare operation names.
.. data:: hasconst
Sequence of bytecodes that access a constant.
.. data:: hasfree
Sequence of bytecodes that access a free variable.
.. data:: hasname
Sequence of bytecodes that access an attribute by name.
.. data:: hasjrel
Sequence of bytecodes that have a relative jump target.
.. data:: hasjabs
Sequence of bytecodes that have an absolute jump target.
.. data:: haslocal
Sequence of bytecodes that access a local variable.
.. data:: hascompare
Sequence of bytecodes of Boolean operations.
.. _bytecodes:
Python Bytecode Instructions
----------------------------
The Python compiler currently generates the following bytecode instructions.
.. opcode:: STOP_CODE ()
Indicates end-of-code to the compiler, not used by the interpreter.
.. opcode:: NOP ()
Do nothing code. Used as a placeholder by the bytecode optimizer.
.. opcode:: POP_TOP ()
Removes the top-of-stack (TOS) item.
.. opcode:: ROT_TWO ()
Swaps the two top-most stack items.
.. opcode:: ROT_THREE ()
Lifts second and third stack item one position up, moves top down to position
three.
.. opcode:: ROT_FOUR ()
Lifts second, third and forth stack item one position up, moves top down to
position four.
.. opcode:: DUP_TOP ()
Duplicates the reference on top of the stack.
Unary Operations take the top of the stack, apply the operation, and push the
result back on the stack.
.. opcode:: UNARY_POSITIVE ()
Implements ``TOS = +TOS``.
.. opcode:: UNARY_NEGATIVE ()
Implements ``TOS = -TOS``.
.. opcode:: UNARY_NOT ()
Implements ``TOS = not TOS``.
.. opcode:: UNARY_CONVERT ()
Implements ``TOS = `TOS```.
.. opcode:: UNARY_INVERT ()
Implements ``TOS = ~TOS``.
.. opcode:: GET_ITER ()
Implements ``TOS = iter(TOS)``.
Binary operations remove the top of the stack (TOS) and the second top-most
stack item (TOS1) from the stack. They perform the operation, and put the
result back on the stack.
.. opcode:: BINARY_POWER ()
Implements ``TOS = TOS1 ** TOS``.
.. opcode:: BINARY_MULTIPLY ()
Implements ``TOS = TOS1 * TOS``.
.. opcode:: BINARY_DIVIDE ()
Implements ``TOS = TOS1 / TOS`` when ``from __future__ import division`` is
not in effect.
.. opcode:: BINARY_FLOOR_DIVIDE ()
Implements ``TOS = TOS1 // TOS``.
.. opcode:: BINARY_TRUE_DIVIDE ()
Implements ``TOS = TOS1 / TOS`` when ``from __future__ import division`` is
in effect.
.. opcode:: BINARY_MODULO ()
Implements ``TOS = TOS1 % TOS``.
.. opcode:: BINARY_ADD ()
Implements ``TOS = TOS1 + TOS``.
.. opcode:: BINARY_SUBTRACT ()
Implements ``TOS = TOS1 - TOS``.
.. opcode:: BINARY_SUBSCR ()
Implements ``TOS = TOS1[TOS]``.
.. opcode:: BINARY_LSHIFT ()
Implements ``TOS = TOS1 << TOS``.
.. opcode:: BINARY_RSHIFT ()
Implements ``TOS = TOS1 >> TOS``.
.. opcode:: BINARY_AND ()
Implements ``TOS = TOS1 & TOS``.
.. opcode:: BINARY_XOR ()
Implements ``TOS = TOS1 ^ TOS``.
.. opcode:: BINARY_OR ()
Implements ``TOS = TOS1 | TOS``.
In-place operations are like binary operations, in that they remove TOS and
TOS1, and push the result back on the stack, but the operation is done in-place
when TOS1 supports it, and the resulting TOS may be (but does not have to be)
the original TOS1.
.. opcode:: INPLACE_POWER ()
Implements in-place ``TOS = TOS1 ** TOS``.
.. opcode:: INPLACE_MULTIPLY ()
Implements in-place ``TOS = TOS1 * TOS``.
.. opcode:: INPLACE_DIVIDE ()
Implements in-place ``TOS = TOS1 / TOS`` when ``from __future__ import
division`` is not in effect.
.. opcode:: INPLACE_FLOOR_DIVIDE ()
Implements in-place ``TOS = TOS1 // TOS``.
.. opcode:: INPLACE_TRUE_DIVIDE ()
Implements in-place ``TOS = TOS1 / TOS`` when ``from __future__ import
division`` is in effect.
.. opcode:: INPLACE_MODULO ()
Implements in-place ``TOS = TOS1 % TOS``.
.. opcode:: INPLACE_ADD ()
Implements in-place ``TOS = TOS1 + TOS``.
.. opcode:: INPLACE_SUBTRACT ()
Implements in-place ``TOS = TOS1 - TOS``.
.. opcode:: INPLACE_LSHIFT ()
Implements in-place ``TOS = TOS1 << TOS``.
.. opcode:: INPLACE_RSHIFT ()
Implements in-place ``TOS = TOS1 >> TOS``.
.. opcode:: INPLACE_AND ()
Implements in-place ``TOS = TOS1 & TOS``.
.. opcode:: INPLACE_XOR ()
Implements in-place ``TOS = TOS1 ^ TOS``.
.. opcode:: INPLACE_OR ()
Implements in-place ``TOS = TOS1 | TOS``.
The slice opcodes take up to three parameters.
.. opcode:: SLICE+0 ()
Implements ``TOS = TOS[:]``.
.. opcode:: SLICE+1 ()
Implements ``TOS = TOS1[TOS:]``.
.. opcode:: SLICE+2 ()
Implements ``TOS = TOS1[:TOS]``.
.. opcode:: SLICE+3 ()
Implements ``TOS = TOS2[TOS1:TOS]``.
Slice assignment needs even an additional parameter. As any statement, they put
nothing on the stack.
.. opcode:: STORE_SLICE+0 ()
Implements ``TOS[:] = TOS1``.
.. opcode:: STORE_SLICE+1 ()
Implements ``TOS1[TOS:] = TOS2``.
.. opcode:: STORE_SLICE+2 ()
Implements ``TOS1[:TOS] = TOS2``.
.. opcode:: STORE_SLICE+3 ()
Implements ``TOS2[TOS1:TOS] = TOS3``.
.. opcode:: DELETE_SLICE+0 ()
Implements ``del TOS[:]``.
.. opcode:: DELETE_SLICE+1 ()
Implements ``del TOS1[TOS:]``.
.. opcode:: DELETE_SLICE+2 ()
Implements ``del TOS1[:TOS]``.
.. opcode:: DELETE_SLICE+3 ()
Implements ``del TOS2[TOS1:TOS]``.
.. opcode:: STORE_SUBSCR ()
Implements ``TOS1[TOS] = TOS2``.
.. opcode:: DELETE_SUBSCR ()
Implements ``del TOS1[TOS]``.
Miscellaneous opcodes.
.. opcode:: PRINT_EXPR ()
Implements the expression statement for the interactive mode. TOS is removed
from the stack and printed. In non-interactive mode, an expression statement
is terminated with :opcode:`POP_TOP`.
.. opcode:: PRINT_ITEM ()
Prints TOS to the file-like object bound to ``sys.stdout``. There is one
such instruction for each item in the :keyword:`print` statement.
.. opcode:: PRINT_ITEM_TO ()
Like ``PRINT_ITEM``, but prints the item second from TOS to the file-like
object at TOS. This is used by the extended print statement.
.. opcode:: PRINT_NEWLINE ()
Prints a new line on ``sys.stdout``. This is generated as the last operation
of a :keyword:`print` statement, unless the statement ends with a comma.
.. opcode:: PRINT_NEWLINE_TO ()
Like ``PRINT_NEWLINE``, but prints the new line on the file-like object on
the TOS. This is used by the extended print statement.
.. opcode:: BREAK_LOOP ()
Terminates a loop due to a :keyword:`break` statement.
.. opcode:: CONTINUE_LOOP (target)
Continues a loop due to a :keyword:`continue` statement. *target* is the
address to jump to (which should be a :opcode:`FOR_ITER` instruction).
.. opcode:: LIST_APPEND (i)
Calls ``list.append(TOS[-i], TOS)``. Used to implement list comprehensions.
While the appended value is popped off, the list object remains on the stack
so that it is available for further iterations of the loop.
.. opcode:: LOAD_LOCALS ()
Pushes a reference to the locals of the current scope on the stack. This is
used in the code for a class definition: After the class body is evaluated,
the locals are passed to the class definition.
.. opcode:: RETURN_VALUE ()
Returns with TOS to the caller of the function.
.. opcode:: YIELD_VALUE ()
Pops ``TOS`` and yields it from a :term:`generator`.
.. opcode:: IMPORT_STAR ()
Loads all symbols not starting with ``'_'`` directly from the module TOS to
the local namespace. The module is popped after loading all names. This
opcode implements ``from module import *``.
.. opcode:: EXEC_STMT ()
Implements ``exec TOS2,TOS1,TOS``. The compiler fills missing optional
parameters with ``None``.
.. opcode:: POP_BLOCK ()
Removes one block from the block stack. Per frame, there is a stack of
blocks, denoting nested loops, try statements, and such.
.. opcode:: END_FINALLY ()
Terminates a :keyword:`finally` clause. The interpreter recalls whether the
exception has to be re-raised, or whether the function returns, and continues
with the outer-next block.
.. opcode:: BUILD_CLASS ()
Creates a new class object. TOS is the methods dictionary, TOS1 the tuple of
the names of the base classes, and TOS2 the class name.
.. opcode:: SETUP_WITH (delta)
This opcode performs several operations before a with block starts. First,
it loads :meth:`~object.__exit__` from the context manager and pushes it onto
the stack for later use by :opcode:`WITH_CLEANUP`. Then,
:meth:`~object.__enter__` is called, and a finally block pointing to *delta*
is pushed. Finally, the result of calling the enter method is pushed onto
the stack. The next opcode will either ignore it (:opcode:`POP_TOP`), or
store it in (a) variable(s) (:opcode:`STORE_FAST`, :opcode:`STORE_NAME`, or
:opcode:`UNPACK_SEQUENCE`).
.. opcode:: WITH_CLEANUP ()
Cleans up the stack when a :keyword:`with` statement block exits. On top of
the stack are 1--3 values indicating how/why the finally clause was entered:
* TOP = ``None``
* (TOP, SECOND) = (``WHY_{RETURN,CONTINUE}``), retval
* TOP = ``WHY_*``; no retval below it
* (TOP, SECOND, THIRD) = exc_info()
Under them is EXIT, the context manager's :meth:`__exit__` bound method.
In the last case, ``EXIT(TOP, SECOND, THIRD)`` is called, otherwise
``EXIT(None, None, None)``.
EXIT is removed from the stack, leaving the values above it in the same
order. In addition, if the stack represents an exception, *and* the function
call returns a 'true' value, this information is "zapped", to prevent
``END_FINALLY`` from re-raising the exception. (But non-local gotos should
still be resumed.)
.. XXX explain the WHY stuff!
All of the following opcodes expect arguments. An argument is two bytes, with
the more significant byte last.
.. opcode:: STORE_NAME (namei)
Implements ``name = TOS``. *namei* is the index of *name* in the attribute
:attr:`co_names` of the code object. The compiler tries to use ``STORE_FAST``
or ``STORE_GLOBAL`` if possible.
.. opcode:: DELETE_NAME (namei)
Implements ``del name``, where *namei* is the index into :attr:`co_names`
attribute of the code object.
.. opcode:: UNPACK_SEQUENCE (count)
Unpacks TOS into *count* individual values, which are put onto the stack
right-to-left.
.. opcode:: DUP_TOPX (count)
Duplicate *count* items, keeping them in the same order. Due to
implementation limits, *count* should be between 1 and 5 inclusive.
.. opcode:: STORE_ATTR (namei)
Implements ``TOS.name = TOS1``, where *namei* is the index of name in
:attr:`co_names`.
.. opcode:: DELETE_ATTR (namei)
Implements ``del TOS.name``, using *namei* as index into :attr:`co_names`.
.. opcode:: STORE_GLOBAL (namei)
Works as ``STORE_NAME``, but stores the name as a global.
.. opcode:: DELETE_GLOBAL (namei)
Works as ``DELETE_NAME``, but deletes a global name.
.. opcode:: LOAD_CONST (consti)
Pushes ``co_consts[consti]`` onto the stack.
.. opcode:: LOAD_NAME (namei)
Pushes the value associated with ``co_names[namei]`` onto the stack.
.. opcode:: BUILD_TUPLE (count)
Creates a tuple consuming *count* items from the stack, and pushes the
resulting tuple onto the stack.
.. opcode:: BUILD_LIST (count)
Works as ``BUILD_TUPLE``, but creates a list.
.. opcode:: BUILD_SET (count)
Works as ``BUILD_TUPLE``, but creates a set.
.. versionadded:: 2.7
.. opcode:: BUILD_MAP (count)
Pushes a new dictionary object onto the stack. The dictionary is pre-sized
to hold *count* entries.
.. opcode:: LOAD_ATTR (namei)
Replaces TOS with ``getattr(TOS, co_names[namei])``.
.. opcode:: COMPARE_OP (opname)
Performs a Boolean operation. The operation name can be found in
``cmp_op[opname]``.
.. opcode:: IMPORT_NAME (namei)
Imports the module ``co_names[namei]``. TOS and TOS1 are popped and provide
the *fromlist* and *level* arguments of :func:`__import__`. The module
object is pushed onto the stack. The current namespace is not affected: for
a proper import statement, a subsequent ``STORE_FAST`` instruction modifies
the namespace.
.. opcode:: IMPORT_FROM (namei)
Loads the attribute ``co_names[namei]`` from the module found in TOS. The
resulting object is pushed onto the stack, to be subsequently stored by a
``STORE_FAST`` instruction.
.. opcode:: JUMP_FORWARD (delta)
Increments bytecode counter by *delta*.
.. opcode:: POP_JUMP_IF_TRUE (target)
If TOS is true, sets the bytecode counter to *target*. TOS is popped.
.. opcode:: POP_JUMP_IF_FALSE (target)
If TOS is false, sets the bytecode counter to *target*. TOS is popped.
.. opcode:: JUMP_IF_TRUE_OR_POP (target)
If TOS is true, sets the bytecode counter to *target* and leaves TOS on the
stack. Otherwise (TOS is false), TOS is popped.
.. opcode:: JUMP_IF_FALSE_OR_POP (target)
If TOS is false, sets the bytecode counter to *target* and leaves TOS on the
stack. Otherwise (TOS is true), TOS is popped.
.. opcode:: JUMP_ABSOLUTE (target)
Set bytecode counter to *target*.
.. opcode:: FOR_ITER (delta)
``TOS`` is an :term:`iterator`. Call its :meth:`!next` method. If this
yields a new value, push it on the stack (leaving the iterator below it). If
the iterator indicates it is exhausted ``TOS`` is popped, and the bytecode
counter is incremented by *delta*.
.. opcode:: LOAD_GLOBAL (namei)
Loads the global named ``co_names[namei]`` onto the stack.
.. opcode:: SETUP_LOOP (delta)
Pushes a block for a loop onto the block stack. The block spans from the
current instruction with a size of *delta* bytes.
.. opcode:: SETUP_EXCEPT (delta)
Pushes a try block from a try-except clause onto the block stack. *delta*
points to the first except block.
.. opcode:: SETUP_FINALLY (delta)
Pushes a try block from a try-except clause onto the block stack. *delta*
points to the finally block.
.. opcode:: STORE_MAP ()
Store a key and value pair in a dictionary. Pops the key and value while
leaving the dictionary on the stack.
.. opcode:: LOAD_FAST (var_num)
Pushes a reference to the local ``co_varnames[var_num]`` onto the stack.
.. opcode:: STORE_FAST (var_num)
Stores TOS into the local ``co_varnames[var_num]``.
.. opcode:: DELETE_FAST (var_num)
Deletes local ``co_varnames[var_num]``.
.. opcode:: LOAD_CLOSURE (i)
Pushes a reference to the cell contained in slot *i* of the cell and free
variable storage. The name of the variable is ``co_cellvars[i]`` if *i* is
less than the length of *co_cellvars*. Otherwise it is ``co_freevars[i -
len(co_cellvars)]``.
.. opcode:: LOAD_DEREF (i)
Loads the cell contained in slot *i* of the cell and free variable storage.
Pushes a reference to the object the cell contains on the stack.
.. opcode:: STORE_DEREF (i)
Stores TOS into the cell contained in slot *i* of the cell and free variable
storage.
.. opcode:: SET_LINENO (lineno)
This opcode is obsolete.
.. opcode:: RAISE_VARARGS (argc)
Raises an exception. *argc* indicates the number of arguments to the raise
statement, ranging from 0 to 3. The handler will find the traceback as TOS2,
the parameter as TOS1, and the exception as TOS.
.. opcode:: CALL_FUNCTION (argc)
Calls a callable object. The low byte of *argc* indicates the number of
positional arguments, the high byte the number of keyword arguments.
The stack contains keyword arguments on top (if any), then the positional
arguments below that (if any), then the callable object to call below that.
Each keyword argument is represented with two values on the stack:
the argument's name, and its value, with the argument's value above the
name on the stack.
The positional arguments are pushed in the order that they are passed in
to the callable object, with the right-most positional argument on top.
``CALL_FUNCTION`` pops all arguments and the callable object off the stack,
calls the callable object with those arguments, and pushes the return value
returned by the callable object.
.. opcode:: MAKE_FUNCTION (argc)
Pushes a new function object on the stack. TOS is the code associated with
the function. The function object is defined to have *argc* default
parameters, which are found below TOS.
.. opcode:: MAKE_CLOSURE (argc)
Creates a new function object, sets its *func_closure* slot, and pushes it on
the stack. TOS is the code associated with the function, TOS1 the tuple
containing cells for the closure's free variables. The function also has
*argc* default parameters, which are found below the cells.
.. opcode:: BUILD_SLICE (argc)
.. index:: builtin: slice
Pushes a slice object on the stack. *argc* must be 2 or 3. If it is 2,
``slice(TOS1, TOS)`` is pushed; if it is 3, ``slice(TOS2, TOS1, TOS)`` is
pushed. See the :func:`slice` built-in function for more information.
.. opcode:: EXTENDED_ARG (ext)
Prefixes any opcode which has an argument too big to fit into the default two
bytes. *ext* holds two additional bytes which, taken together with the
subsequent opcode's argument, comprise a four-byte argument, *ext* being the
two most-significant bytes.
.. opcode:: CALL_FUNCTION_VAR (argc)
Calls a callable object, similarly to :opcode:`CALL_FUNCTION`.
*argc* represents the number of keyword and positional
arguments, identically to :opcode:`CALL_FUNCTION`.
The top of the stack contains an iterable object containing
additional positional arguments.
Below that are keyword arguments (if any), positional arguments (if any)
and a callable object, identically to :opcode:`CALL_FUNCTION`.
Before the callable object is called, the iterable object
is "unpacked" and its contents are appended to the positional
arguments passed in.
The iterable object is ignored when computing
the value of ``argc``.
.. opcode:: CALL_FUNCTION_KW (argc)
Calls a callable object, similarly to :opcode:`CALL_FUNCTION`.
*argc* represents the number of keyword and positional
arguments, identically to :opcode:`CALL_FUNCTION`.
The top of the stack contains a mapping object containing additional keyword
arguments.
Below that are keyword arguments (if any), positional arguments (if any)
and a callable object, identically to :opcode:`CALL_FUNCTION`.
Before the callable is called, the mapping object at the top of the stack is
"unpacked" and its contents are appended to the keyword arguments passed in.
The mapping object at the top of the stack is ignored when computing
the value of ``argc``.
.. opcode:: CALL_FUNCTION_VAR_KW (argc)
Calls a callable object, similarly to :opcode:`CALL_FUNCTION_VAR` and
:opcode:`CALL_FUNCTION_KW`.
*argc* represents the number of keyword and positional
arguments, identically to :opcode:`CALL_FUNCTION`.
The top of the stack contains a mapping object, as per
:opcode:`CALL_FUNCTION_KW`.
Below that is an iterable object, as per
:opcode:`CALL_FUNCTION_VAR`.
Below that are keyword arguments (if any), positional arguments (if any)
and a callable object, identically to :opcode:`CALL_FUNCTION`.
Before the callable is called, the mapping object and iterable object
are each "unpacked" and their contents passed in as keyword and
positional arguments respectively,
identically to :opcode:`CALL_FUNCTION_VAR` and :opcode:`CALL_FUNCTION_KW`.
The mapping object and iterable object are both ignored when computing
the value of ``argc``.
.. opcode:: HAVE_ARGUMENT ()
This is not really an opcode. It identifies the dividing line between
opcodes which don't take arguments ``< HAVE_ARGUMENT`` and those which do
``>= HAVE_ARGUMENT``.
PK %�\\�fߪ � * html/_sources/library/distribution.rst.txtnu �[��� ***********************************
Software Packaging and Distribution
***********************************
These libraries help you with publishing and installing Python software.
While these modules are designed to work in conjunction with the
`Python Package Index <https://pypi.org>`__, they can also be used
with a local index server, or without any index server at all.
.. toctree::
distutils.rst
ensurepip.rst
PK %�\�1� � ' html/_sources/library/distutils.rst.txtnu �[��� :mod:`distutils` --- Building and installing Python modules
===========================================================
.. module:: distutils
:synopsis: Support for building and installing Python modules into an
existing Python installation.
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
The :mod:`distutils` package provides support for building and installing
additional modules into a Python installation. The new modules may be either
100%-pure Python, or may be extension modules written in C, or may be
collections of Python packages which include modules coded in both Python and C.
Most Python users will *not* want to use this module directly, but instead
use the cross-version tools maintained by the Python Packaging Authority. In
particular,
`setuptools <https://setuptools.readthedocs.io/en/latest/>`__ is an
enhanced alternative to :mod:`distutils` that provides:
* support for declaring project dependencies
* additional mechanisms for configuring which files to include in source
releases (including plugins for integration with version control systems)
* the ability to declare project "entry points", which can be used as the
basis for application plugin systems
* the ability to automatically generate Windows command line executables at
installation time rather than needing to prebuild them
* consistent behaviour across all supported Python versions
The recommended `pip <https://pip.pypa.io/>`__ installer runs all
``setup.py`` scripts with ``setuptools``, even if the script itself only
imports ``distutils``. Refer to the
`Python Packaging User Guide <https://packaging.python.org>`_ for more
information.
For the benefits of packaging tool authors and users seeking a deeper
understanding of the details of the current packaging and distribution
system, the legacy :mod:`distutils` based user documentation and API
reference remain available:
* :ref:`install-index`
* :ref:`distutils-index`
PK %�\�{'e@
@
html/_sources/library/dl.rst.txtnu �[���
:mod:`dl` --- Call C functions in shared objects
================================================
.. module:: dl
:platform: Unix
:synopsis: Call C functions in shared objects.
:deprecated:
.. deprecated:: 2.6
The :mod:`dl` module has been removed in Python 3. Use the :mod:`ctypes`
module instead.
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
The :mod:`dl` module defines an interface to the :c:func:`dlopen` function, which
is the most common interface on Unix platforms for handling dynamically linked
libraries. It allows the program to call arbitrary functions in such a library.
.. warning::
The :mod:`dl` module bypasses the Python type system and error handling. If
used incorrectly it may cause segmentation faults, crashes or other incorrect
behaviour.
.. note::
This module will not work unless ``sizeof(int) == sizeof(long) == sizeof(char
*)`` If this is not the case, :exc:`SystemError` will be raised on import.
The :mod:`dl` module defines the following function:
.. function:: open(name[, mode=RTLD_LAZY])
Open a shared object file, and return a handle. Mode signifies late binding
(:const:`RTLD_LAZY`) or immediate binding (:const:`RTLD_NOW`). Default is
:const:`RTLD_LAZY`. Note that some systems do not support :const:`RTLD_NOW`.
Return value is a :class:`dlobject`.
The :mod:`dl` module defines the following constants:
.. data:: RTLD_LAZY
Useful as an argument to :func:`.open`.
.. data:: RTLD_NOW
Useful as an argument to :func:`.open`. Note that on systems which do not
support immediate binding, this constant will not appear in the module. For
maximum portability, use :func:`hasattr` to determine if the system supports
immediate binding.
The :mod:`dl` module defines the following exception:
.. exception:: error
Exception raised when an error has occurred inside the dynamic loading and
linking routines.
Example::
>>> import dl, time
>>> a=dl.open('/lib/libc.so.6')
>>> a.call('time'), time.time()
(929723914, 929723914.498)
This example was tried on a Debian GNU/Linux system, and is a good example of
the fact that using this module is usually a bad alternative.
.. _dl-objects:
Dl Objects
----------
Dl objects, as returned by :func:`.open` above, have the following methods:
.. method:: dl.close()
Free all resources, except the memory.
.. method:: dl.sym(name)
Return the pointer for the function named *name*, as a number, if it exists in
the referenced shared object, otherwise ``None``. This is useful in code like::
>>> if a.sym('time'):
... a.call('time')
... else:
... time.time()
(Note that this function will return a non-zero number, as zero is the *NULL*
pointer)
.. method:: dl.call(name[, arg1[, arg2...]])
Call the function named *name* in the referenced shared object. The arguments
must be either Python integers, which will be passed as is, Python strings, to
which a pointer will be passed, or ``None``, which will be passed as *NULL*.
Note that strings should only be passed to functions as :c:type:`const char\*`,
as Python will not like its string mutated.
There must be at most 10 arguments, and arguments not given will be treated as
``None``. The function's return value must be a C :c:type:`long`, which is a
Python integer.
PK %�\5��8! ! % html/_sources/library/doctest.rst.txtnu �[��� :keepdoctest:
:mod:`doctest` --- Test interactive Python examples
===================================================
.. module:: doctest
:synopsis: Test pieces of code within docstrings.
.. moduleauthor:: Tim Peters <tim@python.org>
.. sectionauthor:: Tim Peters <tim@python.org>
.. sectionauthor:: Moshe Zadka <moshez@debian.org>
.. sectionauthor:: Edward Loper <edloper@users.sourceforge.net>
The :mod:`doctest` module searches for pieces of text that look like interactive
Python sessions, and then executes those sessions to verify that they work
exactly as shown. There are several common ways to use doctest:
* To check that a module's docstrings are up-to-date by verifying that all
interactive examples still work as documented.
* To perform regression testing by verifying that interactive examples from a
test file or a test object work as expected.
* To write tutorial documentation for a package, liberally illustrated with
input-output examples. Depending on whether the examples or the expository text
are emphasized, this has the flavor of "literate testing" or "executable
documentation".
Here's a complete but small example module::
"""
This is the "example" module.
The example module supplies one function, factorial(). For example,
>>> factorial(5)
120
"""
def factorial(n):
"""Return the factorial of n, an exact integer >= 0.
If the result is small enough to fit in an int, return an int.
Else return a long.
>>> [factorial(n) for n in range(6)]
[1, 1, 2, 6, 24, 120]
>>> [factorial(long(n)) for n in range(6)]
[1, 1, 2, 6, 24, 120]
>>> factorial(30)
265252859812191058636308480000000L
>>> factorial(30L)
265252859812191058636308480000000L
>>> factorial(-1)
Traceback (most recent call last):
...
ValueError: n must be >= 0
Factorials of floats are OK, but the float must be an exact integer:
>>> factorial(30.1)
Traceback (most recent call last):
...
ValueError: n must be exact integer
>>> factorial(30.0)
265252859812191058636308480000000L
It must also not be ridiculously large:
>>> factorial(1e100)
Traceback (most recent call last):
...
OverflowError: n too large
"""
import math
if not n >= 0:
raise ValueError("n must be >= 0")
if math.floor(n) != n:
raise ValueError("n must be exact integer")
if n+1 == n: # catch a value like 1e300
raise OverflowError("n too large")
result = 1
factor = 2
while factor <= n:
result *= factor
factor += 1
return result
if __name__ == "__main__":
import doctest
doctest.testmod()
If you run :file:`example.py` directly from the command line, :mod:`doctest`
works its magic:
.. code-block:: shell-session
$ python example.py
$
There's no output! That's normal, and it means all the examples worked. Pass
``-v`` to the script, and :mod:`doctest` prints a detailed log of what
it's trying, and prints a summary at the end:
.. code-block:: shell-session
$ python example.py -v
Trying:
factorial(5)
Expecting:
120
ok
Trying:
[factorial(n) for n in range(6)]
Expecting:
[1, 1, 2, 6, 24, 120]
ok
Trying:
[factorial(long(n)) for n in range(6)]
Expecting:
[1, 1, 2, 6, 24, 120]
ok
And so on, eventually ending with:
.. code-block:: none
Trying:
factorial(1e100)
Expecting:
Traceback (most recent call last):
...
OverflowError: n too large
ok
2 items passed all tests:
1 tests in __main__
8 tests in __main__.factorial
9 tests in 2 items.
9 passed and 0 failed.
Test passed.
$
That's all you need to know to start making productive use of :mod:`doctest`!
Jump in. The following sections provide full details. Note that there are many
examples of doctests in the standard Python test suite and libraries.
Especially useful examples can be found in the standard test file
:file:`Lib/test/test_doctest.py`.
.. _doctest-simple-testmod:
Simple Usage: Checking Examples in Docstrings
---------------------------------------------
The simplest way to start using doctest (but not necessarily the way you'll
continue to do it) is to end each module :mod:`M` with::
if __name__ == "__main__":
import doctest
doctest.testmod()
:mod:`doctest` then examines docstrings in module :mod:`M`.
Running the module as a script causes the examples in the docstrings to get
executed and verified::
python M.py
This won't display anything unless an example fails, in which case the failing
example(s) and the cause(s) of the failure(s) are printed to stdout, and the
final line of output is ``***Test Failed*** N failures.``, where *N* is the
number of examples that failed.
Run it with the ``-v`` switch instead::
python M.py -v
and a detailed report of all examples tried is printed to standard output, along
with assorted summaries at the end.
You can force verbose mode by passing ``verbose=True`` to :func:`testmod`, or
prohibit it by passing ``verbose=False``. In either of those cases,
``sys.argv`` is not examined by :func:`testmod` (so passing ``-v`` or not
has no effect).
Since Python 2.6, there is also a command line shortcut for running
:func:`testmod`. You can instruct the Python interpreter to run the doctest
module directly from the standard library and pass the module name(s) on the
command line::
python -m doctest -v example.py
This will import :file:`example.py` as a standalone module and run
:func:`testmod` on it. Note that this may not work correctly if the file is
part of a package and imports other submodules from that package.
For more information on :func:`testmod`, see section :ref:`doctest-basic-api`.
.. _doctest-simple-testfile:
Simple Usage: Checking Examples in a Text File
----------------------------------------------
Another simple application of doctest is testing interactive examples in a text
file. This can be done with the :func:`testfile` function::
import doctest
doctest.testfile("example.txt")
That short script executes and verifies any interactive Python examples
contained in the file :file:`example.txt`. The file content is treated as if it
were a single giant docstring; the file doesn't need to contain a Python
program! For example, perhaps :file:`example.txt` contains this:
.. code-block:: none
The ``example`` module
======================
Using ``factorial``
-------------------
This is an example text file in reStructuredText format. First import
``factorial`` from the ``example`` module:
>>> from example import factorial
Now use it:
>>> factorial(6)
120
Running ``doctest.testfile("example.txt")`` then finds the error in this
documentation::
File "./example.txt", line 14, in example.txt
Failed example:
factorial(6)
Expected:
120
Got:
720
As with :func:`testmod`, :func:`testfile` won't display anything unless an
example fails. If an example does fail, then the failing example(s) and the
cause(s) of the failure(s) are printed to stdout, using the same format as
:func:`testmod`.
By default, :func:`testfile` looks for files in the calling module's directory.
See section :ref:`doctest-basic-api` for a description of the optional arguments
that can be used to tell it to look for files in other locations.
Like :func:`testmod`, :func:`testfile`'s verbosity can be set with the
``-v`` command-line switch or with the optional keyword argument
*verbose*.
Since Python 2.6, there is also a command line shortcut for running
:func:`testfile`. You can instruct the Python interpreter to run the doctest
module directly from the standard library and pass the file name(s) on the
command line::
python -m doctest -v example.txt
Because the file name does not end with :file:`.py`, :mod:`doctest` infers that
it must be run with :func:`testfile`, not :func:`testmod`.
For more information on :func:`testfile`, see section :ref:`doctest-basic-api`.
.. _doctest-how-it-works:
How It Works
------------
This section examines in detail how doctest works: which docstrings it looks at,
how it finds interactive examples, what execution context it uses, how it
handles exceptions, and how option flags can be used to control its behavior.
This is the information that you need to know to write doctest examples; for
information about actually running doctest on these examples, see the following
sections.
.. _doctest-which-docstrings:
Which Docstrings Are Examined?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The module docstring, and all function, class and method docstrings are
searched. Objects imported into the module are not searched.
In addition, if ``M.__test__`` exists and "is true", it must be a dict, and each
entry maps a (string) name to a function object, class object, or string.
Function and class object docstrings found from ``M.__test__`` are searched, and
strings are treated as if they were docstrings. In output, a key ``K`` in
``M.__test__`` appears with name ::
<name of M>.__test__.K
Any classes found are recursively searched similarly, to test docstrings in
their contained methods and nested classes.
.. versionchanged:: 2.4
A "private name" concept is deprecated and no longer documented.
.. _doctest-finding-examples:
How are Docstring Examples Recognized?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In most cases a copy-and-paste of an interactive console session works fine,
but doctest isn't trying to do an exact emulation of any specific Python shell.
::
>>> # comments are ignored
>>> x = 12
>>> x
12
>>> if x == 13:
... print "yes"
... else:
... print "no"
... print "NO"
... print "NO!!!"
...
no
NO
NO!!!
>>>
Any expected output must immediately follow the final ``'>>> '`` or ``'... '``
line containing the code, and the expected output (if any) extends to the next
``'>>> '`` or all-whitespace line.
The fine print:
* Expected output cannot contain an all-whitespace line, since such a line is
taken to signal the end of expected output. If expected output does contain a
blank line, put ``<BLANKLINE>`` in your doctest example each place a blank line
is expected.
.. versionadded:: 2.4
``<BLANKLINE>`` was added; there was no way to use expected output containing
empty lines in previous versions.
* All hard tab characters are expanded to spaces, using 8-column tab stops.
Tabs in output generated by the tested code are not modified. Because any
hard tabs in the sample output *are* expanded, this means that if the code
output includes hard tabs, the only way the doctest can pass is if the
:const:`NORMALIZE_WHITESPACE` option or :ref:`directive <doctest-directives>`
is in effect.
Alternatively, the test can be rewritten to capture the output and compare it
to an expected value as part of the test. This handling of tabs in the
source was arrived at through trial and error, and has proven to be the least
error prone way of handling them. It is possible to use a different
algorithm for handling tabs by writing a custom :class:`DocTestParser` class.
.. versionchanged:: 2.4
Expanding tabs to spaces is new; previous versions tried to preserve hard tabs,
with confusing results.
* Output to stdout is captured, but not output to stderr (exception tracebacks
are captured via a different means).
* If you continue a line via backslashing in an interactive session, or for any
other reason use a backslash, you should use a raw docstring, which will
preserve your backslashes exactly as you type them::
>>> def f(x):
... r'''Backslashes in a raw docstring: m\n'''
>>> print f.__doc__
Backslashes in a raw docstring: m\n
Otherwise, the backslash will be interpreted as part of the string. For example,
the ``\n`` above would be interpreted as a newline character. Alternatively, you
can double each backslash in the doctest version (and not use a raw string)::
>>> def f(x):
... '''Backslashes in a raw docstring: m\\n'''
>>> print f.__doc__
Backslashes in a raw docstring: m\n
* The starting column doesn't matter::
>>> assert "Easy!"
>>> import math
>>> math.floor(1.9)
1.0
and as many leading whitespace characters are stripped from the expected output
as appeared in the initial ``'>>> '`` line that started the example.
.. _doctest-execution-context:
What's the Execution Context?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
By default, each time :mod:`doctest` finds a docstring to test, it uses a
*shallow copy* of :mod:`M`'s globals, so that running tests doesn't change the
module's real globals, and so that one test in :mod:`M` can't leave behind
crumbs that accidentally allow another test to work. This means examples can
freely use any names defined at top-level in :mod:`M`, and names defined earlier
in the docstring being run. Examples cannot see names defined in other
docstrings.
You can force use of your own dict as the execution context by passing
``globs=your_dict`` to :func:`testmod` or :func:`testfile` instead.
.. _doctest-exceptions:
What About Exceptions?
^^^^^^^^^^^^^^^^^^^^^^
No problem, provided that the traceback is the only output produced by the
example: just paste in the traceback. [#]_ Since tracebacks contain details
that are likely to change rapidly (for example, exact file paths and line
numbers), this is one case where doctest works hard to be flexible in what it
accepts.
Simple example::
>>> [1, 2, 3].remove(42)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ValueError: list.remove(x): x not in list
That doctest succeeds if :exc:`ValueError` is raised, with the ``list.remove(x):
x not in list`` detail as shown.
The expected output for an exception must start with a traceback header, which
may be either of the following two lines, indented the same as the first line of
the example::
Traceback (most recent call last):
Traceback (innermost last):
The traceback header is followed by an optional traceback stack, whose contents
are ignored by doctest. The traceback stack is typically omitted, or copied
verbatim from an interactive session.
The traceback stack is followed by the most interesting part: the line(s)
containing the exception type and detail. This is usually the last line of a
traceback, but can extend across multiple lines if the exception has a
multi-line detail::
>>> raise ValueError('multi\n line\ndetail')
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ValueError: multi
line
detail
The last three lines (starting with :exc:`ValueError`) are compared against the
exception's type and detail, and the rest are ignored.
.. versionchanged:: 2.4
Previous versions were unable to handle multi-line exception details.
Best practice is to omit the traceback stack, unless it adds significant
documentation value to the example. So the last example is probably better as::
>>> raise ValueError('multi\n line\ndetail')
Traceback (most recent call last):
...
ValueError: multi
line
detail
Note that tracebacks are treated very specially. In particular, in the
rewritten example, the use of ``...`` is independent of doctest's
:const:`ELLIPSIS` option. The ellipsis in that example could be left out, or
could just as well be three (or three hundred) commas or digits, or an indented
transcript of a Monty Python skit.
Some details you should read once, but won't need to remember:
* Doctest can't guess whether your expected output came from an exception
traceback or from ordinary printing. So, e.g., an example that expects
``ValueError: 42 is prime`` will pass whether :exc:`ValueError` is actually
raised or if the example merely prints that traceback text. In practice,
ordinary output rarely begins with a traceback header line, so this doesn't
create real problems.
* Each line of the traceback stack (if present) must be indented further than
the first line of the example, *or* start with a non-alphanumeric character.
The first line following the traceback header indented the same and starting
with an alphanumeric is taken to be the start of the exception detail. Of
course this does the right thing for genuine tracebacks.
* When the :const:`IGNORE_EXCEPTION_DETAIL` doctest option is specified,
everything following the leftmost colon and any module information in the
exception name is ignored.
* The interactive shell omits the traceback header line for some
:exc:`SyntaxError`\ s. But doctest uses the traceback header line to
distinguish exceptions from non-exceptions. So in the rare case where you need
to test a :exc:`SyntaxError` that omits the traceback header, you will need to
manually add the traceback header line to your test example.
* For some :exc:`SyntaxError`\ s, Python displays the character position of the
syntax error, using a ``^`` marker::
>>> 1 1
File "<stdin>", line 1
1 1
^
SyntaxError: invalid syntax
Since the lines showing the position of the error come before the exception type
and detail, they are not checked by doctest. For example, the following test
would pass, even though it puts the ``^`` marker in the wrong location::
>>> 1 1
Traceback (most recent call last):
File "<stdin>", line 1
1 1
^
SyntaxError: invalid syntax
.. _option-flags-and-directives:
.. _doctest-options:
Option Flags
^^^^^^^^^^^^
A number of option flags control various aspects of doctest's behavior.
Symbolic names for the flags are supplied as module constants, which can be
:ref:`bitwise ORed <bitwise>` together and passed to various functions.
The names can also be used in :ref:`doctest directives <doctest-directives>`.
The first group of options define test semantics, controlling aspects of how
doctest decides whether actual output matches an example's expected output:
.. data:: DONT_ACCEPT_TRUE_FOR_1
By default, if an expected output block contains just ``1``, an actual output
block containing just ``1`` or just ``True`` is considered to be a match, and
similarly for ``0`` versus ``False``. When :const:`DONT_ACCEPT_TRUE_FOR_1` is
specified, neither substitution is allowed. The default behavior caters to that
Python changed the return type of many functions from integer to boolean;
doctests expecting "little integer" output still work in these cases. This
option will probably go away, but not for several years.
.. data:: DONT_ACCEPT_BLANKLINE
By default, if an expected output block contains a line containing only the
string ``<BLANKLINE>``, then that line will match a blank line in the actual
output. Because a genuinely blank line delimits the expected output, this is
the only way to communicate that a blank line is expected. When
:const:`DONT_ACCEPT_BLANKLINE` is specified, this substitution is not allowed.
.. data:: NORMALIZE_WHITESPACE
When specified, all sequences of whitespace (blanks and newlines) are treated as
equal. Any sequence of whitespace within the expected output will match any
sequence of whitespace within the actual output. By default, whitespace must
match exactly. :const:`NORMALIZE_WHITESPACE` is especially useful when a line of
expected output is very long, and you want to wrap it across multiple lines in
your source.
.. data:: ELLIPSIS
When specified, an ellipsis marker (``...``) in the expected output can match
any substring in the actual output. This includes substrings that span line
boundaries, and empty substrings, so it's best to keep usage of this simple.
Complicated uses can lead to the same kinds of "oops, it matched too much!"
surprises that ``.*`` is prone to in regular expressions.
.. data:: IGNORE_EXCEPTION_DETAIL
When specified, an example that expects an exception passes if an exception of
the expected type is raised, even if the exception detail does not match. For
example, an example expecting ``ValueError: 42`` will pass if the actual
exception raised is ``ValueError: 3*14``, but will fail, e.g., if
:exc:`TypeError` is raised.
It will also ignore the module name used in Python 3 doctest reports. Hence
both of these variations will work with the flag specified, regardless of
whether the test is run under Python 2.7 or Python 3.2 (or later versions)::
>>> raise CustomError('message')
Traceback (most recent call last):
CustomError: message
>>> raise CustomError('message')
Traceback (most recent call last):
my_module.CustomError: message
Note that :const:`ELLIPSIS` can also be used to ignore the
details of the exception message, but such a test may still fail based
on whether or not the module details are printed as part of the
exception name. Using :const:`IGNORE_EXCEPTION_DETAIL` and the details
from Python 2.3 is also the only clear way to write a doctest that doesn't
care about the exception detail yet continues to pass under Python 2.3 or
earlier (those releases do not support :ref:`doctest directives
<doctest-directives>` and ignore them as irrelevant comments). For example::
>>> (1, 2)[3] = 'moo'
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: object doesn't support item assignment
passes under Python 2.3 and later Python versions with the flag specified,
even though the detail
changed in Python 2.4 to say "does not" instead of "doesn't".
.. versionchanged:: 2.7
:const:`IGNORE_EXCEPTION_DETAIL` now also ignores any information
relating to the module containing the exception under test
.. data:: SKIP
When specified, do not run the example at all. This can be useful in contexts
where doctest examples serve as both documentation and test cases, and an
example should be included for documentation purposes, but should not be
checked. E.g., the example's output might be random; or the example might
depend on resources which would be unavailable to the test driver.
The SKIP flag can also be used for temporarily "commenting out" examples.
.. versionadded:: 2.5
.. data:: COMPARISON_FLAGS
A bitmask or'ing together all the comparison flags above.
The second group of options controls how test failures are reported:
.. data:: REPORT_UDIFF
When specified, failures that involve multi-line expected and actual outputs are
displayed using a unified diff.
.. data:: REPORT_CDIFF
When specified, failures that involve multi-line expected and actual outputs
will be displayed using a context diff.
.. data:: REPORT_NDIFF
When specified, differences are computed by ``difflib.Differ``, using the same
algorithm as the popular :file:`ndiff.py` utility. This is the only method that
marks differences within lines as well as across lines. For example, if a line
of expected output contains digit ``1`` where actual output contains letter
``l``, a line is inserted with a caret marking the mismatching column positions.
.. data:: REPORT_ONLY_FIRST_FAILURE
When specified, display the first failing example in each doctest, but suppress
output for all remaining examples. This will prevent doctest from reporting
correct examples that break because of earlier failures; but it might also hide
incorrect examples that fail independently of the first failure. When
:const:`REPORT_ONLY_FIRST_FAILURE` is specified, the remaining examples are
still run, and still count towards the total number of failures reported; only
the output is suppressed.
.. data:: REPORTING_FLAGS
A bitmask or'ing together all the reporting flags above.
.. versionadded:: 2.4
The constants
:const:`DONT_ACCEPT_BLANKLINE`, :const:`NORMALIZE_WHITESPACE`,
:const:`ELLIPSIS`, :const:`IGNORE_EXCEPTION_DETAIL`, :const:`REPORT_UDIFF`,
:const:`REPORT_CDIFF`, :const:`REPORT_NDIFF`,
:const:`REPORT_ONLY_FIRST_FAILURE`, :const:`COMPARISON_FLAGS` and
:const:`REPORTING_FLAGS` were added.
There's also a way to register new option flag names, although this isn't useful
unless you intend to extend :mod:`doctest` internals via subclassing:
.. function:: register_optionflag(name)
Create a new option flag with a given name, and return the new flag's integer
value. :func:`register_optionflag` can be used when subclassing
:class:`OutputChecker` or :class:`DocTestRunner` to create new options that are
supported by your subclasses. :func:`register_optionflag` should always be
called using the following idiom::
MY_FLAG = register_optionflag('MY_FLAG')
.. versionadded:: 2.4
.. _doctest-directives:
Directives
^^^^^^^^^^
Doctest directives may be used to modify the :ref:`option flags
<doctest-options>` for an individual example. Doctest directives are
special Python comments following an example's source code:
.. productionlist:: doctest
directive: "#" "doctest:" `directive_options`
directive_options: `directive_option` ("," `directive_option`)\*
directive_option: `on_or_off` `directive_option_name`
on_or_off: "+" \| "-"
directive_option_name: "DONT_ACCEPT_BLANKLINE" \| "NORMALIZE_WHITESPACE" \| ...
Whitespace is not allowed between the ``+`` or ``-`` and the directive option
name. The directive option name can be any of the option flag names explained
above.
An example's doctest directives modify doctest's behavior for that single
example. Use ``+`` to enable the named behavior, or ``-`` to disable it.
For example, this test passes::
>>> print range(20) # doctest: +NORMALIZE_WHITESPACE
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
10, 11, 12, 13, 14, 15, 16, 17, 18, 19]
Without the directive it would fail, both because the actual output doesn't have
two blanks before the single-digit list elements, and because the actual output
is on a single line. This test also passes, and also requires a directive to do
so::
>>> print range(20) # doctest: +ELLIPSIS
[0, 1, ..., 18, 19]
Multiple directives can be used on a single physical line, separated by
commas::
>>> print range(20) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
[0, 1, ..., 18, 19]
If multiple directive comments are used for a single example, then they are
combined::
>>> print range(20) # doctest: +ELLIPSIS
... # doctest: +NORMALIZE_WHITESPACE
[0, 1, ..., 18, 19]
As the previous example shows, you can add ``...`` lines to your example
containing only directives. This can be useful when an example is too long for
a directive to comfortably fit on the same line::
>>> print range(5) + range(10,20) + range(30,40) + range(50,60)
... # doctest: +ELLIPSIS
[0, ..., 4, 10, ..., 19, 30, ..., 39, 50, ..., 59]
Note that since all options are disabled by default, and directives apply only
to the example they appear in, enabling options (via ``+`` in a directive) is
usually the only meaningful choice. However, option flags can also be passed to
functions that run doctests, establishing different defaults. In such cases,
disabling an option via ``-`` in a directive can be useful.
.. versionadded:: 2.4
Support for doctest directives was added.
.. _doctest-warnings:
Warnings
^^^^^^^^
:mod:`doctest` is serious about requiring exact matches in expected output. If
even a single character doesn't match, the test fails. This will probably
surprise you a few times, as you learn exactly what Python does and doesn't
guarantee about output. For example, when printing a dict, Python doesn't
guarantee that the key-value pairs will be printed in any particular order, so a
test like ::
>>> foo()
{"Hermione": "hippogryph", "Harry": "broomstick"}
is vulnerable! One workaround is to do ::
>>> foo() == {"Hermione": "hippogryph", "Harry": "broomstick"}
True
instead. Another is to do ::
>>> d = foo().items()
>>> d.sort()
>>> d
[('Harry', 'broomstick'), ('Hermione', 'hippogryph')]
There are others, but you get the idea.
Another bad idea is to print things that embed an object address, like ::
>>> id(1.0) # certain to fail some of the time
7948648
>>> class C: pass
>>> C() # the default repr() for instances embeds an address
<__main__.C instance at 0x00AC18F0>
The :const:`ELLIPSIS` directive gives a nice approach for the last example::
>>> C() #doctest: +ELLIPSIS
<__main__.C instance at 0x...>
Floating-point numbers are also subject to small output variations across
platforms, because Python defers to the platform C library for float formatting,
and C libraries vary widely in quality here. ::
>>> 1./7 # risky
0.14285714285714285
>>> print 1./7 # safer
0.142857142857
>>> print round(1./7, 6) # much safer
0.142857
Numbers of the form ``I/2.**J`` are safe across all platforms, and I often
contrive doctest examples to produce numbers of that form::
>>> 3./4 # utterly safe
0.75
Simple fractions are also easier for people to understand, and that makes for
better documentation.
.. _doctest-basic-api:
Basic API
---------
The functions :func:`testmod` and :func:`testfile` provide a simple interface to
doctest that should be sufficient for most basic uses. For a less formal
introduction to these two functions, see sections :ref:`doctest-simple-testmod`
and :ref:`doctest-simple-testfile`.
.. function:: testfile(filename[, module_relative][, name][, package][, globs][, verbose][, report][, optionflags][, extraglobs][, raise_on_error][, parser][, encoding])
All arguments except *filename* are optional, and should be specified in keyword
form.
Test examples in the file named *filename*. Return ``(failure_count,
test_count)``.
Optional argument *module_relative* specifies how the filename should be
interpreted:
* If *module_relative* is ``True`` (the default), then *filename* specifies an
OS-independent module-relative path. By default, this path is relative to the
calling module's directory; but if the *package* argument is specified, then it
is relative to that package. To ensure OS-independence, *filename* should use
``/`` characters to separate path segments, and may not be an absolute path
(i.e., it may not begin with ``/``).
* If *module_relative* is ``False``, then *filename* specifies an OS-specific
path. The path may be absolute or relative; relative paths are resolved with
respect to the current working directory.
Optional argument *name* gives the name of the test; by default, or if ``None``,
``os.path.basename(filename)`` is used.
Optional argument *package* is a Python package or the name of a Python package
whose directory should be used as the base directory for a module-relative
filename. If no package is specified, then the calling module's directory is
used as the base directory for module-relative filenames. It is an error to
specify *package* if *module_relative* is ``False``.
Optional argument *globs* gives a dict to be used as the globals when executing
examples. A new shallow copy of this dict is created for the doctest, so its
examples start with a clean slate. By default, or if ``None``, a new empty dict
is used.
Optional argument *extraglobs* gives a dict merged into the globals used to
execute examples. This works like :meth:`dict.update`: if *globs* and
*extraglobs* have a common key, the associated value in *extraglobs* appears in
the combined dict. By default, or if ``None``, no extra globals are used. This
is an advanced feature that allows parameterization of doctests. For example, a
doctest can be written for a base class, using a generic name for the class,
then reused to test any number of subclasses by passing an *extraglobs* dict
mapping the generic name to the subclass to be tested.
Optional argument *verbose* prints lots of stuff if true, and prints only
failures if false; by default, or if ``None``, it's true if and only if ``'-v'``
is in ``sys.argv``.
Optional argument *report* prints a summary at the end when true, else prints
nothing at the end. In verbose mode, the summary is detailed, else the summary
is very brief (in fact, empty if all tests passed).
Optional argument *optionflags* or's together option flags. See section
:ref:`doctest-options`.
Optional argument *raise_on_error* defaults to false. If true, an exception is
raised upon the first failure or unexpected exception in an example. This
allows failures to be post-mortem debugged. Default behavior is to continue
running examples.
Optional argument *parser* specifies a :class:`DocTestParser` (or subclass) that
should be used to extract tests from the files. It defaults to a normal parser
(i.e., ``DocTestParser()``).
Optional argument *encoding* specifies an encoding that should be used to
convert the file to unicode.
.. versionadded:: 2.4
.. versionchanged:: 2.5
The parameter *encoding* was added.
.. function:: testmod([m][, name][, globs][, verbose][, report][, optionflags][, extraglobs][, raise_on_error][, exclude_empty])
All arguments are optional, and all except for *m* should be specified in
keyword form.
Test examples in docstrings in functions and classes reachable from module *m*
(or module :mod:`__main__` if *m* is not supplied or is ``None``), starting with
``m.__doc__``.
Also test examples reachable from dict ``m.__test__``, if it exists and is not
``None``. ``m.__test__`` maps names (strings) to functions, classes and
strings; function and class docstrings are searched for examples; strings are
searched directly, as if they were docstrings.
Only docstrings attached to objects belonging to module *m* are searched.
Return ``(failure_count, test_count)``.
Optional argument *name* gives the name of the module; by default, or if
``None``, ``m.__name__`` is used.
Optional argument *exclude_empty* defaults to false. If true, objects for which
no doctests are found are excluded from consideration. The default is a backward
compatibility hack, so that code still using :meth:`doctest.master.summarize` in
conjunction with :func:`testmod` continues to get output for objects with no
tests. The *exclude_empty* argument to the newer :class:`DocTestFinder`
constructor defaults to true.
Optional arguments *extraglobs*, *verbose*, *report*, *optionflags*,
*raise_on_error*, and *globs* are the same as for function :func:`testfile`
above, except that *globs* defaults to ``m.__dict__``.
.. versionchanged:: 2.3
The parameter *optionflags* was added.
.. versionchanged:: 2.4
The parameters *extraglobs*, *raise_on_error* and *exclude_empty* were added.
.. versionchanged:: 2.5
The optional argument *isprivate*, deprecated in 2.4, was removed.
.. function:: run_docstring_examples(f, globs[, verbose][, name][, compileflags][, optionflags])
Test examples associated with object *f*; for example, *f* may be a string,
a module, a function, or a class object.
A shallow copy of dictionary argument *globs* is used for the execution context.
Optional argument *name* is used in failure messages, and defaults to
``"NoName"``.
If optional argument *verbose* is true, output is generated even if there are no
failures. By default, output is generated only in case of an example failure.
Optional argument *compileflags* gives the set of flags that should be used by
the Python compiler when running the examples. By default, or if ``None``,
flags are deduced corresponding to the set of future features found in *globs*.
Optional argument *optionflags* works as for function :func:`testfile` above.
.. _doctest-unittest-api:
Unittest API
------------
As your collection of doctest'ed modules grows, you'll want a way to run all
their doctests systematically. Prior to Python 2.4, :mod:`doctest` had a barely
documented :class:`Tester` class that supplied a rudimentary way to combine
doctests from multiple modules. :class:`Tester` was feeble, and in practice most
serious Python testing frameworks build on the :mod:`unittest` module, which
supplies many flexible ways to combine tests from multiple sources. So, in
Python 2.4, :mod:`doctest`'s :class:`Tester` class is deprecated, and
:mod:`doctest` provides two functions that can be used to create :mod:`unittest`
test suites from modules and text files containing doctests. To integrate with
:mod:`unittest` test discovery, include a :func:`load_tests` function in your
test module::
import unittest
import doctest
import my_module_with_doctests
def load_tests(loader, tests, ignore):
tests.addTests(doctest.DocTestSuite(my_module_with_doctests))
return tests
There are two main functions for creating :class:`unittest.TestSuite` instances
from text files and modules with doctests:
.. function:: DocFileSuite(*paths, [module_relative][, package][, setUp][, tearDown][, globs][, optionflags][, parser][, encoding])
Convert doctest tests from one or more text files to a
:class:`unittest.TestSuite`.
The returned :class:`unittest.TestSuite` is to be run by the unittest framework
and runs the interactive examples in each file. If an example in any file
fails, then the synthesized unit test fails, and a :exc:`failureException`
exception is raised showing the name of the file containing the test and a
(sometimes approximate) line number.
Pass one or more paths (as strings) to text files to be examined.
Options may be provided as keyword arguments:
Optional argument *module_relative* specifies how the filenames in *paths*
should be interpreted:
* If *module_relative* is ``True`` (the default), then each filename in
*paths* specifies an OS-independent module-relative path. By default, this
path is relative to the calling module's directory; but if the *package*
argument is specified, then it is relative to that package. To ensure
OS-independence, each filename should use ``/`` characters to separate path
segments, and may not be an absolute path (i.e., it may not begin with
``/``).
* If *module_relative* is ``False``, then each filename in *paths* specifies
an OS-specific path. The path may be absolute or relative; relative paths
are resolved with respect to the current working directory.
Optional argument *package* is a Python package or the name of a Python
package whose directory should be used as the base directory for
module-relative filenames in *paths*. If no package is specified, then the
calling module's directory is used as the base directory for module-relative
filenames. It is an error to specify *package* if *module_relative* is
``False``.
Optional argument *setUp* specifies a set-up function for the test suite.
This is called before running the tests in each file. The *setUp* function
will be passed a :class:`DocTest` object. The setUp function can access the
test globals as the *globs* attribute of the test passed.
Optional argument *tearDown* specifies a tear-down function for the test
suite. This is called after running the tests in each file. The *tearDown*
function will be passed a :class:`DocTest` object. The setUp function can
access the test globals as the *globs* attribute of the test passed.
Optional argument *globs* is a dictionary containing the initial global
variables for the tests. A new copy of this dictionary is created for each
test. By default, *globs* is a new empty dictionary.
Optional argument *optionflags* specifies the default doctest options for the
tests, created by or-ing together individual option flags. See section
:ref:`doctest-options`. See function :func:`set_unittest_reportflags` below
for a better way to set reporting options.
Optional argument *parser* specifies a :class:`DocTestParser` (or subclass)
that should be used to extract tests from the files. It defaults to a normal
parser (i.e., ``DocTestParser()``).
Optional argument *encoding* specifies an encoding that should be used to
convert the file to unicode.
.. versionadded:: 2.4
.. versionchanged:: 2.5
The global ``__file__`` was added to the globals provided to doctests
loaded from a text file using :func:`DocFileSuite`.
.. versionchanged:: 2.5
The parameter *encoding* was added.
.. note::
Unlike :func:`testmod` and :class:`DocTestFinder`, this function raises
a :exc:`ValueError` if *module* contains no docstrings. You can prevent
this error by passing a :class:`DocTestFinder` instance as the
*test_finder* argument with its *exclude_empty* keyword argument set
to ``False``::
>>> finder = doctest.DocTestFinder(exclude_empty=False)
>>> suite = doctest.DocTestSuite(test_finder=finder)
.. function:: DocTestSuite([module][, globs][, extraglobs][, test_finder][, setUp][, tearDown][, checker])
Convert doctest tests for a module to a :class:`unittest.TestSuite`.
The returned :class:`unittest.TestSuite` is to be run by the unittest framework
and runs each doctest in the module. If any of the doctests fail, then the
synthesized unit test fails, and a :exc:`failureException` exception is raised
showing the name of the file containing the test and a (sometimes approximate)
line number.
Optional argument *module* provides the module to be tested. It can be a module
object or a (possibly dotted) module name. If not specified, the module calling
this function is used.
Optional argument *globs* is a dictionary containing the initial global
variables for the tests. A new copy of this dictionary is created for each
test. By default, *globs* is a new empty dictionary.
Optional argument *extraglobs* specifies an extra set of global variables, which
is merged into *globs*. By default, no extra globals are used.
Optional argument *test_finder* is the :class:`DocTestFinder` object (or a
drop-in replacement) that is used to extract doctests from the module.
Optional arguments *setUp*, *tearDown*, and *optionflags* are the same as for
function :func:`DocFileSuite` above.
.. versionadded:: 2.3
.. versionchanged:: 2.4
The parameters *globs*, *extraglobs*, *test_finder*, *setUp*, *tearDown*, and
*optionflags* were added; this function now uses the same search technique as
:func:`testmod`.
Under the covers, :func:`DocTestSuite` creates a :class:`unittest.TestSuite` out
of :class:`doctest.DocTestCase` instances, and :class:`DocTestCase` is a
subclass of :class:`unittest.TestCase`. :class:`DocTestCase` isn't documented
here (it's an internal detail), but studying its code can answer questions about
the exact details of :mod:`unittest` integration.
Similarly, :func:`DocFileSuite` creates a :class:`unittest.TestSuite` out of
:class:`doctest.DocFileCase` instances, and :class:`DocFileCase` is a subclass
of :class:`DocTestCase`.
So both ways of creating a :class:`unittest.TestSuite` run instances of
:class:`DocTestCase`. This is important for a subtle reason: when you run
:mod:`doctest` functions yourself, you can control the :mod:`doctest` options in
use directly, by passing option flags to :mod:`doctest` functions. However, if
you're writing a :mod:`unittest` framework, :mod:`unittest` ultimately controls
when and how tests get run. The framework author typically wants to control
:mod:`doctest` reporting options (perhaps, e.g., specified by command line
options), but there's no way to pass options through :mod:`unittest` to
:mod:`doctest` test runners.
For this reason, :mod:`doctest` also supports a notion of :mod:`doctest`
reporting flags specific to :mod:`unittest` support, via this function:
.. function:: set_unittest_reportflags(flags)
Set the :mod:`doctest` reporting flags to use.
Argument *flags* or's together option flags. See section
:ref:`doctest-options`. Only "reporting flags" can be used.
This is a module-global setting, and affects all future doctests run by module
:mod:`unittest`: the :meth:`runTest` method of :class:`DocTestCase` looks at
the option flags specified for the test case when the :class:`DocTestCase`
instance was constructed. If no reporting flags were specified (which is the
typical and expected case), :mod:`doctest`'s :mod:`unittest` reporting flags are
:ref:`bitwise ORed <bitwise>` into the option flags, and the option flags
so augmented are passed to the :class:`DocTestRunner` instance created to
run the doctest. If any reporting flags were specified when the
:class:`DocTestCase` instance was constructed, :mod:`doctest`'s
:mod:`unittest` reporting flags are ignored.
The value of the :mod:`unittest` reporting flags in effect before the function
was called is returned by the function.
.. versionadded:: 2.4
.. _doctest-advanced-api:
Advanced API
------------
The basic API is a simple wrapper that's intended to make doctest easy to use.
It is fairly flexible, and should meet most users' needs; however, if you
require more fine-grained control over testing, or wish to extend doctest's
capabilities, then you should use the advanced API.
The advanced API revolves around two container classes, which are used to store
the interactive examples extracted from doctest cases:
* :class:`Example`: A single Python :term:`statement`, paired with its expected
output.
* :class:`DocTest`: A collection of :class:`Example`\ s, typically extracted
from a single docstring or text file.
Additional processing classes are defined to find, parse, and run, and check
doctest examples:
* :class:`DocTestFinder`: Finds all docstrings in a given module, and uses a
:class:`DocTestParser` to create a :class:`DocTest` from every docstring that
contains interactive examples.
* :class:`DocTestParser`: Creates a :class:`DocTest` object from a string (such
as an object's docstring).
* :class:`DocTestRunner`: Executes the examples in a :class:`DocTest`, and uses
an :class:`OutputChecker` to verify their output.
* :class:`OutputChecker`: Compares the actual output from a doctest example with
the expected output, and decides whether they match.
The relationships among these processing classes are summarized in the following
diagram::
list of:
+------+ +---------+
|module| --DocTestFinder-> | DocTest | --DocTestRunner-> results
+------+ | ^ +---------+ | ^ (printed)
| | | Example | | |
v | | ... | v |
DocTestParser | Example | OutputChecker
+---------+
.. _doctest-doctest:
DocTest Objects
^^^^^^^^^^^^^^^
.. class:: DocTest(examples, globs, name, filename, lineno, docstring)
A collection of doctest examples that should be run in a single namespace. The
constructor arguments are used to initialize the attributes of the same names.
.. versionadded:: 2.4
:class:`DocTest` defines the following attributes. They are initialized by
the constructor, and should not be modified directly.
.. attribute:: examples
A list of :class:`Example` objects encoding the individual interactive Python
examples that should be run by this test.
.. attribute:: globs
The namespace (aka globals) that the examples should be run in. This is a
dictionary mapping names to values. Any changes to the namespace made by the
examples (such as binding new variables) will be reflected in :attr:`globs`
after the test is run.
.. attribute:: name
A string name identifying the :class:`DocTest`. Typically, this is the name
of the object or file that the test was extracted from.
.. attribute:: filename
The name of the file that this :class:`DocTest` was extracted from; or
``None`` if the filename is unknown, or if the :class:`DocTest` was not
extracted from a file.
.. attribute:: lineno
The line number within :attr:`filename` where this :class:`DocTest` begins, or
``None`` if the line number is unavailable. This line number is zero-based
with respect to the beginning of the file.
.. attribute:: docstring
The string that the test was extracted from, or ``None`` if the string is
unavailable, or if the test was not extracted from a string.
.. _doctest-example:
Example Objects
^^^^^^^^^^^^^^^
.. class:: Example(source, want[, exc_msg][, lineno][, indent][, options])
A single interactive example, consisting of a Python statement and its expected
output. The constructor arguments are used to initialize the attributes of the
same names.
.. versionadded:: 2.4
:class:`Example` defines the following attributes. They are initialized by
the constructor, and should not be modified directly.
.. attribute:: source
A string containing the example's source code. This source code consists of a
single Python statement, and always ends with a newline; the constructor adds
a newline when necessary.
.. attribute:: want
The expected output from running the example's source code (either from
stdout, or a traceback in case of exception). :attr:`want` ends with a
newline unless no output is expected, in which case it's an empty string. The
constructor adds a newline when necessary.
.. attribute:: exc_msg
The exception message generated by the example, if the example is expected to
generate an exception; or ``None`` if it is not expected to generate an
exception. This exception message is compared against the return value of
:func:`traceback.format_exception_only`. :attr:`exc_msg` ends with a newline
unless it's ``None``. The constructor adds a newline if needed.
.. attribute:: lineno
The line number within the string containing this example where the example
begins. This line number is zero-based with respect to the beginning of the
containing string.
.. attribute:: indent
The example's indentation in the containing string, i.e., the number of space
characters that precede the example's first prompt.
.. attribute:: options
A dictionary mapping from option flags to ``True`` or ``False``, which is used
to override default options for this example. Any option flags not contained
in this dictionary are left at their default value (as specified by the
:class:`DocTestRunner`'s :attr:`optionflags`). By default, no options are set.
.. _doctest-doctestfinder:
DocTestFinder objects
^^^^^^^^^^^^^^^^^^^^^
.. class:: DocTestFinder([verbose][, parser][, recurse][, exclude_empty])
A processing class used to extract the :class:`DocTest`\ s that are relevant to
a given object, from its docstring and the docstrings of its contained objects.
:class:`DocTest`\ s can currently be extracted from the following object types:
modules, functions, classes, methods, staticmethods, classmethods, and
properties.
The optional argument *verbose* can be used to display the objects searched by
the finder. It defaults to ``False`` (no output).
The optional argument *parser* specifies the :class:`DocTestParser` object (or a
drop-in replacement) that is used to extract doctests from docstrings.
If the optional argument *recurse* is false, then :meth:`DocTestFinder.find`
will only examine the given object, and not any contained objects.
If the optional argument *exclude_empty* is false, then
:meth:`DocTestFinder.find` will include tests for objects with empty docstrings.
.. versionadded:: 2.4
:class:`DocTestFinder` defines the following method:
.. method:: find(obj[, name][, module][, globs][, extraglobs])
Return a list of the :class:`DocTest`\ s that are defined by *obj*'s
docstring, or by any of its contained objects' docstrings.
The optional argument *name* specifies the object's name; this name will be
used to construct names for the returned :class:`DocTest`\ s. If *name* is
not specified, then ``obj.__name__`` is used.
The optional parameter *module* is the module that contains the given object.
If the module is not specified or is ``None``, then the test finder will attempt
to automatically determine the correct module. The object's module is used:
* As a default namespace, if *globs* is not specified.
* To prevent the DocTestFinder from extracting DocTests from objects that are
imported from other modules. (Contained objects with modules other than
*module* are ignored.)
* To find the name of the file containing the object.
* To help find the line number of the object within its file.
If *module* is ``False``, no attempt to find the module will be made. This is
obscure, of use mostly in testing doctest itself: if *module* is ``False``, or
is ``None`` but cannot be found automatically, then all objects are considered
to belong to the (non-existent) module, so all contained objects will
(recursively) be searched for doctests.
The globals for each :class:`DocTest` is formed by combining *globs* and
*extraglobs* (bindings in *extraglobs* override bindings in *globs*). A new
shallow copy of the globals dictionary is created for each :class:`DocTest`.
If *globs* is not specified, then it defaults to the module's *__dict__*, if
specified, or ``{}`` otherwise. If *extraglobs* is not specified, then it
defaults to ``{}``.
.. _doctest-doctestparser:
DocTestParser objects
^^^^^^^^^^^^^^^^^^^^^
.. class:: DocTestParser()
A processing class used to extract interactive examples from a string, and use
them to create a :class:`DocTest` object.
.. versionadded:: 2.4
:class:`DocTestParser` defines the following methods:
.. method:: get_doctest(string, globs, name, filename, lineno)
Extract all doctest examples from the given string, and collect them into a
:class:`DocTest` object.
*globs*, *name*, *filename*, and *lineno* are attributes for the new
:class:`DocTest` object. See the documentation for :class:`DocTest` for more
information.
.. method:: get_examples(string[, name])
Extract all doctest examples from the given string, and return them as a list
of :class:`Example` objects. Line numbers are 0-based. The optional argument
*name* is a name identifying this string, and is only used for error messages.
.. method:: parse(string[, name])
Divide the given string into examples and intervening text, and return them as
a list of alternating :class:`Example`\ s and strings. Line numbers for the
:class:`Example`\ s are 0-based. The optional argument *name* is a name
identifying this string, and is only used for error messages.
.. _doctest-doctestrunner:
DocTestRunner objects
^^^^^^^^^^^^^^^^^^^^^
.. class:: DocTestRunner([checker][, verbose][, optionflags])
A processing class used to execute and verify the interactive examples in a
:class:`DocTest`.
The comparison between expected outputs and actual outputs is done by an
:class:`OutputChecker`. This comparison may be customized with a number of
option flags; see section :ref:`doctest-options` for more information. If the
option flags are insufficient, then the comparison may also be customized by
passing a subclass of :class:`OutputChecker` to the constructor.
The test runner's display output can be controlled in two ways. First, an output
function can be passed to :meth:`TestRunner.run`; this function will be called
with strings that should be displayed. It defaults to ``sys.stdout.write``. If
capturing the output is not sufficient, then the display output can be also
customized by subclassing DocTestRunner, and overriding the methods
:meth:`report_start`, :meth:`report_success`,
:meth:`report_unexpected_exception`, and :meth:`report_failure`.
The optional keyword argument *checker* specifies the :class:`OutputChecker`
object (or drop-in replacement) that should be used to compare the expected
outputs to the actual outputs of doctest examples.
The optional keyword argument *verbose* controls the :class:`DocTestRunner`'s
verbosity. If *verbose* is ``True``, then information is printed about each
example, as it is run. If *verbose* is ``False``, then only failures are
printed. If *verbose* is unspecified, or ``None``, then verbose output is used
iff the command-line switch ``-v`` is used.
The optional keyword argument *optionflags* can be used to control how the test
runner compares expected output to actual output, and how it displays failures.
For more information, see section :ref:`doctest-options`.
.. versionadded:: 2.4
:class:`DocTestParser` defines the following methods:
.. method:: report_start(out, test, example)
Report that the test runner is about to process the given example. This method
is provided to allow subclasses of :class:`DocTestRunner` to customize their
output; it should not be called directly.
*example* is the example about to be processed. *test* is the test
*containing example*. *out* is the output function that was passed to
:meth:`DocTestRunner.run`.
.. method:: report_success(out, test, example, got)
Report that the given example ran successfully. This method is provided to
allow subclasses of :class:`DocTestRunner` to customize their output; it
should not be called directly.
*example* is the example about to be processed. *got* is the actual output
from the example. *test* is the test containing *example*. *out* is the
output function that was passed to :meth:`DocTestRunner.run`.
.. method:: report_failure(out, test, example, got)
Report that the given example failed. This method is provided to allow
subclasses of :class:`DocTestRunner` to customize their output; it should not
be called directly.
*example* is the example about to be processed. *got* is the actual output
from the example. *test* is the test containing *example*. *out* is the
output function that was passed to :meth:`DocTestRunner.run`.
.. method:: report_unexpected_exception(out, test, example, exc_info)
Report that the given example raised an unexpected exception. This method is
provided to allow subclasses of :class:`DocTestRunner` to customize their
output; it should not be called directly.
*example* is the example about to be processed. *exc_info* is a tuple
containing information about the unexpected exception (as returned by
:func:`sys.exc_info`). *test* is the test containing *example*. *out* is the
output function that was passed to :meth:`DocTestRunner.run`.
.. method:: run(test[, compileflags][, out][, clear_globs])
Run the examples in *test* (a :class:`DocTest` object), and display the
results using the writer function *out*.
The examples are run in the namespace ``test.globs``. If *clear_globs* is
true (the default), then this namespace will be cleared after the test runs,
to help with garbage collection. If you would like to examine the namespace
after the test completes, then use *clear_globs=False*.
*compileflags* gives the set of flags that should be used by the Python
compiler when running the examples. If not specified, then it will default to
the set of future-import flags that apply to *globs*.
The output of each example is checked using the :class:`DocTestRunner`'s
output checker, and the results are formatted by the
:meth:`DocTestRunner.report_\*` methods.
.. method:: summarize([verbose])
Print a summary of all the test cases that have been run by this DocTestRunner,
and return a :term:`named tuple` ``TestResults(failed, attempted)``.
The optional *verbose* argument controls how detailed the summary is. If the
verbosity is not specified, then the :class:`DocTestRunner`'s verbosity is
used.
.. versionchanged:: 2.6
Use a named tuple.
.. _doctest-outputchecker:
OutputChecker objects
^^^^^^^^^^^^^^^^^^^^^
.. class:: OutputChecker()
A class used to check the whether the actual output from a doctest example
matches the expected output. :class:`OutputChecker` defines two methods:
:meth:`check_output`, which compares a given pair of outputs, and returns true
if they match; and :meth:`output_difference`, which returns a string describing
the differences between two outputs.
.. versionadded:: 2.4
:class:`OutputChecker` defines the following methods:
.. method:: check_output(want, got, optionflags)
Return ``True`` iff the actual output from an example (*got*) matches the
expected output (*want*). These strings are always considered to match if
they are identical; but depending on what option flags the test runner is
using, several non-exact match types are also possible. See section
:ref:`doctest-options` for more information about option flags.
.. method:: output_difference(example, got, optionflags)
Return a string describing the differences between the expected output for a
given example (*example*) and the actual output (*got*). *optionflags* is the
set of option flags used to compare *want* and *got*.
.. _doctest-debugging:
Debugging
---------
Doctest provides several mechanisms for debugging doctest examples:
* Several functions convert doctests to executable Python programs, which can be
run under the Python debugger, :mod:`pdb`.
* The :class:`DebugRunner` class is a subclass of :class:`DocTestRunner` that
raises an exception for the first failing example, containing information about
that example. This information can be used to perform post-mortem debugging on
the example.
* The :mod:`unittest` cases generated by :func:`DocTestSuite` support the
:meth:`debug` method defined by :class:`unittest.TestCase`.
* You can add a call to :func:`pdb.set_trace` in a doctest example, and you'll
drop into the Python debugger when that line is executed. Then you can inspect
current values of variables, and so on. For example, suppose :file:`a.py`
contains just this module docstring::
"""
>>> def f(x):
... g(x*2)
>>> def g(x):
... print x+3
... import pdb; pdb.set_trace()
>>> f(3)
9
"""
Then an interactive Python session may look like this::
>>> import a, doctest
>>> doctest.testmod(a)
--Return--
> <doctest a[1]>(3)g()->None
-> import pdb; pdb.set_trace()
(Pdb) list
1 def g(x):
2 print x+3
3 -> import pdb; pdb.set_trace()
[EOF]
(Pdb) print x
6
(Pdb) step
--Return--
> <doctest a[0]>(2)f()->None
-> g(x*2)
(Pdb) list
1 def f(x):
2 -> g(x*2)
[EOF]
(Pdb) print x
3
(Pdb) step
--Return--
> <doctest a[2]>(1)?()->None
-> f(3)
(Pdb) cont
(0, 3)
>>>
.. versionchanged:: 2.4
The ability to use :func:`pdb.set_trace` usefully inside doctests was added.
Functions that convert doctests to Python code, and possibly run the synthesized
code under the debugger:
.. function:: script_from_examples(s)
Convert text with examples to a script.
Argument *s* is a string containing doctest examples. The string is converted
to a Python script, where doctest examples in *s* are converted to regular code,
and everything else is converted to Python comments. The generated script is
returned as a string. For example, ::
import doctest
print doctest.script_from_examples(r"""
Set x and y to 1 and 2.
>>> x, y = 1, 2
Print their sum:
>>> print x+y
3
""")
displays::
# Set x and y to 1 and 2.
x, y = 1, 2
#
# Print their sum:
print x+y
# Expected:
## 3
This function is used internally by other functions (see below), but can also be
useful when you want to transform an interactive Python session into a Python
script.
.. versionadded:: 2.4
.. function:: testsource(module, name)
Convert the doctest for an object to a script.
Argument *module* is a module object, or dotted name of a module, containing the
object whose doctests are of interest. Argument *name* is the name (within the
module) of the object with the doctests of interest. The result is a string,
containing the object's docstring converted to a Python script, as described for
:func:`script_from_examples` above. For example, if module :file:`a.py`
contains a top-level function :func:`f`, then ::
import a, doctest
print doctest.testsource(a, "a.f")
prints a script version of function :func:`f`'s docstring, with doctests
converted to code, and the rest placed in comments.
.. versionadded:: 2.3
.. function:: debug(module, name[, pm])
Debug the doctests for an object.
The *module* and *name* arguments are the same as for function
:func:`testsource` above. The synthesized Python script for the named object's
docstring is written to a temporary file, and then that file is run under the
control of the Python debugger, :mod:`pdb`.
A shallow copy of ``module.__dict__`` is used for both local and global
execution context.
Optional argument *pm* controls whether post-mortem debugging is used. If *pm*
has a true value, the script file is run directly, and the debugger gets
involved only if the script terminates via raising an unhandled exception. If
it does, then post-mortem debugging is invoked, via :func:`pdb.post_mortem`,
passing the traceback object from the unhandled exception. If *pm* is not
specified, or is false, the script is run under the debugger from the start, via
passing an appropriate :func:`execfile` call to :func:`pdb.run`.
.. versionadded:: 2.3
.. versionchanged:: 2.4
The *pm* argument was added.
.. function:: debug_src(src[, pm][, globs])
Debug the doctests in a string.
This is like function :func:`debug` above, except that a string containing
doctest examples is specified directly, via the *src* argument.
Optional argument *pm* has the same meaning as in function :func:`debug` above.
Optional argument *globs* gives a dictionary to use as both local and global
execution context. If not specified, or ``None``, an empty dictionary is used.
If specified, a shallow copy of the dictionary is used.
.. versionadded:: 2.4
The :class:`DebugRunner` class, and the special exceptions it may raise, are of
most interest to testing framework authors, and will only be sketched here. See
the source code, and especially :class:`DebugRunner`'s docstring (which is a
doctest!) for more details:
.. class:: DebugRunner([checker][, verbose][, optionflags])
A subclass of :class:`DocTestRunner` that raises an exception as soon as a
failure is encountered. If an unexpected exception occurs, an
:exc:`UnexpectedException` exception is raised, containing the test, the
example, and the original exception. If the output doesn't match, then a
:exc:`DocTestFailure` exception is raised, containing the test, the example, and
the actual output.
For information about the constructor parameters and methods, see the
documentation for :class:`DocTestRunner` in section :ref:`doctest-advanced-api`.
There are two exceptions that may be raised by :class:`DebugRunner` instances:
.. exception:: DocTestFailure(test, example, got)
An exception raised by :class:`DocTestRunner` to signal that a doctest example's
actual output did not match its expected output. The constructor arguments are
used to initialize the attributes of the same names.
:exc:`DocTestFailure` defines the following attributes:
.. attribute:: DocTestFailure.test
The :class:`DocTest` object that was being run when the example failed.
.. attribute:: DocTestFailure.example
The :class:`Example` that failed.
.. attribute:: DocTestFailure.got
The example's actual output.
.. exception:: UnexpectedException(test, example, exc_info)
An exception raised by :class:`DocTestRunner` to signal that a doctest
example raised an unexpected exception. The constructor arguments are used
to initialize the attributes of the same names.
:exc:`UnexpectedException` defines the following attributes:
.. attribute:: UnexpectedException.test
The :class:`DocTest` object that was being run when the example failed.
.. attribute:: UnexpectedException.example
The :class:`Example` that failed.
.. attribute:: UnexpectedException.exc_info
A tuple containing information about the unexpected exception, as returned by
:func:`sys.exc_info`.
.. _doctest-soapbox:
Soapbox
-------
As mentioned in the introduction, :mod:`doctest` has grown to have three primary
uses:
#. Checking examples in docstrings.
#. Regression testing.
#. Executable documentation / literate testing.
These uses have different requirements, and it is important to distinguish them.
In particular, filling your docstrings with obscure test cases makes for bad
documentation.
When writing a docstring, choose docstring examples with care. There's an art to
this that needs to be learned---it may not be natural at first. Examples should
add genuine value to the documentation. A good example can often be worth many
words. If done with care, the examples will be invaluable for your users, and
will pay back the time it takes to collect them many times over as the years go
by and things change. I'm still amazed at how often one of my :mod:`doctest`
examples stops working after a "harmless" change.
Doctest also makes an excellent tool for regression testing, especially if you
don't skimp on explanatory text. By interleaving prose and examples, it becomes
much easier to keep track of what's actually being tested, and why. When a test
fails, good prose can make it much easier to figure out what the problem is, and
how it should be fixed. It's true that you could write extensive comments in
code-based testing, but few programmers do. Many have found that using doctest
approaches instead leads to much clearer tests. Perhaps this is simply because
doctest makes writing prose a little easier than writing code, while writing
comments in code is a little harder. I think it goes deeper than just that:
the natural attitude when writing a doctest-based test is that you want to
explain the fine points of your software, and illustrate them with examples.
This in turn naturally leads to test files that start with the simplest
features, and logically progress to complications and edge cases. A coherent
narrative is the result, instead of a collection of isolated functions that test
isolated bits of functionality seemingly at random. It's a different attitude,
and produces different results, blurring the distinction between testing and
explaining.
Regression testing is best confined to dedicated objects or files. There are
several options for organizing tests:
* Write text files containing test cases as interactive examples, and test the
files using :func:`testfile` or :func:`DocFileSuite`. This is recommended,
although is easiest to do for new projects, designed from the start to use
doctest.
* Define functions named ``_regrtest_topic`` that consist of single docstrings,
containing test cases for the named topics. These functions can be included in
the same file as the module, or separated out into a separate test file.
* Define a ``__test__`` dictionary mapping from regression test topics to
docstrings containing test cases.
When you have placed your tests in a module, the module can itself be the test
runner. When a test fails, you can arrange for your test runner to re-run only
the failing doctest while you debug the problem. Here is a minimal example of
such a test runner::
if __name__ == '__main__':
import doctest
flags = doctest.REPORT_NDIFF|doctest.REPORT_ONLY_FIRST_FAILURE
if len(sys.argv) > 1:
name = sys.argv[1]
if name in globals():
obj = globals()[name]
else:
obj = __test__[name]
doctest.run_docstring_examples(obj, globals(), name=name,
optionflags=flags)
else:
fail, total = doctest.testmod(optionflags=flags)
print("{} failures out of {} tests".format(fail, total))
.. rubric:: Footnotes
.. [#] Examples containing both expected output and an exception are not supported.
Trying to guess where one ends and the other begins is too error-prone, and that
also makes for a confusing test.
PK %�\�S�2� � - html/_sources/library/docxmlrpcserver.rst.txtnu �[��� :mod:`DocXMLRPCServer` --- Self-documenting XML-RPC server
==========================================================
.. module:: DocXMLRPCServer
:synopsis: Self-documenting XML-RPC server implementation.
.. moduleauthor:: Brian Quinlan <brianq@activestate.com>
.. sectionauthor:: Brian Quinlan <brianq@activestate.com>
.. note::
The :mod:`DocXMLRPCServer` module has been merged into :mod:`xmlrpc.server`
in Python 3. The :term:`2to3` tool will automatically adapt imports when
converting your sources to Python 3.
.. versionadded:: 2.3
The :mod:`DocXMLRPCServer` module extends the classes found in
:mod:`SimpleXMLRPCServer` to serve HTML documentation in response to HTTP GET
requests. Servers can either be free standing, using :class:`~DocXMLRPCServer.DocXMLRPCServer`,
or embedded in a CGI environment, using :class:`DocCGIXMLRPCRequestHandler`.
.. class:: DocXMLRPCServer(addr[, requestHandler[, logRequests[, allow_none[, encoding[, bind_and_activate]]]]])
Create a new server instance. All parameters have the same meaning as for
:class:`SimpleXMLRPCServer.SimpleXMLRPCServer`; *requestHandler* defaults to
:class:`DocXMLRPCRequestHandler`.
.. class:: DocCGIXMLRPCRequestHandler()
Create a new instance to handle XML-RPC requests in a CGI environment.
.. class:: DocXMLRPCRequestHandler()
Create a new request handler instance. This request handler supports XML-RPC
POST requests, documentation GET requests, and modifies logging so that the
*logRequests* parameter to the :class:`~DocXMLRPCServer.DocXMLRPCServer` constructor parameter is
honored.
.. _doc-xmlrpc-servers:
DocXMLRPCServer Objects
-----------------------
The :class:`~DocXMLRPCServer.DocXMLRPCServer` class is derived from
:class:`SimpleXMLRPCServer.SimpleXMLRPCServer` and provides a means of creating
self-documenting, stand alone XML-RPC servers. HTTP POST requests are handled as
XML-RPC method calls. HTTP GET requests are handled by generating pydoc-style
HTML documentation. This allows a server to provide its own web-based
documentation.
.. method:: DocXMLRPCServer.set_server_title(server_title)
Set the title used in the generated HTML documentation. This title will be used
inside the HTML "title" element.
.. method:: DocXMLRPCServer.set_server_name(server_name)
Set the name used in the generated HTML documentation. This name will appear at
the top of the generated documentation inside a "h1" element.
.. method:: DocXMLRPCServer.set_server_documentation(server_documentation)
Set the description used in the generated HTML documentation. This description
will appear as a paragraph, below the server name, in the documentation.
DocCGIXMLRPCRequestHandler
--------------------------
The :class:`DocCGIXMLRPCRequestHandler` class is derived from
:class:`SimpleXMLRPCServer.CGIXMLRPCRequestHandler` and provides a means of
creating self-documenting, XML-RPC CGI scripts. HTTP POST requests are handled
as XML-RPC method calls. HTTP GET requests are handled by generating pydoc-style
HTML documentation. This allows a server to provide its own web-based
documentation.
.. method:: DocCGIXMLRPCRequestHandler.set_server_title(server_title)
Set the title used in the generated HTML documentation. This title will be used
inside the HTML "title" element.
.. method:: DocCGIXMLRPCRequestHandler.set_server_name(server_name)
Set the name used in the generated HTML documentation. This name will appear at
the top of the generated documentation inside a "h1" element.
.. method:: DocCGIXMLRPCRequestHandler.set_server_documentation(server_documentation)
Set the description used in the generated HTML documentation. This description
will appear as a paragraph, below the server name, in the documentation.
PK %�\8��� % html/_sources/library/dumbdbm.rst.txtnu �[��� :mod:`dumbdbm` --- Portable DBM implementation
==============================================
.. module:: dumbdbm
:synopsis: Portable implementation of the simple DBM interface.
.. note::
The :mod:`dumbdbm` module has been renamed to :mod:`dbm.dumb` in Python 3.
The :term:`2to3` tool will automatically adapt imports when converting your
sources to Python 3.
.. index:: single: databases
.. note::
The :mod:`dumbdbm` module is intended as a last resort fallback for the
:mod:`anydbm` module when no more robust module is available. The :mod:`dumbdbm`
module is not written for speed and is not nearly as heavily used as the other
database modules.
The :mod:`dumbdbm` module provides a persistent dictionary-like interface which
is written entirely in Python. Unlike other modules such as :mod:`gdbm` and
:mod:`bsddb`, no external library is required. As with other persistent
mappings, the keys and values must always be strings.
The module defines the following:
.. exception:: error
Raised on dumbdbm-specific errors, such as I/O errors. :exc:`KeyError` is
raised for general mapping errors like specifying an incorrect key.
.. function:: open(filename[, flag[, mode]])
Open a dumbdbm database and return a dumbdbm object. The *filename* argument is
the basename of the database file (without any specific extensions). When a
dumbdbm database is created, files with :file:`.dat` and :file:`.dir` extensions
are created.
The optional *flag* argument is currently ignored; the database is always opened
for update, and will be created if it does not exist.
The optional *mode* argument is the Unix mode of the file, used only when the
database has to be created. It defaults to octal ``0666`` (and will be modified
by the prevailing umask).
.. versionchanged:: 2.2
The *mode* argument was ignored in earlier versions.
In addition to the dictionary-like methods, ``dumbdm`` objects
provide the following method:
.. function:: close()
Close the ``dumbdm`` database.
.. seealso::
Module :mod:`anydbm`
Generic interface to ``dbm``\ -style databases.
Module :mod:`dbm`
Similar interface to the DBM/NDBM library.
Module :mod:`gdbm`
Similar interface to the GNU GDBM library.
Module :mod:`shelve`
Persistence module which stores non-string data.
Module :mod:`whichdb`
Utility module used to determine the type of an existing database.
.. _dumbdbm-objects:
Dumbdbm Objects
---------------
In addition to the methods provided by the :class:`UserDict.DictMixin` class,
:class:`~dumbdbm.dumbdbm` objects provide the following methods.
.. method:: dumbdbm.sync()
Synchronize the on-disk directory and data files. This method is called by the
:meth:`sync` method of :class:`Shelve` objects.
PK %�\�V)v" " * html/_sources/library/dummy_thread.rst.txtnu �[��� :mod:`dummy_thread` --- Drop-in replacement for the :mod:`thread` module
========================================================================
.. module:: dummy_thread
:synopsis: Drop-in replacement for the thread module.
.. note::
The :mod:`dummy_thread` module has been renamed to :mod:`_dummy_thread` in
Python 3. The :term:`2to3` tool will automatically adapt imports when
converting your sources to Python 3; however, you should consider using the
high-lever :mod:`dummy_threading` module instead.
**Source code:** :source:`Lib/dummy_thread.py`
--------------
This module provides a duplicate interface to the :mod:`thread` module. It is
meant to be imported when the :mod:`thread` module is not provided on a
platform.
Suggested usage is::
try:
import thread as _thread
except ImportError:
import dummy_thread as _thread
Be careful to not use this module where deadlock might occur from a thread
being created that blocks waiting for another thread to be created. This often
occurs with blocking I/O.
PK %�\ίxe - html/_sources/library/dummy_threading.rst.txtnu �[��� :mod:`dummy_threading` --- Drop-in replacement for the :mod:`threading` module
==============================================================================
.. module:: dummy_threading
:synopsis: Drop-in replacement for the threading module.
**Source code:** :source:`Lib/dummy_threading.py`
--------------
This module provides a duplicate interface to the :mod:`threading` module. It
is meant to be imported when the :mod:`thread` module is not provided on a
platform.
Suggested usage is::
try:
import threading as _threading
except ImportError:
import dummy_threading as _threading
Be careful to not use this module where deadlock might occur from a thread
being created that blocks waiting for another thread to be created. This often
occurs with blocking I/O.
PK %�\��/�j( j( ) html/_sources/library/easydialogs.rst.txtnu �[���
:mod:`EasyDialogs` --- Basic Macintosh dialogs
==============================================
.. module:: EasyDialogs
:platform: Mac
:synopsis: Basic Macintosh dialogs.
:deprecated:
The :mod:`EasyDialogs` module contains some simple dialogs for the Macintosh.
The dialogs get launched in a separate application which appears in the dock and
must be clicked on for the dialogs be displayed. All routines take an optional
resource ID parameter *id* with which one can override the :const:`DLOG`
resource used for the dialog, provided that the dialog items correspond (both
type and item number) to those in the default :const:`DLOG` resource. See source
code for details.
.. note::
This module has been removed in Python 3.x.
The :mod:`EasyDialogs` module defines the following functions:
.. function:: Message(str[, id[, ok]])
Displays a modal dialog with the message text *str*, which should be at most 255
characters long. The button text defaults to "OK", but is set to the string
argument *ok* if the latter is supplied. Control is returned when the user
clicks the "OK" button.
.. function:: AskString(prompt[, default[, id[, ok[, cancel]]]])
Asks the user to input a string value via a modal dialog. *prompt* is the prompt
message, and the optional *default* supplies the initial value for the string
(otherwise ``""`` is used). The text of the "OK" and "Cancel" buttons can be
changed with the *ok* and *cancel* arguments. All strings can be at most 255
bytes long. :func:`AskString` returns the string entered or :const:`None` in
case the user cancelled.
.. function:: AskPassword(prompt[, default[, id[, ok[, cancel]]]])
Asks the user to input a string value via a modal dialog. Like
:func:`AskString`, but with the text shown as bullets. The arguments have the
same meaning as for :func:`AskString`.
.. function:: AskYesNoCancel(question[, default[, yes[, no[, cancel[, id]]]]])
Presents a dialog with prompt *question* and three buttons labelled "Yes", "No",
and "Cancel". Returns ``1`` for "Yes", ``0`` for "No" and ``-1`` for "Cancel".
The value of *default* (or ``0`` if *default* is not supplied) is returned when
the :kbd:`RETURN` key is pressed. The text of the buttons can be changed with
the *yes*, *no*, and *cancel* arguments; to prevent a button from appearing,
supply ``""`` for the corresponding argument.
.. function:: ProgressBar([title[, maxval[, label[, id]]]])
Displays a modeless progress-bar dialog. This is the constructor for the
:class:`ProgressBar` class described below. *title* is the text string displayed
(default "Working..."), *maxval* is the value at which progress is complete
(default ``0``, indicating that an indeterminate amount of work remains to be
done), and *label* is the text that is displayed above the progress bar itself.
.. function:: GetArgv([optionlist[ commandlist[, addoldfile[, addnewfile[, addfolder[, id]]]]]])
Displays a dialog which aids the user in constructing a command-line argument
list. Returns the list in ``sys.argv`` format, suitable for passing as an
argument to :func:`getopt.getopt`. *addoldfile*, *addnewfile*, and *addfolder*
are boolean arguments. When nonzero, they enable the user to insert into the
command line paths to an existing file, a (possibly) not-yet-existent file, and
a folder, respectively. (Note: Option arguments must appear in the command line
before file and folder arguments in order to be recognized by
:func:`getopt.getopt`.) Arguments containing spaces can be specified by
enclosing them within single or double quotes. A :exc:`SystemExit` exception is
raised if the user presses the "Cancel" button.
*optionlist* is a list that determines a popup menu from which the allowed
options are selected. Its items can take one of two forms: *optstr* or
``(optstr, descr)``. When present, *descr* is a short descriptive string that
is displayed in the dialog while this option is selected in the popup menu. The
correspondence between *optstr*\s and command-line arguments is:
+----------------------+------------------------------------------+
| *optstr* format | Command-line format |
+======================+==========================================+
| ``x`` | :option:`!-x` (short option) |
+----------------------+------------------------------------------+
| ``x:`` or ``x=`` | :option:`!-x` (short option with value) |
+----------------------+------------------------------------------+
| ``xyz`` | :option:`!--xyz` (long option) |
+----------------------+------------------------------------------+
| ``xyz:`` or ``xyz=`` | :option:`!--xyz` (long option with value)|
+----------------------+------------------------------------------+
*commandlist* is a list of items of the form *cmdstr* or ``(cmdstr, descr)``,
where *descr* is as above. The *cmdstr*\ s will appear in a popup menu. When
chosen, the text of *cmdstr* will be appended to the command line as is, except
that a trailing ``':'`` or ``'='`` (if present) will be trimmed off.
.. versionadded:: 2.0
.. function:: AskFileForOpen( [message] [, typeList] [, defaultLocation] [, defaultOptionFlags] [, location] [, clientName] [, windowTitle] [, actionButtonLabel] [, cancelButtonLabel] [, preferenceKey] [, popupExtension] [, eventProc] [, previewProc] [, filterProc] [, wanted] )
Post a dialog asking the user for a file to open, and return the file selected
or :const:`None` if the user cancelled. *message* is a text message to display,
*typeList* is a list of 4-char filetypes allowable, *defaultLocation* is the
pathname, :class:`FSSpec` or :class:`FSRef` of the folder to show initially,
*location* is the ``(x, y)`` position on the screen where the dialog is shown,
*actionButtonLabel* is a string to show instead of "Open" in the OK button,
*cancelButtonLabel* is a string to show instead of "Cancel" in the cancel
button, *wanted* is the type of value wanted as a return: :class:`str`,
:class:`unicode`, :class:`FSSpec`, :class:`FSRef` and subtypes thereof are
acceptable.
.. index:: single: Navigation Services
For a description of the other arguments please see the Apple Navigation
Services documentation and the :mod:`EasyDialogs` source code.
.. function:: AskFileForSave( [message] [, savedFileName] [, defaultLocation] [, defaultOptionFlags] [, location] [, clientName] [, windowTitle] [, actionButtonLabel] [, cancelButtonLabel] [, preferenceKey] [, popupExtension] [, fileType] [, fileCreator] [, eventProc] [, wanted] )
Post a dialog asking the user for a file to save to, and return the file
selected or :const:`None` if the user cancelled. *savedFileName* is the default
for the file name to save to (the return value). See :func:`AskFileForOpen` for
a description of the other arguments.
.. function:: AskFolder( [message] [, defaultLocation] [, defaultOptionFlags] [, location] [, clientName] [, windowTitle] [, actionButtonLabel] [, cancelButtonLabel] [, preferenceKey] [, popupExtension] [, eventProc] [, filterProc] [, wanted] )
Post a dialog asking the user to select a folder, and return the folder selected
or :const:`None` if the user cancelled. See :func:`AskFileForOpen` for a
description of the arguments.
.. seealso::
`Navigation Services Reference <http://developer.apple.com/legacy/mac/library/#documentation/Carbon/Conceptual/NavServicesIntro/ns_intro_carb/ns_into_carb.html>`_
Programmer's reference documentation for the Navigation Services, a part of the
Carbon framework.
.. _progressbar-objects:
ProgressBar Objects
-------------------
:class:`ProgressBar` objects provide support for modeless progress-bar dialogs.
Both determinate (thermometer style) and indeterminate (barber-pole style)
progress bars are supported. The bar will be determinate if its maximum value
is greater than zero; otherwise it will be indeterminate.
.. versionchanged:: 2.2
Support for indeterminate-style progress bars was added.
The dialog is displayed immediately after creation. If the dialog's "Cancel"
button is pressed, or if :kbd:`Cmd-.` or :kbd:`ESC` is typed, the dialog window
is hidden and :exc:`KeyboardInterrupt` is raised (but note that this response
does not occur until the progress bar is next updated, typically via a call to
:meth:`inc` or :meth:`set`). Otherwise, the bar remains visible until the
:class:`ProgressBar` object is discarded.
:class:`ProgressBar` objects possess the following attributes and methods:
.. attribute:: ProgressBar.curval
The current value (of type integer or long integer) of the progress bar. The
normal access methods coerce :attr:`curval` between ``0`` and :attr:`maxval`.
This attribute should not be altered directly.
.. attribute:: ProgressBar.maxval
The maximum value (of type integer or long integer) of the progress bar; the
progress bar (thermometer style) is full when :attr:`curval` equals
:attr:`maxval`. If :attr:`maxval` is ``0``, the bar will be indeterminate
(barber-pole). This attribute should not be altered directly.
.. method:: ProgressBar.title([newstr])
Sets the text in the title bar of the progress dialog to *newstr*.
.. method:: ProgressBar.label([newstr])
Sets the text in the progress box of the progress dialog to *newstr*.
.. method:: ProgressBar.set(value[, max])
Sets the progress bar's :attr:`curval` to *value*, and also :attr:`maxval` to
*max* if the latter is provided. *value* is first coerced between 0 and
:attr:`maxval`. The thermometer bar is updated to reflect the changes,
including a change from indeterminate to determinate or vice versa.
.. method:: ProgressBar.inc([n])
Increments the progress bar's :attr:`curval` by *n*, or by ``1`` if *n* is not
provided. (Note that *n* may be negative, in which case the effect is a
decrement.) The progress bar is updated to reflect the change. If the bar is
indeterminate, this causes one "spin" of the barber pole. The resulting
:attr:`curval` is coerced between 0 and :attr:`maxval` if incrementing causes it
to fall outside this range.
PK %�\�t�v� � , html/_sources/library/email-examples.rst.txtnu �[��� .. _email-examples:
:mod:`email`: Examples
----------------------
Here are a few examples of how to use the :mod:`email` package to read, write,
and send simple email messages, as well as more complex MIME messages.
First, let's see how to create and send a simple text message:
.. literalinclude:: ../includes/email-simple.py
And parsing RFC822 headers can easily be done by the parse(filename) or
parsestr(message_as_string) methods of the Parser() class:
.. literalinclude:: ../includes/email-headers.py
Here's an example of how to send a MIME message containing a bunch of family
pictures that may be residing in a directory:
.. literalinclude:: ../includes/email-mime.py
Here's an example of how to send the entire contents of a directory as an email
message: [1]_
.. literalinclude:: ../includes/email-dir.py
Here's an example of how to unpack a MIME message like the one
above, into a directory of files:
.. literalinclude:: ../includes/email-unpack.py
Here's an example of how to create an HTML message with an alternative plain
text version: [2]_
.. literalinclude:: ../includes/email-alternative.py
.. rubric:: Footnotes
.. [1] Thanks to Matthew Dixon Cowles for the original inspiration and examples.
.. [2] Contributed by Martin Matejek.
PK %�\�hWg�% �% + html/_sources/library/email.charset.rst.txtnu �[��� :mod:`email.charset`: Representing character sets
-------------------------------------------------
.. module:: email.charset
:synopsis: Character Sets
This module provides a class :class:`Charset` for representing character sets
and character set conversions in email messages, as well as a character set
registry and several convenience methods for manipulating this registry.
Instances of :class:`Charset` are used in several other modules within the
:mod:`email` package.
Import this class from the :mod:`email.charset` module.
.. versionadded:: 2.2.2
.. class:: Charset([input_charset])
Map character sets to their email properties.
This class provides information about the requirements imposed on email for a
specific character set. It also provides convenience routines for converting
between character sets, given the availability of the applicable codecs. Given
a character set, it will do its best to provide information on how to use that
character set in an email message in an RFC-compliant way.
Certain character sets must be encoded with quoted-printable or base64 when used
in email headers or bodies. Certain character sets must be converted outright,
and are not allowed in email.
Optional *input_charset* is as described below; it is always coerced to lower
case. After being alias normalized it is also used as a lookup into the
registry of character sets to find out the header encoding, body encoding, and
output conversion codec to be used for the character set. For example, if
*input_charset* is ``iso-8859-1``, then headers and bodies will be encoded using
quoted-printable and no output conversion codec is necessary. If
*input_charset* is ``euc-jp``, then headers will be encoded with base64, bodies
will not be encoded, but output text will be converted from the ``euc-jp``
character set to the ``iso-2022-jp`` character set.
:class:`Charset` instances have the following data attributes:
.. attribute:: input_charset
The initial character set specified. Common aliases are converted to
their *official* email names (e.g. ``latin_1`` is converted to
``iso-8859-1``). Defaults to 7-bit ``us-ascii``.
.. attribute:: header_encoding
If the character set must be encoded before it can be used in an email
header, this attribute will be set to ``Charset.QP`` (for
quoted-printable), ``Charset.BASE64`` (for base64 encoding), or
``Charset.SHORTEST`` for the shortest of QP or BASE64 encoding. Otherwise,
it will be ``None``.
.. attribute:: body_encoding
Same as *header_encoding*, but describes the encoding for the mail
message's body, which indeed may be different than the header encoding.
``Charset.SHORTEST`` is not allowed for *body_encoding*.
.. attribute:: output_charset
Some character sets must be converted before they can be used in email headers
or bodies. If the *input_charset* is one of them, this attribute will
contain the name of the character set output will be converted to. Otherwise, it will
be ``None``.
.. attribute:: input_codec
The name of the Python codec used to convert the *input_charset* to
Unicode. If no conversion codec is necessary, this attribute will be
``None``.
.. attribute:: output_codec
The name of the Python codec used to convert Unicode to the
*output_charset*. If no conversion codec is necessary, this attribute
will have the same value as the *input_codec*.
:class:`Charset` instances also have the following methods:
.. method:: get_body_encoding()
Return the content transfer encoding used for body encoding.
This is either the string ``quoted-printable`` or ``base64`` depending on
the encoding used, or it is a function, in which case you should call the
function with a single argument, the Message object being encoded. The
function should then set the :mailheader:`Content-Transfer-Encoding`
header itself to whatever is appropriate.
Returns the string ``quoted-printable`` if *body_encoding* is ``QP``,
returns the string ``base64`` if *body_encoding* is ``BASE64``, and
returns the string ``7bit`` otherwise.
.. method:: convert(s)
Convert the string *s* from the *input_codec* to the *output_codec*.
.. method:: to_splittable(s)
Convert a possibly multibyte string to a safely splittable format. *s* is
the string to split.
Uses the *input_codec* to try and convert the string to Unicode, so it can
be safely split on character boundaries (even for multibyte characters).
Returns the string as-is if it isn't known how to convert *s* to Unicode
with the *input_charset*.
Characters that could not be converted to Unicode will be replaced with
the Unicode replacement character ``'U+FFFD'``.
.. method:: from_splittable(ustr[, to_output])
Convert a splittable string back into an encoded string. *ustr* is a
Unicode string to "unsplit".
This method uses the proper codec to try and convert the string from
Unicode back into an encoded format. Return the string as-is if it is not
Unicode, or if it could not be converted from Unicode.
Characters that could not be converted from Unicode will be replaced with
an appropriate character (usually ``'?'``).
If *to_output* is ``True`` (the default), uses *output_codec* to convert
to an encoded format. If *to_output* is ``False``, it uses *input_codec*.
.. method:: get_output_charset()
Return the output character set.
This is the *output_charset* attribute if that is not ``None``, otherwise
it is *input_charset*.
.. method:: encoded_header_len()
Return the length of the encoded header string, properly calculating for
quoted-printable or base64 encoding.
.. method:: header_encode(s[, convert])
Header-encode the string *s*.
If *convert* is ``True``, the string will be converted from the input
charset to the output charset automatically. This is not useful for
multibyte character sets, which have line length issues (multibyte
characters must be split on a character, not a byte boundary); use the
higher-level :class:`~email.header.Header` class to deal with these issues
(see :mod:`email.header`). *convert* defaults to ``False``.
The type of encoding (base64 or quoted-printable) will be based on the
*header_encoding* attribute.
.. method:: body_encode(s[, convert])
Body-encode the string *s*.
If *convert* is ``True`` (the default), the string will be converted from
the input charset to output charset automatically. Unlike
:meth:`header_encode`, there are no issues with byte boundaries and
multibyte charsets in email bodies, so this is usually pretty safe.
The type of encoding (base64 or quoted-printable) will be based on the
*body_encoding* attribute.
The :class:`Charset` class also provides a number of methods to support
standard operations and built-in functions.
.. method:: __str__()
Returns *input_charset* as a string coerced to lower
case. :meth:`__repr__` is an alias for :meth:`__str__`.
.. method:: __eq__(other)
This method allows you to compare two :class:`Charset` instances for
equality.
.. method:: __ne__(other)
This method allows you to compare two :class:`Charset` instances for
inequality.
The :mod:`email.charset` module also provides the following functions for adding
new entries to the global character set, alias, and codec registries:
.. function:: add_charset(charset[, header_enc[, body_enc[, output_charset]]])
Add character properties to the global registry.
*charset* is the input character set, and must be the canonical name of a
character set.
Optional *header_enc* and *body_enc* is either ``Charset.QP`` for
quoted-printable, ``Charset.BASE64`` for base64 encoding,
``Charset.SHORTEST`` for the shortest of quoted-printable or base64 encoding,
or ``None`` for no encoding. ``SHORTEST`` is only valid for
*header_enc*. The default is ``None`` for no encoding.
Optional *output_charset* is the character set that the output should be in.
Conversions will proceed from input charset, to Unicode, to the output charset
when the method :meth:`Charset.convert` is called. The default is to output in
the same character set as the input.
Both *input_charset* and *output_charset* must have Unicode codec entries in the
module's character set-to-codec mapping; use :func:`add_codec` to add codecs the
module does not know about. See the :mod:`codecs` module's documentation for
more information.
The global character set registry is kept in the module global dictionary
``CHARSETS``.
.. function:: add_alias(alias, canonical)
Add a character set alias. *alias* is the alias name, e.g. ``latin-1``.
*canonical* is the character set's canonical name, e.g. ``iso-8859-1``.
The global charset alias registry is kept in the module global dictionary
``ALIASES``.
.. function:: add_codec(charset, codecname)
Add a codec that map characters in the given character set to and from Unicode.
*charset* is the canonical name of a character set. *codecname* is the name of a
Python codec, as appropriate for the second argument to the :func:`unicode`
built-in, or to the :meth:`~unicode.encode` method of a Unicode string.
PK %�\��7+H H , html/_sources/library/email.encoders.rst.txtnu �[��� :mod:`email.encoders`: Encoders
-------------------------------
.. module:: email.encoders
:synopsis: Encoders for email message payloads.
When creating :class:`~email.message.Message` objects from scratch, you often
need to encode the payloads for transport through compliant mail servers. This
is especially true for :mimetype:`image/\*` and :mimetype:`text/\*` type messages
containing binary data.
The :mod:`email` package provides some convenient encodings in its
:mod:`encoders` module. These encoders are actually used by the
:class:`~email.mime.audio.MIMEAudio` and :class:`~email.mime.image.MIMEImage`
class constructors to provide default encodings. All encoder functions take
exactly one argument, the message object to encode. They usually extract the
payload, encode it, and reset the payload to this newly encoded value. They
should also set the :mailheader:`Content-Transfer-Encoding` header as appropriate.
Note that these functions are not meaningful for a multipart message. They
must be applied to individual subparts instead, and will raise a
:exc:`TypeError` if passed a message whose type is multipart.
Here are the encoding functions provided:
.. function:: encode_quopri(msg)
Encodes the payload into quoted-printable form and sets the
:mailheader:`Content-Transfer-Encoding` header to ``quoted-printable`` [#]_.
This is a good encoding to use when most of your payload is normal printable
data, but contains a few unprintable characters.
.. function:: encode_base64(msg)
Encodes the payload into base64 form and sets the
:mailheader:`Content-Transfer-Encoding` header to ``base64``. This is a good
encoding to use when most of your payload is unprintable data since it is a more
compact form than quoted-printable. The drawback of base64 encoding is that it
renders the text non-human readable.
.. function:: encode_7or8bit(msg)
This doesn't actually modify the message's payload, but it does set the
:mailheader:`Content-Transfer-Encoding` header to either ``7bit`` or ``8bit`` as
appropriate, based on the payload data.
.. function:: encode_noop(msg)
This does nothing; it doesn't even set the
:mailheader:`Content-Transfer-Encoding` header.
.. rubric:: Footnotes
.. [#] Note that encoding with :meth:`encode_quopri` also encodes all tabs and space
characters in the data.
PK %�\�L؈� � * html/_sources/library/email.errors.rst.txtnu �[��� :mod:`email.errors`: Exception and Defect classes
-------------------------------------------------
.. module:: email.errors
:synopsis: The exception classes used by the email package.
The following exception classes are defined in the :mod:`email.errors` module:
.. exception:: MessageError()
This is the base class for all exceptions that the :mod:`email` package can
raise. It is derived from the standard :exc:`Exception` class and defines no
additional methods.
.. exception:: MessageParseError()
This is the base class for exceptions raised by the :class:`~email.parser.Parser`
class. It is derived from :exc:`MessageError`.
.. exception:: HeaderParseError()
Raised under some error conditions when parsing the :rfc:`2822` headers of a
message, this class is derived from :exc:`MessageParseError`. It can be raised
from the :meth:`Parser.parse <email.parser.Parser.parse>` or
:meth:`Parser.parsestr <email.parser.Parser.parsestr>` methods.
Situations where it can be raised include finding an envelope header after the
first :rfc:`2822` header of the message, finding a continuation line before the
first :rfc:`2822` header is found, or finding a line in the headers which is
neither a header or a continuation line.
.. exception:: BoundaryError()
Raised under some error conditions when parsing the :rfc:`2822` headers of a
message, this class is derived from :exc:`MessageParseError`. It can be raised
from the :meth:`Parser.parse <email.parser.Parser.parse>` or
:meth:`Parser.parsestr <email.parser.Parser.parsestr>` methods.
Situations where it can be raised include not being able to find the starting or
terminating boundary in a :mimetype:`multipart/\*` message when strict parsing
is used.
.. exception:: MultipartConversionError()
Raised when a payload is added to a :class:`~email.message.Message` object
using :meth:`add_payload`, but the payload is already a scalar and the
message's :mailheader:`Content-Type` main type is not either
:mimetype:`multipart` or missing. :exc:`MultipartConversionError` multiply
inherits from :exc:`MessageError` and the built-in :exc:`TypeError`.
Since :meth:`Message.add_payload` is deprecated, this exception is rarely
raised in practice. However the exception may also be raised if the
:meth:`~email.message.Message.attach`
method is called on an instance of a class derived from
:class:`~email.mime.nonmultipart.MIMENonMultipart` (e.g.
:class:`~email.mime.image.MIMEImage`).
Here's the list of the defects that the :class:`~email.parser.FeedParser`
can find while parsing messages. Note that the defects are added to the message
where the problem was found, so for example, if a message nested inside a
:mimetype:`multipart/alternative` had a malformed header, that nested message
object would have a defect, but the containing messages would not.
All defect classes are subclassed from :class:`email.errors.MessageDefect`, but
this class is *not* an exception!
.. versionadded:: 2.4
All the defect classes were added.
* :class:`NoBoundaryInMultipartDefect` -- A message claimed to be a multipart,
but had no :mimetype:`boundary` parameter.
* :class:`StartBoundaryNotFoundDefect` -- The start boundary claimed in the
:mailheader:`Content-Type` header was never found.
* :class:`FirstHeaderLineIsContinuationDefect` -- The message had a continuation
line as its first header line.
* :class:`MisplacedEnvelopeHeaderDefect` - A "Unix From" header was found in the
middle of a header block.
* :class:`MalformedHeaderDefect` -- A header was found that was missing a colon,
or was otherwise malformed.
* :class:`MultipartInvariantViolationDefect` -- A message claimed to be a
:mimetype:`multipart`, but no subparts were found. Note that when a message
has this defect, its :meth:`~email.message.Message.is_multipart` method may
return false even though its content type claims to be :mimetype:`multipart`.
PK %�\4�]�� � - html/_sources/library/email.generator.rst.txtnu �[��� :mod:`email.generator`: Generating MIME documents
-------------------------------------------------
.. module:: email.generator
:synopsis: Generate flat text email messages from a message structure.
One of the most common tasks is to generate the flat text of the email message
represented by a message object structure. You will need to do this if you want
to send your message via the :mod:`smtplib` module or the :mod:`nntplib` module,
or print the message on the console. Taking a message object structure and
producing a flat text document is the job of the :class:`Generator` class.
Again, as with the :mod:`email.parser` module, you aren't limited to the
functionality of the bundled generator; you could write one from scratch
yourself. However the bundled generator knows how to generate most email in a
standards-compliant way, should handle MIME and non-MIME email messages just
fine, and is designed so that the transformation from flat text, to a message
structure via the :class:`~email.parser.Parser` class, and back to flat text,
is idempotent (the input is identical to the output) [#]_. On the other hand,
using the Generator on a :class:`~email.message.Message` constructed by program
may result in changes to the :class:`~email.message.Message` object as defaults
are filled in.
Here are the public methods of the :class:`Generator` class, imported from the
:mod:`email.generator` module:
.. class:: Generator(outfp[, mangle_from_[, maxheaderlen]])
The constructor for the :class:`Generator` class takes a file-like object called
*outfp* for an argument. *outfp* must support the :meth:`write` method and be
usable as the output file in a Python extended print statement.
Optional *mangle_from_* is a flag that, when ``True``, puts a ``>`` character in
front of any line in the body that starts exactly as ``From``, i.e. ``From``
followed by a space at the beginning of the line. This is the only guaranteed
portable way to avoid having such lines be mistaken for a Unix mailbox format
envelope header separator (see `WHY THE CONTENT-LENGTH FORMAT IS BAD
<https://www.jwz.org/doc/content-length.html>`_ for details). *mangle_from_*
defaults to ``True``, but you might want to set this to ``False`` if you are not
writing Unix mailbox format files.
Optional *maxheaderlen* specifies the longest length for a non-continued header.
When a header line is longer than *maxheaderlen* (in characters, with tabs
expanded to 8 spaces), the header will be split as defined in the
:class:`~email.header.Header` class. Set to zero to disable header wrapping.
The default is 78, as recommended (but not required) by :rfc:`2822`.
The other public :class:`Generator` methods are:
.. method:: flatten(msg[, unixfrom])
Print the textual representation of the message object structure rooted at
*msg* to the output file specified when the :class:`Generator` instance
was created. Subparts are visited depth-first and the resulting text will
be properly MIME encoded.
Optional *unixfrom* is a flag that forces the printing of the envelope
header delimiter before the first :rfc:`2822` header of the root message
object. If the root object has no envelope header, a standard one is
crafted. By default, this is set to ``False`` to inhibit the printing of
the envelope delimiter.
Note that for subparts, no envelope header is ever printed.
.. versionadded:: 2.2.2
.. method:: clone(fp)
Return an independent clone of this :class:`Generator` instance with the
exact same options.
.. versionadded:: 2.2.2
.. method:: write(s)
Write the string *s* to the underlying file object, i.e. *outfp* passed to
:class:`Generator`'s constructor. This provides just enough file-like API
for :class:`Generator` instances to be used in extended print statements.
As a convenience, see the methods :meth:`Message.as_string` and
``str(aMessage)``, a.k.a. :meth:`Message.__str__`, which simplify the generation
of a formatted string representation of a message object. For more detail, see
:mod:`email.message`.
The :mod:`email.generator` module also provides a derived class, called
:class:`DecodedGenerator` which is like the :class:`Generator` base class,
except that non-\ :mimetype:`text` parts are substituted with a format string
representing the part.
.. class:: DecodedGenerator(outfp[, mangle_from_[, maxheaderlen[, fmt]]])
This class, derived from :class:`Generator` walks through all the subparts of a
message. If the subpart is of main type :mimetype:`text`, then it prints the
decoded payload of the subpart. Optional *_mangle_from_* and *maxheaderlen* are
as with the :class:`Generator` base class.
If the subpart is not of main type :mimetype:`text`, optional *fmt* is a format
string that is used instead of the message payload. *fmt* is expanded with the
following keywords, ``%(keyword)s`` format:
* ``type`` -- Full MIME type of the non-\ :mimetype:`text` part
* ``maintype`` -- Main MIME type of the non-\ :mimetype:`text` part
* ``subtype`` -- Sub-MIME type of the non-\ :mimetype:`text` part
* ``filename`` -- Filename of the non-\ :mimetype:`text` part
* ``description`` -- Description associated with the non-\ :mimetype:`text` part
* ``encoding`` -- Content transfer encoding of the non-\ :mimetype:`text` part
The default value for *fmt* is ``None``, meaning ::
[Non-text (%(type)s) part of message omitted, filename %(filename)s]
.. versionadded:: 2.2.2
.. versionchanged:: 2.5
The previously deprecated method :meth:`__call__` was removed.
.. rubric:: Footnotes
.. [#] This statement assumes that you use the appropriate setting for the
``unixfrom`` argument, and that you set maxheaderlen=0 (which will
preserve whatever the input line lengths were). It is also not strictly
true, since in many cases runs of whitespace in headers are collapsed
into single blanks. The latter is a bug that will eventually be fixed.
PK %�\� �~k k * html/_sources/library/email.header.rst.txtnu �[��� :mod:`email.header`: Internationalized headers
----------------------------------------------
.. module:: email.header
:synopsis: Representing non-ASCII headers
:rfc:`2822` is the base standard that describes the format of email messages.
It derives from the older :rfc:`822` standard which came into widespread use at
a time when most email was composed of ASCII characters only. :rfc:`2822` is a
specification written assuming email contains only 7-bit ASCII characters.
Of course, as email has been deployed worldwide, it has become
internationalized, such that language specific character sets can now be used in
email messages. The base standard still requires email messages to be
transferred using only 7-bit ASCII characters, so a slew of RFCs have been
written describing how to encode email containing non-ASCII characters into
:rfc:`2822`\ -compliant format. These RFCs include :rfc:`2045`, :rfc:`2046`,
:rfc:`2047`, and :rfc:`2231`. The :mod:`email` package supports these standards
in its :mod:`email.header` and :mod:`email.charset` modules.
If you want to include non-ASCII characters in your email headers, say in the
:mailheader:`Subject` or :mailheader:`To` fields, you should use the
:class:`Header` class and assign the field in the :class:`~email.message.Message`
object to an instance of :class:`Header` instead of using a string for the header
value. Import the :class:`Header` class from the :mod:`email.header` module.
For example::
>>> from email.message import Message
>>> from email.header import Header
>>> msg = Message()
>>> h = Header('p\xf6stal', 'iso-8859-1')
>>> msg['Subject'] = h
>>> print msg.as_string()
Subject: =?iso-8859-1?q?p=F6stal?=
Notice here how we wanted the :mailheader:`Subject` field to contain a non-ASCII
character? We did this by creating a :class:`Header` instance and passing in
the character set that the byte string was encoded in. When the subsequent
:class:`~email.message.Message` instance was flattened, the :mailheader:`Subject`
field was properly :rfc:`2047` encoded. MIME-aware mail readers would show this
header using the embedded ISO-8859-1 character.
.. versionadded:: 2.2.2
Here is the :class:`Header` class description:
.. class:: Header([s[, charset[, maxlinelen[, header_name[, continuation_ws[, errors]]]]]])
Create a MIME-compliant header that can contain strings in different character
sets.
Optional *s* is the initial header value. If ``None`` (the default), the
initial header value is not set. You can later append to the header with
:meth:`append` method calls. *s* may be a byte string or a Unicode string, but
see the :meth:`append` documentation for semantics.
Optional *charset* serves two purposes: it has the same meaning as the *charset*
argument to the :meth:`append` method. It also sets the default character set
for all subsequent :meth:`append` calls that omit the *charset* argument. If
*charset* is not provided in the constructor (the default), the ``us-ascii``
character set is used both as *s*'s initial charset and as the default for
subsequent :meth:`append` calls.
The maximum line length can be specified explicitly via *maxlinelen*. For
splitting the first line to a shorter value (to account for the field header
which isn't included in *s*, e.g. :mailheader:`Subject`) pass in the name of the
field in *header_name*. The default *maxlinelen* is 76, and the default value
for *header_name* is ``None``, meaning it is not taken into account for the
first line of a long, split header.
Optional *continuation_ws* must be :rfc:`2822`\ -compliant folding whitespace,
and is usually either a space or a hard tab character. This character will be
prepended to continuation lines. *continuation_ws* defaults to a single
space character (" ").
Optional *errors* is passed straight through to the :meth:`append` method.
.. method:: append(s[, charset[, errors]])
Append the string *s* to the MIME header.
Optional *charset*, if given, should be a :class:`~email.charset.Charset`
instance (see :mod:`email.charset`) or the name of a character set, which
will be converted to a :class:`~email.charset.Charset` instance. A value
of ``None`` (the default) means that the *charset* given in the constructor
is used.
*s* may be a byte string or a Unicode string. If it is a byte string
(i.e. ``isinstance(s, str)`` is true), then *charset* is the encoding of
that byte string, and a :exc:`UnicodeError` will be raised if the string
cannot be decoded with that character set.
If *s* is a Unicode string, then *charset* is a hint specifying the
character set of the characters in the string. In this case, when
producing an :rfc:`2822`\ -compliant header using :rfc:`2047` rules, the
Unicode string will be encoded using the following charsets in order:
``us-ascii``, the *charset* hint, ``utf-8``. The first character set to
not provoke a :exc:`UnicodeError` is used.
Optional *errors* is passed through to any :func:`unicode` or
:meth:`unicode.encode` call, and defaults to "strict".
.. method:: encode([splitchars])
Encode a message header into an RFC-compliant format, possibly wrapping
long lines and encapsulating non-ASCII parts in base64 or quoted-printable
encodings. Optional *splitchars* is a string containing characters to
split long ASCII lines on, in rough support of :rfc:`2822`'s *highest
level syntactic breaks*. This doesn't affect :rfc:`2047` encoded lines.
The :class:`Header` class also provides a number of methods to support
standard operators and built-in functions.
.. method:: __str__()
A synonym for :meth:`Header.encode`. Useful for ``str(aHeader)``.
.. method:: __unicode__()
A helper for the built-in :func:`unicode` function. Returns the header as
a Unicode string.
.. method:: __eq__(other)
This method allows you to compare two :class:`Header` instances for
equality.
.. method:: __ne__(other)
This method allows you to compare two :class:`Header` instances for
inequality.
The :mod:`email.header` module also provides the following convenient functions.
.. function:: decode_header(header)
Decode a message header value without converting the character set. The header
value is in *header*.
This function returns a list of ``(decoded_string, charset)`` pairs containing
each of the decoded parts of the header. *charset* is ``None`` for non-encoded
parts of the header, otherwise a lower case string containing the name of the
character set specified in the encoded string.
Here's an example::
>>> from email.header import decode_header
>>> decode_header('=?iso-8859-1?q?p=F6stal?=')
[('p\xf6stal', 'iso-8859-1')]
.. function:: make_header(decoded_seq[, maxlinelen[, header_name[, continuation_ws]]])
Create a :class:`Header` instance from a sequence of pairs as returned by
:func:`decode_header`.
:func:`decode_header` takes a header value string and returns a sequence of
pairs of the format ``(decoded_string, charset)`` where *charset* is the name of
the character set.
This function takes one of those sequence of pairs and returns a :class:`Header`
instance. Optional *maxlinelen*, *header_name*, and *continuation_ws* are as in
the :class:`Header` constructor.
PK %�\N�`
u u - html/_sources/library/email.iterators.rst.txtnu �[��� :mod:`email.iterators`: Iterators
---------------------------------
.. module:: email.iterators
:synopsis: Iterate over a message object tree.
Iterating over a message object tree is fairly easy with the
:meth:`Message.walk <email.message.Message.walk>` method. The
:mod:`email.iterators` module provides some useful higher level iterations over
message object trees.
.. function:: body_line_iterator(msg[, decode])
This iterates over all the payloads in all the subparts of *msg*, returning the
string payloads line-by-line. It skips over all the subpart headers, and it
skips over any subpart with a payload that isn't a Python string. This is
somewhat equivalent to reading the flat text representation of the message from
a file using :meth:`~io.TextIOBase.readline`, skipping over all the
intervening headers.
Optional *decode* is passed through to :meth:`Message.get_payload
<email.message.Message.get_payload>`.
.. function:: typed_subpart_iterator(msg[, maintype[, subtype]])
This iterates over all the subparts of *msg*, returning only those subparts that
match the MIME type specified by *maintype* and *subtype*.
Note that *subtype* is optional; if omitted, then subpart MIME type matching is
done only with the main type. *maintype* is optional too; it defaults to
:mimetype:`text`.
Thus, by default :func:`typed_subpart_iterator` returns each subpart that has a
MIME type of :mimetype:`text/\*`.
The following function has been added as a useful debugging tool. It should
*not* be considered part of the supported public interface for the package.
.. function:: _structure(msg[, fp[, level]])
Prints an indented representation of the content types of the message object
structure. For example::
>>> msg = email.message_from_file(somefile)
>>> _structure(msg)
multipart/mixed
text/plain
text/plain
multipart/digest
message/rfc822
text/plain
message/rfc822
text/plain
message/rfc822
text/plain
message/rfc822
text/plain
message/rfc822
text/plain
text/plain
Optional *fp* is a file-like object to print the output to. It must be suitable
for Python's extended print statement. *level* is used internally.
PK %�\�1�6�b �b + html/_sources/library/email.message.rst.txtnu �[��� :mod:`email.message`: Representing an email message
---------------------------------------------------
.. module:: email.message
:synopsis: The base class representing email messages.
The central class in the :mod:`email` package is the :class:`Message` class,
imported from the :mod:`email.message` module. It is the base class for the
:mod:`email` object model. :class:`Message` provides the core functionality for
setting and querying header fields, and for accessing message bodies.
Conceptually, a :class:`Message` object consists of *headers* and *payloads*.
Headers are :rfc:`2822` style field names and values where the field name and
value are separated by a colon. The colon is not part of either the field name
or the field value.
Headers are stored and returned in case-preserving form but are matched
case-insensitively. There may also be a single envelope header, also known as
the *Unix-From* header or the ``From_`` header. The payload is either a string
in the case of simple message objects or a list of :class:`Message` objects for
MIME container documents (e.g. :mimetype:`multipart/\*` and
:mimetype:`message/rfc822`).
:class:`Message` objects provide a mapping style interface for accessing the
message headers, and an explicit interface for accessing both the headers and
the payload. It provides convenience methods for generating a flat text
representation of the message object tree, for accessing commonly used header
parameters, and for recursively walking over the object tree.
Here are the methods of the :class:`Message` class:
.. class:: Message()
The constructor takes no arguments.
.. method:: as_string([unixfrom])
Return the entire message flattened as a string. When optional *unixfrom*
is ``True``, the envelope header is included in the returned string.
*unixfrom* defaults to ``False``. Flattening the message may trigger
changes to the :class:`Message` if defaults need to be filled in to
complete the transformation to a string (for example, MIME boundaries may
be generated or modified).
Note that this method is provided as a convenience and may not always
format the message the way you want. For example, by default it mangles
lines that begin with ``From``. For more flexibility, instantiate a
:class:`~email.generator.Generator` instance and use its
:meth:`~email.generator.Generator.flatten` method directly. For example::
from cStringIO import StringIO
from email.generator import Generator
fp = StringIO()
g = Generator(fp, mangle_from_=False, maxheaderlen=60)
g.flatten(msg)
text = fp.getvalue()
.. method:: __str__()
Equivalent to ``as_string(unixfrom=True)``.
.. method:: is_multipart()
Return ``True`` if the message's payload is a list of sub-\
:class:`Message` objects, otherwise return ``False``. When
:meth:`is_multipart` returns ``False``, the payload should be a string object.
.. method:: set_unixfrom(unixfrom)
Set the message's envelope header to *unixfrom*, which should be a string.
.. method:: get_unixfrom()
Return the message's envelope header. Defaults to ``None`` if the
envelope header was never set.
.. method:: attach(payload)
Add the given *payload* to the current payload, which must be ``None`` or
a list of :class:`Message` objects before the call. After the call, the
payload will always be a list of :class:`Message` objects. If you want to
set the payload to a scalar object (e.g. a string), use
:meth:`set_payload` instead.
.. method:: get_payload([i[, decode]])
Return the current payload, which will be a list of
:class:`Message` objects when :meth:`is_multipart` is ``True``, or a
string when :meth:`is_multipart` is ``False``. If the payload is a list
and you mutate the list object, you modify the message's payload in place.
With optional argument *i*, :meth:`get_payload` will return the *i*-th
element of the payload, counting from zero, if :meth:`is_multipart` is
``True``. An :exc:`IndexError` will be raised if *i* is less than 0 or
greater than or equal to the number of items in the payload. If the
payload is a string (i.e. :meth:`is_multipart` is ``False``) and *i* is
given, a :exc:`TypeError` is raised.
Optional *decode* is a flag indicating whether the payload should be
decoded or not, according to the :mailheader:`Content-Transfer-Encoding`
header. When ``True`` and the message is not a multipart, the payload will
be decoded if this header's value is ``quoted-printable`` or ``base64``.
If some other encoding is used, or :mailheader:`Content-Transfer-Encoding`
header is missing, or if the payload has bogus base64 data, the payload is
returned as-is (undecoded). If the message is a multipart and the
*decode* flag is ``True``, then ``None`` is returned. The default for
*decode* is ``False``.
.. method:: set_payload(payload[, charset])
Set the entire message object's payload to *payload*. It is the client's
responsibility to ensure the payload invariants. Optional *charset* sets
the message's default character set; see :meth:`set_charset` for details.
.. versionchanged:: 2.2.2
*charset* argument added.
.. method:: set_charset(charset)
Set the character set of the payload to *charset*, which can either be a
:class:`~email.charset.Charset` instance (see :mod:`email.charset`), a
string naming a character set, or ``None``. If it is a string, it will
be converted to a :class:`~email.charset.Charset` instance. If *charset*
is ``None``, the ``charset`` parameter will be removed from the
:mailheader:`Content-Type` header (the message will not be otherwise
modified). Anything else will generate a :exc:`TypeError`.
If there is no existing :mailheader:`MIME-Version` header one will be
added. If there is no existing :mailheader:`Content-Type` header, one
will be added with a value of :mimetype:`text/plain`. Whether the
:mailheader:`Content-Type` header already exists or not, its ``charset``
parameter will be set to *charset.output_charset*. If
*charset.input_charset* and *charset.output_charset* differ, the payload
will be re-encoded to the *output_charset*. If there is no existing
:mailheader:`Content-Transfer-Encoding` header, then the payload will be
transfer-encoded, if needed, using the specified
:class:`~email.charset.Charset`, and a header with the appropriate value
will be added. If a :mailheader:`Content-Transfer-Encoding` header
already exists, the payload is assumed to already be correctly encoded
using that :mailheader:`Content-Transfer-Encoding` and is not modified.
The message will be assumed to be of type :mimetype:`text/\*`, with the
payload either in unicode or encoded with *charset.input_charset*.
It will be encoded or converted to *charset.output_charset*
and transfer encoded properly, if needed, when generating the plain text
representation of the message. MIME headers (:mailheader:`MIME-Version`,
:mailheader:`Content-Type`, :mailheader:`Content-Transfer-Encoding`) will
be added as needed.
.. versionadded:: 2.2.2
.. method:: get_charset()
Return the :class:`~email.charset.Charset` instance associated with the
message's payload.
.. versionadded:: 2.2.2
The following methods implement a mapping-like interface for accessing the
message's :rfc:`2822` headers. Note that there are some semantic differences
between these methods and a normal mapping (i.e. dictionary) interface. For
example, in a dictionary there are no duplicate keys, but here there may be
duplicate message headers. Also, in dictionaries there is no guaranteed
order to the keys returned by :meth:`keys`, but in a :class:`Message` object,
headers are always returned in the order they appeared in the original
message, or were added to the message later. Any header deleted and then
re-added are always appended to the end of the header list.
These semantic differences are intentional and are biased toward maximal
convenience.
Note that in all cases, any envelope header present in the message is not
included in the mapping interface.
.. method:: __len__()
Return the total number of headers, including duplicates.
.. method:: __contains__(name)
Return true if the message object has a field named *name*. Matching is
done case-insensitively and *name* should not include the trailing colon.
Used for the ``in`` operator, e.g.::
if 'message-id' in myMessage:
print 'Message-ID:', myMessage['message-id']
.. method:: __getitem__(name)
Return the value of the named header field. *name* should not include the
colon field separator. If the header is missing, ``None`` is returned; a
:exc:`KeyError` is never raised.
Note that if the named field appears more than once in the message's
headers, exactly which of those field values will be returned is
undefined. Use the :meth:`get_all` method to get the values of all the
extant named headers.
.. method:: __setitem__(name, val)
Add a header to the message with field name *name* and value *val*. The
field is appended to the end of the message's existing fields.
Note that this does *not* overwrite or delete any existing header with the same
name. If you want to ensure that the new header is the only one present in the
message with field name *name*, delete the field first, e.g.::
del msg['subject']
msg['subject'] = 'Python roolz!'
.. method:: __delitem__(name)
Delete all occurrences of the field with name *name* from the message's
headers. No exception is raised if the named field isn't present in the headers.
.. method:: has_key(name)
Return true if the message contains a header field named *name*, otherwise
return false.
.. method:: keys()
Return a list of all the message's header field names.
.. method:: values()
Return a list of all the message's field values.
.. method:: items()
Return a list of 2-tuples containing all the message's field headers and
values.
.. method:: get(name[, failobj])
Return the value of the named header field. This is identical to
:meth:`__getitem__` except that optional *failobj* is returned if the
named header is missing (defaults to ``None``).
Here are some additional useful methods:
.. method:: get_all(name[, failobj])
Return a list of all the values for the field named *name*. If there are
no such named headers in the message, *failobj* is returned (defaults to
``None``).
.. method:: add_header(_name, _value, **_params)
Extended header setting. This method is similar to :meth:`__setitem__`
except that additional header parameters can be provided as keyword
arguments. *_name* is the header field to add and *_value* is the
*primary* value for the header.
For each item in the keyword argument dictionary *_params*, the key is
taken as the parameter name, with underscores converted to dashes (since
dashes are illegal in Python identifiers). Normally, the parameter will
be added as ``key="value"`` unless the value is ``None``, in which case
only the key will be added. If the value contains non-ASCII characters,
it must be specified as a three tuple in the format
``(CHARSET, LANGUAGE, VALUE)``, where ``CHARSET`` is a string naming the
charset to be used to encode the value, ``LANGUAGE`` can usually be set
to ``None`` or the empty string (see :RFC:`2231` for other possibilities),
and ``VALUE`` is the string value containing non-ASCII code points.
Here's an example::
msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')
This will add a header that looks like ::
Content-Disposition: attachment; filename="bud.gif"
An example with non-ASCII characters::
msg.add_header('Content-Disposition', 'attachment',
filename=('iso-8859-1', '', 'Fußballer.ppt'))
Which produces ::
Content-Disposition: attachment; filename*="iso-8859-1''Fu%DFballer.ppt"
.. method:: replace_header(_name, _value)
Replace a header. Replace the first header found in the message that
matches *_name*, retaining header order and field name case. If no
matching header was found, a :exc:`KeyError` is raised.
.. versionadded:: 2.2.2
.. method:: get_content_type()
Return the message's content type. The returned string is coerced to
lower case of the form :mimetype:`maintype/subtype`. If there was no
:mailheader:`Content-Type` header in the message the default type as given
by :meth:`get_default_type` will be returned. Since according to
:rfc:`2045`, messages always have a default type, :meth:`get_content_type`
will always return a value.
:rfc:`2045` defines a message's default type to be :mimetype:`text/plain`
unless it appears inside a :mimetype:`multipart/digest` container, in
which case it would be :mimetype:`message/rfc822`. If the
:mailheader:`Content-Type` header has an invalid type specification,
:rfc:`2045` mandates that the default type be :mimetype:`text/plain`.
.. versionadded:: 2.2.2
.. method:: get_content_maintype()
Return the message's main content type. This is the :mimetype:`maintype`
part of the string returned by :meth:`get_content_type`.
.. versionadded:: 2.2.2
.. method:: get_content_subtype()
Return the message's sub-content type. This is the :mimetype:`subtype`
part of the string returned by :meth:`get_content_type`.
.. versionadded:: 2.2.2
.. method:: get_default_type()
Return the default content type. Most messages have a default content
type of :mimetype:`text/plain`, except for messages that are subparts of
:mimetype:`multipart/digest` containers. Such subparts have a default
content type of :mimetype:`message/rfc822`.
.. versionadded:: 2.2.2
.. method:: set_default_type(ctype)
Set the default content type. *ctype* should either be
:mimetype:`text/plain` or :mimetype:`message/rfc822`, although this is not
enforced. The default content type is not stored in the
:mailheader:`Content-Type` header.
.. versionadded:: 2.2.2
.. method:: get_params([failobj[, header[, unquote]]])
Return the message's :mailheader:`Content-Type` parameters, as a list.
The elements of the returned list are 2-tuples of key/value pairs, as
split on the ``'='`` sign. The left hand side of the ``'='`` is the key,
while the right hand side is the value. If there is no ``'='`` sign in
the parameter the value is the empty string, otherwise the value is as
described in :meth:`get_param` and is unquoted if optional *unquote* is
``True`` (the default).
Optional *failobj* is the object to return if there is no
:mailheader:`Content-Type` header. Optional *header* is the header to
search instead of :mailheader:`Content-Type`.
.. versionchanged:: 2.2.2
*unquote* argument added.
.. method:: get_param(param[, failobj[, header[, unquote]]])
Return the value of the :mailheader:`Content-Type` header's parameter
*param* as a string. If the message has no :mailheader:`Content-Type`
header or if there is no such parameter, then *failobj* is returned
(defaults to ``None``).
Optional *header* if given, specifies the message header to use instead of
:mailheader:`Content-Type`.
Parameter keys are always compared case insensitively. The return value
can either be a string, or a 3-tuple if the parameter was :rfc:`2231`
encoded. When it's a 3-tuple, the elements of the value are of the form
``(CHARSET, LANGUAGE, VALUE)``. Note that both ``CHARSET`` and
``LANGUAGE`` can be ``None``, in which case you should consider ``VALUE``
to be encoded in the ``us-ascii`` charset. You can usually ignore
``LANGUAGE``.
If your application doesn't care whether the parameter was encoded as in
:rfc:`2231`, you can collapse the parameter value by calling
:func:`email.utils.collapse_rfc2231_value`, passing in the return value
from :meth:`get_param`. This will return a suitably decoded Unicode
string when the value is a tuple, or the original string unquoted if it
isn't. For example::
rawparam = msg.get_param('foo')
param = email.utils.collapse_rfc2231_value(rawparam)
In any case, the parameter value (either the returned string, or the
``VALUE`` item in the 3-tuple) is always unquoted, unless *unquote* is set
to ``False``.
.. versionchanged:: 2.2.2
*unquote* argument added, and 3-tuple return value possible.
.. method:: set_param(param, value[, header[, requote[, charset[, language]]]])
Set a parameter in the :mailheader:`Content-Type` header. If the
parameter already exists in the header, its value will be replaced with
*value*. If the :mailheader:`Content-Type` header as not yet been defined
for this message, it will be set to :mimetype:`text/plain` and the new
parameter value will be appended as per :rfc:`2045`.
Optional *header* specifies an alternative header to
:mailheader:`Content-Type`, and all parameters will be quoted as necessary
unless optional *requote* is ``False`` (the default is ``True``).
If optional *charset* is specified, the parameter will be encoded
according to :rfc:`2231`. Optional *language* specifies the RFC 2231
language, defaulting to the empty string. Both *charset* and *language*
should be strings.
.. versionadded:: 2.2.2
.. method:: del_param(param[, header[, requote]])
Remove the given parameter completely from the :mailheader:`Content-Type`
header. The header will be re-written in place without the parameter or
its value. All values will be quoted as necessary unless *requote* is
``False`` (the default is ``True``). Optional *header* specifies an
alternative to :mailheader:`Content-Type`.
.. versionadded:: 2.2.2
.. method:: set_type(type[, header][, requote])
Set the main type and subtype for the :mailheader:`Content-Type`
header. *type* must be a string in the form :mimetype:`maintype/subtype`,
otherwise a :exc:`ValueError` is raised.
This method replaces the :mailheader:`Content-Type` header, keeping all
the parameters in place. If *requote* is ``False``, this leaves the
existing header's quoting as is, otherwise the parameters will be quoted
(the default).
An alternative header can be specified in the *header* argument. When the
:mailheader:`Content-Type` header is set a :mailheader:`MIME-Version`
header is also added.
.. versionadded:: 2.2.2
.. method:: get_filename([failobj])
Return the value of the ``filename`` parameter of the
:mailheader:`Content-Disposition` header of the message. If the header
does not have a ``filename`` parameter, this method falls back to looking
for the ``name`` parameter on the :mailheader:`Content-Type` header. If
neither is found, or the header is missing, then *failobj* is returned.
The returned string will always be unquoted as per
:func:`email.utils.unquote`.
.. method:: get_boundary([failobj])
Return the value of the ``boundary`` parameter of the
:mailheader:`Content-Type` header of the message, or *failobj* if either
the header is missing, or has no ``boundary`` parameter. The returned
string will always be unquoted as per :func:`email.utils.unquote`.
.. method:: set_boundary(boundary)
Set the ``boundary`` parameter of the :mailheader:`Content-Type` header to
*boundary*. :meth:`set_boundary` will always quote *boundary* if
necessary. A :exc:`~email.errors.HeaderParseError` is raised if the
message object has no :mailheader:`Content-Type` header.
Note that using this method is subtly different than deleting the old
:mailheader:`Content-Type` header and adding a new one with the new
boundary via :meth:`add_header`, because :meth:`set_boundary` preserves
the order of the :mailheader:`Content-Type` header in the list of
headers. However, it does *not* preserve any continuation lines which may
have been present in the original :mailheader:`Content-Type` header.
.. method:: get_content_charset([failobj])
Return the ``charset`` parameter of the :mailheader:`Content-Type` header,
coerced to lower case. If there is no :mailheader:`Content-Type` header, or if
that header has no ``charset`` parameter, *failobj* is returned.
Note that this method differs from :meth:`get_charset` which returns the
:class:`~email.charset.Charset` instance for the default encoding of the message body.
.. versionadded:: 2.2.2
.. method:: get_charsets([failobj])
Return a list containing the character set names in the message. If the
message is a :mimetype:`multipart`, then the list will contain one element
for each subpart in the payload, otherwise, it will be a list of length 1.
Each item in the list will be a string which is the value of the
``charset`` parameter in the :mailheader:`Content-Type` header for the
represented subpart. However, if the subpart has no
:mailheader:`Content-Type` header, no ``charset`` parameter, or is not of
the :mimetype:`text` main MIME type, then that item in the returned list
will be *failobj*.
.. method:: walk()
The :meth:`walk` method is an all-purpose generator which can be used to
iterate over all the parts and subparts of a message object tree, in
depth-first traversal order. You will typically use :meth:`walk` as the
iterator in a ``for`` loop; each iteration returns the next subpart.
Here's an example that prints the MIME type of every part of a multipart
message structure::
>>> for part in msg.walk():
... print part.get_content_type()
multipart/report
text/plain
message/delivery-status
text/plain
text/plain
message/rfc822
.. versionchanged:: 2.5
The previously deprecated methods :meth:`get_type`, :meth:`get_main_type`, and
:meth:`get_subtype` were removed.
:class:`Message` objects can also optionally contain two instance attributes,
which can be used when generating the plain text of a MIME message.
.. attribute:: preamble
The format of a MIME document allows for some text between the blank line
following the headers, and the first multipart boundary string. Normally,
this text is never visible in a MIME-aware mail reader because it falls
outside the standard MIME armor. However, when viewing the raw text of
the message, or when viewing the message in a non-MIME aware reader, this
text can become visible.
The *preamble* attribute contains this leading extra-armor text for MIME
documents. When the :class:`~email.parser.Parser` discovers some text
after the headers but before the first boundary string, it assigns this
text to the message's *preamble* attribute. When the
:class:`~email.generator.Generator` is writing out the plain text
representation of a MIME message, and it finds the
message has a *preamble* attribute, it will write this text in the area
between the headers and the first boundary. See :mod:`email.parser` and
:mod:`email.generator` for details.
Note that if the message object has no preamble, the *preamble* attribute
will be ``None``.
.. attribute:: epilogue
The *epilogue* attribute acts the same way as the *preamble* attribute,
except that it contains text that appears between the last boundary and
the end of the message.
.. versionchanged:: 2.5
You do not need to set the epilogue to the empty string in order for the
:class:`~email.generator.Generator` to print a newline at the end of the
file.
.. attribute:: defects
The *defects* attribute contains a list of all the problems found when
parsing this message. See :mod:`email.errors` for a detailed description
of the possible parsing defects.
.. versionadded:: 2.4
PK %�\Yu/v�& �& ( html/_sources/library/email.mime.rst.txtnu �[��� :mod:`email.mime`: Creating email and MIME objects from scratch
---------------------------------------------------------------
.. module:: email.mime
:synopsis: Build MIME messages.
Ordinarily, you get a message object structure by passing a file or some text to
a parser, which parses the text and returns the root message object. However
you can also build a complete message structure from scratch, or even individual
:class:`~email.message.Message` objects by hand. In fact, you can also take an
existing structure and add new :class:`~email.message.Message` objects, move them
around, etc. This makes a very convenient interface for slicing-and-dicing MIME
messages.
You can create a new object structure by creating :class:`~email.message.Message`
instances, adding attachments and all the appropriate headers manually. For MIME
messages though, the :mod:`email` package provides some convenient subclasses to
make things easier.
Here are the classes:
.. currentmodule:: email.mime.base
.. class:: MIMEBase(_maintype, _subtype, **_params)
Module: :mod:`email.mime.base`
This is the base class for all the MIME-specific subclasses of
:class:`~email.message.Message`. Ordinarily you won't create instances
specifically of :class:`MIMEBase`, although you could. :class:`MIMEBase`
is provided primarily as a convenient base class for more specific
MIME-aware subclasses.
*_maintype* is the :mailheader:`Content-Type` major type (e.g. :mimetype:`text`
or :mimetype:`image`), and *_subtype* is the :mailheader:`Content-Type` minor
type (e.g. :mimetype:`plain` or :mimetype:`gif`). *_params* is a parameter
key/value dictionary and is passed directly to :meth:`Message.add_header
<email.message.Message.add_header>`.
The :class:`MIMEBase` class always adds a :mailheader:`Content-Type` header
(based on *_maintype*, *_subtype*, and *_params*), and a
:mailheader:`MIME-Version` header (always set to ``1.0``).
.. currentmodule:: email.mime.nonmultipart
.. class:: MIMENonMultipart()
Module: :mod:`email.mime.nonmultipart`
A subclass of :class:`~email.mime.base.MIMEBase`, this is an intermediate base
class for MIME messages that are not :mimetype:`multipart`. The primary
purpose of this class is to prevent the use of the
:meth:`~email.message.Message.attach` method, which only makes sense for
:mimetype:`multipart` messages. If :meth:`~email.message.Message.attach`
is called, a :exc:`~email.errors.MultipartConversionError` exception is raised.
.. versionadded:: 2.2.2
.. currentmodule:: email.mime.multipart
.. class:: MIMEMultipart([_subtype[, boundary[, _subparts[, _params]]]])
Module: :mod:`email.mime.multipart`
A subclass of :class:`~email.mime.base.MIMEBase`, this is an intermediate base
class for MIME messages that are :mimetype:`multipart`. Optional *_subtype*
defaults to :mimetype:`mixed`, but can be used to specify the subtype of the
message. A :mailheader:`Content-Type` header of :mimetype:`multipart/_subtype`
will be added to the message object. A :mailheader:`MIME-Version` header will
also be added.
Optional *boundary* is the multipart boundary string. When ``None`` (the
default), the boundary is calculated when needed (for example, when the
message is serialized).
*_subparts* is a sequence of initial subparts for the payload. It must be
possible to convert this sequence to a list. You can always attach new subparts
to the message by using the :meth:`Message.attach
<email.message.Message.attach>` method.
Additional parameters for the :mailheader:`Content-Type` header are taken from
the keyword arguments, or passed into the *_params* argument, which is a keyword
dictionary.
.. versionadded:: 2.2.2
.. currentmodule:: email.mime.application
.. class:: MIMEApplication(_data[, _subtype[, _encoder[, **_params]]])
Module: :mod:`email.mime.application`
A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the
:class:`MIMEApplication` class is used to represent MIME message objects of
major type :mimetype:`application`. *_data* is a string containing the raw
byte data. Optional *_subtype* specifies the MIME subtype and defaults to
:mimetype:`octet-stream`.
Optional *_encoder* is a callable (i.e. function) which will perform the actual
encoding of the data for transport. This callable takes one argument, which is
the :class:`MIMEApplication` instance. It should use
:meth:`~email.message.Message.get_payload` and
:meth:`~email.message.Message.set_payload` to change the payload to encoded
form. It should also add
any :mailheader:`Content-Transfer-Encoding` or other headers to the message
object as necessary. The default encoding is base64. See the
:mod:`email.encoders` module for a list of the built-in encoders.
*_params* are passed straight through to the base class constructor.
.. versionadded:: 2.5
.. currentmodule:: email.mime.audio
.. class:: MIMEAudio(_audiodata[, _subtype[, _encoder[, **_params]]])
Module: :mod:`email.mime.audio`
A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the
:class:`MIMEAudio` class is used to create MIME message objects of major type
:mimetype:`audio`. *_audiodata* is a string containing the raw audio data. If
this data can be decoded by the standard Python module :mod:`sndhdr`, then the
subtype will be automatically included in the :mailheader:`Content-Type` header.
Otherwise you can explicitly specify the audio subtype via the *_subtype*
parameter. If the minor type could not be guessed and *_subtype* was not given,
then :exc:`TypeError` is raised.
Optional *_encoder* is a callable (i.e. function) which will perform the actual
encoding of the audio data for transport. This callable takes one argument,
which is the :class:`MIMEAudio` instance. It should use
:meth:`~email.message.Message.get_payload` and
:meth:`~email.message.Message.set_payload` to change the payload to encoded
form. It should also add
any :mailheader:`Content-Transfer-Encoding` or other headers to the message
object as necessary. The default encoding is base64. See the
:mod:`email.encoders` module for a list of the built-in encoders.
*_params* are passed straight through to the base class constructor.
.. currentmodule:: email.mime.image
.. class:: MIMEImage(_imagedata[, _subtype[, _encoder[, **_params]]])
Module: :mod:`email.mime.image`
A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the
:class:`MIMEImage` class is used to create MIME message objects of major type
:mimetype:`image`. *_imagedata* is a string containing the raw image data. If
this data can be decoded by the standard Python module :mod:`imghdr`, then the
subtype will be automatically included in the :mailheader:`Content-Type` header.
Otherwise you can explicitly specify the image subtype via the *_subtype*
parameter. If the minor type could not be guessed and *_subtype* was not given,
then :exc:`TypeError` is raised.
Optional *_encoder* is a callable (i.e. function) which will perform the actual
encoding of the image data for transport. This callable takes one argument,
which is the :class:`MIMEImage` instance. It should use
:meth:`~email.message.Message.get_payload` and
:meth:`~email.message.Message.set_payload` to change the payload to encoded
form. It should also add
any :mailheader:`Content-Transfer-Encoding` or other headers to the message
object as necessary. The default encoding is base64. See the
:mod:`email.encoders` module for a list of the built-in encoders.
*_params* are passed straight through to the :class:`~email.mime.base.MIMEBase`
constructor.
.. currentmodule:: email.mime.message
.. class:: MIMEMessage(_msg[, _subtype])
Module: :mod:`email.mime.message`
A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the
:class:`MIMEMessage` class is used to create MIME objects of main type
:mimetype:`message`. *_msg* is used as the payload, and must be an instance
of class :class:`~email.message.Message` (or a subclass thereof), otherwise
a :exc:`TypeError` is raised.
Optional *_subtype* sets the subtype of the message; it defaults to
:mimetype:`rfc822`.
.. currentmodule:: email.mime.text
.. class:: MIMEText(_text[, _subtype[, _charset]])
Module: :mod:`email.mime.text`
A subclass of :class:`~email.mime.nonmultipart.MIMENonMultipart`, the
:class:`MIMEText` class is used to create MIME objects of major type
:mimetype:`text`. *_text* is the string for the payload. *_subtype* is the
minor type and defaults to :mimetype:`plain`. *_charset* is the character
set of the text and is passed as a parameter to the
:class:`~email.mime.nonmultipart.MIMENonMultipart` constructor; it defaults
to ``us-ascii``. If *_text* is unicode, it is encoded using the
*output_charset* of *_charset*, otherwise it is used as-is.
.. versionchanged:: 2.4
The previously deprecated *_encoding* argument has been removed. Content
Transfer Encoding now happens implicitly based on the *_charset*
argument.
Unless the ``_charset`` parameter is explicitly set to ``None``, the
MIMEText object created will have both a :mailheader:`Content-Type` header
with a ``charset`` parameter, and a :mailheader:`Content-Transfer-Encoding`
header. This means that a subsequent ``set_payload`` call will not result
in an encoded payload, even if a charset is passed in the ``set_payload``
command. You can "reset" this behavior by deleting the
``Content-Transfer-Encoding`` header, after which a ``set_payload`` call
will automatically encode the new payload (and add a new
:mailheader:`Content-Transfer-Encoding` header).
PK %�\���W( W( * html/_sources/library/email.parser.rst.txtnu �[��� :mod:`email.parser`: Parsing email messages
-------------------------------------------
.. module:: email.parser
:synopsis: Parse flat text email messages to produce a message object structure.
Message object structures can be created in one of two ways: they can be created
from whole cloth by instantiating :class:`~email.message.Message` objects and
stringing them together via :meth:`~email.message.Message.attach` and
:meth:`~email.message.Message.set_payload` calls, or they
can be created by parsing a flat text representation of the email message.
The :mod:`email` package provides a standard parser that understands most email
document structures, including MIME documents. You can pass the parser a string
or a file object, and the parser will return to you the root
:class:`~email.message.Message` instance of the object structure. For simple,
non-MIME messages the payload of this root object will likely be a string
containing the text of the message. For MIME messages, the root object will
return ``True`` from its :meth:`~email.message.Message.is_multipart` method, and
the subparts can be accessed via the :meth:`~email.message.Message.get_payload`
and :meth:`~email.message.Message.walk` methods.
There are actually two parser interfaces available for use, the classic
:class:`Parser` API and the incremental :class:`FeedParser` API. The classic
:class:`Parser` API is fine if you have the entire text of the message in memory
as a string, or if the entire message lives in a file on the file system.
:class:`FeedParser` is more appropriate for when you're reading the message from
a stream which might block waiting for more input (e.g. reading an email message
from a socket). The :class:`FeedParser` can consume and parse the message
incrementally, and only returns the root object when you close the parser [#]_.
Note that the parser can be extended in limited ways, and of course you can
implement your own parser completely from scratch. There is no magical
connection between the :mod:`email` package's bundled parser and the
:class:`~email.message.Message` class, so your custom parser can create message
object trees any way it finds necessary.
FeedParser API
^^^^^^^^^^^^^^
.. versionadded:: 2.4
The :class:`FeedParser`, imported from the :mod:`email.feedparser` module,
provides an API that is conducive to incremental parsing of email messages, such
as would be necessary when reading the text of an email message from a source
that can block (e.g. a socket). The :class:`FeedParser` can of course be used
to parse an email message fully contained in a string or a file, but the classic
:class:`Parser` API may be more convenient for such use cases. The semantics
and results of the two parser APIs are identical.
The :class:`FeedParser`'s API is simple; you create an instance, feed it a bunch
of text until there's no more to feed it, then close the parser to retrieve the
root message object. The :class:`FeedParser` is extremely accurate when parsing
standards-compliant messages, and it does a very good job of parsing
non-compliant messages, providing information about how a message was deemed
broken. It will populate a message object's *defects* attribute with a list of
any problems it found in a message. See the :mod:`email.errors` module for the
list of defects that it can find.
Here is the API for the :class:`FeedParser`:
.. class:: FeedParser([_factory])
Create a :class:`FeedParser` instance. Optional *_factory* is a no-argument
callable that will be called whenever a new message object is needed. It
defaults to the :class:`email.message.Message` class.
.. method:: feed(data)
Feed the :class:`FeedParser` some more data. *data* should be a string
containing one or more lines. The lines can be partial and the
:class:`FeedParser` will stitch such partial lines together properly. The
lines in the string can have any of the common three line endings,
carriage return, newline, or carriage return and newline (they can even be
mixed).
.. method:: close()
Closing a :class:`FeedParser` completes the parsing of all previously fed
data, and returns the root message object. It is undefined what happens
if you feed more data to a closed :class:`FeedParser`.
Parser class API
^^^^^^^^^^^^^^^^
The :class:`Parser` class, imported from the :mod:`email.parser` module,
provides an API that can be used to parse a message when the complete contents
of the message are available in a string or file. The :mod:`email.parser`
module also provides a second class, called :class:`HeaderParser` which can be
used if you're only interested in the headers of the message.
:class:`HeaderParser` can be much faster in these situations, since it does not
attempt to parse the message body, instead setting the payload to the raw body
as a string. :class:`HeaderParser` has the same API as the :class:`Parser`
class.
.. class:: Parser([_class])
The constructor for the :class:`Parser` class takes an optional argument
*_class*. This must be a callable factory (such as a function or a class), and
it is used whenever a sub-message object needs to be created. It defaults to
:class:`~email.message.Message` (see :mod:`email.message`). The factory will
be called without arguments.
The optional *strict* flag is ignored.
.. deprecated:: 2.4
Because the :class:`Parser` class is a backward compatible API wrapper
around the new-in-Python 2.4 :class:`FeedParser`, *all* parsing is
effectively non-strict. You should simply stop passing a *strict* flag to
the :class:`Parser` constructor.
.. versionchanged:: 2.2.2
The *strict* flag was added.
.. versionchanged:: 2.4
The *strict* flag was deprecated.
The other public :class:`Parser` methods are:
.. method:: parse(fp[, headersonly])
Read all the data from the file-like object *fp*, parse the resulting
text, and return the root message object. *fp* must support both the
:meth:`~io.TextIOBase.readline` and the :meth:`~io.TextIOBase.read`
methods on file-like objects.
The text contained in *fp* must be formatted as a block of :rfc:`2822`
style headers and header continuation lines, optionally preceded by an
envelope header. The header block is terminated either by the end of the
data or by a blank line. Following the header block is the body of the
message (which may contain MIME-encoded subparts).
Optional *headersonly* is a flag specifying whether to stop parsing after
reading the headers or not. The default is ``False``, meaning it parses
the entire contents of the file.
.. versionchanged:: 2.2.2
The *headersonly* flag was added.
.. method:: parsestr(text[, headersonly])
Similar to the :meth:`parse` method, except it takes a string object
instead of a file-like object. Calling this method on a string is exactly
equivalent to wrapping *text* in a :class:`~StringIO.StringIO` instance first and
calling :meth:`parse`.
Optional *headersonly* is as with the :meth:`parse` method.
.. versionchanged:: 2.2.2
The *headersonly* flag was added.
Since creating a message object structure from a string or a file object is such
a common task, two functions are provided as a convenience. They are available
in the top-level :mod:`email` package namespace.
.. currentmodule:: email
.. function:: message_from_string(s[, _class[, strict]])
Return a message object structure from a string. This is exactly equivalent to
``Parser().parsestr(s)``. Optional *_class* and *strict* are interpreted as
with the :class:`~email.parser.Parser` class constructor.
.. versionchanged:: 2.2.2
The *strict* flag was added.
.. function:: message_from_file(fp[, _class[, strict]])
Return a message object structure tree from an open file object. This is
exactly equivalent to ``Parser().parse(fp)``. Optional *_class* and *strict*
are interpreted as with the :class:`~email.parser.Parser` class constructor.
.. versionchanged:: 2.2.2
The *strict* flag was added.
Here's an example of how you might use this at an interactive Python prompt::
>>> import email
>>> msg = email.message_from_string(myString)
Additional notes
^^^^^^^^^^^^^^^^
Here are some notes on the parsing semantics:
* Most non-\ :mimetype:`multipart` type messages are parsed as a single message
object with a string payload. These objects will return ``False`` for
:meth:`~email.message.Message.is_multipart`. Their
:meth:`~email.message.Message.get_payload` method will return a string object.
* All :mimetype:`multipart` type messages will be parsed as a container message
object with a list of sub-message objects for their payload. The outer
container message will return ``True`` for
:meth:`~email.message.Message.is_multipart` and their
:meth:`~email.message.Message.get_payload` method will return the list of
:class:`~email.message.Message` subparts.
* Most messages with a content type of :mimetype:`message/\*` (e.g.
:mimetype:`message/delivery-status` and :mimetype:`message/rfc822`) will also be
parsed as container object containing a list payload of length 1. Their
:meth:`~email.message.Message.is_multipart` method will return ``True``.
The single element in the list payload will be a sub-message object.
* Some non-standards compliant messages may not be internally consistent about
their :mimetype:`multipart`\ -edness. Such messages may have a
:mailheader:`Content-Type` header of type :mimetype:`multipart`, but their
:meth:`~email.message.Message.is_multipart` method may return ``False``.
If such messages were parsed with the :class:`~email.parser.FeedParser`,
they will have an instance of the
:class:`~email.errors.MultipartInvariantViolationDefect` class in their
*defects* attribute list. See :mod:`email.errors` for details.
.. rubric:: Footnotes
.. [#] As of email package version 3.0, introduced in Python 2.4, the classic
:class:`~email.parser.Parser` was re-implemented in terms of the
:class:`~email.parser.FeedParser`, so the semantics and results are
identical between the two parsers.
PK %�\�4���> �> # html/_sources/library/email.rst.txtnu �[��� :mod:`email` --- An email and MIME handling package
===================================================
.. module:: email
:synopsis: Package supporting the parsing, manipulating, and generating email messages,
including MIME documents.
.. moduleauthor:: Barry A. Warsaw <barry@python.org>
.. sectionauthor:: Barry A. Warsaw <barry@python.org>
.. Copyright (C) 2001-2007 Python Software Foundation
.. versionadded:: 2.2
The :mod:`email` package is a library for managing email messages, including
MIME and other :rfc:`2822`\ -based message documents. It subsumes most of the
functionality in several older standard modules such as :mod:`rfc822`,
:mod:`mimetools`, :mod:`multifile`, and other non-standard packages such as
:mod:`mimecntl`. It is specifically *not* designed to do any sending of email
messages to SMTP (:rfc:`2821`), NNTP, or other servers; those are functions of
modules such as :mod:`smtplib` and :mod:`nntplib`. The :mod:`email` package
attempts to be as RFC-compliant as possible, supporting in addition to
:rfc:`2822`, such MIME-related RFCs as :rfc:`2045`, :rfc:`2046`, :rfc:`2047`,
and :rfc:`2231`.
The primary distinguishing feature of the :mod:`email` package is that it splits
the parsing and generating of email messages from the internal *object model*
representation of email. Applications using the :mod:`email` package deal
primarily with objects; you can add sub-objects to messages, remove sub-objects
from messages, completely re-arrange the contents, etc. There is a separate
parser and a separate generator which handles the transformation from flat text
to the object model, and then back to flat text again. There are also handy
subclasses for some common MIME object types, and a few miscellaneous utilities
that help with such common tasks as extracting and parsing message field values,
creating RFC-compliant dates, etc.
The following sections describe the functionality of the :mod:`email` package.
The ordering follows a progression that should be common in applications: an
email message is read as flat text from a file or other source, the text is
parsed to produce the object structure of the email message, this structure is
manipulated, and finally, the object tree is rendered back into flat text.
It is perfectly feasible to create the object structure out of whole cloth ---
i.e. completely from scratch. From there, a similar progression can be taken as
above.
Also included are detailed specifications of all the classes and modules that
the :mod:`email` package provides, the exception classes you might encounter
while using the :mod:`email` package, some auxiliary utilities, and a few
examples. For users of the older :mod:`mimelib` package, or previous versions
of the :mod:`email` package, a section on differences and porting is provided.
Contents of the :mod:`email` package documentation:
.. toctree::
email.message.rst
email.parser.rst
email.generator.rst
email.mime.rst
email.header.rst
email.charset.rst
email.encoders.rst
email.errors.rst
email.utils.rst
email.iterators.rst
email-examples.rst
.. seealso::
Module :mod:`smtplib`
SMTP protocol client
Module :mod:`nntplib`
NNTP protocol client
.. _email-pkg-history:
Package History
---------------
This table describes the release history of the email package, corresponding to
the version of Python that the package was released with. For purposes of this
document, when you see a note about change or added versions, these refer to the
Python version the change was made in, *not* the email package version. This
table also describes the Python compatibility of each version of the package.
+---------------+------------------------------+-----------------------+
| email version | distributed with | compatible with |
+===============+==============================+=======================+
| :const:`1.x` | Python 2.2.0 to Python 2.2.1 | *no longer supported* |
+---------------+------------------------------+-----------------------+
| :const:`2.5` | Python 2.2.2+ and Python 2.3 | Python 2.1 to 2.5 |
+---------------+------------------------------+-----------------------+
| :const:`3.0` | Python 2.4 | Python 2.3 to 2.5 |
+---------------+------------------------------+-----------------------+
| :const:`4.0` | Python 2.5 | Python 2.3 to 2.5 |
+---------------+------------------------------+-----------------------+
Here are the major differences between :mod:`email` version 4 and version 3:
* All modules have been renamed according to :pep:`8` standards. For example,
the version 3 module :mod:`email.Message` was renamed to :mod:`email.message` in
version 4.
* A new subpackage :mod:`email.mime` was added and all the version 3
:mod:`email.MIME\*` modules were renamed and situated into the :mod:`email.mime`
subpackage. For example, the version 3 module :mod:`email.MIMEText` was renamed
to :mod:`email.mime.text`.
*Note that the version 3 names will continue to work until Python 2.6*.
* The :mod:`email.mime.application` module was added, which contains the
:class:`~email.mime.application.MIMEApplication` class.
* Methods that were deprecated in version 3 have been removed. These include
:meth:`Generator.__call__`, :meth:`Message.get_type`,
:meth:`Message.get_main_type`, :meth:`Message.get_subtype`.
* Fixes have been added for :rfc:`2231` support which can change some of the
return types for :func:`Message.get_param <email.message.Message.get_param>`
and friends. Under some
circumstances, values which used to return a 3-tuple now return simple strings
(specifically, if all extended parameter segments were unencoded, there is no
language and charset designation expected, so the return type is now a simple
string). Also, %-decoding used to be done for both encoded and unencoded
segments; this decoding is now done only for encoded segments.
Here are the major differences between :mod:`email` version 3 and version 2:
* The :class:`~email.parser.FeedParser` class was introduced, and the
:class:`~email.parser.Parser` class was implemented in terms of the
:class:`~email.parser.FeedParser`. All parsing therefore is
non-strict, and parsing will make a best effort never to raise an exception.
Problems found while parsing messages are stored in the message's *defect*
attribute.
* All aspects of the API which raised :exc:`DeprecationWarning`\ s in version 2
have been removed. These include the *_encoder* argument to the
:class:`~email.mime.text.MIMEText` constructor, the
:meth:`Message.add_payload` method, the :func:`Utils.dump_address_pair`
function, and the functions :func:`Utils.decode` and :func:`Utils.encode`.
* New :exc:`DeprecationWarning`\ s have been added to:
:meth:`Generator.__call__`, :meth:`Message.get_type`,
:meth:`Message.get_main_type`, :meth:`Message.get_subtype`, and the *strict*
argument to the :class:`~email.parser.Parser` class. These are expected to
be removed in future versions.
* Support for Pythons earlier than 2.3 has been removed.
Here are the differences between :mod:`email` version 2 and version 1:
* The :mod:`email.Header` and :mod:`email.Charset` modules have been added.
* The pickle format for :class:`~email.message.Message` instances has changed.
Since this was never (and still isn't) formally defined, this isn't
considered a backward incompatibility. However if your application pickles
and unpickles :class:`~email.message.Message` instances, be aware that in
:mod:`email` version 2, :class:`~email.message.Message` instances now have
private variables *_charset* and *_default_type*.
* Several methods in the :class:`~email.message.Message` class have been
deprecated, or their signatures changed. Also, many new methods have been
added. See the documentation for the :class:`~email.message.Message` class
for details. The changes should be completely backward compatible.
* The object structure has changed in the face of :mimetype:`message/rfc822`
content types. In :mod:`email` version 1, such a type would be represented
by a scalar payload, i.e. the container message's
:meth:`~email.message.Message.is_multipart` returned false,
:meth:`~email.message.Message.get_payload` was not a list object, but a
single :class:`~email.message.Message` instance.
This structure was inconsistent with the rest of the package, so the object
representation for :mimetype:`message/rfc822` content types was changed. In
:mod:`email` version 2, the container *does* return ``True`` from
:meth:`~email.message.Message.is_multipart`, and
:meth:`~email.message.Message.get_payload` returns a list containing a single
:class:`~email.message.Message` item.
Note that this is one place that backward compatibility could not be
completely maintained. However, if you're already testing the return type of
:meth:`~email.message.Message.get_payload`, you should be fine. You just need
to make sure your code doesn't do a :meth:`~email.message.Message.set_payload`
with a :class:`~email.message.Message` instance on a container with a content
type of :mimetype:`message/rfc822`.
* The :class:`~email.parser.Parser` constructor's *strict* argument was added,
and its :meth:`~email.parser.Parser.parse` and
:meth:`~email.parser.Parser.parsestr` methods grew a *headersonly* argument.
The *strict* flag was also added to functions :func:`email.message_from_file`
and :func:`email.message_from_string`.
* :meth:`Generator.__call__` is deprecated; use :meth:`Generator.flatten
<email.generator.Generator.flatten>` instead. The
:class:`~email.generator.Generator` class has also grown the
:meth:`~email.generator.Generator.clone` method.
* The :class:`~email.generator.DecodedGenerator` class in the
:mod:`email.generator` module was added.
* The intermediate base classes
:class:`~email.mime.nonmultipart.MIMENonMultipart` and
:class:`~email.mime.multipart.MIMEMultipart` have been added, and interposed
in the class hierarchy for most of the other MIME-related derived classes.
* The *_encoder* argument to the :class:`~email.mime.text.MIMEText` constructor
has been deprecated. Encoding now happens implicitly based on the
*_charset* argument.
* The following functions in the :mod:`email.Utils` module have been deprecated:
:func:`dump_address_pairs`, :func:`decode`, and :func:`encode`. The following
functions have been added to the module: :func:`make_msgid`,
:func:`decode_rfc2231`, :func:`encode_rfc2231`, and :func:`decode_params`.
* The non-public function :func:`email.Iterators._structure` was added.
Differences from :mod:`mimelib`
-------------------------------
The :mod:`email` package was originally prototyped as a separate library called
`mimelib <http://mimelib.sourceforge.net/>`_. Changes have been made so that method names
are more consistent, and some methods or modules have either been added or
removed. The semantics of some of the methods have also changed. For the most
part, any functionality available in :mod:`mimelib` is still available in the
:mod:`email` package, albeit often in a different way. Backward compatibility
between the :mod:`mimelib` package and the :mod:`email` package was not a
priority.
Here is a brief description of the differences between the :mod:`mimelib` and
the :mod:`email` packages, along with hints on how to port your applications.
Of course, the most visible difference between the two packages is that the
package name has been changed to :mod:`email`. In addition, the top-level
package has the following differences:
* :func:`messageFromString` has been renamed to :func:`message_from_string`.
* :func:`messageFromFile` has been renamed to :func:`message_from_file`.
The :class:`~email.message.Message` class has the following differences:
* The method :meth:`asString` was renamed to
:meth:`~email.message.Message.as_string`.
* The method :meth:`ismultipart` was renamed to
:meth:`~email.message.Message.is_multipart`.
* The :meth:`~email.message.Message.get_payload` method has grown a *decode*
optional argument.
* The method :meth:`getall` was renamed to
:meth:`~email.message.Message.get_all`.
* The method :meth:`addheader` was renamed to
:meth:`~email.message.Message.add_header`.
* The method :meth:`gettype` was renamed to :meth:`get_type`.
* The method :meth:`getmaintype` was renamed to :meth:`get_main_type`.
* The method :meth:`getsubtype` was renamed to :meth:`get_subtype`.
* The method :meth:`getparams` was renamed to
:meth:`~email.message.Message.get_params`. Also, whereas :meth:`getparams`
returned a list of strings, :meth:`~email.message.Message.get_params` returns
a list of 2-tuples, effectively the key/value pairs of the parameters, split
on the ``'='`` sign.
* The method :meth:`getparam` was renamed to
:meth:`~email.message.Message.get_param`.
* The method :meth:`getcharsets` was renamed to
:meth:`~email.message.Message.get_charsets`.
* The method :meth:`getfilename` was renamed to
:meth:`~email.message.Message.get_filename`.
* The method :meth:`getboundary` was renamed to
:meth:`~email.message.Message.get_boundary`.
* The method :meth:`setboundary` was renamed to
:meth:`~email.message.Message.set_boundary`.
* The method :meth:`getdecodedpayload` was removed. To get similar
functionality, pass the value 1 to the *decode* flag of the
:meth:`~email.message.Message.get_payload` method.
* The method :meth:`getpayloadastext` was removed. Similar functionality is
supported by the :class:`~email.generator.DecodedGenerator` class in the
:mod:`email.generator` module.
* The method :meth:`getbodyastext` was removed. You can get similar
functionality by creating an iterator with
:func:`~email.iterators.typed_subpart_iterator` in the :mod:`email.iterators`
module.
The :class:`~email.parser.Parser` class has no differences in its public
interface. It does have some additional smarts to recognize
:mimetype:`message/delivery-status` type messages, which it represents as a
:class:`~email.message.Message` instance containing separate
:class:`~email.message.Message` subparts for each header block in the delivery
status notification [#]_.
The :class:`~email.generator.Generator` class has no differences in its public
interface. There is a new class in the :mod:`email.generator` module though,
called :class:`~email.generator.DecodedGenerator` which provides most of the
functionality previously available in the :meth:`Message.getpayloadastext`
method.
The following modules and classes have been changed:
* The :class:`~email.mime.base.MIMEBase` class constructor arguments *_major*
and *_minor* have changed to *_maintype* and *_subtype* respectively.
* The ``Image`` class/module has been renamed to ``MIMEImage``. The *_minor*
argument has been renamed to *_subtype*.
* The ``Text`` class/module has been renamed to ``MIMEText``. The *_minor*
argument has been renamed to *_subtype*.
* The ``MessageRFC822`` class/module has been renamed to ``MIMEMessage``. Note
that an earlier version of :mod:`mimelib` called this class/module ``RFC822``,
but that clashed with the Python standard library module :mod:`rfc822` on some
case-insensitive file systems.
Also, the :class:`~email.mime.message.MIMEMessage` class now represents any
kind of MIME message
with main type :mimetype:`message`. It takes an optional argument *_subtype*
which is used to set the MIME subtype. *_subtype* defaults to
:mimetype:`rfc822`.
:mod:`mimelib` provided some utility functions in its :mod:`address` and
:mod:`date` modules. All of these functions have been moved to the
:mod:`email.utils` module.
The ``MsgReader`` class/module has been removed. Its functionality is most
closely supported in the :func:`~email.iterators.body_line_iterator` function
in the :mod:`email.iterators` module.
.. rubric:: Footnotes
.. [#] Delivery Status Notifications (DSN) are defined in :rfc:`1894`.
PK %�\�iL�K K ) html/_sources/library/email.utils.rst.txtnu �[��� :mod:`email.utils`: Miscellaneous utilities
-------------------------------------------
.. module:: email.utils
:synopsis: Miscellaneous email package utilities.
There are several useful utilities provided in the :mod:`email.utils` module:
.. function:: quote(str)
Return a new string with backslashes in *str* replaced by two backslashes, and
double quotes replaced by backslash-double quote.
.. function:: unquote(str)
Return a new string which is an *unquoted* version of *str*. If *str* ends and
begins with double quotes, they are stripped off. Likewise if *str* ends and
begins with angle brackets, they are stripped off.
.. function:: parseaddr(address)
Parse address -- which should be the value of some address-containing field such
as :mailheader:`To` or :mailheader:`Cc` -- into its constituent *realname* and
*email address* parts. Returns a tuple of that information, unless the parse
fails, in which case a 2-tuple of ``('', '')`` is returned.
.. function:: formataddr(pair)
The inverse of :meth:`parseaddr`, this takes a 2-tuple of the form ``(realname,
email_address)`` and returns the string value suitable for a :mailheader:`To` or
:mailheader:`Cc` header. If the first element of *pair* is false, then the
second element is returned unmodified.
.. function:: getaddresses(fieldvalues)
This method returns a list of 2-tuples of the form returned by ``parseaddr()``.
*fieldvalues* is a sequence of header field values as might be returned by
:meth:`Message.get_all <email.message.Message.get_all>`. Here's a simple
example that gets all the recipients of a message::
from email.utils import getaddresses
tos = msg.get_all('to', [])
ccs = msg.get_all('cc', [])
resent_tos = msg.get_all('resent-to', [])
resent_ccs = msg.get_all('resent-cc', [])
all_recipients = getaddresses(tos + ccs + resent_tos + resent_ccs)
.. function:: parsedate(date)
Attempts to parse a date according to the rules in :rfc:`2822`. however, some
mailers don't follow that format as specified, so :func:`parsedate` tries to
guess correctly in such cases. *date* is a string containing an :rfc:`2822`
date, such as ``"Mon, 20 Nov 1995 19:12:08 -0500"``. If it succeeds in parsing
the date, :func:`parsedate` returns a 9-tuple that can be passed directly to
:func:`time.mktime`; otherwise ``None`` will be returned. Note that indexes 6,
7, and 8 of the result tuple are not usable.
.. function:: parsedate_tz(date)
Performs the same function as :func:`parsedate`, but returns either ``None`` or
a 10-tuple; the first 9 elements make up a tuple that can be passed directly to
:func:`time.mktime`, and the tenth is the offset of the date's timezone from UTC
(which is the official term for Greenwich Mean Time) [#]_. If the input string
has no timezone, the last element of the tuple returned is ``None``. Note that
indexes 6, 7, and 8 of the result tuple are not usable.
.. function:: mktime_tz(tuple)
Turn a 10-tuple as returned by :func:`parsedate_tz` into a UTC
timestamp (seconds since the Epoch). If the timezone item in the
tuple is ``None``, assume local time.
.. function:: formatdate([timeval[, localtime][, usegmt]])
Returns a date string as per :rfc:`2822`, e.g.::
Fri, 09 Nov 2001 01:08:47 -0000
Optional *timeval* if given is a floating point time value as accepted by
:func:`time.gmtime` and :func:`time.localtime`, otherwise the current time is
used.
Optional *localtime* is a flag that when ``True``, interprets *timeval*, and
returns a date relative to the local timezone instead of UTC, properly taking
daylight savings time into account. The default is ``False`` meaning UTC is
used.
Optional *usegmt* is a flag that when ``True``, outputs a date string with the
timezone as an ascii string ``GMT``, rather than a numeric ``-0000``. This is
needed for some protocols (such as HTTP). This only applies when *localtime* is
``False``. The default is ``False``.
.. versionadded:: 2.4
.. function:: make_msgid([idstring])
Returns a string suitable for an :rfc:`2822`\ -compliant
:mailheader:`Message-ID` header. Optional *idstring* if given, is a string used
to strengthen the uniqueness of the message id.
.. function:: decode_rfc2231(s)
Decode the string *s* according to :rfc:`2231`.
.. function:: encode_rfc2231(s[, charset[, language]])
Encode the string *s* according to :rfc:`2231`. Optional *charset* and
*language*, if given is the character set name and language name to use. If
neither is given, *s* is returned as-is. If *charset* is given but *language*
is not, the string is encoded using the empty string for *language*.
.. function:: collapse_rfc2231_value(value[, errors[, fallback_charset]])
When a header parameter is encoded in :rfc:`2231` format,
:meth:`Message.get_param <email.message.Message.get_param>` may return a
3-tuple containing the character set,
language, and value. :func:`collapse_rfc2231_value` turns this into a unicode
string. Optional *errors* is passed to the *errors* argument of the built-in
:func:`unicode` function; it defaults to ``replace``. Optional
*fallback_charset* specifies the character set to use if the one in the
:rfc:`2231` header is not known by Python; it defaults to ``us-ascii``.
For convenience, if the *value* passed to :func:`collapse_rfc2231_value` is not
a tuple, it should be a string and it is returned unquoted.
.. function:: decode_params(params)
Decode parameters list according to :rfc:`2231`. *params* is a sequence of
2-tuples containing elements of the form ``(content-type, string-value)``.
.. versionchanged:: 2.4
The :func:`dump_address_pair` function has been removed; use :func:`formataddr`
instead.
.. versionchanged:: 2.4
The :func:`decode` function has been removed; use the
:meth:`Header.decode_header <email.header.Header.decode_header>` method
instead.
.. versionchanged:: 2.4
The :func:`encode` function has been removed; use the :meth:`Header.encode
<email.header.Header.encode>` method instead.
.. rubric:: Footnotes
.. [#] Note that the sign of the timezone offset is the opposite of the sign of the
``time.timezone`` variable for the same timezone; the latter variable follows
the POSIX standard while this module follows :rfc:`2822`.
PK %�\IjT� � ' html/_sources/library/ensurepip.rst.txtnu �[��� :mod:`ensurepip` --- Bootstrapping the ``pip`` installer
========================================================
.. module:: ensurepip
:synopsis: Bootstrapping the ``pip`` installer into an existing Python
installation or virtual environment.
.. versionadded:: 2.7.9
The :mod:`ensurepip` package provides support for bootstrapping the ``pip``
installer into an existing Python installation or virtual environment. This
bootstrapping approach reflects the fact that ``pip`` is an independent
project with its own release cycle, and the latest available stable version
is bundled with maintenance and feature releases of the CPython reference
interpreter.
In most cases, end users of Python shouldn't need to invoke this module
directly (as ``pip`` should be bootstrapped by default), but it may be
needed if installing ``pip`` was skipped when installing Python (or
when creating a virtual environment) or after explicitly uninstalling ``pip``.
.. note::
This module *does not* access the internet. All of the components
needed to bootstrap ``pip`` are included as internal parts of the
package.
.. seealso::
:ref:`installing-index`
The end user guide for installing Python packages
:pep:`453`: Explicit bootstrapping of pip in Python installations
The original rationale and specification for this module.
:pep:`477`: Backport ensurepip (PEP 453) to Python 2.7
The rationale and specification for backporting PEP 453 to Python 2.7.
Command line interface
----------------------
The command line interface is invoked using the interpreter's ``-m`` switch.
The simplest possible invocation is::
python -m ensurepip
This invocation will install ``pip`` if it is not already installed,
but otherwise does nothing. To ensure the installed version of ``pip``
is at least as recent as the one bundled with ``ensurepip``, pass the
``--upgrade`` option::
python -m ensurepip --upgrade
By default, ``pip`` is installed into the current virtual environment
(if one is active) or into the system site packages (if there is no
active virtual environment). The installation location can be controlled
through two additional command line options:
* ``--root <dir>``: Installs ``pip`` relative to the given root directory
rather than the root of the currently active virtual environment (if any)
or the default root for the current Python installation.
* ``--user``: Installs ``pip`` into the user site packages directory rather
than globally for the current Python installation (this option is not
permitted inside an active virtual environment).
By default, the scripts ``pip``, ``pipX``, and ``pipX.Y`` will be installed
(where X.Y stands for the version of Python used to invoke ``ensurepip``). The
scripts installed can be controlled through two additional command line
options:
* ``--altinstall``: if an alternate installation is requested, the ``pip`` and
``pipX`` script will *not* be installed.
* ``--no-default-pip``: if a non-default installation is request, the ``pip``
script will *not* be installed.
.. versionchanged:: 2.7.15
The exit status is non-zero if the command fails.
Module API
----------
:mod:`ensurepip` exposes two functions for programmatic use:
.. function:: version()
Returns a string specifying the bundled version of pip that will be
installed when bootstrapping an environment.
.. function:: bootstrap(root=None, upgrade=False, user=False, \
altinstall=False, default_pip=True, \
verbosity=0)
Bootstraps ``pip`` into the current or designated environment.
*root* specifies an alternative root directory to install relative to.
If *root* is ``None``, then installation uses the default install location
for the current environment.
*upgrade* indicates whether or not to upgrade an existing installation
of an earlier version of ``pip`` to the bundled version.
*user* indicates whether to use the user scheme rather than installing
globally.
By default, the scripts ``pip``, ``pipX``, and ``pipX.Y`` will be installed
(where X.Y stands for the current version of Python).
If *altinstall* is set, then ``pip`` and ``pipX`` will *not* be installed.
If *default_pip* is set to ``False``, then ``pip`` will *not* be installed.
Setting both *altinstall* and *default_pip* will trigger
:exc:`ValueError`.
*verbosity* controls the level of output to :data:`sys.stdout` from the
bootstrapping operation.
.. note::
The bootstrapping process has side effects on both ``sys.path`` and
``os.environ``. Invoking the command line interface in a subprocess
instead allows these side effects to be avoided.
.. note::
The bootstrapping process may install additional modules required by
``pip``, but other software should not assume those dependencies will
always be present by default (as the dependencies may be removed in a
future version of ``pip``).
PK %�\��Y4 4 # html/_sources/library/errno.rst.txtnu �[���
:mod:`errno` --- Standard errno system symbols
==============================================
.. module:: errno
:synopsis: Standard errno system symbols.
This module makes available standard ``errno`` system symbols. The value of each
symbol is the corresponding integer value. The names and descriptions are
borrowed from :file:`linux/include/errno.h`, which should be pretty
all-inclusive.
.. data:: errorcode
Dictionary providing a mapping from the errno value to the string name in the
underlying system. For instance, ``errno.errorcode[errno.EPERM]`` maps to
``'EPERM'``.
To translate a numeric error code to an error message, use :func:`os.strerror`.
Of the following list, symbols that are not used on the current platform are not
defined by the module. The specific list of defined symbols is available as
``errno.errorcode.keys()``. Symbols available can include:
.. data:: EPERM
Operation not permitted
.. data:: ENOENT
No such file or directory
.. data:: ESRCH
No such process
.. data:: EINTR
Interrupted system call
.. data:: EIO
I/O error
.. data:: ENXIO
No such device or address
.. data:: E2BIG
Arg list too long
.. data:: ENOEXEC
Exec format error
.. data:: EBADF
Bad file number
.. data:: ECHILD
No child processes
.. data:: EAGAIN
Try again
.. data:: ENOMEM
Out of memory
.. data:: EACCES
Permission denied
.. data:: EFAULT
Bad address
.. data:: ENOTBLK
Block device required
.. data:: EBUSY
Device or resource busy
.. data:: EEXIST
File exists
.. data:: EXDEV
Cross-device link
.. data:: ENODEV
No such device
.. data:: ENOTDIR
Not a directory
.. data:: EISDIR
Is a directory
.. data:: EINVAL
Invalid argument
.. data:: ENFILE
File table overflow
.. data:: EMFILE
Too many open files
.. data:: ENOTTY
Not a typewriter
.. data:: ETXTBSY
Text file busy
.. data:: EFBIG
File too large
.. data:: ENOSPC
No space left on device
.. data:: ESPIPE
Illegal seek
.. data:: EROFS
Read-only file system
.. data:: EMLINK
Too many links
.. data:: EPIPE
Broken pipe
.. data:: EDOM
Math argument out of domain of func
.. data:: ERANGE
Math result not representable
.. data:: EDEADLK
Resource deadlock would occur
.. data:: ENAMETOOLONG
File name too long
.. data:: ENOLCK
No record locks available
.. data:: ENOSYS
Function not implemented
.. data:: ENOTEMPTY
Directory not empty
.. data:: ELOOP
Too many symbolic links encountered
.. data:: EWOULDBLOCK
Operation would block
.. data:: ENOMSG
No message of desired type
.. data:: EIDRM
Identifier removed
.. data:: ECHRNG
Channel number out of range
.. data:: EL2NSYNC
Level 2 not synchronized
.. data:: EL3HLT
Level 3 halted
.. data:: EL3RST
Level 3 reset
.. data:: ELNRNG
Link number out of range
.. data:: EUNATCH
Protocol driver not attached
.. data:: ENOCSI
No CSI structure available
.. data:: EL2HLT
Level 2 halted
.. data:: EBADE
Invalid exchange
.. data:: EBADR
Invalid request descriptor
.. data:: EXFULL
Exchange full
.. data:: ENOANO
No anode
.. data:: EBADRQC
Invalid request code
.. data:: EBADSLT
Invalid slot
.. data:: EDEADLOCK
File locking deadlock error
.. data:: EBFONT
Bad font file format
.. data:: ENOSTR
Device not a stream
.. data:: ENODATA
No data available
.. data:: ETIME
Timer expired
.. data:: ENOSR
Out of streams resources
.. data:: ENONET
Machine is not on the network
.. data:: ENOPKG
Package not installed
.. data:: EREMOTE
Object is remote
.. data:: ENOLINK
Link has been severed
.. data:: EADV
Advertise error
.. data:: ESRMNT
Srmount error
.. data:: ECOMM
Communication error on send
.. data:: EPROTO
Protocol error
.. data:: EMULTIHOP
Multihop attempted
.. data:: EDOTDOT
RFS specific error
.. data:: EBADMSG
Not a data message
.. data:: EOVERFLOW
Value too large for defined data type
.. data:: ENOTUNIQ
Name not unique on network
.. data:: EBADFD
File descriptor in bad state
.. data:: EREMCHG
Remote address changed
.. data:: ELIBACC
Can not access a needed shared library
.. data:: ELIBBAD
Accessing a corrupted shared library
.. data:: ELIBSCN
.lib section in a.out corrupted
.. data:: ELIBMAX
Attempting to link in too many shared libraries
.. data:: ELIBEXEC
Cannot exec a shared library directly
.. data:: EILSEQ
Illegal byte sequence
.. data:: ERESTART
Interrupted system call should be restarted
.. data:: ESTRPIPE
Streams pipe error
.. data:: EUSERS
Too many users
.. data:: ENOTSOCK
Socket operation on non-socket
.. data:: EDESTADDRREQ
Destination address required
.. data:: EMSGSIZE
Message too long
.. data:: EPROTOTYPE
Protocol wrong type for socket
.. data:: ENOPROTOOPT
Protocol not available
.. data:: EPROTONOSUPPORT
Protocol not supported
.. data:: ESOCKTNOSUPPORT
Socket type not supported
.. data:: EOPNOTSUPP
Operation not supported on transport endpoint
.. data:: EPFNOSUPPORT
Protocol family not supported
.. data:: EAFNOSUPPORT
Address family not supported by protocol
.. data:: EADDRINUSE
Address already in use
.. data:: EADDRNOTAVAIL
Cannot assign requested address
.. data:: ENETDOWN
Network is down
.. data:: ENETUNREACH
Network is unreachable
.. data:: ENETRESET
Network dropped connection because of reset
.. data:: ECONNABORTED
Software caused connection abort
.. data:: ECONNRESET
Connection reset by peer
.. data:: ENOBUFS
No buffer space available
.. data:: EISCONN
Transport endpoint is already connected
.. data:: ENOTCONN
Transport endpoint is not connected
.. data:: ESHUTDOWN
Cannot send after transport endpoint shutdown
.. data:: ETOOMANYREFS
Too many references: cannot splice
.. data:: ETIMEDOUT
Connection timed out
.. data:: ECONNREFUSED
Connection refused
.. data:: EHOSTDOWN
Host is down
.. data:: EHOSTUNREACH
No route to host
.. data:: EALREADY
Operation already in progress
.. data:: EINPROGRESS
Operation now in progress
.. data:: ESTALE
Stale NFS file handle
.. data:: EUCLEAN
Structure needs cleaning
.. data:: ENOTNAM
Not a XENIX named type file
.. data:: ENAVAIL
No XENIX semaphores available
.. data:: EISNAM
Is a named type file
.. data:: EREMOTEIO
Remote I/O error
.. data:: EDQUOT
Quota exceeded
PK %�\9!s�G �G ( html/_sources/library/exceptions.rst.txtnu �[��� .. _bltin-exceptions:
Built-in Exceptions
===================
.. module:: exceptions
:synopsis: Standard exception classes.
Exceptions should be class objects. The exceptions are defined in the module
:mod:`exceptions`. This module never needs to be imported explicitly: the
exceptions are provided in the built-in namespace as well as the
:mod:`exceptions` module.
.. index::
statement: try
statement: except
For class exceptions, in a :keyword:`try` statement with an :keyword:`except`
clause that mentions a particular class, that clause also handles any exception
classes derived from that class (but not exception classes from which *it* is
derived). Two exception classes that are not related via subclassing are never
equivalent, even if they have the same name.
.. index:: statement: raise
The built-in exceptions listed below can be generated by the interpreter or
built-in functions. Except where mentioned, they have an "associated value"
indicating the detailed cause of the error. This may be a string or a tuple
containing several items of information (e.g., an error code and a string
explaining the code). The associated value is the second argument to the
:keyword:`raise` statement. If the exception class is derived from the standard
root class :exc:`BaseException`, the associated value is present as the
exception instance's :attr:`args` attribute.
User code can raise built-in exceptions. This can be used to test an exception
handler or to report an error condition "just like" the situation in which the
interpreter raises the same exception; but beware that there is nothing to
prevent user code from raising an inappropriate error.
The built-in exception classes can be subclassed to define new exceptions;
programmers are encouraged to derive new exceptions from the :exc:`Exception`
class or one of its subclasses, and not from :exc:`BaseException`. More
information on defining exceptions is available in the Python Tutorial under
:ref:`tut-userexceptions`.
The following exceptions are only used as base classes for other exceptions.
.. exception:: BaseException
The base class for all built-in exceptions. It is not meant to be directly
inherited by user-defined classes (for that, use :exc:`Exception`). If
:func:`str` or :func:`unicode` is called on an instance of this class, the
representation of the argument(s) to the instance are returned, or the empty
string when there were no arguments.
.. versionadded:: 2.5
.. attribute:: args
The tuple of arguments given to the exception constructor. Some built-in
exceptions (like :exc:`IOError`) expect a certain number of arguments and
assign a special meaning to the elements of this tuple, while others are
usually called only with a single string giving an error message.
.. exception:: Exception
All built-in, non-system-exiting exceptions are derived from this class. All
user-defined exceptions should also be derived from this class.
.. versionchanged:: 2.5
Changed to inherit from :exc:`BaseException`.
.. exception:: StandardError
The base class for all built-in exceptions except :exc:`StopIteration`,
:exc:`GeneratorExit`, :exc:`KeyboardInterrupt` and :exc:`SystemExit`.
:exc:`StandardError` itself is derived from :exc:`Exception`.
.. exception:: ArithmeticError
The base class for those built-in exceptions that are raised for various
arithmetic errors: :exc:`OverflowError`, :exc:`ZeroDivisionError`,
:exc:`FloatingPointError`.
.. exception:: BufferError
Raised when a :ref:`buffer <bufferobjects>` related operation cannot be
performed.
.. exception:: LookupError
The base class for the exceptions that are raised when a key or index used on
a mapping or sequence is invalid: :exc:`IndexError`, :exc:`KeyError`. This
can be raised directly by :func:`codecs.lookup`.
.. exception:: EnvironmentError
The base class for exceptions that can occur outside the Python system:
:exc:`IOError`, :exc:`OSError`. When exceptions of this type are created with a
2-tuple, the first item is available on the instance's :attr:`errno` attribute
(it is assumed to be an error number), and the second item is available on the
:attr:`strerror` attribute (it is usually the associated error message). The
tuple itself is also available on the :attr:`args` attribute.
.. versionadded:: 1.5.2
When an :exc:`EnvironmentError` exception is instantiated with a 3-tuple, the
first two items are available as above, while the third item is available on the
:attr:`filename` attribute. However, for backwards compatibility, the
:attr:`args` attribute contains only a 2-tuple of the first two constructor
arguments.
The :attr:`filename` attribute is ``None`` when this exception is created with
other than 3 arguments. The :attr:`errno` and :attr:`strerror` attributes are
also ``None`` when the instance was created with other than 2 or 3 arguments.
In this last case, :attr:`args` contains the verbatim constructor arguments as a
tuple.
The following exceptions are the exceptions that are actually raised.
.. exception:: AssertionError
.. index:: statement: assert
Raised when an :keyword:`assert` statement fails.
.. exception:: AttributeError
Raised when an attribute reference (see :ref:`attribute-references`) or
assignment fails. (When an object does not support attribute references or
attribute assignments at all, :exc:`TypeError` is raised.)
.. exception:: EOFError
Raised when one of the built-in functions (:func:`input` or :func:`raw_input`)
hits an end-of-file condition (EOF) without reading any data. (N.B.: the
:meth:`file.read` and :meth:`file.readline` methods return an empty string
when they hit EOF.)
.. exception:: FloatingPointError
Raised when a floating point operation fails. This exception is always defined,
but can only be raised when Python is configured with the
``--with-fpectl`` option, or the :const:`WANT_SIGFPE_HANDLER` symbol is
defined in the :file:`pyconfig.h` file.
.. exception:: GeneratorExit
Raised when a :term:`generator`\'s :meth:`close` method is called. It
directly inherits from :exc:`BaseException` instead of :exc:`StandardError`
since it is technically not an error.
.. versionadded:: 2.5
.. versionchanged:: 2.6
Changed to inherit from :exc:`BaseException`.
.. exception:: IOError
Raised when an I/O operation (such as a :keyword:`print` statement, the built-in
:func:`open` function or a method of a file object) fails for an I/O-related
reason, e.g., "file not found" or "disk full".
This class is derived from :exc:`EnvironmentError`. See the discussion above
for more information on exception instance attributes.
.. versionchanged:: 2.6
Changed :exc:`socket.error` to use this as a base class.
.. exception:: ImportError
Raised when an :keyword:`import` statement fails to find the module definition
or when a ``from ... import`` fails to find a name that is to be imported.
.. exception:: IndexError
Raised when a sequence subscript is out of range. (Slice indices are silently
truncated to fall in the allowed range; if an index is not a plain integer,
:exc:`TypeError` is raised.)
.. XXX xref to sequences
.. exception:: KeyError
Raised when a mapping (dictionary) key is not found in the set of existing keys.
.. XXX xref to mapping objects?
.. exception:: KeyboardInterrupt
Raised when the user hits the interrupt key (normally :kbd:`Control-C` or
:kbd:`Delete`). During execution, a check for interrupts is made regularly.
Interrupts typed when a built-in function :func:`input` or :func:`raw_input` is
waiting for input also raise this exception. The exception inherits from
:exc:`BaseException` so as to not be accidentally caught by code that catches
:exc:`Exception` and thus prevent the interpreter from exiting.
.. versionchanged:: 2.5
Changed to inherit from :exc:`BaseException`.
.. exception:: MemoryError
Raised when an operation runs out of memory but the situation may still be
rescued (by deleting some objects). The associated value is a string indicating
what kind of (internal) operation ran out of memory. Note that because of the
underlying memory management architecture (C's :c:func:`malloc` function), the
interpreter may not always be able to completely recover from this situation; it
nevertheless raises an exception so that a stack traceback can be printed, in
case a run-away program was the cause.
.. exception:: NameError
Raised when a local or global name is not found. This applies only to
unqualified names. The associated value is an error message that includes the
name that could not be found.
.. exception:: NotImplementedError
This exception is derived from :exc:`RuntimeError`. In user defined base
classes, abstract methods should raise this exception when they require derived
classes to override the method.
.. versionadded:: 1.5.2
.. exception:: OSError
.. index:: module: errno
This exception is derived from :exc:`EnvironmentError`. It is raised when a
function returns a system-related error (not for illegal argument types or
other incidental errors). The :attr:`errno` attribute is a numeric error
code from :c:data:`errno`, and the :attr:`strerror` attribute is the
corresponding string, as would be printed by the C function :c:func:`perror`.
See the module :mod:`errno`, which contains names for the error codes defined
by the underlying operating system.
For exceptions that involve a file system path (such as :func:`chdir` or
:func:`unlink`), the exception instance will contain a third attribute,
:attr:`filename`, which is the file name passed to the function.
.. versionadded:: 1.5.2
.. exception:: OverflowError
Raised when the result of an arithmetic operation is too large to be
represented. This cannot occur for long integers (which would rather raise
:exc:`MemoryError` than give up) and for most operations with plain integers,
which return a long integer instead. Because of the lack of standardization
of floating point exception handling in C, most floating point operations
also aren't checked.
.. exception:: ReferenceError
This exception is raised when a weak reference proxy, created by the
:func:`weakref.proxy` function, is used to access an attribute of the referent
after it has been garbage collected. For more information on weak references,
see the :mod:`weakref` module.
.. versionadded:: 2.2
Previously known as the :exc:`weakref.ReferenceError` exception.
.. exception:: RuntimeError
Raised when an error is detected that doesn't fall in any of the other
categories. The associated value is a string indicating what precisely went
wrong.
.. exception:: StopIteration
Raised by an :term:`iterator`\'s :meth:`~iterator.next` method to signal that
there are no further values. This is derived from :exc:`Exception` rather
than :exc:`StandardError`, since this is not considered an error in its
normal application.
.. versionadded:: 2.2
.. exception:: SyntaxError
Raised when the parser encounters a syntax error. This may occur in an
:keyword:`import` statement, in an :keyword:`exec` statement, in a call to the
built-in function :func:`eval` or :func:`input`, or when reading the initial
script or standard input (also interactively).
Instances of this class have attributes :attr:`filename`, :attr:`lineno`,
:attr:`offset` and :attr:`text` for easier access to the details. :func:`str`
of the exception instance returns only the message.
.. exception:: IndentationError
Base class for syntax errors related to incorrect indentation. This is a
subclass of :exc:`SyntaxError`.
.. exception:: TabError
Raised when indentation contains an inconsistent use of tabs and spaces.
This is a subclass of :exc:`IndentationError`.
.. exception:: SystemError
Raised when the interpreter finds an internal error, but the situation does not
look so serious to cause it to abandon all hope. The associated value is a
string indicating what went wrong (in low-level terms).
You should report this to the author or maintainer of your Python interpreter.
Be sure to report the version of the Python interpreter (``sys.version``; it is
also printed at the start of an interactive Python session), the exact error
message (the exception's associated value) and if possible the source of the
program that triggered the error.
.. exception:: SystemExit
This exception is raised by the :func:`sys.exit` function. When it is not
handled, the Python interpreter exits; no stack traceback is printed. If the
associated value is a plain integer, it specifies the system exit status (passed
to C's :c:func:`exit` function); if it is ``None``, the exit status is zero; if
it has another type (such as a string), the object's value is printed and the
exit status is one.
Instances have an attribute :attr:`!code` which is set to the proposed exit
status or error message (defaulting to ``None``). Also, this exception derives
directly from :exc:`BaseException` and not :exc:`StandardError`, since it is not
technically an error.
A call to :func:`sys.exit` is translated into an exception so that clean-up
handlers (:keyword:`finally` clauses of :keyword:`try` statements) can be
executed, and so that a debugger can execute a script without running the risk
of losing control. The :func:`os._exit` function can be used if it is
absolutely positively necessary to exit immediately (for example, in the child
process after a call to :func:`os.fork`).
The exception inherits from :exc:`BaseException` instead of :exc:`StandardError`
or :exc:`Exception` so that it is not accidentally caught by code that catches
:exc:`Exception`. This allows the exception to properly propagate up and cause
the interpreter to exit.
.. versionchanged:: 2.5
Changed to inherit from :exc:`BaseException`.
.. exception:: TypeError
Raised when an operation or function is applied to an object of inappropriate
type. The associated value is a string giving details about the type mismatch.
.. exception:: UnboundLocalError
Raised when a reference is made to a local variable in a function or method, but
no value has been bound to that variable. This is a subclass of
:exc:`NameError`.
.. versionadded:: 2.0
.. exception:: UnicodeError
Raised when a Unicode-related encoding or decoding error occurs. It is a
subclass of :exc:`ValueError`.
:exc:`UnicodeError` has attributes that describe the encoding or decoding
error. For example, ``err.object[err.start:err.end]`` gives the particular
invalid input that the codec failed on.
.. attribute:: encoding
The name of the encoding that raised the error.
.. attribute:: reason
A string describing the specific codec error.
.. attribute:: object
The object the codec was attempting to encode or decode.
.. attribute:: start
The first index of invalid data in :attr:`object`.
.. attribute:: end
The index after the last invalid data in :attr:`object`.
.. versionadded:: 2.0
.. exception:: UnicodeEncodeError
Raised when a Unicode-related error occurs during encoding. It is a subclass of
:exc:`UnicodeError`.
.. versionadded:: 2.3
.. exception:: UnicodeDecodeError
Raised when a Unicode-related error occurs during decoding. It is a subclass of
:exc:`UnicodeError`.
.. versionadded:: 2.3
.. exception:: UnicodeTranslateError
Raised when a Unicode-related error occurs during translating. It is a subclass
of :exc:`UnicodeError`.
.. versionadded:: 2.3
.. exception:: ValueError
Raised when an operation or function receives an argument that has the
right type but an inappropriate value, and the situation is not described by a
more precise exception such as :exc:`IndexError`.
.. exception:: VMSError
Only available on VMS. Raised when a VMS-specific error occurs.
.. exception:: WindowsError
Raised when a Windows-specific error occurs or when the error number does not
correspond to an :c:data:`errno` value. The :attr:`winerror` and
:attr:`strerror` values are created from the return values of the
:c:func:`GetLastError` and :c:func:`FormatMessage` functions from the Windows
Platform API. The :attr:`errno` value maps the :attr:`winerror` value to
corresponding ``errno.h`` values. This is a subclass of :exc:`OSError`.
.. versionadded:: 2.0
.. versionchanged:: 2.5
Previous versions put the :c:func:`GetLastError` codes into :attr:`errno`.
.. exception:: ZeroDivisionError
Raised when the second argument of a division or modulo operation is zero. The
associated value is a string indicating the type of the operands and the
operation.
The following exceptions are used as warning categories; see the :mod:`warnings`
module for more information.
.. exception:: Warning
Base class for warning categories.
.. exception:: UserWarning
Base class for warnings generated by user code.
.. exception:: DeprecationWarning
Base class for warnings about deprecated features.
.. exception:: PendingDeprecationWarning
Base class for warnings about features which will be deprecated in the future.
.. exception:: SyntaxWarning
Base class for warnings about dubious syntax.
.. exception:: RuntimeWarning
Base class for warnings about dubious runtime behavior.
.. exception:: FutureWarning
Base class for warnings about constructs that will change semantically in the
future.
.. exception:: ImportWarning
Base class for warnings about probable mistakes in module imports.
.. versionadded:: 2.5
.. exception:: UnicodeWarning
Base class for warnings related to Unicode.
.. versionadded:: 2.5
Exception hierarchy
-------------------
The class hierarchy for built-in exceptions is:
.. literalinclude:: ../../Lib/test/exception_hierarchy.txt
PK %�\iwlX� � # html/_sources/library/fcntl.rst.txtnu �[��� :mod:`fcntl` --- The ``fcntl`` and ``ioctl`` system calls
=========================================================
.. module:: fcntl
:platform: Unix
:synopsis: The fcntl() and ioctl() system calls.
.. sectionauthor:: Jaap Vermeulen
.. index::
pair: UNIX; file control
pair: UNIX; I/O control
This module performs file control and I/O control on file descriptors. It is an
interface to the :c:func:`fcntl` and :c:func:`ioctl` Unix routines. For a
complete description of these calls, see :manpage:`fcntl(2)` and
:manpage:`ioctl(2)` Unix manual pages.
All functions in this module take a file descriptor *fd* as their first
argument. This can be an integer file descriptor, such as returned by
``sys.stdin.fileno()``, or a file object, such as ``sys.stdin`` itself, which
provides a :meth:`~io.IOBase.fileno` which returns a genuine file descriptor.
The module defines the following functions:
.. function:: fcntl(fd, op[, arg])
Perform the operation *op* on file descriptor *fd* (file objects providing
a :meth:`~io.IOBase.fileno` method are accepted as well). The values used
for for *op* are operating system dependent, and are available as constants
in the :mod:`fcntl` module, using the same names as used in the relevant C
header files. The argument *arg* is optional, and defaults to the integer
value ``0``. When present, it can either be an integer value, or a string.
With the argument missing or an integer value, the return value of this function
is the integer return value of the C :c:func:`fcntl` call. When the argument is
a string it represents a binary structure, e.g. created by :func:`struct.pack`.
The binary data is copied to a buffer whose address is passed to the C
:c:func:`fcntl` call. The return value after a successful call is the contents
of the buffer, converted to a string object. The length of the returned string
will be the same as the length of the *arg* argument. This is limited to 1024
bytes. If the information returned in the buffer by the operating system is
larger than 1024 bytes, this is most likely to result in a segmentation
violation or a more subtle data corruption.
If the :c:func:`fcntl` fails, an :exc:`IOError` is raised.
.. function:: ioctl(fd, op[, arg[, mutate_flag]])
This function is identical to the :func:`~fcntl.fcntl` function, except that the
operations are typically defined in the library module :mod:`termios` and the
argument handling is even more complicated.
The op parameter is limited to values that can fit in 32-bits.
Additional constants of interest for use as the *op* argument can be
found in the :mod:`termios` module, under the same names as used in
the relevant C header files.
The parameter *arg* can be one of an integer, absent (treated identically to the
integer ``0``), an object supporting the read-only buffer interface (most likely
a plain Python string) or an object supporting the read-write buffer interface.
In all but the last case, behaviour is as for the :func:`~fcntl.fcntl`
function.
If a mutable buffer is passed, then the behaviour is determined by the value of
the *mutate_flag* parameter.
If it is false, the buffer's mutability is ignored and behaviour is as for a
read-only buffer, except that the 1024 byte limit mentioned above is avoided --
so long as the buffer you pass is as least as long as what the operating system
wants to put there, things should work.
If *mutate_flag* is true, then the buffer is (in effect) passed to the
underlying :func:`ioctl` system call, the latter's return code is passed back to
the calling Python, and the buffer's new contents reflect the action of the
:func:`ioctl`. This is a slight simplification, because if the supplied buffer
is less than 1024 bytes long it is first copied into a static buffer 1024 bytes
long which is then passed to :func:`ioctl` and copied back into the supplied
buffer.
If *mutate_flag* is not supplied, then from Python 2.5 it defaults to true,
which is a change from versions 2.3 and 2.4. Supply the argument explicitly if
version portability is a priority.
If the :c:func:`ioctl` fails, an :exc:`IOError` exception is raised.
An example::
>>> import array, fcntl, struct, termios, os
>>> os.getpgrp()
13341
>>> struct.unpack('h', fcntl.ioctl(0, termios.TIOCGPGRP, " "))[0]
13341
>>> buf = array.array('h', [0])
>>> fcntl.ioctl(0, termios.TIOCGPGRP, buf, 1)
0
>>> buf
array('h', [13341])
.. function:: flock(fd, op)
Perform the lock operation *op* on file descriptor *fd* (file objects providing
a :meth:`~io.IOBase.fileno` method are accepted as well). See the Unix manual
:manpage:`flock(2)` for details. (On some systems, this function is emulated
using :c:func:`fcntl`.)
If the :c:func:`flock` fails, an :exc:`IOError` exception is raised.
.. function:: lockf(fd, operation, [length, [start, [whence]]])
This is essentially a wrapper around the :func:`~fcntl.fcntl` locking calls.
*fd* is the file descriptor of the file to lock or unlock, and *operation*
is one of the following values:
* :const:`LOCK_UN` -- unlock
* :const:`LOCK_SH` -- acquire a shared lock
* :const:`LOCK_EX` -- acquire an exclusive lock
When *operation* is :const:`LOCK_SH` or :const:`LOCK_EX`, it can also be
bitwise ORed with :const:`LOCK_NB` to avoid blocking on lock acquisition.
If :const:`LOCK_NB` is used and the lock cannot be acquired, an
:exc:`IOError` will be raised and the exception will have an *errno*
attribute set to :const:`EACCES` or :const:`EAGAIN` (depending on the
operating system; for portability, check for both values). On at least some
systems, :const:`LOCK_EX` can only be used if the file descriptor refers to a
file opened for writing.
*length* is the number of bytes to lock, *start* is the byte offset at
which the lock starts, relative to *whence*, and *whence* is as with
:func:`io.IOBase.seek`, specifically:
* :const:`0` -- relative to the start of the file (:data:`os.SEEK_SET`)
* :const:`1` -- relative to the current buffer position (:data:`os.SEEK_CUR`)
* :const:`2` -- relative to the end of the file (:data:`os.SEEK_END`)
The default for *start* is 0, which means to start at the beginning of the file.
The default for *length* is 0 which means to lock to the end of the file. The
default for *whence* is also 0.
Examples (all on a SVR4 compliant system)::
import struct, fcntl, os
f = open(...)
rv = fcntl.fcntl(f, fcntl.F_SETFL, os.O_NDELAY)
lockdata = struct.pack('hhllhh', fcntl.F_WRLCK, 0, 0, 0, 0, 0)
rv = fcntl.fcntl(f, fcntl.F_SETLKW, lockdata)
Note that in the first example the return value variable *rv* will hold an
integer value; in the second example it will hold a string value. The structure
lay-out for the *lockdata* variable is system dependent --- therefore using the
:func:`flock` call may be better.
.. seealso::
Module :mod:`os`
If the locking flags :data:`~os.O_SHLOCK` and :data:`~os.O_EXLOCK` are
present in the :mod:`os` module (on BSD only), the :func:`os.open`
function provides an alternative to the :func:`lockf` and :func:`flock`
functions.
PK %�\�^c� � % html/_sources/library/filecmp.rst.txtnu �[��� :mod:`filecmp` --- File and Directory Comparisons
=================================================
.. module:: filecmp
:synopsis: Compare files efficiently.
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
**Source code:** :source:`Lib/filecmp.py`
--------------
The :mod:`filecmp` module defines functions to compare files and directories,
with various optional time/correctness trade-offs. For comparing files,
see also the :mod:`difflib` module.
The :mod:`filecmp` module defines the following functions:
.. function:: cmp(f1, f2[, shallow])
Compare the files named *f1* and *f2*, returning ``True`` if they seem equal,
``False`` otherwise.
Unless *shallow* is given and is false, files with identical :func:`os.stat`
signatures are taken to be equal.
Files that were compared using this function will not be compared again unless
their :func:`os.stat` signature changes.
Note that no external programs are called from this function, giving it
portability and efficiency.
.. function:: cmpfiles(dir1, dir2, common[, shallow])
Compare the files in the two directories *dir1* and *dir2* whose names are
given by *common*.
Returns three lists of file names: *match*, *mismatch*,
*errors*. *match* contains the list of files that match, *mismatch* contains
the names of those that don't, and *errors* lists the names of files which
could not be compared. Files are listed in *errors* if they don't exist in
one of the directories, the user lacks permission to read them or if the
comparison could not be done for some other reason.
The *shallow* parameter has the same meaning and default value as for
:func:`filecmp.cmp`.
For example, ``cmpfiles('a', 'b', ['c', 'd/e'])`` will compare ``a/c`` with
``b/c`` and ``a/d/e`` with ``b/d/e``. ``'c'`` and ``'d/e'`` will each be in
one of the three returned lists.
Example::
>>> import filecmp
>>> filecmp.cmp('undoc.rst', 'undoc.rst') # doctest: +SKIP
True
>>> filecmp.cmp('undoc.rst', 'index.rst') # doctest: +SKIP
False
.. _dircmp-objects:
The :class:`dircmp` class
-------------------------
:class:`dircmp` instances are built using this constructor:
.. class:: dircmp(a, b[, ignore[, hide]])
Construct a new directory comparison object, to compare the directories *a* and
*b*. *ignore* is a list of names to ignore, and defaults to ``['RCS', 'CVS',
'tags']``. *hide* is a list of names to hide, and defaults to ``[os.curdir,
os.pardir]``.
The :class:`dircmp` class compares files by doing *shallow* comparisons
as described for :func:`filecmp.cmp`.
The :class:`dircmp` class provides the following methods:
.. method:: report()
Print (to ``sys.stdout``) a comparison between *a* and *b*.
.. method:: report_partial_closure()
Print a comparison between *a* and *b* and common immediate
subdirectories.
.. method:: report_full_closure()
Print a comparison between *a* and *b* and common subdirectories
(recursively).
The :class:`dircmp` class offers a number of interesting attributes that may be
used to get various bits of information about the directory trees being
compared.
Note that via :meth:`__getattr__` hooks, all attributes are computed lazily,
so there is no speed penalty if only those attributes which are lightweight
to compute are used.
.. attribute:: left
The directory *a*.
.. attribute:: right
The directory *b*.
.. attribute:: left_list
Files and subdirectories in *a*, filtered by *hide* and *ignore*.
.. attribute:: right_list
Files and subdirectories in *b*, filtered by *hide* and *ignore*.
.. attribute:: common
Files and subdirectories in both *a* and *b*.
.. attribute:: left_only
Files and subdirectories only in *a*.
.. attribute:: right_only
Files and subdirectories only in *b*.
.. attribute:: common_dirs
Subdirectories in both *a* and *b*.
.. attribute:: common_files
Files in both *a* and *b*
.. attribute:: common_funny
Names in both *a* and *b*, such that the type differs between the
directories, or names for which :func:`os.stat` reports an error.
.. attribute:: same_files
Files which are identical in both *a* and *b*, using the class's
file comparison operator.
.. attribute:: diff_files
Files which are in both *a* and *b*, whose contents differ according
to the class's file comparison operator.
.. attribute:: funny_files
Files which are in both *a* and *b*, but could not be compared.
.. attribute:: subdirs
A dictionary mapping names in :attr:`common_dirs` to :class:`dircmp` objects.
Here is a simplified example of using the ``subdirs`` attribute to search
recursively through two directories to show common different files::
>>> from filecmp import dircmp
>>> def print_diff_files(dcmp):
... for name in dcmp.diff_files:
... print "diff_file %s found in %s and %s" % (name, dcmp.left,
... dcmp.right)
... for sub_dcmp in dcmp.subdirs.values():
... print_diff_files(sub_dcmp)
...
>>> dcmp = dircmp('dir1', 'dir2') # doctest: +SKIP
>>> print_diff_files(dcmp) # doctest: +SKIP
PK %�\���#. . ) html/_sources/library/fileformats.rst.txtnu �[���
.. _fileformats:
************
File Formats
************
The modules described in this chapter parse various miscellaneous file formats
that aren't markup languages or are related to e-mail.
.. toctree::
csv.rst
configparser.rst
robotparser.rst
netrc.rst
xdrlib.rst
plistlib.rst
PK %�\2��%� � ' html/_sources/library/fileinput.rst.txtnu �[��� :mod:`fileinput` --- Iterate over lines from multiple input streams
===================================================================
.. module:: fileinput
:synopsis: Loop over standard input or a list of files.
.. moduleauthor:: Guido van Rossum <guido@python.org>
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
**Source code:** :source:`Lib/fileinput.py`
--------------
This module implements a helper class and functions to quickly write a
loop over standard input or a list of files. If you just want to read or
write one file see :func:`open`.
The typical use is::
import fileinput
for line in fileinput.input():
process(line)
This iterates over the lines of all files listed in ``sys.argv[1:]``, defaulting
to ``sys.stdin`` if the list is empty. If a filename is ``'-'``, it is also
replaced by ``sys.stdin``. To specify an alternative list of filenames, pass it
as the first argument to :func:`.input`. A single file name is also allowed.
All files are opened in text mode by default, but you can override this by
specifying the *mode* parameter in the call to :func:`.input` or
:class:`FileInput()`. If an I/O error occurs during opening or reading a file,
:exc:`IOError` is raised.
If ``sys.stdin`` is used more than once, the second and further use will return
no lines, except perhaps for interactive use, or if it has been explicitly reset
(e.g. using ``sys.stdin.seek(0)``).
Empty files are opened and immediately closed; the only time their presence in
the list of filenames is noticeable at all is when the last file opened is
empty.
Lines are returned with any newlines intact, which means that the last line in
a file may not have one.
You can control how files are opened by providing an opening hook via the
*openhook* parameter to :func:`fileinput.input` or :class:`FileInput()`. The
hook must be a function that takes two arguments, *filename* and *mode*, and
returns an accordingly opened file-like object. Two useful hooks are already
provided by this module.
The following function is the primary interface of this module:
.. function:: input([files[, inplace[, backup[, bufsize[, mode[, openhook]]]]]])
Create an instance of the :class:`FileInput` class. The instance will be used
as global state for the functions of this module, and is also returned to use
during iteration. The parameters to this function will be passed along to the
constructor of the :class:`FileInput` class.
.. versionchanged:: 2.5
Added the *mode* and *openhook* parameters.
.. versionchanged:: 2.7.12
The *bufsize* parameter is no longer used.
The following functions use the global state created by :func:`fileinput.input`;
if there is no active state, :exc:`RuntimeError` is raised.
.. function:: filename()
Return the name of the file currently being read. Before the first line has
been read, returns ``None``.
.. function:: fileno()
Return the integer "file descriptor" for the current file. When no file is
opened (before the first line and between files), returns ``-1``.
.. versionadded:: 2.5
.. function:: lineno()
Return the cumulative line number of the line that has just been read. Before
the first line has been read, returns ``0``. After the last line of the last
file has been read, returns the line number of that line.
.. function:: filelineno()
Return the line number in the current file. Before the first line has been
read, returns ``0``. After the last line of the last file has been read,
returns the line number of that line within the file.
.. function:: isfirstline()
Returns true if the line just read is the first line of its file, otherwise
returns false.
.. function:: isstdin()
Returns true if the last line was read from ``sys.stdin``, otherwise returns
false.
.. function:: nextfile()
Close the current file so that the next iteration will read the first line from
the next file (if any); lines not read from the file will not count towards the
cumulative line count. The filename is not changed until after the first line
of the next file has been read. Before the first line has been read, this
function has no effect; it cannot be used to skip the first file. After the
last line of the last file has been read, this function has no effect.
.. function:: close()
Close the sequence.
The class which implements the sequence behavior provided by the module is
available for subclassing as well:
.. class:: FileInput([files[, inplace[, backup[,bufsize[, mode[, openhook]]]]]])
Class :class:`FileInput` is the implementation; its methods :meth:`filename`,
:meth:`fileno`, :meth:`lineno`, :meth:`filelineno`, :meth:`isfirstline`,
:meth:`isstdin`, :meth:`nextfile` and :meth:`close` correspond to the
functions of the same name in the module. In addition it has a
:meth:`~file.readline` method which returns the next input line,
and a :meth:`__getitem__` method which implements the sequence behavior.
The sequence must be accessed in strictly sequential order; random access
and :meth:`~file.readline` cannot be mixed.
With *mode* you can specify which file mode will be passed to :func:`open`. It
must be one of ``'r'``, ``'rU'``, ``'U'`` and ``'rb'``.
The *openhook*, when given, must be a function that takes two arguments,
*filename* and *mode*, and returns an accordingly opened file-like object. You
cannot use *inplace* and *openhook* together.
.. versionchanged:: 2.5
Added the *mode* and *openhook* parameters.
.. versionchanged:: 2.7.12
The *bufsize* parameter is no longer used.
**Optional in-place filtering:** if the keyword argument ``inplace=1`` is passed
to :func:`fileinput.input` or to the :class:`FileInput` constructor, the file is
moved to a backup file and standard output is directed to the input file (if a
file of the same name as the backup file already exists, it will be replaced
silently). This makes it possible to write a filter that rewrites its input
file in place. If the *backup* parameter is given (typically as
``backup='.<some extension>'``), it specifies the extension for the backup file,
and the backup file remains around; by default, the extension is ``'.bak'`` and
it is deleted when the output file is closed. In-place filtering is disabled
when standard input is read.
.. note::
The current implementation does not work for MS-DOS 8+3 filesystems.
The two following opening hooks are provided by this module:
.. function:: hook_compressed(filename, mode)
Transparently opens files compressed with gzip and bzip2 (recognized by the
extensions ``'.gz'`` and ``'.bz2'``) using the :mod:`gzip` and :mod:`bz2`
modules. If the filename extension is not ``'.gz'`` or ``'.bz2'``, the file is
opened normally (ie, using :func:`open` without any decompression).
Usage example: ``fi = fileinput.FileInput(openhook=fileinput.hook_compressed)``
.. versionadded:: 2.5
.. function:: hook_encoded(encoding)
Returns a hook which opens each file with :func:`io.open`, using the given
*encoding* to read the file.
Usage example: ``fi =
fileinput.FileInput(openhook=fileinput.hook_encoded("iso-8859-1"))``
.. note::
With this hook, :class:`FileInput` might return Unicode strings depending on the
specified *encoding*.
.. versionadded:: 2.5
PK %�\��& & % html/_sources/library/filesys.rst.txtnu �[���
.. _filesys:
*************************
File and Directory Access
*************************
The modules described in this chapter deal with disk files and directories. For
example, there are modules for reading the properties of files, manipulating
paths in a portable way, and creating temporary files. The full list of modules
in this chapter is:
.. toctree::
os.path.rst
fileinput.rst
stat.rst
statvfs.rst
filecmp.rst
tempfile.rst
glob.rst
fnmatch.rst
linecache.rst
shutil.rst
dircache.rst
macpath.rst
.. seealso::
Section :ref:`bltin-file-objects`
A description of Python's built-in file objects.
Module :mod:`os`
Operating system interfaces, including functions to work with files at a lower
level than the built-in file object.
PK %�\����D �D html/_sources/library/fl.rst.txtnu �[���
:mod:`fl` --- FORMS library for graphical user interfaces
=========================================================
.. module:: fl
:platform: IRIX
:synopsis: FORMS library for applications with graphical user interfaces.
:deprecated:
.. deprecated:: 2.6
The :mod:`fl` module has been removed in Python 3.
.. index::
single: FORMS Library
single: Overmars, Mark
This module provides an interface to the FORMS Library by Mark Overmars. The
source for the library can be retrieved by anonymous FTP from host
``ftp.cs.ruu.nl``, directory :file:`SGI/FORMS`. It was last tested with version
2.0b.
Most functions are literal translations of their C equivalents, dropping the
initial ``fl_`` from their name. Constants used by the library are defined in
module :mod:`FL` described below.
The creation of objects is a little different in Python than in C: instead of
the 'current form' maintained by the library to which new FORMS objects are
added, all functions that add a FORMS object to a form are methods of the Python
object representing the form. Consequently, there are no Python equivalents for
the C functions :c:func:`fl_addto_form` and :c:func:`fl_end_form`, and the
equivalent of :c:func:`fl_bgn_form` is called :func:`fl.make_form`.
Watch out for the somewhat confusing terminology: FORMS uses the word
:dfn:`object` for the buttons, sliders etc. that you can place in a form. In
Python, 'object' means any value. The Python interface to FORMS introduces two
new Python object types: form objects (representing an entire form) and FORMS
objects (representing one button, slider etc.). Hopefully this isn't too
confusing.
There are no 'free objects' in the Python interface to FORMS, nor is there an
easy way to add object classes written in Python. The FORMS interface to GL
event handling is available, though, so you can mix FORMS with pure GL windows.
**Please note:** importing :mod:`fl` implies a call to the GL function
:c:func:`foreground` and to the FORMS routine :c:func:`fl_init`.
.. _fl-functions:
Functions Defined in Module :mod:`fl`
-------------------------------------
Module :mod:`fl` defines the following functions. For more information about
what they do, see the description of the equivalent C function in the FORMS
documentation:
.. function:: make_form(type, width, height)
Create a form with given type, width and height. This returns a :dfn:`form`
object, whose methods are described below.
.. function:: do_forms()
The standard FORMS main loop. Returns a Python object representing the FORMS
object needing interaction, or the special value :const:`FL.EVENT`.
.. function:: check_forms()
Check for FORMS events. Returns what :func:`do_forms` above returns, or
``None`` if there is no event that immediately needs interaction.
.. function:: set_event_call_back(function)
Set the event callback function.
.. function:: set_graphics_mode(rgbmode, doublebuffering)
Set the graphics modes.
.. function:: get_rgbmode()
Return the current rgb mode. This is the value of the C global variable
:c:data:`fl_rgbmode`.
.. function:: show_message(str1, str2, str3)
Show a dialog box with a three-line message and an OK button.
.. function:: show_question(str1, str2, str3)
Show a dialog box with a three-line message and YES and NO buttons. It returns
``1`` if the user pressed YES, ``0`` if NO.
.. function:: show_choice(str1, str2, str3, but1[, but2[, but3]])
Show a dialog box with a three-line message and up to three buttons. It returns
the number of the button clicked by the user (``1``, ``2`` or ``3``).
.. function:: show_input(prompt, default)
Show a dialog box with a one-line prompt message and text field in which the
user can enter a string. The second argument is the default input string. It
returns the string value as edited by the user.
.. function:: show_file_selector(message, directory, pattern, default)
Show a dialog box in which the user can select a file. It returns the absolute
filename selected by the user, or ``None`` if the user presses Cancel.
.. function:: get_directory()
get_pattern()
get_filename()
These functions return the directory, pattern and filename (the tail part only)
selected by the user in the last :func:`show_file_selector` call.
.. function:: qdevice(dev)
unqdevice(dev)
isqueued(dev)
qtest()
qread()
qreset()
qenter(dev, val)
get_mouse()
tie(button, valuator1, valuator2)
These functions are the FORMS interfaces to the corresponding GL functions. Use
these if you want to handle some GL events yourself when using
:func:`fl.do_events`. When a GL event is detected that FORMS cannot handle,
:func:`fl.do_forms` returns the special value :const:`FL.EVENT` and you should
call :func:`fl.qread` to read the event from the queue. Don't use the
equivalent GL functions!
.. \funcline{blkqread}{?}
.. function:: color()
mapcolor()
getmcolor()
See the description in the FORMS documentation of :c:func:`fl_color`,
:c:func:`fl_mapcolor` and :c:func:`fl_getmcolor`.
.. _form-objects:
Form Objects
------------
Form objects (returned by :func:`make_form` above) have the following methods.
Each method corresponds to a C function whose name is prefixed with ``fl_``; and
whose first argument is a form pointer; please refer to the official FORMS
documentation for descriptions.
All the :meth:`add_\*` methods return a Python object representing the FORMS
object. Methods of FORMS objects are described below. Most kinds of FORMS
object also have some methods specific to that kind; these methods are listed
here.
.. method:: form.show_form(placement, bordertype, name)
Show the form.
.. method:: form.hide_form()
Hide the form.
.. method:: form.redraw_form()
Redraw the form.
.. method:: form.set_form_position(x, y)
Set the form's position.
.. method:: form.freeze_form()
Freeze the form.
.. method:: form.unfreeze_form()
Unfreeze the form.
.. method:: form.activate_form()
Activate the form.
.. method:: form.deactivate_form()
Deactivate the form.
.. method:: form.bgn_group()
Begin a new group of objects; return a group object.
.. method:: form.end_group()
End the current group of objects.
.. method:: form.find_first()
Find the first object in the form.
.. method:: form.find_last()
Find the last object in the form.
.. method:: form.add_box(type, x, y, w, h, name)
Add a box object to the form. No extra methods.
.. method:: form.add_text(type, x, y, w, h, name)
Add a text object to the form. No extra methods.
.. \begin{methoddesc}[form]{add_bitmap}{type, x, y, w, h, name}
.. Add a bitmap object to the form.
.. \end{methoddesc}
.. method:: form.add_clock(type, x, y, w, h, name)
Add a clock object to the form. --- Method: :meth:`get_clock`.
.. method:: form.add_button(type, x, y, w, h, name)
Add a button object to the form. --- Methods: :meth:`get_button`,
:meth:`set_button`.
.. method:: form.add_lightbutton(type, x, y, w, h, name)
Add a lightbutton object to the form. --- Methods: :meth:`get_button`,
:meth:`set_button`.
.. method:: form.add_roundbutton(type, x, y, w, h, name)
Add a roundbutton object to the form. --- Methods: :meth:`get_button`,
:meth:`set_button`.
.. method:: form.add_slider(type, x, y, w, h, name)
Add a slider object to the form. --- Methods: :meth:`set_slider_value`,
:meth:`get_slider_value`, :meth:`set_slider_bounds`, :meth:`get_slider_bounds`,
:meth:`set_slider_return`, :meth:`set_slider_size`,
:meth:`set_slider_precision`, :meth:`set_slider_step`.
.. method:: form.add_valslider(type, x, y, w, h, name)
Add a valslider object to the form. --- Methods: :meth:`set_slider_value`,
:meth:`get_slider_value`, :meth:`set_slider_bounds`, :meth:`get_slider_bounds`,
:meth:`set_slider_return`, :meth:`set_slider_size`,
:meth:`set_slider_precision`, :meth:`set_slider_step`.
.. method:: form.add_dial(type, x, y, w, h, name)
Add a dial object to the form. --- Methods: :meth:`set_dial_value`,
:meth:`get_dial_value`, :meth:`set_dial_bounds`, :meth:`get_dial_bounds`.
.. method:: form.add_positioner(type, x, y, w, h, name)
Add a positioner object to the form. --- Methods:
:meth:`set_positioner_xvalue`, :meth:`set_positioner_yvalue`,
:meth:`set_positioner_xbounds`, :meth:`set_positioner_ybounds`,
:meth:`get_positioner_xvalue`, :meth:`get_positioner_yvalue`,
:meth:`get_positioner_xbounds`, :meth:`get_positioner_ybounds`.
.. method:: form.add_counter(type, x, y, w, h, name)
Add a counter object to the form. --- Methods: :meth:`set_counter_value`,
:meth:`get_counter_value`, :meth:`set_counter_bounds`, :meth:`set_counter_step`,
:meth:`set_counter_precision`, :meth:`set_counter_return`.
.. method:: form.add_input(type, x, y, w, h, name)
Add an input object to the form. --- Methods: :meth:`set_input`,
:meth:`get_input`, :meth:`set_input_color`, :meth:`set_input_return`.
.. method:: form.add_menu(type, x, y, w, h, name)
Add a menu object to the form. --- Methods: :meth:`set_menu`,
:meth:`get_menu`, :meth:`addto_menu`.
.. method:: form.add_choice(type, x, y, w, h, name)
Add a choice object to the form. --- Methods: :meth:`set_choice`,
:meth:`get_choice`, :meth:`clear_choice`, :meth:`addto_choice`,
:meth:`replace_choice`, :meth:`delete_choice`, :meth:`get_choice_text`,
:meth:`set_choice_fontsize`, :meth:`set_choice_fontstyle`.
.. method:: form.add_browser(type, x, y, w, h, name)
Add a browser object to the form. --- Methods: :meth:`set_browser_topline`,
:meth:`clear_browser`, :meth:`add_browser_line`, :meth:`addto_browser`,
:meth:`insert_browser_line`, :meth:`delete_browser_line`,
:meth:`replace_browser_line`, :meth:`get_browser_line`, :meth:`load_browser`,
:meth:`get_browser_maxline`, :meth:`select_browser_line`,
:meth:`deselect_browser_line`, :meth:`deselect_browser`,
:meth:`isselected_browser_line`, :meth:`get_browser`,
:meth:`set_browser_fontsize`, :meth:`set_browser_fontstyle`,
:meth:`set_browser_specialkey`.
.. method:: form.add_timer(type, x, y, w, h, name)
Add a timer object to the form. --- Methods: :meth:`set_timer`,
:meth:`get_timer`.
Form objects have the following data attributes; see the FORMS documentation:
+---------------------+-----------------+--------------------------------+
| Name | C Type | Meaning |
+=====================+=================+================================+
| :attr:`window` | int (read-only) | GL window id |
+---------------------+-----------------+--------------------------------+
| :attr:`w` | float | form width |
+---------------------+-----------------+--------------------------------+
| :attr:`h` | float | form height |
+---------------------+-----------------+--------------------------------+
| :attr:`x` | float | form x origin |
+---------------------+-----------------+--------------------------------+
| :attr:`y` | float | form y origin |
+---------------------+-----------------+--------------------------------+
| :attr:`deactivated` | int | nonzero if form is deactivated |
+---------------------+-----------------+--------------------------------+
| :attr:`visible` | int | nonzero if form is visible |
+---------------------+-----------------+--------------------------------+
| :attr:`frozen` | int | nonzero if form is frozen |
+---------------------+-----------------+--------------------------------+
| :attr:`doublebuf` | int | nonzero if double buffering on |
+---------------------+-----------------+--------------------------------+
.. _forms-objects:
FORMS Objects
-------------
Besides methods specific to particular kinds of FORMS objects, all FORMS objects
also have the following methods:
.. method:: FORMS object.set_call_back(function, argument)
Set the object's callback function and argument. When the object needs
interaction, the callback function will be called with two arguments: the
object, and the callback argument. (FORMS objects without a callback function
are returned by :func:`fl.do_forms` or :func:`fl.check_forms` when they need
interaction.) Call this method without arguments to remove the callback
function.
.. method:: FORMS object.delete_object()
Delete the object.
.. method:: FORMS object.show_object()
Show the object.
.. method:: FORMS object.hide_object()
Hide the object.
.. method:: FORMS object.redraw_object()
Redraw the object.
.. method:: FORMS object.freeze_object()
Freeze the object.
.. method:: FORMS object.unfreeze_object()
Unfreeze the object.
FORMS objects have these data attributes; see the FORMS documentation:
.. \begin{methoddesc}[FORMS object]{handle_object}{} XXX
.. \end{methoddesc}
.. \begin{methoddesc}[FORMS object]{handle_object_direct}{} XXX
.. \end{methoddesc}
+--------------------+-----------------+------------------+
| Name | C Type | Meaning |
+====================+=================+==================+
| :attr:`objclass` | int (read-only) | object class |
+--------------------+-----------------+------------------+
| :attr:`type` | int (read-only) | object type |
+--------------------+-----------------+------------------+
| :attr:`boxtype` | int | box type |
+--------------------+-----------------+------------------+
| :attr:`x` | float | x origin |
+--------------------+-----------------+------------------+
| :attr:`y` | float | y origin |
+--------------------+-----------------+------------------+
| :attr:`w` | float | width |
+--------------------+-----------------+------------------+
| :attr:`h` | float | height |
+--------------------+-----------------+------------------+
| :attr:`col1` | int | primary color |
+--------------------+-----------------+------------------+
| :attr:`col2` | int | secondary color |
+--------------------+-----------------+------------------+
| :attr:`align` | int | alignment |
+--------------------+-----------------+------------------+
| :attr:`lcol` | int | label color |
+--------------------+-----------------+------------------+
| :attr:`lsize` | float | label font size |
+--------------------+-----------------+------------------+
| :attr:`label` | string | label string |
+--------------------+-----------------+------------------+
| :attr:`lstyle` | int | label style |
+--------------------+-----------------+------------------+
| :attr:`pushed` | int (read-only) | (see FORMS docs) |
+--------------------+-----------------+------------------+
| :attr:`focus` | int (read-only) | (see FORMS docs) |
+--------------------+-----------------+------------------+
| :attr:`belowmouse` | int (read-only) | (see FORMS docs) |
+--------------------+-----------------+------------------+
| :attr:`frozen` | int (read-only) | (see FORMS docs) |
+--------------------+-----------------+------------------+
| :attr:`active` | int (read-only) | (see FORMS docs) |
+--------------------+-----------------+------------------+
| :attr:`input` | int (read-only) | (see FORMS docs) |
+--------------------+-----------------+------------------+
| :attr:`visible` | int (read-only) | (see FORMS docs) |
+--------------------+-----------------+------------------+
| :attr:`radio` | int (read-only) | (see FORMS docs) |
+--------------------+-----------------+------------------+
| :attr:`automatic` | int (read-only) | (see FORMS docs) |
+--------------------+-----------------+------------------+
:mod:`FL` --- Constants used with the :mod:`fl` module
======================================================
.. module:: FL
:platform: IRIX
:synopsis: Constants used with the fl module.
:deprecated:
.. deprecated:: 2.6
The :mod:`FL` module has been removed in Python 3.
This module defines symbolic constants needed to use the built-in module
:mod:`fl` (see above); they are equivalent to those defined in the C header file
``<forms.h>`` except that the name prefix ``FL_`` is omitted. Read the module
source for a complete list of the defined names. Suggested use::
import fl
from FL import *
:mod:`flp` --- Functions for loading stored FORMS designs
=========================================================
.. module:: flp
:platform: IRIX
:synopsis: Functions for loading stored FORMS designs.
:deprecated:
.. deprecated:: 2.6
The :mod:`flp` module has been removed in Python 3.
This module defines functions that can read form definitions created by the
'form designer' (:program:`fdesign`) program that comes with the FORMS library
(see module :mod:`fl` above).
For now, see the file :file:`flp.doc` in the Python library source directory for
a description.
XXX A complete description should be inserted here!
PK %�\5�:�
�
html/_sources/library/fm.rst.txtnu �[���
:mod:`fm` --- *Font Manager* interface
======================================
.. module:: fm
:platform: IRIX
:synopsis: Font Manager interface for SGI workstations.
:deprecated:
.. deprecated:: 2.6
The :mod:`fm` module has been removed in Python 3.
.. index::
single: Font Manager, IRIS
single: IRIS Font Manager
This module provides access to the IRIS *Font Manager* library. It is
available only on Silicon Graphics machines. See also: *4Sight User's Guide*,
section 1, chapter 5: "Using the IRIS Font Manager."
This is not yet a full interface to the IRIS Font Manager. Among the unsupported
features are: matrix operations; cache operations; character operations (use
string operations instead); some details of font info; individual glyph metrics;
and printer matching.
It supports the following operations:
.. function:: init()
Initialization function. Calls :c:func:`fminit`. It is normally not necessary to
call this function, since it is called automatically the first time the
:mod:`fm` module is imported.
.. function:: findfont(fontname)
Return a font handle object. Calls ``fmfindfont(fontname)``.
.. function:: enumerate()
Returns a list of available font names. This is an interface to
:c:func:`fmenumerate`.
.. function:: prstr(string)
Render a string using the current font (see the :func:`setfont` font handle
method below). Calls ``fmprstr(string)``.
.. function:: setpath(string)
Sets the font search path. Calls ``fmsetpath(string)``. (XXX Does not work!?!)
.. function:: fontpath()
Returns the current font search path.
Font handle objects support the following operations:
.. method:: font handle.scalefont(factor)
Returns a handle for a scaled version of this font. Calls ``fmscalefont(fh,
factor)``.
.. method:: font handle.setfont()
Makes this font the current font. Note: the effect is undone silently when the
font handle object is deleted. Calls ``fmsetfont(fh)``.
.. method:: font handle.getfontname()
Returns this font's name. Calls ``fmgetfontname(fh)``.
.. method:: font handle.getcomment()
Returns the comment string associated with this font. Raises an exception if
there is none. Calls ``fmgetcomment(fh)``.
.. method:: font handle.getfontinfo()
Returns a tuple giving some pertinent data about this font. This is an interface
to ``fmgetfontinfo()``. The returned tuple contains the following numbers:
``(printermatched, fixed_width, xorig, yorig, xsize, ysize, height, nglyphs)``.
.. method:: font handle.getstrwidth(string)
Returns the width, in pixels, of *string* when drawn in this font. Calls
``fmgetstrwidth(fh, string)``.
PK %�\�"6j % html/_sources/library/fnmatch.rst.txtnu �[��� :mod:`fnmatch` --- Unix filename pattern matching
=================================================
.. module:: fnmatch
:synopsis: Unix shell style filename pattern matching.
.. index:: single: filenames; wildcard expansion
.. index:: module: re
**Source code:** :source:`Lib/fnmatch.py`
--------------
This module provides support for Unix shell-style wildcards, which are *not* the
same as regular expressions (which are documented in the :mod:`re` module). The
special characters used in shell-style wildcards are:
+------------+------------------------------------+
| Pattern | Meaning |
+============+====================================+
| ``*`` | matches everything |
+------------+------------------------------------+
| ``?`` | matches any single character |
+------------+------------------------------------+
| ``[seq]`` | matches any character in *seq* |
+------------+------------------------------------+
| ``[!seq]`` | matches any character not in *seq* |
+------------+------------------------------------+
For a literal match, wrap the meta-characters in brackets.
For example, ``'[?]'`` matches the character ``'?'``.
.. index:: module: glob
Note that the filename separator (``'/'`` on Unix) is *not* special to this
module. See module :mod:`glob` for pathname expansion (:mod:`glob` uses
:func:`.filter` to match pathname segments). Similarly, filenames starting with
a period are not special for this module, and are matched by the ``*`` and ``?``
patterns.
.. function:: fnmatch(filename, pattern)
Test whether the *filename* string matches the *pattern* string, returning
:const:`True` or :const:`False`. Both parameters are case-normalized
using :func:`os.path.normcase`. :func:`fnmatchcase` can be used to perform a
case-sensitive comparison, regardless of whether that's standard for the
operating system.
This example will print all file names in the current directory with the
extension ``.txt``::
import fnmatch
import os
for file in os.listdir('.'):
if fnmatch.fnmatch(file, '*.txt'):
print file
.. function:: fnmatchcase(filename, pattern)
Test whether *filename* matches *pattern*, returning :const:`True` or
:const:`False`; the comparison is case-sensitive and does not apply
:func:`os.path.normcase`.
.. function:: filter(names, pattern)
Return the subset of the list of *names* that match *pattern*. It is the same as
``[n for n in names if fnmatch(n, pattern)]``, but implemented more efficiently.
.. versionadded:: 2.2
.. function:: translate(pattern)
Return the shell-style *pattern* converted to a regular expression for
using with :func:`re.match`.
Example:
>>> import fnmatch, re
>>>
>>> regex = fnmatch.translate('*.txt')
>>> regex
'.*\\.txt\\Z(?ms)'
>>> reobj = re.compile(regex)
>>> reobj.match('foobar.txt')
<_sre.SRE_Match object at 0x...>
.. seealso::
Module :mod:`glob`
Unix shell-style path expansion.
PK %�\�Y�ս3 �3 ' html/_sources/library/formatter.rst.txtnu �[���
:mod:`formatter` --- Generic output formatting
==============================================
.. module:: formatter
:synopsis: Generic output formatter and device interface.
.. index:: single: HTMLParser (class in htmllib)
This module supports two interface definitions, each with multiple
implementations. The *formatter* interface is used by the :class:`~HTMLParser.HTMLParser`
class of the :mod:`htmllib` module, and the *writer* interface is required by
the formatter interface.
Formatter objects transform an abstract flow of formatting events into specific
output events on writer objects. Formatters manage several stack structures to
allow various properties of a writer object to be changed and restored; writers
need not be able to handle relative changes nor any sort of "change back"
operation. Specific writer properties which may be controlled via formatter
objects are horizontal alignment, font, and left margin indentations. A
mechanism is provided which supports providing arbitrary, non-exclusive style
settings to a writer as well. Additional interfaces facilitate formatting
events which are not reversible, such as paragraph separation.
Writer objects encapsulate device interfaces. Abstract devices, such as file
formats, are supported as well as physical devices. The provided
implementations all work with abstract devices. The interface makes available
mechanisms for setting the properties which formatter objects manage and
inserting data into the output.
.. _formatter-interface:
The Formatter Interface
-----------------------
Interfaces to create formatters are dependent on the specific formatter class
being instantiated. The interfaces described below are the required interfaces
which all formatters must support once initialized.
One data element is defined at the module level:
.. data:: AS_IS
Value which can be used in the font specification passed to the ``push_font()``
method described below, or as the new value to any other ``push_property()``
method. Pushing the ``AS_IS`` value allows the corresponding ``pop_property()``
method to be called without having to track whether the property was changed.
The following attributes are defined for formatter instance objects:
.. attribute:: formatter.writer
The writer instance with which the formatter interacts.
.. method:: formatter.end_paragraph(blanklines)
Close any open paragraphs and insert at least *blanklines* before the next
paragraph.
.. method:: formatter.add_line_break()
Add a hard line break if one does not already exist. This does not break the
logical paragraph.
.. method:: formatter.add_hor_rule(*args, **kw)
Insert a horizontal rule in the output. A hard break is inserted if there is
data in the current paragraph, but the logical paragraph is not broken. The
arguments and keywords are passed on to the writer's :meth:`send_line_break`
method.
.. method:: formatter.add_flowing_data(data)
Provide data which should be formatted with collapsed whitespace. Whitespace
from preceding and successive calls to :meth:`add_flowing_data` is considered as
well when the whitespace collapse is performed. The data which is passed to
this method is expected to be word-wrapped by the output device. Note that any
word-wrapping still must be performed by the writer object due to the need to
rely on device and font information.
.. method:: formatter.add_literal_data(data)
Provide data which should be passed to the writer unchanged. Whitespace,
including newline and tab characters, are considered legal in the value of
*data*.
.. method:: formatter.add_label_data(format, counter)
Insert a label which should be placed to the left of the current left margin.
This should be used for constructing bulleted or numbered lists. If the
*format* value is a string, it is interpreted as a format specification for
*counter*, which should be an integer. The result of this formatting becomes the
value of the label; if *format* is not a string it is used as the label value
directly. The label value is passed as the only argument to the writer's
:meth:`send_label_data` method. Interpretation of non-string label values is
dependent on the associated writer.
Format specifications are strings which, in combination with a counter value,
are used to compute label values. Each character in the format string is copied
to the label value, with some characters recognized to indicate a transform on
the counter value. Specifically, the character ``'1'`` represents the counter
value formatter as an Arabic number, the characters ``'A'`` and ``'a'``
represent alphabetic representations of the counter value in upper and lower
case, respectively, and ``'I'`` and ``'i'`` represent the counter value in Roman
numerals, in upper and lower case. Note that the alphabetic and roman
transforms require that the counter value be greater than zero.
.. method:: formatter.flush_softspace()
Send any pending whitespace buffered from a previous call to
:meth:`add_flowing_data` to the associated writer object. This should be called
before any direct manipulation of the writer object.
.. method:: formatter.push_alignment(align)
Push a new alignment setting onto the alignment stack. This may be
:const:`AS_IS` if no change is desired. If the alignment value is changed from
the previous setting, the writer's :meth:`new_alignment` method is called with
the *align* value.
.. method:: formatter.pop_alignment()
Restore the previous alignment.
.. method:: formatter.push_font((size, italic, bold, teletype))
Change some or all font properties of the writer object. Properties which are
not set to :const:`AS_IS` are set to the values passed in while others are
maintained at their current settings. The writer's :meth:`new_font` method is
called with the fully resolved font specification.
.. method:: formatter.pop_font()
Restore the previous font.
.. method:: formatter.push_margin(margin)
Increase the number of left margin indentations by one, associating the logical
tag *margin* with the new indentation. The initial margin level is ``0``.
Changed values of the logical tag must be true values; false values other than
:const:`AS_IS` are not sufficient to change the margin.
.. method:: formatter.pop_margin()
Restore the previous margin.
.. method:: formatter.push_style(*styles)
Push any number of arbitrary style specifications. All styles are pushed onto
the styles stack in order. A tuple representing the entire stack, including
:const:`AS_IS` values, is passed to the writer's :meth:`new_styles` method.
.. method:: formatter.pop_style([n=1])
Pop the last *n* style specifications passed to :meth:`push_style`. A tuple
representing the revised stack, including :const:`AS_IS` values, is passed to
the writer's :meth:`new_styles` method.
.. method:: formatter.set_spacing(spacing)
Set the spacing style for the writer.
.. method:: formatter.assert_line_data([flag=1])
Inform the formatter that data has been added to the current paragraph
out-of-band. This should be used when the writer has been manipulated
directly. The optional *flag* argument can be set to false if the writer
manipulations produced a hard line break at the end of the output.
.. _formatter-impls:
Formatter Implementations
-------------------------
Two implementations of formatter objects are provided by this module. Most
applications may use one of these classes without modification or subclassing.
.. class:: NullFormatter([writer])
A formatter which does nothing. If *writer* is omitted, a :class:`NullWriter`
instance is created. No methods of the writer are called by
:class:`NullFormatter` instances. Implementations should inherit from this
class if implementing a writer interface but don't need to inherit any
implementation.
.. class:: AbstractFormatter(writer)
The standard formatter. This implementation has demonstrated wide applicability
to many writers, and may be used directly in most circumstances. It has been
used to implement a full-featured World Wide Web browser.
.. _writer-interface:
The Writer Interface
--------------------
Interfaces to create writers are dependent on the specific writer class being
instantiated. The interfaces described below are the required interfaces which
all writers must support once initialized. Note that while most applications can
use the :class:`AbstractFormatter` class as a formatter, the writer must
typically be provided by the application.
.. method:: writer.flush()
Flush any buffered output or device control events.
.. method:: writer.new_alignment(align)
Set the alignment style. The *align* value can be any object, but by convention
is a string or ``None``, where ``None`` indicates that the writer's "preferred"
alignment should be used. Conventional *align* values are ``'left'``,
``'center'``, ``'right'``, and ``'justify'``.
.. method:: writer.new_font(font)
Set the font style. The value of *font* will be ``None``, indicating that the
device's default font should be used, or a tuple of the form ``(size,
italic, bold, teletype)``. Size will be a string indicating the size of
font that should be used; specific strings and their interpretation must be
defined by the application. The *italic*, *bold*, and *teletype* values are
Boolean values specifying which of those font attributes should be used.
.. method:: writer.new_margin(margin, level)
Set the margin level to the integer *level* and the logical tag to *margin*.
Interpretation of the logical tag is at the writer's discretion; the only
restriction on the value of the logical tag is that it not be a false value for
non-zero values of *level*.
.. method:: writer.new_spacing(spacing)
Set the spacing style to *spacing*.
.. method:: writer.new_styles(styles)
Set additional styles. The *styles* value is a tuple of arbitrary values; the
value :const:`AS_IS` should be ignored. The *styles* tuple may be interpreted
either as a set or as a stack depending on the requirements of the application
and writer implementation.
.. method:: writer.send_line_break()
Break the current line.
.. method:: writer.send_paragraph(blankline)
Produce a paragraph separation of at least *blankline* blank lines, or the
equivalent. The *blankline* value will be an integer. Note that the
implementation will receive a call to :meth:`send_line_break` before this call
if a line break is needed; this method should not include ending the last line
of the paragraph. It is only responsible for vertical spacing between
paragraphs.
.. method:: writer.send_hor_rule(*args, **kw)
Display a horizontal rule on the output device. The arguments to this method
are entirely application- and writer-specific, and should be interpreted with
care. The method implementation may assume that a line break has already been
issued via :meth:`send_line_break`.
.. method:: writer.send_flowing_data(data)
Output character data which may be word-wrapped and re-flowed as needed. Within
any sequence of calls to this method, the writer may assume that spans of
multiple whitespace characters have been collapsed to single space characters.
.. method:: writer.send_literal_data(data)
Output character data which has already been formatted for display. Generally,
this should be interpreted to mean that line breaks indicated by newline
characters should be preserved and no new line breaks should be introduced. The
data may contain embedded newline and tab characters, unlike data provided to
the :meth:`send_formatted_data` interface.
.. method:: writer.send_label_data(data)
Set *data* to the left of the current left margin, if possible. The value of
*data* is not restricted; treatment of non-string values is entirely
application- and writer-dependent. This method will only be called at the
beginning of a line.
.. _writer-impls:
Writer Implementations
----------------------
Three implementations of the writer object interface are provided as examples by
this module. Most applications will need to derive new writer classes from the
:class:`NullWriter` class.
.. class:: NullWriter()
A writer which only provides the interface definition; no actions are taken on
any methods. This should be the base class for all writers which do not need to
inherit any implementation methods.
.. class:: AbstractWriter()
A writer which can be used in debugging formatters, but not much else. Each
method simply announces itself by printing its name and arguments on standard
output.
.. class:: DumbWriter(file=None, maxcol=72)
Simple writer class which writes output on the file object passed in as *file*
or, if *file* is ``None``, on standard output. The output is simply word-wrapped
to the number of columns specified by *maxcol*. This class is suitable for
reflowing a sequence of paragraphs.
PK %�\�EK K $ html/_sources/library/fpectl.rst.txtnu �[���
:mod:`fpectl` --- Floating point exception control
==================================================
.. module:: fpectl
:platform: Unix
:synopsis: Provide control for floating point exception handling.
.. moduleauthor:: Lee Busby <busby1@llnl.gov>
.. sectionauthor:: Lee Busby <busby1@llnl.gov>
.. note::
The :mod:`fpectl` module is not built by default, and its usage is discouraged
and may be dangerous except in the hands of experts. See also the section
:ref:`fpectl-limitations` on limitations for more details.
.. index:: single: IEEE-754
Most computers carry out floating point operations in conformance with the
so-called IEEE-754 standard. On any real computer, some floating point
operations produce results that cannot be expressed as a normal floating point
value. For example, try ::
>>> import math
>>> math.exp(1000)
inf
>>> math.exp(1000) / math.exp(1000)
nan
(The example above will work on many platforms. DEC Alpha may be one exception.)
"Inf" is a special, non-numeric value in IEEE-754 that stands for "infinity",
and "nan" means "not a number." Note that, other than the non-numeric results,
nothing special happened when you asked Python to carry out those calculations.
That is in fact the default behaviour prescribed in the IEEE-754 standard, and
if it works for you, stop reading now.
In some circumstances, it would be better to raise an exception and stop
processing at the point where the faulty operation was attempted. The
:mod:`fpectl` module is for use in that situation. It provides control over
floating point units from several hardware manufacturers, allowing the user to
turn on the generation of :const:`SIGFPE` whenever any of the IEEE-754
exceptions Division by Zero, Overflow, or Invalid Operation occurs. In tandem
with a pair of wrapper macros that are inserted into the C code comprising your
python system, :const:`SIGFPE` is trapped and converted into the Python
:exc:`FloatingPointError` exception.
The :mod:`fpectl` module defines the following functions and may raise the given
exception:
.. function:: turnon_sigfpe()
Turn on the generation of :const:`SIGFPE`, and set up an appropriate signal
handler.
.. function:: turnoff_sigfpe()
Reset default handling of floating point exceptions.
.. exception:: FloatingPointError
After :func:`turnon_sigfpe` has been executed, a floating point operation that
raises one of the IEEE-754 exceptions Division by Zero, Overflow, or Invalid
operation will in turn raise this standard Python exception.
.. _fpectl-example:
Example
-------
The following example demonstrates how to start up and test operation of the
:mod:`fpectl` module. ::
>>> import fpectl
>>> import fpetest
>>> fpectl.turnon_sigfpe()
>>> fpetest.test()
overflow PASS
FloatingPointError: Overflow
div by 0 PASS
FloatingPointError: Division by zero
[ more output from test elided ]
>>> import math
>>> math.exp(1000)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
FloatingPointError: in math_1
.. _fpectl-limitations:
Limitations and other considerations
------------------------------------
Setting up a given processor to trap IEEE-754 floating point errors currently
requires custom code on a per-architecture basis. You may have to modify
:mod:`fpectl` to control your particular hardware.
Conversion of an IEEE-754 exception to a Python exception requires that the
wrapper macros ``PyFPE_START_PROTECT`` and ``PyFPE_END_PROTECT`` be inserted
into your code in an appropriate fashion. Python itself has been modified to
support the :mod:`fpectl` module, but many other codes of interest to numerical
analysts have not.
The :mod:`fpectl` module is not thread-safe.
.. seealso::
Some files in the source distribution may be interesting in learning more about
how this module operates. The include file :source:`Include/pyfpe.h` discusses the
implementation of this module at some length. :source:`Modules/fpetestmodule.c`
gives several examples of use. Many additional examples can be found in
:source:`Objects/floatobject.c`.
PK %�\@
�� � & html/_sources/library/fpformat.rst.txtnu �[���
:mod:`fpformat` --- Floating point conversions
==============================================
.. module:: fpformat
:synopsis: General floating point formatting functions.
:deprecated:
.. deprecated:: 2.6
The :mod:`fpformat` module has been removed in Python 3.
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
The :mod:`fpformat` module defines functions for dealing with floating point
numbers representations in 100% pure Python.
.. note::
This module is unnecessary: everything here can be done using the ``%`` string
interpolation operator described in the :ref:`string-formatting` section.
The :mod:`fpformat` module defines the following functions and an exception:
.. function:: fix(x, digs)
Format *x* as ``[-]ddd.ddd`` with *digs* digits after the point and at least one
digit before. If ``digs <= 0``, the decimal point is suppressed.
*x* can be either a number or a string that looks like one. *digs* is an
integer.
Return value is a string.
.. function:: sci(x, digs)
Format *x* as ``[-]d.dddE[+-]ddd`` with *digs* digits after the point and
exactly one digit before. If ``digs <= 0``, one digit is kept and the point is
suppressed.
*x* can be either a real number, or a string that looks like one. *digs* is an
integer.
Return value is a string.
.. exception:: NotANumber
Exception raised when a string passed to :func:`fix` or :func:`sci` as the *x*
parameter does not look like a number. This is a subclass of :exc:`ValueError`
when the standard exceptions are strings. The exception value is the improperly
formatted string that caused the exception to be raised.
Example::
>>> import fpformat
>>> fpformat.fix(1.23, 1)
'1.2'
PK %�\^�ұ � ' html/_sources/library/fractions.rst.txtnu �[��� :mod:`fractions` --- Rational numbers
=====================================
.. module:: fractions
:synopsis: Rational numbers.
.. moduleauthor:: Jeffrey Yasskin <jyasskin at gmail.com>
.. sectionauthor:: Jeffrey Yasskin <jyasskin at gmail.com>
.. versionadded:: 2.6
**Source code:** :source:`Lib/fractions.py`
--------------
The :mod:`fractions` module provides support for rational number arithmetic.
A Fraction instance can be constructed from a pair of integers, from
another rational number, or from a string.
.. class:: Fraction(numerator=0, denominator=1)
Fraction(other_fraction)
Fraction(float)
Fraction(decimal)
Fraction(string)
The first version requires that *numerator* and *denominator* are instances
of :class:`numbers.Rational` and returns a new :class:`Fraction` instance
with value ``numerator/denominator``. If *denominator* is :const:`0`, it
raises a :exc:`ZeroDivisionError`. The second version requires that
*other_fraction* is an instance of :class:`numbers.Rational` and returns a
:class:`Fraction` instance with the same value. The next two versions accept
either a :class:`float` or a :class:`decimal.Decimal` instance, and return a
:class:`Fraction` instance with exactly the same value. Note that due to the
usual issues with binary floating-point (see :ref:`tut-fp-issues`), the
argument to ``Fraction(1.1)`` is not exactly equal to 11/10, and so
``Fraction(1.1)`` does *not* return ``Fraction(11, 10)`` as one might expect.
(But see the documentation for the :meth:`limit_denominator` method below.)
The last version of the constructor expects a string or unicode instance.
The usual form for this instance is::
[sign] numerator ['/' denominator]
where the optional ``sign`` may be either '+' or '-' and
``numerator`` and ``denominator`` (if present) are strings of
decimal digits. In addition, any string that represents a finite
value and is accepted by the :class:`float` constructor is also
accepted by the :class:`Fraction` constructor. In either form the
input string may also have leading and/or trailing whitespace.
Here are some examples::
>>> from fractions import Fraction
>>> Fraction(16, -10)
Fraction(-8, 5)
>>> Fraction(123)
Fraction(123, 1)
>>> Fraction()
Fraction(0, 1)
>>> Fraction('3/7')
Fraction(3, 7)
>>> Fraction(' -3/7 ')
Fraction(-3, 7)
>>> Fraction('1.414213 \t\n')
Fraction(1414213, 1000000)
>>> Fraction('-.125')
Fraction(-1, 8)
>>> Fraction('7e-6')
Fraction(7, 1000000)
>>> Fraction(2.25)
Fraction(9, 4)
>>> Fraction(1.1)
Fraction(2476979795053773, 2251799813685248)
>>> from decimal import Decimal
>>> Fraction(Decimal('1.1'))
Fraction(11, 10)
The :class:`Fraction` class inherits from the abstract base class
:class:`numbers.Rational`, and implements all of the methods and
operations from that class. :class:`Fraction` instances are hashable,
and should be treated as immutable. In addition,
:class:`Fraction` has the following methods:
.. versionchanged:: 2.7
The :class:`Fraction` constructor now accepts :class:`float` and
:class:`decimal.Decimal` instances.
.. method:: from_float(flt)
This class method constructs a :class:`Fraction` representing the exact
value of *flt*, which must be a :class:`float`. Beware that
``Fraction.from_float(0.3)`` is not the same value as ``Fraction(3, 10)``.
.. note:: From Python 2.7 onwards, you can also construct a
:class:`Fraction` instance directly from a :class:`float`.
.. method:: from_decimal(dec)
This class method constructs a :class:`Fraction` representing the exact
value of *dec*, which must be a :class:`decimal.Decimal`.
.. note:: From Python 2.7 onwards, you can also construct a
:class:`Fraction` instance directly from a :class:`decimal.Decimal`
instance.
.. method:: limit_denominator(max_denominator=1000000)
Finds and returns the closest :class:`Fraction` to ``self`` that has
denominator at most max_denominator. This method is useful for finding
rational approximations to a given floating-point number:
>>> from fractions import Fraction
>>> Fraction('3.1415926535897932').limit_denominator(1000)
Fraction(355, 113)
or for recovering a rational number that's represented as a float:
>>> from math import pi, cos
>>> Fraction(cos(pi/3))
Fraction(4503599627370497, 9007199254740992)
>>> Fraction(cos(pi/3)).limit_denominator()
Fraction(1, 2)
>>> Fraction(1.1).limit_denominator()
Fraction(11, 10)
.. function:: gcd(a, b)
Return the greatest common divisor of the integers *a* and *b*. If either
*a* or *b* is nonzero, then the absolute value of ``gcd(a, b)`` is the
largest integer that divides both *a* and *b*. ``gcd(a,b)`` has the same
sign as *b* if *b* is nonzero; otherwise it takes the sign of *a*. ``gcd(0,
0)`` returns ``0``.
.. seealso::
Module :mod:`numbers`
The abstract base classes making up the numeric tower.
PK %�\w�O��, �, ' html/_sources/library/framework.rst.txtnu �[���
:mod:`FrameWork` --- Interactive application framework
======================================================
.. module:: FrameWork
:platform: Mac
:synopsis: Interactive application framework.
:deprecated:
The :mod:`FrameWork` module contains classes that together provide a framework
for an interactive Macintosh application. The programmer builds an application
by creating subclasses that override various methods of the bases classes,
thereby implementing the functionality wanted. Overriding functionality can
often be done on various different levels, i.e. to handle clicks in a single
dialog window in a non-standard way it is not necessary to override the complete
event handling.
.. note::
This module has been removed in Python 3.x.
Work on the :mod:`FrameWork` has pretty much stopped, now that :mod:`PyObjC` is
available for full Cocoa access from Python, and the documentation describes
only the most important functionality, and not in the most logical manner at
that. Examine the source or the examples for more details. The following are
some comments posted on the MacPython newsgroup about the strengths and
limitations of :mod:`FrameWork`:
.. epigraph::
The strong point of :mod:`FrameWork` is that it allows you to break into the
control-flow at many different places. :mod:`W`, for instance, uses a different
way to enable/disable menus and that plugs right in leaving the rest intact.
The weak points of :mod:`FrameWork` are that it has no abstract command
interface (but that shouldn't be difficult), that its dialog support is minimal
and that its control/toolbar support is non-existent.
The :mod:`FrameWork` module defines the following functions:
.. function:: Application()
An object representing the complete application. See below for a description of
the methods. The default :meth:`__init__` routine creates an empty window
dictionary and a menu bar with an apple menu.
.. function:: MenuBar()
An object representing the menubar. This object is usually not created by the
user.
.. function:: Menu(bar, title[, after])
An object representing a menu. Upon creation you pass the ``MenuBar`` the menu
appears in, the *title* string and a position (1-based) *after* where the menu
should appear (default: at the end).
.. function:: MenuItem(menu, title[, shortcut, callback])
Create a menu item object. The arguments are the menu to create, the item title
string and optionally the keyboard shortcut and a callback routine. The callback
is called with the arguments menu-id, item number within menu (1-based), current
front window and the event record.
Instead of a callable object the callback can also be a string. In this case
menu selection causes the lookup of a method in the topmost window and the
application. The method name is the callback string with ``'domenu_'``
prepended.
Calling the ``MenuBar`` :meth:`fixmenudimstate` method sets the correct dimming
for all menu items based on the current front window.
.. function:: Separator(menu)
Add a separator to the end of a menu.
.. function:: SubMenu(menu, label)
Create a submenu named *label* under menu *menu*. The menu object is returned.
.. function:: Window(parent)
Creates a (modeless) window. *Parent* is the application object to which the
window belongs. The window is not displayed until later.
.. function:: DialogWindow(parent)
Creates a modeless dialog window.
.. function:: windowbounds(width, height)
Return a ``(left, top, right, bottom)`` tuple suitable for creation of a window
of given width and height. The window will be staggered with respect to previous
windows, and an attempt is made to keep the whole window on-screen. However, the
window will however always be the exact size given, so parts may be offscreen.
.. function:: setwatchcursor()
Set the mouse cursor to a watch.
.. function:: setarrowcursor()
Set the mouse cursor to an arrow.
.. _application-objects:
Application Objects
-------------------
Application objects have the following methods, among others:
.. method:: Application.makeusermenus()
Override this method if you need menus in your application. Append the menus to
the attribute :attr:`menubar`.
.. method:: Application.getabouttext()
Override this method to return a text string describing your application.
Alternatively, override the :meth:`do_about` method for more elaborate "about"
messages.
.. method:: Application.mainloop([mask[, wait]])
This routine is the main event loop, call it to set your application rolling.
*Mask* is the mask of events you want to handle, *wait* is the number of ticks
you want to leave to other concurrent application (default 0, which is probably
not a good idea). While raising *self* to exit the mainloop is still supported
it is not recommended: call ``self._quit()`` instead.
The event loop is split into many small parts, each of which can be overridden.
The default methods take care of dispatching events to windows and dialogs,
handling drags and resizes, Apple Events, events for non-FrameWork windows, etc.
In general, all event handlers should return ``1`` if the event is fully handled
and ``0`` otherwise (because the front window was not a FrameWork window, for
instance). This is needed so that update events and such can be passed on to
other windows like the Sioux console window. Calling :func:`MacOS.HandleEvent`
is not allowed within *our_dispatch* or its callees, since this may result in an
infinite loop if the code is called through the Python inner-loop event handler.
.. method:: Application.asyncevents(onoff)
Call this method with a nonzero parameter to enable asynchronous event handling.
This will tell the inner interpreter loop to call the application event handler
*async_dispatch* whenever events are available. This will cause FrameWork window
updates and the user interface to remain working during long computations, but
will slow the interpreter down and may cause surprising results in non-reentrant
code (such as FrameWork itself). By default *async_dispatch* will immediately
call *our_dispatch* but you may override this to handle only certain events
asynchronously. Events you do not handle will be passed to Sioux and such.
The old on/off value is returned.
.. method:: Application._quit()
Terminate the running :meth:`mainloop` call at the next convenient moment.
.. method:: Application.do_char(c, event)
The user typed character *c*. The complete details of the event can be found in
the *event* structure. This method can also be provided in a ``Window`` object,
which overrides the application-wide handler if the window is frontmost.
.. method:: Application.do_dialogevent(event)
Called early in the event loop to handle modeless dialog events. The default
method simply dispatches the event to the relevant dialog (not through the
``DialogWindow`` object involved). Override if you need special handling of
dialog events (keyboard shortcuts, etc).
.. method:: Application.idle(event)
Called by the main event loop when no events are available. The null-event is
passed (so you can look at mouse position, etc).
.. _window-objects:
Window Objects
--------------
Window objects have the following methods, among others:
.. method:: Window.open()
Override this method to open a window. Store the Mac OS window-id in
:attr:`self.wid` and call the :meth:`do_postopen` method to register the window
with the parent application.
.. method:: Window.close()
Override this method to do any special processing on window close. Call the
:meth:`do_postclose` method to cleanup the parent state.
.. method:: Window.do_postresize(width, height, macoswindowid)
Called after the window is resized. Override if more needs to be done than
calling ``InvalRect``.
.. method:: Window.do_contentclick(local, modifiers, event)
The user clicked in the content part of a window. The arguments are the
coordinates (window-relative), the key modifiers and the raw event.
.. method:: Window.do_update(macoswindowid, event)
An update event for the window was received. Redraw the window.
.. method:: Window.do_activate(activate, event)
The window was activated (``activate == 1``) or deactivated (``activate == 0``).
Handle things like focus highlighting, etc.
.. _controlswindow-object:
ControlsWindow Object
---------------------
ControlsWindow objects have the following methods besides those of ``Window``
objects:
.. method:: ControlsWindow.do_controlhit(window, control, pcode, event)
Part *pcode* of control *control* was hit by the user. Tracking and such has
already been taken care of.
.. _scrolledwindow-object:
ScrolledWindow Object
---------------------
ScrolledWindow objects are ControlsWindow objects with the following extra
methods:
.. method:: ScrolledWindow.scrollbars([wantx[, wanty]])
Create (or destroy) horizontal and vertical scrollbars. The arguments specify
which you want (default: both). The scrollbars always have minimum ``0`` and
maximum ``32767``.
.. method:: ScrolledWindow.getscrollbarvalues()
You must supply this method. It should return a tuple ``(x, y)`` giving the
current position of the scrollbars (between ``0`` and ``32767``). You can return
``None`` for either to indicate the whole document is visible in that direction.
.. method:: ScrolledWindow.updatescrollbars()
Call this method when the document has changed. It will call
:meth:`getscrollbarvalues` and update the scrollbars.
.. method:: ScrolledWindow.scrollbar_callback(which, what, value)
Supplied by you and called after user interaction. *which* will be ``'x'`` or
``'y'``, *what* will be ``'-'``, ``'--'``, ``'set'``, ``'++'`` or ``'+'``. For
``'set'``, *value* will contain the new scrollbar position.
.. method:: ScrolledWindow.scalebarvalues(absmin, absmax, curmin, curmax)
Auxiliary method to help you calculate values to return from
:meth:`getscrollbarvalues`. You pass document minimum and maximum value and
topmost (leftmost) and bottommost (rightmost) visible values and it returns the
correct number or ``None``.
.. method:: ScrolledWindow.do_activate(onoff, event)
Takes care of dimming/highlighting scrollbars when a window becomes frontmost.
If you override this method, call this one at the end of your method.
.. method:: ScrolledWindow.do_postresize(width, height, window)
Moves scrollbars to the correct position. Call this method initially if you
override it.
.. method:: ScrolledWindow.do_controlhit(window, control, pcode, event)
Handles scrollbar interaction. If you override it call this method first, a
nonzero return value indicates the hit was in the scrollbars and has been
handled.
.. _dialogwindow-objects:
DialogWindow Objects
--------------------
DialogWindow objects have the following methods besides those of ``Window``
objects:
.. method:: DialogWindow.open(resid)
Create the dialog window, from the DLOG resource with id *resid*. The dialog
object is stored in :attr:`self.wid`.
.. method:: DialogWindow.do_itemhit(item, event)
Item number *item* was hit. You are responsible for redrawing toggle buttons,
etc.
PK %�\n�sz z ( html/_sources/library/frameworks.rst.txtnu �[���
.. _frameworks:
******************
Program Frameworks
******************
The modules described in this chapter are frameworks that will largely dictate
the structure of your program. Currently the modules described here are all
oriented toward writing command-line interfaces.
The full list of modules described in this chapter is:
.. toctree::
cmd.rst
shlex.rst
PK %�\��h= h= $ html/_sources/library/ftplib.rst.txtnu �[��� :mod:`ftplib` --- FTP protocol client
=====================================
.. module:: ftplib
:synopsis: FTP protocol client (requires sockets).
.. index::
pair: FTP; protocol
single: FTP; ftplib (standard module)
**Source code:** :source:`Lib/ftplib.py`
--------------
This module defines the class :class:`FTP` and a few related items. The
:class:`FTP` class implements the client side of the FTP protocol. You can use
this to write Python programs that perform a variety of automated FTP jobs, such
as mirroring other FTP servers. It is also used by the module :mod:`urllib` to
handle URLs that use FTP. For more information on FTP (File Transfer Protocol),
see Internet :rfc:`959`.
Here's a sample session using the :mod:`ftplib` module::
>>> from ftplib import FTP
>>> ftp = FTP('ftp.debian.org') # connect to host, default port
>>> ftp.login() # user anonymous, passwd anonymous@
'230 Login successful.'
>>> ftp.cwd('debian') # change into "debian" directory
>>> ftp.retrlines('LIST') # list directory contents
-rw-rw-r-- 1 1176 1176 1063 Jun 15 10:18 README
...
drwxr-sr-x 5 1176 1176 4096 Dec 19 2000 pool
drwxr-sr-x 4 1176 1176 4096 Nov 17 2008 project
drwxr-xr-x 3 1176 1176 4096 Oct 10 2012 tools
'226 Directory send OK.'
>>> ftp.retrbinary('RETR README', open('README', 'wb').write)
'226 Transfer complete.'
>>> ftp.quit()
The module defines the following items:
.. class:: FTP([host[, user[, passwd[, acct[, timeout]]]]])
Return a new instance of the :class:`FTP` class. When *host* is given, the
method call ``connect(host)`` is made. When *user* is given, additionally
the method call ``login(user, passwd, acct)`` is made (where *passwd* and
*acct* default to the empty string when not given). The optional *timeout*
parameter specifies a timeout in seconds for blocking operations like the
connection attempt (if is not specified, the global default timeout setting
will be used).
.. versionchanged:: 2.6
*timeout* was added.
.. class:: FTP_TLS([host[, user[, passwd[, acct[, keyfile[, certfile[, context[, timeout]]]]]]]])
A :class:`FTP` subclass which adds TLS support to FTP as described in
:rfc:`4217`.
Connect as usual to port 21 implicitly securing the FTP control connection
before authenticating. Securing the data connection requires the user to
explicitly ask for it by calling the :meth:`prot_p` method. *context*
is a :class:`ssl.SSLContext` object which allows bundling SSL configuration
options, certificates and private keys into a single (potentially
long-lived) structure. Please read :ref:`ssl-security` for best practices.
*keyfile* and *certfile* are a legacy alternative to *context* -- they
can point to PEM-formatted private key and certificate chain files
(respectively) for the SSL connection.
.. versionadded:: 2.7
.. versionchanged:: 2.7.10
The *context* parameter was added.
Here's a sample session using the :class:`FTP_TLS` class:
>>> from ftplib import FTP_TLS
>>> ftps = FTP_TLS('ftp.python.org')
>>> ftps.login() # login anonymously before securing control channel
>>> ftps.prot_p() # switch to secure data connection
>>> ftps.retrlines('LIST') # list directory content securely
total 9
drwxr-xr-x 8 root wheel 1024 Jan 3 1994 .
drwxr-xr-x 8 root wheel 1024 Jan 3 1994 ..
drwxr-xr-x 2 root wheel 1024 Jan 3 1994 bin
drwxr-xr-x 2 root wheel 1024 Jan 3 1994 etc
d-wxrwxr-x 2 ftp wheel 1024 Sep 5 13:43 incoming
drwxr-xr-x 2 root wheel 1024 Nov 17 1993 lib
drwxr-xr-x 6 1094 wheel 1024 Sep 13 19:07 pub
drwxr-xr-x 3 root wheel 1024 Jan 3 1994 usr
-rw-r--r-- 1 root root 312 Aug 1 1994 welcome.msg
'226 Transfer complete.'
>>> ftps.quit()
>>>
.. exception:: error_reply
Exception raised when an unexpected reply is received from the server.
.. exception:: error_temp
Exception raised when an error code signifying a temporary error (response
codes in the range 400--499) is received.
.. exception:: error_perm
Exception raised when an error code signifying a permanent error (response
codes in the range 500--599) is received.
.. exception:: error_proto
Exception raised when a reply is received from the server that does not fit
the response specifications of the File Transfer Protocol, i.e. begin with a
digit in the range 1--5.
.. data:: all_errors
The set of all exceptions (as a tuple) that methods of :class:`FTP`
instances may raise as a result of problems with the FTP connection (as
opposed to programming errors made by the caller). This set includes the
four exceptions listed above as well as :exc:`socket.error` and
:exc:`IOError`.
.. seealso::
Module :mod:`netrc`
Parser for the :file:`.netrc` file format. The file :file:`.netrc` is
typically used by FTP clients to load user authentication information
before prompting the user.
.. index:: single: ftpmirror.py
The file :file:`Tools/scripts/ftpmirror.py` in the Python source distribution is
a script that can mirror FTP sites, or portions thereof, using the :mod:`ftplib`
module. It can be used as an extended example that applies this module.
.. _ftp-objects:
FTP Objects
-----------
Several methods are available in two flavors: one for handling text files and
another for binary files. These are named for the command which is used
followed by ``lines`` for the text version or ``binary`` for the binary version.
:class:`FTP` instances have the following methods:
.. method:: FTP.set_debuglevel(level)
Set the instance's debugging level. This controls the amount of debugging
output printed. The default, ``0``, produces no debugging output. A value of
``1`` produces a moderate amount of debugging output, generally a single line
per request. A value of ``2`` or higher produces the maximum amount of
debugging output, logging each line sent and received on the control connection.
.. method:: FTP.connect(host[, port[, timeout]])
Connect to the given host and port. The default port number is ``21``, as
specified by the FTP protocol specification. It is rarely needed to specify a
different port number. This function should be called only once for each
instance; it should not be called at all if a host was given when the instance
was created. All other methods can only be used after a connection has been
made.
The optional *timeout* parameter specifies a timeout in seconds for the
connection attempt. If no *timeout* is passed, the global default timeout
setting will be used.
.. versionchanged:: 2.6
*timeout* was added.
.. method:: FTP.getwelcome()
Return the welcome message sent by the server in reply to the initial
connection. (This message sometimes contains disclaimers or help information
that may be relevant to the user.)
.. method:: FTP.login([user[, passwd[, acct]]])
Log in as the given *user*. The *passwd* and *acct* parameters are optional and
default to the empty string. If no *user* is specified, it defaults to
``'anonymous'``. If *user* is ``'anonymous'``, the default *passwd* is
``'anonymous@'``. This function should be called only once for each instance,
after a connection has been established; it should not be called at all if a
host and user were given when the instance was created. Most FTP commands are
only allowed after the client has logged in. The *acct* parameter supplies
"accounting information"; few systems implement this.
.. method:: FTP.abort()
Abort a file transfer that is in progress. Using this does not always work, but
it's worth a try.
.. method:: FTP.sendcmd(command)
Send a simple command string to the server and return the response string.
.. method:: FTP.voidcmd(command)
Send a simple command string to the server and handle the response. Return
nothing if a response code corresponding to success (codes in the range
200--299) is received. Raise :exc:`error_reply` otherwise.
.. method:: FTP.retrbinary(command, callback[, maxblocksize[, rest]])
Retrieve a file in binary transfer mode. *command* should be an appropriate
``RETR`` command: ``'RETR filename'``. The *callback* function is called for
each block of data received, with a single string argument giving the data
block. The optional *maxblocksize* argument specifies the maximum chunk size to
read on the low-level socket object created to do the actual transfer (which
will also be the largest size of the data blocks passed to *callback*). A
reasonable default is chosen. *rest* means the same thing as in the
:meth:`transfercmd` method.
.. method:: FTP.retrlines(command[, callback])
Retrieve a file or directory listing in ASCII transfer mode. *command*
should be an appropriate ``RETR`` command (see :meth:`retrbinary`) or a
command such as ``LIST``, ``NLST`` or ``MLSD`` (usually just the string
``'LIST'``). ``LIST`` retrieves a list of files and information about those files.
``NLST`` retrieves a list of file names. On some servers, ``MLSD`` retrieves
a machine readable list of files and information about those files. The *callback*
function is called for each line with a string argument containing the line with
the trailing CRLF stripped. The default *callback* prints the line to ``sys.stdout``.
.. method:: FTP.set_pasv(val)
Enable "passive" mode if *val* is true, otherwise disable passive mode. (In
Python 2.0 and before, passive mode was off by default; in Python 2.1 and later,
it is on by default.)
.. method:: FTP.storbinary(command, fp[, blocksize, callback, rest])
Store a file in binary transfer mode. *command* should be an appropriate
``STOR`` command: ``"STOR filename"``. *fp* is an open file object which is
read until EOF using its :meth:`read` method in blocks of size *blocksize* to
provide the data to be stored. The *blocksize* argument defaults to 8192.
*callback* is an optional single parameter callable that is called
on each block of data after it is sent. *rest* means the same thing as in
the :meth:`transfercmd` method.
.. versionchanged:: 2.1
default for *blocksize* added.
.. versionchanged:: 2.6
*callback* parameter added.
.. versionchanged:: 2.7
*rest* parameter added.
.. method:: FTP.storlines(command, fp[, callback])
Store a file in ASCII transfer mode. *command* should be an appropriate
``STOR`` command (see :meth:`storbinary`). Lines are read until EOF from the
open file object *fp* using its :meth:`~file.readline` method to provide
the data to be stored. *callback* is an optional single parameter callable
that is called on each line after it is sent.
.. versionchanged:: 2.6
*callback* parameter added.
.. method:: FTP.transfercmd(cmd[, rest])
Initiate a transfer over the data connection. If the transfer is active, send an
``EPRT`` or ``PORT`` command and the transfer command specified by *cmd*, and
accept the connection. If the server is passive, send an ``EPSV`` or ``PASV``
command, connect to it, and start the transfer command. Either way, return the
socket for the connection.
If optional *rest* is given, a ``REST`` command is sent to the server, passing
*rest* as an argument. *rest* is usually a byte offset into the requested file,
telling the server to restart sending the file's bytes at the requested offset,
skipping over the initial bytes. Note however that RFC 959 requires only that
*rest* be a string containing characters in the printable range from ASCII code
33 to ASCII code 126. The :meth:`transfercmd` method, therefore, converts
*rest* to a string, but no check is performed on the string's contents. If the
server does not recognize the ``REST`` command, an :exc:`error_reply` exception
will be raised. If this happens, simply call :meth:`transfercmd` without a
*rest* argument.
.. method:: FTP.ntransfercmd(cmd[, rest])
Like :meth:`transfercmd`, but returns a tuple of the data connection and the
expected size of the data. If the expected size could not be computed, ``None``
will be returned as the expected size. *cmd* and *rest* means the same thing as
in :meth:`transfercmd`.
.. method:: FTP.nlst(argument[, ...])
Return a list of file names as returned by the ``NLST`` command. The
optional *argument* is a directory to list (default is the current server
directory). Multiple arguments can be used to pass non-standard options to
the ``NLST`` command.
.. method:: FTP.dir(argument[, ...])
Produce a directory listing as returned by the ``LIST`` command, printing it to
standard output. The optional *argument* is a directory to list (default is the
current server directory). Multiple arguments can be used to pass non-standard
options to the ``LIST`` command. If the last argument is a function, it is used
as a *callback* function as for :meth:`retrlines`; the default prints to
``sys.stdout``. This method returns ``None``.
.. method:: FTP.rename(fromname, toname)
Rename file *fromname* on the server to *toname*.
.. method:: FTP.delete(filename)
Remove the file named *filename* from the server. If successful, returns the
text of the response, otherwise raises :exc:`error_perm` on permission errors or
:exc:`error_reply` on other errors.
.. method:: FTP.cwd(pathname)
Set the current directory on the server.
.. method:: FTP.mkd(pathname)
Create a new directory on the server.
.. method:: FTP.pwd()
Return the pathname of the current directory on the server.
.. method:: FTP.rmd(dirname)
Remove the directory named *dirname* on the server.
.. method:: FTP.size(filename)
Request the size of the file named *filename* on the server. On success, the
size of the file is returned as an integer, otherwise ``None`` is returned.
Note that the ``SIZE`` command is not standardized, but is supported by many
common server implementations.
.. method:: FTP.quit()
Send a ``QUIT`` command to the server and close the connection. This is the
"polite" way to close a connection, but it may raise an exception if the server
responds with an error to the ``QUIT`` command. This implies a call to the
:meth:`close` method which renders the :class:`FTP` instance useless for
subsequent calls (see below).
.. method:: FTP.close()
Close the connection unilaterally. This should not be applied to an already
closed connection such as after a successful call to :meth:`~FTP.quit`.
After this call the :class:`FTP` instance should not be used any more (after
a call to :meth:`close` or :meth:`~FTP.quit` you cannot reopen the
connection by issuing another :meth:`login` method).
FTP_TLS Objects
---------------
:class:`FTP_TLS` class inherits from :class:`FTP`, defining these additional objects:
.. attribute:: FTP_TLS.ssl_version
The SSL version to use (defaults to :attr:`ssl.PROTOCOL_SSLv23`).
.. method:: FTP_TLS.auth()
Set up secure control connection by using TLS or SSL, depending on what
specified in :meth:`ssl_version` attribute.
.. method:: FTP_TLS.prot_p()
Set up secure data connection.
.. method:: FTP_TLS.prot_c()
Set up clear text data connection.
PK %�\��"' "' ' html/_sources/library/functions.rst.txtnu �[���
.. _built-in-funcs:
Built-in Functions
==================
The Python interpreter has a number of functions built into it that are always
available. They are listed here in alphabetical order.
=================== ================= ================== ================= ====================
.. .. Built-in Functions .. ..
=================== ================= ================== ================= ====================
:func:`abs` :func:`divmod` :func:`input` :func:`open` :func:`staticmethod`
:func:`all` :func:`enumerate` :func:`int` :func:`ord` :func:`str`
:func:`any` :func:`eval` :func:`isinstance` :func:`pow` :func:`sum`
:func:`basestring` :func:`execfile` :func:`issubclass` :func:`print` :func:`super`
:func:`bin` :func:`file` :func:`iter` :func:`property` :func:`tuple`
:func:`bool` :func:`filter` :func:`len` :func:`range` :func:`type`
:func:`bytearray` :func:`float` |func-list|_ :func:`raw_input` :func:`unichr`
:func:`callable` :func:`format` :func:`locals` :func:`reduce` :func:`unicode`
:func:`chr` |func-frozenset|_ :func:`long` :func:`reload` :func:`vars`
:func:`classmethod` :func:`getattr` :func:`map` |func-repr|_ :func:`xrange`
:func:`cmp` :func:`globals` :func:`max` :func:`reversed` :func:`zip`
:func:`compile` :func:`hasattr` |func-memoryview|_ :func:`round` :func:`__import__`
:func:`complex` :func:`hash` :func:`min` |func-set|_ ..
:func:`delattr` :func:`help` :func:`next` :func:`setattr` ..
|func-dict|_ :func:`hex` :func:`object` :func:`slice` ..
:func:`dir` :func:`id` :func:`oct` :func:`sorted` ..
=================== ================= ================== ================= ====================
In addition, there are other four built-in functions that are no longer
considered essential: :func:`apply`, :func:`buffer`, :func:`coerce`, and
:func:`intern`. They are documented in the :ref:`non-essential-built-in-funcs`
section.
.. using :func:`dict` would create a link to another page, so local targets are
used, with replacement texts to make the output in the table consistent
.. |func-dict| replace:: ``dict()``
.. |func-frozenset| replace:: ``frozenset()``
.. |func-list| replace:: ``list()``
.. |func-memoryview| replace:: ``memoryview()``
.. |func-repr| replace:: ``repr()``
.. |func-set| replace:: ``set()``
.. function:: abs(x)
Return the absolute value of a number. The argument may be a plain or long
integer or a floating point number. If the argument is a complex number, its
magnitude is returned.
.. function:: all(iterable)
Return ``True`` if all elements of the *iterable* are true (or if the iterable
is empty). Equivalent to::
def all(iterable):
for element in iterable:
if not element:
return False
return True
.. versionadded:: 2.5
.. function:: any(iterable)
Return ``True`` if any element of the *iterable* is true. If the iterable
is empty, return ``False``. Equivalent to::
def any(iterable):
for element in iterable:
if element:
return True
return False
.. versionadded:: 2.5
.. function:: basestring()
This abstract type is the superclass for :class:`str` and :class:`unicode`. It
cannot be called or instantiated, but it can be used to test whether an object
is an instance of :class:`str` or :class:`unicode`. ``isinstance(obj,
basestring)`` is equivalent to ``isinstance(obj, (str, unicode))``.
.. versionadded:: 2.3
.. function:: bin(x)
Convert an integer number to a binary string. The result is a valid Python
expression. If *x* is not a Python :class:`int` object, it has to define an
:meth:`__index__` method that returns an integer.
.. versionadded:: 2.6
.. class:: bool([x])
Return a Boolean value, i.e. one of ``True`` or ``False``. *x* is converted
using the standard truth testing procedure. If *x* is false or omitted, this
returns :const:`False`; otherwise it returns :const:`True`. :class:`bool` is
also a class, which is a subclass of :class:`int`. Class :class:`bool` cannot
be subclassed further. Its only instances are :const:`False` and
:const:`True`.
.. index:: pair: Boolean; type
.. versionadded:: 2.2.1
.. versionchanged:: 2.3
If no argument is given, this function returns :const:`False`.
.. class:: bytearray([source[, encoding[, errors]]])
Return a new array of bytes. The :class:`bytearray` class is a mutable
sequence of integers in the range 0 <= x < 256. It has most of the usual
methods of mutable sequences, described in :ref:`typesseq-mutable`, as well
as most methods that the :class:`str` type has, see :ref:`string-methods`.
The optional *source* parameter can be used to initialize the array in a few
different ways:
* If it is *unicode*, you must also give the *encoding* (and optionally,
*errors*) parameters; :func:`bytearray` then converts the unicode to
bytes using :meth:`unicode.encode`.
* If it is an *integer*, the array will have that size and will be
initialized with null bytes.
* If it is an object conforming to the *buffer* interface, a read-only buffer
of the object will be used to initialize the bytes array.
* If it is an *iterable*, it must be an iterable of integers in the range
``0 <= x < 256``, which are used as the initial contents of the array.
Without an argument, an array of size 0 is created.
.. versionadded:: 2.6
.. function:: callable(object)
Return :const:`True` if the *object* argument appears callable,
:const:`False` if not. If this
returns true, it is still possible that a call fails, but if it is false,
calling *object* will never succeed. Note that classes are callable (calling a
class returns a new instance); class instances are callable if they have a
:meth:`__call__` method.
.. function:: chr(i)
Return a string of one character whose ASCII code is the integer *i*. For
example, ``chr(97)`` returns the string ``'a'``. This is the inverse of
:func:`ord`. The argument must be in the range [0..255], inclusive;
:exc:`ValueError` will be raised if *i* is outside that range. See
also :func:`unichr`.
.. function:: classmethod(function)
Return a class method for *function*.
A class method receives the class as implicit first argument, just like an
instance method receives the instance. To declare a class method, use this
idiom::
class C(object):
@classmethod
def f(cls, arg1, arg2, ...):
...
The ``@classmethod`` form is a function :term:`decorator` -- see the description
of function definitions in :ref:`function` for details.
It can be called either on the class (such as ``C.f()``) or on an instance (such
as ``C().f()``). The instance is ignored except for its class. If a class
method is called for a derived class, the derived class object is passed as the
implied first argument.
Class methods are different than C++ or Java static methods. If you want those,
see :func:`staticmethod` in this section.
For more information on class methods, consult the documentation on the standard
type hierarchy in :ref:`types`.
.. versionadded:: 2.2
.. versionchanged:: 2.4
Function decorator syntax added.
.. function:: cmp(x, y)
Compare the two objects *x* and *y* and return an integer according to the
outcome. The return value is negative if ``x < y``, zero if ``x == y`` and
strictly positive if ``x > y``.
.. function:: compile(source, filename, mode[, flags[, dont_inherit]])
Compile the *source* into a code or AST object. Code objects can be executed
by an :keyword:`exec` statement or evaluated by a call to :func:`eval`.
*source* can either be a Unicode string, a *Latin-1* encoded string or an
AST object.
Refer to the :mod:`ast` module documentation for information on how to work
with AST objects.
The *filename* argument should give the file from which the code was read;
pass some recognizable value if it wasn't read from a file (``'<string>'`` is
commonly used).
The *mode* argument specifies what kind of code must be compiled; it can be
``'exec'`` if *source* consists of a sequence of statements, ``'eval'`` if it
consists of a single expression, or ``'single'`` if it consists of a single
interactive statement (in the latter case, expression statements that
evaluate to something other than ``None`` will be printed).
The optional arguments *flags* and *dont_inherit* control which future
statements (see :pep:`236`) affect the compilation of *source*. If neither
is present (or both are zero) the code is compiled with those future
statements that are in effect in the code that is calling :func:`compile`. If the
*flags* argument is given and *dont_inherit* is not (or is zero) then the
future statements specified by the *flags* argument are used in addition to
those that would be used anyway. If *dont_inherit* is a non-zero integer then
the *flags* argument is it -- the future statements in effect around the call
to compile are ignored.
Future statements are specified by bits which can be bitwise ORed together to
specify multiple statements. The bitfield required to specify a given feature
can be found as the :attr:`~__future__._Feature.compiler_flag` attribute on
the :class:`~__future__._Feature` instance in the :mod:`__future__` module.
This function raises :exc:`SyntaxError` if the compiled source is invalid,
and :exc:`TypeError` if the source contains null bytes.
If you want to parse Python code into its AST representation, see
:func:`ast.parse`.
.. note::
When compiling a string with multi-line code in ``'single'`` or
``'eval'`` mode, input must be terminated by at least one newline
character. This is to facilitate detection of incomplete and complete
statements in the :mod:`code` module.
.. versionchanged:: 2.3
The *flags* and *dont_inherit* arguments were added.
.. versionchanged:: 2.6
Support for compiling AST objects.
.. versionchanged:: 2.7
Allowed use of Windows and Mac newlines. Also input in ``'exec'`` mode
does not have to end in a newline anymore.
.. class:: complex([real[, imag]])
Return a complex number with the value *real* + *imag*\*1j or convert a string or
number to a complex number. If the first parameter is a string, it will be
interpreted as a complex number and the function must be called without a second
parameter. The second parameter can never be a string. Each argument may be any
numeric type (including complex). If *imag* is omitted, it defaults to zero and
the function serves as a numeric conversion function like :func:`int`,
:func:`long` and :func:`float`. If both arguments are omitted, returns ``0j``.
.. note::
When converting from a string, the string must not contain whitespace
around the central ``+`` or ``-`` operator. For example,
``complex('1+2j')`` is fine, but ``complex('1 + 2j')`` raises
:exc:`ValueError`.
The complex type is described in :ref:`typesnumeric`.
.. function:: delattr(object, name)
This is a relative of :func:`setattr`. The arguments are an object and a
string. The string must be the name of one of the object's attributes. The
function deletes the named attribute, provided the object allows it. For
example, ``delattr(x, 'foobar')`` is equivalent to ``del x.foobar``.
.. _func-dict:
.. class:: dict(**kwarg)
dict(mapping, **kwarg)
dict(iterable, **kwarg)
:noindex:
Create a new dictionary. The :class:`dict` object is the dictionary class.
See :class:`dict` and :ref:`typesmapping` for documentation about this class.
For other containers see the built-in :class:`list`, :class:`set`, and
:class:`tuple` classes, as well as the :mod:`collections` module.
.. function:: dir([object])
Without arguments, return the list of names in the current local scope. With an
argument, attempt to return a list of valid attributes for that object.
If the object has a method named :meth:`__dir__`, this method will be called and
must return the list of attributes. This allows objects that implement a custom
:func:`__getattr__` or :func:`__getattribute__` function to customize the way
:func:`dir` reports their attributes.
If the object does not provide :meth:`__dir__`, the function tries its best to
gather information from the object's :attr:`~object.__dict__` attribute, if defined, and
from its type object. The resulting list is not necessarily complete, and may
be inaccurate when the object has a custom :func:`__getattr__`.
The default :func:`dir` mechanism behaves differently with different types of
objects, as it attempts to produce the most relevant, rather than complete,
information:
* If the object is a module object, the list contains the names of the module's
attributes.
* If the object is a type or class object, the list contains the names of its
attributes, and recursively of the attributes of its bases.
* Otherwise, the list contains the object's attributes' names, the names of its
class's attributes, and recursively of the attributes of its class's base
classes.
The resulting list is sorted alphabetically. For example:
>>> import struct
>>> dir() # show the names in the module namespace
['__builtins__', '__doc__', '__name__', 'struct']
>>> dir(struct) # show the names in the struct module
['Struct', '__builtins__', '__doc__', '__file__', '__name__',
'__package__', '_clearcache', 'calcsize', 'error', 'pack', 'pack_into',
'unpack', 'unpack_from']
>>> class Shape(object):
def __dir__(self):
return ['area', 'perimeter', 'location']
>>> s = Shape()
>>> dir(s)
['area', 'perimeter', 'location']
.. note::
Because :func:`dir` is supplied primarily as a convenience for use at an
interactive prompt, it tries to supply an interesting set of names more than it
tries to supply a rigorously or consistently defined set of names, and its
detailed behavior may change across releases. For example, metaclass attributes
are not in the result list when the argument is a class.
.. function:: divmod(a, b)
Take two (non complex) numbers as arguments and return a pair of numbers
consisting of their quotient and remainder when using long division. With mixed
operand types, the rules for binary arithmetic operators apply. For plain and
long integers, the result is the same as ``(a // b, a % b)``. For floating point
numbers the result is ``(q, a % b)``, where *q* is usually ``math.floor(a / b)``
but may be 1 less than that. In any case ``q * b + a % b`` is very close to
*a*, if ``a % b`` is non-zero it has the same sign as *b*, and ``0 <= abs(a % b)
< abs(b)``.
.. versionchanged:: 2.3
Using :func:`divmod` with complex numbers is deprecated.
.. function:: enumerate(sequence, start=0)
Return an enumerate object. *sequence* must be a sequence, an
:term:`iterator`, or some other object which supports iteration. The
:meth:`!next` method of the iterator returned by :func:`enumerate` returns a
tuple containing a count (from *start* which defaults to 0) and the
values obtained from iterating over *sequence*::
>>> seasons = ['Spring', 'Summer', 'Fall', 'Winter']
>>> list(enumerate(seasons))
[(0, 'Spring'), (1, 'Summer'), (2, 'Fall'), (3, 'Winter')]
>>> list(enumerate(seasons, start=1))
[(1, 'Spring'), (2, 'Summer'), (3, 'Fall'), (4, 'Winter')]
Equivalent to::
def enumerate(sequence, start=0):
n = start
for elem in sequence:
yield n, elem
n += 1
.. versionadded:: 2.3
.. versionchanged:: 2.6
The *start* parameter was added.
.. function:: eval(expression[, globals[, locals]])
The arguments are a Unicode or *Latin-1* encoded string and optional
globals and locals. If provided, *globals* must be a dictionary.
If provided, *locals* can be any mapping object.
.. versionchanged:: 2.4
formerly *locals* was required to be a dictionary.
The *expression* argument is parsed and evaluated as a Python expression
(technically speaking, a condition list) using the *globals* and *locals*
dictionaries as global and local namespace. If the *globals* dictionary is
present and lacks '__builtins__', the current globals are copied into *globals*
before *expression* is parsed. This means that *expression* normally has full
access to the standard :mod:`__builtin__` module and restricted environments are
propagated. If the *locals* dictionary is omitted it defaults to the *globals*
dictionary. If both dictionaries are omitted, the expression is executed in the
environment where :func:`eval` is called. The return value is the result of
the evaluated expression. Syntax errors are reported as exceptions. Example:
>>> x = 1
>>> print eval('x+1')
2
This function can also be used to execute arbitrary code objects (such as
those created by :func:`compile`). In this case pass a code object instead
of a string. If the code object has been compiled with ``'exec'`` as the
*mode* argument, :func:`eval`\'s return value will be ``None``.
Hints: dynamic execution of statements is supported by the :keyword:`exec`
statement. Execution of statements from a file is supported by the
:func:`execfile` function. The :func:`globals` and :func:`locals` functions
returns the current global and local dictionary, respectively, which may be
useful to pass around for use by :func:`eval` or :func:`execfile`.
See :func:`ast.literal_eval` for a function that can safely evaluate strings
with expressions containing only literals.
.. function:: execfile(filename[, globals[, locals]])
This function is similar to the :keyword:`exec` statement, but parses a file
instead of a string. It is different from the :keyword:`import` statement in
that it does not use the module administration --- it reads the file
unconditionally and does not create a new module. [#]_
The arguments are a file name and two optional dictionaries. The file is parsed
and evaluated as a sequence of Python statements (similarly to a module) using
the *globals* and *locals* dictionaries as global and local namespace. If
provided, *locals* can be any mapping object. Remember that at module level,
globals and locals are the same dictionary. If two separate objects are
passed as *globals* and *locals*, the code will be executed as if it were
embedded in a class definition.
.. versionchanged:: 2.4
formerly *locals* was required to be a dictionary.
If the *locals* dictionary is omitted it defaults to the *globals* dictionary.
If both dictionaries are omitted, the expression is executed in the environment
where :func:`execfile` is called. The return value is ``None``.
.. note::
The default *locals* act as described for function :func:`locals` below:
modifications to the default *locals* dictionary should not be attempted. Pass
an explicit *locals* dictionary if you need to see effects of the code on
*locals* after function :func:`execfile` returns. :func:`execfile` cannot be
used reliably to modify a function's locals.
.. function:: file(name[, mode[, buffering]])
Constructor function for the :class:`file` type, described further in section
:ref:`bltin-file-objects`. The constructor's arguments are the same as those
of the :func:`open` built-in function described below.
When opening a file, it's preferable to use :func:`open` instead of invoking
this constructor directly. :class:`file` is more suited to type testing (for
example, writing ``isinstance(f, file)``).
.. versionadded:: 2.2
.. function:: filter(function, iterable)
Construct a list from those elements of *iterable* for which *function* returns
true. *iterable* may be either a sequence, a container which supports
iteration, or an iterator. If *iterable* is a string or a tuple, the result
also has that type; otherwise it is always a list. If *function* is ``None``,
the identity function is assumed, that is, all elements of *iterable* that are
false are removed.
Note that ``filter(function, iterable)`` is equivalent to ``[item for item in
iterable if function(item)]`` if function is not ``None`` and ``[item for item
in iterable if item]`` if function is ``None``.
See :func:`itertools.ifilter` and :func:`itertools.ifilterfalse` for iterator
versions of this function, including a variation that filters for elements
where the *function* returns false.
.. class:: float([x])
Return a floating point number constructed from a number or string *x*.
If the argument is a string, it
must contain a possibly signed decimal or floating point number, possibly
embedded in whitespace. The argument may also be [+|-]nan or [+|-]inf.
Otherwise, the argument may be a plain or long integer
or a floating point number, and a floating point number with the same value
(within Python's floating point precision) is returned. If no argument is
given, returns ``0.0``.
.. note::
.. index::
single: NaN
single: Infinity
When passing in a string, values for NaN and Infinity may be returned, depending
on the underlying C library. Float accepts the strings nan, inf and -inf for
NaN and positive or negative infinity. The case and a leading + are ignored as
well as a leading - is ignored for NaN. Float always represents NaN and infinity
as nan, inf or -inf.
The float type is described in :ref:`typesnumeric`.
.. function:: format(value[, format_spec])
.. index::
pair: str; format
single: __format__
Convert a *value* to a "formatted" representation, as controlled by
*format_spec*. The interpretation of *format_spec* will depend on the type
of the *value* argument, however there is a standard formatting syntax that
is used by most built-in types: :ref:`formatspec`.
.. note::
``format(value, format_spec)`` merely calls
``value.__format__(format_spec)``.
.. versionadded:: 2.6
.. _func-frozenset:
.. class:: frozenset([iterable])
:noindex:
Return a new :class:`frozenset` object, optionally with elements taken from
*iterable*. ``frozenset`` is a built-in class. See :class:`frozenset` and
:ref:`types-set` for documentation about this class.
For other containers see the built-in :class:`set`, :class:`list`,
:class:`tuple`, and :class:`dict` classes, as well as the :mod:`collections`
module.
.. versionadded:: 2.4
.. function:: getattr(object, name[, default])
Return the value of the named attribute of *object*. *name* must be a string.
If the string is the name of one of the object's attributes, the result is the
value of that attribute. For example, ``getattr(x, 'foobar')`` is equivalent to
``x.foobar``. If the named attribute does not exist, *default* is returned if
provided, otherwise :exc:`AttributeError` is raised.
.. function:: globals()
Return a dictionary representing the current global symbol table. This is always
the dictionary of the current module (inside a function or method, this is the
module where it is defined, not the module from which it is called).
.. function:: hasattr(object, name)
The arguments are an object and a string. The result is ``True`` if the string
is the name of one of the object's attributes, ``False`` if not. (This is
implemented by calling ``getattr(object, name)`` and seeing whether it raises an
exception or not.)
.. function:: hash(object)
Return the hash value of the object (if it has one). Hash values are integers.
They are used to quickly compare dictionary keys during a dictionary lookup.
Numeric values that compare equal have the same hash value (even if they are of
different types, as is the case for 1 and 1.0).
.. function:: help([object])
Invoke the built-in help system. (This function is intended for interactive
use.) If no argument is given, the interactive help system starts on the
interpreter console. If the argument is a string, then the string is looked up
as the name of a module, function, class, method, keyword, or documentation
topic, and a help page is printed on the console. If the argument is any other
kind of object, a help page on the object is generated.
This function is added to the built-in namespace by the :mod:`site` module.
.. versionadded:: 2.2
.. function:: hex(x)
Convert an integer number (of any size) to a lowercase hexadecimal string
prefixed with "0x", for example:
>>> hex(255)
'0xff'
>>> hex(-42)
'-0x2a'
>>> hex(1L)
'0x1L'
If x is not a Python :class:`int` or :class:`long` object, it has to
define a __hex__() method that returns a string.
See also :func:`int` for converting a hexadecimal string to an
integer using a base of 16.
.. note::
To obtain a hexadecimal string representation for a float, use the
:meth:`float.hex` method.
.. versionchanged:: 2.4
Formerly only returned an unsigned literal.
.. function:: id(object)
Return the "identity" of an object. This is an integer (or long integer) which
is guaranteed to be unique and constant for this object during its lifetime.
Two objects with non-overlapping lifetimes may have the same :func:`id`
value.
.. impl-detail:: This is the address of the object in memory.
.. function:: input([prompt])
Equivalent to ``eval(raw_input(prompt))``.
This function does not catch user errors. If the input is not syntactically
valid, a :exc:`SyntaxError` will be raised. Other exceptions may be raised if
there is an error during evaluation.
If the :mod:`readline` module was loaded, then :func:`input` will use it to
provide elaborate line editing and history features.
Consider using the :func:`raw_input` function for general input from users.
.. class:: int(x=0)
int(x, base=10)
Return an integer object constructed from a number or string *x*, or return ``0`` if no
arguments are given. If *x* is a number, it can be a plain integer, a long
integer, or a floating point number. If *x* is floating point, the conversion
truncates towards zero. If the argument is outside the integer range, the
function returns a long object instead.
If *x* is not a number or if *base* is given, then *x* must be a string or
Unicode object representing an :ref:`integer literal <integers>` in radix
*base*. Optionally, the literal can be
preceded by ``+`` or ``-`` (with no space in between) and surrounded by
whitespace. A base-n literal consists of the digits 0 to n-1, with ``a``
to ``z`` (or ``A`` to ``Z``) having
values 10 to 35. The default *base* is 10. The allowed values are 0 and 2--36.
Base-2, -8, and -16 literals can be optionally prefixed with ``0b``/``0B``,
``0o``/``0O``/``0``, or ``0x``/``0X``, as with integer literals in code.
Base 0 means to interpret the string exactly as an integer literal, so that
the actual base is 2, 8, 10, or 16.
The integer type is described in :ref:`typesnumeric`.
.. function:: isinstance(object, classinfo)
Return true if the *object* argument is an instance of the *classinfo* argument,
or of a (direct, indirect or :term:`virtual <abstract base class>`) subclass
thereof. Also return true if *classinfo*
is a type object (new-style class) and *object* is an object of that type or of
a (direct, indirect or :term:`virtual <abstract base class>`) subclass
thereof. If *object* is not a class instance or
an object of the given type, the function always returns false.
If *classinfo* is a tuple of class or type objects (or recursively, other
such tuples), return true if *object* is an instance of any of the classes
or types. If *classinfo* is not a class, type, or tuple of classes, types,
and such tuples, a :exc:`TypeError` exception is raised.
.. versionchanged:: 2.2
Support for a tuple of type information was added.
.. function:: issubclass(class, classinfo)
Return true if *class* is a subclass (direct, indirect or :term:`virtual
<abstract base class>`) of *classinfo*. A
class is considered a subclass of itself. *classinfo* may be a tuple of class
objects, in which case every entry in *classinfo* will be checked. In any other
case, a :exc:`TypeError` exception is raised.
.. versionchanged:: 2.3
Support for a tuple of type information was added.
.. function:: iter(o[, sentinel])
Return an :term:`iterator` object. The first argument is interpreted very differently
depending on the presence of the second argument. Without a second argument, *o*
must be a collection object which supports the iteration protocol (the
:meth:`__iter__` method), or it must support the sequence protocol (the
:meth:`__getitem__` method with integer arguments starting at ``0``). If it
does not support either of those protocols, :exc:`TypeError` is raised. If the
second argument, *sentinel*, is given, then *o* must be a callable object. The
iterator created in this case will call *o* with no arguments for each call to
its :meth:`~iterator.next` method; if the value returned is equal to *sentinel*,
:exc:`StopIteration` will be raised, otherwise the value will be returned.
One useful application of the second form of :func:`iter` is to read lines of
a file until a certain line is reached. The following example reads a file
until the :meth:`~io.TextIOBase.readline` method returns an empty string::
with open('mydata.txt') as fp:
for line in iter(fp.readline, ''):
process_line(line)
.. versionadded:: 2.2
.. function:: len(s)
Return the length (the number of items) of an object. The argument may be a
sequence (such as a string, bytes, tuple, list, or range) or a collection
(such as a dictionary, set, or frozen set).
.. _func-list:
.. class:: list([iterable])
:noindex:
Return a list whose items are the same and in the same order as *iterable*'s
items. *iterable* may be either a sequence, a container that supports
iteration, or an iterator object. If *iterable* is already a list, a copy is
made and returned, similar to ``iterable[:]``. For instance, ``list('abc')``
returns ``['a', 'b', 'c']`` and ``list( (1, 2, 3) )`` returns ``[1, 2, 3]``. If
no argument is given, returns a new empty list, ``[]``.
:class:`list` is a mutable sequence type, as documented in
:ref:`typesseq`. For other containers see the built in :class:`dict`,
:class:`set`, and :class:`tuple` classes, and the :mod:`collections` module.
.. function:: locals()
Update and return a dictionary representing the current local symbol table.
Free variables are returned by :func:`locals` when it is called in function
blocks, but not in class blocks.
.. note::
The contents of this dictionary should not be modified; changes may not
affect the values of local and free variables used by the interpreter.
.. class:: long(x=0)
long(x, base=10)
Return a long integer object constructed from a string or number *x*.
If the argument is a string, it
must contain a possibly signed number of arbitrary size, possibly embedded in
whitespace. The *base* argument is interpreted in the same way as for
:func:`int`, and may only be given when *x* is a string. Otherwise, the argument
may be a plain or long integer or a floating point number, and a long integer
with the same value is returned. Conversion of floating point numbers to
integers truncates (towards zero). If no arguments are given, returns ``0L``.
The long type is described in :ref:`typesnumeric`.
.. function:: map(function, iterable, ...)
Apply *function* to every item of *iterable* and return a list of the results.
If additional *iterable* arguments are passed, *function* must take that many
arguments and is applied to the items from all iterables in parallel. If one
iterable is shorter than another it is assumed to be extended with ``None``
items. If *function* is ``None``, the identity function is assumed; if there
are multiple arguments, :func:`map` returns a list consisting of tuples
containing the corresponding items from all iterables (a kind of transpose
operation). The *iterable* arguments may be a sequence or any iterable object;
the result is always a list.
.. function:: max(iterable[, key])
max(arg1, arg2, *args[, key])
Return the largest item in an iterable or the largest of two or more
arguments.
If one positional argument is provided, *iterable* must be a non-empty
iterable (such as a non-empty string, tuple or list). The largest item
in the iterable is returned. If two or more positional arguments are
provided, the largest of the positional arguments is returned.
The optional *key* argument specifies a one-argument ordering function like that
used for :meth:`list.sort`. The *key* argument, if supplied, must be in keyword
form (for example, ``max(a,b,c,key=func)``).
.. versionchanged:: 2.5
Added support for the optional *key* argument.
.. _func-memoryview:
.. function:: memoryview(obj)
:noindex:
Return a "memory view" object created from the given argument. See
:ref:`typememoryview` for more information.
.. function:: min(iterable[, key])
min(arg1, arg2, *args[, key])
Return the smallest item in an iterable or the smallest of two or more
arguments.
If one positional argument is provided, *iterable* must be a non-empty
iterable (such as a non-empty string, tuple or list). The smallest item
in the iterable is returned. If two or more positional arguments are
provided, the smallest of the positional arguments is returned.
The optional *key* argument specifies a one-argument ordering function like that
used for :meth:`list.sort`. The *key* argument, if supplied, must be in keyword
form (for example, ``min(a,b,c,key=func)``).
.. versionchanged:: 2.5
Added support for the optional *key* argument.
.. function:: next(iterator[, default])
Retrieve the next item from the *iterator* by calling its
:meth:`~iterator.next` method. If *default* is given, it is returned if the
iterator is exhausted, otherwise :exc:`StopIteration` is raised.
.. versionadded:: 2.6
.. class:: object()
Return a new featureless object. :class:`object` is a base for all new style
classes. It has the methods that are common to all instances of new style
classes.
.. versionadded:: 2.2
.. versionchanged:: 2.3
This function does not accept any arguments. Formerly, it accepted arguments but
ignored them.
.. function:: oct(x)
Convert an integer number (of any size) to an octal string. The result is a
valid Python expression.
.. versionchanged:: 2.4
Formerly only returned an unsigned literal.
.. function:: open(name[, mode[, buffering]])
Open a file, returning an object of the :class:`file` type described in
section :ref:`bltin-file-objects`. If the file cannot be opened,
:exc:`IOError` is raised. When opening a file, it's preferable to use
:func:`open` instead of invoking the :class:`file` constructor directly.
The first two arguments are the same as for ``stdio``'s :c:func:`fopen`:
*name* is the file name to be opened, and *mode* is a string indicating how
the file is to be opened.
The most commonly-used values of *mode* are ``'r'`` for reading, ``'w'`` for
writing (truncating the file if it already exists), and ``'a'`` for appending
(which on *some* Unix systems means that *all* writes append to the end of the
file regardless of the current seek position). If *mode* is omitted, it
defaults to ``'r'``. The default is to use text mode, which may convert
``'\n'`` characters to a platform-specific representation on writing and back
on reading. Thus, when opening a binary file, you should append ``'b'`` to
the *mode* value to open the file in binary mode, which will improve
portability. (Appending ``'b'`` is useful even on systems that don't treat
binary and text files differently, where it serves as documentation.) See below
for more possible values of *mode*.
.. index::
single: line-buffered I/O
single: unbuffered I/O
single: buffer size, I/O
single: I/O control; buffering
The optional *buffering* argument specifies the file's desired buffer size: 0
means unbuffered, 1 means line buffered, any other positive value means use a
buffer of (approximately) that size (in bytes). A negative *buffering* means
to use the system default, which is usually line buffered for tty devices and
fully buffered for other files. If omitted, the system default is used. [#]_
Modes ``'r+'``, ``'w+'`` and ``'a+'`` open the file for updating (reading and writing);
note that ``'w+'`` truncates the file. Append ``'b'`` to the mode to open the file in
binary mode, on systems that differentiate between binary and text files; on
systems that don't have this distinction, adding the ``'b'`` has no effect.
.. index::
single: universal newlines; open() built-in function
In addition to the standard :c:func:`fopen` values *mode* may be ``'U'`` or
``'rU'``. Python is usually built with :term:`universal newlines` support;
supplying ``'U'`` opens the file as a text file, but lines may be terminated
by any of the following: the Unix end-of-line convention ``'\n'``, the
Macintosh convention ``'\r'``, or the Windows convention ``'\r\n'``. All of
these external representations are seen as ``'\n'`` by the Python program.
If Python is built without universal newlines support a *mode* with ``'U'``
is the same as normal text mode. Note that file objects so opened also have
an attribute called :attr:`newlines` which has a value of ``None`` (if no
newlines have yet been seen), ``'\n'``, ``'\r'``, ``'\r\n'``, or a tuple
containing all the newline types seen.
Python enforces that the mode, after stripping ``'U'``, begins with ``'r'``,
``'w'`` or ``'a'``.
Python provides many file handling modules including
:mod:`fileinput`, :mod:`os`, :mod:`os.path`, :mod:`tempfile`, and
:mod:`shutil`.
.. versionchanged:: 2.5
Restriction on first letter of mode string introduced.
.. function:: ord(c)
Given a string of length one, return an integer representing the Unicode code
point of the character when the argument is a unicode object, or the value of
the byte when the argument is an 8-bit string. For example, ``ord('a')`` returns
the integer ``97``, ``ord(u'\u2020')`` returns ``8224``. This is the inverse of
:func:`chr` for 8-bit strings and of :func:`unichr` for unicode objects. If a
unicode argument is given and Python was built with UCS2 Unicode, then the
character's code point must be in the range [0..65535] inclusive; otherwise the
string length is two, and a :exc:`TypeError` will be raised.
.. function:: pow(x, y[, z])
Return *x* to the power *y*; if *z* is present, return *x* to the power *y*,
modulo *z* (computed more efficiently than ``pow(x, y) % z``). The two-argument
form ``pow(x, y)`` is equivalent to using the power operator: ``x**y``.
The arguments must have numeric types. With mixed operand types, the coercion
rules for binary arithmetic operators apply. For int and long int operands, the
result has the same type as the operands (after coercion) unless the second
argument is negative; in that case, all arguments are converted to float and a
float result is delivered. For example, ``10**2`` returns ``100``, but
``10**-2`` returns ``0.01``. (This last feature was added in Python 2.2. In
Python 2.1 and before, if both arguments were of integer types and the second
argument was negative, an exception was raised.) If the second argument is
negative, the third argument must be omitted. If *z* is present, *x* and *y*
must be of integer types, and *y* must be non-negative. (This restriction was
added in Python 2.2. In Python 2.1 and before, floating 3-argument ``pow()``
returned platform-dependent results depending on floating-point rounding
accidents.)
.. function:: print(*objects, sep=' ', end='\\n', file=sys.stdout)
Print *objects* to the stream *file*, separated by *sep* and followed by
*end*. *sep*, *end* and *file*, if present, must be given as keyword
arguments.
All non-keyword arguments are converted to strings like :func:`str` does and
written to the stream, separated by *sep* and followed by *end*. Both *sep*
and *end* must be strings; they can also be ``None``, which means to use the
default values. If no *objects* are given, :func:`print` will just write
*end*.
The *file* argument must be an object with a ``write(string)`` method; if it
is not present or ``None``, :data:`sys.stdout` will be used. Output buffering
is determined by *file*. Use ``file.flush()`` to ensure, for instance,
immediate appearance on a screen.
.. note::
This function is not normally available as a built-in since the name
``print`` is recognized as the :keyword:`print` statement. To disable the
statement and use the :func:`print` function, use this future statement at
the top of your module::
from __future__ import print_function
.. versionadded:: 2.6
.. class:: property([fget[, fset[, fdel[, doc]]]])
Return a property attribute for :term:`new-style class`\es (classes that
derive from :class:`object`).
*fget* is a function for getting an attribute value. *fset* is a function
for setting an attribute value. *fdel* is a function for deleting an attribute
value. And *doc* creates a docstring for the attribute.
A typical use is to define a managed attribute ``x``::
class C(object):
def __init__(self):
self._x = None
def getx(self):
return self._x
def setx(self, value):
self._x = value
def delx(self):
del self._x
x = property(getx, setx, delx, "I'm the 'x' property.")
If *c* is an instance of *C*, ``c.x`` will invoke the getter,
``c.x = value`` will invoke the setter and ``del c.x`` the deleter.
If given, *doc* will be the docstring of the property attribute. Otherwise, the
property will copy *fget*'s docstring (if it exists). This makes it possible to
create read-only properties easily using :func:`property` as a :term:`decorator`::
class Parrot(object):
def __init__(self):
self._voltage = 100000
@property
def voltage(self):
"""Get the current voltage."""
return self._voltage
The ``@property`` decorator turns the :meth:`voltage` method into a "getter"
for a read-only attribute with the same name, and it sets the docstring for
*voltage* to "Get the current voltage."
A property object has :attr:`~property.getter`, :attr:`~property.setter`,
and :attr:`~property.deleter` methods usable as decorators that create a
copy of the property with the corresponding accessor function set to the
decorated function. This is best explained with an example::
class C(object):
def __init__(self):
self._x = None
@property
def x(self):
"""I'm the 'x' property."""
return self._x
@x.setter
def x(self, value):
self._x = value
@x.deleter
def x(self):
del self._x
This code is exactly equivalent to the first example. Be sure to give the
additional functions the same name as the original property (``x`` in this
case.)
The returned property object also has the attributes ``fget``, ``fset``, and
``fdel`` corresponding to the constructor arguments.
.. versionadded:: 2.2
.. versionchanged:: 2.5
Use *fget*'s docstring if no *doc* given.
.. versionchanged:: 2.6
The ``getter``, ``setter``, and ``deleter`` attributes were added.
.. function:: range(stop)
range(start, stop[, step])
This is a versatile function to create lists containing arithmetic progressions.
It is most often used in :keyword:`for` loops. The arguments must be plain
integers. If the *step* argument is omitted, it defaults to ``1``. If the
*start* argument is omitted, it defaults to ``0``. The full form returns a list
of plain integers ``[start, start + step, start + 2 * step, ...]``. If *step*
is positive, the last element is the largest ``start + i * step`` less than
*stop*; if *step* is negative, the last element is the smallest ``start + i *
step`` greater than *stop*. *step* must not be zero (or else :exc:`ValueError`
is raised). Example:
>>> range(10)
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
>>> range(1, 11)
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
>>> range(0, 30, 5)
[0, 5, 10, 15, 20, 25]
>>> range(0, 10, 3)
[0, 3, 6, 9]
>>> range(0, -10, -1)
[0, -1, -2, -3, -4, -5, -6, -7, -8, -9]
>>> range(0)
[]
>>> range(1, 0)
[]
.. function:: raw_input([prompt])
If the *prompt* argument is present, it is written to standard output without a
trailing newline. The function then reads a line from input, converts it to a
string (stripping a trailing newline), and returns that. When EOF is read,
:exc:`EOFError` is raised. Example::
>>> s = raw_input('--> ')
--> Monty Python's Flying Circus
>>> s
"Monty Python's Flying Circus"
If the :mod:`readline` module was loaded, then :func:`raw_input` will use it to
provide elaborate line editing and history features.
.. function:: reduce(function, iterable[, initializer])
Apply *function* of two arguments cumulatively to the items of *iterable*, from
left to right, so as to reduce the iterable to a single value. For example,
``reduce(lambda x, y: x+y, [1, 2, 3, 4, 5])`` calculates ``((((1+2)+3)+4)+5)``.
The left argument, *x*, is the accumulated value and the right argument, *y*, is
the update value from the *iterable*. If the optional *initializer* is present,
it is placed before the items of the iterable in the calculation, and serves as
a default when the iterable is empty. If *initializer* is not given and
*iterable* contains only one item, the first item is returned.
Roughly equivalent to::
def reduce(function, iterable, initializer=None):
it = iter(iterable)
if initializer is None:
try:
initializer = next(it)
except StopIteration:
raise TypeError('reduce() of empty sequence with no initial value')
accum_value = initializer
for x in it:
accum_value = function(accum_value, x)
return accum_value
.. function:: reload(module)
Reload a previously imported *module*. The argument must be a module object, so
it must have been successfully imported before. This is useful if you have
edited the module source file using an external editor and want to try out the
new version without leaving the Python interpreter. The return value is the
module object (the same as the *module* argument).
When ``reload(module)`` is executed:
* Python modules' code is recompiled and the module-level code reexecuted,
defining a new set of objects which are bound to names in the module's
dictionary. The ``init`` function of extension modules is not called a second
time.
* As with all other objects in Python the old objects are only reclaimed after
their reference counts drop to zero.
* The names in the module namespace are updated to point to any new or changed
objects.
* Other references to the old objects (such as names external to the module) are
not rebound to refer to the new objects and must be updated in each namespace
where they occur if that is desired.
There are a number of other caveats:
When a module is reloaded, its dictionary (containing the module's global
variables) is retained. Redefinitions of names will override the old
definitions, so this is generally not a problem. If the new version of a module
does not define a name that was defined by the old version, the old definition
remains. This feature can be used to the module's advantage if it maintains a
global table or cache of objects --- with a :keyword:`try` statement it can test
for the table's presence and skip its initialization if desired::
try:
cache
except NameError:
cache = {}
It is generally not very useful to reload built-in or dynamically loaded
modules. Reloading :mod:`sys`, :mod:`__main__`, :mod:`builtins` and other
key modules is not recommended. In many cases extension modules are not
designed to be initialized more than once, and may fail in arbitrary ways
when reloaded.
If a module imports objects from another module using :keyword:`from` ...
:keyword:`import` ..., calling :func:`reload` for the other module does not
redefine the objects imported from it --- one way around this is to re-execute
the :keyword:`from` statement, another is to use :keyword:`import` and qualified
names (*module*.*name*) instead.
If a module instantiates instances of a class, reloading the module that defines
the class does not affect the method definitions of the instances --- they
continue to use the old class definition. The same is true for derived classes.
.. _func-repr:
.. function:: repr(object)
Return a string containing a printable representation of an object. This is
the same value yielded by conversions (reverse quotes). It is sometimes
useful to be able to access this operation as an ordinary function. For many
types, this function makes an attempt to return a string that would yield an
object with the same value when passed to :func:`eval`, otherwise the
representation is a string enclosed in angle brackets that contains the name
of the type of the object together with additional information often
including the name and address of the object. A class can control what this
function returns for its instances by defining a :meth:`__repr__` method.
.. function:: reversed(seq)
Return a reverse :term:`iterator`. *seq* must be an object which has
a :meth:`__reversed__` method or supports the sequence protocol (the
:meth:`__len__` method and the :meth:`__getitem__` method with integer
arguments starting at ``0``).
.. versionadded:: 2.4
.. versionchanged:: 2.6
Added the possibility to write a custom :meth:`__reversed__` method.
.. function:: round(number[, ndigits])
Return the floating point value *number* rounded to *ndigits* digits after
the decimal point. If *ndigits* is omitted, it defaults to zero. The result
is a floating point number. Values are rounded to the closest multiple of
10 to the power minus *ndigits*; if two multiples are equally close,
rounding is done away from 0 (so, for example, ``round(0.5)`` is ``1.0`` and
``round(-0.5)`` is ``-1.0``).
.. note::
The behavior of :func:`round` for floats can be surprising: for example,
``round(2.675, 2)`` gives ``2.67`` instead of the expected ``2.68``.
This is not a bug: it's a result of the fact that most decimal fractions
can't be represented exactly as a float. See :ref:`tut-fp-issues` for
more information.
.. _func-set:
.. class:: set([iterable])
:noindex:
Return a new :class:`set` object, optionally with elements taken from
*iterable*. ``set`` is a built-in class. See :class:`set` and
:ref:`types-set` for documentation about this class.
For other containers see the built-in :class:`frozenset`, :class:`list`,
:class:`tuple`, and :class:`dict` classes, as well as the :mod:`collections`
module.
.. versionadded:: 2.4
.. function:: setattr(object, name, value)
This is the counterpart of :func:`getattr`. The arguments are an object, a
string and an arbitrary value. The string may name an existing attribute or a
new attribute. The function assigns the value to the attribute, provided the
object allows it. For example, ``setattr(x, 'foobar', 123)`` is equivalent to
``x.foobar = 123``.
.. class:: slice(stop)
slice(start, stop[, step])
.. index:: single: Numerical Python
Return a :term:`slice` object representing the set of indices specified by
``range(start, stop, step)``. The *start* and *step* arguments default to
``None``. Slice objects have read-only data attributes :attr:`~slice.start`,
:attr:`~slice.stop` and :attr:`~slice.step` which merely return the argument
values (or their default). They have no other explicit functionality;
however they are used by Numerical Python and other third party extensions.
Slice objects are also generated when extended indexing syntax is used. For
example: ``a[start:stop:step]`` or ``a[start:stop, i]``. See
:func:`itertools.islice` for an alternate version that returns an iterator.
.. function:: sorted(iterable[, cmp[, key[, reverse]]])
Return a new sorted list from the items in *iterable*.
The optional arguments *cmp*, *key*, and *reverse* have the same meaning as
those for the :meth:`list.sort` method (described in section
:ref:`typesseq-mutable`).
*cmp* specifies a custom comparison function of two arguments (iterable
elements) which should return a negative, zero or positive number depending on
whether the first argument is considered smaller than, equal to, or larger than
the second argument: ``cmp=lambda x,y: cmp(x.lower(), y.lower())``. The default
value is ``None``.
*key* specifies a function of one argument that is used to extract a comparison
key from each list element: ``key=str.lower``. The default value is ``None``
(compare the elements directly).
*reverse* is a boolean value. If set to ``True``, then the list elements are
sorted as if each comparison were reversed.
In general, the *key* and *reverse* conversion processes are much faster
than specifying an equivalent *cmp* function. This is because *cmp* is
called multiple times for each list element while *key* and *reverse* touch
each element only once. Use :func:`functools.cmp_to_key` to convert an
old-style *cmp* function to a *key* function.
The built-in :func:`sorted` function is guaranteed to be stable. A sort is
stable if it guarantees not to change the relative order of elements that
compare equal --- this is helpful for sorting in multiple passes (for
example, sort by department, then by salary grade).
For sorting examples and a brief sorting tutorial, see :ref:`sortinghowto`.
.. versionadded:: 2.4
.. function:: staticmethod(function)
Return a static method for *function*.
A static method does not receive an implicit first argument. To declare a static
method, use this idiom::
class C(object):
@staticmethod
def f(arg1, arg2, ...):
...
The ``@staticmethod`` form is a function :term:`decorator` -- see the
description of function definitions in :ref:`function` for details.
It can be called either on the class (such as ``C.f()``) or on an instance (such
as ``C().f()``). The instance is ignored except for its class.
Static methods in Python are similar to those found in Java or C++. Also see
:func:`classmethod` for a variant that is useful for creating alternate
class constructors.
For more information on static methods, consult the documentation on the
standard type hierarchy in :ref:`types`.
.. versionadded:: 2.2
.. versionchanged:: 2.4
Function decorator syntax added.
.. class:: str(object='')
Return a string containing a nicely printable representation of an object. For
strings, this returns the string itself. The difference with ``repr(object)``
is that ``str(object)`` does not always attempt to return a string that is
acceptable to :func:`eval`; its goal is to return a printable string. If no
argument is given, returns the empty string, ``''``.
For more information on strings see :ref:`typesseq` which describes sequence
functionality (strings are sequences), and also the string-specific methods
described in the :ref:`string-methods` section. To output formatted strings
use template strings or the ``%`` operator described in the
:ref:`string-formatting` section. In addition see the :ref:`stringservices`
section. See also :func:`unicode`.
.. function:: sum(iterable[, start])
Sums *start* and the items of an *iterable* from left to right and returns the
total. *start* defaults to ``0``. The *iterable*'s items are normally numbers,
and the start value is not allowed to be a string.
For some use cases, there are good alternatives to :func:`sum`.
The preferred, fast way to concatenate a sequence of strings is by calling
``''.join(sequence)``. To add floating point values with extended precision,
see :func:`math.fsum`\. To concatenate a series of iterables, consider using
:func:`itertools.chain`.
.. versionadded:: 2.3
.. function:: super(type[, object-or-type])
Return a proxy object that delegates method calls to a parent or sibling
class of *type*. This is useful for accessing inherited methods that have
been overridden in a class. The search order is same as that used by
:func:`getattr` except that the *type* itself is skipped.
The :attr:`~class.__mro__` attribute of the *type* lists the method
resolution search order used by both :func:`getattr` and :func:`super`. The
attribute is dynamic and can change whenever the inheritance hierarchy is
updated.
If the second argument is omitted, the super object returned is unbound. If
the second argument is an object, ``isinstance(obj, type)`` must be true. If
the second argument is a type, ``issubclass(type2, type)`` must be true (this
is useful for classmethods).
.. note::
:func:`super` only works for :term:`new-style class`\es.
There are two typical use cases for *super*. In a class hierarchy with
single inheritance, *super* can be used to refer to parent classes without
naming them explicitly, thus making the code more maintainable. This use
closely parallels the use of *super* in other programming languages.
The second use case is to support cooperative multiple inheritance in a
dynamic execution environment. This use case is unique to Python and is
not found in statically compiled languages or languages that only support
single inheritance. This makes it possible to implement "diamond diagrams"
where multiple base classes implement the same method. Good design dictates
that this method have the same calling signature in every case (because the
order of calls is determined at runtime, because that order adapts
to changes in the class hierarchy, and because that order can include
sibling classes that are unknown prior to runtime).
For both use cases, a typical superclass call looks like this::
class C(B):
def method(self, arg):
super(C, self).method(arg)
Note that :func:`super` is implemented as part of the binding process for
explicit dotted attribute lookups such as ``super().__getitem__(name)``.
It does so by implementing its own :meth:`__getattribute__` method for searching
classes in a predictable order that supports cooperative multiple inheritance.
Accordingly, :func:`super` is undefined for implicit lookups using statements or
operators such as ``super()[name]``.
Also note that :func:`super` is not limited to use inside methods. The two
argument form specifies the arguments exactly and makes the appropriate
references.
For practical suggestions on how to design cooperative classes using
:func:`super`, see `guide to using super()
<https://rhettinger.wordpress.com/2011/05/26/super-considered-super/>`_.
.. versionadded:: 2.2
.. function:: tuple([iterable])
Return a tuple whose items are the same and in the same order as *iterable*'s
items. *iterable* may be a sequence, a container that supports iteration, or an
iterator object. If *iterable* is already a tuple, it is returned unchanged.
For instance, ``tuple('abc')`` returns ``('a', 'b', 'c')`` and ``tuple([1, 2,
3])`` returns ``(1, 2, 3)``. If no argument is given, returns a new empty
tuple, ``()``.
:class:`tuple` is an immutable sequence type, as documented in
:ref:`typesseq`. For other containers see the built in :class:`dict`,
:class:`list`, and :class:`set` classes, and the :mod:`collections` module.
.. class:: type(object)
type(name, bases, dict)
.. index:: object: type
With one argument, return the type of an *object*. The return value is a
type object. The :func:`isinstance` built-in function is recommended for
testing the type of an object.
With three arguments, return a new type object. This is essentially a
dynamic form of the :keyword:`class` statement. The *name* string is the
class name and becomes the :attr:`~definition.__name__` attribute; the *bases* tuple
itemizes the base classes and becomes the :attr:`~class.__bases__` attribute;
and the *dict* dictionary is the namespace containing definitions for class
body and becomes the :attr:`~object.__dict__` attribute. For example, the
following two statements create identical :class:`type` objects:
>>> class X(object):
... a = 1
...
>>> X = type('X', (object,), dict(a=1))
.. versionadded:: 2.2
.. function:: unichr(i)
Return the Unicode string of one character whose Unicode code is the integer
*i*. For example, ``unichr(97)`` returns the string ``u'a'``. This is the
inverse of :func:`ord` for Unicode strings. The valid range for the argument
depends how Python was configured -- it may be either UCS2 [0..0xFFFF] or UCS4
[0..0x10FFFF]. :exc:`ValueError` is raised otherwise. For ASCII and 8-bit
strings see :func:`chr`.
.. versionadded:: 2.0
.. function:: unicode(object='')
unicode(object[, encoding [, errors]])
Return the Unicode string version of *object* using one of the following modes:
If *encoding* and/or *errors* are given, ``unicode()`` will decode the object
which can either be an 8-bit string or a character buffer using the codec for
*encoding*. The *encoding* parameter is a string giving the name of an encoding;
if the encoding is not known, :exc:`LookupError` is raised. Error handling is
done according to *errors*; this specifies the treatment of characters which are
invalid in the input encoding. If *errors* is ``'strict'`` (the default), a
:exc:`ValueError` is raised on errors, while a value of ``'ignore'`` causes
errors to be silently ignored, and a value of ``'replace'`` causes the official
Unicode replacement character, ``U+FFFD``, to be used to replace input
characters which cannot be decoded. See also the :mod:`codecs` module.
If no optional parameters are given, ``unicode()`` will mimic the behaviour of
``str()`` except that it returns Unicode strings instead of 8-bit strings. More
precisely, if *object* is a Unicode string or subclass it will return that
Unicode string without any additional decoding applied.
For objects which provide a :meth:`__unicode__` method, it will call this method
without arguments to create a Unicode string. For all other objects, the 8-bit
string version or representation is requested and then converted to a Unicode
string using the codec for the default encoding in ``'strict'`` mode.
For more information on Unicode strings see :ref:`typesseq` which describes
sequence functionality (Unicode strings are sequences), and also the
string-specific methods described in the :ref:`string-methods` section. To
output formatted strings use template strings or the ``%`` operator described
in the :ref:`string-formatting` section. In addition see the
:ref:`stringservices` section. See also :func:`str`.
.. versionadded:: 2.0
.. versionchanged:: 2.2
Support for :meth:`__unicode__` added.
.. function:: vars([object])
Return the :attr:`~object.__dict__` attribute for a module, class, instance,
or any other object with a :attr:`~object.__dict__` attribute.
Objects such as modules and instances have an updateable :attr:`~object.__dict__`
attribute; however, other objects may have write restrictions on their
:attr:`~object.__dict__` attributes (for example, new-style classes use a
dictproxy to prevent direct dictionary updates).
Without an argument, :func:`vars` acts like :func:`locals`. Note, the
locals dictionary is only useful for reads since updates to the locals
dictionary are ignored.
.. function:: xrange(stop)
xrange(start, stop[, step])
This function is very similar to :func:`range`, but returns an :ref:`xrange
object <typesseq-xrange>`
instead of a list. This is an opaque sequence type which yields the same values
as the corresponding list, without actually storing them all simultaneously.
The advantage of :func:`xrange` over :func:`range` is minimal (since
:func:`xrange` still has to create the values when asked for them) except when a
very large range is used on a memory-starved machine or when all of the range's
elements are never used (such as when the loop is usually terminated with
:keyword:`break`). For more information on xrange objects, see
:ref:`typesseq-xrange` and :ref:`typesseq`.
.. impl-detail::
:func:`xrange` is intended to be simple and fast. Implementations may
impose restrictions to achieve this. The C implementation of Python
restricts all arguments to native C longs ("short" Python integers), and
also requires that the number of elements fit in a native C long. If a
larger range is needed, an alternate version can be crafted using the
:mod:`itertools` module: ``islice(count(start, step),
(stop-start+step-1+2*(step<0))//step)``.
.. function:: zip([iterable, ...])
This function returns a list of tuples, where the *i*-th tuple contains the
*i*-th element from each of the argument sequences or iterables. The returned
list is truncated in length to the length of the shortest argument sequence.
When there are multiple arguments which are all of the same length, :func:`zip`
is similar to :func:`map` with an initial argument of ``None``. With a single
sequence argument, it returns a list of 1-tuples. With no arguments, it returns
an empty list.
The left-to-right evaluation order of the iterables is guaranteed. This
makes possible an idiom for clustering a data series into n-length groups
using ``zip(*[iter(s)]*n)``.
:func:`zip` in conjunction with the ``*`` operator can be used to unzip a
list::
>>> x = [1, 2, 3]
>>> y = [4, 5, 6]
>>> zipped = zip(x, y)
>>> zipped
[(1, 4), (2, 5), (3, 6)]
>>> x2, y2 = zip(*zipped)
>>> x == list(x2) and y == list(y2)
True
.. versionadded:: 2.0
.. versionchanged:: 2.4
Formerly, :func:`zip` required at least one argument and ``zip()`` raised a
:exc:`TypeError` instead of returning an empty list.
.. function:: __import__(name[, globals[, locals[, fromlist[, level]]]])
.. index::
statement: import
module: imp
.. note::
This is an advanced function that is not needed in everyday Python
programming, unlike :func:`importlib.import_module`.
This function is invoked by the :keyword:`import` statement. It can be
replaced (by importing the :mod:`__builtin__` module and assigning to
``__builtin__.__import__``) in order to change semantics of the
:keyword:`import` statement, but nowadays it is usually simpler to use import
hooks (see :pep:`302`). Direct use of :func:`__import__` is rare, except in
cases where you want to import a module whose name is only known at runtime.
The function imports the module *name*, potentially using the given *globals*
and *locals* to determine how to interpret the name in a package context.
The *fromlist* gives the names of objects or submodules that should be
imported from the module given by *name*. The standard implementation does
not use its *locals* argument at all, and uses its *globals* only to
determine the package context of the :keyword:`import` statement.
*level* specifies whether to use absolute or relative imports. The default
is ``-1`` which indicates both absolute and relative imports will be
attempted. ``0`` means only perform absolute imports. Positive values for
*level* indicate the number of parent directories to search relative to the
directory of the module calling :func:`__import__`.
When the *name* variable is of the form ``package.module``, normally, the
top-level package (the name up till the first dot) is returned, *not* the
module named by *name*. However, when a non-empty *fromlist* argument is
given, the module named by *name* is returned.
For example, the statement ``import spam`` results in bytecode resembling the
following code::
spam = __import__('spam', globals(), locals(), [], -1)
The statement ``import spam.ham`` results in this call::
spam = __import__('spam.ham', globals(), locals(), [], -1)
Note how :func:`__import__` returns the toplevel module here because this is
the object that is bound to a name by the :keyword:`import` statement.
On the other hand, the statement ``from spam.ham import eggs, sausage as
saus`` results in ::
_temp = __import__('spam.ham', globals(), locals(), ['eggs', 'sausage'], -1)
eggs = _temp.eggs
saus = _temp.sausage
Here, the ``spam.ham`` module is returned from :func:`__import__`. From this
object, the names to import are retrieved and assigned to their respective
names.
If you simply want to import a module (potentially within a package) by name,
use :func:`importlib.import_module`.
.. versionchanged:: 2.5
The level parameter was added.
.. versionchanged:: 2.5
Keyword support for parameters was added.
.. ---------------------------------------------------------------------------
.. _non-essential-built-in-funcs:
Non-essential Built-in Functions
================================
There are several built-in functions that are no longer essential to learn, know
or use in modern Python programming. They have been kept here to maintain
backwards compatibility with programs written for older versions of Python.
Python programmers, trainers, students and book writers should feel free to
bypass these functions without concerns about missing something important.
.. function:: apply(function, args[, keywords])
The *function* argument must be a callable object (a user-defined or built-in
function or method, or a class object) and the *args* argument must be a
sequence. The *function* is called with *args* as the argument list; the number
of arguments is the length of the tuple. If the optional *keywords* argument is
present, it must be a dictionary whose keys are strings. It specifies keyword
arguments to be added to the end of the argument list. Calling :func:`apply` is
different from just calling ``function(args)``, since in that case there is
always exactly one argument. The use of :func:`apply` is equivalent to
``function(*args, **keywords)``.
.. deprecated:: 2.3
Use ``function(*args, **keywords)`` instead of
``apply(function, args, keywords)`` (see :ref:`tut-unpacking-arguments`).
.. function:: buffer(object[, offset[, size]])
The *object* argument must be an object that supports the buffer call interface
(such as strings, arrays, and buffers). A new buffer object will be created
which references the *object* argument. The buffer object will be a slice from
the beginning of *object* (or from the specified *offset*). The slice will
extend to the end of *object* (or will have a length given by the *size*
argument).
.. function:: coerce(x, y)
Return a tuple consisting of the two numeric arguments converted to a common
type, using the same rules as used by arithmetic operations. If coercion is not
possible, raise :exc:`TypeError`.
.. function:: intern(string)
Enter *string* in the table of "interned" strings and return the interned string
-- which is *string* itself or a copy. Interning strings is useful to gain a
little performance on dictionary lookup -- if the keys in a dictionary are
interned, and the lookup key is interned, the key comparisons (after hashing)
can be done by a pointer compare instead of a string compare. Normally, the
names used in Python programs are automatically interned, and the dictionaries
used to hold module, class or instance attributes have interned keys.
.. versionchanged:: 2.3
Interned strings are not immortal (like they used to be in Python 2.2 and
before); you must keep a reference to the return value of :func:`intern` around
to benefit from it.
.. rubric:: Footnotes
.. [#] It is used relatively rarely so does not warrant being made into a statement.
.. [#] Specifying a buffer size currently has no effect on systems that don't have
:c:func:`setvbuf`. The interface to specify the buffer size is not done using a
method that calls :c:func:`setvbuf`, because that may dump core when called after
any I/O has been performed, and there's no reliable way to determine whether
this is the case.
.. [#] In the current implementation, local variable bindings cannot normally be
affected this way, but variables retrieved from other scopes (such as modules)
can be. This may change.
PK %�\�~a ' html/_sources/library/functools.rst.txtnu �[��� :mod:`functools` --- Higher-order functions and operations on callable objects
==============================================================================
.. module:: functools
:synopsis: Higher-order functions and operations on callable objects.
.. moduleauthor:: Peter Harris <scav@blueyonder.co.uk>
.. moduleauthor:: Raymond Hettinger <python@rcn.com>
.. moduleauthor:: Nick Coghlan <ncoghlan@gmail.com>
.. sectionauthor:: Peter Harris <scav@blueyonder.co.uk>
.. versionadded:: 2.5
**Source code:** :source:`Lib/functools.py`
--------------
The :mod:`functools` module is for higher-order functions: functions that act on
or return other functions. In general, any callable object can be treated as a
function for the purposes of this module.
The :mod:`functools` module defines the following functions:
.. function:: cmp_to_key(func)
Transform an old-style comparison function to a :term:`key function`. Used
with tools that accept key functions (such as :func:`sorted`, :func:`min`,
:func:`max`, :func:`heapq.nlargest`, :func:`heapq.nsmallest`,
:func:`itertools.groupby`). This function is primarily used as a transition
tool for programs being converted to Python 3 where comparison functions are
no longer supported.
A comparison function is any callable that accept two arguments, compares them,
and returns a negative number for less-than, zero for equality, or a positive
number for greater-than. A key function is a callable that accepts one
argument and returns another value to be used as the sort key.
Example::
sorted(iterable, key=cmp_to_key(locale.strcoll)) # locale-aware sort order
For sorting examples and a brief sorting tutorial, see :ref:`sortinghowto`.
.. versionadded:: 2.7
.. function:: total_ordering(cls)
Given a class defining one or more rich comparison ordering methods, this
class decorator supplies the rest. This simplifies the effort involved
in specifying all of the possible rich comparison operations:
The class must define one of :meth:`__lt__`, :meth:`__le__`,
:meth:`__gt__`, or :meth:`__ge__`.
In addition, the class should supply an :meth:`__eq__` method.
For example::
@total_ordering
class Student:
def __eq__(self, other):
return ((self.lastname.lower(), self.firstname.lower()) ==
(other.lastname.lower(), other.firstname.lower()))
def __lt__(self, other):
return ((self.lastname.lower(), self.firstname.lower()) <
(other.lastname.lower(), other.firstname.lower()))
.. versionadded:: 2.7
.. function:: reduce(function, iterable[, initializer])
This is the same function as :func:`reduce`. It is made available in this module
to allow writing code more forward-compatible with Python 3.
.. versionadded:: 2.6
.. function:: partial(func[,*args][, **keywords])
Return a new :ref:`partial object<partial-objects>` which when called will behave
like *func* called with the positional arguments *args* and keyword arguments *keywords*.
If more arguments are supplied to the call, they are appended to *args*. If
additional keyword arguments are supplied, they extend and override *keywords*.
Roughly equivalent to::
def partial(func, *args, **keywords):
def newfunc(*fargs, **fkeywords):
newkeywords = keywords.copy()
newkeywords.update(fkeywords)
return func(*(args + fargs), **newkeywords)
newfunc.func = func
newfunc.args = args
newfunc.keywords = keywords
return newfunc
The :func:`partial` is used for partial function application which "freezes"
some portion of a function's arguments and/or keywords resulting in a new object
with a simplified signature. For example, :func:`partial` can be used to create
a callable that behaves like the :func:`int` function where the *base* argument
defaults to two:
>>> from functools import partial
>>> basetwo = partial(int, base=2)
>>> basetwo.__doc__ = 'Convert base 2 string to an int.'
>>> basetwo('10010')
18
.. function:: update_wrapper(wrapper, wrapped[, assigned][, updated])
Update a *wrapper* function to look like the *wrapped* function. The optional
arguments are tuples to specify which attributes of the original function are
assigned directly to the matching attributes on the wrapper function and which
attributes of the wrapper function are updated with the corresponding attributes
from the original function. The default values for these arguments are the
module level constants *WRAPPER_ASSIGNMENTS* (which assigns to the wrapper
function's *__name__*, *__module__* and *__doc__*, the documentation string) and
*WRAPPER_UPDATES* (which updates the wrapper function's *__dict__*, i.e. the
instance dictionary).
The main intended use for this function is in :term:`decorator` functions which
wrap the decorated function and return the wrapper. If the wrapper function is
not updated, the metadata of the returned function will reflect the wrapper
definition rather than the original function definition, which is typically less
than helpful.
.. function:: wraps(wrapped[, assigned][, updated])
This is a convenience function for invoking :func:`update_wrapper` as a
function decorator when defining a wrapper function. It is equivalent to
``partial(update_wrapper, wrapped=wrapped, assigned=assigned, updated=updated)``.
For example::
>>> from functools import wraps
>>> def my_decorator(f):
... @wraps(f)
... def wrapper(*args, **kwds):
... print 'Calling decorated function'
... return f(*args, **kwds)
... return wrapper
...
>>> @my_decorator
... def example():
... """Docstring"""
... print 'Called example function'
...
>>> example()
Calling decorated function
Called example function
>>> example.__name__
'example'
>>> example.__doc__
'Docstring'
Without the use of this decorator factory, the name of the example function
would have been ``'wrapper'``, and the docstring of the original :func:`example`
would have been lost.
.. _partial-objects:
:class:`partial` Objects
------------------------
:class:`partial` objects are callable objects created by :func:`partial`. They
have three read-only attributes:
.. attribute:: partial.func
A callable object or function. Calls to the :class:`partial` object will be
forwarded to :attr:`func` with new arguments and keywords.
.. attribute:: partial.args
The leftmost positional arguments that will be prepended to the positional
arguments provided to a :class:`partial` object call.
.. attribute:: partial.keywords
The keyword arguments that will be supplied when the :class:`partial` object is
called.
:class:`partial` objects are like :class:`function` objects in that they are
callable, weak referencable, and can have attributes. There are some important
differences. For instance, the :attr:`~definition.__name__` and :attr:`__doc__` attributes
are not created automatically. Also, :class:`partial` objects defined in
classes behave like static methods and do not transform into bound methods
during instance attribute look-up.
PK %�\VW�� � - html/_sources/library/future_builtins.rst.txtnu �[��� :mod:`future_builtins` --- Python 3 builtins
============================================
.. module:: future_builtins
.. sectionauthor:: Georg Brandl
.. versionadded:: 2.6
This module provides functions that exist in 2.x, but have different behavior in
Python 3, so they cannot be put into the 2.x builtins namespace.
Instead, if you want to write code compatible with Python 3 builtins, import
them from this module, like this::
from future_builtins import map, filter
... code using Python 3-style map and filter ...
The :term:`2to3` tool that ports Python 2 code to Python 3 will recognize
this usage and leave the new builtins alone.
.. note::
The Python 3 :func:`print` function is already in the builtins, but cannot be
accessed from Python 2 code unless you use the appropriate future statement::
from __future__ import print_function
Available builtins are:
.. function:: ascii(object)
Returns the same as :func:`repr`. In Python 3, :func:`repr` will return
printable Unicode characters unescaped, while :func:`ascii` will always
backslash-escape them. Using :func:`future_builtins.ascii` instead of
:func:`repr` in 2.6 code makes it clear that you need a pure ASCII return
value.
.. function:: filter(function, iterable)
Works like :func:`itertools.ifilter`.
.. function:: hex(object)
Works like the built-in :func:`hex`, but instead of :meth:`__hex__` it will
use the :meth:`__index__` method on its argument to get an integer that is
then converted to hexadecimal.
.. function:: map(function, iterable, ...)
Works like :func:`itertools.imap`.
.. note::
In Python 3, :func:`map` does not accept ``None`` for the
function argument.
.. function:: oct(object)
Works like the built-in :func:`oct`, but instead of :meth:`__oct__` it will
use the :meth:`__index__` method on its argument to get an integer that is
then converted to octal.
.. function:: zip(*iterables)
Works like :func:`itertools.izip`.
PK %�\��6# 6# html/_sources/library/gc.rst.txtnu �[���
:mod:`gc` --- Garbage Collector interface
=========================================
.. module:: gc
:synopsis: Interface to the cycle-detecting garbage collector.
.. moduleauthor:: Neil Schemenauer <nas@arctrix.com>
.. sectionauthor:: Neil Schemenauer <nas@arctrix.com>
This module provides an interface to the optional garbage collector. It
provides the ability to disable the collector, tune the collection frequency,
and set debugging options. It also provides access to unreachable objects that
the collector found but cannot free. Since the collector supplements the
reference counting already used in Python, you can disable the collector if you
are sure your program does not create reference cycles. Automatic collection
can be disabled by calling ``gc.disable()``. To debug a leaking program call
``gc.set_debug(gc.DEBUG_LEAK)``. Notice that this includes
``gc.DEBUG_SAVEALL``, causing garbage-collected objects to be saved in
gc.garbage for inspection.
The :mod:`gc` module provides the following functions:
.. function:: enable()
Enable automatic garbage collection.
.. function:: disable()
Disable automatic garbage collection.
.. function:: isenabled()
Returns true if automatic collection is enabled.
.. function:: collect([generation])
With no arguments, run a full collection. The optional argument *generation*
may be an integer specifying which generation to collect (from 0 to 2). A
:exc:`ValueError` is raised if the generation number is invalid. The number of
unreachable objects found is returned.
.. versionchanged:: 2.5
The optional *generation* argument was added.
.. versionchanged:: 2.6
The free lists maintained for a number of built-in types are cleared
whenever a full collection or collection of the highest generation (2)
is run. Not all items in some free lists may be freed due to the
particular implementation, in particular :class:`int` and :class:`float`.
.. function:: set_debug(flags)
Set the garbage collection debugging flags. Debugging information will be
written to ``sys.stderr``. See below for a list of debugging flags which can be
combined using bit operations to control debugging.
.. function:: get_debug()
Return the debugging flags currently set.
.. function:: get_objects()
Returns a list of all objects tracked by the collector, excluding the list
returned.
.. versionadded:: 2.2
.. function:: set_threshold(threshold0[, threshold1[, threshold2]])
Set the garbage collection thresholds (the collection frequency). Setting
*threshold0* to zero disables collection.
The GC classifies objects into three generations depending on how many
collection sweeps they have survived. New objects are placed in the youngest
generation (generation ``0``). If an object survives a collection it is moved
into the next older generation. Since generation ``2`` is the oldest
generation, objects in that generation remain there after a collection. In
order to decide when to run, the collector keeps track of the number object
allocations and deallocations since the last collection. When the number of
allocations minus the number of deallocations exceeds *threshold0*, collection
starts. Initially only generation ``0`` is examined. If generation ``0`` has
been examined more than *threshold1* times since generation ``1`` has been
examined, then generation ``1`` is examined as well. Similarly, *threshold2*
controls the number of collections of generation ``1`` before collecting
generation ``2``.
.. function:: get_count()
Return the current collection counts as a tuple of ``(count0, count1,
count2)``.
.. versionadded:: 2.5
.. function:: get_threshold()
Return the current collection thresholds as a tuple of ``(threshold0,
threshold1, threshold2)``.
.. function:: get_referrers(*objs)
Return the list of objects that directly refer to any of objs. This function
will only locate those containers which support garbage collection; extension
types which do refer to other objects but do not support garbage collection will
not be found.
Note that objects which have already been dereferenced, but which live in cycles
and have not yet been collected by the garbage collector can be listed among the
resulting referrers. To get only currently live objects, call :func:`collect`
before calling :func:`get_referrers`.
Care must be taken when using objects returned by :func:`get_referrers` because
some of them could still be under construction and hence in a temporarily
invalid state. Avoid using :func:`get_referrers` for any purpose other than
debugging.
.. versionadded:: 2.2
.. function:: get_referents(*objs)
Return a list of objects directly referred to by any of the arguments. The
referents returned are those objects visited by the arguments' C-level
:c:member:`~PyTypeObject.tp_traverse` methods (if any), and may not be all objects actually
directly reachable. :c:member:`~PyTypeObject.tp_traverse` methods are supported only by objects
that support garbage collection, and are only required to visit objects that may
be involved in a cycle. So, for example, if an integer is directly reachable
from an argument, that integer object may or may not appear in the result list.
.. versionadded:: 2.3
.. function:: is_tracked(obj)
Returns ``True`` if the object is currently tracked by the garbage collector,
``False`` otherwise. As a general rule, instances of atomic types aren't
tracked and instances of non-atomic types (containers, user-defined
objects...) are. However, some type-specific optimizations can be present
in order to suppress the garbage collector footprint of simple instances
(e.g. dicts containing only atomic keys and values)::
>>> gc.is_tracked(0)
False
>>> gc.is_tracked("a")
False
>>> gc.is_tracked([])
True
>>> gc.is_tracked({})
False
>>> gc.is_tracked({"a": 1})
False
>>> gc.is_tracked({"a": []})
True
.. versionadded:: 2.7
The following variable is provided for read-only access (you can mutate its
value but should not rebind it):
.. data:: garbage
A list of objects which the collector found to be unreachable but could not be
freed (uncollectable objects). By default, this list contains only objects with
:meth:`__del__` methods. [#]_ Objects that have :meth:`__del__` methods and are
part of a reference cycle cause the entire reference cycle to be uncollectable,
including objects not necessarily in the cycle but reachable only from it.
Python doesn't collect such cycles automatically because, in general, it isn't
possible for Python to guess a safe order in which to run the :meth:`__del__`
methods. If you know a safe order, you can force the issue by examining the
*garbage* list, and explicitly breaking cycles due to your objects within the
list. Note that these objects are kept alive even so by virtue of being in the
*garbage* list, so they should be removed from *garbage* too. For example,
after breaking cycles, do ``del gc.garbage[:]`` to empty the list. It's
generally better to avoid the issue by not creating cycles containing objects
with :meth:`__del__` methods, and *garbage* can be examined in that case to
verify that no such cycles are being created.
If :const:`DEBUG_SAVEALL` is set, then all unreachable objects will be added to
this list rather than freed.
The following constants are provided for use with :func:`set_debug`:
.. data:: DEBUG_STATS
Print statistics during collection. This information can be useful when tuning
the collection frequency.
.. data:: DEBUG_COLLECTABLE
Print information on collectable objects found.
.. data:: DEBUG_UNCOLLECTABLE
Print information of uncollectable objects found (objects which are not
reachable but cannot be freed by the collector). These objects will be added to
the ``garbage`` list.
.. data:: DEBUG_INSTANCES
When :const:`DEBUG_COLLECTABLE` or :const:`DEBUG_UNCOLLECTABLE` is set, print
information about instance objects found.
.. data:: DEBUG_OBJECTS
When :const:`DEBUG_COLLECTABLE` or :const:`DEBUG_UNCOLLECTABLE` is set, print
information about objects other than instance objects found.
.. data:: DEBUG_SAVEALL
When set, all unreachable objects found will be appended to *garbage* rather
than being freed. This can be useful for debugging a leaking program.
.. data:: DEBUG_LEAK
The debugging flags necessary for the collector to print information about a
leaking program (equal to ``DEBUG_COLLECTABLE | DEBUG_UNCOLLECTABLE |
DEBUG_INSTANCES | DEBUG_OBJECTS | DEBUG_SAVEALL``).
.. rubric:: Footnotes
.. [#] Prior to Python 2.2, the list contained all instance objects in unreachable
cycles, not only those with :meth:`__del__` methods.
PK %�\��>1 " html/_sources/library/gdbm.rst.txtnu �[��� :mod:`gdbm` --- GNU's reinterpretation of dbm
=============================================
.. module:: gdbm
:platform: Unix
:synopsis: GNU's reinterpretation of dbm.
.. note::
The :mod:`gdbm` module has been renamed to :mod:`dbm.gnu` in Python 3. The
:term:`2to3` tool will automatically adapt imports when converting your
sources to Python 3.
.. index:: module: dbm
This module is quite similar to the :mod:`dbm` module, but uses ``gdbm`` instead
to provide some additional functionality. Please note that the file formats
created by ``gdbm`` and ``dbm`` are incompatible.
The :mod:`gdbm` module provides an interface to the GNU DBM library. ``gdbm``
objects behave like mappings (dictionaries), except that keys and values are
always strings. Printing a ``gdbm`` object doesn't print the keys and values,
and the :meth:`items` and :meth:`values` methods are not supported.
The module defines the following constant and functions:
.. exception:: error
Raised on ``gdbm``\ -specific errors, such as I/O errors. :exc:`KeyError` is
raised for general mapping errors like specifying an incorrect key.
.. function:: open(filename, [flag, [mode]])
Open a ``gdbm`` database and return a ``gdbm`` object. The *filename* argument
is the name of the database file.
The optional *flag* argument can be:
+---------+-------------------------------------------+
| Value | Meaning |
+=========+===========================================+
| ``'r'`` | Open existing database for reading only |
| | (default) |
+---------+-------------------------------------------+
| ``'w'`` | Open existing database for reading and |
| | writing |
+---------+-------------------------------------------+
| ``'c'`` | Open database for reading and writing, |
| | creating it if it doesn't exist |
+---------+-------------------------------------------+
| ``'n'`` | Always create a new, empty database, open |
| | for reading and writing |
+---------+-------------------------------------------+
The following additional characters may be appended to the flag to control
how the database is opened:
+---------+--------------------------------------------+
| Value | Meaning |
+=========+============================================+
| ``'f'`` | Open the database in fast mode. Writes |
| | to the database will not be synchronized. |
+---------+--------------------------------------------+
| ``'s'`` | Synchronized mode. This will cause changes |
| | to the database to be immediately written |
| | to the file. |
+---------+--------------------------------------------+
| ``'u'`` | Do not lock database. |
+---------+--------------------------------------------+
Not all flags are valid for all versions of ``gdbm``. The module constant
:const:`open_flags` is a string of supported flag characters. The exception
:exc:`error` is raised if an invalid flag is specified.
The optional *mode* argument is the Unix mode of the file, used only when the
database has to be created. It defaults to octal ``0666``.
In addition to the dictionary-like methods, ``gdbm`` objects have the following
methods:
.. function:: firstkey()
It's possible to loop over every key in the database using this method and the
:meth:`nextkey` method. The traversal is ordered by ``gdbm``'s internal hash
values, and won't be sorted by the key values. This method returns the starting
key.
.. function:: nextkey(key)
Returns the key that follows *key* in the traversal. The following code prints
every key in the database ``db``, without having to create a list in memory that
contains them all::
k = db.firstkey()
while k != None:
print k
k = db.nextkey(k)
.. function:: reorganize()
If you have carried out a lot of deletions and would like to shrink the space
used by the ``gdbm`` file, this routine will reorganize the database. ``gdbm``
will not shorten the length of a database file except by using this
reorganization; otherwise, deleted file space will be kept and reused as new
(key, value) pairs are added.
.. function:: sync()
When the database has been opened in fast mode, this method forces any
unwritten data to be written to the disk.
.. function:: close()
Close the ``gdbm`` database.
.. seealso::
Module :mod:`anydbm`
Generic interface to ``dbm``\ -style databases.
Module :mod:`whichdb`
Utility module used to determine the type of an existing database.
PK %�\���') ) , html/_sources/library/gensuitemodule.rst.txtnu �[���
:mod:`gensuitemodule` --- Generate OSA stub packages
====================================================
.. module:: gensuitemodule
:platform: Mac
:synopsis: Create a stub package from an OSA dictionary
.. sectionauthor:: Jack Jansen <Jack.Jansen@cwi.nl>
.. moduleauthor:: Jack Jansen
The :mod:`gensuitemodule` module creates a Python package implementing stub code
for the AppleScript suites that are implemented by a specific application,
according to its AppleScript dictionary.
It is usually invoked by the user through the :program:`PythonIDE`, but it can
also be run as a script from the command line (pass :option:`--help` for help on
the options) or imported from Python code. For an example of its use see
:file:`Mac/scripts/genallsuites.py` in a source distribution, which generates
the stub packages that are included in the standard library.
It defines the following public functions:
.. function:: is_scriptable(application)
Returns true if ``application``, which should be passed as a pathname, appears
to be scriptable. Take the return value with a grain of salt: :program:`Internet
Explorer` appears not to be scriptable but definitely is.
.. function:: processfile(application[, output, basepkgname, edit_modnames, creatorsignature, dump, verbose])
Create a stub package for ``application``, which should be passed as a full
pathname. For a :file:`.app` bundle this is the pathname to the bundle, not to
the executable inside the bundle; for an unbundled CFM application you pass the
filename of the application binary.
This function asks the application for its OSA terminology resources, decodes
these resources and uses the resultant data to create the Python code for the
package implementing the client stubs.
``output`` is the pathname where the resulting package is stored, if not
specified a standard "save file as" dialog is presented to the user.
``basepkgname`` is the base package on which this package will build, and
defaults to :mod:`StdSuites`. Only when generating :mod:`StdSuites` itself do
you need to specify this. ``edit_modnames`` is a dictionary that can be used to
change modulenames that are too ugly after name mangling. ``creator_signature``
can be used to override the 4-char creator code, which is normally obtained from
the :file:`PkgInfo` file in the package or from the CFM file creator signature.
When ``dump`` is given it should refer to a file object, and ``processfile``
will stop after decoding the resources and dump the Python representation of the
terminology resources to this file. ``verbose`` should also be a file object,
and specifying it will cause ``processfile`` to tell you what it is doing.
.. function:: processfile_fromresource(application[, output, basepkgname, edit_modnames, creatorsignature, dump, verbose])
This function does the same as ``processfile``, except that it uses a different
method to get the terminology resources. It opens ``application`` as a resource
file and reads all ``"aete"`` and ``"aeut"`` resources from this file.
PK %�\��D� $ html/_sources/library/getopt.rst.txtnu �[��� :mod:`getopt` --- C-style parser for command line options
=========================================================
.. module:: getopt
:synopsis: Portable parser for command line options; support both short and long option
names.
**Source code:** :source:`Lib/getopt.py`
--------------
.. note::
The :mod:`getopt` module is a parser for command line options whose API is
designed to be familiar to users of the C :c:func:`getopt` function. Users who
are unfamiliar with the C :c:func:`getopt` function or who would like to write
less code and get better help and error messages should consider using the
:mod:`argparse` module instead.
This module helps scripts to parse the command line arguments in ``sys.argv``.
It supports the same conventions as the Unix :c:func:`getopt` function (including
the special meanings of arguments of the form '``-``' and '``--``'). Long
options similar to those supported by GNU software may be used as well via an
optional third argument.
This module provides two functions and an
exception:
.. function:: getopt(args, options[, long_options])
Parses command line options and parameter list. *args* is the argument list to
be parsed, without the leading reference to the running program. Typically, this
means ``sys.argv[1:]``. *options* is the string of option letters that the
script wants to recognize, with options that require an argument followed by a
colon (``':'``; i.e., the same format that Unix :c:func:`getopt` uses).
.. note::
Unlike GNU :c:func:`getopt`, after a non-option argument, all further
arguments are considered also non-options. This is similar to the way
non-GNU Unix systems work.
*long_options*, if specified, must be a list of strings with the names of the
long options which should be supported. The leading ``'--'``
characters should not be included in the option name. Long options which
require an argument should be followed by an equal sign (``'='``). Optional
arguments are not supported. To accept only long options, *options* should
be an empty string. Long options on the command line can be recognized so
long as they provide a prefix of the option name that matches exactly one of
the accepted options. For example, if *long_options* is ``['foo', 'frob']``,
the option ``--fo`` will match as ``--foo``, but ``--f``
will not match uniquely, so :exc:`GetoptError` will be raised.
The return value consists of two elements: the first is a list of ``(option,
value)`` pairs; the second is the list of program arguments left after the
option list was stripped (this is a trailing slice of *args*). Each
option-and-value pair returned has the option as its first element, prefixed
with a hyphen for short options (e.g., ``'-x'``) or two hyphens for long
options (e.g., ``'--long-option'``), and the option argument as its
second element, or an empty string if the option has no argument. The
options occur in the list in the same order in which they were found, thus
allowing multiple occurrences. Long and short options may be mixed.
.. function:: gnu_getopt(args, options[, long_options])
This function works like :func:`getopt`, except that GNU style scanning mode is
used by default. This means that option and non-option arguments may be
intermixed. The :func:`getopt` function stops processing options as soon as a
non-option argument is encountered.
If the first character of the option string is ``'+'``, or if the environment
variable :envvar:`POSIXLY_CORRECT` is set, then option processing stops as
soon as a non-option argument is encountered.
.. versionadded:: 2.3
.. exception:: GetoptError
This is raised when an unrecognized option is found in the argument list or when
an option requiring an argument is given none. The argument to the exception is
a string indicating the cause of the error. For long options, an argument given
to an option which does not require one will also cause this exception to be
raised. The attributes :attr:`msg` and :attr:`opt` give the error message and
related option; if there is no specific option to which the exception relates,
:attr:`opt` is an empty string.
.. versionchanged:: 1.6
Introduced :exc:`GetoptError` as a synonym for :exc:`error`.
.. exception:: error
Alias for :exc:`GetoptError`; for backward compatibility.
An example using only Unix style options:
>>> import getopt
>>> args = '-a -b -cfoo -d bar a1 a2'.split()
>>> args
['-a', '-b', '-cfoo', '-d', 'bar', 'a1', 'a2']
>>> optlist, args = getopt.getopt(args, 'abc:d:')
>>> optlist
[('-a', ''), ('-b', ''), ('-c', 'foo'), ('-d', 'bar')]
>>> args
['a1', 'a2']
Using long option names is equally easy:
>>> s = '--condition=foo --testing --output-file abc.def -x a1 a2'
>>> args = s.split()
>>> args
['--condition=foo', '--testing', '--output-file', 'abc.def', '-x', 'a1', 'a2']
>>> optlist, args = getopt.getopt(args, 'x', [
... 'condition=', 'output-file=', 'testing'])
>>> optlist
[('--condition', 'foo'), ('--testing', ''), ('--output-file', 'abc.def'), ('-x', '')]
>>> args
['a1', 'a2']
In a script, typical usage is something like this::
import getopt, sys
def main():
try:
opts, args = getopt.getopt(sys.argv[1:], "ho:v", ["help", "output="])
except getopt.GetoptError as err:
# print help information and exit:
print str(err) # will print something like "option -a not recognized"
usage()
sys.exit(2)
output = None
verbose = False
for o, a in opts:
if o == "-v":
verbose = True
elif o in ("-h", "--help"):
usage()
sys.exit()
elif o in ("-o", "--output"):
output = a
else:
assert False, "unhandled option"
# ...
if __name__ == "__main__":
main()
Note that an equivalent command line interface could be produced with less code
and more informative help and error messages by using the :mod:`argparse` module::
import argparse
if __name__ == '__main__':
parser = argparse.ArgumentParser()
parser.add_argument('-o', '--output')
parser.add_argument('-v', dest='verbose', action='store_true')
args = parser.parse_args()
# ... do something with args.output ...
# ... do something with args.verbose ..
.. seealso::
Module :mod:`argparse`
Alternative command line option and argument parsing library.
PK %�\�~�T T % html/_sources/library/getpass.rst.txtnu �[��� :mod:`getpass` --- Portable password input
==========================================
.. module:: getpass
:synopsis: Portable reading of passwords and retrieval of the userid.
.. moduleauthor:: Piers Lauder <piers@cs.su.oz.au>
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
.. Windows (& Mac?) support by Guido van Rossum.
The :mod:`getpass` module provides two functions:
.. function:: getpass([prompt[, stream]])
Prompt the user for a password without echoing. The user is prompted using the
string *prompt*, which defaults to ``'Password: '``. On Unix, the prompt is
written to the file-like object *stream*. *stream* defaults to the
controlling terminal (/dev/tty) or if that is unavailable to ``sys.stderr``
(this argument is ignored on Windows).
If echo free input is unavailable getpass() falls back to printing
a warning message to *stream* and reading from ``sys.stdin`` and
issuing a :exc:`GetPassWarning`.
.. versionchanged:: 2.5
The *stream* parameter was added.
.. versionchanged:: 2.6
On Unix it defaults to using /dev/tty before falling back
to ``sys.stdin`` and ``sys.stderr``.
.. note::
If you call getpass from within IDLE, the input may be done in the
terminal you launched IDLE from rather than the idle window itself.
.. exception:: GetPassWarning
A :exc:`UserWarning` subclass issued when password input may be echoed.
.. function:: getuser()
Return the "login name" of the user.
This function checks the environment variables :envvar:`LOGNAME`,
:envvar:`USER`, :envvar:`LNAME` and :envvar:`USERNAME`, in order, and returns
the value of the first one which is set to a non-empty string. If none are set,
the login name from the password database is returned on systems which support
the :mod:`pwd` module, otherwise, an exception is raised.
PK %�\���&pq pq % html/_sources/library/gettext.rst.txtnu �[��� :mod:`gettext` --- Multilingual internationalization services
=============================================================
.. module:: gettext
:synopsis: Multilingual internationalization services.
.. moduleauthor:: Barry A. Warsaw <barry@zope.com>
.. sectionauthor:: Barry A. Warsaw <barry@zope.com>
**Source code:** :source:`Lib/gettext.py`
--------------
The :mod:`gettext` module provides internationalization (I18N) and localization
(L10N) services for your Python modules and applications. It supports both the
GNU ``gettext`` message catalog API and a higher level, class-based API that may
be more appropriate for Python files. The interface described below allows you
to write your module and application messages in one natural language, and
provide a catalog of translated messages for running under different natural
languages.
Some hints on localizing your Python modules and applications are also given.
GNU :program:`gettext` API
--------------------------
The :mod:`gettext` module defines the following API, which is very similar to
the GNU :program:`gettext` API. If you use this API you will affect the
translation of your entire application globally. Often this is what you want if
your application is monolingual, with the choice of language dependent on the
locale of your user. If you are localizing a Python module, or if your
application needs to switch languages on the fly, you probably want to use the
class-based API instead.
.. function:: bindtextdomain(domain[, localedir])
Bind the *domain* to the locale directory *localedir*. More concretely,
:mod:`gettext` will look for binary :file:`.mo` files for the given domain using
the path (on Unix): :file:`localedir/language/LC_MESSAGES/domain.mo`, where
*languages* is searched for in the environment variables :envvar:`LANGUAGE`,
:envvar:`LC_ALL`, :envvar:`LC_MESSAGES`, and :envvar:`LANG` respectively.
If *localedir* is omitted or ``None``, then the current binding for *domain* is
returned. [#]_
.. function:: bind_textdomain_codeset(domain[, codeset])
Bind the *domain* to *codeset*, changing the encoding of strings returned by the
:func:`gettext` family of functions. If *codeset* is omitted, then the current
binding is returned.
.. versionadded:: 2.4
.. function:: textdomain([domain])
Change or query the current global domain. If *domain* is ``None``, then the
current global domain is returned, otherwise the global domain is set to
*domain*, which is returned.
.. function:: gettext(message)
Return the localized translation of *message*, based on the current global
domain, language, and locale directory. This function is usually aliased as
:func:`_` in the local namespace (see examples below).
.. function:: lgettext(message)
Equivalent to :func:`gettext`, but the translation is returned in the preferred
system encoding, if no other encoding was explicitly set with
:func:`bind_textdomain_codeset`.
.. versionadded:: 2.4
.. function:: dgettext(domain, message)
Like :func:`gettext`, but look the message up in the specified *domain*.
.. function:: ldgettext(domain, message)
Equivalent to :func:`dgettext`, but the translation is returned in the preferred
system encoding, if no other encoding was explicitly set with
:func:`bind_textdomain_codeset`.
.. versionadded:: 2.4
.. function:: ngettext(singular, plural, n)
Like :func:`gettext`, but consider plural forms. If a translation is found,
apply the plural formula to *n*, and return the resulting message (some
languages have more than two plural forms). If no translation is found, return
*singular* if *n* is 1; return *plural* otherwise.
The Plural formula is taken from the catalog header. It is a C or Python
expression that has a free variable *n*; the expression evaluates to the index
of the plural in the catalog. See the GNU gettext documentation for the precise
syntax to be used in :file:`.po` files and the formulas for a variety of
languages.
.. versionadded:: 2.3
.. function:: lngettext(singular, plural, n)
Equivalent to :func:`ngettext`, but the translation is returned in the preferred
system encoding, if no other encoding was explicitly set with
:func:`bind_textdomain_codeset`.
.. versionadded:: 2.4
.. function:: dngettext(domain, singular, plural, n)
Like :func:`ngettext`, but look the message up in the specified *domain*.
.. versionadded:: 2.3
.. function:: ldngettext(domain, singular, plural, n)
Equivalent to :func:`dngettext`, but the translation is returned in the
preferred system encoding, if no other encoding was explicitly set with
:func:`bind_textdomain_codeset`.
.. versionadded:: 2.4
Note that GNU :program:`gettext` also defines a :func:`dcgettext` method, but
this was deemed not useful and so it is currently unimplemented.
Here's an example of typical usage for this API::
import gettext
gettext.bindtextdomain('myapplication', '/path/to/my/language/directory')
gettext.textdomain('myapplication')
_ = gettext.gettext
# ...
print _('This is a translatable string.')
Class-based API
---------------
The class-based API of the :mod:`gettext` module gives you more flexibility and
greater convenience than the GNU :program:`gettext` API. It is the recommended
way of localizing your Python applications and modules. :mod:`!gettext` defines
a "translations" class which implements the parsing of GNU :file:`.mo` format
files, and has methods for returning either standard 8-bit strings or Unicode
strings. Instances of this "translations" class can also install themselves in
the built-in namespace as the function :func:`_`.
.. function:: find(domain[, localedir[, languages[, all]]])
This function implements the standard :file:`.mo` file search algorithm. It
takes a *domain*, identical to what :func:`textdomain` takes. Optional
*localedir* is as in :func:`bindtextdomain` Optional *languages* is a list of
strings, where each string is a language code.
If *localedir* is not given, then the default system locale directory is used.
[#]_ If *languages* is not given, then the following environment variables are
searched: :envvar:`LANGUAGE`, :envvar:`LC_ALL`, :envvar:`LC_MESSAGES`, and
:envvar:`LANG`. The first one returning a non-empty value is used for the
*languages* variable. The environment variables should contain a colon separated
list of languages, which will be split on the colon to produce the expected list
of language code strings.
:func:`find` then expands and normalizes the languages, and then iterates
through them, searching for an existing file built of these components:
:file:`localedir/language/LC_MESSAGES/domain.mo`
The first such file name that exists is returned by :func:`find`. If no such
file is found, then ``None`` is returned. If *all* is given, it returns a list
of all file names, in the order in which they appear in the languages list or
the environment variables.
.. function:: translation(domain[, localedir[, languages[, class_[, fallback[, codeset]]]]])
Return a :class:`Translations` instance based on the *domain*, *localedir*, and
*languages*, which are first passed to :func:`find` to get a list of the
associated :file:`.mo` file paths. Instances with identical :file:`.mo` file
names are cached. The actual class instantiated is either *class_* if provided,
otherwise :class:`GNUTranslations`. The class's constructor must take a single
file object argument. If provided, *codeset* will change the charset used to
encode translated strings.
If multiple files are found, later files are used as fallbacks for earlier ones.
To allow setting the fallback, :func:`copy.copy` is used to clone each
translation object from the cache; the actual instance data is still shared with
the cache.
If no :file:`.mo` file is found, this function raises :exc:`IOError` if
*fallback* is false (which is the default), and returns a
:class:`NullTranslations` instance if *fallback* is true.
.. versionchanged:: 2.4
Added the *codeset* parameter.
.. function:: install(domain[, localedir[, unicode [, codeset[, names]]]])
This installs the function :func:`_` in Python's builtins namespace, based on
*domain*, *localedir*, and *codeset* which are passed to the function
:func:`translation`. The *unicode* flag is passed to the resulting translation
object's :meth:`~NullTranslations.install` method.
For the *names* parameter, please see the description of the translation
object's :meth:`~NullTranslations.install` method.
As seen below, you usually mark the strings in your application that are
candidates for translation, by wrapping them in a call to the :func:`_`
function, like this::
print _('This string will be translated.')
For convenience, you want the :func:`_` function to be installed in Python's
builtins namespace, so it is easily accessible in all modules of your
application.
.. versionchanged:: 2.4
Added the *codeset* parameter.
.. versionchanged:: 2.5
Added the *names* parameter.
The :class:`NullTranslations` class
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Translation classes are what actually implement the translation of original
source file message strings to translated message strings. The base class used
by all translation classes is :class:`NullTranslations`; this provides the basic
interface you can use to write your own specialized translation classes. Here
are the methods of :class:`!NullTranslations`:
.. class:: NullTranslations([fp])
Takes an optional file object *fp*, which is ignored by the base class.
Initializes "protected" instance variables *_info* and *_charset* which are set
by derived classes, as well as *_fallback*, which is set through
:meth:`add_fallback`. It then calls ``self._parse(fp)`` if *fp* is not
``None``.
.. method:: _parse(fp)
No-op'd in the base class, this method takes file object *fp*, and reads
the data from the file, initializing its message catalog. If you have an
unsupported message catalog file format, you should override this method
to parse your format.
.. method:: add_fallback(fallback)
Add *fallback* as the fallback object for the current translation
object. A translation object should consult the fallback if it cannot provide a
translation for a given message.
.. method:: gettext(message)
If a fallback has been set, forward :meth:`!gettext` to the
fallback. Otherwise, return the translated message. Overridden in derived
classes.
.. method:: lgettext(message)
If a fallback has been set, forward :meth:`!lgettext` to the
fallback. Otherwise, return the translated message. Overridden in derived
classes.
.. versionadded:: 2.4
.. method:: ugettext(message)
If a fallback has been set, forward :meth:`!ugettext` to the
fallback. Otherwise, return the translated message as a Unicode
string. Overridden in derived classes.
.. method:: ngettext(singular, plural, n)
If a fallback has been set, forward :meth:`!ngettext` to the
fallback. Otherwise, return the translated message. Overridden in derived
classes.
.. versionadded:: 2.3
.. method:: lngettext(singular, plural, n)
If a fallback has been set, forward :meth:`!lngettext` to the
fallback. Otherwise, return the translated message. Overridden in derived
classes.
.. versionadded:: 2.4
.. method:: ungettext(singular, plural, n)
If a fallback has been set, forward :meth:`!ungettext` to the fallback.
Otherwise, return the translated message as a Unicode string. Overridden
in derived classes.
.. versionadded:: 2.3
.. method:: info()
Return the "protected" :attr:`_info` variable.
.. method:: charset()
Return the "protected" :attr:`_charset` variable.
.. method:: output_charset()
Return the "protected" :attr:`_output_charset` variable, which defines the
encoding used to return translated messages.
.. versionadded:: 2.4
.. method:: set_output_charset(charset)
Change the "protected" :attr:`_output_charset` variable, which defines the
encoding used to return translated messages.
.. versionadded:: 2.4
.. method:: install([unicode [, names]])
If the *unicode* flag is false, this method installs :meth:`self.gettext`
into the built-in namespace, binding it to ``_``. If *unicode* is true,
it binds :meth:`self.ugettext` instead. By default, *unicode* is false.
If the *names* parameter is given, it must be a sequence containing the
names of functions you want to install in the builtins namespace in
addition to :func:`_`. Supported names are ``'gettext'`` (bound to
:meth:`self.gettext` or :meth:`self.ugettext` according to the *unicode*
flag), ``'ngettext'`` (bound to :meth:`self.ngettext` or
:meth:`self.ungettext` according to the *unicode* flag), ``'lgettext'``
and ``'lngettext'``.
Note that this is only one way, albeit the most convenient way, to make
the :func:`_` function available to your application. Because it affects
the entire application globally, and specifically the built-in namespace,
localized modules should never install :func:`_`. Instead, they should use
this code to make :func:`_` available to their module::
import gettext
t = gettext.translation('mymodule', ...)
_ = t.gettext
This puts :func:`_` only in the module's global namespace and so only
affects calls within this module.
.. versionchanged:: 2.5
Added the *names* parameter.
The :class:`GNUTranslations` class
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The :mod:`gettext` module provides one additional class derived from
:class:`NullTranslations`: :class:`GNUTranslations`. This class overrides
:meth:`_parse` to enable reading GNU :program:`gettext` format :file:`.mo` files
in both big-endian and little-endian format. It also coerces both message ids
and message strings to Unicode.
:class:`GNUTranslations` parses optional meta-data out of the translation
catalog. It is convention with GNU :program:`gettext` to include meta-data as
the translation for the empty string. This meta-data is in :rfc:`822`\ -style
``key: value`` pairs, and should contain the ``Project-Id-Version`` key. If the
key ``Content-Type`` is found, then the ``charset`` property is used to
initialize the "protected" :attr:`_charset` instance variable, defaulting to
``None`` if not found. If the charset encoding is specified, then all message
ids and message strings read from the catalog are converted to Unicode using
this encoding. The :meth:`ugettext` method always returns a Unicode, while the
:meth:`gettext` returns an encoded 8-bit string. For the message id arguments
of both methods, either Unicode strings or 8-bit strings containing only
US-ASCII characters are acceptable. Note that the Unicode version of the
methods (i.e. :meth:`ugettext` and :meth:`ungettext`) are the recommended
interface to use for internationalized Python programs.
The entire set of key/value pairs are placed into a dictionary and set as the
"protected" :attr:`_info` instance variable.
If the :file:`.mo` file's magic number is invalid, or if other problems occur
while reading the file, instantiating a :class:`GNUTranslations` class can raise
:exc:`IOError`.
The following methods are overridden from the base class implementation:
.. method:: GNUTranslations.gettext(message)
Look up the *message* id in the catalog and return the corresponding message
string, as an 8-bit string encoded with the catalog's charset encoding, if
known. If there is no entry in the catalog for the *message* id, and a fallback
has been set, the look up is forwarded to the fallback's :meth:`gettext` method.
Otherwise, the *message* id is returned.
.. method:: GNUTranslations.lgettext(message)
Equivalent to :meth:`gettext`, but the translation is returned in the preferred
system encoding, if no other encoding was explicitly set with
:meth:`set_output_charset`.
.. versionadded:: 2.4
.. method:: GNUTranslations.ugettext(message)
Look up the *message* id in the catalog and return the corresponding message
string, as a Unicode string. If there is no entry in the catalog for the
*message* id, and a fallback has been set, the look up is forwarded to the
fallback's :meth:`ugettext` method. Otherwise, the *message* id is returned.
.. method:: GNUTranslations.ngettext(singular, plural, n)
Do a plural-forms lookup of a message id. *singular* is used as the message id
for purposes of lookup in the catalog, while *n* is used to determine which
plural form to use. The returned message string is an 8-bit string encoded with
the catalog's charset encoding, if known.
If the message id is not found in the catalog, and a fallback is specified, the
request is forwarded to the fallback's :meth:`ngettext` method. Otherwise, when
*n* is 1 *singular* is returned, and *plural* is returned in all other cases.
.. versionadded:: 2.3
.. method:: GNUTranslations.lngettext(singular, plural, n)
Equivalent to :meth:`gettext`, but the translation is returned in the preferred
system encoding, if no other encoding was explicitly set with
:meth:`set_output_charset`.
.. versionadded:: 2.4
.. method:: GNUTranslations.ungettext(singular, plural, n)
Do a plural-forms lookup of a message id. *singular* is used as the message id
for purposes of lookup in the catalog, while *n* is used to determine which
plural form to use. The returned message string is a Unicode string.
If the message id is not found in the catalog, and a fallback is specified, the
request is forwarded to the fallback's :meth:`ungettext` method. Otherwise,
when *n* is 1 *singular* is returned, and *plural* is returned in all other
cases.
Here is an example::
n = len(os.listdir('.'))
cat = GNUTranslations(somefile)
message = cat.ungettext(
'There is %(num)d file in this directory',
'There are %(num)d files in this directory',
n) % {'num': n}
.. versionadded:: 2.3
Solaris message catalog support
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The Solaris operating system defines its own binary :file:`.mo` file format, but
since no documentation can be found on this format, it is not supported at this
time.
The Catalog constructor
^^^^^^^^^^^^^^^^^^^^^^^
.. index:: single: GNOME
GNOME uses a version of the :mod:`gettext` module by James Henstridge, but this
version has a slightly different API. Its documented usage was::
import gettext
cat = gettext.Catalog(domain, localedir)
_ = cat.gettext
print _('hello world')
For compatibility with this older module, the function :func:`Catalog` is an
alias for the :func:`translation` function described above.
One difference between this module and Henstridge's: his catalog objects
supported access through a mapping API, but this appears to be unused and so is
not currently supported.
Internationalizing your programs and modules
--------------------------------------------
Internationalization (I18N) refers to the operation by which a program is made
aware of multiple languages. Localization (L10N) refers to the adaptation of
your program, once internationalized, to the local language and cultural habits.
In order to provide multilingual messages for your Python programs, you need to
take the following steps:
#. prepare your program or module by specially marking translatable strings
#. run a suite of tools over your marked files to generate raw messages catalogs
#. create language specific translations of the message catalogs
#. use the :mod:`gettext` module so that message strings are properly translated
In order to prepare your code for I18N, you need to look at all the strings in
your files. Any string that needs to be translated should be marked by wrapping
it in ``_('...')`` --- that is, a call to the function :func:`_`. For example::
filename = 'mylog.txt'
message = _('writing a log message')
fp = open(filename, 'w')
fp.write(message)
fp.close()
In this example, the string ``'writing a log message'`` is marked as a candidate
for translation, while the strings ``'mylog.txt'`` and ``'w'`` are not.
The Python distribution comes with two tools which help you generate the message
catalogs once you've prepared your source code. These may or may not be
available from a binary distribution, but they can be found in a source
distribution, in the :file:`Tools/i18n` directory.
The :program:`pygettext` [#]_ program scans all your Python source code looking
for the strings you previously marked as translatable. It is similar to the GNU
:program:`gettext` program except that it understands all the intricacies of
Python source code, but knows nothing about C or C++ source code. You don't
need GNU ``gettext`` unless you're also going to be translating C code (such as
C extension modules).
:program:`pygettext` generates textual Uniforum-style human readable message
catalog :file:`.pot` files, essentially structured human readable files which
contain every marked string in the source code, along with a placeholder for the
translation strings. :program:`pygettext` is a command line script that supports
a similar command line interface as :program:`xgettext`; for details on its use,
run::
pygettext.py --help
Copies of these :file:`.pot` files are then handed over to the individual human
translators who write language-specific versions for every supported natural
language. They send you back the filled in language-specific versions as a
:file:`.po` file. Using the :program:`msgfmt.py` [#]_ program (in the
:file:`Tools/i18n` directory), you take the :file:`.po` files from your
translators and generate the machine-readable :file:`.mo` binary catalog files.
The :file:`.mo` files are what the :mod:`gettext` module uses for the actual
translation processing during run-time.
How you use the :mod:`gettext` module in your code depends on whether you are
internationalizing a single module or your entire application. The next two
sections will discuss each case.
Localizing your module
^^^^^^^^^^^^^^^^^^^^^^
If you are localizing your module, you must take care not to make global
changes, e.g. to the built-in namespace. You should not use the GNU ``gettext``
API but instead the class-based API.
Let's say your module is called "spam" and the module's various natural language
translation :file:`.mo` files reside in :file:`/usr/share/locale` in GNU
:program:`gettext` format. Here's what you would put at the top of your
module::
import gettext
t = gettext.translation('spam', '/usr/share/locale')
_ = t.lgettext
If your translators were providing you with Unicode strings in their :file:`.po`
files, you'd instead do::
import gettext
t = gettext.translation('spam', '/usr/share/locale')
_ = t.ugettext
Localizing your application
^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you are localizing your application, you can install the :func:`_` function
globally into the built-in namespace, usually in the main driver file of your
application. This will let all your application-specific files just use
``_('...')`` without having to explicitly install it in each file.
In the simple case then, you need only add the following bit of code to the main
driver file of your application::
import gettext
gettext.install('myapplication')
If you need to set the locale directory or the *unicode* flag, you can pass
these into the :func:`install` function::
import gettext
gettext.install('myapplication', '/usr/share/locale', unicode=1)
Changing languages on the fly
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If your program needs to support many languages at the same time, you may want
to create multiple translation instances and then switch between them
explicitly, like so::
import gettext
lang1 = gettext.translation('myapplication', languages=['en'])
lang2 = gettext.translation('myapplication', languages=['fr'])
lang3 = gettext.translation('myapplication', languages=['de'])
# start by using language1
lang1.install()
# ... time goes by, user selects language 2
lang2.install()
# ... more time goes by, user selects language 3
lang3.install()
Deferred translations
^^^^^^^^^^^^^^^^^^^^^
In most coding situations, strings are translated where they are coded.
Occasionally however, you need to mark strings for translation, but defer actual
translation until later. A classic example is::
animals = ['mollusk',
'albatross',
'rat',
'penguin',
'python', ]
# ...
for a in animals:
print a
Here, you want to mark the strings in the ``animals`` list as being
translatable, but you don't actually want to translate them until they are
printed.
Here is one way you can handle this situation::
def _(message): return message
animals = [_('mollusk'),
_('albatross'),
_('rat'),
_('penguin'),
_('python'), ]
del _
# ...
for a in animals:
print _(a)
This works because the dummy definition of :func:`_` simply returns the string
unchanged. And this dummy definition will temporarily override any definition
of :func:`_` in the built-in namespace (until the :keyword:`del` command). Take
care, though if you have a previous definition of :func:`_` in the local
namespace.
Note that the second use of :func:`_` will not identify "a" as being
translatable to the :program:`pygettext` program, since it is not a string.
Another way to handle this is with the following example::
def N_(message): return message
animals = [N_('mollusk'),
N_('albatross'),
N_('rat'),
N_('penguin'),
N_('python'), ]
# ...
for a in animals:
print _(a)
In this case, you are marking translatable strings with the function :func:`N_`,
[#]_ which won't conflict with any definition of :func:`_`. However, you will
need to teach your message extraction program to look for translatable strings
marked with :func:`N_`. :program:`pygettext` and :program:`xpot` both support
this through the use of command line switches.
:func:`gettext` vs. :func:`lgettext`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In Python 2.4 the :func:`lgettext` family of functions were introduced. The
intention of these functions is to provide an alternative which is more
compliant with the current implementation of GNU gettext. Unlike
:func:`gettext`, which returns strings encoded with the same codeset used in the
translation file, :func:`lgettext` will return strings encoded with the
preferred system encoding, as returned by :func:`locale.getpreferredencoding`.
Also notice that Python 2.4 introduces new functions to explicitly choose the
codeset used in translated strings. If a codeset is explicitly set, even
:func:`lgettext` will return translated strings in the requested codeset, as
would be expected in the GNU gettext implementation.
Acknowledgements
----------------
The following people contributed code, feedback, design suggestions, previous
implementations, and valuable experience to the creation of this module:
* Peter Funk
* James Henstridge
* Juan David Ibáñez Palomar
* Marc-André Lemburg
* Martin von Löwis
* François Pinard
* Barry Warsaw
* Gustavo Niemeyer
.. rubric:: Footnotes
.. [#] The default locale directory is system dependent; for example, on RedHat Linux
it is :file:`/usr/share/locale`, but on Solaris it is :file:`/usr/lib/locale`.
The :mod:`gettext` module does not try to support these system dependent
defaults; instead its default is :file:`sys.prefix/share/locale`. For this
reason, it is always best to call :func:`bindtextdomain` with an explicit
absolute path at the start of your application.
.. [#] See the footnote for :func:`bindtextdomain` above.
.. [#] François Pinard has written a program called :program:`xpot` which does a
similar job. It is available as part of his
`po-utils package <https://github.com/pinard/po-utils>`__.
.. [#] :program:`msgfmt.py` is binary compatible with GNU :program:`msgfmt` except that
it provides a simpler, all-Python implementation. With this and
:program:`pygettext.py`, you generally won't need to install the GNU
:program:`gettext` package to internationalize your Python applications.
.. [#] The choice of :func:`N_` here is totally arbitrary; it could have just as easily
been :func:`MarkThisStringForTranslation`.
PK %�\��y y html/_sources/library/gl.rst.txtnu �[��� :mod:`gl` --- *Graphics Library* interface
==========================================
.. module:: gl
:platform: IRIX
:synopsis: Functions from the Silicon Graphics Graphics Library.
:deprecated:
.. deprecated:: 2.6
The :mod:`gl` module has been removed in Python 3.
This module provides access to the Silicon Graphics *Graphics Library*. It is
available only on Silicon Graphics machines.
.. warning::
Some illegal calls to the GL library cause the Python interpreter to dump
core. In particular, the use of most GL calls is unsafe before the first
window is opened.
The module is too large to document here in its entirety, but the following
should help you to get started. The parameter conventions for the C functions
are translated to Python as follows:
* All (short, long, unsigned) int values are represented by Python integers.
* All float and double values are represented by Python floating point numbers.
In most cases, Python integers are also allowed.
* All arrays are represented by one-dimensional Python lists. In most cases,
tuples are also allowed.
* All string and character arguments are represented by Python strings, for
instance, ``winopen('Hi There!')`` and ``rotate(900, 'z')``.
* All (short, long, unsigned) integer arguments or return values that are only
used to specify the length of an array argument are omitted. For example, the C
call ::
lmdef(deftype, index, np, props)
is translated to Python as ::
lmdef(deftype, index, props)
* Output arguments are omitted from the argument list; they are transmitted as
function return values instead. If more than one value must be returned, the
return value is a tuple. If the C function has both a regular return value (that
is not omitted because of the previous rule) and an output argument, the return
value comes first in the tuple. Examples: the C call ::
getmcolor(i, &red, &green, &blue)
is translated to Python as ::
red, green, blue = getmcolor(i)
The following functions are non-standard or have special argument conventions:
.. function:: varray(argument)
Equivalent to but faster than a number of ``v3d()`` calls. The *argument* is a
list (or tuple) of points. Each point must be a tuple of coordinates ``(x, y,
z)`` or ``(x, y)``. The points may be 2- or 3-dimensional but must all have the
same dimension. Float and int values may be mixed however. The points are always
converted to 3D double precision points by assuming ``z = 0.0`` if necessary (as
indicated in the man page), and for each point ``v3d()`` is called.
.. XXX the argument-argument added
.. function:: nvarray()
Equivalent to but faster than a number of ``n3f`` and ``v3f`` calls. The
argument is an array (list or tuple) of pairs of normals and points. Each pair
is a tuple of a point and a normal for that point. Each point or normal must be
a tuple of coordinates ``(x, y, z)``. Three coordinates must be given. Float and
int values may be mixed. For each pair, ``n3f()`` is called for the normal, and
then ``v3f()`` is called for the point.
.. function:: vnarray()
Similar to ``nvarray()`` but the pairs have the point first and the normal
second.
.. function:: nurbssurface(s_k, t_k, ctl, s_ord, t_ord, type)
Defines a nurbs surface. The dimensions of ``ctl[][]`` are computed as follows:
``[len(s_k) - s_ord]``, ``[len(t_k) - t_ord]``.
.. XXX s_k[], t_k[], ctl[][]
.. function:: nurbscurve(knots, ctlpoints, order, type)
Defines a nurbs curve. The length of ctlpoints is ``len(knots) - order``.
.. function:: pwlcurve(points, type)
Defines a piecewise-linear curve. *points* is a list of points. *type* must be
``N_ST``.
.. function:: pick(n)
select(n)
The only argument to these functions specifies the desired size of the pick or
select buffer.
.. function:: endpick()
endselect()
These functions have no arguments. They return a list of integers representing
the used part of the pick/select buffer. No method is provided to detect buffer
overrun.
Here is a tiny but complete example GL program in Python::
import gl, GL, time
def main():
gl.foreground()
gl.prefposition(500, 900, 500, 900)
w = gl.winopen('CrissCross')
gl.ortho2(0.0, 400.0, 0.0, 400.0)
gl.color(GL.WHITE)
gl.clear()
gl.color(GL.RED)
gl.bgnline()
gl.v2f(0.0, 0.0)
gl.v2f(400.0, 400.0)
gl.endline()
gl.bgnline()
gl.v2f(400.0, 0.0)
gl.v2f(0.0, 400.0)
gl.endline()
time.sleep(5)
main()
.. seealso::
`PyOpenGL: The Python OpenGL Binding <http://pyopengl.sourceforge.net/>`_
.. index::
single: OpenGL
single: PyOpenGL
An interface to OpenGL is also available; see information about the **PyOpenGL**
project online at http://pyopengl.sourceforge.net/. This may be a better option
if support for SGI hardware from before about 1996 is not required.
:mod:`DEVICE` --- Constants used with the :mod:`gl` module
==========================================================
.. module:: DEVICE
:platform: IRIX
:synopsis: Constants used with the gl module.
:deprecated:
.. deprecated:: 2.6
The :mod:`DEVICE` module has been removed in Python 3.
This modules defines the constants used by the Silicon Graphics *Graphics
Library* that C programmers find in the header file ``<gl/device.h>``. Read the
module source file for details.
:mod:`GL` --- Constants used with the :mod:`gl` module
======================================================
.. module:: GL
:platform: IRIX
:synopsis: Constants used with the gl module.
:deprecated:
.. deprecated:: 2.6
The :mod:`GL` module has been removed in Python 3.
This module contains constants used by the Silicon Graphics *Graphics Library*
from the C header file ``<gl/gl.h>``. Read the module source file for details.
PK %�\Jյ n n " html/_sources/library/glob.rst.txtnu �[��� :mod:`glob` --- Unix style pathname pattern expansion
=====================================================
.. module:: glob
:synopsis: Unix shell style pathname pattern expansion.
.. index:: single: filenames; pathname expansion
**Source code:** :source:`Lib/glob.py`
--------------
The :mod:`glob` module finds all the pathnames matching a specified pattern
according to the rules used by the Unix shell, although results are returned in
arbitrary order. No tilde expansion is done, but ``*``, ``?``, and character
ranges expressed with ``[]`` will be correctly matched. This is done by using
the :func:`os.listdir` and :func:`fnmatch.fnmatch` functions in concert, and
not by actually invoking a subshell. Note that unlike :func:`fnmatch.fnmatch`,
:mod:`glob` treats filenames beginning with a dot (``.``) as special cases.
(For tilde and shell variable expansion, use :func:`os.path.expanduser` and
:func:`os.path.expandvars`.)
For a literal match, wrap the meta-characters in brackets.
For example, ``'[?]'`` matches the character ``'?'``.
.. function:: glob(pathname)
Return a possibly-empty list of path names that match *pathname*, which must be
a string containing a path specification. *pathname* can be either absolute
(like :file:`/usr/src/Python-1.5/Makefile`) or relative (like
:file:`../../Tools/\*/\*.gif`), and can contain shell-style wildcards. Broken
symlinks are included in the results (as in the shell).
.. function:: iglob(pathname)
Return an :term:`iterator` which yields the same values as :func:`glob`
without actually storing them all simultaneously.
.. versionadded:: 2.5
For example, consider a directory containing only the following files:
:file:`1.gif`, :file:`2.txt`, and :file:`card.gif`. :func:`glob` will produce
the following results. Notice how any leading components of the path are
preserved. ::
>>> import glob
>>> glob.glob('./[0-9].*')
['./1.gif', './2.txt']
>>> glob.glob('*.gif')
['1.gif', 'card.gif']
>>> glob.glob('?.gif')
['1.gif']
If the directory contains files starting with ``.`` they won't be matched by
default. For example, consider a directory containing :file:`card.gif` and
:file:`.card.gif`::
>>> import glob
>>> glob.glob('*.gif')
['card.gif']
>>> glob.glob('.c*')
['.card.gif']
.. seealso::
Module :mod:`fnmatch`
Shell-style filename (not path) expansion
PK %�\4)T6� � ! html/_sources/library/grp.rst.txtnu �[���
:mod:`grp` --- The group database
=================================
.. module:: grp
:platform: Unix
:synopsis: The group database (getgrnam() and friends).
This module provides access to the Unix group database. It is available on all
Unix versions.
Group database entries are reported as a tuple-like object, whose attributes
correspond to the members of the ``group`` structure (Attribute field below, see
``<pwd.h>``):
+-------+-----------+---------------------------------+
| Index | Attribute | Meaning |
+=======+===========+=================================+
| 0 | gr_name | the name of the group |
+-------+-----------+---------------------------------+
| 1 | gr_passwd | the (encrypted) group password; |
| | | often empty |
+-------+-----------+---------------------------------+
| 2 | gr_gid | the numerical group ID |
+-------+-----------+---------------------------------+
| 3 | gr_mem | all the group member's user |
| | | names |
+-------+-----------+---------------------------------+
The gid is an integer, name and password are strings, and the member list is a
list of strings. (Note that most users are not explicitly listed as members of
the group they are in according to the password database. Check both databases
to get complete membership information. Also note that a ``gr_name`` that
starts with a ``+`` or ``-`` is likely to be a YP/NIS reference and may not be
accessible via :func:`getgrnam` or :func:`getgrgid`.)
It defines the following items:
.. function:: getgrgid(gid)
Return the group database entry for the given numeric group ID. :exc:`KeyError`
is raised if the entry asked for cannot be found.
.. function:: getgrnam(name)
Return the group database entry for the given group name. :exc:`KeyError` is
raised if the entry asked for cannot be found.
.. function:: getgrall()
Return a list of all available group entries, in arbitrary order.
.. seealso::
Module :mod:`pwd`
An interface to the user database, similar to this.
Module :mod:`spwd`
An interface to the shadow password database, similar to this.
PK %�\J���� � " html/_sources/library/gzip.rst.txtnu �[��� :mod:`gzip` --- Support for :program:`gzip` files
=================================================
.. module:: gzip
:synopsis: Interfaces for gzip compression and decompression using file objects.
**Source code:** :source:`Lib/gzip.py`
--------------
This module provides a simple interface to compress and decompress files just
like the GNU programs :program:`gzip` and :program:`gunzip` would.
The data compression is provided by the :mod:`zlib` module.
The :mod:`gzip` module provides the :class:`GzipFile` class which is modeled
after Python's File Object. The :class:`GzipFile` class reads and writes
:program:`gzip`\ -format files, automatically compressing or decompressing the
data so that it looks like an ordinary file object.
Note that additional file formats which can be decompressed by the
:program:`gzip` and :program:`gunzip` programs, such as those produced by
:program:`compress` and :program:`pack`, are not supported by this module.
The module defines the following items:
.. class:: GzipFile([filename[, mode[, compresslevel[, fileobj[, mtime]]]]])
Constructor for the :class:`GzipFile` class, which simulates most of the methods
of a file object, with the exception of the :meth:`readinto` and
:meth:`truncate` methods. At least one of *fileobj* and *filename* must be
given a non-trivial value.
The new class instance is based on *fileobj*, which can be a regular file, a
:class:`~StringIO.StringIO` object, or any other object which simulates a file. It
defaults to ``None``, in which case *filename* is opened to provide a file
object.
When *fileobj* is not ``None``, the *filename* argument is only used to be
included in the :program:`gzip` file header, which may include the original
filename of the uncompressed file. It defaults to the filename of *fileobj*, if
discernible; otherwise, it defaults to the empty string, and in this case the
original filename is not included in the header.
The *mode* argument can be any of ``'r'``, ``'rb'``, ``'a'``, ``'ab'``, ``'w'``,
or ``'wb'``, depending on whether the file will be read or written. The default
is the mode of *fileobj* if discernible; otherwise, the default is ``'rb'``. If
not given, the 'b' flag will be added to the mode to ensure the file is opened
in binary mode for cross-platform portability.
The *compresslevel* argument is an integer from ``0`` to ``9`` controlling
the level of compression; ``1`` is fastest and produces the least
compression, and ``9`` is slowest and produces the most compression. ``0``
is no compression. The default is ``9``.
The *mtime* argument is an optional numeric timestamp to be written to
the stream when compressing. All :program:`gzip` compressed streams are
required to contain a timestamp. If omitted or ``None``, the current
time is used. This module ignores the timestamp when decompressing;
however, some programs, such as :program:`gunzip`\ , make use of it.
The format of the timestamp is the same as that of the return value of
``time.time()`` and of the ``st_mtime`` attribute of the object returned
by ``os.stat()``.
Calling a :class:`GzipFile` object's :meth:`close` method does not close
*fileobj*, since you might wish to append more material after the compressed
data. This also allows you to pass a :class:`~StringIO.StringIO` object opened for
writing as *fileobj*, and retrieve the resulting memory buffer using the
:class:`~StringIO.StringIO` object's :meth:`~StringIO.StringIO.getvalue` method.
:class:`GzipFile` supports iteration and the :keyword:`with` statement.
.. versionchanged:: 2.7
Support for the :keyword:`with` statement was added.
.. versionchanged:: 2.7
Support for zero-padded files was added.
.. versionadded:: 2.7
The *mtime* argument.
.. function:: open(filename[, mode[, compresslevel]])
This is a shorthand for ``GzipFile(filename,`` ``mode,`` ``compresslevel)``.
The *filename* argument is required; *mode* defaults to ``'rb'`` and
*compresslevel* defaults to ``9``.
.. _gzip-usage-examples:
Examples of usage
-----------------
Example of how to read a compressed file::
import gzip
with gzip.open('file.txt.gz', 'rb') as f:
file_content = f.read()
Example of how to create a compressed GZIP file::
import gzip
content = "Lots of content here"
with gzip.open('file.txt.gz', 'wb') as f:
f.write(content)
Example of how to GZIP compress an existing file::
import gzip
import shutil
with open('file.txt', 'rb') as f_in, gzip.open('file.txt.gz', 'wb') as f_out:
shutil.copyfileobj(f_in, f_out)
.. seealso::
Module :mod:`zlib`
The basic data compression module needed to support the :program:`gzip` file
format.
PK %�\&�� � � % html/_sources/library/hashlib.rst.txtnu �[��� :mod:`hashlib` --- Secure hashes and message digests
====================================================
.. module:: hashlib
:synopsis: Secure hash and message digest algorithms.
.. moduleauthor:: Gregory P. Smith <greg@krypto.org>
.. sectionauthor:: Gregory P. Smith <greg@krypto.org>
.. versionadded:: 2.5
.. index::
single: message digest, MD5
single: secure hash algorithm, SHA1, SHA224, SHA256, SHA384, SHA512
**Source code:** :source:`Lib/hashlib.py`
--------------
This module implements a common interface to many different secure hash and
message digest algorithms. Included are the FIPS secure hash algorithms SHA1,
SHA224, SHA256, SHA384, and SHA512 (defined in FIPS 180-2) as well as RSA's MD5
algorithm (defined in Internet :rfc:`1321`). The terms secure hash and message
digest are interchangeable. Older algorithms were called message digests. The
modern term is secure hash.
.. note::
If you want the adler32 or crc32 hash functions, they are available in
the :mod:`zlib` module.
.. warning::
Some algorithms have known hash collision weaknesses, refer to the "See
also" section at the end.
There is one constructor method named for each type of :dfn:`hash`. All return
a hash object with the same simple interface. For example: use :func:`sha1` to
create a SHA1 hash object. You can now feed this object with arbitrary strings
using the :meth:`update` method. At any point you can ask it for the
:dfn:`digest` of the concatenation of the strings fed to it so far using the
:meth:`digest` or :meth:`hexdigest` methods.
.. index:: single: OpenSSL; (use in module hashlib)
Constructors for hash algorithms that are always present in this module are
:func:`md5`, :func:`sha1`, :func:`sha224`, :func:`sha256`, :func:`sha384`, and
:func:`sha512`. Additional algorithms may also be available depending upon the
OpenSSL library that Python uses on your platform.
For example, to obtain the digest of the string ``'Nobody inspects the spammish
repetition'``:
>>> import hashlib
>>> m = hashlib.md5()
>>> m.update("Nobody inspects")
>>> m.update(" the spammish repetition")
>>> m.digest()
'\xbbd\x9c\x83\xdd\x1e\xa5\xc9\xd9\xde\xc9\xa1\x8d\xf0\xff\xe9'
>>> m.digest_size
16
>>> m.block_size
64
More condensed:
>>> hashlib.sha224("Nobody inspects the spammish repetition").hexdigest()
'a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2'
A generic :func:`new` constructor that takes the string name of the desired
algorithm as its first parameter also exists to allow access to the above listed
hashes as well as any other algorithms that your OpenSSL library may offer. The
named constructors are much faster than :func:`new` and should be preferred.
Using :func:`new` with an algorithm provided by OpenSSL:
>>> h = hashlib.new('ripemd160')
>>> h.update("Nobody inspects the spammish repetition")
>>> h.hexdigest()
'cc4a5ce1b3df48aec5d22d1f16b894a0b894eccc'
This module provides the following constant attribute:
.. data:: hashlib.algorithms
A tuple providing the names of the hash algorithms guaranteed to be
supported by this module.
.. versionadded:: 2.7
.. data:: algorithms_guaranteed
A set containing the names of the hash algorithms guaranteed to be supported
by this module on all platforms.
.. versionadded:: 2.7.9
.. data:: algorithms_available
A set containing the names of the hash algorithms that are available in the
running Python interpreter. These names will be recognized when passed to
:func:`new`. :attr:`algorithms_guaranteed` will always be a subset. The
same algorithm may appear multiple times in this set under different names
(thanks to OpenSSL).
.. versionadded:: 2.7.9
The following values are provided as constant attributes of the hash objects
returned by the constructors:
.. data:: hash.digest_size
The size of the resulting hash in bytes.
.. data:: hash.block_size
The internal block size of the hash algorithm in bytes.
A hash object has the following methods:
.. method:: hash.update(arg)
Update the hash object with the string *arg*. Repeated calls are equivalent to
a single call with the concatenation of all the arguments: ``m.update(a);
m.update(b)`` is equivalent to ``m.update(a+b)``.
.. versionchanged:: 2.7
The Python GIL is released to allow other threads to run while
hash updates on data larger than 2048 bytes is taking place when
using hash algorithms supplied by OpenSSL.
.. method:: hash.digest()
Return the digest of the strings passed to the :meth:`update` method so far.
This is a string of :attr:`digest_size` bytes which may contain non-ASCII
characters, including null bytes.
.. method:: hash.hexdigest()
Like :meth:`digest` except the digest is returned as a string of double length,
containing only hexadecimal digits. This may be used to exchange the value
safely in email or other non-binary environments.
.. method:: hash.copy()
Return a copy ("clone") of the hash object. This can be used to efficiently
compute the digests of strings that share a common initial substring.
Key derivation
--------------
Key derivation and key stretching algorithms are designed for secure password
hashing. Naive algorithms such as ``sha1(password)`` are not resistant against
brute-force attacks. A good password hashing function must be tunable, slow, and
include a `salt <https://en.wikipedia.org/wiki/Salt_%28cryptography%29>`_.
.. function:: pbkdf2_hmac(name, password, salt, rounds, dklen=None)
The function provides PKCS#5 password-based key derivation function 2. It
uses HMAC as pseudorandom function.
The string *name* is the desired name of the hash digest algorithm for
HMAC, e.g. 'sha1' or 'sha256'. *password* and *salt* are interpreted as
buffers of bytes. Applications and libraries should limit *password* to
a sensible value (e.g. 1024). *salt* should be about 16 or more bytes from
a proper source, e.g. :func:`os.urandom`.
The number of *rounds* should be chosen based on the hash algorithm and
computing power. As of 2013, at least 100,000 rounds of SHA-256 is suggested.
*dklen* is the length of the derived key. If *dklen* is ``None`` then the
digest size of the hash algorithm *name* is used, e.g. 64 for SHA-512.
>>> import hashlib, binascii
>>> dk = hashlib.pbkdf2_hmac('sha256', b'password', b'salt', 100000)
>>> binascii.hexlify(dk)
b'0394a2ede332c9a13eb82e9b24631604c31df978b4e2f0fbd2c549944f9d79a5'
.. versionadded:: 2.7.8
.. note::
A fast implementation of *pbkdf2_hmac* is available with OpenSSL. The
Python implementation uses an inline version of :mod:`hmac`. It is about
three times slower and doesn't release the GIL.
.. seealso::
Module :mod:`hmac`
A module to generate message authentication codes using hashes.
Module :mod:`base64`
Another way to encode binary hashes for non-binary environments.
http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf
The FIPS 180-2 publication on Secure Hash Algorithms.
https://en.wikipedia.org/wiki/Cryptographic_hash_function#Cryptographic_hash_algorithms
Wikipedia article with information on which algorithms have known issues and
what that means regarding their use.
PK %�\�a�́3 �3 # html/_sources/library/heapq.rst.txtnu �[��� :mod:`heapq` --- Heap queue algorithm
=====================================
.. module:: heapq
:synopsis: Heap queue algorithm (a.k.a. priority queue).
.. moduleauthor:: Kevin O'Connor
.. sectionauthor:: Guido van Rossum <guido@python.org>
.. sectionauthor:: François Pinard
.. sectionauthor:: Raymond Hettinger
.. versionadded:: 2.3
**Source code:** :source:`Lib/heapq.py`
--------------
This module provides an implementation of the heap queue algorithm, also known
as the priority queue algorithm.
Heaps are binary trees for which every parent node has a value less than or
equal to any of its children. This implementation uses arrays for which
``heap[k] <= heap[2*k+1]`` and ``heap[k] <= heap[2*k+2]`` for all *k*, counting
elements from zero. For the sake of comparison, non-existing elements are
considered to be infinite. The interesting property of a heap is that its
smallest element is always the root, ``heap[0]``.
The API below differs from textbook heap algorithms in two aspects: (a) We use
zero-based indexing. This makes the relationship between the index for a node
and the indexes for its children slightly less obvious, but is more suitable
since Python uses zero-based indexing. (b) Our pop method returns the smallest
item, not the largest (called a "min heap" in textbooks; a "max heap" is more
common in texts because of its suitability for in-place sorting).
These two make it possible to view the heap as a regular Python list without
surprises: ``heap[0]`` is the smallest item, and ``heap.sort()`` maintains the
heap invariant!
To create a heap, use a list initialized to ``[]``, or you can transform a
populated list into a heap via function :func:`heapify`.
The following functions are provided:
.. function:: heappush(heap, item)
Push the value *item* onto the *heap*, maintaining the heap invariant.
.. function:: heappop(heap)
Pop and return the smallest item from the *heap*, maintaining the heap
invariant. If the heap is empty, :exc:`IndexError` is raised. To access the
smallest item without popping it, use ``heap[0]``.
.. function:: heappushpop(heap, item)
Push *item* on the heap, then pop and return the smallest item from the
*heap*. The combined action runs more efficiently than :func:`heappush`
followed by a separate call to :func:`heappop`.
.. versionadded:: 2.6
.. function:: heapify(x)
Transform list *x* into a heap, in-place, in linear time.
.. function:: heapreplace(heap, item)
Pop and return the smallest item from the *heap*, and also push the new *item*.
The heap size doesn't change. If the heap is empty, :exc:`IndexError` is raised.
This one step operation is more efficient than a :func:`heappop` followed by
:func:`heappush` and can be more appropriate when using a fixed-size heap.
The pop/push combination always returns an element from the heap and replaces
it with *item*.
The value returned may be larger than the *item* added. If that isn't
desired, consider using :func:`heappushpop` instead. Its push/pop
combination returns the smaller of the two values, leaving the larger value
on the heap.
The module also offers three general purpose functions based on heaps.
.. function:: merge(*iterables)
Merge multiple sorted inputs into a single sorted output (for example, merge
timestamped entries from multiple log files). Returns an :term:`iterator`
over the sorted values.
Similar to ``sorted(itertools.chain(*iterables))`` but returns an iterable, does
not pull the data into memory all at once, and assumes that each of the input
streams is already sorted (smallest to largest).
.. versionadded:: 2.6
.. function:: nlargest(n, iterable[, key])
Return a list with the *n* largest elements from the dataset defined by
*iterable*. *key*, if provided, specifies a function of one argument that is
used to extract a comparison key from each element in the iterable:
``key=str.lower`` Equivalent to: ``sorted(iterable, key=key,
reverse=True)[:n]``
.. versionadded:: 2.4
.. versionchanged:: 2.5
Added the optional *key* argument.
.. function:: nsmallest(n, iterable[, key])
Return a list with the *n* smallest elements from the dataset defined by
*iterable*. *key*, if provided, specifies a function of one argument that is
used to extract a comparison key from each element in the iterable:
``key=str.lower`` Equivalent to: ``sorted(iterable, key=key)[:n]``
.. versionadded:: 2.4
.. versionchanged:: 2.5
Added the optional *key* argument.
The latter two functions perform best for smaller values of *n*. For larger
values, it is more efficient to use the :func:`sorted` function. Also, when
``n==1``, it is more efficient to use the built-in :func:`min` and :func:`max`
functions. If repeated usage of these functions is required, consider turning
the iterable into an actual heap.
Basic Examples
--------------
A `heapsort <https://en.wikipedia.org/wiki/Heapsort>`_ can be implemented by
pushing all values onto a heap and then popping off the smallest values one at a
time::
>>> def heapsort(iterable):
... h = []
... for value in iterable:
... heappush(h, value)
... return [heappop(h) for i in range(len(h))]
...
>>> heapsort([1, 3, 5, 7, 9, 2, 4, 6, 8, 0])
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
This is similar to ``sorted(iterable)``, but unlike :func:`sorted`, this
implementation is not stable.
Heap elements can be tuples. This is useful for assigning comparison values
(such as task priorities) alongside the main record being tracked::
>>> h = []
>>> heappush(h, (5, 'write code'))
>>> heappush(h, (7, 'release product'))
>>> heappush(h, (1, 'write spec'))
>>> heappush(h, (3, 'create tests'))
>>> heappop(h)
(1, 'write spec')
Priority Queue Implementation Notes
-----------------------------------
A `priority queue <https://en.wikipedia.org/wiki/Priority_queue>`_ is common use
for a heap, and it presents several implementation challenges:
* Sort stability: how do you get two tasks with equal priorities to be returned
in the order they were originally added?
* In the future with Python 3, tuple comparison breaks for (priority, task)
pairs if the priorities are equal and the tasks do not have a default
comparison order.
* If the priority of a task changes, how do you move it to a new position in
the heap?
* Or if a pending task needs to be deleted, how do you find it and remove it
from the queue?
A solution to the first two challenges is to store entries as 3-element list
including the priority, an entry count, and the task. The entry count serves as
a tie-breaker so that two tasks with the same priority are returned in the order
they were added. And since no two entry counts are the same, the tuple
comparison will never attempt to directly compare two tasks.
The remaining challenges revolve around finding a pending task and making
changes to its priority or removing it entirely. Finding a task can be done
with a dictionary pointing to an entry in the queue.
Removing the entry or changing its priority is more difficult because it would
break the heap structure invariants. So, a possible solution is to mark the
existing entry as removed and add a new entry with the revised priority::
pq = [] # list of entries arranged in a heap
entry_finder = {} # mapping of tasks to entries
REMOVED = '<removed-task>' # placeholder for a removed task
counter = itertools.count() # unique sequence count
def add_task(task, priority=0):
'Add a new task or update the priority of an existing task'
if task in entry_finder:
remove_task(task)
count = next(counter)
entry = [priority, count, task]
entry_finder[task] = entry
heappush(pq, entry)
def remove_task(task):
'Mark an existing task as REMOVED. Raise KeyError if not found.'
entry = entry_finder.pop(task)
entry[-1] = REMOVED
def pop_task():
'Remove and return the lowest priority task. Raise KeyError if empty.'
while pq:
priority, count, task = heappop(pq)
if task is not REMOVED:
del entry_finder[task]
return task
raise KeyError('pop from an empty priority queue')
Theory
------
Heaps are arrays for which ``a[k] <= a[2*k+1]`` and ``a[k] <= a[2*k+2]`` for all
*k*, counting elements from 0. For the sake of comparison, non-existing
elements are considered to be infinite. The interesting property of a heap is
that ``a[0]`` is always its smallest element.
The strange invariant above is meant to be an efficient memory representation
for a tournament. The numbers below are *k*, not ``a[k]``::
0
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
In the tree above, each cell *k* is topping ``2*k+1`` and ``2*k+2``. In a usual
binary tournament we see in sports, each cell is the winner over the two cells
it tops, and we can trace the winner down the tree to see all opponents s/he
had. However, in many computer applications of such tournaments, we do not need
to trace the history of a winner. To be more memory efficient, when a winner is
promoted, we try to replace it by something else at a lower level, and the rule
becomes that a cell and the two cells it tops contain three different items, but
the top cell "wins" over the two topped cells.
If this heap invariant is protected at all time, index 0 is clearly the overall
winner. The simplest algorithmic way to remove it and find the "next" winner is
to move some loser (let's say cell 30 in the diagram above) into the 0 position,
and then percolate this new 0 down the tree, exchanging values, until the
invariant is re-established. This is clearly logarithmic on the total number of
items in the tree. By iterating over all items, you get an O(n log n) sort.
A nice feature of this sort is that you can efficiently insert new items while
the sort is going on, provided that the inserted items are not "better" than the
last 0'th element you extracted. This is especially useful in simulation
contexts, where the tree holds all incoming events, and the "win" condition
means the smallest scheduled time. When an event schedules other events for
execution, they are scheduled into the future, so they can easily go into the
heap. So, a heap is a good structure for implementing schedulers (this is what
I used for my MIDI sequencer :-).
Various structures for implementing schedulers have been extensively studied,
and heaps are good for this, as they are reasonably speedy, the speed is almost
constant, and the worst case is not much different than the average case.
However, there are other representations which are more efficient overall, yet
the worst cases might be terrible.
Heaps are also very useful in big disk sorts. You most probably all know that a
big sort implies producing "runs" (which are pre-sorted sequences, whose size is
usually related to the amount of CPU memory), followed by a merging passes for
these runs, which merging is often very cleverly organised [#]_. It is very
important that the initial sort produces the longest runs possible. Tournaments
are a good way to achieve that. If, using all the memory available to hold a
tournament, you replace and percolate items that happen to fit the current run,
you'll produce runs which are twice the size of the memory for random input, and
much better for input fuzzily ordered.
Moreover, if you output the 0'th item on disk and get an input which may not fit
in the current tournament (because the value "wins" over the last output value),
it cannot fit in the heap, so the size of the heap decreases. The freed memory
could be cleverly reused immediately for progressively building a second heap,
which grows at exactly the same rate the first heap is melting. When the first
heap completely vanishes, you switch heaps and start a new run. Clever and
quite effective!
In a word, heaps are useful memory structures to know. I use them in a few
applications, and I think it is good to keep a 'heap' module around. :-)
.. rubric:: Footnotes
.. [#] The disk balancing algorithms which are current, nowadays, are more annoying
than clever, and this is a consequence of the seeking capabilities of the disks.
On devices which cannot seek, like big tape drives, the story was quite
different, and one had to be very clever to ensure (far in advance) that each
tape movement will be the most effective possible (that is, will best
participate at "progressing" the merge). Some tapes were even able to read
backwards, and this was also used to avoid the rewinding time. Believe me, real
good tape sorts were quite spectacular to watch! From all times, sorting has
always been a Great Art! :-)
PK %�\
���79 79 " html/_sources/library/2to3.rst.txtnu �[��� .. _2to3-reference:
2to3 - Automated Python 2 to 3 code translation
===============================================
.. sectionauthor:: Benjamin Peterson <benjamin@python.org>
2to3 is a Python program that reads Python 2.x source code and applies a series
of *fixers* to transform it into valid Python 3.x code. The standard library
contains a rich set of fixers that will handle almost all code. 2to3 supporting
library :mod:`lib2to3` is, however, a flexible and generic library, so it is
possible to write your own fixers for 2to3. :mod:`lib2to3` could also be
adapted to custom applications in which Python code needs to be edited
automatically.
.. _2to3-using:
Using 2to3
----------
2to3 will usually be installed with the Python interpreter as a script. It is
also located in the :file:`Tools/scripts` directory of the Python root.
2to3's basic arguments are a list of files or directories to transform. The
directories are recursively traversed for Python sources.
Here is a sample Python 2.x source file, :file:`example.py`::
def greet(name):
print "Hello, {0}!".format(name)
print "What's your name?"
name = raw_input()
greet(name)
It can be converted to Python 3.x code via 2to3 on the command line:
.. code-block:: shell-session
$ 2to3 example.py
A diff against the original source file is printed. 2to3 can also write the
needed modifications right back to the source file. (A backup of the original
file is made unless :option:`!-n` is also given.) Writing the changes back is
enabled with the :option:`!-w` flag:
.. code-block:: shell-session
$ 2to3 -w example.py
After transformation, :file:`example.py` looks like this::
def greet(name):
print("Hello, {0}!".format(name))
print("What's your name?")
name = input()
greet(name)
Comments and exact indentation are preserved throughout the translation process.
By default, 2to3 runs a set of :ref:`predefined fixers <2to3-fixers>`. The
:option:`!-l` flag lists all available fixers. An explicit set of fixers to run
can be given with :option:`!-f`. Likewise the :option:`!-x` explicitly disables a
fixer. The following example runs only the ``imports`` and ``has_key`` fixers:
.. code-block:: shell-session
$ 2to3 -f imports -f has_key example.py
This command runs every fixer except the ``apply`` fixer:
.. code-block:: shell-session
$ 2to3 -x apply example.py
Some fixers are *explicit*, meaning they aren't run by default and must be
listed on the command line to be run. Here, in addition to the default fixers,
the ``idioms`` fixer is run:
.. code-block:: shell-session
$ 2to3 -f all -f idioms example.py
Notice how passing ``all`` enables all default fixers.
Sometimes 2to3 will find a place in your source code that needs to be changed,
but 2to3 cannot fix automatically. In this case, 2to3 will print a warning
beneath the diff for a file. You should address the warning in order to have
compliant 3.x code.
2to3 can also refactor doctests. To enable this mode, use the :option:`!-d`
flag. Note that *only* doctests will be refactored. This also doesn't require
the module to be valid Python. For example, doctest like examples in a reST
document could also be refactored with this option.
The :option:`!-v` option enables output of more information on the translation
process.
Since some print statements can be parsed as function calls or statements, 2to3
cannot always read files containing the print function. When 2to3 detects the
presence of the ``from __future__ import print_function`` compiler directive, it
modifies its internal grammar to interpret :func:`print` as a function. This
change can also be enabled manually with the :option:`!-p` flag. Use
:option:`!-p` to run fixers on code that already has had its print statements
converted.
The :option:`!-o` or :option:`!--output-dir` option allows specification of an
alternate directory for processed output files to be written to. The
:option:`!-n` flag is required when using this as backup files do not make sense
when not overwriting the input files.
.. versionadded:: 2.7.3
The :option:`!-o` option was added.
The :option:`!-W` or :option:`!--write-unchanged-files` flag tells 2to3 to always
write output files even if no changes were required to the file. This is most
useful with :option:`!-o` so that an entire Python source tree is copied with
translation from one directory to another.
This option implies the :option:`!-w` flag as it would not make sense otherwise.
.. versionadded:: 2.7.3
The :option:`!-W` flag was added.
The :option:`!--add-suffix` option specifies a string to append to all output
filenames. The :option:`!-n` flag is required when specifying this as backups
are not necessary when writing to different filenames. Example:
.. code-block:: shell-session
$ 2to3 -n -W --add-suffix=3 example.py
Will cause a converted file named ``example.py3`` to be written.
.. versionadded:: 2.7.3
The :option:`!--add-suffix` option was added.
To translate an entire project from one directory tree to another use:
.. code-block:: shell-session
$ 2to3 --output-dir=python3-version/mycode -W -n python2-version/mycode
.. _2to3-fixers:
Fixers
------
Each step of transforming code is encapsulated in a fixer. The command ``2to3
-l`` lists them. As :ref:`documented above <2to3-using>`, each can be turned on
and off individually. They are described here in more detail.
.. 2to3fixer:: apply
Removes usage of :func:`apply`. For example ``apply(function, *args,
**kwargs)`` is converted to ``function(*args, **kwargs)``.
.. 2to3fixer:: asserts
Replaces deprecated :mod:`unittest` method names with the correct ones.
================================ ==========================================
From To
================================ ==========================================
``failUnlessEqual(a, b)`` :meth:`assertEqual(a, b)
<unittest.TestCase.assertEqual>`
``assertEquals(a, b)`` :meth:`assertEqual(a, b)
<unittest.TestCase.assertEqual>`
``failIfEqual(a, b)`` :meth:`assertNotEqual(a, b)
<unittest.TestCase.assertNotEqual>`
``assertNotEquals(a, b)`` :meth:`assertNotEqual(a, b)
<unittest.TestCase.assertNotEqual>`
``failUnless(a)`` :meth:`assertTrue(a)
<unittest.TestCase.assertTrue>`
``assert_(a)`` :meth:`assertTrue(a)
<unittest.TestCase.assertTrue>`
``failIf(a)`` :meth:`assertFalse(a)
<unittest.TestCase.assertFalse>`
``failUnlessRaises(exc, cal)`` :meth:`assertRaises(exc, cal)
<unittest.TestCase.assertRaises>`
``failUnlessAlmostEqual(a, b)`` :meth:`assertAlmostEqual(a, b)
<unittest.TestCase.assertAlmostEqual>`
``assertAlmostEquals(a, b)`` :meth:`assertAlmostEqual(a, b)
<unittest.TestCase.assertAlmostEqual>`
``failIfAlmostEqual(a, b)`` :meth:`assertNotAlmostEqual(a, b)
<unittest.TestCase.assertNotAlmostEqual>`
``assertNotAlmostEquals(a, b)`` :meth:`assertNotAlmostEqual(a, b)
<unittest.TestCase.assertNotAlmostEqual>`
================================ ==========================================
.. 2to3fixer:: basestring
Converts :class:`basestring` to :class:`str`.
.. 2to3fixer:: buffer
Converts :class:`buffer` to :class:`memoryview`. This fixer is optional
because the :class:`memoryview` API is similar but not exactly the same as
that of :class:`buffer`.
.. 2to3fixer:: dict
Fixes dictionary iteration methods. :meth:`dict.iteritems` is converted to
:meth:`dict.items`, :meth:`dict.iterkeys` to :meth:`dict.keys`, and
:meth:`dict.itervalues` to :meth:`dict.values`. Similarly,
:meth:`dict.viewitems`, :meth:`dict.viewkeys` and :meth:`dict.viewvalues` are
converted respectively to :meth:`dict.items`, :meth:`dict.keys` and
:meth:`dict.values`. It also wraps existing usages of :meth:`dict.items`,
:meth:`dict.keys`, and :meth:`dict.values` in a call to :class:`list`.
.. 2to3fixer:: except
Converts ``except X, T`` to ``except X as T``.
.. 2to3fixer:: exec
Converts the :keyword:`exec` statement to the :func:`exec` function.
.. 2to3fixer:: execfile
Removes usage of :func:`execfile`. The argument to :func:`execfile` is
wrapped in calls to :func:`open`, :func:`compile`, and :func:`exec`.
.. 2to3fixer:: exitfunc
Changes assignment of :attr:`sys.exitfunc` to use of the :mod:`atexit`
module.
.. 2to3fixer:: filter
Wraps :func:`filter` usage in a :class:`list` call.
.. 2to3fixer:: funcattrs
Fixes function attributes that have been renamed. For example,
``my_function.func_closure`` is converted to ``my_function.__closure__``.
.. 2to3fixer:: future
Removes ``from __future__ import new_feature`` statements.
.. 2to3fixer:: getcwdu
Renames :func:`os.getcwdu` to :func:`os.getcwd`.
.. 2to3fixer:: has_key
Changes ``dict.has_key(key)`` to ``key in dict``.
.. 2to3fixer:: idioms
This optional fixer performs several transformations that make Python code
more idiomatic. Type comparisons like ``type(x) is SomeClass`` and
``type(x) == SomeClass`` are converted to ``isinstance(x, SomeClass)``.
``while 1`` becomes ``while True``. This fixer also tries to make use of
:func:`sorted` in appropriate places. For example, this block ::
L = list(some_iterable)
L.sort()
is changed to ::
L = sorted(some_iterable)
.. 2to3fixer:: import
Detects sibling imports and converts them to relative imports.
.. 2to3fixer:: imports
Handles module renames in the standard library.
.. 2to3fixer:: imports2
Handles other modules renames in the standard library. It is separate from
the :2to3fixer:`imports` fixer only because of technical limitations.
.. 2to3fixer:: input
Converts ``input(prompt)`` to ``eval(input(prompt))``.
.. 2to3fixer:: intern
Converts :func:`intern` to :func:`sys.intern`.
.. 2to3fixer:: isinstance
Fixes duplicate types in the second argument of :func:`isinstance`. For
example, ``isinstance(x, (int, int))`` is converted to ``isinstance(x,
(int))``.
.. 2to3fixer:: itertools_imports
Removes imports of :func:`itertools.ifilter`, :func:`itertools.izip`, and
:func:`itertools.imap`. Imports of :func:`itertools.ifilterfalse` are also
changed to :func:`itertools.filterfalse`.
.. 2to3fixer:: itertools
Changes usage of :func:`itertools.ifilter`, :func:`itertools.izip`, and
:func:`itertools.imap` to their built-in equivalents.
:func:`itertools.ifilterfalse` is changed to :func:`itertools.filterfalse`.
.. 2to3fixer:: long
Renames :class:`long` to :class:`int`.
.. 2to3fixer:: map
Wraps :func:`map` in a :class:`list` call. It also changes ``map(None, x)``
to ``list(x)``. Using ``from future_builtins import map`` disables this
fixer.
.. 2to3fixer:: metaclass
Converts the old metaclass syntax (``__metaclass__ = Meta`` in the class
body) to the new (``class X(metaclass=Meta)``).
.. 2to3fixer:: methodattrs
Fixes old method attribute names. For example, ``meth.im_func`` is converted
to ``meth.__func__``.
.. 2to3fixer:: ne
Converts the old not-equal syntax, ``<>``, to ``!=``.
.. 2to3fixer:: next
Converts the use of iterator's :meth:`~iterator.next` methods to the
:func:`next` function. It also renames :meth:`~iterator.next` methods to
:meth:`~iterator.__next__`.
.. 2to3fixer:: nonzero
Renames :meth:`__nonzero__` to :meth:`~object.__bool__`.
.. 2to3fixer:: numliterals
Converts octal literals into the new syntax.
.. 2to3fixer:: paren
Add extra parenthesis where they are required in list comprehensions. For
example, ``[x for x in 1, 2]`` becomes ``[x for x in (1, 2)]``.
.. 2to3fixer:: print
Converts the :keyword:`print` statement to the :func:`print` function.
.. 2to3fixer:: raise
Converts ``raise E, V`` to ``raise E(V)``, and ``raise E, V, T`` to ``raise
E(V).with_traceback(T)``. If ``E`` is a tuple, the translation will be
incorrect because substituting tuples for exceptions has been removed in Python 3.
.. 2to3fixer:: raw_input
Converts :func:`raw_input` to :func:`input`.
.. 2to3fixer:: reduce
Handles the move of :func:`reduce` to :func:`functools.reduce`.
.. 2to3fixer:: renames
Changes :data:`sys.maxint` to :data:`sys.maxsize`.
.. 2to3fixer:: repr
Replaces backtick repr with the :func:`repr` function.
.. 2to3fixer:: set_literal
Replaces use of the :class:`set` constructor with set literals. This fixer
is optional.
.. 2to3fixer:: standarderror
Renames :exc:`StandardError` to :exc:`Exception`.
.. 2to3fixer:: sys_exc
Changes the deprecated :data:`sys.exc_value`, :data:`sys.exc_type`,
:data:`sys.exc_traceback` to use :func:`sys.exc_info`.
.. 2to3fixer:: throw
Fixes the API change in generator's :meth:`throw` method.
.. 2to3fixer:: tuple_params
Removes implicit tuple parameter unpacking. This fixer inserts temporary
variables.
.. 2to3fixer:: types
Fixes code broken from the removal of some members in the :mod:`types`
module.
.. 2to3fixer:: unicode
Renames :class:`unicode` to :class:`str`.
.. 2to3fixer:: urllib
Handles the rename of :mod:`urllib` and :mod:`urllib2` to the :mod:`urllib`
package.
.. 2to3fixer:: ws_comma
Removes excess whitespace from comma separated items. This fixer is
optional.
.. 2to3fixer:: xrange
Renames :func:`xrange` to :func:`range` and wraps existing :func:`range`
calls with :class:`list`.
.. 2to3fixer:: xreadlines
Changes ``for x in file.xreadlines()`` to ``for x in file``.
.. 2to3fixer:: zip
Wraps :func:`zip` usage in a :class:`list` call. This is disabled when
``from future_builtins import zip`` appears.
:mod:`lib2to3` - 2to3's library
-------------------------------
.. module:: lib2to3
:synopsis: the 2to3 library
.. moduleauthor:: Guido van Rossum
.. moduleauthor:: Collin Winter
.. moduleauthor:: Benjamin Peterson <benjamin@python.org>
.. note::
The :mod:`lib2to3` API should be considered unstable and may change
drastically in the future.
.. XXX What is the public interface anyway?
PK %�\L�6� " html/_sources/library/hmac.rst.txtnu �[��� :mod:`hmac` --- Keyed-Hashing for Message Authentication
========================================================
.. module:: hmac
:synopsis: Keyed-Hashing for Message Authentication (HMAC) implementation
.. moduleauthor:: Gerhard Häring <ghaering@users.sourceforge.net>
.. sectionauthor:: Gerhard Häring <ghaering@users.sourceforge.net>
.. versionadded:: 2.2
**Source code:** :source:`Lib/hmac.py`
--------------
This module implements the HMAC algorithm as described by :rfc:`2104`.
.. function:: new(key[, msg[, digestmod]])
Return a new hmac object. If *msg* is present, the method call ``update(msg)``
is made. *digestmod* is the digest constructor or module for the HMAC object to
use. It defaults to the :data:`hashlib.md5` constructor.
An HMAC object has the following methods:
.. method:: HMAC.update(msg)
Update the hmac object with the string *msg*. Repeated calls are equivalent to
a single call with the concatenation of all the arguments: ``m.update(a);
m.update(b)`` is equivalent to ``m.update(a + b)``.
.. method:: HMAC.digest()
Return the digest of the strings passed to the :meth:`update` method so far.
This string will be the same length as the *digest_size* of the digest given to
the constructor. It may contain non-ASCII characters, including NUL bytes.
.. warning::
When comparing the output of :meth:`digest` to an externally-supplied
digest during a verification routine, it is recommended to use the
:func:`compare_digest` function instead of the ``==`` operator
to reduce the vulnerability to timing attacks.
.. method:: HMAC.hexdigest()
Like :meth:`digest` except the digest is returned as a string twice the length
containing only hexadecimal digits. This may be used to exchange the value
safely in email or other non-binary environments.
.. warning::
When comparing the output of :meth:`hexdigest` to an externally-supplied
digest during a verification routine, it is recommended to use the
:func:`compare_digest` function instead of the ``==`` operator
to reduce the vulnerability to timing attacks.
.. method:: HMAC.copy()
Return a copy ("clone") of the hmac object. This can be used to efficiently
compute the digests of strings that share a common initial substring.
This module also provides the following helper function:
.. function:: compare_digest(a, b)
Return ``a == b``. This function uses an approach designed to prevent
timing analysis by avoiding content-based short circuiting behaviour,
making it appropriate for cryptography. *a* and *b* must both be of the
same type: either :class:`unicode` or a :term:`bytes-like object`.
.. note::
If *a* and *b* are of different lengths, or if an error occurs,
a timing attack could theoretically reveal information about the
types and lengths of *a* and *b*—but not their values.
.. versionadded:: 2.7.7
.. seealso::
Module :mod:`hashlib`
The Python module providing secure hash functions.
PK %�\��� � % html/_sources/library/hotshot.rst.txtnu �[���
:mod:`hotshot` --- High performance logging profiler
====================================================
.. module:: hotshot
:synopsis: High performance logging profiler, mostly written in C.
.. moduleauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
.. sectionauthor:: Anthony Baxter <anthony@interlink.com.au>
.. versionadded:: 2.2
This module provides a nicer interface to the :mod:`_hotshot` C module. Hotshot
is a replacement for the existing :mod:`profile` module. As it's written mostly
in C, it should result in a much smaller performance impact than the existing
:mod:`profile` module.
.. note::
The :mod:`hotshot` module focuses on minimizing the overhead while profiling, at
the expense of long data post-processing times. For common usage it is
recommended to use :mod:`cProfile` instead. :mod:`hotshot` is not maintained and
might be removed from the standard library in the future.
.. versionchanged:: 2.5
The results should be more meaningful than in the past: the timing core
contained a critical bug.
.. note::
The :mod:`hotshot` profiler does not yet work well with threads. It is useful to
use an unthreaded script to run the profiler over the code you're interested in
measuring if at all possible.
.. class:: Profile(logfile[, lineevents[, linetimings]])
The profiler object. The argument *logfile* is the name of a log file to use for
logged profile data. The argument *lineevents* specifies whether to generate
events for every source line, or just on function call/return. It defaults to
``0`` (only log function call/return). The argument *linetimings* specifies
whether to record timing information. It defaults to ``1`` (store timing
information).
.. _hotshot-objects:
Profile Objects
---------------
Profile objects have the following methods:
.. method:: Profile.addinfo(key, value)
Add an arbitrary labelled value to the profile output.
.. method:: Profile.close()
Close the logfile and terminate the profiler.
.. method:: Profile.fileno()
Return the file descriptor of the profiler's log file.
.. method:: Profile.run(cmd)
Profile an :keyword:`exec`\ -compatible string in the script environment. The
globals from the :mod:`__main__` module are used as both the globals and locals
for the script.
.. method:: Profile.runcall(func, *args, **keywords)
Profile a single call of a callable. Additional positional and keyword arguments
may be passed along; the result of the call is returned, and exceptions are
allowed to propagate cleanly, while ensuring that profiling is disabled on the
way out.
.. method:: Profile.runctx(cmd, globals, locals)
Evaluate an :keyword:`exec`\ -compatible string in a specific environment. The
string is compiled before profiling begins.
.. method:: Profile.start()
Start the profiler.
.. method:: Profile.stop()
Stop the profiler.
Using hotshot data
------------------
.. module:: hotshot.stats
:synopsis: Statistical analysis for Hotshot
.. versionadded:: 2.2
This module loads hotshot profiling data into the standard :mod:`pstats` Stats
objects.
.. function:: load(filename)
Load hotshot data from *filename*. Returns an instance of the
:class:`pstats.Stats` class.
.. seealso::
Module :mod:`profile`
The :mod:`profile` module's :class:`Stats` class
.. _hotshot-example:
Example Usage
-------------
Note that this example runs the Python "benchmark" pystones. It can take some
time to run, and will produce large output files. ::
>>> import hotshot, hotshot.stats, test.pystone
>>> prof = hotshot.Profile("stones.prof")
>>> benchtime, stones = prof.runcall(test.pystone.pystones)
>>> prof.close()
>>> stats = hotshot.stats.load("stones.prof")
>>> stats.strip_dirs()
>>> stats.sort_stats('time', 'calls')
>>> stats.print_stats(20)
850004 function calls in 10.090 CPU seconds
Ordered by: internal time, call count
ncalls tottime percall cumtime percall filename:lineno(function)
1 3.295 3.295 10.090 10.090 pystone.py:79(Proc0)
150000 1.315 0.000 1.315 0.000 pystone.py:203(Proc7)
50000 1.313 0.000 1.463 0.000 pystone.py:229(Func2)
.
.
.
PK %�\
8�� � % html/_sources/library/htmllib.rst.txtnu �[��� :mod:`htmllib` --- A parser for HTML documents
==============================================
.. module:: htmllib
:synopsis: A parser for HTML documents.
:deprecated:
.. deprecated:: 2.6
The :mod:`htmllib` module has been removed in Python 3.
Use :mod:`HTMLParser` instead in Python 2, and the equivalent,
:mod:`html.parser`, in Python 3.
.. index::
single: HTML
single: hypertext
.. index::
module: sgmllib
module: formatter
single: SGMLParser (in module sgmllib)
This module defines a class which can serve as a base for parsing text files
formatted in the HyperText Mark-up Language (HTML). The class is not directly
concerned with I/O --- it must be provided with input in string form via a
method, and makes calls to methods of a "formatter" object in order to produce
output. The :class:`~HTMLParser.HTMLParser` class is designed to be used as a base class
for other classes in order to add functionality, and allows most of its methods
to be extended or overridden. In turn, this class is derived from and extends
the :class:`SGMLParser` class defined in module :mod:`sgmllib`. The
:class:`~HTMLParser.HTMLParser` implementation supports the HTML 2.0 language as described
in :rfc:`1866`. Two implementations of formatter objects are provided in the
:mod:`formatter` module; refer to the documentation for that module for
information on the formatter interface.
The following is a summary of the interface defined by
:class:`sgmllib.SGMLParser`:
* The interface to feed data to an instance is through the :meth:`feed` method,
which takes a string argument. This can be called with as little or as much
text at a time as desired; ``p.feed(a); p.feed(b)`` has the same effect as
``p.feed(a+b)``. When the data contains complete HTML markup constructs, these
are processed immediately; incomplete constructs are saved in a buffer. To
force processing of all unprocessed data, call the :meth:`close` method.
For example, to parse the entire contents of a file, use::
parser.feed(open('myfile.html').read())
parser.close()
* The interface to define semantics for HTML tags is very simple: derive a class
and define methods called :meth:`start_tag`, :meth:`end_tag`, or :meth:`do_tag`.
The parser will call these at appropriate moments: :meth:`start_tag` or
:meth:`do_tag` is called when an opening tag of the form ``<tag ...>`` is
encountered; :meth:`end_tag` is called when a closing tag of the form ``<tag>``
is encountered. If an opening tag requires a corresponding closing tag, like
``<H1>`` ... ``</H1>``, the class should define the :meth:`start_tag` method; if
a tag requires no closing tag, like ``<P>``, the class should define the
:meth:`do_tag` method.
The module defines a parser class and an exception:
.. class:: HTMLParser(formatter)
This is the basic HTML parser class. It supports all entity names required by
the XHTML 1.0 Recommendation (https://www.w3.org/TR/xhtml1). It also defines
handlers for all HTML 2.0 and many HTML 3.0 and 3.2 elements.
.. exception:: HTMLParseError
Exception raised by the :class:`~HTMLParser.HTMLParser` class when it encounters an error
while parsing.
.. versionadded:: 2.4
.. seealso::
Module :mod:`formatter`
Interface definition for transforming an abstract flow of formatting events into
specific output events on writer objects.
Module :mod:`HTMLParser`
Alternate HTML parser that offers a slightly lower-level view of the input, but
is designed to work with XHTML, and does not implement some of the SGML syntax
not used in "HTML as deployed" and which isn't legal for XHTML.
Module :mod:`htmlentitydefs`
Definition of replacement text for XHTML 1.0 entities.
Module :mod:`sgmllib`
Base class for :class:`~HTMLParser.HTMLParser`.
.. _html-parser-objects:
HTMLParser Objects
------------------
In addition to tag methods, the :class:`~HTMLParser.HTMLParser` class provides some
additional methods and instance variables for use within tag methods.
.. attribute:: HTMLParser.formatter
This is the formatter instance associated with the parser.
.. attribute:: HTMLParser.nofill
Boolean flag which should be true when whitespace should not be collapsed, or
false when it should be. In general, this should only be true when character
data is to be treated as "preformatted" text, as within a ``<PRE>`` element.
The default value is false. This affects the operation of :meth:`handle_data`
and :meth:`save_end`.
.. method:: HTMLParser.anchor_bgn(href, name, type)
This method is called at the start of an anchor region. The arguments
correspond to the attributes of the ``<A>`` tag with the same names. The
default implementation maintains a list of hyperlinks (defined by the ``HREF``
attribute for ``<A>`` tags) within the document. The list of hyperlinks is
available as the data attribute :attr:`anchorlist`.
.. method:: HTMLParser.anchor_end()
This method is called at the end of an anchor region. The default
implementation adds a textual footnote marker using an index into the list of
hyperlinks created by :meth:`anchor_bgn`.
.. method:: HTMLParser.handle_image(source, alt[, ismap[, align[, width[, height]]]])
This method is called to handle images. The default implementation simply
passes the *alt* value to the :meth:`handle_data` method.
.. method:: HTMLParser.save_bgn()
Begins saving character data in a buffer instead of sending it to the formatter
object. Retrieve the stored data via :meth:`save_end`. Use of the
:meth:`save_bgn` / :meth:`save_end` pair may not be nested.
.. method:: HTMLParser.save_end()
Ends buffering character data and returns all data saved since the preceding
call to :meth:`save_bgn`. If the :attr:`nofill` flag is false, whitespace is
collapsed to single spaces. A call to this method without a preceding call to
:meth:`save_bgn` will raise a :exc:`TypeError` exception.
:mod:`htmlentitydefs` --- Definitions of HTML general entities
==============================================================
.. module:: htmlentitydefs
:synopsis: Definitions of HTML general entities.
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
.. note::
The :mod:`htmlentitydefs` module has been renamed to :mod:`html.entities` in
Python 3. The :term:`2to3` tool will automatically adapt imports when
converting your sources to Python 3.
**Source code:** :source:`Lib/htmlentitydefs.py`
--------------
This module defines three dictionaries, ``name2codepoint``, ``codepoint2name``,
and ``entitydefs``. ``entitydefs`` is used by the :mod:`htmllib` module to
provide the :attr:`entitydefs` attribute of the :class:`~HTMLParser.HTMLParser` class. The
definition provided here contains all the entities defined by XHTML 1.0 that
can be handled using simple textual substitution in the Latin-1 character set
(ISO-8859-1).
.. data:: entitydefs
A dictionary mapping XHTML 1.0 entity definitions to their replacement text in
ISO Latin-1.
.. data:: name2codepoint
A dictionary that maps HTML entity names to the Unicode code points.
.. versionadded:: 2.3
.. data:: codepoint2name
A dictionary that maps Unicode code points to HTML entity names.
.. versionadded:: 2.3
PK %�\ �h�x- x- ( html/_sources/library/htmlparser.rst.txtnu �[���
:mod:`HTMLParser` --- Simple HTML and XHTML parser
==================================================
.. module:: HTMLParser
:synopsis: A simple parser that can handle HTML and XHTML.
.. note::
The :mod:`HTMLParser` module has been renamed to :mod:`html.parser` in Python
3. The :term:`2to3` tool will automatically adapt imports when converting
your sources to Python 3.
.. versionadded:: 2.2
.. index::
single: HTML
single: XHTML
**Source code:** :source:`Lib/HTMLParser.py`
--------------
This module defines a class :class:`.HTMLParser` which serves as the basis for
parsing text files formatted in HTML (HyperText Mark-up Language) and XHTML.
Unlike the parser in :mod:`htmllib`, this parser is not based on the SGML parser
in :mod:`sgmllib`.
.. class:: HTMLParser()
An :class:`.HTMLParser` instance is fed HTML data and calls handler methods
when start tags, end tags, text, comments, and other markup elements are
encountered. The user should subclass :class:`.HTMLParser` and override its
methods to implement the desired behavior.
The :class:`.HTMLParser` class is instantiated without arguments.
Unlike the parser in :mod:`htmllib`, this parser does not check that end tags
match start tags or call the end-tag handler for elements which are closed
implicitly by closing an outer element.
An exception is defined as well:
.. exception:: HTMLParseError
:class:`.HTMLParser` is able to handle broken markup, but in some cases it
might raise this exception when it encounters an error while parsing.
This exception provides three attributes: :attr:`msg` is a brief
message explaining the error, :attr:`lineno` is the number of the line on
which the broken construct was detected, and :attr:`offset` is the number of
characters into the line at which the construct starts.
Example HTML Parser Application
-------------------------------
As a basic example, below is a simple HTML parser that uses the
:class:`.HTMLParser` class to print out start tags, end tags and data
as they are encountered::
from HTMLParser import HTMLParser
# create a subclass and override the handler methods
class MyHTMLParser(HTMLParser):
def handle_starttag(self, tag, attrs):
print "Encountered a start tag:", tag
def handle_endtag(self, tag):
print "Encountered an end tag :", tag
def handle_data(self, data):
print "Encountered some data :", data
# instantiate the parser and fed it some HTML
parser = MyHTMLParser()
parser.feed('<html><head><title>Test</title></head>'
'<body><h1>Parse me!</h1></body></html>')
The output will then be:
.. code-block:: none
Encountered a start tag: html
Encountered a start tag: head
Encountered a start tag: title
Encountered some data : Test
Encountered an end tag : title
Encountered an end tag : head
Encountered a start tag: body
Encountered a start tag: h1
Encountered some data : Parse me!
Encountered an end tag : h1
Encountered an end tag : body
Encountered an end tag : html
:class:`.HTMLParser` Methods
----------------------------
:class:`.HTMLParser` instances have the following methods:
.. method:: HTMLParser.feed(data)
Feed some text to the parser. It is processed insofar as it consists of
complete elements; incomplete data is buffered until more data is fed or
:meth:`close` is called. *data* can be either :class:`unicode` or
:class:`str`, but passing :class:`unicode` is advised.
.. method:: HTMLParser.close()
Force processing of all buffered data as if it were followed by an end-of-file
mark. This method may be redefined by a derived class to define additional
processing at the end of the input, but the redefined version should always call
the :class:`.HTMLParser` base class method :meth:`close`.
.. method:: HTMLParser.reset()
Reset the instance. Loses all unprocessed data. This is called implicitly at
instantiation time.
.. method:: HTMLParser.getpos()
Return current line number and offset.
.. method:: HTMLParser.get_starttag_text()
Return the text of the most recently opened start tag. This should not normally
be needed for structured processing, but may be useful in dealing with HTML "as
deployed" or for re-generating input with minimal changes (whitespace between
attributes can be preserved, etc.).
The following methods are called when data or markup elements are encountered
and they are meant to be overridden in a subclass. The base class
implementations do nothing (except for :meth:`~HTMLParser.handle_startendtag`):
.. method:: HTMLParser.handle_starttag(tag, attrs)
This method is called to handle the start of a tag (e.g. ``<div id="main">``).
The *tag* argument is the name of the tag converted to lower case. The *attrs*
argument is a list of ``(name, value)`` pairs containing the attributes found
inside the tag's ``<>`` brackets. The *name* will be translated to lower case,
and quotes in the *value* have been removed, and character and entity references
have been replaced.
For instance, for the tag ``<A HREF="https://www.cwi.nl/">``, this method
would be called as ``handle_starttag('a', [('href', 'https://www.cwi.nl/')])``.
.. versionchanged:: 2.6
All entity references from :mod:`htmlentitydefs` are now replaced in the
attribute values.
.. method:: HTMLParser.handle_endtag(tag)
This method is called to handle the end tag of an element (e.g. ``</div>``).
The *tag* argument is the name of the tag converted to lower case.
.. method:: HTMLParser.handle_startendtag(tag, attrs)
Similar to :meth:`handle_starttag`, but called when the parser encounters an
XHTML-style empty tag (``<img ... />``). This method may be overridden by
subclasses which require this particular lexical information; the default
implementation simply calls :meth:`handle_starttag` and :meth:`handle_endtag`.
.. method:: HTMLParser.handle_data(data)
This method is called to process arbitrary data (e.g. text nodes and the
content of ``<script>...</script>`` and ``<style>...</style>``).
.. method:: HTMLParser.handle_entityref(name)
This method is called to process a named character reference of the form
``&name;`` (e.g. ``>``), where *name* is a general entity reference
(e.g. ``'gt'``).
.. method:: HTMLParser.handle_charref(name)
This method is called to process decimal and hexadecimal numeric character
references of the form ``&#NNN;`` and ``&#xNNN;``. For example, the decimal
equivalent for ``>`` is ``>``, whereas the hexadecimal is ``>``;
in this case the method will receive ``'62'`` or ``'x3E'``.
.. method:: HTMLParser.handle_comment(data)
This method is called when a comment is encountered (e.g. ``<!--comment-->``).
For example, the comment ``<!-- comment -->`` will cause this method to be
called with the argument ``' comment '``.
The content of Internet Explorer conditional comments (condcoms) will also be
sent to this method, so, for ``<!--[if IE 9]>IE9-specific content<![endif]-->``,
this method will receive ``'[if IE 9]>IE9-specific content<![endif]'``.
.. method:: HTMLParser.handle_decl(decl)
This method is called to handle an HTML doctype declaration (e.g.
``<!DOCTYPE html>``).
The *decl* parameter will be the entire contents of the declaration inside
the ``<!...>`` markup (e.g. ``'DOCTYPE html'``).
.. method:: HTMLParser.handle_pi(data)
This method is called when a processing instruction is encountered. The *data*
parameter will contain the entire processing instruction. For example, for the
processing instruction ``<?proc color='red'>``, this method would be called as
``handle_pi("proc color='red'")``.
.. note::
The :class:`.HTMLParser` class uses the SGML syntactic rules for processing
instructions. An XHTML processing instruction using the trailing ``'?'`` will
cause the ``'?'`` to be included in *data*.
.. method:: HTMLParser.unknown_decl(data)
This method is called when an unrecognized declaration is read by the parser.
The *data* parameter will be the entire contents of the declaration inside
the ``<![...]>`` markup. It is sometimes useful to be overridden by a
derived class.
.. _htmlparser-examples:
Examples
--------
The following class implements a parser that will be used to illustrate more
examples::
from HTMLParser import HTMLParser
from htmlentitydefs import name2codepoint
class MyHTMLParser(HTMLParser):
def handle_starttag(self, tag, attrs):
print "Start tag:", tag
for attr in attrs:
print " attr:", attr
def handle_endtag(self, tag):
print "End tag :", tag
def handle_data(self, data):
print "Data :", data
def handle_comment(self, data):
print "Comment :", data
def handle_entityref(self, name):
c = unichr(name2codepoint[name])
print "Named ent:", c
def handle_charref(self, name):
if name.startswith('x'):
c = unichr(int(name[1:], 16))
else:
c = unichr(int(name))
print "Num ent :", c
def handle_decl(self, data):
print "Decl :", data
parser = MyHTMLParser()
Parsing a doctype::
>>> parser.feed('<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" '
... '"http://www.w3.org/TR/html4/strict.dtd">')
Decl : DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"
Parsing an element with a few attributes and a title::
>>> parser.feed('<img src="python-logo.png" alt="The Python logo">')
Start tag: img
attr: ('src', 'python-logo.png')
attr: ('alt', 'The Python logo')
>>>
>>> parser.feed('<h1>Python</h1>')
Start tag: h1
Data : Python
End tag : h1
The content of ``script`` and ``style`` elements is returned as is, without
further parsing::
>>> parser.feed('<style type="text/css">#python { color: green }</style>')
Start tag: style
attr: ('type', 'text/css')
Data : #python { color: green }
End tag : style
>>> parser.feed('<script type="text/javascript">'
... 'alert("<strong>hello!</strong>");</script>')
Start tag: script
attr: ('type', 'text/javascript')
Data : alert("<strong>hello!</strong>");
End tag : script
Parsing comments::
>>> parser.feed('<!-- a comment -->'
... '<!--[if IE 9]>IE-specific content<![endif]-->')
Comment : a comment
Comment : [if IE 9]>IE-specific content<![endif]
Parsing named and numeric character references and converting them to the
correct char (note: these 3 references are all equivalent to ``'>'``)::
>>> parser.feed('>>>')
Named ent: >
Num ent : >
Num ent : >
Feeding incomplete chunks to :meth:`~HTMLParser.feed` works, but
:meth:`~HTMLParser.handle_data` might be called more than once::
>>> for chunk in ['<sp', 'an>buff', 'ered ', 'text</s', 'pan>']:
... parser.feed(chunk)
...
Start tag: span
Data : buff
Data : ered
Data : text
End tag : span
Parsing invalid HTML (e.g. unquoted attributes) also works::
>>> parser.feed('<p><a class=link href=#main>tag soup</p ></a>')
Start tag: p
Start tag: a
attr: ('class', 'link')
attr: ('href', '#main')
Data : tag soup
End tag : p
End tag : a
PK %�\���N� N� % html/_sources/library/httplib.rst.txtnu �[��� :mod:`httplib` --- HTTP protocol client
=======================================
.. module:: httplib
:synopsis: HTTP and HTTPS protocol client (requires sockets).
.. note::
The :mod:`httplib` module has been renamed to :mod:`http.client` in Python
3. The :term:`2to3` tool will automatically adapt imports when converting
your sources to Python 3.
.. index::
pair: HTTP; protocol
single: HTTP; httplib (standard module)
.. index:: module: urllib
**Source code:** :source:`Lib/httplib.py`
--------------
This module defines classes which implement the client side of the HTTP and
HTTPS protocols. It is normally not used directly --- the module :mod:`urllib`
uses it to handle URLs that use HTTP and HTTPS.
.. seealso::
The `Requests package <http://requests.readthedocs.org/>`_
is recommended for a higher-level HTTP client interface.
.. note::
HTTPS support is only available if the :mod:`socket` module was compiled with
SSL support.
.. note::
The public interface for this module changed substantially in Python 2.0. The
:class:`HTTP` class is retained only for backward compatibility with 1.5.2. It
should not be used in new code. Refer to the online docstrings for usage.
The module provides the following classes:
.. class:: HTTPConnection(host[, port[, strict[, timeout[, source_address]]]])
An :class:`HTTPConnection` instance represents one transaction with an HTTP
server. It should be instantiated passing it a host and optional port
number. If no port number is passed, the port is extracted from the host
string if it has the form ``host:port``, else the default HTTP port (80) is
used. When true, the optional parameter *strict* (which defaults to a false
value) causes ``BadStatusLine`` to
be raised if the status line can't be parsed as a valid HTTP/1.0 or 1.1
status line. If the optional *timeout* parameter is given, blocking
operations (like connection attempts) will timeout after that many seconds
(if it is not given, the global default timeout setting is used).
The optional *source_address* parameter may be a tuple of a (host, port)
to use as the source address the HTTP connection is made from.
For example, the following calls all create instances that connect to the server
at the same host and port::
>>> h1 = httplib.HTTPConnection('www.cwi.nl')
>>> h2 = httplib.HTTPConnection('www.cwi.nl:80')
>>> h3 = httplib.HTTPConnection('www.cwi.nl', 80)
>>> h3 = httplib.HTTPConnection('www.cwi.nl', 80, timeout=10)
.. versionadded:: 2.0
.. versionchanged:: 2.6
*timeout* was added.
.. versionchanged:: 2.7
*source_address* was added.
.. class:: HTTPSConnection(host[, port[, key_file[, cert_file[, strict[, timeout[, source_address[, context]]]]]]])
A subclass of :class:`HTTPConnection` that uses SSL for communication with
secure servers. Default port is ``443``. If *context* is specified, it must
be a :class:`ssl.SSLContext` instance describing the various SSL options.
*key_file* and *cert_file* are deprecated, please use
:meth:`ssl.SSLContext.load_cert_chain` instead, or let
:func:`ssl.create_default_context` select the system's trusted CA
certificates for you.
Please read :ref:`ssl-security` for more information on best practices.
.. versionadded:: 2.0
.. versionchanged:: 2.6
*timeout* was added.
.. versionchanged:: 2.7
*source_address* was added.
.. versionchanged:: 2.7.9
*context* was added.
This class now performs all the necessary certificate and hostname checks
by default. To revert to the previous, unverified, behavior
:func:`ssl._create_unverified_context` can be passed to the *context*
parameter.
.. class:: HTTPResponse(sock, debuglevel=0, strict=0)
Class whose instances are returned upon successful connection. Not instantiated
directly by user.
.. versionadded:: 2.0
.. class:: HTTPMessage
An :class:`HTTPMessage` instance is used to hold the headers from an HTTP
response. It is implemented using the :class:`mimetools.Message` class and
provides utility functions to deal with HTTP Headers. It is not directly
instantiated by the users.
The following exceptions are raised as appropriate:
.. exception:: HTTPException
The base class of the other exceptions in this module. It is a subclass of
:exc:`Exception`.
.. versionadded:: 2.0
.. exception:: NotConnected
A subclass of :exc:`HTTPException`.
.. versionadded:: 2.0
.. exception:: InvalidURL
A subclass of :exc:`HTTPException`, raised if a port is given and is either
non-numeric or empty.
.. versionadded:: 2.3
.. exception:: UnknownProtocol
A subclass of :exc:`HTTPException`.
.. versionadded:: 2.0
.. exception:: UnknownTransferEncoding
A subclass of :exc:`HTTPException`.
.. versionadded:: 2.0
.. exception:: UnimplementedFileMode
A subclass of :exc:`HTTPException`.
.. versionadded:: 2.0
.. exception:: IncompleteRead
A subclass of :exc:`HTTPException`.
.. versionadded:: 2.0
.. exception:: ImproperConnectionState
A subclass of :exc:`HTTPException`.
.. versionadded:: 2.0
.. exception:: CannotSendRequest
A subclass of :exc:`ImproperConnectionState`.
.. versionadded:: 2.0
.. exception:: CannotSendHeader
A subclass of :exc:`ImproperConnectionState`.
.. versionadded:: 2.0
.. exception:: ResponseNotReady
A subclass of :exc:`ImproperConnectionState`.
.. versionadded:: 2.0
.. exception:: BadStatusLine
A subclass of :exc:`HTTPException`. Raised if a server responds with a HTTP
status code that we don't understand.
.. versionadded:: 2.0
The constants defined in this module are:
.. data:: HTTP_PORT
The default port for the HTTP protocol (always ``80``).
.. data:: HTTPS_PORT
The default port for the HTTPS protocol (always ``443``).
and also the following constants for integer status codes:
+------------------------------------------+---------+-----------------------------------------------------------------------+
| Constant | Value | Definition |
+==========================================+=========+=======================================================================+
| :const:`CONTINUE` | ``100`` | HTTP/1.1, `RFC 2616, Section |
| | | 10.1.1 |
| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.1.1>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`SWITCHING_PROTOCOLS` | ``101`` | HTTP/1.1, `RFC 2616, Section |
| | | 10.1.2 |
| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.1.2>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`PROCESSING` | ``102`` | WEBDAV, `RFC 2518, Section 10.1 |
| | | <http://www.webdav.org/specs/rfc2518.html#STATUS_102>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`OK` | ``200`` | HTTP/1.1, `RFC 2616, Section |
| | | 10.2.1 |
| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`CREATED` | ``201`` | HTTP/1.1, `RFC 2616, Section |
| | | 10.2.2 |
| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.2>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`ACCEPTED` | ``202`` | HTTP/1.1, `RFC 2616, Section |
| | | 10.2.3 |
| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.3>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`NON_AUTHORITATIVE_INFORMATION` | ``203`` | HTTP/1.1, `RFC 2616, Section |
| | | 10.2.4 |
| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.4>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`NO_CONTENT` | ``204`` | HTTP/1.1, `RFC 2616, Section |
| | | 10.2.5 |
| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.5>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`RESET_CONTENT` | ``205`` | HTTP/1.1, `RFC 2616, Section |
| | | 10.2.6 |
| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.6>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`PARTIAL_CONTENT` | ``206`` | HTTP/1.1, `RFC 2616, Section |
| | | 10.2.7 |
| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.7>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`MULTI_STATUS` | ``207`` | WEBDAV `RFC 2518, Section 10.2 |
| | | <http://www.webdav.org/specs/rfc2518.html#STATUS_207>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`IM_USED` | ``226`` | Delta encoding in HTTP, |
| | | :rfc:`3229`, Section 10.4.1 |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`MULTIPLE_CHOICES` | ``300`` | HTTP/1.1, `RFC 2616, Section |
| | | 10.3.1 |
| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.1>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`MOVED_PERMANENTLY` | ``301`` | HTTP/1.1, `RFC 2616, Section |
| | | 10.3.2 |
| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.2>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`FOUND` | ``302`` | HTTP/1.1, `RFC 2616, Section |
| | | 10.3.3 |
| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.3>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`SEE_OTHER` | ``303`` | HTTP/1.1, `RFC 2616, Section |
| | | 10.3.4 |
| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.4>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`NOT_MODIFIED` | ``304`` | HTTP/1.1, `RFC 2616, Section |
| | | 10.3.5 |
| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.5>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`USE_PROXY` | ``305`` | HTTP/1.1, `RFC 2616, Section |
| | | 10.3.6 |
| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.6>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`TEMPORARY_REDIRECT` | ``307`` | HTTP/1.1, `RFC 2616, Section |
| | | 10.3.8 |
| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.8>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`BAD_REQUEST` | ``400`` | HTTP/1.1, `RFC 2616, Section |
| | | 10.4.1 |
| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`UNAUTHORIZED` | ``401`` | HTTP/1.1, `RFC 2616, Section |
| | | 10.4.2 |
| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`PAYMENT_REQUIRED` | ``402`` | HTTP/1.1, `RFC 2616, Section |
| | | 10.4.3 |
| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.3>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`FORBIDDEN` | ``403`` | HTTP/1.1, `RFC 2616, Section |
| | | 10.4.4 |
| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`NOT_FOUND` | ``404`` | HTTP/1.1, `RFC 2616, Section |
| | | 10.4.5 |
| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`METHOD_NOT_ALLOWED` | ``405`` | HTTP/1.1, `RFC 2616, Section |
| | | 10.4.6 |
| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.6>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`NOT_ACCEPTABLE` | ``406`` | HTTP/1.1, `RFC 2616, Section |
| | | 10.4.7 |
| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`PROXY_AUTHENTICATION_REQUIRED` | ``407`` | HTTP/1.1, `RFC 2616, Section |
| | | 10.4.8 |
| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.8>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`REQUEST_TIMEOUT` | ``408`` | HTTP/1.1, `RFC 2616, Section |
| | | 10.4.9 |
| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.9>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`CONFLICT` | ``409`` | HTTP/1.1, `RFC 2616, Section |
| | | 10.4.10 |
| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`GONE` | ``410`` | HTTP/1.1, `RFC 2616, Section |
| | | 10.4.11 |
| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.11>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`LENGTH_REQUIRED` | ``411`` | HTTP/1.1, `RFC 2616, Section |
| | | 10.4.12 |
| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.12>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`PRECONDITION_FAILED` | ``412`` | HTTP/1.1, `RFC 2616, Section |
| | | 10.4.13 |
| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.13>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`REQUEST_ENTITY_TOO_LARGE` | ``413`` | HTTP/1.1, `RFC 2616, Section |
| | | 10.4.14 |
| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.14>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`REQUEST_URI_TOO_LONG` | ``414`` | HTTP/1.1, `RFC 2616, Section |
| | | 10.4.15 |
| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.15>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`UNSUPPORTED_MEDIA_TYPE` | ``415`` | HTTP/1.1, `RFC 2616, Section |
| | | 10.4.16 |
| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.16>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`REQUESTED_RANGE_NOT_SATISFIABLE` | ``416`` | HTTP/1.1, `RFC 2616, Section |
| | | 10.4.17 |
| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.17>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`EXPECTATION_FAILED` | ``417`` | HTTP/1.1, `RFC 2616, Section |
| | | 10.4.18 |
| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.18>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`UNPROCESSABLE_ENTITY` | ``422`` | WEBDAV, `RFC 2518, Section 10.3 |
| | | <http://www.webdav.org/specs/rfc2518.html#STATUS_422>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`LOCKED` | ``423`` | WEBDAV `RFC 2518, Section 10.4 |
| | | <http://www.webdav.org/specs/rfc2518.html#STATUS_423>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`FAILED_DEPENDENCY` | ``424`` | WEBDAV, `RFC 2518, Section 10.5 |
| | | <http://www.webdav.org/specs/rfc2518.html#STATUS_424>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`UPGRADE_REQUIRED` | ``426`` | HTTP Upgrade to TLS, |
| | | :rfc:`2817`, Section 6 |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`INTERNAL_SERVER_ERROR` | ``500`` | HTTP/1.1, `RFC 2616, Section |
| | | 10.5.1 |
| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`NOT_IMPLEMENTED` | ``501`` | HTTP/1.1, `RFC 2616, Section |
| | | 10.5.2 |
| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.2>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`BAD_GATEWAY` | ``502`` | HTTP/1.1 `RFC 2616, Section |
| | | 10.5.3 |
| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.3>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`SERVICE_UNAVAILABLE` | ``503`` | HTTP/1.1, `RFC 2616, Section |
| | | 10.5.4 |
| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.4>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`GATEWAY_TIMEOUT` | ``504`` | HTTP/1.1 `RFC 2616, Section |
| | | 10.5.5 |
| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.5>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`HTTP_VERSION_NOT_SUPPORTED` | ``505`` | HTTP/1.1, `RFC 2616, Section |
| | | 10.5.6 |
| | | <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.6>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`INSUFFICIENT_STORAGE` | ``507`` | WEBDAV, `RFC 2518, Section 10.6 |
| | | <http://www.webdav.org/specs/rfc2518.html#STATUS_507>`_ |
+------------------------------------------+---------+-----------------------------------------------------------------------+
| :const:`NOT_EXTENDED` | ``510`` | An HTTP Extension Framework, |
| | | :rfc:`2774`, Section 7 |
+------------------------------------------+---------+-----------------------------------------------------------------------+
.. data:: responses
This dictionary maps the HTTP 1.1 status codes to the W3C names.
Example: ``httplib.responses[httplib.NOT_FOUND]`` is ``'Not Found'``.
.. versionadded:: 2.5
.. _httpconnection-objects:
HTTPConnection Objects
----------------------
:class:`HTTPConnection` instances have the following methods:
.. method:: HTTPConnection.request(method, url[, body[, headers]])
This will send a request to the server using the HTTP request method *method*
and the selector *url*. If the *body* argument is present, it should be a
string of data to send after the headers are finished. Alternatively, it may
be an open file object, in which case the contents of the file is sent; this
file object should support ``fileno()`` and ``read()`` methods. The
*headers* argument should be a mapping of extra HTTP headers to send with
the request.
If one is not provided in *headers*, a ``Content-Length`` header is added
automatically for all methods if the length of the body can be determined,
either from the length of the ``str`` representation, or from the reported
size of the file on disk. If *body* is ``None`` the header is not set except
for methods that expect a body (``PUT``, ``POST``, and ``PATCH``) in which
case it is set to ``0``.
.. versionchanged:: 2.6
*body* can be a file object.
.. method:: HTTPConnection.getresponse()
Should be called after a request is sent to get the response from the server.
Returns an :class:`HTTPResponse` instance.
.. note::
Note that you must have read the whole response before you can send a new
request to the server.
.. method:: HTTPConnection.set_debuglevel(level)
Set the debugging level (the amount of debugging output printed). The default
debug level is ``0``, meaning no debugging output is printed.
.. method:: HTTPConnection.set_tunnel(host,port=None, headers=None)
Set the host and the port for HTTP Connect Tunnelling. Normally used when
it is required to do HTTPS Connection through a proxy server.
The headers argument should be a mapping of extra HTTP headers to send
with the CONNECT request.
.. versionadded:: 2.7
.. method:: HTTPConnection.connect()
Connect to the server specified when the object was created.
.. method:: HTTPConnection.close()
Close the connection to the server.
As an alternative to using the :meth:`request` method described above, you can
also send your request step by step, by using the four functions below.
.. method:: HTTPConnection.putrequest(request, selector[, skip_host[, skip_accept_encoding]])
This should be the first call after the connection to the server has been made.
It sends a line to the server consisting of the *request* string, the *selector*
string, and the HTTP version (``HTTP/1.1``). To disable automatic sending of
``Host:`` or ``Accept-Encoding:`` headers (for example to accept additional
content encodings), specify *skip_host* or *skip_accept_encoding* with non-False
values.
.. versionchanged:: 2.4
*skip_accept_encoding* argument added.
.. method:: HTTPConnection.putheader(header, argument[, ...])
Send an :rfc:`822`\ -style header to the server. It sends a line to the server
consisting of the header, a colon and a space, and the first argument. If more
arguments are given, continuation lines are sent, each consisting of a tab and
an argument.
.. method:: HTTPConnection.endheaders(message_body=None)
Send a blank line to the server, signalling the end of the headers. The
optional *message_body* argument can be used to pass a message body
associated with the request. The message body will be sent in the same
packet as the message headers if it is string, otherwise it is sent in a
separate packet.
.. versionchanged:: 2.7
*message_body* was added.
.. method:: HTTPConnection.send(data)
Send data to the server. This should be used directly only after the
:meth:`endheaders` method has been called and before :meth:`getresponse` is
called.
.. _httpresponse-objects:
HTTPResponse Objects
--------------------
:class:`HTTPResponse` instances have the following methods and attributes:
.. method:: HTTPResponse.read([amt])
Reads and returns the response body, or up to the next *amt* bytes.
.. method:: HTTPResponse.getheader(name[, default])
Get the contents of the header *name*, or *default* if there is no matching
header.
.. method:: HTTPResponse.getheaders()
Return a list of (header, value) tuples.
.. versionadded:: 2.4
.. method:: HTTPResponse.fileno()
Returns the ``fileno`` of the underlying socket.
.. attribute:: HTTPResponse.msg
A :class:`mimetools.Message` instance containing the response headers.
.. attribute:: HTTPResponse.version
HTTP protocol version used by server. 10 for HTTP/1.0, 11 for HTTP/1.1.
.. attribute:: HTTPResponse.status
Status code returned by server.
.. attribute:: HTTPResponse.reason
Reason phrase returned by server.
.. _httplib-examples:
Examples
--------
Here is an example session that uses the ``GET`` method::
>>> import httplib
>>> conn = httplib.HTTPSConnection("www.python.org")
>>> conn.request("GET", "/")
>>> r1 = conn.getresponse()
>>> print r1.status, r1.reason
200 OK
>>> data1 = r1.read()
>>> conn.request("GET", "/")
>>> r2 = conn.getresponse()
>>> print r2.status, r2.reason
404 Not Found
>>> data2 = r2.read()
>>> conn.close()
Here is an example session that uses the ``HEAD`` method. Note that the
``HEAD`` method never returns any data. ::
>>> import httplib
>>> conn = httplib.HTTPSConnection("www.python.org")
>>> conn.request("HEAD","/")
>>> res = conn.getresponse()
>>> print res.status, res.reason
200 OK
>>> data = res.read()
>>> print len(data)
0
>>> data == ''
True
Here is an example session that shows how to ``POST`` requests::
>>> import httplib, urllib
>>> params = urllib.urlencode({'@number': 12524, '@type': 'issue', '@action': 'show'})
>>> headers = {"Content-type": "application/x-www-form-urlencoded",
... "Accept": "text/plain"}
>>> conn = httplib.HTTPConnection("bugs.python.org")
>>> conn.request("POST", "", params, headers)
>>> response = conn.getresponse()
>>> print response.status, response.reason
302 Found
>>> data = response.read()
>>> data
'Redirecting to <a href="http://bugs.python.org/issue12524">http://bugs.python.org/issue12524</a>'
>>> conn.close()
Client side ``HTTP PUT`` requests are very similar to ``POST`` requests. The
difference lies only the server side where HTTP server will allow resources to
be created via ``PUT`` request. Here is an example session that shows how to do
``PUT`` request using httplib::
>>> # This creates an HTTP message
>>> # with the content of BODY as the enclosed representation
>>> # for the resource http://localhost:8080/foobar
...
>>> import httplib
>>> BODY = "***filecontents***"
>>> conn = httplib.HTTPConnection("localhost", 8080)
>>> conn.request("PUT", "/file", BODY)
>>> response = conn.getresponse()
>>> print response.status, response.reason
200, OK
PK %�\<[�� � " html/_sources/library/i18n.rst.txtnu �[���
.. _i18n:
********************
Internationalization
********************
The modules described in this chapter help you write software that is
independent of language and locale by providing mechanisms for selecting a
language to be used in program messages or by tailoring output to match local
conventions.
The list of modules described in this chapter is:
.. toctree::
gettext.rst
locale.rst
PK %�\�\ � html/_sources/library/ic.rst.txtnu �[��� :mod:`ic` --- Access to the Mac OS X Internet Config
====================================================
.. module:: ic
:platform: Mac
:synopsis: Access to the Mac OS X Internet Config.
:deprecated:
This module provides access to various internet-related preferences set through
:program:`System Preferences` or the :program:`Finder`.
.. note::
This module has been removed in Python 3.x.
.. index:: module: icglue
There is a low-level companion module :mod:`icglue` which provides the basic
Internet Config access functionality. This low-level module is not documented,
but the docstrings of the routines document the parameters and the routine names
are the same as for the Pascal or C API to Internet Config, so the standard IC
programmers' documentation can be used if this module is needed.
The :mod:`ic` module defines the :exc:`error` exception and symbolic names for
all error codes Internet Config can produce; see the source for details.
.. exception:: error
Exception raised on errors in the :mod:`ic` module.
The :mod:`ic` module defines the following class and function:
.. class:: IC([signature[, ic]])
Create an Internet Config object. The signature is a 4-character creator code of
the current application (default ``'Pyth'``) which may influence some of ICs
settings. The optional *ic* argument is a low-level ``icglue.icinstance``
created beforehand, this may be useful if you want to get preferences from a
different config file, etc.
.. function:: launchurl(url[, hint])
parseurl(data[, start[, end[, hint]]])
mapfile(file)
maptypecreator(type, creator[, filename])
settypecreator(file)
These functions are "shortcuts" to the methods of the same name, described
below.
IC Objects
----------
:class:`IC` objects have a mapping interface, hence to obtain the mail address
you simply get ``ic['MailAddress']``. Assignment also works, and changes the
option in the configuration file.
The module knows about various datatypes, and converts the internal IC
representation to a "logical" Python data structure. Running the :mod:`ic`
module standalone will run a test program that lists all keys and values in your
IC database, this will have to serve as documentation.
If the module does not know how to represent the data it returns an instance of
the ``ICOpaqueData`` type, with the raw data in its :attr:`data` attribute.
Objects of this type are also acceptable values for assignment.
Besides the dictionary interface, :class:`IC` objects have the following
methods:
.. method:: IC.launchurl(url[, hint])
Parse the given URL, launch the correct application and pass it the URL. The
optional *hint* can be a scheme name such as ``'mailto:'``, in which case
incomplete URLs are completed with this scheme. If *hint* is not provided,
incomplete URLs are invalid.
.. method:: IC.parseurl(data[, start[, end[, hint]]])
Find a URL somewhere in *data* and return start position, end position and the
URL. The optional *start* and *end* can be used to limit the search, so for
instance if a user clicks in a long text field you can pass the whole text field
and the click-position in *start* and this routine will return the whole URL in
which the user clicked. As above, *hint* is an optional scheme used to complete
incomplete URLs.
.. method:: IC.mapfile(file)
Return the mapping entry for the given *file*, which can be passed as either a
filename or an :func:`FSSpec` result, and which need not exist.
The mapping entry is returned as a tuple ``(version, type, creator, postcreator,
flags, extension, appname, postappname, mimetype, entryname)``, where *version*
is the entry version number, *type* is the 4-character filetype, *creator* is
the 4-character creator type, *postcreator* is the 4-character creator code of
an optional application to post-process the file after downloading, *flags* are
various bits specifying whether to transfer in binary or ascii and such,
*extension* is the filename extension for this file type, *appname* is the
printable name of the application to which this file belongs, *postappname* is
the name of the postprocessing application, *mimetype* is the MIME type of this
file and *entryname* is the name of this entry.
.. method:: IC.maptypecreator(type, creator[, filename])
Return the mapping entry for files with given 4-character *type* and *creator*
codes. The optional *filename* may be specified to further help finding the
correct entry (if the creator code is ``'????'``, for instance).
The mapping entry is returned in the same format as for *mapfile*.
.. method:: IC.settypecreator(file)
Given an existing *file*, specified either as a filename or as an :func:`FSSpec`
result, set its creator and type correctly based on its extension. The finder
is told about the change, so the finder icon will be updated quickly.
PK %�\�+��V �V " html/_sources/library/idle.rst.txtnu �[��� .. _idle:
IDLE
====
.. index::
single: IDLE
single: Python Editor
single: Integrated Development Environment
.. moduleauthor:: Guido van Rossum <guido@python.org>
IDLE is Python's Integrated Development and Learning Environment.
IDLE has the following features:
* coded in 100% pure Python, using the :mod:`tkinter` GUI toolkit
* cross-platform: works mostly the same on Windows, Unix, and Mac OS X
* Python shell window (interactive interpreter) with colorizing
of code input, output, and error messages
* multi-window text editor with multiple undo, Python colorizing,
smart indent, call tips, auto completion, and other features
* search within any window, replace within editor windows, and search
through multiple files (grep)
* debugger with persistent breakpoints, stepping, and viewing
of global and local namespaces
* configuration, browsers, and other dialogs
Menus
-----
IDLE has two main window types, the Shell window and the Editor window. It is
possible to have multiple editor windows simultaneously. Output windows, such
as used for Edit / Find in Files, are a subtype of edit window. They currently
have the same top menu as Editor windows but a different default title and
context menu.
IDLE's menus dynamically change based on which window is currently selected.
Each menu documented below indicates which window type it is associated with.
File menu (Shell and Editor)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
New File
Create a new file editing window.
Open...
Open an existing file with an Open dialog.
Recent Files
Open a list of recent files. Click one to open it.
Open Module...
Open an existing module (searches sys.path).
.. index::
single: Class browser
single: Path browser
Class Browser
Show functions, classes, and methods in the current Editor file in a
tree structure. In the shell, open a module first.
Path Browser
Show sys.path directories, modules, functions, classes and methods in a
tree structure.
Save
Save the current window to the associated file, if there is one. Windows
that have been changed since being opened or last saved have a \* before
and after the window title. If there is no associated file,
do Save As instead.
Save As...
Save the current window with a Save As dialog. The file saved becomes the
new associated file for the window.
Save Copy As...
Save the current window to different file without changing the associated
file.
Print Window
Print the current window to the default printer.
Close
Close the current window (ask to save if unsaved).
Exit
Close all windows and quit IDLE (ask to save unsaved windows).
Edit menu (Shell and Editor)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Undo
Undo the last change to the current window. A maximum of 1000 changes may
be undone.
Redo
Redo the last undone change to the current window.
Cut
Copy selection into the system-wide clipboard; then delete the selection.
Copy
Copy selection into the system-wide clipboard.
Paste
Insert contents of the system-wide clipboard into the current window.
The clipboard functions are also available in context menus.
Select All
Select the entire contents of the current window.
Find...
Open a search dialog with many options
Find Again
Repeat the last search, if there is one.
Find Selection
Search for the currently selected string, if there is one.
Find in Files...
Open a file search dialog. Put results in a new output window.
Replace...
Open a search-and-replace dialog.
Go to Line
Move cursor to the line number requested and make that line visible.
Show Completions
Open a scrollable list allowing selection of keywords and attributes. See
Completions in the Tips sections below.
Expand Word
Expand a prefix you have typed to match a full word in the same window;
repeat to get a different expansion.
Show call tip
After an unclosed parenthesis for a function, open a small window with
function parameter hints.
Show surrounding parens
Highlight the surrounding parenthesis.
Format menu (Editor window only)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Indent Region
Shift selected lines right by the indent width (default 4 spaces).
Dedent Region
Shift selected lines left by the indent width (default 4 spaces).
Comment Out Region
Insert ## in front of selected lines.
Uncomment Region
Remove leading # or ## from selected lines.
Tabify Region
Turn *leading* stretches of spaces into tabs. (Note: We recommend using
4 space blocks to indent Python code.)
Untabify Region
Turn *all* tabs into the correct number of spaces.
Toggle Tabs
Open a dialog to switch between indenting with spaces and tabs.
New Indent Width
Open a dialog to change indent width. The accepted default by the Python
community is 4 spaces.
Format Paragraph
Reformat the current blank-line-delimited paragraph in comment block or
multiline string or selected line in a string. All lines in the
paragraph will be formatted to less than N columns, where N defaults to 72.
Strip trailing whitespace
Remove any space characters after the last non-space character of a line.
.. index::
single: Run script
Run menu (Editor window only)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Python Shell
Open or wake up the Python Shell window.
Check Module
Check the syntax of the module currently open in the Editor window. If the
module has not been saved IDLE will either prompt the user to save or
autosave, as selected in the General tab of the Idle Settings dialog. If
there is a syntax error, the approximate location is indicated in the
Editor window.
Run Module
Do Check Module (above). If no error, restart the shell to clean the
environment, then execute the module. Output is displayed in the Shell
window. Note that output requires use of ``print`` or ``write``.
When execution is complete, the Shell retains focus and displays a prompt.
At this point, one may interactively explore the result of execution.
This is similar to executing a file with ``python -i file`` at a command
line.
Shell menu (Shell window only)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
View Last Restart
Scroll the shell window to the last Shell restart.
Restart Shell
Restart the shell to clean the environment.
Interrupt Execution
Stop a running program.
Debug menu (Shell window only)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Go to File/Line
Look on the current line. with the cursor, and the line above for a filename
and line number. If found, open the file if not already open, and show the
line. Use this to view source lines referenced in an exception traceback
and lines found by Find in Files. Also available in the context menu of
the Shell window and Output windows.
.. index::
single: debugger
single: stack viewer
Debugger (toggle)
When activated, code entered in the Shell or run from an Editor will run
under the debugger. In the Editor, breakpoints can be set with the context
menu. This feature is still incomplete and somewhat experimental.
Stack Viewer
Show the stack traceback of the last exception in a tree widget, with
access to locals and globals.
Auto-open Stack Viewer
Toggle automatically opening the stack viewer on an unhandled exception.
Options menu (Shell and Editor)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Configure IDLE
Open a configuration dialog and change preferences for the following:
fonts, indentation, keybindings, text color themes, startup windows and
size, additional help sources, and extensions (see below). On OS X,
open the configuration dialog by selecting Preferences in the application
menu. To use a new built-in color theme (IDLE Dark) with older IDLEs,
save it as a new custom theme.
Non-default user settings are saved in a .idlerc directory in the user's
home directory. Problems caused by bad user configuration files are solved
by editing or deleting one or more of the files in .idlerc.
Code Context (toggle)(Editor Window only)
Open a pane at the top of the edit window which shows the block context
of the code which has scrolled above the top of the window.
Window menu (Shell and Editor)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Zoom Height
Toggles the window between normal size and maximum height. The initial size
defaults to 40 lines by 80 chars unless changed on the General tab of the
Configure IDLE dialog.
The rest of this menu lists the names of all open windows; select one to bring
it to the foreground (deiconifying it if necessary).
Help menu (Shell and Editor)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
About IDLE
Display version, copyright, license, credits, and more.
IDLE Help
Display a help file for IDLE detailing the menu options, basic editing and
navigation, and other tips.
Python Docs
Access local Python documentation, if installed, or start a web browser
and open docs.python.org showing the latest Python documentation.
Turtle Demo
Run the turtledemo module with example python code and turtle drawings.
Additional help sources may be added here with the Configure IDLE dialog under
the General tab.
.. index::
single: Cut
single: Copy
single: Paste
single: Set Breakpoint
single: Clear Breakpoint
single: breakpoints
Context Menus
^^^^^^^^^^^^^^^^^^^^^^^^^^
Open a context menu by right-clicking in a window (Control-click on OS X).
Context menus have the standard clipboard functions also on the Edit menu.
Cut
Copy selection into the system-wide clipboard; then delete the selection.
Copy
Copy selection into the system-wide clipboard.
Paste
Insert contents of the system-wide clipboard into the current window.
Editor windows also have breakpoint functions. Lines with a breakpoint set are
specially marked. Breakpoints only have an effect when running under the
debugger. Breakpoints for a file are saved in the user's .idlerc directory.
Set Breakpoint
Set a breakpoint on the current line.
Clear Breakpoint
Clear the breakpoint on that line.
Shell and Output windows have the following.
Go to file/line
Same as in Debug menu.
Editing and navigation
----------------------
In this section, 'C' refers to the :kbd:`Control` key on Windows and Unix and
the :kbd:`Command` key on Mac OSX.
* :kbd:`Backspace` deletes to the left; :kbd:`Del` deletes to the right
* :kbd:`C-Backspace` delete word left; :kbd:`C-Del` delete word to the right
* Arrow keys and :kbd:`Page Up`/:kbd:`Page Down` to move around
* :kbd:`C-LeftArrow` and :kbd:`C-RightArrow` moves by words
* :kbd:`Home`/:kbd:`End` go to begin/end of line
* :kbd:`C-Home`/:kbd:`C-End` go to begin/end of file
* Some useful Emacs bindings are inherited from Tcl/Tk:
* :kbd:`C-a` beginning of line
* :kbd:`C-e` end of line
* :kbd:`C-k` kill line (but doesn't put it in clipboard)
* :kbd:`C-l` center window around the insertion point
* :kbd:`C-b` go backward one character without deleting (usually you can
also use the cursor key for this)
* :kbd:`C-f` go forward one character without deleting (usually you can
also use the cursor key for this)
* :kbd:`C-p` go up one line (usually you can also use the cursor key for
this)
* :kbd:`C-d` delete next character
Standard keybindings (like :kbd:`C-c` to copy and :kbd:`C-v` to paste)
may work. Keybindings are selected in the Configure IDLE dialog.
Automatic indentation
^^^^^^^^^^^^^^^^^^^^^
After a block-opening statement, the next line is indented by 4 spaces (in the
Python Shell window by one tab). After certain keywords (break, return etc.)
the next line is dedented. In leading indentation, :kbd:`Backspace` deletes up
to 4 spaces if they are there. :kbd:`Tab` inserts spaces (in the Python
Shell window one tab), number depends on Indent width. Currently, tabs
are restricted to four spaces due to Tcl/Tk limitations.
See also the indent/dedent region commands in the edit menu.
Completions
^^^^^^^^^^^
Completions are supplied for functions, classes, and attributes of classes,
both built-in and user-defined. Completions are also provided for
filenames.
The AutoCompleteWindow (ACW) will open after a predefined delay (default is
two seconds) after a '.' or (in a string) an os.sep is typed. If after one
of those characters (plus zero or more other characters) a tab is typed
the ACW will open immediately if a possible continuation is found.
If there is only one possible completion for the characters entered, a
:kbd:`Tab` will supply that completion without opening the ACW.
'Show Completions' will force open a completions window, by default the
:kbd:`C-space` will open a completions window. In an empty
string, this will contain the files in the current directory. On a
blank line, it will contain the built-in and user-defined functions and
classes in the current namespaces, plus any modules imported. If some
characters have been entered, the ACW will attempt to be more specific.
If a string of characters is typed, the ACW selection will jump to the
entry most closely matching those characters. Entering a :kbd:`tab` will
cause the longest non-ambiguous match to be entered in the Editor window or
Shell. Two :kbd:`tab` in a row will supply the current ACW selection, as
will return or a double click. Cursor keys, Page Up/Down, mouse selection,
and the scroll wheel all operate on the ACW.
"Hidden" attributes can be accessed by typing the beginning of hidden
name after a '.', e.g. '_'. This allows access to modules with
``__all__`` set, or to class-private attributes.
Completions and the 'Expand Word' facility can save a lot of typing!
Completions are currently limited to those in the namespaces. Names in
an Editor window which are not via ``__main__`` and :data:`sys.modules` will
not be found. Run the module once with your imports to correct this situation.
Note that IDLE itself places quite a few modules in sys.modules, so
much can be found by default, e.g. the re module.
If you don't like the ACW popping up unbidden, simply make the delay
longer or disable the extension.
Calltips
^^^^^^^^
A calltip is shown when one types :kbd:`(` after the name of an *accessible*
function. A name expression may include dots and subscripts. A calltip
remains until it is clicked, the cursor is moved out of the argument area,
or :kbd:`)` is typed. When the cursor is in the argument part of a definition,
the menu or shortcut display a calltip.
A calltip consists of the function signature and the first line of the
docstring. For builtins without an accessible signature, the calltip
consists of all lines up the fifth line or the first blank line. These
details may change.
The set of *accessible* functions depends on what modules have been imported
into the user process, including those imported by Idle itself,
and what definitions have been run, all since the last restart.
For example, restart the Shell and enter ``itertools.count(``. A calltip
appears because Idle imports itertools into the user process for its own use.
(This could change.) Enter ``turtle.write(`` and nothing appears. Idle does
not import turtle. The menu or shortcut do nothing either. Enter
``import turtle`` and then ``turtle.write(`` will work.
In an editor, import statements have no effect until one runs the file. One
might want to run a file after writing the import statements at the top,
or immediately run an existing file before editing.
Python Shell window
^^^^^^^^^^^^^^^^^^^
* :kbd:`C-c` interrupts executing command
* :kbd:`C-d` sends end-of-file; closes window if typed at a ``>>>`` prompt
* :kbd:`Alt-/` (Expand word) is also useful to reduce typing
Command history
* :kbd:`Alt-p` retrieves previous command matching what you have typed. On
OS X use :kbd:`C-p`.
* :kbd:`Alt-n` retrieves next. On OS X use :kbd:`C-n`.
* :kbd:`Return` while on any previous command retrieves that command
Text colors
^^^^^^^^^^^
Idle defaults to black on white text, but colors text with special meanings.
For the shell, these are shell output, shell error, user output, and
user error. For Python code, at the shell prompt or in an editor, these are
keywords, builtin class and function names, names following ``class`` and
``def``, strings, and comments. For any text window, these are the cursor (when
present), found text (when possible), and selected text.
Text coloring is done in the background, so uncolorized text is occasionally
visible. To change the color scheme, use the Configure IDLE dialog
Highlighting tab. The marking of debugger breakpoint lines in the editor and
text in popups and dialogs is not user-configurable.
Startup and code execution
--------------------------
Upon startup with the ``-s`` option, IDLE will execute the file referenced by
the environment variables :envvar:`IDLESTARTUP` or :envvar:`PYTHONSTARTUP`.
IDLE first checks for ``IDLESTARTUP``; if ``IDLESTARTUP`` is present the file
referenced is run. If ``IDLESTARTUP`` is not present, IDLE checks for
``PYTHONSTARTUP``. Files referenced by these environment variables are
convenient places to store functions that are used frequently from the IDLE
shell, or for executing import statements to import common modules.
In addition, ``Tk`` also loads a startup file if it is present. Note that the
Tk file is loaded unconditionally. This additional file is ``.Idle.py`` and is
looked for in the user's home directory. Statements in this file will be
executed in the Tk namespace, so this file is not useful for importing
functions to be used from IDLE's Python shell.
Command line usage
^^^^^^^^^^^^^^^^^^
.. code-block:: none
idle.py [-c command] [-d] [-e] [-h] [-i] [-r file] [-s] [-t title] [-] [arg] ...
-c command run command in the shell window
-d enable debugger and open shell window
-e open editor window
-h print help message with legal combinations and exit
-i open shell window
-r file run file in shell window
-s run $IDLESTARTUP or $PYTHONSTARTUP first, in shell window
-t title set title of shell window
- run stdin in shell (- must be last option before args)
If there are arguments:
* If ``-``, ``-c``, or ``r`` is used, all arguments are placed in
``sys.argv[1:...]`` and ``sys.argv[0]`` is set to ``''``, ``'-c'``,
or ``'-r'``. No editor window is opened, even if that is the default
set in the Options dialog.
* Otherwise, arguments are files opened for editing and
``sys.argv`` reflects the arguments passed to IDLE itself.
IDLE-console differences
^^^^^^^^^^^^^^^^^^^^^^^^
As much as possible, the result of executing Python code with IDLE is the
same as executing the same code in a console window. However, the different
interface and operation occasionally affect visible results. For instance,
``sys.modules`` starts with more entries.
IDLE also replaces ``sys.stdin``, ``sys.stdout``, and ``sys.stderr`` with
objects that get input from and send output to the Shell window.
When this window has the focus, it controls the keyboard and screen.
This is normally transparent, but functions that directly access the keyboard
and screen will not work. If ``sys`` is reset with ``reload(sys)``,
IDLE's changes are lost and things like ``input``, ``raw_input``, and
``print`` will not work correctly.
With IDLE's Shell, one enters, edits, and recalls complete statements.
Some consoles only work with a single physical line at a time. IDLE uses
``exec`` to run each statement. As a result, ``'__builtins__'`` is always
defined for each statement.
Running without a subprocess
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
By default, IDLE executes user code in a separate subprocess via a socket,
which uses the internal loopback interface. This connection is not
externally visible and no data is sent to or received from the Internet.
If firewall software complains anyway, you can ignore it.
If the attempt to make the socket connection fails, Idle will notify you.
Such failures are sometimes transient, but if persistent, the problem
may be either a firewall blocking the connection or misconfiguration of
a particular system. Until the problem is fixed, one can run Idle with
the -n command line switch.
If IDLE is started with the -n command line switch it will run in a
single process and will not create the subprocess which runs the RPC
Python execution server. This can be useful if Python cannot create
the subprocess or the RPC socket interface on your platform. However,
in this mode user code is not isolated from IDLE itself. Also, the
environment is not restarted when Run/Run Module (F5) is selected. If
your code has been modified, you must reload() the affected modules and
re-import any specific items (e.g. from foo import baz) if the changes
are to take effect. For these reasons, it is preferable to run IDLE
with the default subprocess if at all possible.
.. deprecated:: 3.4
Help and preferences
--------------------
Additional help sources
^^^^^^^^^^^^^^^^^^^^^^^
IDLE includes a help menu entry called "Python Docs" that will open the
extensive sources of help, including tutorials, available at docs.python.org.
Selected URLs can be added or removed from the help menu at any time using the
Configure IDLE dialog. See the IDLE help option in the help menu of IDLE for
more information.
Setting preferences
^^^^^^^^^^^^^^^^^^^
The font preferences, highlighting, keys, and general preferences can be
changed via Configure IDLE on the Option menu. Keys can be user defined;
IDLE ships with four built-in key sets. In addition, a user can create a
custom key set in the Configure IDLE dialog under the keys tab.
Extensions
^^^^^^^^^^
IDLE contains an extension facility. Preferences for extensions can be
changed with Configure Extensions. See the beginning of config-extensions.def
in the idlelib directory for further information. The default extensions
are currently:
* FormatParagraph
* AutoExpand
* ZoomHeight
* ScriptBinding
* CallTips
* ParenMatch
* AutoComplete
* CodeContext
* RstripExtension
PK %�\ȴ�� � % html/_sources/library/imageop.rst.txtnu �[���
:mod:`imageop` --- Manipulate raw image data
============================================
.. module:: imageop
:synopsis: Manipulate raw image data.
:deprecated:
.. deprecated:: 2.6
The :mod:`imageop` module has been removed in Python 3.
The :mod:`imageop` module contains some useful operations on images. It operates
on images consisting of 8 or 32 bit pixels stored in Python strings. This is
the same format as used by :func:`gl.lrectwrite` and the :mod:`imgfile` module.
The module defines the following variables and functions:
.. exception:: error
This exception is raised on all errors, such as unknown number of bits per
pixel, etc.
.. function:: crop(image, psize, width, height, x0, y0, x1, y1)
Return the selected part of *image*, which should be *width* by *height* in size
and consist of pixels of *psize* bytes. *x0*, *y0*, *x1* and *y1* are like the
:func:`gl.lrectread` parameters, i.e. the boundary is included in the new image.
The new boundaries need not be inside the picture. Pixels that fall outside the
old image will have their value set to zero. If *x0* is bigger than *x1* the
new image is mirrored. The same holds for the y coordinates.
.. function:: scale(image, psize, width, height, newwidth, newheight)
Return *image* scaled to size *newwidth* by *newheight*. No interpolation is
done, scaling is done by simple-minded pixel duplication or removal. Therefore,
computer-generated images or dithered images will not look nice after scaling.
.. function:: tovideo(image, psize, width, height)
Run a vertical low-pass filter over an image. It does so by computing each
destination pixel as the average of two vertically-aligned source pixels. The
main use of this routine is to forestall excessive flicker if the image is
displayed on a video device that uses interlacing, hence the name.
.. function:: grey2mono(image, width, height, threshold)
Convert an 8-bit deep greyscale image to a 1-bit deep image by thresholding all
the pixels. The resulting image is tightly packed and is probably only useful
as an argument to :func:`mono2grey`.
.. function:: dither2mono(image, width, height)
Convert an 8-bit greyscale image to a 1-bit monochrome image using a
(simple-minded) dithering algorithm.
.. function:: mono2grey(image, width, height, p0, p1)
Convert a 1-bit monochrome image to an 8 bit greyscale or color image. All
pixels that are zero-valued on input get value *p0* on output and all one-value
input pixels get value *p1* on output. To convert a monochrome black-and-white
image to greyscale pass the values ``0`` and ``255`` respectively.
.. function:: grey2grey4(image, width, height)
Convert an 8-bit greyscale image to a 4-bit greyscale image without dithering.
.. function:: grey2grey2(image, width, height)
Convert an 8-bit greyscale image to a 2-bit greyscale image without dithering.
.. function:: dither2grey2(image, width, height)
Convert an 8-bit greyscale image to a 2-bit greyscale image with dithering. As
for :func:`dither2mono`, the dithering algorithm is currently very simple.
.. function:: grey42grey(image, width, height)
Convert a 4-bit greyscale image to an 8-bit greyscale image.
.. function:: grey22grey(image, width, height)
Convert a 2-bit greyscale image to an 8-bit greyscale image.
.. data:: backward_compatible
If set to 0, the functions in this module use a non-backward compatible way
of representing multi-byte pixels on little-endian systems. The SGI for
which this module was originally written is a big-endian system, so setting
this variable will have no effect. However, the code wasn't originally
intended to run on anything else, so it made assumptions about byte order
which are not universal. Setting this variable to 0 will cause the byte
order to be reversed on little-endian systems, so that it then is the same as
on big-endian systems.
PK %�\� �!EC EC % html/_sources/library/imaplib.rst.txtnu �[��� :mod:`imaplib` --- IMAP4 protocol client
========================================
.. module:: imaplib
:synopsis: IMAP4 protocol client (requires sockets).
.. moduleauthor:: Piers Lauder <piers@communitysolutions.com.au>
.. sectionauthor:: Piers Lauder <piers@communitysolutions.com.au>
.. revised by ESR, January 2000
.. changes for IMAP4_SSL by Tino Lange <Tino.Lange@isg.de>, March 2002
.. changes for IMAP4_stream by Piers Lauder <piers@communitysolutions.com.au>,
November 2002
.. index::
pair: IMAP4; protocol
pair: IMAP4_SSL; protocol
pair: IMAP4_stream; protocol
**Source code:** :source:`Lib/imaplib.py`
--------------
This module defines three classes, :class:`IMAP4`, :class:`IMAP4_SSL` and
:class:`IMAP4_stream`, which encapsulate a connection to an IMAP4 server and
implement a large subset of the IMAP4rev1 client protocol as defined in
:rfc:`2060`. It is backward compatible with IMAP4 (:rfc:`1730`) servers, but
note that the ``STATUS`` command is not supported in IMAP4.
Three classes are provided by the :mod:`imaplib` module, :class:`IMAP4` is the
base class:
.. class:: IMAP4([host[, port]])
This class implements the actual IMAP4 protocol. The connection is created and
protocol version (IMAP4 or IMAP4rev1) is determined when the instance is
initialized. If *host* is not specified, ``''`` (the local host) is used. If
*port* is omitted, the standard IMAP4 port (143) is used.
Three exceptions are defined as attributes of the :class:`IMAP4` class:
.. exception:: IMAP4.error
Exception raised on any errors. The reason for the exception is passed to the
constructor as a string.
.. exception:: IMAP4.abort
IMAP4 server errors cause this exception to be raised. This is a sub-class of
:exc:`IMAP4.error`. Note that closing the instance and instantiating a new one
will usually allow recovery from this exception.
.. exception:: IMAP4.readonly
This exception is raised when a writable mailbox has its status changed by the
server. This is a sub-class of :exc:`IMAP4.error`. Some other client now has
write permission, and the mailbox will need to be re-opened to re-obtain write
permission.
There's also a subclass for secure connections:
.. class:: IMAP4_SSL([host[, port[, keyfile[, certfile]]]])
This is a subclass derived from :class:`IMAP4` that connects over an SSL
encrypted socket (to use this class you need a socket module that was compiled
with SSL support). If *host* is not specified, ``''`` (the local host) is used.
If *port* is omitted, the standard IMAP4-over-SSL port (993) is used. *keyfile*
and *certfile* are also optional - they can contain a PEM formatted private key
and certificate chain file for the SSL connection.
The second subclass allows for connections created by a child process:
.. class:: IMAP4_stream(command)
This is a subclass derived from :class:`IMAP4` that connects to the
``stdin/stdout`` file descriptors created by passing *command* to
``os.popen2()``.
.. versionadded:: 2.3
The following utility functions are defined:
.. function:: Internaldate2tuple(datestr)
Parse an IMAP4 ``INTERNALDATE`` string and return corresponding local
time. The return value is a :class:`time.struct_time` instance or
``None`` if the string has wrong format.
.. function:: Int2AP(num)
Converts an integer into a string representation using characters from the set
[``A`` .. ``P``].
.. function:: ParseFlags(flagstr)
Converts an IMAP4 ``FLAGS`` response to a tuple of individual flags.
.. function:: Time2Internaldate(date_time)
Convert *date_time* to an IMAP4 ``INTERNALDATE`` representation. The
return value is a string in the form: ``"DD-Mmm-YYYY HH:MM:SS
+HHMM"`` (including double-quotes). The *date_time* argument can be a
number (int or float) representing seconds since epoch (as returned
by :func:`time.time`), a 9-tuple representing local time (as returned by
:func:`time.localtime`), or a double-quoted string. In the last case, it
is assumed to already be in the correct format.
Note that IMAP4 message numbers change as the mailbox changes; in particular,
after an ``EXPUNGE`` command performs deletions the remaining messages are
renumbered. So it is highly advisable to use UIDs instead, with the UID command.
At the end of the module, there is a test section that contains a more extensive
example of usage.
.. seealso::
Documents describing the protocol, and sources and binaries for servers
implementing it, can all be found at the University of Washington's *IMAP
Information Center* (https://www.washington.edu/imap/).
.. _imap4-objects:
IMAP4 Objects
-------------
All IMAP4rev1 commands are represented by methods of the same name, either
upper-case or lower-case.
All arguments to commands are converted to strings, except for ``AUTHENTICATE``,
and the last argument to ``APPEND`` which is passed as an IMAP4 literal. If
necessary (the string contains IMAP4 protocol-sensitive characters and isn't
enclosed with either parentheses or double quotes) each string is quoted.
However, the *password* argument to the ``LOGIN`` command is always quoted. If
you want to avoid having an argument string quoted (eg: the *flags* argument to
``STORE``) then enclose the string in parentheses (eg: ``r'(\Deleted)'``).
Each command returns a tuple: ``(type, [data, ...])`` where *type* is usually
``'OK'`` or ``'NO'``, and *data* is either the text from the command response,
or mandated results from the command. Each *data* is either a string, or a
tuple. If a tuple, then the first part is the header of the response, and the
second part contains the data (ie: 'literal' value).
The *message_set* options to commands below is a string specifying one or more
messages to be acted upon. It may be a simple message number (``'1'``), a range
of message numbers (``'2:4'``), or a group of non-contiguous ranges separated by
commas (``'1:3,6:9'``). A range can contain an asterisk to indicate an infinite
upper bound (``'3:*'``).
An :class:`IMAP4` instance has the following methods:
.. method:: IMAP4.append(mailbox, flags, date_time, message)
Append *message* to named mailbox.
.. method:: IMAP4.authenticate(mechanism, authobject)
Authenticate command --- requires response processing.
*mechanism* specifies which authentication mechanism is to be used - it should
appear in the instance variable ``capabilities`` in the form ``AUTH=mechanism``.
*authobject* must be a callable object::
data = authobject(response)
It will be called to process server continuation responses. It should return
``data`` that will be encoded and sent to server. It should return ``None`` if
the client abort response ``*`` should be sent instead.
.. method:: IMAP4.check()
Checkpoint mailbox on server.
.. method:: IMAP4.close()
Close currently selected mailbox. Deleted messages are removed from writable
mailbox. This is the recommended command before ``LOGOUT``.
.. method:: IMAP4.copy(message_set, new_mailbox)
Copy *message_set* messages onto end of *new_mailbox*.
.. method:: IMAP4.create(mailbox)
Create new mailbox named *mailbox*.
.. method:: IMAP4.delete(mailbox)
Delete old mailbox named *mailbox*.
.. method:: IMAP4.deleteacl(mailbox, who)
Delete the ACLs (remove any rights) set for who on mailbox.
.. versionadded:: 2.4
.. method:: IMAP4.expunge()
Permanently remove deleted items from selected mailbox. Generates an ``EXPUNGE``
response for each deleted message. Returned data contains a list of ``EXPUNGE``
message numbers in order received.
.. method:: IMAP4.fetch(message_set, message_parts)
Fetch (parts of) messages. *message_parts* should be a string of message part
names enclosed within parentheses, eg: ``"(UID BODY[TEXT])"``. Returned data
are tuples of message part envelope and data.
.. method:: IMAP4.getacl(mailbox)
Get the ``ACL``\ s for *mailbox*. The method is non-standard, but is supported
by the ``Cyrus`` server.
.. method:: IMAP4.getannotation(mailbox, entry, attribute)
Retrieve the specified ``ANNOTATION``\ s for *mailbox*. The method is
non-standard, but is supported by the ``Cyrus`` server.
.. versionadded:: 2.5
.. method:: IMAP4.getquota(root)
Get the ``quota`` *root*'s resource usage and limits. This method is part of the
IMAP4 QUOTA extension defined in rfc2087.
.. versionadded:: 2.3
.. method:: IMAP4.getquotaroot(mailbox)
Get the list of ``quota`` ``roots`` for the named *mailbox*. This method is part
of the IMAP4 QUOTA extension defined in rfc2087.
.. versionadded:: 2.3
.. method:: IMAP4.list([directory[, pattern]])
List mailbox names in *directory* matching *pattern*. *directory* defaults to
the top-level mail folder, and *pattern* defaults to match anything. Returned
data contains a list of ``LIST`` responses.
.. method:: IMAP4.login(user, password)
Identify the client using a plaintext password. The *password* will be quoted.
.. method:: IMAP4.login_cram_md5(user, password)
Force use of ``CRAM-MD5`` authentication when identifying the client to protect
the password. Will only work if the server ``CAPABILITY`` response includes the
phrase ``AUTH=CRAM-MD5``.
.. versionadded:: 2.3
.. method:: IMAP4.logout()
Shutdown connection to server. Returns server ``BYE`` response.
.. method:: IMAP4.lsub([directory[, pattern]])
List subscribed mailbox names in directory matching pattern. *directory*
defaults to the top level directory and *pattern* defaults to match any mailbox.
Returned data are tuples of message part envelope and data.
.. method:: IMAP4.myrights(mailbox)
Show my ACLs for a mailbox (i.e. the rights that I have on mailbox).
.. versionadded:: 2.4
.. method:: IMAP4.namespace()
Returns IMAP namespaces as defined in RFC2342.
.. versionadded:: 2.3
.. method:: IMAP4.noop()
Send ``NOOP`` to server.
.. method:: IMAP4.open(host, port)
Opens socket to *port* at *host*. This method is implicitly called by
the :class:`IMAP4` constructor. The connection objects established by this
method will be used in the :meth:`IMAP4.read`, :meth:`IMAP4.readline`,
:meth:`IMAP4.send`, and :meth:`IMAP4.shutdown` methods. You may override
this method.
.. method:: IMAP4.partial(message_num, message_part, start, length)
Fetch truncated part of a message. Returned data is a tuple of message part
envelope and data.
.. method:: IMAP4.proxyauth(user)
Assume authentication as *user*. Allows an authorised administrator to proxy
into any user's mailbox.
.. versionadded:: 2.3
.. method:: IMAP4.read(size)
Reads *size* bytes from the remote server. You may override this method.
.. method:: IMAP4.readline()
Reads one line from the remote server. You may override this method.
.. method:: IMAP4.recent()
Prompt server for an update. Returned data is ``None`` if no new messages, else
value of ``RECENT`` response.
.. method:: IMAP4.rename(oldmailbox, newmailbox)
Rename mailbox named *oldmailbox* to *newmailbox*.
.. method:: IMAP4.response(code)
Return data for response *code* if received, or ``None``. Returns the given
code, instead of the usual type.
.. method:: IMAP4.search(charset, criterion[, ...])
Search mailbox for matching messages. *charset* may be ``None``, in which case
no ``CHARSET`` will be specified in the request to the server. The IMAP
protocol requires that at least one criterion be specified; an exception will be
raised when the server returns an error.
Example::
# M is a connected IMAP4 instance...
typ, msgnums = M.search(None, 'FROM', '"LDJ"')
# or:
typ, msgnums = M.search(None, '(FROM "LDJ")')
.. method:: IMAP4.select([mailbox[, readonly]])
Select a mailbox. Returned data is the count of messages in *mailbox*
(``EXISTS`` response). The default *mailbox* is ``'INBOX'``. If the *readonly*
flag is set, modifications to the mailbox are not allowed.
.. method:: IMAP4.send(data)
Sends ``data`` to the remote server. You may override this method.
.. method:: IMAP4.setacl(mailbox, who, what)
Set an ``ACL`` for *mailbox*. The method is non-standard, but is supported by
the ``Cyrus`` server.
.. method:: IMAP4.setannotation(mailbox, entry, attribute[, ...])
Set ``ANNOTATION``\ s for *mailbox*. The method is non-standard, but is
supported by the ``Cyrus`` server.
.. versionadded:: 2.5
.. method:: IMAP4.setquota(root, limits)
Set the ``quota`` *root*'s resource *limits*. This method is part of the IMAP4
QUOTA extension defined in rfc2087.
.. versionadded:: 2.3
.. method:: IMAP4.shutdown()
Close connection established in ``open``. This method is implicitly
called by :meth:`IMAP4.logout`. You may override this method.
.. method:: IMAP4.socket()
Returns socket instance used to connect to server.
.. method:: IMAP4.sort(sort_criteria, charset, search_criterion[, ...])
The ``sort`` command is a variant of ``search`` with sorting semantics for the
results. Returned data contains a space separated list of matching message
numbers.
Sort has two arguments before the *search_criterion* argument(s); a
parenthesized list of *sort_criteria*, and the searching *charset*. Note that
unlike ``search``, the searching *charset* argument is mandatory. There is also
a ``uid sort`` command which corresponds to ``sort`` the way that ``uid search``
corresponds to ``search``. The ``sort`` command first searches the mailbox for
messages that match the given searching criteria using the charset argument for
the interpretation of strings in the searching criteria. It then returns the
numbers of matching messages.
This is an ``IMAP4rev1`` extension command.
.. method:: IMAP4.status(mailbox, names)
Request named status conditions for *mailbox*.
.. method:: IMAP4.store(message_set, command, flag_list)
Alters flag dispositions for messages in mailbox. *command* is specified by
section 6.4.6 of :rfc:`2060` as being one of "FLAGS", "+FLAGS", or "-FLAGS",
optionally with a suffix of ".SILENT".
For example, to set the delete flag on all messages::
typ, data = M.search(None, 'ALL')
for num in data[0].split():
M.store(num, '+FLAGS', '\\Deleted')
M.expunge()
.. method:: IMAP4.subscribe(mailbox)
Subscribe to new mailbox.
.. method:: IMAP4.thread(threading_algorithm, charset, search_criterion[, ...])
The ``thread`` command is a variant of ``search`` with threading semantics for
the results. Returned data contains a space separated list of thread members.
Thread members consist of zero or more messages numbers, delimited by spaces,
indicating successive parent and child.
Thread has two arguments before the *search_criterion* argument(s); a
*threading_algorithm*, and the searching *charset*. Note that unlike
``search``, the searching *charset* argument is mandatory. There is also a
``uid thread`` command which corresponds to ``thread`` the way that ``uid
search`` corresponds to ``search``. The ``thread`` command first searches the
mailbox for messages that match the given searching criteria using the charset
argument for the interpretation of strings in the searching criteria. It then
returns the matching messages threaded according to the specified threading
algorithm.
This is an ``IMAP4rev1`` extension command.
.. versionadded:: 2.4
.. method:: IMAP4.uid(command, arg[, ...])
Execute command args with messages identified by UID, rather than message
number. Returns response appropriate to command. At least one argument must be
supplied; if none are provided, the server will return an error and an exception
will be raised.
.. method:: IMAP4.unsubscribe(mailbox)
Unsubscribe from old mailbox.
.. method:: IMAP4.xatom(name[, arg[, ...]])
Allow simple extension commands notified by server in ``CAPABILITY`` response.
Instances of :class:`IMAP4_SSL` have just one additional method:
.. method:: IMAP4_SSL.ssl()
Returns SSLObject instance used for the secure connection with the server.
The following attributes are defined on instances of :class:`IMAP4`:
.. attribute:: IMAP4.PROTOCOL_VERSION
The most recent supported protocol in the ``CAPABILITY`` response from the
server.
.. attribute:: IMAP4.debug
Integer value to control debugging output. The initialize value is taken from
the module variable ``Debug``. Values greater than three trace each command.
.. _imap4-example:
IMAP4 Example
-------------
Here is a minimal example (without error checking) that opens a mailbox and
retrieves and prints all messages::
import getpass, imaplib
M = imaplib.IMAP4()
M.login(getpass.getuser(), getpass.getpass())
M.select()
typ, data = M.search(None, 'ALL')
for num in data[0].split():
typ, data = M.fetch(num, '(RFC822)')
print 'Message %s\n%s\n' % (num, data[0][1])
M.close()
M.logout()
PK %�\����
�
% html/_sources/library/imgfile.rst.txtnu �[���
:mod:`imgfile` --- Support for SGI imglib files
===============================================
.. module:: imgfile
:platform: IRIX
:synopsis: Support for SGI imglib files.
:deprecated:
.. deprecated:: 2.6
The :mod:`imgfile` module has been removed in Python 3.
The :mod:`imgfile` module allows Python programs to access SGI imglib image
files (also known as :file:`.rgb` files). The module is far from complete, but
is provided anyway since the functionality that there is enough in some cases.
Currently, colormap files are not supported.
The module defines the following variables and functions:
.. exception:: error
This exception is raised on all errors, such as unsupported file type, etc.
.. function:: getsizes(file)
This function returns a tuple ``(x, y, z)`` where *x* and *y* are the size of
the image in pixels and *z* is the number of bytes per pixel. Only 3 byte RGB
pixels and 1 byte greyscale pixels are currently supported.
.. function:: read(file)
This function reads and decodes the image on the specified file, and returns it
as a Python string. The string has either 1 byte greyscale pixels or 4 byte RGBA
pixels. The bottom left pixel is the first in the string. This format is
suitable to pass to :func:`gl.lrectwrite`, for instance.
.. function:: readscaled(file, x, y, filter[, blur])
This function is identical to read but it returns an image that is scaled to the
given *x* and *y* sizes. If the *filter* and *blur* parameters are omitted
scaling is done by simply dropping or duplicating pixels, so the result will be
less than perfect, especially for computer-generated images.
Alternatively, you can specify a filter to use to smooth the image after
scaling. The filter forms supported are ``'impulse'``, ``'box'``,
``'triangle'``, ``'quadratic'`` and ``'gaussian'``. If a filter is specified
*blur* is an optional parameter specifying the blurriness of the filter. It
defaults to ``1.0``.
:func:`readscaled` makes no attempt to keep the aspect ratio correct, so that is
the users' responsibility.
.. function:: ttob(flag)
This function sets a global flag which defines whether the scan lines of the
image are read or written from bottom to top (flag is zero, compatible with SGI
GL) or from top to bottom(flag is one, compatible with X). The default is zero.
.. function:: write(file, data, x, y, z)
This function writes the RGB or greyscale data in *data* to image file *file*.
*x* and *y* give the size of the image, *z* is 1 for 1 byte greyscale images or
3 for RGB images (which are stored as 4 byte values of which only the lower
three bytes are used). These are the formats returned by :func:`gl.lrectread`.
PK %�\z��^K
K
$ html/_sources/library/imghdr.rst.txtnu �[��� :mod:`imghdr` --- Determine the type of an image
================================================
.. module:: imghdr
:synopsis: Determine the type of image contained in a file or byte stream.
**Source code:** :source:`Lib/imghdr.py`
--------------
The :mod:`imghdr` module determines the type of image contained in a file or
byte stream.
The :mod:`imghdr` module defines the following function:
.. function:: what(filename[, h])
Tests the image data contained in the file named by *filename*, and returns a
string describing the image type. If optional *h* is provided, the *filename*
is ignored and *h* is assumed to contain the byte stream to test.
The following image types are recognized, as listed below with the return value
from :func:`what`:
+------------+-----------------------------------+
| Value | Image format |
+============+===================================+
| ``'rgb'`` | SGI ImgLib Files |
+------------+-----------------------------------+
| ``'gif'`` | GIF 87a and 89a Files |
+------------+-----------------------------------+
| ``'pbm'`` | Portable Bitmap Files |
+------------+-----------------------------------+
| ``'pgm'`` | Portable Graymap Files |
+------------+-----------------------------------+
| ``'ppm'`` | Portable Pixmap Files |
+------------+-----------------------------------+
| ``'tiff'`` | TIFF Files |
+------------+-----------------------------------+
| ``'rast'`` | Sun Raster Files |
+------------+-----------------------------------+
| ``'xbm'`` | X Bitmap Files |
+------------+-----------------------------------+
| ``'jpeg'`` | JPEG data in JFIF or Exif formats |
+------------+-----------------------------------+
| ``'bmp'`` | BMP files |
+------------+-----------------------------------+
| ``'png'`` | Portable Network Graphics |
+------------+-----------------------------------+
.. versionadded:: 2.5
Exif detection.
You can extend the list of file types :mod:`imghdr` can recognize by appending
to this variable:
.. data:: tests
A list of functions performing the individual tests. Each function takes two
arguments: the byte-stream and an open file-like object. When :func:`what` is
called with a byte-stream, the file-like object will be ``None``.
The test function should return a string describing the image type if the test
succeeded, or ``None`` if it failed.
Example::
>>> import imghdr
>>> imghdr.what('bass.gif')
'gif'
PK %�\B�(�11 11 ! html/_sources/library/imp.rst.txtnu �[���
:mod:`imp` --- Access the :keyword:`import` internals
=====================================================
.. module:: imp
:synopsis: Access the implementation of the import statement.
.. index:: statement: import
This module provides an interface to the mechanisms used to implement the
:keyword:`import` statement. It defines the following constants and functions:
.. function:: get_magic()
.. index:: pair: file; byte-code
Return the magic string value used to recognize byte-compiled code files
(:file:`.pyc` files). (This value may be different for each Python version.)
.. function:: get_suffixes()
Return a list of 3-element tuples, each describing a particular type of
module. Each triple has the form ``(suffix, mode, type)``, where *suffix* is
a string to be appended to the module name to form the filename to search
for, *mode* is the mode string to pass to the built-in :func:`open` function
to open the file (this can be ``'r'`` for text files or ``'rb'`` for binary
files), and *type* is the file type, which has one of the values
:const:`PY_SOURCE`, :const:`PY_COMPILED`, or :const:`C_EXTENSION`, described
below.
.. function:: find_module(name[, path])
Try to find the module *name*. If *path* is omitted or ``None``, the list of
directory names given by ``sys.path`` is searched, but first a few special
places are searched: the function tries to find a built-in module with the
given name (:const:`C_BUILTIN`), then a frozen module (:const:`PY_FROZEN`),
and on some systems some other places are looked in as well (on Windows, it
looks in the registry which may point to a specific file).
Otherwise, *path* must be a list of directory names; each directory is
searched for files with any of the suffixes returned by :func:`get_suffixes`
above. Invalid names in the list are silently ignored (but all list items
must be strings).
If search is successful, the return value is a 3-element tuple ``(file,
pathname, description)``:
*file* is an open file object positioned at the beginning, *pathname* is the
pathname of the file found, and *description* is a 3-element tuple as
contained in the list returned by :func:`get_suffixes` describing the kind of
module found.
If the module does not live in a file, the returned *file* is ``None``,
*pathname* is the empty string, and the *description* tuple contains empty
strings for its suffix and mode; the module type is indicated as given in
parentheses above. If the search is unsuccessful, :exc:`ImportError` is
raised. Other exceptions indicate problems with the arguments or
environment.
If the module is a package, *file* is ``None``, *pathname* is the package
path and the last item in the *description* tuple is :const:`PKG_DIRECTORY`.
This function does not handle hierarchical module names (names containing
dots). In order to find *P.M*, that is, submodule *M* of package *P*, use
:func:`find_module` and :func:`load_module` to find and load package *P*, and
then use :func:`find_module` with the *path* argument set to ``P.__path__``.
When *P* itself has a dotted name, apply this recipe recursively.
.. function:: load_module(name, file, pathname, description)
.. index:: builtin: reload
Load a module that was previously found by :func:`find_module` (or by an
otherwise conducted search yielding compatible results). This function does
more than importing the module: if the module was already imported, it is
equivalent to a :func:`reload`! The *name* argument indicates the full
module name (including the package name, if this is a submodule of a
package). The *file* argument is an open file, and *pathname* is the
corresponding file name; these can be ``None`` and ``''``, respectively, when
the module is a package or not being loaded from a file. The *description*
argument is a tuple, as would be returned by :func:`get_suffixes`, describing
what kind of module must be loaded.
If the load is successful, the return value is the module object; otherwise,
an exception (usually :exc:`ImportError`) is raised.
**Important:** the caller is responsible for closing the *file* argument, if
it was not ``None``, even when an exception is raised. This is best done
using a :keyword:`try` ... :keyword:`finally` statement.
.. function:: new_module(name)
Return a new empty module object called *name*. This object is *not* inserted
in ``sys.modules``.
.. function:: lock_held()
Return ``True`` if the import lock is currently held, else ``False``. On
platforms without threads, always return ``False``.
On platforms with threads, a thread executing an import holds an internal lock
until the import is complete. This lock blocks other threads from doing an
import until the original import completes, which in turn prevents other threads
from seeing incomplete module objects constructed by the original thread while
in the process of completing its import (and the imports, if any, triggered by
that).
.. function:: acquire_lock()
Acquire the interpreter's import lock for the current thread. This lock should
be used by import hooks to ensure thread-safety when importing modules.
Once a thread has acquired the import lock, the same thread may acquire it
again without blocking; the thread must release it once for each time it has
acquired it.
On platforms without threads, this function does nothing.
.. versionadded:: 2.3
.. function:: release_lock()
Release the interpreter's import lock. On platforms without threads, this
function does nothing.
.. versionadded:: 2.3
The following constants with integer values, defined in this module, are used to
indicate the search result of :func:`find_module`.
.. data:: PY_SOURCE
The module was found as a source file.
.. data:: PY_COMPILED
The module was found as a compiled code object file.
.. data:: C_EXTENSION
The module was found as dynamically loadable shared library.
.. data:: PKG_DIRECTORY
The module was found as a package directory.
.. data:: C_BUILTIN
The module was found as a built-in module.
.. data:: PY_FROZEN
The module was found as a frozen module (see :func:`init_frozen`).
The following constant and functions are obsolete; their functionality is
available through :func:`find_module` or :func:`load_module`. They are kept
around for backward compatibility:
.. data:: SEARCH_ERROR
Unused.
.. function:: init_builtin(name)
Initialize the built-in module called *name* and return its module object along
with storing it in ``sys.modules``. If the module was already initialized, it
will be initialized *again*. Re-initialization involves the copying of the
built-in module's ``__dict__`` from the cached module over the module's entry in
``sys.modules``. If there is no built-in module called *name*, ``None`` is
returned.
.. function:: init_frozen(name)
Initialize the frozen module called *name* and return its module object. If
the module was already initialized, it will be initialized *again*. If there
is no frozen module called *name*, ``None`` is returned. (Frozen modules are
modules written in Python whose compiled byte-code object is incorporated
into a custom-built Python interpreter by Python's :program:`freeze`
utility. See :file:`Tools/freeze/` for now.)
.. function:: is_builtin(name)
Return ``1`` if there is a built-in module called *name* which can be
initialized again. Return ``-1`` if there is a built-in module called *name*
which cannot be initialized again (see :func:`init_builtin`). Return ``0`` if
there is no built-in module called *name*.
.. function:: is_frozen(name)
Return ``True`` if there is a frozen module (see :func:`init_frozen`) called
*name*, or ``False`` if there is no such module.
.. function:: load_compiled(name, pathname, [file])
.. index:: pair: file; byte-code
Load and initialize a module implemented as a byte-compiled code file and return
its module object. If the module was already initialized, it will be
initialized *again*. The *name* argument is used to create or access a module
object. The *pathname* argument points to the byte-compiled code file. The
*file* argument is the byte-compiled code file, open for reading in binary mode,
from the beginning. It must currently be a real file object, not a user-defined
class emulating a file.
.. function:: load_dynamic(name, pathname[, file])
Load and initialize a module implemented as a dynamically loadable shared
library and return its module object. If the module was already initialized, it
will be initialized *again*. Re-initialization involves copying the ``__dict__``
attribute of the cached instance of the module over the value used in the module
cached in ``sys.modules``. The *pathname* argument must point to the shared
library. The *name* argument is used to construct the name of the
initialization function: an external C function called ``initname()`` in the
shared library is called. The optional *file* argument is ignored. (Note:
using shared libraries is highly system dependent, and not all systems support
it.)
.. impl-detail::
The import internals identify extension modules by filename, so doing
``foo = load_dynamic("foo", "mod.so")`` and
``bar = load_dynamic("bar", "mod.so")`` will result in both foo and bar
referring to the same module, regardless of whether or not
``mod.so`` exports an ``initbar`` function. On systems which
support them, symlinks can be used to import multiple modules from
the same shared library, as each reference to the module will use
a different file name.
.. function:: load_source(name, pathname[, file])
Load and initialize a module implemented as a Python source file and return its
module object. If the module was already initialized, it will be initialized
*again*. The *name* argument is used to create or access a module object. The
*pathname* argument points to the source file. The *file* argument is the
source file, open for reading as text, from the beginning. It must currently be
a real file object, not a user-defined class emulating a file. Note that if a
properly matching byte-compiled file (with suffix :file:`.pyc` or :file:`.pyo`)
exists, it will be used instead of parsing the given source file.
.. class:: NullImporter(path_string)
The :class:`NullImporter` type is a :pep:`302` import hook that handles
non-directory path strings by failing to find any modules. Calling this type
with an existing directory or empty string raises :exc:`ImportError`.
Otherwise, a :class:`NullImporter` instance is returned.
Python adds instances of this type to ``sys.path_importer_cache`` for any path
entries that are not directories and are not handled by any other path hooks on
``sys.path_hooks``. Instances have only one method:
.. method:: NullImporter.find_module(fullname [, path])
This method always returns ``None``, indicating that the requested module could
not be found.
.. versionadded:: 2.5
.. _examples-imp:
Examples
--------
The following function emulates what was the standard import statement up to
Python 1.4 (no hierarchical module names). (This *implementation* wouldn't work
in that version, since :func:`find_module` has been extended and
:func:`load_module` has been added in 1.4.) ::
import imp
import sys
def __import__(name, globals=None, locals=None, fromlist=None):
# Fast path: see if the module has already been imported.
try:
return sys.modules[name]
except KeyError:
pass
# If any of the following calls raises an exception,
# there's a problem we can't handle -- let the caller handle it.
fp, pathname, description = imp.find_module(name)
try:
return imp.load_module(name, fp, pathname, description)
finally:
# Since we may exit via an exception, close fp explicitly.
if fp:
fp.close()
.. index::
builtin: reload
module: knee
A more complete example that implements hierarchical module names and includes a
:func:`reload` function can be found in the module :mod:`knee`. The :mod:`knee`
module can be found in :file:`Demo/imputil/` in the Python source distribution.
PK %�\rs�f f ' html/_sources/library/importlib.rst.txtnu �[��� :mod:`importlib` --- Convenience wrappers for :func:`__import__`
================================================================
.. module:: importlib
:synopsis: Convenience wrappers for __import__
.. moduleauthor:: Brett Cannon <brett@python.org>
.. sectionauthor:: Brett Cannon <brett@python.org>
.. versionadded:: 2.7
This module is a minor subset of what is available in the more full-featured
package of the same name from Python 3.1 that provides a complete
implementation of :keyword:`import`. What is here has been provided to
help ease in transitioning from 2.7 to 3.1.
.. function:: import_module(name, package=None)
Import a module. The *name* argument specifies what module to
import in absolute or relative terms
(e.g. either ``pkg.mod`` or ``..mod``). If the name is
specified in relative terms, then the *package* argument must be
specified to the package which is to act as the anchor for resolving the
package name (e.g. ``import_module('..mod', 'pkg.subpkg')`` will import
``pkg.mod``). The specified module will be inserted into
:data:`sys.modules` and returned.
PK %�\&v� o o % html/_sources/library/imputil.rst.txtnu �[���
:mod:`imputil` --- Import utilities
=====================================================
.. module:: imputil
:synopsis: Manage and augment the import process.
:deprecated:
.. deprecated:: 2.6
The :mod:`imputil` module has been removed in Python 3.
.. index:: statement: import
This module provides a very handy and useful mechanism for custom
:keyword:`import` hooks. Compared to the older :mod:`ihooks` module,
:mod:`imputil` takes a dramatically simpler and more straight-forward
approach to custom :keyword:`import` functions.
.. class:: ImportManager([fs_imp])
Manage the import process.
.. method:: ImportManager.install([namespace])
Install this ImportManager into the specified namespace.
.. method:: ImportManager.uninstall()
Restore the previous import mechanism.
.. method:: ImportManager.add_suffix(suffix, importFunc)
Undocumented.
.. class:: Importer()
Base class for replacing standard import functions.
.. method:: Importer.import_top(name)
Import a top-level module.
.. method:: Importer.get_code(parent, modname, fqname)
Find and retrieve the code for the given module.
*parent* specifies a parent module to define a context for importing.
It may be ``None``, indicating no particular context for the search.
*modname* specifies a single module (not dotted) within the parent.
*fqname* specifies the fully-qualified module name. This is a
(potentially) dotted name from the "root" of the module namespace
down to the modname.
If there is no parent, then modname==fqname.
This method should return ``None``, or a 3-tuple.
* If the module was not found, then ``None`` should be returned.
* The first item of the 2- or 3-tuple should be the integer 0 or 1,
specifying whether the module that was found is a package or not.
* The second item is the code object for the module (it will be
executed within the new module's namespace). This item can also
be a fully-loaded module object (e.g. loaded from a shared lib).
* The third item is a dictionary of name/value pairs that will be
inserted into new module before the code object is executed. This
is provided in case the module's code expects certain values (such
as where the module was found). When the second item is a module
object, then these names/values will be inserted *after* the module
has been loaded/initialized.
.. class:: BuiltinImporter()
Emulate the import mechanism for built-in and frozen modules. This is a
sub-class of the :class:`Importer` class.
.. method:: BuiltinImporter.get_code(parent, modname, fqname)
Undocumented.
.. function:: py_suffix_importer(filename, finfo, fqname)
Undocumented.
.. class:: DynLoadSuffixImporter([desc])
Undocumented.
.. method:: DynLoadSuffixImporter.import_file(filename, finfo, fqname)
Undocumented.
.. _examples-imputil:
Examples
--------
This is a re-implementation of hierarchical module import.
This code is intended to be read, not executed. However, it does work
-- all you need to do to enable it is "import knee".
(The name is a pun on the clunkier predecessor of this module, "ni".)
::
import sys, imp, __builtin__
# Replacement for __import__()
def import_hook(name, globals=None, locals=None, fromlist=None):
parent = determine_parent(globals)
q, tail = find_head_package(parent, name)
m = load_tail(q, tail)
if not fromlist:
return q
if hasattr(m, "__path__"):
ensure_fromlist(m, fromlist)
return m
def determine_parent(globals):
if not globals or not globals.has_key("__name__"):
return None
pname = globals['__name__']
if globals.has_key("__path__"):
parent = sys.modules[pname]
assert globals is parent.__dict__
return parent
if '.' in pname:
i = pname.rfind('.')
pname = pname[:i]
parent = sys.modules[pname]
assert parent.__name__ == pname
return parent
return None
def find_head_package(parent, name):
if '.' in name:
i = name.find('.')
head = name[:i]
tail = name[i+1:]
else:
head = name
tail = ""
if parent:
qname = "%s.%s" % (parent.__name__, head)
else:
qname = head
q = import_module(head, qname, parent)
if q: return q, tail
if parent:
qname = head
parent = None
q = import_module(head, qname, parent)
if q: return q, tail
raise ImportError("No module named " + qname)
def load_tail(q, tail):
m = q
while tail:
i = tail.find('.')
if i < 0: i = len(tail)
head, tail = tail[:i], tail[i+1:]
mname = "%s.%s" % (m.__name__, head)
m = import_module(head, mname, m)
if not m:
raise ImportError("No module named " + mname)
return m
def ensure_fromlist(m, fromlist, recursive=0):
for sub in fromlist:
if sub == "*":
if not recursive:
try:
all = m.__all__
except AttributeError:
pass
else:
ensure_fromlist(m, all, 1)
continue
if sub != "*" and not hasattr(m, sub):
subname = "%s.%s" % (m.__name__, sub)
submod = import_module(sub, subname, m)
if not submod:
raise ImportError("No module named " + subname)
def import_module(partname, fqname, parent):
try:
return sys.modules[fqname]
except KeyError:
pass
try:
fp, pathname, stuff = imp.find_module(partname,
parent and parent.__path__)
except ImportError:
return None
try:
m = imp.load_module(fqname, fp, pathname, stuff)
finally:
if fp: fp.close()
if parent:
setattr(parent, partname, m)
return m
# Replacement for reload()
def reload_hook(module):
name = module.__name__
if '.' not in name:
return import_module(name, name, None)
i = name.rfind('.')
pname = name[:i]
parent = sys.modules[pname]
return import_module(name[i+1:], name, parent)
# Save the original hooks
original_import = __builtin__.__import__
original_reload = __builtin__.reload
# Now install our hooks
__builtin__.__import__ = import_hook
__builtin__.reload = reload_hook
.. index::
module: knee
Also see the :mod:`importers` module (which can be found
in :file:`Demo/imputil/` in the Python source distribution) for additional
examples.
PK %�\g5�s� � # html/_sources/library/index.rst.txtnu �[��� .. _library-index:
###############################
The Python Standard Library
###############################
While :ref:`reference-index` describes the exact syntax and
semantics of the Python language, this library reference manual
describes the standard library that is distributed with Python. It also
describes some of the optional components that are commonly included
in Python distributions.
Python's standard library is very extensive, offering a wide range of
facilities as indicated by the long table of contents listed below. The
library contains built-in modules (written in C) that provide access to
system functionality such as file I/O that would otherwise be
inaccessible to Python programmers, as well as modules written in Python
that provide standardized solutions for many problems that occur in
everyday programming. Some of these modules are explicitly designed to
encourage and enhance the portability of Python programs by abstracting
away platform-specifics into platform-neutral APIs.
The Python installers for the Windows platform usually include
the entire standard library and often also include many additional
components. For Unix-like operating systems Python is normally provided
as a collection of packages, so it may be necessary to use the packaging
tools provided with the operating system to obtain some or all of the
optional components.
In addition to the standard library, there is a growing collection of
several thousand components (from individual programs and modules to
packages and entire application development frameworks), available from
the `Python Package Index <https://pypi.org>`_.
.. toctree::
:maxdepth: 2
:numbered:
intro.rst
functions.rst
constants.rst
stdtypes.rst
exceptions.rst
strings.rst
datatypes.rst
numeric.rst
filesys.rst
persistence.rst
archiving.rst
fileformats.rst
crypto.rst
allos.rst
someos.rst
ipc.rst
netdata.rst
markup.rst
internet.rst
mm.rst
i18n.rst
frameworks.rst
tk.rst
development.rst
debug.rst
distribution.rst
python.rst
custominterp.rst
restricted.rst
modules.rst
language.rst
compiler.rst
misc.rst
windows.rst
unix.rst
mac.rst
macosa.rst
sgi.rst
sun.rst
undoc.rst
PK %�\�B�m �m % html/_sources/library/inspect.rst.txtnu �[��� :mod:`inspect` --- Inspect live objects
=======================================
.. module:: inspect
:synopsis: Extract information and source code from live objects.
.. moduleauthor:: Ka-Ping Yee <ping@lfw.org>
.. sectionauthor:: Ka-Ping Yee <ping@lfw.org>
.. versionadded:: 2.1
**Source code:** :source:`Lib/inspect.py`
--------------
The :mod:`inspect` module provides several useful functions to help get
information about live objects such as modules, classes, methods, functions,
tracebacks, frame objects, and code objects. For example, it can help you
examine the contents of a class, retrieve the source code of a method, extract
and format the argument list for a function, or get all the information you need
to display a detailed traceback.
There are four main kinds of services provided by this module: type checking,
getting source code, inspecting classes and functions, and examining the
interpreter stack.
.. _inspect-types:
Types and members
-----------------
The :func:`getmembers` function retrieves the members of an object such as a
class or module. The sixteen functions whose names begin with "is" are mainly
provided as convenient choices for the second argument to :func:`getmembers`.
They also help you determine when you can expect to find the following special
attributes:
+-----------+-----------------+---------------------------+-------+
| Type | Attribute | Description | Notes |
+===========+=================+===========================+=======+
| module | __doc__ | documentation string | |
+-----------+-----------------+---------------------------+-------+
| | __file__ | filename (missing for | |
| | | built-in modules) | |
+-----------+-----------------+---------------------------+-------+
| class | __doc__ | documentation string | |
+-----------+-----------------+---------------------------+-------+
| | __module__ | name of module in which | |
| | | this class was defined | |
+-----------+-----------------+---------------------------+-------+
| method | __doc__ | documentation string | |
+-----------+-----------------+---------------------------+-------+
| | __name__ | name with which this | |
| | | method was defined | |
+-----------+-----------------+---------------------------+-------+
| | im_class | class object that asked | \(1) |
| | | for this method | |
+-----------+-----------------+---------------------------+-------+
| | im_func or | function object | |
| | __func__ | containing implementation | |
| | | of method | |
+-----------+-----------------+---------------------------+-------+
| | im_self or | instance to which this | |
| | __self__ | method is bound, or | |
| | | ``None`` | |
+-----------+-----------------+---------------------------+-------+
| function | __doc__ | documentation string | |
+-----------+-----------------+---------------------------+-------+
| | __name__ | name with which this | |
| | | function was defined | |
+-----------+-----------------+---------------------------+-------+
| | func_code | code object containing | |
| | | compiled function | |
| | | :term:`bytecode` | |
+-----------+-----------------+---------------------------+-------+
| | func_defaults | tuple of any default | |
| | | values for arguments | |
+-----------+-----------------+---------------------------+-------+
| | func_doc | (same as __doc__) | |
+-----------+-----------------+---------------------------+-------+
| | func_globals | global namespace in which | |
| | | this function was defined | |
+-----------+-----------------+---------------------------+-------+
| | func_name | (same as __name__) | |
+-----------+-----------------+---------------------------+-------+
| generator | __iter__ | defined to support | |
| | | iteration over container | |
+-----------+-----------------+---------------------------+-------+
| | close | raises new GeneratorExit | |
| | | exception inside the | |
| | | generator to terminate | |
| | | the iteration | |
+-----------+-----------------+---------------------------+-------+
| | gi_code | code object | |
+-----------+-----------------+---------------------------+-------+
| | gi_frame | frame object or possibly | |
| | | ``None`` once the | |
| | | generator has been | |
| | | exhausted | |
+-----------+-----------------+---------------------------+-------+
| | gi_running | set to 1 when generator | |
| | | is executing, 0 otherwise | |
+-----------+-----------------+---------------------------+-------+
| | next | return the next item from | |
| | | the container | |
+-----------+-----------------+---------------------------+-------+
| | send | resumes the generator and | |
| | | "sends" a value that | |
| | | becomes the result of the | |
| | | current yield-expression | |
+-----------+-----------------+---------------------------+-------+
| | throw | used to raise an | |
| | | exception inside the | |
| | | generator | |
+-----------+-----------------+---------------------------+-------+
| traceback | tb_frame | frame object at this | |
| | | level | |
+-----------+-----------------+---------------------------+-------+
| | tb_lasti | index of last attempted | |
| | | instruction in bytecode | |
+-----------+-----------------+---------------------------+-------+
| | tb_lineno | current line number in | |
| | | Python source code | |
+-----------+-----------------+---------------------------+-------+
| | tb_next | next inner traceback | |
| | | object (called by this | |
| | | level) | |
+-----------+-----------------+---------------------------+-------+
| frame | f_back | next outer frame object | |
| | | (this frame's caller) | |
+-----------+-----------------+---------------------------+-------+
| | f_builtins | builtins namespace seen | |
| | | by this frame | |
+-----------+-----------------+---------------------------+-------+
| | f_code | code object being | |
| | | executed in this frame | |
+-----------+-----------------+---------------------------+-------+
| | f_exc_traceback | traceback if raised in | |
| | | this frame, or ``None`` | |
+-----------+-----------------+---------------------------+-------+
| | f_exc_type | exception type if raised | |
| | | in this frame, or | |
| | | ``None`` | |
+-----------+-----------------+---------------------------+-------+
| | f_exc_value | exception value if raised | |
| | | in this frame, or | |
| | | ``None`` | |
+-----------+-----------------+---------------------------+-------+
| | f_globals | global namespace seen by | |
| | | this frame | |
+-----------+-----------------+---------------------------+-------+
| | f_lasti | index of last attempted | |
| | | instruction in bytecode | |
+-----------+-----------------+---------------------------+-------+
| | f_lineno | current line number in | |
| | | Python source code | |
+-----------+-----------------+---------------------------+-------+
| | f_locals | local namespace seen by | |
| | | this frame | |
+-----------+-----------------+---------------------------+-------+
| | f_restricted | 0 or 1 if frame is in | |
| | | restricted execution mode | |
+-----------+-----------------+---------------------------+-------+
| | f_trace | tracing function for this | |
| | | frame, or ``None`` | |
+-----------+-----------------+---------------------------+-------+
| code | co_argcount | number of arguments (not | |
| | | including \* or \*\* | |
| | | args) | |
+-----------+-----------------+---------------------------+-------+
| | co_code | string of raw compiled | |
| | | bytecode | |
+-----------+-----------------+---------------------------+-------+
| | co_consts | tuple of constants used | |
| | | in the bytecode | |
+-----------+-----------------+---------------------------+-------+
| | co_filename | name of file in which | |
| | | this code object was | |
| | | created | |
+-----------+-----------------+---------------------------+-------+
| | co_firstlineno | number of first line in | |
| | | Python source code | |
+-----------+-----------------+---------------------------+-------+
| | co_flags | bitmap: 1=optimized ``|`` | |
| | | 2=newlocals ``|`` 4=\*arg | |
| | | ``|`` 8=\*\*arg | |
+-----------+-----------------+---------------------------+-------+
| | co_lnotab | encoded mapping of line | |
| | | numbers to bytecode | |
| | | indices | |
+-----------+-----------------+---------------------------+-------+
| | co_name | name with which this code | |
| | | object was defined | |
+-----------+-----------------+---------------------------+-------+
| | co_names | tuple of names of local | |
| | | variables | |
+-----------+-----------------+---------------------------+-------+
| | co_nlocals | number of local variables | |
+-----------+-----------------+---------------------------+-------+
| | co_stacksize | virtual machine stack | |
| | | space required | |
+-----------+-----------------+---------------------------+-------+
| | co_varnames | tuple of names of | |
| | | arguments and local | |
| | | variables | |
+-----------+-----------------+---------------------------+-------+
| builtin | __doc__ | documentation string | |
+-----------+-----------------+---------------------------+-------+
| | __name__ | original name of this | |
| | | function or method | |
+-----------+-----------------+---------------------------+-------+
| | __self__ | instance to which a | |
| | | method is bound, or | |
| | | ``None`` | |
+-----------+-----------------+---------------------------+-------+
Note:
(1)
.. versionchanged:: 2.2
:attr:`im_class` used to refer to the class that defined the method.
.. function:: getmembers(object[, predicate])
Return all the members of an object in a list of (name, value) pairs sorted by
name. If the optional *predicate* argument is supplied, only members for which
the predicate returns a true value are included.
.. note::
:func:`getmembers` does not return metaclass attributes when the argument
is a class (this behavior is inherited from the :func:`dir` function).
.. function:: getmoduleinfo(path)
Return a tuple of values that describe how Python will interpret the file
identified by *path* if it is a module, or ``None`` if it would not be
identified as a module. The return tuple is ``(name, suffix, mode,
module_type)``, where *name* is the name of the module without the name of
any enclosing package, *suffix* is the trailing part of the file name (which
may not be a dot-delimited extension), *mode* is the :func:`open` mode that
would be used (``'r'`` or ``'rb'``), and *module_type* is an integer giving
the type of the module. *module_type* will have a value which can be
compared to the constants defined in the :mod:`imp` module; see the
documentation for that module for more information on module types.
.. versionchanged:: 2.6
Returns a :term:`named tuple` ``ModuleInfo(name, suffix, mode,
module_type)``.
.. function:: getmodulename(path)
Return the name of the module named by the file *path*, without including the
names of enclosing packages. This uses the same algorithm as the interpreter
uses when searching for modules. If the name cannot be matched according to the
interpreter's rules, ``None`` is returned.
.. function:: ismodule(object)
Return true if the object is a module.
.. function:: isclass(object)
Return true if the object is a class, whether built-in or created in Python
code.
.. function:: ismethod(object)
Return true if the object is a bound or unbound method written in Python.
.. function:: isfunction(object)
Return true if the object is a Python function, which includes functions
created by a :term:`lambda` expression.
.. function:: isgeneratorfunction(object)
Return true if the object is a Python generator function.
.. versionadded:: 2.6
.. function:: isgenerator(object)
Return true if the object is a generator.
.. versionadded:: 2.6
.. function:: istraceback(object)
Return true if the object is a traceback.
.. function:: isframe(object)
Return true if the object is a frame.
.. function:: iscode(object)
Return true if the object is a code.
.. function:: isbuiltin(object)
Return true if the object is a built-in function or a bound built-in method.
.. function:: isroutine(object)
Return true if the object is a user-defined or built-in function or method.
.. function:: isabstract(object)
Return true if the object is an abstract base class.
.. versionadded:: 2.6
.. function:: ismethoddescriptor(object)
Return true if the object is a method descriptor, but not if
:func:`ismethod`, :func:`isclass`, :func:`isfunction` or :func:`isbuiltin`
are true.
This is new as of Python 2.2, and, for example, is true of
``int.__add__``. An object passing this test
has a :meth:`~object.__get__` method but not a :meth:`~object.__set__`
method, but beyond that the set of attributes varies. A
:attr:`~definition.__name__` attribute is usually
sensible, and :attr:`__doc__` often is.
Methods implemented via descriptors that also pass one of the other tests
return false from the :func:`ismethoddescriptor` test, simply because the
other tests promise more -- you can, e.g., count on having the
:attr:`im_func` attribute (etc) when an object passes :func:`ismethod`.
.. function:: isdatadescriptor(object)
Return true if the object is a data descriptor.
Data descriptors have both a :attr:`~object.__get__` and a :attr:`~object.__set__` method.
Examples are properties (defined in Python), getsets, and members. The
latter two are defined in C and there are more specific tests available for
those types, which is robust across Python implementations. Typically, data
descriptors will also have :attr:`~definition.__name__` and :attr:`__doc__` attributes
(properties, getsets, and members have both of these attributes), but this is
not guaranteed.
.. versionadded:: 2.3
.. function:: isgetsetdescriptor(object)
Return true if the object is a getset descriptor.
.. impl-detail::
getsets are attributes defined in extension modules via
:c:type:`PyGetSetDef` structures. For Python implementations without such
types, this method will always return ``False``.
.. versionadded:: 2.5
.. function:: ismemberdescriptor(object)
Return true if the object is a member descriptor.
.. impl-detail::
Member descriptors are attributes defined in extension modules via
:c:type:`PyMemberDef` structures. For Python implementations without such
types, this method will always return ``False``.
.. versionadded:: 2.5
.. _inspect-source:
Retrieving source code
----------------------
.. function:: getdoc(object)
Get the documentation string for an object, cleaned up with :func:`cleandoc`.
.. function:: getcomments(object)
Return in a single string any lines of comments immediately preceding the
object's source code (for a class, function, or method), or at the top of the
Python source file (if the object is a module).
.. function:: getfile(object)
Return the name of the (text or binary) file in which an object was defined.
This will fail with a :exc:`TypeError` if the object is a built-in module,
class, or function.
.. function:: getmodule(object)
Try to guess which module an object was defined in.
.. function:: getsourcefile(object)
Return the name of the Python source file in which an object was defined. This
will fail with a :exc:`TypeError` if the object is a built-in module, class, or
function.
.. function:: getsourcelines(object)
Return a list of source lines and starting line number for an object. The
argument may be a module, class, method, function, traceback, frame, or code
object. The source code is returned as a list of the lines corresponding to the
object and the line number indicates where in the original source file the first
line of code was found. An :exc:`IOError` is raised if the source code cannot
be retrieved.
.. function:: getsource(object)
Return the text of the source code for an object. The argument may be a module,
class, method, function, traceback, frame, or code object. The source code is
returned as a single string. An :exc:`IOError` is raised if the source code
cannot be retrieved.
.. function:: cleandoc(doc)
Clean up indentation from docstrings that are indented to line up with blocks
of code.
All leading whitespace is removed from the first line. Any leading whitespace
that can be uniformly removed from the second line onwards is removed. Empty
lines at the beginning and end are subsequently removed. Also, all tabs are
expanded to spaces.
.. versionadded:: 2.6
.. _inspect-classes-functions:
Classes and functions
---------------------
.. function:: getclasstree(classes[, unique])
Arrange the given list of classes into a hierarchy of nested lists. Where a
nested list appears, it contains classes derived from the class whose entry
immediately precedes the list. Each entry is a 2-tuple containing a class and a
tuple of its base classes. If the *unique* argument is true, exactly one entry
appears in the returned structure for each class in the given list. Otherwise,
classes using multiple inheritance and their descendants will appear multiple
times.
.. function:: getargspec(func)
Get the names and default values of a Python function's arguments. A tuple of
four things is returned: ``(args, varargs, keywords, defaults)``. *args* is a
list of the argument names (it may contain nested lists). *varargs* and
*keywords* are the names of the ``*`` and ``**`` arguments or
``None``. *defaults* is a tuple of default argument values or ``None`` if there
are no default arguments; if this tuple has *n* elements, they correspond to
the last *n* elements listed in *args*.
.. versionchanged:: 2.6
Returns a :term:`named tuple` ``ArgSpec(args, varargs, keywords,
defaults)``.
.. function:: getargvalues(frame)
Get information about arguments passed into a particular frame. A tuple of
four things is returned: ``(args, varargs, keywords, locals)``. *args* is a
list of the argument names (it may contain nested lists). *varargs* and
*keywords* are the names of the ``*`` and ``**`` arguments or ``None``.
*locals* is the locals dictionary of the given frame.
.. versionchanged:: 2.6
Returns a :term:`named tuple` ``ArgInfo(args, varargs, keywords,
locals)``.
.. function:: formatargspec(args[, varargs, varkw, defaults, formatarg, formatvarargs, formatvarkw, formatvalue, join])
Format a pretty argument spec from the four values returned by
:func:`getargspec`. The format\* arguments are the corresponding optional
formatting functions that are called to turn names and values into strings.
.. function:: formatargvalues(args[, varargs, varkw, locals, formatarg, formatvarargs, formatvarkw, formatvalue, join])
Format a pretty argument spec from the four values returned by
:func:`getargvalues`. The format\* arguments are the corresponding optional
formatting functions that are called to turn names and values into strings.
.. function:: getmro(cls)
Return a tuple of class cls's base classes, including cls, in method resolution
order. No class appears more than once in this tuple. Note that the method
resolution order depends on cls's type. Unless a very peculiar user-defined
metatype is in use, cls will be the first element of the tuple.
.. function:: getcallargs(func[, *args][, **kwds])
Bind the *args* and *kwds* to the argument names of the Python function or
method *func*, as if it was called with them. For bound methods, bind also the
first argument (typically named ``self``) to the associated instance. A dict
is returned, mapping the argument names (including the names of the ``*`` and
``**`` arguments, if any) to their values from *args* and *kwds*. In case of
invoking *func* incorrectly, i.e. whenever ``func(*args, **kwds)`` would raise
an exception because of incompatible signature, an exception of the same type
and the same or similar message is raised. For example::
>>> from inspect import getcallargs
>>> def f(a, b=1, *pos, **named):
... pass
>>> getcallargs(f, 1, 2, 3)
{'a': 1, 'named': {}, 'b': 2, 'pos': (3,)}
>>> getcallargs(f, a=2, x=4)
{'a': 2, 'named': {'x': 4}, 'b': 1, 'pos': ()}
>>> getcallargs(f)
Traceback (most recent call last):
...
TypeError: f() takes at least 1 argument (0 given)
.. versionadded:: 2.7
.. _inspect-stack:
The interpreter stack
---------------------
When the following functions return "frame records," each record is a tuple of
six items: the frame object, the filename, the line number of the current line,
the function name, a list of lines of context from the source code, and the
index of the current line within that list.
.. note::
Keeping references to frame objects, as found in the first element of the frame
records these functions return, can cause your program to create reference
cycles. Once a reference cycle has been created, the lifespan of all objects
which can be accessed from the objects which form the cycle can become much
longer even if Python's optional cycle detector is enabled. If such cycles must
be created, it is important to ensure they are explicitly broken to avoid the
delayed destruction of objects and increased memory consumption which occurs.
Though the cycle detector will catch these, destruction of the frames (and local
variables) can be made deterministic by removing the cycle in a
:keyword:`finally` clause. This is also important if the cycle detector was
disabled when Python was compiled or using :func:`gc.disable`. For example::
def handle_stackframe_without_leak():
frame = inspect.currentframe()
try:
# do something with the frame
finally:
del frame
The optional *context* argument supported by most of these functions specifies
the number of lines of context to return, which are centered around the current
line.
.. function:: getframeinfo(frame[, context])
Get information about a frame or traceback object. A 5-tuple is returned, the
last five elements of the frame's frame record.
.. versionchanged:: 2.6
Returns a :term:`named tuple` ``Traceback(filename, lineno, function,
code_context, index)``.
.. function:: getouterframes(frame[, context])
Get a list of frame records for a frame and all outer frames. These frames
represent the calls that lead to the creation of *frame*. The first entry in the
returned list represents *frame*; the last entry represents the outermost call
on *frame*'s stack.
.. function:: getinnerframes(traceback[, context])
Get a list of frame records for a traceback's frame and all inner frames. These
frames represent calls made as a consequence of *frame*. The first entry in the
list represents *traceback*; the last entry represents where the exception was
raised.
.. function:: currentframe()
Return the frame object for the caller's stack frame.
.. impl-detail::
This function relies on Python stack frame support in the interpreter,
which isn't guaranteed to exist in all implementations of Python. If
running in an implementation without Python stack frame support this
function returns ``None``.
.. function:: stack([context])
Return a list of frame records for the caller's stack. The first entry in the
returned list represents the caller; the last entry represents the outermost
call on the stack.
.. function:: trace([context])
Return a list of frame records for the stack between the current frame and the
frame in which an exception currently being handled was raised in. The first
entry in the list represents the caller; the last entry represents where the
exception was raised.
PK %�\o!��� � & html/_sources/library/internet.rst.txtnu �[���
.. _internet:
******************************
Internet Protocols and Support
******************************
.. index::
single: WWW
single: Internet
single: World Wide Web
.. index:: module: socket
The modules described in this chapter implement Internet protocols and support
for related technology. They are all implemented in Python. Most of these
modules require the presence of the system-dependent module :mod:`socket`, which
is currently supported on most popular platforms. Here is an overview:
.. toctree::
webbrowser.rst
cgi.rst
cgitb.rst
wsgiref.rst
urllib.rst
urllib2.rst
httplib.rst
ftplib.rst
poplib.rst
imaplib.rst
nntplib.rst
smtplib.rst
smtpd.rst
telnetlib.rst
uuid.rst
urlparse.rst
socketserver.rst
basehttpserver.rst
simplehttpserver.rst
cgihttpserver.rst
cookielib.rst
cookie.rst
xmlrpclib.rst
simplexmlrpcserver.rst
docxmlrpcserver.rst
PK %�\ V��
�
# html/_sources/library/intro.rst.txtnu �[���
.. _library-intro:
************
Introduction
************
The "Python library" contains several different kinds of components.
It contains data types that would normally be considered part of the "core" of a
language, such as numbers and lists. For these types, the Python language core
defines the form of literals and places some constraints on their semantics, but
does not fully define the semantics. (On the other hand, the language core does
define syntactic properties like the spelling and priorities of operators.)
The library also contains built-in functions and exceptions --- objects that can
be used by all Python code without the need of an :keyword:`import` statement.
Some of these are defined by the core language, but many are not essential for
the core semantics and are only described here.
The bulk of the library, however, consists of a collection of modules. There are
many ways to dissect this collection. Some modules are written in C and built
in to the Python interpreter; others are written in Python and imported in
source form. Some modules provide interfaces that are highly specific to
Python, like printing a stack trace; some provide interfaces that are specific
to particular operating systems, such as access to specific hardware; others
provide interfaces that are specific to a particular application domain, like
the World Wide Web. Some modules are available in all versions and ports of
Python; others are only available when the underlying system supports or
requires them; yet others are available only when a particular configuration
option was chosen at the time when Python was compiled and installed.
This manual is organized "from the inside out:" it first describes the built-in
data types, then the built-in functions and exceptions, and finally the modules,
grouped in chapters of related modules. The ordering of the chapters as well as
the ordering of the modules within each chapter is roughly from most relevant to
least important.
This means that if you start reading this manual from the start, and skip to the
next chapter when you get bored, you will get a reasonable overview of the
available modules and application areas that are supported by the Python
library. Of course, you don't *have* to read it like a novel --- you can also
browse the table of contents (in front of the manual), or look for a specific
function, module or term in the index (in the back). And finally, if you enjoy
learning about random subjects, you choose a random page number (see module
:mod:`random`) and read a section or two. Regardless of the order in which you
read the sections of this manual, it helps to start with chapter
:ref:`built-in-funcs`, as the remainder of the manual assumes familiarity with
this material.
Let the show begin!
PK %�\� ��g� g� html/_sources/library/io.rst.txtnu �[��� :mod:`io` --- Core tools for working with streams
=================================================
.. module:: io
:synopsis: Core tools for working with streams.
.. moduleauthor:: Guido van Rossum <guido@python.org>
.. moduleauthor:: Mike Verdone <mike.verdone@gmail.com>
.. moduleauthor:: Mark Russell <mark.russell@zen.co.uk>
.. moduleauthor:: Antoine Pitrou <solipsis@pitrou.net>
.. moduleauthor:: Amaury Forgeot d'Arc <amauryfa@gmail.com>
.. moduleauthor:: Benjamin Peterson <benjamin@python.org>
.. sectionauthor:: Benjamin Peterson <benjamin@python.org>
.. versionadded:: 2.6
The :mod:`io` module provides the Python interfaces to stream handling.
Under Python 2.x, this is proposed as an alternative to the built-in
:class:`file` object, but in Python 3.x it is the default interface to
access files and streams.
.. note::
Since this module has been designed primarily for Python 3.x, you have to
be aware that all uses of "bytes" in this document refer to the
:class:`str` type (of which :class:`bytes` is an alias), and all uses
of "text" refer to the :class:`unicode` type. Furthermore, those two
types are not interchangeable in the :mod:`io` APIs.
At the top of the I/O hierarchy is the abstract base class :class:`IOBase`. It
defines the basic interface to a stream. Note, however, that there is no
separation between reading and writing to streams; implementations are allowed
to raise an :exc:`IOError` if they do not support a given operation.
Extending :class:`IOBase` is :class:`RawIOBase` which deals simply with the
reading and writing of raw bytes to a stream. :class:`FileIO` subclasses
:class:`RawIOBase` to provide an interface to files in the machine's
file system.
:class:`BufferedIOBase` deals with buffering on a raw byte stream
(:class:`RawIOBase`). Its subclasses, :class:`BufferedWriter`,
:class:`BufferedReader`, and :class:`BufferedRWPair` buffer streams that are
readable, writable, and both readable and writable.
:class:`BufferedRandom` provides a buffered interface to random access
streams. :class:`BytesIO` is a simple stream of in-memory bytes.
Another :class:`IOBase` subclass, :class:`TextIOBase`, deals with
streams whose bytes represent text, and handles encoding and decoding
from and to :class:`unicode` strings. :class:`TextIOWrapper`, which extends
it, is a buffered text interface to a buffered raw stream
(:class:`BufferedIOBase`). Finally, :class:`~io.StringIO` is an in-memory
stream for unicode text.
Argument names are not part of the specification, and only the arguments of
:func:`.open` are intended to be used as keyword arguments.
Module Interface
----------------
.. data:: DEFAULT_BUFFER_SIZE
An int containing the default buffer size used by the module's buffered I/O
classes. :func:`.open` uses the file's blksize (as obtained by
:func:`os.stat`) if possible.
.. function:: open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True)
Open *file* and return a corresponding stream. If the file cannot be opened,
an :exc:`IOError` is raised.
*file* is either a string giving the pathname (absolute or
relative to the current working directory) of the file to be opened or
an integer file descriptor of the file to be wrapped. (If a file descriptor
is given, it is closed when the returned I/O object is closed, unless
*closefd* is set to ``False``.)
*mode* is an optional string that specifies the mode in which the file is
opened. It defaults to ``'r'`` which means open for reading in text mode.
Other common values are ``'w'`` for writing (truncating the file if it
already exists), and ``'a'`` for appending (which on *some* Unix systems,
means that *all* writes append to the end of the file regardless of the
current seek position). In text mode, if *encoding* is not specified the
encoding used is platform dependent. (For reading and writing raw bytes use
binary mode and leave *encoding* unspecified.) The available modes are:
========= ===============================================================
Character Meaning
--------- ---------------------------------------------------------------
``'r'`` open for reading (default)
``'w'`` open for writing, truncating the file first
``'a'`` open for writing, appending to the end of the file if it exists
``'b'`` binary mode
``'t'`` text mode (default)
``'+'`` open a disk file for updating (reading and writing)
``'U'`` universal newlines mode (for backwards compatibility; should
not be used in new code)
========= ===============================================================
The default mode is ``'rt'`` (open for reading text). For binary random
access, the mode ``'w+b'`` opens and truncates the file to 0 bytes, while
``'r+b'`` opens the file without truncation.
Python distinguishes between files opened in binary and text modes, even when
the underlying operating system doesn't. Files opened in binary mode
(including ``'b'`` in the *mode* argument) return contents as :class:`bytes`
objects without any decoding. In text mode (the default, or when ``'t'`` is
included in the *mode* argument), the contents of the file are returned as
:class:`unicode` strings, the bytes having been first decoded using a
platform-dependent encoding or using the specified *encoding* if given.
*buffering* is an optional integer used to set the buffering policy.
Pass 0 to switch buffering off (only allowed in binary mode), 1 to select
line buffering (only usable in text mode), and an integer > 1 to indicate
the size of a fixed-size chunk buffer. When no *buffering* argument is
given, the default buffering policy works as follows:
* Binary files are buffered in fixed-size chunks; the size of the buffer
is chosen using a heuristic trying to determine the underlying device's
"block size" and falling back on :attr:`DEFAULT_BUFFER_SIZE`.
On many systems, the buffer will typically be 4096 or 8192 bytes long.
* "Interactive" text files (files for which :meth:`isatty` returns True)
use line buffering. Other text files use the policy described above
for binary files.
*encoding* is the name of the encoding used to decode or encode the file.
This should only be used in text mode. The default encoding is platform
dependent (whatever :func:`locale.getpreferredencoding` returns), but any
encoding supported by Python can be used. See the :mod:`codecs` module for
the list of supported encodings.
*errors* is an optional string that specifies how encoding and decoding
errors are to be handled—this cannot be used in binary mode. Pass
``'strict'`` to raise a :exc:`ValueError` exception if there is an encoding
error (the default of ``None`` has the same effect), or pass ``'ignore'`` to
ignore errors. (Note that ignoring encoding errors can lead to data loss.)
``'replace'`` causes a replacement marker (such as ``'?'``) to be inserted
where there is malformed data. When writing, ``'xmlcharrefreplace'``
(replace with the appropriate XML character reference) or
``'backslashreplace'`` (replace with backslashed escape sequences) can be
used. Any other error handling name that has been registered with
:func:`codecs.register_error` is also valid.
.. index::
single: universal newlines; open() (in module io)
*newline* controls how :term:`universal newlines` works (it only applies to
text mode). It can be ``None``, ``''``, ``'\n'``, ``'\r'``, and ``'\r\n'``.
It works as follows:
* On input, if *newline* is ``None``, universal newlines mode is enabled.
Lines in the input can end in ``'\n'``, ``'\r'``, or ``'\r\n'``, and these
are translated into ``'\n'`` before being returned to the caller. If it is
``''``, universal newlines mode is enabled, but line endings are returned to
the caller untranslated. If it has any of the other legal values, input
lines are only terminated by the given string, and the line ending is
returned to the caller untranslated.
* On output, if *newline* is ``None``, any ``'\n'`` characters written are
translated to the system default line separator, :data:`os.linesep`. If
*newline* is ``''``, no translation takes place. If *newline* is any of
the other legal values, any ``'\n'`` characters written are translated to
the given string.
If *closefd* is ``False`` and a file descriptor rather than a filename was
given, the underlying file descriptor will be kept open when the file is
closed. If a filename is given *closefd* has no effect and must be ``True``
(the default).
The type of file object returned by the :func:`.open` function depends on the
mode. When :func:`.open` is used to open a file in a text mode (``'w'``,
``'r'``, ``'wt'``, ``'rt'``, etc.), it returns a subclass of
:class:`TextIOBase` (specifically :class:`TextIOWrapper`). When used to open
a file in a binary mode with buffering, the returned class is a subclass of
:class:`BufferedIOBase`. The exact class varies: in read binary mode, it
returns a :class:`BufferedReader`; in write binary and append binary modes,
it returns a :class:`BufferedWriter`, and in read/write mode, it returns a
:class:`BufferedRandom`. When buffering is disabled, the raw stream, a
subclass of :class:`RawIOBase`, :class:`FileIO`, is returned.
It is also possible to use an :class:`unicode` or :class:`bytes` string
as a file for both reading and writing. For :class:`unicode` strings
:class:`~io.StringIO` can be used like a file opened in text mode,
and for :class:`bytes` a :class:`BytesIO` can be used like a
file opened in a binary mode.
.. exception:: BlockingIOError
Error raised when blocking would occur on a non-blocking stream. It inherits
:exc:`IOError`.
In addition to those of :exc:`IOError`, :exc:`BlockingIOError` has one
attribute:
.. attribute:: characters_written
An integer containing the number of characters written to the stream
before it blocked.
.. exception:: UnsupportedOperation
An exception inheriting :exc:`IOError` and :exc:`ValueError` that is raised
when an unsupported operation is called on a stream.
I/O Base Classes
----------------
.. class:: IOBase
The abstract base class for all I/O classes, acting on streams of bytes.
There is no public constructor.
This class provides empty abstract implementations for many methods
that derived classes can override selectively; the default
implementations represent a file that cannot be read, written or
seeked.
Even though :class:`IOBase` does not declare :meth:`read`, :meth:`readinto`,
or :meth:`write` because their signatures will vary, implementations and
clients should consider those methods part of the interface. Also,
implementations may raise an :exc:`IOError` when operations they do not
support are called.
The basic type used for binary data read from or written to a file is
:class:`bytes` (also known as :class:`str`). Method arguments may
also be :class:`bytearray` or :class:`memoryview` of arrays of bytes.
In some cases, such as :meth:`~RawIOBase.readinto`, a writable object
such as :class:`bytearray` is required.
Text I/O classes work with :class:`unicode` data.
.. versionchanged:: 2.7
Implementations should support :class:`memoryview` arguments.
Note that calling any method (even inquiries) on a closed stream is
undefined. Implementations may raise :exc:`IOError` in this case.
IOBase (and its subclasses) support the iterator protocol, meaning that an
:class:`IOBase` object can be iterated over yielding the lines in a stream.
Lines are defined slightly differently depending on whether the stream is
a binary stream (yielding :class:`bytes`), or a text stream (yielding
:class:`unicode` strings). See :meth:`~IOBase.readline` below.
IOBase is also a context manager and therefore supports the
:keyword:`with` statement. In this example, *file* is closed after the
:keyword:`with` statement's suite is finished---even if an exception occurs::
with io.open('spam.txt', 'w') as file:
file.write(u'Spam and eggs!')
:class:`IOBase` provides these data attributes and methods:
.. method:: close()
Flush and close this stream. This method has no effect if the file is
already closed. Once the file is closed, any operation on the file
(e.g. reading or writing) will raise a :exc:`ValueError`.
As a convenience, it is allowed to call this method more than once;
only the first call, however, will have an effect.
.. attribute:: closed
True if the stream is closed.
.. method:: fileno()
Return the underlying file descriptor (an integer) of the stream if it
exists. An :exc:`IOError` is raised if the IO object does not use a file
descriptor.
.. method:: flush()
Flush the write buffers of the stream if applicable. This does nothing
for read-only and non-blocking streams.
.. method:: isatty()
Return ``True`` if the stream is interactive (i.e., connected to
a terminal/tty device).
.. method:: readable()
Return ``True`` if the stream can be read from. If ``False``, :meth:`read`
will raise :exc:`IOError`.
.. method:: readline(limit=-1)
Read and return one line from the stream. If *limit* is specified, at
most *limit* bytes will be read.
The line terminator is always ``b'\n'`` for binary files; for text files,
the *newline* argument to :func:`.open` can be used to select the line
terminator(s) recognized.
.. method:: readlines(hint=-1)
Read and return a list of lines from the stream. *hint* can be specified
to control the number of lines read: no more lines will be read if the
total size (in bytes/characters) of all lines so far exceeds *hint*.
Note that it's already possible to iterate on file objects using ``for
line in file: ...`` without calling ``file.readlines()``.
.. method:: seek(offset[, whence])
Change the stream position to the given byte *offset*. *offset* is
interpreted relative to the position indicated by *whence*. The default
value for *whence* is :data:`SEEK_SET`. Values for *whence* are:
* :data:`SEEK_SET` or ``0`` -- start of the stream (the default);
*offset* should be zero or positive
* :data:`SEEK_CUR` or ``1`` -- current stream position; *offset* may
be negative
* :data:`SEEK_END` or ``2`` -- end of the stream; *offset* is usually
negative
Return the new absolute position.
.. versionadded:: 2.7
The ``SEEK_*`` constants
.. method:: seekable()
Return ``True`` if the stream supports random access. If ``False``,
:meth:`seek`, :meth:`tell` and :meth:`truncate` will raise :exc:`IOError`.
.. method:: tell()
Return the current stream position.
.. method:: truncate(size=None)
Resize the stream to the given *size* in bytes (or the current position
if *size* is not specified). The current stream position isn't changed.
This resizing can extend or reduce the current file size. In case of
extension, the contents of the new file area depend on the platform
(on most systems, additional bytes are zero-filled, on Windows they're
undetermined). The new file size is returned.
.. method:: writable()
Return ``True`` if the stream supports writing. If ``False``,
:meth:`write` and :meth:`truncate` will raise :exc:`IOError`.
.. method:: writelines(lines)
Write a list of lines to the stream. Line separators are not added, so it
is usual for each of the lines provided to have a line separator at the
end.
.. method:: __del__()
Prepare for object destruction. :class:`IOBase` provides a default
implementation of this method that calls the instance's
:meth:`~IOBase.close` method.
.. class:: RawIOBase
Base class for raw binary I/O. It inherits :class:`IOBase`. There is no
public constructor.
Raw binary I/O typically provides low-level access to an underlying OS
device or API, and does not try to encapsulate it in high-level primitives
(this is left to Buffered I/O and Text I/O, described later in this page).
In addition to the attributes and methods from :class:`IOBase`,
RawIOBase provides the following methods:
.. method:: read(n=-1)
Read up to *n* bytes from the object and return them. As a convenience,
if *n* is unspecified or -1, :meth:`readall` is called. Otherwise,
only one system call is ever made. Fewer than *n* bytes may be
returned if the operating system call returns fewer than *n* bytes.
If 0 bytes are returned, and *n* was not 0, this indicates end of file.
If the object is in non-blocking mode and no bytes are available,
``None`` is returned.
.. method:: readall()
Read and return all the bytes from the stream until EOF, using multiple
calls to the stream if necessary.
.. method:: readinto(b)
Read up to len(b) bytes into *b*, and return the number
of bytes read. The object *b* should be a pre-allocated, writable
array of bytes, either :class:`bytearray` or :class:`memoryview`.
If the object is in non-blocking mode and no
bytes are available, ``None`` is returned.
.. method:: write(b)
Write *b* to the underlying raw stream, and return the
number of bytes written. The object *b* should be an array
of bytes, either :class:`bytes`, :class:`bytearray`, or
:class:`memoryview`. The return value can be less than
``len(b)``, depending on specifics of the underlying raw stream, and
especially if it is in non-blocking mode. ``None`` is returned if the
raw stream is set not to block and no single byte could be readily
written to it. The caller may release or mutate *b* after
this method returns, so the implementation should only access *b*
during the method call.
.. class:: BufferedIOBase
Base class for binary streams that support some kind of buffering.
It inherits :class:`IOBase`. There is no public constructor.
The main difference with :class:`RawIOBase` is that methods :meth:`read`,
:meth:`readinto` and :meth:`write` will try (respectively) to read as much
input as requested or to consume all given output, at the expense of
making perhaps more than one system call.
In addition, those methods can raise :exc:`BlockingIOError` if the
underlying raw stream is in non-blocking mode and cannot take or give
enough data; unlike their :class:`RawIOBase` counterparts, they will
never return ``None``.
Besides, the :meth:`read` method does not have a default
implementation that defers to :meth:`readinto`.
A typical :class:`BufferedIOBase` implementation should not inherit from a
:class:`RawIOBase` implementation, but wrap one, like
:class:`BufferedWriter` and :class:`BufferedReader` do.
:class:`BufferedIOBase` provides or overrides these methods and attribute in
addition to those from :class:`IOBase`:
.. attribute:: raw
The underlying raw stream (a :class:`RawIOBase` instance) that
:class:`BufferedIOBase` deals with. This is not part of the
:class:`BufferedIOBase` API and may not exist on some implementations.
.. method:: detach()
Separate the underlying raw stream from the buffer and return it.
After the raw stream has been detached, the buffer is in an unusable
state.
Some buffers, like :class:`BytesIO`, do not have the concept of a single
raw stream to return from this method. They raise
:exc:`UnsupportedOperation`.
.. versionadded:: 2.7
.. method:: read(n=-1)
Read and return up to *n* bytes. If the argument is omitted, ``None``, or
negative, data is read and returned until EOF is reached. An empty bytes
object is returned if the stream is already at EOF.
If the argument is positive, and the underlying raw stream is not
interactive, multiple raw reads may be issued to satisfy the byte count
(unless EOF is reached first). But for interactive raw streams, at most
one raw read will be issued, and a short result does not imply that EOF is
imminent.
A :exc:`BlockingIOError` is raised if the underlying raw stream is in
non blocking-mode, and has no data available at the moment.
.. method:: read1(n=-1)
Read and return up to *n* bytes, with at most one call to the underlying
raw stream's :meth:`~RawIOBase.read` method. This can be useful if you
are implementing your own buffering on top of a :class:`BufferedIOBase`
object.
.. method:: readinto(b)
Read up to len(b) bytes into *b*, and return the number of bytes read.
The object *b* should be a pre-allocated, writable array of bytes,
either :class:`bytearray` or :class:`memoryview`.
Like :meth:`read`, multiple reads may be issued to the underlying raw
stream, unless the latter is 'interactive'.
A :exc:`BlockingIOError` is raised if the underlying raw stream is in
non blocking-mode, and has no data available at the moment.
.. method:: write(b)
Write *b*, and return the number of bytes written
(always equal to ``len(b)``, since if the write fails
an :exc:`IOError` will be raised). The object *b* should be
an array of bytes, either :class:`bytes`, :class:`bytearray`,
or :class:`memoryview`. Depending on the actual
implementation, these bytes may be readily written to the underlying
stream, or held in a buffer for performance and latency reasons.
When in non-blocking mode, a :exc:`BlockingIOError` is raised if the
data needed to be written to the raw stream but it couldn't accept
all the data without blocking.
The caller may release or mutate *b* after this method returns,
so the implementation should only access *b* during the method call.
Raw File I/O
------------
.. class:: FileIO(name, mode='r', closefd=True)
:class:`FileIO` represents an OS-level file containing bytes data.
It implements the :class:`RawIOBase` interface (and therefore the
:class:`IOBase` interface, too).
The *name* can be one of two things:
* a string representing the path to the file which will be opened;
* an integer representing the number of an existing OS-level file descriptor
to which the resulting :class:`FileIO` object will give access.
The *mode* can be ``'r'``, ``'w'`` or ``'a'`` for reading (default), writing,
or appending. The file will be created if it doesn't exist when opened for
writing or appending; it will be truncated when opened for writing. Add a
``'+'`` to the mode to allow simultaneous reading and writing.
The :meth:`read` (when called with a positive argument), :meth:`readinto`
and :meth:`write` methods on this class will only make one system call.
In addition to the attributes and methods from :class:`IOBase` and
:class:`RawIOBase`, :class:`FileIO` provides the following data
attributes and methods:
.. attribute:: mode
The mode as given in the constructor.
.. attribute:: name
The file name. This is the file descriptor of the file when no name is
given in the constructor.
Buffered Streams
----------------
Buffered I/O streams provide a higher-level interface to an I/O device
than raw I/O does.
.. class:: BytesIO([initial_bytes])
A stream implementation using an in-memory bytes buffer. It inherits
:class:`BufferedIOBase`.
The optional argument *initial_bytes* is a :class:`bytes` object that
contains initial data.
:class:`BytesIO` provides or overrides these methods in addition to those
from :class:`BufferedIOBase` and :class:`IOBase`:
.. method:: getvalue()
Return ``bytes`` containing the entire contents of the buffer.
.. method:: read1()
In :class:`BytesIO`, this is the same as :meth:`read`.
.. class:: BufferedReader(raw, buffer_size=DEFAULT_BUFFER_SIZE)
A buffer providing higher-level access to a readable, sequential
:class:`RawIOBase` object. It inherits :class:`BufferedIOBase`.
When reading data from this object, a larger amount of data may be
requested from the underlying raw stream, and kept in an internal buffer.
The buffered data can then be returned directly on subsequent reads.
The constructor creates a :class:`BufferedReader` for the given readable
*raw* stream and *buffer_size*. If *buffer_size* is omitted,
:data:`DEFAULT_BUFFER_SIZE` is used.
:class:`BufferedReader` provides or overrides these methods in addition to
those from :class:`BufferedIOBase` and :class:`IOBase`:
.. method:: peek([n])
Return bytes from the stream without advancing the position. At most one
single read on the raw stream is done to satisfy the call. The number of
bytes returned may be less or more than requested.
.. method:: read([n])
Read and return *n* bytes, or if *n* is not given or negative, until EOF
or if the read call would block in non-blocking mode.
.. method:: read1(n)
Read and return up to *n* bytes with only one call on the raw stream. If
at least one byte is buffered, only buffered bytes are returned.
Otherwise, one raw stream read call is made.
.. class:: BufferedWriter(raw, buffer_size=DEFAULT_BUFFER_SIZE)
A buffer providing higher-level access to a writeable, sequential
:class:`RawIOBase` object. It inherits :class:`BufferedIOBase`.
When writing to this object, data is normally held into an internal
buffer. The buffer will be written out to the underlying :class:`RawIOBase`
object under various conditions, including:
* when the buffer gets too small for all pending data;
* when :meth:`flush()` is called;
* when a :meth:`seek()` is requested (for :class:`BufferedRandom` objects);
* when the :class:`BufferedWriter` object is closed or destroyed.
The constructor creates a :class:`BufferedWriter` for the given writeable
*raw* stream. If the *buffer_size* is not given, it defaults to
:data:`DEFAULT_BUFFER_SIZE`.
A third argument, *max_buffer_size*, is supported, but unused and deprecated.
:class:`BufferedWriter` provides or overrides these methods in addition to
those from :class:`BufferedIOBase` and :class:`IOBase`:
.. method:: flush()
Force bytes held in the buffer into the raw stream. A
:exc:`BlockingIOError` should be raised if the raw stream blocks.
.. method:: write(b)
Write *b*, and return the number of bytes written.
The object *b* should be an array of bytes, either
:class:`bytes`, :class:`bytearray`, or :class:`memoryview`.
When in non-blocking mode, a :exc:`BlockingIOError` is raised
if the buffer needs to be written out but the raw stream blocks.
.. class:: BufferedRandom(raw, buffer_size=DEFAULT_BUFFER_SIZE)
A buffered interface to random access streams. It inherits
:class:`BufferedReader` and :class:`BufferedWriter`, and further supports
:meth:`seek` and :meth:`tell` functionality.
The constructor creates a reader and writer for a seekable raw stream, given
in the first argument. If the *buffer_size* is omitted it defaults to
:data:`DEFAULT_BUFFER_SIZE`.
A third argument, *max_buffer_size*, is supported, but unused and deprecated.
:class:`BufferedRandom` is capable of anything :class:`BufferedReader` or
:class:`BufferedWriter` can do.
.. class:: BufferedRWPair(reader, writer, buffer_size=DEFAULT_BUFFER_SIZE)
A buffered I/O object combining two unidirectional :class:`RawIOBase`
objects -- one readable, the other writeable -- into a single bidirectional
endpoint. It inherits :class:`BufferedIOBase`.
*reader* and *writer* are :class:`RawIOBase` objects that are readable and
writeable respectively. If the *buffer_size* is omitted it defaults to
:data:`DEFAULT_BUFFER_SIZE`.
A fourth argument, *max_buffer_size*, is supported, but unused and
deprecated.
:class:`BufferedRWPair` implements all of :class:`BufferedIOBase`\'s methods
except for :meth:`~BufferedIOBase.detach`, which raises
:exc:`UnsupportedOperation`.
.. warning::
:class:`BufferedRWPair` does not attempt to synchronize accesses to
its underlying raw streams. You should not pass it the same object
as reader and writer; use :class:`BufferedRandom` instead.
Text I/O
--------
.. class:: TextIOBase
Base class for text streams. This class provides a unicode character
and line based interface to stream I/O. There is no :meth:`readinto`
method because Python's :class:`unicode` strings are immutable.
It inherits :class:`IOBase`. There is no public constructor.
:class:`TextIOBase` provides or overrides these data attributes and
methods in addition to those from :class:`IOBase`:
.. attribute:: encoding
The name of the encoding used to decode the stream's bytes into
strings, and to encode strings into bytes.
.. attribute:: errors
The error setting of the decoder or encoder.
.. attribute:: newlines
A string, a tuple of strings, or ``None``, indicating the newlines
translated so far. Depending on the implementation and the initial
constructor flags, this may not be available.
.. attribute:: buffer
The underlying binary buffer (a :class:`BufferedIOBase` instance) that
:class:`TextIOBase` deals with. This is not part of the
:class:`TextIOBase` API and may not exist on some implementations.
.. method:: detach()
Separate the underlying binary buffer from the :class:`TextIOBase` and
return it.
After the underlying buffer has been detached, the :class:`TextIOBase` is
in an unusable state.
Some :class:`TextIOBase` implementations, like :class:`~io.StringIO`, may not
have the concept of an underlying buffer and calling this method will
raise :exc:`UnsupportedOperation`.
.. versionadded:: 2.7
.. method:: read(n=-1)
Read and return at most *n* characters from the stream as a single
:class:`unicode`. If *n* is negative or ``None``, reads until EOF.
.. method:: readline(limit=-1)
Read until newline or EOF and return a single ``unicode``. If the
stream is already at EOF, an empty string is returned.
If *limit* is specified, at most *limit* characters will be read.
.. method:: seek(offset[, whence])
Change the stream position to the given *offset*. Behaviour depends on
the *whence* parameter. The default value for *whence* is
:data:`SEEK_SET`.
* :data:`SEEK_SET` or ``0``: seek from the start of the stream
(the default); *offset* must either be a number returned by
:meth:`TextIOBase.tell`, or zero. Any other *offset* value
produces undefined behaviour.
* :data:`SEEK_CUR` or ``1``: "seek" to the current position;
*offset* must be zero, which is a no-operation (all other values
are unsupported).
* :data:`SEEK_END` or ``2``: seek to the end of the stream;
*offset* must be zero (all other values are unsupported).
Return the new absolute position as an opaque number.
.. versionadded:: 2.7
The ``SEEK_*`` constants.
.. method:: tell()
Return the current stream position as an opaque number. The number
does not usually represent a number of bytes in the underlying
binary storage.
.. method:: write(s)
Write the :class:`unicode` string *s* to the stream and return the
number of characters written.
.. class:: TextIOWrapper(buffer, encoding=None, errors=None, newline=None, line_buffering=False)
A buffered text stream over a :class:`BufferedIOBase` binary stream.
It inherits :class:`TextIOBase`.
*encoding* gives the name of the encoding that the stream will be decoded or
encoded with. It defaults to :func:`locale.getpreferredencoding`.
*errors* is an optional string that specifies how encoding and decoding
errors are to be handled. Pass ``'strict'`` to raise a :exc:`ValueError`
exception if there is an encoding error (the default of ``None`` has the same
effect), or pass ``'ignore'`` to ignore errors. (Note that ignoring encoding
errors can lead to data loss.) ``'replace'`` causes a replacement marker
(such as ``'?'``) to be inserted where there is malformed data. When
writing, ``'xmlcharrefreplace'`` (replace with the appropriate XML character
reference) or ``'backslashreplace'`` (replace with backslashed escape
sequences) can be used. Any other error handling name that has been
registered with :func:`codecs.register_error` is also valid.
.. index::
single: universal newlines; io.TextIOWrapper class
*newline* controls how line endings are handled. It can be ``None``,
``''``, ``'\n'``, ``'\r'``, and ``'\r\n'``. It works as follows:
* On input, if *newline* is ``None``, :term:`universal newlines` mode is
enabled. Lines in the input can end in ``'\n'``, ``'\r'``, or ``'\r\n'``,
and these are translated into ``'\n'`` before being returned to the
caller. If it is ``''``, universal newlines mode is enabled, but line
endings are returned to the caller untranslated. If it has any of the
other legal values, input lines are only terminated by the given string,
and the line ending is returned to the caller untranslated.
* On output, if *newline* is ``None``, any ``'\n'`` characters written are
translated to the system default line separator, :data:`os.linesep`. If
*newline* is ``''``, no translation takes place. If *newline* is any of
the other legal values, any ``'\n'`` characters written are translated to
the given string.
If *line_buffering* is ``True``, :meth:`flush` is implied when a call to
write contains a newline character or a carriage return.
:class:`TextIOWrapper` provides one attribute in addition to those of
:class:`TextIOBase` and its parents:
.. attribute:: line_buffering
Whether line buffering is enabled.
.. class:: StringIO(initial_value=u'', newline=u'\\n')
An in-memory stream for unicode text. It inherits :class:`TextIOWrapper`.
The initial value of the buffer can be set by providing *initial_value*.
If newline translation is enabled, newlines will be encoded as if by
:meth:`~TextIOBase.write`. The stream is positioned at the start of
the buffer.
The *newline* argument works like that of :class:`TextIOWrapper`.
The default is to consider only ``\n`` characters as ends of lines and
to do no newline translation. If *newline* is set to ``None``,
newlines are written as ``\n`` on all platforms, but universal
newline decoding is still performed when reading.
:class:`~io.StringIO` provides this method in addition to those from
:class:`TextIOWrapper` and its parents:
.. method:: getvalue()
Return a ``unicode`` containing the entire contents of the buffer at any
time before the :class:`~io.StringIO` object's :meth:`close` method is
called. Newlines are decoded as if by :meth:`~TextIOBase.read`,
although the stream position is not changed.
Example usage::
import io
output = io.StringIO()
output.write(u'First line.\n')
output.write(u'Second line.\n')
# Retrieve file contents -- this will be
# u'First line.\nSecond line.\n'
contents = output.getvalue()
# Close object and discard memory buffer --
# .getvalue() will now raise an exception.
output.close()
.. index::
single: universal newlines; io.IncrementalNewlineDecoder class
.. class:: IncrementalNewlineDecoder
A helper codec that decodes newlines for :term:`universal newlines` mode.
It inherits :class:`codecs.IncrementalDecoder`.
Advanced topics
---------------
Here we will discuss several advanced topics pertaining to the concrete
I/O implementations described above.
Performance
^^^^^^^^^^^
Binary I/O
""""""""""
By reading and writing only large chunks of data even when the user asks
for a single byte, buffered I/O is designed to hide any inefficiency in
calling and executing the operating system's unbuffered I/O routines. The
gain will vary very much depending on the OS and the kind of I/O which is
performed (for example, on some contemporary OSes such as Linux, unbuffered
disk I/O can be as fast as buffered I/O). The bottom line, however, is
that buffered I/O will offer you predictable performance regardless of the
platform and the backing device. Therefore, it is most always preferable to
use buffered I/O rather than unbuffered I/O.
Text I/O
""""""""
Text I/O over a binary storage (such as a file) is significantly slower than
binary I/O over the same storage, because it implies conversions from
unicode to binary data using a character codec. This can become noticeable
if you handle huge amounts of text data (for example very large log files).
Also, :meth:`TextIOWrapper.tell` and :meth:`TextIOWrapper.seek` are both
quite slow due to the reconstruction algorithm used.
:class:`~io.StringIO`, however, is a native in-memory unicode container and will
exhibit similar speed to :class:`BytesIO`.
Multi-threading
^^^^^^^^^^^^^^^
:class:`FileIO` objects are thread-safe to the extent that the operating
system calls (such as ``read(2)`` under Unix) they are wrapping are thread-safe
too.
Binary buffered objects (instances of :class:`BufferedReader`,
:class:`BufferedWriter`, :class:`BufferedRandom` and :class:`BufferedRWPair`)
protect their internal structures using a lock; it is therefore safe to call
them from multiple threads at once.
:class:`TextIOWrapper` objects are not thread-safe.
Reentrancy
^^^^^^^^^^
Binary buffered objects (instances of :class:`BufferedReader`,
:class:`BufferedWriter`, :class:`BufferedRandom` and :class:`BufferedRWPair`)
are not reentrant. While reentrant calls will not happen in normal situations,
they can arise if you are doing I/O in a :mod:`signal` handler. If it is
attempted to enter a buffered object again while already being accessed
*from the same thread*, then a :exc:`RuntimeError` is raised.
The above implicitly extends to text files, since the :func:`open()`
function will wrap a buffered object inside a :class:`TextIOWrapper`. This
includes standard streams and therefore affects the built-in function
:func:`print()` as well.
PK %�\�rL�v v ! html/_sources/library/ipc.rst.txtnu �[���
.. _ipc:
*****************************************
Interprocess Communication and Networking
*****************************************
The modules described in this chapter provide mechanisms for different processes
to communicate.
Some modules only work for two processes that are on the same machine, e.g.
:mod:`signal` and :mod:`subprocess`. Other modules support networking protocols
that two or more processes can use to communicate across machines.
The list of modules described in this chapter is:
.. toctree::
subprocess.rst
socket.rst
ssl.rst
signal.rst
popen2.rst
asyncore.rst
asynchat.rst
PK %�\���� � ' html/_sources/library/itertools.rst.txtnu �[���
:mod:`itertools` --- Functions creating iterators for efficient looping
=======================================================================
.. module:: itertools
:synopsis: Functions creating iterators for efficient looping.
.. moduleauthor:: Raymond Hettinger <python@rcn.com>
.. sectionauthor:: Raymond Hettinger <python@rcn.com>
.. testsetup::
from itertools import *
.. versionadded:: 2.3
This module implements a number of :term:`iterator` building blocks inspired
by constructs from APL, Haskell, and SML. Each has been recast in a form
suitable for Python.
The module standardizes a core set of fast, memory efficient tools that are
useful by themselves or in combination. Together, they form an "iterator
algebra" making it possible to construct specialized tools succinctly and
efficiently in pure Python.
For instance, SML provides a tabulation tool: ``tabulate(f)`` which produces a
sequence ``f(0), f(1), ...``. The same effect can be achieved in Python
by combining :func:`imap` and :func:`count` to form ``imap(f, count())``.
These tools and their built-in counterparts also work well with the high-speed
functions in the :mod:`operator` module. For example, the multiplication
operator can be mapped across two vectors to form an efficient dot-product:
``sum(imap(operator.mul, vector1, vector2))``.
**Infinite Iterators:**
================== ================= ================================================= =========================================
Iterator Arguments Results Example
================== ================= ================================================= =========================================
:func:`count` start, [step] start, start+step, start+2*step, ... ``count(10) --> 10 11 12 13 14 ...``
:func:`cycle` p p0, p1, ... plast, p0, p1, ... ``cycle('ABCD') --> A B C D A B C D ...``
:func:`repeat` elem [,n] elem, elem, elem, ... endlessly or up to n times ``repeat(10, 3) --> 10 10 10``
================== ================= ================================================= =========================================
**Iterators terminating on the shortest input sequence:**
==================== ============================ ================================================= =============================================================
Iterator Arguments Results Example
==================== ============================ ================================================= =============================================================
:func:`chain` p, q, ... p0, p1, ... plast, q0, q1, ... ``chain('ABC', 'DEF') --> A B C D E F``
:func:`compress` data, selectors (d[0] if s[0]), (d[1] if s[1]), ... ``compress('ABCDEF', [1,0,1,0,1,1]) --> A C E F``
:func:`dropwhile` pred, seq seq[n], seq[n+1], starting when pred fails ``dropwhile(lambda x: x<5, [1,4,6,4,1]) --> 6 4 1``
:func:`groupby` iterable[, keyfunc] sub-iterators grouped by value of keyfunc(v)
:func:`ifilter` pred, seq elements of seq where pred(elem) is true ``ifilter(lambda x: x%2, range(10)) --> 1 3 5 7 9``
:func:`ifilterfalse` pred, seq elements of seq where pred(elem) is false ``ifilterfalse(lambda x: x%2, range(10)) --> 0 2 4 6 8``
:func:`islice` seq, [start,] stop [, step] elements from seq[start:stop:step] ``islice('ABCDEFG', 2, None) --> C D E F G``
:func:`imap` func, p, q, ... func(p0, q0), func(p1, q1), ... ``imap(pow, (2,3,10), (5,2,3)) --> 32 9 1000``
:func:`starmap` func, seq func(\*seq[0]), func(\*seq[1]), ... ``starmap(pow, [(2,5), (3,2), (10,3)]) --> 32 9 1000``
:func:`tee` it, n it1, it2, ... itn splits one iterator into n
:func:`takewhile` pred, seq seq[0], seq[1], until pred fails ``takewhile(lambda x: x<5, [1,4,6,4,1]) --> 1 4``
:func:`izip` p, q, ... (p[0], q[0]), (p[1], q[1]), ... ``izip('ABCD', 'xy') --> Ax By``
:func:`izip_longest` p, q, ... (p[0], q[0]), (p[1], q[1]), ... ``izip_longest('ABCD', 'xy', fillvalue='-') --> Ax By C- D-``
==================== ============================ ================================================= =============================================================
**Combinatoric generators:**
============================================== ==================== =============================================================
Iterator Arguments Results
============================================== ==================== =============================================================
:func:`product` p, q, ... [repeat=1] cartesian product, equivalent to a nested for-loop
:func:`permutations` p[, r] r-length tuples, all possible orderings, no repeated elements
:func:`combinations` p, r r-length tuples, in sorted order, no repeated elements
:func:`combinations_with_replacement` p, r r-length tuples, in sorted order, with repeated elements
``product('ABCD', repeat=2)`` ``AA AB AC AD BA BB BC BD CA CB CC CD DA DB DC DD``
``permutations('ABCD', 2)`` ``AB AC AD BA BC BD CA CB CD DA DB DC``
``combinations('ABCD', 2)`` ``AB AC AD BC BD CD``
``combinations_with_replacement('ABCD', 2)`` ``AA AB AC AD BB BC BD CC CD DD``
============================================== ==================== =============================================================
.. _itertools-functions:
Itertool functions
------------------
The following module functions all construct and return iterators. Some provide
streams of infinite length, so they should only be accessed by functions or
loops that truncate the stream.
.. function:: chain(*iterables)
Make an iterator that returns elements from the first iterable until it is
exhausted, then proceeds to the next iterable, until all of the iterables are
exhausted. Used for treating consecutive sequences as a single sequence.
Roughly equivalent to::
def chain(*iterables):
# chain('ABC', 'DEF') --> A B C D E F
for it in iterables:
for element in it:
yield element
.. classmethod:: chain.from_iterable(iterable)
Alternate constructor for :func:`chain`. Gets chained inputs from a
single iterable argument that is evaluated lazily. Roughly equivalent to::
def from_iterable(iterables):
# chain.from_iterable(['ABC', 'DEF']) --> A B C D E F
for it in iterables:
for element in it:
yield element
.. versionadded:: 2.6
.. function:: combinations(iterable, r)
Return *r* length subsequences of elements from the input *iterable*.
Combinations are emitted in lexicographic sort order. So, if the
input *iterable* is sorted, the combination tuples will be produced
in sorted order.
Elements are treated as unique based on their position, not on their
value. So if the input elements are unique, there will be no repeat
values in each combination.
Roughly equivalent to::
def combinations(iterable, r):
# combinations('ABCD', 2) --> AB AC AD BC BD CD
# combinations(range(4), 3) --> 012 013 023 123
pool = tuple(iterable)
n = len(pool)
if r > n:
return
indices = range(r)
yield tuple(pool[i] for i in indices)
while True:
for i in reversed(range(r)):
if indices[i] != i + n - r:
break
else:
return
indices[i] += 1
for j in range(i+1, r):
indices[j] = indices[j-1] + 1
yield tuple(pool[i] for i in indices)
The code for :func:`combinations` can be also expressed as a subsequence
of :func:`permutations` after filtering entries where the elements are not
in sorted order (according to their position in the input pool)::
def combinations(iterable, r):
pool = tuple(iterable)
n = len(pool)
for indices in permutations(range(n), r):
if sorted(indices) == list(indices):
yield tuple(pool[i] for i in indices)
The number of items returned is ``n! / r! / (n-r)!`` when ``0 <= r <= n``
or zero when ``r > n``.
.. versionadded:: 2.6
.. function:: combinations_with_replacement(iterable, r)
Return *r* length subsequences of elements from the input *iterable*
allowing individual elements to be repeated more than once.
Combinations are emitted in lexicographic sort order. So, if the
input *iterable* is sorted, the combination tuples will be produced
in sorted order.
Elements are treated as unique based on their position, not on their
value. So if the input elements are unique, the generated combinations
will also be unique.
Roughly equivalent to::
def combinations_with_replacement(iterable, r):
# combinations_with_replacement('ABC', 2) --> AA AB AC BB BC CC
pool = tuple(iterable)
n = len(pool)
if not n and r:
return
indices = [0] * r
yield tuple(pool[i] for i in indices)
while True:
for i in reversed(range(r)):
if indices[i] != n - 1:
break
else:
return
indices[i:] = [indices[i] + 1] * (r - i)
yield tuple(pool[i] for i in indices)
The code for :func:`combinations_with_replacement` can be also expressed as
a subsequence of :func:`product` after filtering entries where the elements
are not in sorted order (according to their position in the input pool)::
def combinations_with_replacement(iterable, r):
pool = tuple(iterable)
n = len(pool)
for indices in product(range(n), repeat=r):
if sorted(indices) == list(indices):
yield tuple(pool[i] for i in indices)
The number of items returned is ``(n+r-1)! / r! / (n-1)!`` when ``n > 0``.
.. versionadded:: 2.7
.. function:: compress(data, selectors)
Make an iterator that filters elements from *data* returning only those that
have a corresponding element in *selectors* that evaluates to ``True``.
Stops when either the *data* or *selectors* iterables has been exhausted.
Roughly equivalent to::
def compress(data, selectors):
# compress('ABCDEF', [1,0,1,0,1,1]) --> A C E F
return (d for d, s in izip(data, selectors) if s)
.. versionadded:: 2.7
.. function:: count(start=0, step=1)
Make an iterator that returns evenly spaced values starting with *n*. Often
used as an argument to :func:`imap` to generate consecutive data points.
Also, used with :func:`izip` to add sequence numbers. Equivalent to::
def count(start=0, step=1):
# count(10) --> 10 11 12 13 14 ...
# count(2.5, 0.5) -> 2.5 3.0 3.5 ...
n = start
while True:
yield n
n += step
When counting with floating point numbers, better accuracy can sometimes be
achieved by substituting multiplicative code such as: ``(start + step * i
for i in count())``.
.. versionchanged:: 2.7
added *step* argument and allowed non-integer arguments.
.. function:: cycle(iterable)
Make an iterator returning elements from the iterable and saving a copy of each.
When the iterable is exhausted, return elements from the saved copy. Repeats
indefinitely. Roughly equivalent to::
def cycle(iterable):
# cycle('ABCD') --> A B C D A B C D A B C D ...
saved = []
for element in iterable:
yield element
saved.append(element)
while saved:
for element in saved:
yield element
Note, this member of the toolkit may require significant auxiliary storage
(depending on the length of the iterable).
.. function:: dropwhile(predicate, iterable)
Make an iterator that drops elements from the iterable as long as the predicate
is true; afterwards, returns every element. Note, the iterator does not produce
*any* output until the predicate first becomes false, so it may have a lengthy
start-up time. Roughly equivalent to::
def dropwhile(predicate, iterable):
# dropwhile(lambda x: x<5, [1,4,6,4,1]) --> 6 4 1
iterable = iter(iterable)
for x in iterable:
if not predicate(x):
yield x
break
for x in iterable:
yield x
.. function:: groupby(iterable[, key])
Make an iterator that returns consecutive keys and groups from the *iterable*.
The *key* is a function computing a key value for each element. If not
specified or is ``None``, *key* defaults to an identity function and returns
the element unchanged. Generally, the iterable needs to already be sorted on
the same key function.
The operation of :func:`groupby` is similar to the ``uniq`` filter in Unix. It
generates a break or new group every time the value of the key function changes
(which is why it is usually necessary to have sorted the data using the same key
function). That behavior differs from SQL's GROUP BY which aggregates common
elements regardless of their input order.
The returned group is itself an iterator that shares the underlying iterable
with :func:`groupby`. Because the source is shared, when the :func:`groupby`
object is advanced, the previous group is no longer visible. So, if that data
is needed later, it should be stored as a list::
groups = []
uniquekeys = []
data = sorted(data, key=keyfunc)
for k, g in groupby(data, keyfunc):
groups.append(list(g)) # Store group iterator as a list
uniquekeys.append(k)
:func:`groupby` is roughly equivalent to::
class groupby(object):
# [k for k, g in groupby('AAAABBBCCDAABBB')] --> A B C D A B
# [list(g) for k, g in groupby('AAAABBBCCD')] --> AAAA BBB CC D
def __init__(self, iterable, key=None):
if key is None:
key = lambda x: x
self.keyfunc = key
self.it = iter(iterable)
self.tgtkey = self.currkey = self.currvalue = object()
def __iter__(self):
return self
def next(self):
while self.currkey == self.tgtkey:
self.currvalue = next(self.it) # Exit on StopIteration
self.currkey = self.keyfunc(self.currvalue)
self.tgtkey = self.currkey
return (self.currkey, self._grouper(self.tgtkey))
def _grouper(self, tgtkey):
while self.currkey == tgtkey:
yield self.currvalue
self.currvalue = next(self.it) # Exit on StopIteration
self.currkey = self.keyfunc(self.currvalue)
.. versionadded:: 2.4
.. function:: ifilter(predicate, iterable)
Make an iterator that filters elements from iterable returning only those for
which the predicate is ``True``. If *predicate* is ``None``, return the items
that are true. Roughly equivalent to::
def ifilter(predicate, iterable):
# ifilter(lambda x: x%2, range(10)) --> 1 3 5 7 9
if predicate is None:
predicate = bool
for x in iterable:
if predicate(x):
yield x
.. function:: ifilterfalse(predicate, iterable)
Make an iterator that filters elements from iterable returning only those for
which the predicate is ``False``. If *predicate* is ``None``, return the items
that are false. Roughly equivalent to::
def ifilterfalse(predicate, iterable):
# ifilterfalse(lambda x: x%2, range(10)) --> 0 2 4 6 8
if predicate is None:
predicate = bool
for x in iterable:
if not predicate(x):
yield x
.. function:: imap(function, *iterables)
Make an iterator that computes the function using arguments from each of the
iterables. If *function* is set to ``None``, then :func:`imap` returns the
arguments as a tuple. Like :func:`map` but stops when the shortest iterable is
exhausted instead of filling in ``None`` for shorter iterables. The reason for
the difference is that infinite iterator arguments are typically an error for
:func:`map` (because the output is fully evaluated) but represent a common and
useful way of supplying arguments to :func:`imap`. Roughly equivalent to::
def imap(function, *iterables):
# imap(pow, (2,3,10), (5,2,3)) --> 32 9 1000
iterables = map(iter, iterables)
while True:
args = [next(it) for it in iterables]
if function is None:
yield tuple(args)
else:
yield function(*args)
.. function:: islice(iterable, stop)
islice(iterable, start, stop[, step])
Make an iterator that returns selected elements from the iterable. If *start* is
non-zero, then elements from the iterable are skipped until start is reached.
Afterward, elements are returned consecutively unless *step* is set higher than
one which results in items being skipped. If *stop* is ``None``, then iteration
continues until the iterator is exhausted, if at all; otherwise, it stops at the
specified position. Unlike regular slicing, :func:`islice` does not support
negative values for *start*, *stop*, or *step*. Can be used to extract related
fields from data where the internal structure has been flattened (for example, a
multi-line report may list a name field on every third line). Roughly equivalent to::
def islice(iterable, *args):
# islice('ABCDEFG', 2) --> A B
# islice('ABCDEFG', 2, 4) --> C D
# islice('ABCDEFG', 2, None) --> C D E F G
# islice('ABCDEFG', 0, None, 2) --> A C E G
s = slice(*args)
start, stop, step = s.start or 0, s.stop or sys.maxint, s.step or 1
it = iter(xrange(start, stop, step)))
try:
nexti = next(it)
except StopIteration:
# Consume *iterable* up to the *start* position.
for i, element in izip(xrange(start), iterable):
pass
return
try:
for i, element in enumerate(iterable):
if i == nexti:
yield element
nexti = next(it)
except StopIteration:
# Consume to *stop*.
for i, element in izip(xrange(i + 1, stop), iterable):
pass
If *start* is ``None``, then iteration starts at zero. If *step* is ``None``,
then the step defaults to one.
.. versionchanged:: 2.5
accept ``None`` values for default *start* and *step*.
.. function:: izip(*iterables)
Make an iterator that aggregates elements from each of the iterables. Like
:func:`zip` except that it returns an iterator instead of a list. Used for
lock-step iteration over several iterables at a time. Roughly equivalent to::
def izip(*iterables):
# izip('ABCD', 'xy') --> Ax By
iterators = map(iter, iterables)
while iterators:
yield tuple(map(next, iterators))
.. versionchanged:: 2.4
When no iterables are specified, returns a zero length iterator instead of
raising a :exc:`TypeError` exception.
The left-to-right evaluation order of the iterables is guaranteed. This
makes possible an idiom for clustering a data series into n-length groups
using ``izip(*[iter(s)]*n)``.
:func:`izip` should only be used with unequal length inputs when you don't
care about trailing, unmatched values from the longer iterables. If those
values are important, use :func:`izip_longest` instead.
.. function:: izip_longest(*iterables[, fillvalue])
Make an iterator that aggregates elements from each of the iterables. If the
iterables are of uneven length, missing values are filled-in with *fillvalue*.
Iteration continues until the longest iterable is exhausted. Roughly equivalent to::
class ZipExhausted(Exception):
pass
def izip_longest(*args, **kwds):
# izip_longest('ABCD', 'xy', fillvalue='-') --> Ax By C- D-
fillvalue = kwds.get('fillvalue')
counter = [len(args) - 1]
def sentinel():
if not counter[0]:
raise ZipExhausted
counter[0] -= 1
yield fillvalue
fillers = repeat(fillvalue)
iterators = [chain(it, sentinel(), fillers) for it in args]
try:
while iterators:
yield tuple(map(next, iterators))
except ZipExhausted:
pass
If one of the iterables is potentially infinite, then the
:func:`izip_longest` function should be wrapped with something that limits
the number of calls (for example :func:`islice` or :func:`takewhile`). If
not specified, *fillvalue* defaults to ``None``.
.. versionadded:: 2.6
.. function:: permutations(iterable[, r])
Return successive *r* length permutations of elements in the *iterable*.
If *r* is not specified or is ``None``, then *r* defaults to the length
of the *iterable* and all possible full-length permutations
are generated.
Permutations are emitted in lexicographic sort order. So, if the
input *iterable* is sorted, the permutation tuples will be produced
in sorted order.
Elements are treated as unique based on their position, not on their
value. So if the input elements are unique, there will be no repeat
values in each permutation.
Roughly equivalent to::
def permutations(iterable, r=None):
# permutations('ABCD', 2) --> AB AC AD BA BC BD CA CB CD DA DB DC
# permutations(range(3)) --> 012 021 102 120 201 210
pool = tuple(iterable)
n = len(pool)
r = n if r is None else r
if r > n:
return
indices = range(n)
cycles = range(n, n-r, -1)
yield tuple(pool[i] for i in indices[:r])
while n:
for i in reversed(range(r)):
cycles[i] -= 1
if cycles[i] == 0:
indices[i:] = indices[i+1:] + indices[i:i+1]
cycles[i] = n - i
else:
j = cycles[i]
indices[i], indices[-j] = indices[-j], indices[i]
yield tuple(pool[i] for i in indices[:r])
break
else:
return
The code for :func:`permutations` can be also expressed as a subsequence of
:func:`product`, filtered to exclude entries with repeated elements (those
from the same position in the input pool)::
def permutations(iterable, r=None):
pool = tuple(iterable)
n = len(pool)
r = n if r is None else r
for indices in product(range(n), repeat=r):
if len(set(indices)) == r:
yield tuple(pool[i] for i in indices)
The number of items returned is ``n! / (n-r)!`` when ``0 <= r <= n``
or zero when ``r > n``.
.. versionadded:: 2.6
.. function:: product(*iterables[, repeat])
Cartesian product of input iterables.
Roughly equivalent to nested for-loops in a generator expression. For example,
``product(A, B)`` returns the same as ``((x,y) for x in A for y in B)``.
The nested loops cycle like an odometer with the rightmost element advancing
on every iteration. This pattern creates a lexicographic ordering so that if
the input's iterables are sorted, the product tuples are emitted in sorted
order.
To compute the product of an iterable with itself, specify the number of
repetitions with the optional *repeat* keyword argument. For example,
``product(A, repeat=4)`` means the same as ``product(A, A, A, A)``.
This function is roughly equivalent to the following code, except that the
actual implementation does not build up intermediate results in memory::
def product(*args, **kwds):
# product('ABCD', 'xy') --> Ax Ay Bx By Cx Cy Dx Dy
# product(range(2), repeat=3) --> 000 001 010 011 100 101 110 111
pools = map(tuple, args) * kwds.get('repeat', 1)
result = [[]]
for pool in pools:
result = [x+[y] for x in result for y in pool]
for prod in result:
yield tuple(prod)
.. versionadded:: 2.6
.. function:: repeat(object[, times])
Make an iterator that returns *object* over and over again. Runs indefinitely
unless the *times* argument is specified. Used as argument to :func:`imap` for
invariant function parameters. Also used with :func:`izip` to create constant
fields in a tuple record. Roughly equivalent to::
def repeat(object, times=None):
# repeat(10, 3) --> 10 10 10
if times is None:
while True:
yield object
else:
for i in xrange(times):
yield object
A common use for *repeat* is to supply a stream of constant values to *imap*
or *zip*::
>>> list(imap(pow, xrange(10), repeat(2)))
[0, 1, 4, 9, 16, 25, 36, 49, 64, 81]
.. function:: starmap(function, iterable)
Make an iterator that computes the function using arguments obtained from
the iterable. Used instead of :func:`imap` when argument parameters are already
grouped in tuples from a single iterable (the data has been "pre-zipped"). The
difference between :func:`imap` and :func:`starmap` parallels the distinction
between ``function(a,b)`` and ``function(*c)``. Roughly equivalent to::
def starmap(function, iterable):
# starmap(pow, [(2,5), (3,2), (10,3)]) --> 32 9 1000
for args in iterable:
yield function(*args)
.. versionchanged:: 2.6
Previously, :func:`starmap` required the function arguments to be tuples.
Now, any iterable is allowed.
.. function:: takewhile(predicate, iterable)
Make an iterator that returns elements from the iterable as long as the
predicate is true. Roughly equivalent to::
def takewhile(predicate, iterable):
# takewhile(lambda x: x<5, [1,4,6,4,1]) --> 1 4
for x in iterable:
if predicate(x):
yield x
else:
break
.. function:: tee(iterable[, n=2])
Return *n* independent iterators from a single iterable. Roughly equivalent to::
def tee(iterable, n=2):
it = iter(iterable)
deques = [collections.deque() for i in range(n)]
def gen(mydeque):
while True:
if not mydeque: # when the local deque is empty
newval = next(it) # fetch a new value and
for d in deques: # load it to all the deques
d.append(newval)
yield mydeque.popleft()
return tuple(gen(d) for d in deques)
Once :func:`tee` has made a split, the original *iterable* should not be
used anywhere else; otherwise, the *iterable* could get advanced without
the tee objects being informed.
This itertool may require significant auxiliary storage (depending on how
much temporary data needs to be stored). In general, if one iterator uses
most or all of the data before another iterator starts, it is faster to use
:func:`list` instead of :func:`tee`.
.. versionadded:: 2.4
.. _itertools-recipes:
Recipes
-------
This section shows recipes for creating an extended toolset using the existing
itertools as building blocks.
The extended tools offer the same high performance as the underlying toolset.
The superior memory performance is kept by processing elements one at a time
rather than bringing the whole iterable into memory all at once. Code volume is
kept small by linking the tools together in a functional style which helps
eliminate temporary variables. High speed is retained by preferring
"vectorized" building blocks over the use of for-loops and :term:`generator`\s
which incur interpreter overhead.
.. testcode::
def take(n, iterable):
"Return first n items of the iterable as a list"
return list(islice(iterable, n))
def tabulate(function, start=0):
"Return function(0), function(1), ..."
return imap(function, count(start))
def consume(iterator, n=None):
"Advance the iterator n-steps ahead. If n is None, consume entirely."
# Use functions that consume iterators at C speed.
if n is None:
# feed the entire iterator into a zero-length deque
collections.deque(iterator, maxlen=0)
else:
# advance to the empty slice starting at position n
next(islice(iterator, n, n), None)
def nth(iterable, n, default=None):
"Returns the nth item or a default value"
return next(islice(iterable, n, None), default)
def all_equal(iterable):
"Returns True if all the elements are equal to each other"
g = groupby(iterable)
return next(g, True) and not next(g, False)
def quantify(iterable, pred=bool):
"Count how many times the predicate is true"
return sum(imap(pred, iterable))
def padnone(iterable):
"""Returns the sequence elements and then returns None indefinitely.
Useful for emulating the behavior of the built-in map() function.
"""
return chain(iterable, repeat(None))
def ncycles(iterable, n):
"Returns the sequence elements n times"
return chain.from_iterable(repeat(tuple(iterable), n))
def dotproduct(vec1, vec2):
return sum(imap(operator.mul, vec1, vec2))
def flatten(listOfLists):
"Flatten one level of nesting"
return chain.from_iterable(listOfLists)
def repeatfunc(func, times=None, *args):
"""Repeat calls to func with specified arguments.
Example: repeatfunc(random.random)
"""
if times is None:
return starmap(func, repeat(args))
return starmap(func, repeat(args, times))
def pairwise(iterable):
"s -> (s0,s1), (s1,s2), (s2, s3), ..."
a, b = tee(iterable)
next(b, None)
return izip(a, b)
def grouper(iterable, n, fillvalue=None):
"Collect data into fixed-length chunks or blocks"
# grouper('ABCDEFG', 3, 'x') --> ABC DEF Gxx
args = [iter(iterable)] * n
return izip_longest(fillvalue=fillvalue, *args)
def roundrobin(*iterables):
"roundrobin('ABC', 'D', 'EF') --> A D E B F C"
# Recipe credited to George Sakkis
pending = len(iterables)
nexts = cycle(iter(it).next for it in iterables)
while pending:
try:
for next in nexts:
yield next()
except StopIteration:
pending -= 1
nexts = cycle(islice(nexts, pending))
def powerset(iterable):
"powerset([1,2,3]) --> () (1,) (2,) (3,) (1,2) (1,3) (2,3) (1,2,3)"
s = list(iterable)
return chain.from_iterable(combinations(s, r) for r in range(len(s)+1))
def unique_everseen(iterable, key=None):
"List unique elements, preserving order. Remember all elements ever seen."
# unique_everseen('AAAABBBCCDAABBB') --> A B C D
# unique_everseen('ABBCcAD', str.lower) --> A B C D
seen = set()
seen_add = seen.add
if key is None:
for element in ifilterfalse(seen.__contains__, iterable):
seen_add(element)
yield element
else:
for element in iterable:
k = key(element)
if k not in seen:
seen_add(k)
yield element
def unique_justseen(iterable, key=None):
"List unique elements, preserving order. Remember only the element just seen."
# unique_justseen('AAAABBBCCDAABBB') --> A B C D A B
# unique_justseen('ABBCcAD', str.lower) --> A B C A D
return imap(next, imap(itemgetter(1), groupby(iterable, key)))
def iter_except(func, exception, first=None):
""" Call a function repeatedly until an exception is raised.
Converts a call-until-exception interface to an iterator interface.
Like __builtin__.iter(func, sentinel) but uses an exception instead
of a sentinel to end the loop.
Examples:
bsddbiter = iter_except(db.next, bsddb.error, db.first)
heapiter = iter_except(functools.partial(heappop, h), IndexError)
dictiter = iter_except(d.popitem, KeyError)
dequeiter = iter_except(d.popleft, IndexError)
queueiter = iter_except(q.get_nowait, Queue.Empty)
setiter = iter_except(s.pop, KeyError)
"""
try:
if first is not None:
yield first()
while 1:
yield func()
except exception:
pass
def random_product(*args, **kwds):
"Random selection from itertools.product(*args, **kwds)"
pools = map(tuple, args) * kwds.get('repeat', 1)
return tuple(random.choice(pool) for pool in pools)
def random_permutation(iterable, r=None):
"Random selection from itertools.permutations(iterable, r)"
pool = tuple(iterable)
r = len(pool) if r is None else r
return tuple(random.sample(pool, r))
def random_combination(iterable, r):
"Random selection from itertools.combinations(iterable, r)"
pool = tuple(iterable)
n = len(pool)
indices = sorted(random.sample(xrange(n), r))
return tuple(pool[i] for i in indices)
def random_combination_with_replacement(iterable, r):
"Random selection from itertools.combinations_with_replacement(iterable, r)"
pool = tuple(iterable)
n = len(pool)
indices = sorted(random.randrange(n) for i in xrange(r))
return tuple(pool[i] for i in indices)
def tee_lookahead(t, i):
"""Inspect the i-th upcomping value from a tee object
while leaving the tee object at its current position.
Raise an IndexError if the underlying iterator doesn't
have enough values.
"""
for value in islice(t.__copy__(), i, None):
return value
raise IndexError(i)
Note, many of the above recipes can be optimized by replacing global lookups
with local variables defined as default values. For example, the
*dotproduct* recipe can be written as::
def dotproduct(vec1, vec2, sum=sum, imap=imap, mul=operator.mul):
return sum(imap(mul, vec1, vec2))
PK %�\g v� " html/_sources/library/jpeg.rst.txtnu �[���
:mod:`jpeg` --- Read and write JPEG files
=========================================
.. module:: jpeg
:platform: IRIX
:synopsis: Read and write image files in compressed JPEG format.
:deprecated:
.. deprecated:: 2.6
The :mod:`jpeg` module has been removed in Python 3.
.. index:: single: Independent JPEG Group
The module :mod:`jpeg` provides access to the jpeg compressor and decompressor
written by the Independent JPEG Group (IJG). JPEG is a standard for compressing
pictures; it is defined in ISO 10918. For details on JPEG or the Independent
JPEG Group software refer to the JPEG standard or the documentation provided
with the software.
.. index::
single: Python Imaging Library
single: PIL (the Python Imaging Library)
single: Lundh, Fredrik
A portable interface to JPEG image files is available with the Python Imaging
Library (PIL) by Fredrik Lundh. Information on PIL is available at
http://www.pythonware.com/products/pil/.
The :mod:`jpeg` module defines an exception and some functions.
.. exception:: error
Exception raised by :func:`compress` and :func:`decompress` in case of errors.
.. function:: compress(data, w, h, b)
.. index:: single: JFIF
Treat data as a pixmap of width *w* and height *h*, with *b* bytes per pixel.
The data is in SGI GL order, so the first pixel is in the lower-left corner.
This means that :func:`gl.lrectread` return data can immediately be passed to
:func:`compress`. Currently only 1 byte and 4 byte pixels are allowed, the
former being treated as greyscale and the latter as RGB color. :func:`compress`
returns a string that contains the compressed picture, in JFIF format.
.. function:: decompress(data)
.. index:: single: JFIF
Data is a string containing a picture in JFIF format. It returns a tuple
``(data, width, height, bytesperpixel)``. Again, the data is suitable to pass
to :func:`gl.lrectwrite`.
.. function:: setoption(name, value)
Set various options. Subsequent :func:`compress` and :func:`decompress` calls
will use these options. The following options are available:
+-----------------+---------------------------------------------+
| Option | Effect |
+=================+=============================================+
| ``'forcegray'`` | Force output to be grayscale, even if input |
| | is RGB. |
+-----------------+---------------------------------------------+
| ``'quality'`` | Set the quality of the compressed image to |
| | a value between ``0`` and ``100`` (default |
| | is ``75``). This only affects compression. |
+-----------------+---------------------------------------------+
| ``'optimize'`` | Perform Huffman table optimization. Takes |
| | longer, but results in smaller compressed |
| | image. This only affects compression. |
+-----------------+---------------------------------------------+
| ``'smooth'`` | Perform inter-block smoothing on |
| | uncompressed image. Only useful for low- |
| | quality images. This only affects |
| | decompression. |
+-----------------+---------------------------------------------+
.. seealso::
JPEG Still Image Data Compression Standard
The canonical reference for the JPEG image format, by Pennebaker and Mitchell.
`Information Technology - Digital Compression and Coding of Continuous-tone Still Images - Requirements and Guidelines <http://www.w3.org/Graphics/JPEG/itu-t81.pdf>`_
The ISO standard for JPEG is also published as ITU T.81. This is available
online in PDF form.
PK %�\}��;�c �c " html/_sources/library/json.rst.txtnu �[��� :mod:`json` --- JSON encoder and decoder
========================================
.. module:: json
:synopsis: Encode and decode the JSON format.
.. moduleauthor:: Bob Ippolito <bob@redivi.com>
.. sectionauthor:: Bob Ippolito <bob@redivi.com>
.. versionadded:: 2.6
`JSON (JavaScript Object Notation) <http://json.org>`_, specified by
:rfc:`7159` (which obsoletes :rfc:`4627`) and by
`ECMA-404 <http://www.ecma-international.org/publications/standards/Ecma-404.htm>`_,
is a lightweight data interchange format inspired by
`JavaScript <https://en.wikipedia.org/wiki/JavaScript>`_ object literal syntax
(although it is not a strict subset of JavaScript [#rfc-errata]_ ).
:mod:`json` exposes an API familiar to users of the standard library
:mod:`marshal` and :mod:`pickle` modules.
Encoding basic Python object hierarchies::
>>> import json
>>> json.dumps(['foo', {'bar': ('baz', None, 1.0, 2)}])
'["foo", {"bar": ["baz", null, 1.0, 2]}]'
>>> print json.dumps("\"foo\bar")
"\"foo\bar"
>>> print json.dumps(u'\u1234')
"\u1234"
>>> print json.dumps('\\')
"\\"
>>> print json.dumps({"c": 0, "b": 0, "a": 0}, sort_keys=True)
{"a": 0, "b": 0, "c": 0}
>>> from StringIO import StringIO
>>> io = StringIO()
>>> json.dump(['streaming API'], io)
>>> io.getvalue()
'["streaming API"]'
Compact encoding::
>>> import json
>>> json.dumps([1,2,3,{'4': 5, '6': 7}], separators=(',',':'))
'[1,2,3,{"4":5,"6":7}]'
Pretty printing::
>>> import json
>>> print json.dumps({'4': 5, '6': 7}, sort_keys=True,
... indent=4, separators=(',', ': '))
{
"4": 5,
"6": 7
}
Decoding JSON::
>>> import json
>>> json.loads('["foo", {"bar":["baz", null, 1.0, 2]}]')
[u'foo', {u'bar': [u'baz', None, 1.0, 2]}]
>>> json.loads('"\\"foo\\bar"')
u'"foo\x08ar'
>>> from StringIO import StringIO
>>> io = StringIO('["streaming API"]')
>>> json.load(io)
[u'streaming API']
Specializing JSON object decoding::
>>> import json
>>> def as_complex(dct):
... if '__complex__' in dct:
... return complex(dct['real'], dct['imag'])
... return dct
...
>>> json.loads('{"__complex__": true, "real": 1, "imag": 2}',
... object_hook=as_complex)
(1+2j)
>>> import decimal
>>> json.loads('1.1', parse_float=decimal.Decimal)
Decimal('1.1')
Extending :class:`JSONEncoder`::
>>> import json
>>> class ComplexEncoder(json.JSONEncoder):
... def default(self, obj):
... if isinstance(obj, complex):
... return [obj.real, obj.imag]
... # Let the base class default method raise the TypeError
... return json.JSONEncoder.default(self, obj)
...
>>> json.dumps(2 + 1j, cls=ComplexEncoder)
'[2.0, 1.0]'
>>> ComplexEncoder().encode(2 + 1j)
'[2.0, 1.0]'
>>> list(ComplexEncoder().iterencode(2 + 1j))
['[', '2.0', ', ', '1.0', ']']
.. highlight:: none
Using :mod:`json.tool` from the shell to validate and pretty-print::
$ echo '{"json":"obj"}' | python -m json.tool
{
"json": "obj"
}
$ echo '{1.2:3.4}' | python -mjson.tool
Expecting property name enclosed in double quotes: line 1 column 2 (char 1)
.. highlight:: python
.. note::
JSON is a subset of `YAML <http://yaml.org/>`_ 1.2. The JSON produced by
this module's default settings (in particular, the default *separators*
value) is also a subset of YAML 1.0 and 1.1. This module can thus also be
used as a YAML serializer.
Basic Usage
-----------
.. function:: dump(obj, fp, skipkeys=False, ensure_ascii=True, \
check_circular=True, allow_nan=True, cls=None, \
indent=None, separators=None, encoding="utf-8", \
default=None, sort_keys=False, **kw)
Serialize *obj* as a JSON formatted stream to *fp* (a ``.write()``-supporting
:term:`file-like object`) using this :ref:`conversion table
<py-to-json-table>`.
If *skipkeys* is true (default: ``False``), then dict keys that are not
of a basic type (:class:`str`, :class:`unicode`, :class:`int`, :class:`long`,
:class:`float`, :class:`bool`, ``None``) will be skipped instead of raising a
:exc:`TypeError`.
If *ensure_ascii* is true (the default), all non-ASCII characters in the
output are escaped with ``\uXXXX`` sequences, and the result is a
:class:`str` instance consisting of ASCII characters only. If
*ensure_ascii* is false, some chunks written to *fp* may be
:class:`unicode` instances. This usually happens because the input contains
unicode strings or the *encoding* parameter is used. Unless ``fp.write()``
explicitly understands :class:`unicode` (as in :func:`codecs.getwriter`)
this is likely to cause an error.
If *check_circular* is false (default: ``True``), then the circular
reference check for container types will be skipped and a circular reference
will result in an :exc:`OverflowError` (or worse).
If *allow_nan* is false (default: ``True``), then it will be a
:exc:`ValueError` to serialize out of range :class:`float` values (``nan``,
``inf``, ``-inf``) in strict compliance of the JSON specification.
If *allow_nan* is true, their JavaScript equivalents (``NaN``,
``Infinity``, ``-Infinity``) will be used.
If *indent* is a non-negative integer, then JSON array elements and object
members will be pretty-printed with that indent level. An indent level of 0,
or negative, will only insert newlines. ``None`` (the default) selects the
most compact representation.
.. note::
Since the default item separator is ``', '``, the output might include
trailing whitespace when *indent* is specified. You can use
``separators=(',', ': ')`` to avoid this.
If specified, *separators* should be an ``(item_separator, key_separator)``
tuple. By default, ``(', ', ': ')`` are used. To get the most compact JSON
representation, you should specify ``(',', ':')`` to eliminate whitespace.
*encoding* is the character encoding for str instances, default is UTF-8.
If specified, *default* should be a function that gets called for objects that
can't otherwise be serialized. It should return a JSON encodable version of
the object or raise a :exc:`TypeError`. If not specified, :exc:`TypeError`
is raised.
If *sort_keys* is true (default: ``False``), then the output of
dictionaries will be sorted by key.
To use a custom :class:`JSONEncoder` subclass (e.g. one that overrides the
:meth:`default` method to serialize additional types), specify it with the
*cls* kwarg; otherwise :class:`JSONEncoder` is used.
.. note::
Unlike :mod:`pickle` and :mod:`marshal`, JSON is not a framed protocol so
trying to serialize more objects with repeated calls to :func:`dump` and
the same *fp* will result in an invalid JSON file.
.. function:: dumps(obj, skipkeys=False, ensure_ascii=True, \
check_circular=True, allow_nan=True, cls=None, \
indent=None, separators=None, encoding="utf-8", \
default=None, sort_keys=False, **kw)
Serialize *obj* to a JSON formatted :class:`str` using this :ref:`conversion
table <py-to-json-table>`. If *ensure_ascii* is false, the result may
contain non-ASCII characters and the return value may be a :class:`unicode`
instance.
The arguments have the same meaning as in :func:`dump`.
.. note::
Keys in key/value pairs of JSON are always of the type :class:`str`. When
a dictionary is converted into JSON, all the keys of the dictionary are
coerced to strings. As a result of this, if a dictionary is converted
into JSON and then back into a dictionary, the dictionary may not equal
the original one. That is, ``loads(dumps(x)) != x`` if x has non-string
keys.
.. function:: load(fp[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, object_pairs_hook[, **kw]]]]]]]])
Deserialize *fp* (a ``.read()``-supporting :term:`file-like object`
containing a JSON document) to a Python object using this :ref:`conversion
table <json-to-py-table>`.
If the contents of *fp* are encoded with an ASCII based encoding other than
UTF-8 (e.g. latin-1), then an appropriate *encoding* name must be specified.
Encodings that are not ASCII based (such as UCS-2) are not allowed, and
should be wrapped with ``codecs.getreader(encoding)(fp)``, or simply decoded
to a :class:`unicode` object and passed to :func:`loads`.
*object_hook* is an optional function that will be called with the result of
any object literal decoded (a :class:`dict`). The return value of
*object_hook* will be used instead of the :class:`dict`. This feature can be used
to implement custom decoders (e.g. `JSON-RPC <http://www.jsonrpc.org>`_
class hinting).
*object_pairs_hook* is an optional function that will be called with the
result of any object literal decoded with an ordered list of pairs. The
return value of *object_pairs_hook* will be used instead of the
:class:`dict`. This feature can be used to implement custom decoders that
rely on the order that the key and value pairs are decoded (for example,
:func:`collections.OrderedDict` will remember the order of insertion). If
*object_hook* is also defined, the *object_pairs_hook* takes priority.
.. versionchanged:: 2.7
Added support for *object_pairs_hook*.
*parse_float*, if specified, will be called with the string of every JSON
float to be decoded. By default, this is equivalent to ``float(num_str)``.
This can be used to use another datatype or parser for JSON floats
(e.g. :class:`decimal.Decimal`).
*parse_int*, if specified, will be called with the string of every JSON int
to be decoded. By default, this is equivalent to ``int(num_str)``. This can
be used to use another datatype or parser for JSON integers
(e.g. :class:`float`).
*parse_constant*, if specified, will be called with one of the following
strings: ``'-Infinity'``, ``'Infinity'``, ``'NaN'``.
This can be used to raise an exception if invalid JSON numbers
are encountered.
.. versionchanged:: 2.7
*parse_constant* doesn't get called on 'null', 'true', 'false' anymore.
To use a custom :class:`JSONDecoder` subclass, specify it with the ``cls``
kwarg; otherwise :class:`JSONDecoder` is used. Additional keyword arguments
will be passed to the constructor of the class.
.. function:: loads(s[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, object_pairs_hook[, **kw]]]]]]]])
Deserialize *s* (a :class:`str` or :class:`unicode` instance containing a JSON
document) to a Python object using this :ref:`conversion table
<json-to-py-table>`.
If *s* is a :class:`str` instance and is encoded with an ASCII based encoding
other than UTF-8 (e.g. latin-1), then an appropriate *encoding* name must be
specified. Encodings that are not ASCII based (such as UCS-2) are not
allowed and should be decoded to :class:`unicode` first.
The other arguments have the same meaning as in :func:`load`.
Encoders and Decoders
---------------------
.. class:: JSONDecoder([encoding[, object_hook[, parse_float[, parse_int[, parse_constant[, strict[, object_pairs_hook]]]]]]])
Simple JSON decoder.
Performs the following translations in decoding by default:
.. _json-to-py-table:
+---------------+-------------------+
| JSON | Python |
+===============+===================+
| object | dict |
+---------------+-------------------+
| array | list |
+---------------+-------------------+
| string | unicode |
+---------------+-------------------+
| number (int) | int, long |
+---------------+-------------------+
| number (real) | float |
+---------------+-------------------+
| true | True |
+---------------+-------------------+
| false | False |
+---------------+-------------------+
| null | None |
+---------------+-------------------+
It also understands ``NaN``, ``Infinity``, and ``-Infinity`` as their
corresponding ``float`` values, which is outside the JSON spec.
*encoding* determines the encoding used to interpret any :class:`str` objects
decoded by this instance (UTF-8 by default). It has no effect when decoding
:class:`unicode` objects.
Note that currently only encodings that are a superset of ASCII work, strings
of other encodings should be passed in as :class:`unicode`.
*object_hook*, if specified, will be called with the result of every JSON
object decoded and its return value will be used in place of the given
:class:`dict`. This can be used to provide custom deserializations (e.g. to
support JSON-RPC class hinting).
*object_pairs_hook*, if specified will be called with the result of every
JSON object decoded with an ordered list of pairs. The return value of
*object_pairs_hook* will be used instead of the :class:`dict`. This
feature can be used to implement custom decoders that rely on the order
that the key and value pairs are decoded (for example,
:func:`collections.OrderedDict` will remember the order of insertion). If
*object_hook* is also defined, the *object_pairs_hook* takes priority.
.. versionchanged:: 2.7
Added support for *object_pairs_hook*.
*parse_float*, if specified, will be called with the string of every JSON
float to be decoded. By default, this is equivalent to ``float(num_str)``.
This can be used to use another datatype or parser for JSON floats
(e.g. :class:`decimal.Decimal`).
*parse_int*, if specified, will be called with the string of every JSON int
to be decoded. By default, this is equivalent to ``int(num_str)``. This can
be used to use another datatype or parser for JSON integers
(e.g. :class:`float`).
*parse_constant*, if specified, will be called with one of the following
strings: ``'-Infinity'``, ``'Infinity'``, ``'NaN'``.
This can be used to raise an exception if invalid JSON numbers
are encountered.
If *strict* is false (``True`` is the default), then control characters
will be allowed inside strings. Control characters in this context are
those with character codes in the 0--31 range, including ``'\t'`` (tab),
``'\n'``, ``'\r'`` and ``'\0'``.
If the data being deserialized is not a valid JSON document, a
:exc:`ValueError` will be raised.
.. method:: decode(s)
Return the Python representation of *s* (a :class:`str` or
:class:`unicode` instance containing a JSON document).
.. method:: raw_decode(s)
Decode a JSON document from *s* (a :class:`str` or :class:`unicode`
beginning with a JSON document) and return a 2-tuple of the Python
representation and the index in *s* where the document ended.
This can be used to decode a JSON document from a string that may have
extraneous data at the end.
.. class:: JSONEncoder([skipkeys[, ensure_ascii[, check_circular[, allow_nan[, sort_keys[, indent[, separators[, encoding[, default]]]]]]]]])
Extensible JSON encoder for Python data structures.
Supports the following objects and types by default:
.. _py-to-json-table:
+-------------------+---------------+
| Python | JSON |
+===================+===============+
| dict | object |
+-------------------+---------------+
| list, tuple | array |
+-------------------+---------------+
| str, unicode | string |
+-------------------+---------------+
| int, long, float | number |
+-------------------+---------------+
| True | true |
+-------------------+---------------+
| False | false |
+-------------------+---------------+
| None | null |
+-------------------+---------------+
To extend this to recognize other objects, subclass and implement a
:meth:`default` method with another method that returns a serializable object
for ``o`` if possible, otherwise it should call the superclass implementation
(to raise :exc:`TypeError`).
If *skipkeys* is false (the default), then it is a :exc:`TypeError` to
attempt encoding of keys that are not str, int, long, float or ``None``. If
*skipkeys* is true, such items are simply skipped.
If *ensure_ascii* is true (the default), all non-ASCII characters in the
output are escaped with ``\uXXXX`` sequences, and the results are
:class:`str` instances consisting of ASCII characters only. If
*ensure_ascii* is false, a result may be a :class:`unicode`
instance. This usually happens if the input contains unicode strings or the
*encoding* parameter is used.
If *check_circular* is true (the default), then lists, dicts, and custom
encoded objects will be checked for circular references during encoding to
prevent an infinite recursion (which would cause an :exc:`OverflowError`).
Otherwise, no such check takes place.
If *allow_nan* is true (the default), then ``NaN``, ``Infinity``, and
``-Infinity`` will be encoded as such. This behavior is not JSON
specification compliant, but is consistent with most JavaScript based
encoders and decoders. Otherwise, it will be a :exc:`ValueError` to encode
such floats.
If *sort_keys* is true (default: ``False``), then the output of dictionaries
will be sorted by key; this is useful for regression tests to ensure that
JSON serializations can be compared on a day-to-day basis.
If *indent* is a non-negative integer (it is ``None`` by default), then JSON
array elements and object members will be pretty-printed with that indent
level. An indent level of 0 will only insert newlines. ``None`` is the most
compact representation.
.. note::
Since the default item separator is ``', '``, the output might include
trailing whitespace when *indent* is specified. You can use
``separators=(',', ': ')`` to avoid this.
If specified, *separators* should be an ``(item_separator, key_separator)``
tuple. By default, ``(', ', ': ')`` are used. To get the most compact JSON
representation, you should specify ``(',', ':')`` to eliminate whitespace.
If specified, *default* should be a function that gets called for objects that
can't otherwise be serialized. It should return a JSON encodable version of
the object or raise a :exc:`TypeError`. If not specified, :exc:`TypeError`
is raised.
If *encoding* is not ``None``, then all input strings will be transformed
into unicode using that encoding prior to JSON-encoding. The default is
UTF-8.
.. method:: default(o)
Implement this method in a subclass such that it returns a serializable
object for *o*, or calls the base implementation (to raise a
:exc:`TypeError`).
For example, to support arbitrary iterators, you could implement default
like this::
def default(self, o):
try:
iterable = iter(o)
except TypeError:
pass
else:
return list(iterable)
# Let the base class default method raise the TypeError
return JSONEncoder.default(self, o)
.. method:: encode(o)
Return a JSON string representation of a Python data structure, *o*. For
example::
>>> JSONEncoder().encode({"foo": ["bar", "baz"]})
'{"foo": ["bar", "baz"]}'
.. method:: iterencode(o)
Encode the given object, *o*, and yield each string representation as
available. For example::
for chunk in JSONEncoder().iterencode(bigobject):
mysocket.write(chunk)
Standard Compliance and Interoperability
----------------------------------------
The JSON format is specified by :rfc:`7159` and by
`ECMA-404 <http://www.ecma-international.org/publications/standards/Ecma-404.htm>`_.
This section details this module's level of compliance with the RFC.
For simplicity, :class:`JSONEncoder` and :class:`JSONDecoder` subclasses, and
parameters other than those explicitly mentioned, are not considered.
This module does not comply with the RFC in a strict fashion, implementing some
extensions that are valid JavaScript but not valid JSON. In particular:
- Infinite and NaN number values are accepted and output;
- Repeated names within an object are accepted, and only the value of the last
name-value pair is used.
Since the RFC permits RFC-compliant parsers to accept input texts that are not
RFC-compliant, this module's deserializer is technically RFC-compliant under
default settings.
Character Encodings
^^^^^^^^^^^^^^^^^^^
The RFC requires that JSON be represented using either UTF-8, UTF-16, or
UTF-32, with UTF-8 being the recommended default for maximum interoperability.
Accordingly, this module uses UTF-8 as the default for its *encoding* parameter.
This module's deserializer only directly works with ASCII-compatible encodings;
UTF-16, UTF-32, and other ASCII-incompatible encodings require the use of
workarounds described in the documentation for the deserializer's *encoding*
parameter.
As permitted, though not required, by the RFC, this module's serializer sets
*ensure_ascii=True* by default, thus escaping the output so that the resulting
strings only contain ASCII characters.
The RFC prohibits adding a byte order mark (BOM) to the start of a JSON text,
and this module's serializer does not add a BOM to its output.
The RFC permits, but does not require, JSON deserializers to ignore an initial
BOM in their input. This module's deserializer raises a :exc:`ValueError`
when an initial BOM is present.
The RFC does not explicitly forbid JSON strings which contain byte sequences
that don't correspond to valid Unicode characters (e.g. unpaired UTF-16
surrogates), but it does note that they may cause interoperability problems.
By default, this module accepts and outputs (when present in the original
:class:`str`) code points for such sequences.
Infinite and NaN Number Values
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The RFC does not permit the representation of infinite or NaN number values.
Despite that, by default, this module accepts and outputs ``Infinity``,
``-Infinity``, and ``NaN`` as if they were valid JSON number literal values::
>>> # Neither of these calls raises an exception, but the results are not valid JSON
>>> json.dumps(float('-inf'))
'-Infinity'
>>> json.dumps(float('nan'))
'NaN'
>>> # Same when deserializing
>>> json.loads('-Infinity')
-inf
>>> json.loads('NaN')
nan
In the serializer, the *allow_nan* parameter can be used to alter this
behavior. In the deserializer, the *parse_constant* parameter can be used to
alter this behavior.
Repeated Names Within an Object
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The RFC specifies that the names within a JSON object should be unique, but
does not mandate how repeated names in JSON objects should be handled. By
default, this module does not raise an exception; instead, it ignores all but
the last name-value pair for a given name::
>>> weird_json = '{"x": 1, "x": 2, "x": 3}'
>>> json.loads(weird_json)
{u'x': 3}
The *object_pairs_hook* parameter can be used to alter this behavior.
Top-level Non-Object, Non-Array Values
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The old version of JSON specified by the obsolete :rfc:`4627` required that
the top-level value of a JSON text must be either a JSON object or array
(Python :class:`dict` or :class:`list`), and could not be a JSON null,
boolean, number, or string value. :rfc:`7159` removed that restriction, and
this module does not and has never implemented that restriction in either its
serializer or its deserializer.
Regardless, for maximum interoperability, you may wish to voluntarily adhere
to the restriction yourself.
Implementation Limitations
^^^^^^^^^^^^^^^^^^^^^^^^^^
Some JSON deserializer implementations may set limits on:
* the size of accepted JSON texts
* the maximum level of nesting of JSON objects and arrays
* the range and precision of JSON numbers
* the content and maximum length of JSON strings
This module does not impose any such limits beyond those of the relevant
Python datatypes themselves or the Python interpreter itself.
When serializing to JSON, beware any such limitations in applications that may
consume your JSON. In particular, it is common for JSON numbers to be
deserialized into IEEE 754 double precision numbers and thus subject to that
representation's range and precision limitations. This is especially relevant
when serializing Python :class:`int` values of extremely large magnitude, or
when serializing instances of "exotic" numerical types such as
:class:`decimal.Decimal`.
.. rubric:: Footnotes
.. [#rfc-errata] As noted in `the errata for RFC 7159
<https://www.rfc-editor.org/errata_search.php?rfc=7159>`_,
JSON permits literal U+2028 (LINE SEPARATOR) and
U+2029 (PARAGRAPH SEPARATOR) characters in strings, whereas JavaScript
(as of ECMAScript Edition 5.1) does not.
PK %�\ϖ��i i % html/_sources/library/keyword.rst.txtnu �[��� :mod:`keyword` --- Testing for Python keywords
==============================================
.. module:: keyword
:synopsis: Test whether a string is a keyword in Python.
**Source code:** :source:`Lib/keyword.py`
--------------
This module allows a Python program to determine if a string is a keyword.
.. function:: iskeyword(s)
Return true if *s* is a Python keyword.
.. data:: kwlist
Sequence containing all the keywords defined for the interpreter. If any
keywords are defined to only be active when particular :mod:`__future__`
statements are in effect, these will be included as well.
PK %�\�A�F & html/_sources/library/language.rst.txtnu �[���
.. _language:
************************
Python Language Services
************************
Python provides a number of modules to assist in working with the Python
language. These modules support tokenizing, parsing, syntax analysis, bytecode
disassembly, and various other facilities.
These modules include:
.. toctree::
parser.rst
ast.rst
symtable.rst
symbol.rst
token.rst
keyword.rst
tokenize.rst
tabnanny.rst
pyclbr.rst
py_compile.rst
compileall.rst
dis.rst
pickletools.rst
PK %�\����_ _ ' html/_sources/library/linecache.rst.txtnu �[���
:mod:`linecache` --- Random access to text lines
================================================
.. module:: linecache
:synopsis: This module provides random access to individual lines from text files.
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
**Source code:** :source:`Lib/linecache.py`
--------------
The :mod:`linecache` module allows one to get any line from any file, while
attempting to optimize internally, using a cache, the common case where many
lines are read from a single file. This is used by the :mod:`traceback` module
to retrieve source lines for inclusion in the formatted traceback.
The :mod:`linecache` module defines the following functions:
.. function:: getline(filename, lineno[, module_globals])
Get line *lineno* from file named *filename*. This function will never raise an
exception --- it will return ``''`` on errors (the terminating newline character
will be included for lines that are found).
.. index:: triple: module; search; path
If a file named *filename* is not found, the function will look for it in the
module search path, ``sys.path``, after first checking for a :pep:`302`
``__loader__`` in *module_globals*, in case the module was imported from a
zipfile or other non-filesystem import source.
.. versionadded:: 2.5
The *module_globals* parameter was added.
.. function:: clearcache()
Clear the cache. Use this function if you no longer need lines from files
previously read using :func:`getline`.
.. function:: checkcache([filename])
Check the cache for validity. Use this function if files in the cache may have
changed on disk, and you require the updated version. If *filename* is omitted,
it will check all the entries in the cache.
Example::
>>> import linecache
>>> linecache.getline('/etc/passwd', 4)
'sys:x:3:3:sys:/dev:/bin/sh\n'
PK %�\� ���a �a $ html/_sources/library/locale.rst.txtnu �[���
:mod:`locale` --- Internationalization services
===============================================
.. module:: locale
:synopsis: Internationalization services.
.. moduleauthor:: Martin von Löwis <martin@v.loewis.de>
.. sectionauthor:: Martin von Löwis <martin@v.loewis.de>
The :mod:`locale` module opens access to the POSIX locale database and
functionality. The POSIX locale mechanism allows programmers to deal with
certain cultural issues in an application, without requiring the programmer to
know all the specifics of each country where the software is executed.
.. index:: module: _locale
The :mod:`locale` module is implemented on top of the :mod:`_locale` module,
which in turn uses an ANSI C locale implementation if available.
The :mod:`locale` module defines the following exception and functions:
.. exception:: Error
Exception raised when the locale passed to :func:`setlocale` is not
recognized.
.. function:: setlocale(category[, locale])
If *locale* is given and not ``None``, :func:`setlocale` modifies the locale
setting for the *category*. The available categories are listed in the data
description below. *locale* may be a string, or an iterable of two strings
(language code and encoding). If it's an iterable, it's converted to a locale
name using the locale aliasing engine. An empty string specifies the user's
default settings. If the modification of the locale fails, the exception
:exc:`Error` is raised. If successful, the new locale setting is returned.
If *locale* is omitted or ``None``, the current setting for *category* is
returned.
:func:`setlocale` is not thread-safe on most systems. Applications typically
start with a call of ::
import locale
locale.setlocale(locale.LC_ALL, '')
This sets the locale for all categories to the user's default setting (typically
specified in the :envvar:`LANG` environment variable). If the locale is not
changed thereafter, using multithreading should not cause problems.
.. versionchanged:: 2.0
Added support for iterable values of the *locale* parameter.
.. function:: localeconv()
Returns the database of the local conventions as a dictionary. This dictionary
has the following strings as keys:
.. tabularcolumns:: |l|l|L|
+----------------------+-------------------------------------+--------------------------------+
| Category | Key | Meaning |
+======================+=====================================+================================+
| :const:`LC_NUMERIC` | ``'decimal_point'`` | Decimal point character. |
+----------------------+-------------------------------------+--------------------------------+
| | ``'grouping'`` | Sequence of numbers specifying |
| | | which relative positions the |
| | | ``'thousands_sep'`` is |
| | | expected. If the sequence is |
| | | terminated with |
| | | :const:`CHAR_MAX`, no further |
| | | grouping is performed. If the |
| | | sequence terminates with a |
| | | ``0``, the last group size is |
| | | repeatedly used. |
+----------------------+-------------------------------------+--------------------------------+
| | ``'thousands_sep'`` | Character used between groups. |
+----------------------+-------------------------------------+--------------------------------+
| :const:`LC_MONETARY` | ``'int_curr_symbol'`` | International currency symbol. |
+----------------------+-------------------------------------+--------------------------------+
| | ``'currency_symbol'`` | Local currency symbol. |
+----------------------+-------------------------------------+--------------------------------+
| | ``'p_cs_precedes/n_cs_precedes'`` | Whether the currency symbol |
| | | precedes the value (for |
| | | positive resp. negative |
| | | values). |
+----------------------+-------------------------------------+--------------------------------+
| | ``'p_sep_by_space/n_sep_by_space'`` | Whether the currency symbol is |
| | | separated from the value by a |
| | | space (for positive resp. |
| | | negative values). |
+----------------------+-------------------------------------+--------------------------------+
| | ``'mon_decimal_point'`` | Decimal point used for |
| | | monetary values. |
+----------------------+-------------------------------------+--------------------------------+
| | ``'frac_digits'`` | Number of fractional digits |
| | | used in local formatting of |
| | | monetary values. |
+----------------------+-------------------------------------+--------------------------------+
| | ``'int_frac_digits'`` | Number of fractional digits |
| | | used in international |
| | | formatting of monetary values. |
+----------------------+-------------------------------------+--------------------------------+
| | ``'mon_thousands_sep'`` | Group separator used for |
| | | monetary values. |
+----------------------+-------------------------------------+--------------------------------+
| | ``'mon_grouping'`` | Equivalent to ``'grouping'``, |
| | | used for monetary values. |
+----------------------+-------------------------------------+--------------------------------+
| | ``'positive_sign'`` | Symbol used to annotate a |
| | | positive monetary value. |
+----------------------+-------------------------------------+--------------------------------+
| | ``'negative_sign'`` | Symbol used to annotate a |
| | | negative monetary value. |
+----------------------+-------------------------------------+--------------------------------+
| | ``'p_sign_posn/n_sign_posn'`` | The position of the sign (for |
| | | positive resp. negative |
| | | values), see below. |
+----------------------+-------------------------------------+--------------------------------+
All numeric values can be set to :const:`CHAR_MAX` to indicate that there is no
value specified in this locale.
The possible values for ``'p_sign_posn'`` and ``'n_sign_posn'`` are given below.
+--------------+-----------------------------------------+
| Value | Explanation |
+==============+=========================================+
| ``0`` | Currency and value are surrounded by |
| | parentheses. |
+--------------+-----------------------------------------+
| ``1`` | The sign should precede the value and |
| | currency symbol. |
+--------------+-----------------------------------------+
| ``2`` | The sign should follow the value and |
| | currency symbol. |
+--------------+-----------------------------------------+
| ``3`` | The sign should immediately precede the |
| | value. |
+--------------+-----------------------------------------+
| ``4`` | The sign should immediately follow the |
| | value. |
+--------------+-----------------------------------------+
| ``CHAR_MAX`` | Nothing is specified in this locale. |
+--------------+-----------------------------------------+
.. function:: nl_langinfo(option)
Return some locale-specific information as a string. This function is not
available on all systems, and the set of possible options might also vary
across platforms. The possible argument values are numbers, for which
symbolic constants are available in the locale module.
The :func:`nl_langinfo` function accepts one of the following keys. Most
descriptions are taken from the corresponding description in the GNU C
library.
.. data:: CODESET
Get a string with the name of the character encoding used in the
selected locale.
.. data:: D_T_FMT
Get a string that can be used as a format string for :func:`time.strftime` to
represent date and time in a locale-specific way.
.. data:: D_FMT
Get a string that can be used as a format string for :func:`time.strftime` to
represent a date in a locale-specific way.
.. data:: T_FMT
Get a string that can be used as a format string for :func:`time.strftime` to
represent a time in a locale-specific way.
.. data:: T_FMT_AMPM
Get a format string for :func:`time.strftime` to represent time in the am/pm
format.
.. data:: DAY_1 ... DAY_7
Get the name of the n-th day of the week.
.. note::
This follows the US convention of :const:`DAY_1` being Sunday, not the
international convention (ISO 8601) that Monday is the first day of the
week.
.. data:: ABDAY_1 ... ABDAY_7
Get the abbreviated name of the n-th day of the week.
.. data:: MON_1 ... MON_12
Get the name of the n-th month.
.. data:: ABMON_1 ... ABMON_12
Get the abbreviated name of the n-th month.
.. data:: RADIXCHAR
Get the radix character (decimal dot, decimal comma, etc.).
.. data:: THOUSEP
Get the separator character for thousands (groups of three digits).
.. data:: YESEXPR
Get a regular expression that can be used with the regex function to
recognize a positive response to a yes/no question.
.. note::
The expression is in the syntax suitable for the :c:func:`regex` function
from the C library, which might differ from the syntax used in :mod:`re`.
.. data:: NOEXPR
Get a regular expression that can be used with the regex(3) function to
recognize a negative response to a yes/no question.
.. data:: CRNCYSTR
Get the currency symbol, preceded by "-" if the symbol should appear before
the value, "+" if the symbol should appear after the value, or "." if the
symbol should replace the radix character.
.. data:: ERA
Get a string that represents the era used in the current locale.
Most locales do not define this value. An example of a locale which does
define this value is the Japanese one. In Japan, the traditional
representation of dates includes the name of the era corresponding to the
then-emperor's reign.
Normally it should not be necessary to use this value directly. Specifying
the ``E`` modifier in their format strings causes the :func:`time.strftime`
function to use this information. The format of the returned string is not
specified, and therefore you should not assume knowledge of it on different
systems.
.. data:: ERA_D_T_FMT
Get a format string for :func:`time.strftime` to represent date and time in a
locale-specific era-based way.
.. data:: ERA_D_FMT
Get a format string for :func:`time.strftime` to represent a date in a
locale-specific era-based way.
.. data:: ERA_T_FMT
Get a format string for :func:`time.strftime` to represent a time in a
locale-specific era-based way.
.. data:: ALT_DIGITS
Get a representation of up to 100 values used to represent the values
0 to 99.
.. function:: getdefaultlocale([envvars])
Tries to determine the default locale settings and returns them as a tuple of
the form ``(language code, encoding)``.
According to POSIX, a program which has not called ``setlocale(LC_ALL, '')``
runs using the portable ``'C'`` locale. Calling ``setlocale(LC_ALL, '')`` lets
it use the default locale as defined by the :envvar:`LANG` variable. Since we
do not want to interfere with the current locale setting we thus emulate the
behavior in the way described above.
To maintain compatibility with other platforms, not only the :envvar:`LANG`
variable is tested, but a list of variables given as envvars parameter. The
first found to be defined will be used. *envvars* defaults to the search path
used in GNU gettext; it must always contain the variable name ``LANG``. The GNU
gettext search path contains ``'LANGUAGE'``, ``'LC_ALL'``, ``'LC_CTYPE'``, and
``'LANG'``, in that order.
Except for the code ``'C'``, the language code corresponds to :rfc:`1766`.
*language code* and *encoding* may be ``None`` if their values cannot be
determined.
.. versionadded:: 2.0
.. function:: getlocale([category])
Returns the current setting for the given locale category as sequence containing
*language code*, *encoding*. *category* may be one of the :const:`LC_\*` values
except :const:`LC_ALL`. It defaults to :const:`LC_CTYPE`.
Except for the code ``'C'``, the language code corresponds to :rfc:`1766`.
*language code* and *encoding* may be ``None`` if their values cannot be
determined.
.. versionadded:: 2.0
.. function:: getpreferredencoding([do_setlocale])
Return the encoding used for text data, according to user preferences. User
preferences are expressed differently on different systems, and might not be
available programmatically on some systems, so this function only returns a
guess.
On some systems, it is necessary to invoke :func:`setlocale` to obtain the user
preferences, so this function is not thread-safe. If invoking setlocale is not
necessary or desired, *do_setlocale* should be set to ``False``.
.. versionadded:: 2.3
.. function:: normalize(localename)
Returns a normalized locale code for the given locale name. The returned locale
code is formatted for use with :func:`setlocale`. If normalization fails, the
original name is returned unchanged.
If the given encoding is not known, the function defaults to the default
encoding for the locale code just like :func:`setlocale`.
.. versionadded:: 2.0
.. function:: resetlocale([category])
Sets the locale for *category* to the default setting.
The default setting is determined by calling :func:`getdefaultlocale`.
*category* defaults to :const:`LC_ALL`.
.. versionadded:: 2.0
.. function:: strcoll(string1, string2)
Compares two strings according to the current :const:`LC_COLLATE` setting. As
any other compare function, returns a negative, or a positive value, or ``0``,
depending on whether *string1* collates before or after *string2* or is equal to
it.
.. function:: strxfrm(string)
.. index:: builtin: cmp
Transforms a string to one that can be used for the built-in function
:func:`cmp`, and still returns locale-aware results. This function can be used
when the same string is compared repeatedly, e.g. when collating a sequence of
strings.
.. function:: format(format, val[, grouping[, monetary]])
Formats a number *val* according to the current :const:`LC_NUMERIC` setting.
The format follows the conventions of the ``%`` operator. For floating point
values, the decimal point is modified if appropriate. If *grouping* is true,
also takes the grouping into account.
If *monetary* is true, the conversion uses monetary thousands separator and
grouping strings.
Please note that this function will only work for exactly one %char specifier.
For whole format strings, use :func:`format_string`.
.. versionchanged:: 2.5
Added the *monetary* parameter.
.. function:: format_string(format, val[, grouping])
Processes formatting specifiers as in ``format % val``, but takes the current
locale settings into account.
.. versionadded:: 2.5
.. function:: currency(val[, symbol[, grouping[, international]]])
Formats a number *val* according to the current :const:`LC_MONETARY` settings.
The returned string includes the currency symbol if *symbol* is true, which is
the default. If *grouping* is true (which is not the default), grouping is done
with the value. If *international* is true (which is not the default), the
international currency symbol is used.
Note that this function will not work with the 'C' locale, so you have to set a
locale via :func:`setlocale` first.
.. versionadded:: 2.5
.. function:: str(float)
Formats a floating point number using the same format as the built-in function
``str(float)``, but takes the decimal point into account.
.. function:: atof(string)
Converts a string to a floating point number, following the :const:`LC_NUMERIC`
settings.
.. function:: atoi(string)
Converts a string to an integer, following the :const:`LC_NUMERIC` conventions.
.. data:: LC_CTYPE
.. index:: module: string
Locale category for the character type functions. Depending on the settings of
this category, the functions of module :mod:`string` dealing with case change
their behaviour.
.. data:: LC_COLLATE
Locale category for sorting strings. The functions :func:`strcoll` and
:func:`strxfrm` of the :mod:`locale` module are affected.
.. data:: LC_TIME
Locale category for the formatting of time. The function :func:`time.strftime`
follows these conventions.
.. data:: LC_MONETARY
Locale category for formatting of monetary values. The available options are
available from the :func:`localeconv` function.
.. data:: LC_MESSAGES
Locale category for message display. Python currently does not support
application specific locale-aware messages. Messages displayed by the operating
system, like those returned by :func:`os.strerror` might be affected by this
category.
.. data:: LC_NUMERIC
Locale category for formatting numbers. The functions :func:`.format`,
:func:`atoi`, :func:`atof` and :func:`.str` of the :mod:`locale` module are
affected by that category. All other numeric formatting operations are not
affected.
.. data:: LC_ALL
Combination of all locale settings. If this flag is used when the locale is
changed, setting the locale for all categories is attempted. If that fails for
any category, no category is changed at all. When the locale is retrieved using
this flag, a string indicating the setting for all categories is returned. This
string can be later used to restore the settings.
.. data:: CHAR_MAX
This is a symbolic constant used for different values returned by
:func:`localeconv`.
Example::
>>> import locale
>>> loc = locale.getlocale() # get current locale
# use German locale; name might vary with platform
>>> locale.setlocale(locale.LC_ALL, 'de_DE')
>>> locale.strcoll('f\xe4n', 'foo') # compare a string containing an umlaut
>>> locale.setlocale(locale.LC_ALL, '') # use user's preferred locale
>>> locale.setlocale(locale.LC_ALL, 'C') # use default (C) locale
>>> locale.setlocale(locale.LC_ALL, loc) # restore saved locale
Background, details, hints, tips and caveats
--------------------------------------------
The C standard defines the locale as a program-wide property that may be
relatively expensive to change. On top of that, some implementation are broken
in such a way that frequent locale changes may cause core dumps. This makes the
locale somewhat painful to use correctly.
Initially, when a program is started, the locale is the ``C`` locale, no matter
what the user's preferred locale is. The program must explicitly say that it
wants the user's preferred locale settings by calling ``setlocale(LC_ALL, '')``.
It is generally a bad idea to call :func:`setlocale` in some library routine,
since as a side effect it affects the entire program. Saving and restoring it
is almost as bad: it is expensive and affects other threads that happen to run
before the settings have been restored.
If, when coding a module for general use, you need a locale independent version
of an operation that is affected by the locale (such as :func:`string.lower`, or
certain formats used with :func:`time.strftime`), you will have to find a way to
do it without using the standard library routine. Even better is convincing
yourself that using locale settings is okay. Only as a last resort should you
document that your module is not compatible with non-\ ``C`` locale settings.
.. index:: module: string
The case conversion functions in the :mod:`string` module are affected by the
locale settings. When a call to the :func:`setlocale` function changes the
:const:`LC_CTYPE` settings, the variables ``string.lowercase``,
``string.uppercase`` and ``string.letters`` are recalculated. Note that code
that uses these variable through ':keyword:`from` ... :keyword:`import` ...',
e.g. ``from string import letters``, is not affected by subsequent
:func:`setlocale` calls.
The only way to perform numeric operations according to the locale is to use the
special functions defined by this module: :func:`atof`, :func:`atoi`,
:func:`.format`, :func:`.str`.
.. _embedding-locale:
For extension writers and programs that embed Python
----------------------------------------------------
Extension modules should never call :func:`setlocale`, except to find out what
the current locale is. But since the return value can only be used portably to
restore it, that is not very useful (except perhaps to find out whether or not
the locale is ``C``).
When Python code uses the :mod:`locale` module to change the locale, this also
affects the embedding application. If the embedding application doesn't want
this to happen, it should remove the :mod:`_locale` extension module (which does
all the work) from the table of built-in modules in the :file:`config.c` file,
and make sure that the :mod:`_locale` module is not accessible as a shared
library.
.. _locale-gettext:
Access to message catalogs
--------------------------
.. function:: gettext(msg)
.. function:: dgettext(domain, msg)
.. function:: dcgettext(domain, msg, category)
.. function:: textdomain(domain)
.. function:: bindtextdomain(domain, dir)
The locale module exposes the C library's gettext interface on systems that
provide this interface. It consists of the functions :func:`!gettext`,
:func:`!dgettext`, :func:`!dcgettext`, :func:`!textdomain`, :func:`!bindtextdomain`,
and :func:`!bind_textdomain_codeset`. These are similar to the same functions in
the :mod:`gettext` module, but use the C library's binary format for message
catalogs, and the C library's search algorithms for locating message catalogs.
Python applications should normally find no need to invoke these functions, and
should use :mod:`gettext` instead. A known exception to this rule are
applications that link with additional C libraries which internally invoke
:c:func:`gettext` or :c:func:`dcgettext`. For these applications, it may be
necessary to bind the text domain, so that the libraries can properly locate
their message catalogs.
PK %�\P��H{ H{ , html/_sources/library/logging.config.rst.txtnu �[��� :mod:`logging.config` --- Logging configuration
===============================================
.. module:: logging.config
:synopsis: Configuration of the logging module.
.. moduleauthor:: Vinay Sajip <vinay_sajip@red-dove.com>
.. sectionauthor:: Vinay Sajip <vinay_sajip@red-dove.com>
.. sidebar:: Important
This page contains only reference information. For tutorials,
please see
* :ref:`Basic Tutorial <logging-basic-tutorial>`
* :ref:`Advanced Tutorial <logging-advanced-tutorial>`
* :ref:`Logging Cookbook <logging-cookbook>`
**Source code:** :source:`Lib/logging/config.py`
--------------
This section describes the API for configuring the logging module.
.. _logging-config-api:
Configuration functions
^^^^^^^^^^^^^^^^^^^^^^^
The following functions configure the logging module. They are located in the
:mod:`logging.config` module. Their use is optional --- you can configure the
logging module using these functions or by making calls to the main API (defined
in :mod:`logging` itself) and defining handlers which are declared either in
:mod:`logging` or :mod:`logging.handlers`.
.. function:: dictConfig(config)
Takes the logging configuration from a dictionary. The contents of
this dictionary are described in :ref:`logging-config-dictschema`
below.
If an error is encountered during configuration, this function will
raise a :exc:`ValueError`, :exc:`TypeError`, :exc:`AttributeError`
or :exc:`ImportError` with a suitably descriptive message. The
following is a (possibly incomplete) list of conditions which will
raise an error:
* A ``level`` which is not a string or which is a string not
corresponding to an actual logging level.
* A ``propagate`` value which is not a boolean.
* An id which does not have a corresponding destination.
* A non-existent handler id found during an incremental call.
* An invalid logger name.
* Inability to resolve to an internal or external object.
Parsing is performed by the :class:`DictConfigurator` class, whose
constructor is passed the dictionary used for configuration, and
has a :meth:`configure` method. The :mod:`logging.config` module
has a callable attribute :attr:`dictConfigClass`
which is initially set to :class:`DictConfigurator`.
You can replace the value of :attr:`dictConfigClass` with a
suitable implementation of your own.
:func:`dictConfig` calls :attr:`dictConfigClass` passing
the specified dictionary, and then calls the :meth:`configure` method on
the returned object to put the configuration into effect::
def dictConfig(config):
dictConfigClass(config).configure()
For example, a subclass of :class:`DictConfigurator` could call
``DictConfigurator.__init__()`` in its own :meth:`__init__()`, then
set up custom prefixes which would be usable in the subsequent
:meth:`configure` call. :attr:`dictConfigClass` would be bound to
this new subclass, and then :func:`dictConfig` could be called exactly as
in the default, uncustomized state.
.. versionadded:: 2.7
.. function:: fileConfig(fname, defaults=None, disable_existing_loggers=True)
Reads the logging configuration from a :mod:`configparser`\-format file
named *fname*. The format of the file should be as described in
:ref:`logging-config-fileformat`. This function can be called several times
from an application, allowing an end user to select from various pre-canned
configurations (if the developer provides a mechanism to present the choices
and load the chosen configuration).
:param defaults: Defaults to be passed to the ConfigParser can be specified
in this argument.
:param disable_existing_loggers: If specified as ``False``, loggers which
exist when this call is made are left
enabled. The default is ``True`` because this
enables old behaviour in a
backward-compatible way. This behaviour is to
disable any existing loggers unless they or
their ancestors are explicitly named in the
logging configuration.
.. versionchanged:: 2.6
The ``disable_existing_loggers`` keyword argument was added. Previously,
existing loggers were *always* disabled.
.. function:: listen(port=DEFAULT_LOGGING_CONFIG_PORT)
Starts up a socket server on the specified port, and listens for new
configurations. If no port is specified, the module's default
:const:`DEFAULT_LOGGING_CONFIG_PORT` is used. Logging configurations will be
sent as a file suitable for processing by :func:`fileConfig`. Returns a
:class:`~threading.Thread` instance on which you can call
:meth:`~threading.Thread.start` to start the server, and which you can
:meth:`~threading.Thread.join` when appropriate. To stop the server,
call :func:`stopListening`.
To send a configuration to the socket, read in the configuration file and
send it to the socket as a string of bytes preceded by a four-byte length
string packed in binary using ``struct.pack('>L', n)``.
.. note::
Because portions of the configuration are passed through
:func:`eval`, use of this function may open its users to a security risk.
While the function only binds to a socket on ``localhost``, and so does
not accept connections from remote machines, there are scenarios where
untrusted code could be run under the account of the process which calls
:func:`listen`. Specifically, if the process calling :func:`listen` runs
on a multi-user machine where users cannot trust each other, then a
malicious user could arrange to run essentially arbitrary code in a
victim user's process, simply by connecting to the victim's
:func:`listen` socket and sending a configuration which runs whatever
code the attacker wants to have executed in the victim's process. This is
especially easy to do if the default port is used, but not hard even if a
different port is used).
.. function:: stopListening()
Stops the listening server which was created with a call to :func:`listen`.
This is typically called before calling :meth:`join` on the return value from
:func:`listen`.
.. _logging-config-dictschema:
Configuration dictionary schema
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Describing a logging configuration requires listing the various
objects to create and the connections between them; for example, you
may create a handler named 'console' and then say that the logger
named 'startup' will send its messages to the 'console' handler.
These objects aren't limited to those provided by the :mod:`logging`
module because you might write your own formatter or handler class.
The parameters to these classes may also need to include external
objects such as ``sys.stderr``. The syntax for describing these
objects and connections is defined in :ref:`logging-config-dict-connections`
below.
Dictionary Schema Details
"""""""""""""""""""""""""
The dictionary passed to :func:`dictConfig` must contain the following
keys:
* *version* - to be set to an integer value representing the schema
version. The only valid value at present is 1, but having this key
allows the schema to evolve while still preserving backwards
compatibility.
All other keys are optional, but if present they will be interpreted
as described below. In all cases below where a 'configuring dict' is
mentioned, it will be checked for the special ``'()'`` key to see if a
custom instantiation is required. If so, the mechanism described in
:ref:`logging-config-dict-userdef` below is used to create an instance;
otherwise, the context is used to determine what to instantiate.
* *formatters* - the corresponding value will be a dict in which each
key is a formatter id and each value is a dict describing how to
configure the corresponding :class:`~logging.Formatter` instance.
The configuring dict is searched for keys ``format`` and ``datefmt``
(with defaults of ``None``) and these are used to construct a
:class:`~logging.Formatter` instance.
* *filters* - the corresponding value will be a dict in which each key
is a filter id and each value is a dict describing how to configure
the corresponding Filter instance.
The configuring dict is searched for the key ``name`` (defaulting to the
empty string) and this is used to construct a :class:`logging.Filter`
instance.
* *handlers* - the corresponding value will be a dict in which each
key is a handler id and each value is a dict describing how to
configure the corresponding Handler instance.
The configuring dict is searched for the following keys:
* ``class`` (mandatory). This is the fully qualified name of the
handler class.
* ``level`` (optional). The level of the handler.
* ``formatter`` (optional). The id of the formatter for this
handler.
* ``filters`` (optional). A list of ids of the filters for this
handler.
All *other* keys are passed through as keyword arguments to the
handler's constructor. For example, given the snippet:
.. code-block:: yaml
handlers:
console:
class : logging.StreamHandler
formatter: brief
level : INFO
filters: [allow_foo]
stream : ext://sys.stdout
file:
class : logging.handlers.RotatingFileHandler
formatter: precise
filename: logconfig.log
maxBytes: 1024
backupCount: 3
the handler with id ``console`` is instantiated as a
:class:`logging.StreamHandler`, using ``sys.stdout`` as the underlying
stream. The handler with id ``file`` is instantiated as a
:class:`logging.handlers.RotatingFileHandler` with the keyword arguments
``filename='logconfig.log', maxBytes=1024, backupCount=3``.
* *loggers* - the corresponding value will be a dict in which each key
is a logger name and each value is a dict describing how to
configure the corresponding Logger instance.
The configuring dict is searched for the following keys:
* ``level`` (optional). The level of the logger.
* ``propagate`` (optional). The propagation setting of the logger.
* ``filters`` (optional). A list of ids of the filters for this
logger.
* ``handlers`` (optional). A list of ids of the handlers for this
logger.
The specified loggers will be configured according to the level,
propagation, filters and handlers specified.
* *root* - this will be the configuration for the root logger.
Processing of the configuration will be as for any logger, except
that the ``propagate`` setting will not be applicable.
* *incremental* - whether the configuration is to be interpreted as
incremental to the existing configuration. This value defaults to
``False``, which means that the specified configuration replaces the
existing configuration with the same semantics as used by the
existing :func:`fileConfig` API.
If the specified value is ``True``, the configuration is processed
as described in the section on :ref:`logging-config-dict-incremental`.
* *disable_existing_loggers* - whether any existing loggers are to be
disabled. This setting mirrors the parameter of the same name in
:func:`fileConfig`. If absent, this parameter defaults to ``True``.
This value is ignored if *incremental* is ``True``.
.. _logging-config-dict-incremental:
Incremental Configuration
"""""""""""""""""""""""""
It is difficult to provide complete flexibility for incremental
configuration. For example, because objects such as filters
and formatters are anonymous, once a configuration is set up, it is
not possible to refer to such anonymous objects when augmenting a
configuration.
Furthermore, there is not a compelling case for arbitrarily altering
the object graph of loggers, handlers, filters, formatters at
run-time, once a configuration is set up; the verbosity of loggers and
handlers can be controlled just by setting levels (and, in the case of
loggers, propagation flags). Changing the object graph arbitrarily in
a safe way is problematic in a multi-threaded environment; while not
impossible, the benefits are not worth the complexity it adds to the
implementation.
Thus, when the ``incremental`` key of a configuration dict is present
and is ``True``, the system will completely ignore any ``formatters`` and
``filters`` entries, and process only the ``level``
settings in the ``handlers`` entries, and the ``level`` and
``propagate`` settings in the ``loggers`` and ``root`` entries.
Using a value in the configuration dict lets configurations to be sent
over the wire as pickled dicts to a socket listener. Thus, the logging
verbosity of a long-running application can be altered over time with
no need to stop and restart the application.
.. _logging-config-dict-connections:
Object connections
""""""""""""""""""
The schema describes a set of logging objects - loggers,
handlers, formatters, filters - which are connected to each other in
an object graph. Thus, the schema needs to represent connections
between the objects. For example, say that, once configured, a
particular logger has attached to it a particular handler. For the
purposes of this discussion, we can say that the logger represents the
source, and the handler the destination, of a connection between the
two. Of course in the configured objects this is represented by the
logger holding a reference to the handler. In the configuration dict,
this is done by giving each destination object an id which identifies
it unambiguously, and then using the id in the source object's
configuration to indicate that a connection exists between the source
and the destination object with that id.
So, for example, consider the following YAML snippet:
.. code-block:: yaml
formatters:
brief:
# configuration for formatter with id 'brief' goes here
precise:
# configuration for formatter with id 'precise' goes here
handlers:
h1: #This is an id
# configuration of handler with id 'h1' goes here
formatter: brief
h2: #This is another id
# configuration of handler with id 'h2' goes here
formatter: precise
loggers:
foo.bar.baz:
# other configuration for logger 'foo.bar.baz'
handlers: [h1, h2]
(Note: YAML used here because it's a little more readable than the
equivalent Python source form for the dictionary.)
The ids for loggers are the logger names which would be used
programmatically to obtain a reference to those loggers, e.g.
``foo.bar.baz``. The ids for Formatters and Filters can be any string
value (such as ``brief``, ``precise`` above) and they are transient,
in that they are only meaningful for processing the configuration
dictionary and used to determine connections between objects, and are
not persisted anywhere when the configuration call is complete.
The above snippet indicates that logger named ``foo.bar.baz`` should
have two handlers attached to it, which are described by the handler
ids ``h1`` and ``h2``. The formatter for ``h1`` is that described by id
``brief``, and the formatter for ``h2`` is that described by id
``precise``.
.. _logging-config-dict-userdef:
User-defined objects
""""""""""""""""""""
The schema supports user-defined objects for handlers, filters and
formatters. (Loggers do not need to have different types for
different instances, so there is no support in this configuration
schema for user-defined logger classes.)
Objects to be configured are described by dictionaries
which detail their configuration. In some places, the logging system
will be able to infer from the context how an object is to be
instantiated, but when a user-defined object is to be instantiated,
the system will not know how to do this. In order to provide complete
flexibility for user-defined object instantiation, the user needs
to provide a 'factory' - a callable which is called with a
configuration dictionary and which returns the instantiated object.
This is signalled by an absolute import path to the factory being
made available under the special key ``'()'``. Here's a concrete
example:
.. code-block:: yaml
formatters:
brief:
format: '%(message)s'
default:
format: '%(asctime)s %(levelname)-8s %(name)-15s %(message)s'
datefmt: '%Y-%m-%d %H:%M:%S'
custom:
(): my.package.customFormatterFactory
bar: baz
spam: 99.9
answer: 42
The above YAML snippet defines three formatters. The first, with id
``brief``, is a standard :class:`logging.Formatter` instance with the
specified format string. The second, with id ``default``, has a
longer format and also defines the time format explicitly, and will
result in a :class:`logging.Formatter` initialized with those two format
strings. Shown in Python source form, the ``brief`` and ``default``
formatters have configuration sub-dictionaries::
{
'format' : '%(message)s'
}
and::
{
'format' : '%(asctime)s %(levelname)-8s %(name)-15s %(message)s',
'datefmt' : '%Y-%m-%d %H:%M:%S'
}
respectively, and as these dictionaries do not contain the special key
``'()'``, the instantiation is inferred from the context: as a result,
standard :class:`logging.Formatter` instances are created. The
configuration sub-dictionary for the third formatter, with id
``custom``, is::
{
'()' : 'my.package.customFormatterFactory',
'bar' : 'baz',
'spam' : 99.9,
'answer' : 42
}
and this contains the special key ``'()'``, which means that
user-defined instantiation is wanted. In this case, the specified
factory callable will be used. If it is an actual callable it will be
used directly - otherwise, if you specify a string (as in the example)
the actual callable will be located using normal import mechanisms.
The callable will be called with the **remaining** items in the
configuration sub-dictionary as keyword arguments. In the above
example, the formatter with id ``custom`` will be assumed to be
returned by the call::
my.package.customFormatterFactory(bar='baz', spam=99.9, answer=42)
The key ``'()'`` has been used as the special key because it is not a
valid keyword parameter name, and so will not clash with the names of
the keyword arguments used in the call. The ``'()'`` also serves as a
mnemonic that the corresponding value is a callable.
.. _logging-config-dict-externalobj:
Access to external objects
""""""""""""""""""""""""""
There are times where a configuration needs to refer to objects
external to the configuration, for example ``sys.stderr``. If the
configuration dict is constructed using Python code, this is
straightforward, but a problem arises when the configuration is
provided via a text file (e.g. JSON, YAML). In a text file, there is
no standard way to distinguish ``sys.stderr`` from the literal string
``'sys.stderr'``. To facilitate this distinction, the configuration
system looks for certain special prefixes in string values and
treat them specially. For example, if the literal string
``'ext://sys.stderr'`` is provided as a value in the configuration,
then the ``ext://`` will be stripped off and the remainder of the
value processed using normal import mechanisms.
The handling of such prefixes is done in a way analogous to protocol
handling: there is a generic mechanism to look for prefixes which
match the regular expression ``^(?P<prefix>[a-z]+)://(?P<suffix>.*)$``
whereby, if the ``prefix`` is recognised, the ``suffix`` is processed
in a prefix-dependent manner and the result of the processing replaces
the string value. If the prefix is not recognised, then the string
value will be left as-is.
.. _logging-config-dict-internalobj:
Access to internal objects
""""""""""""""""""""""""""
As well as external objects, there is sometimes also a need to refer
to objects in the configuration. This will be done implicitly by the
configuration system for things that it knows about. For example, the
string value ``'DEBUG'`` for a ``level`` in a logger or handler will
automatically be converted to the value ``logging.DEBUG``, and the
``handlers``, ``filters`` and ``formatter`` entries will take an
object id and resolve to the appropriate destination object.
However, a more generic mechanism is needed for user-defined
objects which are not known to the :mod:`logging` module. For
example, consider :class:`logging.handlers.MemoryHandler`, which takes
a ``target`` argument which is another handler to delegate to. Since
the system already knows about this class, then in the configuration,
the given ``target`` just needs to be the object id of the relevant
target handler, and the system will resolve to the handler from the
id. If, however, a user defines a ``my.package.MyHandler`` which has
an ``alternate`` handler, the configuration system would not know that
the ``alternate`` referred to a handler. To cater for this, a generic
resolution system allows the user to specify::
handlers:
file:
# configuration of file handler goes here
custom:
(): my.package.MyHandler
alternate: cfg://handlers.file
The literal string ``'cfg://handlers.file'`` will be resolved in an
analogous way to strings with the ``ext://`` prefix, but looking
in the configuration itself rather than the import namespace. The
mechanism allows access by dot or by index, in a similar way to
that provided by ``str.format``. Thus, given the following snippet::
handlers:
email:
class: logging.handlers.SMTPHandler
mailhost: localhost
fromaddr: my_app@domain.tld
toaddrs:
- support_team@domain.tld
- dev_team@domain.tld
subject: Houston, we have a problem.
in the configuration, the string ``'cfg://handlers'`` would resolve to
the dict with key ``handlers``, the string ``'cfg://handlers.email``
would resolve to the dict with key ``email`` in the ``handlers`` dict,
and so on. The string ``'cfg://handlers.email.toaddrs[1]`` would
resolve to ``'dev_team.domain.tld'`` and the string
``'cfg://handlers.email.toaddrs[0]'`` would resolve to the value
``'support_team@domain.tld'``. The ``subject`` value could be accessed
using either ``'cfg://handlers.email.subject'`` or, equivalently,
``'cfg://handlers.email[subject]'``. The latter form only needs to be
used if the key contains spaces or non-alphanumeric characters. If an
index value consists only of decimal digits, access will be attempted
using the corresponding integer value, falling back to the string
value if needed.
Given a string ``cfg://handlers.myhandler.mykey.123``, this will
resolve to ``config_dict['handlers']['myhandler']['mykey']['123']``.
If the string is specified as ``cfg://handlers.myhandler.mykey[123]``,
the system will attempt to retrieve the value from
``config_dict['handlers']['myhandler']['mykey'][123]``, and fall back
to ``config_dict['handlers']['myhandler']['mykey']['123']`` if that
fails.
.. _logging-import-resolution:
Import resolution and custom importers
""""""""""""""""""""""""""""""""""""""
Import resolution, by default, uses the builtin :func:`__import__` function
to do its importing. You may want to replace this with your own importing
mechanism: if so, you can replace the :attr:`importer` attribute of the
:class:`DictConfigurator` or its superclass, the
:class:`BaseConfigurator` class. However, you need to be
careful because of the way functions are accessed from classes via
descriptors. If you are using a Python callable to do your imports, and you
want to define it at class level rather than instance level, you need to wrap
it with :func:`staticmethod`. For example::
from importlib import import_module
from logging.config import BaseConfigurator
BaseConfigurator.importer = staticmethod(import_module)
You don't need to wrap with :func:`staticmethod` if you're setting the import
callable on a configurator *instance*.
.. _logging-config-fileformat:
Configuration file format
^^^^^^^^^^^^^^^^^^^^^^^^^
The configuration file format understood by :func:`fileConfig` is based on
:mod:`configparser` functionality. The file must contain sections called
``[loggers]``, ``[handlers]`` and ``[formatters]`` which identify by name the
entities of each type which are defined in the file. For each such entity, there
is a separate section which identifies how that entity is configured. Thus, for
a logger named ``log01`` in the ``[loggers]`` section, the relevant
configuration details are held in a section ``[logger_log01]``. Similarly, a
handler called ``hand01`` in the ``[handlers]`` section will have its
configuration held in a section called ``[handler_hand01]``, while a formatter
called ``form01`` in the ``[formatters]`` section will have its configuration
specified in a section called ``[formatter_form01]``. The root logger
configuration must be specified in a section called ``[logger_root]``.
.. note::
The :func:`fileConfig` API is older than the :func:`dictConfig` API and does
not provide functionality to cover certain aspects of logging. For example,
you cannot configure :class:`~logging.Filter` objects, which provide for
filtering of messages beyond simple integer levels, using :func:`fileConfig`.
If you need to have instances of :class:`~logging.Filter` in your logging
configuration, you will need to use :func:`dictConfig`. Note that future
enhancements to configuration functionality will be added to
:func:`dictConfig`, so it's worth considering transitioning to this newer
API when it's convenient to do so.
Examples of these sections in the file are given below.
.. code-block:: ini
[loggers]
keys=root,log02,log03,log04,log05,log06,log07
[handlers]
keys=hand01,hand02,hand03,hand04,hand05,hand06,hand07,hand08,hand09
[formatters]
keys=form01,form02,form03,form04,form05,form06,form07,form08,form09
The root logger must specify a level and a list of handlers. An example of a
root logger section is given below.
.. code-block:: ini
[logger_root]
level=NOTSET
handlers=hand01
The ``level`` entry can be one of ``DEBUG, INFO, WARNING, ERROR, CRITICAL`` or
``NOTSET``. For the root logger only, ``NOTSET`` means that all messages will be
logged. Level values are :func:`eval`\ uated in the context of the ``logging``
package's namespace.
The ``handlers`` entry is a comma-separated list of handler names, which must
appear in the ``[handlers]`` section. These names must appear in the
``[handlers]`` section and have corresponding sections in the configuration
file.
For loggers other than the root logger, some additional information is required.
This is illustrated by the following example.
.. code-block:: ini
[logger_parser]
level=DEBUG
handlers=hand01
propagate=1
qualname=compiler.parser
The ``level`` and ``handlers`` entries are interpreted as for the root logger,
except that if a non-root logger's level is specified as ``NOTSET``, the system
consults loggers higher up the hierarchy to determine the effective level of the
logger. The ``propagate`` entry is set to 1 to indicate that messages must
propagate to handlers higher up the logger hierarchy from this logger, or 0 to
indicate that messages are **not** propagated to handlers up the hierarchy. The
``qualname`` entry is the hierarchical channel name of the logger, that is to
say the name used by the application to get the logger.
Sections which specify handler configuration are exemplified by the following.
.. code-block:: ini
[handler_hand01]
class=StreamHandler
level=NOTSET
formatter=form01
args=(sys.stdout,)
The ``class`` entry indicates the handler's class (as determined by :func:`eval`
in the ``logging`` package's namespace). The ``level`` is interpreted as for
loggers, and ``NOTSET`` is taken to mean 'log everything'.
.. versionchanged:: 2.6
Added support for resolving the handler’s class as a dotted module and
class name.
The ``formatter`` entry indicates the key name of the formatter for this
handler. If blank, a default formatter (``logging._defaultFormatter``) is used.
If a name is specified, it must appear in the ``[formatters]`` section and have
a corresponding section in the configuration file.
The ``args`` entry, when :func:`eval`\ uated in the context of the ``logging``
package's namespace, is the list of arguments to the constructor for the handler
class. Refer to the constructors for the relevant handlers, or to the examples
below, to see how typical entries are constructed.
.. code-block:: ini
[handler_hand02]
class=FileHandler
level=DEBUG
formatter=form02
args=('python.log', 'w')
[handler_hand03]
class=handlers.SocketHandler
level=INFO
formatter=form03
args=('localhost', handlers.DEFAULT_TCP_LOGGING_PORT)
[handler_hand04]
class=handlers.DatagramHandler
level=WARN
formatter=form04
args=('localhost', handlers.DEFAULT_UDP_LOGGING_PORT)
[handler_hand05]
class=handlers.SysLogHandler
level=ERROR
formatter=form05
args=(('localhost', handlers.SYSLOG_UDP_PORT), handlers.SysLogHandler.LOG_USER)
[handler_hand06]
class=handlers.NTEventLogHandler
level=CRITICAL
formatter=form06
args=('Python Application', '', 'Application')
[handler_hand07]
class=handlers.SMTPHandler
level=WARN
formatter=form07
args=('localhost', 'from@abc', ['user1@abc', 'user2@xyz'], 'Logger Subject')
[handler_hand08]
class=handlers.MemoryHandler
level=NOTSET
formatter=form08
target=
args=(10, ERROR)
[handler_hand09]
class=handlers.HTTPHandler
level=NOTSET
formatter=form09
args=('localhost:9022', '/log', 'GET')
Sections which specify formatter configuration are typified by the following.
.. code-block:: ini
[formatter_form01]
format=F1 %(asctime)s %(levelname)s %(message)s
datefmt=
class=logging.Formatter
The ``format`` entry is the overall format string, and the ``datefmt`` entry is
the :func:`strftime`\ -compatible date/time format string. If empty, the
package substitutes ISO8601 format date/times, which is almost equivalent to
specifying the date format string ``'%Y-%m-%d %H:%M:%S'``. The ISO8601 format
also specifies milliseconds, which are appended to the result of using the above
format string, with a comma separator. An example time in ISO8601 format is
``2003-01-23 00:29:50,411``.
The ``class`` entry is optional. It indicates the name of the formatter's class
(as a dotted module and class name.) This option is useful for instantiating a
:class:`~logging.Formatter` subclass. Subclasses of
:class:`~logging.Formatter` can present exception tracebacks in an expanded or
condensed format.
.. note::
Due to the use of :func:`eval` as described above, there are
potential security risks which result from using the :func:`listen` to send
and receive configurations via sockets. The risks are limited to where
multiple users with no mutual trust run code on the same machine; see the
:func:`listen` documentation for more information.
.. seealso::
Module :mod:`logging`
API reference for the logging module.
Module :mod:`logging.handlers`
Useful handlers included with the logging module.
PK %�\�O�9�m �m . html/_sources/library/logging.handlers.rst.txtnu �[��� :mod:`logging.handlers` --- Logging handlers
============================================
.. module:: logging.handlers
:synopsis: Handlers for the logging module.
.. moduleauthor:: Vinay Sajip <vinay_sajip@red-dove.com>
.. sectionauthor:: Vinay Sajip <vinay_sajip@red-dove.com>
.. sidebar:: Important
This page contains only reference information. For tutorials,
please see
* :ref:`Basic Tutorial <logging-basic-tutorial>`
* :ref:`Advanced Tutorial <logging-advanced-tutorial>`
* :ref:`Logging Cookbook <logging-cookbook>`
**Source code:** :source:`Lib/logging/handlers.py`
--------------
.. currentmodule:: logging
The following useful handlers are provided in the package. Note that three of
the handlers (:class:`StreamHandler`, :class:`FileHandler` and
:class:`NullHandler`) are actually defined in the :mod:`logging` module itself,
but have been documented here along with the other handlers.
.. _stream-handler:
StreamHandler
^^^^^^^^^^^^^
The :class:`StreamHandler` class, located in the core :mod:`logging` package,
sends logging output to streams such as *sys.stdout*, *sys.stderr* or any
file-like object (or, more precisely, any object which supports :meth:`write`
and :meth:`flush` methods).
.. class:: StreamHandler(stream=None)
Returns a new instance of the :class:`StreamHandler` class. If *stream* is
specified, the instance will use it for logging output; otherwise, *sys.stderr*
will be used.
.. method:: emit(record)
If a formatter is specified, it is used to format the record. The record
is then written to the stream with a newline terminator. If exception
information is present, it is formatted using
:func:`traceback.print_exception` and appended to the stream.
.. method:: flush()
Flushes the stream by calling its :meth:`flush` method. Note that the
:meth:`close` method is inherited from :class:`~logging.Handler` and so
does no output, so an explicit :meth:`flush` call may be needed at times.
.. _file-handler:
FileHandler
^^^^^^^^^^^
The :class:`FileHandler` class, located in the core :mod:`logging` package,
sends logging output to a disk file. It inherits the output functionality from
:class:`StreamHandler`.
.. class:: FileHandler(filename, mode='a', encoding=None, delay=False)
Returns a new instance of the :class:`FileHandler` class. The specified file is
opened and used as the stream for logging. If *mode* is not specified,
:const:`'a'` is used. If *encoding* is not ``None``, it is used to open the file
with that encoding. If *delay* is true, then file opening is deferred until the
first call to :meth:`emit`. By default, the file grows indefinitely.
.. versionchanged:: 2.6
*delay* was added.
.. method:: close()
Closes the file.
.. method:: emit(record)
Outputs the record to the file.
.. _null-handler:
NullHandler
^^^^^^^^^^^
.. versionadded:: 2.7
The :class:`NullHandler` class, located in the core :mod:`logging` package,
does not do any formatting or output. It is essentially a 'no-op' handler
for use by library developers.
.. class:: NullHandler()
Returns a new instance of the :class:`NullHandler` class.
.. method:: emit(record)
This method does nothing.
.. method:: handle(record)
This method does nothing.
.. method:: createLock()
This method returns ``None`` for the lock, since there is no
underlying I/O to which access needs to be serialized.
See :ref:`library-config` for more information on how to use
:class:`NullHandler`.
.. _watched-file-handler:
WatchedFileHandler
^^^^^^^^^^^^^^^^^^
.. currentmodule:: logging.handlers
.. versionadded:: 2.6
The :class:`WatchedFileHandler` class, located in the :mod:`logging.handlers`
module, is a :class:`FileHandler` which watches the file it is logging to. If
the file changes, it is closed and reopened using the file name.
A file change can happen because of usage of programs such as *newsyslog* and
*logrotate* which perform log file rotation. This handler, intended for use
under Unix/Linux, watches the file to see if it has changed since the last emit.
(A file is deemed to have changed if its device or inode have changed.) If the
file has changed, the old file stream is closed, and the file opened to get a
new stream.
This handler is not appropriate for use under Windows, because under Windows
open log files cannot be moved or renamed - logging opens the files with
exclusive locks - and so there is no need for such a handler. Furthermore,
*ST_INO* is not supported under Windows; :func:`~os.stat` always returns zero
for this value.
.. class:: WatchedFileHandler(filename[,mode[, encoding[, delay]]])
Returns a new instance of the :class:`WatchedFileHandler` class. The specified
file is opened and used as the stream for logging. If *mode* is not specified,
:const:`'a'` is used. If *encoding* is not ``None``, it is used to open the file
with that encoding. If *delay* is true, then file opening is deferred until the
first call to :meth:`emit`. By default, the file grows indefinitely.
.. method:: emit(record)
Outputs the record to the file, but first checks to see if the file has
changed. If it has, the existing stream is flushed and closed and the
file opened again, before outputting the record to the file.
.. _rotating-file-handler:
RotatingFileHandler
^^^^^^^^^^^^^^^^^^^
The :class:`RotatingFileHandler` class, located in the :mod:`logging.handlers`
module, supports rotation of disk log files.
.. class:: RotatingFileHandler(filename, mode='a', maxBytes=0, backupCount=0, encoding=None, delay=0)
Returns a new instance of the :class:`RotatingFileHandler` class. The specified
file is opened and used as the stream for logging. If *mode* is not specified,
``'a'`` is used. If *encoding* is not ``None``, it is used to open the file
with that encoding. If *delay* is true, then file opening is deferred until the
first call to :meth:`emit`. By default, the file grows indefinitely.
You can use the *maxBytes* and *backupCount* values to allow the file to
:dfn:`rollover` at a predetermined size. When the size is about to be exceeded,
the file is closed and a new file is silently opened for output. Rollover occurs
whenever the current log file is nearly *maxBytes* in length; if either of
*maxBytes* or *backupCount* is zero, rollover never occurs. If *backupCount*
is non-zero, the system will save old log files by appending the extensions
'.1', '.2' etc., to the filename. For example, with a *backupCount* of 5 and
a base file name of :file:`app.log`, you would get :file:`app.log`,
:file:`app.log.1`, :file:`app.log.2`, up to :file:`app.log.5`. The file being
written to is always :file:`app.log`. When this file is filled, it is closed
and renamed to :file:`app.log.1`, and if files :file:`app.log.1`,
:file:`app.log.2`, etc. exist, then they are renamed to :file:`app.log.2`,
:file:`app.log.3` etc. respectively.
.. versionchanged:: 2.6
*delay* was added.
.. method:: doRollover()
Does a rollover, as described above.
.. method:: emit(record)
Outputs the record to the file, catering for rollover as described
previously.
.. _timed-rotating-file-handler:
TimedRotatingFileHandler
^^^^^^^^^^^^^^^^^^^^^^^^
The :class:`TimedRotatingFileHandler` class, located in the
:mod:`logging.handlers` module, supports rotation of disk log files at certain
timed intervals.
.. class:: TimedRotatingFileHandler(filename, when='h', interval=1, backupCount=0, encoding=None, delay=False, utc=False)
Returns a new instance of the :class:`TimedRotatingFileHandler` class. The
specified file is opened and used as the stream for logging. On rotating it also
sets the filename suffix. Rotating happens based on the product of *when* and
*interval*.
You can use the *when* to specify the type of *interval*. The list of possible
values is below. Note that they are not case sensitive.
+----------------+-----------------------+
| Value | Type of interval |
+================+=======================+
| ``'S'`` | Seconds |
+----------------+-----------------------+
| ``'M'`` | Minutes |
+----------------+-----------------------+
| ``'H'`` | Hours |
+----------------+-----------------------+
| ``'D'`` | Days |
+----------------+-----------------------+
| ``'W0'-'W6'`` | Weekday (0=Monday) |
+----------------+-----------------------+
| ``'midnight'`` | Roll over at midnight |
+----------------+-----------------------+
When using weekday-based rotation, specify 'W0' for Monday, 'W1' for
Tuesday, and so on up to 'W6' for Sunday. In this case, the value passed for
*interval* isn't used.
The system will save old log files by appending extensions to the filename.
The extensions are date-and-time based, using the strftime format
``%Y-%m-%d_%H-%M-%S`` or a leading portion thereof, depending on the
rollover interval.
When computing the next rollover time for the first time (when the handler
is created), the last modification time of an existing log file, or else
the current time, is used to compute when the next rotation will occur.
If the *utc* argument is true, times in UTC will be used; otherwise
local time is used.
If *backupCount* is nonzero, at most *backupCount* files
will be kept, and if more would be created when rollover occurs, the oldest
one is deleted. The deletion logic uses the interval to determine which
files to delete, so changing the interval may leave old files lying around.
If *delay* is true, then file opening is deferred until the first call to
:meth:`emit`.
.. versionchanged:: 2.6
*delay* and *utc* were added.
.. method:: doRollover()
Does a rollover, as described above.
.. method:: emit(record)
Outputs the record to the file, catering for rollover as described above.
.. _socket-handler:
SocketHandler
^^^^^^^^^^^^^
The :class:`SocketHandler` class, located in the :mod:`logging.handlers` module,
sends logging output to a network socket. The base class uses a TCP socket.
.. class:: SocketHandler(host, port)
Returns a new instance of the :class:`SocketHandler` class intended to
communicate with a remote machine whose address is given by *host* and *port*.
.. method:: close()
Closes the socket.
.. method:: emit()
Pickles the record's attribute dictionary and writes it to the socket in
binary format. If there is an error with the socket, silently drops the
packet. If the connection was previously lost, re-establishes the
connection. To unpickle the record at the receiving end into a
:class:`~logging.LogRecord`, use the :func:`~logging.makeLogRecord`
function.
.. method:: handleError()
Handles an error which has occurred during :meth:`emit`. The most likely
cause is a lost connection. Closes the socket so that we can retry on the
next event.
.. method:: makeSocket()
This is a factory method which allows subclasses to define the precise
type of socket they want. The default implementation creates a TCP socket
(:const:`socket.SOCK_STREAM`).
.. method:: makePickle(record)
Pickles the record's attribute dictionary in binary format with a length
prefix, and returns it ready for transmission across the socket.
Note that pickles aren't completely secure. If you are concerned about
security, you may want to override this method to implement a more secure
mechanism. For example, you can sign pickles using HMAC and then verify
them on the receiving end, or alternatively you can disable unpickling of
global objects on the receiving end.
.. method:: send(packet)
Send a pickled string *packet* to the socket. This function allows for
partial sends which can happen when the network is busy.
.. method:: createSocket()
Tries to create a socket; on failure, uses an exponential back-off
algorithm. On initial failure, the handler will drop the message it was
trying to send. When subsequent messages are handled by the same
instance, it will not try connecting until some time has passed. The
default parameters are such that the initial delay is one second, and if
after that delay the connection still can't be made, the handler will
double the delay each time up to a maximum of 30 seconds.
This behaviour is controlled by the following handler attributes:
* ``retryStart`` (initial delay, defaulting to 1.0 seconds).
* ``retryFactor`` (multiplier, defaulting to 2.0).
* ``retryMax`` (maximum delay, defaulting to 30.0 seconds).
This means that if the remote listener starts up *after* the handler has
been used, you could lose messages (since the handler won't even attempt
a connection until the delay has elapsed, but just silently drop messages
during the delay period).
.. _datagram-handler:
DatagramHandler
^^^^^^^^^^^^^^^
The :class:`DatagramHandler` class, located in the :mod:`logging.handlers`
module, inherits from :class:`SocketHandler` to support sending logging messages
over UDP sockets.
.. class:: DatagramHandler(host, port)
Returns a new instance of the :class:`DatagramHandler` class intended to
communicate with a remote machine whose address is given by *host* and *port*.
.. method:: emit()
Pickles the record's attribute dictionary and writes it to the socket in
binary format. If there is an error with the socket, silently drops the
packet. To unpickle the record at the receiving end into a
:class:`~logging.LogRecord`, use the :func:`~logging.makeLogRecord`
function.
.. method:: makeSocket()
The factory method of :class:`SocketHandler` is here overridden to create
a UDP socket (:const:`socket.SOCK_DGRAM`).
.. method:: send(s)
Send a pickled string to a socket.
.. _syslog-handler:
SysLogHandler
^^^^^^^^^^^^^
The :class:`SysLogHandler` class, located in the :mod:`logging.handlers` module,
supports sending logging messages to a remote or local Unix syslog.
.. class:: SysLogHandler(address=('localhost', SYSLOG_UDP_PORT), facility=LOG_USER, socktype=socket.SOCK_DGRAM)
Returns a new instance of the :class:`SysLogHandler` class intended to
communicate with a remote Unix machine whose address is given by *address* in
the form of a ``(host, port)`` tuple. If *address* is not specified,
``('localhost', 514)`` is used. The address is used to open a socket. An
alternative to providing a ``(host, port)`` tuple is providing an address as a
string, for example '/dev/log'. In this case, a Unix domain socket is used to
send the message to the syslog. If *facility* is not specified,
:const:`LOG_USER` is used. The type of socket opened depends on the
*socktype* argument, which defaults to :const:`socket.SOCK_DGRAM` and thus
opens a UDP socket. To open a TCP socket (for use with the newer syslog
daemons such as rsyslog), specify a value of :const:`socket.SOCK_STREAM`.
Note that if your server is not listening on UDP port 514,
:class:`SysLogHandler` may appear not to work. In that case, check what
address you should be using for a domain socket - it's system dependent.
For example, on Linux it's usually '/dev/log' but on OS/X it's
'/var/run/syslog'. You'll need to check your platform and use the
appropriate address (you may need to do this check at runtime if your
application needs to run on several platforms). On Windows, you pretty
much have to use the UDP option.
.. versionchanged:: 2.7
*socktype* was added.
.. method:: close()
Closes the socket to the remote host.
.. method:: emit(record)
The record is formatted, and then sent to the syslog server. If exception
information is present, it is *not* sent to the server.
.. method:: encodePriority(facility, priority)
Encodes the facility and priority into an integer. You can pass in strings
or integers - if strings are passed, internal mapping dictionaries are
used to convert them to integers.
The symbolic ``LOG_`` values are defined in :class:`SysLogHandler` and
mirror the values defined in the ``sys/syslog.h`` header file.
**Priorities**
+--------------------------+---------------+
| Name (string) | Symbolic value|
+==========================+===============+
| ``alert`` | LOG_ALERT |
+--------------------------+---------------+
| ``crit`` or ``critical`` | LOG_CRIT |
+--------------------------+---------------+
| ``debug`` | LOG_DEBUG |
+--------------------------+---------------+
| ``emerg`` or ``panic`` | LOG_EMERG |
+--------------------------+---------------+
| ``err`` or ``error`` | LOG_ERR |
+--------------------------+---------------+
| ``info`` | LOG_INFO |
+--------------------------+---------------+
| ``notice`` | LOG_NOTICE |
+--------------------------+---------------+
| ``warn`` or ``warning`` | LOG_WARNING |
+--------------------------+---------------+
**Facilities**
+---------------+---------------+
| Name (string) | Symbolic value|
+===============+===============+
| ``auth`` | LOG_AUTH |
+---------------+---------------+
| ``authpriv`` | LOG_AUTHPRIV |
+---------------+---------------+
| ``cron`` | LOG_CRON |
+---------------+---------------+
| ``daemon`` | LOG_DAEMON |
+---------------+---------------+
| ``ftp`` | LOG_FTP |
+---------------+---------------+
| ``kern`` | LOG_KERN |
+---------------+---------------+
| ``lpr`` | LOG_LPR |
+---------------+---------------+
| ``mail`` | LOG_MAIL |
+---------------+---------------+
| ``news`` | LOG_NEWS |
+---------------+---------------+
| ``syslog`` | LOG_SYSLOG |
+---------------+---------------+
| ``user`` | LOG_USER |
+---------------+---------------+
| ``uucp`` | LOG_UUCP |
+---------------+---------------+
| ``local0`` | LOG_LOCAL0 |
+---------------+---------------+
| ``local1`` | LOG_LOCAL1 |
+---------------+---------------+
| ``local2`` | LOG_LOCAL2 |
+---------------+---------------+
| ``local3`` | LOG_LOCAL3 |
+---------------+---------------+
| ``local4`` | LOG_LOCAL4 |
+---------------+---------------+
| ``local5`` | LOG_LOCAL5 |
+---------------+---------------+
| ``local6`` | LOG_LOCAL6 |
+---------------+---------------+
| ``local7`` | LOG_LOCAL7 |
+---------------+---------------+
.. method:: mapPriority(levelname)
Maps a logging level name to a syslog priority name.
You may need to override this if you are using custom levels, or
if the default algorithm is not suitable for your needs. The
default algorithm maps ``DEBUG``, ``INFO``, ``WARNING``, ``ERROR`` and
``CRITICAL`` to the equivalent syslog names, and all other level
names to 'warning'.
.. _nt-eventlog-handler:
NTEventLogHandler
^^^^^^^^^^^^^^^^^
The :class:`NTEventLogHandler` class, located in the :mod:`logging.handlers`
module, supports sending logging messages to a local Windows NT, Windows 2000 or
Windows XP event log. Before you can use it, you need Mark Hammond's Win32
extensions for Python installed.
.. class:: NTEventLogHandler(appname, dllname=None, logtype='Application')
Returns a new instance of the :class:`NTEventLogHandler` class. The *appname* is
used to define the application name as it appears in the event log. An
appropriate registry entry is created using this name. The *dllname* should give
the fully qualified pathname of a .dll or .exe which contains message
definitions to hold in the log (if not specified, ``'win32service.pyd'`` is used
- this is installed with the Win32 extensions and contains some basic
placeholder message definitions. Note that use of these placeholders will make
your event logs big, as the entire message source is held in the log. If you
want slimmer logs, you have to pass in the name of your own .dll or .exe which
contains the message definitions you want to use in the event log). The
*logtype* is one of ``'Application'``, ``'System'`` or ``'Security'``, and
defaults to ``'Application'``.
.. method:: close()
At this point, you can remove the application name from the registry as a
source of event log entries. However, if you do this, you will not be able
to see the events as you intended in the Event Log Viewer - it needs to be
able to access the registry to get the .dll name. The current version does
not do this.
.. method:: emit(record)
Determines the message ID, event category and event type, and then logs
the message in the NT event log.
.. method:: getEventCategory(record)
Returns the event category for the record. Override this if you want to
specify your own categories. This version returns 0.
.. method:: getEventType(record)
Returns the event type for the record. Override this if you want to
specify your own types. This version does a mapping using the handler's
typemap attribute, which is set up in :meth:`__init__` to a dictionary
which contains mappings for :const:`DEBUG`, :const:`INFO`,
:const:`WARNING`, :const:`ERROR` and :const:`CRITICAL`. If you are using
your own levels, you will either need to override this method or place a
suitable dictionary in the handler's *typemap* attribute.
.. method:: getMessageID(record)
Returns the message ID for the record. If you are using your own messages,
you could do this by having the *msg* passed to the logger being an ID
rather than a format string. Then, in here, you could use a dictionary
lookup to get the message ID. This version returns 1, which is the base
message ID in :file:`win32service.pyd`.
.. _smtp-handler:
SMTPHandler
^^^^^^^^^^^
The :class:`SMTPHandler` class, located in the :mod:`logging.handlers` module,
supports sending logging messages to an email address via SMTP.
.. class:: SMTPHandler(mailhost, fromaddr, toaddrs, subject, credentials=None, secure=None)
Returns a new instance of the :class:`SMTPHandler` class. The instance is
initialized with the from and to addresses and subject line of the email.
The *toaddrs* should be a list of strings. To specify a non-standard SMTP
port, use the (host, port) tuple format for the *mailhost* argument. If you
use a string, the standard SMTP port is used. If your SMTP server requires
authentication, you can specify a (username, password) tuple for the
*credentials* argument.
To specify the use of a secure protocol (TLS), pass in a tuple to the
*secure* argument. This will only be used when authentication credentials are
supplied. The tuple should be either an empty tuple, or a single-value tuple
with the name of a keyfile, or a 2-value tuple with the names of the keyfile
and certificate file. (This tuple is passed to the
:meth:`smtplib.SMTP.starttls` method.)
.. versionchanged:: 2.6
*credentials* was added.
.. versionchanged:: 2.7
*secure* was added.
.. method:: emit(record)
Formats the record and sends it to the specified addressees.
.. method:: getSubject(record)
If you want to specify a subject line which is record-dependent, override
this method.
.. _memory-handler:
MemoryHandler
^^^^^^^^^^^^^
The :class:`MemoryHandler` class, located in the :mod:`logging.handlers` module,
supports buffering of logging records in memory, periodically flushing them to a
:dfn:`target` handler. Flushing occurs whenever the buffer is full, or when an
event of a certain severity or greater is seen.
:class:`MemoryHandler` is a subclass of the more general
:class:`BufferingHandler`, which is an abstract class. This buffers logging
records in memory. Whenever each record is added to the buffer, a check is made
by calling :meth:`shouldFlush` to see if the buffer should be flushed. If it
should, then :meth:`flush` is expected to do the flushing.
.. class:: BufferingHandler(capacity)
Initializes the handler with a buffer of the specified capacity.
.. method:: emit(record)
Appends the record to the buffer. If :meth:`shouldFlush` returns true,
calls :meth:`flush` to process the buffer.
.. method:: flush()
You can override this to implement custom flushing behavior. This version
just zaps the buffer to empty.
.. method:: shouldFlush(record)
Returns true if the buffer is up to capacity. This method can be
overridden to implement custom flushing strategies.
.. class:: MemoryHandler(capacity, flushLevel=ERROR, target=None)
Returns a new instance of the :class:`MemoryHandler` class. The instance is
initialized with a buffer size of *capacity*. If *flushLevel* is not specified,
:const:`ERROR` is used. If no *target* is specified, the target will need to be
set using :meth:`setTarget` before this handler does anything useful.
.. method:: close()
Calls :meth:`flush`, sets the target to :const:`None` and clears the
buffer.
.. method:: flush()
For a :class:`MemoryHandler`, flushing means just sending the buffered
records to the target, if there is one. The buffer is also cleared when
this happens. Override if you want different behavior.
.. method:: setTarget(target)
Sets the target handler for this handler.
.. method:: shouldFlush(record)
Checks for buffer full or a record at the *flushLevel* or higher.
.. _http-handler:
HTTPHandler
^^^^^^^^^^^
The :class:`HTTPHandler` class, located in the :mod:`logging.handlers` module,
supports sending logging messages to a Web server, using either ``GET`` or
``POST`` semantics.
.. class:: HTTPHandler(host, url, method='GET')
Returns a new instance of the :class:`HTTPHandler` class. The ``host`` can be
of the form ``host:port``, should you need to use a specific port number.
.. method:: mapLogRecord(record)
Provides a dictionary, based on ``record``, which is to be URL-encoded
and sent to the web server. The default implementation just returns
``record.__dict__``. This method can be overridden if e.g. only a
subset of :class:`~logging.LogRecord` is to be sent to the web server, or
if more specific customization of what's sent to the server is required.
.. method:: emit(record)
Sends the record to the Web server as a URL-encoded dictionary. The
:meth:`mapLogRecord` method is used to convert the record to the
dictionary to be sent.
.. note:: Since preparing a record for sending it to a Web server is not
the same as a generic formatting operation, using :meth:`setFormatter`
to specify a :class:`Formatter` for a :class:`HTTPHandler` has no effect.
Instead of calling :meth:`format`, this handler calls :meth:`mapLogRecord`
and then :func:`urllib.urlencode` to encode the dictionary in a form
suitable for sending to a Web server.
.. seealso::
Module :mod:`logging`
API reference for the logging module.
Module :mod:`logging.config`
Configuration API for the logging module.
PK %�\��: "� "� % html/_sources/library/logging.rst.txtnu �[��� :mod:`logging` --- Logging facility for Python
==============================================
.. module:: logging
:synopsis: Flexible event logging system for applications.
.. moduleauthor:: Vinay Sajip <vinay_sajip@red-dove.com>
.. sectionauthor:: Vinay Sajip <vinay_sajip@red-dove.com>
.. index:: pair: Errors; logging
.. sidebar:: Important
This page contains the API reference information. For tutorial
information and discussion of more advanced topics, see
* :ref:`Basic Tutorial <logging-basic-tutorial>`
* :ref:`Advanced Tutorial <logging-advanced-tutorial>`
* :ref:`Logging Cookbook <logging-cookbook>`
**Source code:** :source:`Lib/logging/__init__.py`
--------------
.. versionadded:: 2.3
This module defines functions and classes which implement a flexible event
logging system for applications and libraries.
The key benefit of having the logging API provided by a standard library module
is that all Python modules can participate in logging, so your application log
can include your own messages integrated with messages from third-party
modules.
The module provides a lot of functionality and flexibility. If you are
unfamiliar with logging, the best way to get to grips with it is to see the
tutorials (see the links on the right).
The basic classes defined by the module, together with their functions, are
listed below.
* Loggers expose the interface that application code directly uses.
* Handlers send the log records (created by loggers) to the appropriate
destination.
* Filters provide a finer grained facility for determining which log records
to output.
* Formatters specify the layout of log records in the final output.
.. _logger:
Logger Objects
--------------
Loggers have the following attributes and methods. Note that Loggers are never
instantiated directly, but always through the module-level function
``logging.getLogger(name)``. Multiple calls to :func:`getLogger` with the same
name will always return a reference to the same Logger object.
The ``name`` is potentially a period-separated hierarchical value, like
``foo.bar.baz`` (though it could also be just plain ``foo``, for example).
Loggers that are further down in the hierarchical list are children of loggers
higher up in the list. For example, given a logger with a name of ``foo``,
loggers with names of ``foo.bar``, ``foo.bar.baz``, and ``foo.bam`` are all
descendants of ``foo``. The logger name hierarchy is analogous to the Python
package hierarchy, and identical to it if you organise your loggers on a
per-module basis using the recommended construction
``logging.getLogger(__name__)``. That's because in a module, ``__name__``
is the module's name in the Python package namespace.
.. class:: Logger
.. attribute:: Logger.propagate
If this evaluates to true, events logged to this logger will be passed to the
handlers of higher level (ancestor) loggers, in addition to any handlers
attached to this logger. Messages are passed directly to the ancestor
loggers' handlers - neither the level nor filters of the ancestor loggers in
question are considered.
If this evaluates to false, logging messages are not passed to the handlers
of ancestor loggers.
The constructor sets this attribute to ``True``.
.. note:: If you attach a handler to a logger *and* one or more of its
ancestors, it may emit the same record multiple times. In general, you
should not need to attach a handler to more than one logger - if you just
attach it to the appropriate logger which is highest in the logger
hierarchy, then it will see all events logged by all descendant loggers,
provided that their propagate setting is left set to ``True``. A common
scenario is to attach handlers only to the root logger, and to let
propagation take care of the rest.
.. method:: Logger.setLevel(level)
Sets the threshold for this logger to *level*. Logging messages which are less
severe than *level* will be ignored. When a logger is created, the level is set to
:const:`NOTSET` (which causes all messages to be processed when the logger is
the root logger, or delegation to the parent when the logger is a non-root
logger). Note that the root logger is created with level :const:`WARNING`.
The term 'delegation to the parent' means that if a logger has a level of
NOTSET, its chain of ancestor loggers is traversed until either an ancestor with
a level other than NOTSET is found, or the root is reached.
If an ancestor is found with a level other than NOTSET, then that ancestor's
level is treated as the effective level of the logger where the ancestor search
began, and is used to determine how a logging event is handled.
If the root is reached, and it has a level of NOTSET, then all messages will be
processed. Otherwise, the root's level will be used as the effective level.
See :ref:`levels` for a list of levels.
.. method:: Logger.isEnabledFor(lvl)
Indicates if a message of severity *lvl* would be processed by this logger.
This method checks first the module-level level set by
``logging.disable(lvl)`` and then the logger's effective level as determined
by :meth:`getEffectiveLevel`.
.. method:: Logger.getEffectiveLevel()
Indicates the effective level for this logger. If a value other than
:const:`NOTSET` has been set using :meth:`setLevel`, it is returned. Otherwise,
the hierarchy is traversed towards the root until a value other than
:const:`NOTSET` is found, and that value is returned. The value returned is
an integer, typically one of :const:`logging.DEBUG`, :const:`logging.INFO`
etc.
.. method:: Logger.getChild(suffix)
Returns a logger which is a descendant to this logger, as determined by the suffix.
Thus, ``logging.getLogger('abc').getChild('def.ghi')`` would return the same
logger as would be returned by ``logging.getLogger('abc.def.ghi')``. This is a
convenience method, useful when the parent logger is named using e.g. ``__name__``
rather than a literal string.
.. versionadded:: 2.7
.. method:: Logger.debug(msg, *args, **kwargs)
Logs a message with level :const:`DEBUG` on this logger. The *msg* is the
message format string, and the *args* are the arguments which are merged into
*msg* using the string formatting operator. (Note that this means that you can
use keywords in the format string, together with a single dictionary argument.)
There are two keyword arguments in *kwargs* which are inspected: *exc_info*
which, if it does not evaluate as false, causes exception information to be
added to the logging message. If an exception tuple (in the format returned by
:func:`sys.exc_info`) is provided, it is used; otherwise, :func:`sys.exc_info`
is called to get the exception information.
The second keyword argument is *extra* which can be used to pass a
dictionary which is used to populate the __dict__ of the LogRecord created for
the logging event with user-defined attributes. These custom attributes can then
be used as you like. For example, they could be incorporated into logged
messages. For example::
FORMAT = '%(asctime)-15s %(clientip)s %(user)-8s %(message)s'
logging.basicConfig(format=FORMAT)
d = {'clientip': '192.168.0.1', 'user': 'fbloggs'}
logger = logging.getLogger('tcpserver')
logger.warning('Protocol problem: %s', 'connection reset', extra=d)
would print something like ::
2006-02-08 22:20:02,165 192.168.0.1 fbloggs Protocol problem: connection reset
The keys in the dictionary passed in *extra* should not clash with the keys used
by the logging system. (See the :class:`Formatter` documentation for more
information on which keys are used by the logging system.)
If you choose to use these attributes in logged messages, you need to exercise
some care. In the above example, for instance, the :class:`Formatter` has been
set up with a format string which expects 'clientip' and 'user' in the attribute
dictionary of the LogRecord. If these are missing, the message will not be
logged because a string formatting exception will occur. So in this case, you
always need to pass the *extra* dictionary with these keys.
While this might be annoying, this feature is intended for use in specialized
circumstances, such as multi-threaded servers where the same code executes in
many contexts, and interesting conditions which arise are dependent on this
context (such as remote client IP address and authenticated user name, in the
above example). In such circumstances, it is likely that specialized
:class:`Formatter`\ s would be used with particular :class:`Handler`\ s.
.. method:: Logger.info(msg, *args, **kwargs)
Logs a message with level :const:`INFO` on this logger. The arguments are
interpreted as for :meth:`debug`.
.. method:: Logger.warning(msg, *args, **kwargs)
Logs a message with level :const:`WARNING` on this logger. The arguments are
interpreted as for :meth:`debug`.
.. method:: Logger.error(msg, *args, **kwargs)
Logs a message with level :const:`ERROR` on this logger. The arguments are
interpreted as for :meth:`debug`.
.. method:: Logger.critical(msg, *args, **kwargs)
Logs a message with level :const:`CRITICAL` on this logger. The arguments are
interpreted as for :meth:`debug`.
.. method:: Logger.log(lvl, msg, *args, **kwargs)
Logs a message with integer level *lvl* on this logger. The other arguments are
interpreted as for :meth:`debug`.
.. method:: Logger.exception(msg, *args, **kwargs)
Logs a message with level :const:`ERROR` on this logger. The arguments are
interpreted as for :meth:`debug`, except that any passed *exc_info* is not
inspected. Exception info is always added to the logging message. This method
should only be called from an exception handler.
.. method:: Logger.addFilter(filter)
Adds the specified filter *filter* to this logger.
.. method:: Logger.removeFilter(filter)
Removes the specified filter *filter* from this logger.
.. method:: Logger.filter(record)
Applies this logger's filters to the record and returns a true value if the
record is to be processed. The filters are consulted in turn, until one of
them returns a false value. If none of them return a false value, the record
will be processed (passed to handlers). If one returns a false value, no
further processing of the record occurs.
.. method:: Logger.addHandler(hdlr)
Adds the specified handler *hdlr* to this logger.
.. method:: Logger.removeHandler(hdlr)
Removes the specified handler *hdlr* from this logger.
.. method:: Logger.findCaller()
Finds the caller's source filename and line number. Returns the filename, line
number and function name as a 3-element tuple.
.. versionchanged:: 2.4
The function name was added. In earlier versions, the filename and line
number were returned as a 2-element tuple.
.. method:: Logger.handle(record)
Handles a record by passing it to all handlers associated with this logger and
its ancestors (until a false value of *propagate* is found). This method is used
for unpickled records received from a socket, as well as those created locally.
Logger-level filtering is applied using :meth:`~Logger.filter`.
.. method:: Logger.makeRecord(name, lvl, fn, lno, msg, args, exc_info, func=None, extra=None)
This is a factory method which can be overridden in subclasses to create
specialized :class:`LogRecord` instances.
.. versionchanged:: 2.5
*func* and *extra* were added.
.. _levels:
Logging Levels
--------------
The numeric values of logging levels are given in the following table. These are
primarily of interest if you want to define your own levels, and need them to
have specific values relative to the predefined levels. If you define a level
with the same numeric value, it overwrites the predefined value; the predefined
name is lost.
+--------------+---------------+
| Level | Numeric value |
+==============+===============+
| ``CRITICAL`` | 50 |
+--------------+---------------+
| ``ERROR`` | 40 |
+--------------+---------------+
| ``WARNING`` | 30 |
+--------------+---------------+
| ``INFO`` | 20 |
+--------------+---------------+
| ``DEBUG`` | 10 |
+--------------+---------------+
| ``NOTSET`` | 0 |
+--------------+---------------+
.. _handler:
Handler Objects
---------------
Handlers have the following attributes and methods. Note that :class:`Handler`
is never instantiated directly; this class acts as a base for more useful
subclasses. However, the :meth:`__init__` method in subclasses needs to call
:meth:`Handler.__init__`.
.. method:: Handler.__init__(level=NOTSET)
Initializes the :class:`Handler` instance by setting its level, setting the list
of filters to the empty list and creating a lock (using :meth:`createLock`) for
serializing access to an I/O mechanism.
.. method:: Handler.createLock()
Initializes a thread lock which can be used to serialize access to underlying
I/O functionality which may not be threadsafe.
.. method:: Handler.acquire()
Acquires the thread lock created with :meth:`createLock`.
.. method:: Handler.release()
Releases the thread lock acquired with :meth:`acquire`.
.. method:: Handler.setLevel(level)
Sets the threshold for this handler to *level*. Logging messages which are less
severe than *level* will be ignored. When a handler is created, the level is set
to :const:`NOTSET` (which causes all messages to be processed).
See :ref:`levels` for a list of levels.
.. method:: Handler.setFormatter(fmt)
Sets the :class:`Formatter` for this handler to *fmt*.
.. method:: Handler.addFilter(filter)
Adds the specified filter *filter* to this handler.
.. method:: Handler.removeFilter(filter)
Removes the specified filter *filter* from this handler.
.. method:: Handler.filter(record)
Applies this handler's filters to the record and returns a true value if the
record is to be processed. The filters are consulted in turn, until one of
them returns a false value. If none of them return a false value, the record
will be emitted. If one returns a false value, the handler will not emit the
record.
.. method:: Handler.flush()
Ensure all logging output has been flushed. This version does nothing and is
intended to be implemented by subclasses.
.. method:: Handler.close()
Tidy up any resources used by the handler. This version does no output but
removes the handler from an internal list of handlers which is closed when
:func:`shutdown` is called. Subclasses should ensure that this gets called
from overridden :meth:`close` methods.
.. method:: Handler.handle(record)
Conditionally emits the specified logging record, depending on filters which may
have been added to the handler. Wraps the actual emission of the record with
acquisition/release of the I/O thread lock.
.. method:: Handler.handleError(record)
This method should be called from handlers when an exception is encountered
during an :meth:`emit` call. If the module-level attribute
``raiseExceptions`` is ``False``, exceptions get silently ignored. This is
what is mostly wanted for a logging system - most users will not care about
errors in the logging system, they are more interested in application
errors. You could, however, replace this with a custom handler if you wish.
The specified record is the one which was being processed when the exception
occurred. (The default value of ``raiseExceptions`` is ``True``, as that is
more useful during development).
.. method:: Handler.format(record)
Do formatting for a record - if a formatter is set, use it. Otherwise, use the
default formatter for the module.
.. method:: Handler.emit(record)
Do whatever it takes to actually log the specified logging record. This version
is intended to be implemented by subclasses and so raises a
:exc:`NotImplementedError`.
For a list of handlers included as standard, see :mod:`logging.handlers`.
.. _formatter-objects:
Formatter Objects
-----------------
.. currentmodule:: logging
:class:`Formatter` objects have the following attributes and methods. They are
responsible for converting a :class:`LogRecord` to (usually) a string which can
be interpreted by either a human or an external system. The base
:class:`Formatter` allows a formatting string to be specified. If none is
supplied, the default value of ``'%(message)s'`` is used, which just includes
the message in the logging call. To have additional items of information in the
formatted output (such as a timestamp), keep reading.
A Formatter can be initialized with a format string which makes use of knowledge
of the :class:`LogRecord` attributes - such as the default value mentioned above
making use of the fact that the user's message and arguments are pre-formatted
into a :class:`LogRecord`'s *message* attribute. This format string contains
standard Python %-style mapping keys. See section :ref:`string-formatting`
for more information on string formatting.
The useful mapping keys in a :class:`LogRecord` are given in the section on
:ref:`logrecord-attributes`.
.. class:: Formatter(fmt=None, datefmt=None)
Returns a new instance of the :class:`Formatter` class. The instance is
initialized with a format string for the message as a whole, as well as a
format string for the date/time portion of a message. If no *fmt* is
specified, ``'%(message)s'`` is used. If no *datefmt* is specified, the
ISO8601 date format is used.
.. method:: format(record)
The record's attribute dictionary is used as the operand to a string
formatting operation. Returns the resulting string. Before formatting the
dictionary, a couple of preparatory steps are carried out. The *message*
attribute of the record is computed using *msg* % *args*. If the
formatting string contains ``'(asctime)'``, :meth:`formatTime` is called
to format the event time. If there is exception information, it is
formatted using :meth:`formatException` and appended to the message. Note
that the formatted exception information is cached in attribute
*exc_text*. This is useful because the exception information can be
pickled and sent across the wire, but you should be careful if you have
more than one :class:`Formatter` subclass which customizes the formatting
of exception information. In this case, you will have to clear the cached
value after a formatter has done its formatting, so that the next
formatter to handle the event doesn't use the cached value but
recalculates it afresh.
.. method:: formatTime(record, datefmt=None)
This method should be called from :meth:`format` by a formatter which
wants to make use of a formatted time. This method can be overridden in
formatters to provide for any specific requirement, but the basic behavior
is as follows: if *datefmt* (a string) is specified, it is used with
:func:`time.strftime` to format the creation time of the
record. Otherwise, the ISO8601 format is used. The resulting string is
returned.
This function uses a user-configurable function to convert the creation
time to a tuple. By default, :func:`time.localtime` is used; to change
this for a particular formatter instance, set the ``converter`` attribute
to a function with the same signature as :func:`time.localtime` or
:func:`time.gmtime`. To change it for all formatters, for example if you
want all logging times to be shown in GMT, set the ``converter``
attribute in the ``Formatter`` class.
.. method:: formatException(exc_info)
Formats the specified exception information (a standard exception tuple as
returned by :func:`sys.exc_info`) as a string. This default implementation
just uses :func:`traceback.print_exception`. The resulting string is
returned.
.. _filter:
Filter Objects
--------------
``Filters`` can be used by ``Handlers`` and ``Loggers`` for more sophisticated
filtering than is provided by levels. The base filter class only allows events
which are below a certain point in the logger hierarchy. For example, a filter
initialized with 'A.B' will allow events logged by loggers 'A.B', 'A.B.C',
'A.B.C.D', 'A.B.D' etc. but not 'A.BB', 'B.A.B' etc. If initialized with the
empty string, all events are passed.
.. class:: Filter(name='')
Returns an instance of the :class:`Filter` class. If *name* is specified, it
names a logger which, together with its children, will have its events allowed
through the filter. If *name* is the empty string, allows every event.
.. method:: filter(record)
Is the specified record to be logged? Returns zero for no, nonzero for
yes. If deemed appropriate, the record may be modified in-place by this
method.
Note that filters attached to handlers are consulted before an event is
emitted by the handler, whereas filters attached to loggers are consulted
whenever an event is logged (using :meth:`debug`, :meth:`info`,
etc.), before sending an event to handlers. This means that events which have
been generated by descendant loggers will not be filtered by a logger's filter
setting, unless the filter has also been applied to those descendant loggers.
You don't actually need to subclass ``Filter``: you can pass any instance
which has a ``filter`` method with the same semantics.
Although filters are used primarily to filter records based on more
sophisticated criteria than levels, they get to see every record which is
processed by the handler or logger they're attached to: this can be useful if
you want to do things like counting how many records were processed by a
particular logger or handler, or adding, changing or removing attributes in
the LogRecord being processed. Obviously changing the LogRecord needs to be
done with some care, but it does allow the injection of contextual information
into logs (see :ref:`filters-contextual`).
.. _log-record:
LogRecord Objects
-----------------
:class:`LogRecord` instances are created automatically by the :class:`Logger`
every time something is logged, and can be created manually via
:func:`makeLogRecord` (for example, from a pickled event received over the
wire).
.. class:: LogRecord(name, level, pathname, lineno, msg, args, exc_info, func=None)
Contains all the information pertinent to the event being logged.
The primary information is passed in :attr:`msg` and :attr:`args`, which
are combined using ``msg % args`` to create the :attr:`message` field of the
record.
:param name: The name of the logger used to log the event represented by
this LogRecord. Note that this name will always have this
value, even though it may be emitted by a handler attached to
a different (ancestor) logger.
:param level: The numeric level of the logging event (one of DEBUG, INFO etc.)
Note that this is converted to *two* attributes of the LogRecord:
``levelno`` for the numeric value and ``levelname`` for the
corresponding level name.
:param pathname: The full pathname of the source file where the logging call
was made.
:param lineno: The line number in the source file where the logging call was
made.
:param msg: The event description message, possibly a format string with
placeholders for variable data.
:param args: Variable data to merge into the *msg* argument to obtain the
event description.
:param exc_info: An exception tuple with the current exception information,
or ``None`` if no exception information is available.
:param func: The name of the function or method from which the logging call
was invoked.
.. versionchanged:: 2.5
*func* was added.
.. method:: getMessage()
Returns the message for this :class:`LogRecord` instance after merging any
user-supplied arguments with the message. If the user-supplied message
argument to the logging call is not a string, :func:`str` is called on it to
convert it to a string. This allows use of user-defined classes as
messages, whose ``__str__`` method can return the actual format string to
be used.
.. _logrecord-attributes:
LogRecord attributes
--------------------
The LogRecord has a number of attributes, most of which are derived from the
parameters to the constructor. (Note that the names do not always correspond
exactly between the LogRecord constructor parameters and the LogRecord
attributes.) These attributes can be used to merge data from the record into
the format string. The following table lists (in alphabetical order) the
attribute names, their meanings and the corresponding placeholder in a %-style
format string.
+----------------+-------------------------+-----------------------------------------------+
| Attribute name | Format | Description |
+================+=========================+===============================================+
| args | You shouldn't need to | The tuple of arguments merged into ``msg`` to |
| | format this yourself. | produce ``message``, or a dict whose values |
| | | are used for the merge (when there is only one|
| | | argument, and it is a dictionary). |
+----------------+-------------------------+-----------------------------------------------+
| asctime | ``%(asctime)s`` | Human-readable time when the |
| | | :class:`LogRecord` was created. By default |
| | | this is of the form '2003-07-08 16:49:45,896' |
| | | (the numbers after the comma are millisecond |
| | | portion of the time). |
+----------------+-------------------------+-----------------------------------------------+
| created | ``%(created)f`` | Time when the :class:`LogRecord` was created |
| | | (as returned by :func:`time.time`). |
+----------------+-------------------------+-----------------------------------------------+
| exc_info | You shouldn't need to | Exception tuple (à la ``sys.exc_info``) or, |
| | format this yourself. | if no exception has occurred, ``None``. |
+----------------+-------------------------+-----------------------------------------------+
| filename | ``%(filename)s`` | Filename portion of ``pathname``. |
+----------------+-------------------------+-----------------------------------------------+
| funcName | ``%(funcName)s`` | Name of function containing the logging call. |
+----------------+-------------------------+-----------------------------------------------+
| levelname | ``%(levelname)s`` | Text logging level for the message |
| | | (``'DEBUG'``, ``'INFO'``, ``'WARNING'``, |
| | | ``'ERROR'``, ``'CRITICAL'``). |
+----------------+-------------------------+-----------------------------------------------+
| levelno | ``%(levelno)s`` | Numeric logging level for the message |
| | | (:const:`DEBUG`, :const:`INFO`, |
| | | :const:`WARNING`, :const:`ERROR`, |
| | | :const:`CRITICAL`). |
+----------------+-------------------------+-----------------------------------------------+
| lineno | ``%(lineno)d`` | Source line number where the logging call was |
| | | issued (if available). |
+----------------+-------------------------+-----------------------------------------------+
| module | ``%(module)s`` | Module (name portion of ``filename``). |
+----------------+-------------------------+-----------------------------------------------+
| msecs | ``%(msecs)d`` | Millisecond portion of the time when the |
| | | :class:`LogRecord` was created. |
+----------------+-------------------------+-----------------------------------------------+
| message | ``%(message)s`` | The logged message, computed as ``msg % |
| | | args``. This is set when |
| | | :meth:`Formatter.format` is invoked. |
+----------------+-------------------------+-----------------------------------------------+
| msg | You shouldn't need to | The format string passed in the original |
| | format this yourself. | logging call. Merged with ``args`` to |
| | | produce ``message``, or an arbitrary object |
| | | (see :ref:`arbitrary-object-messages`). |
+----------------+-------------------------+-----------------------------------------------+
| name | ``%(name)s`` | Name of the logger used to log the call. |
+----------------+-------------------------+-----------------------------------------------+
| pathname | ``%(pathname)s`` | Full pathname of the source file where the |
| | | logging call was issued (if available). |
+----------------+-------------------------+-----------------------------------------------+
| process | ``%(process)d`` | Process ID (if available). |
+----------------+-------------------------+-----------------------------------------------+
| processName | ``%(processName)s`` | Process name (if available). |
+----------------+-------------------------+-----------------------------------------------+
| relativeCreated| ``%(relativeCreated)d`` | Time in milliseconds when the LogRecord was |
| | | created, relative to the time the logging |
| | | module was loaded. |
+----------------+-------------------------+-----------------------------------------------+
| thread | ``%(thread)d`` | Thread ID (if available). |
+----------------+-------------------------+-----------------------------------------------+
| threadName | ``%(threadName)s`` | Thread name (if available). |
+----------------+-------------------------+-----------------------------------------------+
.. versionchanged:: 2.5
*funcName* was added.
.. versionchanged:: 2.6
*processName* was added.
.. _logger-adapter:
LoggerAdapter Objects
---------------------
:class:`LoggerAdapter` instances are used to conveniently pass contextual
information into logging calls. For a usage example, see the section on
:ref:`adding contextual information to your logging output <context-info>`.
.. versionadded:: 2.6
.. class:: LoggerAdapter(logger, extra)
Returns an instance of :class:`LoggerAdapter` initialized with an
underlying :class:`Logger` instance and a dict-like object.
.. method:: process(msg, kwargs)
Modifies the message and/or keyword arguments passed to a logging call in
order to insert contextual information. This implementation takes the object
passed as *extra* to the constructor and adds it to *kwargs* using key
'extra'. The return value is a (*msg*, *kwargs*) tuple which has the
(possibly modified) versions of the arguments passed in.
In addition to the above, :class:`LoggerAdapter` supports the following
methods of :class:`Logger`: :meth:`~Logger.debug`, :meth:`~Logger.info`,
:meth:`~Logger.warning`, :meth:`~Logger.error`, :meth:`~Logger.exception`,
:meth:`~Logger.critical`, :meth:`~Logger.log` and :meth:`~Logger.isEnabledFor`.
These methods have the same signatures as their counterparts in :class:`Logger`,
so you can use the two types of instances interchangeably for these calls.
.. versionchanged:: 2.7
The :meth:`~Logger.isEnabledFor` method was added to :class:`LoggerAdapter`.
This method delegates to the underlying logger.
Thread Safety
-------------
The logging module is intended to be thread-safe without any special work
needing to be done by its clients. It achieves this though using threading
locks; there is one lock to serialize access to the module's shared data, and
each handler also creates a lock to serialize access to its underlying I/O.
If you are implementing asynchronous signal handlers using the :mod:`signal`
module, you may not be able to use logging from within such handlers. This is
because lock implementations in the :mod:`threading` module are not always
re-entrant, and so cannot be invoked from such signal handlers.
Module-Level Functions
----------------------
In addition to the classes described above, there are a number of module- level
functions.
.. function:: getLogger([name])
Return a logger with the specified name or, if no name is specified, return a
logger which is the root logger of the hierarchy. If specified, the name is
typically a dot-separated hierarchical name like *"a"*, *"a.b"* or *"a.b.c.d"*.
Choice of these names is entirely up to the developer who is using logging.
All calls to this function with a given name return the same logger instance.
This means that logger instances never need to be passed between different parts
of an application.
.. function:: getLoggerClass()
Return either the standard :class:`Logger` class, or the last class passed to
:func:`setLoggerClass`. This function may be called from within a new class
definition, to ensure that installing a customized :class:`Logger` class will
not undo customizations already applied by other code. For example::
class MyLogger(logging.getLoggerClass()):
# ... override behaviour here
.. function:: debug(msg[, *args[, **kwargs]])
Logs a message with level :const:`DEBUG` on the root logger. The *msg* is the
message format string, and the *args* are the arguments which are merged into
*msg* using the string formatting operator. (Note that this means that you can
use keywords in the format string, together with a single dictionary argument.)
There are two keyword arguments in *kwargs* which are inspected: *exc_info*
which, if it does not evaluate as false, causes exception information to be
added to the logging message. If an exception tuple (in the format returned by
:func:`sys.exc_info`) is provided, it is used; otherwise, :func:`sys.exc_info`
is called to get the exception information.
The other optional keyword argument is *extra* which can be used to pass a
dictionary which is used to populate the __dict__ of the LogRecord created for
the logging event with user-defined attributes. These custom attributes can then
be used as you like. For example, they could be incorporated into logged
messages. For example::
FORMAT = "%(asctime)-15s %(clientip)s %(user)-8s %(message)s"
logging.basicConfig(format=FORMAT)
d = {'clientip': '192.168.0.1', 'user': 'fbloggs'}
logging.warning("Protocol problem: %s", "connection reset", extra=d)
would print something like::
2006-02-08 22:20:02,165 192.168.0.1 fbloggs Protocol problem: connection reset
The keys in the dictionary passed in *extra* should not clash with the keys used
by the logging system. (See the :class:`Formatter` documentation for more
information on which keys are used by the logging system.)
If you choose to use these attributes in logged messages, you need to exercise
some care. In the above example, for instance, the :class:`Formatter` has been
set up with a format string which expects 'clientip' and 'user' in the attribute
dictionary of the LogRecord. If these are missing, the message will not be
logged because a string formatting exception will occur. So in this case, you
always need to pass the *extra* dictionary with these keys.
While this might be annoying, this feature is intended for use in specialized
circumstances, such as multi-threaded servers where the same code executes in
many contexts, and interesting conditions which arise are dependent on this
context (such as remote client IP address and authenticated user name, in the
above example). In such circumstances, it is likely that specialized
:class:`Formatter`\ s would be used with particular :class:`Handler`\ s.
.. versionchanged:: 2.5
*extra* was added.
.. function:: info(msg[, *args[, **kwargs]])
Logs a message with level :const:`INFO` on the root logger. The arguments are
interpreted as for :func:`debug`.
.. function:: warning(msg[, *args[, **kwargs]])
Logs a message with level :const:`WARNING` on the root logger. The arguments are
interpreted as for :func:`debug`.
.. function:: error(msg[, *args[, **kwargs]])
Logs a message with level :const:`ERROR` on the root logger. The arguments are
interpreted as for :func:`debug`.
.. function:: critical(msg[, *args[, **kwargs]])
Logs a message with level :const:`CRITICAL` on the root logger. The arguments
are interpreted as for :func:`debug`.
.. function:: exception(msg[, *args[, **kwargs]])
Logs a message with level :const:`ERROR` on the root logger. The arguments are
interpreted as for :func:`debug`, except that any passed *exc_info* is not
inspected. Exception info is always added to the logging message. This
function should only be called from an exception handler.
.. function:: log(level, msg[, *args[, **kwargs]])
Logs a message with level *level* on the root logger. The other arguments are
interpreted as for :func:`debug`.
.. note:: The above module-level convenience functions, which delegate to the
root logger, call :func:`basicConfig` to ensure that at least one handler
is available. Because of this, they should *not* be used in threads,
in versions of Python earlier than 2.7.1 and 3.2, unless at least one
handler has been added to the root logger *before* the threads are
started. In earlier versions of Python, due to a thread safety shortcoming
in :func:`basicConfig`, this can (under rare circumstances) lead to
handlers being added multiple times to the root logger, which can in turn
lead to multiple messages for the same event.
.. function:: disable(lvl)
Provides an overriding level *lvl* for all loggers which takes precedence over
the logger's own level. When the need arises to temporarily throttle logging
output down across the whole application, this function can be useful. Its
effect is to disable all logging calls of severity *lvl* and below, so that
if you call it with a value of INFO, then all INFO and DEBUG events would be
discarded, whereas those of severity WARNING and above would be processed
according to the logger's effective level. If
``logging.disable(logging.NOTSET)`` is called, it effectively removes this
overriding level, so that logging output again depends on the effective
levels of individual loggers.
.. function:: addLevelName(lvl, levelName)
Associates level *lvl* with text *levelName* in an internal dictionary, which is
used to map numeric levels to a textual representation, for example when a
:class:`Formatter` formats a message. This function can also be used to define
your own levels. The only constraints are that all levels used must be
registered using this function, levels should be positive integers and they
should increase in increasing order of severity.
.. note:: If you are thinking of defining your own levels, please see the
section on :ref:`custom-levels`.
.. function:: getLevelName(lvl)
Returns the textual representation of logging level *lvl*. If the level is one
of the predefined levels :const:`CRITICAL`, :const:`ERROR`, :const:`WARNING`,
:const:`INFO` or :const:`DEBUG` then you get the corresponding string. If you
have associated levels with names using :func:`addLevelName` then the name you
have associated with *lvl* is returned. If a numeric value corresponding to one
of the defined levels is passed in, the corresponding string representation is
returned. Otherwise, the string "Level %s" % lvl is returned.
.. note:: Integer levels should be used when e.g. setting levels on instances
of :class:`Logger` and handlers. This function is used to convert between
an integer level and the level name displayed in the formatted log output
by means of the ``%(levelname)s`` format specifier (see
:ref:`logrecord-attributes`).
.. function:: makeLogRecord(attrdict)
Creates and returns a new :class:`LogRecord` instance whose attributes are
defined by *attrdict*. This function is useful for taking a pickled
:class:`LogRecord` attribute dictionary, sent over a socket, and reconstituting
it as a :class:`LogRecord` instance at the receiving end.
.. function:: basicConfig([**kwargs])
Does basic configuration for the logging system by creating a
:class:`StreamHandler` with a default :class:`Formatter` and adding it to the
root logger. The functions :func:`debug`, :func:`info`, :func:`warning`,
:func:`error` and :func:`critical` will call :func:`basicConfig` automatically
if no handlers are defined for the root logger.
This function does nothing if the root logger already has handlers
configured for it.
.. versionchanged:: 2.4
Formerly, :func:`basicConfig` did not take any keyword arguments.
.. note:: This function should be called from the main thread before other
threads are started. In versions of Python prior to 2.7.1 and 3.2, if
this function is called from multiple threads, it is possible (in rare
circumstances) that a handler will be added to the root logger more than
once, leading to unexpected results such as messages being duplicated in
the log.
The following keyword arguments are supported.
.. tabularcolumns:: |l|L|
+--------------+---------------------------------------------+
| Format | Description |
+==============+=============================================+
| *filename* | Specifies that a FileHandler be created, |
| | using the specified filename, rather than a |
| | StreamHandler. |
+--------------+---------------------------------------------+
| *filemode* | If *filename* is specified, open the file |
| | in this mode. Defaults to ``'a'``. |
+--------------+---------------------------------------------+
| *format* | Use the specified format string for the |
| | handler. |
+--------------+---------------------------------------------+
| *datefmt* | Use the specified date/time format, as |
| | accepted by :func:`time.strftime`. |
+--------------+---------------------------------------------+
| *level* | Set the root logger level to the specified |
| | :ref:`level <levels>`. |
+--------------+---------------------------------------------+
| *stream* | Use the specified stream to initialize the |
| | StreamHandler. Note that this argument is |
| | incompatible with *filename* - if both are |
| | present, *stream* is ignored. |
+--------------+---------------------------------------------+
.. function:: shutdown()
Informs the logging system to perform an orderly shutdown by flushing and
closing all handlers. This should be called at application exit and no
further use of the logging system should be made after this call.
.. function:: setLoggerClass(klass)
Tells the logging system to use the class *klass* when instantiating a logger.
The class should define :meth:`__init__` such that only a name argument is
required, and the :meth:`__init__` should call :meth:`Logger.__init__`. This
function is typically called before any loggers are instantiated by applications
which need to use custom logger behavior.
Integration with the warnings module
------------------------------------
The :func:`captureWarnings` function can be used to integrate :mod:`logging`
with the :mod:`warnings` module.
.. function:: captureWarnings(capture)
This function is used to turn the capture of warnings by logging on and
off.
If *capture* is ``True``, warnings issued by the :mod:`warnings` module will
be redirected to the logging system. Specifically, a warning will be
formatted using :func:`warnings.formatwarning` and the resulting string
logged to a logger named ``'py.warnings'`` with a severity of :const:`WARNING`.
If *capture* is ``False``, the redirection of warnings to the logging system
will stop, and warnings will be redirected to their original destinations
(i.e. those in effect before ``captureWarnings(True)`` was called).
.. seealso::
Module :mod:`logging.config`
Configuration API for the logging module.
Module :mod:`logging.handlers`
Useful handlers included with the logging module.
:pep:`282` - A Logging System
The proposal which described this feature for inclusion in the Python standard
library.
`Original Python logging package <https://www.red-dove.com/python_logging.html>`_
This is the original source for the :mod:`logging` package. The version of the
package available from this site is suitable for use with Python 1.5.2, 2.1.x
and 2.2.x, which do not include the :mod:`logging` package in the standard
library.
PK %�\xi�� ! html/_sources/library/mac.rst.txtnu �[��� .. _mac-specific-services:
**************************
Mac OS X specific services
**************************
This chapter describes modules that are only available on the Mac OS X platform.
See the chapters :ref:`mac-scripting` and :ref:`undoc-mac-modules` for more
modules, and the HOWTO :ref:`using-on-mac` for a general introduction to
Mac-specific Python programming.
.. note::
Most of the OS X APIs that these modules use are deprecated or removed
in recent versions of OS X. Many are not available when Python is
executing in 64-bit mode. These modules have been removed in
Python 3. You should avoid using them in Python 2.
.. toctree::
ic.rst
macos.rst
macostools.rst
easydialogs.rst
framework.rst
autogil.rst
carbon.rst
colorpicker.rst
PK %�\&�?� � # html/_sources/library/macos.rst.txtnu �[��� :mod:`MacOS` --- Access to Mac OS interpreter features
======================================================
.. module:: MacOS
:platform: Mac
:synopsis: Access to Mac OS-specific interpreter features.
:deprecated:
This module provides access to MacOS specific functionality in the Python
interpreter, such as how the interpreter eventloop functions and the like. Use
with care.
.. note::
This module has been removed in Python 3.x.
Note the capitalization of the module name; this is a historical artifact.
.. data:: runtimemodel
Always ``'macho'``, from Python 2.4 on. In earlier versions of Python the value
could also be ``'ppc'`` for the classic Mac OS 8 runtime model or ``'carbon'``
for the Mac OS 9 runtime model.
.. data:: linkmodel
The way the interpreter has been linked. As extension modules may be
incompatible between linking models, packages could use this information to give
more decent error messages. The value is one of ``'static'`` for a statically
linked Python, ``'framework'`` for Python in a Mac OS X framework, ``'shared'``
for Python in a standard Unix shared library. Older Pythons could also have the
value ``'cfm'`` for Mac OS 9-compatible Python.
.. exception:: Error
.. index:: module: macerrors
This exception is raised on MacOS generated errors, either from functions in
this module or from other mac-specific modules like the toolbox interfaces. The
arguments are the integer error code (the :c:data:`OSErr` value) and a textual
description of the error code. Symbolic names for all known error codes are
defined in the standard module :mod:`macerrors`.
.. function:: GetErrorString(errno)
Return the textual description of MacOS error code *errno*.
.. function:: DebugStr(message [, object])
On Mac OS X the string is simply printed to stderr (on older Mac OS systems more
elaborate functionality was available), but it provides a convenient location to
attach a breakpoint in a low-level debugger like :program:`gdb`.
.. note::
Not available in 64-bit mode.
.. function:: SysBeep()
Ring the bell.
.. note::
Not available in 64-bit mode.
.. function:: GetTicks()
Get the number of clock ticks (1/60th of a second) since system boot.
.. function:: GetCreatorAndType(file)
Return the file creator and file type as two four-character strings. The *file*
parameter can be a pathname or an ``FSSpec`` or ``FSRef`` object.
.. note::
It is not possible to use an ``FSSpec`` in 64-bit mode.
.. function:: SetCreatorAndType(file, creator, type)
Set the file creator and file type. The *file* parameter can be a pathname or an
``FSSpec`` or ``FSRef`` object. *creator* and *type* must be four character
strings.
.. note::
It is not possible to use an ``FSSpec`` in 64-bit mode.
.. function:: openrf(name [, mode])
Open the resource fork of a file. Arguments are the same as for the built-in
function :func:`open`. The object returned has file-like semantics, but it is
not a Python file object, so there may be subtle differences.
.. function:: WMAvailable()
Checks whether the current process has access to the window manager. The method
will return ``False`` if the window manager is not available, for instance when
running on Mac OS X Server or when logged in via ssh, or when the current
interpreter is not running from a fullblown application bundle. A script runs
from an application bundle either when it has been started with
:program:`pythonw` instead of :program:`python` or when running as an applet.
.. function:: splash([resourceid])
Opens a splash screen by resource id. Use resourceid ``0`` to close
the splash screen.
.. note::
Not available in 64-bit mode.
PK %�\�� z| | $ html/_sources/library/macosa.rst.txtnu �[���
.. _mac-scripting:
*********************
MacPython OSA Modules
*********************
This chapter describes the current implementation of the Open Scripting
Architecture (OSA, also commonly referred to as AppleScript) for Python,
allowing you to control scriptable applications from your Python program,
and with a fairly pythonic interface. Development on this set of modules has
stopped.
For a description of the various components of AppleScript and OSA, and to get
an understanding of the architecture and terminology, you should read Apple's
documentation. The "Applescript Language Guide" explains the conceptual model
and the terminology, and documents the standard suite. The "Open Scripting
Architecture" document explains how to use OSA from an application programmers
point of view. In the Apple Help Viewer these books are located in the Developer
Documentation, Core Technologies section.
As an example of scripting an application, the following piece of AppleScript
will get the name of the frontmost :program:`Finder` window and print it::
tell application "Finder"
get name of window 1
end tell
In Python, the following code fragment will do the same::
import Finder
f = Finder.Finder()
print f.get(f.window(1).name)
As distributed the Python library includes packages that implement the standard
suites, plus packages that interface to a small number of common applications.
To send AppleEvents to an application you must first create the Python package
interfacing to the terminology of the application (what :program:`Script Editor`
calls the "Dictionary"). This can be done from within the :program:`PythonIDE`
or by running the :file:`gensuitemodule.py` module as a standalone program from
the command line.
The generated output is a package with a number of modules, one for every suite
used in the program plus an :mod:`__init__` module to glue it all together. The
Python inheritance graph follows the AppleScript inheritance graph, so if a
program's dictionary specifies that it includes support for the Standard Suite,
but extends one or two verbs with extra arguments then the output suite will
contain a module :mod:`Standard_Suite` that imports and re-exports everything
from :mod:`StdSuites.Standard_Suite` but overrides the methods that have extra
functionality. The output of :mod:`gensuitemodule` is pretty readable, and
contains the documentation that was in the original AppleScript dictionary in
Python docstrings, so reading it is a good source of documentation.
The output package implements a main class with the same name as the package
which contains all the AppleScript verbs as methods, with the direct object as
the first argument and all optional parameters as keyword arguments. AppleScript
classes are also implemented as Python classes, as are comparisons and all the
other thingies.
The main Python class implementing the verbs also allows access to the
properties and elements declared in the AppleScript class "application". In the
current release that is as far as the object orientation goes, so in the example
above we need to use ``f.get(f.window(1).name)`` instead of the more Pythonic
``f.window(1).name.get()``.
If an AppleScript identifier is not a Python identifier the name is mangled
according to a small number of rules:
* spaces are replaced with underscores
* other non-alphanumeric characters are replaced with ``_xx_`` where ``xx`` is
the hexadecimal character value
* any Python reserved word gets an underscore appended
Python also has support for creating scriptable applications in Python, but The
following modules are relevant to MacPython AppleScript support:
.. toctree::
gensuitemodule.rst
aetools.rst
aepack.rst
aetypes.rst
miniaeframe.rst
In addition, support modules have been pre-generated for :mod:`Finder`,
:mod:`Terminal`, :mod:`Explorer`, :mod:`Netscape`, :mod:`CodeWarrior`,
:mod:`SystemEvents` and :mod:`StdSuites`.
PK %�\�� � ( html/_sources/library/macostools.rst.txtnu �[���
:mod:`macostools` --- Convenience routines for file manipulation
================================================================
.. module:: macostools
:platform: Mac
:synopsis: Convenience routines for file manipulation.
:deprecated:
This module contains some convenience routines for file-manipulation on the
Macintosh. All file parameters can be specified as pathnames, :class:`FSRef` or
:class:`FSSpec` objects. This module expects a filesystem which supports forked
files, so it should not be used on UFS partitions.
.. note::
This module has been removed in Python 3.
The :mod:`macostools` module defines the following functions:
.. function:: copy(src, dst[, createpath[, copytimes]])
Copy file *src* to *dst*. If *createpath* is non-zero the folders leading to
*dst* are created if necessary. The method copies data and resource fork and
some finder information (creator, type, flags) and optionally the creation,
modification and backup times (default is to copy them). Custom icons, comments
and icon position are not copied.
.. note::
This function does not work in 64-bit code because it uses APIs that
are not available in 64-bit mode.
.. function:: copytree(src, dst)
Recursively copy a file tree from *src* to *dst*, creating folders as needed.
*src* and *dst* should be specified as pathnames.
.. note::
This function does not work in 64-bit code because it uses APIs that
are not available in 64-bit mode.
.. function:: mkalias(src, dst)
Create a finder alias *dst* pointing to *src*.
.. note::
This function does not work in 64-bit code because it uses APIs that
are not available in 64-bit mode.
.. function:: touched(dst)
Tell the finder that some bits of finder-information such as creator or type for
file *dst* has changed. The file can be specified by pathname or fsspec. This
call should tell the finder to redraw the files icon.
.. deprecated:: 2.6
The function is a no-op on OS X.
.. data:: BUFSIZ
The buffer size for ``copy``, default 1 megabyte.
Note that the process of creating finder aliases is not specified in the Apple
documentation. Hence, aliases created with :func:`mkalias` could conceivably
have incompatible behaviour in some cases.
:mod:`findertools` --- The :program:`finder`'s Apple Events interface
======================================================================
.. module:: findertools
:platform: Mac
:synopsis: Wrappers around the finder's Apple Events interface.
.. index:: single: AppleEvents
This module contains routines that give Python programs access to some
functionality provided by the finder. They are implemented as wrappers around
the AppleEvent interface to the finder.
All file and folder parameters can be specified either as full pathnames, or as
:class:`FSRef` or :class:`FSSpec` objects.
The :mod:`findertools` module defines the following functions:
.. function:: launch(file)
Tell the finder to launch *file*. What launching means depends on the file:
applications are started, folders are opened and documents are opened in the
correct application.
.. function:: Print(file)
Tell the finder to print a file. The behaviour is identical to selecting the
file and using the print command in the finder's file menu.
.. function:: copy(file, destdir)
Tell the finder to copy a file or folder *file* to folder *destdir*. The
function returns an :class:`Alias` object pointing to the new file.
.. function:: move(file, destdir)
Tell the finder to move a file or folder *file* to folder *destdir*. The
function returns an :class:`Alias` object pointing to the new file.
.. function:: sleep()
Tell the finder to put the Macintosh to sleep, if your machine supports it.
.. function:: restart()
Tell the finder to perform an orderly restart of the machine.
.. function:: shutdown()
Tell the finder to perform an orderly shutdown of the machine.
PK %�\nZ�� � % html/_sources/library/macpath.rst.txtnu �[���
:mod:`macpath` --- Mac OS 9 path manipulation functions
=======================================================
.. module:: macpath
:synopsis: Mac OS 9 path manipulation functions.
This module is the Mac OS 9 (and earlier) implementation of the :mod:`os.path`
module. It can be used to manipulate old-style Macintosh pathnames on Mac OS X
(or any other platform).
The following functions are available in this module: :func:`normcase`,
:func:`normpath`, :func:`isabs`, :func:`join`, :func:`split`, :func:`isdir`,
:func:`isfile`, :func:`walk`, :func:`exists`. For other functions available in
:mod:`os.path` dummy counterparts are available.
PK %�\veu_!
!
% html/_sources/library/mailbox.rst.txtnu �[���
:mod:`mailbox` --- Manipulate mailboxes in various formats
==========================================================
.. module:: mailbox
:synopsis: Manipulate mailboxes in various formats
.. moduleauthor:: Gregory K. Johnson <gkj@gregorykjohnson.com>
.. sectionauthor:: Gregory K. Johnson <gkj@gregorykjohnson.com>
This module defines two classes, :class:`Mailbox` and :class:`Message`, for
accessing and manipulating on-disk mailboxes and the messages they contain.
:class:`Mailbox` offers a dictionary-like mapping from keys to messages.
:class:`Message` extends the :mod:`email.message` module's
:class:`~email.message.Message` class with format-specific state and behavior.
Supported mailbox formats are
Maildir, mbox, MH, Babyl, and MMDF.
.. seealso::
Module :mod:`email`
Represent and manipulate messages.
.. _mailbox-objects:
:class:`Mailbox` objects
------------------------
.. class:: Mailbox
A mailbox, which may be inspected and modified.
The :class:`Mailbox` class defines an interface and is not intended to be
instantiated. Instead, format-specific subclasses should inherit from
:class:`Mailbox` and your code should instantiate a particular subclass.
The :class:`Mailbox` interface is dictionary-like, with small keys
corresponding to messages. Keys are issued by the :class:`Mailbox` instance
with which they will be used and are only meaningful to that :class:`Mailbox`
instance. A key continues to identify a message even if the corresponding
message is modified, such as by replacing it with another message.
Messages may be added to a :class:`Mailbox` instance using the set-like
method :meth:`add` and removed using a ``del`` statement or the set-like
methods :meth:`remove` and :meth:`discard`.
:class:`Mailbox` interface semantics differ from dictionary semantics in some
noteworthy ways. Each time a message is requested, a new representation
(typically a :class:`Message` instance) is generated based upon the current
state of the mailbox. Similarly, when a message is added to a
:class:`Mailbox` instance, the provided message representation's contents are
copied. In neither case is a reference to the message representation kept by
the :class:`Mailbox` instance.
The default :class:`Mailbox` iterator iterates over message representations,
not keys as the default dictionary iterator does. Moreover, modification of a
mailbox during iteration is safe and well-defined. Messages added to the
mailbox after an iterator is created will not be seen by the
iterator. Messages removed from the mailbox before the iterator yields them
will be silently skipped, though using a key from an iterator may result in a
:exc:`KeyError` exception if the corresponding message is subsequently
removed.
.. warning::
Be very cautious when modifying mailboxes that might be simultaneously
changed by some other process. The safest mailbox format to use for such
tasks is Maildir; try to avoid using single-file formats such as mbox for
concurrent writing. If you're modifying a mailbox, you *must* lock it by
calling the :meth:`lock` and :meth:`unlock` methods *before* reading any
messages in the file or making any changes by adding or deleting a
message. Failing to lock the mailbox runs the risk of losing messages or
corrupting the entire mailbox.
:class:`Mailbox` instances have the following methods:
.. method:: add(message)
Add *message* to the mailbox and return the key that has been assigned to
it.
Parameter *message* may be a :class:`Message` instance, an
:class:`email.message.Message` instance, a string, or a file-like object
(which should be open in text mode). If *message* is an instance of the
appropriate format-specific :class:`Message` subclass (e.g., if it's an
:class:`mboxMessage` instance and this is an :class:`mbox` instance), its
format-specific information is used. Otherwise, reasonable defaults for
format-specific information are used.
.. method:: remove(key)
__delitem__(key)
discard(key)
Delete the message corresponding to *key* from the mailbox.
If no such message exists, a :exc:`KeyError` exception is raised if the
method was called as :meth:`remove` or :meth:`__delitem__` but no
exception is raised if the method was called as :meth:`discard`. The
behavior of :meth:`discard` may be preferred if the underlying mailbox
format supports concurrent modification by other processes.
.. method:: __setitem__(key, message)
Replace the message corresponding to *key* with *message*. Raise a
:exc:`KeyError` exception if no message already corresponds to *key*.
As with :meth:`add`, parameter *message* may be a :class:`Message`
instance, an :class:`email.message.Message` instance, a string, or a
file-like object (which should be open in text mode). If *message* is an
instance of the appropriate format-specific :class:`Message` subclass
(e.g., if it's an :class:`mboxMessage` instance and this is an
:class:`mbox` instance), its format-specific information is
used. Otherwise, the format-specific information of the message that
currently corresponds to *key* is left unchanged.
.. method:: iterkeys()
keys()
Return an iterator over all keys if called as :meth:`iterkeys` or return a
list of keys if called as :meth:`keys`.
.. method:: itervalues()
__iter__()
values()
Return an iterator over representations of all messages if called as
:meth:`itervalues` or :meth:`__iter__` or return a list of such
representations if called as :meth:`values`. The messages are represented
as instances of the appropriate format-specific :class:`Message` subclass
unless a custom message factory was specified when the :class:`Mailbox`
instance was initialized.
.. note::
The behavior of :meth:`__iter__` is unlike that of dictionaries, which
iterate over keys.
.. method:: iteritems()
items()
Return an iterator over (*key*, *message*) pairs, where *key* is a key and
*message* is a message representation, if called as :meth:`iteritems` or
return a list of such pairs if called as :meth:`items`. The messages are
represented as instances of the appropriate format-specific
:class:`Message` subclass unless a custom message factory was specified
when the :class:`Mailbox` instance was initialized.
.. method:: get(key, default=None)
__getitem__(key)
Return a representation of the message corresponding to *key*. If no such
message exists, *default* is returned if the method was called as
:meth:`get` and a :exc:`KeyError` exception is raised if the method was
called as :meth:`__getitem__`. The message is represented as an instance
of the appropriate format-specific :class:`Message` subclass unless a
custom message factory was specified when the :class:`Mailbox` instance
was initialized.
.. method:: get_message(key)
Return a representation of the message corresponding to *key* as an
instance of the appropriate format-specific :class:`Message` subclass, or
raise a :exc:`KeyError` exception if no such message exists.
.. method:: get_string(key)
Return a string representation of the message corresponding to *key*, or
raise a :exc:`KeyError` exception if no such message exists.
.. method:: get_file(key)
Return a file-like representation of the message corresponding to *key*,
or raise a :exc:`KeyError` exception if no such message exists. The
file-like object behaves as if open in binary mode. This file should be
closed once it is no longer needed.
.. note::
Unlike other representations of messages, file-like representations are
not necessarily independent of the :class:`Mailbox` instance that
created them or of the underlying mailbox. More specific documentation
is provided by each subclass.
.. method:: has_key(key)
__contains__(key)
Return ``True`` if *key* corresponds to a message, ``False`` otherwise.
.. method:: __len__()
Return a count of messages in the mailbox.
.. method:: clear()
Delete all messages from the mailbox.
.. method:: pop(key[, default])
Return a representation of the message corresponding to *key* and delete
the message. If no such message exists, return *default* if it was
supplied or else raise a :exc:`KeyError` exception. The message is
represented as an instance of the appropriate format-specific
:class:`Message` subclass unless a custom message factory was specified
when the :class:`Mailbox` instance was initialized.
.. method:: popitem()
Return an arbitrary (*key*, *message*) pair, where *key* is a key and
*message* is a message representation, and delete the corresponding
message. If the mailbox is empty, raise a :exc:`KeyError` exception. The
message is represented as an instance of the appropriate format-specific
:class:`Message` subclass unless a custom message factory was specified
when the :class:`Mailbox` instance was initialized.
.. method:: update(arg)
Parameter *arg* should be a *key*-to-*message* mapping or an iterable of
(*key*, *message*) pairs. Updates the mailbox so that, for each given
*key* and *message*, the message corresponding to *key* is set to
*message* as if by using :meth:`__setitem__`. As with :meth:`__setitem__`,
each *key* must already correspond to a message in the mailbox or else a
:exc:`KeyError` exception will be raised, so in general it is incorrect
for *arg* to be a :class:`Mailbox` instance.
.. note::
Unlike with dictionaries, keyword arguments are not supported.
.. method:: flush()
Write any pending changes to the filesystem. For some :class:`Mailbox`
subclasses, changes are always written immediately and :meth:`flush` does
nothing, but you should still make a habit of calling this method.
.. method:: lock()
Acquire an exclusive advisory lock on the mailbox so that other processes
know not to modify it. An :exc:`ExternalClashError` is raised if the lock
is not available. The particular locking mechanisms used depend upon the
mailbox format. You should *always* lock the mailbox before making any
modifications to its contents.
.. method:: unlock()
Release the lock on the mailbox, if any.
.. method:: close()
Flush the mailbox, unlock it if necessary, and close any open files. For
some :class:`Mailbox` subclasses, this method does nothing.
.. _mailbox-maildir:
:class:`Maildir`
^^^^^^^^^^^^^^^^
.. class:: Maildir(dirname, factory=rfc822.Message, create=True)
A subclass of :class:`Mailbox` for mailboxes in Maildir format. Parameter
*factory* is a callable object that accepts a file-like message representation
(which behaves as if opened in binary mode) and returns a custom representation.
If *factory* is ``None``, :class:`MaildirMessage` is used as the default message
representation. If *create* is ``True``, the mailbox is created if it does not
exist.
It is for historical reasons that *factory* defaults to :class:`rfc822.Message`
and that *dirname* is named as such rather than *path*. For a :class:`Maildir`
instance that behaves like instances of other :class:`Mailbox` subclasses, set
*factory* to ``None``.
Maildir is a directory-based mailbox format invented for the qmail mail
transfer agent and now widely supported by other programs. Messages in a
Maildir mailbox are stored in separate files within a common directory
structure. This design allows Maildir mailboxes to be accessed and modified
by multiple unrelated programs without data corruption, so file locking is
unnecessary.
Maildir mailboxes contain three subdirectories, namely: :file:`tmp`,
:file:`new`, and :file:`cur`. Messages are created momentarily in the
:file:`tmp` subdirectory and then moved to the :file:`new` subdirectory to
finalize delivery. A mail user agent may subsequently move the message to the
:file:`cur` subdirectory and store information about the state of the message
in a special "info" section appended to its file name.
Folders of the style introduced by the Courier mail transfer agent are also
supported. Any subdirectory of the main mailbox is considered a folder if
``'.'`` is the first character in its name. Folder names are represented by
:class:`Maildir` without the leading ``'.'``. Each folder is itself a Maildir
mailbox but should not contain other folders. Instead, a logical nesting is
indicated using ``'.'`` to delimit levels, e.g., "Archived.2005.07".
.. note::
The Maildir specification requires the use of a colon (``':'``) in certain
message file names. However, some operating systems do not permit this
character in file names, If you wish to use a Maildir-like format on such
an operating system, you should specify another character to use
instead. The exclamation point (``'!'``) is a popular choice. For
example::
import mailbox
mailbox.Maildir.colon = '!'
The :attr:`colon` attribute may also be set on a per-instance basis.
:class:`Maildir` instances have all of the methods of :class:`Mailbox` in
addition to the following:
.. method:: list_folders()
Return a list of the names of all folders.
.. method:: get_folder(folder)
Return a :class:`Maildir` instance representing the folder whose name is
*folder*. A :exc:`NoSuchMailboxError` exception is raised if the folder
does not exist.
.. method:: add_folder(folder)
Create a folder whose name is *folder* and return a :class:`Maildir`
instance representing it.
.. method:: remove_folder(folder)
Delete the folder whose name is *folder*. If the folder contains any
messages, a :exc:`NotEmptyError` exception will be raised and the folder
will not be deleted.
.. method:: clean()
Delete temporary files from the mailbox that have not been accessed in the
last 36 hours. The Maildir specification says that mail-reading programs
should do this occasionally.
Some :class:`Mailbox` methods implemented by :class:`Maildir` deserve special
remarks:
.. method:: add(message)
__setitem__(key, message)
update(arg)
.. warning::
These methods generate unique file names based upon the current process
ID. When using multiple threads, undetected name clashes may occur and
cause corruption of the mailbox unless threads are coordinated to avoid
using these methods to manipulate the same mailbox simultaneously.
.. method:: flush()
All changes to Maildir mailboxes are immediately applied, so this method
does nothing.
.. method:: lock()
unlock()
Maildir mailboxes do not support (or require) locking, so these methods do
nothing.
.. method:: close()
:class:`Maildir` instances do not keep any open files and the underlying
mailboxes do not support locking, so this method does nothing.
.. method:: get_file(key)
Depending upon the host platform, it may not be possible to modify or
remove the underlying message while the returned file remains open.
.. seealso::
`maildir man page from qmail <http://www.qmail.org/man/man5/maildir.html>`_
The original specification of the format.
`Using maildir format <https://cr.yp.to/proto/maildir.html>`_
Notes on Maildir by its inventor. Includes an updated name-creation scheme and
details on "info" semantics.
`maildir man page from Courier <http://www.courier-mta.org/maildir.html>`_
Another specification of the format. Describes a common extension for supporting
folders.
.. _mailbox-mbox:
:class:`mbox`
^^^^^^^^^^^^^
.. class:: mbox(path, factory=None, create=True)
A subclass of :class:`Mailbox` for mailboxes in mbox format. Parameter *factory*
is a callable object that accepts a file-like message representation (which
behaves as if opened in binary mode) and returns a custom representation. If
*factory* is ``None``, :class:`mboxMessage` is used as the default message
representation. If *create* is ``True``, the mailbox is created if it does not
exist.
The mbox format is the classic format for storing mail on Unix systems. All
messages in an mbox mailbox are stored in a single file with the beginning of
each message indicated by a line whose first five characters are "From ".
Several variations of the mbox format exist to address perceived shortcomings in
the original. In the interest of compatibility, :class:`mbox` implements the
original format, which is sometimes referred to as :dfn:`mboxo`. This means that
the :mailheader:`Content-Length` header, if present, is ignored and that any
occurrences of "From " at the beginning of a line in a message body are
transformed to ">From " when storing the message, although occurrences of ">From
" are not transformed to "From " when reading the message.
Some :class:`Mailbox` methods implemented by :class:`mbox` deserve special
remarks:
.. method:: get_file(key)
Using the file after calling :meth:`flush` or :meth:`close` on the
:class:`mbox` instance may yield unpredictable results or raise an
exception.
.. method:: lock()
unlock()
Three locking mechanisms are used---dot locking and, if available, the
:c:func:`flock` and :c:func:`lockf` system calls.
.. seealso::
`mbox man page from qmail <http://www.qmail.org/man/man5/mbox.html>`_
A specification of the format and its variations.
`mbox man page from tin <http://www.tin.org/bin/man.cgi?section=5&topic=mbox>`_
Another specification of the format, with details on locking.
`Configuring Netscape Mail on Unix: Why The Content-Length Format is Bad <https://www.jwz.org/doc/content-length.html>`_
An argument for using the original mbox format rather than a variation.
`"mbox" is a family of several mutually incompatible mailbox formats <https://www.loc.gov/preservation/digital/formats/fdd/fdd000383.shtml>`_
A history of mbox variations.
.. _mailbox-mh:
:class:`MH`
^^^^^^^^^^^
.. class:: MH(path, factory=None, create=True)
A subclass of :class:`Mailbox` for mailboxes in MH format. Parameter *factory*
is a callable object that accepts a file-like message representation (which
behaves as if opened in binary mode) and returns a custom representation. If
*factory* is ``None``, :class:`MHMessage` is used as the default message
representation. If *create* is ``True``, the mailbox is created if it does not
exist.
MH is a directory-based mailbox format invented for the MH Message Handling
System, a mail user agent. Each message in an MH mailbox resides in its own
file. An MH mailbox may contain other MH mailboxes (called :dfn:`folders`) in
addition to messages. Folders may be nested indefinitely. MH mailboxes also
support :dfn:`sequences`, which are named lists used to logically group
messages without moving them to sub-folders. Sequences are defined in a file
called :file:`.mh_sequences` in each folder.
The :class:`MH` class manipulates MH mailboxes, but it does not attempt to
emulate all of :program:`mh`'s behaviors. In particular, it does not modify
and is not affected by the :file:`context` or :file:`.mh_profile` files that
are used by :program:`mh` to store its state and configuration.
:class:`MH` instances have all of the methods of :class:`Mailbox` in addition
to the following:
.. method:: list_folders()
Return a list of the names of all folders.
.. method:: get_folder(folder)
Return an :class:`MH` instance representing the folder whose name is
*folder*. A :exc:`NoSuchMailboxError` exception is raised if the folder
does not exist.
.. method:: add_folder(folder)
Create a folder whose name is *folder* and return an :class:`MH` instance
representing it.
.. method:: remove_folder(folder)
Delete the folder whose name is *folder*. If the folder contains any
messages, a :exc:`NotEmptyError` exception will be raised and the folder
will not be deleted.
.. method:: get_sequences()
Return a dictionary of sequence names mapped to key lists. If there are no
sequences, the empty dictionary is returned.
.. method:: set_sequences(sequences)
Re-define the sequences that exist in the mailbox based upon *sequences*,
a dictionary of names mapped to key lists, like returned by
:meth:`get_sequences`.
.. method:: pack()
Rename messages in the mailbox as necessary to eliminate gaps in
numbering. Entries in the sequences list are updated correspondingly.
.. note::
Already-issued keys are invalidated by this operation and should not be
subsequently used.
Some :class:`Mailbox` methods implemented by :class:`MH` deserve special
remarks:
.. method:: remove(key)
__delitem__(key)
discard(key)
These methods immediately delete the message. The MH convention of marking
a message for deletion by prepending a comma to its name is not used.
.. method:: lock()
unlock()
Three locking mechanisms are used---dot locking and, if available, the
:c:func:`flock` and :c:func:`lockf` system calls. For MH mailboxes, locking
the mailbox means locking the :file:`.mh_sequences` file and, only for the
duration of any operations that affect them, locking individual message
files.
.. method:: get_file(key)
Depending upon the host platform, it may not be possible to remove the
underlying message while the returned file remains open.
.. method:: flush()
All changes to MH mailboxes are immediately applied, so this method does
nothing.
.. method:: close()
:class:`MH` instances do not keep any open files, so this method is
equivalent to :meth:`unlock`.
.. seealso::
`nmh - Message Handling System <http://www.nongnu.org/nmh/>`_
Home page of :program:`nmh`, an updated version of the original :program:`mh`.
`MH & nmh: Email for Users & Programmers <http://rand-mh.sourceforge.net/book/>`_
A GPL-licensed book on :program:`mh` and :program:`nmh`, with some information
on the mailbox format.
.. _mailbox-babyl:
:class:`Babyl`
^^^^^^^^^^^^^^
.. class:: Babyl(path, factory=None, create=True)
A subclass of :class:`Mailbox` for mailboxes in Babyl format. Parameter
*factory* is a callable object that accepts a file-like message representation
(which behaves as if opened in binary mode) and returns a custom representation.
If *factory* is ``None``, :class:`BabylMessage` is used as the default message
representation. If *create* is ``True``, the mailbox is created if it does not
exist.
Babyl is a single-file mailbox format used by the Rmail mail user agent
included with Emacs. The beginning of a message is indicated by a line
containing the two characters Control-Underscore (``'\037'``) and Control-L
(``'\014'``). The end of a message is indicated by the start of the next
message or, in the case of the last message, a line containing a
Control-Underscore (``'\037'``) character.
Messages in a Babyl mailbox have two sets of headers, original headers and
so-called visible headers. Visible headers are typically a subset of the
original headers that have been reformatted or abridged to be more
attractive. Each message in a Babyl mailbox also has an accompanying list of
:dfn:`labels`, or short strings that record extra information about the
message, and a list of all user-defined labels found in the mailbox is kept
in the Babyl options section.
:class:`Babyl` instances have all of the methods of :class:`Mailbox` in
addition to the following:
.. method:: get_labels()
Return a list of the names of all user-defined labels used in the mailbox.
.. note::
The actual messages are inspected to determine which labels exist in
the mailbox rather than consulting the list of labels in the Babyl
options section, but the Babyl section is updated whenever the mailbox
is modified.
Some :class:`Mailbox` methods implemented by :class:`Babyl` deserve special
remarks:
.. method:: get_file(key)
In Babyl mailboxes, the headers of a message are not stored contiguously
with the body of the message. To generate a file-like representation, the
headers and body are copied together into a :class:`~StringIO.StringIO` instance
(from the :mod:`StringIO` module), which has an API identical to that of a
file. As a result, the file-like object is truly independent of the
underlying mailbox but does not save memory compared to a string
representation.
.. method:: lock()
unlock()
Three locking mechanisms are used---dot locking and, if available, the
:c:func:`flock` and :c:func:`lockf` system calls.
.. seealso::
`Format of Version 5 Babyl Files <https://quimby.gnus.org/notes/BABYL>`_
A specification of the Babyl format.
`Reading Mail with Rmail <https://www.gnu.org/software/emacs/manual/html_node/emacs/Rmail.html>`_
The Rmail manual, with some information on Babyl semantics.
.. _mailbox-mmdf:
:class:`MMDF`
^^^^^^^^^^^^^
.. class:: MMDF(path, factory=None, create=True)
A subclass of :class:`Mailbox` for mailboxes in MMDF format. Parameter *factory*
is a callable object that accepts a file-like message representation (which
behaves as if opened in binary mode) and returns a custom representation. If
*factory* is ``None``, :class:`MMDFMessage` is used as the default message
representation. If *create* is ``True``, the mailbox is created if it does not
exist.
MMDF is a single-file mailbox format invented for the Multichannel Memorandum
Distribution Facility, a mail transfer agent. Each message is in the same
form as an mbox message but is bracketed before and after by lines containing
four Control-A (``'\001'``) characters. As with the mbox format, the
beginning of each message is indicated by a line whose first five characters
are "From ", but additional occurrences of "From " are not transformed to
">From " when storing messages because the extra message separator lines
prevent mistaking such occurrences for the starts of subsequent messages.
Some :class:`Mailbox` methods implemented by :class:`MMDF` deserve special
remarks:
.. method:: get_file(key)
Using the file after calling :meth:`flush` or :meth:`close` on the
:class:`MMDF` instance may yield unpredictable results or raise an
exception.
.. method:: lock()
unlock()
Three locking mechanisms are used---dot locking and, if available, the
:c:func:`flock` and :c:func:`lockf` system calls.
.. seealso::
`mmdf man page from tin <http://www.tin.org/bin/man.cgi?section=5&topic=mmdf>`_
A specification of MMDF format from the documentation of tin, a newsreader.
`MMDF <https://en.wikipedia.org/wiki/MMDF>`_
A Wikipedia article describing the Multichannel Memorandum Distribution
Facility.
.. _mailbox-message-objects:
:class:`Message` objects
------------------------
.. class:: Message([message])
A subclass of the :mod:`email.message` module's
:class:`~email.message.Message`. Subclasses of :class:`mailbox.Message` add
mailbox-format-specific state and behavior.
If *message* is omitted, the new instance is created in a default, empty state.
If *message* is an :class:`email.message.Message` instance, its contents are
copied; furthermore, any format-specific information is converted insofar as
possible if *message* is a :class:`Message` instance. If *message* is a string
or a file, it should contain an :rfc:`2822`\ -compliant message, which is read
and parsed.
The format-specific state and behaviors offered by subclasses vary, but in
general it is only the properties that are not specific to a particular
mailbox that are supported (although presumably the properties are specific
to a particular mailbox format). For example, file offsets for single-file
mailbox formats and file names for directory-based mailbox formats are not
retained, because they are only applicable to the original mailbox. But state
such as whether a message has been read by the user or marked as important is
retained, because it applies to the message itself.
There is no requirement that :class:`Message` instances be used to represent
messages retrieved using :class:`Mailbox` instances. In some situations, the
time and memory required to generate :class:`Message` representations might
not be acceptable. For such situations, :class:`Mailbox` instances also
offer string and file-like representations, and a custom message factory may
be specified when a :class:`Mailbox` instance is initialized.
.. _mailbox-maildirmessage:
:class:`MaildirMessage`
^^^^^^^^^^^^^^^^^^^^^^^
.. class:: MaildirMessage([message])
A message with Maildir-specific behaviors. Parameter *message* has the same
meaning as with the :class:`Message` constructor.
Typically, a mail user agent application moves all of the messages in the
:file:`new` subdirectory to the :file:`cur` subdirectory after the first time
the user opens and closes the mailbox, recording that the messages are old
whether or not they've actually been read. Each message in :file:`cur` has an
"info" section added to its file name to store information about its state.
(Some mail readers may also add an "info" section to messages in
:file:`new`.) The "info" section may take one of two forms: it may contain
"2," followed by a list of standardized flags (e.g., "2,FR") or it may
contain "1," followed by so-called experimental information. Standard flags
for Maildir messages are as follows:
+------+---------+--------------------------------+
| Flag | Meaning | Explanation |
+======+=========+================================+
| D | Draft | Under composition |
+------+---------+--------------------------------+
| F | Flagged | Marked as important |
+------+---------+--------------------------------+
| P | Passed | Forwarded, resent, or bounced |
+------+---------+--------------------------------+
| R | Replied | Replied to |
+------+---------+--------------------------------+
| S | Seen | Read |
+------+---------+--------------------------------+
| T | Trashed | Marked for subsequent deletion |
+------+---------+--------------------------------+
:class:`MaildirMessage` instances offer the following methods:
.. method:: get_subdir()
Return either "new" (if the message should be stored in the :file:`new`
subdirectory) or "cur" (if the message should be stored in the :file:`cur`
subdirectory).
.. note::
A message is typically moved from :file:`new` to :file:`cur` after its
mailbox has been accessed, whether or not the message is has been
read. A message ``msg`` has been read if ``"S" in msg.get_flags()`` is
``True``.
.. method:: set_subdir(subdir)
Set the subdirectory the message should be stored in. Parameter *subdir*
must be either "new" or "cur".
.. method:: get_flags()
Return a string specifying the flags that are currently set. If the
message complies with the standard Maildir format, the result is the
concatenation in alphabetical order of zero or one occurrence of each of
``'D'``, ``'F'``, ``'P'``, ``'R'``, ``'S'``, and ``'T'``. The empty string
is returned if no flags are set or if "info" contains experimental
semantics.
.. method:: set_flags(flags)
Set the flags specified by *flags* and unset all others.
.. method:: add_flag(flag)
Set the flag(s) specified by *flag* without changing other flags. To add
more than one flag at a time, *flag* may be a string of more than one
character. The current "info" is overwritten whether or not it contains
experimental information rather than flags.
.. method:: remove_flag(flag)
Unset the flag(s) specified by *flag* without changing other flags. To
remove more than one flag at a time, *flag* maybe a string of more than
one character. If "info" contains experimental information rather than
flags, the current "info" is not modified.
.. method:: get_date()
Return the delivery date of the message as a floating-point number
representing seconds since the epoch.
.. method:: set_date(date)
Set the delivery date of the message to *date*, a floating-point number
representing seconds since the epoch.
.. method:: get_info()
Return a string containing the "info" for a message. This is useful for
accessing and modifying "info" that is experimental (i.e., not a list of
flags).
.. method:: set_info(info)
Set "info" to *info*, which should be a string.
When a :class:`MaildirMessage` instance is created based upon an
:class:`mboxMessage` or :class:`MMDFMessage` instance, the :mailheader:`Status`
and :mailheader:`X-Status` headers are omitted and the following conversions
take place:
+--------------------+----------------------------------------------+
| Resulting state | :class:`mboxMessage` or :class:`MMDFMessage` |
| | state |
+====================+==============================================+
| "cur" subdirectory | O flag |
+--------------------+----------------------------------------------+
| F flag | F flag |
+--------------------+----------------------------------------------+
| R flag | A flag |
+--------------------+----------------------------------------------+
| S flag | R flag |
+--------------------+----------------------------------------------+
| T flag | D flag |
+--------------------+----------------------------------------------+
When a :class:`MaildirMessage` instance is created based upon an
:class:`MHMessage` instance, the following conversions take place:
+-------------------------------+--------------------------+
| Resulting state | :class:`MHMessage` state |
+===============================+==========================+
| "cur" subdirectory | "unseen" sequence |
+-------------------------------+--------------------------+
| "cur" subdirectory and S flag | no "unseen" sequence |
+-------------------------------+--------------------------+
| F flag | "flagged" sequence |
+-------------------------------+--------------------------+
| R flag | "replied" sequence |
+-------------------------------+--------------------------+
When a :class:`MaildirMessage` instance is created based upon a
:class:`BabylMessage` instance, the following conversions take place:
+-------------------------------+-------------------------------+
| Resulting state | :class:`BabylMessage` state |
+===============================+===============================+
| "cur" subdirectory | "unseen" label |
+-------------------------------+-------------------------------+
| "cur" subdirectory and S flag | no "unseen" label |
+-------------------------------+-------------------------------+
| P flag | "forwarded" or "resent" label |
+-------------------------------+-------------------------------+
| R flag | "answered" label |
+-------------------------------+-------------------------------+
| T flag | "deleted" label |
+-------------------------------+-------------------------------+
.. _mailbox-mboxmessage:
:class:`mboxMessage`
^^^^^^^^^^^^^^^^^^^^
.. class:: mboxMessage([message])
A message with mbox-specific behaviors. Parameter *message* has the same meaning
as with the :class:`Message` constructor.
Messages in an mbox mailbox are stored together in a single file. The
sender's envelope address and the time of delivery are typically stored in a
line beginning with "From " that is used to indicate the start of a message,
though there is considerable variation in the exact format of this data among
mbox implementations. Flags that indicate the state of the message, such as
whether it has been read or marked as important, are typically stored in
:mailheader:`Status` and :mailheader:`X-Status` headers.
Conventional flags for mbox messages are as follows:
+------+----------+--------------------------------+
| Flag | Meaning | Explanation |
+======+==========+================================+
| R | Read | Read |
+------+----------+--------------------------------+
| O | Old | Previously detected by MUA |
+------+----------+--------------------------------+
| D | Deleted | Marked for subsequent deletion |
+------+----------+--------------------------------+
| F | Flagged | Marked as important |
+------+----------+--------------------------------+
| A | Answered | Replied to |
+------+----------+--------------------------------+
The "R" and "O" flags are stored in the :mailheader:`Status` header, and the
"D", "F", and "A" flags are stored in the :mailheader:`X-Status` header. The
flags and headers typically appear in the order mentioned.
:class:`mboxMessage` instances offer the following methods:
.. method:: get_from()
Return a string representing the "From " line that marks the start of the
message in an mbox mailbox. The leading "From " and the trailing newline
are excluded.
.. method:: set_from(from_, time_=None)
Set the "From " line to *from_*, which should be specified without a
leading "From " or trailing newline. For convenience, *time_* may be
specified and will be formatted appropriately and appended to *from_*. If
*time_* is specified, it should be a :class:`time.struct_time` instance, a
tuple suitable for passing to :meth:`time.strftime`, or ``True`` (to use
:meth:`time.gmtime`).
.. method:: get_flags()
Return a string specifying the flags that are currently set. If the
message complies with the conventional format, the result is the
concatenation in the following order of zero or one occurrence of each of
``'R'``, ``'O'``, ``'D'``, ``'F'``, and ``'A'``.
.. method:: set_flags(flags)
Set the flags specified by *flags* and unset all others. Parameter *flags*
should be the concatenation in any order of zero or more occurrences of
each of ``'R'``, ``'O'``, ``'D'``, ``'F'``, and ``'A'``.
.. method:: add_flag(flag)
Set the flag(s) specified by *flag* without changing other flags. To add
more than one flag at a time, *flag* may be a string of more than one
character.
.. method:: remove_flag(flag)
Unset the flag(s) specified by *flag* without changing other flags. To
remove more than one flag at a time, *flag* maybe a string of more than
one character.
When an :class:`mboxMessage` instance is created based upon a
:class:`MaildirMessage` instance, a "From " line is generated based upon the
:class:`MaildirMessage` instance's delivery date, and the following conversions
take place:
+-----------------+-------------------------------+
| Resulting state | :class:`MaildirMessage` state |
+=================+===============================+
| R flag | S flag |
+-----------------+-------------------------------+
| O flag | "cur" subdirectory |
+-----------------+-------------------------------+
| D flag | T flag |
+-----------------+-------------------------------+
| F flag | F flag |
+-----------------+-------------------------------+
| A flag | R flag |
+-----------------+-------------------------------+
When an :class:`mboxMessage` instance is created based upon an
:class:`MHMessage` instance, the following conversions take place:
+-------------------+--------------------------+
| Resulting state | :class:`MHMessage` state |
+===================+==========================+
| R flag and O flag | no "unseen" sequence |
+-------------------+--------------------------+
| O flag | "unseen" sequence |
+-------------------+--------------------------+
| F flag | "flagged" sequence |
+-------------------+--------------------------+
| A flag | "replied" sequence |
+-------------------+--------------------------+
When an :class:`mboxMessage` instance is created based upon a
:class:`BabylMessage` instance, the following conversions take place:
+-------------------+-----------------------------+
| Resulting state | :class:`BabylMessage` state |
+===================+=============================+
| R flag and O flag | no "unseen" label |
+-------------------+-----------------------------+
| O flag | "unseen" label |
+-------------------+-----------------------------+
| D flag | "deleted" label |
+-------------------+-----------------------------+
| A flag | "answered" label |
+-------------------+-----------------------------+
When a :class:`Message` instance is created based upon an :class:`MMDFMessage`
instance, the "From " line is copied and all flags directly correspond:
+-----------------+----------------------------+
| Resulting state | :class:`MMDFMessage` state |
+=================+============================+
| R flag | R flag |
+-----------------+----------------------------+
| O flag | O flag |
+-----------------+----------------------------+
| D flag | D flag |
+-----------------+----------------------------+
| F flag | F flag |
+-----------------+----------------------------+
| A flag | A flag |
+-----------------+----------------------------+
.. _mailbox-mhmessage:
:class:`MHMessage`
^^^^^^^^^^^^^^^^^^
.. class:: MHMessage([message])
A message with MH-specific behaviors. Parameter *message* has the same meaning
as with the :class:`Message` constructor.
MH messages do not support marks or flags in the traditional sense, but they
do support sequences, which are logical groupings of arbitrary messages. Some
mail reading programs (although not the standard :program:`mh` and
:program:`nmh`) use sequences in much the same way flags are used with other
formats, as follows:
+----------+------------------------------------------+
| Sequence | Explanation |
+==========+==========================================+
| unseen | Not read, but previously detected by MUA |
+----------+------------------------------------------+
| replied | Replied to |
+----------+------------------------------------------+
| flagged | Marked as important |
+----------+------------------------------------------+
:class:`MHMessage` instances offer the following methods:
.. method:: get_sequences()
Return a list of the names of sequences that include this message.
.. method:: set_sequences(sequences)
Set the list of sequences that include this message.
.. method:: add_sequence(sequence)
Add *sequence* to the list of sequences that include this message.
.. method:: remove_sequence(sequence)
Remove *sequence* from the list of sequences that include this message.
When an :class:`MHMessage` instance is created based upon a
:class:`MaildirMessage` instance, the following conversions take place:
+--------------------+-------------------------------+
| Resulting state | :class:`MaildirMessage` state |
+====================+===============================+
| "unseen" sequence | no S flag |
+--------------------+-------------------------------+
| "replied" sequence | R flag |
+--------------------+-------------------------------+
| "flagged" sequence | F flag |
+--------------------+-------------------------------+
When an :class:`MHMessage` instance is created based upon an
:class:`mboxMessage` or :class:`MMDFMessage` instance, the :mailheader:`Status`
and :mailheader:`X-Status` headers are omitted and the following conversions
take place:
+--------------------+----------------------------------------------+
| Resulting state | :class:`mboxMessage` or :class:`MMDFMessage` |
| | state |
+====================+==============================================+
| "unseen" sequence | no R flag |
+--------------------+----------------------------------------------+
| "replied" sequence | A flag |
+--------------------+----------------------------------------------+
| "flagged" sequence | F flag |
+--------------------+----------------------------------------------+
When an :class:`MHMessage` instance is created based upon a
:class:`BabylMessage` instance, the following conversions take place:
+--------------------+-----------------------------+
| Resulting state | :class:`BabylMessage` state |
+====================+=============================+
| "unseen" sequence | "unseen" label |
+--------------------+-----------------------------+
| "replied" sequence | "answered" label |
+--------------------+-----------------------------+
.. _mailbox-babylmessage:
:class:`BabylMessage`
^^^^^^^^^^^^^^^^^^^^^
.. class:: BabylMessage([message])
A message with Babyl-specific behaviors. Parameter *message* has the same
meaning as with the :class:`Message` constructor.
Certain message labels, called :dfn:`attributes`, are defined by convention
to have special meanings. The attributes are as follows:
+-----------+------------------------------------------+
| Label | Explanation |
+===========+==========================================+
| unseen | Not read, but previously detected by MUA |
+-----------+------------------------------------------+
| deleted | Marked for subsequent deletion |
+-----------+------------------------------------------+
| filed | Copied to another file or mailbox |
+-----------+------------------------------------------+
| answered | Replied to |
+-----------+------------------------------------------+
| forwarded | Forwarded |
+-----------+------------------------------------------+
| edited | Modified by the user |
+-----------+------------------------------------------+
| resent | Resent |
+-----------+------------------------------------------+
By default, Rmail displays only visible headers. The :class:`BabylMessage`
class, though, uses the original headers because they are more
complete. Visible headers may be accessed explicitly if desired.
:class:`BabylMessage` instances offer the following methods:
.. method:: get_labels()
Return a list of labels on the message.
.. method:: set_labels(labels)
Set the list of labels on the message to *labels*.
.. method:: add_label(label)
Add *label* to the list of labels on the message.
.. method:: remove_label(label)
Remove *label* from the list of labels on the message.
.. method:: get_visible()
Return an :class:`Message` instance whose headers are the message's
visible headers and whose body is empty.
.. method:: set_visible(visible)
Set the message's visible headers to be the same as the headers in
*message*. Parameter *visible* should be a :class:`Message` instance, an
:class:`email.message.Message` instance, a string, or a file-like object
(which should be open in text mode).
.. method:: update_visible()
When a :class:`BabylMessage` instance's original headers are modified, the
visible headers are not automatically modified to correspond. This method
updates the visible headers as follows: each visible header with a
corresponding original header is set to the value of the original header,
each visible header without a corresponding original header is removed,
and any of :mailheader:`Date`, :mailheader:`From`, :mailheader:`Reply-To`,
:mailheader:`To`, :mailheader:`CC`, and :mailheader:`Subject` that are
present in the original headers but not the visible headers are added to
the visible headers.
When a :class:`BabylMessage` instance is created based upon a
:class:`MaildirMessage` instance, the following conversions take place:
+-------------------+-------------------------------+
| Resulting state | :class:`MaildirMessage` state |
+===================+===============================+
| "unseen" label | no S flag |
+-------------------+-------------------------------+
| "deleted" label | T flag |
+-------------------+-------------------------------+
| "answered" label | R flag |
+-------------------+-------------------------------+
| "forwarded" label | P flag |
+-------------------+-------------------------------+
When a :class:`BabylMessage` instance is created based upon an
:class:`mboxMessage` or :class:`MMDFMessage` instance, the :mailheader:`Status`
and :mailheader:`X-Status` headers are omitted and the following conversions
take place:
+------------------+----------------------------------------------+
| Resulting state | :class:`mboxMessage` or :class:`MMDFMessage` |
| | state |
+==================+==============================================+
| "unseen" label | no R flag |
+------------------+----------------------------------------------+
| "deleted" label | D flag |
+------------------+----------------------------------------------+
| "answered" label | A flag |
+------------------+----------------------------------------------+
When a :class:`BabylMessage` instance is created based upon an
:class:`MHMessage` instance, the following conversions take place:
+------------------+--------------------------+
| Resulting state | :class:`MHMessage` state |
+==================+==========================+
| "unseen" label | "unseen" sequence |
+------------------+--------------------------+
| "answered" label | "replied" sequence |
+------------------+--------------------------+
.. _mailbox-mmdfmessage:
:class:`MMDFMessage`
^^^^^^^^^^^^^^^^^^^^
.. class:: MMDFMessage([message])
A message with MMDF-specific behaviors. Parameter *message* has the same meaning
as with the :class:`Message` constructor.
As with message in an mbox mailbox, MMDF messages are stored with the
sender's address and the delivery date in an initial line beginning with
"From ". Likewise, flags that indicate the state of the message are
typically stored in :mailheader:`Status` and :mailheader:`X-Status` headers.
Conventional flags for MMDF messages are identical to those of mbox message
and are as follows:
+------+----------+--------------------------------+
| Flag | Meaning | Explanation |
+======+==========+================================+
| R | Read | Read |
+------+----------+--------------------------------+
| O | Old | Previously detected by MUA |
+------+----------+--------------------------------+
| D | Deleted | Marked for subsequent deletion |
+------+----------+--------------------------------+
| F | Flagged | Marked as important |
+------+----------+--------------------------------+
| A | Answered | Replied to |
+------+----------+--------------------------------+
The "R" and "O" flags are stored in the :mailheader:`Status` header, and the
"D", "F", and "A" flags are stored in the :mailheader:`X-Status` header. The
flags and headers typically appear in the order mentioned.
:class:`MMDFMessage` instances offer the following methods, which are
identical to those offered by :class:`mboxMessage`:
.. method:: get_from()
Return a string representing the "From " line that marks the start of the
message in an mbox mailbox. The leading "From " and the trailing newline
are excluded.
.. method:: set_from(from_, time_=None)
Set the "From " line to *from_*, which should be specified without a
leading "From " or trailing newline. For convenience, *time_* may be
specified and will be formatted appropriately and appended to *from_*. If
*time_* is specified, it should be a :class:`time.struct_time` instance, a
tuple suitable for passing to :meth:`time.strftime`, or ``True`` (to use
:meth:`time.gmtime`).
.. method:: get_flags()
Return a string specifying the flags that are currently set. If the
message complies with the conventional format, the result is the
concatenation in the following order of zero or one occurrence of each of
``'R'``, ``'O'``, ``'D'``, ``'F'``, and ``'A'``.
.. method:: set_flags(flags)
Set the flags specified by *flags* and unset all others. Parameter *flags*
should be the concatenation in any order of zero or more occurrences of
each of ``'R'``, ``'O'``, ``'D'``, ``'F'``, and ``'A'``.
.. method:: add_flag(flag)
Set the flag(s) specified by *flag* without changing other flags. To add
more than one flag at a time, *flag* may be a string of more than one
character.
.. method:: remove_flag(flag)
Unset the flag(s) specified by *flag* without changing other flags. To
remove more than one flag at a time, *flag* maybe a string of more than
one character.
When an :class:`MMDFMessage` instance is created based upon a
:class:`MaildirMessage` instance, a "From " line is generated based upon the
:class:`MaildirMessage` instance's delivery date, and the following conversions
take place:
+-----------------+-------------------------------+
| Resulting state | :class:`MaildirMessage` state |
+=================+===============================+
| R flag | S flag |
+-----------------+-------------------------------+
| O flag | "cur" subdirectory |
+-----------------+-------------------------------+
| D flag | T flag |
+-----------------+-------------------------------+
| F flag | F flag |
+-----------------+-------------------------------+
| A flag | R flag |
+-----------------+-------------------------------+
When an :class:`MMDFMessage` instance is created based upon an
:class:`MHMessage` instance, the following conversions take place:
+-------------------+--------------------------+
| Resulting state | :class:`MHMessage` state |
+===================+==========================+
| R flag and O flag | no "unseen" sequence |
+-------------------+--------------------------+
| O flag | "unseen" sequence |
+-------------------+--------------------------+
| F flag | "flagged" sequence |
+-------------------+--------------------------+
| A flag | "replied" sequence |
+-------------------+--------------------------+
When an :class:`MMDFMessage` instance is created based upon a
:class:`BabylMessage` instance, the following conversions take place:
+-------------------+-----------------------------+
| Resulting state | :class:`BabylMessage` state |
+===================+=============================+
| R flag and O flag | no "unseen" label |
+-------------------+-----------------------------+
| O flag | "unseen" label |
+-------------------+-----------------------------+
| D flag | "deleted" label |
+-------------------+-----------------------------+
| A flag | "answered" label |
+-------------------+-----------------------------+
When an :class:`MMDFMessage` instance is created based upon an
:class:`mboxMessage` instance, the "From " line is copied and all flags directly
correspond:
+-----------------+----------------------------+
| Resulting state | :class:`mboxMessage` state |
+=================+============================+
| R flag | R flag |
+-----------------+----------------------------+
| O flag | O flag |
+-----------------+----------------------------+
| D flag | D flag |
+-----------------+----------------------------+
| F flag | F flag |
+-----------------+----------------------------+
| A flag | A flag |
+-----------------+----------------------------+
Exceptions
----------
The following exception classes are defined in the :mod:`mailbox` module:
.. exception:: Error()
The based class for all other module-specific exceptions.
.. exception:: NoSuchMailboxError()
Raised when a mailbox is expected but is not found, such as when instantiating a
:class:`Mailbox` subclass with a path that does not exist (and with the *create*
parameter set to ``False``), or when opening a folder that does not exist.
.. exception:: NotEmptyError()
Raised when a mailbox is not empty but is expected to be, such as when deleting
a folder that contains messages.
.. exception:: ExternalClashError()
Raised when some mailbox-related condition beyond the control of the program
causes it to be unable to proceed, such as when failing to acquire a lock that
another program already holds a lock, or when a uniquely-generated file name
already exists.
.. exception:: FormatError()
Raised when the data in a file cannot be parsed, such as when an :class:`MH`
instance attempts to read a corrupted :file:`.mh_sequences` file.
.. _mailbox-deprecated:
Deprecated classes and methods
------------------------------
.. deprecated:: 2.6
Older versions of the :mod:`mailbox` module do not support modification of
mailboxes, such as adding or removing message, and do not provide classes to
represent format-specific message properties. For backward compatibility, the
older mailbox classes are still available, but the newer classes should be used
in preference to them. The old classes have been removed in Python 3.
Older mailbox objects support only iteration and provide a single public method:
.. method:: oldmailbox.next()
Return the next message in the mailbox, created with the optional *factory*
argument passed into the mailbox object's constructor. By default this is an
:class:`rfc822.Message` object (see the :mod:`rfc822` module). Depending on the
mailbox implementation the *fp* attribute of this object may be a true file
object or a class instance simulating a file object, taking care of things like
message boundaries if multiple mail messages are contained in a single file,
etc. If no more messages are available, this method returns ``None``.
Most of the older mailbox classes have names that differ from the current
mailbox class names, except for :class:`Maildir`. For this reason, the new
:class:`Maildir` class defines a :meth:`!next` method and its constructor differs
slightly from those of the other new mailbox classes.
The older mailbox classes whose names are not the same as their newer
counterparts are as follows:
.. class:: UnixMailbox(fp[, factory])
Access to a classic Unix-style mailbox, where all messages are contained in a
single file and separated by ``From`` (a.k.a. ``From_``) lines. The file object
*fp* points to the mailbox file. The optional *factory* parameter is a callable
that should create new message objects. *factory* is called with one argument,
*fp* by the :meth:`!next` method of the mailbox object. The default is the
:class:`rfc822.Message` class (see the :mod:`rfc822` module -- and the note
below).
.. note::
For reasons of this module's internal implementation, you will probably want to
open the *fp* object in binary mode. This is especially important on Windows.
For maximum portability, messages in a Unix-style mailbox are separated by any
line that begins exactly with the string ``'From '`` (note the trailing space)
if preceded by exactly two newlines. Because of the wide-range of variations in
practice, nothing else on the ``From_`` line should be considered. However, the
current implementation doesn't check for the leading two newlines. This is
usually fine for most applications.
The :class:`UnixMailbox` class implements a more strict version of ``From_``
line checking, using a regular expression that usually correctly matched
``From_`` delimiters. It considers delimiter line to be separated by ``From
name time`` lines. For maximum portability, use the
:class:`PortableUnixMailbox` class instead. This class is identical to
:class:`UnixMailbox` except that individual messages are separated by only
``From`` lines.
.. class:: PortableUnixMailbox(fp[, factory])
A less-strict version of :class:`UnixMailbox`, which considers only the ``From``
at the beginning of the line separating messages. The "*name* *time*" portion
of the From line is ignored, to protect against some variations that are
observed in practice. This works since lines in the message which begin with
``'From '`` are quoted by mail handling software at delivery-time.
.. class:: MmdfMailbox(fp[, factory])
Access an MMDF-style mailbox, where all messages are contained in a single file
and separated by lines consisting of 4 control-A characters. The file object
*fp* points to the mailbox file. Optional *factory* is as with the
:class:`UnixMailbox` class.
.. class:: MHMailbox(dirname[, factory])
Access an MH mailbox, a directory with each message in a separate file with a
numeric name. The name of the mailbox directory is passed in *dirname*.
*factory* is as with the :class:`UnixMailbox` class.
.. class:: BabylMailbox(fp[, factory])
Access a Babyl mailbox, which is similar to an MMDF mailbox. In Babyl format,
each message has two sets of headers, the *original* headers and the *visible*
headers. The original headers appear before a line containing only ``'*** EOOH
***'`` (End-Of-Original-Headers) and the visible headers appear after the
``EOOH`` line. Babyl-compliant mail readers will show you only the visible
headers, and :class:`BabylMailbox` objects will return messages containing only
the visible headers. You'll have to do your own parsing of the mailbox file to
get at the original headers. Mail messages start with the EOOH line and end
with a line containing only ``'\037\014'``. *factory* is as with the
:class:`UnixMailbox` class.
If you wish to use the older mailbox classes with the :mod:`email` module rather
than the deprecated :mod:`rfc822` module, you can do so as follows::
import email
import email.Errors
import mailbox
def msgfactory(fp):
try:
return email.message_from_file(fp)
except email.Errors.MessageParseError:
# Don't return None since that will
# stop the mailbox iterator
return ''
mbox = mailbox.UnixMailbox(fp, msgfactory)
Alternatively, if you know your mailbox contains only well-formed MIME messages,
you can simplify this to::
import email
import mailbox
mbox = mailbox.UnixMailbox(fp, email.message_from_file)
.. _mailbox-examples:
Examples
--------
A simple example of printing the subjects of all messages in a mailbox that seem
interesting::
import mailbox
for message in mailbox.mbox('~/mbox'):
subject = message['subject'] # Could possibly be None.
if subject and 'python' in subject.lower():
print subject
To copy all mail from a Babyl mailbox to an MH mailbox, converting all of the
format-specific information that can be converted::
import mailbox
destination = mailbox.MH('~/Mail')
destination.lock()
for message in mailbox.Babyl('~/RMAIL'):
destination.add(mailbox.MHMessage(message))
destination.flush()
destination.unlock()
This example sorts mail from several mailing lists into different mailboxes,
being careful to avoid mail corruption due to concurrent modification by other
programs, mail loss due to interruption of the program, or premature termination
due to malformed messages in the mailbox::
import mailbox
import email.errors
list_names = ('python-list', 'python-dev', 'python-bugs')
boxes = dict((name, mailbox.mbox('~/email/%s' % name)) for name in list_names)
inbox = mailbox.Maildir('~/Maildir', factory=None)
for key in inbox.iterkeys():
try:
message = inbox[key]
except email.errors.MessageParseError:
continue # The message is malformed. Just leave it.
for name in list_names:
list_id = message['list-id']
if list_id and name in list_id:
# Get mailbox to use
box = boxes[name]
# Write copy to disk before removing original.
# If there's a crash, you might duplicate a message, but
# that's better than losing a message completely.
box.lock()
box.add(message)
box.flush()
box.unlock()
# Remove original message
inbox.lock()
inbox.discard(key)
inbox.flush()
inbox.unlock()
break # Found destination, so stop looking.
for box in boxes.itervalues():
box.close()
PK %�\�,��[ [ % html/_sources/library/mailcap.rst.txtnu �[��� :mod:`mailcap` --- Mailcap file handling
========================================
.. module:: mailcap
:synopsis: Mailcap file handling.
**Source code:** :source:`Lib/mailcap.py`
--------------
Mailcap files are used to configure how MIME-aware applications such as mail
readers and Web browsers react to files with different MIME types. (The name
"mailcap" is derived from the phrase "mail capability".) For example, a mailcap
file might contain a line like ``video/mpeg; xmpeg %s``. Then, if the user
encounters an email message or Web document with the MIME type
:mimetype:`video/mpeg`, ``%s`` will be replaced by a filename (usually one
belonging to a temporary file) and the :program:`xmpeg` program can be
automatically started to view the file.
The mailcap format is documented in :rfc:`1524`, "A User Agent Configuration
Mechanism For Multimedia Mail Format Information," but is not an Internet
standard. However, mailcap files are supported on most Unix systems.
.. function:: findmatch(caps, MIMEtype[, key[, filename[, plist]]])
Return a 2-tuple; the first element is a string containing the command line to
be executed (which can be passed to :func:`os.system`), and the second element
is the mailcap entry for a given MIME type. If no matching MIME type can be
found, ``(None, None)`` is returned.
*key* is the name of the field desired, which represents the type of activity to
be performed; the default value is 'view', since in the most common case you
simply want to view the body of the MIME-typed data. Other possible values
might be 'compose' and 'edit', if you wanted to create a new body of the given
MIME type or alter the existing body data. See :rfc:`1524` for a complete list
of these fields.
*filename* is the filename to be substituted for ``%s`` in the command line; the
default value is ``'/dev/null'`` which is almost certainly not what you want, so
usually you'll override it by specifying a filename.
*plist* can be a list containing named parameters; the default value is simply
an empty list. Each entry in the list must be a string containing the parameter
name, an equals sign (``'='``), and the parameter's value. Mailcap entries can
contain named parameters like ``%{foo}``, which will be replaced by the value
of the parameter named 'foo'. For example, if the command line ``showpartial
%{id} %{number} %{total}`` was in a mailcap file, and *plist* was set to
``['id=1', 'number=2', 'total=3']``, the resulting command line would be
``'showpartial 1 2 3'``.
In a mailcap file, the "test" field can optionally be specified to test some
external condition (such as the machine architecture, or the window system in
use) to determine whether or not the mailcap line applies. :func:`findmatch`
will automatically check such conditions and skip the entry if the check fails.
.. function:: getcaps()
Returns a dictionary mapping MIME types to a list of mailcap file entries. This
dictionary must be passed to the :func:`findmatch` function. An entry is stored
as a list of dictionaries, but it shouldn't be necessary to know the details of
this representation.
The information is derived from all of the mailcap files found on the system.
Settings in the user's mailcap file :file:`$HOME/.mailcap` will override
settings in the system mailcap files :file:`/etc/mailcap`,
:file:`/usr/etc/mailcap`, and :file:`/usr/local/etc/mailcap`.
An example usage::
>>> import mailcap
>>> d = mailcap.getcaps()
>>> mailcap.findmatch(d, 'video/mpeg', filename='tmp1223')
('xmpeg tmp1223', {'view': 'xmpeg %s'})
PK %�\Z� �� � $ html/_sources/library/markup.rst.txtnu �[��� .. _markup:
**********************************
Structured Markup Processing Tools
**********************************
Python supports a variety of modules to work with various forms of structured
data markup. This includes modules to work with the Standard Generalized Markup
Language (SGML) and the Hypertext Markup Language (HTML), and several interfaces
for working with the Extensible Markup Language (XML).
It is important to note that modules in the :mod:`xml` package require that
there be at least one SAX-compliant XML parser available. Starting with Python
2.3, the Expat parser is included with Python, so the :mod:`xml.parsers.expat`
module will always be available. You may still want to be aware of the `PyXML
add-on package <http://pyxml.sourceforge.net/>`_; that package provides an
extended set of XML libraries for Python.
The documentation for the :mod:`xml.dom` and :mod:`xml.sax` packages are the
definition of the Python bindings for the DOM and SAX interfaces.
.. toctree::
htmlparser.rst
sgmllib.rst
htmllib.rst
xml.rst
xml.etree.elementtree.rst
xml.dom.rst
xml.dom.minidom.rst
xml.dom.pulldom.rst
xml.sax.rst
xml.sax.handler.rst
xml.sax.utils.rst
xml.sax.reader.rst
pyexpat.rst
PK %�\\��-9 9 % html/_sources/library/marshal.rst.txtnu �[���
:mod:`marshal` --- Internal Python object serialization
=======================================================
.. module:: marshal
:synopsis: Convert Python objects to streams of bytes and back (with different
constraints).
This module contains functions that can read and write Python values in a binary
format. The format is specific to Python, but independent of machine
architecture issues (e.g., you can write a Python value to a file on a PC,
transport the file to a Sun, and read it back there). Details of the format are
undocumented on purpose; it may change between Python versions (although it
rarely does). [#]_
.. index::
module: pickle
module: shelve
This is not a general "persistence" module. For general persistence and
transfer of Python objects through RPC calls, see the modules :mod:`pickle` and
:mod:`shelve`. The :mod:`marshal` module exists mainly to support reading and
writing the "pseudo-compiled" code for Python modules of :file:`.pyc` files.
Therefore, the Python maintainers reserve the right to modify the marshal format
in backward incompatible ways should the need arise. If you're serializing and
de-serializing Python objects, use the :mod:`pickle` module instead -- the
performance is comparable, version independence is guaranteed, and pickle
supports a substantially wider range of objects than marshal.
.. warning::
The :mod:`marshal` module is not intended to be secure against erroneous or
maliciously constructed data. Never unmarshal data received from an
untrusted or unauthenticated source.
.. index:: object; code, code object
Not all Python object types are supported; in general, only objects whose value
is independent from a particular invocation of Python can be written and read by
this module. The following types are supported: booleans, integers, long
integers, floating point numbers, complex numbers, strings, Unicode objects,
tuples, lists, sets, frozensets, dictionaries, and code objects, where it should
be understood that tuples, lists, sets, frozensets and dictionaries are only
supported as long as the values contained therein are themselves supported; and
recursive lists, sets and dictionaries should not be written (they will cause
infinite loops). The singletons :const:`None`, :const:`Ellipsis` and
:exc:`StopIteration` can also be marshalled and unmarshalled.
.. warning::
On machines where C's ``long int`` type has more than 32 bits (such as the
DEC Alpha), it is possible to create plain Python integers that are longer
than 32 bits. If such an integer is marshaled and read back in on a machine
where C's ``long int`` type has only 32 bits, a Python long integer object
is returned instead. While of a different type, the numeric value is the
same. (This behavior is new in Python 2.2. In earlier versions, all but the
least-significant 32 bits of the value were lost, and a warning message was
printed.)
There are functions that read/write files as well as functions operating on
strings.
The module defines these functions:
.. function:: dump(value, file[, version])
Write the value on the open file. The value must be a supported type. The
file must be an open file object such as ``sys.stdout`` or returned by
:func:`open` or :func:`os.popen`. It may not be a wrapper such as
TemporaryFile on Windows. It must be opened in binary mode (``'wb'``
or ``'w+b'``).
If the value has (or contains an object that has) an unsupported type, a
:exc:`ValueError` exception is raised --- but garbage data will also be written
to the file. The object will not be properly read back by :func:`load`.
.. versionadded:: 2.4
The *version* argument indicates the data format that ``dump`` should use
(see below).
.. function:: load(file)
Read one value from the open file and return it. If no valid value is read
(e.g. because the data has a different Python version's incompatible marshal
format), raise :exc:`EOFError`, :exc:`ValueError` or :exc:`TypeError`. The
file must be an open file object opened in binary mode (``'rb'`` or
``'r+b'``).
.. note::
If an object containing an unsupported type was marshalled with :func:`dump`,
:func:`load` will substitute ``None`` for the unmarshallable type.
.. function:: dumps(value[, version])
Return the string that would be written to a file by ``dump(value, file)``. The
value must be a supported type. Raise a :exc:`ValueError` exception if value
has (or contains an object that has) an unsupported type.
.. versionadded:: 2.4
The *version* argument indicates the data format that ``dumps`` should use
(see below).
.. function:: loads(string)
Convert the string to a value. If no valid value is found, raise
:exc:`EOFError`, :exc:`ValueError` or :exc:`TypeError`. Extra characters in the
string are ignored.
In addition, the following constants are defined:
.. data:: version
Indicates the format that the module uses. Version 0 is the historical format,
version 1 (added in Python 2.4) shares interned strings and version 2 (added in
Python 2.5) uses a binary format for floating point numbers. The current version
is 2.
.. versionadded:: 2.4
.. rubric:: Footnotes
.. [#] The name of this module stems from a bit of terminology used by the designers of
Modula-3 (amongst others), who use the term "marshalling" for shipping of data
around in a self-contained form. Strictly speaking, "to marshal" means to
convert some data from internal to external form (in an RPC buffer for instance)
and "unmarshalling" for the reverse process.
PK %�\Jg��* �* " html/_sources/library/math.rst.txtnu �[���
:mod:`math` --- Mathematical functions
======================================
.. module:: math
:synopsis: Mathematical functions (sin() etc.).
.. testsetup::
from math import fsum
This module is always available. It provides access to the mathematical
functions defined by the C standard.
These functions cannot be used with complex numbers; use the functions of the
same name from the :mod:`cmath` module if you require support for complex
numbers. The distinction between functions which support complex numbers and
those which don't is made since most users do not want to learn quite as much
mathematics as required to understand complex numbers. Receiving an exception
instead of a complex result allows earlier detection of the unexpected complex
number used as a parameter, so that the programmer can determine how and why it
was generated in the first place.
The following functions are provided by this module. Except when explicitly
noted otherwise, all return values are floats.
Number-theoretic and representation functions
---------------------------------------------
.. function:: ceil(x)
Return the ceiling of *x* as a float, the smallest integer value greater than or
equal to *x*.
.. function:: copysign(x, y)
Return *x* with the sign of *y*. On a platform that supports
signed zeros, ``copysign(1.0, -0.0)`` returns *-1.0*.
.. versionadded:: 2.6
.. function:: fabs(x)
Return the absolute value of *x*.
.. function:: factorial(x)
Return *x* factorial. Raises :exc:`ValueError` if *x* is not integral or
is negative.
.. versionadded:: 2.6
.. function:: floor(x)
Return the floor of *x* as a float, the largest integer value less than or equal
to *x*.
.. function:: fmod(x, y)
Return ``fmod(x, y)``, as defined by the platform C library. Note that the
Python expression ``x % y`` may not return the same result. The intent of the C
standard is that ``fmod(x, y)`` be exactly (mathematically; to infinite
precision) equal to ``x - n*y`` for some integer *n* such that the result has
the same sign as *x* and magnitude less than ``abs(y)``. Python's ``x % y``
returns a result with the sign of *y* instead, and may not be exactly computable
for float arguments. For example, ``fmod(-1e-100, 1e100)`` is ``-1e-100``, but
the result of Python's ``-1e-100 % 1e100`` is ``1e100-1e-100``, which cannot be
represented exactly as a float, and rounds to the surprising ``1e100``. For
this reason, function :func:`fmod` is generally preferred when working with
floats, while Python's ``x % y`` is preferred when working with integers.
.. function:: frexp(x)
Return the mantissa and exponent of *x* as the pair ``(m, e)``. *m* is a float
and *e* is an integer such that ``x == m * 2**e`` exactly. If *x* is zero,
returns ``(0.0, 0)``, otherwise ``0.5 <= abs(m) < 1``. This is used to "pick
apart" the internal representation of a float in a portable way.
.. function:: fsum(iterable)
Return an accurate floating point sum of values in the iterable. Avoids
loss of precision by tracking multiple intermediate partial sums::
>>> sum([.1, .1, .1, .1, .1, .1, .1, .1, .1, .1])
0.9999999999999999
>>> fsum([.1, .1, .1, .1, .1, .1, .1, .1, .1, .1])
1.0
The algorithm's accuracy depends on IEEE-754 arithmetic guarantees and the
typical case where the rounding mode is half-even. On some non-Windows
builds, the underlying C library uses extended precision addition and may
occasionally double-round an intermediate sum causing it to be off in its
least significant bit.
For further discussion and two alternative approaches, see the `ASPN cookbook
recipes for accurate floating point summation
<https://code.activestate.com/recipes/393090/>`_\.
.. versionadded:: 2.6
.. function:: isinf(x)
Check if the float *x* is positive or negative infinity.
.. versionadded:: 2.6
.. function:: isnan(x)
Check if the float *x* is a NaN (not a number). For more information
on NaNs, see the IEEE 754 standards.
.. versionadded:: 2.6
.. function:: ldexp(x, i)
Return ``x * (2**i)``. This is essentially the inverse of function
:func:`frexp`.
.. function:: modf(x)
Return the fractional and integer parts of *x*. Both results carry the sign
of *x* and are floats.
.. function:: trunc(x)
Return the :class:`~numbers.Real` value *x* truncated to an
:class:`~numbers.Integral` (usually a long integer). Uses the
``__trunc__`` method.
.. versionadded:: 2.6
Note that :func:`frexp` and :func:`modf` have a different call/return pattern
than their C equivalents: they take a single argument and return a pair of
values, rather than returning their second return value through an 'output
parameter' (there is no such thing in Python).
For the :func:`ceil`, :func:`floor`, and :func:`modf` functions, note that *all*
floating-point numbers of sufficiently large magnitude are exact integers.
Python floats typically carry no more than 53 bits of precision (the same as the
platform C double type), in which case any float *x* with ``abs(x) >= 2**52``
necessarily has no fractional bits.
Power and logarithmic functions
-------------------------------
.. function:: exp(x)
Return ``e**x``.
.. function:: expm1(x)
Return ``e**x - 1``. For small floats *x*, the subtraction in
``exp(x) - 1`` can result in a significant loss of precision; the
:func:`expm1` function provides a way to compute this quantity to
full precision::
>>> from math import exp, expm1
>>> exp(1e-5) - 1 # gives result accurate to 11 places
1.0000050000069649e-05
>>> expm1(1e-5) # result accurate to full precision
1.0000050000166668e-05
.. versionadded:: 2.7
.. function:: log(x[, base])
With one argument, return the natural logarithm of *x* (to base *e*).
With two arguments, return the logarithm of *x* to the given *base*,
calculated as ``log(x)/log(base)``.
.. versionchanged:: 2.3
*base* argument added.
.. function:: log1p(x)
Return the natural logarithm of *1+x* (base *e*). The
result is calculated in a way which is accurate for *x* near zero.
.. versionadded:: 2.6
.. function:: log10(x)
Return the base-10 logarithm of *x*. This is usually more accurate
than ``log(x, 10)``.
.. function:: pow(x, y)
Return ``x`` raised to the power ``y``. Exceptional cases follow
Annex 'F' of the C99 standard as far as possible. In particular,
``pow(1.0, x)`` and ``pow(x, 0.0)`` always return ``1.0``, even
when ``x`` is a zero or a NaN. If both ``x`` and ``y`` are finite,
``x`` is negative, and ``y`` is not an integer then ``pow(x, y)``
is undefined, and raises :exc:`ValueError`.
Unlike the built-in ``**`` operator, :func:`math.pow` converts both
its arguments to type :class:`float`. Use ``**`` or the built-in
:func:`pow` function for computing exact integer powers.
.. versionchanged:: 2.6
The outcome of ``1**nan`` and ``nan**0`` was undefined.
.. function:: sqrt(x)
Return the square root of *x*.
Trigonometric functions
-----------------------
.. function:: acos(x)
Return the arc cosine of *x*, in radians.
.. function:: asin(x)
Return the arc sine of *x*, in radians.
.. function:: atan(x)
Return the arc tangent of *x*, in radians.
.. function:: atan2(y, x)
Return ``atan(y / x)``, in radians. The result is between ``-pi`` and ``pi``.
The vector in the plane from the origin to point ``(x, y)`` makes this angle
with the positive X axis. The point of :func:`atan2` is that the signs of both
inputs are known to it, so it can compute the correct quadrant for the angle.
For example, ``atan(1)`` and ``atan2(1, 1)`` are both ``pi/4``, but ``atan2(-1,
-1)`` is ``-3*pi/4``.
.. function:: cos(x)
Return the cosine of *x* radians.
.. function:: hypot(x, y)
Return the Euclidean norm, ``sqrt(x*x + y*y)``. This is the length of the vector
from the origin to point ``(x, y)``.
.. function:: sin(x)
Return the sine of *x* radians.
.. function:: tan(x)
Return the tangent of *x* radians.
Angular conversion
------------------
.. function:: degrees(x)
Convert angle *x* from radians to degrees.
.. function:: radians(x)
Convert angle *x* from degrees to radians.
Hyperbolic functions
--------------------
.. function:: acosh(x)
Return the inverse hyperbolic cosine of *x*.
.. versionadded:: 2.6
.. function:: asinh(x)
Return the inverse hyperbolic sine of *x*.
.. versionadded:: 2.6
.. function:: atanh(x)
Return the inverse hyperbolic tangent of *x*.
.. versionadded:: 2.6
.. function:: cosh(x)
Return the hyperbolic cosine of *x*.
.. function:: sinh(x)
Return the hyperbolic sine of *x*.
.. function:: tanh(x)
Return the hyperbolic tangent of *x*.
Special functions
-----------------
.. function:: erf(x)
Return the error function at *x*.
.. versionadded:: 2.7
.. function:: erfc(x)
Return the complementary error function at *x*.
.. versionadded:: 2.7
.. function:: gamma(x)
Return the Gamma function at *x*.
.. versionadded:: 2.7
.. function:: lgamma(x)
Return the natural logarithm of the absolute value of the Gamma
function at *x*.
.. versionadded:: 2.7
Constants
---------
.. data:: pi
The mathematical constant π = 3.141592..., to available precision.
.. data:: e
The mathematical constant e = 2.718281..., to available precision.
.. impl-detail::
The :mod:`math` module consists mostly of thin wrappers around the platform C
math library functions. Behavior in exceptional cases follows Annex F of
the C99 standard where appropriate. The current implementation will raise
:exc:`ValueError` for invalid operations like ``sqrt(-1.0)`` or ``log(0.0)``
(where C99 Annex F recommends signaling invalid operation or divide-by-zero),
and :exc:`OverflowError` for results that overflow (for example,
``exp(1000.0)``). A NaN will not be returned from any of the functions
above unless one or more of the input arguments was a NaN; in that case,
most functions will return a NaN, but (again following C99 Annex F) there
are some exceptions to this rule, for example ``pow(float('nan'), 0.0)`` or
``hypot(float('nan'), float('inf'))``.
Note that Python makes no effort to distinguish signaling NaNs from
quiet NaNs, and behavior for signaling NaNs remains unspecified.
Typical behavior is to treat all NaNs as though they were quiet.
.. versionchanged:: 2.6
Behavior in special cases now aims to follow C99 Annex F. In earlier
versions of Python the behavior in special cases was loosely specified.
.. seealso::
Module :mod:`cmath`
Complex number versions of many of these functions.
PK %�\���9�
�
! html/_sources/library/md5.rst.txtnu �[���
:mod:`md5` --- MD5 message digest algorithm
===========================================
.. module:: md5
:synopsis: RSA's MD5 message digest algorithm.
:deprecated:
.. deprecated:: 2.5
Use the :mod:`hashlib` module instead.
.. index::
single: message digest, MD5
single: checksum; MD5
This module implements the interface to RSA's MD5 message digest algorithm (see
also Internet :rfc:`1321`). Its use is quite straightforward: use :func:`new`
to create an md5 object. You can now feed this object with arbitrary strings
using the :meth:`update` method, and at any point you can ask it for the
:dfn:`digest` (a strong kind of 128-bit checksum, a.k.a. "fingerprint") of the
concatenation of the strings fed to it so far using the :meth:`digest` method.
For example, to obtain the digest of the string ``'Nobody inspects the spammish
repetition'``:
>>> import md5
>>> m = md5.new()
>>> m.update("Nobody inspects")
>>> m.update(" the spammish repetition")
>>> m.digest()
'\xbbd\x9c\x83\xdd\x1e\xa5\xc9\xd9\xde\xc9\xa1\x8d\xf0\xff\xe9'
More condensed:
>>> md5.new("Nobody inspects the spammish repetition").digest()
'\xbbd\x9c\x83\xdd\x1e\xa5\xc9\xd9\xde\xc9\xa1\x8d\xf0\xff\xe9'
The following values are provided as constants in the module and as attributes
of the md5 objects returned by :func:`new`:
.. data:: digest_size
The size of the resulting digest in bytes. This is always ``16``.
The md5 module provides the following functions:
.. function:: new([arg])
Return a new md5 object. If *arg* is present, the method call ``update(arg)``
is made.
.. function:: md5([arg])
For backward compatibility reasons, this is an alternative name for the
:func:`new` function.
An md5 object has the following methods:
.. method:: md5.update(arg)
Update the md5 object with the string *arg*. Repeated calls are equivalent to a
single call with the concatenation of all the arguments: ``m.update(a);
m.update(b)`` is equivalent to ``m.update(a+b)``.
.. method:: md5.digest()
Return the digest of the strings passed to the :meth:`update` method so far.
This is a 16-byte string which may contain non-ASCII characters, including null
bytes.
.. method:: md5.hexdigest()
Like :meth:`digest` except the digest is returned as a string of length 32,
containing only hexadecimal digits. This may be used to exchange the value
safely in email or other non-binary environments.
.. method:: md5.copy()
Return a copy ("clone") of the md5 object. This can be used to efficiently
compute the digests of strings that share a common initial substring.
.. seealso::
Module :mod:`sha`
Similar module implementing the Secure Hash Algorithm (SHA). The SHA algorithm
is considered a more secure hash.
PK %�\�Rہ~ ~ # html/_sources/library/mhlib.rst.txtnu �[��� :mod:`mhlib` --- Access to MH mailboxes
=======================================
.. module:: mhlib
:synopsis: Manipulate MH mailboxes from Python.
:deprecated:
.. deprecated:: 2.6
The :mod:`mhlib` module has been removed in Python 3. Use the
:mod:`mailbox` instead.
.. sectionauthor:: Skip Montanaro <skip@pobox.com>
The :mod:`mhlib` module provides a Python interface to MH folders and their
contents.
The module contains three basic classes, :class:`MH`, which represents a
particular collection of folders, :class:`Folder`, which represents a single
folder, and :class:`Message`, which represents a single message.
.. class:: MH([path[, profile]])
:class:`MH` represents a collection of MH folders.
.. class:: Folder(mh, name)
The :class:`Folder` class represents a single folder and its messages.
.. class:: Message(folder, number[, name])
:class:`Message` objects represent individual messages in a folder. The Message
class is derived from :class:`mimetools.Message`.
.. _mh-objects:
MH Objects
----------
:class:`MH` instances have the following methods:
.. method:: MH.error(format[, ...])
Print an error message -- can be overridden.
.. method:: MH.getprofile(key)
Return a profile entry (``None`` if not set).
.. method:: MH.getpath()
Return the mailbox pathname.
.. method:: MH.getcontext()
Return the current folder name.
.. method:: MH.setcontext(name)
Set the current folder name.
.. method:: MH.listfolders()
Return a list of top-level folders.
.. method:: MH.listallfolders()
Return a list of all folders.
.. method:: MH.listsubfolders(name)
Return a list of direct subfolders of the given folder.
.. method:: MH.listallsubfolders(name)
Return a list of all subfolders of the given folder.
.. method:: MH.makefolder(name)
Create a new folder.
.. method:: MH.deletefolder(name)
Delete a folder -- must have no subfolders.
.. method:: MH.openfolder(name)
Return a new open folder object.
.. _mh-folder-objects:
Folder Objects
--------------
:class:`Folder` instances represent open folders and have the following methods:
.. method:: Folder.error(format[, ...])
Print an error message -- can be overridden.
.. method:: Folder.getfullname()
Return the folder's full pathname.
.. method:: Folder.getsequencesfilename()
Return the full pathname of the folder's sequences file.
.. method:: Folder.getmessagefilename(n)
Return the full pathname of message *n* of the folder.
.. method:: Folder.listmessages()
Return a list of messages in the folder (as numbers).
.. method:: Folder.getcurrent()
Return the current message number.
.. method:: Folder.setcurrent(n)
Set the current message number to *n*.
.. method:: Folder.parsesequence(seq)
Parse msgs syntax into list of messages.
.. method:: Folder.getlast()
Get last message, or ``0`` if no messages are in the folder.
.. method:: Folder.setlast(n)
Set last message (internal use only).
.. method:: Folder.getsequences()
Return dictionary of sequences in folder. The sequence names are used as keys,
and the values are the lists of message numbers in the sequences.
.. method:: Folder.putsequences(dict)
Return dictionary of sequences in folder name: list.
.. method:: Folder.removemessages(list)
Remove messages in list from folder.
.. method:: Folder.refilemessages(list, tofolder)
Move messages in list to other folder.
.. method:: Folder.movemessage(n, tofolder, ton)
Move one message to a given destination in another folder.
.. method:: Folder.copymessage(n, tofolder, ton)
Copy one message to a given destination in another folder.
.. _mh-message-objects:
Message Objects
---------------
The :class:`Message` class adds one method to those of
:class:`mimetools.Message`:
.. method:: Message.openmessage(n)
Return a new open message object (costs a file descriptor).
PK %�\�6J� � ' html/_sources/library/mimetools.rst.txtnu �[���
:mod:`mimetools` --- Tools for parsing MIME messages
====================================================
.. module:: mimetools
:synopsis: Tools for parsing MIME-style message bodies.
:deprecated:
.. deprecated:: 2.3
The :mod:`email` package should be used in preference to the :mod:`mimetools`
module. This module is present only to maintain backward compatibility, and
it has been removed in 3.x.
.. index:: module: rfc822
This module defines a subclass of the :mod:`rfc822` module's :class:`Message`
class and a number of utility functions that are useful for the manipulation for
MIME multipart or encoded message.
It defines the following items:
.. class:: Message(fp[, seekable])
Return a new instance of the :class:`Message` class. This is a subclass of the
:class:`rfc822.Message` class, with some additional methods (see below). The
*seekable* argument has the same meaning as for :class:`rfc822.Message`.
.. function:: choose_boundary()
Return a unique string that has a high likelihood of being usable as a part
boundary. The string has the form ``'hostipaddr.uid.pid.timestamp.random'``.
.. function:: decode(input, output, encoding)
Read data encoded using the allowed MIME *encoding* from open file object
*input* and write the decoded data to open file object *output*. Valid values
for *encoding* include ``'base64'``, ``'quoted-printable'``, ``'uuencode'``,
``'x-uuencode'``, ``'uue'``, ``'x-uue'``, ``'7bit'``, and ``'8bit'``. Decoding
messages encoded in ``'7bit'`` or ``'8bit'`` has no effect. The input is simply
copied to the output.
.. function:: encode(input, output, encoding)
Read data from open file object *input* and write it encoded using the allowed
MIME *encoding* to open file object *output*. Valid values for *encoding* are
the same as for :meth:`decode`.
.. function:: copyliteral(input, output)
Read lines from open file *input* until EOF and write them to open file
*output*.
.. function:: copybinary(input, output)
Read blocks until EOF from open file *input* and write them to open file
*output*. The block size is currently fixed at 8192.
.. seealso::
Module :mod:`email`
Comprehensive email handling package; supersedes the :mod:`mimetools` module.
Module :mod:`rfc822`
Provides the base class for :class:`mimetools.Message`.
Module :mod:`multifile`
Support for reading files which contain distinct parts, such as MIME data.
http://faqs.cs.uu.nl/na-dir/mail/mime-faq/.html
The MIME Frequently Asked Questions document. For an overview of MIME, see the
answer to question 1.1 in Part 1 of this document.
.. _mimetools-message-objects:
Additional Methods of Message Objects
-------------------------------------
The :class:`Message` class defines the following methods in addition to the
:class:`rfc822.Message` methods:
.. method:: Message.getplist()
Return the parameter list of the :mailheader:`Content-Type` header. This is a
list of strings. For parameters of the form ``key=value``, *key* is converted
to lower case but *value* is not. For example, if the message contains the
header ``Content-type: text/html; spam=1; Spam=2; Spam`` then :meth:`getplist`
will return the Python list ``['spam=1', 'spam=2', 'Spam']``.
.. method:: Message.getparam(name)
Return the *value* of the first parameter (as returned by :meth:`getplist`) of
the form ``name=value`` for the given *name*. If *value* is surrounded by
quotes of the form '``<``...\ ``>``' or '``"``...\ ``"``', these are removed.
.. method:: Message.getencoding()
Return the encoding specified in the :mailheader:`Content-Transfer-Encoding`
message header. If no such header exists, return ``'7bit'``. The encoding is
converted to lower case.
.. method:: Message.gettype()
Return the message type (of the form ``type/subtype``) as specified in the
:mailheader:`Content-Type` header. If no such header exists, return
``'text/plain'``. The type is converted to lower case.
.. method:: Message.getmaintype()
Return the main type as specified in the :mailheader:`Content-Type` header. If
no such header exists, return ``'text'``. The main type is converted to lower
case.
.. method:: Message.getsubtype()
Return the subtype as specified in the :mailheader:`Content-Type` header. If no
such header exists, return ``'plain'``. The subtype is converted to lower case.
PK %�\='.�o& o& ' html/_sources/library/mimetypes.rst.txtnu �[��� :mod:`mimetypes` --- Map filenames to MIME types
================================================
.. module:: mimetypes
:synopsis: Mapping of filename extensions to MIME types.
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
.. index:: pair: MIME; content type
**Source code:** :source:`Lib/mimetypes.py`
--------------
The :mod:`mimetypes` module converts between a filename or URL and the MIME type
associated with the filename extension. Conversions are provided from filename
to MIME type and from MIME type to filename extension; encodings are not
supported for the latter conversion.
The module provides one class and a number of convenience functions. The
functions are the normal interface to this module, but some applications may be
interested in the class as well.
The functions described below provide the primary interface for this module. If
the module has not been initialized, they will call :func:`init` if they rely on
the information :func:`init` sets up.
.. function:: guess_type(url, strict=True)
.. index:: pair: MIME; headers
Guess the type of a file based on its filename or URL, given by *url*. The
return value is a tuple ``(type, encoding)`` where *type* is ``None`` if the
type can't be guessed (missing or unknown suffix) or a string of the form
``'type/subtype'``, usable for a MIME :mailheader:`content-type` header.
*encoding* is ``None`` for no encoding or the name of the program used to encode
(e.g. :program:`compress` or :program:`gzip`). The encoding is suitable for use
as a :mailheader:`Content-Encoding` header, **not** as a
:mailheader:`Content-Transfer-Encoding` header. The mappings are table driven.
Encoding suffixes are case sensitive; type suffixes are first tried case
sensitively, then case insensitively.
The optional *strict* argument is a flag specifying whether the list of known MIME types
is limited to only the official types `registered with IANA
<https://www.iana.org/assignments/media-types/media-types.xhtml>`_.
When *strict* is ``True`` (the default), only the IANA types are supported; when
*strict* is ``False``, some additional non-standard but commonly used MIME types
are also recognized.
.. function:: guess_all_extensions(type, strict=True)
Guess the extensions for a file based on its MIME type, given by *type*. The
return value is a list of strings giving all possible filename extensions,
including the leading dot (``'.'``). The extensions are not guaranteed to have
been associated with any particular data stream, but would be mapped to the MIME
type *type* by :func:`guess_type`.
The optional *strict* argument has the same meaning as with the :func:`guess_type` function.
.. function:: guess_extension(type, strict=True)
Guess the extension for a file based on its MIME type, given by *type*. The
return value is a string giving a filename extension, including the leading dot
(``'.'``). The extension is not guaranteed to have been associated with any
particular data stream, but would be mapped to the MIME type *type* by
:func:`guess_type`. If no extension can be guessed for *type*, ``None`` is
returned.
The optional *strict* argument has the same meaning as with the :func:`guess_type` function.
Some additional functions and data items are available for controlling the
behavior of the module.
.. function:: init(files=None)
Initialize the internal data structures. If given, *files* must be a sequence
of file names which should be used to augment the default type map. If omitted,
the file names to use are taken from :const:`knownfiles`; on Windows, the
current registry settings are loaded. Each file named in *files* or
:const:`knownfiles` takes precedence over those named before it. Calling
:func:`init` repeatedly is allowed.
Specifying an empty list for *files* will prevent the system defaults from
being applied: only the well-known values will be present from a built-in list.
.. versionchanged:: 2.7
Previously, Windows registry settings were ignored.
.. function:: read_mime_types(filename)
Load the type map given in the file *filename*, if it exists. The type map is
returned as a dictionary mapping filename extensions, including the leading dot
(``'.'``), to strings of the form ``'type/subtype'``. If the file *filename*
does not exist or cannot be read, ``None`` is returned.
.. function:: add_type(type, ext, strict=True)
Add a mapping from the MIME type *type* to the extension *ext*. When the
extension is already known, the new type will replace the old one. When the type
is already known the extension will be added to the list of known extensions.
When *strict* is ``True`` (the default), the mapping will be added to the
official MIME types, otherwise to the non-standard ones.
.. data:: inited
Flag indicating whether or not the global data structures have been initialized.
This is set to ``True`` by :func:`init`.
.. data:: knownfiles
.. index:: single: file; mime.types
List of type map file names commonly installed. These files are typically named
:file:`mime.types` and are installed in different locations by different
packages.
.. data:: suffix_map
Dictionary mapping suffixes to suffixes. This is used to allow recognition of
encoded files for which the encoding and the type are indicated by the same
extension. For example, the :file:`.tgz` extension is mapped to :file:`.tar.gz`
to allow the encoding and type to be recognized separately.
.. data:: encodings_map
Dictionary mapping filename extensions to encoding types.
.. data:: types_map
Dictionary mapping filename extensions to MIME types.
.. data:: common_types
Dictionary mapping filename extensions to non-standard, but commonly found MIME
types.
An example usage of the module::
>>> import mimetypes
>>> mimetypes.init()
>>> mimetypes.knownfiles
['/etc/mime.types', '/etc/httpd/mime.types', ... ]
>>> mimetypes.suffix_map['.tgz']
'.tar.gz'
>>> mimetypes.encodings_map['.gz']
'gzip'
>>> mimetypes.types_map['.tgz']
'application/x-tar-gz'
.. _mimetypes-objects:
MimeTypes Objects
-----------------
The :class:`MimeTypes` class may be useful for applications which may want more
than one MIME-type database; it provides an interface similar to the one of the
:mod:`mimetypes` module.
.. class:: MimeTypes(filenames=(), strict=True)
This class represents a MIME-types database. By default, it provides access to
the same database as the rest of this module. The initial database is a copy of
that provided by the module, and may be extended by loading additional
:file:`mime.types`\ -style files into the database using the :meth:`read` or
:meth:`readfp` methods. The mapping dictionaries may also be cleared before
loading additional data if the default data is not desired.
The optional *filenames* parameter can be used to cause additional files to be
loaded "on top" of the default database.
.. attribute:: MimeTypes.suffix_map
Dictionary mapping suffixes to suffixes. This is used to allow recognition of
encoded files for which the encoding and the type are indicated by the same
extension. For example, the :file:`.tgz` extension is mapped to :file:`.tar.gz`
to allow the encoding and type to be recognized separately. This is initially a
copy of the global :data:`suffix_map` defined in the module.
.. attribute:: MimeTypes.encodings_map
Dictionary mapping filename extensions to encoding types. This is initially a
copy of the global :data:`encodings_map` defined in the module.
.. attribute:: MimeTypes.types_map
Tuple containing two dictionaries, mapping filename extensions to MIME types:
the first dictionary is for the non-standards types and the second one is for
the standard types. They are initialized by :data:`common_types` and
:data:`types_map`.
.. attribute:: MimeTypes.types_map_inv
Tuple containing two dictionaries, mapping MIME types to a list of filename
extensions: the first dictionary is for the non-standards types and the
second one is for the standard types. They are initialized by
:data:`common_types` and :data:`types_map`.
.. method:: MimeTypes.guess_extension(type, strict=True)
Similar to the :func:`guess_extension` function, using the tables stored as part
of the object.
.. method:: MimeTypes.guess_type(url, strict=True)
Similar to the :func:`guess_type` function, using the tables stored as part of
the object.
.. method:: MimeTypes.guess_all_extensions(type, strict=True)
Similar to the :func:`guess_all_extensions` function, using the tables stored
as part of the object.
.. method:: MimeTypes.read(filename, strict=True)
Load MIME information from a file named *filename*. This uses :meth:`readfp` to
parse the file.
If *strict* is ``True``, information will be added to list of standard types,
else to the list of non-standard types.
.. method:: MimeTypes.readfp(fp, strict=True)
Load MIME type information from an open file *fp*. The file must have the format of
the standard :file:`mime.types` files.
If *strict* is ``True``, information will be added to the list of standard
types, else to the list of non-standard types.
.. method:: MimeTypes.read_windows_registry(strict=True)
Load MIME type information from the Windows registry. Availability: Windows.
If *strict* is ``True``, information will be added to the list of standard
types, else to the list of non-standard types.
.. versionadded:: 2.7
PK %�\��r.
( html/_sources/library/mimewriter.rst.txtnu �[��� :mod:`MimeWriter` --- Generic MIME file writer
==============================================
.. module:: MimeWriter
:synopsis: Write MIME format files.
:deprecated:
.. sectionauthor:: Christopher G. Petrilli <petrilli@amber.org>
.. deprecated:: 2.3
The :mod:`email` package should be used in preference to the :mod:`MimeWriter`
module. This module is present only to maintain backward compatibility.
This module defines the class :class:`~MimeWriter.MimeWriter`. The :class:`~MimeWriter.MimeWriter`
class implements a basic formatter for creating MIME multi-part files. It
doesn't seek around the output file nor does it use large amounts of buffer
space. You must write the parts out in the order that they should occur in the
final file. :class:`~MimeWriter.MimeWriter` does buffer the headers you add, allowing you
to rearrange their order.
.. class:: MimeWriter(fp)
Return a new instance of the :class:`~MimeWriter.MimeWriter` class. The only argument
passed, *fp*, is a file object to be used for writing. Note that a
:class:`~StringIO.StringIO` object could also be used.
.. _mimewriter-objects:
MimeWriter Objects
------------------
:class:`~MimeWriter.MimeWriter` instances have the following methods:
.. method:: MimeWriter.addheader(key, value[, prefix])
Add a header line to the MIME message. The *key* is the name of the header,
where the *value* obviously provides the value of the header. The optional
argument *prefix* determines where the header is inserted; ``0`` means append
at the end, ``1`` is insert at the start. The default is to append.
.. method:: MimeWriter.flushheaders()
Causes all headers accumulated so far to be written out (and forgotten). This is
useful if you don't need a body part at all, e.g. for a subpart of type
:mimetype:`message/rfc822` that's (mis)used to store some header-like
information.
.. method:: MimeWriter.startbody(ctype[, plist[, prefix]])
Returns a file-like object which can be used to write to the body of the
message. The content-type is set to the provided *ctype*, and the optional
parameter *plist* provides additional parameters for the content-type
declaration. *prefix* functions as in :meth:`addheader` except that the default
is to insert at the start.
.. method:: MimeWriter.startmultipartbody(subtype[, boundary[, plist[, prefix]]])
Returns a file-like object which can be used to write to the body of the
message. Additionally, this method initializes the multi-part code, where
*subtype* provides the multipart subtype, *boundary* may provide a user-defined
boundary specification, and *plist* provides optional parameters for the
subtype. *prefix* functions as in :meth:`startbody`. Subparts should be created
using :meth:`nextpart`.
.. method:: MimeWriter.nextpart()
Returns a new instance of :class:`~MimeWriter.MimeWriter` which represents an individual
part in a multipart message. This may be used to write the part as well as
used for creating recursively complex multipart messages. The message must first
be initialized with :meth:`startmultipartbody` before using :meth:`nextpart`.
.. method:: MimeWriter.lastpart()
This is used to designate the last part of a multipart message, and should
*always* be used when writing multipart messages.
PK %�\���
�
$ html/_sources/library/mimify.rst.txtnu �[���
:mod:`mimify` --- MIME processing of mail messages
==================================================
.. module:: mimify
:synopsis: Mimification and unmimification of mail messages.
:deprecated:
.. deprecated:: 2.3
The :mod:`email` package should be used in preference to the :mod:`mimify`
module. This module is present only to maintain backward compatibility.
The :mod:`mimify` module defines two functions to convert mail messages to and
from MIME format. The mail message can be either a simple message or a
so-called multipart message. Each part is treated separately. Mimifying (a part
of) a message entails encoding the message as quoted-printable if it contains
any characters that cannot be represented using 7-bit ASCII. Unmimifying (a
part of) a message entails undoing the quoted-printable encoding. Mimify and
unmimify are especially useful when a message has to be edited before being
sent. Typical use would be::
unmimify message
edit message
mimify message
send message
The modules defines the following user-callable functions and user-settable
variables:
.. function:: mimify(infile, outfile)
Copy the message in *infile* to *outfile*, converting parts to quoted-printable
and adding MIME mail headers when necessary. *infile* and *outfile* can be file
objects (actually, any object that has a :meth:`readline` method (for *infile*)
or a :meth:`write` method (for *outfile*)) or strings naming the files. If
*infile* and *outfile* are both strings, they may have the same value.
.. function:: unmimify(infile, outfile[, decode_base64])
Copy the message in *infile* to *outfile*, decoding all quoted-printable parts.
*infile* and *outfile* can be file objects (actually, any object that has a
:meth:`readline` method (for *infile*) or a :meth:`write` method (for
*outfile*)) or strings naming the files. If *infile* and *outfile* are both
strings, they may have the same value. If the *decode_base64* argument is
provided and tests true, any parts that are coded in the base64 encoding are
decoded as well.
.. function:: mime_decode_header(line)
Return a decoded version of the encoded header line in *line*. This only
supports the ISO 8859-1 charset (Latin-1).
.. function:: mime_encode_header(line)
Return a MIME-encoded version of the header line in *line*.
.. data:: MAXLEN
By default, a part will be encoded as quoted-printable when it contains any
non-ASCII characters (characters with the 8th bit set), or if there are any
lines longer than :const:`MAXLEN` characters (default value 200).
.. data:: CHARSET
When not specified in the mail headers, a character set must be filled in. The
string used is stored in :const:`CHARSET`, and the default value is ISO-8859-1
(also known as Latin1 (latin-one)).
This module can also be used from the command line. Usage is as follows::
mimify.py -e [-l length] [infile [outfile]]
mimify.py -d [-b] [infile [outfile]]
to encode (mimify) and decode (unmimify) respectively. *infile* defaults to
standard input, *outfile* defaults to standard output. The same file can be
specified for input and output.
If the **-l** option is given when encoding, if there are any lines longer than
the specified *length*, the containing part will be encoded.
If the **-b** option is given when decoding, any base64 parts will be decoded as
well.
.. seealso::
Module :mod:`quopri`
Encode and decode MIME quoted-printable files.
PK %�\��
) html/_sources/library/miniaeframe.rst.txtnu �[���
:mod:`MiniAEFrame` --- Open Scripting Architecture server support
=================================================================
.. module:: MiniAEFrame
:platform: Mac
:synopsis: Support to act as an Open Scripting Architecture (OSA) server ("Apple Events").
.. index::
single: Open Scripting Architecture
single: AppleEvents
module: FrameWork
The module :mod:`MiniAEFrame` provides a framework for an application that can
function as an Open Scripting Architecture (OSA) server, i.e. receive and
process AppleEvents. It can be used in conjunction with :mod:`FrameWork` or
standalone. As an example, it is used in :program:`PythonCGISlave`.
The :mod:`MiniAEFrame` module defines the following classes:
.. class:: AEServer()
A class that handles AppleEvent dispatch. Your application should subclass this
class together with either :class:`MiniApplication` or
:class:`FrameWork.Application`. Your :meth:`__init__` method should call the
:meth:`__init__` method for both classes.
.. class:: MiniApplication()
A class that is more or less compatible with :class:`FrameWork.Application` but
with less functionality. Its event loop supports the apple menu, command-dot and
AppleEvents; other events are passed on to the Python interpreter and/or Sioux.
Useful if your application wants to use :class:`AEServer` but does not provide
its own windows, etc.
.. _aeserver-objects:
AEServer Objects
----------------
.. method:: AEServer.installaehandler(classe, type, callback)
Installs an AppleEvent handler. *classe* and *type* are the four-character OSA
Class and Type designators, ``'****'`` wildcards are allowed. When a matching
AppleEvent is received the parameters are decoded and your callback is invoked.
.. method:: AEServer.callback(_object, **kwargs)
Your callback is called with the OSA Direct Object as first positional
parameter. The other parameters are passed as keyword arguments, with the
4-character designator as name. Three extra keyword parameters are passed:
``_class`` and ``_type`` are the Class and Type designators and ``_attributes``
is a dictionary with the AppleEvent attributes.
The return value of your method is packed with :func:`aetools.packevent` and
sent as reply.
Note that there are some serious problems with the current design. AppleEvents
which have non-identifier 4-character designators for arguments are not
implementable, and it is not possible to return an error to the originator. This
will be addressed in a future release.
PK %�\��O�� � " html/_sources/library/misc.rst.txtnu �[���
.. _misc:
**********************
Miscellaneous Services
**********************
The modules described in this chapter provide miscellaneous services that are
available in all Python versions. Here's an overview:
.. toctree::
formatter.rst
PK %�\�I6-� � html/_sources/library/mm.rst.txtnu �[���
.. _mmedia:
*******************
Multimedia Services
*******************
The modules described in this chapter implement various algorithms or interfaces
that are mainly useful for multimedia applications. They are available at the
discretion of the installation. Here's an overview:
.. toctree::
audioop.rst
imageop.rst
aifc.rst
sunau.rst
wave.rst
chunk.rst
colorsys.rst
imghdr.rst
sndhdr.rst
ossaudiodev.rst
PK %�\�},5�( �( " html/_sources/library/mmap.rst.txtnu �[���
:mod:`mmap` --- Memory-mapped file support
==========================================
.. module:: mmap
:synopsis: Interface to memory-mapped files for Unix and Windows.
Memory-mapped file objects behave like both strings and like file objects.
Unlike normal string objects, however, these are mutable. You can use mmap
objects in most places where strings are expected; for example, you can use
the :mod:`re` module to search through a memory-mapped file. Since they're
mutable, you can change a single character by doing ``obj[index] = 'a'``, or
change a substring by assigning to a slice: ``obj[i1:i2] = '...'``. You can
also read and write data starting at the current file position, and
:meth:`seek` through the file to different positions.
A memory-mapped file is created by the :class:`~mmap.mmap` constructor, which is
different on Unix and on Windows. In either case you must provide a file
descriptor for a file opened for update. If you wish to map an existing Python
file object, use its :meth:`fileno` method to obtain the correct value for the
*fileno* parameter. Otherwise, you can open the file using the
:func:`os.open` function, which returns a file descriptor directly (the file
still needs to be closed when done).
.. note::
If you want to create a memory-mapping for a writable, buffered file, you
should :func:`~io.IOBase.flush` the file first. This is necessary to ensure
that local modifications to the buffers are actually available to the
mapping.
For both the Unix and Windows versions of the constructor, *access* may be
specified as an optional keyword parameter. *access* accepts one of three
values: :const:`ACCESS_READ`, :const:`ACCESS_WRITE`, or :const:`ACCESS_COPY`
to specify read-only, write-through or copy-on-write memory respectively.
*access* can be used on both Unix and Windows. If *access* is not specified,
Windows mmap returns a write-through mapping. The initial memory values for
all three access types are taken from the specified file. Assignment to an
:const:`ACCESS_READ` memory map raises a :exc:`TypeError` exception.
Assignment to an :const:`ACCESS_WRITE` memory map affects both memory and the
underlying file. Assignment to an :const:`ACCESS_COPY` memory map affects
memory but does not update the underlying file.
.. versionchanged:: 2.5
To map anonymous memory, -1 should be passed as the fileno along with the
length.
.. versionchanged:: 2.6
mmap.mmap has formerly been a factory function creating mmap objects. Now
mmap.mmap is the class itself.
.. class:: mmap(fileno, length[, tagname[, access[, offset]]])
**(Windows version)** Maps *length* bytes from the file specified by the
file handle *fileno*, and creates a mmap object. If *length* is larger
than the current size of the file, the file is extended to contain *length*
bytes. If *length* is ``0``, the maximum length of the map is the current
size of the file, except that if the file is empty Windows raises an
exception (you cannot create an empty mapping on Windows).
*tagname*, if specified and not ``None``, is a string giving a tag name for
the mapping. Windows allows you to have many different mappings against
the same file. If you specify the name of an existing tag, that tag is
opened, otherwise a new tag of this name is created. If this parameter is
omitted or ``None``, the mapping is created without a name. Avoiding the
use of the tag parameter will assist in keeping your code portable between
Unix and Windows.
*offset* may be specified as a non-negative integer offset. mmap references
will be relative to the offset from the beginning of the file. *offset*
defaults to 0. *offset* must be a multiple of the :const:`ALLOCATIONGRANULARITY`.
.. class:: mmap(fileno, length[, flags[, prot[, access[, offset]]]])
:noindex:
**(Unix version)** Maps *length* bytes from the file specified by the file
descriptor *fileno*, and returns a mmap object. If *length* is ``0``, the
maximum length of the map will be the current size of the file when
:class:`~mmap.mmap` is called.
*flags* specifies the nature of the mapping. :const:`MAP_PRIVATE` creates a
private copy-on-write mapping, so changes to the contents of the mmap
object will be private to this process, and :const:`MAP_SHARED` creates a
mapping that's shared with all other processes mapping the same areas of
the file. The default value is :const:`MAP_SHARED`.
*prot*, if specified, gives the desired memory protection; the two most
useful values are :const:`PROT_READ` and :const:`PROT_WRITE`, to specify
that the pages may be read or written. *prot* defaults to
:const:`PROT_READ \| PROT_WRITE`.
*access* may be specified in lieu of *flags* and *prot* as an optional
keyword parameter. It is an error to specify both *flags*, *prot* and
*access*. See the description of *access* above for information on how to
use this parameter.
*offset* may be specified as a non-negative integer offset. mmap references
will be relative to the offset from the beginning of the file. *offset*
defaults to 0. *offset* must be a multiple of :const:`ALLOCATIONGRANULARITY`
which is equal to :const:`PAGESIZE` on Unix systems.
To ensure validity of the created memory mapping the file specified
by the descriptor *fileno* is internally automatically synchronized
with physical backing store on Mac OS X and OpenVMS.
This example shows a simple way of using :class:`~mmap.mmap`::
import mmap
# write a simple example file
with open("hello.txt", "wb") as f:
f.write("Hello Python!\n")
with open("hello.txt", "r+b") as f:
# memory-map the file, size 0 means whole file
mm = mmap.mmap(f.fileno(), 0)
# read content via standard file methods
print mm.readline() # prints "Hello Python!"
# read content via slice notation
print mm[:5] # prints "Hello"
# update content using slice notation;
# note that new content must have same size
mm[6:] = " world!\n"
# ... and read again using standard file methods
mm.seek(0)
print mm.readline() # prints "Hello world!"
# close the map
mm.close()
The next example demonstrates how to create an anonymous map and exchange
data between the parent and child processes::
import mmap
import os
mm = mmap.mmap(-1, 13)
mm.write("Hello world!")
pid = os.fork()
if pid == 0: # In a child process
mm.seek(0)
print mm.readline()
mm.close()
Memory-mapped file objects support the following methods:
.. method:: close()
Closes the mmap. Subsequent calls to other methods of the object will
result in a ValueError exception being raised. This will not close
the open file.
.. method:: find(string[, start[, end]])
Returns the lowest index in the object where the substring *string* is
found, such that *string* is contained in the range [*start*, *end*].
Optional arguments *start* and *end* are interpreted as in slice notation.
Returns ``-1`` on failure.
.. method:: flush([offset, size])
Flushes changes made to the in-memory copy of a file back to disk. Without
use of this call there is no guarantee that changes are written back before
the object is destroyed. If *offset* and *size* are specified, only
changes to the given range of bytes will be flushed to disk; otherwise, the
whole extent of the mapping is flushed. *offset* must be a multiple of the
:const:`PAGESIZE` or :const:`ALLOCATIONGRANULARITY`.
**(Windows version)** A nonzero value returned indicates success; zero
indicates failure.
**(Unix version)** A zero value is returned to indicate success. An
exception is raised when the call failed.
.. method:: move(dest, src, count)
Copy the *count* bytes starting at offset *src* to the destination index
*dest*. If the mmap was created with :const:`ACCESS_READ`, then calls to
move will raise a :exc:`TypeError` exception.
.. method:: read(num)
Return a string containing up to *num* bytes starting from the current
file position; the file position is updated to point after the bytes that
were returned.
.. method:: read_byte()
Returns a string of length 1 containing the character at the current file
position, and advances the file position by 1.
.. method:: readline()
Returns a single line, starting at the current file position and up to the
next newline.
.. method:: resize(newsize)
Resizes the map and the underlying file, if any. If the mmap was created
with :const:`ACCESS_READ` or :const:`ACCESS_COPY`, resizing the map will
raise a :exc:`TypeError` exception.
.. method:: rfind(string[, start[, end]])
Returns the highest index in the object where the substring *string* is
found, such that *string* is contained in the range [*start*, *end*].
Optional arguments *start* and *end* are interpreted as in slice notation.
Returns ``-1`` on failure.
.. method:: seek(pos[, whence])
Set the file's current position. *whence* argument is optional and
defaults to ``os.SEEK_SET`` or ``0`` (absolute file positioning); other
values are ``os.SEEK_CUR`` or ``1`` (seek relative to the current
position) and ``os.SEEK_END`` or ``2`` (seek relative to the file's end).
.. method:: size()
Return the length of the file, which can be larger than the size of the
memory-mapped area.
.. method:: tell()
Returns the current position of the file pointer.
.. method:: write(string)
Write the bytes in *string* into memory at the current position of the
file pointer; the file position is updated to point after the bytes that
were written. If the mmap was created with :const:`ACCESS_READ`, then
writing to it will raise a :exc:`TypeError` exception.
.. method:: write_byte(byte)
Write the single-character string *byte* into memory at the current
position of the file pointer; the file position is advanced by ``1``. If
the mmap was created with :const:`ACCESS_READ`, then writing to it will
raise a :exc:`TypeError` exception.
PK %�\^D4
4
* html/_sources/library/modulefinder.rst.txtnu �[��� :mod:`modulefinder` --- Find modules used by a script
=====================================================
.. module:: modulefinder
:synopsis: Find modules used by a script.
.. sectionauthor:: A.M. Kuchling <amk@amk.ca>
.. versionadded:: 2.3
**Source code:** :source:`Lib/modulefinder.py`
--------------
This module provides a :class:`ModuleFinder` class that can be used to determine
the set of modules imported by a script. ``modulefinder.py`` can also be run as
a script, giving the filename of a Python script as its argument, after which a
report of the imported modules will be printed.
.. function:: AddPackagePath(pkg_name, path)
Record that the package named *pkg_name* can be found in the specified *path*.
.. function:: ReplacePackage(oldname, newname)
Allows specifying that the module named *oldname* is in fact the package named
*newname*. The most common usage would be to handle how the :mod:`_xmlplus`
package replaces the :mod:`xml` package.
.. class:: ModuleFinder([path=None, debug=0, excludes=[], replace_paths=[]])
This class provides :meth:`run_script` and :meth:`report` methods to determine
the set of modules imported by a script. *path* can be a list of directories to
search for modules; if not specified, ``sys.path`` is used. *debug* sets the
debugging level; higher values make the class print debugging messages about
what it's doing. *excludes* is a list of module names to exclude from the
analysis. *replace_paths* is a list of ``(oldpath, newpath)`` tuples that will
be replaced in module paths.
.. method:: report()
Print a report to standard output that lists the modules imported by the
script and their paths, as well as modules that are missing or seem to be
missing.
.. method:: run_script(pathname)
Analyze the contents of the *pathname* file, which must contain Python
code.
.. attribute:: modules
A dictionary mapping module names to modules. See
:ref:`modulefinder-example`.
.. _modulefinder-example:
Example usage of :class:`ModuleFinder`
--------------------------------------
The script that is going to get analyzed later on (bacon.py)::
import re, itertools
try:
import baconhameggs
except ImportError:
pass
try:
import guido.python.ham
except ImportError:
pass
The script that will output the report of bacon.py::
from modulefinder import ModuleFinder
finder = ModuleFinder()
finder.run_script('bacon.py')
print 'Loaded modules:'
for name, mod in finder.modules.iteritems():
print '%s: ' % name,
print ','.join(mod.globalnames.keys()[:3])
print '-'*50
print 'Modules not imported:'
print '\n'.join(finder.badmodules.iterkeys())
Sample output (may vary depending on the architecture)::
Loaded modules:
_types:
copy_reg: _inverted_registry,_slotnames,__all__
sre_compile: isstring,_sre,_optimize_unicode
_sre:
sre_constants: REPEAT_ONE,makedict,AT_END_LINE
sys:
re: __module__,finditer,_expand
itertools:
__main__: re,itertools,baconhameggs
sre_parse: __getslice__,_PATTERNENDERS,SRE_FLAG_UNICODE
array:
types: __module__,IntType,TypeType
---------------------------------------------------
Modules not imported:
guido.python.ham
baconhameggs
PK %�\{�U�~ ~ % html/_sources/library/modules.rst.txtnu �[���
.. _modules:
*****************
Importing Modules
*****************
The modules described in this chapter provide new ways to import other Python
modules and hooks for customizing the import process.
The full list of modules described in this chapter is:
.. toctree::
imp.rst
importlib.rst
imputil.rst
zipimport.rst
pkgutil.rst
modulefinder.rst
runpy.rst
PK %�\ZG��vJ vJ $ html/_sources/library/msilib.rst.txtnu �[��� :mod:`msilib` --- Read and write Microsoft Installer files
==========================================================
.. module:: msilib
:platform: Windows
:synopsis: Creation of Microsoft Installer files, and CAB files.
.. moduleauthor:: Martin v. Löwis <martin@v.loewis.de>
.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
.. index:: single: msi
.. versionadded:: 2.5
The :mod:`msilib` supports the creation of Microsoft Installer (``.msi``) files.
Because these files often contain an embedded "cabinet" file (``.cab``), it also
exposes an API to create CAB files. Support for reading ``.cab`` files is
currently not implemented; read support for the ``.msi`` database is possible.
This package aims to provide complete access to all tables in an ``.msi`` file,
therefore, it is a fairly low-level API. Two primary applications of this
package are the :mod:`distutils` command ``bdist_msi``, and the creation of
Python installer package itself (although that currently uses a different
version of ``msilib``).
The package contents can be roughly split into four parts: low-level CAB
routines, low-level MSI routines, higher-level MSI routines, and standard table
structures.
.. function:: FCICreate(cabname, files)
Create a new CAB file named *cabname*. *files* must be a list of tuples, each
containing the name of the file on disk, and the name of the file inside the CAB
file.
The files are added to the CAB file in the order they appear in the list. All
files are added into a single CAB file, using the MSZIP compression algorithm.
Callbacks to Python for the various steps of MSI creation are currently not
exposed.
.. function:: UuidCreate()
Return the string representation of a new unique identifier. This wraps the
Windows API functions :c:func:`UuidCreate` and :c:func:`UuidToString`.
.. function:: OpenDatabase(path, persist)
Return a new database object by calling MsiOpenDatabase. *path* is the file
name of the MSI file; *persist* can be one of the constants
``MSIDBOPEN_CREATEDIRECT``, ``MSIDBOPEN_CREATE``, ``MSIDBOPEN_DIRECT``,
``MSIDBOPEN_READONLY``, or ``MSIDBOPEN_TRANSACT``, and may include the flag
``MSIDBOPEN_PATCHFILE``. See the Microsoft documentation for the meaning of
these flags; depending on the flags, an existing database is opened, or a new
one created.
.. function:: CreateRecord(count)
Return a new record object by calling :c:func:`MSICreateRecord`. *count* is the
number of fields of the record.
.. function:: init_database(name, schema, ProductName, ProductCode, ProductVersion, Manufacturer)
Create and return a new database *name*, initialize it with *schema*, and set
the properties *ProductName*, *ProductCode*, *ProductVersion*, and
*Manufacturer*.
*schema* must be a module object containing ``tables`` and
``_Validation_records`` attributes; typically, :mod:`msilib.schema` should be
used.
The database will contain just the schema and the validation records when this
function returns.
.. function:: add_data(database, table, records)
Add all *records* to the table named *table* in *database*.
The *table* argument must be one of the predefined tables in the MSI schema,
e.g. ``'Feature'``, ``'File'``, ``'Component'``, ``'Dialog'``, ``'Control'``,
etc.
*records* should be a list of tuples, each one containing all fields of a
record according to the schema of the table. For optional fields,
``None`` can be passed.
Field values can be int or long numbers, strings, or instances of the Binary
class.
.. class:: Binary(filename)
Represents entries in the Binary table; inserting such an object using
:func:`add_data` reads the file named *filename* into the table.
.. function:: add_tables(database, module)
Add all table content from *module* to *database*. *module* must contain an
attribute *tables* listing all tables for which content should be added, and one
attribute per table that has the actual content.
This is typically used to install the sequence tables.
.. function:: add_stream(database, name, path)
Add the file *path* into the ``_Stream`` table of *database*, with the stream
name *name*.
.. function:: gen_uuid()
Return a new UUID, in the format that MSI typically requires (i.e. in curly
braces, and with all hexdigits in upper-case).
.. seealso::
`FCICreateFile <https://msdn.microsoft.com/library?url=/library/en-us/devnotes/winprog/fcicreate.asp>`_
`UuidCreate <https://msdn.microsoft.com/library?url=/library/en-us/rpc/rpc/uuidcreate.asp>`_
`UuidToString <https://msdn.microsoft.com/library?url=/library/en-us/rpc/rpc/uuidtostring.asp>`_
.. _database-objects:
Database Objects
----------------
.. method:: Database.OpenView(sql)
Return a view object, by calling :c:func:`MSIDatabaseOpenView`. *sql* is the SQL
statement to execute.
.. method:: Database.Commit()
Commit the changes pending in the current transaction, by calling
:c:func:`MSIDatabaseCommit`.
.. method:: Database.GetSummaryInformation(count)
Return a new summary information object, by calling
:c:func:`MsiGetSummaryInformation`. *count* is the maximum number of updated
values.
.. seealso::
`MSIDatabaseOpenView <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msidatabaseopenview.asp>`_
`MSIDatabaseCommit <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msidatabasecommit.asp>`_
`MSIGetSummaryInformation <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msigetsummaryinformation.asp>`_
.. _view-objects:
View Objects
------------
.. method:: View.Execute(params)
Execute the SQL query of the view, through :c:func:`MSIViewExecute`. If
*params* is not ``None``, it is a record describing actual values of the
parameter tokens in the query.
.. method:: View.GetColumnInfo(kind)
Return a record describing the columns of the view, through calling
:c:func:`MsiViewGetColumnInfo`. *kind* can be either ``MSICOLINFO_NAMES`` or
``MSICOLINFO_TYPES``.
.. method:: View.Fetch()
Return a result record of the query, through calling :c:func:`MsiViewFetch`.
.. method:: View.Modify(kind, data)
Modify the view, by calling :c:func:`MsiViewModify`. *kind* can be one of
``MSIMODIFY_SEEK``, ``MSIMODIFY_REFRESH``, ``MSIMODIFY_INSERT``,
``MSIMODIFY_UPDATE``, ``MSIMODIFY_ASSIGN``, ``MSIMODIFY_REPLACE``,
``MSIMODIFY_MERGE``, ``MSIMODIFY_DELETE``, ``MSIMODIFY_INSERT_TEMPORARY``,
``MSIMODIFY_VALIDATE``, ``MSIMODIFY_VALIDATE_NEW``,
``MSIMODIFY_VALIDATE_FIELD``, or ``MSIMODIFY_VALIDATE_DELETE``.
*data* must be a record describing the new data.
.. method:: View.Close()
Close the view, through :c:func:`MsiViewClose`.
.. seealso::
`MsiViewExecute <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msiviewexecute.asp>`_
`MSIViewGetColumnInfo <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msiviewgetcolumninfo.asp>`_
`MsiViewFetch <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msiviewfetch.asp>`_
`MsiViewModify <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msiviewmodify.asp>`_
`MsiViewClose <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msiviewclose.asp>`_
.. _summary-objects:
Summary Information Objects
---------------------------
.. method:: SummaryInformation.GetProperty(field)
Return a property of the summary, through :c:func:`MsiSummaryInfoGetProperty`.
*field* is the name of the property, and can be one of the constants
``PID_CODEPAGE``, ``PID_TITLE``, ``PID_SUBJECT``, ``PID_AUTHOR``,
``PID_KEYWORDS``, ``PID_COMMENTS``, ``PID_TEMPLATE``, ``PID_LASTAUTHOR``,
``PID_REVNUMBER``, ``PID_LASTPRINTED``, ``PID_CREATE_DTM``,
``PID_LASTSAVE_DTM``, ``PID_PAGECOUNT``, ``PID_WORDCOUNT``, ``PID_CHARCOUNT``,
``PID_APPNAME``, or ``PID_SECURITY``.
.. method:: SummaryInformation.GetPropertyCount()
Return the number of summary properties, through
:c:func:`MsiSummaryInfoGetPropertyCount`.
.. method:: SummaryInformation.SetProperty(field, value)
Set a property through :c:func:`MsiSummaryInfoSetProperty`. *field* can have the
same values as in :meth:`GetProperty`, *value* is the new value of the property.
Possible value types are integer and string.
.. method:: SummaryInformation.Persist()
Write the modified properties to the summary information stream, using
:c:func:`MsiSummaryInfoPersist`.
.. seealso::
`MsiSummaryInfoGetProperty <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msisummaryinfogetproperty.asp>`_
`MsiSummaryInfoGetPropertyCount <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msisummaryinfogetpropertycount.asp>`_
`MsiSummaryInfoSetProperty <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msisummaryinfosetproperty.asp>`_
`MsiSummaryInfoPersist <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msisummaryinfopersist.asp>`_
.. _record-objects:
Record Objects
--------------
.. method:: Record.GetFieldCount()
Return the number of fields of the record, through
:c:func:`MsiRecordGetFieldCount`.
.. method:: Record.GetInteger(field)
Return the value of *field* as an integer where possible. *field* must
be an integer.
.. method:: Record.GetString(field)
Return the value of *field* as a string where possible. *field* must
be an integer.
.. method:: Record.SetString(field, value)
Set *field* to *value* through :c:func:`MsiRecordSetString`. *field* must be an
integer; *value* a string.
.. method:: Record.SetStream(field, value)
Set *field* to the contents of the file named *value*, through
:c:func:`MsiRecordSetStream`. *field* must be an integer; *value* a string.
.. method:: Record.SetInteger(field, value)
Set *field* to *value* through :c:func:`MsiRecordSetInteger`. Both *field* and
*value* must be an integer.
.. method:: Record.ClearData()
Set all fields of the record to 0, through :c:func:`MsiRecordClearData`.
.. seealso::
`MsiRecordGetFieldCount <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msirecordgetfieldcount.asp>`_
`MsiRecordSetString <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msirecordsetstring.asp>`_
`MsiRecordSetStream <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msirecordsetstream.asp>`_
`MsiRecordSetInteger <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msirecordsetinteger.asp>`_
`MsiRecordClear <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/msirecordclear.asp>`_
.. _msi-errors:
Errors
------
All wrappers around MSI functions raise :exc:`MSIError`; the string inside the
exception will contain more detail.
.. _cab:
CAB Objects
-----------
.. class:: CAB(name)
The class :class:`CAB` represents a CAB file. During MSI construction, files
will be added simultaneously to the ``Files`` table, and to a CAB file. Then,
when all files have been added, the CAB file can be written, then added to the
MSI file.
*name* is the name of the CAB file in the MSI file.
.. method:: append(full, file, logical)
Add the file with the pathname *full* to the CAB file, under the name
*logical*. If there is already a file named *logical*, a new file name is
created.
Return the index of the file in the CAB file, and the new name of the file
inside the CAB file.
.. method:: commit(database)
Generate a CAB file, add it as a stream to the MSI file, put it into the
``Media`` table, and remove the generated file from the disk.
.. _msi-directory:
Directory Objects
-----------------
.. class:: Directory(database, cab, basedir, physical, logical, default, [componentflags])
Create a new directory in the Directory table. There is a current component at
each point in time for the directory, which is either explicitly created through
:meth:`start_component`, or implicitly when files are added for the first time.
Files are added into the current component, and into the cab file. To create a
directory, a base directory object needs to be specified (can be ``None``), the
path to the physical directory, and a logical directory name. *default*
specifies the DefaultDir slot in the directory table. *componentflags* specifies
the default flags that new components get.
.. method:: start_component([component[, feature[, flags[, keyfile[, uuid]]]]])
Add an entry to the Component table, and make this component the current
component for this directory. If no component name is given, the directory
name is used. If no *feature* is given, the current feature is used. If no
*flags* are given, the directory's default flags are used. If no *keyfile*
is given, the KeyPath is left null in the Component table.
.. method:: add_file(file[, src[, version[, language]]])
Add a file to the current component of the directory, starting a new one
if there is no current component. By default, the file name in the source
and the file table will be identical. If the *src* file is specified, it
is interpreted relative to the current directory. Optionally, a *version*
and a *language* can be specified for the entry in the File table.
.. method:: glob(pattern[, exclude])
Add a list of files to the current component as specified in the glob
pattern. Individual files can be excluded in the *exclude* list.
.. method:: remove_pyc()
Remove ``.pyc``/``.pyo`` files on uninstall.
.. seealso::
`Directory Table <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/directory_table.asp>`_
`File Table <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/file_table.asp>`_
`Component Table <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/component_table.asp>`_
`FeatureComponents Table <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/featurecomponents_table.asp>`_
.. _features:
Features
--------
.. class:: Feature(database, id, title, desc, display[, level=1[, parent[, directory[, attributes=0]]]])
Add a new record to the ``Feature`` table, using the values *id*, *parent.id*,
*title*, *desc*, *display*, *level*, *directory*, and *attributes*. The
resulting feature object can be passed to the :meth:`start_component` method of
:class:`Directory`.
.. method:: set_current()
Make this feature the current feature of :mod:`msilib`. New components are
automatically added to the default feature, unless a feature is explicitly
specified.
.. seealso::
`Feature Table <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/feature_table.asp>`_
.. _msi-gui:
GUI classes
-----------
:mod:`msilib` provides several classes that wrap the GUI tables in an MSI
database. However, no standard user interface is provided; use
:mod:`~distutils.command.bdist_msi` to create MSI files with a user-interface
for installing Python packages.
.. class:: Control(dlg, name)
Base class of the dialog controls. *dlg* is the dialog object the control
belongs to, and *name* is the control's name.
.. method:: event(event, argument[, condition=1[, ordering]])
Make an entry into the ``ControlEvent`` table for this control.
.. method:: mapping(event, attribute)
Make an entry into the ``EventMapping`` table for this control.
.. method:: condition(action, condition)
Make an entry into the ``ControlCondition`` table for this control.
.. class:: RadioButtonGroup(dlg, name, property)
Create a radio button control named *name*. *property* is the installer property
that gets set when a radio button is selected.
.. method:: add(name, x, y, width, height, text [, value])
Add a radio button named *name* to the group, at the coordinates *x*, *y*,
*width*, *height*, and with the label *text*. If *value* is omitted, it
defaults to *name*.
.. class:: Dialog(db, name, x, y, w, h, attr, title, first, default, cancel)
Return a new :class:`Dialog` object. An entry in the ``Dialog`` table is made,
with the specified coordinates, dialog attributes, title, name of the first,
default, and cancel controls.
.. method:: control(name, type, x, y, width, height, attributes, property, text, control_next, help)
Return a new :class:`Control` object. An entry in the ``Control`` table is
made with the specified parameters.
This is a generic method; for specific types, specialized methods are
provided.
.. method:: text(name, x, y, width, height, attributes, text)
Add and return a ``Text`` control.
.. method:: bitmap(name, x, y, width, height, text)
Add and return a ``Bitmap`` control.
.. method:: line(name, x, y, width, height)
Add and return a ``Line`` control.
.. method:: pushbutton(name, x, y, width, height, attributes, text, next_control)
Add and return a ``PushButton`` control.
.. method:: radiogroup(name, x, y, width, height, attributes, property, text, next_control)
Add and return a ``RadioButtonGroup`` control.
.. method:: checkbox(name, x, y, width, height, attributes, property, text, next_control)
Add and return a ``CheckBox`` control.
.. seealso::
`Dialog Table <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/dialog_table.asp>`_
`Control Table <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/control_table.asp>`_
`Control Types <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/controls.asp>`_
`ControlCondition Table <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/controlcondition_table.asp>`_
`ControlEvent Table <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/controlevent_table.asp>`_
`EventMapping Table <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/eventmapping_table.asp>`_
`RadioButton Table <https://msdn.microsoft.com/library?url=/library/en-us/msi/setup/radiobutton_table.asp>`_
.. _msi-tables:
Precomputed tables
------------------
:mod:`msilib` provides a few subpackages that contain only schema and table
definitions. Currently, these definitions are based on MSI version 2.0.
.. data:: schema
This is the standard MSI schema for MSI 2.0, with the *tables* variable
providing a list of table definitions, and *_Validation_records* providing the
data for MSI validation.
.. data:: sequence
This module contains table contents for the standard sequence tables:
*AdminExecuteSequence*, *AdminUISequence*, *AdvtExecuteSequence*,
*InstallExecuteSequence*, and *InstallUISequence*.
.. data:: text
This module contains definitions for the UIText and ActionText tables, for the
standard installer actions.
PK %�\��>�� � $ html/_sources/library/msvcrt.rst.txtnu �[���
:mod:`msvcrt` --- Useful routines from the MS VC++ runtime
==========================================================
.. module:: msvcrt
:platform: Windows
:synopsis: Miscellaneous useful routines from the MS VC++ runtime.
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
These functions provide access to some useful capabilities on Windows platforms.
Some higher-level modules use these functions to build the Windows
implementations of their services. For example, the :mod:`getpass` module uses
this in the implementation of the :func:`getpass` function.
Further documentation on these functions can be found in the Platform API
documentation.
The module implements both the normal and wide char variants of the console I/O
api. The normal API deals only with ASCII characters and is of limited use
for internationalized applications. The wide char API should be used where
ever possible.
.. _msvcrt-files:
File Operations
---------------
.. function:: locking(fd, mode, nbytes)
Lock part of a file based on file descriptor *fd* from the C runtime. Raises
:exc:`IOError` on failure. The locked region of the file extends from the
current file position for *nbytes* bytes, and may continue beyond the end of the
file. *mode* must be one of the :const:`LK_\*` constants listed below. Multiple
regions in a file may be locked at the same time, but may not overlap. Adjacent
regions are not merged; they must be unlocked individually.
.. data:: LK_LOCK
LK_RLCK
Locks the specified bytes. If the bytes cannot be locked, the program
immediately tries again after 1 second. If, after 10 attempts, the bytes cannot
be locked, :exc:`IOError` is raised.
.. data:: LK_NBLCK
LK_NBRLCK
Locks the specified bytes. If the bytes cannot be locked, :exc:`IOError` is
raised.
.. data:: LK_UNLCK
Unlocks the specified bytes, which must have been previously locked.
.. function:: setmode(fd, flags)
Set the line-end translation mode for the file descriptor *fd*. To set it to
text mode, *flags* should be :const:`os.O_TEXT`; for binary, it should be
:const:`os.O_BINARY`.
.. function:: open_osfhandle(handle, flags)
Create a C runtime file descriptor from the file handle *handle*. The *flags*
parameter should be a bitwise OR of :const:`os.O_APPEND`, :const:`os.O_RDONLY`,
and :const:`os.O_TEXT`. The returned file descriptor may be used as a parameter
to :func:`os.fdopen` to create a file object.
.. function:: get_osfhandle(fd)
Return the file handle for the file descriptor *fd*. Raises :exc:`IOError` if
*fd* is not recognized.
.. _msvcrt-console:
Console I/O
-----------
.. function:: kbhit()
Return true if a keypress is waiting to be read.
.. function:: getch()
Read a keypress and return the resulting character. Nothing is echoed to the
console. This call will block if a keypress is not already available, but will
not wait for :kbd:`Enter` to be pressed. If the pressed key was a special
function key, this will return ``'\000'`` or ``'\xe0'``; the next call will
return the keycode. The :kbd:`Control-C` keypress cannot be read with this
function.
.. function:: getwch()
Wide char variant of :func:`getch`, returning a Unicode value.
.. versionadded:: 2.6
.. function:: getche()
Similar to :func:`getch`, but the keypress will be echoed if it represents a
printable character.
.. function:: getwche()
Wide char variant of :func:`getche`, returning a Unicode value.
.. versionadded:: 2.6
.. function:: putch(char)
Print the character *char* to the console without buffering.
.. function:: putwch(unicode_char)
Wide char variant of :func:`putch`, accepting a Unicode value.
.. versionadded:: 2.6
.. function:: ungetch(char)
Cause the character *char* to be "pushed back" into the console buffer; it will
be the next character read by :func:`getch` or :func:`getche`.
.. function:: ungetwch(unicode_char)
Wide char variant of :func:`ungetch`, accepting a Unicode value.
.. versionadded:: 2.6
.. _msvcrt-other:
Other Functions
---------------
.. function:: heapmin()
Force the :c:func:`malloc` heap to clean itself up and return unused blocks to
the operating system. On failure, this raises :exc:`IOError`.
PK %�\_n�� � ' html/_sources/library/multifile.rst.txtnu �[���
:mod:`multifile` --- Support for files containing distinct parts
================================================================
.. module:: multifile
:synopsis: Support for reading files which contain distinct parts, such as some MIME data.
:deprecated:
.. sectionauthor:: Eric S. Raymond <esr@snark.thyrsus.com>
.. deprecated:: 2.5
The :mod:`email` package should be used in preference to the :mod:`multifile`
module. This module is present only to maintain backward compatibility.
The :class:`MultiFile` object enables you to treat sections of a text file as
file-like input objects, with ``''`` being returned by :meth:`readline` when a
given delimiter pattern is encountered. The defaults of this class are designed
to make it useful for parsing MIME multipart messages, but by subclassing it and
overriding methods it can be easily adapted for more general use.
.. class:: MultiFile(fp[, seekable])
Create a multi-file. You must instantiate this class with an input object
argument for the :class:`MultiFile` instance to get lines from, such as a file
object returned by :func:`open`.
:class:`MultiFile` only ever looks at the input object's :meth:`readline`,
:meth:`seek` and :meth:`tell` methods, and the latter two are only needed if you
want random access to the individual MIME parts. To use :class:`MultiFile` on a
non-seekable stream object, set the optional *seekable* argument to false; this
will prevent using the input object's :meth:`seek` and :meth:`tell` methods.
It will be useful to know that in :class:`MultiFile`'s view of the world, text
is composed of three kinds of lines: data, section-dividers, and end-markers.
MultiFile is designed to support parsing of messages that may have multiple
nested message parts, each with its own pattern for section-divider and
end-marker lines.
.. seealso::
Module :mod:`email`
Comprehensive email handling package; supersedes the :mod:`multifile` module.
.. _multifile-objects:
MultiFile Objects
-----------------
A :class:`MultiFile` instance has the following methods:
.. method:: MultiFile.readline(str)
Read a line. If the line is data (not a section-divider or end-marker or real
EOF) return it. If the line matches the most-recently-stacked boundary, return
``''`` and set ``self.last`` to 1 or 0 according as the match is or is not an
end-marker. If the line matches any other stacked boundary, raise an error. On
encountering end-of-file on the underlying stream object, the method raises
:exc:`Error` unless all boundaries have been popped.
.. method:: MultiFile.readlines(str)
Return all lines remaining in this part as a list of strings.
.. method:: MultiFile.read()
Read all lines, up to the next section. Return them as a single (multiline)
string. Note that this doesn't take a size argument!
.. method:: MultiFile.seek(pos[, whence])
Seek. Seek indices are relative to the start of the current section. The *pos*
and *whence* arguments are interpreted as for a file seek.
.. method:: MultiFile.tell()
Return the file position relative to the start of the current section.
.. method:: MultiFile.next()
Skip lines to the next section (that is, read lines until a section-divider or
end-marker has been consumed). Return true if there is such a section, false if
an end-marker is seen. Re-enable the most-recently-pushed boundary.
.. method:: MultiFile.is_data(str)
Return true if *str* is data and false if it might be a section boundary. As
written, it tests for a prefix other than ``'-``\ ``-'`` at start of line (which
all MIME boundaries have) but it is declared so it can be overridden in derived
classes.
Note that this test is used intended as a fast guard for the real boundary
tests; if it always returns false it will merely slow processing, not cause it
to fail.
.. method:: MultiFile.push(str)
Push a boundary string. When a decorated version of this boundary is found as
an input line, it will be interpreted as a section-divider or end-marker
(depending on the decoration, see :rfc:`2045`). All subsequent reads will
return the empty string to indicate end-of-file, until a call to :meth:`pop`
removes the boundary a or :meth:`.next` call reenables it.
It is possible to push more than one boundary. Encountering the
most-recently-pushed boundary will return EOF; encountering any other
boundary will raise an error.
.. method:: MultiFile.pop()
Pop a section boundary. This boundary will no longer be interpreted as EOF.
.. method:: MultiFile.section_divider(str)
Turn a boundary into a section-divider line. By default, this method
prepends ``'--'`` (which MIME section boundaries have) but it is declared so
it can be overridden in derived classes. This method need not append LF or
CR-LF, as comparison with the result ignores trailing whitespace.
.. method:: MultiFile.end_marker(str)
Turn a boundary string into an end-marker line. By default, this method
prepends ``'--'`` and appends ``'--'`` (like a MIME-multipart end-of-message
marker) but it is declared so it can be overridden in derived classes. This
method need not append LF or CR-LF, as comparison with the result ignores
trailing whitespace.
Finally, :class:`MultiFile` instances have two public instance variables:
.. attribute:: MultiFile.level
Nesting depth of the current part.
.. attribute:: MultiFile.last
True if the last end-of-file was for an end-of-message marker.
.. _multifile-example:
:class:`MultiFile` Example
--------------------------
.. sectionauthor:: Skip Montanaro <skip@pobox.com>
::
import mimetools
import multifile
import StringIO
def extract_mime_part_matching(stream, mimetype):
"""Return the first element in a multipart MIME message on stream
matching mimetype."""
msg = mimetools.Message(stream)
msgtype = msg.gettype()
params = msg.getplist()
data = StringIO.StringIO()
if msgtype[:10] == "multipart/":
file = multifile.MultiFile(stream)
file.push(msg.getparam("boundary"))
while file.next():
submsg = mimetools.Message(file)
try:
data = StringIO.StringIO()
mimetools.decode(file, data, submsg.getencoding())
except ValueError:
continue
if submsg.gettype() == mimetype:
break
file.pop()
return data.getvalue()
PK %�\�kk��i �i - html/_sources/library/multiprocessing.rst.txtnu �[��� :mod:`multiprocessing` --- Process-based "threading" interface
==============================================================
.. module:: multiprocessing
:synopsis: Process-based "threading" interface.
.. versionadded:: 2.6
Introduction
----------------------
:mod:`multiprocessing` is a package that supports spawning processes using an
API similar to the :mod:`threading` module. The :mod:`multiprocessing` package
offers both local and remote concurrency, effectively side-stepping the
:term:`Global Interpreter Lock` by using subprocesses instead of threads. Due
to this, the :mod:`multiprocessing` module allows the programmer to fully
leverage multiple processors on a given machine. It runs on both Unix and
Windows.
The :mod:`multiprocessing` module also introduces APIs which do not have
analogs in the :mod:`threading` module. A prime example of this is the
:class:`Pool` object which offers a convenient means of parallelizing the
execution of a function across multiple input values, distributing the
input data across processes (data parallelism). The following example
demonstrates the common practice of defining such functions in a module so
that child processes can successfully import that module. This basic example
of data parallelism using :class:`Pool`, ::
from multiprocessing import Pool
def f(x):
return x*x
if __name__ == '__main__':
p = Pool(5)
print(p.map(f, [1, 2, 3]))
will print to standard output ::
[1, 4, 9]
The :class:`Process` class
~~~~~~~~~~~~~~~~~~~~~~~~~~
In :mod:`multiprocessing`, processes are spawned by creating a :class:`Process`
object and then calling its :meth:`~Process.start` method. :class:`Process`
follows the API of :class:`threading.Thread`. A trivial example of a
multiprocess program is ::
from multiprocessing import Process
def f(name):
print 'hello', name
if __name__ == '__main__':
p = Process(target=f, args=('bob',))
p.start()
p.join()
To show the individual process IDs involved, here is an expanded example::
from multiprocessing import Process
import os
def info(title):
print title
print 'module name:', __name__
if hasattr(os, 'getppid'): # only available on Unix
print 'parent process:', os.getppid()
print 'process id:', os.getpid()
def f(name):
info('function f')
print 'hello', name
if __name__ == '__main__':
info('main line')
p = Process(target=f, args=('bob',))
p.start()
p.join()
For an explanation of why (on Windows) the ``if __name__ == '__main__'`` part is
necessary, see :ref:`multiprocessing-programming`.
Exchanging objects between processes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:mod:`multiprocessing` supports two types of communication channel between
processes:
**Queues**
The :class:`~multiprocessing.Queue` class is a near clone of :class:`Queue.Queue`. For
example::
from multiprocessing import Process, Queue
def f(q):
q.put([42, None, 'hello'])
if __name__ == '__main__':
q = Queue()
p = Process(target=f, args=(q,))
p.start()
print q.get() # prints "[42, None, 'hello']"
p.join()
Queues are thread and process safe.
**Pipes**
The :func:`Pipe` function returns a pair of connection objects connected by a
pipe which by default is duplex (two-way). For example::
from multiprocessing import Process, Pipe
def f(conn):
conn.send([42, None, 'hello'])
conn.close()
if __name__ == '__main__':
parent_conn, child_conn = Pipe()
p = Process(target=f, args=(child_conn,))
p.start()
print parent_conn.recv() # prints "[42, None, 'hello']"
p.join()
The two connection objects returned by :func:`Pipe` represent the two ends of
the pipe. Each connection object has :meth:`~Connection.send` and
:meth:`~Connection.recv` methods (among others). Note that data in a pipe
may become corrupted if two processes (or threads) try to read from or write
to the *same* end of the pipe at the same time. Of course there is no risk
of corruption from processes using different ends of the pipe at the same
time.
Synchronization between processes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:mod:`multiprocessing` contains equivalents of all the synchronization
primitives from :mod:`threading`. For instance one can use a lock to ensure
that only one process prints to standard output at a time::
from multiprocessing import Process, Lock
def f(l, i):
l.acquire()
print 'hello world', i
l.release()
if __name__ == '__main__':
lock = Lock()
for num in range(10):
Process(target=f, args=(lock, num)).start()
Without using the lock output from the different processes is liable to get all
mixed up.
Sharing state between processes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
As mentioned above, when doing concurrent programming it is usually best to
avoid using shared state as far as possible. This is particularly true when
using multiple processes.
However, if you really do need to use some shared data then
:mod:`multiprocessing` provides a couple of ways of doing so.
**Shared memory**
Data can be stored in a shared memory map using :class:`Value` or
:class:`Array`. For example, the following code ::
from multiprocessing import Process, Value, Array
def f(n, a):
n.value = 3.1415927
for i in range(len(a)):
a[i] = -a[i]
if __name__ == '__main__':
num = Value('d', 0.0)
arr = Array('i', range(10))
p = Process(target=f, args=(num, arr))
p.start()
p.join()
print num.value
print arr[:]
will print ::
3.1415927
[0, -1, -2, -3, -4, -5, -6, -7, -8, -9]
The ``'d'`` and ``'i'`` arguments used when creating ``num`` and ``arr`` are
typecodes of the kind used by the :mod:`array` module: ``'d'`` indicates a
double precision float and ``'i'`` indicates a signed integer. These shared
objects will be process and thread-safe.
For more flexibility in using shared memory one can use the
:mod:`multiprocessing.sharedctypes` module which supports the creation of
arbitrary ctypes objects allocated from shared memory.
**Server process**
A manager object returned by :func:`Manager` controls a server process which
holds Python objects and allows other processes to manipulate them using
proxies.
A manager returned by :func:`Manager` will support types :class:`list`,
:class:`dict`, :class:`~managers.Namespace`, :class:`Lock`, :class:`RLock`,
:class:`Semaphore`, :class:`BoundedSemaphore`, :class:`Condition`,
:class:`Event`, :class:`~multiprocessing.Queue`, :class:`Value` and :class:`Array`. For
example, ::
from multiprocessing import Process, Manager
def f(d, l):
d[1] = '1'
d['2'] = 2
d[0.25] = None
l.reverse()
if __name__ == '__main__':
manager = Manager()
d = manager.dict()
l = manager.list(range(10))
p = Process(target=f, args=(d, l))
p.start()
p.join()
print d
print l
will print ::
{0.25: None, 1: '1', '2': 2}
[9, 8, 7, 6, 5, 4, 3, 2, 1, 0]
Server process managers are more flexible than using shared memory objects
because they can be made to support arbitrary object types. Also, a single
manager can be shared by processes on different computers over a network.
They are, however, slower than using shared memory.
Using a pool of workers
~~~~~~~~~~~~~~~~~~~~~~~
The :class:`~multiprocessing.pool.Pool` class represents a pool of worker
processes. It has methods which allows tasks to be offloaded to the worker
processes in a few different ways.
For example::
from multiprocessing import Pool, TimeoutError
import time
import os
def f(x):
return x*x
if __name__ == '__main__':
pool = Pool(processes=4) # start 4 worker processes
# print "[0, 1, 4,..., 81]"
print pool.map(f, range(10))
# print same numbers in arbitrary order
for i in pool.imap_unordered(f, range(10)):
print i
# evaluate "f(20)" asynchronously
res = pool.apply_async(f, (20,)) # runs in *only* one process
print res.get(timeout=1) # prints "400"
# evaluate "os.getpid()" asynchronously
res = pool.apply_async(os.getpid, ()) # runs in *only* one process
print res.get(timeout=1) # prints the PID of that process
# launching multiple evaluations asynchronously *may* use more processes
multiple_results = [pool.apply_async(os.getpid, ()) for i in range(4)]
print [res.get(timeout=1) for res in multiple_results]
# make a single worker sleep for 10 secs
res = pool.apply_async(time.sleep, (10,))
try:
print res.get(timeout=1)
except TimeoutError:
print "We lacked patience and got a multiprocessing.TimeoutError"
Note that the methods of a pool should only ever be used by the
process which created it.
.. note::
Functionality within this package requires that the ``__main__`` module be
importable by the children. This is covered in :ref:`multiprocessing-programming`
however it is worth pointing out here. This means that some examples, such
as the :class:`Pool` examples will not work in the interactive interpreter.
For example::
>>> from multiprocessing import Pool
>>> p = Pool(5)
>>> def f(x):
... return x*x
...
>>> p.map(f, [1,2,3])
Process PoolWorker-1:
Process PoolWorker-2:
Process PoolWorker-3:
Traceback (most recent call last):
Traceback (most recent call last):
Traceback (most recent call last):
AttributeError: 'module' object has no attribute 'f'
AttributeError: 'module' object has no attribute 'f'
AttributeError: 'module' object has no attribute 'f'
(If you try this it will actually output three full tracebacks
interleaved in a semi-random fashion, and then you may have to
stop the master process somehow.)
Reference
---------
The :mod:`multiprocessing` package mostly replicates the API of the
:mod:`threading` module.
:class:`Process` and exceptions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. class:: Process(group=None, target=None, name=None, args=(), kwargs={})
Process objects represent activity that is run in a separate process. The
:class:`Process` class has equivalents of all the methods of
:class:`threading.Thread`.
The constructor should always be called with keyword arguments. *group*
should always be ``None``; it exists solely for compatibility with
:class:`threading.Thread`. *target* is the callable object to be invoked by
the :meth:`run()` method. It defaults to ``None``, meaning nothing is
called. *name* is the process name. By default, a unique name is constructed
of the form 'Process-N\ :sub:`1`:N\ :sub:`2`:...:N\ :sub:`k`' where N\
:sub:`1`,N\ :sub:`2`,...,N\ :sub:`k` is a sequence of integers whose length
is determined by the *generation* of the process. *args* is the argument
tuple for the target invocation. *kwargs* is a dictionary of keyword
arguments for the target invocation. By default, no arguments are passed to
*target*.
If a subclass overrides the constructor, it must make sure it invokes the
base class constructor (:meth:`Process.__init__`) before doing anything else
to the process.
.. method:: run()
Method representing the process's activity.
You may override this method in a subclass. The standard :meth:`run`
method invokes the callable object passed to the object's constructor as
the target argument, if any, with sequential and keyword arguments taken
from the *args* and *kwargs* arguments, respectively.
.. method:: start()
Start the process's activity.
This must be called at most once per process object. It arranges for the
object's :meth:`run` method to be invoked in a separate process.
.. method:: join([timeout])
Block the calling thread until the process whose :meth:`join` method is
called terminates or until the optional timeout occurs.
If *timeout* is ``None`` then there is no timeout.
A process can be joined many times.
A process cannot join itself because this would cause a deadlock. It is
an error to attempt to join a process before it has been started.
.. attribute:: name
The process's name.
The name is a string used for identification purposes only. It has no
semantics. Multiple processes may be given the same name. The initial
name is set by the constructor.
.. method:: is_alive
Return whether the process is alive.
Roughly, a process object is alive from the moment the :meth:`start`
method returns until the child process terminates.
.. attribute:: daemon
The process's daemon flag, a Boolean value. This must be set before
:meth:`start` is called.
The initial value is inherited from the creating process.
When a process exits, it attempts to terminate all of its daemonic child
processes.
Note that a daemonic process is not allowed to create child processes.
Otherwise a daemonic process would leave its children orphaned if it gets
terminated when its parent process exits. Additionally, these are **not**
Unix daemons or services, they are normal processes that will be
terminated (and not joined) if non-daemonic processes have exited.
In addition to the :class:`threading.Thread` API, :class:`Process` objects
also support the following attributes and methods:
.. attribute:: pid
Return the process ID. Before the process is spawned, this will be
``None``.
.. attribute:: exitcode
The child's exit code. This will be ``None`` if the process has not yet
terminated. A negative value *-N* indicates that the child was terminated
by signal *N*.
.. attribute:: authkey
The process's authentication key (a byte string).
When :mod:`multiprocessing` is initialized the main process is assigned a
random string using :func:`os.urandom`.
When a :class:`Process` object is created, it will inherit the
authentication key of its parent process, although this may be changed by
setting :attr:`authkey` to another byte string.
See :ref:`multiprocessing-auth-keys`.
.. method:: terminate()
Terminate the process. On Unix this is done using the ``SIGTERM`` signal;
on Windows :c:func:`TerminateProcess` is used. Note that exit handlers and
finally clauses, etc., will not be executed.
Note that descendant processes of the process will *not* be terminated --
they will simply become orphaned.
.. warning::
If this method is used when the associated process is using a pipe or
queue then the pipe or queue is liable to become corrupted and may
become unusable by other process. Similarly, if the process has
acquired a lock or semaphore etc. then terminating it is liable to
cause other processes to deadlock.
Note that the :meth:`start`, :meth:`join`, :meth:`is_alive`,
:meth:`terminate` and :attr:`exitcode` methods should only be called by
the process that created the process object.
Example usage of some of the methods of :class:`Process`:
.. doctest::
>>> import multiprocessing, time, signal
>>> p = multiprocessing.Process(target=time.sleep, args=(1000,))
>>> print p, p.is_alive()
<Process(Process-1, initial)> False
>>> p.start()
>>> print p, p.is_alive()
<Process(Process-1, started)> True
>>> p.terminate()
>>> time.sleep(0.1)
>>> print p, p.is_alive()
<Process(Process-1, stopped[SIGTERM])> False
>>> p.exitcode == -signal.SIGTERM
True
.. exception:: BufferTooShort
Exception raised by :meth:`Connection.recv_bytes_into()` when the supplied
buffer object is too small for the message read.
If ``e`` is an instance of :exc:`BufferTooShort` then ``e.args[0]`` will give
the message as a byte string.
Pipes and Queues
~~~~~~~~~~~~~~~~
When using multiple processes, one generally uses message passing for
communication between processes and avoids having to use any synchronization
primitives like locks.
For passing messages one can use :func:`Pipe` (for a connection between two
processes) or a queue (which allows multiple producers and consumers).
The :class:`~multiprocessing.Queue`, :class:`multiprocessing.queues.SimpleQueue` and :class:`JoinableQueue` types are multi-producer,
multi-consumer FIFO queues modelled on the :class:`Queue.Queue` class in the
standard library. They differ in that :class:`~multiprocessing.Queue` lacks the
:meth:`~Queue.Queue.task_done` and :meth:`~Queue.Queue.join` methods introduced
into Python 2.5's :class:`Queue.Queue` class.
If you use :class:`JoinableQueue` then you **must** call
:meth:`JoinableQueue.task_done` for each task removed from the queue or else the
semaphore used to count the number of unfinished tasks may eventually overflow,
raising an exception.
Note that one can also create a shared queue by using a manager object -- see
:ref:`multiprocessing-managers`.
.. note::
:mod:`multiprocessing` uses the usual :exc:`Queue.Empty` and
:exc:`Queue.Full` exceptions to signal a timeout. They are not available in
the :mod:`multiprocessing` namespace so you need to import them from
:mod:`Queue`.
.. note::
When an object is put on a queue, the object is pickled and a
background thread later flushes the pickled data to an underlying
pipe. This has some consequences which are a little surprising,
but should not cause any practical difficulties -- if they really
bother you then you can instead use a queue created with a
:ref:`manager <multiprocessing-managers>`.
(1) After putting an object on an empty queue there may be an
infinitesimal delay before the queue's :meth:`~Queue.empty`
method returns :const:`False` and :meth:`~Queue.get_nowait` can
return without raising :exc:`Queue.Empty`.
(2) If multiple processes are enqueuing objects, it is possible for
the objects to be received at the other end out-of-order.
However, objects enqueued by the same process will always be in
the expected order with respect to each other.
.. warning::
If a process is killed using :meth:`Process.terminate` or :func:`os.kill`
while it is trying to use a :class:`~multiprocessing.Queue`, then the data in the queue is
likely to become corrupted. This may cause any other process to get an
exception when it tries to use the queue later on.
.. warning::
As mentioned above, if a child process has put items on a queue (and it has
not used :meth:`JoinableQueue.cancel_join_thread
<multiprocessing.Queue.cancel_join_thread>`), then that process will
not terminate until all buffered items have been flushed to the pipe.
This means that if you try joining that process you may get a deadlock unless
you are sure that all items which have been put on the queue have been
consumed. Similarly, if the child process is non-daemonic then the parent
process may hang on exit when it tries to join all its non-daemonic children.
Note that a queue created using a manager does not have this issue. See
:ref:`multiprocessing-programming`.
For an example of the usage of queues for interprocess communication see
:ref:`multiprocessing-examples`.
.. function:: Pipe([duplex])
Returns a pair ``(conn1, conn2)`` of :class:`Connection` objects representing
the ends of a pipe.
If *duplex* is ``True`` (the default) then the pipe is bidirectional. If
*duplex* is ``False`` then the pipe is unidirectional: ``conn1`` can only be
used for receiving messages and ``conn2`` can only be used for sending
messages.
.. class:: Queue([maxsize])
Returns a process shared queue implemented using a pipe and a few
locks/semaphores. When a process first puts an item on the queue a feeder
thread is started which transfers objects from a buffer into the pipe.
The usual :exc:`Queue.Empty` and :exc:`Queue.Full` exceptions from the
standard library's :mod:`Queue` module are raised to signal timeouts.
:class:`~multiprocessing.Queue` implements all the methods of :class:`Queue.Queue` except for
:meth:`~Queue.Queue.task_done` and :meth:`~Queue.Queue.join`.
.. method:: qsize()
Return the approximate size of the queue. Because of
multithreading/multiprocessing semantics, this number is not reliable.
Note that this may raise :exc:`NotImplementedError` on Unix platforms like
Mac OS X where ``sem_getvalue()`` is not implemented.
.. method:: empty()
Return ``True`` if the queue is empty, ``False`` otherwise. Because of
multithreading/multiprocessing semantics, this is not reliable.
.. method:: full()
Return ``True`` if the queue is full, ``False`` otherwise. Because of
multithreading/multiprocessing semantics, this is not reliable.
.. method:: put(obj[, block[, timeout]])
Put obj into the queue. If the optional argument *block* is ``True``
(the default) and *timeout* is ``None`` (the default), block if necessary until
a free slot is available. If *timeout* is a positive number, it blocks at
most *timeout* seconds and raises the :exc:`Queue.Full` exception if no
free slot was available within that time. Otherwise (*block* is
``False``), put an item on the queue if a free slot is immediately
available, else raise the :exc:`Queue.Full` exception (*timeout* is
ignored in that case).
.. method:: put_nowait(obj)
Equivalent to ``put(obj, False)``.
.. method:: get([block[, timeout]])
Remove and return an item from the queue. If optional args *block* is
``True`` (the default) and *timeout* is ``None`` (the default), block if
necessary until an item is available. If *timeout* is a positive number,
it blocks at most *timeout* seconds and raises the :exc:`Queue.Empty`
exception if no item was available within that time. Otherwise (block is
``False``), return an item if one is immediately available, else raise the
:exc:`Queue.Empty` exception (*timeout* is ignored in that case).
.. method:: get_nowait()
Equivalent to ``get(False)``.
:class:`~multiprocessing.Queue` has a few additional methods not found in
:class:`Queue.Queue`. These methods are usually unnecessary for most
code:
.. method:: close()
Indicate that no more data will be put on this queue by the current
process. The background thread will quit once it has flushed all buffered
data to the pipe. This is called automatically when the queue is garbage
collected.
.. method:: join_thread()
Join the background thread. This can only be used after :meth:`close` has
been called. It blocks until the background thread exits, ensuring that
all data in the buffer has been flushed to the pipe.
By default if a process is not the creator of the queue then on exit it
will attempt to join the queue's background thread. The process can call
:meth:`cancel_join_thread` to make :meth:`join_thread` do nothing.
.. method:: cancel_join_thread()
Prevent :meth:`join_thread` from blocking. In particular, this prevents
the background thread from being joined automatically when the process
exits -- see :meth:`join_thread`.
A better name for this method might be
``allow_exit_without_flush()``. It is likely to cause enqueued
data to lost, and you almost certainly will not need to use it.
It is really only there if you need the current process to exit
immediately without waiting to flush enqueued data to the
underlying pipe, and you don't care about lost data.
.. note::
This class's functionality requires a functioning shared semaphore
implementation on the host operating system. Without one, the
functionality in this class will be disabled, and attempts to
instantiate a :class:`Queue` will result in an :exc:`ImportError`. See
:issue:`3770` for additional information. The same holds true for any
of the specialized queue types listed below.
.. class:: multiprocessing.queues.SimpleQueue()
It is a simplified :class:`~multiprocessing.Queue` type, very close to a locked :class:`Pipe`.
.. method:: empty()
Return ``True`` if the queue is empty, ``False`` otherwise.
.. method:: get()
Remove and return an item from the queue.
.. method:: put(item)
Put *item* into the queue.
.. class:: JoinableQueue([maxsize])
:class:`JoinableQueue`, a :class:`~multiprocessing.Queue` subclass, is a queue which
additionally has :meth:`task_done` and :meth:`join` methods.
.. method:: task_done()
Indicate that a formerly enqueued task is complete. Used by queue consumer
threads. For each :meth:`~Queue.get` used to fetch a task, a subsequent
call to :meth:`task_done` tells the queue that the processing on the task
is complete.
If a :meth:`~Queue.Queue.join` is currently blocking, it will resume when all
items have been processed (meaning that a :meth:`task_done` call was
received for every item that had been :meth:`~Queue.put` into the queue).
Raises a :exc:`ValueError` if called more times than there were items
placed in the queue.
.. method:: join()
Block until all items in the queue have been gotten and processed.
The count of unfinished tasks goes up whenever an item is added to the
queue. The count goes down whenever a consumer thread calls
:meth:`task_done` to indicate that the item was retrieved and all work on
it is complete. When the count of unfinished tasks drops to zero,
:meth:`~Queue.Queue.join` unblocks.
Miscellaneous
~~~~~~~~~~~~~
.. function:: active_children()
Return list of all live children of the current process.
Calling this has the side effect of "joining" any processes which have
already finished.
.. function:: cpu_count()
Return the number of CPUs in the system. May raise
:exc:`NotImplementedError`.
.. function:: current_process()
Return the :class:`Process` object corresponding to the current process.
An analogue of :func:`threading.current_thread`.
.. function:: freeze_support()
Add support for when a program which uses :mod:`multiprocessing` has been
frozen to produce a Windows executable. (Has been tested with **py2exe**,
**PyInstaller** and **cx_Freeze**.)
One needs to call this function straight after the ``if __name__ ==
'__main__'`` line of the main module. For example::
from multiprocessing import Process, freeze_support
def f():
print 'hello world!'
if __name__ == '__main__':
freeze_support()
Process(target=f).start()
If the ``freeze_support()`` line is omitted then trying to run the frozen
executable will raise :exc:`RuntimeError`.
Calling ``freeze_support()`` has no effect when invoked on any operating
system other than Windows. In addition, if the module is being run
normally by the Python interpreter on Windows (the program has not been
frozen), then ``freeze_support()`` has no effect.
.. function:: set_executable()
Sets the path of the Python interpreter to use when starting a child process.
(By default :data:`sys.executable` is used). Embedders will probably need to
do some thing like ::
set_executable(os.path.join(sys.exec_prefix, 'pythonw.exe'))
before they can create child processes. (Windows only)
.. note::
:mod:`multiprocessing` contains no analogues of
:func:`threading.active_count`, :func:`threading.enumerate`,
:func:`threading.settrace`, :func:`threading.setprofile`,
:class:`threading.Timer`, or :class:`threading.local`.
Connection Objects
~~~~~~~~~~~~~~~~~~
.. currentmodule:: None
Connection objects allow the sending and receiving of picklable objects or
strings. They can be thought of as message oriented connected sockets.
Connection objects are usually created using
:func:`Pipe <multiprocessing.Pipe>` -- see also
:ref:`multiprocessing-listeners-clients`.
.. class:: Connection
.. method:: send(obj)
Send an object to the other end of the connection which should be read
using :meth:`recv`.
The object must be picklable. Very large pickles (approximately 32 MB+,
though it depends on the OS) may raise a :exc:`ValueError` exception.
.. method:: recv()
Return an object sent from the other end of the connection using
:meth:`send`. Blocks until there is something to receive. Raises
:exc:`EOFError` if there is nothing left to receive
and the other end was closed.
.. method:: fileno()
Return the file descriptor or handle used by the connection.
.. method:: close()
Close the connection.
This is called automatically when the connection is garbage collected.
.. method:: poll([timeout])
Return whether there is any data available to be read.
If *timeout* is not specified then it will return immediately. If
*timeout* is a number then this specifies the maximum time in seconds to
block. If *timeout* is ``None`` then an infinite timeout is used.
.. method:: send_bytes(buffer[, offset[, size]])
Send byte data from an object supporting the buffer interface as a
complete message.
If *offset* is given then data is read from that position in *buffer*. If
*size* is given then that many bytes will be read from buffer. Very large
buffers (approximately 32 MB+, though it depends on the OS) may raise a
:exc:`ValueError` exception
.. method:: recv_bytes([maxlength])
Return a complete message of byte data sent from the other end of the
connection as a string. Blocks until there is something to receive.
Raises :exc:`EOFError` if there is nothing left
to receive and the other end has closed.
If *maxlength* is specified and the message is longer than *maxlength*
then :exc:`IOError` is raised and the connection will no longer be
readable.
.. method:: recv_bytes_into(buffer[, offset])
Read into *buffer* a complete message of byte data sent from the other end
of the connection and return the number of bytes in the message. Blocks
until there is something to receive. Raises
:exc:`EOFError` if there is nothing left to receive and the other end was
closed.
*buffer* must be an object satisfying the writable buffer interface. If
*offset* is given then the message will be written into the buffer from
that position. Offset must be a non-negative integer less than the
length of *buffer* (in bytes).
If the buffer is too short then a :exc:`BufferTooShort` exception is
raised and the complete message is available as ``e.args[0]`` where ``e``
is the exception instance.
For example:
.. doctest::
>>> from multiprocessing import Pipe
>>> a, b = Pipe()
>>> a.send([1, 'hello', None])
>>> b.recv()
[1, 'hello', None]
>>> b.send_bytes('thank you')
>>> a.recv_bytes()
'thank you'
>>> import array
>>> arr1 = array.array('i', range(5))
>>> arr2 = array.array('i', [0] * 10)
>>> a.send_bytes(arr1)
>>> count = b.recv_bytes_into(arr2)
>>> assert count == len(arr1) * arr1.itemsize
>>> arr2
array('i', [0, 1, 2, 3, 4, 0, 0, 0, 0, 0])
.. warning::
The :meth:`Connection.recv` method automatically unpickles the data it
receives, which can be a security risk unless you can trust the process
which sent the message.
Therefore, unless the connection object was produced using :func:`Pipe` you
should only use the :meth:`~Connection.recv` and :meth:`~Connection.send`
methods after performing some sort of authentication. See
:ref:`multiprocessing-auth-keys`.
.. warning::
If a process is killed while it is trying to read or write to a pipe then
the data in the pipe is likely to become corrupted, because it may become
impossible to be sure where the message boundaries lie.
Synchronization primitives
~~~~~~~~~~~~~~~~~~~~~~~~~~
.. currentmodule:: multiprocessing
Generally synchronization primitives are not as necessary in a multiprocess
program as they are in a multithreaded program. See the documentation for
:mod:`threading` module.
Note that one can also create synchronization primitives by using a manager
object -- see :ref:`multiprocessing-managers`.
.. class:: BoundedSemaphore([value])
A bounded semaphore object: a close analog of
:class:`threading.BoundedSemaphore`.
A solitary difference from its close analog exists: its ``acquire`` method's
first argument is named *block* and it supports an optional second argument
*timeout*, as is consistent with :meth:`Lock.acquire`.
.. note::
On Mac OS X, this is indistinguishable from :class:`Semaphore` because
``sem_getvalue()`` is not implemented on that platform.
.. class:: Condition([lock])
A condition variable: a clone of :class:`threading.Condition`.
If *lock* is specified then it should be a :class:`Lock` or :class:`RLock`
object from :mod:`multiprocessing`.
.. class:: Event()
A clone of :class:`threading.Event`.
This method returns the state of the internal semaphore on exit, so it
will always return ``True`` except if a timeout is given and the operation
times out.
.. versionchanged:: 2.7
Previously, the method always returned ``None``.
.. class:: Lock()
A non-recursive lock object: a close analog of :class:`threading.Lock`.
Once a process or thread has acquired a lock, subsequent attempts to
acquire it from any process or thread will block until it is released;
any process or thread may release it. The concepts and behaviors of
:class:`threading.Lock` as it applies to threads are replicated here in
:class:`multiprocessing.Lock` as it applies to either processes or threads,
except as noted.
Note that :class:`Lock` is actually a factory function which returns an
instance of ``multiprocessing.synchronize.Lock`` initialized with a
default context.
:class:`Lock` supports the :term:`context manager` protocol and thus may be
used in :keyword:`with` statements.
.. method:: acquire(block=True, timeout=None)
Acquire a lock, blocking or non-blocking.
With the *block* argument set to ``True`` (the default), the method call
will block until the lock is in an unlocked state, then set it to locked
and return ``True``. Note that the name of this first argument differs
from that in :meth:`threading.Lock.acquire`.
With the *block* argument set to ``False``, the method call does not
block. If the lock is currently in a locked state, return ``False``;
otherwise set the lock to a locked state and return ``True``.
When invoked with a positive, floating-point value for *timeout*, block
for at most the number of seconds specified by *timeout* as long as
the lock can not be acquired. Invocations with a negative value for
*timeout* are equivalent to a *timeout* of zero. Invocations with a
*timeout* value of ``None`` (the default) set the timeout period to
infinite. The *timeout* argument has no practical implications if the
*block* argument is set to ``False`` and is thus ignored. Returns
``True`` if the lock has been acquired or ``False`` if the timeout period
has elapsed. Note that the *timeout* argument does not exist in this
method's analog, :meth:`threading.Lock.acquire`.
.. method:: release()
Release a lock. This can be called from any process or thread, not only
the process or thread which originally acquired the lock.
Behavior is the same as in :meth:`threading.Lock.release` except that
when invoked on an unlocked lock, a :exc:`ValueError` is raised.
.. class:: RLock()
A recursive lock object: a close analog of :class:`threading.RLock`. A
recursive lock must be released by the process or thread that acquired it.
Once a process or thread has acquired a recursive lock, the same process
or thread may acquire it again without blocking; that process or thread
must release it once for each time it has been acquired.
Note that :class:`RLock` is actually a factory function which returns an
instance of ``multiprocessing.synchronize.RLock`` initialized with a
default context.
:class:`RLock` supports the :term:`context manager` protocol and thus may be
used in :keyword:`with` statements.
.. method:: acquire(block=True, timeout=None)
Acquire a lock, blocking or non-blocking.
When invoked with the *block* argument set to ``True``, block until the
lock is in an unlocked state (not owned by any process or thread) unless
the lock is already owned by the current process or thread. The current
process or thread then takes ownership of the lock (if it does not
already have ownership) and the recursion level inside the lock increments
by one, resulting in a return value of ``True``. Note that there are
several differences in this first argument's behavior compared to the
implementation of :meth:`threading.RLock.acquire`, starting with the name
of the argument itself.
When invoked with the *block* argument set to ``False``, do not block.
If the lock has already been acquired (and thus is owned) by another
process or thread, the current process or thread does not take ownership
and the recursion level within the lock is not changed, resulting in
a return value of ``False``. If the lock is in an unlocked state, the
current process or thread takes ownership and the recursion level is
incremented, resulting in a return value of ``True``.
Use and behaviors of the *timeout* argument are the same as in
:meth:`Lock.acquire`. Note that the *timeout* argument does
not exist in this method's analog, :meth:`threading.RLock.acquire`.
.. method:: release()
Release a lock, decrementing the recursion level. If after the
decrement the recursion level is zero, reset the lock to unlocked (not
owned by any process or thread) and if any other processes or threads
are blocked waiting for the lock to become unlocked, allow exactly one
of them to proceed. If after the decrement the recursion level is still
nonzero, the lock remains locked and owned by the calling process or
thread.
Only call this method when the calling process or thread owns the lock.
An :exc:`AssertionError` is raised if this method is called by a process
or thread other than the owner or if the lock is in an unlocked (unowned)
state. Note that the type of exception raised in this situation
differs from the implemented behavior in :meth:`threading.RLock.release`.
.. class:: Semaphore([value])
A semaphore object: a close analog of :class:`threading.Semaphore`.
A solitary difference from its close analog exists: its ``acquire`` method's
first argument is named *block* and it supports an optional second argument
*timeout*, as is consistent with :meth:`Lock.acquire`.
.. note::
The :meth:`acquire` method of :class:`BoundedSemaphore`, :class:`Lock`,
:class:`RLock` and :class:`Semaphore` has a timeout parameter not supported
by the equivalents in :mod:`threading`. The signature is
``acquire(block=True, timeout=None)`` with keyword parameters being
acceptable. If *block* is ``True`` and *timeout* is not ``None`` then it
specifies a timeout in seconds. If *block* is ``False`` then *timeout* is
ignored.
On Mac OS X, ``sem_timedwait`` is unsupported, so calling ``acquire()`` with
a timeout will emulate that function's behavior using a sleeping loop.
.. note::
If the SIGINT signal generated by :kbd:`Ctrl-C` arrives while the main thread is
blocked by a call to :meth:`BoundedSemaphore.acquire`, :meth:`Lock.acquire`,
:meth:`RLock.acquire`, :meth:`Semaphore.acquire`, :meth:`Condition.acquire`
or :meth:`Condition.wait` then the call will be immediately interrupted and
:exc:`KeyboardInterrupt` will be raised.
This differs from the behaviour of :mod:`threading` where SIGINT will be
ignored while the equivalent blocking calls are in progress.
.. note::
Some of this package's functionality requires a functioning shared semaphore
implementation on the host operating system. Without one, the
:mod:`multiprocessing.synchronize` module will be disabled, and attempts to
import it will result in an :exc:`ImportError`. See
:issue:`3770` for additional information.
Shared :mod:`ctypes` Objects
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
It is possible to create shared objects using shared memory which can be
inherited by child processes.
.. function:: Value(typecode_or_type, *args[, lock])
Return a :mod:`ctypes` object allocated from shared memory. By default the
return value is actually a synchronized wrapper for the object.
*typecode_or_type* determines the type of the returned object: it is either a
ctypes type or a one character typecode of the kind used by the :mod:`array`
module. *\*args* is passed on to the constructor for the type.
If *lock* is ``True`` (the default) then a new recursive lock
object is created to synchronize access to the value. If *lock* is
a :class:`Lock` or :class:`RLock` object then that will be used to
synchronize access to the value. If *lock* is ``False`` then
access to the returned object will not be automatically protected
by a lock, so it will not necessarily be "process-safe".
Operations like ``+=`` which involve a read and write are not
atomic. So if, for instance, you want to atomically increment a
shared value it is insufficient to just do ::
counter.value += 1
Assuming the associated lock is recursive (which it is by default)
you can instead do ::
with counter.get_lock():
counter.value += 1
Note that *lock* is a keyword-only argument.
.. function:: Array(typecode_or_type, size_or_initializer, *, lock=True)
Return a ctypes array allocated from shared memory. By default the return
value is actually a synchronized wrapper for the array.
*typecode_or_type* determines the type of the elements of the returned array:
it is either a ctypes type or a one character typecode of the kind used by
the :mod:`array` module. If *size_or_initializer* is an integer, then it
determines the length of the array, and the array will be initially zeroed.
Otherwise, *size_or_initializer* is a sequence which is used to initialize
the array and whose length determines the length of the array.
If *lock* is ``True`` (the default) then a new lock object is created to
synchronize access to the value. If *lock* is a :class:`Lock` or
:class:`RLock` object then that will be used to synchronize access to the
value. If *lock* is ``False`` then access to the returned object will not be
automatically protected by a lock, so it will not necessarily be
"process-safe".
Note that *lock* is a keyword only argument.
Note that an array of :data:`ctypes.c_char` has *value* and *raw*
attributes which allow one to use it to store and retrieve strings.
The :mod:`multiprocessing.sharedctypes` module
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
.. module:: multiprocessing.sharedctypes
:synopsis: Allocate ctypes objects from shared memory.
The :mod:`multiprocessing.sharedctypes` module provides functions for allocating
:mod:`ctypes` objects from shared memory which can be inherited by child
processes.
.. note::
Although it is possible to store a pointer in shared memory remember that
this will refer to a location in the address space of a specific process.
However, the pointer is quite likely to be invalid in the context of a second
process and trying to dereference the pointer from the second process may
cause a crash.
.. function:: RawArray(typecode_or_type, size_or_initializer)
Return a ctypes array allocated from shared memory.
*typecode_or_type* determines the type of the elements of the returned array:
it is either a ctypes type or a one character typecode of the kind used by
the :mod:`array` module. If *size_or_initializer* is an integer then it
determines the length of the array, and the array will be initially zeroed.
Otherwise *size_or_initializer* is a sequence which is used to initialize the
array and whose length determines the length of the array.
Note that setting and getting an element is potentially non-atomic -- use
:func:`Array` instead to make sure that access is automatically synchronized
using a lock.
.. function:: RawValue(typecode_or_type, *args)
Return a ctypes object allocated from shared memory.
*typecode_or_type* determines the type of the returned object: it is either a
ctypes type or a one character typecode of the kind used by the :mod:`array`
module. *\*args* is passed on to the constructor for the type.
Note that setting and getting the value is potentially non-atomic -- use
:func:`Value` instead to make sure that access is automatically synchronized
using a lock.
Note that an array of :data:`ctypes.c_char` has ``value`` and ``raw``
attributes which allow one to use it to store and retrieve strings -- see
documentation for :mod:`ctypes`.
.. function:: Array(typecode_or_type, size_or_initializer, *args[, lock])
The same as :func:`RawArray` except that depending on the value of *lock* a
process-safe synchronization wrapper may be returned instead of a raw ctypes
array.
If *lock* is ``True`` (the default) then a new lock object is created to
synchronize access to the value. If *lock* is a
:class:`~multiprocessing.Lock` or :class:`~multiprocessing.RLock` object
then that will be used to synchronize access to the
value. If *lock* is ``False`` then access to the returned object will not be
automatically protected by a lock, so it will not necessarily be
"process-safe".
Note that *lock* is a keyword-only argument.
.. function:: Value(typecode_or_type, *args[, lock])
The same as :func:`RawValue` except that depending on the value of *lock* a
process-safe synchronization wrapper may be returned instead of a raw ctypes
object.
If *lock* is ``True`` (the default) then a new lock object is created to
synchronize access to the value. If *lock* is a :class:`~multiprocessing.Lock` or
:class:`~multiprocessing.RLock` object then that will be used to synchronize access to the
value. If *lock* is ``False`` then access to the returned object will not be
automatically protected by a lock, so it will not necessarily be
"process-safe".
Note that *lock* is a keyword-only argument.
.. function:: copy(obj)
Return a ctypes object allocated from shared memory which is a copy of the
ctypes object *obj*.
.. function:: synchronized(obj[, lock])
Return a process-safe wrapper object for a ctypes object which uses *lock* to
synchronize access. If *lock* is ``None`` (the default) then a
:class:`multiprocessing.RLock` object is created automatically.
A synchronized wrapper will have two methods in addition to those of the
object it wraps: :meth:`get_obj` returns the wrapped object and
:meth:`get_lock` returns the lock object used for synchronization.
Note that accessing the ctypes object through the wrapper can be a lot slower
than accessing the raw ctypes object.
The table below compares the syntax for creating shared ctypes objects from
shared memory with the normal ctypes syntax. (In the table ``MyStruct`` is some
subclass of :class:`ctypes.Structure`.)
==================== ========================== ===========================
ctypes sharedctypes using type sharedctypes using typecode
==================== ========================== ===========================
c_double(2.4) RawValue(c_double, 2.4) RawValue('d', 2.4)
MyStruct(4, 6) RawValue(MyStruct, 4, 6)
(c_short * 7)() RawArray(c_short, 7) RawArray('h', 7)
(c_int * 3)(9, 2, 8) RawArray(c_int, (9, 2, 8)) RawArray('i', (9, 2, 8))
==================== ========================== ===========================
Below is an example where a number of ctypes objects are modified by a child
process::
from multiprocessing import Process, Lock
from multiprocessing.sharedctypes import Value, Array
from ctypes import Structure, c_double
class Point(Structure):
_fields_ = [('x', c_double), ('y', c_double)]
def modify(n, x, s, A):
n.value **= 2
x.value **= 2
s.value = s.value.upper()
for a in A:
a.x **= 2
a.y **= 2
if __name__ == '__main__':
lock = Lock()
n = Value('i', 7)
x = Value(c_double, 1.0/3.0, lock=False)
s = Array('c', 'hello world', lock=lock)
A = Array(Point, [(1.875,-6.25), (-5.75,2.0), (2.375,9.5)], lock=lock)
p = Process(target=modify, args=(n, x, s, A))
p.start()
p.join()
print n.value
print x.value
print s.value
print [(a.x, a.y) for a in A]
.. highlightlang:: none
The results printed are ::
49
0.1111111111111111
HELLO WORLD
[(3.515625, 39.0625), (33.0625, 4.0), (5.640625, 90.25)]
.. highlightlang:: python
.. _multiprocessing-managers:
Managers
~~~~~~~~
Managers provide a way to create data which can be shared between different
processes. A manager object controls a server process which manages *shared
objects*. Other processes can access the shared objects by using proxies.
.. function:: multiprocessing.Manager()
Returns a started :class:`~multiprocessing.managers.SyncManager` object which
can be used for sharing objects between processes. The returned manager
object corresponds to a spawned child process and has methods which will
create shared objects and return corresponding proxies.
.. module:: multiprocessing.managers
:synopsis: Share data between process with shared objects.
Manager processes will be shutdown as soon as they are garbage collected or
their parent process exits. The manager classes are defined in the
:mod:`multiprocessing.managers` module:
.. class:: BaseManager([address[, authkey]])
Create a BaseManager object.
Once created one should call :meth:`start` or ``get_server().serve_forever()`` to ensure
that the manager object refers to a started manager process.
*address* is the address on which the manager process listens for new
connections. If *address* is ``None`` then an arbitrary one is chosen.
*authkey* is the authentication key which will be used to check the validity
of incoming connections to the server process. If *authkey* is ``None`` then
``current_process().authkey``. Otherwise *authkey* is used and it
must be a string.
.. method:: start([initializer[, initargs]])
Start a subprocess to start the manager. If *initializer* is not ``None``
then the subprocess will call ``initializer(*initargs)`` when it starts.
.. method:: get_server()
Returns a :class:`Server` object which represents the actual server under
the control of the Manager. The :class:`Server` object supports the
:meth:`serve_forever` method::
>>> from multiprocessing.managers import BaseManager
>>> manager = BaseManager(address=('', 50000), authkey='abc')
>>> server = manager.get_server()
>>> server.serve_forever()
:class:`Server` additionally has an :attr:`address` attribute.
.. method:: connect()
Connect a local manager object to a remote manager process::
>>> from multiprocessing.managers import BaseManager
>>> m = BaseManager(address=('127.0.0.1', 5000), authkey='abc')
>>> m.connect()
.. method:: shutdown()
Stop the process used by the manager. This is only available if
:meth:`start` has been used to start the server process.
This can be called multiple times.
.. method:: register(typeid[, callable[, proxytype[, exposed[, method_to_typeid[, create_method]]]]])
A classmethod which can be used for registering a type or callable with
the manager class.
*typeid* is a "type identifier" which is used to identify a particular
type of shared object. This must be a string.
*callable* is a callable used for creating objects for this type
identifier. If a manager instance will be created using the
:meth:`from_address` classmethod or if the *create_method* argument is
``False`` then this can be left as ``None``.
*proxytype* is a subclass of :class:`BaseProxy` which is used to create
proxies for shared objects with this *typeid*. If ``None`` then a proxy
class is created automatically.
*exposed* is used to specify a sequence of method names which proxies for
this typeid should be allowed to access using
:meth:`BaseProxy._callmethod`. (If *exposed* is ``None`` then
:attr:`proxytype._exposed_` is used instead if it exists.) In the case
where no exposed list is specified, all "public methods" of the shared
object will be accessible. (Here a "public method" means any attribute
which has a :meth:`~object.__call__` method and whose name does not begin
with ``'_'``.)
*method_to_typeid* is a mapping used to specify the return type of those
exposed methods which should return a proxy. It maps method names to
typeid strings. (If *method_to_typeid* is ``None`` then
:attr:`proxytype._method_to_typeid_` is used instead if it exists.) If a
method's name is not a key of this mapping or if the mapping is ``None``
then the object returned by the method will be copied by value.
*create_method* determines whether a method should be created with name
*typeid* which can be used to tell the server process to create a new
shared object and return a proxy for it. By default it is ``True``.
:class:`BaseManager` instances also have one read-only property:
.. attribute:: address
The address used by the manager.
.. class:: SyncManager
A subclass of :class:`BaseManager` which can be used for the synchronization
of processes. Objects of this type are returned by
:func:`multiprocessing.Manager`.
It also supports creation of shared lists and dictionaries.
.. method:: BoundedSemaphore([value])
Create a shared :class:`threading.BoundedSemaphore` object and return a
proxy for it.
.. method:: Condition([lock])
Create a shared :class:`threading.Condition` object and return a proxy for
it.
If *lock* is supplied then it should be a proxy for a
:class:`threading.Lock` or :class:`threading.RLock` object.
.. method:: Event()
Create a shared :class:`threading.Event` object and return a proxy for it.
.. method:: Lock()
Create a shared :class:`threading.Lock` object and return a proxy for it.
.. method:: Namespace()
Create a shared :class:`Namespace` object and return a proxy for it.
.. method:: Queue([maxsize])
Create a shared :class:`Queue.Queue` object and return a proxy for it.
.. method:: RLock()
Create a shared :class:`threading.RLock` object and return a proxy for it.
.. method:: Semaphore([value])
Create a shared :class:`threading.Semaphore` object and return a proxy for
it.
.. method:: Array(typecode, sequence)
Create an array and return a proxy for it.
.. method:: Value(typecode, value)
Create an object with a writable ``value`` attribute and return a proxy
for it.
.. method:: dict()
dict(mapping)
dict(sequence)
Create a shared ``dict`` object and return a proxy for it.
.. method:: list()
list(sequence)
Create a shared ``list`` object and return a proxy for it.
.. note::
Modifications to mutable values or items in dict and list proxies will not
be propagated through the manager, because the proxy has no way of knowing
when its values or items are modified. To modify such an item, you can
re-assign the modified object to the container proxy::
# create a list proxy and append a mutable object (a dictionary)
lproxy = manager.list()
lproxy.append({})
# now mutate the dictionary
d = lproxy[0]
d['a'] = 1
d['b'] = 2
# at this point, the changes to d are not yet synced, but by
# reassigning the dictionary, the proxy is notified of the change
lproxy[0] = d
.. class:: Namespace
A type that can register with :class:`SyncManager`.
A namespace object has no public methods, but does have writable attributes.
Its representation shows the values of its attributes.
However, when using a proxy for a namespace object, an attribute beginning with
``'_'`` will be an attribute of the proxy and not an attribute of the referent:
.. doctest::
>>> manager = multiprocessing.Manager()
>>> Global = manager.Namespace()
>>> Global.x = 10
>>> Global.y = 'hello'
>>> Global._z = 12.3 # this is an attribute of the proxy
>>> print Global
Namespace(x=10, y='hello')
Customized managers
>>>>>>>>>>>>>>>>>>>
To create one's own manager, one creates a subclass of :class:`BaseManager` and
uses the :meth:`~BaseManager.register` classmethod to register new types or
callables with the manager class. For example::
from multiprocessing.managers import BaseManager
class MathsClass(object):
def add(self, x, y):
return x + y
def mul(self, x, y):
return x * y
class MyManager(BaseManager):
pass
MyManager.register('Maths', MathsClass)
if __name__ == '__main__':
manager = MyManager()
manager.start()
maths = manager.Maths()
print maths.add(4, 3) # prints 7
print maths.mul(7, 8) # prints 56
Using a remote manager
>>>>>>>>>>>>>>>>>>>>>>
It is possible to run a manager server on one machine and have clients use it
from other machines (assuming that the firewalls involved allow it).
Running the following commands creates a server for a single shared queue which
remote clients can access::
>>> from multiprocessing.managers import BaseManager
>>> import Queue
>>> queue = Queue.Queue()
>>> class QueueManager(BaseManager): pass
>>> QueueManager.register('get_queue', callable=lambda:queue)
>>> m = QueueManager(address=('', 50000), authkey='abracadabra')
>>> s = m.get_server()
>>> s.serve_forever()
One client can access the server as follows::
>>> from multiprocessing.managers import BaseManager
>>> class QueueManager(BaseManager): pass
>>> QueueManager.register('get_queue')
>>> m = QueueManager(address=('foo.bar.org', 50000), authkey='abracadabra')
>>> m.connect()
>>> queue = m.get_queue()
>>> queue.put('hello')
Another client can also use it::
>>> from multiprocessing.managers import BaseManager
>>> class QueueManager(BaseManager): pass
>>> QueueManager.register('get_queue')
>>> m = QueueManager(address=('foo.bar.org', 50000), authkey='abracadabra')
>>> m.connect()
>>> queue = m.get_queue()
>>> queue.get()
'hello'
Local processes can also access that queue, using the code from above on the
client to access it remotely::
>>> from multiprocessing import Process, Queue
>>> from multiprocessing.managers import BaseManager
>>> class Worker(Process):
... def __init__(self, q):
... self.q = q
... super(Worker, self).__init__()
... def run(self):
... self.q.put('local hello')
...
>>> queue = Queue()
>>> w = Worker(queue)
>>> w.start()
>>> class QueueManager(BaseManager): pass
...
>>> QueueManager.register('get_queue', callable=lambda: queue)
>>> m = QueueManager(address=('', 50000), authkey='abracadabra')
>>> s = m.get_server()
>>> s.serve_forever()
Proxy Objects
~~~~~~~~~~~~~
A proxy is an object which *refers* to a shared object which lives (presumably)
in a different process. The shared object is said to be the *referent* of the
proxy. Multiple proxy objects may have the same referent.
A proxy object has methods which invoke corresponding methods of its referent
(although not every method of the referent will necessarily be available through
the proxy). A proxy can usually be used in most of the same ways that its
referent can:
.. doctest::
>>> from multiprocessing import Manager
>>> manager = Manager()
>>> l = manager.list([i*i for i in range(10)])
>>> print l
[0, 1, 4, 9, 16, 25, 36, 49, 64, 81]
>>> print repr(l)
<ListProxy object, typeid 'list' at 0x...>
>>> l[4]
16
>>> l[2:5]
[4, 9, 16]
Notice that applying :func:`str` to a proxy will return the representation of
the referent, whereas applying :func:`repr` will return the representation of
the proxy.
An important feature of proxy objects is that they are picklable so they can be
passed between processes. Note, however, that if a proxy is sent to the
corresponding manager's process then unpickling it will produce the referent
itself. This means, for example, that one shared object can contain a second:
.. doctest::
>>> a = manager.list()
>>> b = manager.list()
>>> a.append(b) # referent of a now contains referent of b
>>> print a, b
[[]] []
>>> b.append('hello')
>>> print a, b
[['hello']] ['hello']
.. note::
The proxy types in :mod:`multiprocessing` do nothing to support comparisons
by value. So, for instance, we have:
.. doctest::
>>> manager.list([1,2,3]) == [1,2,3]
False
One should just use a copy of the referent instead when making comparisons.
.. class:: BaseProxy
Proxy objects are instances of subclasses of :class:`BaseProxy`.
.. method:: _callmethod(methodname[, args[, kwds]])
Call and return the result of a method of the proxy's referent.
If ``proxy`` is a proxy whose referent is ``obj`` then the expression ::
proxy._callmethod(methodname, args, kwds)
will evaluate the expression ::
getattr(obj, methodname)(*args, **kwds)
in the manager's process.
The returned value will be a copy of the result of the call or a proxy to
a new shared object -- see documentation for the *method_to_typeid*
argument of :meth:`BaseManager.register`.
If an exception is raised by the call, then is re-raised by
:meth:`_callmethod`. If some other exception is raised in the manager's
process then this is converted into a :exc:`RemoteError` exception and is
raised by :meth:`_callmethod`.
Note in particular that an exception will be raised if *methodname* has
not been *exposed*.
An example of the usage of :meth:`_callmethod`:
.. doctest::
>>> l = manager.list(range(10))
>>> l._callmethod('__len__')
10
>>> l._callmethod('__getslice__', (2, 7)) # equiv to `l[2:7]`
[2, 3, 4, 5, 6]
>>> l._callmethod('__getitem__', (20,)) # equiv to `l[20]`
Traceback (most recent call last):
...
IndexError: list index out of range
.. method:: _getvalue()
Return a copy of the referent.
If the referent is unpicklable then this will raise an exception.
.. method:: __repr__
Return a representation of the proxy object.
.. method:: __str__
Return the representation of the referent.
Cleanup
>>>>>>>
A proxy object uses a weakref callback so that when it gets garbage collected it
deregisters itself from the manager which owns its referent.
A shared object gets deleted from the manager process when there are no longer
any proxies referring to it.
Process Pools
~~~~~~~~~~~~~
.. module:: multiprocessing.pool
:synopsis: Create pools of processes.
One can create a pool of processes which will carry out tasks submitted to it
with the :class:`Pool` class.
.. class:: multiprocessing.Pool([processes[, initializer[, initargs[, maxtasksperchild]]]])
A process pool object which controls a pool of worker processes to which jobs
can be submitted. It supports asynchronous results with timeouts and
callbacks and has a parallel map implementation.
*processes* is the number of worker processes to use. If *processes* is
``None`` then the number returned by :func:`cpu_count` is used. If
*initializer* is not ``None`` then each worker process will call
``initializer(*initargs)`` when it starts.
Note that the methods of the pool object should only be called by
the process which created the pool.
.. versionadded:: 2.7
*maxtasksperchild* is the number of tasks a worker process can complete
before it will exit and be replaced with a fresh worker process, to enable
unused resources to be freed. The default *maxtasksperchild* is ``None``, which
means worker processes will live as long as the pool.
.. note::
Worker processes within a :class:`Pool` typically live for the complete
duration of the Pool's work queue. A frequent pattern found in other
systems (such as Apache, mod_wsgi, etc) to free resources held by
workers is to allow a worker within a pool to complete only a set
amount of work before being exiting, being cleaned up and a new
process spawned to replace the old one. The *maxtasksperchild*
argument to the :class:`Pool` exposes this ability to the end user.
.. method:: apply(func[, args[, kwds]])
Equivalent of the :func:`apply` built-in function. It blocks until the
result is ready, so :meth:`apply_async` is better suited for performing
work in parallel. Additionally, *func* is only executed in one of the
workers of the pool.
.. method:: apply_async(func[, args[, kwds[, callback]]])
A variant of the :meth:`apply` method which returns a result object.
If *callback* is specified then it should be a callable which accepts a
single argument. When the result becomes ready *callback* is applied to
it (unless the call failed). *callback* should complete immediately since
otherwise the thread which handles the results will get blocked.
.. method:: map(func, iterable[, chunksize])
A parallel equivalent of the :func:`map` built-in function (it supports only
one *iterable* argument though). It blocks until the result is ready.
This method chops the iterable into a number of chunks which it submits to
the process pool as separate tasks. The (approximate) size of these
chunks can be specified by setting *chunksize* to a positive integer.
.. method:: map_async(func, iterable[, chunksize[, callback]])
A variant of the :meth:`.map` method which returns a result object.
If *callback* is specified then it should be a callable which accepts a
single argument. When the result becomes ready *callback* is applied to
it (unless the call failed). *callback* should complete immediately since
otherwise the thread which handles the results will get blocked.
.. method:: imap(func, iterable[, chunksize])
An equivalent of :func:`itertools.imap`.
The *chunksize* argument is the same as the one used by the :meth:`.map`
method. For very long iterables using a large value for *chunksize* can
make the job complete **much** faster than using the default value of
``1``.
Also if *chunksize* is ``1`` then the :meth:`!next` method of the iterator
returned by the :meth:`imap` method has an optional *timeout* parameter:
``next(timeout)`` will raise :exc:`multiprocessing.TimeoutError` if the
result cannot be returned within *timeout* seconds.
.. method:: imap_unordered(func, iterable[, chunksize])
The same as :meth:`imap` except that the ordering of the results from the
returned iterator should be considered arbitrary. (Only when there is
only one worker process is the order guaranteed to be "correct".)
.. method:: close()
Prevents any more tasks from being submitted to the pool. Once all the
tasks have been completed the worker processes will exit.
.. method:: terminate()
Stops the worker processes immediately without completing outstanding
work. When the pool object is garbage collected :meth:`terminate` will be
called immediately.
.. method:: join()
Wait for the worker processes to exit. One must call :meth:`close` or
:meth:`terminate` before using :meth:`join`.
.. class:: AsyncResult
The class of the result returned by :meth:`Pool.apply_async` and
:meth:`Pool.map_async`.
.. method:: get([timeout])
Return the result when it arrives. If *timeout* is not ``None`` and the
result does not arrive within *timeout* seconds then
:exc:`multiprocessing.TimeoutError` is raised. If the remote call raised
an exception then that exception will be reraised by :meth:`get`.
.. method:: wait([timeout])
Wait until the result is available or until *timeout* seconds pass.
.. method:: ready()
Return whether the call has completed.
.. method:: successful()
Return whether the call completed without raising an exception. Will
raise :exc:`AssertionError` if the result is not ready.
The following example demonstrates the use of a pool::
from multiprocessing import Pool
import time
def f(x):
return x*x
if __name__ == '__main__':
pool = Pool(processes=4) # start 4 worker processes
result = pool.apply_async(f, (10,)) # evaluate "f(10)" asynchronously in a single process
print result.get(timeout=1) # prints "100" unless your computer is *very* slow
print pool.map(f, range(10)) # prints "[0, 1, 4,..., 81]"
it = pool.imap(f, range(10))
print it.next() # prints "0"
print it.next() # prints "1"
print it.next(timeout=1) # prints "4" unless your computer is *very* slow
result = pool.apply_async(time.sleep, (10,))
print result.get(timeout=1) # raises multiprocessing.TimeoutError
.. _multiprocessing-listeners-clients:
Listeners and Clients
~~~~~~~~~~~~~~~~~~~~~
.. module:: multiprocessing.connection
:synopsis: API for dealing with sockets.
Usually message passing between processes is done using queues or by using
:class:`Connection` objects returned by :func:`~multiprocessing.Pipe`.
However, the :mod:`multiprocessing.connection` module allows some extra
flexibility. It basically gives a high level message oriented API for dealing
with sockets or Windows named pipes, and also has support for *digest
authentication* using the :mod:`hmac` module.
.. function:: deliver_challenge(connection, authkey)
Send a randomly generated message to the other end of the connection and wait
for a reply.
If the reply matches the digest of the message using *authkey* as the key
then a welcome message is sent to the other end of the connection. Otherwise
:exc:`AuthenticationError` is raised.
.. function:: answer_challenge(connection, authkey)
Receive a message, calculate the digest of the message using *authkey* as the
key, and then send the digest back.
If a welcome message is not received, then :exc:`AuthenticationError` is
raised.
.. function:: Client(address[, family[, authenticate[, authkey]]])
Attempt to set up a connection to the listener which is using address
*address*, returning a :class:`Connection`.
The type of the connection is determined by *family* argument, but this can
generally be omitted since it can usually be inferred from the format of
*address*. (See :ref:`multiprocessing-address-formats`)
If *authenticate* is ``True`` or *authkey* is a string then digest
authentication is used. The key used for authentication will be either
*authkey* or ``current_process().authkey)`` if *authkey* is ``None``.
If authentication fails then :exc:`AuthenticationError` is raised. See
:ref:`multiprocessing-auth-keys`.
.. class:: Listener([address[, family[, backlog[, authenticate[, authkey]]]]])
A wrapper for a bound socket or Windows named pipe which is 'listening' for
connections.
*address* is the address to be used by the bound socket or named pipe of the
listener object.
.. note::
If an address of '0.0.0.0' is used, the address will not be a connectable
end point on Windows. If you require a connectable end-point,
you should use '127.0.0.1'.
*family* is the type of socket (or named pipe) to use. This can be one of
the strings ``'AF_INET'`` (for a TCP socket), ``'AF_UNIX'`` (for a Unix
domain socket) or ``'AF_PIPE'`` (for a Windows named pipe). Of these only
the first is guaranteed to be available. If *family* is ``None`` then the
family is inferred from the format of *address*. If *address* is also
``None`` then a default is chosen. This default is the family which is
assumed to be the fastest available. See
:ref:`multiprocessing-address-formats`. Note that if *family* is
``'AF_UNIX'`` and address is ``None`` then the socket will be created in a
private temporary directory created using :func:`tempfile.mkstemp`.
If the listener object uses a socket then *backlog* (1 by default) is passed
to the :meth:`~socket.socket.listen` method of the socket once it has been
bound.
If *authenticate* is ``True`` (``False`` by default) or *authkey* is not
``None`` then digest authentication is used.
If *authkey* is a string then it will be used as the authentication key;
otherwise it must be ``None``.
If *authkey* is ``None`` and *authenticate* is ``True`` then
``current_process().authkey`` is used as the authentication key. If
*authkey* is ``None`` and *authenticate* is ``False`` then no
authentication is done. If authentication fails then
:exc:`AuthenticationError` is raised. See :ref:`multiprocessing-auth-keys`.
.. method:: accept()
Accept a connection on the bound socket or named pipe of the listener
object and return a :class:`Connection` object.
If authentication is attempted and fails, then
:exc:`~multiprocessing.AuthenticationError` is raised.
.. method:: close()
Close the bound socket or named pipe of the listener object. This is
called automatically when the listener is garbage collected. However it
is advisable to call it explicitly.
Listener objects have the following read-only properties:
.. attribute:: address
The address which is being used by the Listener object.
.. attribute:: last_accepted
The address from which the last accepted connection came. If this is
unavailable then it is ``None``.
The module defines the following exceptions:
.. exception:: ProcessError
The base class of all :mod:`multiprocessing` exceptions.
.. exception:: BufferTooShort
Exception raised by :meth:`Connection.recv_bytes_into()` when the supplied
buffer object is too small for the message read.
.. exception:: AuthenticationError
Raised when there is an authentication error.
.. exception:: TimeoutError
Raised by methods with a timeout when the timeout expires.
**Examples**
The following server code creates a listener which uses ``'secret password'`` as
an authentication key. It then waits for a connection and sends some data to
the client::
from multiprocessing.connection import Listener
from array import array
address = ('localhost', 6000) # family is deduced to be 'AF_INET'
listener = Listener(address, authkey='secret password')
conn = listener.accept()
print 'connection accepted from', listener.last_accepted
conn.send([2.25, None, 'junk', float])
conn.send_bytes('hello')
conn.send_bytes(array('i', [42, 1729]))
conn.close()
listener.close()
The following code connects to the server and receives some data from the
server::
from multiprocessing.connection import Client
from array import array
address = ('localhost', 6000)
conn = Client(address, authkey='secret password')
print conn.recv() # => [2.25, None, 'junk', float]
print conn.recv_bytes() # => 'hello'
arr = array('i', [0, 0, 0, 0, 0])
print conn.recv_bytes_into(arr) # => 8
print arr # => array('i', [42, 1729, 0, 0, 0])
conn.close()
.. _multiprocessing-address-formats:
Address Formats
>>>>>>>>>>>>>>>
* An ``'AF_INET'`` address is a tuple of the form ``(hostname, port)`` where
*hostname* is a string and *port* is an integer.
* An ``'AF_UNIX'`` address is a string representing a filename on the
filesystem.
* An ``'AF_PIPE'`` address is a string of the form
:samp:`r'\\\\.\\pipe\\{PipeName}'`. To use :func:`Client` to connect to a named
pipe on a remote computer called *ServerName* one should use an address of the
form :samp:`r'\\\\{ServerName}\\pipe\\{PipeName}'` instead.
Note that any string beginning with two backslashes is assumed by default to be
an ``'AF_PIPE'`` address rather than an ``'AF_UNIX'`` address.
.. _multiprocessing-auth-keys:
Authentication keys
~~~~~~~~~~~~~~~~~~~
When one uses :meth:`Connection.recv`, the
data received is automatically
unpickled. Unfortunately unpickling data from an untrusted source is a security
risk. Therefore :class:`Listener` and :func:`Client` use the :mod:`hmac` module
to provide digest authentication.
An authentication key is a string which can be thought of as a password: once a
connection is established both ends will demand proof that the other knows the
authentication key. (Demonstrating that both ends are using the same key does
**not** involve sending the key over the connection.)
If authentication is requested but no authentication key is specified then the
return value of ``current_process().authkey`` is used (see
:class:`~multiprocessing.Process`). This value will be automatically inherited by
any :class:`~multiprocessing.Process` object that the current process creates.
This means that (by default) all processes of a multi-process program will share
a single authentication key which can be used when setting up connections
between themselves.
Suitable authentication keys can also be generated by using :func:`os.urandom`.
Logging
~~~~~~~
Some support for logging is available. Note, however, that the :mod:`logging`
package does not use process shared locks so it is possible (depending on the
handler type) for messages from different processes to get mixed up.
.. currentmodule:: multiprocessing
.. function:: get_logger()
Returns the logger used by :mod:`multiprocessing`. If necessary, a new one
will be created.
When first created the logger has level :data:`logging.NOTSET` and no
default handler. Messages sent to this logger will not by default propagate
to the root logger.
Note that on Windows child processes will only inherit the level of the
parent process's logger -- any other customization of the logger will not be
inherited.
.. currentmodule:: multiprocessing
.. function:: log_to_stderr()
This function performs a call to :func:`get_logger` but in addition to
returning the logger created by get_logger, it adds a handler which sends
output to :data:`sys.stderr` using format
``'[%(levelname)s/%(processName)s] %(message)s'``.
Below is an example session with logging turned on::
>>> import multiprocessing, logging
>>> logger = multiprocessing.log_to_stderr()
>>> logger.setLevel(logging.INFO)
>>> logger.warning('doomed')
[WARNING/MainProcess] doomed
>>> m = multiprocessing.Manager()
[INFO/SyncManager-...] child process calling self.run()
[INFO/SyncManager-...] created temp directory /.../pymp-...
[INFO/SyncManager-...] manager serving at '/.../listener-...'
>>> del m
[INFO/MainProcess] sending shutdown message to manager
[INFO/SyncManager-...] manager exiting with exitcode 0
In addition to having these two logging functions, the multiprocessing also
exposes two additional logging level attributes. These are :const:`SUBWARNING`
and :const:`SUBDEBUG`. The table below illustrates where theses fit in the
normal level hierarchy.
+----------------+----------------+
| Level | Numeric value |
+================+================+
| ``SUBWARNING`` | 25 |
+----------------+----------------+
| ``SUBDEBUG`` | 5 |
+----------------+----------------+
For a full table of logging levels, see the :mod:`logging` module.
These additional logging levels are used primarily for certain debug messages
within the multiprocessing module. Below is the same example as above, except
with :const:`SUBDEBUG` enabled::
>>> import multiprocessing, logging
>>> logger = multiprocessing.log_to_stderr()
>>> logger.setLevel(multiprocessing.SUBDEBUG)
>>> logger.warning('doomed')
[WARNING/MainProcess] doomed
>>> m = multiprocessing.Manager()
[INFO/SyncManager-...] child process calling self.run()
[INFO/SyncManager-...] created temp directory /.../pymp-...
[INFO/SyncManager-...] manager serving at '/.../pymp-djGBXN/listener-...'
>>> del m
[SUBDEBUG/MainProcess] finalizer calling ...
[INFO/MainProcess] sending shutdown message to manager
[DEBUG/SyncManager-...] manager received shutdown message
[SUBDEBUG/SyncManager-...] calling <Finalize object, callback=unlink, ...
[SUBDEBUG/SyncManager-...] finalizer calling <built-in function unlink> ...
[SUBDEBUG/SyncManager-...] calling <Finalize object, dead>
[SUBDEBUG/SyncManager-...] finalizer calling <function rmtree at 0x5aa730> ...
[INFO/SyncManager-...] manager exiting with exitcode 0
The :mod:`multiprocessing.dummy` module
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. module:: multiprocessing.dummy
:synopsis: Dumb wrapper around threading.
:mod:`multiprocessing.dummy` replicates the API of :mod:`multiprocessing` but is
no more than a wrapper around the :mod:`threading` module.
.. _multiprocessing-programming:
Programming guidelines
----------------------
There are certain guidelines and idioms which should be adhered to when using
:mod:`multiprocessing`.
All platforms
~~~~~~~~~~~~~
Avoid shared state
As far as possible one should try to avoid shifting large amounts of data
between processes.
It is probably best to stick to using queues or pipes for communication
between processes rather than using the lower level synchronization
primitives from the :mod:`threading` module.
Picklability
Ensure that the arguments to the methods of proxies are picklable.
Thread safety of proxies
Do not use a proxy object from more than one thread unless you protect it
with a lock.
(There is never a problem with different processes using the *same* proxy.)
Joining zombie processes
On Unix when a process finishes but has not been joined it becomes a zombie.
There should never be very many because each time a new process starts (or
:func:`~multiprocessing.active_children` is called) all completed processes
which have not yet been joined will be joined. Also calling a finished
process's :meth:`Process.is_alive <multiprocessing.Process.is_alive>` will
join the process. Even so it is probably good
practice to explicitly join all the processes that you start.
Better to inherit than pickle/unpickle
On Windows many types from :mod:`multiprocessing` need to be picklable so
that child processes can use them. However, one should generally avoid
sending shared objects to other processes using pipes or queues. Instead
you should arrange the program so that a process which needs access to a
shared resource created elsewhere can inherit it from an ancestor process.
Avoid terminating processes
Using the :meth:`Process.terminate <multiprocessing.Process.terminate>`
method to stop a process is liable to
cause any shared resources (such as locks, semaphores, pipes and queues)
currently being used by the process to become broken or unavailable to other
processes.
Therefore it is probably best to only consider using
:meth:`Process.terminate <multiprocessing.Process.terminate>` on processes
which never use any shared resources.
Joining processes that use queues
Bear in mind that a process that has put items in a queue will wait before
terminating until all the buffered items are fed by the "feeder" thread to
the underlying pipe. (The child process can call the
:meth:`~multiprocessing.Queue.cancel_join_thread` method of the queue to avoid this behaviour.)
This means that whenever you use a queue you need to make sure that all
items which have been put on the queue will eventually be removed before the
process is joined. Otherwise you cannot be sure that processes which have
put items on the queue will terminate. Remember also that non-daemonic
processes will be joined automatically.
An example which will deadlock is the following::
from multiprocessing import Process, Queue
def f(q):
q.put('X' * 1000000)
if __name__ == '__main__':
queue = Queue()
p = Process(target=f, args=(queue,))
p.start()
p.join() # this deadlocks
obj = queue.get()
A fix here would be to swap the last two lines (or simply remove the
``p.join()`` line).
Explicitly pass resources to child processes
On Unix a child process can make use of a shared resource created in a
parent process using a global resource. However, it is better to pass the
object as an argument to the constructor for the child process.
Apart from making the code (potentially) compatible with Windows this also
ensures that as long as the child process is still alive the object will not
be garbage collected in the parent process. This might be important if some
resource is freed when the object is garbage collected in the parent
process.
So for instance ::
from multiprocessing import Process, Lock
def f():
... do something using "lock" ...
if __name__ == '__main__':
lock = Lock()
for i in range(10):
Process(target=f).start()
should be rewritten as ::
from multiprocessing import Process, Lock
def f(l):
... do something using "l" ...
if __name__ == '__main__':
lock = Lock()
for i in range(10):
Process(target=f, args=(lock,)).start()
Beware of replacing :data:`sys.stdin` with a "file like object"
:mod:`multiprocessing` originally unconditionally called::
os.close(sys.stdin.fileno())
in the :meth:`multiprocessing.Process._bootstrap` method --- this resulted
in issues with processes-in-processes. This has been changed to::
sys.stdin.close()
sys.stdin = open(os.devnull)
Which solves the fundamental issue of processes colliding with each other
resulting in a bad file descriptor error, but introduces a potential danger
to applications which replace :func:`sys.stdin` with a "file-like object"
with output buffering. This danger is that if multiple processes call
:meth:`~io.IOBase.close()` on this file-like object, it could result in the same
data being flushed to the object multiple times, resulting in corruption.
If you write a file-like object and implement your own caching, you can
make it fork-safe by storing the pid whenever you append to the cache,
and discarding the cache when the pid changes. For example::
@property
def cache(self):
pid = os.getpid()
if pid != self._pid:
self._pid = pid
self._cache = []
return self._cache
For more information, see :issue:`5155`, :issue:`5313` and :issue:`5331`
Windows
~~~~~~~
Since Windows lacks :func:`os.fork` it has a few extra restrictions:
More picklability
Ensure that all arguments to :meth:`Process.__init__` are picklable. This
means, in particular, that bound or unbound methods cannot be used directly
as the ``target`` argument on Windows --- just define a function and use
that instead.
Also, if you subclass :class:`~multiprocessing.Process` then make sure that
instances will be picklable when the :meth:`Process.start
<multiprocessing.Process.start>` method is called.
Global variables
Bear in mind that if code run in a child process tries to access a global
variable, then the value it sees (if any) may not be the same as the value
in the parent process at the time that :meth:`Process.start
<multiprocessing.Process.start>` was called.
However, global variables which are just module level constants cause no
problems.
Safe importing of main module
Make sure that the main module can be safely imported by a new Python
interpreter without causing unintended side effects (such a starting a new
process).
For example, under Windows running the following module would fail with a
:exc:`RuntimeError`::
from multiprocessing import Process
def foo():
print 'hello'
p = Process(target=foo)
p.start()
Instead one should protect the "entry point" of the program by using ``if
__name__ == '__main__':`` as follows::
from multiprocessing import Process, freeze_support
def foo():
print 'hello'
if __name__ == '__main__':
freeze_support()
p = Process(target=foo)
p.start()
(The ``freeze_support()`` line can be omitted if the program will be run
normally instead of frozen.)
This allows the newly spawned Python interpreter to safely import the module
and then run the module's ``foo()`` function.
Similar restrictions apply if a pool or manager is created in the main
module.
.. _multiprocessing-examples:
Examples
--------
Demonstration of how to create and use customized managers and proxies:
.. literalinclude:: ../includes/mp_newtype.py
Using :class:`~multiprocessing.pool.Pool`:
.. literalinclude:: ../includes/mp_pool.py
Synchronization types like locks, conditions and queues:
.. literalinclude:: ../includes/mp_synchronize.py
An example showing how to use queues to feed tasks to a collection of worker
processes and collect the results:
.. literalinclude:: ../includes/mp_workers.py
An example of how a pool of worker processes can each run a
:class:`SimpleHTTPServer.HttpServer` instance while sharing a single listening
socket.
.. literalinclude:: ../includes/mp_webserver.py
Some simple benchmarks comparing :mod:`multiprocessing` with :mod:`threading`:
.. literalinclude:: ../includes/mp_benchmarks.py
PK %�\d+�N� � # html/_sources/library/mutex.rst.txtnu �[���
:mod:`mutex` --- Mutual exclusion support
=========================================
.. module:: mutex
:synopsis: Lock and queue for mutual exclusion.
:deprecated:
.. deprecated:: 2.6
The :mod:`mutex` module has been removed in Python 3.
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
The :mod:`mutex` module defines a class that allows mutual-exclusion via
acquiring and releasing locks. It does not require (or imply)
:mod:`threading` or multi-tasking, though it could be useful for those
purposes.
The :mod:`mutex` module defines the following class:
.. class:: mutex()
Create a new (unlocked) mutex.
A mutex has two pieces of state --- a "locked" bit and a queue. When the mutex
is not locked, the queue is empty. Otherwise, the queue contains zero or more
``(function, argument)`` pairs representing functions (or methods) waiting to
acquire the lock. When the mutex is unlocked while the queue is not empty, the
first queue entry is removed and its ``function(argument)`` pair called,
implying it now has the lock.
Of course, no multi-threading is implied -- hence the funny interface for
:meth:`lock`, where a function is called once the lock is acquired.
.. _mutex-objects:
Mutex Objects
-------------
:class:`~mutex.mutex` objects have following methods:
.. method:: mutex.test()
Check whether the mutex is locked.
.. method:: mutex.testandset()
"Atomic" test-and-set, grab the lock if it is not set, and return ``True``,
otherwise, return ``False``.
.. method:: mutex.lock(function, argument)
Execute ``function(argument)``, unless the mutex is locked. In the case it is
locked, place the function and argument on the queue. See :meth:`unlock` for
explanation of when ``function(argument)`` is executed in that case.
.. method:: mutex.unlock()
Unlock the mutex if queue is empty, otherwise execute the first element in the
queue.
PK %�\�~ZI� � % html/_sources/library/netdata.rst.txtnu �[���
.. _netdata:
**********************
Internet Data Handling
**********************
This chapter describes modules which support handling data formats commonly used
on the Internet.
.. toctree::
email.rst
json.rst
mailcap.rst
mailbox.rst
mhlib.rst
mimetools.rst
mimetypes.rst
mimewriter.rst
mimify.rst
multifile.rst
rfc822.rst
base64.rst
binhex.rst
binascii.rst
quopri.rst
uu.rst
PK %�\;>��/ / # html/_sources/library/netrc.rst.txtnu �[���
:mod:`netrc` --- netrc file processing
======================================
.. module:: netrc
:synopsis: Loading of .netrc files.
.. moduleauthor:: Eric S. Raymond <esr@snark.thyrsus.com>
.. sectionauthor:: Eric S. Raymond <esr@snark.thyrsus.com>
.. versionadded:: 1.5.2
**Source code:** :source:`Lib/netrc.py`
--------------
The :class:`~netrc.netrc` class parses and encapsulates the netrc file format used by
the Unix :program:`ftp` program and other FTP clients.
.. class:: netrc([file])
A :class:`~netrc.netrc` instance or subclass instance encapsulates data from a netrc
file. The initialization argument, if present, specifies the file to parse. If
no argument is given, the file :file:`.netrc` in the user's home directory will
be read. Parse errors will raise :exc:`NetrcParseError` with diagnostic
information including the file name, line number, and terminating token.
If no argument is specified on a POSIX system, the presence of passwords in
the :file:`.netrc` file will raise a :exc:`NetrcParseError` if the file
ownership or permissions are insecure (owned by a user other than the user
running the process, or accessible for read or write by any other user).
This implements security behavior equivalent to that of ftp and other
programs that use :file:`.netrc`.
.. versionchanged:: 2.7.6 Added the POSIX permissions check.
.. exception:: NetrcParseError
Exception raised by the :class:`~netrc.netrc` class when syntactical errors are
encountered in source text. Instances of this exception provide three
interesting attributes: :attr:`msg` is a textual explanation of the error,
:attr:`filename` is the name of the source file, and :attr:`lineno` gives the
line number on which the error was found.
.. _netrc-objects:
netrc Objects
-------------
A :class:`~netrc.netrc` instance has the following methods:
.. method:: netrc.authenticators(host)
Return a 3-tuple ``(login, account, password)`` of authenticators for *host*.
If the netrc file did not contain an entry for the given host, return the tuple
associated with the 'default' entry. If neither matching host nor default entry
is available, return ``None``.
.. method:: netrc.__repr__()
Dump the class data as a string in the format of a netrc file. (This discards
comments and may reorder the entries.)
Instances of :class:`~netrc.netrc` have public instance variables:
.. attribute:: netrc.hosts
Dictionary mapping host names to ``(login, account, password)`` tuples. The
'default' entry, if any, is represented as a pseudo-host by that name.
.. attribute:: netrc.macros
Dictionary mapping macro names to string lists.
.. note::
Passwords are limited to a subset of the ASCII character set. Versions of
this module prior to 2.3 were extremely limited. Starting with 2.3, all
ASCII punctuation is allowed in passwords. However, note that whitespace and
non-printable characters are not allowed in passwords. This is a limitation
of the way the .netrc file is parsed and may be removed in the future.
PK %�\
Pe?]
]
! html/_sources/library/new.rst.txtnu �[��� :mod:`new` --- Creation of runtime internal objects
===================================================
.. module:: new
:synopsis: Interface to the creation of runtime implementation objects.
:deprecated:
.. deprecated:: 2.6
The :mod:`new` module has been removed in Python 3. Use the :mod:`types`
module's classes instead.
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
The :mod:`new` module allows an interface to the interpreter object creation
functions. This is for use primarily in marshal-type functions, when a new
object needs to be created "magically" and not by using the regular creation
functions. This module provides a low-level interface to the interpreter, so
care must be exercised when using this module. It is possible to supply
non-sensical arguments which crash the interpreter when the object is used.
The :mod:`new` module defines the following functions:
.. function:: instance(class[, dict])
This function creates an instance of *class* with dictionary *dict* without
calling the :meth:`__init__` constructor. If *dict* is omitted or ``None``, a
new, empty dictionary is created for the new instance. Note that there are no
guarantees that the object will be in a consistent state.
.. function:: instancemethod(function, instance, class)
This function will return a method object, bound to *instance*, or unbound if
*instance* is ``None``. *function* must be callable.
.. function:: function(code, globals[, name[, argdefs[, closure]]])
Returns a (Python) function with the given code and globals. If *name* is given,
it must be a string or ``None``. If it is a string, the function will have the
given name, otherwise the function name will be taken from ``code.co_name``. If
*argdefs* is given, it must be a tuple and will be used to determine the default
values of parameters. If *closure* is given, it must be ``None`` or a tuple of
cell objects containing objects to bind to the names in ``code.co_freevars``.
.. function:: code(argcount, nlocals, stacksize, flags, codestring, constants, names, varnames, filename, name, firstlineno, lnotab)
This function is an interface to the :c:func:`PyCode_New` C function.
.. XXX This is still undocumented!
.. function:: module(name[, doc])
This function returns a new module object with name *name*. *name* must be a
string. The optional *doc* argument can have any type.
.. function:: classobj(name, baseclasses, dict)
This function returns a new class object, with name *name*, derived from
*baseclasses* (which should be a tuple of classes) and with namespace *dict*.
PK %�\ _�<< < ! html/_sources/library/nis.rst.txtnu �[���
:mod:`nis` --- Interface to Sun's NIS (Yellow Pages)
====================================================
.. module:: nis
:platform: Unix
:synopsis: Interface to Sun's NIS (Yellow Pages) library.
.. moduleauthor:: Fred Gansevles <Fred.Gansevles@cs.utwente.nl>
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
The :mod:`nis` module gives a thin wrapper around the NIS library, useful for
central administration of several hosts.
Because NIS exists only on Unix systems, this module is only available for Unix.
The :mod:`nis` module defines the following functions:
.. function:: match(key, mapname[, domain=default_domain])
Return the match for *key* in map *mapname*, or raise an error
(:exc:`nis.error`) if there is none. Both should be strings, *key* is 8-bit
clean. Return value is an arbitrary array of bytes (may contain ``NULL`` and
other joys).
Note that *mapname* is first checked if it is an alias to another name.
.. versionchanged:: 2.5
The *domain* argument allows overriding the NIS domain used for the lookup. If
unspecified, lookup is in the default NIS domain.
.. function:: cat(mapname[, domain=default_domain])
Return a dictionary mapping *key* to *value* such that ``match(key,
mapname)==value``. Note that both keys and values of the dictionary are
arbitrary arrays of bytes.
Note that *mapname* is first checked if it is an alias to another name.
.. versionchanged:: 2.5
The *domain* argument allows overriding the NIS domain used for the lookup. If
unspecified, lookup is in the default NIS domain.
.. function:: maps([domain=default_domain])
Return a list of all valid maps.
.. versionchanged:: 2.5
The *domain* argument allows overriding the NIS domain used for the lookup. If
unspecified, lookup is in the default NIS domain.
.. function:: get_default_domain()
Return the system default NIS domain.
.. versionadded:: 2.5
The :mod:`nis` module defines the following exception:
.. exception:: error
An error raised when a NIS function returns an error code.
PK %�\����8 �8 % html/_sources/library/nntplib.rst.txtnu �[���
:mod:`nntplib` --- NNTP protocol client
=======================================
.. module:: nntplib
:synopsis: NNTP protocol client (requires sockets).
.. index::
pair: NNTP; protocol
single: Network News Transfer Protocol
**Source code:** :source:`Lib/nntplib.py`
--------------
This module defines the class :class:`NNTP` which implements the client side of
the NNTP protocol. It can be used to implement a news reader or poster, or
automated news processors. For more information on NNTP (Network News Transfer
Protocol), see Internet :rfc:`977`.
Here are two small examples of how it can be used. To list some statistics
about a newsgroup and print the subjects of the last 10 articles::
>>> s = NNTP('news.gmane.org')
>>> resp, count, first, last, name = s.group('gmane.comp.python.committers')
>>> print 'Group', name, 'has', count, 'articles, range', first, 'to', last
Group gmane.comp.python.committers has 1071 articles, range 1 to 1071
>>> resp, subs = s.xhdr('subject', first + '-' + last)
>>> for id, sub in subs[-10:]: print id, sub
...
1062 Re: Mercurial Status?
1063 Re: [python-committers] (Windows) buildbots on 3.x
1064 Re: Mercurial Status?
1065 Re: Mercurial Status?
1066 Python 2.6.6 status
1067 Commit Privileges for Ask Solem
1068 Re: Commit Privileges for Ask Solem
1069 Re: Commit Privileges for Ask Solem
1070 Re: Commit Privileges for Ask Solem
1071 2.6.6 rc 2
>>> s.quit()
'205 Bye!'
To post an article from a file (this assumes that the article has valid
headers, and that you have right to post on the particular newsgroup)::
>>> s = NNTP('news.gmane.org')
>>> f = open('articlefile')
>>> s.post(f)
'240 Article posted successfully.'
>>> s.quit()
'205 Bye!'
The module itself defines the following items:
.. class:: NNTP(host[, port [, user[, password [, readermode] [, usenetrc]]]])
Return a new instance of the :class:`NNTP` class, representing a connection
to the NNTP server running on host *host*, listening at port *port*. The
default *port* is 119. If the optional *user* and *password* are provided,
or if suitable credentials are present in :file:`/.netrc` and the optional
flag *usenetrc* is true (the default), the ``AUTHINFO USER`` and ``AUTHINFO
PASS`` commands are used to identify and authenticate the user to the server.
If the optional flag *readermode* is true, then a ``mode reader`` command is
sent before authentication is performed. Reader mode is sometimes necessary
if you are connecting to an NNTP server on the local machine and intend to
call reader-specific commands, such as ``group``. If you get unexpected
:exc:`NNTPPermanentError`\ s, you might need to set *readermode*.
*readermode* defaults to ``None``. *usenetrc* defaults to ``True``.
.. versionchanged:: 2.4
*usenetrc* argument added.
.. exception:: NNTPError
Derived from the standard exception :exc:`Exception`, this is the base class for
all exceptions raised by the :mod:`nntplib` module.
.. exception:: NNTPReplyError
Exception raised when an unexpected reply is received from the server. For
backwards compatibility, the exception ``error_reply`` is equivalent to this
class.
.. exception:: NNTPTemporaryError
Exception raised when an error code in the range 400--499 is received. For
backwards compatibility, the exception ``error_temp`` is equivalent to this
class.
.. exception:: NNTPPermanentError
Exception raised when an error code in the range 500--599 is received. For
backwards compatibility, the exception ``error_perm`` is equivalent to this
class.
.. exception:: NNTPProtocolError
Exception raised when a reply is received from the server that does not begin
with a digit in the range 1--5. For backwards compatibility, the exception
``error_proto`` is equivalent to this class.
.. exception:: NNTPDataError
Exception raised when there is some error in the response data. For backwards
compatibility, the exception ``error_data`` is equivalent to this class.
.. _nntp-objects:
NNTP Objects
------------
NNTP instances have the following methods. The *response* that is returned as
the first item in the return tuple of almost all methods is the server's
response: a string beginning with a three-digit code. If the server's response
indicates an error, the method raises one of the above exceptions.
.. method:: NNTP.getwelcome()
Return the welcome message sent by the server in reply to the initial
connection. (This message sometimes contains disclaimers or help information
that may be relevant to the user.)
.. method:: NNTP.set_debuglevel(level)
Set the instance's debugging level. This controls the amount of debugging
output printed. The default, ``0``, produces no debugging output. A value of
``1`` produces a moderate amount of debugging output, generally a single line
per request or response. A value of ``2`` or higher produces the maximum amount
of debugging output, logging each line sent and received on the connection
(including message text).
.. method:: NNTP.newgroups(date, time, [file])
Send a ``NEWGROUPS`` command. The *date* argument should be a string of the
form ``'yymmdd'`` indicating the date, and *time* should be a string of the form
``'hhmmss'`` indicating the time. Return a pair ``(response, groups)`` where
*groups* is a list of group names that are new since the given date and time. If
the *file* parameter is supplied, then the output of the ``NEWGROUPS`` command
is stored in a file. If *file* is a string, then the method will open a file
object with that name, write to it then close it. If *file* is a file object,
then it will start calling :meth:`write` on it to store the lines of the command
output. If *file* is supplied, then the returned *list* is an empty list.
.. method:: NNTP.newnews(group, date, time, [file])
Send a ``NEWNEWS`` command. Here, *group* is a group name or ``'*'``, and
*date* and *time* have the same meaning as for :meth:`newgroups`. Return a pair
``(response, articles)`` where *articles* is a list of message ids. If the
*file* parameter is supplied, then the output of the ``NEWNEWS`` command is
stored in a file. If *file* is a string, then the method will open a file
object with that name, write to it then close it. If *file* is a file object,
then it will start calling :meth:`write` on it to store the lines of the command
output. If *file* is supplied, then the returned *list* is an empty list.
.. method:: NNTP.list([file])
Send a ``LIST`` command. Return a pair ``(response, list)`` where *list* is a
list of tuples. Each tuple has the form ``(group, last, first, flag)``, where
*group* is a group name, *last* and *first* are the last and first article
numbers (as strings), and *flag* is ``'y'`` if posting is allowed, ``'n'`` if
not, and ``'m'`` if the newsgroup is moderated. (Note the ordering: *last*,
*first*.) If the *file* parameter is supplied, then the output of the ``LIST``
command is stored in a file. If *file* is a string, then the method will open
a file object with that name, write to it then close it. If *file* is a file
object, then it will start calling :meth:`write` on it to store the lines of the
command output. If *file* is supplied, then the returned *list* is an empty
list.
.. method:: NNTP.descriptions(grouppattern)
Send a ``LIST NEWSGROUPS`` command, where *grouppattern* is a wildmat string as
specified in RFC2980 (it's essentially the same as DOS or UNIX shell wildcard
strings). Return a pair ``(response, list)``, where *list* is a list of tuples
containing ``(name, title)``.
.. versionadded:: 2.4
.. method:: NNTP.description(group)
Get a description for a single group *group*. If more than one group matches
(if 'group' is a real wildmat string), return the first match. If no group
matches, return an empty string.
This elides the response code from the server. If the response code is needed,
use :meth:`descriptions`.
.. versionadded:: 2.4
.. method:: NNTP.group(name)
Send a ``GROUP`` command, where *name* is the group name. Return a tuple
``(response, count, first, last, name)`` where *count* is the (estimated) number
of articles in the group, *first* is the first article number in the group,
*last* is the last article number in the group, and *name* is the group name.
The numbers are returned as strings.
.. method:: NNTP.help([file])
Send a ``HELP`` command. Return a pair ``(response, list)`` where *list* is a
list of help strings. If the *file* parameter is supplied, then the output of
the ``HELP`` command is stored in a file. If *file* is a string, then the
method will open a file object with that name, write to it then close it. If
*file* is a file object, then it will start calling :meth:`write` on it to store
the lines of the command output. If *file* is supplied, then the returned *list*
is an empty list.
.. method:: NNTP.stat(id)
Send a ``STAT`` command, where *id* is the message id (enclosed in ``'<'`` and
``'>'``) or an article number (as a string). Return a triple ``(response,
number, id)`` where *number* is the article number (as a string) and *id* is the
message id (enclosed in ``'<'`` and ``'>'``).
.. method:: NNTP.next()
Send a ``NEXT`` command. Return as for :meth:`.stat`.
.. method:: NNTP.last()
Send a ``LAST`` command. Return as for :meth:`.stat`.
.. method:: NNTP.head(id)
Send a ``HEAD`` command, where *id* has the same meaning as for :meth:`.stat`.
Return a tuple ``(response, number, id, list)`` where the first three are the
same as for :meth:`.stat`, and *list* is a list of the article's headers (an
uninterpreted list of lines, without trailing newlines).
.. method:: NNTP.body(id,[file])
Send a ``BODY`` command, where *id* has the same meaning as for :meth:`.stat`.
If the *file* parameter is supplied, then the body is stored in a file. If
*file* is a string, then the method will open a file object with that name,
write to it then close it. If *file* is a file object, then it will start
calling :meth:`write` on it to store the lines of the body. Return as for
:meth:`head`. If *file* is supplied, then the returned *list* is an empty list.
.. method:: NNTP.article(id)
Send an ``ARTICLE`` command, where *id* has the same meaning as for
:meth:`.stat`. Return as for :meth:`head`.
.. method:: NNTP.slave()
Send a ``SLAVE`` command. Return the server's *response*.
.. method:: NNTP.xhdr(header, string, [file])
Send an ``XHDR`` command. This command is not defined in the RFC but is a
common extension. The *header* argument is a header keyword, e.g.
``'subject'``. The *string* argument should have the form ``'first-last'``
where *first* and *last* are the first and last article numbers to search.
Return a pair ``(response, list)``, where *list* is a list of pairs ``(id,
text)``, where *id* is an article number (as a string) and *text* is the text of
the requested header for that article. If the *file* parameter is supplied, then
the output of the ``XHDR`` command is stored in a file. If *file* is a string,
then the method will open a file object with that name, write to it then close
it. If *file* is a file object, then it will start calling :meth:`write` on it
to store the lines of the command output. If *file* is supplied, then the
returned *list* is an empty list.
.. method:: NNTP.post(file)
Post an article using the ``POST`` command. The *file* argument is an open file
object which is read until EOF using its :meth:`~file.readline` method. It should be
a well-formed news article, including the required headers. The :meth:`post`
method automatically escapes lines beginning with ``.``.
.. method:: NNTP.ihave(id, file)
Send an ``IHAVE`` command. *id* is a message id (enclosed in ``'<'`` and
``'>'``). If the response is not an error, treat *file* exactly as for the
:meth:`post` method.
.. method:: NNTP.date()
Return a triple ``(response, date, time)``, containing the current date and time
in a form suitable for the :meth:`newnews` and :meth:`newgroups` methods. This
is an optional NNTP extension, and may not be supported by all servers.
.. method:: NNTP.xgtitle(name, [file])
Process an ``XGTITLE`` command, returning a pair ``(response, list)``, where
*list* is a list of tuples containing ``(name, title)``. If the *file* parameter
is supplied, then the output of the ``XGTITLE`` command is stored in a file.
If *file* is a string, then the method will open a file object with that name,
write to it then close it. If *file* is a file object, then it will start
calling :meth:`write` on it to store the lines of the command output. If *file*
is supplied, then the returned *list* is an empty list. This is an optional NNTP
extension, and may not be supported by all servers.
RFC2980 says "It is suggested that this extension be deprecated". Use
:meth:`descriptions` or :meth:`description` instead.
.. method:: NNTP.xover(start, end, [file])
Return a pair ``(resp, list)``. *list* is a list of tuples, one for each
article in the range delimited by the *start* and *end* article numbers. Each
tuple is of the form ``(article number, subject, poster, date, id, references,
size, lines)``. If the *file* parameter is supplied, then the output of the
``XOVER`` command is stored in a file. If *file* is a string, then the method
will open a file object with that name, write to it then close it. If *file*
is a file object, then it will start calling :meth:`write` on it to store the
lines of the command output. If *file* is supplied, then the returned *list* is
an empty list. This is an optional NNTP extension, and may not be supported by
all servers.
.. method:: NNTP.xpath(id)
Return a pair ``(resp, path)``, where *path* is the directory path to the
article with message ID *id*. This is an optional NNTP extension, and may not
be supported by all servers.
.. method:: NNTP.quit()
Send a ``QUIT`` command and close the connection. Once this method has been
called, no other methods of the NNTP object should be called.
PK %�\R��?G G % html/_sources/library/numbers.rst.txtnu �[��� :mod:`numbers` --- Numeric abstract base classes
================================================
.. module:: numbers
:synopsis: Numeric abstract base classes (Complex, Real, Integral, etc.).
.. versionadded:: 2.6
The :mod:`numbers` module (:pep:`3141`) defines a hierarchy of numeric
:term:`abstract base classes <abstract base class>` which progressively define
more operations. None of the types defined in this module can be instantiated.
.. class:: Number
The root of the numeric hierarchy. If you just want to check if an argument
*x* is a number, without caring what kind, use ``isinstance(x, Number)``.
The numeric tower
-----------------
.. class:: Complex
Subclasses of this type describe complex numbers and include the operations
that work on the built-in :class:`complex` type. These are: conversions to
:class:`complex` and :class:`bool`, :attr:`.real`, :attr:`.imag`, ``+``,
``-``, ``*``, ``/``, :func:`abs`, :meth:`conjugate`, ``==``, and ``!=``. All
except ``-`` and ``!=`` are abstract.
.. attribute:: real
Abstract. Retrieves the real component of this number.
.. attribute:: imag
Abstract. Retrieves the imaginary component of this number.
.. method:: conjugate()
Abstract. Returns the complex conjugate. For example, ``(1+3j).conjugate()
== (1-3j)``.
.. class:: Real
To :class:`Complex`, :class:`Real` adds the operations that work on real
numbers.
In short, those are: a conversion to :class:`float`, :func:`math.trunc`,
:func:`round`, :func:`math.floor`, :func:`math.ceil`, :func:`divmod`, ``//``,
``%``, ``<``, ``<=``, ``>``, and ``>=``.
Real also provides defaults for :func:`complex`, :attr:`~Complex.real`,
:attr:`~Complex.imag`, and :meth:`~Complex.conjugate`.
.. class:: Rational
Subtypes :class:`Real` and adds
:attr:`~Rational.numerator` and :attr:`~Rational.denominator` properties, which
should be in lowest terms. With these, it provides a default for
:func:`float`.
.. attribute:: numerator
Abstract.
.. attribute:: denominator
Abstract.
.. class:: Integral
Subtypes :class:`Rational` and adds a conversion to :class:`int`. Provides
defaults for :func:`float`, :attr:`~Rational.numerator`, and
:attr:`~Rational.denominator`. Adds abstract methods for ``**`` and
bit-string operations: ``<<``, ``>>``, ``&``, ``^``, ``|``, ``~``.
Notes for type implementors
---------------------------
Implementors should be careful to make equal numbers equal and hash
them to the same values. This may be subtle if there are two different
extensions of the real numbers. For example, :class:`fractions.Fraction`
implements :func:`hash` as follows::
def __hash__(self):
if self.denominator == 1:
# Get integers right.
return hash(self.numerator)
# Expensive check, but definitely correct.
if self == float(self):
return hash(float(self))
else:
# Use tuple's hash to avoid a high collision rate on
# simple fractions.
return hash((self.numerator, self.denominator))
Adding More Numeric ABCs
~~~~~~~~~~~~~~~~~~~~~~~~
There are, of course, more possible ABCs for numbers, and this would
be a poor hierarchy if it precluded the possibility of adding
those. You can add ``MyFoo`` between :class:`Complex` and
:class:`Real` with::
class MyFoo(Complex): ...
MyFoo.register(Real)
Implementing the arithmetic operations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
We want to implement the arithmetic operations so that mixed-mode
operations either call an implementation whose author knew about the
types of both arguments, or convert both to the nearest built in type
and do the operation there. For subtypes of :class:`Integral`, this
means that :meth:`__add__` and :meth:`__radd__` should be defined as::
class MyIntegral(Integral):
def __add__(self, other):
if isinstance(other, MyIntegral):
return do_my_adding_stuff(self, other)
elif isinstance(other, OtherTypeIKnowAbout):
return do_my_other_adding_stuff(self, other)
else:
return NotImplemented
def __radd__(self, other):
if isinstance(other, MyIntegral):
return do_my_adding_stuff(other, self)
elif isinstance(other, OtherTypeIKnowAbout):
return do_my_other_adding_stuff(other, self)
elif isinstance(other, Integral):
return int(other) + int(self)
elif isinstance(other, Real):
return float(other) + float(self)
elif isinstance(other, Complex):
return complex(other) + complex(self)
else:
return NotImplemented
There are 5 different cases for a mixed-type operation on subclasses
of :class:`Complex`. I'll refer to all of the above code that doesn't
refer to ``MyIntegral`` and ``OtherTypeIKnowAbout`` as
"boilerplate". ``a`` will be an instance of ``A``, which is a subtype
of :class:`Complex` (``a : A <: Complex``), and ``b : B <:
Complex``. I'll consider ``a + b``:
1. If ``A`` defines an :meth:`__add__` which accepts ``b``, all is
well.
2. If ``A`` falls back to the boilerplate code, and it were to
return a value from :meth:`__add__`, we'd miss the possibility
that ``B`` defines a more intelligent :meth:`__radd__`, so the
boilerplate should return :const:`NotImplemented` from
:meth:`__add__`. (Or ``A`` may not implement :meth:`__add__` at
all.)
3. Then ``B``'s :meth:`__radd__` gets a chance. If it accepts
``a``, all is well.
4. If it falls back to the boilerplate, there are no more possible
methods to try, so this is where the default implementation
should live.
5. If ``B <: A``, Python tries ``B.__radd__`` before
``A.__add__``. This is ok, because it was implemented with
knowledge of ``A``, so it can handle those instances before
delegating to :class:`Complex`.
If ``A <: Complex`` and ``B <: Real`` without sharing any other knowledge,
then the appropriate shared operation is the one involving the built
in :class:`complex`, and both :meth:`__radd__` s land there, so ``a+b
== b+a``.
Because most of the operations on any given type will be very similar,
it can be useful to define a helper function which generates the
forward and reverse instances of any given operator. For example,
:class:`fractions.Fraction` uses::
def _operator_fallbacks(monomorphic_operator, fallback_operator):
def forward(a, b):
if isinstance(b, (int, long, Fraction)):
return monomorphic_operator(a, b)
elif isinstance(b, float):
return fallback_operator(float(a), b)
elif isinstance(b, complex):
return fallback_operator(complex(a), b)
else:
return NotImplemented
forward.__name__ = '__' + fallback_operator.__name__ + '__'
forward.__doc__ = monomorphic_operator.__doc__
def reverse(b, a):
if isinstance(a, Rational):
# Includes ints.
return monomorphic_operator(a, b)
elif isinstance(a, numbers.Real):
return fallback_operator(float(a), float(b))
elif isinstance(a, numbers.Complex):
return fallback_operator(complex(a), complex(b))
else:
return NotImplemented
reverse.__name__ = '__r' + fallback_operator.__name__ + '__'
reverse.__doc__ = monomorphic_operator.__doc__
return forward, reverse
def _add(a, b):
"""a + b"""
return Fraction(a.numerator * b.denominator +
b.numerator * a.denominator,
a.denominator * b.denominator)
__add__, __radd__ = _operator_fallbacks(_add, operator.add)
# ...
PK %�\<��z� � % html/_sources/library/numeric.rst.txtnu �[���
.. _numeric:
********************************
Numeric and Mathematical Modules
********************************
The modules described in this chapter provide numeric and math-related functions
and data types. The :mod:`numbers` module defines an abstract hierarchy of
numeric types. The :mod:`math` and :mod:`cmath` modules contain various
mathematical functions for floating-point and complex numbers. For users more
interested in decimal accuracy than in speed, the :mod:`decimal` module supports
exact representations of decimal numbers.
The following modules are documented in this chapter:
.. toctree::
numbers.rst
math.rst
cmath.rst
decimal.rst
fractions.rst
random.rst
itertools.rst
functools.rst
operator.rst
PK %�\��LV LV & html/_sources/library/operator.rst.txtnu �[��� :mod:`operator` --- Standard operators as functions
===================================================
.. module:: operator
:synopsis: Functions corresponding to the standard operators.
.. sectionauthor:: Skip Montanaro <skip@automatrix.com>
.. testsetup::
import operator
from operator import itemgetter
The :mod:`operator` module exports a set of efficient functions corresponding to
the intrinsic operators of Python. For example, ``operator.add(x, y)`` is
equivalent to the expression ``x+y``. The function names are those used for
special class methods; variants without leading and trailing ``__`` are also
provided for convenience.
The functions fall into categories that perform object comparisons, logical
operations, mathematical operations, sequence operations, and abstract type
tests.
The object comparison functions are useful for all objects, and are named after
the rich comparison operators they support:
.. function:: lt(a, b)
le(a, b)
eq(a, b)
ne(a, b)
ge(a, b)
gt(a, b)
__lt__(a, b)
__le__(a, b)
__eq__(a, b)
__ne__(a, b)
__ge__(a, b)
__gt__(a, b)
Perform "rich comparisons" between *a* and *b*. Specifically, ``lt(a, b)`` is
equivalent to ``a < b``, ``le(a, b)`` is equivalent to ``a <= b``, ``eq(a,
b)`` is equivalent to ``a == b``, ``ne(a, b)`` is equivalent to ``a != b``,
``gt(a, b)`` is equivalent to ``a > b`` and ``ge(a, b)`` is equivalent to ``a
>= b``. Note that unlike the built-in :func:`cmp`, these functions can
return any value, which may or may not be interpretable as a Boolean value.
See :ref:`comparisons` for more information about rich comparisons.
.. versionadded:: 2.2
The logical operations are also generally applicable to all objects, and support
truth tests, identity tests, and boolean operations:
.. function:: not_(obj)
__not__(obj)
Return the outcome of :keyword:`not` *obj*. (Note that there is no
:meth:`__not__` method for object instances; only the interpreter core defines
this operation. The result is affected by the :meth:`__nonzero__` and
:meth:`__len__` methods.)
.. function:: truth(obj)
Return :const:`True` if *obj* is true, and :const:`False` otherwise. This is
equivalent to using the :class:`bool` constructor.
.. function:: is_(a, b)
Return ``a is b``. Tests object identity.
.. versionadded:: 2.3
.. function:: is_not(a, b)
Return ``a is not b``. Tests object identity.
.. versionadded:: 2.3
The mathematical and bitwise operations are the most numerous:
.. function:: abs(obj)
__abs__(obj)
Return the absolute value of *obj*.
.. function:: add(a, b)
__add__(a, b)
Return ``a + b``, for *a* and *b* numbers.
.. function:: and_(a, b)
__and__(a, b)
Return the bitwise and of *a* and *b*.
.. function:: div(a, b)
__div__(a, b)
Return ``a / b`` when ``__future__.division`` is not in effect. This is
also known as "classic" division.
.. function:: floordiv(a, b)
__floordiv__(a, b)
Return ``a // b``.
.. versionadded:: 2.2
.. function:: index(a)
__index__(a)
Return *a* converted to an integer. Equivalent to ``a.__index__()``.
.. versionadded:: 2.5
.. function:: inv(obj)
invert(obj)
__inv__(obj)
__invert__(obj)
Return the bitwise inverse of the number *obj*. This is equivalent to ``~obj``.
.. versionadded:: 2.0
The names :func:`invert` and :func:`__invert__`.
.. function:: lshift(a, b)
__lshift__(a, b)
Return *a* shifted left by *b*.
.. function:: mod(a, b)
__mod__(a, b)
Return ``a % b``.
.. function:: mul(a, b)
__mul__(a, b)
Return ``a * b``, for *a* and *b* numbers.
.. function:: neg(obj)
__neg__(obj)
Return *obj* negated (``-obj``).
.. function:: or_(a, b)
__or__(a, b)
Return the bitwise or of *a* and *b*.
.. function:: pos(obj)
__pos__(obj)
Return *obj* positive (``+obj``).
.. function:: pow(a, b)
__pow__(a, b)
Return ``a ** b``, for *a* and *b* numbers.
.. versionadded:: 2.3
.. function:: rshift(a, b)
__rshift__(a, b)
Return *a* shifted right by *b*.
.. function:: sub(a, b)
__sub__(a, b)
Return ``a - b``.
.. function:: truediv(a, b)
__truediv__(a, b)
Return ``a / b`` when ``__future__.division`` is in effect. This is also
known as "true" division.
.. versionadded:: 2.2
.. function:: xor(a, b)
__xor__(a, b)
Return the bitwise exclusive or of *a* and *b*.
Operations which work with sequences (some of them with mappings too) include:
.. function:: concat(a, b)
__concat__(a, b)
Return ``a + b`` for *a* and *b* sequences.
.. function:: contains(a, b)
__contains__(a, b)
Return the outcome of the test ``b in a``. Note the reversed operands.
.. versionadded:: 2.0
The name :func:`__contains__`.
.. function:: countOf(a, b)
Return the number of occurrences of *b* in *a*.
.. function:: delitem(a, b)
__delitem__(a, b)
Remove the value of *a* at index *b*.
.. function:: delslice(a, b, c)
__delslice__(a, b, c)
Delete the slice of *a* from index *b* to index *c-1*.
.. deprecated:: 2.6
This function is removed in Python 3.x. Use :func:`delitem` with a slice
index.
.. function:: getitem(a, b)
__getitem__(a, b)
Return the value of *a* at index *b*.
.. function:: getslice(a, b, c)
__getslice__(a, b, c)
Return the slice of *a* from index *b* to index *c-1*.
.. deprecated:: 2.6
This function is removed in Python 3.x. Use :func:`getitem` with a slice
index.
.. function:: indexOf(a, b)
Return the index of the first of occurrence of *b* in *a*.
.. function:: repeat(a, b)
__repeat__(a, b)
.. deprecated:: 2.7
Use :func:`__mul__` instead.
Return ``a * b`` where *a* is a sequence and *b* is an integer.
.. function:: sequenceIncludes(...)
.. deprecated:: 2.0
Use :func:`contains` instead.
Alias for :func:`contains`.
.. function:: setitem(a, b, c)
__setitem__(a, b, c)
Set the value of *a* at index *b* to *c*.
.. function:: setslice(a, b, c, v)
__setslice__(a, b, c, v)
Set the slice of *a* from index *b* to index *c-1* to the sequence *v*.
.. deprecated:: 2.6
This function is removed in Python 3.x. Use :func:`setitem` with a slice
index.
Example use of operator functions::
>>> # Elementwise multiplication
>>> map(mul, [0, 1, 2, 3], [10, 20, 30, 40])
[0, 20, 60, 120]
>>> # Dot product
>>> sum(map(mul, [0, 1, 2, 3], [10, 20, 30, 40]))
200
Many operations have an "in-place" version. The following functions provide a
more primitive access to in-place operators than the usual syntax does; for
example, the :term:`statement` ``x += y`` is equivalent to
``x = operator.iadd(x, y)``. Another way to put it is to say that
``z = operator.iadd(x, y)`` is equivalent to the compound statement
``z = x; z += y``.
.. function:: iadd(a, b)
__iadd__(a, b)
``a = iadd(a, b)`` is equivalent to ``a += b``.
.. versionadded:: 2.5
.. function:: iand(a, b)
__iand__(a, b)
``a = iand(a, b)`` is equivalent to ``a &= b``.
.. versionadded:: 2.5
.. function:: iconcat(a, b)
__iconcat__(a, b)
``a = iconcat(a, b)`` is equivalent to ``a += b`` for *a* and *b* sequences.
.. versionadded:: 2.5
.. function:: idiv(a, b)
__idiv__(a, b)
``a = idiv(a, b)`` is equivalent to ``a /= b`` when ``__future__.division`` is
not in effect.
.. versionadded:: 2.5
.. function:: ifloordiv(a, b)
__ifloordiv__(a, b)
``a = ifloordiv(a, b)`` is equivalent to ``a //= b``.
.. versionadded:: 2.5
.. function:: ilshift(a, b)
__ilshift__(a, b)
``a = ilshift(a, b)`` is equivalent to ``a <<= b``.
.. versionadded:: 2.5
.. function:: imod(a, b)
__imod__(a, b)
``a = imod(a, b)`` is equivalent to ``a %= b``.
.. versionadded:: 2.5
.. function:: imul(a, b)
__imul__(a, b)
``a = imul(a, b)`` is equivalent to ``a *= b``.
.. versionadded:: 2.5
.. function:: ior(a, b)
__ior__(a, b)
``a = ior(a, b)`` is equivalent to ``a |= b``.
.. versionadded:: 2.5
.. function:: ipow(a, b)
__ipow__(a, b)
``a = ipow(a, b)`` is equivalent to ``a **= b``.
.. versionadded:: 2.5
.. function:: irepeat(a, b)
__irepeat__(a, b)
.. deprecated:: 2.7
Use :func:`__imul__` instead.
``a = irepeat(a, b)`` is equivalent to ``a *= b`` where *a* is a sequence and
*b* is an integer.
.. versionadded:: 2.5
.. function:: irshift(a, b)
__irshift__(a, b)
``a = irshift(a, b)`` is equivalent to ``a >>= b``.
.. versionadded:: 2.5
.. function:: isub(a, b)
__isub__(a, b)
``a = isub(a, b)`` is equivalent to ``a -= b``.
.. versionadded:: 2.5
.. function:: itruediv(a, b)
__itruediv__(a, b)
``a = itruediv(a, b)`` is equivalent to ``a /= b`` when ``__future__.division``
is in effect.
.. versionadded:: 2.5
.. function:: ixor(a, b)
__ixor__(a, b)
``a = ixor(a, b)`` is equivalent to ``a ^= b``.
.. versionadded:: 2.5
The :mod:`operator` module also defines a few predicates to test the type of
objects; however, these are not all reliable. It is preferable to test
abstract base classes instead (see :mod:`collections` and
:mod:`numbers` for details).
.. function:: isCallable(obj)
.. deprecated:: 2.0
Use ``isinstance(x, collections.Callable)`` instead.
Returns true if the object *obj* can be called like a function, otherwise it
returns false. True is returned for functions, bound and unbound methods, class
objects, and instance objects which support the :meth:`__call__` method.
.. function:: isMappingType(obj)
.. deprecated:: 2.7
Use ``isinstance(x, collections.Mapping)`` instead.
Returns true if the object *obj* supports the mapping interface. This is true for
dictionaries and all instance objects defining :meth:`__getitem__`.
.. function:: isNumberType(obj)
.. deprecated:: 2.7
Use ``isinstance(x, numbers.Number)`` instead.
Returns true if the object *obj* represents a number. This is true for all
numeric types implemented in C.
.. function:: isSequenceType(obj)
.. deprecated:: 2.7
Use ``isinstance(x, collections.Sequence)`` instead.
Returns true if the object *obj* supports the sequence protocol. This returns true
for all objects which define sequence methods in C, and for all instance objects
defining :meth:`__getitem__`.
The :mod:`operator` module also defines tools for generalized attribute and item
lookups. These are useful for making fast field extractors as arguments for
:func:`map`, :func:`sorted`, :meth:`itertools.groupby`, or other functions that
expect a function argument.
.. function:: attrgetter(attr)
attrgetter(*attrs)
Return a callable object that fetches *attr* from its operand.
If more than one attribute is requested, returns a tuple of attributes.
The attribute names can also contain dots. For example:
* After ``f = attrgetter('name')``, the call ``f(b)`` returns ``b.name``.
* After ``f = attrgetter('name', 'date')``, the call ``f(b)`` returns
``(b.name, b.date)``.
* After ``f = attrgetter('name.first', 'name.last')``, the call ``f(b)``
returns ``(b.name.first, b.name.last)``.
Equivalent to::
def attrgetter(*items):
if len(items) == 1:
attr = items[0]
def g(obj):
return resolve_attr(obj, attr)
else:
def g(obj):
return tuple(resolve_attr(obj, attr) for attr in items)
return g
def resolve_attr(obj, attr):
for name in attr.split("."):
obj = getattr(obj, name)
return obj
.. versionadded:: 2.4
.. versionchanged:: 2.5
Added support for multiple attributes.
.. versionchanged:: 2.6
Added support for dotted attributes.
.. function:: itemgetter(item)
itemgetter(*items)
Return a callable object that fetches *item* from its operand using the
operand's :meth:`__getitem__` method. If multiple items are specified,
returns a tuple of lookup values. For example:
* After ``f = itemgetter(2)``, the call ``f(r)`` returns ``r[2]``.
* After ``g = itemgetter(2, 5, 3)``, the call ``g(r)`` returns
``(r[2], r[5], r[3])``.
Equivalent to::
def itemgetter(*items):
if len(items) == 1:
item = items[0]
def g(obj):
return obj[item]
else:
def g(obj):
return tuple(obj[item] for item in items)
return g
The items can be any type accepted by the operand's :meth:`__getitem__`
method. Dictionaries accept any hashable value. Lists, tuples, and
strings accept an index or a slice:
>>> itemgetter(1)('ABCDEFG')
'B'
>>> itemgetter(1,3,5)('ABCDEFG')
('B', 'D', 'F')
>>> itemgetter(slice(2,None))('ABCDEFG')
'CDEFG'
.. versionadded:: 2.4
.. versionchanged:: 2.5
Added support for multiple item extraction.
Example of using :func:`itemgetter` to retrieve specific fields from a
tuple record:
>>> inventory = [('apple', 3), ('banana', 2), ('pear', 5), ('orange', 1)]
>>> getcount = itemgetter(1)
>>> map(getcount, inventory)
[3, 2, 5, 1]
>>> sorted(inventory, key=getcount)
[('orange', 1), ('banana', 2), ('apple', 3), ('pear', 5)]
.. function:: methodcaller(name[, args...])
Return a callable object that calls the method *name* on its operand. If
additional arguments and/or keyword arguments are given, they will be given
to the method as well. For example:
* After ``f = methodcaller('name')``, the call ``f(b)`` returns ``b.name()``.
* After ``f = methodcaller('name', 'foo', bar=1)``, the call ``f(b)``
returns ``b.name('foo', bar=1)``.
Equivalent to::
def methodcaller(name, *args, **kwargs):
def caller(obj):
return getattr(obj, name)(*args, **kwargs)
return caller
.. versionadded:: 2.6
.. _operator-map:
Mapping Operators to Functions
------------------------------
This table shows how abstract operations correspond to operator symbols in the
Python syntax and the functions in the :mod:`operator` module.
+-----------------------+-------------------------+---------------------------------------+
| Operation | Syntax | Function |
+=======================+=========================+=======================================+
| Addition | ``a + b`` | ``add(a, b)`` |
+-----------------------+-------------------------+---------------------------------------+
| Concatenation | ``seq1 + seq2`` | ``concat(seq1, seq2)`` |
+-----------------------+-------------------------+---------------------------------------+
| Containment Test | ``obj in seq`` | ``contains(seq, obj)`` |
+-----------------------+-------------------------+---------------------------------------+
| Division | ``a / b`` | ``div(a, b)`` (without |
| | | ``__future__.division``) |
+-----------------------+-------------------------+---------------------------------------+
| Division | ``a / b`` | ``truediv(a, b)`` (with |
| | | ``__future__.division``) |
+-----------------------+-------------------------+---------------------------------------+
| Division | ``a // b`` | ``floordiv(a, b)`` |
+-----------------------+-------------------------+---------------------------------------+
| Bitwise And | ``a & b`` | ``and_(a, b)`` |
+-----------------------+-------------------------+---------------------------------------+
| Bitwise Exclusive Or | ``a ^ b`` | ``xor(a, b)`` |
+-----------------------+-------------------------+---------------------------------------+
| Bitwise Inversion | ``~ a`` | ``invert(a)`` |
+-----------------------+-------------------------+---------------------------------------+
| Bitwise Or | ``a | b`` | ``or_(a, b)`` |
+-----------------------+-------------------------+---------------------------------------+
| Exponentiation | ``a ** b`` | ``pow(a, b)`` |
+-----------------------+-------------------------+---------------------------------------+
| Identity | ``a is b`` | ``is_(a, b)`` |
+-----------------------+-------------------------+---------------------------------------+
| Identity | ``a is not b`` | ``is_not(a, b)`` |
+-----------------------+-------------------------+---------------------------------------+
| Indexed Assignment | ``obj[k] = v`` | ``setitem(obj, k, v)`` |
+-----------------------+-------------------------+---------------------------------------+
| Indexed Deletion | ``del obj[k]`` | ``delitem(obj, k)`` |
+-----------------------+-------------------------+---------------------------------------+
| Indexing | ``obj[k]`` | ``getitem(obj, k)`` |
+-----------------------+-------------------------+---------------------------------------+
| Left Shift | ``a << b`` | ``lshift(a, b)`` |
+-----------------------+-------------------------+---------------------------------------+
| Modulo | ``a % b`` | ``mod(a, b)`` |
+-----------------------+-------------------------+---------------------------------------+
| Multiplication | ``a * b`` | ``mul(a, b)`` |
+-----------------------+-------------------------+---------------------------------------+
| Negation (Arithmetic) | ``- a`` | ``neg(a)`` |
+-----------------------+-------------------------+---------------------------------------+
| Negation (Logical) | ``not a`` | ``not_(a)`` |
+-----------------------+-------------------------+---------------------------------------+
| Positive | ``+ a`` | ``pos(a)`` |
+-----------------------+-------------------------+---------------------------------------+
| Right Shift | ``a >> b`` | ``rshift(a, b)`` |
+-----------------------+-------------------------+---------------------------------------+
| Sequence Repetition | ``seq * i`` | ``repeat(seq, i)`` |
+-----------------------+-------------------------+---------------------------------------+
| Slice Assignment | ``seq[i:j] = values`` | ``setitem(seq, slice(i, j), values)`` |
+-----------------------+-------------------------+---------------------------------------+
| Slice Deletion | ``del seq[i:j]`` | ``delitem(seq, slice(i, j))`` |
+-----------------------+-------------------------+---------------------------------------+
| Slicing | ``seq[i:j]`` | ``getitem(seq, slice(i, j))`` |
+-----------------------+-------------------------+---------------------------------------+
| String Formatting | ``s % obj`` | ``mod(s, obj)`` |
+-----------------------+-------------------------+---------------------------------------+
| Subtraction | ``a - b`` | ``sub(a, b)`` |
+-----------------------+-------------------------+---------------------------------------+
| Truth Test | ``obj`` | ``truth(obj)`` |
+-----------------------+-------------------------+---------------------------------------+
| Ordering | ``a < b`` | ``lt(a, b)`` |
+-----------------------+-------------------------+---------------------------------------+
| Ordering | ``a <= b`` | ``le(a, b)`` |
+-----------------------+-------------------------+---------------------------------------+
| Equality | ``a == b`` | ``eq(a, b)`` |
+-----------------------+-------------------------+---------------------------------------+
| Difference | ``a != b`` | ``ne(a, b)`` |
+-----------------------+-------------------------+---------------------------------------+
| Ordering | ``a >= b`` | ``ge(a, b)`` |
+-----------------------+-------------------------+---------------------------------------+
| Ordering | ``a > b`` | ``gt(a, b)`` |
+-----------------------+-------------------------+---------------------------------------+
PK %�\�O��-- -- & html/_sources/library/optparse.rst.txtnu �[��� :mod:`optparse` --- Parser for command line options
===================================================
.. module:: optparse
:synopsis: Command-line option parsing library.
:deprecated:
.. moduleauthor:: Greg Ward <gward@python.net>
.. sectionauthor:: Greg Ward <gward@python.net>
.. versionadded:: 2.3
.. deprecated:: 2.7
The :mod:`optparse` module is deprecated and will not be developed further;
development will continue with the :mod:`argparse` module.
**Source code:** :source:`Lib/optparse.py`
--------------
:mod:`optparse` is a more convenient, flexible, and powerful library for parsing
command-line options than the old :mod:`getopt` module. :mod:`optparse` uses a
more declarative style of command-line parsing: you create an instance of
:class:`OptionParser`, populate it with options, and parse the command
line. :mod:`optparse` allows users to specify options in the conventional
GNU/POSIX syntax, and additionally generates usage and help messages for you.
Here's an example of using :mod:`optparse` in a simple script::
from optparse import OptionParser
...
parser = OptionParser()
parser.add_option("-f", "--file", dest="filename",
help="write report to FILE", metavar="FILE")
parser.add_option("-q", "--quiet",
action="store_false", dest="verbose", default=True,
help="don't print status messages to stdout")
(options, args) = parser.parse_args()
With these few lines of code, users of your script can now do the "usual thing"
on the command-line, for example::
<yourscript> --file=outfile -q
As it parses the command line, :mod:`optparse` sets attributes of the
``options`` object returned by :meth:`parse_args` based on user-supplied
command-line values. When :meth:`parse_args` returns from parsing this command
line, ``options.filename`` will be ``"outfile"`` and ``options.verbose`` will be
``False``. :mod:`optparse` supports both long and short options, allows short
options to be merged together, and allows options to be associated with their
arguments in a variety of ways. Thus, the following command lines are all
equivalent to the above example::
<yourscript> -f outfile --quiet
<yourscript> --quiet --file outfile
<yourscript> -q -foutfile
<yourscript> -qfoutfile
Additionally, users can run one of ::
<yourscript> -h
<yourscript> --help
and :mod:`optparse` will print out a brief summary of your script's options:
.. code-block:: text
Usage: <yourscript> [options]
Options:
-h, --help show this help message and exit
-f FILE, --file=FILE write report to FILE
-q, --quiet don't print status messages to stdout
where the value of *yourscript* is determined at runtime (normally from
``sys.argv[0]``).
.. _optparse-background:
Background
----------
:mod:`optparse` was explicitly designed to encourage the creation of programs
with straightforward, conventional command-line interfaces. To that end, it
supports only the most common command-line syntax and semantics conventionally
used under Unix. If you are unfamiliar with these conventions, read this
section to acquaint yourself with them.
.. _optparse-terminology:
Terminology
^^^^^^^^^^^
argument
a string entered on the command-line, and passed by the shell to ``execl()``
or ``execv()``. In Python, arguments are elements of ``sys.argv[1:]``
(``sys.argv[0]`` is the name of the program being executed). Unix shells
also use the term "word".
It is occasionally desirable to substitute an argument list other than
``sys.argv[1:]``, so you should read "argument" as "an element of
``sys.argv[1:]``, or of some other list provided as a substitute for
``sys.argv[1:]``".
option
an argument used to supply extra information to guide or customize the
execution of a program. There are many different syntaxes for options; the
traditional Unix syntax is a hyphen ("-") followed by a single letter,
e.g. ``-x`` or ``-F``. Also, traditional Unix syntax allows multiple
options to be merged into a single argument, e.g. ``-x -F`` is equivalent
to ``-xF``. The GNU project introduced ``--`` followed by a series of
hyphen-separated words, e.g. ``--file`` or ``--dry-run``. These are the
only two option syntaxes provided by :mod:`optparse`.
Some other option syntaxes that the world has seen include:
* a hyphen followed by a few letters, e.g. ``-pf`` (this is *not* the same
as multiple options merged into a single argument)
* a hyphen followed by a whole word, e.g. ``-file`` (this is technically
equivalent to the previous syntax, but they aren't usually seen in the same
program)
* a plus sign followed by a single letter, or a few letters, or a word, e.g.
``+f``, ``+rgb``
* a slash followed by a letter, or a few letters, or a word, e.g. ``/f``,
``/file``
These option syntaxes are not supported by :mod:`optparse`, and they never
will be. This is deliberate: the first three are non-standard on any
environment, and the last only makes sense if you're exclusively targeting
VMS, MS-DOS, and/or Windows.
option argument
an argument that follows an option, is closely associated with that option,
and is consumed from the argument list when that option is. With
:mod:`optparse`, option arguments may either be in a separate argument from
their option:
.. code-block:: text
-f foo
--file foo
or included in the same argument:
.. code-block:: text
-ffoo
--file=foo
Typically, a given option either takes an argument or it doesn't. Lots of
people want an "optional option arguments" feature, meaning that some options
will take an argument if they see it, and won't if they don't. This is
somewhat controversial, because it makes parsing ambiguous: if ``-a`` takes
an optional argument and ``-b`` is another option entirely, how do we
interpret ``-ab``? Because of this ambiguity, :mod:`optparse` does not
support this feature.
positional argument
something leftover in the argument list after options have been parsed, i.e.
after options and their arguments have been parsed and removed from the
argument list.
required option
an option that must be supplied on the command-line; note that the phrase
"required option" is self-contradictory in English. :mod:`optparse` doesn't
prevent you from implementing required options, but doesn't give you much
help at it either.
For example, consider this hypothetical command-line::
prog -v --report report.txt foo bar
``-v`` and ``--report`` are both options. Assuming that ``--report``
takes one argument, ``report.txt`` is an option argument. ``foo`` and
``bar`` are positional arguments.
.. _optparse-what-options-for:
What are options for?
^^^^^^^^^^^^^^^^^^^^^
Options are used to provide extra information to tune or customize the execution
of a program. In case it wasn't clear, options are usually *optional*. A
program should be able to run just fine with no options whatsoever. (Pick a
random program from the Unix or GNU toolsets. Can it run without any options at
all and still make sense? The main exceptions are ``find``, ``tar``, and
``dd``\ ---all of which are mutant oddballs that have been rightly criticized
for their non-standard syntax and confusing interfaces.)
Lots of people want their programs to have "required options". Think about it.
If it's required, then it's *not optional*! If there is a piece of information
that your program absolutely requires in order to run successfully, that's what
positional arguments are for.
As an example of good command-line interface design, consider the humble ``cp``
utility, for copying files. It doesn't make much sense to try to copy files
without supplying a destination and at least one source. Hence, ``cp`` fails if
you run it with no arguments. However, it has a flexible, useful syntax that
does not require any options at all::
cp SOURCE DEST
cp SOURCE ... DEST-DIR
You can get pretty far with just that. Most ``cp`` implementations provide a
bunch of options to tweak exactly how the files are copied: you can preserve
mode and modification time, avoid following symlinks, ask before clobbering
existing files, etc. But none of this distracts from the core mission of
``cp``, which is to copy either one file to another, or several files to another
directory.
.. _optparse-what-positional-arguments-for:
What are positional arguments for?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Positional arguments are for those pieces of information that your program
absolutely, positively requires to run.
A good user interface should have as few absolute requirements as possible. If
your program requires 17 distinct pieces of information in order to run
successfully, it doesn't much matter *how* you get that information from the
user---most people will give up and walk away before they successfully run the
program. This applies whether the user interface is a command-line, a
configuration file, or a GUI: if you make that many demands on your users, most
of them will simply give up.
In short, try to minimize the amount of information that users are absolutely
required to supply---use sensible defaults whenever possible. Of course, you
also want to make your programs reasonably flexible. That's what options are
for. Again, it doesn't matter if they are entries in a config file, widgets in
the "Preferences" dialog of a GUI, or command-line options---the more options
you implement, the more flexible your program is, and the more complicated its
implementation becomes. Too much flexibility has drawbacks as well, of course;
too many options can overwhelm users and make your code much harder to maintain.
.. _optparse-tutorial:
Tutorial
--------
While :mod:`optparse` is quite flexible and powerful, it's also straightforward
to use in most cases. This section covers the code patterns that are common to
any :mod:`optparse`\ -based program.
First, you need to import the OptionParser class; then, early in the main
program, create an OptionParser instance::
from optparse import OptionParser
...
parser = OptionParser()
Then you can start defining options. The basic syntax is::
parser.add_option(opt_str, ...,
attr=value, ...)
Each option has one or more option strings, such as ``-f`` or ``--file``,
and several option attributes that tell :mod:`optparse` what to expect and what
to do when it encounters that option on the command line.
Typically, each option will have one short option string and one long option
string, e.g.::
parser.add_option("-f", "--file", ...)
You're free to define as many short option strings and as many long option
strings as you like (including zero), as long as there is at least one option
string overall.
The option strings passed to :meth:`OptionParser.add_option` are effectively
labels for the
option defined by that call. For brevity, we will frequently refer to
*encountering an option* on the command line; in reality, :mod:`optparse`
encounters *option strings* and looks up options from them.
Once all of your options are defined, instruct :mod:`optparse` to parse your
program's command line::
(options, args) = parser.parse_args()
(If you like, you can pass a custom argument list to :meth:`parse_args`, but
that's rarely necessary: by default it uses ``sys.argv[1:]``.)
:meth:`parse_args` returns two values:
* ``options``, an object containing values for all of your options---e.g. if
``--file`` takes a single string argument, then ``options.file`` will be the
filename supplied by the user, or ``None`` if the user did not supply that
option
* ``args``, the list of positional arguments leftover after parsing options
This tutorial section only covers the four most important option attributes:
:attr:`~Option.action`, :attr:`~Option.type`, :attr:`~Option.dest`
(destination), and :attr:`~Option.help`. Of these, :attr:`~Option.action` is the
most fundamental.
.. _optparse-understanding-option-actions:
Understanding option actions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Actions tell :mod:`optparse` what to do when it encounters an option on the
command line. There is a fixed set of actions hard-coded into :mod:`optparse`;
adding new actions is an advanced topic covered in section
:ref:`optparse-extending-optparse`. Most actions tell :mod:`optparse` to store
a value in some variable---for example, take a string from the command line and
store it in an attribute of ``options``.
If you don't specify an option action, :mod:`optparse` defaults to ``store``.
.. _optparse-store-action:
The store action
^^^^^^^^^^^^^^^^
The most common option action is ``store``, which tells :mod:`optparse` to take
the next argument (or the remainder of the current argument), ensure that it is
of the correct type, and store it to your chosen destination.
For example::
parser.add_option("-f", "--file",
action="store", type="string", dest="filename")
Now let's make up a fake command line and ask :mod:`optparse` to parse it::
args = ["-f", "foo.txt"]
(options, args) = parser.parse_args(args)
When :mod:`optparse` sees the option string ``-f``, it consumes the next
argument, ``foo.txt``, and stores it in ``options.filename``. So, after this
call to :meth:`parse_args`, ``options.filename`` is ``"foo.txt"``.
Some other option types supported by :mod:`optparse` are ``int`` and ``float``.
Here's an option that expects an integer argument::
parser.add_option("-n", type="int", dest="num")
Note that this option has no long option string, which is perfectly acceptable.
Also, there's no explicit action, since the default is ``store``.
Let's parse another fake command-line. This time, we'll jam the option argument
right up against the option: since ``-n42`` (one argument) is equivalent to
``-n 42`` (two arguments), the code ::
(options, args) = parser.parse_args(["-n42"])
print options.num
will print ``42``.
If you don't specify a type, :mod:`optparse` assumes ``string``. Combined with
the fact that the default action is ``store``, that means our first example can
be a lot shorter::
parser.add_option("-f", "--file", dest="filename")
If you don't supply a destination, :mod:`optparse` figures out a sensible
default from the option strings: if the first long option string is
``--foo-bar``, then the default destination is ``foo_bar``. If there are no
long option strings, :mod:`optparse` looks at the first short option string: the
default destination for ``-f`` is ``f``.
:mod:`optparse` also includes built-in ``long`` and ``complex`` types. Adding
types is covered in section :ref:`optparse-extending-optparse`.
.. _optparse-handling-boolean-options:
Handling boolean (flag) options
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Flag options---set a variable to true or false when a particular option is seen
---are quite common. :mod:`optparse` supports them with two separate actions,
``store_true`` and ``store_false``. For example, you might have a ``verbose``
flag that is turned on with ``-v`` and off with ``-q``::
parser.add_option("-v", action="store_true", dest="verbose")
parser.add_option("-q", action="store_false", dest="verbose")
Here we have two different options with the same destination, which is perfectly
OK. (It just means you have to be a bit careful when setting default values---
see below.)
When :mod:`optparse` encounters ``-v`` on the command line, it sets
``options.verbose`` to ``True``; when it encounters ``-q``,
``options.verbose`` is set to ``False``.
.. _optparse-other-actions:
Other actions
^^^^^^^^^^^^^
Some other actions supported by :mod:`optparse` are:
``"store_const"``
store a constant value
``"append"``
append this option's argument to a list
``"count"``
increment a counter by one
``"callback"``
call a specified function
These are covered in section :ref:`optparse-reference-guide`, Reference Guide
and section :ref:`optparse-option-callbacks`.
.. _optparse-default-values:
Default values
^^^^^^^^^^^^^^
All of the above examples involve setting some variable (the "destination") when
certain command-line options are seen. What happens if those options are never
seen? Since we didn't supply any defaults, they are all set to ``None``. This
is usually fine, but sometimes you want more control. :mod:`optparse` lets you
supply a default value for each destination, which is assigned before the
command line is parsed.
First, consider the verbose/quiet example. If we want :mod:`optparse` to set
``verbose`` to ``True`` unless ``-q`` is seen, then we can do this::
parser.add_option("-v", action="store_true", dest="verbose", default=True)
parser.add_option("-q", action="store_false", dest="verbose")
Since default values apply to the *destination* rather than to any particular
option, and these two options happen to have the same destination, this is
exactly equivalent::
parser.add_option("-v", action="store_true", dest="verbose")
parser.add_option("-q", action="store_false", dest="verbose", default=True)
Consider this::
parser.add_option("-v", action="store_true", dest="verbose", default=False)
parser.add_option("-q", action="store_false", dest="verbose", default=True)
Again, the default value for ``verbose`` will be ``True``: the last default
value supplied for any particular destination is the one that counts.
A clearer way to specify default values is the :meth:`set_defaults` method of
OptionParser, which you can call at any time before calling :meth:`parse_args`::
parser.set_defaults(verbose=True)
parser.add_option(...)
(options, args) = parser.parse_args()
As before, the last value specified for a given option destination is the one
that counts. For clarity, try to use one method or the other of setting default
values, not both.
.. _optparse-generating-help:
Generating help
^^^^^^^^^^^^^^^
:mod:`optparse`'s ability to generate help and usage text automatically is
useful for creating user-friendly command-line interfaces. All you have to do
is supply a :attr:`~Option.help` value for each option, and optionally a short
usage message for your whole program. Here's an OptionParser populated with
user-friendly (documented) options::
usage = "usage: %prog [options] arg1 arg2"
parser = OptionParser(usage=usage)
parser.add_option("-v", "--verbose",
action="store_true", dest="verbose", default=True,
help="make lots of noise [default]")
parser.add_option("-q", "--quiet",
action="store_false", dest="verbose",
help="be vewwy quiet (I'm hunting wabbits)")
parser.add_option("-f", "--filename",
metavar="FILE", help="write output to FILE")
parser.add_option("-m", "--mode",
default="intermediate",
help="interaction mode: novice, intermediate, "
"or expert [default: %default]")
If :mod:`optparse` encounters either ``-h`` or ``--help`` on the
command-line, or if you just call :meth:`parser.print_help`, it prints the
following to standard output:
.. code-block:: text
Usage: <yourscript> [options] arg1 arg2
Options:
-h, --help show this help message and exit
-v, --verbose make lots of noise [default]
-q, --quiet be vewwy quiet (I'm hunting wabbits)
-f FILE, --filename=FILE
write output to FILE
-m MODE, --mode=MODE interaction mode: novice, intermediate, or
expert [default: intermediate]
(If the help output is triggered by a help option, :mod:`optparse` exits after
printing the help text.)
There's a lot going on here to help :mod:`optparse` generate the best possible
help message:
* the script defines its own usage message::
usage = "usage: %prog [options] arg1 arg2"
:mod:`optparse` expands ``%prog`` in the usage string to the name of the
current program, i.e. ``os.path.basename(sys.argv[0])``. The expanded string
is then printed before the detailed option help.
If you don't supply a usage string, :mod:`optparse` uses a bland but sensible
default: ``"Usage: %prog [options]"``, which is fine if your script doesn't
take any positional arguments.
* every option defines a help string, and doesn't worry about line-wrapping---
:mod:`optparse` takes care of wrapping lines and making the help output look
good.
* options that take a value indicate this fact in their automatically-generated
help message, e.g. for the "mode" option::
-m MODE, --mode=MODE
Here, "MODE" is called the meta-variable: it stands for the argument that the
user is expected to supply to ``-m``/``--mode``. By default,
:mod:`optparse` converts the destination variable name to uppercase and uses
that for the meta-variable. Sometimes, that's not what you want---for
example, the ``--filename`` option explicitly sets ``metavar="FILE"``,
resulting in this automatically-generated option description::
-f FILE, --filename=FILE
This is important for more than just saving space, though: the manually
written help text uses the meta-variable ``FILE`` to clue the user in that
there's a connection between the semi-formal syntax ``-f FILE`` and the informal
semantic description "write output to FILE". This is a simple but effective
way to make your help text a lot clearer and more useful for end users.
.. versionadded:: 2.4
Options that have a default value can include ``%default`` in the help
string---\ :mod:`optparse` will replace it with :func:`str` of the option's
default value. If an option has no default value (or the default value is
``None``), ``%default`` expands to ``none``.
Grouping Options
++++++++++++++++
When dealing with many options, it is convenient to group these options for
better help output. An :class:`OptionParser` can contain several option groups,
each of which can contain several options.
An option group is obtained using the class :class:`OptionGroup`:
.. class:: OptionGroup(parser, title, description=None)
where
* parser is the :class:`OptionParser` instance the group will be insterted in
to
* title is the group title
* description, optional, is a long description of the group
:class:`OptionGroup` inherits from :class:`OptionContainer` (like
:class:`OptionParser`) and so the :meth:`add_option` method can be used to add
an option to the group.
Once all the options are declared, using the :class:`OptionParser` method
:meth:`add_option_group` the group is added to the previously defined parser.
Continuing with the parser defined in the previous section, adding an
:class:`OptionGroup` to a parser is easy::
group = OptionGroup(parser, "Dangerous Options",
"Caution: use these options at your own risk. "
"It is believed that some of them bite.")
group.add_option("-g", action="store_true", help="Group option.")
parser.add_option_group(group)
This would result in the following help output:
.. code-block:: text
Usage: <yourscript> [options] arg1 arg2
Options:
-h, --help show this help message and exit
-v, --verbose make lots of noise [default]
-q, --quiet be vewwy quiet (I'm hunting wabbits)
-f FILE, --filename=FILE
write output to FILE
-m MODE, --mode=MODE interaction mode: novice, intermediate, or
expert [default: intermediate]
Dangerous Options:
Caution: use these options at your own risk. It is believed that some
of them bite.
-g Group option.
A bit more complete example might involve using more than one group: still
extending the previous example::
group = OptionGroup(parser, "Dangerous Options",
"Caution: use these options at your own risk. "
"It is believed that some of them bite.")
group.add_option("-g", action="store_true", help="Group option.")
parser.add_option_group(group)
group = OptionGroup(parser, "Debug Options")
group.add_option("-d", "--debug", action="store_true",
help="Print debug information")
group.add_option("-s", "--sql", action="store_true",
help="Print all SQL statements executed")
group.add_option("-e", action="store_true", help="Print every action done")
parser.add_option_group(group)
that results in the following output:
.. code-block:: text
Usage: <yourscript> [options] arg1 arg2
Options:
-h, --help show this help message and exit
-v, --verbose make lots of noise [default]
-q, --quiet be vewwy quiet (I'm hunting wabbits)
-f FILE, --filename=FILE
write output to FILE
-m MODE, --mode=MODE interaction mode: novice, intermediate, or expert
[default: intermediate]
Dangerous Options:
Caution: use these options at your own risk. It is believed that some
of them bite.
-g Group option.
Debug Options:
-d, --debug Print debug information
-s, --sql Print all SQL statements executed
-e Print every action done
Another interesting method, in particular when working programmatically with
option groups is:
.. method:: OptionParser.get_option_group(opt_str)
Return the :class:`OptionGroup` to which the short or long option
string *opt_str* (e.g. ``'-o'`` or ``'--option'``) belongs. If
there's no such :class:`OptionGroup`, return ``None``.
.. _optparse-printing-version-string:
Printing a version string
^^^^^^^^^^^^^^^^^^^^^^^^^
Similar to the brief usage string, :mod:`optparse` can also print a version
string for your program. You have to supply the string as the ``version``
argument to OptionParser::
parser = OptionParser(usage="%prog [-f] [-q]", version="%prog 1.0")
``%prog`` is expanded just like it is in ``usage``. Apart from that,
``version`` can contain anything you like. When you supply it, :mod:`optparse`
automatically adds a ``--version`` option to your parser. If it encounters
this option on the command line, it expands your ``version`` string (by
replacing ``%prog``), prints it to stdout, and exits.
For example, if your script is called ``/usr/bin/foo``:
.. code-block:: shell-session
$ /usr/bin/foo --version
foo 1.0
The following two methods can be used to print and get the ``version`` string:
.. method:: OptionParser.print_version(file=None)
Print the version message for the current program (``self.version``) to
*file* (default stdout). As with :meth:`print_usage`, any occurrence
of ``%prog`` in ``self.version`` is replaced with the name of the current
program. Does nothing if ``self.version`` is empty or undefined.
.. method:: OptionParser.get_version()
Same as :meth:`print_version` but returns the version string instead of
printing it.
.. _optparse-how-optparse-handles-errors:
How :mod:`optparse` handles errors
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
There are two broad classes of errors that :mod:`optparse` has to worry about:
programmer errors and user errors. Programmer errors are usually erroneous
calls to :func:`OptionParser.add_option`, e.g. invalid option strings, unknown
option attributes, missing option attributes, etc. These are dealt with in the
usual way: raise an exception (either :exc:`optparse.OptionError` or
:exc:`TypeError`) and let the program crash.
Handling user errors is much more important, since they are guaranteed to happen
no matter how stable your code is. :mod:`optparse` can automatically detect
some user errors, such as bad option arguments (passing ``-n 4x`` where
``-n`` takes an integer argument), missing arguments (``-n`` at the end
of the command line, where ``-n`` takes an argument of any type). Also,
you can call :func:`OptionParser.error` to signal an application-defined error
condition::
(options, args) = parser.parse_args()
...
if options.a and options.b:
parser.error("options -a and -b are mutually exclusive")
In either case, :mod:`optparse` handles the error the same way: it prints the
program's usage message and an error message to standard error and exits with
error status 2.
Consider the first example above, where the user passes ``4x`` to an option
that takes an integer:
.. code-block:: shell-session
$ /usr/bin/foo -n 4x
Usage: foo [options]
foo: error: option -n: invalid integer value: '4x'
Or, where the user fails to pass a value at all:
.. code-block:: shell-session
$ /usr/bin/foo -n
Usage: foo [options]
foo: error: -n option requires an argument
:mod:`optparse`\ -generated error messages take care always to mention the
option involved in the error; be sure to do the same when calling
:func:`OptionParser.error` from your application code.
If :mod:`optparse`'s default error-handling behaviour does not suit your needs,
you'll need to subclass OptionParser and override its :meth:`~OptionParser.exit`
and/or :meth:`~OptionParser.error` methods.
.. _optparse-putting-it-all-together:
Putting it all together
^^^^^^^^^^^^^^^^^^^^^^^
Here's what :mod:`optparse`\ -based scripts usually look like::
from optparse import OptionParser
...
def main():
usage = "usage: %prog [options] arg"
parser = OptionParser(usage)
parser.add_option("-f", "--file", dest="filename",
help="read data from FILENAME")
parser.add_option("-v", "--verbose",
action="store_true", dest="verbose")
parser.add_option("-q", "--quiet",
action="store_false", dest="verbose")
...
(options, args) = parser.parse_args()
if len(args) != 1:
parser.error("incorrect number of arguments")
if options.verbose:
print "reading %s..." % options.filename
...
if __name__ == "__main__":
main()
.. _optparse-reference-guide:
Reference Guide
---------------
.. _optparse-creating-parser:
Creating the parser
^^^^^^^^^^^^^^^^^^^
The first step in using :mod:`optparse` is to create an OptionParser instance.
.. class:: OptionParser(...)
The OptionParser constructor has no required arguments, but a number of
optional keyword arguments. You should always pass them as keyword
arguments, i.e. do not rely on the order in which the arguments are declared.
``usage`` (default: ``"%prog [options]"``)
The usage summary to print when your program is run incorrectly or with a
help option. When :mod:`optparse` prints the usage string, it expands
``%prog`` to ``os.path.basename(sys.argv[0])`` (or to ``prog`` if you
passed that keyword argument). To suppress a usage message, pass the
special value :data:`optparse.SUPPRESS_USAGE`.
``option_list`` (default: ``[]``)
A list of Option objects to populate the parser with. The options in
``option_list`` are added after any options in ``standard_option_list`` (a
class attribute that may be set by OptionParser subclasses), but before
any version or help options. Deprecated; use :meth:`add_option` after
creating the parser instead.
``option_class`` (default: optparse.Option)
Class to use when adding options to the parser in :meth:`add_option`.
``version`` (default: ``None``)
A version string to print when the user supplies a version option. If you
supply a true value for ``version``, :mod:`optparse` automatically adds a
version option with the single option string ``--version``. The
substring ``%prog`` is expanded the same as for ``usage``.
``conflict_handler`` (default: ``"error"``)
Specifies what to do when options with conflicting option strings are
added to the parser; see section
:ref:`optparse-conflicts-between-options`.
``description`` (default: ``None``)
A paragraph of text giving a brief overview of your program.
:mod:`optparse` reformats this paragraph to fit the current terminal width
and prints it when the user requests help (after ``usage``, but before the
list of options).
``formatter`` (default: a new :class:`IndentedHelpFormatter`)
An instance of optparse.HelpFormatter that will be used for printing help
text. :mod:`optparse` provides two concrete classes for this purpose:
IndentedHelpFormatter and TitledHelpFormatter.
``add_help_option`` (default: ``True``)
If true, :mod:`optparse` will add a help option (with option strings ``-h``
and ``--help``) to the parser.
``prog``
The string to use when expanding ``%prog`` in ``usage`` and ``version``
instead of ``os.path.basename(sys.argv[0])``.
``epilog`` (default: ``None``)
A paragraph of help text to print after the option help.
.. _optparse-populating-parser:
Populating the parser
^^^^^^^^^^^^^^^^^^^^^
There are several ways to populate the parser with options. The preferred way
is by using :meth:`OptionParser.add_option`, as shown in section
:ref:`optparse-tutorial`. :meth:`add_option` can be called in one of two ways:
* pass it an Option instance (as returned by :func:`make_option`)
* pass it any combination of positional and keyword arguments that are
acceptable to :func:`make_option` (i.e., to the Option constructor), and it
will create the Option instance for you
The other alternative is to pass a list of pre-constructed Option instances to
the OptionParser constructor, as in::
option_list = [
make_option("-f", "--filename",
action="store", type="string", dest="filename"),
make_option("-q", "--quiet",
action="store_false", dest="verbose"),
]
parser = OptionParser(option_list=option_list)
(:func:`make_option` is a factory function for creating Option instances;
currently it is an alias for the Option constructor. A future version of
:mod:`optparse` may split Option into several classes, and :func:`make_option`
will pick the right class to instantiate. Do not instantiate Option directly.)
.. _optparse-defining-options:
Defining options
^^^^^^^^^^^^^^^^
Each Option instance represents a set of synonymous command-line option strings,
e.g. ``-f`` and ``--file``. You can specify any number of short or
long option strings, but you must specify at least one overall option string.
The canonical way to create an :class:`Option` instance is with the
:meth:`add_option` method of :class:`OptionParser`.
.. method:: OptionParser.add_option(option)
OptionParser.add_option(*opt_str, attr=value, ...)
To define an option with only a short option string::
parser.add_option("-f", attr=value, ...)
And to define an option with only a long option string::
parser.add_option("--foo", attr=value, ...)
The keyword arguments define attributes of the new Option object. The most
important option attribute is :attr:`~Option.action`, and it largely
determines which other attributes are relevant or required. If you pass
irrelevant option attributes, or fail to pass required ones, :mod:`optparse`
raises an :exc:`OptionError` exception explaining your mistake.
An option's *action* determines what :mod:`optparse` does when it encounters
this option on the command-line. The standard option actions hard-coded into
:mod:`optparse` are:
``"store"``
store this option's argument (default)
``"store_const"``
store a constant value
``"store_true"``
store a true value
``"store_false"``
store a false value
``"append"``
append this option's argument to a list
``"append_const"``
append a constant value to a list
``"count"``
increment a counter by one
``"callback"``
call a specified function
``"help"``
print a usage message including all options and the documentation for them
(If you don't supply an action, the default is ``"store"``. For this action,
you may also supply :attr:`~Option.type` and :attr:`~Option.dest` option
attributes; see :ref:`optparse-standard-option-actions`.)
As you can see, most actions involve storing or updating a value somewhere.
:mod:`optparse` always creates a special object for this, conventionally called
``options`` (it happens to be an instance of :class:`optparse.Values`). Option
arguments (and various other values) are stored as attributes of this object,
according to the :attr:`~Option.dest` (destination) option attribute.
For example, when you call ::
parser.parse_args()
one of the first things :mod:`optparse` does is create the ``options`` object::
options = Values()
If one of the options in this parser is defined with ::
parser.add_option("-f", "--file", action="store", type="string", dest="filename")
and the command-line being parsed includes any of the following::
-ffoo
-f foo
--file=foo
--file foo
then :mod:`optparse`, on seeing this option, will do the equivalent of ::
options.filename = "foo"
The :attr:`~Option.type` and :attr:`~Option.dest` option attributes are almost
as important as :attr:`~Option.action`, but :attr:`~Option.action` is the only
one that makes sense for *all* options.
.. _optparse-option-attributes:
Option attributes
^^^^^^^^^^^^^^^^^
The following option attributes may be passed as keyword arguments to
:meth:`OptionParser.add_option`. If you pass an option attribute that is not
relevant to a particular option, or fail to pass a required option attribute,
:mod:`optparse` raises :exc:`OptionError`.
.. attribute:: Option.action
(default: ``"store"``)
Determines :mod:`optparse`'s behaviour when this option is seen on the
command line; the available options are documented :ref:`here
<optparse-standard-option-actions>`.
.. attribute:: Option.type
(default: ``"string"``)
The argument type expected by this option (e.g., ``"string"`` or ``"int"``);
the available option types are documented :ref:`here
<optparse-standard-option-types>`.
.. attribute:: Option.dest
(default: derived from option strings)
If the option's action implies writing or modifying a value somewhere, this
tells :mod:`optparse` where to write it: :attr:`~Option.dest` names an
attribute of the ``options`` object that :mod:`optparse` builds as it parses
the command line.
.. attribute:: Option.default
The value to use for this option's destination if the option is not seen on
the command line. See also :meth:`OptionParser.set_defaults`.
.. attribute:: Option.nargs
(default: 1)
How many arguments of type :attr:`~Option.type` should be consumed when this
option is seen. If > 1, :mod:`optparse` will store a tuple of values to
:attr:`~Option.dest`.
.. attribute:: Option.const
For actions that store a constant value, the constant value to store.
.. attribute:: Option.choices
For options of type ``"choice"``, the list of strings the user may choose
from.
.. attribute:: Option.callback
For options with action ``"callback"``, the callable to call when this option
is seen. See section :ref:`optparse-option-callbacks` for detail on the
arguments passed to the callable.
.. attribute:: Option.callback_args
Option.callback_kwargs
Additional positional and keyword arguments to pass to ``callback`` after the
four standard callback arguments.
.. attribute:: Option.help
Help text to print for this option when listing all available options after
the user supplies a :attr:`~Option.help` option (such as ``--help``). If
no help text is supplied, the option will be listed without help text. To
hide this option, use the special value :data:`optparse.SUPPRESS_HELP`.
.. attribute:: Option.metavar
(default: derived from option strings)
Stand-in for the option argument(s) to use when printing help text. See
section :ref:`optparse-tutorial` for an example.
.. _optparse-standard-option-actions:
Standard option actions
^^^^^^^^^^^^^^^^^^^^^^^
The various option actions all have slightly different requirements and effects.
Most actions have several relevant option attributes which you may specify to
guide :mod:`optparse`'s behaviour; a few have required attributes, which you
must specify for any option using that action.
* ``"store"`` [relevant: :attr:`~Option.type`, :attr:`~Option.dest`,
:attr:`~Option.nargs`, :attr:`~Option.choices`]
The option must be followed by an argument, which is converted to a value
according to :attr:`~Option.type` and stored in :attr:`~Option.dest`. If
:attr:`~Option.nargs` > 1, multiple arguments will be consumed from the
command line; all will be converted according to :attr:`~Option.type` and
stored to :attr:`~Option.dest` as a tuple. See the
:ref:`optparse-standard-option-types` section.
If :attr:`~Option.choices` is supplied (a list or tuple of strings), the type
defaults to ``"choice"``.
If :attr:`~Option.type` is not supplied, it defaults to ``"string"``.
If :attr:`~Option.dest` is not supplied, :mod:`optparse` derives a destination
from the first long option string (e.g., ``--foo-bar`` implies
``foo_bar``). If there are no long option strings, :mod:`optparse` derives a
destination from the first short option string (e.g., ``-f`` implies ``f``).
Example::
parser.add_option("-f")
parser.add_option("-p", type="float", nargs=3, dest="point")
As it parses the command line ::
-f foo.txt -p 1 -3.5 4 -fbar.txt
:mod:`optparse` will set ::
options.f = "foo.txt"
options.point = (1.0, -3.5, 4.0)
options.f = "bar.txt"
* ``"store_const"`` [required: :attr:`~Option.const`; relevant:
:attr:`~Option.dest`]
The value :attr:`~Option.const` is stored in :attr:`~Option.dest`.
Example::
parser.add_option("-q", "--quiet",
action="store_const", const=0, dest="verbose")
parser.add_option("-v", "--verbose",
action="store_const", const=1, dest="verbose")
parser.add_option("--noisy",
action="store_const", const=2, dest="verbose")
If ``--noisy`` is seen, :mod:`optparse` will set ::
options.verbose = 2
* ``"store_true"`` [relevant: :attr:`~Option.dest`]
A special case of ``"store_const"`` that stores a true value to
:attr:`~Option.dest`.
* ``"store_false"`` [relevant: :attr:`~Option.dest`]
Like ``"store_true"``, but stores a false value.
Example::
parser.add_option("--clobber", action="store_true", dest="clobber")
parser.add_option("--no-clobber", action="store_false", dest="clobber")
* ``"append"`` [relevant: :attr:`~Option.type`, :attr:`~Option.dest`,
:attr:`~Option.nargs`, :attr:`~Option.choices`]
The option must be followed by an argument, which is appended to the list in
:attr:`~Option.dest`. If no default value for :attr:`~Option.dest` is
supplied, an empty list is automatically created when :mod:`optparse` first
encounters this option on the command-line. If :attr:`~Option.nargs` > 1,
multiple arguments are consumed, and a tuple of length :attr:`~Option.nargs`
is appended to :attr:`~Option.dest`.
The defaults for :attr:`~Option.type` and :attr:`~Option.dest` are the same as
for the ``"store"`` action.
Example::
parser.add_option("-t", "--tracks", action="append", type="int")
If ``-t3`` is seen on the command-line, :mod:`optparse` does the equivalent
of::
options.tracks = []
options.tracks.append(int("3"))
If, a little later on, ``--tracks=4`` is seen, it does::
options.tracks.append(int("4"))
The ``append`` action calls the ``append`` method on the current value of the
option. This means that any default value specified must have an ``append``
method. It also means that if the default value is non-empty, the default
elements will be present in the parsed value for the option, with any values
from the command line appended after those default values::
>>> parser.add_option("--files", action="append", default=['~/.mypkg/defaults'])
>>> opts, args = parser.parse_args(['--files', 'overrides.mypkg'])
>>> opts.files
['~/.mypkg/defaults', 'overrides.mypkg']
* ``"append_const"`` [required: :attr:`~Option.const`; relevant:
:attr:`~Option.dest`]
Like ``"store_const"``, but the value :attr:`~Option.const` is appended to
:attr:`~Option.dest`; as with ``"append"``, :attr:`~Option.dest` defaults to
``None``, and an empty list is automatically created the first time the option
is encountered.
* ``"count"`` [relevant: :attr:`~Option.dest`]
Increment the integer stored at :attr:`~Option.dest`. If no default value is
supplied, :attr:`~Option.dest` is set to zero before being incremented the
first time.
Example::
parser.add_option("-v", action="count", dest="verbosity")
The first time ``-v`` is seen on the command line, :mod:`optparse` does the
equivalent of::
options.verbosity = 0
options.verbosity += 1
Every subsequent occurrence of ``-v`` results in ::
options.verbosity += 1
* ``"callback"`` [required: :attr:`~Option.callback`; relevant:
:attr:`~Option.type`, :attr:`~Option.nargs`, :attr:`~Option.callback_args`,
:attr:`~Option.callback_kwargs`]
Call the function specified by :attr:`~Option.callback`, which is called as ::
func(option, opt_str, value, parser, *args, **kwargs)
See section :ref:`optparse-option-callbacks` for more detail.
* ``"help"``
Prints a complete help message for all the options in the current option
parser. The help message is constructed from the ``usage`` string passed to
OptionParser's constructor and the :attr:`~Option.help` string passed to every
option.
If no :attr:`~Option.help` string is supplied for an option, it will still be
listed in the help message. To omit an option entirely, use the special value
:data:`optparse.SUPPRESS_HELP`.
:mod:`optparse` automatically adds a :attr:`~Option.help` option to all
OptionParsers, so you do not normally need to create one.
Example::
from optparse import OptionParser, SUPPRESS_HELP
# usually, a help option is added automatically, but that can
# be suppressed using the add_help_option argument
parser = OptionParser(add_help_option=False)
parser.add_option("-h", "--help", action="help")
parser.add_option("-v", action="store_true", dest="verbose",
help="Be moderately verbose")
parser.add_option("--file", dest="filename",
help="Input file to read data from")
parser.add_option("--secret", help=SUPPRESS_HELP)
If :mod:`optparse` sees either ``-h`` or ``--help`` on the command line,
it will print something like the following help message to stdout (assuming
``sys.argv[0]`` is ``"foo.py"``):
.. code-block:: text
Usage: foo.py [options]
Options:
-h, --help Show this help message and exit
-v Be moderately verbose
--file=FILENAME Input file to read data from
After printing the help message, :mod:`optparse` terminates your process with
``sys.exit(0)``.
* ``"version"``
Prints the version number supplied to the OptionParser to stdout and exits.
The version number is actually formatted and printed by the
``print_version()`` method of OptionParser. Generally only relevant if the
``version`` argument is supplied to the OptionParser constructor. As with
:attr:`~Option.help` options, you will rarely create ``version`` options,
since :mod:`optparse` automatically adds them when needed.
.. _optparse-standard-option-types:
Standard option types
^^^^^^^^^^^^^^^^^^^^^
:mod:`optparse` has six built-in option types: ``"string"``, ``"int"``,
``"long"``, ``"choice"``, ``"float"`` and ``"complex"``. If you need to add new
option types, see section :ref:`optparse-extending-optparse`.
Arguments to string options are not checked or converted in any way: the text on
the command line is stored in the destination (or passed to the callback) as-is.
Integer arguments (type ``"int"`` or ``"long"``) are parsed as follows:
* if the number starts with ``0x``, it is parsed as a hexadecimal number
* if the number starts with ``0``, it is parsed as an octal number
* if the number starts with ``0b``, it is parsed as a binary number
* otherwise, the number is parsed as a decimal number
The conversion is done by calling either :func:`int` or :func:`long` with the
appropriate base (2, 8, 10, or 16). If this fails, so will :mod:`optparse`,
although with a more useful error message.
``"float"`` and ``"complex"`` option arguments are converted directly with
:func:`float` and :func:`complex`, with similar error-handling.
``"choice"`` options are a subtype of ``"string"`` options. The
:attr:`~Option.choices` option attribute (a sequence of strings) defines the
set of allowed option arguments. :func:`optparse.check_choice` compares
user-supplied option arguments against this master list and raises
:exc:`OptionValueError` if an invalid string is given.
.. _optparse-parsing-arguments:
Parsing arguments
^^^^^^^^^^^^^^^^^
The whole point of creating and populating an OptionParser is to call its
:meth:`parse_args` method::
(options, args) = parser.parse_args(args=None, values=None)
where the input parameters are
``args``
the list of arguments to process (default: ``sys.argv[1:]``)
``values``
an :class:`optparse.Values` object to store option arguments in (default: a
new instance of :class:`Values`) -- if you give an existing object, the
option defaults will not be initialized on it
and the return values are
``options``
the same object that was passed in as ``values``, or the optparse.Values
instance created by :mod:`optparse`
``args``
the leftover positional arguments after all options have been processed
The most common usage is to supply neither keyword argument. If you supply
``values``, it will be modified with repeated :func:`setattr` calls (roughly one
for every option argument stored to an option destination) and returned by
:meth:`parse_args`.
If :meth:`parse_args` encounters any errors in the argument list, it calls the
OptionParser's :meth:`error` method with an appropriate end-user error message.
This ultimately terminates your process with an exit status of 2 (the
traditional Unix exit status for command-line errors).
.. _optparse-querying-manipulating-option-parser:
Querying and manipulating your option parser
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The default behavior of the option parser can be customized slightly, and you
can also poke around your option parser and see what's there. OptionParser
provides several methods to help you out:
.. method:: OptionParser.disable_interspersed_args()
Set parsing to stop on the first non-option. For example, if ``-a`` and
``-b`` are both simple options that take no arguments, :mod:`optparse`
normally accepts this syntax::
prog -a arg1 -b arg2
and treats it as equivalent to ::
prog -a -b arg1 arg2
To disable this feature, call :meth:`disable_interspersed_args`. This
restores traditional Unix syntax, where option parsing stops with the first
non-option argument.
Use this if you have a command processor which runs another command which has
options of its own and you want to make sure these options don't get
confused. For example, each command might have a different set of options.
.. method:: OptionParser.enable_interspersed_args()
Set parsing to not stop on the first non-option, allowing interspersing
switches with command arguments. This is the default behavior.
.. method:: OptionParser.get_option(opt_str)
Returns the Option instance with the option string *opt_str*, or ``None`` if
no options have that option string.
.. method:: OptionParser.has_option(opt_str)
Return true if the OptionParser has an option with option string *opt_str*
(e.g., ``-q`` or ``--verbose``).
.. method:: OptionParser.remove_option(opt_str)
If the :class:`OptionParser` has an option corresponding to *opt_str*, that
option is removed. If that option provided any other option strings, all of
those option strings become invalid. If *opt_str* does not occur in any
option belonging to this :class:`OptionParser`, raises :exc:`ValueError`.
.. _optparse-conflicts-between-options:
Conflicts between options
^^^^^^^^^^^^^^^^^^^^^^^^^
If you're not careful, it's easy to define options with conflicting option
strings::
parser.add_option("-n", "--dry-run", ...)
...
parser.add_option("-n", "--noisy", ...)
(This is particularly true if you've defined your own OptionParser subclass with
some standard options.)
Every time you add an option, :mod:`optparse` checks for conflicts with existing
options. If it finds any, it invokes the current conflict-handling mechanism.
You can set the conflict-handling mechanism either in the constructor::
parser = OptionParser(..., conflict_handler=handler)
or with a separate call::
parser.set_conflict_handler(handler)
The available conflict handlers are:
``"error"`` (default)
assume option conflicts are a programming error and raise
:exc:`OptionConflictError`
``"resolve"``
resolve option conflicts intelligently (see below)
As an example, let's define an :class:`OptionParser` that resolves conflicts
intelligently and add conflicting options to it::
parser = OptionParser(conflict_handler="resolve")
parser.add_option("-n", "--dry-run", ..., help="do no harm")
parser.add_option("-n", "--noisy", ..., help="be noisy")
At this point, :mod:`optparse` detects that a previously-added option is already
using the ``-n`` option string. Since ``conflict_handler`` is ``"resolve"``,
it resolves the situation by removing ``-n`` from the earlier option's list of
option strings. Now ``--dry-run`` is the only way for the user to activate
that option. If the user asks for help, the help message will reflect that::
Options:
--dry-run do no harm
...
-n, --noisy be noisy
It's possible to whittle away the option strings for a previously-added option
until there are none left, and the user has no way of invoking that option from
the command-line. In that case, :mod:`optparse` removes that option completely,
so it doesn't show up in help text or anywhere else. Carrying on with our
existing OptionParser::
parser.add_option("--dry-run", ..., help="new dry-run option")
At this point, the original ``-n``/``--dry-run`` option is no longer
accessible, so :mod:`optparse` removes it, leaving this help text::
Options:
...
-n, --noisy be noisy
--dry-run new dry-run option
.. _optparse-cleanup:
Cleanup
^^^^^^^
OptionParser instances have several cyclic references. This should not be a
problem for Python's garbage collector, but you may wish to break the cyclic
references explicitly by calling :meth:`~OptionParser.destroy` on your
OptionParser once you are done with it. This is particularly useful in
long-running applications where large object graphs are reachable from your
OptionParser.
.. _optparse-other-methods:
Other methods
^^^^^^^^^^^^^
OptionParser supports several other public methods:
.. method:: OptionParser.set_usage(usage)
Set the usage string according to the rules described above for the ``usage``
constructor keyword argument. Passing ``None`` sets the default usage
string; use :data:`optparse.SUPPRESS_USAGE` to suppress a usage message.
.. method:: OptionParser.print_usage(file=None)
Print the usage message for the current program (``self.usage``) to *file*
(default stdout). Any occurrence of the string ``%prog`` in ``self.usage``
is replaced with the name of the current program. Does nothing if
``self.usage`` is empty or not defined.
.. method:: OptionParser.get_usage()
Same as :meth:`print_usage` but returns the usage string instead of
printing it.
.. method:: OptionParser.set_defaults(dest=value, ...)
Set default values for several option destinations at once. Using
:meth:`set_defaults` is the preferred way to set default values for options,
since multiple options can share the same destination. For example, if
several "mode" options all set the same destination, any one of them can set
the default, and the last one wins::
parser.add_option("--advanced", action="store_const",
dest="mode", const="advanced",
default="novice") # overridden below
parser.add_option("--novice", action="store_const",
dest="mode", const="novice",
default="advanced") # overrides above setting
To avoid this confusion, use :meth:`set_defaults`::
parser.set_defaults(mode="advanced")
parser.add_option("--advanced", action="store_const",
dest="mode", const="advanced")
parser.add_option("--novice", action="store_const",
dest="mode", const="novice")
.. _optparse-option-callbacks:
Option Callbacks
----------------
When :mod:`optparse`'s built-in actions and types aren't quite enough for your
needs, you have two choices: extend :mod:`optparse` or define a callback option.
Extending :mod:`optparse` is more general, but overkill for a lot of simple
cases. Quite often a simple callback is all you need.
There are two steps to defining a callback option:
* define the option itself using the ``"callback"`` action
* write the callback; this is a function (or method) that takes at least four
arguments, as described below
.. _optparse-defining-callback-option:
Defining a callback option
^^^^^^^^^^^^^^^^^^^^^^^^^^
As always, the easiest way to define a callback option is by using the
:meth:`OptionParser.add_option` method. Apart from :attr:`~Option.action`, the
only option attribute you must specify is ``callback``, the function to call::
parser.add_option("-c", action="callback", callback=my_callback)
``callback`` is a function (or other callable object), so you must have already
defined ``my_callback()`` when you create this callback option. In this simple
case, :mod:`optparse` doesn't even know if ``-c`` takes any arguments,
which usually means that the option takes no arguments---the mere presence of
``-c`` on the command-line is all it needs to know. In some
circumstances, though, you might want your callback to consume an arbitrary
number of command-line arguments. This is where writing callbacks gets tricky;
it's covered later in this section.
:mod:`optparse` always passes four particular arguments to your callback, and it
will only pass additional arguments if you specify them via
:attr:`~Option.callback_args` and :attr:`~Option.callback_kwargs`. Thus, the
minimal callback function signature is::
def my_callback(option, opt, value, parser):
The four arguments to a callback are described below.
There are several other option attributes that you can supply when you define a
callback option:
:attr:`~Option.type`
has its usual meaning: as with the ``"store"`` or ``"append"`` actions, it
instructs :mod:`optparse` to consume one argument and convert it to
:attr:`~Option.type`. Rather than storing the converted value(s) anywhere,
though, :mod:`optparse` passes it to your callback function.
:attr:`~Option.nargs`
also has its usual meaning: if it is supplied and > 1, :mod:`optparse` will
consume :attr:`~Option.nargs` arguments, each of which must be convertible to
:attr:`~Option.type`. It then passes a tuple of converted values to your
callback.
:attr:`~Option.callback_args`
a tuple of extra positional arguments to pass to the callback
:attr:`~Option.callback_kwargs`
a dictionary of extra keyword arguments to pass to the callback
.. _optparse-how-callbacks-called:
How callbacks are called
^^^^^^^^^^^^^^^^^^^^^^^^
All callbacks are called as follows::
func(option, opt_str, value, parser, *args, **kwargs)
where
``option``
is the Option instance that's calling the callback
``opt_str``
is the option string seen on the command-line that's triggering the callback.
(If an abbreviated long option was used, ``opt_str`` will be the full,
canonical option string---e.g. if the user puts ``--foo`` on the
command-line as an abbreviation for ``--foobar``, then ``opt_str`` will be
``"--foobar"``.)
``value``
is the argument to this option seen on the command-line. :mod:`optparse` will
only expect an argument if :attr:`~Option.type` is set; the type of ``value`` will be
the type implied by the option's type. If :attr:`~Option.type` for this option is
``None`` (no argument expected), then ``value`` will be ``None``. If :attr:`~Option.nargs`
> 1, ``value`` will be a tuple of values of the appropriate type.
``parser``
is the OptionParser instance driving the whole thing, mainly useful because
you can access some other interesting data through its instance attributes:
``parser.largs``
the current list of leftover arguments, ie. arguments that have been
consumed but are neither options nor option arguments. Feel free to modify
``parser.largs``, e.g. by adding more arguments to it. (This list will
become ``args``, the second return value of :meth:`parse_args`.)
``parser.rargs``
the current list of remaining arguments, ie. with ``opt_str`` and
``value`` (if applicable) removed, and only the arguments following them
still there. Feel free to modify ``parser.rargs``, e.g. by consuming more
arguments.
``parser.values``
the object where option values are by default stored (an instance of
optparse.OptionValues). This lets callbacks use the same mechanism as the
rest of :mod:`optparse` for storing option values; you don't need to mess
around with globals or closures. You can also access or modify the
value(s) of any options already encountered on the command-line.
``args``
is a tuple of arbitrary positional arguments supplied via the
:attr:`~Option.callback_args` option attribute.
``kwargs``
is a dictionary of arbitrary keyword arguments supplied via
:attr:`~Option.callback_kwargs`.
.. _optparse-raising-errors-in-callback:
Raising errors in a callback
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The callback function should raise :exc:`OptionValueError` if there are any
problems with the option or its argument(s). :mod:`optparse` catches this and
terminates the program, printing the error message you supply to stderr. Your
message should be clear, concise, accurate, and mention the option at fault.
Otherwise, the user will have a hard time figuring out what they did wrong.
.. _optparse-callback-example-1:
Callback example 1: trivial callback
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Here's an example of a callback option that takes no arguments, and simply
records that the option was seen::
def record_foo_seen(option, opt_str, value, parser):
parser.values.saw_foo = True
parser.add_option("--foo", action="callback", callback=record_foo_seen)
Of course, you could do that with the ``"store_true"`` action.
.. _optparse-callback-example-2:
Callback example 2: check option order
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Here's a slightly more interesting example: record the fact that ``-a`` is
seen, but blow up if it comes after ``-b`` in the command-line. ::
def check_order(option, opt_str, value, parser):
if parser.values.b:
raise OptionValueError("can't use -a after -b")
parser.values.a = 1
...
parser.add_option("-a", action="callback", callback=check_order)
parser.add_option("-b", action="store_true", dest="b")
.. _optparse-callback-example-3:
Callback example 3: check option order (generalized)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you want to re-use this callback for several similar options (set a flag, but
blow up if ``-b`` has already been seen), it needs a bit of work: the error
message and the flag that it sets must be generalized. ::
def check_order(option, opt_str, value, parser):
if parser.values.b:
raise OptionValueError("can't use %s after -b" % opt_str)
setattr(parser.values, option.dest, 1)
...
parser.add_option("-a", action="callback", callback=check_order, dest='a')
parser.add_option("-b", action="store_true", dest="b")
parser.add_option("-c", action="callback", callback=check_order, dest='c')
.. _optparse-callback-example-4:
Callback example 4: check arbitrary condition
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Of course, you could put any condition in there---you're not limited to checking
the values of already-defined options. For example, if you have options that
should not be called when the moon is full, all you have to do is this::
def check_moon(option, opt_str, value, parser):
if is_moon_full():
raise OptionValueError("%s option invalid when moon is full"
% opt_str)
setattr(parser.values, option.dest, 1)
...
parser.add_option("--foo",
action="callback", callback=check_moon, dest="foo")
(The definition of ``is_moon_full()`` is left as an exercise for the reader.)
.. _optparse-callback-example-5:
Callback example 5: fixed arguments
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Things get slightly more interesting when you define callback options that take
a fixed number of arguments. Specifying that a callback option takes arguments
is similar to defining a ``"store"`` or ``"append"`` option: if you define
:attr:`~Option.type`, then the option takes one argument that must be
convertible to that type; if you further define :attr:`~Option.nargs`, then the
option takes :attr:`~Option.nargs` arguments.
Here's an example that just emulates the standard ``"store"`` action::
def store_value(option, opt_str, value, parser):
setattr(parser.values, option.dest, value)
...
parser.add_option("--foo",
action="callback", callback=store_value,
type="int", nargs=3, dest="foo")
Note that :mod:`optparse` takes care of consuming 3 arguments and converting
them to integers for you; all you have to do is store them. (Or whatever;
obviously you don't need a callback for this example.)
.. _optparse-callback-example-6:
Callback example 6: variable arguments
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Things get hairy when you want an option to take a variable number of arguments.
For this case, you must write a callback, as :mod:`optparse` doesn't provide any
built-in capabilities for it. And you have to deal with certain intricacies of
conventional Unix command-line parsing that :mod:`optparse` normally handles for
you. In particular, callbacks should implement the conventional rules for bare
``--`` and ``-`` arguments:
* either ``--`` or ``-`` can be option arguments
* bare ``--`` (if not the argument to some option): halt command-line
processing and discard the ``--``
* bare ``-`` (if not the argument to some option): halt command-line
processing but keep the ``-`` (append it to ``parser.largs``)
If you want an option that takes a variable number of arguments, there are
several subtle, tricky issues to worry about. The exact implementation you
choose will be based on which trade-offs you're willing to make for your
application (which is why :mod:`optparse` doesn't support this sort of thing
directly).
Nevertheless, here's a stab at a callback for an option with variable
arguments::
def vararg_callback(option, opt_str, value, parser):
assert value is None
value = []
def floatable(str):
try:
float(str)
return True
except ValueError:
return False
for arg in parser.rargs:
# stop on --foo like options
if arg[:2] == "--" and len(arg) > 2:
break
# stop on -a, but not on -3 or -3.0
if arg[:1] == "-" and len(arg) > 1 and not floatable(arg):
break
value.append(arg)
del parser.rargs[:len(value)]
setattr(parser.values, option.dest, value)
...
parser.add_option("-c", "--callback", dest="vararg_attr",
action="callback", callback=vararg_callback)
.. _optparse-extending-optparse:
Extending :mod:`optparse`
-------------------------
Since the two major controlling factors in how :mod:`optparse` interprets
command-line options are the action and type of each option, the most likely
direction of extension is to add new actions and new types.
.. _optparse-adding-new-types:
Adding new types
^^^^^^^^^^^^^^^^
To add new types, you need to define your own subclass of :mod:`optparse`'s
:class:`Option` class. This class has a couple of attributes that define
:mod:`optparse`'s types: :attr:`~Option.TYPES` and :attr:`~Option.TYPE_CHECKER`.
.. attribute:: Option.TYPES
A tuple of type names; in your subclass, simply define a new tuple
:attr:`TYPES` that builds on the standard one.
.. attribute:: Option.TYPE_CHECKER
A dictionary mapping type names to type-checking functions. A type-checking
function has the following signature::
def check_mytype(option, opt, value)
where ``option`` is an :class:`Option` instance, ``opt`` is an option string
(e.g., ``-f``), and ``value`` is the string from the command line that must
be checked and converted to your desired type. ``check_mytype()`` should
return an object of the hypothetical type ``mytype``. The value returned by
a type-checking function will wind up in the OptionValues instance returned
by :meth:`OptionParser.parse_args`, or be passed to a callback as the
``value`` parameter.
Your type-checking function should raise :exc:`OptionValueError` if it
encounters any problems. :exc:`OptionValueError` takes a single string
argument, which is passed as-is to :class:`OptionParser`'s :meth:`error`
method, which in turn prepends the program name and the string ``"error:"``
and prints everything to stderr before terminating the process.
Here's a silly example that demonstrates adding a ``"complex"`` option type to
parse Python-style complex numbers on the command line. (This is even sillier
than it used to be, because :mod:`optparse` 1.3 added built-in support for
complex numbers, but never mind.)
First, the necessary imports::
from copy import copy
from optparse import Option, OptionValueError
You need to define your type-checker first, since it's referred to later (in the
:attr:`~Option.TYPE_CHECKER` class attribute of your Option subclass)::
def check_complex(option, opt, value):
try:
return complex(value)
except ValueError:
raise OptionValueError(
"option %s: invalid complex value: %r" % (opt, value))
Finally, the Option subclass::
class MyOption (Option):
TYPES = Option.TYPES + ("complex",)
TYPE_CHECKER = copy(Option.TYPE_CHECKER)
TYPE_CHECKER["complex"] = check_complex
(If we didn't make a :func:`copy` of :attr:`Option.TYPE_CHECKER`, we would end
up modifying the :attr:`~Option.TYPE_CHECKER` attribute of :mod:`optparse`'s
Option class. This being Python, nothing stops you from doing that except good
manners and common sense.)
That's it! Now you can write a script that uses the new option type just like
any other :mod:`optparse`\ -based script, except you have to instruct your
OptionParser to use MyOption instead of Option::
parser = OptionParser(option_class=MyOption)
parser.add_option("-c", type="complex")
Alternately, you can build your own option list and pass it to OptionParser; if
you don't use :meth:`add_option` in the above way, you don't need to tell
OptionParser which option class to use::
option_list = [MyOption("-c", action="store", type="complex", dest="c")]
parser = OptionParser(option_list=option_list)
.. _optparse-adding-new-actions:
Adding new actions
^^^^^^^^^^^^^^^^^^
Adding new actions is a bit trickier, because you have to understand that
:mod:`optparse` has a couple of classifications for actions:
"store" actions
actions that result in :mod:`optparse` storing a value to an attribute of the
current OptionValues instance; these options require a :attr:`~Option.dest`
attribute to be supplied to the Option constructor.
"typed" actions
actions that take a value from the command line and expect it to be of a
certain type; or rather, a string that can be converted to a certain type.
These options require a :attr:`~Option.type` attribute to the Option
constructor.
These are overlapping sets: some default "store" actions are ``"store"``,
``"store_const"``, ``"append"``, and ``"count"``, while the default "typed"
actions are ``"store"``, ``"append"``, and ``"callback"``.
When you add an action, you need to categorize it by listing it in at least one
of the following class attributes of Option (all are lists of strings):
.. attribute:: Option.ACTIONS
All actions must be listed in ACTIONS.
.. attribute:: Option.STORE_ACTIONS
"store" actions are additionally listed here.
.. attribute:: Option.TYPED_ACTIONS
"typed" actions are additionally listed here.
.. attribute:: Option.ALWAYS_TYPED_ACTIONS
Actions that always take a type (i.e. whose options always take a value) are
additionally listed here. The only effect of this is that :mod:`optparse`
assigns the default type, ``"string"``, to options with no explicit type
whose action is listed in :attr:`ALWAYS_TYPED_ACTIONS`.
In order to actually implement your new action, you must override Option's
:meth:`take_action` method and add a case that recognizes your action.
For example, let's add an ``"extend"`` action. This is similar to the standard
``"append"`` action, but instead of taking a single value from the command-line
and appending it to an existing list, ``"extend"`` will take multiple values in
a single comma-delimited string, and extend an existing list with them. That
is, if ``--names`` is an ``"extend"`` option of type ``"string"``, the command
line ::
--names=foo,bar --names blah --names ding,dong
would result in a list ::
["foo", "bar", "blah", "ding", "dong"]
Again we define a subclass of Option::
class MyOption(Option):
ACTIONS = Option.ACTIONS + ("extend",)
STORE_ACTIONS = Option.STORE_ACTIONS + ("extend",)
TYPED_ACTIONS = Option.TYPED_ACTIONS + ("extend",)
ALWAYS_TYPED_ACTIONS = Option.ALWAYS_TYPED_ACTIONS + ("extend",)
def take_action(self, action, dest, opt, value, values, parser):
if action == "extend":
lvalue = value.split(",")
values.ensure_value(dest, []).extend(lvalue)
else:
Option.take_action(
self, action, dest, opt, value, values, parser)
Features of note:
* ``"extend"`` both expects a value on the command-line and stores that value
somewhere, so it goes in both :attr:`~Option.STORE_ACTIONS` and
:attr:`~Option.TYPED_ACTIONS`.
* to ensure that :mod:`optparse` assigns the default type of ``"string"`` to
``"extend"`` actions, we put the ``"extend"`` action in
:attr:`~Option.ALWAYS_TYPED_ACTIONS` as well.
* :meth:`MyOption.take_action` implements just this one new action, and passes
control back to :meth:`Option.take_action` for the standard :mod:`optparse`
actions.
* ``values`` is an instance of the optparse_parser.Values class, which provides
the very useful :meth:`ensure_value` method. :meth:`ensure_value` is
essentially :func:`getattr` with a safety valve; it is called as ::
values.ensure_value(attr, value)
If the ``attr`` attribute of ``values`` doesn't exist or is ``None``, then
ensure_value() first sets it to ``value``, and then returns 'value. This is
very handy for actions like ``"extend"``, ``"append"``, and ``"count"``, all
of which accumulate data in a variable and expect that variable to be of a
certain type (a list for the first two, an integer for the latter). Using
:meth:`ensure_value` means that scripts using your action don't have to worry
about setting a default value for the option destinations in question; they
can just leave the default as ``None`` and :meth:`ensure_value` will take care of
getting it right when it's needed.
PK %�\;�};&3 &3 % html/_sources/library/os.path.rst.txtnu �[��� :mod:`os.path` --- Common pathname manipulations
================================================
.. module:: os.path
:synopsis: Operations on pathnames.
.. index:: single: path; operations
This module implements some useful functions on pathnames. To read or
write files see :func:`open`, and for accessing the filesystem see the
:mod:`os` module.
.. note::
On Windows, many of these functions do not properly support UNC pathnames.
:func:`splitunc` and :func:`ismount` do handle them correctly.
Unlike a unix shell, Python does not do any *automatic* path expansions.
Functions such as :func:`expanduser` and :func:`expandvars` can be invoked
explicitly when an application desires shell-like path expansion. (See also
the :mod:`glob` module.)
.. note::
Since different operating systems have different path name conventions, there
are several versions of this module in the standard library. The
:mod:`os.path` module is always the path module suitable for the operating
system Python is running on, and therefore usable for local paths. However,
you can also import and use the individual modules if you want to manipulate
a path that is *always* in one of the different formats. They all have the
same interface:
* :mod:`posixpath` for UNIX-style paths
* :mod:`ntpath` for Windows paths
* :mod:`macpath` for old-style MacOS paths
* :mod:`os2emxpath` for OS/2 EMX paths
.. function:: abspath(path)
Return a normalized absolutized version of the pathname *path*. On most
platforms, this is equivalent to calling the function :func:`normpath` as
follows: ``normpath(join(os.getcwd(), path))``.
.. versionadded:: 1.5.2
.. function:: basename(path)
Return the base name of pathname *path*. This is the second element of the
pair returned by passing *path* to the function :func:`split`. Note that
the result of this function is different
from the Unix :program:`basename` program; where :program:`basename` for
``'/foo/bar/'`` returns ``'bar'``, the :func:`basename` function returns an
empty string (``''``).
.. function:: commonprefix(list)
Return the longest path prefix (taken character-by-character) that is a prefix
of all paths in *list*. If *list* is empty, return the empty string (``''``).
Note that this may return invalid paths because it works a character at a time.
.. function:: dirname(path)
Return the directory name of pathname *path*. This is the first element of
the pair returned by passing *path* to the function :func:`split`.
.. function:: exists(path)
Return ``True`` if *path* refers to an existing path. Returns ``False`` for
broken symbolic links. On some platforms, this function may return ``False`` if
permission is not granted to execute :func:`os.stat` on the requested file, even
if the *path* physically exists.
.. function:: lexists(path)
Return ``True`` if *path* refers to an existing path. Returns ``True`` for
broken symbolic links. Equivalent to :func:`exists` on platforms lacking
:func:`os.lstat`.
.. versionadded:: 2.4
.. function:: expanduser(path)
On Unix and Windows, return the argument with an initial component of ``~`` or
``~user`` replaced by that *user*'s home directory.
.. index:: module: pwd
On Unix, an initial ``~`` is replaced by the environment variable :envvar:`HOME`
if it is set; otherwise the current user's home directory is looked up in the
password directory through the built-in module :mod:`pwd`. An initial ``~user``
is looked up directly in the password directory.
On Windows, :envvar:`HOME` and :envvar:`USERPROFILE` will be used if set,
otherwise a combination of :envvar:`HOMEPATH` and :envvar:`HOMEDRIVE` will be
used. An initial ``~user`` is handled by stripping the last directory component
from the created user path derived above.
If the expansion fails or if the path does not begin with a tilde, the path is
returned unchanged.
.. function:: expandvars(path)
Return the argument with environment variables expanded. Substrings of the form
``$name`` or ``${name}`` are replaced by the value of environment variable
*name*. Malformed variable names and references to non-existing variables are
left unchanged.
On Windows, ``%name%`` expansions are supported in addition to ``$name`` and
``${name}``.
.. function:: getatime(path)
Return the time of last access of *path*. The return value is a number giving
the number of seconds since the epoch (see the :mod:`time` module). Raise
:exc:`os.error` if the file does not exist or is inaccessible.
.. versionadded:: 1.5.2
.. versionchanged:: 2.3
If :func:`os.stat_float_times` returns ``True``, the result is a floating point
number.
.. function:: getmtime(path)
Return the time of last modification of *path*. The return value is a number
giving the number of seconds since the epoch (see the :mod:`time` module).
Raise :exc:`os.error` if the file does not exist or is inaccessible.
.. versionadded:: 1.5.2
.. versionchanged:: 2.3
If :func:`os.stat_float_times` returns ``True``, the result is a floating point
number.
.. function:: getctime(path)
Return the system's ctime which, on some systems (like Unix) is the time of the
last metadata change, and, on others (like Windows), is the creation time for *path*.
The return value is a number giving the number of seconds since the epoch (see
the :mod:`time` module). Raise :exc:`os.error` if the file does not exist or
is inaccessible.
.. versionadded:: 2.3
.. function:: getsize(path)
Return the size, in bytes, of *path*. Raise :exc:`os.error` if the file does
not exist or is inaccessible.
.. versionadded:: 1.5.2
.. function:: isabs(path)
Return ``True`` if *path* is an absolute pathname. On Unix, that means it
begins with a slash, on Windows that it begins with a (back)slash after chopping
off a potential drive letter.
.. function:: isfile(path)
Return ``True`` if *path* is an existing regular file. This follows symbolic
links, so both :func:`islink` and :func:`isfile` can be true for the same path.
.. function:: isdir(path)
Return ``True`` if *path* is an existing directory. This follows symbolic
links, so both :func:`islink` and :func:`isdir` can be true for the same path.
.. function:: islink(path)
Return ``True`` if *path* refers to a directory entry that is a symbolic link.
Always ``False`` if symbolic links are not supported by the Python runtime.
.. function:: ismount(path)
Return ``True`` if pathname *path* is a :dfn:`mount point`: a point in a file
system where a different file system has been mounted. The function checks
whether *path*'s parent, :file:`path/..`, is on a different device than *path*,
or whether :file:`path/..` and *path* point to the same i-node on the same
device --- this should detect mount points for all Unix and POSIX variants.
.. function:: join(path, *paths)
Join one or more path components intelligently. The return value is the
concatenation of *path* and any members of *\*paths* with exactly one
directory separator (``os.sep``) following each non-empty part except the
last, meaning that the result will only end in a separator if the last
part is empty. If a component is an absolute path, all previous
components are thrown away and joining continues from the absolute path
component.
On Windows, the drive letter is not reset when an absolute path component
(e.g., ``r'\foo'``) is encountered. If a component contains a drive
letter, all previous components are thrown away and the drive letter is
reset. Note that since there is a current directory for each drive,
``os.path.join("c:", "foo")`` represents a path relative to the current
directory on drive :file:`C:` (:file:`c:foo`), not :file:`c:\\foo`.
.. function:: normcase(path)
Normalize the case of a pathname. On Unix and Mac OS X, this returns the
path unchanged; on case-insensitive filesystems, it converts the path to
lowercase. On Windows, it also converts forward slashes to backward slashes.
.. function:: normpath(path)
Normalize a pathname by collapsing redundant separators and up-level
references so that ``A//B``, ``A/B/``, ``A/./B`` and ``A/foo/../B`` all
become ``A/B``. This string manipulation may change the meaning of a path
that contains symbolic links. On Windows, it converts forward slashes to
backward slashes. To normalize case, use :func:`normcase`.
.. function:: realpath(path)
Return the canonical path of the specified filename, eliminating any symbolic
links encountered in the path (if they are supported by the operating system).
.. versionadded:: 2.2
.. function:: relpath(path[, start])
Return a relative filepath to *path* either from the current directory or
from an optional *start* directory. This is a path computation: the
filesystem is not accessed to confirm the existence or nature of *path* or
*start*.
*start* defaults to :attr:`os.curdir`.
Availability: Windows, Unix.
.. versionadded:: 2.6
.. function:: samefile(path1, path2)
Return ``True`` if both pathname arguments refer to the same file or directory
(as indicated by device number and i-node number). Raise an exception if an
:func:`os.stat` call on either pathname fails.
Availability: Unix.
.. function:: sameopenfile(fp1, fp2)
Return ``True`` if the file descriptors *fp1* and *fp2* refer to the same file.
Availability: Unix.
.. function:: samestat(stat1, stat2)
Return ``True`` if the stat tuples *stat1* and *stat2* refer to the same file.
These structures may have been returned by :func:`os.fstat`,
:func:`os.lstat`, or :func:`os.stat`. This function implements the
underlying comparison used by :func:`samefile` and :func:`sameopenfile`.
Availability: Unix.
.. function:: split(path)
Split the pathname *path* into a pair, ``(head, tail)`` where *tail* is the
last pathname component and *head* is everything leading up to that. The
*tail* part will never contain a slash; if *path* ends in a slash, *tail*
will be empty. If there is no slash in *path*, *head* will be empty. If
*path* is empty, both *head* and *tail* are empty. Trailing slashes are
stripped from *head* unless it is the root (one or more slashes only). In
all cases, ``join(head, tail)`` returns a path to the same location as *path*
(but the strings may differ). Also see the functions :func:`dirname` and
:func:`basename`.
.. function:: splitdrive(path)
Split the pathname *path* into a pair ``(drive, tail)`` where *drive* is either
a drive specification or the empty string. On systems which do not use drive
specifications, *drive* will always be the empty string. In all cases, ``drive
+ tail`` will be the same as *path*.
.. versionadded:: 1.3
.. function:: splitext(path)
Split the pathname *path* into a pair ``(root, ext)`` such that ``root + ext ==
path``, and *ext* is empty or begins with a period and contains at most one
period. Leading periods on the basename are ignored; ``splitext('.cshrc')``
returns ``('.cshrc', '')``.
.. versionchanged:: 2.6
Earlier versions could produce an empty root when the only period was the
first character.
.. function:: splitunc(path)
Split the pathname *path* into a pair ``(unc, rest)`` so that *unc* is the UNC
mount point (such as ``r'\\host\mount'``), if present, and *rest* the rest of
the path (such as ``r'\path\file.ext'``). For paths containing drive letters,
*unc* will always be the empty string.
Availability: Windows.
.. function:: walk(path, visit, arg)
Calls the function *visit* with arguments ``(arg, dirname, names)`` for each
directory in the directory tree rooted at *path* (including *path* itself, if it
is a directory). The argument *dirname* specifies the visited directory, the
argument *names* lists the files in the directory (gotten from
``os.listdir(dirname)``). The *visit* function may modify *names* to influence
the set of directories visited below *dirname*, e.g. to avoid visiting certain
parts of the tree. (The object referred to by *names* must be modified in
place, using :keyword:`del` or slice assignment.)
.. note::
Symbolic links to directories are not treated as subdirectories, and that
:func:`walk` therefore will not visit them. To visit linked directories you must
identify them with ``os.path.islink(file)`` and ``os.path.isdir(file)``, and
invoke :func:`walk` as necessary.
.. note::
This function is deprecated and has been removed in Python 3 in favor of
:func:`os.walk`.
.. data:: supports_unicode_filenames
``True`` if arbitrary Unicode strings can be used as file names (within limitations
imposed by the file system).
.. versionadded:: 2.3
PK %�\/� �B �B html/_sources/library/os.rst.txtnu �[��� :mod:`os` --- Miscellaneous operating system interfaces
=======================================================
.. module:: os
:synopsis: Miscellaneous operating system interfaces.
This module provides a portable way of using operating system dependent
functionality. If you just want to read or write a file see :func:`open`, if
you want to manipulate paths, see the :mod:`os.path` module, and if you want to
read all the lines in all the files on the command line see the :mod:`fileinput`
module. For creating temporary files and directories see the :mod:`tempfile`
module, and for high-level file and directory handling see the :mod:`shutil`
module.
Notes on the availability of these functions:
* The design of all built-in operating system dependent modules of Python is
such that as long as the same functionality is available, it uses the same
interface; for example, the function ``os.stat(path)`` returns stat
information about *path* in the same format (which happens to have originated
with the POSIX interface).
* Extensions peculiar to a particular operating system are also available
through the :mod:`os` module, but using them is of course a threat to
portability.
* An "Availability: Unix" note means that this function is commonly found on
Unix systems. It does not make any claims about its existence on a specific
operating system.
* If not separately noted, all functions that claim "Availability: Unix" are
supported on Mac OS X, which builds on a Unix core.
.. Availability notes get their own line and occur at the end of the function
.. documentation.
.. note::
All functions in this module raise :exc:`OSError` in the case of invalid or
inaccessible file names and paths, or other arguments that have the correct
type, but are not accepted by the operating system.
.. exception:: error
An alias for the built-in :exc:`OSError` exception.
.. data:: name
The name of the operating system dependent module imported. The following
names have currently been registered: ``'posix'``, ``'nt'``,
``'os2'``, ``'ce'``, ``'java'``, ``'riscos'``.
.. seealso::
:attr:`sys.platform` has a finer granularity. :func:`os.uname` gives
system-dependent version information.
The :mod:`platform` module provides detailed checks for the
system's identity.
.. _os-procinfo:
Process Parameters
------------------
These functions and data items provide information and operate on the current
process and user.
.. data:: environ
A :term:`mapping` object representing the string environment. For example,
``environ['HOME']`` is the pathname of your home directory (on some platforms),
and is equivalent to ``getenv("HOME")`` in C.
This mapping is captured the first time the :mod:`os` module is imported,
typically during Python startup as part of processing :file:`site.py`. Changes
to the environment made after this time are not reflected in ``os.environ``,
except for changes made by modifying ``os.environ`` directly.
If the platform supports the :func:`putenv` function, this mapping may be used
to modify the environment as well as query the environment. :func:`putenv` will
be called automatically when the mapping is modified.
.. note::
Calling :func:`putenv` directly does not change ``os.environ``, so it's better
to modify ``os.environ``.
.. note::
On some platforms, including FreeBSD and Mac OS X, setting ``environ`` may
cause memory leaks. Refer to the system documentation for
:c:func:`putenv`.
If :func:`putenv` is not provided, a modified copy of this mapping may be
passed to the appropriate process-creation functions to cause child processes
to use a modified environment.
If the platform supports the :func:`unsetenv` function, you can delete items in
this mapping to unset environment variables. :func:`unsetenv` will be called
automatically when an item is deleted from ``os.environ``, and when
one of the :meth:`pop` or :meth:`clear` methods is called.
.. versionchanged:: 2.6
Also unset environment variables when calling :meth:`os.environ.clear`
and :meth:`os.environ.pop`.
.. function:: chdir(path)
fchdir(fd)
getcwd()
:noindex:
These functions are described in :ref:`os-file-dir`.
.. function:: ctermid()
Return the filename corresponding to the controlling terminal of the process.
Availability: Unix.
.. function:: getegid()
Return the effective group id of the current process. This corresponds to the
"set id" bit on the file being executed in the current process.
Availability: Unix.
.. function:: geteuid()
.. index:: single: user; effective id
Return the current process's effective user id.
Availability: Unix.
.. function:: getgid()
.. index:: single: process; group
Return the real group id of the current process.
Availability: Unix.
.. function:: getgroups()
Return list of supplemental group ids associated with the current process.
Availability: Unix.
.. note::
On Mac OS X, :func:`getgroups` behavior differs somewhat from
other Unix platforms. If the Python interpreter was built with a
deployment target of :const:`10.5` or earlier, :func:`getgroups` returns
the list of effective group ids associated with the current user process;
this list is limited to a system-defined number of entries, typically 16,
and may be modified by calls to :func:`setgroups` if suitably privileged.
If built with a deployment target greater than :const:`10.5`,
:func:`getgroups` returns the current group access list for the user
associated with the effective user id of the process; the group access
list may change over the lifetime of the process, it is not affected by
calls to :func:`setgroups`, and its length is not limited to 16. The
deployment target value, :const:`MACOSX_DEPLOYMENT_TARGET`, can be
obtained with :func:`sysconfig.get_config_var`.
.. function:: initgroups(username, gid)
Call the system initgroups() to initialize the group access list with all of
the groups of which the specified username is a member, plus the specified
group id.
Availability: Unix.
.. versionadded:: 2.7
.. function:: getlogin()
Return the name of the user logged in on the controlling terminal of the
process. For most purposes, it is more useful to use the environment
variable :envvar:`LOGNAME` to find out who the user is, or
``pwd.getpwuid(os.getuid())[0]`` to get the login name of the process's real
user id.
Availability: Unix.
.. function:: getpgid(pid)
Return the process group id of the process with process id *pid*. If *pid* is 0,
the process group id of the current process is returned.
Availability: Unix.
.. versionadded:: 2.3
.. function:: getpgrp()
.. index:: single: process; group
Return the id of the current process group.
Availability: Unix.
.. function:: getpid()
.. index:: single: process; id
Return the current process id.
Availability: Unix, Windows.
.. function:: getppid()
.. index:: single: process; id of parent
Return the parent's process id.
Availability: Unix.
.. function:: getresuid()
Return a tuple (ruid, euid, suid) denoting the current process's
real, effective, and saved user ids.
Availability: Unix.
.. versionadded:: 2.7
.. function:: getresgid()
Return a tuple (rgid, egid, sgid) denoting the current process's
real, effective, and saved group ids.
Availability: Unix.
.. versionadded:: 2.7
.. function:: getuid()
.. index:: single: user; id
Return the current process's real user id.
Availability: Unix.
.. function:: getenv(varname[, value])
Return the value of the environment variable *varname* if it exists, or *value*
if it doesn't. *value* defaults to ``None``.
Availability: most flavors of Unix, Windows.
.. function:: putenv(varname, value)
.. index:: single: environment variables; setting
Set the environment variable named *varname* to the string *value*. Such
changes to the environment affect subprocesses started with :func:`os.system`,
:func:`popen` or :func:`fork` and :func:`execv`.
Availability: most flavors of Unix, Windows.
.. note::
On some platforms, including FreeBSD and Mac OS X, setting ``environ`` may
cause memory leaks. Refer to the system documentation for putenv.
When :func:`putenv` is supported, assignments to items in ``os.environ`` are
automatically translated into corresponding calls to :func:`putenv`; however,
calls to :func:`putenv` don't update ``os.environ``, so it is actually
preferable to assign to items of ``os.environ``.
.. function:: setegid(egid)
Set the current process's effective group id.
Availability: Unix.
.. function:: seteuid(euid)
Set the current process's effective user id.
Availability: Unix.
.. function:: setgid(gid)
Set the current process' group id.
Availability: Unix.
.. function:: setgroups(groups)
Set the list of supplemental group ids associated with the current process to
*groups*. *groups* must be a sequence, and each element must be an integer
identifying a group. This operation is typically available only to the superuser.
Availability: Unix.
.. versionadded:: 2.2
.. note:: On Mac OS X, the length of *groups* may not exceed the
system-defined maximum number of effective group ids, typically 16.
See the documentation for :func:`getgroups` for cases where it may not
return the same group list set by calling setgroups().
.. function:: setpgrp()
Call the system call :c:func:`setpgrp` or ``setpgrp(0, 0)`` depending on
which version is implemented (if any). See the Unix manual for the semantics.
Availability: Unix.
.. function:: setpgid(pid, pgrp)
Call the system call :c:func:`setpgid` to set the process group id of the
process with id *pid* to the process group with id *pgrp*. See the Unix manual
for the semantics.
Availability: Unix.
.. function:: setregid(rgid, egid)
Set the current process's real and effective group ids.
Availability: Unix.
.. function:: setresgid(rgid, egid, sgid)
Set the current process's real, effective, and saved group ids.
Availability: Unix.
.. versionadded:: 2.7
.. function:: setresuid(ruid, euid, suid)
Set the current process's real, effective, and saved user ids.
Availability: Unix.
.. versionadded:: 2.7
.. function:: setreuid(ruid, euid)
Set the current process's real and effective user ids.
Availability: Unix.
.. function:: getsid(pid)
Call the system call :c:func:`getsid`. See the Unix manual for the semantics.
Availability: Unix.
.. versionadded:: 2.4
.. function:: setsid()
Call the system call :c:func:`setsid`. See the Unix manual for the semantics.
Availability: Unix.
.. function:: setuid(uid)
.. index:: single: user; id, setting
Set the current process's user id.
Availability: Unix.
.. placed in this section since it relates to errno.... a little weak
.. function:: strerror(code)
Return the error message corresponding to the error code in *code*.
On platforms where :c:func:`strerror` returns ``NULL`` when given an unknown
error number, :exc:`ValueError` is raised.
Availability: Unix, Windows.
.. function:: umask(mask)
Set the current numeric umask and return the previous umask.
Availability: Unix, Windows.
.. function:: uname()
.. index::
single: gethostname() (in module socket)
single: gethostbyaddr() (in module socket)
Return a 5-tuple containing information identifying the current operating
system. The tuple contains 5 strings: ``(sysname, nodename, release, version,
machine)``. Some systems truncate the nodename to 8 characters or to the
leading component; a better way to get the hostname is
:func:`socket.gethostname` or even
``socket.gethostbyaddr(socket.gethostname())``.
Availability: recent flavors of Unix.
.. function:: unsetenv(varname)
.. index:: single: environment variables; deleting
Unset (delete) the environment variable named *varname*. Such changes to the
environment affect subprocesses started with :func:`os.system`, :func:`popen` or
:func:`fork` and :func:`execv`.
When :func:`unsetenv` is supported, deletion of items in ``os.environ`` is
automatically translated into a corresponding call to :func:`unsetenv`; however,
calls to :func:`unsetenv` don't update ``os.environ``, so it is actually
preferable to delete items of ``os.environ``.
Availability: most flavors of Unix, Windows.
.. _os-newstreams:
File Object Creation
--------------------
These functions create new file objects. (See also :func:`open`.)
.. function:: fdopen(fd[, mode[, bufsize]])
.. index:: single: I/O control; buffering
Return an open file object connected to the file descriptor *fd*. The *mode*
and *bufsize* arguments have the same meaning as the corresponding arguments
to the built-in :func:`open` function. If :func:`fdopen` raises an
exception, it leaves *fd* untouched (unclosed).
Availability: Unix, Windows.
.. versionchanged:: 2.3
When specified, the *mode* argument must now start with one of the letters
``'r'``, ``'w'``, or ``'a'``, otherwise a :exc:`ValueError` is raised.
.. versionchanged:: 2.5
On Unix, when the *mode* argument starts with ``'a'``, the *O_APPEND* flag is
set on the file descriptor (which the :c:func:`fdopen` implementation already
does on most platforms).
.. function:: popen(command[, mode[, bufsize]])
Open a pipe to or from *command*. The return value is an open file object
connected to the pipe, which can be read or written depending on whether *mode*
is ``'r'`` (default) or ``'w'``. The *bufsize* argument has the same meaning as
the corresponding argument to the built-in :func:`open` function. The exit
status of the command (encoded in the format specified for :func:`wait`) is
available as the return value of the :meth:`~file.close` method of the file object,
except that when the exit status is zero (termination without errors), ``None``
is returned.
Availability: Unix, Windows.
.. deprecated:: 2.6
This function is obsolete. Use the :mod:`subprocess` module. Check
especially the :ref:`subprocess-replacements` section.
.. versionchanged:: 2.0
This function worked unreliably under Windows in earlier versions of Python.
This was due to the use of the :c:func:`_popen` function from the libraries
provided with Windows. Newer versions of Python do not use the broken
implementation from the Windows libraries.
.. function:: tmpfile()
Return a new file object opened in update mode (``w+b``). The file has no
directory entries associated with it and will be automatically deleted once
there are no file descriptors for the file.
Availability: Unix, Windows.
There are a number of different :func:`popen\*` functions that provide slightly
different ways to create subprocesses.
.. deprecated:: 2.6
All of the :func:`popen\*` functions are obsolete. Use the :mod:`subprocess`
module.
For each of the :func:`popen\*` variants, if *bufsize* is specified, it
specifies the buffer size for the I/O pipes. *mode*, if provided, should be the
string ``'b'`` or ``'t'``; on Windows this is needed to determine whether the
file objects should be opened in binary or text mode. The default value for
*mode* is ``'t'``.
Also, for each of these variants, on Unix, *cmd* may be a sequence, in which
case arguments will be passed directly to the program without shell intervention
(as with :func:`os.spawnv`). If *cmd* is a string it will be passed to the shell
(as with :func:`os.system`).
These methods do not make it possible to retrieve the exit status from the child
processes. The only way to control the input and output streams and also
retrieve the return codes is to use the :mod:`subprocess` module; these are only
available on Unix.
For a discussion of possible deadlock conditions related to the use of these
functions, see :ref:`popen2-flow-control`.
.. function:: popen2(cmd[, mode[, bufsize]])
Execute *cmd* as a sub-process and return the file objects ``(child_stdin,
child_stdout)``.
.. deprecated:: 2.6
This function is obsolete. Use the :mod:`subprocess` module. Check
especially the :ref:`subprocess-replacements` section.
Availability: Unix, Windows.
.. versionadded:: 2.0
.. function:: popen3(cmd[, mode[, bufsize]])
Execute *cmd* as a sub-process and return the file objects ``(child_stdin,
child_stdout, child_stderr)``.
.. deprecated:: 2.6
This function is obsolete. Use the :mod:`subprocess` module. Check
especially the :ref:`subprocess-replacements` section.
Availability: Unix, Windows.
.. versionadded:: 2.0
.. function:: popen4(cmd[, mode[, bufsize]])
Execute *cmd* as a sub-process and return the file objects ``(child_stdin,
child_stdout_and_stderr)``.
.. deprecated:: 2.6
This function is obsolete. Use the :mod:`subprocess` module. Check
especially the :ref:`subprocess-replacements` section.
Availability: Unix, Windows.
.. versionadded:: 2.0
(Note that ``child_stdin, child_stdout, and child_stderr`` are named from the
point of view of the child process, so *child_stdin* is the child's standard
input.)
This functionality is also available in the :mod:`popen2` module using functions
of the same names, but the return values of those functions have a different
order.
.. _os-fd-ops:
File Descriptor Operations
--------------------------
These functions operate on I/O streams referenced using file descriptors.
File descriptors are small integers corresponding to a file that has been opened
by the current process. For example, standard input is usually file descriptor
0, standard output is 1, and standard error is 2. Further files opened by a
process will then be assigned 3, 4, 5, and so forth. The name "file descriptor"
is slightly deceptive; on Unix platforms, sockets and pipes are also referenced
by file descriptors.
The :meth:`~file.fileno` method can be used to obtain the file descriptor
associated with a file object when required. Note that using the file
descriptor directly will bypass the file object methods, ignoring aspects such
as internal buffering of data.
.. function:: close(fd)
Close file descriptor *fd*.
Availability: Unix, Windows.
.. note::
This function is intended for low-level I/O and must be applied to a file
descriptor as returned by :func:`os.open` or :func:`pipe`. To close a "file
object" returned by the built-in function :func:`open` or by :func:`popen` or
:func:`fdopen`, use its :meth:`~io.IOBase.close` method.
.. function:: closerange(fd_low, fd_high)
Close all file descriptors from *fd_low* (inclusive) to *fd_high* (exclusive),
ignoring errors. Equivalent to::
for fd in xrange(fd_low, fd_high):
try:
os.close(fd)
except OSError:
pass
Availability: Unix, Windows.
.. versionadded:: 2.6
.. function:: dup(fd)
Return a duplicate of file descriptor *fd*.
Availability: Unix, Windows.
.. function:: dup2(fd, fd2)
Duplicate file descriptor *fd* to *fd2*, closing the latter first if necessary.
Availability: Unix, Windows.
.. function:: fchmod(fd, mode)
Change the mode of the file given by *fd* to the numeric *mode*. See the docs
for :func:`chmod` for possible values of *mode*.
Availability: Unix.
.. versionadded:: 2.6
.. function:: fchown(fd, uid, gid)
Change the owner and group id of the file given by *fd* to the numeric *uid*
and *gid*. To leave one of the ids unchanged, set it to -1.
Availability: Unix.
.. versionadded:: 2.6
.. function:: fdatasync(fd)
Force write of file with filedescriptor *fd* to disk. Does not force update of
metadata.
Availability: Unix.
.. note::
This function is not available on MacOS.
.. function:: fpathconf(fd, name)
Return system configuration information relevant to an open file. *name*
specifies the configuration value to retrieve; it may be a string which is the
name of a defined system value; these names are specified in a number of
standards (POSIX.1, Unix 95, Unix 98, and others). Some platforms define
additional names as well. The names known to the host operating system are
given in the ``pathconf_names`` dictionary. For configuration variables not
included in that mapping, passing an integer for *name* is also accepted.
If *name* is a string and is not known, :exc:`ValueError` is raised. If a
specific value for *name* is not supported by the host system, even if it is
included in ``pathconf_names``, an :exc:`OSError` is raised with
:const:`errno.EINVAL` for the error number.
Availability: Unix.
.. function:: fstat(fd)
Return status for file descriptor *fd*, like :func:`~os.stat`.
Availability: Unix, Windows.
.. function:: fstatvfs(fd)
Return information about the filesystem containing the file associated with file
descriptor *fd*, like :func:`statvfs`.
Availability: Unix.
.. function:: fsync(fd)
Force write of file with filedescriptor *fd* to disk. On Unix, this calls the
native :c:func:`fsync` function; on Windows, the MS :c:func:`_commit` function.
If you're starting with a Python file object *f*, first do ``f.flush()``, and
then do ``os.fsync(f.fileno())``, to ensure that all internal buffers associated
with *f* are written to disk.
Availability: Unix, and Windows starting in 2.2.3.
.. function:: ftruncate(fd, length)
Truncate the file corresponding to file descriptor *fd*, so that it is at most
*length* bytes in size.
Availability: Unix.
.. function:: isatty(fd)
Return ``True`` if the file descriptor *fd* is open and connected to a
tty(-like) device, else ``False``.
.. function:: lseek(fd, pos, how)
Set the current position of file descriptor *fd* to position *pos*, modified
by *how*: :const:`SEEK_SET` or ``0`` to set the position relative to the
beginning of the file; :const:`SEEK_CUR` or ``1`` to set it relative to the
current position; :const:`SEEK_END` or ``2`` to set it relative to the end of
the file. Return the new cursor position in bytes, starting from the beginning.
Availability: Unix, Windows.
.. data:: SEEK_SET
SEEK_CUR
SEEK_END
Parameters to the :func:`lseek` function. Their values are 0, 1, and 2,
respectively.
Availability: Windows, Unix.
.. versionadded:: 2.5
.. function:: open(file, flags[, mode])
Open the file *file* and set various flags according to *flags* and possibly its
mode according to *mode*. The default *mode* is ``0777`` (octal), and the
current umask value is first masked out. Return the file descriptor for the
newly opened file.
For a description of the flag and mode values, see the C run-time documentation;
flag constants (like :const:`O_RDONLY` and :const:`O_WRONLY`) are defined in
this module too (see :ref:`open-constants`). In particular, on Windows adding
:const:`O_BINARY` is needed to open files in binary mode.
Availability: Unix, Windows.
.. note::
This function is intended for low-level I/O. For normal usage, use the
built-in function :func:`open`, which returns a "file object" with
:meth:`~file.read` and :meth:`~file.write` methods (and many more). To
wrap a file descriptor in a "file object", use :func:`fdopen`.
.. function:: openpty()
.. index:: module: pty
Open a new pseudo-terminal pair. Return a pair of file descriptors ``(master,
slave)`` for the pty and the tty, respectively. For a (slightly) more portable
approach, use the :mod:`pty` module.
Availability: some flavors of Unix.
.. function:: pipe()
Create a pipe. Return a pair of file descriptors ``(r, w)`` usable for reading
and writing, respectively.
Availability: Unix, Windows.
.. function:: read(fd, n)
Read at most *n* bytes from file descriptor *fd*. Return a string containing the
bytes read. If the end of the file referred to by *fd* has been reached, an
empty string is returned.
Availability: Unix, Windows.
.. note::
This function is intended for low-level I/O and must be applied to a file
descriptor as returned by :func:`os.open` or :func:`pipe`. To read a "file object"
returned by the built-in function :func:`open` or by :func:`popen` or
:func:`fdopen`, or :data:`sys.stdin`, use its :meth:`~file.read` or
:meth:`~file.readline` methods.
.. function:: tcgetpgrp(fd)
Return the process group associated with the terminal given by *fd* (an open
file descriptor as returned by :func:`os.open`).
Availability: Unix.
.. function:: tcsetpgrp(fd, pg)
Set the process group associated with the terminal given by *fd* (an open file
descriptor as returned by :func:`os.open`) to *pg*.
Availability: Unix.
.. function:: ttyname(fd)
Return a string which specifies the terminal device associated with
file descriptor *fd*. If *fd* is not associated with a terminal device, an
exception is raised.
Availability: Unix.
.. function:: write(fd, str)
Write the string *str* to file descriptor *fd*. Return the number of bytes
actually written.
Availability: Unix, Windows.
.. note::
This function is intended for low-level I/O and must be applied to a file
descriptor as returned by :func:`os.open` or :func:`pipe`. To write a "file
object" returned by the built-in function :func:`open` or by :func:`popen` or
:func:`fdopen`, or :data:`sys.stdout` or :data:`sys.stderr`, use its
:meth:`~file.write` method.
.. _open-constants:
``open()`` flag constants
~~~~~~~~~~~~~~~~~~~~~~~~~
The following constants are options for the *flags* parameter to the
:func:`~os.open` function. They can be combined using the bitwise OR operator
``|``. Some of them are not available on all platforms. For descriptions of
their availability and use, consult the :manpage:`open(2)` manual page on Unix
or `the MSDN <http://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windows.
.. data:: O_RDONLY
O_WRONLY
O_RDWR
O_APPEND
O_CREAT
O_EXCL
O_TRUNC
The above constants are available on Unix and Windows.
.. data:: O_DSYNC
O_RSYNC
O_SYNC
O_NDELAY
O_NONBLOCK
O_NOCTTY
The above constants are only available on Unix.
.. data:: O_BINARY
O_NOINHERIT
O_SHORT_LIVED
O_TEMPORARY
O_RANDOM
O_SEQUENTIAL
O_TEXT
The above constants are only available on Windows.
.. data:: O_ASYNC
O_DIRECT
O_DIRECTORY
O_NOFOLLOW
O_NOATIME
O_SHLOCK
O_EXLOCK
The above constants are extensions and not present if they are not
defined by the C library.
.. _os-file-dir:
Files and Directories
---------------------
.. function:: access(path, mode)
Use the real uid/gid to test for access to *path*. Note that most operations
will use the effective uid/gid, therefore this routine can be used in a
suid/sgid environment to test if the invoking user has the specified access to
*path*. *mode* should be :const:`F_OK` to test the existence of *path*, or it
can be the inclusive OR of one or more of :const:`R_OK`, :const:`W_OK`, and
:const:`X_OK` to test permissions. Return :const:`True` if access is allowed,
:const:`False` if not. See the Unix man page :manpage:`access(2)` for more
information.
Availability: Unix, Windows.
.. note::
Using :func:`access` to check if a user is authorized to e.g. open a file
before actually doing so using :func:`open` creates a security hole,
because the user might exploit the short time interval between checking
and opening the file to manipulate it. It's preferable to use :term:`EAFP`
techniques. For example::
if os.access("myfile", os.R_OK):
with open("myfile") as fp:
return fp.read()
return "some default data"
is better written as::
try:
fp = open("myfile")
except IOError as e:
if e.errno == errno.EACCES:
return "some default data"
# Not a permission error.
raise
else:
with fp:
return fp.read()
.. note::
I/O operations may fail even when :func:`access` indicates that they would
succeed, particularly for operations on network filesystems which may have
permissions semantics beyond the usual POSIX permission-bit model.
.. data:: F_OK
Value to pass as the *mode* parameter of :func:`access` to test the existence of
*path*.
.. data:: R_OK
Value to include in the *mode* parameter of :func:`access` to test the
readability of *path*.
.. data:: W_OK
Value to include in the *mode* parameter of :func:`access` to test the
writability of *path*.
.. data:: X_OK
Value to include in the *mode* parameter of :func:`access` to determine if
*path* can be executed.
.. function:: chdir(path)
.. index:: single: directory; changing
Change the current working directory to *path*.
Availability: Unix, Windows.
.. function:: fchdir(fd)
Change the current working directory to the directory represented by the file
descriptor *fd*. The descriptor must refer to an opened directory, not an open
file.
Availability: Unix.
.. versionadded:: 2.3
.. function:: getcwd()
Return a string representing the current working directory.
Availability: Unix, Windows.
.. function:: getcwdu()
Return a Unicode object representing the current working directory.
Availability: Unix, Windows.
.. versionadded:: 2.3
.. function:: chflags(path, flags)
Set the flags of *path* to the numeric *flags*. *flags* may take a combination
(bitwise OR) of the following values (as defined in the :mod:`stat` module):
* :data:`stat.UF_NODUMP`
* :data:`stat.UF_IMMUTABLE`
* :data:`stat.UF_APPEND`
* :data:`stat.UF_OPAQUE`
* :data:`stat.UF_NOUNLINK`
* :data:`stat.UF_COMPRESSED`
* :data:`stat.UF_HIDDEN`
* :data:`stat.SF_ARCHIVED`
* :data:`stat.SF_IMMUTABLE`
* :data:`stat.SF_APPEND`
* :data:`stat.SF_NOUNLINK`
* :data:`stat.SF_SNAPSHOT`
Availability: Unix.
.. versionadded:: 2.6
.. function:: chroot(path)
Change the root directory of the current process to *path*. Availability:
Unix.
.. versionadded:: 2.2
.. function:: chmod(path, mode)
Change the mode of *path* to the numeric *mode*. *mode* may take one of the
following values (as defined in the :mod:`stat` module) or bitwise ORed
combinations of them:
* :data:`stat.S_ISUID`
* :data:`stat.S_ISGID`
* :data:`stat.S_ENFMT`
* :data:`stat.S_ISVTX`
* :data:`stat.S_IREAD`
* :data:`stat.S_IWRITE`
* :data:`stat.S_IEXEC`
* :data:`stat.S_IRWXU`
* :data:`stat.S_IRUSR`
* :data:`stat.S_IWUSR`
* :data:`stat.S_IXUSR`
* :data:`stat.S_IRWXG`
* :data:`stat.S_IRGRP`
* :data:`stat.S_IWGRP`
* :data:`stat.S_IXGRP`
* :data:`stat.S_IRWXO`
* :data:`stat.S_IROTH`
* :data:`stat.S_IWOTH`
* :data:`stat.S_IXOTH`
Availability: Unix, Windows.
.. note::
Although Windows supports :func:`chmod`, you can only set the file's read-only
flag with it (via the ``stat.S_IWRITE`` and ``stat.S_IREAD``
constants or a corresponding integer value). All other bits are
ignored.
.. function:: chown(path, uid, gid)
Change the owner and group id of *path* to the numeric *uid* and *gid*. To leave
one of the ids unchanged, set it to -1.
Availability: Unix.
.. function:: lchflags(path, flags)
Set the flags of *path* to the numeric *flags*, like :func:`chflags`, but do not
follow symbolic links.
Availability: Unix.
.. versionadded:: 2.6
.. function:: lchmod(path, mode)
Change the mode of *path* to the numeric *mode*. If path is a symlink, this
affects the symlink rather than the target. See the docs for :func:`chmod`
for possible values of *mode*.
Availability: Unix.
.. versionadded:: 2.6
.. function:: lchown(path, uid, gid)
Change the owner and group id of *path* to the numeric *uid* and *gid*. This
function will not follow symbolic links.
Availability: Unix.
.. versionadded:: 2.3
.. function:: link(source, link_name)
Create a hard link pointing to *source* named *link_name*.
Availability: Unix.
.. function:: listdir(path)
Return a list containing the names of the entries in the directory given by
*path*. The list is in arbitrary order. It does not include the special
entries ``'.'`` and ``'..'`` even if they are present in the
directory.
Availability: Unix, Windows.
.. versionchanged:: 2.3
On Windows NT/2k/XP and Unix, if *path* is a Unicode object, the result will be
a list of Unicode objects. Undecodable filenames will still be returned as
string objects.
.. function:: lstat(path)
Perform the equivalent of an :c:func:`lstat` system call on the given path.
Similar to :func:`~os.stat`, but does not follow symbolic links. On
platforms that do not support symbolic links, this is an alias for
:func:`~os.stat`.
.. function:: mkfifo(path[, mode])
Create a FIFO (a named pipe) named *path* with numeric mode *mode*. The default
*mode* is ``0666`` (octal). The current umask value is first masked out from
the mode.
Availability: Unix.
FIFOs are pipes that can be accessed like regular files. FIFOs exist until they
are deleted (for example with :func:`os.unlink`). Generally, FIFOs are used as
rendezvous between "client" and "server" type processes: the server opens the
FIFO for reading, and the client opens it for writing. Note that :func:`mkfifo`
doesn't open the FIFO --- it just creates the rendezvous point.
.. function:: mknod(filename[, mode=0600[, device=0]])
Create a filesystem node (file, device special file or named pipe) named
*filename*. *mode* specifies both the permissions to use and the type of node to
be created, being combined (bitwise OR) with one of ``stat.S_IFREG``,
``stat.S_IFCHR``, ``stat.S_IFBLK``,
and ``stat.S_IFIFO`` (those constants are available in :mod:`stat`).
For ``stat.S_IFCHR`` and
``stat.S_IFBLK``, *device* defines the newly created device special file (probably using
:func:`os.makedev`), otherwise it is ignored.
.. versionadded:: 2.3
.. function:: major(device)
Extract the device major number from a raw device number (usually the
:attr:`st_dev` or :attr:`st_rdev` field from :c:type:`stat`).
.. versionadded:: 2.3
.. function:: minor(device)
Extract the device minor number from a raw device number (usually the
:attr:`st_dev` or :attr:`st_rdev` field from :c:type:`stat`).
.. versionadded:: 2.3
.. function:: makedev(major, minor)
Compose a raw device number from the major and minor device numbers.
.. versionadded:: 2.3
.. function:: mkdir(path[, mode])
Create a directory named *path* with numeric mode *mode*. The default *mode* is
``0777`` (octal). If the directory already exists,
:exc:`OSError` is raised.
.. _mkdir_modebits:
On some systems, *mode* is ignored. Where it is used, the current umask
value is first masked out. If bits other than the last 9 (i.e. the last 3
digits of the octal representation of the *mode*) are set, their meaning is
platform-dependent. On some platforms, they are ignored and you should call
:func:`chmod` explicitly to set them.
It is also possible to create temporary directories; see the
:mod:`tempfile` module's :func:`tempfile.mkdtemp` function.
Availability: Unix, Windows.
.. function:: makedirs(path[, mode])
.. index::
single: directory; creating
single: UNC paths; and os.makedirs()
Recursive directory creation function. Like :func:`mkdir`, but makes all
intermediate-level directories needed to contain the leaf directory. Raises an
:exc:`error` exception if the leaf directory already exists or cannot be
created. The default *mode* is ``0777`` (octal).
The *mode* parameter is passed to :func:`mkdir`; see :ref:`the mkdir()
description <mkdir_modebits>` for how it is interpreted.
.. note::
:func:`makedirs` will become confused if the path elements to create include
:data:`os.pardir`.
.. versionadded:: 1.5.2
.. versionchanged:: 2.3
This function now handles UNC paths correctly.
.. function:: pathconf(path, name)
Return system configuration information relevant to a named file. *name*
specifies the configuration value to retrieve; it may be a string which is the
name of a defined system value; these names are specified in a number of
standards (POSIX.1, Unix 95, Unix 98, and others). Some platforms define
additional names as well. The names known to the host operating system are
given in the ``pathconf_names`` dictionary. For configuration variables not
included in that mapping, passing an integer for *name* is also accepted.
If *name* is a string and is not known, :exc:`ValueError` is raised. If a
specific value for *name* is not supported by the host system, even if it is
included in ``pathconf_names``, an :exc:`OSError` is raised with
:const:`errno.EINVAL` for the error number.
Availability: Unix.
.. data:: pathconf_names
Dictionary mapping names accepted by :func:`pathconf` and :func:`fpathconf` to
the integer values defined for those names by the host operating system. This
can be used to determine the set of names known to the system. Availability:
Unix.
.. function:: readlink(path)
Return a string representing the path to which the symbolic link points. The
result may be either an absolute or relative pathname; if it is relative, it may
be converted to an absolute pathname using ``os.path.join(os.path.dirname(path),
result)``.
.. versionchanged:: 2.6
If the *path* is a Unicode object the result will also be a Unicode object.
Availability: Unix.
.. function:: remove(path)
Remove (delete) the file *path*. If *path* is a directory, :exc:`OSError` is
raised; see :func:`rmdir` below to remove a directory. This is identical to
the :func:`unlink` function documented below. On Windows, attempting to
remove a file that is in use causes an exception to be raised; on Unix, the
directory entry is removed but the storage allocated to the file is not made
available until the original file is no longer in use.
Availability: Unix, Windows.
.. function:: removedirs(path)
.. index:: single: directory; deleting
Remove directories recursively. Works like :func:`rmdir` except that, if the
leaf directory is successfully removed, :func:`removedirs` tries to
successively remove every parent directory mentioned in *path* until an error
is raised (which is ignored, because it generally means that a parent directory
is not empty). For example, ``os.removedirs('foo/bar/baz')`` will first remove
the directory ``'foo/bar/baz'``, and then remove ``'foo/bar'`` and ``'foo'`` if
they are empty. Raises :exc:`OSError` if the leaf directory could not be
successfully removed.
.. versionadded:: 1.5.2
.. function:: rename(src, dst)
Rename the file or directory *src* to *dst*. If *dst* is a directory,
:exc:`OSError` will be raised. On Unix, if *dst* exists and is a file, it will
be replaced silently if the user has permission. The operation may fail on some
Unix flavors if *src* and *dst* are on different filesystems. If successful,
the renaming will be an atomic operation (this is a POSIX requirement). On
Windows, if *dst* already exists, :exc:`OSError` will be raised even if it is a
file; there may be no way to implement an atomic rename when *dst* names an
existing file.
Availability: Unix, Windows.
.. function:: renames(old, new)
Recursive directory or file renaming function. Works like :func:`rename`, except
creation of any intermediate directories needed to make the new pathname good is
attempted first. After the rename, directories corresponding to rightmost path
segments of the old name will be pruned away using :func:`removedirs`.
.. versionadded:: 1.5.2
.. note::
This function can fail with the new directory structure made if you lack
permissions needed to remove the leaf directory or file.
.. function:: rmdir(path)
Remove (delete) the directory *path*. Only works when the directory is
empty, otherwise, :exc:`OSError` is raised. In order to remove whole
directory trees, :func:`shutil.rmtree` can be used.
Availability: Unix, Windows.
.. function:: stat(path)
Perform the equivalent of a :c:func:`stat` system call on the given path.
(This function follows symlinks; to stat a symlink use :func:`lstat`.)
The return value is an object whose attributes correspond to the members
of the :c:type:`stat` structure, namely:
* :attr:`st_mode` - protection bits,
* :attr:`st_ino` - inode number,
* :attr:`st_dev` - device,
* :attr:`st_nlink` - number of hard links,
* :attr:`st_uid` - user id of owner,
* :attr:`st_gid` - group id of owner,
* :attr:`st_size` - size of file, in bytes,
* :attr:`st_atime` - time of most recent access,
* :attr:`st_mtime` - time of most recent content modification,
* :attr:`st_ctime` - platform dependent; time of most recent metadata change on
Unix, or the time of creation on Windows)
.. versionchanged:: 2.3
If :func:`stat_float_times` returns ``True``, the time values are floats, measuring
seconds. Fractions of a second may be reported if the system supports that.
See :func:`stat_float_times` for further discussion.
On some Unix systems (such as Linux), the following attributes may also be
available:
* :attr:`st_blocks` - number of 512-byte blocks allocated for file
* :attr:`st_blksize` - filesystem blocksize for efficient file system I/O
* :attr:`st_rdev` - type of device if an inode device
* :attr:`st_flags` - user defined flags for file
On other Unix systems (such as FreeBSD), the following attributes may be
available (but may be only filled out if root tries to use them):
* :attr:`st_gen` - file generation number
* :attr:`st_birthtime` - time of file creation
On RISCOS systems, the following attributes are also available:
* :attr:`st_ftype` (file type)
* :attr:`st_attrs` (attributes)
* :attr:`st_obtype` (object type).
.. note::
The exact meaning and resolution of the :attr:`st_atime`,
:attr:`st_mtime`, and :attr:`st_ctime` attributes depend on the operating
system and the file system. For example, on Windows systems using the FAT
or FAT32 file systems, :attr:`st_mtime` has 2-second resolution, and
:attr:`st_atime` has only 1-day resolution. See your operating system
documentation for details.
For backward compatibility, the return value of :func:`~os.stat` is also accessible
as a tuple of at least 10 integers giving the most important (and portable)
members of the :c:type:`stat` structure, in the order :attr:`st_mode`,
:attr:`st_ino`, :attr:`st_dev`, :attr:`st_nlink`, :attr:`st_uid`,
:attr:`st_gid`, :attr:`st_size`, :attr:`st_atime`, :attr:`st_mtime`,
:attr:`st_ctime`. More items may be added at the end by some implementations.
.. index:: module: stat
The standard module :mod:`stat` defines functions and constants that are useful
for extracting information from a :c:type:`stat` structure. (On Windows, some
items are filled with dummy values.)
Example::
>>> import os
>>> statinfo = os.stat('somefile.txt')
>>> statinfo
(33188, 422511, 769, 1, 1032, 100, 926, 1105022698,1105022732, 1105022732)
>>> statinfo.st_size
926
Availability: Unix, Windows.
.. versionchanged:: 2.2
Added access to values as attributes of the returned object.
.. versionchanged:: 2.5
Added :attr:`st_gen` and :attr:`st_birthtime`.
.. function:: stat_float_times([newvalue])
Determine whether :class:`stat_result` represents time stamps as float objects.
If *newvalue* is ``True``, future calls to :func:`~os.stat` return floats, if it is
``False``, future calls return ints. If *newvalue* is omitted, return the
current setting.
For compatibility with older Python versions, accessing :class:`stat_result` as
a tuple always returns integers.
.. versionchanged:: 2.5
Python now returns float values by default. Applications which do not work
correctly with floating point time stamps can use this function to restore the
old behaviour.
The resolution of the timestamps (that is the smallest possible fraction)
depends on the system. Some systems only support second resolution; on these
systems, the fraction will always be zero.
It is recommended that this setting is only changed at program startup time in
the *__main__* module; libraries should never change this setting. If an
application uses a library that works incorrectly if floating point time stamps
are processed, this application should turn the feature off until the library
has been corrected.
.. function:: statvfs(path)
Perform a :c:func:`statvfs` system call on the given path. The return value is
an object whose attributes describe the filesystem on the given path, and
correspond to the members of the :c:type:`statvfs` structure, namely:
:attr:`f_bsize`, :attr:`f_frsize`, :attr:`f_blocks`, :attr:`f_bfree`,
:attr:`f_bavail`, :attr:`f_files`, :attr:`f_ffree`, :attr:`f_favail`,
:attr:`f_flag`, :attr:`f_namemax`.
.. index:: module: statvfs
For backward compatibility, the return value is also accessible as a tuple whose
values correspond to the attributes, in the order given above. The standard
module :mod:`statvfs` defines constants that are useful for extracting
information from a :c:type:`statvfs` structure when accessing it as a sequence;
this remains useful when writing code that needs to work with versions of Python
that don't support accessing the fields as attributes.
Availability: Unix.
.. versionchanged:: 2.2
Added access to values as attributes of the returned object.
.. function:: symlink(source, link_name)
Create a symbolic link pointing to *source* named *link_name*.
Availability: Unix.
.. function:: tempnam([dir[, prefix]])
Return a unique path name that is reasonable for creating a temporary file.
This will be an absolute path that names a potential directory entry in the
directory *dir* or a common location for temporary files if *dir* is omitted or
``None``. If given and not ``None``, *prefix* is used to provide a short prefix
to the filename. Applications are responsible for properly creating and
managing files created using paths returned by :func:`tempnam`; no automatic
cleanup is provided. On Unix, the environment variable :envvar:`TMPDIR`
overrides *dir*, while on Windows :envvar:`TMP` is used. The specific
behavior of this function depends on the C library implementation; some aspects
are underspecified in system documentation.
.. warning::
Use of :func:`tempnam` is vulnerable to symlink attacks; consider using
:func:`tmpfile` (section :ref:`os-newstreams`) instead.
Availability: Unix, Windows.
.. function:: tmpnam()
Return a unique path name that is reasonable for creating a temporary file.
This will be an absolute path that names a potential directory entry in a common
location for temporary files. Applications are responsible for properly
creating and managing files created using paths returned by :func:`tmpnam`; no
automatic cleanup is provided.
.. warning::
Use of :func:`tmpnam` is vulnerable to symlink attacks; consider using
:func:`tmpfile` (section :ref:`os-newstreams`) instead.
Availability: Unix, Windows. This function probably shouldn't be used on
Windows, though: Microsoft's implementation of :func:`tmpnam` always creates a
name in the root directory of the current drive, and that's generally a poor
location for a temp file (depending on privileges, you may not even be able to
open a file using this name).
.. data:: TMP_MAX
The maximum number of unique names that :func:`tmpnam` will generate before
reusing names.
.. function:: unlink(path)
Remove (delete) the file *path*. This is the same function as
:func:`remove`; the :func:`unlink` name is its traditional Unix
name.
Availability: Unix, Windows.
.. function:: utime(path, times)
Set the access and modified times of the file specified by *path*. If *times*
is ``None``, then the file's access and modified times are set to the current
time. (The effect is similar to running the Unix program :program:`touch` on
the path.) Otherwise, *times* must be a 2-tuple of numbers, of the form
``(atime, mtime)`` which is used to set the access and modified times,
respectively. Whether a directory can be given for *path* depends on whether
the operating system implements directories as files (for example, Windows
does not). Note that the exact times you set here may not be returned by a
subsequent :func:`~os.stat` call, depending on the resolution with which your
operating system records access and modification times; see :func:`~os.stat`.
.. versionchanged:: 2.0
Added support for ``None`` for *times*.
Availability: Unix, Windows.
.. function:: walk(top, topdown=True, onerror=None, followlinks=False)
.. index::
single: directory; walking
single: directory; traversal
Generate the file names in a directory tree by walking the tree
either top-down or bottom-up. For each directory in the tree rooted at directory
*top* (including *top* itself), it yields a 3-tuple ``(dirpath, dirnames,
filenames)``.
*dirpath* is a string, the path to the directory. *dirnames* is a list of the
names of the subdirectories in *dirpath* (excluding ``'.'`` and ``'..'``).
*filenames* is a list of the names of the non-directory files in *dirpath*.
Note that the names in the lists contain no path components. To get a full path
(which begins with *top*) to a file or directory in *dirpath*, do
``os.path.join(dirpath, name)``.
If optional argument *topdown* is ``True`` or not specified, the triple for a
directory is generated before the triples for any of its subdirectories
(directories are generated top-down). If *topdown* is ``False``, the triple
for a directory is generated after the triples for all of its subdirectories
(directories are generated bottom-up). No matter the value of *topdown*, the
list of subdirectories is retrieved before the tuples for the directory and
its subdirectories are generated.
When *topdown* is ``True``, the caller can modify the *dirnames* list in-place
(perhaps using :keyword:`del` or slice assignment), and :func:`walk` will only
recurse into the subdirectories whose names remain in *dirnames*; this can be
used to prune the search, impose a specific order of visiting, or even to inform
:func:`walk` about directories the caller creates or renames before it resumes
:func:`walk` again. Modifying *dirnames* when *topdown* is ``False`` has
no effect on the behavior of the walk, because in bottom-up mode the directories
in *dirnames* are generated before *dirpath* itself is generated.
By default, errors from the :func:`listdir` call are ignored. If optional
argument *onerror* is specified, it should be a function; it will be called with
one argument, an :exc:`OSError` instance. It can report the error to continue
with the walk, or raise the exception to abort the walk. Note that the filename
is available as the ``filename`` attribute of the exception object.
By default, :func:`walk` will not walk down into symbolic links that resolve to
directories. Set *followlinks* to ``True`` to visit directories pointed to by
symlinks, on systems that support them.
.. versionadded:: 2.6
The *followlinks* parameter.
.. note::
Be aware that setting *followlinks* to ``True`` can lead to infinite recursion if a
link points to a parent directory of itself. :func:`walk` does not keep track of
the directories it visited already.
.. note::
If you pass a relative pathname, don't change the current working directory
between resumptions of :func:`walk`. :func:`walk` never changes the current
directory, and assumes that its caller doesn't either.
This example displays the number of bytes taken by non-directory files in each
directory under the starting directory, except that it doesn't look under any
CVS subdirectory::
import os
from os.path import join, getsize
for root, dirs, files in os.walk('python/Lib/email'):
print root, "consumes",
print sum(getsize(join(root, name)) for name in files),
print "bytes in", len(files), "non-directory files"
if 'CVS' in dirs:
dirs.remove('CVS') # don't visit CVS directories
In the next example, walking the tree bottom-up is essential: :func:`rmdir`
doesn't allow deleting a directory before the directory is empty::
# Delete everything reachable from the directory named in "top",
# assuming there are no symbolic links.
# CAUTION: This is dangerous! For example, if top == '/', it
# could delete all your disk files.
import os
for root, dirs, files in os.walk(top, topdown=False):
for name in files:
os.remove(os.path.join(root, name))
for name in dirs:
os.rmdir(os.path.join(root, name))
.. versionadded:: 2.3
.. _os-process:
Process Management
------------------
These functions may be used to create and manage processes.
The various :func:`exec\* <execl>` functions take a list of arguments for the new
program loaded into the process. In each case, the first of these arguments is
passed to the new program as its own name rather than as an argument a user may
have typed on a command line. For the C programmer, this is the ``argv[0]``
passed to a program's :c:func:`main`. For example, ``os.execv('/bin/echo',
['foo', 'bar'])`` will only print ``bar`` on standard output; ``foo`` will seem
to be ignored.
.. function:: abort()
Generate a :const:`SIGABRT` signal to the current process. On Unix, the default
behavior is to produce a core dump; on Windows, the process immediately returns
an exit code of ``3``. Be aware that calling this function will not call the
Python signal handler registered for :const:`SIGABRT` with
:func:`signal.signal`.
Availability: Unix, Windows.
.. function:: execl(path, arg0, arg1, ...)
execle(path, arg0, arg1, ..., env)
execlp(file, arg0, arg1, ...)
execlpe(file, arg0, arg1, ..., env)
execv(path, args)
execve(path, args, env)
execvp(file, args)
execvpe(file, args, env)
These functions all execute a new program, replacing the current process; they
do not return. On Unix, the new executable is loaded into the current process,
and will have the same process id as the caller. Errors will be reported as
:exc:`OSError` exceptions.
The current process is replaced immediately. Open file objects and
descriptors are not flushed, so if there may be data buffered
on these open files, you should flush them using
:func:`sys.stdout.flush` or :func:`os.fsync` before calling an
:func:`exec\* <execl>` function.
The "l" and "v" variants of the :func:`exec\* <execl>` functions differ in how
command-line arguments are passed. The "l" variants are perhaps the easiest
to work with if the number of parameters is fixed when the code is written; the
individual parameters simply become additional parameters to the :func:`execl\*`
functions. The "v" variants are good when the number of parameters is
variable, with the arguments being passed in a list or tuple as the *args*
parameter. In either case, the arguments to the child process should start with
the name of the command being run, but this is not enforced.
The variants which include a "p" near the end (:func:`execlp`,
:func:`execlpe`, :func:`execvp`, and :func:`execvpe`) will use the
:envvar:`PATH` environment variable to locate the program *file*. When the
environment is being replaced (using one of the :func:`exec\*e <execl>` variants,
discussed in the next paragraph), the new environment is used as the source of
the :envvar:`PATH` variable. The other variants, :func:`execl`, :func:`execle`,
:func:`execv`, and :func:`execve`, will not use the :envvar:`PATH` variable to
locate the executable; *path* must contain an appropriate absolute or relative
path.
For :func:`execle`, :func:`execlpe`, :func:`execve`, and :func:`execvpe` (note
that these all end in "e"), the *env* parameter must be a mapping which is
used to define the environment variables for the new process (these are used
instead of the current process' environment); the functions :func:`execl`,
:func:`execlp`, :func:`execv`, and :func:`execvp` all cause the new process to
inherit the environment of the current process.
Availability: Unix, Windows.
.. function:: _exit(n)
Exit the process with status *n*, without calling cleanup handlers, flushing
stdio buffers, etc.
Availability: Unix, Windows.
.. note::
The standard way to exit is ``sys.exit(n)``. :func:`_exit` should
normally only be used in the child process after a :func:`fork`.
The following exit codes are defined and can be used with :func:`_exit`,
although they are not required. These are typically used for system programs
written in Python, such as a mail server's external command delivery program.
.. note::
Some of these may not be available on all Unix platforms, since there is some
variation. These constants are defined where they are defined by the underlying
platform.
.. data:: EX_OK
Exit code that means no error occurred.
Availability: Unix.
.. versionadded:: 2.3
.. data:: EX_USAGE
Exit code that means the command was used incorrectly, such as when the wrong
number of arguments are given.
Availability: Unix.
.. versionadded:: 2.3
.. data:: EX_DATAERR
Exit code that means the input data was incorrect.
Availability: Unix.
.. versionadded:: 2.3
.. data:: EX_NOINPUT
Exit code that means an input file did not exist or was not readable.
Availability: Unix.
.. versionadded:: 2.3
.. data:: EX_NOUSER
Exit code that means a specified user did not exist.
Availability: Unix.
.. versionadded:: 2.3
.. data:: EX_NOHOST
Exit code that means a specified host did not exist.
Availability: Unix.
.. versionadded:: 2.3
.. data:: EX_UNAVAILABLE
Exit code that means that a required service is unavailable.
Availability: Unix.
.. versionadded:: 2.3
.. data:: EX_SOFTWARE
Exit code that means an internal software error was detected.
Availability: Unix.
.. versionadded:: 2.3
.. data:: EX_OSERR
Exit code that means an operating system error was detected, such as the
inability to fork or create a pipe.
Availability: Unix.
.. versionadded:: 2.3
.. data:: EX_OSFILE
Exit code that means some system file did not exist, could not be opened, or had
some other kind of error.
Availability: Unix.
.. versionadded:: 2.3
.. data:: EX_CANTCREAT
Exit code that means a user specified output file could not be created.
Availability: Unix.
.. versionadded:: 2.3
.. data:: EX_IOERR
Exit code that means that an error occurred while doing I/O on some file.
Availability: Unix.
.. versionadded:: 2.3
.. data:: EX_TEMPFAIL
Exit code that means a temporary failure occurred. This indicates something
that may not really be an error, such as a network connection that couldn't be
made during a retryable operation.
Availability: Unix.
.. versionadded:: 2.3
.. data:: EX_PROTOCOL
Exit code that means that a protocol exchange was illegal, invalid, or not
understood.
Availability: Unix.
.. versionadded:: 2.3
.. data:: EX_NOPERM
Exit code that means that there were insufficient permissions to perform the
operation (but not intended for file system problems).
Availability: Unix.
.. versionadded:: 2.3
.. data:: EX_CONFIG
Exit code that means that some kind of configuration error occurred.
Availability: Unix.
.. versionadded:: 2.3
.. data:: EX_NOTFOUND
Exit code that means something like "an entry was not found".
Availability: Unix.
.. versionadded:: 2.3
.. function:: fork()
Fork a child process. Return ``0`` in the child and the child's process id in the
parent. If an error occurs :exc:`OSError` is raised.
Note that some platforms including FreeBSD <= 6.3, Cygwin and OS/2 EMX have
known issues when using fork() from a thread.
.. warning::
See :mod:`ssl` for applications that use the SSL module with fork().
Availability: Unix.
.. function:: forkpty()
Fork a child process, using a new pseudo-terminal as the child's controlling
terminal. Return a pair of ``(pid, fd)``, where *pid* is ``0`` in the child, the
new child's process id in the parent, and *fd* is the file descriptor of the
master end of the pseudo-terminal. For a more portable approach, use the
:mod:`pty` module. If an error occurs :exc:`OSError` is raised.
Availability: some flavors of Unix.
.. function:: kill(pid, sig)
.. index::
single: process; killing
single: process; signalling
Send signal *sig* to the process *pid*. Constants for the specific signals
available on the host platform are defined in the :mod:`signal` module.
Windows: The :data:`signal.CTRL_C_EVENT` and
:data:`signal.CTRL_BREAK_EVENT` signals are special signals which can
only be sent to console processes which share a common console window,
e.g., some subprocesses. Any other value for *sig* will cause the process
to be unconditionally killed by the TerminateProcess API, and the exit code
will be set to *sig*. The Windows version of :func:`kill` additionally takes
process handles to be killed.
.. versionadded:: 2.7 Windows support
.. function:: killpg(pgid, sig)
.. index::
single: process; killing
single: process; signalling
Send the signal *sig* to the process group *pgid*.
Availability: Unix.
.. versionadded:: 2.3
.. function:: nice(increment)
Add *increment* to the process's "niceness". Return the new niceness.
Availability: Unix.
.. function:: plock(op)
Lock program segments into memory. The value of *op* (defined in
``<sys/lock.h>``) determines which segments are locked.
Availability: Unix.
.. function:: popen(...)
popen2(...)
popen3(...)
popen4(...)
:noindex:
Run child processes, returning opened pipes for communications. These functions
are described in section :ref:`os-newstreams`.
.. function:: spawnl(mode, path, ...)
spawnle(mode, path, ..., env)
spawnlp(mode, file, ...)
spawnlpe(mode, file, ..., env)
spawnv(mode, path, args)
spawnve(mode, path, args, env)
spawnvp(mode, file, args)
spawnvpe(mode, file, args, env)
Execute the program *path* in a new process.
(Note that the :mod:`subprocess` module provides more powerful facilities for
spawning new processes and retrieving their results; using that module is
preferable to using these functions. Check especially the
:ref:`subprocess-replacements` section.)
If *mode* is :const:`P_NOWAIT`, this function returns the process id of the new
process; if *mode* is :const:`P_WAIT`, returns the process's exit code if it
exits normally, or ``-signal``, where *signal* is the signal that killed the
process. On Windows, the process id will actually be the process handle, so can
be used with the :func:`waitpid` function.
The "l" and "v" variants of the :func:`spawn\* <spawnl>` functions differ in how
command-line arguments are passed. The "l" variants are perhaps the easiest
to work with if the number of parameters is fixed when the code is written; the
individual parameters simply become additional parameters to the
:func:`spawnl\*` functions. The "v" variants are good when the number of
parameters is variable, with the arguments being passed in a list or tuple as
the *args* parameter. In either case, the arguments to the child process must
start with the name of the command being run.
The variants which include a second "p" near the end (:func:`spawnlp`,
:func:`spawnlpe`, :func:`spawnvp`, and :func:`spawnvpe`) will use the
:envvar:`PATH` environment variable to locate the program *file*. When the
environment is being replaced (using one of the :func:`spawn\*e <spawnl>` variants,
discussed in the next paragraph), the new environment is used as the source of
the :envvar:`PATH` variable. The other variants, :func:`spawnl`,
:func:`spawnle`, :func:`spawnv`, and :func:`spawnve`, will not use the
:envvar:`PATH` variable to locate the executable; *path* must contain an
appropriate absolute or relative path.
For :func:`spawnle`, :func:`spawnlpe`, :func:`spawnve`, and :func:`spawnvpe`
(note that these all end in "e"), the *env* parameter must be a mapping
which is used to define the environment variables for the new process (they are
used instead of the current process' environment); the functions
:func:`spawnl`, :func:`spawnlp`, :func:`spawnv`, and :func:`spawnvp` all cause
the new process to inherit the environment of the current process. Note that
keys and values in the *env* dictionary must be strings; invalid keys or
values will cause the function to fail, with a return value of ``127``.
As an example, the following calls to :func:`spawnlp` and :func:`spawnvpe` are
equivalent::
import os
os.spawnlp(os.P_WAIT, 'cp', 'cp', 'index.html', '/dev/null')
L = ['cp', 'index.html', '/dev/null']
os.spawnvpe(os.P_WAIT, 'cp', L, os.environ)
Availability: Unix, Windows. :func:`spawnlp`, :func:`spawnlpe`, :func:`spawnvp`
and :func:`spawnvpe` are not available on Windows. :func:`spawnle` and
:func:`spawnve` are not thread-safe on Windows; we advise you to use the
:mod:`subprocess` module instead.
.. versionadded:: 1.6
.. data:: P_NOWAIT
P_NOWAITO
Possible values for the *mode* parameter to the :func:`spawn\* <spawnl>` family of
functions. If either of these values is given, the :func:`spawn\*` functions
will return as soon as the new process has been created, with the process id as
the return value.
Availability: Unix, Windows.
.. versionadded:: 1.6
.. data:: P_WAIT
Possible value for the *mode* parameter to the :func:`spawn\* <spawnl>` family of
functions. If this is given as *mode*, the :func:`spawn\*` functions will not
return until the new process has run to completion and will return the exit code
of the process the run is successful, or ``-signal`` if a signal kills the
process.
Availability: Unix, Windows.
.. versionadded:: 1.6
.. data:: P_DETACH
P_OVERLAY
Possible values for the *mode* parameter to the :func:`spawn\* <spawnl>` family of
functions. These are less portable than those listed above. :const:`P_DETACH`
is similar to :const:`P_NOWAIT`, but the new process is detached from the
console of the calling process. If :const:`P_OVERLAY` is used, the current
process will be replaced; the :func:`spawn\*` function will not return.
Availability: Windows.
.. versionadded:: 1.6
.. function:: startfile(path[, operation])
Start a file with its associated application.
When *operation* is not specified or ``'open'``, this acts like double-clicking
the file in Windows Explorer, or giving the file name as an argument to the
:program:`start` command from the interactive command shell: the file is opened
with whatever application (if any) its extension is associated.
When another *operation* is given, it must be a "command verb" that specifies
what should be done with the file. Common verbs documented by Microsoft are
``'print'`` and ``'edit'`` (to be used on files) as well as ``'explore'`` and
``'find'`` (to be used on directories).
:func:`startfile` returns as soon as the associated application is launched.
There is no option to wait for the application to close, and no way to retrieve
the application's exit status. The *path* parameter is relative to the current
directory. If you want to use an absolute path, make sure the first character
is not a slash (``'/'``); the underlying Win32 :c:func:`ShellExecute` function
doesn't work if it is. Use the :func:`os.path.normpath` function to ensure that
the path is properly encoded for Win32.
Availability: Windows.
.. versionadded:: 2.0
.. versionadded:: 2.5
The *operation* parameter.
.. function:: system(command)
Execute the command (a string) in a subshell. This is implemented by calling
the Standard C function :c:func:`system`, and has the same limitations.
Changes to :data:`sys.stdin`, etc. are not reflected in the environment of the
executed command.
On Unix, the return value is the exit status of the process encoded in the
format specified for :func:`wait`. Note that POSIX does not specify the meaning
of the return value of the C :c:func:`system` function, so the return value of
the Python function is system-dependent.
On Windows, the return value is that returned by the system shell after running
*command*, given by the Windows environment variable :envvar:`COMSPEC`: on
:program:`command.com` systems (Windows 95, 98 and ME) this is always ``0``; on
:program:`cmd.exe` systems (Windows NT, 2000 and XP) this is the exit status of
the command run; on systems using a non-native shell, consult your shell
documentation.
The :mod:`subprocess` module provides more powerful facilities for spawning new
processes and retrieving their results; using that module is preferable to using
this function. See the
:ref:`subprocess-replacements` section in the :mod:`subprocess` documentation
for some helpful recipes.
Availability: Unix, Windows.
.. function:: times()
Return a 5-tuple of floating point numbers indicating accumulated (processor
or other) times, in seconds. The items are: user time, system time,
children's user time, children's system time, and elapsed real time since a
fixed point in the past, in that order. See the Unix manual page
:manpage:`times(2)` or the corresponding Windows Platform API documentation.
On Windows, only the first two items are filled, the others are zero.
Availability: Unix, Windows
.. function:: wait()
Wait for completion of a child process, and return a tuple containing its pid
and exit status indication: a 16-bit number, whose low byte is the signal number
that killed the process, and whose high byte is the exit status (if the signal
number is zero); the high bit of the low byte is set if a core file was
produced.
Availability: Unix.
.. function:: waitpid(pid, options)
The details of this function differ on Unix and Windows.
On Unix: Wait for completion of a child process given by process id *pid*, and
return a tuple containing its process id and exit status indication (encoded as
for :func:`wait`). The semantics of the call are affected by the value of the
integer *options*, which should be ``0`` for normal operation.
If *pid* is greater than ``0``, :func:`waitpid` requests status information for
that specific process. If *pid* is ``0``, the request is for the status of any
child in the process group of the current process. If *pid* is ``-1``, the
request pertains to any child of the current process. If *pid* is less than
``-1``, status is requested for any process in the process group ``-pid`` (the
absolute value of *pid*).
An :exc:`OSError` is raised with the value of errno when the syscall
returns -1.
On Windows: Wait for completion of a process given by process handle *pid*, and
return a tuple containing *pid*, and its exit status shifted left by 8 bits
(shifting makes cross-platform use of the function easier). A *pid* less than or
equal to ``0`` has no special meaning on Windows, and raises an exception. The
value of integer *options* has no effect. *pid* can refer to any process whose
id is known, not necessarily a child process. The :func:`spawn\* <spawnl>`
functions called with :const:`P_NOWAIT` return suitable process handles.
.. function:: wait3(options)
Similar to :func:`waitpid`, except no process id argument is given and a
3-element tuple containing the child's process id, exit status indication, and
resource usage information is returned. Refer to :mod:`resource`.\
:func:`~resource.getrusage` for details on resource usage information. The
option argument is the same as that provided to :func:`waitpid` and
:func:`wait4`.
Availability: Unix.
.. versionadded:: 2.5
.. function:: wait4(pid, options)
Similar to :func:`waitpid`, except a 3-element tuple, containing the child's
process id, exit status indication, and resource usage information is returned.
Refer to :mod:`resource`.\ :func:`~resource.getrusage` for details on
resource usage information. The arguments to :func:`wait4` are the same as
those provided to :func:`waitpid`.
Availability: Unix.
.. versionadded:: 2.5
.. data:: WNOHANG
The option for :func:`waitpid` to return immediately if no child process status
is available immediately. The function returns ``(0, 0)`` in this case.
Availability: Unix.
.. data:: WCONTINUED
This option causes child processes to be reported if they have been continued
from a job control stop since their status was last reported.
Availability: Some Unix systems.
.. versionadded:: 2.3
.. data:: WUNTRACED
This option causes child processes to be reported if they have been stopped but
their current state has not been reported since they were stopped.
Availability: Unix.
.. versionadded:: 2.3
The following functions take a process status code as returned by
:func:`system`, :func:`wait`, or :func:`waitpid` as a parameter. They may be
used to determine the disposition of a process.
.. function:: WCOREDUMP(status)
Return ``True`` if a core dump was generated for the process, otherwise
return ``False``.
Availability: Unix.
.. versionadded:: 2.3
.. function:: WIFCONTINUED(status)
Return ``True`` if the process has been continued from a job control stop,
otherwise return ``False``.
Availability: Unix.
.. versionadded:: 2.3
.. function:: WIFSTOPPED(status)
Return ``True`` if the process has been stopped, otherwise return
``False``.
Availability: Unix.
.. function:: WIFSIGNALED(status)
Return ``True`` if the process exited due to a signal, otherwise return
``False``.
Availability: Unix.
.. function:: WIFEXITED(status)
Return ``True`` if the process exited using the :manpage:`exit(2)` system call,
otherwise return ``False``.
Availability: Unix.
.. function:: WEXITSTATUS(status)
If ``WIFEXITED(status)`` is true, return the integer parameter to the
:manpage:`exit(2)` system call. Otherwise, the return value is meaningless.
Availability: Unix.
.. function:: WSTOPSIG(status)
Return the signal which caused the process to stop.
Availability: Unix.
.. function:: WTERMSIG(status)
Return the signal which caused the process to exit.
Availability: Unix.
.. _os-path:
Miscellaneous System Information
--------------------------------
.. function:: confstr(name)
Return string-valued system configuration values. *name* specifies the
configuration value to retrieve; it may be a string which is the name of a
defined system value; these names are specified in a number of standards (POSIX,
Unix 95, Unix 98, and others). Some platforms define additional names as well.
The names known to the host operating system are given as the keys of the
``confstr_names`` dictionary. For configuration variables not included in that
mapping, passing an integer for *name* is also accepted.
If the configuration value specified by *name* isn't defined, ``None`` is
returned.
If *name* is a string and is not known, :exc:`ValueError` is raised. If a
specific value for *name* is not supported by the host system, even if it is
included in ``confstr_names``, an :exc:`OSError` is raised with
:const:`errno.EINVAL` for the error number.
Availability: Unix
.. data:: confstr_names
Dictionary mapping names accepted by :func:`confstr` to the integer values
defined for those names by the host operating system. This can be used to
determine the set of names known to the system.
Availability: Unix.
.. function:: getloadavg()
Return the number of processes in the system run queue averaged over the last
1, 5, and 15 minutes or raises :exc:`OSError` if the load average was
unobtainable.
Availability: Unix.
.. versionadded:: 2.3
.. function:: sysconf(name)
Return integer-valued system configuration values. If the configuration value
specified by *name* isn't defined, ``-1`` is returned. The comments regarding
the *name* parameter for :func:`confstr` apply here as well; the dictionary that
provides information on the known names is given by ``sysconf_names``.
Availability: Unix.
.. data:: sysconf_names
Dictionary mapping names accepted by :func:`sysconf` to the integer values
defined for those names by the host operating system. This can be used to
determine the set of names known to the system.
Availability: Unix.
The following data values are used to support path manipulation operations. These
are defined for all platforms.
Higher-level operations on pathnames are defined in the :mod:`os.path` module.
.. data:: curdir
The constant string used by the operating system to refer to the current
directory. This is ``'.'`` for Windows and POSIX. Also available via
:mod:`os.path`.
.. data:: pardir
The constant string used by the operating system to refer to the parent
directory. This is ``'..'`` for Windows and POSIX. Also available via
:mod:`os.path`.
.. data:: sep
The character used by the operating system to separate pathname components.
This is ``'/'`` for POSIX and ``'\\'`` for Windows. Note that knowing this
is not sufficient to be able to parse or concatenate pathnames --- use
:func:`os.path.split` and :func:`os.path.join` --- but it is occasionally
useful. Also available via :mod:`os.path`.
.. data:: altsep
An alternative character used by the operating system to separate pathname
components, or ``None`` if only one separator character exists. This is set to
``'/'`` on Windows systems where ``sep`` is a backslash. Also available via
:mod:`os.path`.
.. data:: extsep
The character which separates the base filename from the extension; for example,
the ``'.'`` in :file:`os.py`. Also available via :mod:`os.path`.
.. versionadded:: 2.2
.. data:: pathsep
The character conventionally used by the operating system to separate search
path components (as in :envvar:`PATH`), such as ``':'`` for POSIX or ``';'`` for
Windows. Also available via :mod:`os.path`.
.. data:: defpath
The default search path used by :func:`exec\*p\* <execl>` and
:func:`spawn\*p\* <spawnl>` if the environment doesn't have a ``'PATH'``
key. Also available via :mod:`os.path`.
.. data:: linesep
The string used to separate (or, rather, terminate) lines on the current
platform. This may be a single character, such as ``'\n'`` for POSIX, or
multiple characters, for example, ``'\r\n'`` for Windows. Do not use
*os.linesep* as a line terminator when writing files opened in text mode (the
default); use a single ``'\n'`` instead, on all platforms.
.. data:: devnull
The file path of the null device. For example: ``'/dev/null'`` for
POSIX, ``'nul'`` for Windows. Also available via :mod:`os.path`.
.. versionadded:: 2.4
.. _os-miscfunc:
Miscellaneous Functions
-----------------------
.. function:: urandom(n)
Return a string of *n* random bytes suitable for cryptographic use.
This function returns random bytes from an OS-specific randomness source. The
returned data should be unpredictable enough for cryptographic applications,
though its exact quality depends on the OS implementation. On a UNIX-like
system this will query ``/dev/urandom``, and on Windows it will use
``CryptGenRandom()``. If a randomness source is not found,
:exc:`NotImplementedError` will be raised.
For an easy-to-use interface to the random number generator
provided by your platform, please see :class:`random.SystemRandom`.
.. versionadded:: 2.4
PK %�\@U.ޝC �C ) html/_sources/library/ossaudiodev.rst.txtnu �[���
:mod:`ossaudiodev` --- Access to OSS-compatible audio devices
=============================================================
.. module:: ossaudiodev
:platform: Linux, FreeBSD
:synopsis: Access to OSS-compatible audio devices.
.. versionadded:: 2.3
This module allows you to access the OSS (Open Sound System) audio interface.
OSS is available for a wide range of open-source and commercial Unices, and is
the standard audio interface for Linux and recent versions of FreeBSD.
.. Things will get more complicated for future Linux versions, since
ALSA is in the standard kernel as of 2.5.x. Presumably if you
use ALSA, you'll have to make sure its OSS compatibility layer
is active to use ossaudiodev, but you're gonna need it for the vast
majority of Linux audio apps anyway.
Sounds like things are also complicated for other BSDs. In response
to my python-dev query, Thomas Wouters said:
> Likewise, googling shows OpenBSD also uses OSS/Free -- the commercial
> OSS installation manual tells you to remove references to OSS/Free from the
> kernel :)
but Aleksander Piotrowsk actually has an OpenBSD box, and he quotes
from its <soundcard.h>:
> * WARNING! WARNING!
> * This is an OSS (Linux) audio emulator.
> * Use the Native NetBSD API for developing new code, and this
> * only for compiling Linux programs.
There's also an ossaudio manpage on OpenBSD that explains things
further. Presumably NetBSD and OpenBSD have a different standard
audio interface. That's the great thing about standards, there are so
many to choose from ... ;-)
This probably all warrants a footnote or two, but I don't understand
things well enough right now to write it! --GPW
.. seealso::
`Open Sound System Programmer's Guide <http://www.opensound.com/pguide/oss.pdf>`_
the official documentation for the OSS C API
The module defines a large number of constants supplied by the OSS device
driver; see ``<sys/soundcard.h>`` on either Linux or FreeBSD for a listing.
:mod:`ossaudiodev` defines the following variables and functions:
.. exception:: OSSAudioError
This exception is raised on certain errors. The argument is a string describing
what went wrong.
(If :mod:`ossaudiodev` receives an error from a system call such as
:c:func:`open`, :c:func:`write`, or :c:func:`ioctl`, it raises :exc:`IOError`.
Errors detected directly by :mod:`ossaudiodev` result in :exc:`OSSAudioError`.)
(For backwards compatibility, the exception class is also available as
``ossaudiodev.error``.)
.. function:: open(mode)
open(device, mode)
Open an audio device and return an OSS audio device object. This object
supports many file-like methods, such as :meth:`read`, :meth:`write`, and
:meth:`fileno` (although there are subtle differences between conventional Unix
read/write semantics and those of OSS audio devices). It also supports a number
of audio-specific methods; see below for the complete list of methods.
*device* is the audio device filename to use. If it is not specified, this
module first looks in the environment variable :envvar:`AUDIODEV` for a device
to use. If not found, it falls back to :file:`/dev/dsp`.
*mode* is one of ``'r'`` for read-only (record) access, ``'w'`` for
write-only (playback) access and ``'rw'`` for both. Since many sound cards
only allow one process to have the recorder or player open at a time, it is a
good idea to open the device only for the activity needed. Further, some
sound cards are half-duplex: they can be opened for reading or writing, but
not both at once.
Note the unusual calling syntax: the *first* argument is optional, and the
second is required. This is a historical artifact for compatibility with the
older :mod:`linuxaudiodev` module which :mod:`ossaudiodev` supersedes.
.. XXX it might also be motivated
by my unfounded-but-still-possibly-true belief that the default
audio device varies unpredictably across operating systems. -GW
.. function:: openmixer([device])
Open a mixer device and return an OSS mixer device object. *device* is the
mixer device filename to use. If it is not specified, this module first looks
in the environment variable :envvar:`MIXERDEV` for a device to use. If not
found, it falls back to :file:`/dev/mixer`.
.. _ossaudio-device-objects:
Audio Device Objects
--------------------
Before you can write to or read from an audio device, you must call three
methods in the correct order:
#. :meth:`setfmt` to set the output format
#. :meth:`channels` to set the number of channels
#. :meth:`speed` to set the sample rate
Alternately, you can use the :meth:`setparameters` method to set all three audio
parameters at once. This is more convenient, but may not be as flexible in all
cases.
The audio device objects returned by :func:`.open` define the following methods
and (read-only) attributes:
.. method:: oss_audio_device.close()
Explicitly close the audio device. When you are done writing to or reading from
an audio device, you should explicitly close it. A closed device cannot be used
again.
.. method:: oss_audio_device.fileno()
Return the file descriptor associated with the device.
.. method:: oss_audio_device.read(size)
Read *size* bytes from the audio input and return them as a Python string.
Unlike most Unix device drivers, OSS audio devices in blocking mode (the
default) will block :func:`read` until the entire requested amount of data is
available.
.. method:: oss_audio_device.write(data)
Write the Python string *data* to the audio device and return the number of
bytes written. If the audio device is in blocking mode (the default), the
entire string is always written (again, this is different from usual Unix device
semantics). If the device is in non-blocking mode, some data may not be written
---see :meth:`writeall`.
.. method:: oss_audio_device.writeall(data)
Write the entire Python string *data* to the audio device: waits until the audio
device is able to accept data, writes as much data as it will accept, and
repeats until *data* has been completely written. If the device is in blocking
mode (the default), this has the same effect as :meth:`write`; :meth:`writeall`
is only useful in non-blocking mode. Has no return value, since the amount of
data written is always equal to the amount of data supplied.
The following methods each map to exactly one :c:func:`ioctl` system call. The
correspondence is obvious: for example, :meth:`setfmt` corresponds to the
``SNDCTL_DSP_SETFMT`` ioctl, and :meth:`sync` to ``SNDCTL_DSP_SYNC`` (this can
be useful when consulting the OSS documentation). If the underlying
:c:func:`ioctl` fails, they all raise :exc:`IOError`.
.. method:: oss_audio_device.nonblock()
Put the device into non-blocking mode. Once in non-blocking mode, there is no
way to return it to blocking mode.
.. method:: oss_audio_device.getfmts()
Return a bitmask of the audio output formats supported by the soundcard. Some
of the formats supported by OSS are:
+-------------------------+---------------------------------------------+
| Format | Description |
+=========================+=============================================+
| :const:`AFMT_MU_LAW` | a logarithmic encoding (used by Sun ``.au`` |
| | files and :file:`/dev/audio`) |
+-------------------------+---------------------------------------------+
| :const:`AFMT_A_LAW` | a logarithmic encoding |
+-------------------------+---------------------------------------------+
| :const:`AFMT_IMA_ADPCM` | a 4:1 compressed format defined by the |
| | Interactive Multimedia Association |
+-------------------------+---------------------------------------------+
| :const:`AFMT_U8` | Unsigned, 8-bit audio |
+-------------------------+---------------------------------------------+
| :const:`AFMT_S16_LE` | Signed, 16-bit audio, little-endian byte |
| | order (as used by Intel processors) |
+-------------------------+---------------------------------------------+
| :const:`AFMT_S16_BE` | Signed, 16-bit audio, big-endian byte order |
| | (as used by 68k, PowerPC, Sparc) |
+-------------------------+---------------------------------------------+
| :const:`AFMT_S8` | Signed, 8 bit audio |
+-------------------------+---------------------------------------------+
| :const:`AFMT_U16_LE` | Unsigned, 16-bit little-endian audio |
+-------------------------+---------------------------------------------+
| :const:`AFMT_U16_BE` | Unsigned, 16-bit big-endian audio |
+-------------------------+---------------------------------------------+
Consult the OSS documentation for a full list of audio formats, and note that
most devices support only a subset of these formats. Some older devices only
support :const:`AFMT_U8`; the most common format used today is
:const:`AFMT_S16_LE`.
.. method:: oss_audio_device.setfmt(format)
Try to set the current audio format to *format*---see :meth:`getfmts` for a
list. Returns the audio format that the device was set to, which may not be the
requested format. May also be used to return the current audio format---do this
by passing an "audio format" of :const:`AFMT_QUERY`.
.. method:: oss_audio_device.channels(nchannels)
Set the number of output channels to *nchannels*. A value of 1 indicates
monophonic sound, 2 stereophonic. Some devices may have more than 2 channels,
and some high-end devices may not support mono. Returns the number of channels
the device was set to.
.. method:: oss_audio_device.speed(samplerate)
Try to set the audio sampling rate to *samplerate* samples per second. Returns
the rate actually set. Most sound devices don't support arbitrary sampling
rates. Common rates are:
+-------+-------------------------------------------+
| Rate | Description |
+=======+===========================================+
| 8000 | default rate for :file:`/dev/audio` |
+-------+-------------------------------------------+
| 11025 | speech recording |
+-------+-------------------------------------------+
| 22050 | |
+-------+-------------------------------------------+
| 44100 | CD quality audio (at 16 bits/sample and 2 |
| | channels) |
+-------+-------------------------------------------+
| 96000 | DVD quality audio (at 24 bits/sample) |
+-------+-------------------------------------------+
.. method:: oss_audio_device.sync()
Wait until the sound device has played every byte in its buffer. (This happens
implicitly when the device is closed.) The OSS documentation recommends closing
and re-opening the device rather than using :meth:`sync`.
.. method:: oss_audio_device.reset()
Immediately stop playing or recording and return the device to a state where it
can accept commands. The OSS documentation recommends closing and re-opening
the device after calling :meth:`reset`.
.. method:: oss_audio_device.post()
Tell the driver that there is likely to be a pause in the output, making it
possible for the device to handle the pause more intelligently. You might use
this after playing a spot sound effect, before waiting for user input, or before
doing disk I/O.
The following convenience methods combine several ioctls, or one ioctl and some
simple calculations.
.. method:: oss_audio_device.setparameters(format, nchannels, samplerate[, strict=False])
Set the key audio sampling parameters---sample format, number of channels, and
sampling rate---in one method call. *format*, *nchannels*, and *samplerate*
should be as specified in the :meth:`setfmt`, :meth:`channels`, and
:meth:`speed` methods. If *strict* is true, :meth:`setparameters` checks to
see if each parameter was actually set to the requested value, and raises
:exc:`OSSAudioError` if not. Returns a tuple (*format*, *nchannels*,
*samplerate*) indicating the parameter values that were actually set by the
device driver (i.e., the same as the return values of :meth:`setfmt`,
:meth:`channels`, and :meth:`speed`).
For example, ::
(fmt, channels, rate) = dsp.setparameters(fmt, channels, rate)
is equivalent to ::
fmt = dsp.setfmt(fmt)
channels = dsp.channels(channels)
rate = dsp.rate(rate)
.. method:: oss_audio_device.bufsize()
Returns the size of the hardware buffer, in samples.
.. method:: oss_audio_device.obufcount()
Returns the number of samples that are in the hardware buffer yet to be played.
.. method:: oss_audio_device.obuffree()
Returns the number of samples that could be queued into the hardware buffer to
be played without blocking.
Audio device objects also support several read-only attributes:
.. attribute:: oss_audio_device.closed
Boolean indicating whether the device has been closed.
.. attribute:: oss_audio_device.name
String containing the name of the device file.
.. attribute:: oss_audio_device.mode
The I/O mode for the file, either ``"r"``, ``"rw"``, or ``"w"``.
.. _mixer-device-objects:
Mixer Device Objects
--------------------
The mixer object provides two file-like methods:
.. method:: oss_mixer_device.close()
This method closes the open mixer device file. Any further attempts to use the
mixer after this file is closed will raise an :exc:`IOError`.
.. method:: oss_mixer_device.fileno()
Returns the file handle number of the open mixer device file.
The remaining methods are specific to audio mixing:
.. method:: oss_mixer_device.controls()
This method returns a bitmask specifying the available mixer controls ("Control"
being a specific mixable "channel", such as :const:`SOUND_MIXER_PCM` or
:const:`SOUND_MIXER_SYNTH`). This bitmask indicates a subset of all available
mixer controls---the :const:`SOUND_MIXER_\*` constants defined at module level.
To determine if, for example, the current mixer object supports a PCM mixer, use
the following Python code::
mixer=ossaudiodev.openmixer()
if mixer.controls() & (1 << ossaudiodev.SOUND_MIXER_PCM):
# PCM is supported
... code ...
For most purposes, the :const:`SOUND_MIXER_VOLUME` (master volume) and
:const:`SOUND_MIXER_PCM` controls should suffice---but code that uses the mixer
should be flexible when it comes to choosing mixer controls. On the Gravis
Ultrasound, for example, :const:`SOUND_MIXER_VOLUME` does not exist.
.. method:: oss_mixer_device.stereocontrols()
Returns a bitmask indicating stereo mixer controls. If a bit is set, the
corresponding control is stereo; if it is unset, the control is either
monophonic or not supported by the mixer (use in combination with
:meth:`controls` to determine which).
See the code example for the :meth:`controls` function for an example of getting
data from a bitmask.
.. method:: oss_mixer_device.reccontrols()
Returns a bitmask specifying the mixer controls that may be used to record. See
the code example for :meth:`controls` for an example of reading from a bitmask.
.. method:: oss_mixer_device.get(control)
Returns the volume of a given mixer control. The returned volume is a 2-tuple
``(left_volume,right_volume)``. Volumes are specified as numbers from 0
(silent) to 100 (full volume). If the control is monophonic, a 2-tuple is still
returned, but both volumes are the same.
Raises :exc:`OSSAudioError` if an invalid control was is specified, or
:exc:`IOError` if an unsupported control is specified.
.. method:: oss_mixer_device.set(control, (left, right))
Sets the volume for a given mixer control to ``(left,right)``. ``left`` and
``right`` must be ints and between 0 (silent) and 100 (full volume). On
success, the new volume is returned as a 2-tuple. Note that this may not be
exactly the same as the volume specified, because of the limited resolution of
some soundcard's mixers.
Raises :exc:`OSSAudioError` if an invalid mixer control was specified, or if the
specified volumes were out-of-range.
.. method:: oss_mixer_device.get_recsrc()
This method returns a bitmask indicating which control(s) are currently being
used as a recording source.
.. method:: oss_mixer_device.set_recsrc(bitmask)
Call this function to specify a recording source. Returns a bitmask indicating
the new recording source (or sources) if successful; raises :exc:`IOError` if an
invalid source was specified. To set the current recording source to the
microphone input::
mixer.setrecsrc (1 << ossaudiodev.SOUND_MIXER_MIC)
PK %�\ʙ*y�
�
& html/_sources/library/othergui.rst.txtnu �[��� .. _other-gui-packages:
Other Graphical User Interface Packages
=======================================
Major cross-platform (Windows, Mac OS X, Unix-like) GUI toolkits are
available for Python:
.. seealso::
`PyGTK <http://www.pygtk.org/>`_
is a set of bindings for the `GTK <http://www.gtk.org/>`_ widget set. It
provides an object oriented interface that is slightly higher level than
the C one. It comes with many more widgets than Tkinter provides, and has
good Python-specific reference documentation. There are also bindings to
`GNOME <https://www.gnome.org/>`_. An online `tutorial
<http://www.pygtk.org/pygtk2tutorial/index.html>`_ is available.
`PyQt <https://riverbankcomputing.com/software/pyqt/intro>`_
PyQt is a :program:`sip`\ -wrapped binding to the Qt toolkit. Qt is an
extensive C++ GUI application development framework that is
available for Unix, Windows and Mac OS X. :program:`sip` is a tool
for generating bindings for C++ libraries as Python classes, and
is specifically designed for Python. The *PyQt3* bindings have a
book, `GUI Programming with Python: QT Edition
<https://www.commandprompt.com/community/pyqt/>`_ by Boudewijn
Rempt. The *PyQt4* bindings also have a book, `Rapid GUI Programming
with Python and Qt <https://www.qtrac.eu/pyqtbook.html>`_, by Mark
Summerfield.
`wxPython <http://www.wxpython.org>`_
wxPython is a cross-platform GUI toolkit for Python that is built around
the popular `wxWidgets <https://www.wxwidgets.org/>`_ (formerly wxWindows)
C++ toolkit. It provides a native look and feel for applications on
Windows, Mac OS X, and Unix systems by using each platform's native
widgets where ever possible, (GTK+ on Unix-like systems). In addition to
an extensive set of widgets, wxPython provides classes for online
documentation and context sensitive help, printing, HTML viewing,
low-level device context drawing, drag and drop, system clipboard access,
an XML-based resource format and more, including an ever growing library
of user-contributed modules. wxPython has a book, `wxPython in Action
<https://www.manning.com/books/wxpython-in-action>`_, by Noel Rappin and
Robin Dunn.
PyGTK, PyQt, and wxPython, all have a modern look and feel and more
widgets than Tkinter. In addition, there are many other GUI toolkits for
Python, both cross-platform, and platform-specific. See the `GUI Programming
<https://wiki.python.org/moin/GuiProgramming>`_ page in the Python Wiki for a
much more complete list, and also for links to documents where the
different GUI toolkits are compared.
PK %�\N@�< < $ html/_sources/library/parser.rst.txtnu �[���
:mod:`parser` --- Access Python parse trees
===========================================
.. module:: parser
:synopsis: Access parse trees for Python source code.
.. moduleauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
.. Copyright 1995 Virginia Polytechnic Institute and State University and Fred
L. Drake, Jr. This copyright notice must be distributed on all copies, but
this document otherwise may be distributed as part of the Python
distribution. No fee may be charged for this document in any representation,
either on paper or electronically. This restriction does not affect other
elements in a distributed package in any way.
.. index:: single: parsing; Python source code
The :mod:`parser` module provides an interface to Python's internal parser and
byte-code compiler. The primary purpose for this interface is to allow Python
code to edit the parse tree of a Python expression and create executable code
from this. This is better than trying to parse and modify an arbitrary Python
code fragment as a string because parsing is performed in a manner identical to
the code forming the application. It is also faster.
.. note::
From Python 2.5 onward, it's much more convenient to cut in at the Abstract
Syntax Tree (AST) generation and compilation stage, using the :mod:`ast`
module.
The :mod:`parser` module exports the names documented here also with "st"
replaced by "ast"; this is a legacy from the time when there was no other
AST and has nothing to do with the AST found in Python 2.5. This is also the
reason for the functions' keyword arguments being called *ast*, not *st*.
The "ast" functions have been removed in Python 3.
There are a few things to note about this module which are important to making
use of the data structures created. This is not a tutorial on editing the parse
trees for Python code, but some examples of using the :mod:`parser` module are
presented.
Most importantly, a good understanding of the Python grammar processed by the
internal parser is required. For full information on the language syntax, refer
to :ref:`reference-index`. The parser
itself is created from a grammar specification defined in the file
:file:`Grammar/Grammar` in the standard Python distribution. The parse trees
stored in the ST objects created by this module are the actual output from the
internal parser when created by the :func:`expr` or :func:`suite` functions,
described below. The ST objects created by :func:`sequence2st` faithfully
simulate those structures. Be aware that the values of the sequences which are
considered "correct" will vary from one version of Python to another as the
formal grammar for the language is revised. However, transporting code from one
Python version to another as source text will always allow correct parse trees
to be created in the target version, with the only restriction being that
migrating to an older version of the interpreter will not support more recent
language constructs. The parse trees are not typically compatible from one
version to another, whereas source code has always been forward-compatible.
Each element of the sequences returned by :func:`st2list` or :func:`st2tuple`
has a simple form. Sequences representing non-terminal elements in the grammar
always have a length greater than one. The first element is an integer which
identifies a production in the grammar. These integers are given symbolic names
in the C header file :file:`Include/graminit.h` and the Python module
:mod:`symbol`. Each additional element of the sequence represents a component
of the production as recognized in the input string: these are always sequences
which have the same form as the parent. An important aspect of this structure
which should be noted is that keywords used to identify the parent node type,
such as the keyword :keyword:`if` in an :const:`if_stmt`, are included in the
node tree without any special treatment. For example, the :keyword:`if` keyword
is represented by the tuple ``(1, 'if')``, where ``1`` is the numeric value
associated with all :const:`NAME` tokens, including variable and function names
defined by the user. In an alternate form returned when line number information
is requested, the same token might be represented as ``(1, 'if', 12)``, where
the ``12`` represents the line number at which the terminal symbol was found.
Terminal elements are represented in much the same way, but without any child
elements and the addition of the source text which was identified. The example
of the :keyword:`if` keyword above is representative. The various types of
terminal symbols are defined in the C header file :file:`Include/token.h` and
the Python module :mod:`token`.
The ST objects are not required to support the functionality of this module,
but are provided for three purposes: to allow an application to amortize the
cost of processing complex parse trees, to provide a parse tree representation
which conserves memory space when compared to the Python list or tuple
representation, and to ease the creation of additional modules in C which
manipulate parse trees. A simple "wrapper" class may be created in Python to
hide the use of ST objects.
The :mod:`parser` module defines functions for a few distinct purposes. The
most important purposes are to create ST objects and to convert ST objects to
other representations such as parse trees and compiled code objects, but there
are also functions which serve to query the type of parse tree represented by an
ST object.
.. seealso::
Module :mod:`symbol`
Useful constants representing internal nodes of the parse tree.
Module :mod:`token`
Useful constants representing leaf nodes of the parse tree and functions for
testing node values.
.. _creating-sts:
Creating ST Objects
-------------------
ST objects may be created from source code or from a parse tree. When creating
an ST object from source, different functions are used to create the ``'eval'``
and ``'exec'`` forms.
.. function:: expr(source)
The :func:`expr` function parses the parameter *source* as if it were an input
to ``compile(source, 'file.py', 'eval')``. If the parse succeeds, an ST object
is created to hold the internal parse tree representation, otherwise an
appropriate exception is raised.
.. function:: suite(source)
The :func:`suite` function parses the parameter *source* as if it were an input
to ``compile(source, 'file.py', 'exec')``. If the parse succeeds, an ST object
is created to hold the internal parse tree representation, otherwise an
appropriate exception is raised.
.. function:: sequence2st(sequence)
This function accepts a parse tree represented as a sequence and builds an
internal representation if possible. If it can validate that the tree conforms
to the Python grammar and all nodes are valid node types in the host version of
Python, an ST object is created from the internal representation and returned
to the called. If there is a problem creating the internal representation, or
if the tree cannot be validated, a :exc:`ParserError` exception is raised. An
ST object created this way should not be assumed to compile correctly; normal
exceptions raised by compilation may still be initiated when the ST object is
passed to :func:`compilest`. This may indicate problems not related to syntax
(such as a :exc:`MemoryError` exception), but may also be due to constructs such
as the result of parsing ``del f(0)``, which escapes the Python parser but is
checked by the bytecode compiler.
Sequences representing terminal tokens may be represented as either two-element
lists of the form ``(1, 'name')`` or as three-element lists of the form ``(1,
'name', 56)``. If the third element is present, it is assumed to be a valid
line number. The line number may be specified for any subset of the terminal
symbols in the input tree.
.. function:: tuple2st(sequence)
This is the same function as :func:`sequence2st`. This entry point is
maintained for backward compatibility.
.. _converting-sts:
Converting ST Objects
---------------------
ST objects, regardless of the input used to create them, may be converted to
parse trees represented as list- or tuple- trees, or may be compiled into
executable code objects. Parse trees may be extracted with or without line
numbering information.
.. function:: st2list(ast[, line_info])
This function accepts an ST object from the caller in *ast* and returns a
Python list representing the equivalent parse tree. The resulting list
representation can be used for inspection or the creation of a new parse tree in
list form. This function does not fail so long as memory is available to build
the list representation. If the parse tree will only be used for inspection,
:func:`st2tuple` should be used instead to reduce memory consumption and
fragmentation. When the list representation is required, this function is
significantly faster than retrieving a tuple representation and converting that
to nested lists.
If *line_info* is true, line number information will be included for all
terminal tokens as a third element of the list representing the token. Note
that the line number provided specifies the line on which the token *ends*.
This information is omitted if the flag is false or omitted.
.. function:: st2tuple(ast[, line_info])
This function accepts an ST object from the caller in *ast* and returns a
Python tuple representing the equivalent parse tree. Other than returning a
tuple instead of a list, this function is identical to :func:`st2list`.
If *line_info* is true, line number information will be included for all
terminal tokens as a third element of the list representing the token. This
information is omitted if the flag is false or omitted.
.. function:: compilest(ast, filename='<syntax-tree>')
.. index:: builtin: eval
The Python byte compiler can be invoked on an ST object to produce code objects
which can be used as part of an :keyword:`exec` statement or a call to the
built-in :func:`eval` function. This function provides the interface to the
compiler, passing the internal parse tree from *ast* to the parser, using the
source file name specified by the *filename* parameter. The default value
supplied for *filename* indicates that the source was an ST object.
Compiling an ST object may result in exceptions related to compilation; an
example would be a :exc:`SyntaxError` caused by the parse tree for ``del f(0)``:
this statement is considered legal within the formal grammar for Python but is
not a legal language construct. The :exc:`SyntaxError` raised for this
condition is actually generated by the Python byte-compiler normally, which is
why it can be raised at this point by the :mod:`parser` module. Most causes of
compilation failure can be diagnosed programmatically by inspection of the parse
tree.
.. _querying-sts:
Queries on ST Objects
---------------------
Two functions are provided which allow an application to determine if an ST was
created as an expression or a suite. Neither of these functions can be used to
determine if an ST was created from source code via :func:`expr` or
:func:`suite` or from a parse tree via :func:`sequence2st`.
.. function:: isexpr(ast)
.. index:: builtin: compile
When *ast* represents an ``'eval'`` form, this function returns true, otherwise
it returns false. This is useful, since code objects normally cannot be queried
for this information using existing built-in functions. Note that the code
objects created by :func:`compilest` cannot be queried like this either, and
are identical to those created by the built-in :func:`compile` function.
.. function:: issuite(ast)
This function mirrors :func:`isexpr` in that it reports whether an ST object
represents an ``'exec'`` form, commonly known as a "suite." It is not safe to
assume that this function is equivalent to ``not isexpr(ast)``, as additional
syntactic fragments may be supported in the future.
.. _st-errors:
Exceptions and Error Handling
-----------------------------
The parser module defines a single exception, but may also pass other built-in
exceptions from other portions of the Python runtime environment. See each
function for information about the exceptions it can raise.
.. exception:: ParserError
Exception raised when a failure occurs within the parser module. This is
generally produced for validation failures rather than the built-in
:exc:`SyntaxError` raised during normal parsing. The exception argument is
either a string describing the reason of the failure or a tuple containing a
sequence causing the failure from a parse tree passed to :func:`sequence2st`
and an explanatory string. Calls to :func:`sequence2st` need to be able to
handle either type of exception, while calls to other functions in the module
will only need to be aware of the simple string values.
Note that the functions :func:`compilest`, :func:`expr`, and :func:`suite` may
raise exceptions which are normally raised by the parsing and compilation
process. These include the built in exceptions :exc:`MemoryError`,
:exc:`OverflowError`, :exc:`SyntaxError`, and :exc:`SystemError`. In these
cases, these exceptions carry all the meaning normally associated with them.
Refer to the descriptions of each function for detailed information.
.. _st-objects:
ST Objects
----------
Ordered and equality comparisons are supported between ST objects. Pickling of
ST objects (using the :mod:`pickle` module) is also supported.
.. data:: STType
The type of the objects returned by :func:`expr`, :func:`suite` and
:func:`sequence2st`.
ST objects have the following methods:
.. method:: ST.compile([filename])
Same as ``compilest(st, filename)``.
.. method:: ST.isexpr()
Same as ``isexpr(st)``.
.. method:: ST.issuite()
Same as ``issuite(st)``.
.. method:: ST.tolist([line_info])
Same as ``st2list(st, line_info)``.
.. method:: ST.totuple([line_info])
Same as ``st2tuple(st, line_info)``.
Example: Emulation of :func:`compile`
-------------------------------------
While many useful operations may take place between parsing and bytecode
generation, the simplest operation is to do nothing. For this purpose, using
the :mod:`parser` module to produce an intermediate data structure is equivalent
to the code ::
>>> code = compile('a + 5', 'file.py', 'eval')
>>> a = 5
>>> eval(code)
10
The equivalent operation using the :mod:`parser` module is somewhat longer, and
allows the intermediate internal parse tree to be retained as an ST object::
>>> import parser
>>> st = parser.expr('a + 5')
>>> code = st.compile('file.py')
>>> a = 5
>>> eval(code)
10
An application which needs both ST and code objects can package this code into
readily available functions::
import parser
def load_suite(source_string):
st = parser.suite(source_string)
return st, st.compile()
def load_expression(source_string):
st = parser.expr(source_string)
return st, st.compile()
PK %�\��> �> ! html/_sources/library/pdb.rst.txtnu �[��� .. _debugger:
:mod:`pdb` --- The Python Debugger
==================================
.. module:: pdb
:synopsis: The Python debugger for interactive interpreters.
**Source code:** :source:`Lib/pdb.py`
--------------
.. index:: single: debugging
The module :mod:`pdb` defines an interactive source code debugger for Python
programs. It supports setting (conditional) breakpoints and single stepping at
the source line level, inspection of stack frames, source code listing, and
evaluation of arbitrary Python code in the context of any stack frame. It also
supports post-mortem debugging and can be called under program control.
.. index::
single: Pdb (class in pdb)
module: bdb
module: cmd
The debugger is extensible --- it is actually defined as the class :class:`Pdb`.
This is currently undocumented but easily understood by reading the source. The
extension interface uses the modules :mod:`bdb` and :mod:`cmd`.
The debugger's prompt is ``(Pdb)``. Typical usage to run a program under control
of the debugger is::
>>> import pdb
>>> import mymodule
>>> pdb.run('mymodule.test()')
> <string>(0)?()
(Pdb) continue
> <string>(1)?()
(Pdb) continue
NameError: 'spam'
> <string>(1)?()
(Pdb)
:file:`pdb.py` can also be invoked as a script to debug other scripts. For
example::
python -m pdb myscript.py
When invoked as a script, pdb will automatically enter post-mortem debugging if
the program being debugged exits abnormally. After post-mortem debugging (or
after normal exit of the program), pdb will restart the program. Automatic
restarting preserves pdb's state (such as breakpoints) and in most cases is more
useful than quitting the debugger upon program's exit.
.. versionadded:: 2.4
Restarting post-mortem behavior added.
The typical usage to break into the debugger from a running program is to
insert ::
import pdb; pdb.set_trace()
at the location you want to break into the debugger. You can then step through
the code following this statement, and continue running without the debugger using
the ``c`` command.
The typical usage to inspect a crashed program is::
>>> import pdb
>>> import mymodule
>>> mymodule.test()
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "./mymodule.py", line 4, in test
test2()
File "./mymodule.py", line 3, in test2
print spam
NameError: spam
>>> pdb.pm()
> ./mymodule.py(3)test2()
-> print spam
(Pdb)
The module defines the following functions; each enters the debugger in a
slightly different way:
.. function:: run(statement[, globals[, locals]])
Execute the *statement* (given as a string) under debugger control. The
debugger prompt appears before any code is executed; you can set breakpoints and
type ``continue``, or you can step through the statement using ``step`` or
``next`` (all these commands are explained below). The optional *globals* and
*locals* arguments specify the environment in which the code is executed; by
default the dictionary of the module :mod:`__main__` is used. (See the
explanation of the :keyword:`exec` statement or the :func:`eval` built-in
function.)
.. function:: runeval(expression[, globals[, locals]])
Evaluate the *expression* (given as a string) under debugger control. When
:func:`runeval` returns, it returns the value of the expression. Otherwise this
function is similar to :func:`run`.
.. function:: runcall(function[, argument, ...])
Call the *function* (a function or method object, not a string) with the given
arguments. When :func:`runcall` returns, it returns whatever the function call
returned. The debugger prompt appears as soon as the function is entered.
.. function:: set_trace()
Enter the debugger at the calling stack frame. This is useful to hard-code a
breakpoint at a given point in a program, even if the code is not otherwise
being debugged (e.g. when an assertion fails).
.. function:: post_mortem([traceback])
Enter post-mortem debugging of the given *traceback* object. If no
*traceback* is given, it uses the one of the exception that is currently
being handled (an exception must be being handled if the default is to be
used).
.. function:: pm()
Enter post-mortem debugging of the traceback found in
:data:`sys.last_traceback`.
The ``run*`` functions and :func:`set_trace` are aliases for instantiating the
:class:`Pdb` class and calling the method of the same name. If you want to
access further features, you have to do this yourself:
.. class:: Pdb(completekey='tab', stdin=None, stdout=None, skip=None)
:class:`Pdb` is the debugger class.
The *completekey*, *stdin* and *stdout* arguments are passed to the
underlying :class:`cmd.Cmd` class; see the description there.
The *skip* argument, if given, must be an iterable of glob-style module name
patterns. The debugger will not step into frames that originate in a module
that matches one of these patterns. [1]_
Example call to enable tracing with *skip*::
import pdb; pdb.Pdb(skip=['django.*']).set_trace()
.. versionadded:: 2.7
The *skip* argument.
.. method:: run(statement[, globals[, locals]])
runeval(expression[, globals[, locals]])
runcall(function[, argument, ...])
set_trace()
See the documentation for the functions explained above.
.. _debugger-commands:
Debugger Commands
=================
The debugger recognizes the following commands. Most commands can be
abbreviated to one or two letters; e.g. ``h(elp)`` means that either ``h`` or
``help`` can be used to enter the help command (but not ``he`` or ``hel``, nor
``H`` or ``Help`` or ``HELP``). Arguments to commands must be separated by
whitespace (spaces or tabs). Optional arguments are enclosed in square brackets
(``[]``) in the command syntax; the square brackets must not be typed.
Alternatives in the command syntax are separated by a vertical bar (``|``).
Entering a blank line repeats the last command entered. Exception: if the last
command was a ``list`` command, the next 11 lines are listed.
Commands that the debugger doesn't recognize are assumed to be Python statements
and are executed in the context of the program being debugged. Python
statements can also be prefixed with an exclamation point (``!``). This is a
powerful way to inspect the program being debugged; it is even possible to
change a variable or call a function. When an exception occurs in such a
statement, the exception name is printed but the debugger's state is not
changed.
Multiple commands may be entered on a single line, separated by ``;;``. (A
single ``;`` is not used as it is the separator for multiple commands in a line
that is passed to the Python parser.) No intelligence is applied to separating
the commands; the input is split at the first ``;;`` pair, even if it is in the
middle of a quoted string.
The debugger supports aliases. Aliases can have parameters which allows one a
certain level of adaptability to the context under examination.
.. index::
pair: .pdbrc; file
triple: debugger; configuration; file
If a file :file:`.pdbrc` exists in the user's home directory or in the current
directory, it is read in and executed as if it had been typed at the debugger
prompt. This is particularly useful for aliases. If both files exist, the one
in the home directory is read first and aliases defined there can be overridden
by the local file.
h(elp) [*command*]
Without argument, print the list of available commands. With a *command* as
argument, print help about that command. ``help pdb`` displays the full
documentation file; if the environment variable :envvar:`PAGER` is defined, the
file is piped through that command instead. Since the *command* argument must
be an identifier, ``help exec`` must be entered to get help on the ``!``
command.
w(here)
Print a stack trace, with the most recent frame at the bottom. An arrow
indicates the current frame, which determines the context of most commands.
d(own)
Move the current frame one level down in the stack trace (to a newer frame).
u(p)
Move the current frame one level up in the stack trace (to an older frame).
b(reak) [[*filename*:]\ *lineno* | *function*\ [, *condition*]]
With a *lineno* argument, set a break there in the current file. With a
*function* argument, set a break at the first executable statement within that
function. The line number may be prefixed with a filename and a colon, to
specify a breakpoint in another file (probably one that hasn't been loaded yet).
The file is searched on ``sys.path``. Note that each breakpoint is assigned a
number to which all the other breakpoint commands refer.
If a second argument is present, it is an expression which must evaluate to true
before the breakpoint is honored.
Without argument, list all breaks, including for each breakpoint, the number of
times that breakpoint has been hit, the current ignore count, and the associated
condition if any.
tbreak [[*filename*:]\ *lineno* | *function*\ [, *condition*]]
Temporary breakpoint, which is removed automatically when it is first hit. The
arguments are the same as break.
cl(ear) [*filename:lineno* | *bpnumber* [*bpnumber ...*]]
With a *filename:lineno* argument, clear all the breakpoints at this line.
With a space separated list of breakpoint numbers, clear those breakpoints.
Without argument, clear all breaks (but first ask confirmation).
disable [*bpnumber* [*bpnumber ...*]]
Disables the breakpoints given as a space separated list of breakpoint numbers.
Disabling a breakpoint means it cannot cause the program to stop execution, but
unlike clearing a breakpoint, it remains in the list of breakpoints and can be
(re-)enabled.
enable [*bpnumber* [*bpnumber ...*]]
Enables the breakpoints specified.
ignore *bpnumber* [*count*]
Sets the ignore count for the given breakpoint number. If count is omitted, the
ignore count is set to 0. A breakpoint becomes active when the ignore count is
zero. When non-zero, the count is decremented each time the breakpoint is
reached and the breakpoint is not disabled and any associated condition
evaluates to true.
condition *bpnumber* [*condition*]
Condition is an expression which must evaluate to true before the breakpoint is
honored. If condition is absent, any existing condition is removed; i.e., the
breakpoint is made unconditional.
commands [*bpnumber*]
Specify a list of commands for breakpoint number *bpnumber*. The commands
themselves appear on the following lines. Type a line containing just 'end' to
terminate the commands. An example::
(Pdb) commands 1
(com) print some_variable
(com) end
(Pdb)
To remove all commands from a breakpoint, type commands and follow it
immediately with end; that is, give no commands.
With no *bpnumber* argument, commands refers to the last breakpoint set.
You can use breakpoint commands to start your program up again. Simply use the
continue command, or step, or any other command that resumes execution.
Specifying any command resuming execution (currently continue, step, next,
return, jump, quit and their abbreviations) terminates the command list (as if
that command was immediately followed by end). This is because any time you
resume execution (even with a simple next or step), you may encounter another
breakpoint—which could have its own command list, leading to ambiguities about
which list to execute.
If you use the 'silent' command in the command list, the usual message about
stopping at a breakpoint is not printed. This may be desirable for breakpoints
that are to print a specific message and then continue. If none of the other
commands print anything, you see no sign that the breakpoint was reached.
.. versionadded:: 2.5
s(tep)
Execute the current line, stop at the first possible occasion (either in a
function that is called or on the next line in the current function).
n(ext)
Continue execution until the next line in the current function is reached or it
returns. (The difference between ``next`` and ``step`` is that ``step`` stops
inside a called function, while ``next`` executes called functions at (nearly)
full speed, only stopping at the next line in the current function.)
unt(il)
Continue execution until the line with the line number greater than the
current one is reached or when returning from current frame.
.. versionadded:: 2.6
r(eturn)
Continue execution until the current function returns.
c(ont(inue))
Continue execution, only stop when a breakpoint is encountered.
j(ump) *lineno*
Set the next line that will be executed. Only available in the bottom-most
frame. This lets you jump back and execute code again, or jump forward to skip
code that you don't want to run.
It should be noted that not all jumps are allowed --- for instance it is not
possible to jump into the middle of a :keyword:`for` loop or out of a
:keyword:`finally` clause.
l(ist) [*first*\ [, *last*]]
List source code for the current file. Without arguments, list 11 lines around
the current line or continue the previous listing. With one argument, list 11
lines around at that line. With two arguments, list the given range; if the
second argument is less than the first, it is interpreted as a count.
a(rgs)
Print the argument list of the current function.
p *expression*
Evaluate the *expression* in the current context and print its value.
.. note::
``print`` can also be used, but is not a debugger command --- this executes the
Python :keyword:`print` statement.
pp *expression*
Like the ``p`` command, except the value of the expression is pretty-printed
using the :mod:`pprint` module.
alias [*name* [command]]
Creates an alias called *name* that executes *command*. The command must *not*
be enclosed in quotes. Replaceable parameters can be indicated by ``%1``,
``%2``, and so on, while ``%*`` is replaced by all the parameters. If no
command is given, the current alias for *name* is shown. If no arguments are
given, all aliases are listed.
Aliases may be nested and can contain anything that can be legally typed at the
pdb prompt. Note that internal pdb commands *can* be overridden by aliases.
Such a command is then hidden until the alias is removed. Aliasing is
recursively applied to the first word of the command line; all other words in
the line are left alone.
As an example, here are two useful aliases (especially when placed in the
:file:`.pdbrc` file)::
#Print instance variables (usage "pi classInst")
alias pi for k in %1.__dict__.keys(): print "%1.",k,"=",%1.__dict__[k]
#Print instance variables in self
alias ps pi self
unalias *name*
Deletes the specified alias.
[!]\ *statement*
Execute the (one-line) *statement* in the context of the current stack frame.
The exclamation point can be omitted unless the first word of the statement
resembles a debugger command. To set a global variable, you can prefix the
assignment command with a ``global`` command on the same line, e.g.::
(Pdb) global list_options; list_options = ['-l']
(Pdb)
run [*args* ...]
Restart the debugged Python program. If an argument is supplied, it is split
with "shlex" and the result is used as the new sys.argv. History, breakpoints,
actions and debugger options are preserved. "restart" is an alias for "run".
.. versionadded:: 2.6
q(uit)
Quit from the debugger. The program being executed is aborted.
.. rubric:: Footnotes
.. [1] Whether a frame is considered to originate in a certain module
is determined by the ``__name__`` in the frame globals.
PK %�\K�p�: : ) html/_sources/library/persistence.rst.txtnu �[���
.. _persistence:
****************
Data Persistence
****************
The modules described in this chapter support storing Python data in a
persistent form on disk. The :mod:`pickle` and :mod:`marshal` modules can turn
many Python data types into a stream of bytes and then recreate the objects from
the bytes. The various DBM-related modules support a family of hash-based file
formats that store a mapping of strings to other strings. The :mod:`bsddb`
module also provides such disk-based string-to-string mappings based on hashing,
and also supports B-Tree and record-based formats.
The list of modules described in this chapter is:
.. toctree::
pickle.rst
copy_reg.rst
shelve.rst
marshal.rst
anydbm.rst
whichdb.rst
dbm.rst
gdbm.rst
dbhash.rst
bsddb.rst
dumbdbm.rst
sqlite3.rst
PK %�\i�Xh�� �� $ html/_sources/library/pickle.rst.txtnu �[��� :mod:`pickle` --- Python object serialization
=============================================
.. index::
single: persistence
pair: persistent; objects
pair: serializing; objects
pair: marshalling; objects
pair: flattening; objects
pair: pickling; objects
.. module:: pickle
:synopsis: Convert Python objects to streams of bytes and back.
.. sectionauthor:: Jim Kerr <jbkerr@sr.hp.com>.
.. sectionauthor:: Barry Warsaw <barry@zope.com>
The :mod:`pickle` module implements a fundamental, but powerful algorithm for
serializing and de-serializing a Python object structure. "Pickling" is the
process whereby a Python object hierarchy is converted into a byte stream, and
"unpickling" is the inverse operation, whereby a byte stream is converted back
into an object hierarchy. Pickling (and unpickling) is alternatively known as
"serialization", "marshalling," [#]_ or "flattening", however, to avoid
confusion, the terms used here are "pickling" and "unpickling".
This documentation describes both the :mod:`pickle` module and the
:mod:`cPickle` module.
.. warning::
The :mod:`pickle` module is not secure against erroneous or maliciously
constructed data. Never unpickle data received from an untrusted or
unauthenticated source.
Relationship to other Python modules
------------------------------------
The :mod:`pickle` module has an optimized cousin called the :mod:`cPickle`
module. As its name implies, :mod:`cPickle` is written in C, so it can be up to
1000 times faster than :mod:`pickle`. However it does not support subclassing
of the :func:`Pickler` and :func:`Unpickler` classes, because in :mod:`cPickle`
these are functions, not classes. Most applications have no need for this
functionality, and can benefit from the improved performance of :mod:`cPickle`.
Other than that, the interfaces of the two modules are nearly identical; the
common interface is described in this manual and differences are pointed out
where necessary. In the following discussions, we use the term "pickle" to
collectively describe the :mod:`pickle` and :mod:`cPickle` modules.
The data streams the two modules produce are guaranteed to be interchangeable.
Python has a more primitive serialization module called :mod:`marshal`, but in
general :mod:`pickle` should always be the preferred way to serialize Python
objects. :mod:`marshal` exists primarily to support Python's :file:`.pyc`
files.
The :mod:`pickle` module differs from :mod:`marshal` in several significant ways:
* The :mod:`pickle` module keeps track of the objects it has already serialized,
so that later references to the same object won't be serialized again.
:mod:`marshal` doesn't do this.
This has implications both for recursive objects and object sharing. Recursive
objects are objects that contain references to themselves. These are not
handled by marshal, and in fact, attempting to marshal recursive objects will
crash your Python interpreter. Object sharing happens when there are multiple
references to the same object in different places in the object hierarchy being
serialized. :mod:`pickle` stores such objects only once, and ensures that all
other references point to the master copy. Shared objects remain shared, which
can be very important for mutable objects.
* :mod:`marshal` cannot be used to serialize user-defined classes and their
instances. :mod:`pickle` can save and restore class instances transparently,
however the class definition must be importable and live in the same module as
when the object was stored.
* The :mod:`marshal` serialization format is not guaranteed to be portable
across Python versions. Because its primary job in life is to support
:file:`.pyc` files, the Python implementers reserve the right to change the
serialization format in non-backwards compatible ways should the need arise.
The :mod:`pickle` serialization format is guaranteed to be backwards compatible
across Python releases.
Note that serialization is a more primitive notion than persistence; although
:mod:`pickle` reads and writes file objects, it does not handle the issue of
naming persistent objects, nor the (even more complicated) issue of concurrent
access to persistent objects. The :mod:`pickle` module can transform a complex
object into a byte stream and it can transform the byte stream into an object
with the same internal structure. Perhaps the most obvious thing to do with
these byte streams is to write them onto a file, but it is also conceivable to
send them across a network or store them in a database. The module
:mod:`shelve` provides a simple interface to pickle and unpickle objects on
DBM-style database files.
Data stream format
------------------
.. index::
single: XDR
single: External Data Representation
The data format used by :mod:`pickle` is Python-specific. This has the
advantage that there are no restrictions imposed by external standards such as
XDR (which can't represent pointer sharing); however it means that non-Python
programs may not be able to reconstruct pickled Python objects.
By default, the :mod:`pickle` data format uses a printable ASCII representation.
This is slightly more voluminous than a binary representation. The big
advantage of using printable ASCII (and of some other characteristics of
:mod:`pickle`'s representation) is that for debugging or recovery purposes it is
possible for a human to read the pickled file with a standard text editor.
There are currently 3 different protocols which can be used for pickling.
* Protocol version 0 is the original ASCII protocol and is backwards compatible
with earlier versions of Python.
* Protocol version 1 is the old binary format which is also compatible with
earlier versions of Python.
* Protocol version 2 was introduced in Python 2.3. It provides much more
efficient pickling of :term:`new-style class`\es.
Refer to :pep:`307` for more information.
If a *protocol* is not specified, protocol 0 is used. If *protocol* is specified
as a negative value or :const:`HIGHEST_PROTOCOL`, the highest protocol version
available will be used.
.. versionchanged:: 2.3
Introduced the *protocol* parameter.
A binary format, which is slightly more efficient, can be chosen by specifying a
*protocol* version >= 1.
Usage
-----
To serialize an object hierarchy, you first create a pickler, then you call the
pickler's :meth:`dump` method. To de-serialize a data stream, you first create
an unpickler, then you call the unpickler's :meth:`load` method. The
:mod:`pickle` module provides the following constant:
.. data:: HIGHEST_PROTOCOL
The highest protocol version available. This value can be passed as a
*protocol* value.
.. versionadded:: 2.3
.. note::
Be sure to always open pickle files created with protocols >= 1 in binary mode.
For the old ASCII-based pickle protocol 0 you can use either text mode or binary
mode as long as you stay consistent.
A pickle file written with protocol 0 in binary mode will contain lone linefeeds
as line terminators and therefore will look "funny" when viewed in Notepad or
other editors which do not support this format.
The :mod:`pickle` module provides the following functions to make the pickling
process more convenient:
.. function:: dump(obj, file[, protocol])
Write a pickled representation of *obj* to the open file object *file*. This is
equivalent to ``Pickler(file, protocol).dump(obj)``.
If the *protocol* parameter is omitted, protocol 0 is used. If *protocol* is
specified as a negative value or :const:`HIGHEST_PROTOCOL`, the highest protocol
version will be used.
.. versionchanged:: 2.3
Introduced the *protocol* parameter.
*file* must have a :meth:`write` method that accepts a single string argument.
It can thus be a file object opened for writing, a :mod:`StringIO` object, or
any other custom object that meets this interface.
.. function:: load(file)
Read a string from the open file object *file* and interpret it as a pickle data
stream, reconstructing and returning the original object hierarchy. This is
equivalent to ``Unpickler(file).load()``.
*file* must have two methods, a :meth:`read` method that takes an integer
argument, and a :meth:`readline` method that requires no arguments. Both
methods should return a string. Thus *file* can be a file object opened for
reading, a :mod:`StringIO` object, or any other custom object that meets this
interface.
This function automatically determines whether the data stream was written in
binary mode or not.
.. function:: dumps(obj[, protocol])
Return the pickled representation of the object as a string, instead of writing
it to a file.
If the *protocol* parameter is omitted, protocol 0 is used. If *protocol* is
specified as a negative value or :const:`HIGHEST_PROTOCOL`, the highest protocol
version will be used.
.. versionchanged:: 2.3
The *protocol* parameter was added.
.. function:: loads(string)
Read a pickled object hierarchy from a string. Characters in the string past
the pickled object's representation are ignored.
The :mod:`pickle` module also defines three exceptions:
.. exception:: PickleError
A common base class for the other exceptions defined below. This inherits from
:exc:`Exception`.
.. exception:: PicklingError
This exception is raised when an unpicklable object is passed to the
:meth:`dump` method.
.. exception:: UnpicklingError
This exception is raised when there is a problem unpickling an object. Note that
other exceptions may also be raised during unpickling, including (but not
necessarily limited to) :exc:`AttributeError`, :exc:`EOFError`,
:exc:`ImportError`, and :exc:`IndexError`.
The :mod:`pickle` module also exports two callables [#]_, :class:`Pickler` and
:class:`Unpickler`:
.. class:: Pickler(file[, protocol])
This takes a file-like object to which it will write a pickle data stream.
If the *protocol* parameter is omitted, protocol 0 is used. If *protocol* is
specified as a negative value or :const:`HIGHEST_PROTOCOL`, the highest
protocol version will be used.
.. versionchanged:: 2.3
Introduced the *protocol* parameter.
*file* must have a :meth:`write` method that accepts a single string argument.
It can thus be an open file object, a :mod:`StringIO` object, or any other
custom object that meets this interface.
:class:`Pickler` objects define one (or two) public methods:
.. method:: dump(obj)
Write a pickled representation of *obj* to the open file object given in the
constructor. Either the binary or ASCII format will be used, depending on the
value of the *protocol* argument passed to the constructor.
.. method:: clear_memo()
Clears the pickler's "memo". The memo is the data structure that remembers
which objects the pickler has already seen, so that shared or recursive objects
pickled by reference and not by value. This method is useful when re-using
picklers.
.. note::
Prior to Python 2.3, :meth:`clear_memo` was only available on the picklers
created by :mod:`cPickle`. In the :mod:`pickle` module, picklers have an
instance variable called :attr:`memo` which is a Python dictionary. So to clear
the memo for a :mod:`pickle` module pickler, you could do the following::
mypickler.memo.clear()
Code that does not need to support older versions of Python should simply use
:meth:`clear_memo`.
It is possible to make multiple calls to the :meth:`dump` method of the same
:class:`Pickler` instance. These must then be matched to the same number of
calls to the :meth:`load` method of the corresponding :class:`Unpickler`
instance. If the same object is pickled by multiple :meth:`dump` calls, the
:meth:`load` will all yield references to the same object. [#]_
:class:`Unpickler` objects are defined as:
.. class:: Unpickler(file)
This takes a file-like object from which it will read a pickle data stream.
This class automatically determines whether the data stream was written in
binary mode or not, so it does not need a flag as in the :class:`Pickler`
factory.
*file* must have two methods, a :meth:`read` method that takes an integer
argument, and a :meth:`readline` method that requires no arguments. Both
methods should return a string. Thus *file* can be a file object opened for
reading, a :mod:`StringIO` object, or any other custom object that meets this
interface.
:class:`Unpickler` objects have one (or two) public methods:
.. method:: load()
Read a pickled object representation from the open file object given in
the constructor, and return the reconstituted object hierarchy specified
therein.
This method automatically determines whether the data stream was written
in binary mode or not.
.. method:: noload()
This is just like :meth:`load` except that it doesn't actually create any
objects. This is useful primarily for finding what's called "persistent
ids" that may be referenced in a pickle data stream. See section
:ref:`pickle-protocol` below for more details.
**Note:** the :meth:`noload` method is currently only available on
:class:`Unpickler` objects created with the :mod:`cPickle` module.
:mod:`pickle` module :class:`Unpickler`\ s do not have the :meth:`noload`
method.
What can be pickled and unpickled?
----------------------------------
The following types can be pickled:
* ``None``, ``True``, and ``False``
* integers, long integers, floating point numbers, complex numbers
* normal and Unicode strings
* tuples, lists, sets, and dictionaries containing only picklable objects
* functions defined at the top level of a module
* built-in functions defined at the top level of a module
* classes that are defined at the top level of a module
* instances of such classes whose :attr:`~object.__dict__` or the result of
calling :meth:`__getstate__` is picklable (see section :ref:`pickle-protocol`
for details).
Attempts to pickle unpicklable objects will raise the :exc:`PicklingError`
exception; when this happens, an unspecified number of bytes may have already
been written to the underlying file. Trying to pickle a highly recursive data
structure may exceed the maximum recursion depth, a :exc:`RuntimeError` will be
raised in this case. You can carefully raise this limit with
:func:`sys.setrecursionlimit`.
Note that functions (built-in and user-defined) are pickled by "fully qualified"
name reference, not by value. This means that only the function name is
pickled, along with the name of the module the function is defined in. Neither
the function's code, nor any of its function attributes are pickled. Thus the
defining module must be importable in the unpickling environment, and the module
must contain the named object, otherwise an exception will be raised. [#]_
Similarly, classes are pickled by named reference, so the same restrictions in
the unpickling environment apply. Note that none of the class's code or data is
pickled, so in the following example the class attribute ``attr`` is not
restored in the unpickling environment::
class Foo:
attr = 'a class attr'
picklestring = pickle.dumps(Foo)
These restrictions are why picklable functions and classes must be defined in
the top level of a module.
Similarly, when class instances are pickled, their class's code and data are not
pickled along with them. Only the instance data are pickled. This is done on
purpose, so you can fix bugs in a class or add methods to the class and still
load objects that were created with an earlier version of the class. If you
plan to have long-lived objects that will see many versions of a class, it may
be worthwhile to put a version number in the objects so that suitable
conversions can be made by the class's :meth:`__setstate__` method.
.. _pickle-protocol:
The pickle protocol
-------------------
.. currentmodule:: None
This section describes the "pickling protocol" that defines the interface
between the pickler/unpickler and the objects that are being serialized. This
protocol provides a standard way for you to define, customize, and control how
your objects are serialized and de-serialized. The description in this section
doesn't cover specific customizations that you can employ to make the unpickling
environment slightly safer from untrusted pickle data streams; see section
:ref:`pickle-sub` for more details.
.. _pickle-inst:
Pickling and unpickling normal class instances
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. method:: object.__getinitargs__()
When a pickled class instance is unpickled, its :meth:`__init__` method is
normally *not* invoked. If it is desirable that the :meth:`__init__` method
be called on unpickling, an old-style class can define a method
:meth:`__getinitargs__`, which should return a *tuple* of positional
arguments to be passed to the class constructor (:meth:`__init__` for
example). Keyword arguments are not supported. The :meth:`__getinitargs__`
method is called at pickle time; the tuple it returns is incorporated in the
pickle for the instance.
.. method:: object.__getnewargs__()
New-style types can provide a :meth:`__getnewargs__` method that is used for
protocol 2. Implementing this method is needed if the type establishes some
internal invariants when the instance is created, or if the memory allocation
is affected by the values passed to the :meth:`__new__` method for the type
(as it is for tuples and strings). Instances of a :term:`new-style class`
``C`` are created using ::
obj = C.__new__(C, *args)
where *args* is the result of calling :meth:`__getnewargs__` on the original
object; if there is no :meth:`__getnewargs__`, an empty tuple is assumed.
.. method:: object.__getstate__()
Classes can further influence how their instances are pickled; if the class
defines the method :meth:`__getstate__`, it is called and the return state is
pickled as the contents for the instance, instead of the contents of the
instance's dictionary. If there is no :meth:`__getstate__` method, the
instance's :attr:`~object.__dict__` is pickled.
.. method:: object.__setstate__(state)
Upon unpickling, if the class also defines the method :meth:`__setstate__`,
it is called with the unpickled state. [#]_ If there is no
:meth:`__setstate__` method, the pickled state must be a dictionary and its
items are assigned to the new instance's dictionary. If a class defines both
:meth:`__getstate__` and :meth:`__setstate__`, the state object needn't be a
dictionary and these methods can do what they want. [#]_
.. note::
For :term:`new-style class`\es, if :meth:`__getstate__` returns a false
value, the :meth:`__setstate__` method will not be called.
.. note::
At unpickling time, some methods like :meth:`__getattr__`,
:meth:`__getattribute__`, or :meth:`__setattr__` may be called upon the
instance. In case those methods rely on some internal invariant being
true, the type should implement either :meth:`__getinitargs__` or
:meth:`__getnewargs__` to establish such an invariant; otherwise, neither
:meth:`__new__` nor :meth:`__init__` will be called.
Pickling and unpickling extension types
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. method:: object.__reduce__()
When the :class:`Pickler` encounters an object of a type it knows nothing
about --- such as an extension type --- it looks in two places for a hint of
how to pickle it. One alternative is for the object to implement a
:meth:`__reduce__` method. If provided, at pickling time :meth:`__reduce__`
will be called with no arguments, and it must return either a string or a
tuple.
If a string is returned, it names a global variable whose contents are
pickled as normal. The string returned by :meth:`__reduce__` should be the
object's local name relative to its module; the pickle module searches the
module namespace to determine the object's module.
When a tuple is returned, it must be between two and five elements long.
Optional elements can either be omitted, or ``None`` can be provided as their
value. The contents of this tuple are pickled as normal and used to
reconstruct the object at unpickling time. The semantics of each element
are:
* A callable object that will be called to create the initial version of the
object. The next element of the tuple will provide arguments for this
callable, and later elements provide additional state information that will
subsequently be used to fully reconstruct the pickled data.
In the unpickling environment this object must be either a class, a
callable registered as a "safe constructor" (see below), or it must have an
attribute :attr:`__safe_for_unpickling__` with a true value. Otherwise, an
:exc:`UnpicklingError` will be raised in the unpickling environment. Note
that as usual, the callable itself is pickled by name.
* A tuple of arguments for the callable object.
.. versionchanged:: 2.5
Formerly, this argument could also be ``None``.
* Optionally, the object's state, which will be passed to the object's
:meth:`__setstate__` method as described in section :ref:`pickle-inst`. If
the object has no :meth:`__setstate__` method, then, as above, the value
must be a dictionary and it will be added to the object's
:attr:`~object.__dict__`.
* Optionally, an iterator (and not a sequence) yielding successive list
items. These list items will be pickled, and appended to the object using
either ``obj.append(item)`` or ``obj.extend(list_of_items)``. This is
primarily used for list subclasses, but may be used by other classes as
long as they have :meth:`append` and :meth:`extend` methods with the
appropriate signature. (Whether :meth:`append` or :meth:`extend` is used
depends on which pickle protocol version is used as well as the number of
items to append, so both must be supported.)
* Optionally, an iterator (not a sequence) yielding successive dictionary
items, which should be tuples of the form ``(key, value)``. These items
will be pickled and stored to the object using ``obj[key] = value``. This
is primarily used for dictionary subclasses, but may be used by other
classes as long as they implement :meth:`__setitem__`.
.. method:: object.__reduce_ex__(protocol)
It is sometimes useful to know the protocol version when implementing
:meth:`__reduce__`. This can be done by implementing a method named
:meth:`__reduce_ex__` instead of :meth:`__reduce__`. :meth:`__reduce_ex__`,
when it exists, is called in preference over :meth:`__reduce__` (you may
still provide :meth:`__reduce__` for backwards compatibility). The
:meth:`__reduce_ex__` method will be called with a single integer argument,
the protocol version.
The :class:`object` class implements both :meth:`__reduce__` and
:meth:`__reduce_ex__`; however, if a subclass overrides :meth:`__reduce__`
but not :meth:`__reduce_ex__`, the :meth:`__reduce_ex__` implementation
detects this and calls :meth:`__reduce__`.
An alternative to implementing a :meth:`__reduce__` method on the object to be
pickled, is to register the callable with the :mod:`copy_reg` module. This
module provides a way for programs to register "reduction functions" and
constructors for user-defined types. Reduction functions have the same
semantics and interface as the :meth:`__reduce__` method described above, except
that they are called with a single argument, the object to be pickled.
The registered constructor is deemed a "safe constructor" for purposes of
unpickling as described above.
Pickling and unpickling external objects
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. index::
single: persistent_id (pickle protocol)
single: persistent_load (pickle protocol)
For the benefit of object persistence, the :mod:`pickle` module supports the
notion of a reference to an object outside the pickled data stream. Such
objects are referenced by a "persistent id", which is just an arbitrary string
of printable ASCII characters. The resolution of such names is not defined by
the :mod:`pickle` module; it will delegate this resolution to user defined
functions on the pickler and unpickler. [#]_
To define external persistent id resolution, you need to set the
:attr:`~Pickler.persistent_id` attribute of the pickler object and the
:attr:`~Unpickler.persistent_load` attribute of the unpickler object.
To pickle objects that have an external persistent id, the pickler must have a
custom :func:`~Pickler.persistent_id` method that takes an object as an
argument and returns either ``None`` or the persistent id for that object.
When ``None`` is returned, the pickler simply pickles the object as normal.
When a persistent id string is returned, the pickler will pickle that string,
along with a marker so that the unpickler will recognize the string as a
persistent id.
To unpickle external objects, the unpickler must have a custom
:func:`~Unpickler.persistent_load` function that takes a persistent id string
and returns the referenced object.
Here's a silly example that *might* shed more light::
import pickle
from cStringIO import StringIO
src = StringIO()
p = pickle.Pickler(src)
def persistent_id(obj):
if hasattr(obj, 'x'):
return 'the value %d' % obj.x
else:
return None
p.persistent_id = persistent_id
class Integer:
def __init__(self, x):
self.x = x
def __str__(self):
return 'My name is integer %d' % self.x
i = Integer(7)
print i
p.dump(i)
datastream = src.getvalue()
print repr(datastream)
dst = StringIO(datastream)
up = pickle.Unpickler(dst)
class FancyInteger(Integer):
def __str__(self):
return 'I am the integer %d' % self.x
def persistent_load(persid):
if persid.startswith('the value '):
value = int(persid.split()[2])
return FancyInteger(value)
else:
raise pickle.UnpicklingError, 'Invalid persistent id'
up.persistent_load = persistent_load
j = up.load()
print j
In the :mod:`cPickle` module, the unpickler's :attr:`~Unpickler.persistent_load`
attribute can also be set to a Python list, in which case, when the unpickler
reaches a persistent id, the persistent id string will simply be appended to
this list. This functionality exists so that a pickle data stream can be
"sniffed" for object references without actually instantiating all the objects
in a pickle.
[#]_ Setting :attr:`~Unpickler.persistent_load` to a list is usually used in
conjunction with the :meth:`~Unpickler.noload` method on the Unpickler.
.. BAW: Both pickle and cPickle support something called inst_persistent_id()
which appears to give unknown types a second shot at producing a persistent
id. Since Jim Fulton can't remember why it was added or what it's for, I'm
leaving it undocumented.
.. _pickle-sub:
Subclassing Unpicklers
----------------------
.. index::
single: load_global() (pickle protocol)
single: find_global() (pickle protocol)
By default, unpickling will import any class that it finds in the pickle data.
You can control exactly what gets unpickled and what gets called by customizing
your unpickler. Unfortunately, exactly how you do this is different depending
on whether you're using :mod:`pickle` or :mod:`cPickle`. [#]_
In the :mod:`pickle` module, you need to derive a subclass from
:class:`Unpickler`, overriding the :meth:`load_global` method.
:meth:`load_global` should read two lines from the pickle data stream where the
first line will the name of the module containing the class and the second line
will be the name of the instance's class. It then looks up the class, possibly
importing the module and digging out the attribute, then it appends what it
finds to the unpickler's stack. Later on, this class will be assigned to the
:attr:`__class__` attribute of an empty class, as a way of magically creating an
instance without calling its class's :meth:`__init__`. Your job (should you
choose to accept it), would be to have :meth:`load_global` push onto the
unpickler's stack, a known safe version of any class you deem safe to unpickle.
It is up to you to produce such a class. Or you could raise an error if you
want to disallow all unpickling of instances. If this sounds like a hack,
you're right. Refer to the source code to make this work.
Things are a little cleaner with :mod:`cPickle`, but not by much. To control
what gets unpickled, you can set the unpickler's :attr:`~Unpickler.find_global`
attribute to a function or ``None``. If it is ``None`` then any attempts to
unpickle instances will raise an :exc:`UnpicklingError`. If it is a function,
then it should accept a module name and a class name, and return the
corresponding class object. It is responsible for looking up the class and
performing any necessary imports, and it may raise an error to prevent
instances of the class from being unpickled.
The moral of the story is that you should be really careful about the source of
the strings your application unpickles.
.. _pickle-example:
Example
-------
For the simplest code, use the :func:`dump` and :func:`load` functions. Note
that a self-referencing list is pickled and restored correctly. ::
import pickle
data1 = {'a': [1, 2.0, 3, 4+6j],
'b': ('string', u'Unicode string'),
'c': None}
selfref_list = [1, 2, 3]
selfref_list.append(selfref_list)
output = open('data.pkl', 'wb')
# Pickle dictionary using protocol 0.
pickle.dump(data1, output)
# Pickle the list using the highest protocol available.
pickle.dump(selfref_list, output, -1)
output.close()
The following example reads the resulting pickled data. When reading a
pickle-containing file, you should open the file in binary mode because you
can't be sure if the ASCII or binary format was used. ::
import pprint, pickle
pkl_file = open('data.pkl', 'rb')
data1 = pickle.load(pkl_file)
pprint.pprint(data1)
data2 = pickle.load(pkl_file)
pprint.pprint(data2)
pkl_file.close()
Here's a larger example that shows how to modify pickling behavior for a class.
The :class:`TextReader` class opens a text file, and returns the line number and
line contents each time its :meth:`!readline` method is called. If a
:class:`TextReader` instance is pickled, all attributes *except* the file object
member are saved. When the instance is unpickled, the file is reopened, and
reading resumes from the last location. The :meth:`__setstate__` and
:meth:`__getstate__` methods are used to implement this behavior. ::
#!/usr/local/bin/python
class TextReader:
"""Print and number lines in a text file."""
def __init__(self, file):
self.file = file
self.fh = open(file)
self.lineno = 0
def readline(self):
self.lineno = self.lineno + 1
line = self.fh.readline()
if not line:
return None
if line.endswith("\n"):
line = line[:-1]
return "%d: %s" % (self.lineno, line)
def __getstate__(self):
odict = self.__dict__.copy() # copy the dict since we change it
del odict['fh'] # remove filehandle entry
return odict
def __setstate__(self, dict):
fh = open(dict['file']) # reopen file
count = dict['lineno'] # read from file...
while count: # until line count is restored
fh.readline()
count = count - 1
self.__dict__.update(dict) # update attributes
self.fh = fh # save the file object
A sample usage might be something like this::
>>> import TextReader
>>> obj = TextReader.TextReader("TextReader.py")
>>> obj.readline()
'1: #!/usr/local/bin/python'
>>> obj.readline()
'2: '
>>> obj.readline()
'3: class TextReader:'
>>> import pickle
>>> pickle.dump(obj, open('save.p', 'wb'))
If you want to see that :mod:`pickle` works across Python processes, start
another Python session, before continuing. What follows can happen from either
the same process or a new process. ::
>>> import pickle
>>> reader = pickle.load(open('save.p', 'rb'))
>>> reader.readline()
'4: """Print and number lines in a text file."""'
.. seealso::
Module :mod:`copy_reg`
Pickle interface constructor registration for extension types.
Module :mod:`shelve`
Indexed databases of objects; uses :mod:`pickle`.
Module :mod:`copy`
Shallow and deep object copying.
Module :mod:`marshal`
High-performance serialization of built-in types.
:mod:`cPickle` --- A faster :mod:`pickle`
=========================================
.. module:: cPickle
:synopsis: Faster version of pickle, but not subclassable.
.. moduleauthor:: Jim Fulton <jim@zope.com>
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
.. index:: module: pickle
The :mod:`cPickle` module supports serialization and de-serialization of Python
objects, providing an interface and functionality nearly identical to the
:mod:`pickle` module. There are several differences, the most important being
performance and subclassability.
First, :mod:`cPickle` can be up to 1000 times faster than :mod:`pickle` because
the former is implemented in C. Second, in the :mod:`cPickle` module the
callables :func:`Pickler` and :func:`Unpickler` are functions, not classes.
This means that you cannot use them to derive custom pickling and unpickling
subclasses. Most applications have no need for this functionality and should
benefit from the greatly improved performance of the :mod:`cPickle` module.
The pickle data stream produced by :mod:`pickle` and :mod:`cPickle` are
identical, so it is possible to use :mod:`pickle` and :mod:`cPickle`
interchangeably with existing pickles. [#]_
There are additional minor differences in API between :mod:`cPickle` and
:mod:`pickle`, however for most applications, they are interchangeable. More
documentation is provided in the :mod:`pickle` module documentation, which
includes a list of the documented differences.
.. rubric:: Footnotes
.. [#] Don't confuse this with the :mod:`marshal` module
.. [#] In the :mod:`pickle` module these callables are classes, which you could
subclass to customize the behavior. However, in the :mod:`cPickle` module these
callables are factory functions and so cannot be subclassed. One common reason
to subclass is to control what objects can actually be unpickled. See section
:ref:`pickle-sub` for more details.
.. [#] *Warning*: this is intended for pickling multiple objects without intervening
modifications to the objects or their parts. If you modify an object and then
pickle it again using the same :class:`Pickler` instance, the object is not
pickled again --- a reference to it is pickled and the :class:`Unpickler` will
return the old value, not the modified one. There are two problems here: (1)
detecting changes, and (2) marshalling a minimal set of changes. Garbage
Collection may also become a problem here.
.. [#] The exception raised will likely be an :exc:`ImportError` or an
:exc:`AttributeError` but it could be something else.
.. [#] These methods can also be used to implement copying class instances.
.. [#] This protocol is also used by the shallow and deep copying operations defined in
the :mod:`copy` module.
.. [#] The actual mechanism for associating these user defined functions is slightly
different for :mod:`pickle` and :mod:`cPickle`. The description given here
works the same for both implementations. Users of the :mod:`pickle` module
could also use subclassing to effect the same results, overriding the
:meth:`persistent_id` and :meth:`persistent_load` methods in the derived
classes.
.. [#] We'll leave you with the image of Guido and Jim sitting around sniffing pickles
in their living rooms.
.. [#] A word of caution: the mechanisms described here use internal attributes and
methods, which are subject to change in future versions of Python. We intend to
someday provide a common interface for controlling this behavior, which will
work in either :mod:`pickle` or :mod:`cPickle`.
.. [#] Since the pickle data format is actually a tiny stack-oriented programming
language, and some freedom is taken in the encodings of certain objects, it is
possible that the two modules produce different data streams for the same input
objects. However it is guaranteed that they will always be able to read each
other's data streams.
PK %�\�^��� � ) html/_sources/library/pickletools.rst.txtnu �[��� :mod:`pickletools` --- Tools for pickle developers
==================================================
.. module:: pickletools
:synopsis: Contains extensive comments about the pickle protocols and pickle-machine
opcodes, as well as some useful functions.
.. versionadded:: 2.3
**Source code:** :source:`Lib/pickletools.py`
--------------
This module contains various constants relating to the intimate details of the
:mod:`pickle` module, some lengthy comments about the implementation, and a few
useful functions for analyzing pickled data. The contents of this module are
useful for Python core developers who are working on the :mod:`pickle` and
:mod:`cPickle` implementations; ordinary users of the :mod:`pickle` module
probably won't find the :mod:`pickletools` module relevant.
.. function:: dis(pickle, out=None, memo=None, indentlevel=4)
Outputs a symbolic disassembly of the pickle to the file-like object *out*,
defaulting to ``sys.stdout``. *pickle* can be a string or a file-like object.
*memo* can be a Python dictionary that will be used as the pickle's memo; it can
be used to perform disassemblies across multiple pickles created by the same
pickler. Successive levels, indicated by ``MARK`` opcodes in the stream, are
indented by *indentlevel* spaces.
.. function:: genops(pickle)
Provides an :term:`iterator` over all of the opcodes in a pickle, returning a
sequence of ``(opcode, arg, pos)`` triples. *opcode* is an instance of an
:class:`OpcodeInfo` class; *arg* is the decoded value, as a Python object, of
the opcode's argument; *pos* is the position at which this opcode is located.
*pickle* can be a string or a file-like object.
.. function:: optimize(picklestring)
Returns a new equivalent pickle string after eliminating unused ``PUT``
opcodes. The optimized pickle is shorter, takes less transmission time,
requires less storage space, and unpickles more efficiently.
.. versionadded:: 2.6
PK %�\:7�N� � # html/_sources/library/pipes.rst.txtnu �[��� :mod:`pipes` --- Interface to shell pipelines
=============================================
.. module:: pipes
:platform: Unix
:synopsis: A Python interface to Unix shell pipelines.
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
**Source code:** :source:`Lib/pipes.py`
--------------
The :mod:`pipes` module defines a class to abstract the concept of a *pipeline*
--- a sequence of converters from one file to another.
Because the module uses :program:`/bin/sh` command lines, a POSIX or compatible
shell for :func:`os.system` and :func:`os.popen` is required.
.. class:: Template()
An abstraction of a pipeline.
Example::
>>> import pipes
>>> t = pipes.Template()
>>> t.append('tr a-z A-Z', '--')
>>> f = t.open('pipefile', 'w')
>>> f.write('hello world')
>>> f.close()
>>> open('pipefile').read()
'HELLO WORLD'
.. function:: quote(s)
.. deprecated:: 2.7
Prior to Python 2.7, this function was not publicly documented. It is
finally exposed publicly in Python 3.3 as the
:func:`quote <shlex.quote>` function in the :mod:`shlex` module.
Return a shell-escaped version of the string *s*. The returned value is a
string that can safely be used as one token in a shell command line, for
cases where you cannot use a list.
This idiom would be unsafe::
>>> filename = 'somefile; rm -rf ~'
>>> command = 'ls -l {}'.format(filename)
>>> print command # executed by a shell: boom!
ls -l somefile; rm -rf ~
:func:`quote` lets you plug the security hole::
>>> command = 'ls -l {}'.format(quote(filename))
>>> print command
ls -l 'somefile; rm -rf ~'
>>> remote_command = 'ssh home {}'.format(quote(command))
>>> print remote_command
ssh home 'ls -l '"'"'somefile; rm -rf ~'"'"''
The quoting is compatible with UNIX shells and with :func:`shlex.split`:
>>> remote_command = shlex.split(remote_command)
>>> remote_command
['ssh', 'home', "ls -l 'somefile; rm -rf ~'"]
>>> command = shlex.split(remote_command[-1])
>>> command
['ls', '-l', 'somefile; rm -rf ~']
.. _template-objects:
Template Objects
----------------
Template objects following methods:
.. method:: Template.reset()
Restore a pipeline template to its initial state.
.. method:: Template.clone()
Return a new, equivalent, pipeline template.
.. method:: Template.debug(flag)
If *flag* is true, turn debugging on. Otherwise, turn debugging off. When
debugging is on, commands to be executed are printed, and the shell is given
``set -x`` command to be more verbose.
.. method:: Template.append(cmd, kind)
Append a new action at the end. The *cmd* variable must be a valid bourne shell
command. The *kind* variable consists of two letters.
The first letter can be either of ``'-'`` (which means the command reads its
standard input), ``'f'`` (which means the commands reads a given file on the
command line) or ``'.'`` (which means the commands reads no input, and hence
must be first.)
Similarly, the second letter can be either of ``'-'`` (which means the command
writes to standard output), ``'f'`` (which means the command writes a file on
the command line) or ``'.'`` (which means the command does not write anything,
and hence must be last.)
.. method:: Template.prepend(cmd, kind)
Add a new action at the beginning. See :meth:`append` for explanations of the
arguments.
.. method:: Template.open(file, mode)
Return a file-like object, open to *file*, but read from or written to by the
pipeline. Note that only one of ``'r'``, ``'w'`` may be given.
.. method:: Template.copy(infile, outfile)
Copy *infile* to *outfile* through the pipe.
PK %�\}� " " % html/_sources/library/pkgutil.rst.txtnu �[��� :mod:`pkgutil` --- Package extension utility
============================================
.. module:: pkgutil
:synopsis: Utilities for the import system.
.. versionadded:: 2.3
**Source code:** :source:`Lib/pkgutil.py`
--------------
This module provides utilities for the import system, in particular package
support.
.. function:: extend_path(path, name)
Extend the search path for the modules which comprise a package. Intended
use is to place the following code in a package's :file:`__init__.py`::
from pkgutil import extend_path
__path__ = extend_path(__path__, __name__)
This will add to the package's ``__path__`` all subdirectories of directories
on ``sys.path`` named after the package. This is useful if one wants to
distribute different parts of a single logical package as multiple
directories.
It also looks for :file:`\*.pkg` files beginning where ``*`` matches the
*name* argument. This feature is similar to :file:`\*.pth` files (see the
:mod:`site` module for more information), except that it doesn't special-case
lines starting with ``import``. A :file:`\*.pkg` file is trusted at face
value: apart from checking for duplicates, all entries found in a
:file:`\*.pkg` file are added to the path, regardless of whether they exist
on the filesystem. (This is a feature.)
If the input path is not a list (as is the case for frozen packages) it is
returned unchanged. The input path is not modified; an extended copy is
returned. Items are only appended to the copy at the end.
It is assumed that :data:`sys.path` is a sequence. Items of :data:`sys.path`
that are not (Unicode or 8-bit) strings referring to existing directories are
ignored. Unicode items on :data:`sys.path` that cause errors when used as
filenames may cause this function to raise an exception (in line with
:func:`os.path.isdir` behavior).
.. class:: ImpImporter(dirname=None)
:pep:`302` Importer that wraps Python's "classic" import algorithm.
If *dirname* is a string, a :pep:`302` importer is created that searches that
directory. If *dirname* is ``None``, a :pep:`302` importer is created that
searches the current :data:`sys.path`, plus any modules that are frozen or
built-in.
Note that :class:`ImpImporter` does not currently support being used by
placement on :data:`sys.meta_path`.
.. class:: ImpLoader(fullname, file, filename, etc)
:pep:`302` Loader that wraps Python's "classic" import algorithm.
.. function:: find_loader(fullname)
Find a :pep:`302` "loader" object for *fullname*.
If *fullname* contains dots, path must be the containing package's
``__path__``. Returns ``None`` if the module cannot be found or imported.
This function uses :func:`iter_importers`, and is thus subject to the same
limitations regarding platform-specific special import locations such as the
Windows registry.
.. function:: get_importer(path_item)
Retrieve a :pep:`302` importer for the given *path_item*.
The returned importer is cached in :data:`sys.path_importer_cache` if it was
newly created by a path hook.
If there is no importer, a wrapper around the basic import machinery is
returned. This wrapper is never inserted into the importer cache (``None``
is inserted instead).
The cache (or part of it) can be cleared manually if a rescan of
:data:`sys.path_hooks` is necessary.
.. function:: get_loader(module_or_name)
Get a :pep:`302` "loader" object for *module_or_name*.
If the module or package is accessible via the normal import mechanism, a
wrapper around the relevant part of that machinery is returned. Returns
``None`` if the module cannot be found or imported. If the named module is
not already imported, its containing package (if any) is imported, in order
to establish the package ``__path__``.
This function uses :func:`iter_importers`, and is thus subject to the same
limitations regarding platform-specific special import locations such as the
Windows registry.
.. function:: iter_importers(fullname='')
Yield :pep:`302` importers for the given module name.
If fullname contains a '.', the importers will be for the package containing
fullname, otherwise they will be importers for :data:`sys.meta_path`,
:data:`sys.path`, and Python's "classic" import machinery, in that order. If
the named module is in a package, that package is imported as a side effect
of invoking this function.
Non-:pep:`302` mechanisms (e.g. the Windows registry) used by the standard
import machinery to find files in alternative locations are partially
supported, but are searched *after* :data:`sys.path`. Normally, these
locations are searched *before* :data:`sys.path`, preventing :data:`sys.path`
entries from shadowing them.
For this to cause a visible difference in behaviour, there must be a module
or package name that is accessible via both :data:`sys.path` and one of the
non-:pep:`302` file system mechanisms. In this case, the emulation will find
the former version, while the builtin import mechanism will find the latter.
Items of the following types can be affected by this discrepancy:
``imp.C_EXTENSION``, ``imp.PY_SOURCE``, ``imp.PY_COMPILED``,
``imp.PKG_DIRECTORY``.
.. function:: iter_modules(path=None, prefix='')
Yields ``(module_loader, name, ispkg)`` for all submodules on *path*, or, if
path is ``None``, all top-level modules on ``sys.path``.
*path* should be either ``None`` or a list of paths to look for modules in.
*prefix* is a string to output on the front of every module name on output.
.. function:: walk_packages(path=None, prefix='', onerror=None)
Yields ``(module_loader, name, ispkg)`` for all modules recursively on
*path*, or, if path is ``None``, all accessible modules.
*path* should be either ``None`` or a list of paths to look for modules in.
*prefix* is a string to output on the front of every module name on output.
Note that this function must import all *packages* (*not* all modules!) on
the given *path*, in order to access the ``__path__`` attribute to find
submodules.
*onerror* is a function which gets called with one argument (the name of the
package which was being imported) if any exception occurs while trying to
import a package. If no *onerror* function is supplied, :exc:`ImportError`\s
are caught and ignored, while all other exceptions are propagated,
terminating the search.
Examples::
# list all modules python can access
walk_packages()
# list all submodules of ctypes
walk_packages(ctypes.__path__, ctypes.__name__ + '.')
.. function:: get_data(package, resource)
Get a resource from a package.
This is a wrapper for the :pep:`302` loader :func:`get_data` API. The
*package* argument should be the name of a package, in standard module format
(``foo.bar``). The *resource* argument should be in the form of a relative
filename, using ``/`` as the path separator. The parent directory name
``..`` is not allowed, and nor is a rooted name (starting with a ``/``).
The function returns a binary string that is the contents of the specified
resource.
For packages located in the filesystem, which have already been imported,
this is the rough equivalent of::
d = os.path.dirname(sys.modules[package].__file__)
data = open(os.path.join(d, resource), 'rb').read()
If the package cannot be located or loaded, or it uses a :pep:`302` loader
which does not support :func:`get_data`, then ``None`` is returned.
.. versionadded:: 2.6
PK %�\���R% R% & html/_sources/library/platform.rst.txtnu �[��� :mod:`platform` --- Access to underlying platform's identifying data
=====================================================================
.. module:: platform
:synopsis: Retrieves as much platform identifying data as possible.
.. moduleauthor:: Marc-Andre Lemburg <mal@egenix.com>
.. sectionauthor:: Bjorn Pettersen <bpettersen@corp.fairisaac.com>
.. versionadded:: 2.3
**Source code:** :source:`Lib/platform.py`
--------------
.. note::
Specific platforms listed alphabetically, with Linux included in the Unix
section.
Cross Platform
--------------
.. function:: architecture(executable=sys.executable, bits='', linkage='')
Queries the given executable (defaults to the Python interpreter binary) for
various architecture information.
Returns a tuple ``(bits, linkage)`` which contain information about the bit
architecture and the linkage format used for the executable. Both values are
returned as strings.
Values that cannot be determined are returned as given by the parameter presets.
If bits is given as ``''``, the ``sizeof(pointer)`` (or
``sizeof(long)`` on Python version < 1.5.2) is used as indicator for the
supported pointer size.
The function relies on the system's :file:`file` command to do the actual work.
This is available on most if not all Unix platforms and some non-Unix platforms
and then only if the executable points to the Python interpreter. Reasonable
defaults are used when the above needs are not met.
.. note::
On Mac OS X (and perhaps other platforms), executable files may be
universal files containing multiple architectures.
To get at the "64-bitness" of the current interpreter, it is more
reliable to query the :attr:`sys.maxsize` attribute::
is_64bits = sys.maxsize > 2**32
.. function:: machine()
Returns the machine type, e.g. ``'i386'``. An empty string is returned if the
value cannot be determined.
.. function:: node()
Returns the computer's network name (may not be fully qualified!). An empty
string is returned if the value cannot be determined.
.. function:: platform(aliased=0, terse=0)
Returns a single string identifying the underlying platform with as much useful
information as possible.
The output is intended to be *human readable* rather than machine parseable. It
may look different on different platforms and this is intended.
If *aliased* is true, the function will use aliases for various platforms that
report system names which differ from their common names, for example SunOS will
be reported as Solaris. The :func:`system_alias` function is used to implement
this.
Setting *terse* to true causes the function to return only the absolute minimum
information needed to identify the platform.
.. function:: processor()
Returns the (real) processor name, e.g. ``'amdk6'``.
An empty string is returned if the value cannot be determined. Note that many
platforms do not provide this information or simply return the same value as for
:func:`machine`. NetBSD does this.
.. function:: python_build()
Returns a tuple ``(buildno, builddate)`` stating the Python build number and
date as strings.
.. function:: python_compiler()
Returns a string identifying the compiler used for compiling Python.
.. function:: python_branch()
Returns a string identifying the Python implementation SCM branch.
.. versionadded:: 2.6
.. function:: python_implementation()
Returns a string identifying the Python implementation. Possible return values
are: 'CPython', 'IronPython', 'Jython', 'PyPy'.
.. versionadded:: 2.6
.. function:: python_revision()
Returns a string identifying the Python implementation SCM revision.
.. versionadded:: 2.6
.. function:: python_version()
Returns the Python version as string ``'major.minor.patchlevel'``.
Note that unlike the Python ``sys.version``, the returned value will always
include the patchlevel (it defaults to 0).
.. function:: python_version_tuple()
Returns the Python version as tuple ``(major, minor, patchlevel)`` of strings.
Note that unlike the Python ``sys.version``, the returned value will always
include the patchlevel (it defaults to ``'0'``).
.. function:: release()
Returns the system's release, e.g. ``'2.2.0'`` or ``'NT'`` An empty string is
returned if the value cannot be determined.
.. function:: system()
Returns the system/OS name, e.g. ``'Linux'``, ``'Windows'``, or ``'Java'``. An
empty string is returned if the value cannot be determined.
.. function:: system_alias(system, release, version)
Returns ``(system, release, version)`` aliased to common marketing names used
for some systems. It also does some reordering of the information in some cases
where it would otherwise cause confusion.
.. function:: version()
Returns the system's release version, e.g. ``'#3 on degas'``. An empty string is
returned if the value cannot be determined.
.. function:: uname()
Fairly portable uname interface. Returns a tuple of strings ``(system, node,
release, version, machine, processor)`` identifying the underlying platform.
Note that unlike the :func:`os.uname` function this also returns possible
processor information as additional tuple entry.
Entries which cannot be determined are set to ``''``.
Java Platform
-------------
.. function:: java_ver(release='', vendor='', vminfo=('','',''), osinfo=('','',''))
Version interface for Jython.
Returns a tuple ``(release, vendor, vminfo, osinfo)`` with *vminfo* being a
tuple ``(vm_name, vm_release, vm_vendor)`` and *osinfo* being a tuple
``(os_name, os_version, os_arch)``. Values which cannot be determined are set to
the defaults given as parameters (which all default to ``''``).
Windows Platform
----------------
.. function:: win32_ver(release='', version='', csd='', ptype='')
Get additional version information from the Windows Registry and return a tuple
``(release, version, csd, ptype)`` referring to OS release, version number,
CSD level (service pack) and OS type (multi/single processor).
As a hint: *ptype* is ``'Uniprocessor Free'`` on single processor NT machines
and ``'Multiprocessor Free'`` on multi processor machines. The *'Free'* refers
to the OS version being free of debugging code. It could also state *'Checked'*
which means the OS version uses debugging code, i.e. code that checks arguments,
ranges, etc.
.. note::
This function works best with Mark Hammond's
:mod:`win32all` package installed, but also on Python 2.3 and
later (support for this was added in Python 2.6). It obviously
only runs on Win32 compatible platforms.
Win95/98 specific
^^^^^^^^^^^^^^^^^
.. function:: popen(cmd, mode='r', bufsize=None)
Portable :func:`popen` interface. Find a working popen implementation
preferring :func:`win32pipe.popen`. On Windows NT, :func:`win32pipe.popen`
should work; on Windows 9x it hangs due to bugs in the MS C library.
Mac OS Platform
---------------
.. function:: mac_ver(release='', versioninfo=('','',''), machine='')
Get Mac OS version information and return it as tuple ``(release, versioninfo,
machine)`` with *versioninfo* being a tuple ``(version, dev_stage,
non_release_version)``.
Entries which cannot be determined are set to ``''``. All tuple entries are
strings.
Unix Platforms
--------------
.. function:: dist(distname='', version='', id='', supported_dists=('SuSE','debian','redhat','mandrake',...))
This is an old version of the functionality now provided by
:func:`linux_distribution`. For new code, please use the
:func:`linux_distribution`.
The only difference between the two is that ``dist()`` always
returns the short name of the distribution taken from the
``supported_dists`` parameter.
.. deprecated:: 2.6
.. function:: linux_distribution(distname='', version='', id='', supported_dists=('SuSE','debian','redhat','mandrake',...), full_distribution_name=1)
Tries to determine the name of the Linux OS distribution name.
``supported_dists`` may be given to define the set of Linux distributions to
look for. It defaults to a list of currently supported Linux distributions
identified by their release file name.
If ``full_distribution_name`` is true (default), the full distribution read
from the OS is returned. Otherwise the short name taken from
``supported_dists`` is used.
Returns a tuple ``(distname,version,id)`` which defaults to the args given as
parameters. ``id`` is the item in parentheses after the version number. It
is usually the version codename.
.. note::
This function is deprecated since Python 3.5 and removed in Python 3.8.
See alternative like the `distro <https://pypi.org/project/distro>`_ package.
.. versionadded:: 2.6
.. function:: libc_ver(executable=sys.executable, lib='', version='', chunksize=2048)
Tries to determine the libc version against which the file executable (defaults
to the Python interpreter) is linked. Returns a tuple of strings ``(lib,
version)`` which default to the given parameters in case the lookup fails.
Note that this function has intimate knowledge of how different libc versions
add symbols to the executable is probably only usable for executables compiled
using :program:`gcc`.
The file is read and scanned in chunks of *chunksize* bytes.
PK %�\�/�& & & html/_sources/library/plistlib.rst.txtnu �[��� :mod:`plistlib` --- Generate and parse Mac OS X ``.plist`` files
================================================================
.. module:: plistlib
:synopsis: Generate and parse Mac OS X plist files.
.. moduleauthor:: Jack Jansen
.. sectionauthor:: Georg Brandl <georg@python.org>
.. (harvested from docstrings in the original file)
.. versionchanged:: 2.6
This module was previously only available in the Mac-specific library, it is
now available for all platforms.
.. index::
pair: plist; file
single: property list
**Source code:** :source:`Lib/plistlib.py`
--------------
This module provides an interface for reading and writing the "property list"
XML files used mainly by Mac OS X.
The property list (``.plist``) file format is a simple XML pickle supporting
basic object types, like dictionaries, lists, numbers and strings. Usually the
top level object is a dictionary.
Values can be strings, integers, floats, booleans, tuples, lists, dictionaries
(but only with string keys), :class:`Data` or :class:`datetime.datetime`
objects. String values (including dictionary keys) may be unicode strings --
they will be written out as UTF-8.
The ``<data>`` plist type is supported through the :class:`Data` class. This is
a thin wrapper around a Python string. Use :class:`Data` if your strings
contain control characters.
.. seealso::
`PList manual page <https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man5/plist.5.html>`_
Apple's documentation of the file format.
This module defines the following functions:
.. function:: readPlist(pathOrFile)
Read a plist file. *pathOrFile* may either be a file name or a (readable)
file object. Return the unpacked root object (which usually is a
dictionary).
The XML data is parsed using the Expat parser from :mod:`xml.parsers.expat`
-- see its documentation for possible exceptions on ill-formed XML.
Unknown elements will simply be ignored by the plist parser.
.. function:: writePlist(rootObject, pathOrFile)
Write *rootObject* to a plist file. *pathOrFile* may either be a file name
or a (writable) file object.
A :exc:`TypeError` will be raised if the object is of an unsupported type or
a container that contains objects of unsupported types.
.. function:: readPlistFromString(data)
Read a plist from a string. Return the root object.
.. function:: writePlistToString(rootObject)
Return *rootObject* as a plist-formatted string.
.. function:: readPlistFromResource(path, restype='plst', resid=0)
Read a plist from the resource with type *restype* from the resource fork of
*path*. Availability: Mac OS X.
.. note::
In Python 3.x, this function has been removed.
.. function:: writePlistToResource(rootObject, path, restype='plst', resid=0)
Write *rootObject* as a resource with type *restype* to the resource fork of
*path*. Availability: Mac OS X.
.. note::
In Python 3.x, this function has been removed.
The following class is available:
.. class:: Data(data)
Return a "data" wrapper object around the string *data*. This is used in
functions converting from/to plists to represent the ``<data>`` type
available in plists.
It has one attribute, :attr:`data`, that can be used to retrieve the Python
string stored in it.
Examples
--------
Generating a plist::
pl = dict(
aString="Doodah",
aList=["A", "B", 12, 32.1, [1, 2, 3]],
aFloat = 0.1,
anInt = 728,
aDict=dict(
anotherString="<hello & hi there!>",
aUnicodeValue=u'M\xe4ssig, Ma\xdf',
aTrueValue=True,
aFalseValue=False,
),
someData = Data("<binary gunk>"),
someMoreData = Data("<lots of binary gunk>" * 10),
aDate = datetime.datetime.fromtimestamp(time.mktime(time.gmtime())),
)
# unicode keys are possible, but a little awkward to use:
pl[u'\xc5benraa'] = "That was a unicode key."
writePlist(pl, fileName)
Parsing a plist::
pl = readPlist(pathOrFile)
print pl["aKey"]
PK %�\� �Cn n $ html/_sources/library/popen2.rst.txtnu �[���
:mod:`popen2` --- Subprocesses with accessible I/O streams
==========================================================
.. module:: popen2
:synopsis: Subprocesses with accessible standard I/O streams.
:deprecated:
.. sectionauthor:: Drew Csillag <drew_csillag@geocities.com>
.. deprecated:: 2.6
This module is obsolete. Use the :mod:`subprocess` module. Check
especially the :ref:`subprocess-replacements` section.
This module allows you to spawn processes and connect to their
input/output/error pipes and obtain their return codes under Unix and Windows.
The :mod:`subprocess` module provides more powerful facilities for spawning new
processes and retrieving their results. Using the :mod:`subprocess` module is
preferable to using the :mod:`popen2` module.
The primary interface offered by this module is a trio of factory functions.
For each of these, if *bufsize* is specified, it specifies the buffer size for
the I/O pipes. *mode*, if provided, should be the string ``'b'`` or ``'t'``; on
Windows this is needed to determine whether the file objects should be opened in
binary or text mode. The default value for *mode* is ``'t'``.
On Unix, *cmd* may be a sequence, in which case arguments will be passed
directly to the program without shell intervention (as with :func:`os.spawnv`).
If *cmd* is a string it will be passed to the shell (as with :func:`os.system`).
The only way to retrieve the return codes for the child processes is by using
the :meth:`poll` or :meth:`wait` methods on the :class:`Popen3` and
:class:`Popen4` classes; these are only available on Unix. This information is
not available when using the :func:`popen2`, :func:`popen3`, and :func:`popen4`
functions, or the equivalent functions in the :mod:`os` module. (Note that the
tuples returned by the :mod:`os` module's functions are in a different order
from the ones returned by the :mod:`popen2` module.)
.. function:: popen2(cmd[, bufsize[, mode]])
Executes *cmd* as a sub-process. Returns the file objects ``(child_stdout,
child_stdin)``.
.. function:: popen3(cmd[, bufsize[, mode]])
Executes *cmd* as a sub-process. Returns the file objects ``(child_stdout,
child_stdin, child_stderr)``.
.. function:: popen4(cmd[, bufsize[, mode]])
Executes *cmd* as a sub-process. Returns the file objects
``(child_stdout_and_stderr, child_stdin)``.
.. versionadded:: 2.0
On Unix, a class defining the objects returned by the factory functions is also
available. These are not used for the Windows implementation, and are not
available on that platform.
.. class:: Popen3(cmd[, capturestderr[, bufsize]])
This class represents a child process. Normally, :class:`Popen3` instances are
created using the :func:`popen2` and :func:`popen3` factory functions described
above.
If not using one of the helper functions to create :class:`Popen3` objects, the
parameter *cmd* is the shell command to execute in a sub-process. The
*capturestderr* flag, if true, specifies that the object should capture standard
error output of the child process. The default is false. If the *bufsize*
parameter is specified, it specifies the size of the I/O buffers to/from the
child process.
.. class:: Popen4(cmd[, bufsize])
Similar to :class:`Popen3`, but always captures standard error into the same
file object as standard output. These are typically created using
:func:`popen4`.
.. versionadded:: 2.0
.. _popen3-objects:
Popen3 and Popen4 Objects
-------------------------
Instances of the :class:`Popen3` and :class:`Popen4` classes have the following
methods:
.. method:: Popen3.poll()
Returns ``-1`` if child process hasn't completed yet, or its status code
(see :meth:`wait`) otherwise.
.. method:: Popen3.wait()
Waits for and returns the status code of the child process. The status code
encodes both the return code of the process and information about whether it
exited using the :c:func:`exit` system call or died due to a signal. Functions
to help interpret the status code are defined in the :mod:`os` module; see
section :ref:`os-process` for the :func:`W\*` family of functions.
The following attributes are also available:
.. attribute:: Popen3.fromchild
A file object that provides output from the child process. For :class:`Popen4`
instances, this will provide both the standard output and standard error
streams.
.. attribute:: Popen3.tochild
A file object that provides input to the child process.
.. attribute:: Popen3.childerr
A file object that provides error output from the child process, if
*capturestderr* was true for the constructor, otherwise ``None``. This will
always be ``None`` for :class:`Popen4` instances.
.. attribute:: Popen3.pid
The process ID of the child process.
.. _popen2-flow-control:
Flow Control Issues
-------------------
Any time you are working with any form of inter-process communication, control
flow needs to be carefully thought out. This remains the case with the file
objects provided by this module (or the :mod:`os` module equivalents).
When reading output from a child process that writes a lot of data to standard
error while the parent is reading from the child's standard output, a deadlock
can occur. A similar situation can occur with other combinations of reads and
writes. The essential factors are that more than :const:`_PC_PIPE_BUF` bytes
are being written by one process in a blocking fashion, while the other process
is reading from the first process, also in a blocking fashion.
.. Example explanation and suggested work-arounds substantially stolen
from Martin von Löwis:
https://mail.python.org/pipermail/python-dev/2000-September/009460.html
There are several ways to deal with this situation.
The simplest application change, in many cases, will be to follow this model in
the parent process::
import popen2
r, w, e = popen2.popen3('python slave.py')
e.readlines()
r.readlines()
r.close()
e.close()
w.close()
with code like this in the child::
import os
import sys
# note that each of these print statements
# writes a single long string
print >>sys.stderr, 400 * 'this is a test\n'
os.close(sys.stderr.fileno())
print >>sys.stdout, 400 * 'this is another test\n'
In particular, note that ``sys.stderr`` must be closed after writing all data,
or :meth:`readlines` won't return. Also note that :func:`os.close` must be
used, as ``sys.stderr.close()`` won't close ``stderr`` (otherwise assigning to
``sys.stderr`` will silently close it, so no further errors can be printed).
Applications which need to support a more general approach should integrate I/O
over pipes with their :func:`select` loops, or use separate threads to read each
of the individual files provided by whichever :func:`popen\*` function or
:class:`Popen\*` class was used.
.. seealso::
Module :mod:`subprocess`
Module for spawning and managing subprocesses.
PK %�\�hM L L $ html/_sources/library/poplib.rst.txtnu �[��� :mod:`poplib` --- POP3 protocol client
======================================
.. module:: poplib
:synopsis: POP3 protocol client (requires sockets).
.. sectionauthor:: Andrew T. Csillag
.. revised by ESR, January 2000
.. index:: pair: POP3; protocol
**Source code:** :source:`Lib/poplib.py`
--------------
This module defines a class, :class:`POP3`, which encapsulates a connection to a
POP3 server and implements the protocol as defined in :rfc:`1725`. The
:class:`POP3` class supports both the minimal and optional command sets.
Additionally, this module provides a class :class:`POP3_SSL`, which provides
support for connecting to POP3 servers that use SSL as an underlying protocol
layer.
Note that POP3, though widely supported, is obsolescent. The implementation
quality of POP3 servers varies widely, and too many are quite poor. If your
mailserver supports IMAP, you would be better off using the
:class:`imaplib.IMAP4` class, as IMAP servers tend to be better implemented.
The :mod:`poplib` module provides two classes:
.. class:: POP3(host[, port[, timeout]])
This class implements the actual POP3 protocol. The connection is created when
the instance is initialized. If *port* is omitted, the standard POP3 port (110)
is used. The optional *timeout* parameter specifies a timeout in seconds for the
connection attempt (if not specified, the global default timeout setting will
be used).
.. versionchanged:: 2.6
*timeout* was added.
.. class:: POP3_SSL(host[, port[, keyfile[, certfile]]])
This is a subclass of :class:`POP3` that connects to the server over an SSL
encrypted socket. If *port* is not specified, 995, the standard POP3-over-SSL
port is used. *keyfile* and *certfile* are also optional - they can contain a
PEM formatted private key and certificate chain file for the SSL connection.
.. versionadded:: 2.4
One exception is defined as an attribute of the :mod:`poplib` module:
.. exception:: error_proto
Exception raised on any errors from this module (errors from :mod:`socket`
module are not caught). The reason for the exception is passed to the
constructor as a string.
.. seealso::
Module :mod:`imaplib`
The standard Python IMAP module.
`Frequently Asked Questions About Fetchmail <http://www.catb.org/~esr/fetchmail/fetchmail-FAQ.html>`_
The FAQ for the :program:`fetchmail` POP/IMAP client collects information on
POP3 server variations and RFC noncompliance that may be useful if you need to
write an application based on the POP protocol.
.. _pop3-objects:
POP3 Objects
------------
All POP3 commands are represented by methods of the same name, in lower-case;
most return the response text sent by the server.
An :class:`POP3` instance has the following methods:
.. method:: POP3.set_debuglevel(level)
Set the instance's debugging level. This controls the amount of debugging
output printed. The default, ``0``, produces no debugging output. A value of
``1`` produces a moderate amount of debugging output, generally a single line
per request. A value of ``2`` or higher produces the maximum amount of
debugging output, logging each line sent and received on the control connection.
.. method:: POP3.getwelcome()
Returns the greeting string sent by the POP3 server.
.. method:: POP3.user(username)
Send user command, response should indicate that a password is required.
.. method:: POP3.pass_(password)
Send password, response includes message count and mailbox size. Note: the
mailbox on the server is locked until :meth:`~poplib.quit` is called.
.. method:: POP3.apop(user, secret)
Use the more secure APOP authentication to log into the POP3 server.
.. method:: POP3.rpop(user)
Use RPOP authentication (similar to UNIX r-commands) to log into POP3 server.
.. method:: POP3.stat()
Get mailbox status. The result is a tuple of 2 integers: ``(message count,
mailbox size)``.
.. method:: POP3.list([which])
Request message list, result is in the form ``(response, ['mesg_num octets',
...], octets)``. If *which* is set, it is the message to list.
.. method:: POP3.retr(which)
Retrieve whole message number *which*, and set its seen flag. Result is in form
``(response, ['line', ...], octets)``.
.. method:: POP3.dele(which)
Flag message number *which* for deletion. On most servers deletions are not
actually performed until QUIT (the major exception is Eudora QPOP, which
deliberately violates the RFCs by doing pending deletes on any disconnect).
.. method:: POP3.rset()
Remove any deletion marks for the mailbox.
.. method:: POP3.noop()
Do nothing. Might be used as a keep-alive.
.. method:: POP3.quit()
Signoff: commit changes, unlock mailbox, drop connection.
.. method:: POP3.top(which, howmuch)
Retrieves the message header plus *howmuch* lines of the message after the
header of message number *which*. Result is in form ``(response, ['line', ...],
octets)``.
The POP3 TOP command this method uses, unlike the RETR command, doesn't set the
message's seen flag; unfortunately, TOP is poorly specified in the RFCs and is
frequently broken in off-brand servers. Test this method by hand against the
POP3 servers you will use before trusting it.
.. method:: POP3.uidl([which])
Return message digest (unique id) list. If *which* is specified, result contains
the unique id for that message in the form ``'response mesgnum uid``, otherwise
result is list ``(response, ['mesgnum uid', ...], octets)``.
Instances of :class:`POP3_SSL` have no additional methods. The interface of this
subclass is identical to its parent.
.. _pop3-example:
POP3 Example
------------
Here is a minimal example (without error checking) that opens a mailbox and
retrieves and prints all messages::
import getpass, poplib
M = poplib.POP3('localhost')
M.user(getpass.getuser())
M.pass_(getpass.getpass())
numMessages = len(M.list()[1])
for i in range(numMessages):
for j in M.retr(i+1)[1]:
print j
At the end of the module, there is a test section that contains a more extensive
example of usage.
PK %�\H�o . . # html/_sources/library/posix.rst.txtnu �[��� :mod:`posix` --- The most common POSIX system calls
===================================================
.. module:: posix
:platform: Unix
:synopsis: The most common POSIX system calls (normally used via module os).
This module provides access to operating system functionality that is
standardized by the C Standard and the POSIX standard (a thinly disguised Unix
interface).
.. index:: module: os
**Do not import this module directly.** Instead, import the module :mod:`os`,
which provides a *portable* version of this interface. On Unix, the :mod:`os`
module provides a superset of the :mod:`posix` interface. On non-Unix operating
systems the :mod:`posix` module is not available, but a subset is always
available through the :mod:`os` interface. Once :mod:`os` is imported, there is
*no* performance penalty in using it instead of :mod:`posix`. In addition,
:mod:`os` provides some additional functionality, such as automatically calling
:func:`~os.putenv` when an entry in ``os.environ`` is changed.
Errors are reported as exceptions; the usual exceptions are given for type
errors, while errors reported by the system calls raise :exc:`OSError`.
.. _posix-large-files:
Large File Support
------------------
.. index::
single: large files
single: file; large files
.. sectionauthor:: Steve Clift <clift@mail.anacapa.net>
Several operating systems (including AIX, HP-UX, Irix and Solaris) provide
support for files that are larger than 2 GB from a C programming model where
:c:type:`int` and :c:type:`long` are 32-bit values. This is typically accomplished
by defining the relevant size and offset types as 64-bit values. Such files are
sometimes referred to as :dfn:`large files`.
Large file support is enabled in Python when the size of an :c:type:`off_t` is
larger than a :c:type:`long` and the :c:type:`long long` type is available and is
at least as large as an :c:type:`off_t`. Python longs are then used to represent
file sizes, offsets and other values that can exceed the range of a Python int.
It may be necessary to configure and compile Python with certain compiler flags
to enable this mode. For example, it is enabled by default with recent versions
of Irix, but with Solaris 2.6 and 2.7 you need to do something like::
CFLAGS="`getconf LFS_CFLAGS`" OPT="-g -O2 $CFLAGS" \
./configure
On large-file-capable Linux systems, this might work::
CFLAGS='-D_LARGEFILE64_SOURCE -D_FILE_OFFSET_BITS=64' OPT="-g -O2 $CFLAGS" \
./configure
.. _posix-contents:
Notable Module Contents
-----------------------
In addition to many functions described in the :mod:`os` module documentation,
:mod:`posix` defines the following data item:
.. data:: environ
A dictionary representing the string environment at the time the interpreter
was started. For example, ``environ['HOME']`` is the pathname of your home
directory, equivalent to ``getenv("HOME")`` in C.
Modifying this dictionary does not affect the string environment passed on by
:func:`~os.execv`, :func:`~os.popen` or :func:`~os.system`; if you need to
change the environment, pass ``environ`` to :func:`~os.execve` or add
variable assignments and export statements to the command string for
:func:`~os.system` or :func:`~os.popen`.
.. note::
The :mod:`os` module provides an alternate implementation of ``environ`` which
updates the environment on modification. Note also that updating ``os.environ``
will render this dictionary obsolete. Use of the :mod:`os` module version of
this is recommended over direct access to the :mod:`posix` module.
PK %�\,NO� ' html/_sources/library/posixfile.rst.txtnu �[��� :mod:`posixfile` --- File-like objects with locking support
===========================================================
.. module:: posixfile
:platform: Unix
:synopsis: A file-like object with support for locking.
:deprecated:
.. moduleauthor:: Jaap Vermeulen
.. sectionauthor:: Jaap Vermeulen
.. index:: pair: POSIX; file object
.. deprecated:: 1.5
The locking operation that this module provides is done better and more portably
by the :func:`fcntl.lockf` call.
.. index:: single: fcntl() (in module fcntl)
This module implements some additional functionality over the built-in file
objects. In particular, it implements file locking, control over the file
flags, and an easy interface to duplicate the file object. The module defines a
new file object, the posixfile object. It has all the standard file object
methods and adds the methods described below. This module only works for
certain flavors of Unix, since it uses :func:`fcntl.fcntl` for file locking.
To instantiate a posixfile object, use the :func:`posixfile.open` function. The
resulting object looks and feels roughly the same as a standard file object.
The :mod:`posixfile` module defines the following constants:
.. data:: SEEK_SET
Offset is calculated from the start of the file.
.. data:: SEEK_CUR
Offset is calculated from the current position in the file.
.. data:: SEEK_END
Offset is calculated from the end of the file.
The :mod:`posixfile` module defines the following functions:
.. function:: open(filename[, mode[, bufsize]])
Create a new posixfile object with the given filename and mode. The *filename*,
*mode* and *bufsize* arguments are interpreted the same way as by the built-in
:func:`open` function.
.. function:: fileopen(fileobject)
Create a new posixfile object with the given standard file object. The resulting
object has the same filename and mode as the original file object.
The posixfile object defines the following additional methods:
.. method:: posixfile.lock(fmt, [len[, start[, whence]]])
Lock the specified section of the file that the file object is referring to.
The format is explained below in a table. The *len* argument specifies the
length of the section that should be locked. The default is ``0``. *start*
specifies the starting offset of the section, where the default is ``0``. The
*whence* argument specifies where the offset is relative to. It accepts one of
the constants :const:`SEEK_SET`, :const:`SEEK_CUR` or :const:`SEEK_END`. The
default is :const:`SEEK_SET`. For more information about the arguments refer to
the :manpage:`fcntl(2)` manual page on your system.
.. method:: posixfile.flags([flags])
Set the specified flags for the file that the file object is referring to. The
new flags are ORed with the old flags, unless specified otherwise. The format
is explained below in a table. Without the *flags* argument a string indicating
the current flags is returned (this is the same as the ``?`` modifier). For
more information about the flags refer to the :manpage:`fcntl(2)` manual page on
your system.
.. method:: posixfile.dup()
Duplicate the file object and the underlying file pointer and file descriptor.
The resulting object behaves as if it were newly opened.
.. method:: posixfile.dup2(fd)
Duplicate the file object and the underlying file pointer and file descriptor.
The new object will have the given file descriptor. Otherwise the resulting
object behaves as if it were newly opened.
.. method:: posixfile.file()
Return the standard file object that the posixfile object is based on. This is
sometimes necessary for functions that insist on a standard file object.
All methods raise :exc:`IOError` when the request fails.
Format characters for the :meth:`lock` method have the following meaning:
+--------+-----------------------------------------------+
| Format | Meaning |
+========+===============================================+
| ``u`` | unlock the specified region |
+--------+-----------------------------------------------+
| ``r`` | request a read lock for the specified section |
+--------+-----------------------------------------------+
| ``w`` | request a write lock for the specified |
| | section |
+--------+-----------------------------------------------+
In addition the following modifiers can be added to the format:
+----------+--------------------------------+-------+
| Modifier | Meaning | Notes |
+==========+================================+=======+
| ``|`` | wait until the lock has been | |
| | granted | |
+----------+--------------------------------+-------+
| ``?`` | return the first lock | \(1) |
| | conflicting with the requested | |
| | lock, or ``None`` if there is | |
| | no conflict. | |
+----------+--------------------------------+-------+
Note:
(1)
The lock returned is in the format ``(mode, len, start, whence, pid)`` where
*mode* is a character representing the type of lock ('r' or 'w'). This modifier
prevents a request from being granted; it is for query purposes only.
Format characters for the :meth:`flags` method have the following meanings:
+--------+-----------------------------------------------+
| Format | Meaning |
+========+===============================================+
| ``a`` | append only flag |
+--------+-----------------------------------------------+
| ``c`` | close on exec flag |
+--------+-----------------------------------------------+
| ``n`` | no delay flag (also called non-blocking flag) |
+--------+-----------------------------------------------+
| ``s`` | synchronization flag |
+--------+-----------------------------------------------+
In addition the following modifiers can be added to the format:
+----------+---------------------------------+-------+
| Modifier | Meaning | Notes |
+==========+=================================+=======+
| ``!`` | turn the specified flags 'off', | \(1) |
| | instead of the default 'on' | |
+----------+---------------------------------+-------+
| ``=`` | replace the flags, instead of | \(1) |
| | the default 'OR' operation | |
+----------+---------------------------------+-------+
| ``?`` | return a string in which the | \(2) |
| | characters represent the flags | |
| | that are set. | |
+----------+---------------------------------+-------+
Notes:
(1)
The ``!`` and ``=`` modifiers are mutually exclusive.
(2)
This string represents the flags after they may have been altered by the same
call.
Examples::
import posixfile
file = posixfile.open('testfile', 'w')
file.lock('w|')
...
file.lock('u')
file.close()
PK %�\���o# o# $ html/_sources/library/pprint.rst.txtnu �[��� :mod:`pprint` --- Data pretty printer
=====================================
.. module:: pprint
:synopsis: Data pretty printer.
.. moduleauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
**Source code:** :source:`Lib/pprint.py`
--------------
The :mod:`pprint` module provides a capability to "pretty-print" arbitrary
Python data structures in a form which can be used as input to the interpreter.
If the formatted structures include objects which are not fundamental Python
types, the representation may not be loadable. This may be the case if objects
such as files, sockets, classes, or instances are included, as well as many
other built-in objects which are not representable as Python constants.
The formatted representation keeps objects on a single line if it can, and
breaks them onto multiple lines if they don't fit within the allowed width.
Construct :class:`PrettyPrinter` objects explicitly if you need to adjust the
width constraint.
.. versionchanged:: 2.5
Dictionaries are sorted by key before the display is computed; before 2.5, a
dictionary was sorted only if its display required more than one line, although
that wasn't documented.
.. versionchanged:: 2.6
Added support for :class:`set` and :class:`frozenset`.
The :mod:`pprint` module defines one class:
.. First the implementation class:
.. class:: PrettyPrinter(indent=1, width=80, depth=None, stream=None)
Construct a :class:`PrettyPrinter` instance. This constructor understands
several keyword parameters. An output stream may be set using the *stream*
keyword; the only method used on the stream object is the file protocol's
:meth:`write` method. If not specified, the :class:`PrettyPrinter` adopts
``sys.stdout``. Three additional parameters may be used to control the
formatted representation. The keywords are *indent*, *depth*, and *width*. The
amount of indentation added for each recursive level is specified by *indent*;
the default is one. Other values can cause output to look a little odd, but can
make nesting easier to spot. The number of levels which may be printed is
controlled by *depth*; if the data structure being printed is too deep, the next
contained level is replaced by ``...``. By default, there is no constraint on
the depth of the objects being formatted. The desired output width is
constrained using the *width* parameter; the default is 80 characters. If a
structure cannot be formatted within the constrained width, a best effort will
be made.
>>> import pprint
>>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
>>> stuff.insert(0, stuff[:])
>>> pp = pprint.PrettyPrinter(indent=4)
>>> pp.pprint(stuff)
[ ['spam', 'eggs', 'lumberjack', 'knights', 'ni'],
'spam',
'eggs',
'lumberjack',
'knights',
'ni']
>>> tup = ('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead',
... ('parrot', ('fresh fruit',))))))))
>>> pp = pprint.PrettyPrinter(depth=6)
>>> pp.pprint(tup)
('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead', (...)))))))
The :class:`PrettyPrinter` class supports several derivative functions:
.. function:: pformat(object, indent=1, width=80, depth=None)
Return the formatted representation of *object* as a string. *indent*, *width*
and *depth* will be passed to the :class:`PrettyPrinter` constructor as
formatting parameters.
.. versionchanged:: 2.4
The parameters *indent*, *width* and *depth* were added.
.. function:: pprint(object, stream=None, indent=1, width=80, depth=None)
Prints the formatted representation of *object* on *stream*, followed by a
newline. If *stream* is ``None``, ``sys.stdout`` is used. This may be used in
the interactive interpreter instead of a :keyword:`print` statement for
inspecting values. *indent*, *width* and *depth* will be passed to the
:class:`PrettyPrinter` constructor as formatting parameters.
>>> import pprint
>>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
>>> stuff.insert(0, stuff)
>>> pprint.pprint(stuff)
[<Recursion on list with id=...>,
'spam',
'eggs',
'lumberjack',
'knights',
'ni']
.. versionchanged:: 2.4
The parameters *indent*, *width* and *depth* were added.
.. function:: isreadable(object)
.. index:: builtin: eval
Determine if the formatted representation of *object* is "readable," or can be
used to reconstruct the value using :func:`eval`. This always returns ``False``
for recursive objects.
>>> pprint.isreadable(stuff)
False
.. function:: isrecursive(object)
Determine if *object* requires a recursive representation.
One more support function is also defined:
.. function:: saferepr(object)
Return a string representation of *object*, protected against recursive data
structures. If the representation of *object* exposes a recursive entry, the
recursive reference will be represented as ``<Recursion on typename with
id=number>``. The representation is not otherwise formatted.
>>> pprint.saferepr(stuff)
"[<Recursion on list with id=...>, 'spam', 'eggs', 'lumberjack', 'knights', 'ni']"
.. _prettyprinter-objects:
PrettyPrinter Objects
---------------------
:class:`PrettyPrinter` instances have the following methods:
.. method:: PrettyPrinter.pformat(object)
Return the formatted representation of *object*. This takes into account the
options passed to the :class:`PrettyPrinter` constructor.
.. method:: PrettyPrinter.pprint(object)
Print the formatted representation of *object* on the configured stream,
followed by a newline.
The following methods provide the implementations for the corresponding
functions of the same names. Using these methods on an instance is slightly
more efficient since new :class:`PrettyPrinter` objects don't need to be
created.
.. method:: PrettyPrinter.isreadable(object)
.. index:: builtin: eval
Determine if the formatted representation of the object is "readable," or can be
used to reconstruct the value using :func:`eval`. Note that this returns
``False`` for recursive objects. If the *depth* parameter of the
:class:`PrettyPrinter` is set and the object is deeper than allowed, this
returns ``False``.
.. method:: PrettyPrinter.isrecursive(object)
Determine if the object requires a recursive representation.
This method is provided as a hook to allow subclasses to modify the way objects
are converted to strings. The default implementation uses the internals of the
:func:`saferepr` implementation.
.. method:: PrettyPrinter.format(object, context, maxlevels, level)
Returns three values: the formatted version of *object* as a string, a flag
indicating whether the result is readable, and a flag indicating whether
recursion was detected. The first argument is the object to be presented. The
second is a dictionary which contains the :func:`id` of objects that are part of
the current presentation context (direct and indirect containers for *object*
that are affecting the presentation) as the keys; if an object needs to be
presented which is already represented in *context*, the third return value
should be ``True``. Recursive calls to the :meth:`.format` method should add
additional entries for containers to this dictionary. The third argument,
*maxlevels*, gives the requested limit to recursion; this will be ``0`` if there
is no requested limit. This argument should be passed unmodified to recursive
calls. The fourth argument, *level*, gives the current level; recursive calls
should be passed a value less than that of the current call.
.. versionadded:: 2.3
.. _pprint-example:
pprint Example
--------------
This example demonstrates several uses of the :func:`pprint` function and its
parameters.
>>> import pprint
>>> tup = ('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead',
... ('parrot', ('fresh fruit',))))))))
>>> stuff = ['a' * 10, tup, ['a' * 30, 'b' * 30], ['c' * 20, 'd' * 20]]
>>> pprint.pprint(stuff)
['aaaaaaaaaa',
('spam',
('eggs',
('lumberjack',
('knights', ('ni', ('dead', ('parrot', ('fresh fruit',)))))))),
['aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa', 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb'],
['cccccccccccccccccccc', 'dddddddddddddddddddd']]
>>> pprint.pprint(stuff, depth=3)
['aaaaaaaaaa',
('spam', ('eggs', (...))),
['aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa', 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb'],
['cccccccccccccccccccc', 'dddddddddddddddddddd']]
>>> pprint.pprint(stuff, width=60)
['aaaaaaaaaa',
('spam',
('eggs',
('lumberjack',
('knights',
('ni', ('dead', ('parrot', ('fresh fruit',)))))))),
['aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb'],
['cccccccccccccccccccc', 'dddddddddddddddddddd']]
PK %�\��~�o �o % html/_sources/library/profile.rst.txtnu �[��� .. _profile:
********************
The Python Profilers
********************
**Source code:** :source:`Lib/profile.py` and :source:`Lib/pstats.py`
--------------
.. _profiler-introduction:
Introduction to the profilers
=============================
.. index::
single: deterministic profiling
single: profiling, deterministic
:mod:`cProfile` and :mod:`profile` provide :dfn:`deterministic profiling` of
Python programs. A :dfn:`profile` is a set of statistics that describes how
often and for how long various parts of the program executed. These statistics
can be formatted into reports via the :mod:`pstats` module.
The Python standard library provides three different implementations of the same
profiling interface:
1. :mod:`cProfile` is recommended for most users; it's a C extension with
reasonable overhead that makes it suitable for profiling long-running
programs. Based on :mod:`lsprof`, contributed by Brett Rosen and Ted
Czotter.
.. versionadded:: 2.5
2. :mod:`profile`, a pure Python module whose interface is imitated by
:mod:`cProfile`, but which adds significant overhead to profiled programs.
If you're trying to extend the profiler in some way, the task might be easier
with this module. Originally designed and written by Jim Roskind.
.. versionchanged:: 2.4
Now also reports the time spent in calls to built-in functions
and methods.
3. :mod:`hotshot` was an experimental C module that focused on minimizing
the overhead of profiling, at the expense of longer data
post-processing times. It is no longer maintained and may be
dropped in a future version of Python.
.. versionchanged:: 2.5
The results should be more meaningful than in the past: the timing core
contained a critical bug.
The :mod:`profile` and :mod:`cProfile` modules export the same interface, so
they are mostly interchangeable; :mod:`cProfile` has a much lower overhead but
is newer and might not be available on all systems.
:mod:`cProfile` is really a compatibility layer on top of the internal
:mod:`_lsprof` module. The :mod:`hotshot` module is reserved for specialized
usage.
.. note::
The profiler modules are designed to provide an execution profile for a given
program, not for benchmarking purposes (for that, there is :mod:`timeit` for
reasonably accurate results). This particularly applies to benchmarking
Python code against C code: the profilers introduce overhead for Python code,
but not for C-level functions, and so the C code would seem faster than any
Python one.
.. _profile-instant:
Instant User's Manual
=====================
This section is provided for users that "don't want to read the manual." It
provides a very brief overview, and allows a user to rapidly perform profiling
on an existing application.
To profile a function that takes a single argument, you can do::
import cProfile
import re
cProfile.run('re.compile("foo|bar")')
(Use :mod:`profile` instead of :mod:`cProfile` if the latter is not available on
your system.)
The above action would run :func:`re.compile` and print profile results like
the following::
197 function calls (192 primitive calls) in 0.002 seconds
Ordered by: standard name
ncalls tottime percall cumtime percall filename:lineno(function)
1 0.000 0.000 0.001 0.001 <string>:1(<module>)
1 0.000 0.000 0.001 0.001 re.py:212(compile)
1 0.000 0.000 0.001 0.001 re.py:268(_compile)
1 0.000 0.000 0.000 0.000 sre_compile.py:172(_compile_charset)
1 0.000 0.000 0.000 0.000 sre_compile.py:201(_optimize_charset)
4 0.000 0.000 0.000 0.000 sre_compile.py:25(_identityfunction)
3/1 0.000 0.000 0.000 0.000 sre_compile.py:33(_compile)
The first line indicates that 197 calls were monitored. Of those calls, 192
were :dfn:`primitive`, meaning that the call was not induced via recursion. The
next line: ``Ordered by: standard name``, indicates that the text string in the
far right column was used to sort the output. The column headings include:
ncalls
for the number of calls,
tottime
for the total time spent in the given function (and excluding time made in
calls to sub-functions)
percall
is the quotient of ``tottime`` divided by ``ncalls``
cumtime
is the cumulative time spent in this and all subfunctions (from invocation
till exit). This figure is accurate *even* for recursive functions.
percall
is the quotient of ``cumtime`` divided by primitive calls
filename:lineno(function)
provides the respective data of each function
When there are two numbers in the first column (for example ``3/1``), it means
that the function recursed. The second value is the number of primitive calls
and the former is the total number of calls. Note that when the function does
not recurse, these two values are the same, and only the single figure is
printed.
Instead of printing the output at the end of the profile run, you can save the
results to a file by specifying a filename to the :func:`run` function::
import cProfile
import re
cProfile.run('re.compile("foo|bar")', 'restats')
The :class:`pstats.Stats` class reads profile results from a file and formats
them in various ways.
The file :mod:`cProfile` can also be invoked as a script to profile another
script. For example::
python -m cProfile [-o output_file] [-s sort_order] myscript.py
``-o`` writes the profile results to a file instead of to stdout
``-s`` specifies one of the :func:`~pstats.Stats.sort_stats` sort values to sort
the output by. This only applies when ``-o`` is not supplied.
The :mod:`pstats` module's :class:`~pstats.Stats` class has a variety of methods
for manipulating and printing the data saved into a profile results file::
import pstats
p = pstats.Stats('restats')
p.strip_dirs().sort_stats(-1).print_stats()
The :meth:`~pstats.Stats.strip_dirs` method removed the extraneous path from all
the module names. The :meth:`~pstats.Stats.sort_stats` method sorted all the
entries according to the standard module/line/name string that is printed. The
:meth:`~pstats.Stats.print_stats` method printed out all the statistics. You
might try the following sort calls::
p.sort_stats('name')
p.print_stats()
The first call will actually sort the list by function name, and the second call
will print out the statistics. The following are some interesting calls to
experiment with::
p.sort_stats('cumulative').print_stats(10)
This sorts the profile by cumulative time in a function, and then only prints
the ten most significant lines. If you want to understand what algorithms are
taking time, the above line is what you would use.
If you were looking to see what functions were looping a lot, and taking a lot
of time, you would do::
p.sort_stats('time').print_stats(10)
to sort according to time spent within each function, and then print the
statistics for the top ten functions.
You might also try::
p.sort_stats('file').print_stats('__init__')
This will sort all the statistics by file name, and then print out statistics
for only the class init methods (since they are spelled with ``__init__`` in
them). As one final example, you could try::
p.sort_stats('time', 'cum').print_stats(.5, 'init')
This line sorts statistics with a primary key of time, and a secondary key of
cumulative time, and then prints out some of the statistics. To be specific, the
list is first culled down to 50% (re: ``.5``) of its original size, then only
lines containing ``init`` are maintained, and that sub-sub-list is printed.
If you wondered what functions called the above functions, you could now (``p``
is still sorted according to the last criteria) do::
p.print_callers(.5, 'init')
and you would get a list of callers for each of the listed functions.
If you want more functionality, you're going to have to read the manual, or
guess what the following functions do::
p.print_callees()
p.add('restats')
Invoked as a script, the :mod:`pstats` module is a statistics browser for
reading and examining profile dumps. It has a simple line-oriented interface
(implemented using :mod:`cmd`) and interactive help.
:mod:`profile` and :mod:`cProfile` Module Reference
=======================================================
.. module:: cProfile
.. module:: profile
:synopsis: Python source profiler.
Both the :mod:`profile` and :mod:`cProfile` modules provide the following
functions:
.. function:: run(command, filename=None, sort=-1)
This function takes a single argument that can be passed to the :func:`exec`
function, and an optional file name. In all cases this routine executes::
exec(command, __main__.__dict__, __main__.__dict__)
and gathers profiling statistics from the execution. If no file name is
present, then this function automatically creates a :class:`~pstats.Stats`
instance and prints a simple profiling report. If the sort value is specified
it is passed to this :class:`~pstats.Stats` instance to control how the
results are sorted.
.. function:: runctx(command, globals, locals, filename=None)
This function is similar to :func:`run`, with added arguments to supply the
globals and locals dictionaries for the *command* string. This routine
executes::
exec(command, globals, locals)
and gathers profiling statistics as in the :func:`run` function above.
.. class:: Profile(timer=None, timeunit=0.0, subcalls=True, builtins=True)
This class is normally only used if more precise control over profiling is
needed than what the :func:`cProfile.run` function provides.
A custom timer can be supplied for measuring how long code takes to run via
the *timer* argument. This must be a function that returns a single number
representing the current time. If the number is an integer, the *timeunit*
specifies a multiplier that specifies the duration of each unit of time. For
example, if the timer returns times measured in thousands of seconds, the
time unit would be ``.001``.
Directly using the :class:`Profile` class allows formatting profile results
without writing the profile data to a file::
import cProfile, pstats, StringIO
pr = cProfile.Profile()
pr.enable()
# ... do something ...
pr.disable()
s = StringIO.StringIO()
sortby = 'cumulative'
ps = pstats.Stats(pr, stream=s).sort_stats(sortby)
ps.print_stats()
print s.getvalue()
.. method:: enable()
Start collecting profiling data.
.. method:: disable()
Stop collecting profiling data.
.. method:: create_stats()
Stop collecting profiling data and record the results internally
as the current profile.
.. method:: print_stats(sort=-1)
Create a :class:`~pstats.Stats` object based on the current
profile and print the results to stdout.
.. method:: dump_stats(filename)
Write the results of the current profile to *filename*.
.. method:: run(cmd)
Profile the cmd via :func:`exec`.
.. method:: runctx(cmd, globals, locals)
Profile the cmd via :func:`exec` with the specified global and
local environment.
.. method:: runcall(func, *args, **kwargs)
Profile ``func(*args, **kwargs)``
.. _profile-stats:
The :class:`Stats` Class
========================
Analysis of the profiler data is done using the :class:`~pstats.Stats` class.
.. module:: pstats
:synopsis: Statistics object for use with the profiler.
.. class:: Stats(*filenames or profile, stream=sys.stdout)
This class constructor creates an instance of a "statistics object" from a
*filename* (or list of filenames) or from a :class:`Profile` instance. Output
will be printed to the stream specified by *stream*.
The file selected by the above constructor must have been created by the
corresponding version of :mod:`profile` or :mod:`cProfile`. To be specific,
there is *no* file compatibility guaranteed with future versions of this
profiler, and there is no compatibility with files produced by other
profilers, or the same profiler run on a different operating system. If
several files are provided, all the statistics for identical functions will
be coalesced, so that an overall view of several processes can be considered
in a single report. If additional files need to be combined with data in an
existing :class:`~pstats.Stats` object, the :meth:`~pstats.Stats.add` method
can be used.
Instead of reading the profile data from a file, a :class:`cProfile.Profile`
or :class:`profile.Profile` object can be used as the profile data source.
:class:`Stats` objects have the following methods:
.. method:: strip_dirs()
This method for the :class:`Stats` class removes all leading path
information from file names. It is very useful in reducing the size of
the printout to fit within (close to) 80 columns. This method modifies
the object, and the stripped information is lost. After performing a
strip operation, the object is considered to have its entries in a
"random" order, as it was just after object initialization and loading.
If :meth:`~pstats.Stats.strip_dirs` causes two function names to be
indistinguishable (they are on the same line of the same filename, and
have the same function name), then the statistics for these two entries
are accumulated into a single entry.
.. method:: add(*filenames)
This method of the :class:`Stats` class accumulates additional profiling
information into the current profiling object. Its arguments should refer
to filenames created by the corresponding version of :func:`profile.run`
or :func:`cProfile.run`. Statistics for identically named (re: file, line,
name) functions are automatically accumulated into single function
statistics.
.. method:: dump_stats(filename)
Save the data loaded into the :class:`Stats` object to a file named
*filename*. The file is created if it does not exist, and is overwritten
if it already exists. This is equivalent to the method of the same name
on the :class:`profile.Profile` and :class:`cProfile.Profile` classes.
.. versionadded:: 2.3
.. method:: sort_stats(*keys)
This method modifies the :class:`Stats` object by sorting it according to
the supplied criteria. The argument is typically a string identifying the
basis of a sort (example: ``'time'`` or ``'name'``).
When more than one key is provided, then additional keys are used as
secondary criteria when there is equality in all keys selected before
them. For example, ``sort_stats('name', 'file')`` will sort all the
entries according to their function name, and resolve all ties (identical
function names) by sorting by file name.
Abbreviations can be used for any key names, as long as the abbreviation
is unambiguous. The following are the keys currently defined:
+------------------+----------------------+
| Valid Arg | Meaning |
+==================+======================+
| ``'calls'`` | call count |
+------------------+----------------------+
| ``'cumulative'`` | cumulative time |
+------------------+----------------------+
| ``'cumtime'`` | cumulative time |
+------------------+----------------------+
| ``'file'`` | file name |
+------------------+----------------------+
| ``'filename'`` | file name |
+------------------+----------------------+
| ``'module'`` | file name |
+------------------+----------------------+
| ``'ncalls'`` | call count |
+------------------+----------------------+
| ``'pcalls'`` | primitive call count |
+------------------+----------------------+
| ``'line'`` | line number |
+------------------+----------------------+
| ``'name'`` | function name |
+------------------+----------------------+
| ``'nfl'`` | name/file/line |
+------------------+----------------------+
| ``'stdname'`` | standard name |
+------------------+----------------------+
| ``'time'`` | internal time |
+------------------+----------------------+
| ``'tottime'`` | internal time |
+------------------+----------------------+
Note that all sorts on statistics are in descending order (placing most
time consuming items first), where as name, file, and line number searches
are in ascending order (alphabetical). The subtle distinction between
``'nfl'`` and ``'stdname'`` is that the standard name is a sort of the
name as printed, which means that the embedded line numbers get compared
in an odd way. For example, lines 3, 20, and 40 would (if the file names
were the same) appear in the string order 20, 3 and 40. In contrast,
``'nfl'`` does a numeric compare of the line numbers. In fact,
``sort_stats('nfl')`` is the same as ``sort_stats('name', 'file',
'line')``.
For backward-compatibility reasons, the numeric arguments ``-1``, ``0``,
``1``, and ``2`` are permitted. They are interpreted as ``'stdname'``,
``'calls'``, ``'time'``, and ``'cumulative'`` respectively. If this old
style format (numeric) is used, only one sort key (the numeric key) will
be used, and additional arguments will be silently ignored.
.. For compatibility with the old profiler.
.. method:: reverse_order()
This method for the :class:`Stats` class reverses the ordering of the
basic list within the object. Note that by default ascending vs
descending order is properly selected based on the sort key of choice.
.. This method is provided primarily for compatibility with the old
profiler.
.. method:: print_stats(*restrictions)
This method for the :class:`Stats` class prints out a report as described
in the :func:`profile.run` definition.
The order of the printing is based on the last
:meth:`~pstats.Stats.sort_stats` operation done on the object (subject to
caveats in :meth:`~pstats.Stats.add` and
:meth:`~pstats.Stats.strip_dirs`).
The arguments provided (if any) can be used to limit the list down to the
significant entries. Initially, the list is taken to be the complete set
of profiled functions. Each restriction is either an integer (to select a
count of lines), or a decimal fraction between 0.0 and 1.0 inclusive (to
select a percentage of lines), or a regular expression (to pattern match
the standard name that is printed. If several restrictions are provided,
then they are applied sequentially. For example::
print_stats(.1, 'foo:')
would first limit the printing to first 10% of list, and then only print
functions that were part of filename :file:`.\*foo:`. In contrast, the
command::
print_stats('foo:', .1)
would limit the list to all functions having file names :file:`.\*foo:`,
and then proceed to only print the first 10% of them.
.. method:: print_callers(*restrictions)
This method for the :class:`Stats` class prints a list of all functions
that called each function in the profiled database. The ordering is
identical to that provided by :meth:`~pstats.Stats.print_stats`, and the
definition of the restricting argument is also identical. Each caller is
reported on its own line. The format differs slightly depending on the
profiler that produced the stats:
* With :mod:`profile`, a number is shown in parentheses after each caller
to show how many times this specific call was made. For convenience, a
second non-parenthesized number repeats the cumulative time spent in the
function at the right.
* With :mod:`cProfile`, each caller is preceded by three numbers: the
number of times this specific call was made, and the total and
cumulative times spent in the current function while it was invoked by
this specific caller.
.. method:: print_callees(*restrictions)
This method for the :class:`Stats` class prints a list of all function
that were called by the indicated function. Aside from this reversal of
direction of calls (re: called vs was called by), the arguments and
ordering are identical to the :meth:`~pstats.Stats.print_callers` method.
.. _deterministic-profiling:
What Is Deterministic Profiling?
================================
:dfn:`Deterministic profiling` is meant to reflect the fact that all *function
call*, *function return*, and *exception* events are monitored, and precise
timings are made for the intervals between these events (during which time the
user's code is executing). In contrast, :dfn:`statistical profiling` (which is
not done by this module) randomly samples the effective instruction pointer, and
deduces where time is being spent. The latter technique traditionally involves
less overhead (as the code does not need to be instrumented), but provides only
relative indications of where time is being spent.
In Python, since there is an interpreter active during execution, the presence
of instrumented code is not required to do deterministic profiling. Python
automatically provides a :dfn:`hook` (optional callback) for each event. In
addition, the interpreted nature of Python tends to add so much overhead to
execution, that deterministic profiling tends to only add small processing
overhead in typical applications. The result is that deterministic profiling is
not that expensive, yet provides extensive run time statistics about the
execution of a Python program.
Call count statistics can be used to identify bugs in code (surprising counts),
and to identify possible inline-expansion points (high call counts). Internal
time statistics can be used to identify "hot loops" that should be carefully
optimized. Cumulative time statistics should be used to identify high level
errors in the selection of algorithms. Note that the unusual handling of
cumulative times in this profiler allows statistics for recursive
implementations of algorithms to be directly compared to iterative
implementations.
.. _profile-limitations:
Limitations
===========
One limitation has to do with accuracy of timing information. There is a
fundamental problem with deterministic profilers involving accuracy. The most
obvious restriction is that the underlying "clock" is only ticking at a rate
(typically) of about .001 seconds. Hence no measurements will be more accurate
than the underlying clock. If enough measurements are taken, then the "error"
will tend to average out. Unfortunately, removing this first error induces a
second source of error.
The second problem is that it "takes a while" from when an event is dispatched
until the profiler's call to get the time actually *gets* the state of the
clock. Similarly, there is a certain lag when exiting the profiler event
handler from the time that the clock's value was obtained (and then squirreled
away), until the user's code is once again executing. As a result, functions
that are called many times, or call many functions, will typically accumulate
this error. The error that accumulates in this fashion is typically less than
the accuracy of the clock (less than one clock tick), but it *can* accumulate
and become very significant.
The problem is more important with :mod:`profile` than with the lower-overhead
:mod:`cProfile`. For this reason, :mod:`profile` provides a means of
calibrating itself for a given platform so that this error can be
probabilistically (on the average) removed. After the profiler is calibrated, it
will be more accurate (in a least square sense), but it will sometimes produce
negative numbers (when call counts are exceptionally low, and the gods of
probability work against you :-). ) Do *not* be alarmed by negative numbers in
the profile. They should *only* appear if you have calibrated your profiler,
and the results are actually better than without calibration.
.. _profile-calibration:
Calibration
===========
The profiler of the :mod:`profile` module subtracts a constant from each event
handling time to compensate for the overhead of calling the time function, and
socking away the results. By default, the constant is 0. The following
procedure can be used to obtain a better constant for a given platform (see
:ref:`profile-limitations`). ::
import profile
pr = profile.Profile()
for i in range(5):
print pr.calibrate(10000)
The method executes the number of Python calls given by the argument, directly
and again under the profiler, measuring the time for both. It then computes the
hidden overhead per profiler event, and returns that as a float. For example,
on a 1.8Ghz Intel Core i5 running Mac OS X, and using Python's time.clock() as
the timer, the magical number is about 4.04e-6.
The object of this exercise is to get a fairly consistent result. If your
computer is *very* fast, or your timer function has poor resolution, you might
have to pass 100000, or even 1000000, to get consistent results.
When you have a consistent answer, there are three ways you can use it: [#]_ ::
import profile
# 1. Apply computed bias to all Profile instances created hereafter.
profile.Profile.bias = your_computed_bias
# 2. Apply computed bias to a specific Profile instance.
pr = profile.Profile()
pr.bias = your_computed_bias
# 3. Specify computed bias in instance constructor.
pr = profile.Profile(bias=your_computed_bias)
If you have a choice, you are better off choosing a smaller constant, and then
your results will "less often" show up as negative in profile statistics.
.. _profile-timers:
Using a custom timer
====================
If you want to change how current time is determined (for example, to force use
of wall-clock time or elapsed process time), pass the timing function you want
to the :class:`Profile` class constructor::
pr = profile.Profile(your_time_func)
The resulting profiler will then call ``your_time_func``. Depending on whether
you are using :class:`profile.Profile` or :class:`cProfile.Profile`,
``your_time_func``'s return value will be interpreted differently:
:class:`profile.Profile`
``your_time_func`` should return a single number, or a list of numbers whose
sum is the current time (like what :func:`os.times` returns). If the
function returns a single time number, or the list of returned numbers has
length 2, then you will get an especially fast version of the dispatch
routine.
Be warned that you should calibrate the profiler class for the timer function
that you choose (see :ref:`profile-calibration`). For most machines, a timer
that returns a lone integer value will provide the best results in terms of
low overhead during profiling. (:func:`os.times` is *pretty* bad, as it
returns a tuple of floating point values). If you want to substitute a
better timer in the cleanest fashion, derive a class and hardwire a
replacement dispatch method that best handles your timer call, along with the
appropriate calibration constant.
:class:`cProfile.Profile`
``your_time_func`` should return a single number. If it returns integers,
you can also invoke the class constructor with a second argument specifying
the real duration of one unit of time. For example, if
``your_integer_time_func`` returns times measured in thousands of seconds,
you would construct the :class:`Profile` instance as follows::
pr = cProfile.Profile(your_integer_time_func, 0.001)
As the :class:`cProfile.Profile` class cannot be calibrated, custom timer
functions should be used with care and should be as fast as possible. For
the best results with a custom timer, it might be necessary to hard-code it
in the C source of the internal :mod:`_lsprof` module.
.. rubric:: Footnotes
.. [#] Prior to Python 2.2, it was necessary to edit the profiler source code to
embed the bias as a literal number. You still can, but that method is no longer
described, because no longer needed.
PK %�\���J� � ! html/_sources/library/pty.rst.txtnu �[���
:mod:`pty` --- Pseudo-terminal utilities
========================================
.. module:: pty
:platform: Linux
:synopsis: Pseudo-Terminal Handling for Linux.
.. moduleauthor:: Steen Lumholt
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
The :mod:`pty` module defines operations for handling the pseudo-terminal
concept: starting another process and being able to write to and read from its
controlling terminal programmatically.
Because pseudo-terminal handling is highly platform dependent, there is code to
do it only for Linux. (The Linux code is supposed to work on other platforms,
but hasn't been tested yet.)
The :mod:`pty` module defines the following functions:
.. function:: fork()
Fork. Connect the child's controlling terminal to a pseudo-terminal. Return
value is ``(pid, fd)``. Note that the child gets *pid* 0, and the *fd* is
*invalid*. The parent's return value is the *pid* of the child, and *fd* is a
file descriptor connected to the child's controlling terminal (and also to the
child's standard input and output).
.. function:: openpty()
Open a new pseudo-terminal pair, using :func:`os.openpty` if possible, or
emulation code for generic Unix systems. Return a pair of file descriptors
``(master, slave)``, for the master and the slave end, respectively.
.. function:: spawn(argv[, master_read[, stdin_read]])
Spawn a process, and connect its controlling terminal with the current
process's standard io. This is often used to baffle programs which insist on
reading from the controlling terminal.
The functions *master_read* and *stdin_read* should be functions which read from
a file descriptor. The defaults try to read 1024 bytes each time they are
called.
PK %�\��� �
�
! html/_sources/library/pwd.rst.txtnu �[���
:mod:`pwd` --- The password database
====================================
.. module:: pwd
:platform: Unix
:synopsis: The password database (getpwnam() and friends).
This module provides access to the Unix user account and password database. It
is available on all Unix versions.
Password database entries are reported as a tuple-like object, whose attributes
correspond to the members of the ``passwd`` structure (Attribute field below,
see ``<pwd.h>``):
+-------+---------------+-----------------------------+
| Index | Attribute | Meaning |
+=======+===============+=============================+
| 0 | ``pw_name`` | Login name |
+-------+---------------+-----------------------------+
| 1 | ``pw_passwd`` | Optional encrypted password |
+-------+---------------+-----------------------------+
| 2 | ``pw_uid`` | Numerical user ID |
+-------+---------------+-----------------------------+
| 3 | ``pw_gid`` | Numerical group ID |
+-------+---------------+-----------------------------+
| 4 | ``pw_gecos`` | User name or comment field |
+-------+---------------+-----------------------------+
| 5 | ``pw_dir`` | User home directory |
+-------+---------------+-----------------------------+
| 6 | ``pw_shell`` | User command interpreter |
+-------+---------------+-----------------------------+
The uid and gid items are integers, all others are strings. :exc:`KeyError` is
raised if the entry asked for cannot be found.
.. note::
.. index:: module: crypt
In traditional Unix the field ``pw_passwd`` usually contains a password
encrypted with a DES derived algorithm (see module :mod:`crypt`). However most
modern unices use a so-called *shadow password* system. On those unices the
*pw_passwd* field only contains an asterisk (``'*'``) or the letter ``'x'``
where the encrypted password is stored in a file :file:`/etc/shadow` which is
not world readable. Whether the *pw_passwd* field contains anything useful is
system-dependent. If available, the :mod:`spwd` module should be used where
access to the encrypted password is required.
It defines the following items:
.. function:: getpwuid(uid)
Return the password database entry for the given numeric user ID.
.. function:: getpwnam(name)
Return the password database entry for the given user name.
.. function:: getpwall()
Return a list of all available password database entries, in arbitrary order.
.. seealso::
Module :mod:`grp`
An interface to the group database, similar to this.
Module :mod:`spwd`
An interface to the shadow password database, similar to this.
PK %�\��8� � ( html/_sources/library/py_compile.rst.txtnu �[��� :mod:`py_compile` --- Compile Python source files
=================================================
.. module:: py_compile
:synopsis: Generate byte-code files from Python source files.
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
.. documentation based on module docstrings
.. index:: pair: file; byte-code
**Source code:** :source:`Lib/py_compile.py`
--------------
The :mod:`py_compile` module provides a function to generate a byte-code file
from a source file, and another function used when the module source file is
invoked as a script.
Though not often needed, this function can be useful when installing modules for
shared use, especially if some of the users may not have permission to write the
byte-code cache files in the directory containing the source code.
.. exception:: PyCompileError
Exception raised when an error occurs while attempting to compile the file.
.. function:: compile(file[, cfile[, dfile[, doraise]]])
Compile a source file to byte-code and write out the byte-code cache file. The
source code is loaded from the file named *file*. The byte-code is written to
*cfile*, which defaults to *file* ``+`` ``'c'`` (``'o'`` if optimization is
enabled in the current interpreter). If *dfile* is specified, it is used as the
name of the source file in error messages instead of *file*. If *doraise* is
true, a :exc:`PyCompileError` is raised when an error is encountered while
compiling *file*. If *doraise* is false (the default), an error string is
written to ``sys.stderr``, but no exception is raised.
.. function:: main([args])
Compile several source files. The files named in *args* (or on the command
line, if *args* is not specified) are compiled and the resulting bytecode is
cached in the normal manner. This function does not search a directory
structure to locate source files; it only compiles files named explicitly.
If ``'-'`` is the only parameter in args, the list of files is taken from
standard input.
.. versionchanged:: 2.7
Added support for ``'-'``.
When this module is run as a script, the :func:`main` is used to compile all the
files named on the command line. The exit status is nonzero if one of the files
could not be compiled.
.. versionchanged:: 2.6
Added the nonzero exit status when module is run as a script.
.. seealso::
Module :mod:`compileall`
Utilities to compile all Python source files in a directory tree.
PK
%�\$qR� � $ html/_sources/library/pyclbr.rst.txtnu �[��� :mod:`pyclbr` --- Python class browser support
==============================================
.. module:: pyclbr
:synopsis: Supports information extraction for a Python class browser.
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
**Source code:** :source:`Lib/pyclbr.py`
--------------
The :mod:`pyclbr` module can be used to determine some limited information
about the classes, methods and top-level functions defined in a module. The
information provided is sufficient to implement a traditional three-pane
class browser. The information is extracted from the source code rather
than by importing the module, so this module is safe to use with untrusted
code. This restriction makes it impossible to use this module with modules
not implemented in Python, including all standard and optional extension
modules.
.. function:: readmodule(module, path=None)
Read a module and return a dictionary mapping class names to class
descriptor objects. The parameter *module* should be the name of a
module as a string; it may be the name of a module within a package. The
*path* parameter should be a sequence, and is used to augment the value
of ``sys.path``, which is used to locate module source code.
.. function:: readmodule_ex(module, path=None)
Like :func:`readmodule`, but the returned dictionary, in addition to
mapping class names to class descriptor objects, also maps top-level
function names to function descriptor objects. Moreover, if the module
being read is a package, the key ``'__path__'`` in the returned
dictionary has as its value a list which contains the package search
path.
.. _pyclbr-class-objects:
Class Objects
-------------
The :class:`Class` objects used as values in the dictionary returned by
:func:`readmodule` and :func:`readmodule_ex` provide the following data
attributes:
.. attribute:: Class.module
The name of the module defining the class described by the class descriptor.
.. attribute:: Class.name
The name of the class.
.. attribute:: Class.super
A list of :class:`Class` objects which describe the immediate base
classes of the class being described. Classes which are named as
superclasses but which are not discoverable by :func:`readmodule` are
listed as a string with the class name instead of as :class:`Class`
objects.
.. attribute:: Class.methods
A dictionary mapping method names to line numbers.
.. attribute:: Class.file
Name of the file containing the ``class`` statement defining the class.
.. attribute:: Class.lineno
The line number of the ``class`` statement within the file named by
:attr:`~Class.file`.
.. _pyclbr-function-objects:
Function Objects
----------------
The :class:`Function` objects used as values in the dictionary returned by
:func:`readmodule_ex` provide the following attributes:
.. attribute:: Function.module
The name of the module defining the function described by the function
descriptor.
.. attribute:: Function.name
The name of the function.
.. attribute:: Function.file
Name of the file containing the ``def`` statement defining the function.
.. attribute:: Function.lineno
The line number of the ``def`` statement within the file named by
:attr:`~Function.file`.
PK
%�\�J��� � # html/_sources/library/pydoc.rst.txtnu �[��� :mod:`pydoc` --- Documentation generator and online help system
===============================================================
.. module:: pydoc
:synopsis: Documentation generator and online help system.
.. moduleauthor:: Ka-Ping Yee <ping@lfw.org>
.. sectionauthor:: Ka-Ping Yee <ping@lfw.org>
.. versionadded:: 2.1
.. index::
single: documentation; generation
single: documentation; online
single: help; online
**Source code:** :source:`Lib/pydoc.py`
--------------
The :mod:`pydoc` module automatically generates documentation from Python
modules. The documentation can be presented as pages of text on the console,
served to a Web browser, or saved to HTML files.
For modules, classes, functions and methods, the displayed documentation is
derived from the docstring (i.e. the :attr:`__doc__` attribute) of the object,
and recursively of its documentable members. If there is no docstring,
:mod:`pydoc` tries to obtain a description from the block of comment lines just
above the definition of the class, function or method in the source file, or at
the top of the module (see :func:`inspect.getcomments`).
The built-in function :func:`help` invokes the online help system in the
interactive interpreter, which uses :mod:`pydoc` to generate its documentation
as text on the console. The same text documentation can also be viewed from
outside the Python interpreter by running :program:`pydoc` as a script at the
operating system's command prompt. For example, running ::
pydoc sys
at a shell prompt will display documentation on the :mod:`sys` module, in a
style similar to the manual pages shown by the Unix :program:`man` command. The
argument to :program:`pydoc` can be the name of a function, module, or package,
or a dotted reference to a class, method, or function within a module or module
in a package. If the argument to :program:`pydoc` looks like a path (that is,
it contains the path separator for your operating system, such as a slash in
Unix), and refers to an existing Python source file, then documentation is
produced for that file.
.. note::
In order to find objects and their documentation, :mod:`pydoc` imports the
module(s) to be documented. Therefore, any code on module level will be
executed on that occasion. Use an ``if __name__ == '__main__':`` guard to
only execute code when a file is invoked as a script and not just imported.
When printing output to the console, :program:`pydoc` attempts to paginate the
output for easier reading. If the :envvar:`PAGER` environment variable is set,
:program:`pydoc` will use its value as a pagination program.
Specifying a ``-w`` flag before the argument will cause HTML documentation
to be written out to a file in the current directory, instead of displaying text
on the console.
Specifying a ``-k`` flag before the argument will search the synopsis
lines of all available modules for the keyword given as the argument, again in a
manner similar to the Unix :program:`man` command. The synopsis line of a
module is the first line of its documentation string.
You can also use :program:`pydoc` to start an HTTP server on the local machine
that will serve documentation to visiting Web browsers. :program:`pydoc -p 1234`
will start a HTTP server on port 1234, allowing you to browse
the documentation at ``http://localhost:1234/`` in your preferred Web browser.
:program:`pydoc -g` will start the server and additionally bring up a
small :mod:`Tkinter`\ -based graphical interface to help you search for
documentation pages.
When :program:`pydoc` generates documentation, it uses the current environment
and path to locate modules. Thus, invoking :program:`pydoc spam`
documents precisely the version of the module you would get if you started the
Python interpreter and typed ``import spam``.
Module docs for core modules are assumed to reside in
https://docs.python.org/library/. This can be overridden by setting the
:envvar:`PYTHONDOCS` environment variable to a different URL or to a local
directory containing the Library Reference Manual pages.
PK
%�\x7��p �p % html/_sources/library/pyexpat.rst.txtnu �[���
:mod:`xml.parsers.expat` --- Fast XML parsing using Expat
=========================================================
.. module:: xml.parsers.expat
:synopsis: An interface to the Expat non-validating XML parser.
.. moduleauthor:: Paul Prescod <paul@prescod.net>
.. Markup notes:
Many of the attributes of the XMLParser objects are callbacks. Since
signature information must be presented, these are described using the method
directive. Since they are attributes which are set by client code, in-text
references to these attributes should be marked using the :member: role.
.. warning::
The :mod:`pyexpat` module is not secure against maliciously
constructed data. If you need to parse untrusted or unauthenticated data see
:ref:`xml-vulnerabilities`.
.. versionadded:: 2.0
.. index:: single: Expat
The :mod:`xml.parsers.expat` module is a Python interface to the Expat
non-validating XML parser. The module provides a single extension type,
:class:`xmlparser`, that represents the current state of an XML parser. After
an :class:`xmlparser` object has been created, various attributes of the object
can be set to handler functions. When an XML document is then fed to the
parser, the handler functions are called for the character data and markup in
the XML document.
.. index:: module: pyexpat
This module uses the :mod:`pyexpat` module to provide access to the Expat
parser. Direct use of the :mod:`pyexpat` module is deprecated.
This module provides one exception and one type object:
.. exception:: ExpatError
The exception raised when Expat reports an error. See section
:ref:`expaterror-objects` for more information on interpreting Expat errors.
.. exception:: error
Alias for :exc:`ExpatError`.
.. data:: XMLParserType
The type of the return values from the :func:`ParserCreate` function.
The :mod:`xml.parsers.expat` module contains two functions:
.. function:: ErrorString(errno)
Returns an explanatory string for a given error number *errno*.
.. function:: ParserCreate([encoding[, namespace_separator]])
Creates and returns a new :class:`xmlparser` object. *encoding*, if specified,
must be a string naming the encoding used by the XML data. Expat doesn't
support as many encodings as Python does, and its repertoire of encodings can't
be extended; it supports UTF-8, UTF-16, ISO-8859-1 (Latin1), and ASCII. If
*encoding* [1]_ is given it will override the implicit or explicit encoding of the
document.
Expat can optionally do XML namespace processing for you, enabled by providing a
value for *namespace_separator*. The value must be a one-character string; a
:exc:`ValueError` will be raised if the string has an illegal length (``None``
is considered the same as omission). When namespace processing is enabled,
element type names and attribute names that belong to a namespace will be
expanded. The element name passed to the element handlers
:attr:`StartElementHandler` and :attr:`EndElementHandler` will be the
concatenation of the namespace URI, the namespace separator character, and the
local part of the name. If the namespace separator is a zero byte (``chr(0)``)
then the namespace URI and the local part will be concatenated without any
separator.
For example, if *namespace_separator* is set to a space character (``' '``) and
the following document is parsed:
.. code-block:: xml
<?xml version="1.0"?>
<root xmlns = "http://default-namespace.org/"
xmlns:py = "http://www.python.org/ns/">
<py:elem1 />
<elem2 xmlns="" />
</root>
:attr:`StartElementHandler` will receive the following strings for each
element::
http://default-namespace.org/ root
http://www.python.org/ns/ elem1
elem2
Due to limitations in the ``Expat`` library used by :mod:`pyexpat`,
the :class:`xmlparser` instance returned can only be used to parse a single
XML document. Call ``ParserCreate`` for each document to provide unique
parser instances.
.. seealso::
`The Expat XML Parser <http://www.libexpat.org/>`_
Home page of the Expat project.
.. _xmlparser-objects:
XMLParser Objects
-----------------
:class:`xmlparser` objects have the following methods:
.. method:: xmlparser.Parse(data[, isfinal])
Parses the contents of the string *data*, calling the appropriate handler
functions to process the parsed data. *isfinal* must be true on the final call
to this method; it allows the parsing of a single file in fragments,
not the submission of multiple files.
*data* can be the empty string at any time.
.. method:: xmlparser.ParseFile(file)
Parse XML data reading from the object *file*. *file* only needs to provide
the ``read(nbytes)`` method, returning the empty string when there's no more
data.
.. method:: xmlparser.SetBase(base)
Sets the base to be used for resolving relative URIs in system identifiers in
declarations. Resolving relative identifiers is left to the application: this
value will be passed through as the *base* argument to the
:func:`ExternalEntityRefHandler`, :func:`NotationDeclHandler`, and
:func:`UnparsedEntityDeclHandler` functions.
.. method:: xmlparser.GetBase()
Returns a string containing the base set by a previous call to :meth:`SetBase`,
or ``None`` if :meth:`SetBase` hasn't been called.
.. method:: xmlparser.GetInputContext()
Returns the input data that generated the current event as a string. The data is
in the encoding of the entity which contains the text. When called while an
event handler is not active, the return value is ``None``.
.. versionadded:: 2.1
.. method:: xmlparser.ExternalEntityParserCreate(context[, encoding])
Create a "child" parser which can be used to parse an external parsed entity
referred to by content parsed by the parent parser. The *context* parameter
should be the string passed to the :meth:`ExternalEntityRefHandler` handler
function, described below. The child parser is created with the
:attr:`ordered_attributes`, :attr:`returns_unicode` and
:attr:`specified_attributes` set to the values of this parser.
.. method:: xmlparser.SetParamEntityParsing(flag)
Control parsing of parameter entities (including the external DTD subset).
Possible *flag* values are :const:`XML_PARAM_ENTITY_PARSING_NEVER`,
:const:`XML_PARAM_ENTITY_PARSING_UNLESS_STANDALONE` and
:const:`XML_PARAM_ENTITY_PARSING_ALWAYS`. Return true if setting the flag
was successful.
.. method:: xmlparser.UseForeignDTD([flag])
Calling this with a true value for *flag* (the default) will cause Expat to call
the :attr:`ExternalEntityRefHandler` with :const:`None` for all arguments to
allow an alternate DTD to be loaded. If the document does not contain a
document type declaration, the :attr:`ExternalEntityRefHandler` will still be
called, but the :attr:`StartDoctypeDeclHandler` and
:attr:`EndDoctypeDeclHandler` will not be called.
Passing a false value for *flag* will cancel a previous call that passed a true
value, but otherwise has no effect.
This method can only be called before the :meth:`Parse` or :meth:`ParseFile`
methods are called; calling it after either of those have been called causes
:exc:`ExpatError` to be raised with the :attr:`code` attribute set to
:const:`errors.XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING`.
.. versionadded:: 2.3
:class:`xmlparser` objects have the following attributes:
.. attribute:: xmlparser.buffer_size
The size of the buffer used when :attr:`buffer_text` is true.
A new buffer size can be set by assigning a new integer value
to this attribute.
When the size is changed, the buffer will be flushed.
.. versionadded:: 2.3
.. versionchanged:: 2.6
The buffer size can now be changed.
.. attribute:: xmlparser.buffer_text
Setting this to true causes the :class:`xmlparser` object to buffer textual
content returned by Expat to avoid multiple calls to the
:meth:`CharacterDataHandler` callback whenever possible. This can improve
performance substantially since Expat normally breaks character data into chunks
at every line ending. This attribute is false by default, and may be changed at
any time.
.. versionadded:: 2.3
.. attribute:: xmlparser.buffer_used
If :attr:`buffer_text` is enabled, the number of bytes stored in the buffer.
These bytes represent UTF-8 encoded text. This attribute has no meaningful
interpretation when :attr:`buffer_text` is false.
.. versionadded:: 2.3
.. attribute:: xmlparser.ordered_attributes
Setting this attribute to a non-zero integer causes the attributes to be
reported as a list rather than a dictionary. The attributes are presented in
the order found in the document text. For each attribute, two list entries are
presented: the attribute name and the attribute value. (Older versions of this
module also used this format.) By default, this attribute is false; it may be
changed at any time.
.. versionadded:: 2.1
.. attribute:: xmlparser.returns_unicode
If this attribute is set to a non-zero integer, the handler functions will be
passed Unicode strings. If :attr:`returns_unicode` is :const:`False`, 8-bit
strings containing UTF-8 encoded data will be passed to the handlers. This is
:const:`True` by default when Python is built with Unicode support.
.. versionchanged:: 1.6
Can be changed at any time to affect the result type.
.. attribute:: xmlparser.specified_attributes
If set to a non-zero integer, the parser will report only those attributes which
were specified in the document instance and not those which were derived from
attribute declarations. Applications which set this need to be especially
careful to use what additional information is available from the declarations as
needed to comply with the standards for the behavior of XML processors. By
default, this attribute is false; it may be changed at any time.
.. versionadded:: 2.1
The following attributes contain values relating to the most recent error
encountered by an :class:`xmlparser` object, and will only have correct values
once a call to :meth:`Parse` or :meth:`ParseFile` has raised an
:exc:`xml.parsers.expat.ExpatError` exception.
.. attribute:: xmlparser.ErrorByteIndex
Byte index at which an error occurred.
.. attribute:: xmlparser.ErrorCode
Numeric code specifying the problem. This value can be passed to the
:func:`ErrorString` function, or compared to one of the constants defined in the
``errors`` object.
.. attribute:: xmlparser.ErrorColumnNumber
Column number at which an error occurred.
.. attribute:: xmlparser.ErrorLineNumber
Line number at which an error occurred.
The following attributes contain values relating to the current parse location
in an :class:`xmlparser` object. During a callback reporting a parse event they
indicate the location of the first of the sequence of characters that generated
the event. When called outside of a callback, the position indicated will be
just past the last parse event (regardless of whether there was an associated
callback).
.. versionadded:: 2.4
.. attribute:: xmlparser.CurrentByteIndex
Current byte index in the parser input.
.. attribute:: xmlparser.CurrentColumnNumber
Current column number in the parser input.
.. attribute:: xmlparser.CurrentLineNumber
Current line number in the parser input.
Here is the list of handlers that can be set. To set a handler on an
:class:`xmlparser` object *o*, use ``o.handlername = func``. *handlername* must
be taken from the following list, and *func* must be a callable object accepting
the correct number of arguments. The arguments are all strings, unless
otherwise stated.
.. method:: xmlparser.XmlDeclHandler(version, encoding, standalone)
Called when the XML declaration is parsed. The XML declaration is the
(optional) declaration of the applicable version of the XML recommendation, the
encoding of the document text, and an optional "standalone" declaration.
*version* and *encoding* will be strings of the type dictated by the
:attr:`returns_unicode` attribute, and *standalone* will be ``1`` if the
document is declared standalone, ``0`` if it is declared not to be standalone,
or ``-1`` if the standalone clause was omitted. This is only available with
Expat version 1.95.0 or newer.
.. versionadded:: 2.1
.. method:: xmlparser.StartDoctypeDeclHandler(doctypeName, systemId, publicId, has_internal_subset)
Called when Expat begins parsing the document type declaration (``<!DOCTYPE
...``). The *doctypeName* is provided exactly as presented. The *systemId* and
*publicId* parameters give the system and public identifiers if specified, or
``None`` if omitted. *has_internal_subset* will be true if the document
contains and internal document declaration subset. This requires Expat version
1.2 or newer.
.. method:: xmlparser.EndDoctypeDeclHandler()
Called when Expat is done parsing the document type declaration. This requires
Expat version 1.2 or newer.
.. method:: xmlparser.ElementDeclHandler(name, model)
Called once for each element type declaration. *name* is the name of the
element type, and *model* is a representation of the content model.
.. method:: xmlparser.AttlistDeclHandler(elname, attname, type, default, required)
Called for each declared attribute for an element type. If an attribute list
declaration declares three attributes, this handler is called three times, once
for each attribute. *elname* is the name of the element to which the
declaration applies and *attname* is the name of the attribute declared. The
attribute type is a string passed as *type*; the possible values are
``'CDATA'``, ``'ID'``, ``'IDREF'``, ... *default* gives the default value for
the attribute used when the attribute is not specified by the document instance,
or ``None`` if there is no default value (``#IMPLIED`` values). If the
attribute is required to be given in the document instance, *required* will be
true. This requires Expat version 1.95.0 or newer.
.. method:: xmlparser.StartElementHandler(name, attributes)
Called for the start of every element. *name* is a string containing the
element name, and *attributes* is a dictionary mapping attribute names to their
values.
.. method:: xmlparser.EndElementHandler(name)
Called for the end of every element.
.. method:: xmlparser.ProcessingInstructionHandler(target, data)
Called for every processing instruction.
.. method:: xmlparser.CharacterDataHandler(data)
Called for character data. This will be called for normal character data, CDATA
marked content, and ignorable whitespace. Applications which must distinguish
these cases can use the :attr:`StartCdataSectionHandler`,
:attr:`EndCdataSectionHandler`, and :attr:`ElementDeclHandler` callbacks to
collect the required information.
.. method:: xmlparser.UnparsedEntityDeclHandler(entityName, base, systemId, publicId, notationName)
Called for unparsed (NDATA) entity declarations. This is only present for
version 1.2 of the Expat library; for more recent versions, use
:attr:`EntityDeclHandler` instead. (The underlying function in the Expat
library has been declared obsolete.)
.. method:: xmlparser.EntityDeclHandler(entityName, is_parameter_entity, value, base, systemId, publicId, notationName)
Called for all entity declarations. For parameter and internal entities,
*value* will be a string giving the declared contents of the entity; this will
be ``None`` for external entities. The *notationName* parameter will be
``None`` for parsed entities, and the name of the notation for unparsed
entities. *is_parameter_entity* will be true if the entity is a parameter entity
or false for general entities (most applications only need to be concerned with
general entities). This is only available starting with version 1.95.0 of the
Expat library.
.. versionadded:: 2.1
.. method:: xmlparser.NotationDeclHandler(notationName, base, systemId, publicId)
Called for notation declarations. *notationName*, *base*, and *systemId*, and
*publicId* are strings if given. If the public identifier is omitted,
*publicId* will be ``None``.
.. method:: xmlparser.StartNamespaceDeclHandler(prefix, uri)
Called when an element contains a namespace declaration. Namespace declarations
are processed before the :attr:`StartElementHandler` is called for the element
on which declarations are placed.
.. method:: xmlparser.EndNamespaceDeclHandler(prefix)
Called when the closing tag is reached for an element that contained a
namespace declaration. This is called once for each namespace declaration on
the element in the reverse of the order for which the
:attr:`StartNamespaceDeclHandler` was called to indicate the start of each
namespace declaration's scope. Calls to this handler are made after the
corresponding :attr:`EndElementHandler` for the end of the element.
.. method:: xmlparser.CommentHandler(data)
Called for comments. *data* is the text of the comment, excluding the leading
``'<!-``\ ``-'`` and trailing ``'-``\ ``->'``.
.. method:: xmlparser.StartCdataSectionHandler()
Called at the start of a CDATA section. This and :attr:`EndCdataSectionHandler`
are needed to be able to identify the syntactical start and end for CDATA
sections.
.. method:: xmlparser.EndCdataSectionHandler()
Called at the end of a CDATA section.
.. method:: xmlparser.DefaultHandler(data)
Called for any characters in the XML document for which no applicable handler
has been specified. This means characters that are part of a construct which
could be reported, but for which no handler has been supplied.
.. method:: xmlparser.DefaultHandlerExpand(data)
This is the same as the :func:`DefaultHandler`, but doesn't inhibit expansion
of internal entities. The entity reference will not be passed to the default
handler.
.. method:: xmlparser.NotStandaloneHandler()
Called if the XML document hasn't been declared as being a standalone document.
This happens when there is an external subset or a reference to a parameter
entity, but the XML declaration does not set standalone to ``yes`` in an XML
declaration. If this handler returns ``0``, then the parser will raise an
:const:`XML_ERROR_NOT_STANDALONE` error. If this handler is not set, no
exception is raised by the parser for this condition.
.. method:: xmlparser.ExternalEntityRefHandler(context, base, systemId, publicId)
Called for references to external entities. *base* is the current base, as set
by a previous call to :meth:`SetBase`. The public and system identifiers,
*systemId* and *publicId*, are strings if given; if the public identifier is not
given, *publicId* will be ``None``. The *context* value is opaque and should
only be used as described below.
For external entities to be parsed, this handler must be implemented. It is
responsible for creating the sub-parser using
``ExternalEntityParserCreate(context)``, initializing it with the appropriate
callbacks, and parsing the entity. This handler should return an integer; if it
returns ``0``, the parser will raise an
:const:`XML_ERROR_EXTERNAL_ENTITY_HANDLING` error, otherwise parsing will
continue.
If this handler is not provided, external entities are reported by the
:attr:`DefaultHandler` callback, if provided.
.. _expaterror-objects:
ExpatError Exceptions
---------------------
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
:exc:`ExpatError` exceptions have a number of interesting attributes:
.. attribute:: ExpatError.code
Expat's internal error number for the specific error. This will match one of
the constants defined in the ``errors`` object from this module.
.. versionadded:: 2.1
.. attribute:: ExpatError.lineno
Line number on which the error was detected. The first line is numbered ``1``.
.. versionadded:: 2.1
.. attribute:: ExpatError.offset
Character offset into the line where the error occurred. The first column is
numbered ``0``.
.. versionadded:: 2.1
.. _expat-example:
Example
-------
The following program defines three handlers that just print out their
arguments. ::
import xml.parsers.expat
# 3 handler functions
def start_element(name, attrs):
print 'Start element:', name, attrs
def end_element(name):
print 'End element:', name
def char_data(data):
print 'Character data:', repr(data)
p = xml.parsers.expat.ParserCreate()
p.StartElementHandler = start_element
p.EndElementHandler = end_element
p.CharacterDataHandler = char_data
p.Parse("""<?xml version="1.0"?>
<parent id="top"><child1 name="paul">Text goes here</child1>
<child2 name="fred">More text</child2>
</parent>""", 1)
The output from this program is::
Start element: parent {'id': 'top'}
Start element: child1 {'name': 'paul'}
Character data: 'Text goes here'
End element: child1
Character data: '\n'
Start element: child2 {'name': 'fred'}
Character data: 'More text'
End element: child2
Character data: '\n'
End element: parent
.. _expat-content-models:
Content Model Descriptions
--------------------------
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
Content models are described using nested tuples. Each tuple contains four
values: the type, the quantifier, the name, and a tuple of children. Children
are simply additional content model descriptions.
The values of the first two fields are constants defined in the ``model`` object
of the :mod:`xml.parsers.expat` module. These constants can be collected in two
groups: the model type group and the quantifier group.
The constants in the model type group are:
.. data:: XML_CTYPE_ANY
:noindex:
The element named by the model name was declared to have a content model of
``ANY``.
.. data:: XML_CTYPE_CHOICE
:noindex:
The named element allows a choice from a number of options; this is used for
content models such as ``(A | B | C)``.
.. data:: XML_CTYPE_EMPTY
:noindex:
Elements which are declared to be ``EMPTY`` have this model type.
.. data:: XML_CTYPE_MIXED
:noindex:
.. data:: XML_CTYPE_NAME
:noindex:
.. data:: XML_CTYPE_SEQ
:noindex:
Models which represent a series of models which follow one after the other are
indicated with this model type. This is used for models such as ``(A, B, C)``.
The constants in the quantifier group are:
.. data:: XML_CQUANT_NONE
:noindex:
No modifier is given, so it can appear exactly once, as for ``A``.
.. data:: XML_CQUANT_OPT
:noindex:
The model is optional: it can appear once or not at all, as for ``A?``.
.. data:: XML_CQUANT_PLUS
:noindex:
The model must occur one or more times (like ``A+``).
.. data:: XML_CQUANT_REP
:noindex:
The model must occur zero or more times, as for ``A*``.
.. _expat-errors:
Expat error constants
---------------------
The following constants are provided in the ``errors`` object of the
:mod:`xml.parsers.expat` module. These constants are useful in interpreting
some of the attributes of the :exc:`ExpatError` exception objects raised when an
error has occurred.
The ``errors`` object has the following attributes:
.. data:: XML_ERROR_ASYNC_ENTITY
:noindex:
.. data:: XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF
:noindex:
An entity reference in an attribute value referred to an external entity instead
of an internal entity.
.. data:: XML_ERROR_BAD_CHAR_REF
:noindex:
A character reference referred to a character which is illegal in XML (for
example, character ``0``, or '``�``').
.. data:: XML_ERROR_BINARY_ENTITY_REF
:noindex:
An entity reference referred to an entity which was declared with a notation, so
cannot be parsed.
.. data:: XML_ERROR_DUPLICATE_ATTRIBUTE
:noindex:
An attribute was used more than once in a start tag.
.. data:: XML_ERROR_INCORRECT_ENCODING
:noindex:
.. data:: XML_ERROR_INVALID_TOKEN
:noindex:
Raised when an input byte could not properly be assigned to a character; for
example, a NUL byte (value ``0``) in a UTF-8 input stream.
.. data:: XML_ERROR_JUNK_AFTER_DOC_ELEMENT
:noindex:
Something other than whitespace occurred after the document element.
.. data:: XML_ERROR_MISPLACED_XML_PI
:noindex:
An XML declaration was found somewhere other than the start of the input data.
.. data:: XML_ERROR_NO_ELEMENTS
:noindex:
The document contains no elements (XML requires all documents to contain exactly
one top-level element)..
.. data:: XML_ERROR_NO_MEMORY
:noindex:
Expat was not able to allocate memory internally.
.. data:: XML_ERROR_PARAM_ENTITY_REF
:noindex:
A parameter entity reference was found where it was not allowed.
.. data:: XML_ERROR_PARTIAL_CHAR
:noindex:
An incomplete character was found in the input.
.. data:: XML_ERROR_RECURSIVE_ENTITY_REF
:noindex:
An entity reference contained another reference to the same entity; possibly via
a different name, and possibly indirectly.
.. data:: XML_ERROR_SYNTAX
:noindex:
Some unspecified syntax error was encountered.
.. data:: XML_ERROR_TAG_MISMATCH
:noindex:
An end tag did not match the innermost open start tag.
.. data:: XML_ERROR_UNCLOSED_TOKEN
:noindex:
Some token (such as a start tag) was not closed before the end of the stream or
the next token was encountered.
.. data:: XML_ERROR_UNDEFINED_ENTITY
:noindex:
A reference was made to an entity which was not defined.
.. data:: XML_ERROR_UNKNOWN_ENCODING
:noindex:
The document encoding is not supported by Expat.
.. data:: XML_ERROR_UNCLOSED_CDATA_SECTION
:noindex:
A CDATA marked section was not closed.
.. data:: XML_ERROR_EXTERNAL_ENTITY_HANDLING
:noindex:
.. data:: XML_ERROR_NOT_STANDALONE
:noindex:
The parser determined that the document was not "standalone" though it declared
itself to be in the XML declaration, and the :attr:`NotStandaloneHandler` was
set and returned ``0``.
.. data:: XML_ERROR_UNEXPECTED_STATE
:noindex:
.. data:: XML_ERROR_ENTITY_DECLARED_IN_PE
:noindex:
.. data:: XML_ERROR_FEATURE_REQUIRES_XML_DTD
:noindex:
An operation was requested that requires DTD support to be compiled in, but
Expat was configured without DTD support. This should never be reported by a
standard build of the :mod:`xml.parsers.expat` module.
.. data:: XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING
:noindex:
A behavioral change was requested after parsing started that can only be changed
before parsing has started. This is (currently) only raised by
:meth:`UseForeignDTD`.
.. data:: XML_ERROR_UNBOUND_PREFIX
:noindex:
An undeclared prefix was found when namespace processing was enabled.
.. data:: XML_ERROR_UNDECLARING_PREFIX
:noindex:
The document attempted to remove the namespace declaration associated with a
prefix.
.. data:: XML_ERROR_INCOMPLETE_PE
:noindex:
A parameter entity contained incomplete markup.
.. data:: XML_ERROR_XML_DECL
:noindex:
The document contained no document element at all.
.. data:: XML_ERROR_TEXT_DECL
:noindex:
There was an error parsing a text declaration in an external entity.
.. data:: XML_ERROR_PUBLICID
:noindex:
Characters were found in the public id that are not allowed.
.. data:: XML_ERROR_SUSPENDED
:noindex:
The requested operation was made on a suspended parser, but isn't allowed. This
includes attempts to provide additional input or to stop the parser.
.. data:: XML_ERROR_NOT_SUSPENDED
:noindex:
An attempt to resume the parser was made when the parser had not been suspended.
.. data:: XML_ERROR_ABORTED
:noindex:
This should not be reported to Python applications.
.. data:: XML_ERROR_FINISHED
:noindex:
The requested operation was made on a parser which was finished parsing input,
but isn't allowed. This includes attempts to provide additional input or to
stop the parser.
.. data:: XML_ERROR_SUSPEND_PE
:noindex:
.. rubric:: Footnotes
.. [1] The encoding string included in XML output should conform to the
appropriate standards. For example, "UTF-8" is valid, but "UTF8" is
not. See https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl
and https://www.iana.org/assignments/character-sets/character-sets.xhtml.
PK
%�\b�7q $ html/_sources/library/python.rst.txtnu �[���
.. _python:
***********************
Python Runtime Services
***********************
The modules described in this chapter provide a wide range of services related
to the Python interpreter and its interaction with its environment. Here's an
overview:
.. toctree::
sys.rst
sysconfig.rst
__builtin__.rst
future_builtins.rst
__main__.rst
warnings.rst
contextlib.rst
abc.rst
atexit.rst
traceback.rst
__future__.rst
gc.rst
inspect.rst
site.rst
user.rst
fpectl.rst
PK
%�\��6�z z # html/_sources/library/queue.rst.txtnu �[��� :mod:`Queue` --- A synchronized queue class
===========================================
.. module:: Queue
:synopsis: A synchronized queue class.
.. note::
The :mod:`Queue` module has been renamed to :mod:`queue` in Python 3. The
:term:`2to3` tool will automatically adapt imports when converting your
sources to Python 3.
**Source code:** :source:`Lib/Queue.py`
--------------
The :mod:`Queue` module implements multi-producer, multi-consumer queues.
It is especially useful in threaded programming when information must be
exchanged safely between multiple threads. The :class:`~Queue.Queue` class in this
module implements all the required locking semantics. It depends on the
availability of thread support in Python; see the :mod:`threading`
module.
The module implements three types of queue, which differ only in the order in
which the entries are retrieved. In a FIFO queue, the first tasks added are
the first retrieved. In a LIFO queue, the most recently added entry is
the first retrieved (operating like a stack). With a priority queue,
the entries are kept sorted (using the :mod:`heapq` module) and the
lowest valued entry is retrieved first.
The :mod:`Queue` module defines the following classes and exceptions:
.. class:: Queue(maxsize=0)
Constructor for a FIFO queue. *maxsize* is an integer that sets the upperbound
limit on the number of items that can be placed in the queue. Insertion will
block once this size has been reached, until queue items are consumed. If
*maxsize* is less than or equal to zero, the queue size is infinite.
.. class:: LifoQueue(maxsize=0)
Constructor for a LIFO queue. *maxsize* is an integer that sets the upperbound
limit on the number of items that can be placed in the queue. Insertion will
block once this size has been reached, until queue items are consumed. If
*maxsize* is less than or equal to zero, the queue size is infinite.
.. versionadded:: 2.6
.. class:: PriorityQueue(maxsize=0)
Constructor for a priority queue. *maxsize* is an integer that sets the upperbound
limit on the number of items that can be placed in the queue. Insertion will
block once this size has been reached, until queue items are consumed. If
*maxsize* is less than or equal to zero, the queue size is infinite.
The lowest valued entries are retrieved first (the lowest valued entry is the
one returned by ``sorted(list(entries))[0]``). A typical pattern for entries
is a tuple in the form: ``(priority_number, data)``.
.. versionadded:: 2.6
.. exception:: Empty
Exception raised when non-blocking :meth:`~Queue.get` (or
:meth:`~Queue.get_nowait`) is called
on a :class:`~Queue.Queue` object which is empty.
.. exception:: Full
Exception raised when non-blocking :meth:`~Queue.put` (or
:meth:`~Queue.put_nowait`) is called
on a :class:`~Queue.Queue` object which is full.
.. seealso::
:class:`collections.deque` is an alternative implementation of unbounded
queues with fast atomic :func:`append` and :func:`popleft` operations that
do not require locking.
.. _queueobjects:
Queue Objects
-------------
Queue objects (:class:`~Queue.Queue`, :class:`LifoQueue`, or :class:`PriorityQueue`)
provide the public methods described below.
.. method:: Queue.qsize()
Return the approximate size of the queue. Note, qsize() > 0 doesn't
guarantee that a subsequent get() will not block, nor will qsize() < maxsize
guarantee that put() will not block.
.. method:: Queue.empty()
Return ``True`` if the queue is empty, ``False`` otherwise. If empty()
returns ``True`` it doesn't guarantee that a subsequent call to put()
will not block. Similarly, if empty() returns ``False`` it doesn't
guarantee that a subsequent call to get() will not block.
.. method:: Queue.full()
Return ``True`` if the queue is full, ``False`` otherwise. If full()
returns ``True`` it doesn't guarantee that a subsequent call to get()
will not block. Similarly, if full() returns ``False`` it doesn't
guarantee that a subsequent call to put() will not block.
.. method:: Queue.put(item[, block[, timeout]])
Put *item* into the queue. If optional args *block* is true and *timeout* is
``None`` (the default), block if necessary until a free slot is available. If
*timeout* is a positive number, it blocks at most *timeout* seconds and raises
the :exc:`Full` exception if no free slot was available within that time.
Otherwise (*block* is false), put an item on the queue if a free slot is
immediately available, else raise the :exc:`Full` exception (*timeout* is
ignored in that case).
.. versionadded:: 2.3
The *timeout* parameter.
.. method:: Queue.put_nowait(item)
Equivalent to ``put(item, False)``.
.. method:: Queue.get([block[, timeout]])
Remove and return an item from the queue. If optional args *block* is true and
*timeout* is ``None`` (the default), block if necessary until an item is available.
If *timeout* is a positive number, it blocks at most *timeout* seconds and
raises the :exc:`Empty` exception if no item was available within that time.
Otherwise (*block* is false), return an item if one is immediately available,
else raise the :exc:`Empty` exception (*timeout* is ignored in that case).
.. versionadded:: 2.3
The *timeout* parameter.
.. method:: Queue.get_nowait()
Equivalent to ``get(False)``.
Two methods are offered to support tracking whether enqueued tasks have been
fully processed by daemon consumer threads.
.. method:: Queue.task_done()
Indicate that a formerly enqueued task is complete. Used by queue consumer
threads. For each :meth:`get` used to fetch a task, a subsequent call to
:meth:`task_done` tells the queue that the processing on the task is complete.
If a :meth:`join` is currently blocking, it will resume when all items have been
processed (meaning that a :meth:`task_done` call was received for every item
that had been :meth:`put` into the queue).
Raises a :exc:`ValueError` if called more times than there were items placed in
the queue.
.. versionadded:: 2.5
.. method:: Queue.join()
Blocks until all items in the queue have been gotten and processed.
The count of unfinished tasks goes up whenever an item is added to the queue.
The count goes down whenever a consumer thread calls :meth:`task_done` to
indicate that the item was retrieved and all work on it is complete. When the
count of unfinished tasks drops to zero, :meth:`join` unblocks.
.. versionadded:: 2.5
Example of how to wait for enqueued tasks to be completed::
def worker():
while True:
item = q.get()
do_work(item)
q.task_done()
q = Queue()
for i in range(num_worker_threads):
t = Thread(target=worker)
t.daemon = True
t.start()
for item in source():
q.put(item)
q.join() # block until all tasks are done
PK
%�\H�Un
n
$ html/_sources/library/quopri.rst.txtnu �[��� :mod:`quopri` --- Encode and decode MIME quoted-printable data
==============================================================
.. module:: quopri
:synopsis: Encode and decode files using the MIME quoted-printable encoding.
.. index::
pair: quoted-printable; encoding
single: MIME; quoted-printable encoding
**Source code:** :source:`Lib/quopri.py`
--------------
This module performs quoted-printable transport encoding and decoding, as
defined in :rfc:`1521`: "MIME (Multipurpose Internet Mail Extensions) Part One:
Mechanisms for Specifying and Describing the Format of Internet Message Bodies".
The quoted-printable encoding is designed for data where there are relatively
few nonprintable characters; the base64 encoding scheme available via the
:mod:`base64` module is more compact if there are many such characters, as when
sending a graphics file.
.. function:: decode(input, output[,header])
Decode the contents of the *input* file and write the resulting decoded binary
data to the *output* file. *input* and *output* must either be file objects or
objects that mimic the file object interface. *input* will be read until
``input.readline()`` returns an empty string. If the optional argument *header*
is present and true, underscore will be decoded as space. This is used to decode
"Q"-encoded headers as described in :rfc:`1522`: "MIME (Multipurpose Internet
Mail Extensions) Part Two: Message Header Extensions for Non-ASCII Text".
.. function:: encode(input, output, quotetabs)
Encode the contents of the *input* file and write the resulting quoted-printable
data to the *output* file. *input* and *output* must either be file objects or
objects that mimic the file object interface. *input* will be read until
``input.readline()`` returns an empty string. *quotetabs* is a flag which
controls whether to encode embedded spaces and tabs; when true it encodes such
embedded whitespace, and when false it leaves them unencoded. Note that spaces
and tabs appearing at the end of lines are always encoded, as per :rfc:`1521`.
.. function:: decodestring(s[,header])
Like :func:`decode`, except that it accepts a source string and returns the
corresponding decoded string.
.. function:: encodestring(s[, quotetabs])
Like :func:`encode`, except that it accepts a source string and returns the
corresponding encoded string. *quotetabs* is optional (defaulting to 0), and is
passed straight through to :func:`encode`.
.. seealso::
Module :mod:`mimify`
General utilities for processing of MIME messages.
Module :mod:`base64`
Encode and decode MIME base64 data
PK
%�\�V�-4 4 $ html/_sources/library/random.rst.txtnu �[��� :mod:`random` --- Generate pseudo-random numbers
================================================
.. module:: random
:synopsis: Generate pseudo-random numbers with various common distributions.
**Source code:** :source:`Lib/random.py`
--------------
This module implements pseudo-random number generators for various
distributions.
For integers, uniform selection from a range. For sequences, uniform selection
of a random element, a function to generate a random permutation of a list
in-place, and a function for random sampling without replacement.
On the real line, there are functions to compute uniform, normal (Gaussian),
lognormal, negative exponential, gamma, and beta distributions. For generating
distributions of angles, the von Mises distribution is available.
Almost all module functions depend on the basic function :func:`.random`, which
generates a random float uniformly in the semi-open range [0.0, 1.0). Python
uses the Mersenne Twister as the core generator. It produces 53-bit precision
floats and has a period of 2\*\*19937-1. The underlying implementation in C is
both fast and threadsafe. The Mersenne Twister is one of the most extensively
tested random number generators in existence. However, being completely
deterministic, it is not suitable for all purposes, and is completely unsuitable
for cryptographic purposes.
The functions supplied by this module are actually bound methods of a hidden
instance of the :class:`random.Random` class. You can instantiate your own
instances of :class:`Random` to get generators that don't share state. This is
especially useful for multi-threaded programs, creating a different instance of
:class:`Random` for each thread, and using the :meth:`jumpahead` method to make
it likely that the generated sequences seen by each thread don't overlap.
Class :class:`Random` can also be subclassed if you want to use a different
basic generator of your own devising: in that case, override the :meth:`~Random.random`,
:meth:`~Random.seed`, :meth:`~Random.getstate`, :meth:`~Random.setstate` and
:meth:`~Random.jumpahead` methods. Optionally, a new generator can supply a
:meth:`~Random.getrandbits` method --- this
allows :meth:`randrange` to produce selections over an arbitrarily large range.
.. versionadded:: 2.4
the :meth:`getrandbits` method.
As an example of subclassing, the :mod:`random` module provides the
:class:`WichmannHill` class that implements an alternative generator in pure
Python. The class provides a backward compatible way to reproduce results from
earlier versions of Python, which used the Wichmann-Hill algorithm as the core
generator. Note that this Wichmann-Hill generator can no longer be recommended:
its period is too short by contemporary standards, and the sequence generated is
known to fail some stringent randomness tests. See the references below for a
recent variant that repairs these flaws.
.. versionchanged:: 2.3
MersenneTwister replaced Wichmann-Hill as the default generator.
The :mod:`random` module also provides the :class:`SystemRandom` class which
uses the system function :func:`os.urandom` to generate random numbers
from sources provided by the operating system.
.. warning::
The pseudo-random generators of this module should not be used for
security purposes. Use :func:`os.urandom` or :class:`SystemRandom` if
you require a cryptographically secure pseudo-random number generator.
Bookkeeping functions:
.. function:: seed(a=None)
Initialize internal state of the random number generator.
``None`` or no argument seeds from current time or from an operating
system specific randomness source if available (see the :func:`os.urandom`
function for details on availability).
If *a* is not ``None`` or an :class:`int` or a :class:`long`, then
``hash(a)`` is used instead. Note that the hash values for some types
are nondeterministic when :envvar:`PYTHONHASHSEED` is enabled.
.. versionchanged:: 2.4
formerly, operating system resources were not used.
.. function:: getstate()
Return an object capturing the current internal state of the generator. This
object can be passed to :func:`setstate` to restore the state.
.. versionadded:: 2.1
.. versionchanged:: 2.6
State values produced in Python 2.6 cannot be loaded into earlier versions.
.. function:: setstate(state)
*state* should have been obtained from a previous call to :func:`getstate`, and
:func:`setstate` restores the internal state of the generator to what it was at
the time :func:`getstate` was called.
.. versionadded:: 2.1
.. function:: jumpahead(n)
Change the internal state to one different from and likely far away from the
current state. *n* is a non-negative integer which is used to scramble the
current state vector. This is most useful in multi-threaded programs, in
conjunction with multiple instances of the :class:`Random` class:
:meth:`setstate` or :meth:`seed` can be used to force all instances into the
same internal state, and then :meth:`jumpahead` can be used to force the
instances' states far apart.
.. versionadded:: 2.1
.. versionchanged:: 2.3
Instead of jumping to a specific state, *n* steps ahead, ``jumpahead(n)``
jumps to another state likely to be separated by many steps.
.. function:: getrandbits(k)
Returns a python :class:`long` int with *k* random bits. This method is supplied
with the MersenneTwister generator and some other generators may also provide it
as an optional part of the API. When available, :meth:`getrandbits` enables
:meth:`randrange` to handle arbitrarily large ranges.
.. versionadded:: 2.4
Functions for integers:
.. function:: randrange(stop)
randrange(start, stop[, step])
Return a randomly selected element from ``range(start, stop, step)``. This is
equivalent to ``choice(range(start, stop, step))``, but doesn't actually build a
range object.
.. versionadded:: 1.5.2
.. function:: randint(a, b)
Return a random integer *N* such that ``a <= N <= b``.
Functions for sequences:
.. function:: choice(seq)
Return a random element from the non-empty sequence *seq*. If *seq* is empty,
raises :exc:`IndexError`.
.. function:: shuffle(x[, random])
Shuffle the sequence *x* in place. The optional argument *random* is a
0-argument function returning a random float in [0.0, 1.0); by default, this is
the function :func:`.random`.
Note that for even rather small ``len(x)``, the total number of permutations of
*x* is larger than the period of most random number generators; this implies
that most permutations of a long sequence can never be generated.
.. function:: sample(population, k)
Return a *k* length list of unique elements chosen from the population sequence.
Used for random sampling without replacement.
.. versionadded:: 2.3
Returns a new list containing elements from the population while leaving the
original population unchanged. The resulting list is in selection order so that
all sub-slices will also be valid random samples. This allows raffle winners
(the sample) to be partitioned into grand prize and second place winners (the
subslices).
Members of the population need not be :term:`hashable` or unique. If the population
contains repeats, then each occurrence is a possible selection in the sample.
To choose a sample from a range of integers, use an :func:`xrange` object as an
argument. This is especially fast and space efficient for sampling from a large
population: ``sample(xrange(10000000), 60)``.
The following functions generate specific real-valued distributions. Function
parameters are named after the corresponding variables in the distribution's
equation, as used in common mathematical practice; most of these equations can
be found in any statistics text.
.. function:: random()
Return the next random floating point number in the range [0.0, 1.0).
.. function:: uniform(a, b)
Return a random floating point number *N* such that ``a <= N <= b`` for
``a <= b`` and ``b <= N <= a`` for ``b < a``.
The end-point value ``b`` may or may not be included in the range
depending on floating-point rounding in the equation ``a + (b-a) * random()``.
.. function:: triangular(low, high, mode)
Return a random floating point number *N* such that ``low <= N <= high`` and
with the specified *mode* between those bounds. The *low* and *high* bounds
default to zero and one. The *mode* argument defaults to the midpoint
between the bounds, giving a symmetric distribution.
.. versionadded:: 2.6
.. function:: betavariate(alpha, beta)
Beta distribution. Conditions on the parameters are ``alpha > 0`` and
``beta > 0``. Returned values range between 0 and 1.
.. function:: expovariate(lambd)
Exponential distribution. *lambd* is 1.0 divided by the desired
mean. It should be nonzero. (The parameter would be called
"lambda", but that is a reserved word in Python.) Returned values
range from 0 to positive infinity if *lambd* is positive, and from
negative infinity to 0 if *lambd* is negative.
.. function:: gammavariate(alpha, beta)
Gamma distribution. (*Not* the gamma function!) Conditions on the
parameters are ``alpha > 0`` and ``beta > 0``.
The probability distribution function is::
x ** (alpha - 1) * math.exp(-x / beta)
pdf(x) = --------------------------------------
math.gamma(alpha) * beta ** alpha
.. function:: gauss(mu, sigma)
Gaussian distribution. *mu* is the mean, and *sigma* is the standard
deviation. This is slightly faster than the :func:`normalvariate` function
defined below.
.. function:: lognormvariate(mu, sigma)
Log normal distribution. If you take the natural logarithm of this
distribution, you'll get a normal distribution with mean *mu* and standard
deviation *sigma*. *mu* can have any value, and *sigma* must be greater than
zero.
.. function:: normalvariate(mu, sigma)
Normal distribution. *mu* is the mean, and *sigma* is the standard deviation.
.. function:: vonmisesvariate(mu, kappa)
*mu* is the mean angle, expressed in radians between 0 and 2\*\ *pi*, and *kappa*
is the concentration parameter, which must be greater than or equal to zero. If
*kappa* is equal to zero, this distribution reduces to a uniform random angle
over the range 0 to 2\*\ *pi*.
.. function:: paretovariate(alpha)
Pareto distribution. *alpha* is the shape parameter.
.. function:: weibullvariate(alpha, beta)
Weibull distribution. *alpha* is the scale parameter and *beta* is the shape
parameter.
Alternative Generators:
.. class:: WichmannHill([seed])
Class that implements the Wichmann-Hill algorithm as the core generator. Has all
of the same methods as :class:`Random` plus the :meth:`whseed` method described
below. Because this class is implemented in pure Python, it is not threadsafe
and may require locks between calls. The period of the generator is
6,953,607,871,644 which is small enough to require care that two independent
random sequences do not overlap.
.. function:: whseed([x])
This is obsolete, supplied for bit-level compatibility with versions of Python
prior to 2.1. See :func:`seed` for details. :func:`whseed` does not guarantee
that distinct integer arguments yield distinct internal states, and can yield no
more than about 2\*\*24 distinct internal states in all.
.. class:: SystemRandom([seed])
Class that uses the :func:`os.urandom` function for generating random numbers
from sources provided by the operating system. Not available on all systems.
Does not rely on software state and sequences are not reproducible. Accordingly,
the :meth:`seed` and :meth:`jumpahead` methods have no effect and are ignored.
The :meth:`getstate` and :meth:`setstate` methods raise
:exc:`NotImplementedError` if called.
.. versionadded:: 2.4
Examples of basic usage::
>>> random.random() # Random float x, 0.0 <= x < 1.0
0.37444887175646646
>>> random.uniform(1, 10) # Random float x, 1.0 <= x < 10.0
1.1800146073117523
>>> random.randint(1, 10) # Integer from 1 to 10, endpoints included
7
>>> random.randrange(0, 101, 2) # Even integer from 0 to 100
26
>>> random.choice('abcdefghij') # Choose a random element
'c'
>>> items = [1, 2, 3, 4, 5, 6, 7]
>>> random.shuffle(items)
>>> items
[7, 3, 2, 5, 6, 4, 1]
>>> random.sample([1, 2, 3, 4, 5], 3) # Choose 3 elements
[4, 1, 5]
.. seealso::
M. Matsumoto and T. Nishimura, "Mersenne Twister: A 623-dimensionally
equidistributed uniform pseudorandom number generator", ACM Transactions on
Modeling and Computer Simulation Vol. 8, No. 1, January pp.3--30 1998.
Wichmann, B. A. & Hill, I. D., "Algorithm AS 183: An efficient and portable
pseudo-random number generator", Applied Statistics 31 (1982) 188-190.
`Complementary-Multiply-with-Carry recipe
<http://code.activestate.com/recipes/576707/>`_ for a compatible alternative
random number generator with a long period and comparatively simple update
operations.
PK
%�\�f!�>� >� html/_sources/library/re.rst.txtnu �[���
:mod:`re` --- Regular expression operations
===========================================
.. module:: re
:synopsis: Regular expression operations.
.. moduleauthor:: Fredrik Lundh <fredrik@pythonware.com>
.. sectionauthor:: Andrew M. Kuchling <amk@amk.ca>
This module provides regular expression matching operations similar to
those found in Perl. Both patterns and strings to be searched can be
Unicode strings as well as 8-bit strings.
Regular expressions use the backslash character (``'\'``) to indicate
special forms or to allow special characters to be used without invoking
their special meaning. This collides with Python's usage of the same
character for the same purpose in string literals; for example, to match
a literal backslash, one might have to write ``'\\\\'`` as the pattern
string, because the regular expression must be ``\\``, and each
backslash must be expressed as ``\\`` inside a regular Python string
literal.
The solution is to use Python's raw string notation for regular expression
patterns; backslashes are not handled in any special way in a string literal
prefixed with ``'r'``. So ``r"\n"`` is a two-character string containing
``'\'`` and ``'n'``, while ``"\n"`` is a one-character string containing a
newline. Usually patterns will be expressed in Python code using this raw
string notation.
It is important to note that most regular expression operations are available as
module-level functions and :class:`RegexObject` methods. The functions are
shortcuts that don't require you to compile a regex object first, but miss some
fine-tuning parameters.
.. seealso::
The third-party `regex <https://pypi.org/project/regex/>`_ module,
which has an API compatible with the standard library :mod:`re` module,
but offers additional functionality and a more thorough Unicode support.
.. _re-syntax:
Regular Expression Syntax
-------------------------
A regular expression (or RE) specifies a set of strings that matches it; the
functions in this module let you check if a particular string matches a given
regular expression (or if a given regular expression matches a particular
string, which comes down to the same thing).
Regular expressions can be concatenated to form new regular expressions; if *A*
and *B* are both regular expressions, then *AB* is also a regular expression.
In general, if a string *p* matches *A* and another string *q* matches *B*, the
string *pq* will match AB. This holds unless *A* or *B* contain low precedence
operations; boundary conditions between *A* and *B*; or have numbered group
references. Thus, complex expressions can easily be constructed from simpler
primitive expressions like the ones described here. For details of the theory
and implementation of regular expressions, consult the Friedl book referenced
above, or almost any textbook about compiler construction.
A brief explanation of the format of regular expressions follows. For further
information and a gentler presentation, consult the :ref:`regex-howto`.
Regular expressions can contain both special and ordinary characters. Most
ordinary characters, like ``'A'``, ``'a'``, or ``'0'``, are the simplest regular
expressions; they simply match themselves. You can concatenate ordinary
characters, so ``last`` matches the string ``'last'``. (In the rest of this
section, we'll write RE's in ``this special style``, usually without quotes, and
strings to be matched ``'in single quotes'``.)
Some characters, like ``'|'`` or ``'('``, are special. Special
characters either stand for classes of ordinary characters, or affect
how the regular expressions around them are interpreted. Regular
expression pattern strings may not contain null bytes, but can specify
the null byte using the ``\number`` notation, e.g., ``'\x00'``.
Repetition qualifiers (``*``, ``+``, ``?``, ``{m,n}``, etc) cannot be
directly nested. This avoids ambiguity with the non-greedy modifier suffix
``?``, and with other modifiers in other implementations. To apply a second
repetition to an inner repetition, parentheses may be used. For example,
the expression ``(?:a{6})*`` matches any multiple of six ``'a'`` characters.
The special characters are:
``'.'``
(Dot.) In the default mode, this matches any character except a newline. If
the :const:`DOTALL` flag has been specified, this matches any character
including a newline.
``'^'``
(Caret.) Matches the start of the string, and in :const:`MULTILINE` mode also
matches immediately after each newline.
``'$'``
Matches the end of the string or just before the newline at the end of the
string, and in :const:`MULTILINE` mode also matches before a newline. ``foo``
matches both 'foo' and 'foobar', while the regular expression ``foo$`` matches
only 'foo'. More interestingly, searching for ``foo.$`` in ``'foo1\nfoo2\n'``
matches 'foo2' normally, but 'foo1' in :const:`MULTILINE` mode; searching for
a single ``$`` in ``'foo\n'`` will find two (empty) matches: one just before
the newline, and one at the end of the string.
``'*'``
Causes the resulting RE to match 0 or more repetitions of the preceding RE, as
many repetitions as are possible. ``ab*`` will match 'a', 'ab', or 'a' followed
by any number of 'b's.
``'+'``
Causes the resulting RE to match 1 or more repetitions of the preceding RE.
``ab+`` will match 'a' followed by any non-zero number of 'b's; it will not
match just 'a'.
``'?'``
Causes the resulting RE to match 0 or 1 repetitions of the preceding RE.
``ab?`` will match either 'a' or 'ab'.
``*?``, ``+?``, ``??``
The ``'*'``, ``'+'``, and ``'?'`` qualifiers are all :dfn:`greedy`; they match
as much text as possible. Sometimes this behaviour isn't desired; if the RE
``<.*>`` is matched against ``<a> b <c>``, it will match the entire
string, and not just ``<a>``. Adding ``?`` after the qualifier makes it
perform the match in :dfn:`non-greedy` or :dfn:`minimal` fashion; as *few*
characters as possible will be matched. Using the RE ``<.*?>`` will match
only ``<a>``.
``{m}``
Specifies that exactly *m* copies of the previous RE should be matched; fewer
matches cause the entire RE not to match. For example, ``a{6}`` will match
exactly six ``'a'`` characters, but not five.
``{m,n}``
Causes the resulting RE to match from *m* to *n* repetitions of the preceding
RE, attempting to match as many repetitions as possible. For example,
``a{3,5}`` will match from 3 to 5 ``'a'`` characters. Omitting *m* specifies a
lower bound of zero, and omitting *n* specifies an infinite upper bound. As an
example, ``a{4,}b`` will match ``aaaab`` or a thousand ``'a'`` characters
followed by a ``b``, but not ``aaab``. The comma may not be omitted or the
modifier would be confused with the previously described form.
``{m,n}?``
Causes the resulting RE to match from *m* to *n* repetitions of the preceding
RE, attempting to match as *few* repetitions as possible. This is the
non-greedy version of the previous qualifier. For example, on the
6-character string ``'aaaaaa'``, ``a{3,5}`` will match 5 ``'a'`` characters,
while ``a{3,5}?`` will only match 3 characters.
``'\'``
Either escapes special characters (permitting you to match characters like
``'*'``, ``'?'``, and so forth), or signals a special sequence; special
sequences are discussed below.
If you're not using a raw string to express the pattern, remember that Python
also uses the backslash as an escape sequence in string literals; if the escape
sequence isn't recognized by Python's parser, the backslash and subsequent
character are included in the resulting string. However, if Python would
recognize the resulting sequence, the backslash should be repeated twice. This
is complicated and hard to understand, so it's highly recommended that you use
raw strings for all but the simplest expressions.
``[]``
Used to indicate a set of characters. In a set:
* Characters can be listed individually, e.g. ``[amk]`` will match ``'a'``,
``'m'``, or ``'k'``.
* Ranges of characters can be indicated by giving two characters and separating
them by a ``'-'``, for example ``[a-z]`` will match any lowercase ASCII letter,
``[0-5][0-9]`` will match all the two-digits numbers from ``00`` to ``59``, and
``[0-9A-Fa-f]`` will match any hexadecimal digit. If ``-`` is escaped (e.g.
``[a\-z]``) or if it's placed as the first or last character (e.g. ``[a-]``),
it will match a literal ``'-'``.
* Special characters lose their special meaning inside sets. For example,
``[(+*)]`` will match any of the literal characters ``'('``, ``'+'``,
``'*'``, or ``')'``.
* Character classes such as ``\w`` or ``\S`` (defined below) are also accepted
inside a set, although the characters they match depends on whether
:const:`LOCALE` or :const:`UNICODE` mode is in force.
* Characters that are not within a range can be matched by :dfn:`complementing`
the set. If the first character of the set is ``'^'``, all the characters
that are *not* in the set will be matched. For example, ``[^5]`` will match
any character except ``'5'``, and ``[^^]`` will match any character except
``'^'``. ``^`` has no special meaning if it's not the first character in
the set.
* To match a literal ``']'`` inside a set, precede it with a backslash, or
place it at the beginning of the set. For example, both ``[()[\]{}]`` and
``[]()[{}]`` will both match a parenthesis.
``'|'``
``A|B``, where A and B can be arbitrary REs, creates a regular expression that
will match either A or B. An arbitrary number of REs can be separated by the
``'|'`` in this way. This can be used inside groups (see below) as well. As
the target string is scanned, REs separated by ``'|'`` are tried from left to
right. When one pattern completely matches, that branch is accepted. This means
that once ``A`` matches, ``B`` will not be tested further, even if it would
produce a longer overall match. In other words, the ``'|'`` operator is never
greedy. To match a literal ``'|'``, use ``\|``, or enclose it inside a
character class, as in ``[|]``.
``(...)``
Matches whatever regular expression is inside the parentheses, and indicates the
start and end of a group; the contents of a group can be retrieved after a match
has been performed, and can be matched later in the string with the ``\number``
special sequence, described below. To match the literals ``'('`` or ``')'``,
use ``\(`` or ``\)``, or enclose them inside a character class: ``[(] [)]``.
``(?...)``
This is an extension notation (a ``'?'`` following a ``'('`` is not meaningful
otherwise). The first character after the ``'?'`` determines what the meaning
and further syntax of the construct is. Extensions usually do not create a new
group; ``(?P<name>...)`` is the only exception to this rule. Following are the
currently supported extensions.
``(?iLmsux)``
(One or more letters from the set ``'i'``, ``'L'``, ``'m'``, ``'s'``,
``'u'``, ``'x'``.) The group matches the empty string; the letters
set the corresponding flags: :const:`re.I` (ignore case),
:const:`re.L` (locale dependent), :const:`re.M` (multi-line),
:const:`re.S` (dot matches all), :const:`re.U` (Unicode dependent),
and :const:`re.X` (verbose), for the entire regular expression. (The
flags are described in :ref:`contents-of-module-re`.) This
is useful if you wish to include the flags as part of the regular
expression, instead of passing a *flag* argument to the
:func:`re.compile` function.
Note that the ``(?x)`` flag changes how the expression is parsed. It should be
used first in the expression string, or after one or more whitespace characters.
If there are non-whitespace characters before the flag, the results are
undefined.
``(?:...)``
A non-capturing version of regular parentheses. Matches whatever regular
expression is inside the parentheses, but the substring matched by the group
*cannot* be retrieved after performing a match or referenced later in the
pattern.
``(?P<name>...)``
Similar to regular parentheses, but the substring matched by the group is
accessible via the symbolic group name *name*. Group names must be valid
Python identifiers, and each group name must be defined only once within a
regular expression. A symbolic group is also a numbered group, just as if
the group were not named.
Named groups can be referenced in three contexts. If the pattern is
``(?P<quote>['"]).*?(?P=quote)`` (i.e. matching a string quoted with either
single or double quotes):
+---------------------------------------+----------------------------------+
| Context of reference to group "quote" | Ways to reference it |
+=======================================+==================================+
| in the same pattern itself | * ``(?P=quote)`` (as shown) |
| | * ``\1`` |
+---------------------------------------+----------------------------------+
| when processing match object ``m`` | * ``m.group('quote')`` |
| | * ``m.end('quote')`` (etc.) |
+---------------------------------------+----------------------------------+
| in a string passed to the ``repl`` | * ``\g<quote>`` |
| argument of ``re.sub()`` | * ``\g<1>`` |
| | * ``\1`` |
+---------------------------------------+----------------------------------+
``(?P=name)``
A backreference to a named group; it matches whatever text was matched by the
earlier group named *name*.
``(?#...)``
A comment; the contents of the parentheses are simply ignored.
``(?=...)``
Matches if ``...`` matches next, but doesn't consume any of the string. This is
called a lookahead assertion. For example, ``Isaac (?=Asimov)`` will match
``'Isaac '`` only if it's followed by ``'Asimov'``.
``(?!...)``
Matches if ``...`` doesn't match next. This is a negative lookahead assertion.
For example, ``Isaac (?!Asimov)`` will match ``'Isaac '`` only if it's *not*
followed by ``'Asimov'``.
``(?<=...)``
Matches if the current position in the string is preceded by a match for ``...``
that ends at the current position. This is called a :dfn:`positive lookbehind
assertion`. ``(?<=abc)def`` will find a match in ``abcdef``, since the
lookbehind will back up 3 characters and check if the contained pattern matches.
The contained pattern must only match strings of some fixed length, meaning that
``abc`` or ``a|b`` are allowed, but ``a*`` and ``a{3,4}`` are not. Group
references are not supported even if they match strings of some fixed length.
Note that
patterns which start with positive lookbehind assertions will not match at the
beginning of the string being searched; you will most likely want to use the
:func:`search` function rather than the :func:`match` function:
>>> import re
>>> m = re.search('(?<=abc)def', 'abcdef')
>>> m.group(0)
'def'
This example looks for a word following a hyphen:
>>> m = re.search('(?<=-)\w+', 'spam-egg')
>>> m.group(0)
'egg'
``(?<!...)``
Matches if the current position in the string is not preceded by a match for
``...``. This is called a :dfn:`negative lookbehind assertion`. Similar to
positive lookbehind assertions, the contained pattern must only match strings of
some fixed length and shouldn't contain group references.
Patterns which start with negative lookbehind assertions may
match at the beginning of the string being searched.
``(?(id/name)yes-pattern|no-pattern)``
Will try to match with ``yes-pattern`` if the group with given *id* or *name*
exists, and with ``no-pattern`` if it doesn't. ``no-pattern`` is optional and
can be omitted. For example, ``(<)?(\w+@\w+(?:\.\w+)+)(?(1)>)`` is a poor email
matching pattern, which will match with ``'<user@host.com>'`` as well as
``'user@host.com'``, but not with ``'<user@host.com'``.
.. versionadded:: 2.4
The special sequences consist of ``'\'`` and a character from the list below.
If the ordinary character is not on the list, then the resulting RE will match
the second character. For example, ``\$`` matches the character ``'$'``.
``\number``
Matches the contents of the group of the same number. Groups are numbered
starting from 1. For example, ``(.+) \1`` matches ``'the the'`` or ``'55 55'``,
but not ``'thethe'`` (note the space after the group). This special sequence
can only be used to match one of the first 99 groups. If the first digit of
*number* is 0, or *number* is 3 octal digits long, it will not be interpreted as
a group match, but as the character with octal value *number*. Inside the
``'['`` and ``']'`` of a character class, all numeric escapes are treated as
characters.
``\A``
Matches only at the start of the string.
``\b``
Matches the empty string, but only at the beginning or end of a word. A word is
defined as a sequence of alphanumeric or underscore characters, so the end of a
word is indicated by whitespace or a non-alphanumeric, non-underscore character.
Note that formally, ``\b`` is defined as the boundary between a ``\w`` and
a ``\W`` character (or vice versa), or between ``\w`` and the beginning/end
of the string, so the precise set of characters deemed to be alphanumeric
depends on the values of the ``UNICODE`` and ``LOCALE`` flags.
For example, ``r'\bfoo\b'`` matches ``'foo'``, ``'foo.'``, ``'(foo)'``,
``'bar foo baz'`` but not ``'foobar'`` or ``'foo3'``.
Inside a character range, ``\b`` represents the backspace character, for
compatibility with Python's string literals.
``\B``
Matches the empty string, but only when it is *not* at the beginning or end of a
word. This means that ``r'py\B'`` matches ``'python'``, ``'py3'``, ``'py2'``,
but not ``'py'``, ``'py.'``, or ``'py!'``.
``\B`` is just the opposite of ``\b``, so is also subject to the settings
of ``LOCALE`` and ``UNICODE``.
``\d``
When the :const:`UNICODE` flag is not specified, matches any decimal digit; this
is equivalent to the set ``[0-9]``. With :const:`UNICODE`, it will match
whatever is classified as a decimal digit in the Unicode character properties
database.
``\D``
When the :const:`UNICODE` flag is not specified, matches any non-digit
character; this is equivalent to the set ``[^0-9]``. With :const:`UNICODE`, it
will match anything other than character marked as digits in the Unicode
character properties database.
``\s``
When the :const:`UNICODE` flag is not specified, it matches any whitespace
character, this is equivalent to the set ``[ \t\n\r\f\v]``. The
:const:`LOCALE` flag has no extra effect on matching of the space.
If :const:`UNICODE` is set, this will match the characters ``[ \t\n\r\f\v]``
plus whatever is classified as space in the Unicode character properties
database.
``\S``
When the :const:`UNICODE` flag is not specified, matches any non-whitespace
character; this is equivalent to the set ``[^ \t\n\r\f\v]`` The
:const:`LOCALE` flag has no extra effect on non-whitespace match. If
:const:`UNICODE` is set, then any character not marked as space in the
Unicode character properties database is matched.
``\w``
When the :const:`LOCALE` and :const:`UNICODE` flags are not specified, matches
any alphanumeric character and the underscore; this is equivalent to the set
``[a-zA-Z0-9_]``. With :const:`LOCALE`, it will match the set ``[0-9_]`` plus
whatever characters are defined as alphanumeric for the current locale. If
:const:`UNICODE` is set, this will match the characters ``[0-9_]`` plus whatever
is classified as alphanumeric in the Unicode character properties database.
``\W``
When the :const:`LOCALE` and :const:`UNICODE` flags are not specified, matches
any non-alphanumeric character; this is equivalent to the set ``[^a-zA-Z0-9_]``.
With :const:`LOCALE`, it will match any character not in the set ``[0-9_]``, and
not defined as alphanumeric for the current locale. If :const:`UNICODE` is set,
this will match anything other than ``[0-9_]`` plus characters classified as
not alphanumeric in the Unicode character properties database.
``\Z``
Matches only at the end of the string.
If both :const:`LOCALE` and :const:`UNICODE` flags are included for a
particular sequence, then :const:`LOCALE` flag takes effect first followed by
the :const:`UNICODE`.
Most of the standard escapes supported by Python string literals are also
accepted by the regular expression parser::
\a \b \f \n
\r \t \v \x
\\
(Note that ``\b`` is used to represent word boundaries, and means "backspace"
only inside character classes.)
Octal escapes are included in a limited form: If the first digit is a 0, or if
there are three octal digits, it is considered an octal escape. Otherwise, it is
a group reference. As for string literals, octal escapes are always at most
three digits in length.
.. seealso::
Mastering Regular Expressions
Book on regular expressions by Jeffrey Friedl, published by O'Reilly. The
second edition of the book no longer covers Python at all, but the first
edition covered writing good regular expression patterns in great detail.
.. _contents-of-module-re:
Module Contents
---------------
The module defines several functions, constants, and an exception. Some of the
functions are simplified versions of the full featured methods for compiled
regular expressions. Most non-trivial applications always use the compiled
form.
.. function:: compile(pattern, flags=0)
Compile a regular expression pattern into a regular expression object, which
can be used for matching using its :func:`~RegexObject.match` and
:func:`~RegexObject.search` methods, described below.
The expression's behaviour can be modified by specifying a *flags* value.
Values can be any of the following variables, combined using bitwise OR (the
``|`` operator).
The sequence ::
prog = re.compile(pattern)
result = prog.match(string)
is equivalent to ::
result = re.match(pattern, string)
but using :func:`re.compile` and saving the resulting regular expression
object for reuse is more efficient when the expression will be used several
times in a single program.
.. note::
The compiled versions of the most recent patterns passed to
:func:`re.match`, :func:`re.search` or :func:`re.compile` are cached, so
programs that use only a few regular expressions at a time needn't worry
about compiling regular expressions.
.. data:: DEBUG
Display debug information about compiled expression.
.. data:: I
IGNORECASE
Perform case-insensitive matching; expressions like ``[A-Z]`` will match
lowercase letters, too. This is not affected by the current locale. To
get this effect on non-ASCII Unicode characters such as ``ü`` and ``Ü``,
add the :const:`UNICODE` flag.
.. data:: L
LOCALE
Make ``\w``, ``\W``, ``\b``, ``\B``, ``\s`` and ``\S`` dependent on the
current locale.
.. data:: M
MULTILINE
When specified, the pattern character ``'^'`` matches at the beginning of the
string and at the beginning of each line (immediately following each newline);
and the pattern character ``'$'`` matches at the end of the string and at the
end of each line (immediately preceding each newline). By default, ``'^'``
matches only at the beginning of the string, and ``'$'`` only at the end of the
string and immediately before the newline (if any) at the end of the string.
.. data:: S
DOTALL
Make the ``'.'`` special character match any character at all, including a
newline; without this flag, ``'.'`` will match anything *except* a newline.
.. data:: U
UNICODE
Make the ``\w``, ``\W``, ``\b``, ``\B``, ``\d``, ``\D``, ``\s`` and ``\S``
sequences dependent on the Unicode character properties database. Also
enables non-ASCII matching for :const:`IGNORECASE`.
.. versionadded:: 2.0
.. data:: X
VERBOSE
This flag allows you to write regular expressions that look nicer and are
more readable by allowing you to visually separate logical sections of the
pattern and add comments. Whitespace within the pattern is ignored, except
when in a character class, or when preceded by an unescaped backslash,
or within tokens like ``*?``, ``(?:`` or ``(?P<...>``.
When a line contains a ``#`` that is not in a character class and is not
preceded by an unescaped backslash, all characters from the leftmost such
``#`` through the end of the line are ignored.
This means that the two following regular expression objects that match a
decimal number are functionally equal::
a = re.compile(r"""\d + # the integral part
\. # the decimal point
\d * # some fractional digits""", re.X)
b = re.compile(r"\d+\.\d*")
.. function:: search(pattern, string, flags=0)
Scan through *string* looking for the first location where the regular expression
*pattern* produces a match, and return a corresponding :class:`MatchObject`
instance. Return ``None`` if no position in the string matches the pattern; note
that this is different from finding a zero-length match at some point in the
string.
.. function:: match(pattern, string, flags=0)
If zero or more characters at the beginning of *string* match the regular
expression *pattern*, return a corresponding :class:`MatchObject` instance.
Return ``None`` if the string does not match the pattern; note that this is
different from a zero-length match.
Note that even in :const:`MULTILINE` mode, :func:`re.match` will only match
at the beginning of the string and not at the beginning of each line.
If you want to locate a match anywhere in *string*, use :func:`search`
instead (see also :ref:`search-vs-match`).
.. function:: split(pattern, string, maxsplit=0, flags=0)
Split *string* by the occurrences of *pattern*. If capturing parentheses are
used in *pattern*, then the text of all groups in the pattern are also returned
as part of the resulting list. If *maxsplit* is nonzero, at most *maxsplit*
splits occur, and the remainder of the string is returned as the final element
of the list. (Incompatibility note: in the original Python 1.5 release,
*maxsplit* was ignored. This has been fixed in later releases.)
>>> re.split('\W+', 'Words, words, words.')
['Words', 'words', 'words', '']
>>> re.split('(\W+)', 'Words, words, words.')
['Words', ', ', 'words', ', ', 'words', '.', '']
>>> re.split('\W+', 'Words, words, words.', 1)
['Words', 'words, words.']
>>> re.split('[a-f]+', '0a3B9', flags=re.IGNORECASE)
['0', '3', '9']
If there are capturing groups in the separator and it matches at the start of
the string, the result will start with an empty string. The same holds for
the end of the string:
>>> re.split('(\W+)', '...words, words...')
['', '...', 'words', ', ', 'words', '...', '']
That way, separator components are always found at the same relative
indices within the result list (e.g., if there's one capturing group
in the separator, the 0th, the 2nd and so forth).
Note that *split* will never split a string on an empty pattern match.
For example:
>>> re.split('x*', 'foo')
['foo']
>>> re.split("(?m)^$", "foo\n\nbar\n")
['foo\n\nbar\n']
.. versionchanged:: 2.7
Added the optional flags argument.
.. function:: findall(pattern, string, flags=0)
Return all non-overlapping matches of *pattern* in *string*, as a list of
strings. The *string* is scanned left-to-right, and matches are returned in
the order found. If one or more groups are present in the pattern, return a
list of groups; this will be a list of tuples if the pattern has more than
one group. Empty matches are included in the result.
.. note::
Due to the limitation of the current implementation the character
following an empty match is not included in a next match, so
``findall(r'^|\w+', 'two words')`` returns ``['', 'wo', 'words']``
(note missed "t"). This is changed in Python 3.7.
.. versionadded:: 1.5.2
.. versionchanged:: 2.4
Added the optional flags argument.
.. function:: finditer(pattern, string, flags=0)
Return an :term:`iterator` yielding :class:`MatchObject` instances over all
non-overlapping matches for the RE *pattern* in *string*. The *string* is
scanned left-to-right, and matches are returned in the order found. Empty
matches are included in the result. See also the note about :func:`findall`.
.. versionadded:: 2.2
.. versionchanged:: 2.4
Added the optional flags argument.
.. function:: sub(pattern, repl, string, count=0, flags=0)
Return the string obtained by replacing the leftmost non-overlapping occurrences
of *pattern* in *string* by the replacement *repl*. If the pattern isn't found,
*string* is returned unchanged. *repl* can be a string or a function; if it is
a string, any backslash escapes in it are processed. That is, ``\n`` is
converted to a single newline character, ``\r`` is converted to a carriage return, and
so forth. Unknown escapes such as ``\j`` are left alone. Backreferences, such
as ``\6``, are replaced with the substring matched by group 6 in the pattern.
For example:
>>> re.sub(r'def\s+([a-zA-Z_][a-zA-Z_0-9]*)\s*\(\s*\):',
... r'static PyObject*\npy_\1(void)\n{',
... 'def myfunc():')
'static PyObject*\npy_myfunc(void)\n{'
If *repl* is a function, it is called for every non-overlapping occurrence of
*pattern*. The function takes a single match object argument, and returns the
replacement string. For example:
>>> def dashrepl(matchobj):
... if matchobj.group(0) == '-': return ' '
... else: return '-'
>>> re.sub('-{1,2}', dashrepl, 'pro----gram-files')
'pro--gram files'
>>> re.sub(r'\sAND\s', ' & ', 'Baked Beans And Spam', flags=re.IGNORECASE)
'Baked Beans & Spam'
The pattern may be a string or an RE object.
The optional argument *count* is the maximum number of pattern occurrences to be
replaced; *count* must be a non-negative integer. If omitted or zero, all
occurrences will be replaced. Empty matches for the pattern are replaced only
when not adjacent to a previous match, so ``sub('x*', '-', 'abc')`` returns
``'-a-b-c-'``.
In string-type *repl* arguments, in addition to the character escapes and
backreferences described above,
``\g<name>`` will use the substring matched by the group named ``name``, as
defined by the ``(?P<name>...)`` syntax. ``\g<number>`` uses the corresponding
group number; ``\g<2>`` is therefore equivalent to ``\2``, but isn't ambiguous
in a replacement such as ``\g<2>0``. ``\20`` would be interpreted as a
reference to group 20, not a reference to group 2 followed by the literal
character ``'0'``. The backreference ``\g<0>`` substitutes in the entire
substring matched by the RE.
.. versionchanged:: 2.7
Added the optional flags argument.
.. function:: subn(pattern, repl, string, count=0, flags=0)
Perform the same operation as :func:`sub`, but return a tuple ``(new_string,
number_of_subs_made)``.
.. versionchanged:: 2.7
Added the optional flags argument.
.. function:: escape(pattern)
Escape all the characters in *pattern* except ASCII letters and numbers.
This is useful if you want to match an arbitrary literal string that may
have regular expression metacharacters in it. For example::
>>> print re.escape('python.exe')
python\.exe
>>> legal_chars = string.ascii_lowercase + string.digits + "!#$%&'*+-.^_`|~:"
>>> print '[%s]+' % re.escape(legal_chars)
[abcdefghijklmnopqrstuvwxyz0123456789\!\#\$\%\&\'\*\+\-\.\^\_\`\|\~\:]+
>>> operators = ['+', '-', '*', '/', '**']
>>> print '|'.join(map(re.escape, sorted(operators, reverse=True)))
\/|\-|\+|\*\*|\*
.. function:: purge()
Clear the regular expression cache.
.. exception:: error
Exception raised when a string passed to one of the functions here is not a
valid regular expression (for example, it might contain unmatched parentheses)
or when some other error occurs during compilation or matching. It is never an
error if a string contains no match for a pattern.
.. _re-objects:
Regular Expression Objects
--------------------------
.. class:: RegexObject
The :class:`RegexObject` class supports the following methods and attributes:
.. method:: RegexObject.search(string[, pos[, endpos]])
Scan through *string* looking for a location where this regular expression
produces a match, and return a corresponding :class:`MatchObject` instance.
Return ``None`` if no position in the string matches the pattern; note that this
is different from finding a zero-length match at some point in the string.
The optional second parameter *pos* gives an index in the string where the
search is to start; it defaults to ``0``. This is not completely equivalent to
slicing the string; the ``'^'`` pattern character matches at the real beginning
of the string and at positions just after a newline, but not necessarily at the
index where the search is to start.
The optional parameter *endpos* limits how far the string will be searched; it
will be as if the string is *endpos* characters long, so only the characters
from *pos* to ``endpos - 1`` will be searched for a match. If *endpos* is less
than *pos*, no match will be found, otherwise, if *rx* is a compiled regular
expression object, ``rx.search(string, 0, 50)`` is equivalent to
``rx.search(string[:50], 0)``.
>>> pattern = re.compile("d")
>>> pattern.search("dog") # Match at index 0
<_sre.SRE_Match object at ...>
>>> pattern.search("dog", 1) # No match; search doesn't include the "d"
.. method:: RegexObject.match(string[, pos[, endpos]])
If zero or more characters at the *beginning* of *string* match this regular
expression, return a corresponding :class:`MatchObject` instance. Return
``None`` if the string does not match the pattern; note that this is different
from a zero-length match.
The optional *pos* and *endpos* parameters have the same meaning as for the
:meth:`~RegexObject.search` method.
>>> pattern = re.compile("o")
>>> pattern.match("dog") # No match as "o" is not at the start of "dog".
>>> pattern.match("dog", 1) # Match as "o" is the 2nd character of "dog".
<_sre.SRE_Match object at ...>
If you want to locate a match anywhere in *string*, use
:meth:`~RegexObject.search` instead (see also :ref:`search-vs-match`).
.. method:: RegexObject.split(string, maxsplit=0)
Identical to the :func:`split` function, using the compiled pattern.
.. method:: RegexObject.findall(string[, pos[, endpos]])
Similar to the :func:`findall` function, using the compiled pattern, but
also accepts optional *pos* and *endpos* parameters that limit the search
region like for :meth:`match`.
.. method:: RegexObject.finditer(string[, pos[, endpos]])
Similar to the :func:`finditer` function, using the compiled pattern, but
also accepts optional *pos* and *endpos* parameters that limit the search
region like for :meth:`match`.
.. method:: RegexObject.sub(repl, string, count=0)
Identical to the :func:`sub` function, using the compiled pattern.
.. method:: RegexObject.subn(repl, string, count=0)
Identical to the :func:`subn` function, using the compiled pattern.
.. attribute:: RegexObject.flags
The regex matching flags. This is a combination of the flags given to
:func:`.compile` and any ``(?...)`` inline flags in the pattern.
.. attribute:: RegexObject.groups
The number of capturing groups in the pattern.
.. attribute:: RegexObject.groupindex
A dictionary mapping any symbolic group names defined by ``(?P<id>)`` to group
numbers. The dictionary is empty if no symbolic groups were used in the
pattern.
.. attribute:: RegexObject.pattern
The pattern string from which the RE object was compiled.
.. _match-objects:
Match Objects
-------------
.. class:: MatchObject
Match objects always have a boolean value of ``True``.
Since :meth:`~regex.match` and :meth:`~regex.search` return ``None``
when there is no match, you can test whether there was a match with a simple
``if`` statement::
match = re.search(pattern, string)
if match:
process(match)
Match objects support the following methods and attributes:
.. method:: MatchObject.expand(template)
Return the string obtained by doing backslash substitution on the template
string *template*, as done by the :meth:`~RegexObject.sub` method. Escapes
such as ``\n`` are converted to the appropriate characters, and numeric
backreferences (``\1``, ``\2``) and named backreferences (``\g<1>``,
``\g<name>``) are replaced by the contents of the corresponding group.
.. method:: MatchObject.group([group1, ...])
Returns one or more subgroups of the match. If there is a single argument, the
result is a single string; if there are multiple arguments, the result is a
tuple with one item per argument. Without arguments, *group1* defaults to zero
(the whole match is returned). If a *groupN* argument is zero, the corresponding
return value is the entire matching string; if it is in the inclusive range
[1..99], it is the string matching the corresponding parenthesized group. If a
group number is negative or larger than the number of groups defined in the
pattern, an :exc:`IndexError` exception is raised. If a group is contained in a
part of the pattern that did not match, the corresponding result is ``None``.
If a group is contained in a part of the pattern that matched multiple times,
the last match is returned.
>>> m = re.match(r"(\w+) (\w+)", "Isaac Newton, physicist")
>>> m.group(0) # The entire match
'Isaac Newton'
>>> m.group(1) # The first parenthesized subgroup.
'Isaac'
>>> m.group(2) # The second parenthesized subgroup.
'Newton'
>>> m.group(1, 2) # Multiple arguments give us a tuple.
('Isaac', 'Newton')
If the regular expression uses the ``(?P<name>...)`` syntax, the *groupN*
arguments may also be strings identifying groups by their group name. If a
string argument is not used as a group name in the pattern, an :exc:`IndexError`
exception is raised.
A moderately complicated example:
>>> m = re.match(r"(?P<first_name>\w+) (?P<last_name>\w+)", "Malcolm Reynolds")
>>> m.group('first_name')
'Malcolm'
>>> m.group('last_name')
'Reynolds'
Named groups can also be referred to by their index:
>>> m.group(1)
'Malcolm'
>>> m.group(2)
'Reynolds'
If a group matches multiple times, only the last match is accessible:
>>> m = re.match(r"(..)+", "a1b2c3") # Matches 3 times.
>>> m.group(1) # Returns only the last match.
'c3'
.. method:: MatchObject.groups([default])
Return a tuple containing all the subgroups of the match, from 1 up to however
many groups are in the pattern. The *default* argument is used for groups that
did not participate in the match; it defaults to ``None``. (Incompatibility
note: in the original Python 1.5 release, if the tuple was one element long, a
string would be returned instead. In later versions (from 1.5.1 on), a
singleton tuple is returned in such cases.)
For example:
>>> m = re.match(r"(\d+)\.(\d+)", "24.1632")
>>> m.groups()
('24', '1632')
If we make the decimal place and everything after it optional, not all groups
might participate in the match. These groups will default to ``None`` unless
the *default* argument is given:
>>> m = re.match(r"(\d+)\.?(\d+)?", "24")
>>> m.groups() # Second group defaults to None.
('24', None)
>>> m.groups('0') # Now, the second group defaults to '0'.
('24', '0')
.. method:: MatchObject.groupdict([default])
Return a dictionary containing all the *named* subgroups of the match, keyed by
the subgroup name. The *default* argument is used for groups that did not
participate in the match; it defaults to ``None``. For example:
>>> m = re.match(r"(?P<first_name>\w+) (?P<last_name>\w+)", "Malcolm Reynolds")
>>> m.groupdict()
{'first_name': 'Malcolm', 'last_name': 'Reynolds'}
.. method:: MatchObject.start([group])
MatchObject.end([group])
Return the indices of the start and end of the substring matched by *group*;
*group* defaults to zero (meaning the whole matched substring). Return ``-1`` if
*group* exists but did not contribute to the match. For a match object *m*, and
a group *g* that did contribute to the match, the substring matched by group *g*
(equivalent to ``m.group(g)``) is ::
m.string[m.start(g):m.end(g)]
Note that ``m.start(group)`` will equal ``m.end(group)`` if *group* matched a
null string. For example, after ``m = re.search('b(c?)', 'cba')``,
``m.start(0)`` is 1, ``m.end(0)`` is 2, ``m.start(1)`` and ``m.end(1)`` are both
2, and ``m.start(2)`` raises an :exc:`IndexError` exception.
An example that will remove *remove_this* from email addresses:
>>> email = "tony@tiremove_thisger.net"
>>> m = re.search("remove_this", email)
>>> email[:m.start()] + email[m.end():]
'tony@tiger.net'
.. method:: MatchObject.span([group])
For :class:`MatchObject` *m*, return the 2-tuple ``(m.start(group),
m.end(group))``. Note that if *group* did not contribute to the match, this is
``(-1, -1)``. *group* defaults to zero, the entire match.
.. attribute:: MatchObject.pos
The value of *pos* which was passed to the :meth:`~RegexObject.search` or
:meth:`~RegexObject.match` method of the :class:`RegexObject`. This is the
index into the string at which the RE engine started looking for a match.
.. attribute:: MatchObject.endpos
The value of *endpos* which was passed to the :meth:`~RegexObject.search` or
:meth:`~RegexObject.match` method of the :class:`RegexObject`. This is the
index into the string beyond which the RE engine will not go.
.. attribute:: MatchObject.lastindex
The integer index of the last matched capturing group, or ``None`` if no group
was matched at all. For example, the expressions ``(a)b``, ``((a)(b))``, and
``((ab))`` will have ``lastindex == 1`` if applied to the string ``'ab'``, while
the expression ``(a)(b)`` will have ``lastindex == 2``, if applied to the same
string.
.. attribute:: MatchObject.lastgroup
The name of the last matched capturing group, or ``None`` if the group didn't
have a name, or if no group was matched at all.
.. attribute:: MatchObject.re
The regular expression object whose :meth:`~RegexObject.match` or
:meth:`~RegexObject.search` method produced this :class:`MatchObject`
instance.
.. attribute:: MatchObject.string
The string passed to :meth:`~RegexObject.match` or
:meth:`~RegexObject.search`.
Examples
--------
Checking For a Pair
^^^^^^^^^^^^^^^^^^^
In this example, we'll use the following helper function to display match
objects a little more gracefully:
.. testcode::
def displaymatch(match):
if match is None:
return None
return '<Match: %r, groups=%r>' % (match.group(), match.groups())
Suppose you are writing a poker program where a player's hand is represented as
a 5-character string with each character representing a card, "a" for ace, "k"
for king, "q" for queen, "j" for jack, "t" for 10, and "2" through "9"
representing the card with that value.
To see if a given string is a valid hand, one could do the following:
>>> valid = re.compile(r"^[a2-9tjqk]{5}$")
>>> displaymatch(valid.match("akt5q")) # Valid.
"<Match: 'akt5q', groups=()>"
>>> displaymatch(valid.match("akt5e")) # Invalid.
>>> displaymatch(valid.match("akt")) # Invalid.
>>> displaymatch(valid.match("727ak")) # Valid.
"<Match: '727ak', groups=()>"
That last hand, ``"727ak"``, contained a pair, or two of the same valued cards.
To match this with a regular expression, one could use backreferences as such:
>>> pair = re.compile(r".*(.).*\1")
>>> displaymatch(pair.match("717ak")) # Pair of 7s.
"<Match: '717', groups=('7',)>"
>>> displaymatch(pair.match("718ak")) # No pairs.
>>> displaymatch(pair.match("354aa")) # Pair of aces.
"<Match: '354aa', groups=('a',)>"
To find out what card the pair consists of, one could use the
:meth:`~MatchObject.group` method of :class:`MatchObject` in the following
manner:
.. doctest::
>>> pair.match("717ak").group(1)
'7'
# Error because re.match() returns None, which doesn't have a group() method:
>>> pair.match("718ak").group(1)
Traceback (most recent call last):
File "<pyshell#23>", line 1, in <module>
re.match(r".*(.).*\1", "718ak").group(1)
AttributeError: 'NoneType' object has no attribute 'group'
>>> pair.match("354aa").group(1)
'a'
Simulating scanf()
^^^^^^^^^^^^^^^^^^
.. index:: single: scanf()
Python does not currently have an equivalent to :c:func:`scanf`. Regular
expressions are generally more powerful, though also more verbose, than
:c:func:`scanf` format strings. The table below offers some more-or-less
equivalent mappings between :c:func:`scanf` format tokens and regular
expressions.
+--------------------------------+---------------------------------------------+
| :c:func:`scanf` Token | Regular Expression |
+================================+=============================================+
| ``%c`` | ``.`` |
+--------------------------------+---------------------------------------------+
| ``%5c`` | ``.{5}`` |
+--------------------------------+---------------------------------------------+
| ``%d`` | ``[-+]?\d+`` |
+--------------------------------+---------------------------------------------+
| ``%e``, ``%E``, ``%f``, ``%g`` | ``[-+]?(\d+(\.\d*)?|\.\d+)([eE][-+]?\d+)?`` |
+--------------------------------+---------------------------------------------+
| ``%i`` | ``[-+]?(0[xX][\dA-Fa-f]+|0[0-7]*|\d+)`` |
+--------------------------------+---------------------------------------------+
| ``%o`` | ``[-+]?[0-7]+`` |
+--------------------------------+---------------------------------------------+
| ``%s`` | ``\S+`` |
+--------------------------------+---------------------------------------------+
| ``%u`` | ``\d+`` |
+--------------------------------+---------------------------------------------+
| ``%x``, ``%X`` | ``[-+]?(0[xX])?[\dA-Fa-f]+`` |
+--------------------------------+---------------------------------------------+
To extract the filename and numbers from a string like ::
/usr/sbin/sendmail - 0 errors, 4 warnings
you would use a :c:func:`scanf` format like ::
%s - %d errors, %d warnings
The equivalent regular expression would be ::
(\S+) - (\d+) errors, (\d+) warnings
.. _search-vs-match:
search() vs. match()
^^^^^^^^^^^^^^^^^^^^
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
Python offers two different primitive operations based on regular expressions:
:func:`re.match` checks for a match only at the beginning of the string, while
:func:`re.search` checks for a match anywhere in the string (this is what Perl
does by default).
For example::
>>> re.match("c", "abcdef") # No match
>>> re.search("c", "abcdef") # Match
<_sre.SRE_Match object at ...>
Regular expressions beginning with ``'^'`` can be used with :func:`search` to
restrict the match at the beginning of the string::
>>> re.match("c", "abcdef") # No match
>>> re.search("^c", "abcdef") # No match
>>> re.search("^a", "abcdef") # Match
<_sre.SRE_Match object at ...>
Note however that in :const:`MULTILINE` mode :func:`match` only matches at the
beginning of the string, whereas using :func:`search` with a regular expression
beginning with ``'^'`` will match at the beginning of each line.
>>> re.match('X', 'A\nB\nX', re.MULTILINE) # No match
>>> re.search('^X', 'A\nB\nX', re.MULTILINE) # Match
<_sre.SRE_Match object at ...>
Making a Phonebook
^^^^^^^^^^^^^^^^^^
:func:`split` splits a string into a list delimited by the passed pattern. The
method is invaluable for converting textual data into data structures that can be
easily read and modified by Python as demonstrated in the following example that
creates a phonebook.
First, here is the input. Normally it may come from a file, here we are using
triple-quoted string syntax:
>>> text = """Ross McFluff: 834.345.1254 155 Elm Street
...
... Ronald Heathmore: 892.345.3428 436 Finley Avenue
... Frank Burger: 925.541.7625 662 South Dogwood Way
...
...
... Heather Albrecht: 548.326.4584 919 Park Place"""
The entries are separated by one or more newlines. Now we convert the string
into a list with each nonempty line having its own entry:
.. doctest::
:options: +NORMALIZE_WHITESPACE
>>> entries = re.split("\n+", text)
>>> entries
['Ross McFluff: 834.345.1254 155 Elm Street',
'Ronald Heathmore: 892.345.3428 436 Finley Avenue',
'Frank Burger: 925.541.7625 662 South Dogwood Way',
'Heather Albrecht: 548.326.4584 919 Park Place']
Finally, split each entry into a list with first name, last name, telephone
number, and address. We use the ``maxsplit`` parameter of :func:`split`
because the address has spaces, our splitting pattern, in it:
.. doctest::
:options: +NORMALIZE_WHITESPACE
>>> [re.split(":? ", entry, 3) for entry in entries]
[['Ross', 'McFluff', '834.345.1254', '155 Elm Street'],
['Ronald', 'Heathmore', '892.345.3428', '436 Finley Avenue'],
['Frank', 'Burger', '925.541.7625', '662 South Dogwood Way'],
['Heather', 'Albrecht', '548.326.4584', '919 Park Place']]
The ``:?`` pattern matches the colon after the last name, so that it does not
occur in the result list. With a ``maxsplit`` of ``4``, we could separate the
house number from the street name:
.. doctest::
:options: +NORMALIZE_WHITESPACE
>>> [re.split(":? ", entry, 4) for entry in entries]
[['Ross', 'McFluff', '834.345.1254', '155', 'Elm Street'],
['Ronald', 'Heathmore', '892.345.3428', '436', 'Finley Avenue'],
['Frank', 'Burger', '925.541.7625', '662', 'South Dogwood Way'],
['Heather', 'Albrecht', '548.326.4584', '919', 'Park Place']]
Text Munging
^^^^^^^^^^^^
:func:`sub` replaces every occurrence of a pattern with a string or the
result of a function. This example demonstrates using :func:`sub` with
a function to "munge" text, or randomize the order of all the characters
in each word of a sentence except for the first and last characters::
>>> def repl(m):
... inner_word = list(m.group(2))
... random.shuffle(inner_word)
... return m.group(1) + "".join(inner_word) + m.group(3)
>>> text = "Professor Abdolmalek, please report your absences promptly."
>>> re.sub(r"(\w)(\w+)(\w)", repl, text)
'Poefsrosr Aealmlobdk, pslaee reorpt your abnseces plmrptoy.'
>>> re.sub(r"(\w)(\w+)(\w)", repl, text)
'Pofsroser Aodlambelk, plasee reoprt yuor asnebces potlmrpy.'
Finding all Adverbs
^^^^^^^^^^^^^^^^^^^
:func:`findall` matches *all* occurrences of a pattern, not just the first
one as :func:`search` does. For example, if a writer wanted to
find all of the adverbs in some text, they might use :func:`findall` in
the following manner:
>>> text = "He was carefully disguised but captured quickly by police."
>>> re.findall(r"\w+ly", text)
['carefully', 'quickly']
Finding all Adverbs and their Positions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If one wants more information about all matches of a pattern than the matched
text, :func:`finditer` is useful as it provides instances of
:class:`MatchObject` instead of strings. Continuing with the previous example,
if a writer wanted to find all of the adverbs *and their positions*
in some text, they would use :func:`finditer` in the following manner:
>>> text = "He was carefully disguised but captured quickly by police."
>>> for m in re.finditer(r"\w+ly", text):
... print '%02d-%02d: %s' % (m.start(), m.end(), m.group(0))
07-16: carefully
40-47: quickly
Raw String Notation
^^^^^^^^^^^^^^^^^^^
Raw string notation (``r"text"``) keeps regular expressions sane. Without it,
every backslash (``'\'``) in a regular expression would have to be prefixed with
another one to escape it. For example, the two following lines of code are
functionally identical:
>>> re.match(r"\W(.)\1\W", " ff ")
<_sre.SRE_Match object at ...>
>>> re.match("\\W(.)\\1\\W", " ff ")
<_sre.SRE_Match object at ...>
When one wants to match a literal backslash, it must be escaped in the regular
expression. With raw string notation, this means ``r"\\"``. Without raw string
notation, one must use ``"\\\\"``, making the following lines of code
functionally identical:
>>> re.match(r"\\", r"\\")
<_sre.SRE_Match object at ...>
>>> re.match("\\\\", r"\\")
<_sre.SRE_Match object at ...>
PK
%�\�JN) ) & html/_sources/library/readline.rst.txtnu �[��� :mod:`readline` --- GNU readline interface
==========================================
.. module:: readline
:platform: Unix
:synopsis: GNU readline support for Python.
.. sectionauthor:: Skip Montanaro <skip@pobox.com>
The :mod:`readline` module defines a number of functions to facilitate
completion and reading/writing of history files from the Python interpreter.
This module can be used directly, or via the :mod:`rlcompleter` module, which
supports completion of Python identifiers at the interactive prompt. Settings
made using this module affect the behaviour of both the interpreter's
interactive prompt and the prompts offered by the :func:`raw_input` and
:func:`input` built-in functions.
.. note::
The underlying Readline library API may be implemented by
the ``libedit`` library instead of GNU readline.
On MacOS X the :mod:`readline` module detects which library is being used
at run time.
The configuration file for ``libedit`` is different from that
of GNU readline. If you programmatically load configuration strings
you can check for the text "libedit" in :const:`readline.__doc__`
to differentiate between GNU readline and libedit.
Readline keybindings may be configured via an initialization file, typically
``.inputrc`` in your home directory. See `Readline Init File
<https://cnswww.cns.cwru.edu/php/chet/readline/rluserman.html#SEC9>`_
in the GNU Readline manual for information about the format and
allowable constructs of that file, and the capabilities of the
Readline library in general.
Init file
---------
The following functions relate to the init file and user configuration:
.. function:: parse_and_bind(string)
Execute the init line provided in the *string* argument. This calls
:c:func:`rl_parse_and_bind` in the underlying library.
.. function:: read_init_file([filename])
Execute a readline initialization file. The default filename is the last filename
used. This calls :c:func:`rl_read_init_file` in the underlying library.
Line buffer
-----------
The following functions operate on the line buffer:
.. function:: get_line_buffer()
Return the current contents of the line buffer (:c:data:`rl_line_buffer`
in the underlying library).
.. function:: insert_text(string)
Insert text into the line buffer at the cursor position. This calls
:c:func:`rl_insert_text` in the underlying library, but ignores
the return value.
.. function:: redisplay()
Change what's displayed on the screen to reflect the current contents of the
line buffer. This calls :c:func:`rl_redisplay` in the underlying library.
History file
------------
The following functions operate on a history file:
.. function:: read_history_file([filename])
Load a readline history file, and append it to the history list.
The default filename is :file:`~/.history`. This calls
:c:func:`read_history` in the underlying library.
.. function:: write_history_file([filename])
Save the history list to a readline history file, overwriting any
existing file. The default filename is :file:`~/.history`. This calls
:c:func:`write_history` in the underlying library.
.. function:: get_history_length()
set_history_length(length)
Set or return the desired number of lines to save in the history file.
The :func:`write_history_file` function uses this value to truncate
the history file, by calling :c:func:`history_truncate_file` in
the underlying library. Negative values imply
unlimited history file size.
History list
------------
The following functions operate on a global history list:
.. function:: clear_history()
Clear the current history. This calls :c:func:`clear_history` in the
underlying library. The Python function only exists if Python was
compiled for a version of the library that supports it.
.. versionadded:: 2.4
.. function:: get_current_history_length()
Return the number of items currently in the history. (This is different from
:func:`get_history_length`, which returns the maximum number of lines that will
be written to a history file.)
.. versionadded:: 2.3
.. function:: get_history_item(index)
Return the current contents of history item at *index*. The item index
is one-based. This calls :c:func:`history_get` in the underlying library.
.. versionadded:: 2.3
.. function:: remove_history_item(pos)
Remove history item specified by its position from the history.
The position is zero-based. This calls :c:func:`remove_history` in
the underlying library.
.. versionadded:: 2.4
.. function:: replace_history_item(pos, line)
Replace history item specified by its position with *line*.
The position is zero-based. This calls :c:func:`replace_history_entry`
in the underlying library.
.. versionadded:: 2.4
.. function:: add_history(line)
Append *line* to the history buffer, as if it was the last line typed.
This calls :c:func:`add_history` in the underlying library.
Startup hooks
-------------
.. versionadded:: 2.3
.. function:: set_startup_hook([function])
Set or remove the function invoked by the :c:data:`rl_startup_hook`
callback of the underlying library. If *function* is specified, it will
be used as the new hook function; if omitted or ``None``, any function
already installed is removed. The hook is called with no
arguments just before readline prints the first prompt.
.. function:: set_pre_input_hook([function])
Set or remove the function invoked by the :c:data:`rl_pre_input_hook`
callback of the underlying library. If *function* is specified, it will
be used as the new hook function; if omitted or ``None``, any
function already installed is removed. The hook is called
with no arguments after the first prompt has been printed and just before
readline starts reading input characters. This function only exists
if Python was compiled for a version of the library that supports it.
Completion
----------
The following functions relate to implementing a custom word completion
function. This is typically operated by the Tab key, and can suggest and
automatically complete a word being typed. By default, Readline is set up
to be used by :mod:`rlcompleter` to complete Python identifiers for
the interactive interpreter. If the :mod:`readline` module is to be used
with a custom completer, a different set of word delimiters should be set.
.. function:: set_completer([function])
Set or remove the completer function. If *function* is specified, it will be
used as the new completer function; if omitted or ``None``, any completer
function already installed is removed. The completer function is called as
``function(text, state)``, for *state* in ``0``, ``1``, ``2``, ..., until it
returns a non-string value. It should return the next possible completion
starting with *text*.
The installed completer function is invoked by the *entry_func* callback
passed to :c:func:`rl_completion_matches` in the underlying library.
The *text* string comes from the first parameter to the
:c:data:`rl_attempted_completion_function` callback of the
underlying library.
.. function:: get_completer()
Get the completer function, or ``None`` if no completer function has been set.
.. versionadded:: 2.3
.. function:: get_completion_type()
Get the type of completion being attempted. This returns the
:c:data:`rl_completion_type` variable in the underlying library as
an integer.
.. versionadded:: 2.6
.. function:: get_begidx()
get_endidx()
Get the beginning or ending index of the completion scope.
These indexes are the *start* and *end* arguments passed to the
:c:data:`rl_attempted_completion_function` callback of the
underlying library.
.. function:: set_completer_delims(string)
get_completer_delims()
Set or get the word delimiters for completion. These determine the
start of the word to be considered for completion (the completion scope).
These functions access the :c:data:`rl_completer_word_break_characters`
variable in the underlying library.
.. function:: set_completion_display_matches_hook([function])
Set or remove the completion display function. If *function* is
specified, it will be used as the new completion display function;
if omitted or ``None``, any completion display function already
installed is removed. This sets or clears the
:c:data:`rl_completion_display_matches_hook` callback in the
underlying library. The completion display function is called as
``function(substitution, [matches], longest_match_length)`` once
each time matches need to be displayed.
.. versionadded:: 2.6
.. _readline-example:
Example
-------
The following example demonstrates how to use the :mod:`readline` module's
history reading and writing functions to automatically load and save a history
file named :file:`.pyhist` from the user's home directory. The code below would
normally be executed automatically during interactive sessions from the user's
:envvar:`PYTHONSTARTUP` file. ::
import os
import readline
histfile = os.path.join(os.path.expanduser("~"), ".pyhist")
try:
readline.read_history_file(histfile)
# default history len is -1 (infinite), which may grow unruly
readline.set_history_length(1000)
except IOError:
pass
import atexit
atexit.register(readline.write_history_file, histfile)
del os, histfile
The following example extends the :class:`code.InteractiveConsole` class to
support history save/restore. ::
import code
import readline
import atexit
import os
class HistoryConsole(code.InteractiveConsole):
def __init__(self, locals=None, filename="<console>",
histfile=os.path.expanduser("~/.console-history")):
code.InteractiveConsole.__init__(self, locals, filename)
self.init_history(histfile)
def init_history(self, histfile):
readline.parse_and_bind("tab: complete")
if hasattr(readline, "read_history_file"):
try:
readline.read_history_file(histfile)
except IOError:
pass
atexit.register(self.save_history, histfile)
def save_history(self, histfile):
readline.set_history_length(1000)
readline.write_history_file(histfile)
PK
%�\��\�n n " html/_sources/library/repr.rst.txtnu �[��� :mod:`repr` --- Alternate :func:`repr` implementation
=====================================================
.. module:: repr
:synopsis: Alternate repr() implementation with size limits.
:noindex:
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
.. note::
The :mod:`repr` module has been renamed to :mod:`reprlib` in Python 3. The
:term:`2to3` tool will automatically adapt imports when converting your
sources to Python 3.
**Source code:** :source:`Lib/repr.py`
--------------
The :mod:`repr` module provides a means for producing object representations
with limits on the size of the resulting strings. This is used in the Python
debugger and may be useful in other contexts as well.
This module provides a class, an instance, and a function:
.. class:: Repr()
Class which provides formatting services useful in implementing functions
similar to the built-in :ref:`repr() <func-repr>`; size limits for different
object types are added to avoid the generation of representations which are
excessively long.
.. data:: aRepr
This is an instance of :class:`Repr` which is used to provide the :func:`.repr`
function described below. Changing the attributes of this object will affect
the size limits used by :func:`.repr` and the Python debugger.
.. function:: repr(obj)
This is the :meth:`~Repr.repr` method of ``aRepr``. It returns a string
similar to that returned by the built-in function of the same name, but with
limits on most sizes.
.. _repr-objects:
Repr Objects
------------
:class:`Repr` instances provide several attributes which can be used to provide
size limits for the representations of different object types, and methods
which format specific object types.
.. attribute:: Repr.maxlevel
Depth limit on the creation of recursive representations. The default is ``6``.
.. attribute:: Repr.maxdict
Repr.maxlist
Repr.maxtuple
Repr.maxset
Repr.maxfrozenset
Repr.maxdeque
Repr.maxarray
Limits on the number of entries represented for the named object type. The
default is ``4`` for :attr:`maxdict`, ``5`` for :attr:`maxarray`, and ``6`` for
the others.
.. versionadded:: 2.4
:attr:`maxset`, :attr:`maxfrozenset`, and :attr:`set`.
.. attribute:: Repr.maxlong
Maximum number of characters in the representation for a long integer. Digits
are dropped from the middle. The default is ``40``.
.. attribute:: Repr.maxstring
Limit on the number of characters in the representation of the string. Note
that the "normal" representation of the string is used as the character source:
if escape sequences are needed in the representation, these may be mangled when
the representation is shortened. The default is ``30``.
.. attribute:: Repr.maxother
This limit is used to control the size of object types for which no specific
formatting method is available on the :class:`Repr` object. It is applied in a
similar manner as :attr:`maxstring`. The default is ``20``.
.. method:: Repr.repr(obj)
The equivalent to the built-in :ref:`repr() <func-repr>` that uses the
formatting imposed by the instance.
.. method:: Repr.repr1(obj, level)
Recursive implementation used by :meth:`.repr`. This uses the type of *obj* to
determine which formatting method to call, passing it *obj* and *level*. The
type-specific methods should call :meth:`repr1` to perform recursive formatting,
with ``level - 1`` for the value of *level* in the recursive call.
.. method:: Repr.repr_TYPE(obj, level)
:noindex:
Formatting methods for specific types are implemented as methods with a name
based on the type name. In the method name, **TYPE** is replaced by
``string.join(string.split(type(obj).__name__, '_'))``. Dispatch to these
methods is handled by :meth:`repr1`. Type-specific methods which need to
recursively format a value should call ``self.repr1(subobj, level - 1)``.
.. _subclassing-reprs:
Subclassing Repr Objects
------------------------
The use of dynamic dispatching by :meth:`Repr.repr1` allows subclasses of
:class:`Repr` to add support for additional built-in object types or to modify
the handling of types already supported. This example shows how special support
for file objects could be added::
import repr as reprlib
import sys
class MyRepr(reprlib.Repr):
def repr_file(self, obj, level):
if obj.name in ['<stdin>', '<stdout>', '<stderr>']:
return obj.name
else:
return repr(obj)
aRepr = MyRepr()
print aRepr.repr(sys.stdin) # prints '<stdin>'
PK
%�\�bO�{% {% & html/_sources/library/resource.rst.txtnu �[���
:mod:`resource` --- Resource usage information
==============================================
.. module:: resource
:platform: Unix
:synopsis: An interface to provide resource usage information on the current process.
.. moduleauthor:: Jeremy Hylton <jeremy@alum.mit.edu>
.. sectionauthor:: Jeremy Hylton <jeremy@alum.mit.edu>
This module provides basic mechanisms for measuring and controlling system
resources utilized by a program.
Symbolic constants are used to specify particular system resources and to
request usage information about either the current process or its children.
A single exception is defined for errors:
.. exception:: error
The functions described below may raise this error if the underlying system call
failures unexpectedly.
Resource Limits
---------------
Resources usage can be limited using the :func:`setrlimit` function described
below. Each resource is controlled by a pair of limits: a soft limit and a hard
limit. The soft limit is the current limit, and may be lowered or raised by a
process over time. The soft limit can never exceed the hard limit. The hard
limit can be lowered to any value greater than the soft limit, but not raised.
(Only processes with the effective UID of the super-user can raise a hard
limit.)
The specific resources that can be limited are system dependent. They are
described in the :manpage:`getrlimit(2)` man page. The resources listed below
are supported when the underlying operating system supports them; resources
which cannot be checked or controlled by the operating system are not defined in
this module for those platforms.
.. data:: RLIM_INFINITY
Constant used to represent the limit for an unlimited resource.
.. function:: getrlimit(resource)
Returns a tuple ``(soft, hard)`` with the current soft and hard limits of
*resource*. Raises :exc:`ValueError` if an invalid resource is specified, or
:exc:`error` if the underlying system call fails unexpectedly.
.. function:: setrlimit(resource, limits)
Sets new limits of consumption of *resource*. The *limits* argument must be a
tuple ``(soft, hard)`` of two integers describing the new limits. A value of
:data:`~resource.RLIM_INFINITY` can be used to request a limit that is
unlimited.
Raises :exc:`ValueError` if an invalid resource is specified, if the new soft
limit exceeds the hard limit, or if a process tries to raise its hard limit.
Specifying a limit of :data:`~resource.RLIM_INFINITY` when the hard or
system limit for that resource is not unlimited will result in a
:exc:`ValueError`. A process with the effective UID of super-user can
request any valid limit value, including unlimited, but :exc:`ValueError`
will still be raised if the requested limit exceeds the system imposed
limit.
``setrlimit`` may also raise :exc:`error` if the underlying system call
fails.
These symbols define resources whose consumption can be controlled using the
:func:`setrlimit` and :func:`getrlimit` functions described below. The values of
these symbols are exactly the constants used by C programs.
The Unix man page for :manpage:`getrlimit(2)` lists the available resources.
Note that not all systems use the same symbol or same value to denote the same
resource. This module does not attempt to mask platform differences --- symbols
not defined for a platform will not be available from this module on that
platform.
.. data:: RLIMIT_CORE
The maximum size (in bytes) of a core file that the current process can create.
This may result in the creation of a partial core file if a larger core would be
required to contain the entire process image.
.. data:: RLIMIT_CPU
The maximum amount of processor time (in seconds) that a process can use. If
this limit is exceeded, a :const:`SIGXCPU` signal is sent to the process. (See
the :mod:`signal` module documentation for information about how to catch this
signal and do something useful, e.g. flush open files to disk.)
.. data:: RLIMIT_FSIZE
The maximum size of a file which the process may create.
.. data:: RLIMIT_DATA
The maximum size (in bytes) of the process's heap.
.. data:: RLIMIT_STACK
The maximum size (in bytes) of the call stack for the current process. This only
affects the stack of the main thread in a multi-threaded process.
.. data:: RLIMIT_RSS
The maximum resident set size that should be made available to the process.
.. data:: RLIMIT_NPROC
The maximum number of processes the current process may create.
.. data:: RLIMIT_NOFILE
The maximum number of open file descriptors for the current process.
.. data:: RLIMIT_OFILE
The BSD name for :const:`RLIMIT_NOFILE`.
.. data:: RLIMIT_MEMLOCK
The maximum address space which may be locked in memory.
.. data:: RLIMIT_VMEM
The largest area of mapped memory which the process may occupy.
.. data:: RLIMIT_AS
The maximum area (in bytes) of address space which may be taken by the process.
Resource Usage
--------------
These functions are used to retrieve resource usage information:
.. function:: getrusage(who)
This function returns an object that describes the resources consumed by either
the current process or its children, as specified by the *who* parameter. The
*who* parameter should be specified using one of the :const:`RUSAGE_\*`
constants described below.
The fields of the return value each describe how a particular system resource
has been used, e.g. amount of time spent running is user mode or number of times
the process was swapped out of main memory. Some values are dependent on the
clock tick internal, e.g. the amount of memory the process is using.
For backward compatibility, the return value is also accessible as a tuple of 16
elements.
The fields :attr:`ru_utime` and :attr:`ru_stime` of the return value are
floating point values representing the amount of time spent executing in user
mode and the amount of time spent executing in system mode, respectively. The
remaining values are integers. Consult the :manpage:`getrusage(2)` man page for
detailed information about these values. A brief summary is presented here:
+--------+---------------------+-------------------------------+
| Index | Field | Resource |
+========+=====================+===============================+
| ``0`` | :attr:`ru_utime` | time in user mode (float) |
+--------+---------------------+-------------------------------+
| ``1`` | :attr:`ru_stime` | time in system mode (float) |
+--------+---------------------+-------------------------------+
| ``2`` | :attr:`ru_maxrss` | maximum resident set size |
+--------+---------------------+-------------------------------+
| ``3`` | :attr:`ru_ixrss` | shared memory size |
+--------+---------------------+-------------------------------+
| ``4`` | :attr:`ru_idrss` | unshared memory size |
+--------+---------------------+-------------------------------+
| ``5`` | :attr:`ru_isrss` | unshared stack size |
+--------+---------------------+-------------------------------+
| ``6`` | :attr:`ru_minflt` | page faults not requiring I/O |
+--------+---------------------+-------------------------------+
| ``7`` | :attr:`ru_majflt` | page faults requiring I/O |
+--------+---------------------+-------------------------------+
| ``8`` | :attr:`ru_nswap` | number of swap outs |
+--------+---------------------+-------------------------------+
| ``9`` | :attr:`ru_inblock` | block input operations |
+--------+---------------------+-------------------------------+
| ``10`` | :attr:`ru_oublock` | block output operations |
+--------+---------------------+-------------------------------+
| ``11`` | :attr:`ru_msgsnd` | messages sent |
+--------+---------------------+-------------------------------+
| ``12`` | :attr:`ru_msgrcv` | messages received |
+--------+---------------------+-------------------------------+
| ``13`` | :attr:`ru_nsignals` | signals received |
+--------+---------------------+-------------------------------+
| ``14`` | :attr:`ru_nvcsw` | voluntary context switches |
+--------+---------------------+-------------------------------+
| ``15`` | :attr:`ru_nivcsw` | involuntary context switches |
+--------+---------------------+-------------------------------+
This function will raise a :exc:`ValueError` if an invalid *who* parameter is
specified. It may also raise :exc:`error` exception in unusual circumstances.
.. versionchanged:: 2.3
Added access to values as attributes of the returned object.
.. function:: getpagesize()
Returns the number of bytes in a system page. (This need not be the same as the
hardware page size.)
The following :const:`RUSAGE_\*` symbols are passed to the :func:`getrusage`
function to specify which processes information should be provided for.
.. data:: RUSAGE_SELF
:const:`RUSAGE_SELF` should be used to request information pertaining only to
the process itself.
.. data:: RUSAGE_CHILDREN
Pass to :func:`getrusage` to request resource information for child processes of
the calling process.
.. data:: RUSAGE_BOTH
Pass to :func:`getrusage` to request resources consumed by both the current
process and child processes. May not be available on all systems.
PK
%�\���� � ( html/_sources/library/restricted.rst.txtnu �[���
.. _restricted:
********************
Restricted Execution
********************
.. warning::
In Python 2.3 these modules have been disabled due to various known and not
readily fixable security holes. The modules are still documented here to help
in reading old code that uses the :mod:`rexec` and :mod:`Bastion` modules.
*Restricted execution* is the basic framework in Python that allows for the
segregation of trusted and untrusted code. The framework is based on the notion
that trusted Python code (a *supervisor*) can create a "padded cell' (or
environment) with limited permissions, and run the untrusted code within this
cell. The untrusted code cannot break out of its cell, and can only interact
with sensitive system resources through interfaces defined and managed by the
trusted code. The term "restricted execution" is favored over "safe-Python"
since true safety is hard to define, and is determined by the way the restricted
environment is created. Note that the restricted environments can be nested,
with inner cells creating subcells of lesser, but never greater, privilege.
An interesting aspect of Python's restricted execution model is that the
interfaces presented to untrusted code usually have the same names as those
presented to trusted code. Therefore no special interfaces need to be learned
to write code designed to run in a restricted environment. And because the
exact nature of the padded cell is determined by the supervisor, different
restrictions can be imposed, depending on the application. For example, it
might be deemed "safe" for untrusted code to read any file within a specified
directory, but never to write a file. In this case, the supervisor may redefine
the built-in :func:`open` function so that it raises an exception whenever the
*mode* parameter is ``'w'``. It might also perform a :c:func:`chroot`\ -like
operation on the *filename* parameter, such that root is always relative to some
safe "sandbox" area of the filesystem. In this case, the untrusted code would
still see a built-in :func:`open` function in its environment, with the same
calling interface. The semantics would be identical too, with :exc:`IOError`\ s
being raised when the supervisor determined that an unallowable parameter is
being used.
The Python run-time determines whether a particular code block is executing in
restricted execution mode based on the identity of the ``__builtins__`` object
in its global variables: if this is (the dictionary of) the standard
:mod:`__builtin__` module, the code is deemed to be unrestricted, else it is
deemed to be restricted.
Python code executing in restricted mode faces a number of limitations that are
designed to prevent it from escaping from the padded cell. For instance, the
function object attribute :attr:`func_globals` and the class and instance object
attribute :attr:`~object.__dict__` are unavailable.
Two modules provide the framework for setting up restricted execution
environments:
.. toctree::
rexec.rst
bastion.rst
.. seealso::
`Grail Home Page <http://grail.sourceforge.net/>`_
Grail, an Internet browser written in Python, uses these modules to support
Python applets. More information on the use of Python's restricted execution
mode in Grail is available on the Web site.
PK
%�\���- �- # html/_sources/library/rexec.rst.txtnu �[��� :mod:`rexec` --- Restricted execution framework
===============================================
.. module:: rexec
:synopsis: Basic restricted execution framework.
:deprecated:
.. deprecated:: 2.6
The :mod:`rexec` module has been removed in Python 3.
.. versionchanged:: 2.3
Disabled module.
.. warning::
The documentation has been left in place to help in reading old code that uses
the module.
This module contains the :class:`RExec` class, which supports :meth:`r_eval`,
:meth:`r_execfile`, :meth:`r_exec`, and :meth:`r_import` methods, which are
restricted versions of the standard Python functions :meth:`eval`,
:meth:`execfile` and the :keyword:`exec` and :keyword:`import` statements. Code
executed in this restricted environment will only have access to modules and
functions that are deemed safe; you can subclass :class:`RExec` to add or remove
capabilities as desired.
.. warning::
While the :mod:`rexec` module is designed to perform as described below, it does
have a few known vulnerabilities which could be exploited by carefully written
code. Thus it should not be relied upon in situations requiring "production
ready" security. In such situations, execution via sub-processes or very
careful "cleansing" of both code and data to be processed may be necessary.
Alternatively, help in patching known :mod:`rexec` vulnerabilities would be
welcomed.
.. note::
The :class:`RExec` class can prevent code from performing unsafe operations like
reading or writing disk files, or using TCP/IP sockets. However, it does not
protect against code using extremely large amounts of memory or processor time.
.. class:: RExec([hooks[, verbose]])
Returns an instance of the :class:`RExec` class.
*hooks* is an instance of the :class:`RHooks` class or a subclass of it. If it
is omitted or ``None``, the default :class:`RHooks` class is instantiated.
Whenever the :mod:`rexec` module searches for a module (even a built-in one) or
reads a module's code, it doesn't actually go out to the file system itself.
Rather, it calls methods of an :class:`RHooks` instance that was passed to or
created by its constructor. (Actually, the :class:`RExec` object doesn't make
these calls --- they are made by a module loader object that's part of the
:class:`RExec` object. This allows another level of flexibility, which can be
useful when changing the mechanics of :keyword:`import` within the restricted
environment.)
By providing an alternate :class:`RHooks` object, we can control the file system
accesses made to import a module, without changing the actual algorithm that
controls the order in which those accesses are made. For instance, we could
substitute an :class:`RHooks` object that passes all filesystem requests to a
file server elsewhere, via some RPC mechanism such as ILU. Grail's applet
loader uses this to support importing applets from a URL for a directory.
If *verbose* is true, additional debugging output may be sent to standard
output.
It is important to be aware that code running in a restricted environment can
still call the :func:`sys.exit` function. To disallow restricted code from
exiting the interpreter, always protect calls that cause restricted code to run
with a :keyword:`try`/:keyword:`except` statement that catches the
:exc:`SystemExit` exception. Removing the :func:`sys.exit` function from the
restricted environment is not sufficient --- the restricted code could still use
``raise SystemExit``. Removing :exc:`SystemExit` is not a reasonable option;
some library code makes use of this and would break were it not available.
.. seealso::
`Grail Home Page <http://grail.sourceforge.net/>`_
Grail is a Web browser written entirely in Python. It uses the :mod:`rexec`
module as a foundation for supporting Python applets, and can be used as an
example usage of this module.
.. _rexec-objects:
RExec Objects
-------------
:class:`RExec` instances support the following methods:
.. method:: RExec.r_eval(code)
*code* must either be a string containing a Python expression, or a compiled
code object, which will be evaluated in the restricted environment's
:mod:`__main__` module. The value of the expression or code object will be
returned.
.. method:: RExec.r_exec(code)
*code* must either be a string containing one or more lines of Python code, or a
compiled code object, which will be executed in the restricted environment's
:mod:`__main__` module.
.. method:: RExec.r_execfile(filename)
Execute the Python code contained in the file *filename* in the restricted
environment's :mod:`__main__` module.
Methods whose names begin with ``s_`` are similar to the functions beginning
with ``r_``, but the code will be granted access to restricted versions of the
standard I/O streams ``sys.stdin``, ``sys.stderr``, and ``sys.stdout``.
.. method:: RExec.s_eval(code)
*code* must be a string containing a Python expression, which will be evaluated
in the restricted environment.
.. method:: RExec.s_exec(code)
*code* must be a string containing one or more lines of Python code, which will
be executed in the restricted environment.
.. method:: RExec.s_execfile(code)
Execute the Python code contained in the file *filename* in the restricted
environment.
:class:`RExec` objects must also support various methods which will be
implicitly called by code executing in the restricted environment. Overriding
these methods in a subclass is used to change the policies enforced by a
restricted environment.
.. method:: RExec.r_import(modulename[, globals[, locals[, fromlist]]])
Import the module *modulename*, raising an :exc:`ImportError` exception if the
module is considered unsafe.
.. method:: RExec.r_open(filename[, mode[, bufsize]])
Method called when :func:`open` is called in the restricted environment. The
arguments are identical to those of :func:`open`, and a file object (or a class
instance compatible with file objects) should be returned. :class:`RExec`'s
default behaviour is allow opening any file for reading, but forbidding any
attempt to write a file. See the example below for an implementation of a less
restrictive :meth:`r_open`.
.. method:: RExec.r_reload(module)
Reload the module object *module*, re-parsing and re-initializing it.
.. method:: RExec.r_unload(module)
Unload the module object *module* (remove it from the restricted environment's
``sys.modules`` dictionary).
And their equivalents with access to restricted standard I/O streams:
.. method:: RExec.s_import(modulename[, globals[, locals[, fromlist]]])
Import the module *modulename*, raising an :exc:`ImportError` exception if the
module is considered unsafe.
.. method:: RExec.s_reload(module)
Reload the module object *module*, re-parsing and re-initializing it.
.. method:: RExec.s_unload(module)
Unload the module object *module*.
.. XXX what are the semantics of this?
.. _rexec-extension:
Defining restricted environments
--------------------------------
The :class:`RExec` class has the following class attributes, which are used by
the :meth:`__init__` method. Changing them on an existing instance won't have
any effect; instead, create a subclass of :class:`RExec` and assign them new
values in the class definition. Instances of the new class will then use those
new values. All these attributes are tuples of strings.
.. attribute:: RExec.nok_builtin_names
Contains the names of built-in functions which will *not* be available to
programs running in the restricted environment. The value for :class:`RExec` is
``('open', 'reload', '__import__')``. (This gives the exceptions, because by far
the majority of built-in functions are harmless. A subclass that wants to
override this variable should probably start with the value from the base class
and concatenate additional forbidden functions --- when new dangerous built-in
functions are added to Python, they will also be added to this module.)
.. attribute:: RExec.ok_builtin_modules
Contains the names of built-in modules which can be safely imported. The value
for :class:`RExec` is ``('audioop', 'array', 'binascii', 'cmath', 'errno',
'imageop', 'marshal', 'math', 'md5', 'operator', 'parser', 'regex', 'select',
'sha', '_sre', 'strop', 'struct', 'time')``. A similar remark about overriding
this variable applies --- use the value from the base class as a starting point.
.. attribute:: RExec.ok_path
Contains the directories which will be searched when an :keyword:`import` is
performed in the restricted environment. The value for :class:`RExec` is the
same as ``sys.path`` (at the time the module is loaded) for unrestricted code.
.. attribute:: RExec.ok_posix_names
Contains the names of the functions in the :mod:`os` module which will be
available to programs running in the restricted environment. The value for
:class:`RExec` is ``('error', 'fstat', 'listdir', 'lstat', 'readlink', 'stat',
'times', 'uname', 'getpid', 'getppid', 'getcwd', 'getuid', 'getgid', 'geteuid',
'getegid')``.
.. Should this be called ok_os_names?
.. attribute:: RExec.ok_sys_names
Contains the names of the functions and variables in the :mod:`sys` module which
will be available to programs running in the restricted environment. The value
for :class:`RExec` is ``('ps1', 'ps2', 'copyright', 'version', 'platform',
'exit', 'maxint')``.
.. attribute:: RExec.ok_file_types
Contains the file types from which modules are allowed to be loaded. Each file
type is an integer constant defined in the :mod:`imp` module. The meaningful
values are :const:`PY_SOURCE`, :const:`PY_COMPILED`, and :const:`C_EXTENSION`.
The value for :class:`RExec` is ``(C_EXTENSION, PY_SOURCE)``. Adding
:const:`PY_COMPILED` in subclasses is not recommended; an attacker could exit
the restricted execution mode by putting a forged byte-compiled file
(:file:`.pyc`) anywhere in your file system, for example by writing it to
:file:`/tmp` or uploading it to the :file:`/incoming` directory of your public
FTP server.
An example
----------
Let us say that we want a slightly more relaxed policy than the standard
:class:`RExec` class. For example, if we're willing to allow files in
:file:`/tmp` to be written, we can subclass the :class:`RExec` class::
class TmpWriterRExec(rexec.RExec):
def r_open(self, file, mode='r', buf=-1):
if mode in ('r', 'rb'):
pass
elif mode in ('w', 'wb', 'a', 'ab'):
# check filename: must begin with /tmp/
if file[:5]!='/tmp/':
raise IOError("can't write outside /tmp")
elif (string.find(file, '/../') >= 0 or
file[:3] == '../' or file[-3:] == '/..'):
raise IOError("'..' in filename forbidden")
else: raise IOError("Illegal open() mode")
return open(file, mode, buf)
Notice that the above code will occasionally forbid a perfectly valid filename;
for example, code in the restricted environment won't be able to open a file
called :file:`/tmp/foo/../bar`. To fix this, the :meth:`r_open` method would
have to simplify the filename to :file:`/tmp/bar`, which would require splitting
apart the filename and performing various operations on it. In cases where
security is at stake, it may be preferable to write simple code which is
sometimes overly restrictive, instead of more general code that is also more
complex and may harbor a subtle security hole.
PK
%�\��0�6 �6 $ html/_sources/library/rfc822.rst.txtnu �[���
:mod:`rfc822` --- Parse RFC 2822 mail headers
=============================================
.. module:: rfc822
:synopsis: Parse 2822 style mail messages.
:deprecated:
.. deprecated:: 2.3
The :mod:`email` package should be used in preference to the :mod:`rfc822`
module. This module is present only to maintain backward compatibility, and
has been removed in Python 3.
This module defines a class, :class:`Message`, which represents an "email
message" as defined by the Internet standard :rfc:`2822`. [#]_ Such messages
consist of a collection of message headers, and a message body. This module
also defines a helper class :class:`AddressList` for parsing :rfc:`2822`
addresses. Please refer to the RFC for information on the specific syntax of
:rfc:`2822` messages.
.. index:: module: mailbox
The :mod:`mailbox` module provides classes to read mailboxes produced by
various end-user mail programs.
.. class:: Message(file[, seekable])
A :class:`Message` instance is instantiated with an input object as parameter.
Message relies only on the input object having a :meth:`readline` method; in
particular, ordinary file objects qualify. Instantiation reads headers from the
input object up to a delimiter line (normally a blank line) and stores them in
the instance. The message body, following the headers, is not consumed.
This class can work with any input object that supports a :meth:`readline`
method. If the input object has seek and tell capability, the
:meth:`rewindbody` method will work; also, illegal lines will be pushed back
onto the input stream. If the input object lacks seek but has an :meth:`unread`
method that can push back a line of input, :class:`Message` will use that to
push back illegal lines. Thus this class can be used to parse messages coming
from a buffered stream.
The optional *seekable* argument is provided as a workaround for certain stdio
libraries in which :c:func:`tell` discards buffered data before discovering that
the :c:func:`lseek` system call doesn't work. For maximum portability, you
should set the seekable argument to zero to prevent that initial :meth:`tell`
when passing in an unseekable object such as a file object created from a socket
object.
Input lines as read from the file may either be terminated by CR-LF or by a
single linefeed; a terminating CR-LF is replaced by a single linefeed before the
line is stored.
All header matching is done independent of upper or lower case; e.g.
``m['From']``, ``m['from']`` and ``m['FROM']`` all yield the same result.
.. class:: AddressList(field)
You may instantiate the :class:`AddressList` helper class using a single string
parameter, a comma-separated list of :rfc:`2822` addresses to be parsed. (The
parameter ``None`` yields an empty list.)
.. function:: quote(str)
Return a new string with backslashes in *str* replaced by two backslashes and
double quotes replaced by backslash-double quote.
.. function:: unquote(str)
Return a new string which is an *unquoted* version of *str*. If *str* ends and
begins with double quotes, they are stripped off. Likewise if *str* ends and
begins with angle brackets, they are stripped off.
.. function:: parseaddr(address)
Parse *address*, which should be the value of some address-containing field such
as :mailheader:`To` or :mailheader:`Cc`, into its constituent "realname" and
"email address" parts. Returns a tuple of that information, unless the parse
fails, in which case a 2-tuple ``(None, None)`` is returned.
.. function:: dump_address_pair(pair)
The inverse of :meth:`parseaddr`, this takes a 2-tuple of the form ``(realname,
email_address)`` and returns the string value suitable for a :mailheader:`To` or
:mailheader:`Cc` header. If the first element of *pair* is false, then the
second element is returned unmodified.
.. function:: parsedate(date)
Attempts to parse a date according to the rules in :rfc:`2822`. however, some
mailers don't follow that format as specified, so :func:`parsedate` tries to
guess correctly in such cases. *date* is a string containing an :rfc:`2822`
date, such as ``'Mon, 20 Nov 1995 19:12:08 -0500'``. If it succeeds in parsing
the date, :func:`parsedate` returns a 9-tuple that can be passed directly to
:func:`time.mktime`; otherwise ``None`` will be returned. Note that indexes 6,
7, and 8 of the result tuple are not usable.
.. function:: parsedate_tz(date)
Performs the same function as :func:`parsedate`, but returns either ``None`` or
a 10-tuple; the first 9 elements make up a tuple that can be passed directly to
:func:`time.mktime`, and the tenth is the offset of the date's timezone from UTC
(which is the official term for Greenwich Mean Time). (Note that the sign of
the timezone offset is the opposite of the sign of the ``time.timezone``
variable for the same timezone; the latter variable follows the POSIX standard
while this module follows :rfc:`2822`.) If the input string has no timezone,
the last element of the tuple returned is ``None``. Note that indexes 6, 7, and
8 of the result tuple are not usable.
.. function:: mktime_tz(tuple)
Turn a 10-tuple as returned by :func:`parsedate_tz` into a UTC timestamp. If
the timezone item in the tuple is ``None``, assume local time. Minor
deficiency: this first interprets the first 8 elements as a local time and then
compensates for the timezone difference; this may yield a slight error around
daylight savings time switch dates. Not enough to worry about for common use.
.. seealso::
Module :mod:`email`
Comprehensive email handling package; supersedes the :mod:`rfc822` module.
Module :mod:`mailbox`
Classes to read various mailbox formats produced by end-user mail programs.
Module :mod:`mimetools`
Subclass of :class:`rfc822.Message` that handles MIME encoded messages.
.. _message-objects:
Message Objects
---------------
A :class:`Message` instance has the following methods:
.. method:: Message.rewindbody()
Seek to the start of the message body. This only works if the file object is
seekable.
.. method:: Message.isheader(line)
Returns a line's canonicalized fieldname (the dictionary key that will be used
to index it) if the line is a legal :rfc:`2822` header; otherwise returns
``None`` (implying that parsing should stop here and the line be pushed back on
the input stream). It is sometimes useful to override this method in a
subclass.
.. method:: Message.islast(line)
Return true if the given line is a delimiter on which Message should stop. The
delimiter line is consumed, and the file object's read location positioned
immediately after it. By default this method just checks that the line is
blank, but you can override it in a subclass.
.. method:: Message.iscomment(line)
Return ``True`` if the given line should be ignored entirely, just skipped. By
default this is a stub that always returns ``False``, but you can override it in
a subclass.
.. method:: Message.getallmatchingheaders(name)
Return a list of lines consisting of all headers matching *name*, if any. Each
physical line, whether it is a continuation line or not, is a separate list
item. Return the empty list if no header matches *name*.
.. method:: Message.getfirstmatchingheader(name)
Return a list of lines comprising the first header matching *name*, and its
continuation line(s), if any. Return ``None`` if there is no header matching
*name*.
.. method:: Message.getrawheader(name)
Return a single string consisting of the text after the colon in the first
header matching *name*. This includes leading whitespace, the trailing
linefeed, and internal linefeeds and whitespace if there any continuation
line(s) were present. Return ``None`` if there is no header matching *name*.
.. method:: Message.getheader(name[, default])
Return a single string consisting of the last header matching *name*,
but strip leading and trailing whitespace.
Internal whitespace is not stripped. The optional *default* argument can be
used to specify a different default to be returned when there is no header
matching *name*; it defaults to ``None``.
This is the preferred way to get parsed headers.
.. method:: Message.get(name[, default])
An alias for :meth:`getheader`, to make the interface more compatible with
regular dictionaries.
.. method:: Message.getaddr(name)
Return a pair ``(full name, email address)`` parsed from the string returned by
``getheader(name)``. If no header matching *name* exists, return ``(None,
None)``; otherwise both the full name and the address are (possibly empty)
strings.
Example: If *m*'s first :mailheader:`From` header contains the string
``'jack@cwi.nl (Jack Jansen)'``, then ``m.getaddr('From')`` will yield the pair
``('Jack Jansen', 'jack@cwi.nl')``. If the header contained ``'Jack Jansen
<jack@cwi.nl>'`` instead, it would yield the exact same result.
.. method:: Message.getaddrlist(name)
This is similar to ``getaddr(list)``, but parses a header containing a list of
email addresses (e.g. a :mailheader:`To` header) and returns a list of ``(full
name, email address)`` pairs (even if there was only one address in the header).
If there is no header matching *name*, return an empty list.
If multiple headers exist that match the named header (e.g. if there are several
:mailheader:`Cc` headers), all are parsed for addresses. Any continuation lines
the named headers contain are also parsed.
.. method:: Message.getdate(name)
Retrieve a header using :meth:`getheader` and parse it into a 9-tuple compatible
with :func:`time.mktime`; note that fields 6, 7, and 8 are not usable. If
there is no header matching *name*, or it is unparsable, return ``None``.
Date parsing appears to be a black art, and not all mailers adhere to the
standard. While it has been tested and found correct on a large collection of
email from many sources, it is still possible that this function may
occasionally yield an incorrect result.
.. method:: Message.getdate_tz(name)
Retrieve a header using :meth:`getheader` and parse it into a 10-tuple; the
first 9 elements will make a tuple compatible with :func:`time.mktime`, and the
10th is a number giving the offset of the date's timezone from UTC. Note that
fields 6, 7, and 8 are not usable. Similarly to :meth:`getdate`, if there is
no header matching *name*, or it is unparsable, return ``None``.
:class:`Message` instances also support a limited mapping interface. In
particular: ``m[name]`` is like ``m.getheader(name)`` but raises :exc:`KeyError`
if there is no matching header; and ``len(m)``, ``m.get(name[, default])``,
``name in m``, ``m.keys()``, ``m.values()`` ``m.items()``, and
``m.setdefault(name[, default])`` act as expected, with the one difference
that :meth:`setdefault` uses an empty string as the default value.
:class:`Message` instances also support the mapping writable interface ``m[name]
= value`` and ``del m[name]``. :class:`Message` objects do not support the
:meth:`clear`, :meth:`copy`, :meth:`popitem`, or :meth:`update` methods of the
mapping interface. (Support for :meth:`get` and :meth:`setdefault` was only
added in Python 2.2.)
Finally, :class:`Message` instances have some public instance variables:
.. attribute:: Message.headers
A list containing the entire set of header lines, in the order in which they
were read (except that setitem calls may disturb this order). Each line contains
a trailing newline. The blank line terminating the headers is not contained in
the list.
.. attribute:: Message.fp
The file or file-like object passed at instantiation time. This can be used to
read the message content.
.. attribute:: Message.unixfrom
The Unix ``From`` line, if the message had one, or an empty string. This is
needed to regenerate the message in some contexts, such as an ``mbox``\ -style
mailbox file.
.. _addresslist-objects:
AddressList Objects
-------------------
An :class:`AddressList` instance has the following methods:
.. method:: AddressList.__len__()
Return the number of addresses in the address list.
.. method:: AddressList.__str__()
Return a canonicalized string representation of the address list. Addresses are
rendered in "name" <host@domain> form, comma-separated.
.. method:: AddressList.__add__(alist)
Return a new :class:`AddressList` instance that contains all addresses in both
:class:`AddressList` operands, with duplicates removed (set union).
.. method:: AddressList.__iadd__(alist)
In-place version of :meth:`__add__`; turns this :class:`AddressList` instance
into the union of itself and the right-hand instance, *alist*.
.. method:: AddressList.__sub__(alist)
Return a new :class:`AddressList` instance that contains every address in the
left-hand :class:`AddressList` operand that is not present in the right-hand
address operand (set difference).
.. method:: AddressList.__isub__(alist)
In-place version of :meth:`__sub__`, removing addresses in this list which are
also in *alist*.
Finally, :class:`AddressList` instances have one public instance variable:
.. attribute:: AddressList.addresslist
A list of tuple string pairs, one per address. In each member, the first is the
canonicalized name part, the second is the actual route-address (``'@'``\
-separated username-host.domain pair).
.. rubric:: Footnotes
.. [#] This module originally conformed to :rfc:`822`, hence the name. Since then,
:rfc:`2822` has been released as an update to :rfc:`822`. This module should be
considered :rfc:`2822`\ -conformant, especially in cases where the syntax or
semantics have changed since :rfc:`822`.
PK
%�\=E� � ) html/_sources/library/rlcompleter.rst.txtnu �[��� :mod:`rlcompleter` --- Completion function for GNU readline
===========================================================
.. module:: rlcompleter
:synopsis: Python identifier completion, suitable for the GNU readline library.
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
**Source code:** :source:`Lib/rlcompleter.py`
--------------
The :mod:`rlcompleter` module defines a completion function suitable for the
:mod:`readline` module by completing valid Python identifiers and keywords.
When this module is imported on a Unix platform with the :mod:`readline` module
available, an instance of the :class:`Completer` class is automatically created
and its :meth:`complete` method is set as the :mod:`readline` completer.
Example::
>>> import rlcompleter
>>> import readline
>>> readline.parse_and_bind("tab: complete")
>>> readline. <TAB PRESSED>
readline.__doc__ readline.get_line_buffer( readline.read_init_file(
readline.__file__ readline.insert_text( readline.set_completer(
readline.__name__ readline.parse_and_bind(
>>> readline.
The :mod:`rlcompleter` module is designed for use with Python's interactive
mode. A user can add the following lines to his or her initialization file
(identified by the :envvar:`PYTHONSTARTUP` environment variable) to get
automatic :kbd:`Tab` completion::
try:
import readline
except ImportError:
print "Module readline not available."
else:
import rlcompleter
readline.parse_and_bind("tab: complete")
On platforms without :mod:`readline`, the :class:`Completer` class defined by
this module can still be used for custom purposes.
.. _completer-objects:
Completer Objects
-----------------
Completer objects have the following method:
.. method:: Completer.complete(text, state)
Return the *state*\ th completion for *text*.
If called for *text* that doesn't include a period character (``'.'``), it will
complete from names currently defined in :mod:`__main__`, :mod:`__builtin__` and
keywords (as defined by the :mod:`keyword` module).
If called for a dotted name, it will try to evaluate anything without obvious
side-effects (functions will not be evaluated, but it can generate calls to
:meth:`__getattr__`) up to the last part, and find matches for the rest via the
:func:`dir` function. Any exception raised during the evaluation of the
expression is caught, silenced and :const:`None` is returned.
PK
%�\kYmƎ � ) html/_sources/library/robotparser.rst.txtnu �[���
:mod:`robotparser` --- Parser for robots.txt
=============================================
.. module:: robotparser
:synopsis: Loads a robots.txt file and answers questions about
fetchability of other URLs.
.. sectionauthor:: Skip Montanaro <skip@pobox.com>
.. index::
single: WWW
single: World Wide Web
single: URL
single: robots.txt
.. note::
The :mod:`robotparser` module has been renamed :mod:`urllib.robotparser` in
Python 3.
The :term:`2to3` tool will automatically adapt imports when converting
your sources to Python 3.
This module provides a single class, :class:`RobotFileParser`, which answers
questions about whether or not a particular user agent can fetch a URL on the
Web site that published the :file:`robots.txt` file. For more details on the
structure of :file:`robots.txt` files, see http://www.robotstxt.org/orig.html.
.. class:: RobotFileParser(url='')
This class provides methods to read, parse and answer questions about the
:file:`robots.txt` file at *url*.
.. method:: set_url(url)
Sets the URL referring to a :file:`robots.txt` file.
.. method:: read()
Reads the :file:`robots.txt` URL and feeds it to the parser.
.. method:: parse(lines)
Parses the lines argument.
.. method:: can_fetch(useragent, url)
Returns ``True`` if the *useragent* is allowed to fetch the *url*
according to the rules contained in the parsed :file:`robots.txt`
file.
.. method:: mtime()
Returns the time the ``robots.txt`` file was last fetched. This is
useful for long-running web spiders that need to check for new
``robots.txt`` files periodically.
.. method:: modified()
Sets the time the ``robots.txt`` file was last fetched to the current
time.
The following example demonstrates basic use of the RobotFileParser class. ::
>>> import robotparser
>>> rp = robotparser.RobotFileParser()
>>> rp.set_url("http://www.musi-cal.com/robots.txt")
>>> rp.read()
>>> rp.can_fetch("*", "http://www.musi-cal.com/cgi-bin/search?city=San+Francisco")
False
>>> rp.can_fetch("*", "http://www.musi-cal.com/")
True
PK
%�\�� # html/_sources/library/runpy.rst.txtnu �[��� :mod:`runpy` --- Locating and executing Python modules
======================================================
.. module:: runpy
:synopsis: Locate and run Python modules without importing them first.
.. moduleauthor:: Nick Coghlan <ncoghlan@gmail.com>
.. versionadded:: 2.5
**Source code:** :source:`Lib/runpy.py`
--------------
The :mod:`runpy` module is used to locate and run Python modules without
importing them first. Its main use is to implement the :option:`-m` command
line switch that allows scripts to be located using the Python module
namespace rather than the filesystem.
The :mod:`runpy` module provides two functions:
.. function:: run_module(mod_name, init_globals=None, run_name=None, alter_sys=False)
.. index::
module: __main__
Execute the code of the specified module and return the resulting module
globals dictionary. The module's code is first located using the standard
import mechanism (refer to :pep:`302` for details) and then executed in a
fresh module namespace.
If the supplied module name refers to a package rather than a normal
module, then that package is imported and the ``__main__`` submodule within
that package is then executed and the resulting module globals dictionary
returned.
The optional dictionary argument *init_globals* may be used to pre-populate
the module's globals dictionary before the code is executed. The supplied
dictionary will not be modified. If any of the special global variables
below are defined in the supplied dictionary, those definitions are
overridden by :func:`run_module`.
The special global variables ``__name__``, ``__file__``, ``__loader__``
and ``__package__`` are set in the globals dictionary before the module
code is executed (Note that this is a minimal set of variables - other
variables may be set implicitly as an interpreter implementation detail).
``__name__`` is set to *run_name* if this optional argument is not
:const:`None`, to ``mod_name + '.__main__'`` if the named module is a
package and to the *mod_name* argument otherwise.
``__file__`` is set to the name provided by the module loader. If the
loader does not make filename information available, this variable is set
to :const:`None`.
``__loader__`` is set to the :pep:`302` module loader used to retrieve the
code for the module (This loader may be a wrapper around the standard
import mechanism).
``__package__`` is set to *mod_name* if the named module is a package and
to ``mod_name.rpartition('.')[0]`` otherwise.
If the argument *alter_sys* is supplied and evaluates to :const:`True`,
then ``sys.argv[0]`` is updated with the value of ``__file__`` and
``sys.modules[__name__]`` is updated with a temporary module object for the
module being executed. Both ``sys.argv[0]`` and ``sys.modules[__name__]``
are restored to their original values before the function returns.
Note that this manipulation of :mod:`sys` is not thread-safe. Other threads
may see the partially initialised module, as well as the altered list of
arguments. It is recommended that the :mod:`sys` module be left alone when
invoking this function from threaded code.
.. seealso::
The :option:`-m` option offering equivalent functionality from the
command line.
.. versionchanged:: 2.7
Added ability to execute packages by looking for a ``__main__``
submodule
.. function:: run_path(file_path, init_globals=None, run_name=None)
.. index::
module: __main__
Execute the code at the named filesystem location and return the resulting
module globals dictionary. As with a script name supplied to the CPython
command line, the supplied path may refer to a Python source file, a
compiled bytecode file or a valid sys.path entry containing a ``__main__``
module (e.g. a zipfile containing a top-level ``__main__.py`` file).
For a simple script, the specified code is simply executed in a fresh
module namespace. For a valid sys.path entry (typically a zipfile or
directory), the entry is first added to the beginning of ``sys.path``. The
function then looks for and executes a :mod:`__main__` module using the
updated path. Note that there is no special protection against invoking
an existing :mod:`__main__` entry located elsewhere on ``sys.path`` if
there is no such module at the specified location.
The optional dictionary argument *init_globals* may be used to pre-populate
the module's globals dictionary before the code is executed. The supplied
dictionary will not be modified. If any of the special global variables
below are defined in the supplied dictionary, those definitions are
overridden by :func:`run_path`.
The special global variables ``__name__``, ``__file__``, ``__loader__``
and ``__package__`` are set in the globals dictionary before the module
code is executed (Note that this is a minimal set of variables - other
variables may be set implicitly as an interpreter implementation detail).
``__name__`` is set to *run_name* if this optional argument is not
:const:`None` and to ``'<run_path>'`` otherwise.
``__file__`` is set to the name provided by the module loader. If the
loader does not make filename information available, this variable is set
to :const:`None`. For a simple script, this will be set to ``file_path``.
``__loader__`` is set to the :pep:`302` module loader used to retrieve the
code for the module (This loader may be a wrapper around the standard
import mechanism). For a simple script, this will be set to :const:`None`.
``__package__`` is set to ``__name__.rpartition('.')[0]``.
A number of alterations are also made to the :mod:`sys` module. Firstly,
``sys.path`` may be altered as described above. ``sys.argv[0]`` is updated
with the value of ``file_path`` and ``sys.modules[__name__]`` is updated
with a temporary module object for the module being executed. All
modifications to items in :mod:`sys` are reverted before the function
returns.
Note that, unlike :func:`run_module`, the alterations made to :mod:`sys`
are not optional in this function as these adjustments are essential to
allowing the execution of sys.path entries. As the thread-safety
limitations still apply, use of this function in threaded code should be
either serialised with the import lock or delegated to a separate process.
.. seealso::
:ref:`using-on-interface-options` for equivalent functionality on the
command line (``python path/to/script``).
.. versionadded:: 2.7
.. seealso::
:pep:`338` -- Executing modules as scripts
PEP written and implemented by Nick Coghlan.
:pep:`366` -- Main module explicit relative imports
PEP written and implemented by Nick Coghlan.
:ref:`using-on-general` - CPython command line details
PK
%�\�#�$ $ # html/_sources/library/sched.rst.txtnu �[��� :mod:`sched` --- Event scheduler
================================
.. module:: sched
:synopsis: General purpose event scheduler.
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
.. index:: single: event scheduling
**Source code:** :source:`Lib/sched.py`
--------------
The :mod:`sched` module defines a class which implements a general purpose event
scheduler:
.. class:: scheduler(timefunc, delayfunc)
The :class:`scheduler` class defines a generic interface to scheduling events.
It needs two functions to actually deal with the "outside world" --- *timefunc*
should be callable without arguments, and return a number (the "time", in any
units whatsoever). The *delayfunc* function should be callable with one
argument, compatible with the output of *timefunc*, and should delay that many
time units. *delayfunc* will also be called with the argument ``0`` after each
event is run to allow other threads an opportunity to run in multi-threaded
applications.
Example::
>>> import sched, time
>>> s = sched.scheduler(time.time, time.sleep)
>>> def print_time(): print "From print_time", time.time()
...
>>> def print_some_times():
... print time.time()
... s.enter(5, 1, print_time, ())
... s.enter(10, 1, print_time, ())
... s.run()
... print time.time()
...
>>> print_some_times()
930343690.257
From print_time 930343695.274
From print_time 930343700.273
930343700.276
In multi-threaded environments, the :class:`scheduler` class has limitations
with respect to thread-safety, inability to insert a new task before
the one currently pending in a running scheduler, and holding up the main
thread until the event queue is empty. Instead, the preferred approach
is to use the :class:`threading.Timer` class instead.
Example::
>>> import time
>>> from threading import Timer
>>> def print_time():
... print "From print_time", time.time()
...
>>> def print_some_times():
... print time.time()
... Timer(5, print_time, ()).start()
... Timer(10, print_time, ()).start()
... time.sleep(11) # sleep while time-delay events execute
... print time.time()
...
>>> print_some_times()
930343690.257
From print_time 930343695.274
From print_time 930343700.273
930343701.301
.. _scheduler-objects:
Scheduler Objects
-----------------
:class:`scheduler` instances have the following methods and attributes:
.. method:: scheduler.enterabs(time, priority, action, argument)
Schedule a new event. The *time* argument should be a numeric type compatible
with the return value of the *timefunc* function passed to the constructor.
Events scheduled for the same *time* will be executed in the order of their
*priority*. A lower number represents a higher priority.
Executing the event means executing ``action(*argument)``. *argument* must be a
sequence holding the parameters for *action*.
Return value is an event which may be used for later cancellation of the event
(see :meth:`cancel`).
.. method:: scheduler.enter(delay, priority, action, argument)
Schedule an event for *delay* more time units. Other than the relative time, the
other arguments, the effect and the return value are the same as those for
:meth:`enterabs`.
.. method:: scheduler.cancel(event)
Remove the event from the queue. If *event* is not an event currently in the
queue, this method will raise a :exc:`ValueError`.
.. method:: scheduler.empty()
Return true if the event queue is empty.
.. method:: scheduler.run()
Run all scheduled events. This function will wait (using the :func:`delayfunc`
function passed to the constructor) for the next event, then execute it and so
on until there are no more scheduled events.
Either *action* or *delayfunc* can raise an exception. In either case, the
scheduler will maintain a consistent state and propagate the exception. If an
exception is raised by *action*, the event will not be attempted in future calls
to :meth:`run`.
If a sequence of events takes longer to run than the time available before the
next event, the scheduler will simply fall behind. No events will be dropped;
the calling code is responsible for canceling events which are no longer
pertinent.
.. attribute:: scheduler.queue
Read-only attribute returning a list of upcoming events in the order they
will be run. Each event is shown as a :term:`named tuple` with the
following fields: time, priority, action, argument.
.. versionadded:: 2.6
PK
%�\!��!c c * html/_sources/library/scrolledtext.rst.txtnu �[��� :mod:`ScrolledText` --- Scrolled Text Widget
============================================
.. module:: ScrolledText
:platform: Tk
:synopsis: Text widget with a vertical scroll bar.
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
The :mod:`ScrolledText` module provides a class of the same name which
implements a basic text widget which has a vertical scroll bar configured to do
the "right thing." Using the :class:`~ScrolledText.ScrolledText` class is a lot easier than
setting up a text widget and scroll bar directly. The constructor is the same
as that of the :class:`Tkinter.Text` class.
.. note::
:mod:`ScrolledText` has been renamed to :mod:`tkinter.scrolledtext` in Python
3. The :term:`2to3` tool will automatically adapt imports when converting
your sources to Python 3.
The text widget and scrollbar are packed together in a :class:`Frame`, and the
methods of the :class:`Grid` and :class:`Pack` geometry managers are acquired
from the :class:`Frame` object. This allows the :class:`~ScrolledText.ScrolledText` widget to
be used directly to achieve most normal geometry management behavior.
Should more specific control be necessary, the following attributes are
available:
.. attribute:: ScrolledText.frame
The frame which surrounds the text and scroll bar widgets.
.. attribute:: ScrolledText.vbar
The scroll bar widget.
PK
%�\ RU�P �P $ html/_sources/library/select.rst.txtnu �[���
:mod:`select` --- Waiting for I/O completion
============================================
.. module:: select
:synopsis: Wait for I/O completion on multiple streams.
This module provides access to the :c:func:`select` and :c:func:`poll` functions
available in most operating systems, :c:func:`epoll` available on Linux 2.5+ and
:c:func:`kqueue` available on most BSD.
Note that on Windows, it only works for sockets; on other operating systems,
it also works for other file types (in particular, on Unix, it works on pipes).
It cannot be used on regular files to determine whether a file has grown since
it was last read.
The module defines the following:
.. exception:: error
The exception raised when an error occurs. The accompanying value is a pair
containing the numeric error code from :c:data:`errno` and the corresponding
string, as would be printed by the C function :c:func:`perror`.
.. function:: epoll([sizehint=-1])
(Only supported on Linux 2.5.44 and newer.) Returns an edge polling object,
which can be used as Edge or Level Triggered interface for I/O events; see
section :ref:`epoll-objects` below for the methods supported by epolling
objects.
.. versionadded:: 2.6
.. function:: poll()
(Not supported by all operating systems.) Returns a polling object, which
supports registering and unregistering file descriptors, and then polling them
for I/O events; see section :ref:`poll-objects` below for the methods supported
by polling objects.
.. function:: kqueue()
(Only supported on BSD.) Returns a kernel queue object; see section
:ref:`kqueue-objects` below for the methods supported by kqueue objects.
.. versionadded:: 2.6
.. function:: kevent(ident, filter=KQ_FILTER_READ, flags=KQ_EV_ADD, fflags=0, data=0, udata=0)
(Only supported on BSD.) Returns a kernel event object; see section
:ref:`kevent-objects` below for the methods supported by kevent objects.
.. versionadded:: 2.6
.. function:: select(rlist, wlist, xlist[, timeout])
This is a straightforward interface to the Unix :c:func:`select` system call.
The first three arguments are sequences of 'waitable objects': either
integers representing file descriptors or objects with a parameterless method
named :meth:`~io.IOBase.fileno` returning such an integer:
* *rlist*: wait until ready for reading
* *wlist*: wait until ready for writing
* *xlist*: wait for an "exceptional condition" (see the manual page for what
your system considers such a condition)
Empty sequences are allowed, but acceptance of three empty sequences is
platform-dependent. (It is known to work on Unix but not on Windows.) The
optional *timeout* argument specifies a time-out as a floating point number
in seconds. When the *timeout* argument is omitted the function blocks until
at least one file descriptor is ready. A time-out value of zero specifies a
poll and never blocks.
The return value is a triple of lists of objects that are ready: subsets of the
first three arguments. When the time-out is reached without a file descriptor
becoming ready, three empty lists are returned.
.. index::
single: socket() (in module socket)
single: popen() (in module os)
Among the acceptable object types in the sequences are Python file objects (e.g.
``sys.stdin``, or objects returned by :func:`open` or :func:`os.popen`), socket
objects returned by :func:`socket.socket`. You may also define a :dfn:`wrapper`
class yourself, as long as it has an appropriate :meth:`~io.IOBase.fileno`
method (that really returns a file descriptor, not just a random integer).
.. note::
.. index:: single: WinSock
File objects on Windows are not acceptable, but sockets are. On Windows,
the underlying :c:func:`select` function is provided by the WinSock
library, and does not handle file descriptors that don't originate from
WinSock.
.. attribute:: select.PIPE_BUF
Files reported as ready for writing by :func:`select`, :func:`poll` or
similar interfaces in this module are guaranteed to not block on a write
of up to :const:`PIPE_BUF` bytes.
This value is guaranteed by POSIX to be at least 512. Availability: Unix.
.. versionadded:: 2.7
.. _epoll-objects:
Edge and Level Trigger Polling (epoll) Objects
----------------------------------------------
http://linux.die.net/man/4/epoll
*eventmask*
+-----------------------+-----------------------------------------------+
| Constant | Meaning |
+=======================+===============================================+
| :const:`EPOLLIN` | Available for read |
+-----------------------+-----------------------------------------------+
| :const:`EPOLLOUT` | Available for write |
+-----------------------+-----------------------------------------------+
| :const:`EPOLLPRI` | Urgent data for read |
+-----------------------+-----------------------------------------------+
| :const:`EPOLLERR` | Error condition happened on the assoc. fd |
+-----------------------+-----------------------------------------------+
| :const:`EPOLLHUP` | Hang up happened on the assoc. fd |
+-----------------------+-----------------------------------------------+
| :const:`EPOLLET` | Set Edge Trigger behavior, the default is |
| | Level Trigger behavior |
+-----------------------+-----------------------------------------------+
| :const:`EPOLLONESHOT` | Set one-shot behavior. After one event is |
| | pulled out, the fd is internally disabled |
+-----------------------+-----------------------------------------------+
| :const:`EPOLLRDNORM` | Equivalent to :const:`EPOLLIN` |
+-----------------------+-----------------------------------------------+
| :const:`EPOLLRDBAND` | Priority data band can be read. |
+-----------------------+-----------------------------------------------+
| :const:`EPOLLWRNORM` | Equivalent to :const:`EPOLLOUT` |
+-----------------------+-----------------------------------------------+
| :const:`EPOLLWRBAND` | Priority data may be written. |
+-----------------------+-----------------------------------------------+
| :const:`EPOLLMSG` | Ignored. |
+-----------------------+-----------------------------------------------+
.. method:: epoll.close()
Close the control file descriptor of the epoll object.
.. method:: epoll.fileno()
Return the file descriptor number of the control fd.
.. method:: epoll.fromfd(fd)
Create an epoll object from a given file descriptor.
.. method:: epoll.register(fd[, eventmask])
Register a fd descriptor with the epoll object.
.. note::
Registering a file descriptor that's already registered raises an
IOError -- contrary to :ref:`poll-objects`'s register.
.. method:: epoll.modify(fd, eventmask)
Modify a register file descriptor.
.. method:: epoll.unregister(fd)
Remove a registered file descriptor from the epoll object.
.. method:: epoll.poll([timeout=-1[, maxevents=-1]])
Wait for events. timeout in seconds (float)
.. _poll-objects:
Polling Objects
---------------
The :c:func:`poll` system call, supported on most Unix systems, provides better
scalability for network servers that service many, many clients at the same
time. :c:func:`poll` scales better because the system call only requires listing
the file descriptors of interest, while :c:func:`select` builds a bitmap, turns
on bits for the fds of interest, and then afterward the whole bitmap has to be
linearly scanned again. :c:func:`select` is O(highest file descriptor), while
:c:func:`poll` is O(number of file descriptors).
.. method:: poll.register(fd[, eventmask])
Register a file descriptor with the polling object. Future calls to the
:meth:`poll` method will then check whether the file descriptor has any
pending I/O events. *fd* can be either an integer, or an object with a
:meth:`~io.IOBase.fileno` method that returns an integer. File objects
implement :meth:`!fileno`, so they can also be used as the argument.
*eventmask* is an optional bitmask describing the type of events you want to
check for, and can be a combination of the constants :const:`POLLIN`,
:const:`POLLPRI`, and :const:`POLLOUT`, described in the table below. If not
specified, the default value used will check for all 3 types of events.
+-------------------+------------------------------------------+
| Constant | Meaning |
+===================+==========================================+
| :const:`POLLIN` | There is data to read |
+-------------------+------------------------------------------+
| :const:`POLLPRI` | There is urgent data to read |
+-------------------+------------------------------------------+
| :const:`POLLOUT` | Ready for output: writing will not block |
+-------------------+------------------------------------------+
| :const:`POLLERR` | Error condition of some sort |
+-------------------+------------------------------------------+
| :const:`POLLHUP` | Hung up |
+-------------------+------------------------------------------+
| :const:`POLLNVAL` | Invalid request: descriptor not open |
+-------------------+------------------------------------------+
Registering a file descriptor that's already registered is not an error, and has
the same effect as registering the descriptor exactly once.
.. method:: poll.modify(fd, eventmask)
Modifies an already registered fd. This has the same effect as
``register(fd, eventmask)``. Attempting to modify a file descriptor
that was never registered causes an :exc:`IOError` exception with errno
:const:`ENOENT` to be raised.
.. versionadded:: 2.6
.. method:: poll.unregister(fd)
Remove a file descriptor being tracked by a polling object. Just like the
:meth:`register` method, *fd* can be an integer or an object with a
:meth:`~io.IOBase.fileno` method that returns an integer.
Attempting to remove a file descriptor that was never registered causes a
:exc:`KeyError` exception to be raised.
.. method:: poll.poll([timeout])
Polls the set of registered file descriptors, and returns a possibly-empty list
containing ``(fd, event)`` 2-tuples for the descriptors that have events or
errors to report. *fd* is the file descriptor, and *event* is a bitmask with
bits set for the reported events for that descriptor --- :const:`POLLIN` for
waiting input, :const:`POLLOUT` to indicate that the descriptor can be written
to, and so forth. An empty list indicates that the call timed out and no file
descriptors had any events to report. If *timeout* is given, it specifies the
length of time in milliseconds which the system will wait for events before
returning. If *timeout* is omitted, negative, or :const:`None`, the call will
block until there is an event for this poll object.
.. _kqueue-objects:
Kqueue Objects
--------------
.. method:: kqueue.close()
Close the control file descriptor of the kqueue object.
.. method:: kqueue.fileno()
Return the file descriptor number of the control fd.
.. method:: kqueue.fromfd(fd)
Create a kqueue object from a given file descriptor.
.. method:: kqueue.control(changelist, max_events[, timeout=None]) -> eventlist
Low level interface to kevent
- changelist must be an iterable of kevent object or ``None``
- max_events must be 0 or a positive integer
- timeout in seconds (floats possible)
.. _kevent-objects:
Kevent Objects
--------------
https://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2
.. attribute:: kevent.ident
Value used to identify the event. The interpretation depends on the filter
but it's usually the file descriptor. In the constructor ident can either
be an int or an object with a fileno() function. kevent stores the integer
internally.
.. attribute:: kevent.filter
Name of the kernel filter.
+---------------------------+---------------------------------------------+
| Constant | Meaning |
+===========================+=============================================+
| :const:`KQ_FILTER_READ` | Takes a descriptor and returns whenever |
| | there is data available to read |
+---------------------------+---------------------------------------------+
| :const:`KQ_FILTER_WRITE` | Takes a descriptor and returns whenever |
| | there is data available to write |
+---------------------------+---------------------------------------------+
| :const:`KQ_FILTER_AIO` | AIO requests |
+---------------------------+---------------------------------------------+
| :const:`KQ_FILTER_VNODE` | Returns when one or more of the requested |
| | events watched in *fflag* occurs |
+---------------------------+---------------------------------------------+
| :const:`KQ_FILTER_PROC` | Watch for events on a process id |
+---------------------------+---------------------------------------------+
| :const:`KQ_FILTER_NETDEV` | Watch for events on a network device |
| | [not available on Mac OS X] |
+---------------------------+---------------------------------------------+
| :const:`KQ_FILTER_SIGNAL` | Returns whenever the watched signal is |
| | delivered to the process |
+---------------------------+---------------------------------------------+
| :const:`KQ_FILTER_TIMER` | Establishes an arbitrary timer |
+---------------------------+---------------------------------------------+
.. attribute:: kevent.flags
Filter action.
+---------------------------+---------------------------------------------+
| Constant | Meaning |
+===========================+=============================================+
| :const:`KQ_EV_ADD` | Adds or modifies an event |
+---------------------------+---------------------------------------------+
| :const:`KQ_EV_DELETE` | Removes an event from the queue |
+---------------------------+---------------------------------------------+
| :const:`KQ_EV_ENABLE` | Permitscontrol() to returns the event |
+---------------------------+---------------------------------------------+
| :const:`KQ_EV_DISABLE` | Disablesevent |
+---------------------------+---------------------------------------------+
| :const:`KQ_EV_ONESHOT` | Removes event after first occurrence |
+---------------------------+---------------------------------------------+
| :const:`KQ_EV_CLEAR` | Reset the state after an event is retrieved |
+---------------------------+---------------------------------------------+
| :const:`KQ_EV_SYSFLAGS` | internal event |
+---------------------------+---------------------------------------------+
| :const:`KQ_EV_FLAG1` | internal event |
+---------------------------+---------------------------------------------+
| :const:`KQ_EV_EOF` | Filter specific EOF condition |
+---------------------------+---------------------------------------------+
| :const:`KQ_EV_ERROR` | See return values |
+---------------------------+---------------------------------------------+
.. attribute:: kevent.fflags
Filter specific flags.
:const:`KQ_FILTER_READ` and :const:`KQ_FILTER_WRITE` filter flags:
+----------------------------+--------------------------------------------+
| Constant | Meaning |
+============================+============================================+
| :const:`KQ_NOTE_LOWAT` | low water mark of a socket buffer |
+----------------------------+--------------------------------------------+
:const:`KQ_FILTER_VNODE` filter flags:
+----------------------------+--------------------------------------------+
| Constant | Meaning |
+============================+============================================+
| :const:`KQ_NOTE_DELETE` | *unlink()* was called |
+----------------------------+--------------------------------------------+
| :const:`KQ_NOTE_WRITE` | a write occurred |
+----------------------------+--------------------------------------------+
| :const:`KQ_NOTE_EXTEND` | the file was extended |
+----------------------------+--------------------------------------------+
| :const:`KQ_NOTE_ATTRIB` | an attribute was changed |
+----------------------------+--------------------------------------------+
| :const:`KQ_NOTE_LINK` | the link count has changed |
+----------------------------+--------------------------------------------+
| :const:`KQ_NOTE_RENAME` | the file was renamed |
+----------------------------+--------------------------------------------+
| :const:`KQ_NOTE_REVOKE` | access to the file was revoked |
+----------------------------+--------------------------------------------+
:const:`KQ_FILTER_PROC` filter flags:
+----------------------------+--------------------------------------------+
| Constant | Meaning |
+============================+============================================+
| :const:`KQ_NOTE_EXIT` | the process has exited |
+----------------------------+--------------------------------------------+
| :const:`KQ_NOTE_FORK` | the process has called *fork()* |
+----------------------------+--------------------------------------------+
| :const:`KQ_NOTE_EXEC` | the process has executed a new process |
+----------------------------+--------------------------------------------+
| :const:`KQ_NOTE_PCTRLMASK` | internal filter flag |
+----------------------------+--------------------------------------------+
| :const:`KQ_NOTE_PDATAMASK` | internal filter flag |
+----------------------------+--------------------------------------------+
| :const:`KQ_NOTE_TRACK` | follow a process across *fork()* |
+----------------------------+--------------------------------------------+
| :const:`KQ_NOTE_CHILD` | returned on the child process for |
| | *NOTE_TRACK* |
+----------------------------+--------------------------------------------+
| :const:`KQ_NOTE_TRACKERR` | unable to attach to a child |
+----------------------------+--------------------------------------------+
:const:`KQ_FILTER_NETDEV` filter flags (not available on Mac OS X):
+----------------------------+--------------------------------------------+
| Constant | Meaning |
+============================+============================================+
| :const:`KQ_NOTE_LINKUP` | link is up |
+----------------------------+--------------------------------------------+
| :const:`KQ_NOTE_LINKDOWN` | link is down |
+----------------------------+--------------------------------------------+
| :const:`KQ_NOTE_LINKINV` | link state is invalid |
+----------------------------+--------------------------------------------+
.. attribute:: kevent.data
Filter specific data.
.. attribute:: kevent.udata
User defined value.
PK
%�\� � }: }: " html/_sources/library/sets.rst.txtnu �[���
:mod:`sets` --- Unordered collections of unique elements
========================================================
.. module:: sets
:synopsis: Implementation of sets of unique elements.
:deprecated:
.. moduleauthor:: Greg V. Wilson <gvwilson@nevex.com>
.. moduleauthor:: Alex Martelli <aleax@aleax.it>
.. moduleauthor:: Guido van Rossum <guido@python.org>
.. sectionauthor:: Raymond D. Hettinger <python@rcn.com>
.. versionadded:: 2.3
.. deprecated:: 2.6
The built-in :class:`set`/:class:`frozenset` types replace this module.
The :mod:`sets` module provides classes for constructing and manipulating
unordered collections of unique elements. Common uses include membership
testing, removing duplicates from a sequence, and computing standard math
operations on sets such as intersection, union, difference, and symmetric
difference.
Like other collections, sets support ``x in set``, ``len(set)``, and ``for x in
set``. Being an unordered collection, sets do not record element position or
order of insertion. Accordingly, sets do not support indexing, slicing, or
other sequence-like behavior.
Most set applications use the :class:`Set` class which provides every set method
except for :meth:`__hash__`. For advanced applications requiring a hash method,
the :class:`ImmutableSet` class adds a :meth:`__hash__` method but omits methods
which alter the contents of the set. Both :class:`Set` and :class:`ImmutableSet`
derive from :class:`BaseSet`, an abstract class useful for determining whether
something is a set: ``isinstance(obj, BaseSet)``.
The set classes are implemented using dictionaries. Accordingly, the
requirements for set elements are the same as those for dictionary keys; namely,
that the element defines both :meth:`__eq__` and :meth:`__hash__`. As a result,
sets cannot contain mutable elements such as lists or dictionaries. However,
they can contain immutable collections such as tuples or instances of
:class:`ImmutableSet`. For convenience in implementing sets of sets, inner sets
are automatically converted to immutable form, for example,
``Set([Set(['dog'])])`` is transformed to ``Set([ImmutableSet(['dog'])])``.
.. class:: Set([iterable])
Constructs a new empty :class:`Set` object. If the optional *iterable*
parameter is supplied, updates the set with elements obtained from iteration.
All of the elements in *iterable* should be immutable or be transformable to an
immutable using the protocol described in section :ref:`immutable-transforms`.
.. class:: ImmutableSet([iterable])
Constructs a new empty :class:`ImmutableSet` object. If the optional *iterable*
parameter is supplied, updates the set with elements obtained from iteration.
All of the elements in *iterable* should be immutable or be transformable to an
immutable using the protocol described in section :ref:`immutable-transforms`.
Because :class:`ImmutableSet` objects provide a :meth:`__hash__` method, they
can be used as set elements or as dictionary keys. :class:`ImmutableSet`
objects do not have methods for adding or removing elements, so all of the
elements must be known when the constructor is called.
.. _set-objects:
Set Objects
-----------
Instances of :class:`Set` and :class:`ImmutableSet` both provide the following
operations:
+-------------------------------+------------+---------------------------------+
| Operation | Equivalent | Result |
+===============================+============+=================================+
| ``len(s)`` | | number of elements in set *s* |
| | | (cardinality) |
+-------------------------------+------------+---------------------------------+
| ``x in s`` | | test *x* for membership in *s* |
+-------------------------------+------------+---------------------------------+
| ``x not in s`` | | test *x* for non-membership in |
| | | *s* |
+-------------------------------+------------+---------------------------------+
| ``s.issubset(t)`` | ``s <= t`` | test whether every element in |
| | | *s* is in *t* |
+-------------------------------+------------+---------------------------------+
| ``s.issuperset(t)`` | ``s >= t`` | test whether every element in |
| | | *t* is in *s* |
+-------------------------------+------------+---------------------------------+
| ``s.union(t)`` | ``s | t`` | new set with elements from both |
| | | *s* and *t* |
+-------------------------------+------------+---------------------------------+
| ``s.intersection(t)`` | ``s & t`` | new set with elements common to |
| | | *s* and *t* |
+-------------------------------+------------+---------------------------------+
| ``s.difference(t)`` | ``s - t`` | new set with elements in *s* |
| | | but not in *t* |
+-------------------------------+------------+---------------------------------+
| ``s.symmetric_difference(t)`` | ``s ^ t`` | new set with elements in either |
| | | *s* or *t* but not both |
+-------------------------------+------------+---------------------------------+
| ``s.copy()`` | | new set with a shallow copy of |
| | | *s* |
+-------------------------------+------------+---------------------------------+
Note, the non-operator versions of :meth:`union`, :meth:`intersection`,
:meth:`difference`, and :meth:`symmetric_difference` will accept any iterable as
an argument. In contrast, their operator based counterparts require their
arguments to be sets. This precludes error-prone constructions like
``Set('abc') & 'cbs'`` in favor of the more readable
``Set('abc').intersection('cbs')``.
.. versionchanged:: 2.3.1
Formerly all arguments were required to be sets.
In addition, both :class:`Set` and :class:`ImmutableSet` support set to set
comparisons. Two sets are equal if and only if every element of each set is
contained in the other (each is a subset of the other). A set is less than
another set if and only if the first set is a proper subset of the second set
(is a subset, but is not equal). A set is greater than another set if and only
if the first set is a proper superset of the second set (is a superset, but is
not equal).
The subset and equality comparisons do not generalize to a complete ordering
function. For example, any two disjoint sets are not equal and are not subsets
of each other, so *all* of the following return ``False``: ``a<b``, ``a==b``,
or ``a>b``. Accordingly, sets do not implement the :meth:`__cmp__` method.
Since sets only define partial ordering (subset relationships), the output of
the :meth:`list.sort` method is undefined for lists of sets.
The following table lists operations available in :class:`ImmutableSet` but not
found in :class:`Set`:
+-------------+------------------------------+
| Operation | Result |
+=============+==============================+
| ``hash(s)`` | returns a hash value for *s* |
+-------------+------------------------------+
The following table lists operations available in :class:`Set` but not found in
:class:`ImmutableSet`:
+--------------------------------------+-------------+---------------------------------+
| Operation | Equivalent | Result |
+======================================+=============+=================================+
| ``s.update(t)`` | *s* \|= *t* | return set *s* with elements |
| | | added from *t* |
+--------------------------------------+-------------+---------------------------------+
| ``s.intersection_update(t)`` | *s* &= *t* | return set *s* keeping only |
| | | elements also found in *t* |
+--------------------------------------+-------------+---------------------------------+
| ``s.difference_update(t)`` | *s* -= *t* | return set *s* after removing |
| | | elements found in *t* |
+--------------------------------------+-------------+---------------------------------+
| ``s.symmetric_difference_update(t)`` | *s* ^= *t* | return set *s* with elements |
| | | from *s* or *t* but not both |
+--------------------------------------+-------------+---------------------------------+
| ``s.add(x)`` | | add element *x* to set *s* |
+--------------------------------------+-------------+---------------------------------+
| ``s.remove(x)`` | | remove *x* from set *s*; raises |
| | | :exc:`KeyError` if not present |
+--------------------------------------+-------------+---------------------------------+
| ``s.discard(x)`` | | removes *x* from set *s* if |
| | | present |
+--------------------------------------+-------------+---------------------------------+
| ``s.pop()`` | | remove and return an arbitrary |
| | | element from *s*; raises |
| | | :exc:`KeyError` if empty |
+--------------------------------------+-------------+---------------------------------+
| ``s.clear()`` | | remove all elements from set |
| | | *s* |
+--------------------------------------+-------------+---------------------------------+
Note, the non-operator versions of :meth:`update`, :meth:`intersection_update`,
:meth:`difference_update`, and :meth:`symmetric_difference_update` will accept
any iterable as an argument.
.. versionchanged:: 2.3.1
Formerly all arguments were required to be sets.
Also note, the module also includes a :meth:`union_update` method which is an
alias for :meth:`update`. The method is included for backwards compatibility.
Programmers should prefer the :meth:`update` method because it is supported by
the built-in :class:`set()` and :class:`frozenset()` types.
.. _set-example:
Example
-------
>>> from sets import Set
>>> engineers = Set(['John', 'Jane', 'Jack', 'Janice'])
>>> programmers = Set(['Jack', 'Sam', 'Susan', 'Janice'])
>>> managers = Set(['Jane', 'Jack', 'Susan', 'Zack'])
>>> employees = engineers | programmers | managers # union
>>> engineering_management = engineers & managers # intersection
>>> fulltime_management = managers - engineers - programmers # difference
>>> engineers.add('Marvin') # add element
>>> print engineers # doctest: +SKIP
Set(['Jane', 'Marvin', 'Janice', 'John', 'Jack'])
>>> employees.issuperset(engineers) # superset test
False
>>> employees.update(engineers) # update from another set
>>> employees.issuperset(engineers)
True
>>> for group in [engineers, programmers, managers, employees]: # doctest: +SKIP
... group.discard('Susan') # unconditionally remove element
... print group
...
Set(['Jane', 'Marvin', 'Janice', 'John', 'Jack'])
Set(['Janice', 'Jack', 'Sam'])
Set(['Jane', 'Zack', 'Jack'])
Set(['Jack', 'Sam', 'Jane', 'Marvin', 'Janice', 'John', 'Zack'])
.. _immutable-transforms:
Protocol for automatic conversion to immutable
----------------------------------------------
Sets can only contain immutable elements. For convenience, mutable :class:`Set`
objects are automatically copied to an :class:`ImmutableSet` before being added
as a set element.
The mechanism is to always add a :term:`hashable` element, or if it is not
hashable, the element is checked to see if it has an :meth:`__as_immutable__`
method which returns an immutable equivalent.
Since :class:`Set` objects have a :meth:`__as_immutable__` method returning an
instance of :class:`ImmutableSet`, it is possible to construct sets of sets.
A similar mechanism is needed by the :meth:`__contains__` and :meth:`remove`
methods which need to hash an element to check for membership in a set. Those
methods check an element for hashability and, if not, check for a
:meth:`__as_temporarily_immutable__` method which returns the element wrapped by
a class that provides temporary methods for :meth:`__hash__`, :meth:`__eq__`,
and :meth:`__ne__`.
The alternate mechanism spares the need to build a separate copy of the original
mutable object.
:class:`Set` objects implement the :meth:`__as_temporarily_immutable__` method
which returns the :class:`Set` object wrapped by a new class
:class:`_TemporarilyImmutableSet`.
The two mechanisms for adding hashability are normally invisible to the user;
however, a conflict can arise in a multi-threaded environment where one thread
is updating a set while another has temporarily wrapped it in
:class:`_TemporarilyImmutableSet`. In other words, sets of mutable sets are not
thread-safe.
.. _comparison-to-builtin-set:
Comparison to the built-in :class:`set` types
---------------------------------------------
The built-in :class:`set` and :class:`frozenset` types were designed based on
lessons learned from the :mod:`sets` module. The key differences are:
* :class:`Set` and :class:`ImmutableSet` were renamed to :class:`set` and
:class:`frozenset`.
* There is no equivalent to :class:`BaseSet`. Instead, use ``isinstance(x,
(set, frozenset))``.
* The hash algorithm for the built-ins performs significantly better (fewer
collisions) for most datasets.
* The built-in versions have more space efficient pickles.
* The built-in versions do not have a :meth:`union_update` method. Instead, use
the :meth:`update` method which is equivalent.
* The built-in versions do not have a ``_repr(sorted=True)`` method.
Instead, use the built-in :func:`repr` and :func:`sorted` functions:
``repr(sorted(s))``.
* The built-in version does not have a protocol for automatic conversion to
immutable. Many found this feature to be confusing and no one in the community
reported having found real uses for it.
PK
%�\�� B B ! html/_sources/library/sgi.rst.txtnu �[���
.. _sgi:
**************************
SGI IRIX Specific Services
**************************
The modules described in this chapter provide interfaces to features that are
unique to SGI's IRIX operating system (versions 4 and 5).
.. toctree::
al.rst
cd.rst
fl.rst
fm.rst
gl.rst
imgfile.rst
jpeg.rst
PK
%�\g�Ko�) �) % html/_sources/library/sgmllib.rst.txtnu �[��� :mod:`sgmllib` --- Simple SGML parser
=====================================
.. module:: sgmllib
:synopsis: Only as much of an SGML parser as needed to parse HTML.
:deprecated:
.. deprecated:: 2.6
The :mod:`sgmllib` module has been removed in Python 3.
.. index:: single: SGML
This module defines a class :class:`SGMLParser` which serves as the basis for
parsing text files formatted in SGML (Standard Generalized Mark-up Language).
In fact, it does not provide a full SGML parser --- it only parses SGML insofar
as it is used by HTML, and the module only exists as a base for the
:mod:`htmllib` module. Another HTML parser which supports XHTML and offers a
somewhat different interface is available in the :mod:`HTMLParser` module.
.. class:: SGMLParser()
The :class:`SGMLParser` class is instantiated without arguments. The parser is
hardcoded to recognize the following constructs:
* Opening and closing tags of the form ``<tag attr="value" ...>`` and
``</tag>``, respectively.
* Numeric character references of the form ``&#name;``.
* Entity references of the form ``&name;``.
* SGML comments of the form ``<!--text-->``. Note that spaces, tabs, and
newlines are allowed between the trailing ``>`` and the immediately preceding
``--``.
A single exception is defined as well:
.. exception:: SGMLParseError
Exception raised by the :class:`SGMLParser` class when it encounters an error
while parsing.
.. versionadded:: 2.1
:class:`SGMLParser` instances have the following methods:
.. method:: SGMLParser.reset()
Reset the instance. Loses all unprocessed data. This is called implicitly at
instantiation time.
.. method:: SGMLParser.setnomoretags()
Stop processing tags. Treat all following input as literal input (CDATA).
(This is only provided so the HTML tag ``<PLAINTEXT>`` can be implemented.)
.. method:: SGMLParser.setliteral()
Enter literal mode (CDATA mode).
.. method:: SGMLParser.feed(data)
Feed some text to the parser. It is processed insofar as it consists of
complete elements; incomplete data is buffered until more data is fed or
:meth:`close` is called.
.. method:: SGMLParser.close()
Force processing of all buffered data as if it were followed by an end-of-file
mark. This method may be redefined by a derived class to define additional
processing at the end of the input, but the redefined version should always call
:meth:`close`.
.. method:: SGMLParser.get_starttag_text()
Return the text of the most recently opened start tag. This should not normally
be needed for structured processing, but may be useful in dealing with HTML "as
deployed" or for re-generating input with minimal changes (whitespace between
attributes can be preserved, etc.).
.. method:: SGMLParser.handle_starttag(tag, method, attributes)
This method is called to handle start tags for which either a :meth:`start_tag`
or :meth:`do_tag` method has been defined. The *tag* argument is the name of
the tag converted to lower case, and the *method* argument is the bound method
which should be used to support semantic interpretation of the start tag. The
*attributes* argument is a list of ``(name, value)`` pairs containing the
attributes found inside the tag's ``<>`` brackets.
The *name* has been translated to lower case. Double quotes and backslashes in
the *value* have been interpreted, as well as known character references and
known entity references terminated by a semicolon (normally, entity references
can be terminated by any non-alphanumerical character, but this would break the
very common case of ``<A HREF="url?spam=1&eggs=2">`` when ``eggs`` is a valid
entity name).
For instance, for the tag ``<A HREF="http://www.cwi.nl/">``, this method would
be called as ``unknown_starttag('a', [('href', 'http://www.cwi.nl/')])``. The
base implementation simply calls *method* with *attributes* as the only
argument.
.. versionadded:: 2.5
Handling of entity and character references within attribute values.
.. method:: SGMLParser.handle_endtag(tag, method)
This method is called to handle endtags for which an :meth:`end_tag` method has
been defined. The *tag* argument is the name of the tag converted to lower
case, and the *method* argument is the bound method which should be used to
support semantic interpretation of the end tag. If no :meth:`end_tag` method is
defined for the closing element, this handler is not called. The base
implementation simply calls *method*.
.. method:: SGMLParser.handle_data(data)
This method is called to process arbitrary data. It is intended to be
overridden by a derived class; the base class implementation does nothing.
.. method:: SGMLParser.handle_charref(ref)
This method is called to process a character reference of the form ``&#ref;``.
The base implementation uses :meth:`convert_charref` to convert the reference to
a string. If that method returns a string, it is passed to :meth:`handle_data`,
otherwise ``unknown_charref(ref)`` is called to handle the error.
.. versionchanged:: 2.5
Use :meth:`convert_charref` instead of hard-coding the conversion.
.. method:: SGMLParser.convert_charref(ref)
Convert a character reference to a string, or ``None``. *ref* is the reference
passed in as a string. In the base implementation, *ref* must be a decimal
number in the range 0--255. It converts the code point found using the
:meth:`convert_codepoint` method. If *ref* is invalid or out of range, this
method returns ``None``. This method is called by the default
:meth:`handle_charref` implementation and by the attribute value parser.
.. versionadded:: 2.5
.. method:: SGMLParser.convert_codepoint(codepoint)
Convert a code point to a :class:`str` value. Encodings can be handled here if
appropriate, though the rest of :mod:`sgmllib` is oblivious on this matter.
.. versionadded:: 2.5
.. method:: SGMLParser.handle_entityref(ref)
This method is called to process a general entity reference of the form
``&ref;`` where *ref* is a general entity reference. It converts *ref* by
passing it to :meth:`convert_entityref`. If a translation is returned, it calls
the method :meth:`handle_data` with the translation; otherwise, it calls the
method ``unknown_entityref(ref)``. The default :attr:`entitydefs` defines
translations for ``&``, ``'``, ``>``, ``<``, and ``"``.
.. versionchanged:: 2.5
Use :meth:`convert_entityref` instead of hard-coding the conversion.
.. method:: SGMLParser.convert_entityref(ref)
Convert a named entity reference to a :class:`str` value, or ``None``. The
resulting value will not be parsed. *ref* will be only the name of the entity.
The default implementation looks for *ref* in the instance (or class) variable
:attr:`entitydefs` which should be a mapping from entity names to corresponding
translations. If no translation is available for *ref*, this method returns
``None``. This method is called by the default :meth:`handle_entityref`
implementation and by the attribute value parser.
.. versionadded:: 2.5
.. method:: SGMLParser.handle_comment(comment)
This method is called when a comment is encountered. The *comment* argument is
a string containing the text between the ``<!--`` and ``-->`` delimiters, but
not the delimiters themselves. For example, the comment ``<!--text-->`` will
cause this method to be called with the argument ``'text'``. The default method
does nothing.
.. method:: SGMLParser.handle_decl(data)
Method called when an SGML declaration is read by the parser. In practice, the
``DOCTYPE`` declaration is the only thing observed in HTML, but the parser does
not discriminate among different (or broken) declarations. Internal subsets in
a ``DOCTYPE`` declaration are not supported. The *data* parameter will be the
entire contents of the declaration inside the ``<!``...\ ``>`` markup. The
default implementation does nothing.
.. method:: SGMLParser.report_unbalanced(tag)
This method is called when an end tag is found which does not correspond to any
open element.
.. method:: SGMLParser.unknown_starttag(tag, attributes)
This method is called to process an unknown start tag. It is intended to be
overridden by a derived class; the base class implementation does nothing.
.. method:: SGMLParser.unknown_endtag(tag)
This method is called to process an unknown end tag. It is intended to be
overridden by a derived class; the base class implementation does nothing.
.. method:: SGMLParser.unknown_charref(ref)
This method is called to process unresolvable numeric character references.
Refer to :meth:`handle_charref` to determine what is handled by default. It is
intended to be overridden by a derived class; the base class implementation does
nothing.
.. method:: SGMLParser.unknown_entityref(ref)
This method is called to process an unknown entity reference. It is intended to
be overridden by a derived class; the base class implementation does nothing.
Apart from overriding or extending the methods listed above, derived classes may
also define methods of the following form to define processing of specific tags.
Tag names in the input stream are case independent; the *tag* occurring in
method names must be in lower case:
.. method:: SGMLParser.start_tag(attributes)
:noindex:
This method is called to process an opening tag *tag*. It has preference over
:meth:`do_tag`. The *attributes* argument has the same meaning as described for
:meth:`handle_starttag` above.
.. method:: SGMLParser.do_tag(attributes)
:noindex:
This method is called to process an opening tag *tag* for which no
:meth:`start_tag` method is defined. The *attributes* argument has the same
meaning as described for :meth:`handle_starttag` above.
.. method:: SGMLParser.end_tag()
:noindex:
This method is called to process a closing tag *tag*.
Note that the parser maintains a stack of open elements for which no end tag has
been found yet. Only tags processed by :meth:`start_tag` are pushed on this
stack. Definition of an :meth:`end_tag` method is optional for these tags. For
tags processed by :meth:`do_tag` or by :meth:`unknown_tag`, no :meth:`end_tag`
method must be defined; if defined, it will not be used. If both
:meth:`start_tag` and :meth:`do_tag` methods exist for a tag, the
:meth:`start_tag` method takes precedence.
PK
%�\�M��
�
! html/_sources/library/sha.rst.txtnu �[���
:mod:`sha` --- SHA-1 message digest algorithm
=============================================
.. module:: sha
:synopsis: NIST's secure hash algorithm, SHA.
:deprecated:
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
.. deprecated:: 2.5
Use the :mod:`hashlib` module instead.
.. index::
single: NIST
single: Secure Hash Algorithm
single: checksum; SHA
This module implements the interface to NIST's secure hash algorithm, known as
SHA-1. SHA-1 is an improved version of the original SHA hash algorithm. It is
used in the same way as the :mod:`md5` module: use :func:`new` to create an sha
object, then feed this object with arbitrary strings using the :meth:`update`
method, and at any point you can ask it for the :dfn:`digest` of the
concatenation of the strings fed to it so far. SHA-1 digests are 160 bits
instead of MD5's 128 bits.
.. function:: new([string])
Return a new sha object. If *string* is present, the method call
``update(string)`` is made.
The following values are provided as constants in the module and as attributes
of the sha objects returned by :func:`new`:
.. data:: blocksize
Size of the blocks fed into the hash function; this is always ``1``. This size
is used to allow an arbitrary string to be hashed.
.. data:: digest_size
The size of the resulting digest in bytes. This is always ``20``.
An sha object has the same methods as md5 objects:
.. method:: sha.update(arg)
Update the sha object with the string *arg*. Repeated calls are equivalent to a
single call with the concatenation of all the arguments: ``m.update(a);
m.update(b)`` is equivalent to ``m.update(a+b)``.
.. method:: sha.digest()
Return the digest of the strings passed to the :meth:`update` method so far.
This is a 20-byte string which may contain non-ASCII characters, including null
bytes.
.. method:: sha.hexdigest()
Like :meth:`digest` except the digest is returned as a string of length 40,
containing only hexadecimal digits. This may be used to exchange the value
safely in email or other non-binary environments.
.. method:: sha.copy()
Return a copy ("clone") of the sha object. This can be used to efficiently
compute the digests of strings that share a common initial substring.
.. seealso::
`Secure Hash Standard <http://csrc.nist.gov/publications/fips/fips180-2/fips180-2withchangenotice.pdf>`_
The Secure Hash Algorithm is defined by NIST document FIPS PUB 180-2: `Secure
Hash Standard
<http://csrc.nist.gov/publications/fips/fips180-2/fips180-2withchangenotice.pdf>`_,
published in August 2002.
`Cryptographic Toolkit (Secure Hashing) <http://csrc.nist.gov/CryptoToolkit/tkhash.html>`_
Links from NIST to various information on secure hashing.
PK
%�\�~�� $ html/_sources/library/shelve.rst.txtnu �[��� :mod:`shelve` --- Python object persistence
===========================================
.. module:: shelve
:synopsis: Python object persistence.
.. index:: module: pickle
**Source code:** :source:`Lib/shelve.py`
--------------
A "shelf" is a persistent, dictionary-like object. The difference with "dbm"
databases is that the values (not the keys!) in a shelf can be essentially
arbitrary Python objects --- anything that the :mod:`pickle` module can handle.
This includes most class instances, recursive data types, and objects containing
lots of shared sub-objects. The keys are ordinary strings.
.. function:: open(filename, flag='c', protocol=None, writeback=False)
Open a persistent dictionary. The filename specified is the base filename for
the underlying database. As a side-effect, an extension may be added to the
filename and more than one file may be created. By default, the underlying
database file is opened for reading and writing. The optional *flag* parameter
has the same interpretation as the *flag* parameter of :func:`anydbm.open`.
By default, version 0 pickles are used to serialize values. The version of the
pickle protocol can be specified with the *protocol* parameter.
.. versionchanged:: 2.3
The *protocol* parameter was added.
Because of Python semantics, a shelf cannot know when a mutable
persistent-dictionary entry is modified. By default modified objects are
written *only* when assigned to the shelf (see :ref:`shelve-example`). If the
optional *writeback* parameter is set to ``True``, all entries accessed are also
cached in memory, and written back on :meth:`~Shelf.sync` and
:meth:`~Shelf.close`; this can make it handier to mutate mutable entries in
the persistent dictionary, but, if many entries are accessed, it can consume
vast amounts of memory for the cache, and it can make the close operation
very slow since all accessed entries are written back (there is no way to
determine which accessed entries are mutable, nor which ones were actually
mutated).
Like file objects, shelve objects should be closed explicitly to ensure
that the persistent data is flushed to disk.
.. warning::
Because the :mod:`shelve` module is backed by :mod:`pickle`, it is insecure
to load a shelf from an untrusted source. Like with pickle, loading a shelf
can execute arbitrary code.
Shelf objects support most of the methods supported by dictionaries. This
eases the transition from dictionary based scripts to those requiring
persistent storage.
Note, the Python 3 transition methods (:meth:`~dict.viewkeys`,
:meth:`~dict.viewvalues`, and :meth:`~dict.viewitems`) are not supported.
Two additional methods are supported:
.. method:: Shelf.sync()
Write back all entries in the cache if the shelf was opened with *writeback*
set to :const:`True`. Also empty the cache and synchronize the persistent
dictionary on disk, if feasible. This is called automatically when the shelf
is closed with :meth:`close`.
.. method:: Shelf.close()
Synchronize and close the persistent *dict* object. Operations on a closed
shelf will fail with a :exc:`ValueError`.
.. seealso::
`Persistent dictionary recipe <https://code.activestate.com/recipes/576642/>`_
with widely supported storage formats and having the speed of native
dictionaries.
Restrictions
------------
.. index::
module: dbm
module: gdbm
module: bsddb
* The choice of which database package will be used (such as :mod:`dbm`,
:mod:`gdbm` or :mod:`bsddb`) depends on which interface is available. Therefore
it is not safe to open the database directly using :mod:`dbm`. The database is
also (unfortunately) subject to the limitations of :mod:`dbm`, if it is used ---
this means that (the pickled representation of) the objects stored in the
database should be fairly small, and in rare cases key collisions may cause the
database to refuse updates.
* The :mod:`shelve` module does not support *concurrent* read/write access to
shelved objects. (Multiple simultaneous read accesses are safe.) When a
program has a shelf open for writing, no other program should have it open for
reading or writing. Unix file locking can be used to solve this, but this
differs across Unix versions and requires knowledge about the database
implementation used.
.. class:: Shelf(dict, protocol=None, writeback=False)
A subclass of :class:`UserDict.DictMixin` which stores pickled values in the
*dict* object.
By default, version 0 pickles are used to serialize values. The version of the
pickle protocol can be specified with the *protocol* parameter. See the
:mod:`pickle` documentation for a discussion of the pickle protocols.
.. versionchanged:: 2.3
The *protocol* parameter was added.
If the *writeback* parameter is ``True``, the object will hold a cache of all
entries accessed and write them back to the *dict* at sync and close times.
This allows natural operations on mutable entries, but can consume much more
memory and make sync and close take a long time.
.. class:: BsdDbShelf(dict, protocol=None, writeback=False)
A subclass of :class:`Shelf` which exposes :meth:`first`, :meth:`!next`,
:meth:`previous`, :meth:`last` and :meth:`set_location` which are available in
the :mod:`bsddb` module but not in other database modules. The *dict* object
passed to the constructor must support those methods. This is generally
accomplished by calling one of :func:`bsddb.hashopen`, :func:`bsddb.btopen` or
:func:`bsddb.rnopen`. The optional *protocol* and *writeback* parameters have
the same interpretation as for the :class:`Shelf` class.
.. class:: DbfilenameShelf(filename, flag='c', protocol=None, writeback=False)
A subclass of :class:`Shelf` which accepts a *filename* instead of a dict-like
object. The underlying file will be opened using :func:`anydbm.open`. By
default, the file will be created and opened for both read and write. The
optional *flag* parameter has the same interpretation as for the :func:`.open`
function. The optional *protocol* and *writeback* parameters have the same
interpretation as for the :class:`Shelf` class.
.. _shelve-example:
Example
-------
To summarize the interface (``key`` is a string, ``data`` is an arbitrary
object)::
import shelve
d = shelve.open(filename) # open -- file may get suffix added by low-level
# library
d[key] = data # store data at key (overwrites old data if
# using an existing key)
data = d[key] # retrieve a COPY of data at key (raise KeyError if no
# such key)
del d[key] # delete data stored at key (raises KeyError
# if no such key)
flag = d.has_key(key) # true if the key exists
klist = d.keys() # a list of all existing keys (slow!)
# as d was opened WITHOUT writeback=True, beware:
d['xx'] = range(4) # this works as expected, but...
d['xx'].append(5) # *this doesn't!* -- d['xx'] is STILL range(4)!
# having opened d without writeback=True, you need to code carefully:
temp = d['xx'] # extracts the copy
temp.append(5) # mutates the copy
d['xx'] = temp # stores the copy right back, to persist it
# or, d=shelve.open(filename,writeback=True) would let you just code
# d['xx'].append(5) and have it work as expected, BUT it would also
# consume more memory and make the d.close() operation slower.
d.close() # close it
.. seealso::
Module :mod:`anydbm`
Generic interface to ``dbm``\ -style databases.
Module :mod:`bsddb`
BSD ``db`` database interface.
Module :mod:`dbhash`
Thin layer around the :mod:`bsddb` which provides an :func:`~dbhash.open`
function like the other database modules.
Module :mod:`dbm`
Standard Unix database interface.
Module :mod:`dumbdbm`
Portable implementation of the ``dbm`` interface.
Module :mod:`gdbm`
GNU database interface, based on the ``dbm`` interface.
Module :mod:`pickle`
Object serialization used by :mod:`shelve`.
Module :mod:`cPickle`
High-performance version of :mod:`pickle`.
PK
%�\t� 1, 1, # html/_sources/library/shlex.rst.txtnu �[��� :mod:`shlex` --- Simple lexical analysis
========================================
.. module:: shlex
:synopsis: Simple lexical analysis for Unix shell-like languages.
.. moduleauthor:: Eric S. Raymond <esr@snark.thyrsus.com>
.. moduleauthor:: Gustavo Niemeyer <niemeyer@conectiva.com>
.. sectionauthor:: Eric S. Raymond <esr@snark.thyrsus.com>
.. sectionauthor:: Gustavo Niemeyer <niemeyer@conectiva.com>
.. versionadded:: 1.5.2
**Source code:** :source:`Lib/shlex.py`
--------------
The :class:`~shlex.shlex` class makes it easy to write lexical analyzers for
simple syntaxes resembling that of the Unix shell. This will often be useful
for writing minilanguages, (for example, in run control files for Python
applications) or for parsing quoted strings.
Prior to Python 2.7.3, this module did not support Unicode input.
The :mod:`shlex` module defines the following functions:
.. function:: split(s[, comments[, posix]])
Split the string *s* using shell-like syntax. If *comments* is :const:`False`
(the default), the parsing of comments in the given string will be disabled
(setting the :attr:`~shlex.commenters` attribute of the
:class:`~shlex.shlex` instance to the empty string). This function operates
in POSIX mode by default, but uses non-POSIX mode if the *posix* argument is
false.
.. versionadded:: 2.3
.. versionchanged:: 2.6
Added the *posix* parameter.
.. note::
Since the :func:`split` function instantiates a :class:`~shlex.shlex`
instance, passing ``None`` for *s* will read the string to split from
standard input.
The :mod:`shlex` module defines the following class:
.. class:: shlex([instream[, infile[, posix]]])
A :class:`~shlex.shlex` instance or subclass instance is a lexical analyzer
object. The initialization argument, if present, specifies where to read
characters from. It must be a file-/stream-like object with
:meth:`~io.TextIOBase.read` and :meth:`~io.TextIOBase.readline` methods, or
a string (strings are accepted since Python 2.3). If no argument is given,
input will be taken from ``sys.stdin``. The second optional argument is a
filename string, which sets the initial value of the :attr:`~shlex.infile`
attribute. If the *instream* argument is omitted or equal to ``sys.stdin``,
this second argument defaults to "stdin". The *posix* argument was
introduced in Python 2.3, and defines the operational mode. When *posix* is
not true (default), the :class:`~shlex.shlex` instance will operate in
compatibility mode. When operating in POSIX mode, :class:`~shlex.shlex`
will try to be as close as possible to the POSIX shell parsing rules.
.. seealso::
Module :mod:`ConfigParser`
Parser for configuration files similar to the Windows :file:`.ini` files.
.. _shlex-objects:
shlex Objects
-------------
A :class:`~shlex.shlex` instance has the following methods:
.. method:: shlex.get_token()
Return a token. If tokens have been stacked using :meth:`push_token`, pop a
token off the stack. Otherwise, read one from the input stream. If reading
encounters an immediate end-of-file, :attr:`eof` is returned (the empty
string (``''``) in non-POSIX mode, and ``None`` in POSIX mode).
.. method:: shlex.push_token(str)
Push the argument onto the token stack.
.. method:: shlex.read_token()
Read a raw token. Ignore the pushback stack, and do not interpret source
requests. (This is not ordinarily a useful entry point, and is documented here
only for the sake of completeness.)
.. method:: shlex.sourcehook(filename)
When :class:`~shlex.shlex` detects a source request (see :attr:`source`
below) this method is given the following token as argument, and expected
to return a tuple consisting of a filename and an open file-like object.
Normally, this method first strips any quotes off the argument. If the result
is an absolute pathname, or there was no previous source request in effect, or
the previous source was a stream (such as ``sys.stdin``), the result is left
alone. Otherwise, if the result is a relative pathname, the directory part of
the name of the file immediately before it on the source inclusion stack is
prepended (this behavior is like the way the C preprocessor handles ``#include
"file.h"``).
The result of the manipulations is treated as a filename, and returned as the
first component of the tuple, with :func:`open` called on it to yield the second
component. (Note: this is the reverse of the order of arguments in instance
initialization!)
This hook is exposed so that you can use it to implement directory search paths,
addition of file extensions, and other namespace hacks. There is no
corresponding 'close' hook, but a shlex instance will call the
:meth:`~io.IOBase.close` method of the sourced input stream when it returns
EOF.
For more explicit control of source stacking, use the :meth:`push_source` and
:meth:`pop_source` methods.
.. method:: shlex.push_source(stream[, filename])
Push an input source stream onto the input stack. If the filename argument is
specified it will later be available for use in error messages. This is the
same method used internally by the :meth:`sourcehook` method.
.. versionadded:: 2.1
.. method:: shlex.pop_source()
Pop the last-pushed input source from the input stack. This is the same method
used internally when the lexer reaches EOF on a stacked input stream.
.. versionadded:: 2.1
.. method:: shlex.error_leader([file[, line]])
This method generates an error message leader in the format of a Unix C compiler
error label; the format is ``'"%s", line %d: '``, where the ``%s`` is replaced
with the name of the current source file and the ``%d`` with the current input
line number (the optional arguments can be used to override these).
This convenience is provided to encourage :mod:`shlex` users to generate error
messages in the standard, parseable format understood by Emacs and other Unix
tools.
Instances of :class:`~shlex.shlex` subclasses have some public instance
variables which either control lexical analysis or can be used for debugging:
.. attribute:: shlex.commenters
The string of characters that are recognized as comment beginners. All
characters from the comment beginner to end of line are ignored. Includes just
``'#'`` by default.
.. attribute:: shlex.wordchars
The string of characters that will accumulate into multi-character tokens. By
default, includes all ASCII alphanumerics and underscore.
.. attribute:: shlex.whitespace
Characters that will be considered whitespace and skipped. Whitespace bounds
tokens. By default, includes space, tab, linefeed and carriage-return.
.. attribute:: shlex.escape
Characters that will be considered as escape. This will be only used in POSIX
mode, and includes just ``'\'`` by default.
.. versionadded:: 2.3
.. attribute:: shlex.quotes
Characters that will be considered string quotes. The token accumulates until
the same quote is encountered again (thus, different quote types protect each
other as in the shell.) By default, includes ASCII single and double quotes.
.. attribute:: shlex.escapedquotes
Characters in :attr:`quotes` that will interpret escape characters defined in
:attr:`escape`. This is only used in POSIX mode, and includes just ``'"'`` by
default.
.. versionadded:: 2.3
.. attribute:: shlex.whitespace_split
If ``True``, tokens will only be split in whitespaces. This is useful, for
example, for parsing command lines with :class:`~shlex.shlex`, getting
tokens in a similar way to shell arguments.
.. versionadded:: 2.3
.. attribute:: shlex.infile
The name of the current input file, as initially set at class instantiation time
or stacked by later source requests. It may be useful to examine this when
constructing error messages.
.. attribute:: shlex.instream
The input stream from which this :class:`~shlex.shlex` instance is reading
characters.
.. attribute:: shlex.source
This attribute is ``None`` by default. If you assign a string to it, that
string will be recognized as a lexical-level inclusion request similar to the
``source`` keyword in various shells. That is, the immediately following token
will be opened as a filename and input will
be taken from that stream until EOF, at which
point the :meth:`~io.IOBase.close` method of that stream will be called and
the input source will again become the original input stream. Source
requests may be stacked any number of levels deep.
.. attribute:: shlex.debug
If this attribute is numeric and ``1`` or more, a :class:`~shlex.shlex`
instance will print verbose progress output on its behavior. If you need
to use this, you can read the module source code to learn the details.
.. attribute:: shlex.lineno
Source line number (count of newlines seen so far plus one).
.. attribute:: shlex.token
The token buffer. It may be useful to examine this when catching exceptions.
.. attribute:: shlex.eof
Token used to determine end of file. This will be set to the empty string
(``''``), in non-POSIX mode, and to ``None`` in POSIX mode.
.. versionadded:: 2.3
.. _shlex-parsing-rules:
Parsing Rules
-------------
When operating in non-POSIX mode, :class:`~shlex.shlex` will try to obey to the
following rules.
* Quote characters are not recognized within words (``Do"Not"Separate`` is
parsed as the single word ``Do"Not"Separate``);
* Escape characters are not recognized;
* Enclosing characters in quotes preserve the literal value of all characters
within the quotes;
* Closing quotes separate words (``"Do"Separate`` is parsed as ``"Do"`` and
``Separate``);
* If :attr:`~shlex.whitespace_split` is ``False``, any character not
declared to be a word character, whitespace, or a quote will be returned as
a single-character token. If it is ``True``, :class:`~shlex.shlex` will only
split words in whitespaces;
* EOF is signaled with an empty string (``''``);
* It's not possible to parse empty strings, even if quoted.
When operating in POSIX mode, :class:`~shlex.shlex` will try to obey to the
following parsing rules.
* Quotes are stripped out, and do not separate words (``"Do"Not"Separate"`` is
parsed as the single word ``DoNotSeparate``);
* Non-quoted escape characters (e.g. ``'\'``) preserve the literal value of the
next character that follows;
* Enclosing characters in quotes which are not part of
:attr:`~shlex.escapedquotes` (e.g. ``"'"``) preserve the literal value
of all characters within the quotes;
* Enclosing characters in quotes which are part of
:attr:`~shlex.escapedquotes` (e.g. ``'"'``) preserves the literal value
of all characters within the quotes, with the exception of the characters
mentioned in :attr:`~shlex.escape`. The escape characters retain its
special meaning only when followed by the quote in use, or the escape
character itself. Otherwise the escape character will be considered a
normal character.
* EOF is signaled with a :const:`None` value;
* Quoted empty strings (``''``) are allowed;
PK
%�\�gz��4 �4 $ html/_sources/library/shutil.rst.txtnu �[��� :mod:`shutil` --- High-level file operations
============================================
.. module:: shutil
:synopsis: High-level file operations, including copying.
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
.. partly based on the docstrings
.. index::
single: file; copying
single: copying files
**Source code:** :source:`Lib/shutil.py`
--------------
The :mod:`shutil` module offers a number of high-level operations on files and
collections of files. In particular, functions are provided which support file
copying and removal. For operations on individual files, see also the
:mod:`os` module.
.. warning::
Even the higher-level file copying functions (:func:`shutil.copy`,
:func:`shutil.copy2`) can't copy all file metadata.
On POSIX platforms, this means that file owner and group are lost as well
as ACLs. On Mac OS, the resource fork and other metadata are not used.
This means that resources will be lost and file type and creator codes will
not be correct. On Windows, file owners, ACLs and alternate data streams
are not copied.
.. _file-operations:
Directory and files operations
------------------------------
.. function:: copyfileobj(fsrc, fdst[, length])
Copy the contents of the file-like object *fsrc* to the file-like object *fdst*.
The integer *length*, if given, is the buffer size. In particular, a negative
*length* value means to copy the data without looping over the source data in
chunks; by default the data is read in chunks to avoid uncontrolled memory
consumption. Note that if the current file position of the *fsrc* object is not
0, only the contents from the current file position to the end of the file will
be copied.
.. function:: copyfile(src, dst)
Copy the contents (no metadata) of the file named *src* to a file named
*dst*. *dst* must be the complete target file name; look at
:func:`shutil.copy` for a copy that accepts a target directory path. If
*src* and *dst* are the same files, :exc:`Error` is raised.
The destination location must be writable; otherwise, an :exc:`IOError` exception
will be raised. If *dst* already exists, it will be replaced. Special files
such as character or block devices and pipes cannot be copied with this
function. *src* and *dst* are path names given as strings.
.. function:: copymode(src, dst)
Copy the permission bits from *src* to *dst*. The file contents, owner, and
group are unaffected. *src* and *dst* are path names given as strings.
.. function:: copystat(src, dst)
Copy the permission bits, last access time, last modification time, and flags
from *src* to *dst*. The file contents, owner, and group are unaffected. *src*
and *dst* are path names given as strings.
.. function:: copy(src, dst)
Copy the file *src* to the file or directory *dst*. If *dst* is a directory, a
file with the same basename as *src* is created (or overwritten) in the
directory specified. Permission bits are copied. *src* and *dst* are path
names given as strings.
.. function:: copy2(src, dst)
Identical to :func:`~shutil.copy` except that :func:`copy2`
also attempts to preserve file metadata.
:func:`copy2` uses :func:`copystat` to copy the file metadata.
Please see :func:`copystat` for more information.
.. function:: ignore_patterns(\*patterns)
This factory function creates a function that can be used as a callable for
:func:`copytree`\'s *ignore* argument, ignoring files and directories that
match one of the glob-style *patterns* provided. See the example below.
.. versionadded:: 2.6
.. function:: copytree(src, dst, symlinks=False, ignore=None)
Recursively copy an entire directory tree rooted at *src*. The destination
directory, named by *dst*, must not already exist; it will be created as
well as missing parent directories. Permissions and times of directories
are copied with :func:`copystat`, individual files are copied using
:func:`shutil.copy2`.
If *symlinks* is true, symbolic links in the source tree are represented as
symbolic links in the new tree, but the metadata of the original links is NOT
copied; if false or omitted, the contents and metadata of the linked files
are copied to the new tree.
If *ignore* is given, it must be a callable that will receive as its
arguments the directory being visited by :func:`copytree`, and a list of its
contents, as returned by :func:`os.listdir`. Since :func:`copytree` is
called recursively, the *ignore* callable will be called once for each
directory that is copied. The callable must return a sequence of directory
and file names relative to the current directory (i.e. a subset of the items
in its second argument); these names will then be ignored in the copy
process. :func:`ignore_patterns` can be used to create such a callable that
ignores names based on glob-style patterns.
If exception(s) occur, an :exc:`Error` is raised with a list of reasons.
The source code for this should be considered an example rather than the
ultimate tool.
.. versionchanged:: 2.3
:exc:`Error` is raised if any exceptions occur during copying, rather than
printing a message.
.. versionchanged:: 2.5
Create intermediate directories needed to create *dst*, rather than raising an
error. Copy permissions and times of directories using :func:`copystat`.
.. versionchanged:: 2.6
Added the *ignore* argument to be able to influence what is being copied.
.. function:: rmtree(path[, ignore_errors[, onerror]])
.. index:: single: directory; deleting
Delete an entire directory tree; *path* must point to a directory (but not a
symbolic link to a directory). If *ignore_errors* is true, errors resulting
from failed removals will be ignored; if false or omitted, such errors are
handled by calling a handler specified by *onerror* or, if that is omitted,
they raise an exception.
If *onerror* is provided, it must be a callable that accepts three
parameters: *function*, *path*, and *excinfo*. The first parameter,
*function*, is the function which raised the exception; it will be
:func:`os.path.islink`, :func:`os.listdir`, :func:`os.remove` or
:func:`os.rmdir`. The second parameter, *path*, will be the path name passed
to *function*. The third parameter, *excinfo*, will be the exception
information return by :func:`sys.exc_info`. Exceptions raised by *onerror*
will not be caught.
.. versionchanged:: 2.6
Explicitly check for *path* being a symbolic link and raise :exc:`OSError`
in that case.
.. function:: move(src, dst)
Recursively move a file or directory (*src*) to another location (*dst*).
If the destination is an existing directory, then *src* is moved inside that
directory. If the destination already exists but is not a directory, it may
be overwritten depending on :func:`os.rename` semantics.
If the destination is on the current filesystem, then :func:`os.rename` is
used. Otherwise, *src* is copied (using :func:`shutil.copy2`) to *dst* and
then removed.
.. versionadded:: 2.3
.. exception:: Error
This exception collects exceptions that are raised during a multi-file
operation. For :func:`copytree`, the exception argument is a list of 3-tuples
(*srcname*, *dstname*, *exception*).
.. versionadded:: 2.3
.. _copytree-example:
copytree example
::::::::::::::::
This example is the implementation of the :func:`copytree` function, described
above, with the docstring omitted. It demonstrates many of the other functions
provided by this module. ::
def copytree(src, dst, symlinks=False, ignore=None):
names = os.listdir(src)
if ignore is not None:
ignored_names = ignore(src, names)
else:
ignored_names = set()
os.makedirs(dst)
errors = []
for name in names:
if name in ignored_names:
continue
srcname = os.path.join(src, name)
dstname = os.path.join(dst, name)
try:
if symlinks and os.path.islink(srcname):
linkto = os.readlink(srcname)
os.symlink(linkto, dstname)
elif os.path.isdir(srcname):
copytree(srcname, dstname, symlinks, ignore)
else:
copy2(srcname, dstname)
# XXX What about devices, sockets etc.?
except (IOError, os.error) as why:
errors.append((srcname, dstname, str(why)))
# catch the Error from the recursive copytree so that we can
# continue with other files
except Error as err:
errors.extend(err.args[0])
try:
copystat(src, dst)
except WindowsError:
# can't copy file access times on Windows
pass
except OSError as why:
errors.extend((src, dst, str(why)))
if errors:
raise Error(errors)
Another example that uses the :func:`ignore_patterns` helper::
from shutil import copytree, ignore_patterns
copytree(source, destination, ignore=ignore_patterns('*.pyc', 'tmp*'))
This will copy everything except ``.pyc`` files and files or directories whose
name starts with ``tmp``.
Another example that uses the *ignore* argument to add a logging call::
from shutil import copytree
import logging
def _logpath(path, names):
logging.info('Working in %s' % path)
return [] # nothing will be ignored
copytree(source, destination, ignore=_logpath)
.. _archiving-operations:
Archiving operations
--------------------
High-level utilities to create and read compressed and archived files are also
provided. They rely on the :mod:`zipfile` and :mod:`tarfile` modules.
.. function:: make_archive(base_name, format, [root_dir, [base_dir, [verbose, [dry_run, [owner, [group, [logger]]]]]]])
Create an archive file (eg. zip or tar) and returns its name.
*base_name* is the name of the file to create, including the path, minus
any format-specific extension. *format* is the archive format: one of
"zip" (if the :mod:`zlib` module or external ``zip`` executable is
available), "tar", "gztar" (if the :mod:`zlib` module is available), or
"bztar" (if the :mod:`bz2` module is available).
*root_dir* is a directory that will be the root directory of the
archive; ie. we typically chdir into *root_dir* before creating the
archive.
*base_dir* is the directory where we start archiving from;
ie. *base_dir* will be the common prefix of all files and
directories in the archive.
*root_dir* and *base_dir* both default to the current directory.
*owner* and *group* are used when creating a tar archive. By default,
uses the current owner and group.
*logger* must be an object compatible with :pep:`282`, usually an instance of
:class:`logging.Logger`.
.. versionadded:: 2.7
.. function:: get_archive_formats()
Return a list of supported formats for archiving.
Each element of the returned sequence is a tuple ``(name, description)``.
By default :mod:`shutil` provides these formats:
- *zip*: ZIP file (if the :mod:`zlib` module or external ``zip``
executable is available).
- *tar*: uncompressed tar file.
- *gztar*: gzip'ed tar-file (if the :mod:`zlib` module is available).
- *bztar*: bzip2'ed tar-file (if the :mod:`bz2` module is available).
You can register new formats or provide your own archiver for any existing
formats, by using :func:`register_archive_format`.
.. versionadded:: 2.7
.. function:: register_archive_format(name, function, [extra_args, [description]])
Register an archiver for the format *name*. *function* is a callable that
will be used to invoke the archiver.
If given, *extra_args* is a sequence of ``(name, value)`` that will be
used as extra keywords arguments when the archiver callable is used.
*description* is used by :func:`get_archive_formats` which returns the
list of archivers. Defaults to an empty list.
.. versionadded:: 2.7
.. function:: unregister_archive_format(name)
Remove the archive format *name* from the list of supported formats.
.. versionadded:: 2.7
.. _archiving-example:
Archiving example
:::::::::::::::::
In this example, we create a gzip'ed tar-file archive containing all files
found in the :file:`.ssh` directory of the user::
>>> from shutil import make_archive
>>> import os
>>> archive_name = os.path.expanduser(os.path.join('~', 'myarchive'))
>>> root_dir = os.path.expanduser(os.path.join('~', '.ssh'))
>>> make_archive(archive_name, 'gztar', root_dir)
'/Users/tarek/myarchive.tar.gz'
The resulting archive contains:
.. code-block:: shell-session
$ tar -tzvf /Users/tarek/myarchive.tar.gz
drwx------ tarek/staff 0 2010-02-01 16:23:40 ./
-rw-r--r-- tarek/staff 609 2008-06-09 13:26:54 ./authorized_keys
-rwxr-xr-x tarek/staff 65 2008-06-09 13:26:54 ./config
-rwx------ tarek/staff 668 2008-06-09 13:26:54 ./id_dsa
-rwxr-xr-x tarek/staff 609 2008-06-09 13:26:54 ./id_dsa.pub
-rw------- tarek/staff 1675 2008-06-09 13:26:54 ./id_rsa
-rw-r--r-- tarek/staff 397 2008-06-09 13:26:54 ./id_rsa.pub
-rw-r--r-- tarek/staff 37192 2010-02-06 18:23:10 ./known_hosts
PK
%�\t�,�) �) $ html/_sources/library/signal.rst.txtnu �[���
:mod:`signal` --- Set handlers for asynchronous events
======================================================
.. module:: signal
:synopsis: Set handlers for asynchronous events.
This module provides mechanisms to use signal handlers in Python. Some general
rules for working with signals and their handlers:
* A handler for a particular signal, once set, remains installed until it is
explicitly reset (Python emulates the BSD style interface regardless of the
underlying implementation), with the exception of the handler for
:const:`SIGCHLD`, which follows the underlying implementation.
* There is no way to "block" signals temporarily from critical sections (since
this is not supported by all Unix flavors).
* Although Python signal handlers are called asynchronously as far as the Python
user is concerned, they can only occur between the "atomic" instructions of the
Python interpreter. This means that signals arriving during long calculations
implemented purely in C (such as regular expression matches on large bodies of
text) may be delayed for an arbitrary amount of time.
* When a signal arrives during an I/O operation, it is possible that the I/O
operation raises an exception after the signal handler returns. This is
dependent on the underlying Unix system's semantics regarding interrupted system
calls.
* Because the C signal handler always returns, it makes little sense to catch
synchronous errors like :const:`SIGFPE` or :const:`SIGSEGV`.
* Python installs a small number of signal handlers by default: :const:`SIGPIPE`
is ignored (so write errors on pipes and sockets can be reported as ordinary
Python exceptions) and :const:`SIGINT` is translated into a
:exc:`KeyboardInterrupt` exception. All of these can be overridden.
* Some care must be taken if both signals and threads are used in the same
program. The fundamental thing to remember in using signals and threads
simultaneously is: always perform :func:`signal` operations in the main thread
of execution. Any thread can perform an :func:`alarm`, :func:`getsignal`,
:func:`pause`, :func:`setitimer` or :func:`getitimer`; only the main thread
can set a new signal handler, and the main thread will be the only one to
receive signals (this is enforced by the Python :mod:`signal` module, even
if the underlying thread implementation supports sending signals to
individual threads). This means that signals can't be used as a means of
inter-thread communication. Use locks instead.
The variables defined in the :mod:`signal` module are:
.. data:: SIG_DFL
This is one of two standard signal handling options; it will simply perform
the default function for the signal. For example, on most systems the
default action for :const:`SIGQUIT` is to dump core and exit, while the
default action for :const:`SIGCHLD` is to simply ignore it.
.. data:: SIG_IGN
This is another standard signal handler, which will simply ignore the given
signal.
.. data:: SIG*
All the signal numbers are defined symbolically. For example, the hangup signal
is defined as :const:`signal.SIGHUP`; the variable names are identical to the
names used in C programs, as found in ``<signal.h>``. The Unix man page for
':c:func:`signal`' lists the existing signals (on some systems this is
:manpage:`signal(2)`, on others the list is in :manpage:`signal(7)`). Note that
not all systems define the same set of signal names; only those names defined by
the system are defined by this module.
.. data:: CTRL_C_EVENT
The signal corresponding to the :kbd:`Ctrl+C` keystroke event. This signal can
only be used with :func:`os.kill`.
Availability: Windows.
.. versionadded:: 2.7
.. data:: CTRL_BREAK_EVENT
The signal corresponding to the :kbd:`Ctrl+Break` keystroke event. This signal can
only be used with :func:`os.kill`.
Availability: Windows.
.. versionadded:: 2.7
.. data:: NSIG
One more than the number of the highest signal number.
.. data:: ITIMER_REAL
Decrements interval timer in real time, and delivers :const:`SIGALRM` upon expiration.
.. data:: ITIMER_VIRTUAL
Decrements interval timer only when the process is executing, and delivers
SIGVTALRM upon expiration.
.. data:: ITIMER_PROF
Decrements interval timer both when the process executes and when the
system is executing on behalf of the process. Coupled with ITIMER_VIRTUAL,
this timer is usually used to profile the time spent by the application
in user and kernel space. SIGPROF is delivered upon expiration.
The :mod:`signal` module defines one exception:
.. exception:: ItimerError
Raised to signal an error from the underlying :func:`setitimer` or
:func:`getitimer` implementation. Expect this error if an invalid
interval timer or a negative time is passed to :func:`setitimer`.
This error is a subtype of :exc:`IOError`.
The :mod:`signal` module defines the following functions:
.. function:: alarm(time)
If *time* is non-zero, this function requests that a :const:`SIGALRM` signal be
sent to the process in *time* seconds. Any previously scheduled alarm is
canceled (only one alarm can be scheduled at any time). The returned value is
then the number of seconds before any previously set alarm was to have been
delivered. If *time* is zero, no alarm is scheduled, and any scheduled alarm is
canceled. If the return value is zero, no alarm is currently scheduled. (See
the Unix man page :manpage:`alarm(2)`.) Availability: Unix.
.. function:: getsignal(signalnum)
Return the current signal handler for the signal *signalnum*. The returned value
may be a callable Python object, or one of the special values
:const:`signal.SIG_IGN`, :const:`signal.SIG_DFL` or :const:`None`. Here,
:const:`signal.SIG_IGN` means that the signal was previously ignored,
:const:`signal.SIG_DFL` means that the default way of handling the signal was
previously in use, and ``None`` means that the previous signal handler was not
installed from Python.
.. function:: pause()
Cause the process to sleep until a signal is received; the appropriate handler
will then be called. Returns nothing. Not on Windows. (See the Unix man page
:manpage:`signal(2)`.)
.. function:: setitimer(which, seconds[, interval])
Sets given interval timer (one of :const:`signal.ITIMER_REAL`,
:const:`signal.ITIMER_VIRTUAL` or :const:`signal.ITIMER_PROF`) specified
by *which* to fire after *seconds* (float is accepted, different from
:func:`alarm`) and after that every *interval* seconds. The interval
timer specified by *which* can be cleared by setting seconds to zero.
When an interval timer fires, a signal is sent to the process.
The signal sent is dependent on the timer being used;
:const:`signal.ITIMER_REAL` will deliver :const:`SIGALRM`,
:const:`signal.ITIMER_VIRTUAL` sends :const:`SIGVTALRM`,
and :const:`signal.ITIMER_PROF` will deliver :const:`SIGPROF`.
The old values are returned as a tuple: (delay, interval).
Attempting to pass an invalid interval timer will cause an
:exc:`ItimerError`. Availability: Unix.
.. versionadded:: 2.6
.. function:: getitimer(which)
Returns current value of a given interval timer specified by *which*.
Availability: Unix.
.. versionadded:: 2.6
.. function:: set_wakeup_fd(fd)
Set the wakeup fd to *fd*. When a signal is received, a ``'\0'`` byte is
written to the fd. This can be used by a library to wakeup a poll or select
call, allowing the signal to be fully processed.
The old wakeup fd is returned (or -1 if file descriptor wakeup was not
enabled). If *fd* is -1, file descriptor wakeup is disabled.
If not -1, *fd* must be non-blocking. It is up to the library to remove
any bytes from *fd* before calling poll or select again.
When threads are enabled, this function can only be called from the main thread;
attempting to call it from other threads will cause a :exc:`ValueError`
exception to be raised.
.. versionadded:: 2.6
.. function:: siginterrupt(signalnum, flag)
Change system call restart behaviour: if *flag* is :const:`False`, system
calls will be restarted when interrupted by signal *signalnum*, otherwise
system calls will be interrupted. Returns nothing. Availability: Unix (see
the man page :manpage:`siginterrupt(3)` for further information).
Note that installing a signal handler with :func:`signal` will reset the
restart behaviour to interruptible by implicitly calling
:c:func:`siginterrupt` with a true *flag* value for the given signal.
.. versionadded:: 2.6
.. function:: signal(signalnum, handler)
Set the handler for signal *signalnum* to the function *handler*. *handler* can
be a callable Python object taking two arguments (see below), or one of the
special values :const:`signal.SIG_IGN` or :const:`signal.SIG_DFL`. The previous
signal handler will be returned (see the description of :func:`getsignal`
above). (See the Unix man page :manpage:`signal(2)`.)
When threads are enabled, this function can only be called from the main thread;
attempting to call it from other threads will cause a :exc:`ValueError`
exception to be raised.
The *handler* is called with two arguments: the signal number and the current
stack frame (``None`` or a frame object; for a description of frame objects,
see the :ref:`description in the type hierarchy <frame-objects>` or see the
attribute descriptions in the :mod:`inspect` module).
On Windows, :func:`signal` can only be called with :const:`SIGABRT`,
:const:`SIGFPE`, :const:`SIGILL`, :const:`SIGINT`, :const:`SIGSEGV`, or
:const:`SIGTERM`. A :exc:`ValueError` will be raised in any other case.
.. _signal-example:
Example
-------
Here is a minimal example program. It uses the :func:`alarm` function to limit
the time spent waiting to open a file; this is useful if the file is for a
serial device that may not be turned on, which would normally cause the
:func:`os.open` to hang indefinitely. The solution is to set a 5-second alarm
before opening the file; if the operation takes too long, the alarm signal will
be sent, and the handler raises an exception. ::
import signal, os
def handler(signum, frame):
print 'Signal handler called with signal', signum
raise IOError("Couldn't open device!")
# Set the signal handler and a 5-second alarm
signal.signal(signal.SIGALRM, handler)
signal.alarm(5)
# This open() may hang indefinitely
fd = os.open('/dev/ttyS0', os.O_RDWR)
signal.alarm(0) # Disable the alarm
PK
%�\qN2�� � . html/_sources/library/simplehttpserver.rst.txtnu �[���
:mod:`SimpleHTTPServer` --- Simple HTTP request handler
=======================================================
.. module:: SimpleHTTPServer
:synopsis: This module provides a basic request handler for HTTP servers.
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
.. note::
The :mod:`SimpleHTTPServer` module has been merged into :mod:`http.server` in
Python 3. The :term:`2to3` tool will automatically adapt imports when
converting your sources to Python 3.
.. warning::
mod:`SimpleHTTServer` is not recommended for production. It only implements
basic security checks.
The :mod:`SimpleHTTPServer` module defines a single class,
:class:`SimpleHTTPRequestHandler`, which is interface-compatible with
:class:`BaseHTTPServer.BaseHTTPRequestHandler`.
The :mod:`SimpleHTTPServer` module defines the following class:
.. class:: SimpleHTTPRequestHandler(request, client_address, server)
This class serves files from the current directory and below, directly
mapping the directory structure to HTTP requests.
A lot of the work, such as parsing the request, is done by the base class
:class:`BaseHTTPServer.BaseHTTPRequestHandler`. This class implements the
:func:`do_GET` and :func:`do_HEAD` functions.
The following are defined as class-level attributes of
:class:`SimpleHTTPRequestHandler`:
.. attribute:: server_version
This will be ``"SimpleHTTP/" + __version__``, where ``__version__`` is
defined at the module level.
.. attribute:: extensions_map
A dictionary mapping suffixes into MIME types. The default is
signified by an empty string, and is considered to be
``application/octet-stream``. The mapping is used case-insensitively,
and so should contain only lower-cased keys.
The :class:`SimpleHTTPRequestHandler` class defines the following methods:
.. method:: do_HEAD()
This method serves the ``'HEAD'`` request type: it sends the headers it
would send for the equivalent ``GET`` request. See the :meth:`do_GET`
method for a more complete explanation of the possible headers.
.. method:: do_GET()
The request is mapped to a local file by interpreting the request as a
path relative to the current working directory.
If the request was mapped to a directory, the directory is checked for a
file named ``index.html`` or ``index.htm`` (in that order). If found, the
file's contents are returned; otherwise a directory listing is generated
by calling the :meth:`list_directory` method. This method uses
:func:`os.listdir` to scan the directory, and returns a ``404`` error
response if the :func:`listdir` fails.
If the request was mapped to a file, it is opened and the contents are
returned. Any :exc:`IOError` exception in opening the requested file is
mapped to a ``404``, ``'File not found'`` error. Otherwise, the content
type is guessed by calling the :meth:`guess_type` method, which in turn
uses the *extensions_map* variable.
A ``'Content-type:'`` header with the guessed content type is output,
followed by a ``'Content-Length:'`` header with the file's size and a
``'Last-Modified:'`` header with the file's modification time.
Then follows a blank line signifying the end of the headers, and then the
contents of the file are output. If the file's MIME type starts with
``text/`` the file is opened in text mode; otherwise binary mode is used.
The :func:`test` function in the :mod:`SimpleHTTPServer` module is an
example which creates a server using the :class:`SimpleHTTPRequestHandler`
as the Handler.
.. versionadded:: 2.5
The ``'Last-Modified'`` header.
The :mod:`SimpleHTTPServer` module can be used in the following manner in order
to set up a very basic web server serving files relative to the current
directory. ::
import SimpleHTTPServer
import SocketServer
PORT = 8000
Handler = SimpleHTTPServer.SimpleHTTPRequestHandler
httpd = SocketServer.TCPServer(("", PORT), Handler)
print "serving at port", PORT
httpd.serve_forever()
The :mod:`SimpleHTTPServer` module can also be invoked directly using the
:option:`-m` switch of the interpreter with a ``port number`` argument.
Similar to the previous example, this serves the files relative to the
current directory. ::
python -m SimpleHTTPServer 8000
.. seealso::
Module :mod:`BaseHTTPServer`
Base class implementation for Web server and request handler.
PK
%�\���ǁ* �* 0 html/_sources/library/simplexmlrpcserver.rst.txtnu �[��� :mod:`SimpleXMLRPCServer` --- Basic XML-RPC server
==================================================
.. module:: SimpleXMLRPCServer
:synopsis: Basic XML-RPC server implementation.
.. moduleauthor:: Brian Quinlan <brianq@activestate.com>
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
.. note::
The :mod:`SimpleXMLRPCServer` module has been merged into
:mod:`xmlrpc.server` in Python 3. The :term:`2to3` tool will automatically
adapt imports when converting your sources to Python 3.
.. versionadded:: 2.2
**Source code:** :source:`Lib/SimpleXMLRPCServer.py`
--------------
The :mod:`SimpleXMLRPCServer` module provides a basic server framework for
XML-RPC servers written in Python. Servers can either be free standing, using
:class:`~SimpleXMLRPCServer.SimpleXMLRPCServer`, or embedded in a CGI environment, using
:class:`CGIXMLRPCRequestHandler`.
.. class:: SimpleXMLRPCServer(addr[, requestHandler[, logRequests[, allow_none[, encoding[, bind_and_activate]]]])
Create a new server instance. This class provides methods for registration of
functions that can be called by the XML-RPC protocol. The *requestHandler*
parameter should be a factory for request handler instances; it defaults to
:class:`SimpleXMLRPCRequestHandler`. The *addr* and *requestHandler* parameters
are passed to the :class:`SocketServer.TCPServer` constructor. If *logRequests*
is true (the default), requests will be logged; setting this parameter to false
will turn off logging. The *allow_none* and *encoding* parameters are passed
on to :mod:`xmlrpclib` and control the XML-RPC responses that will be returned
from the server. The *bind_and_activate* parameter controls whether
:meth:`server_bind` and :meth:`server_activate` are called immediately by the
constructor; it defaults to true. Setting it to false allows code to manipulate
the *allow_reuse_address* class variable before the address is bound.
.. versionchanged:: 2.5
The *allow_none* and *encoding* parameters were added.
.. versionchanged:: 2.6
The *bind_and_activate* parameter was added.
.. class:: CGIXMLRPCRequestHandler([allow_none[, encoding]])
Create a new instance to handle XML-RPC requests in a CGI environment. The
*allow_none* and *encoding* parameters are passed on to :mod:`xmlrpclib` and
control the XML-RPC responses that will be returned from the server.
.. versionadded:: 2.3
.. versionchanged:: 2.5
The *allow_none* and *encoding* parameters were added.
.. class:: SimpleXMLRPCRequestHandler()
Create a new request handler instance. This request handler supports ``POST``
requests and modifies logging so that the *logRequests* parameter to the
:class:`~SimpleXMLRPCServer.SimpleXMLRPCServer` constructor parameter is honored.
.. _simple-xmlrpc-servers:
SimpleXMLRPCServer Objects
--------------------------
The :class:`~SimpleXMLRPCServer.SimpleXMLRPCServer` class is based on
:class:`SocketServer.TCPServer` and provides a means of creating simple, stand
alone XML-RPC servers.
.. method:: SimpleXMLRPCServer.register_function(function[, name])
Register a function that can respond to XML-RPC requests. If *name* is given,
it will be the method name associated with *function*, otherwise
``function.__name__`` will be used. *name* can be either a normal or Unicode
string, and may contain characters not legal in Python identifiers, including
the period character.
.. method:: SimpleXMLRPCServer.register_instance(instance[, allow_dotted_names])
Register an object which is used to expose method names which have not been
registered using :meth:`register_function`. If *instance* contains a
:meth:`_dispatch` method, it is called with the requested method name and the
parameters from the request. Its API is ``def _dispatch(self, method, params)``
(note that *params* does not represent a variable argument list). If it calls
an underlying function to perform its task, that function is called as
``func(*params)``, expanding the parameter list. The return value from
:meth:`_dispatch` is returned to the client as the result. If *instance* does
not have a :meth:`_dispatch` method, it is searched for an attribute matching
the name of the requested method.
If the optional *allow_dotted_names* argument is true and the instance does not
have a :meth:`_dispatch` method, then if the requested method name contains
periods, each component of the method name is searched for individually, with
the effect that a simple hierarchical search is performed. The value found from
this search is then called with the parameters from the request, and the return
value is passed back to the client.
.. warning::
Enabling the *allow_dotted_names* option allows intruders to access your
module's global variables and may allow intruders to execute arbitrary code on
your machine. Only use this option on a secure, closed network.
.. versionchanged:: 2.3.5, 2.4.1
*allow_dotted_names* was added to plug a security hole; prior versions are
insecure.
.. method:: SimpleXMLRPCServer.register_introspection_functions()
Registers the XML-RPC introspection functions ``system.listMethods``,
``system.methodHelp`` and ``system.methodSignature``.
.. versionadded:: 2.3
.. method:: SimpleXMLRPCServer.register_multicall_functions()
Registers the XML-RPC multicall function system.multicall.
.. attribute:: SimpleXMLRPCRequestHandler.rpc_paths
An attribute value that must be a tuple listing valid path portions of the URL
for receiving XML-RPC requests. Requests posted to other paths will result in a
404 "no such page" HTTP error. If this tuple is empty, all paths will be
considered valid. The default value is ``('/', '/RPC2')``.
.. versionadded:: 2.5
.. attribute:: SimpleXMLRPCRequestHandler.encode_threshold
If this attribute is not ``None``, responses larger than this value
will be encoded using the *gzip* transfer encoding, if permitted by
the client. The default is ``1400`` which corresponds roughly
to a single TCP packet.
.. versionadded:: 2.7
.. _simplexmlrpcserver-example:
SimpleXMLRPCServer Example
^^^^^^^^^^^^^^^^^^^^^^^^^^
Server code::
from SimpleXMLRPCServer import SimpleXMLRPCServer
from SimpleXMLRPCServer import SimpleXMLRPCRequestHandler
# Restrict to a particular path.
class RequestHandler(SimpleXMLRPCRequestHandler):
rpc_paths = ('/RPC2',)
# Create server
server = SimpleXMLRPCServer(("localhost", 8000),
requestHandler=RequestHandler)
server.register_introspection_functions()
# Register pow() function; this will use the value of
# pow.__name__ as the name, which is just 'pow'.
server.register_function(pow)
# Register a function under a different name
def adder_function(x,y):
return x + y
server.register_function(adder_function, 'add')
# Register an instance; all the methods of the instance are
# published as XML-RPC methods (in this case, just 'div').
class MyFuncs:
def div(self, x, y):
return x // y
server.register_instance(MyFuncs())
# Run the server's main loop
server.serve_forever()
The following client code will call the methods made available by the preceding
server::
import xmlrpclib
s = xmlrpclib.ServerProxy('http://localhost:8000')
print s.pow(2,3) # Returns 2**3 = 8
print s.add(2,3) # Returns 5
print s.div(5,2) # Returns 5//2 = 2
# Print list of available methods
print s.system.listMethods()
The following :class:`~SimpleXMLRPCServer.SimpleXMLRPCServer` example is included in the module
`Lib/SimpleXMLRPCServer.py`::
server = SimpleXMLRPCServer(("localhost", 8000))
server.register_function(pow)
server.register_function(lambda x,y: x+y, 'add')
server.register_multicall_functions()
server.serve_forever()
This demo server can be run from the command line as::
python -m SimpleXMLRPCServer
Example client code which talks to the above server is included with
`Lib/xmlrpclib.py`::
server = ServerProxy("http://localhost:8000")
print server
multi = MultiCall(server)
multi.pow(2, 9)
multi.add(5, 1)
multi.add(24, 11)
try:
for response in multi():
print response
except Error, v:
print "ERROR", v
And the client can be invoked directly using the following command::
python -m xmlrpclib
CGIXMLRPCRequestHandler
-----------------------
The :class:`CGIXMLRPCRequestHandler` class can be used to handle XML-RPC
requests sent to Python CGI scripts.
.. method:: CGIXMLRPCRequestHandler.register_function(function[, name])
Register a function that can respond to XML-RPC requests. If *name* is given,
it will be the method name associated with function, otherwise
*function.__name__* will be used. *name* can be either a normal or Unicode
string, and may contain characters not legal in Python identifiers, including
the period character.
.. method:: CGIXMLRPCRequestHandler.register_instance(instance)
Register an object which is used to expose method names which have not been
registered using :meth:`register_function`. If instance contains a
:meth:`_dispatch` method, it is called with the requested method name and the
parameters from the request; the return value is returned to the client as the
result. If instance does not have a :meth:`_dispatch` method, it is searched
for an attribute matching the name of the requested method; if the requested
method name contains periods, each component of the method name is searched for
individually, with the effect that a simple hierarchical search is performed.
The value found from this search is then called with the parameters from the
request, and the return value is passed back to the client.
.. method:: CGIXMLRPCRequestHandler.register_introspection_functions()
Register the XML-RPC introspection functions ``system.listMethods``,
``system.methodHelp`` and ``system.methodSignature``.
.. method:: CGIXMLRPCRequestHandler.register_multicall_functions()
Register the XML-RPC multicall function ``system.multicall``.
.. method:: CGIXMLRPCRequestHandler.handle_request([request_text = None])
Handle an XML-RPC request. If *request_text* is given, it should be the POST
data provided by the HTTP server, otherwise the contents of stdin will be used.
Example::
class MyFuncs:
def div(self, x, y): return x // y
handler = CGIXMLRPCRequestHandler()
handler.register_function(pow)
handler.register_function(lambda x,y: x+y, 'add')
handler.register_introspection_functions()
handler.register_instance(MyFuncs())
handler.handle_request()
PK
%�\٣6�� � " html/_sources/library/site.rst.txtnu �[��� :mod:`site` --- Site-specific configuration hook
================================================
.. module:: site
:synopsis: Module responsible for site-specific configuration.
**Source code:** :source:`Lib/site.py`
--------------
.. highlightlang:: none
**This module is automatically imported during initialization.** The automatic
import can be suppressed using the interpreter's :option:`-S` option.
.. index:: triple: module; search; path
Importing this module will append site-specific paths to the module search path
and add a few builtins.
.. index::
pair: site-python; directory
pair: site-packages; directory
It starts by constructing up to four directories from a head and a tail part.
For the head part, it uses ``sys.prefix`` and ``sys.exec_prefix``; empty heads
are skipped. For the tail part, it uses the empty string and then
:file:`lib/site-packages` (on Windows) or
:file:`lib/python{X.Y}/site-packages` and then :file:`lib/site-python` (on
Unix and Macintosh). For each of the distinct head-tail combinations, it sees
if it refers to an existing directory, and if so, adds it to ``sys.path`` and
also inspects the newly added path for configuration files.
A path configuration file is a file whose name has the form :file:`{name}.pth`
and exists in one of the four directories mentioned above; its contents are
additional items (one per line) to be added to ``sys.path``. Non-existing items
are never added to ``sys.path``, and no check is made that the item refers to a
directory rather than a file. No item is added to ``sys.path`` more than
once. Blank lines and lines beginning with ``#`` are skipped. Lines starting
with ``import`` (followed by space or tab) are executed.
.. versionchanged:: 2.6
A space or tab is now required after the import keyword.
.. index::
single: package
triple: path; configuration; file
For example, suppose ``sys.prefix`` and ``sys.exec_prefix`` are set to
:file:`/usr/local`. The Python X.Y library is then installed in
:file:`/usr/local/lib/python{X.Y}`. Suppose this has
a subdirectory :file:`/usr/local/lib/python{X.Y}/site-packages` with three
subsubdirectories, :file:`foo`, :file:`bar` and :file:`spam`, and two path
configuration files, :file:`foo.pth` and :file:`bar.pth`. Assume
:file:`foo.pth` contains the following::
# foo package configuration
foo
bar
bletch
and :file:`bar.pth` contains::
# bar package configuration
bar
Then the following version-specific directories are added to
``sys.path``, in this order::
/usr/local/lib/pythonX.Y/site-packages/bar
/usr/local/lib/pythonX.Y/site-packages/foo
Note that :file:`bletch` is omitted because it doesn't exist; the :file:`bar`
directory precedes the :file:`foo` directory because :file:`bar.pth` comes
alphabetically before :file:`foo.pth`; and :file:`spam` is omitted because it is
not mentioned in either path configuration file.
.. index:: module: sitecustomize
After these path manipulations, an attempt is made to import a module named
:mod:`sitecustomize`, which can perform arbitrary site-specific customizations.
It is typically created by a system administrator in the site-packages
directory. If this import fails with an :exc:`ImportError` exception, it is
silently ignored. If Python is started without output streams available, as
with :file:`pythonw.exe` on Windows (which is used by default to start IDLE),
attempted output from :mod:`sitecustomize` is ignored. Any exception other
than :exc:`ImportError` causes a silent and perhaps mysterious failure of the
process.
.. index:: module: usercustomize
After this, an attempt is made to import a module named :mod:`usercustomize`,
which can perform arbitrary user-specific customizations, if
:data:`ENABLE_USER_SITE` is true. This file is intended to be created in the
user site-packages directory (see below), which is part of ``sys.path`` unless
disabled by :option:`-s`. An :exc:`ImportError` will be silently ignored.
Note that for some non-Unix systems, ``sys.prefix`` and ``sys.exec_prefix`` are
empty, and the path manipulations are skipped; however the import of
:mod:`sitecustomize` and :mod:`usercustomize` is still attempted.
.. data:: PREFIXES
A list of prefixes for site-packages directories.
.. versionadded:: 2.6
.. data:: ENABLE_USER_SITE
Flag showing the status of the user site-packages directory. ``True`` means
that it is enabled and was added to ``sys.path``. ``False`` means that it
was disabled by user request (with :option:`-s` or
:envvar:`PYTHONNOUSERSITE`). ``None`` means it was disabled for security
reasons (mismatch between user or group id and effective id) or by an
administrator.
.. versionadded:: 2.6
.. data:: USER_SITE
Path to the user site-packages for the running Python. Can be ``None`` if
:func:`getusersitepackages` hasn't been called yet. Default value is
:file:`~/.local/lib/python{X.Y}/site-packages` for UNIX and non-framework Mac
OS X builds, :file:`~/Library/Python/{X.Y}/lib/python/site-packages` for Mac
framework builds, and :file:`{%APPDATA%}\\Python\\Python{XY}\\site-packages`
on Windows. This directory is a site directory, which means that
:file:`.pth` files in it will be processed.
.. versionadded:: 2.6
.. data:: USER_BASE
Path to the base directory for the user site-packages. Can be ``None`` if
:func:`getuserbase` hasn't been called yet. Default value is
:file:`~/.local` for UNIX and Mac OS X non-framework builds,
:file:`~/Library/Python/{X.Y}` for Mac framework builds, and
:file:`{%APPDATA%}\\Python` for Windows. This value is used by Distutils to
compute the installation directories for scripts, data files, Python modules,
etc. for the :ref:`user installation scheme <inst-alt-install-user>`. See
also :envvar:`PYTHONUSERBASE`.
.. versionadded:: 2.6
.. function:: addsitedir(sitedir, known_paths=None)
Add a directory to sys.path and process its :file:`.pth` files. Typically
used in :mod:`sitecustomize` or :mod:`usercustomize` (see above).
.. function:: getsitepackages()
Return a list containing all global site-packages directories (and possibly
site-python).
.. versionadded:: 2.7
.. function:: getuserbase()
Return the path of the user base directory, :data:`USER_BASE`. If it is not
initialized yet, this function will also set it, respecting
:envvar:`PYTHONUSERBASE`.
.. versionadded:: 2.7
.. function:: getusersitepackages()
Return the path of the user-specific site-packages directory,
:data:`USER_SITE`. If it is not initialized yet, this function will also set
it, respecting :envvar:`PYTHONNOUSERSITE` and :data:`USER_BASE`.
.. versionadded:: 2.7
The :mod:`site` module also provides a way to get the user directories from the
command line:
.. code-block:: sh
$ python -m site --user-site
/home/user/.local/lib/python2.7/site-packages
.. program:: site
If it is called without arguments, it will print the contents of
:data:`sys.path` on the standard output, followed by the value of
:data:`USER_BASE` and whether the directory exists, then the same thing for
:data:`USER_SITE`, and finally the value of :data:`ENABLE_USER_SITE`.
.. cmdoption:: --user-base
Print the path to the user base directory.
.. cmdoption:: --user-site
Print the path to the user site-packages directory.
If both options are given, user base and user site will be printed (always in
this order), separated by :data:`os.pathsep`.
If any option is given, the script will exit with one of these values: ``0`` if
the user site-packages directory is enabled, ``1`` if it was disabled by the
user, ``2`` if it is disabled for security reasons or by an administrator, and a
value greater than 2 if there is an error.
.. seealso::
:pep:`370` -- Per user site-packages directory
PK
%�\�4�2� � # html/_sources/library/smtpd.rst.txtnu �[��� :mod:`smtpd` --- SMTP Server
============================
.. module:: smtpd
:synopsis: A SMTP server implementation in Python.
.. moduleauthor:: Barry Warsaw <barry@zope.com>
.. sectionauthor:: Moshe Zadka <moshez@moshez.org>
**Source code:** :source:`Lib/smtpd.py`
--------------
This module offers several classes to implement SMTP servers. One is a generic
do-nothing implementation, which can be overridden, while the other two offer
specific mail-sending strategies.
SMTPServer Objects
------------------
.. class:: SMTPServer(localaddr, remoteaddr)
Create a new :class:`SMTPServer` object, which binds to local address
*localaddr*. It will treat *remoteaddr* as an upstream SMTP relayer. Both
*localaddr* and *remoteaddr* should be a :ref:`(host, port) <host_port>`
tuple. The object inherits from :class:`asyncore.dispatcher`, and so will
insert itself into :mod:`asyncore`'s event loop on instantiation.
.. method:: process_message(peer, mailfrom, rcpttos, data)
Raise :exc:`NotImplementedError` exception. Override this in subclasses to
do something useful with this message. Whatever was passed in the
constructor as *remoteaddr* will be available as the :attr:`_remoteaddr`
attribute. *peer* is the remote host's address, *mailfrom* is the envelope
originator, *rcpttos* are the envelope recipients and *data* is a string
containing the contents of the e-mail (which should be in :rfc:`2822`
format).
DebuggingServer Objects
-----------------------
.. class:: DebuggingServer(localaddr, remoteaddr)
Create a new debugging server. Arguments are as per :class:`SMTPServer`.
Messages will be discarded, and printed on stdout.
PureProxy Objects
-----------------
.. class:: PureProxy(localaddr, remoteaddr)
Create a new pure proxy server. Arguments are as per :class:`SMTPServer`.
Everything will be relayed to *remoteaddr*. Note that running this has a good
chance to make you into an open relay, so please be careful.
MailmanProxy Objects
--------------------
.. class:: MailmanProxy(localaddr, remoteaddr)
Create a new pure proxy server. Arguments are as per :class:`SMTPServer`.
Everything will be relayed to *remoteaddr*, unless local mailman configurations
knows about an address, in which case it will be handled via mailman. Note that
running this has a good chance to make you into an open relay, so please be
careful.
PK
%�\ v:: :: % html/_sources/library/smtplib.rst.txtnu �[��� :mod:`smtplib` --- SMTP protocol client
=======================================
.. module:: smtplib
:synopsis: SMTP protocol client (requires sockets).
.. sectionauthor:: Eric S. Raymond <esr@snark.thyrsus.com>
.. index::
pair: SMTP; protocol
single: Simple Mail Transfer Protocol
**Source code:** :source:`Lib/smtplib.py`
--------------
The :mod:`smtplib` module defines an SMTP client session object that can be used
to send mail to any Internet machine with an SMTP or ESMTP listener daemon. For
details of SMTP and ESMTP operation, consult :rfc:`821` (Simple Mail Transfer
Protocol) and :rfc:`1869` (SMTP Service Extensions).
.. class:: SMTP([host[, port[, local_hostname[, timeout]]]])
An :class:`SMTP` instance encapsulates an SMTP connection. It has methods
that support a full repertoire of SMTP and ESMTP operations. If the optional
host and port parameters are given, the SMTP :meth:`connect` method is
called with those parameters during initialization. If specified,
*local_hostname* is used as the FQDN of the local host in the HELO/EHLO
command. Otherwise, the local hostname is found using
:func:`socket.getfqdn`. If the :meth:`connect` call returns anything other
than a success code, an :exc:`SMTPConnectError` is raised. The optional
*timeout* parameter specifies a timeout in seconds for blocking operations
like the connection attempt (if not specified, the global default timeout
setting will be used). If the timeout expires, :exc:`socket.timeout`
is raised.
For normal use, you should only require the initialization/connect,
:meth:`sendmail`, and :meth:`SMTP.quit` methods.
An example is included below.
.. versionchanged:: 2.6
*timeout* was added.
.. class:: SMTP_SSL([host[, port[, local_hostname[, keyfile[, certfile[, timeout]]]]]])
An :class:`SMTP_SSL` instance behaves exactly the same as instances of
:class:`SMTP`. :class:`SMTP_SSL` should be used for situations where SSL is
required from the beginning of the connection and using :meth:`starttls` is
not appropriate. If *host* is not specified, the local host is used. If
*port* is omitted, the standard SMTP-over-SSL port (465) is used.
*local_hostname* has the same meaning as it does for the :class:`SMTP`
class. *keyfile* and *certfile* are also optional, and can contain a PEM
formatted private key and certificate chain file for the SSL connection. The
optional *timeout* parameter specifies a timeout in seconds for blocking
operations like the connection attempt (if not specified, the global default
timeout setting will be used). If the timeout expires, :exc:`socket.timeout`
is raised.
.. versionadded:: 2.6
.. class:: LMTP([host[, port[, local_hostname]]])
The LMTP protocol, which is very similar to ESMTP, is heavily based on the
standard SMTP client. It's common to use Unix sockets for LMTP, so our
:meth:`connect` method must support that as well as a regular host:port
server. *local_hostname* has the same meaning as it does for the
:class:`SMTP` class. To specify a Unix socket, you must use an absolute
path for *host*, starting with a '/'.
Authentication is supported, using the regular SMTP mechanism. When using a
Unix socket, LMTP generally don't support or require any authentication, but
your mileage might vary.
.. versionadded:: 2.6
A nice selection of exceptions is defined as well:
.. exception:: SMTPException
The base exception class for all the other exceptions provided by this
module.
.. exception:: SMTPServerDisconnected
This exception is raised when the server unexpectedly disconnects, or when an
attempt is made to use the :class:`SMTP` instance before connecting it to a
server.
.. exception:: SMTPResponseException
Base class for all exceptions that include an SMTP error code. These exceptions
are generated in some instances when the SMTP server returns an error code. The
error code is stored in the :attr:`smtp_code` attribute of the error, and the
:attr:`smtp_error` attribute is set to the error message.
.. exception:: SMTPSenderRefused
Sender address refused. In addition to the attributes set by on all
:exc:`SMTPResponseException` exceptions, this sets 'sender' to the string that
the SMTP server refused.
.. exception:: SMTPRecipientsRefused
All recipient addresses refused. The errors for each recipient are accessible
through the attribute :attr:`recipients`, which is a dictionary of exactly the
same sort as :meth:`SMTP.sendmail` returns.
.. exception:: SMTPDataError
The SMTP server refused to accept the message data.
.. exception:: SMTPConnectError
Error occurred during establishment of a connection with the server.
.. exception:: SMTPHeloError
The server refused our ``HELO`` message.
.. exception:: SMTPAuthenticationError
SMTP authentication went wrong. Most probably the server didn't accept the
username/password combination provided.
.. seealso::
:rfc:`821` - Simple Mail Transfer Protocol
Protocol definition for SMTP. This document covers the model, operating
procedure, and protocol details for SMTP.
:rfc:`1869` - SMTP Service Extensions
Definition of the ESMTP extensions for SMTP. This describes a framework for
extending SMTP with new commands, supporting dynamic discovery of the commands
provided by the server, and defines a few additional commands.
.. _smtp-objects:
SMTP Objects
------------
An :class:`SMTP` instance has the following methods:
.. method:: SMTP.set_debuglevel(level)
Set the debug output level. A true value for *level* results in debug messages
for connection and for all messages sent to and received from the server.
.. method:: SMTP.docmd(cmd, [, argstring])
Send a command *cmd* to the server. The optional argument *argstring* is simply
concatenated to the command, separated by a space.
This returns a 2-tuple composed of a numeric response code and the actual
response line (multiline responses are joined into one long line.)
In normal operation it should not be necessary to call this method explicitly.
It is used to implement other methods and may be useful for testing private
extensions.
If the connection to the server is lost while waiting for the reply,
:exc:`SMTPServerDisconnected` will be raised.
.. method:: SMTP.connect([host[, port]])
Connect to a host on a given port. The defaults are to connect to the local
host at the standard SMTP port (25). If the hostname ends with a colon (``':'``)
followed by a number, that suffix will be stripped off and the number
interpreted as the port number to use. This method is automatically invoked by
the constructor if a host is specified during instantiation. Returns a
2-tuple of the response code and message sent by the server in its
connection response.
.. method:: SMTP.helo([hostname])
Identify yourself to the SMTP server using ``HELO``. The hostname argument
defaults to the fully qualified domain name of the local host.
The message returned by the server is stored as the :attr:`helo_resp` attribute
of the object.
In normal operation it should not be necessary to call this method explicitly.
It will be implicitly called by the :meth:`sendmail` when necessary.
.. method:: SMTP.ehlo([hostname])
Identify yourself to an ESMTP server using ``EHLO``. The hostname argument
defaults to the fully qualified domain name of the local host. Examine the
response for ESMTP option and store them for use by :meth:`has_extn`.
Also sets several informational attributes: the message returned by
the server is stored as the :attr:`ehlo_resp` attribute, :attr:`does_esmtp`
is set to true or false depending on whether the server supports ESMTP, and
:attr:`esmtp_features` will be a dictionary containing the names of the
SMTP service extensions this server supports, and their
parameters (if any).
Unless you wish to use :meth:`has_extn` before sending mail, it should not be
necessary to call this method explicitly. It will be implicitly called by
:meth:`sendmail` when necessary.
.. method:: SMTP.ehlo_or_helo_if_needed()
This method call :meth:`ehlo` and or :meth:`helo` if there has been no
previous ``EHLO`` or ``HELO`` command this session. It tries ESMTP ``EHLO``
first.
:exc:`SMTPHeloError`
The server didn't reply properly to the ``HELO`` greeting.
.. versionadded:: 2.6
.. method:: SMTP.has_extn(name)
Return :const:`True` if *name* is in the set of SMTP service extensions returned
by the server, :const:`False` otherwise. Case is ignored.
.. method:: SMTP.verify(address)
Check the validity of an address on this server using SMTP ``VRFY``. Returns a
tuple consisting of code 250 and a full :rfc:`822` address (including human
name) if the user address is valid. Otherwise returns an SMTP error code of 400
or greater and an error string.
.. note::
Many sites disable SMTP ``VRFY`` in order to foil spammers.
.. method:: SMTP.login(user, password)
Log in on an SMTP server that requires authentication. The arguments are the
username and the password to authenticate with. If there has been no previous
``EHLO`` or ``HELO`` command this session, this method tries ESMTP ``EHLO``
first. This method will return normally if the authentication was successful, or
may raise the following exceptions:
:exc:`SMTPHeloError`
The server didn't reply properly to the ``HELO`` greeting.
:exc:`SMTPAuthenticationError`
The server didn't accept the username/password combination.
:exc:`SMTPException`
No suitable authentication method was found.
.. method:: SMTP.starttls([keyfile[, certfile]])
Put the SMTP connection in TLS (Transport Layer Security) mode. All SMTP
commands that follow will be encrypted. You should then call :meth:`ehlo`
again.
If *keyfile* and *certfile* are provided, these are passed to the :mod:`socket`
module's :func:`ssl` function.
If there has been no previous ``EHLO`` or ``HELO`` command this session,
this method tries ESMTP ``EHLO`` first.
.. versionchanged:: 2.6
:exc:`SMTPHeloError`
The server didn't reply properly to the ``HELO`` greeting.
:exc:`SMTPException`
The server does not support the STARTTLS extension.
.. versionchanged:: 2.6
:exc:`RuntimeError`
SSL/TLS support is not available to your Python interpreter.
.. method:: SMTP.sendmail(from_addr, to_addrs, msg[, mail_options, rcpt_options])
Send mail. The required arguments are an :rfc:`822` from-address string, a list
of :rfc:`822` to-address strings (a bare string will be treated as a list with 1
address), and a message string. The caller may pass a list of ESMTP options
(such as ``8bitmime``) to be used in ``MAIL FROM`` commands as *mail_options*.
ESMTP options (such as ``DSN`` commands) that should be used with all ``RCPT``
commands can be passed as *rcpt_options*. (If you need to use different ESMTP
options to different recipients you have to use the low-level methods such as
:meth:`mail`, :meth:`rcpt` and :meth:`data` to send the message.)
.. note::
The *from_addr* and *to_addrs* parameters are used to construct the message
envelope used by the transport agents. The :class:`SMTP` does not modify the
message headers in any way.
If there has been no previous ``EHLO`` or ``HELO`` command this session, this
method tries ESMTP ``EHLO`` first. If the server does ESMTP, message size and
each of the specified options will be passed to it (if the option is in the
feature set the server advertises). If ``EHLO`` fails, ``HELO`` will be tried
and ESMTP options suppressed.
This method will return normally if the mail is accepted for at least one
recipient. Otherwise it will raise an exception. That is, if this method does
not raise an exception, then someone should get your mail. If this method does
not raise an exception, it returns a dictionary, with one entry for each
recipient that was refused. Each entry contains a tuple of the SMTP error code
and the accompanying error message sent by the server.
This method may raise the following exceptions:
:exc:`SMTPRecipientsRefused`
All recipients were refused. Nobody got the mail. The :attr:`recipients`
attribute of the exception object is a dictionary with information about the
refused recipients (like the one returned when at least one recipient was
accepted).
:exc:`SMTPHeloError`
The server didn't reply properly to the ``HELO`` greeting.
:exc:`SMTPSenderRefused`
The server didn't accept the *from_addr*.
:exc:`SMTPDataError`
The server replied with an unexpected error code (other than a refusal of a
recipient).
Unless otherwise noted, the connection will be open even after an exception is
raised.
.. method:: SMTP.quit()
Terminate the SMTP session and close the connection. Return the result of
the SMTP ``QUIT`` command.
.. versionchanged:: 2.6
Return a value.
Low-level methods corresponding to the standard SMTP/ESMTP commands ``HELP``,
``RSET``, ``NOOP``, ``MAIL``, ``RCPT``, and ``DATA`` are also supported.
Normally these do not need to be called directly, so they are not documented
here. For details, consult the module code.
.. _smtp-example:
SMTP Example
------------
This example prompts the user for addresses needed in the message envelope ('To'
and 'From' addresses), and the message to be delivered. Note that the headers
to be included with the message must be included in the message as entered; this
example doesn't do any processing of the :rfc:`822` headers. In particular, the
'To' and 'From' addresses must be included in the message headers explicitly. ::
import smtplib
def prompt(prompt):
return raw_input(prompt).strip()
fromaddr = prompt("From: ")
toaddrs = prompt("To: ").split()
print "Enter message, end with ^D (Unix) or ^Z (Windows):"
# Add the From: and To: headers at the start!
msg = ("From: %s\r\nTo: %s\r\n\r\n"
% (fromaddr, ", ".join(toaddrs)))
while 1:
try:
line = raw_input()
except EOFError:
break
if not line:
break
msg = msg + line
print "Message length is " + repr(len(msg))
server = smtplib.SMTP('localhost')
server.set_debuglevel(1)
server.sendmail(fromaddr, toaddrs, msg)
server.quit()
.. note::
In general, you will want to use the :mod:`email` package's features to
construct an email message, which you can then convert to a string and send
via :meth:`sendmail`; see :ref:`email-examples`.
PK
%�\��� � $ html/_sources/library/sndhdr.rst.txtnu �[��� :mod:`sndhdr` --- Determine type of sound file
==============================================
.. module:: sndhdr
:synopsis: Determine type of a sound file.
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
.. Based on comments in the module source file.
.. index::
single: A-LAW
single: u-LAW
**Source code:** :source:`Lib/sndhdr.py`
--------------
The :mod:`sndhdr` provides utility functions which attempt to determine the type
of sound data which is in a file. When these functions are able to determine
what type of sound data is stored in a file, they return a tuple ``(type,
sampling_rate, channels, frames, bits_per_sample)``. The value for *type*
indicates the data type and will be one of the strings ``'aifc'``, ``'aiff'``,
``'au'``, ``'hcom'``, ``'sndr'``, ``'sndt'``, ``'voc'``, ``'wav'``, ``'8svx'``,
``'sb'``, ``'ub'``, or ``'ul'``. The *sampling_rate* will be either the actual
value or ``0`` if unknown or difficult to decode. Similarly, *channels* will be
either the number of channels or ``0`` if it cannot be determined or if the
value is difficult to decode. The value for *frames* will be either the number
of frames or ``-1``. The last item in the tuple, *bits_per_sample*, will either
be the sample size in bits or ``'A'`` for A-LAW or ``'U'`` for u-LAW.
.. function:: what(filename)
Determines the type of sound data stored in the file *filename* using
:func:`whathdr`. If it succeeds, returns a tuple as described above, otherwise
``None`` is returned.
.. function:: whathdr(filename)
Determines the type of sound data stored in a file based on the file header.
The name of the file is given by *filename*. This function returns a tuple as
described above on success, or ``None``.
PK
%�\<��G=� =� $ html/_sources/library/socket.rst.txtnu �[��� :mod:`socket` --- Low-level networking interface
================================================
.. module:: socket
:synopsis: Low-level networking interface.
This module provides access to the BSD *socket* interface. It is available on
all modern Unix systems, Windows, Mac OS X, BeOS, OS/2, and probably additional
platforms.
.. note::
Some behavior may be platform dependent, since calls are made to the operating
system socket APIs.
For an introduction to socket programming (in C), see the following papers: An
Introductory 4.3BSD Interprocess Communication Tutorial, by Stuart Sechrest and
An Advanced 4.3BSD Interprocess Communication Tutorial, by Samuel J. Leffler et
al, both in the UNIX Programmer's Manual, Supplementary Documents 1 (sections
PS1:7 and PS1:8). The platform-specific reference material for the various
socket-related system calls are also a valuable source of information on the
details of socket semantics. For Unix, refer to the manual pages; for Windows,
see the WinSock (or Winsock 2) specification. For IPv6-ready APIs, readers may
want to refer to :rfc:`3493` titled Basic Socket Interface Extensions for IPv6.
.. index:: object: socket
The Python interface is a straightforward transliteration of the Unix system
call and library interface for sockets to Python's object-oriented style: the
:func:`.socket` function returns a :dfn:`socket object` whose methods implement
the various socket system calls. Parameter types are somewhat higher-level than
in the C interface: as with :meth:`read` and :meth:`write` operations on Python
files, buffer allocation on receive operations is automatic, and buffer length
is implicit on send operations.
.. _host_port:
Socket addresses are represented as follows: A single string is used for the
:const:`AF_UNIX` address family. A pair ``(host, port)`` is used for the
:const:`AF_INET` address family, where *host* is a string representing either a
hostname in Internet domain notation like ``'daring.cwi.nl'`` or an IPv4 address
like ``'100.50.200.5'``, and *port* is an integer. For
:const:`AF_INET6` address family, a four-tuple ``(host, port, flowinfo,
scopeid)`` is used, where *flowinfo* and *scopeid* represents ``sin6_flowinfo``
and ``sin6_scope_id`` member in :const:`struct sockaddr_in6` in C. For
:mod:`socket` module methods, *flowinfo* and *scopeid* can be omitted just for
backward compatibility. Note, however, omission of *scopeid* can cause problems
in manipulating scoped IPv6 addresses. Other address families are currently not
supported. The address format required by a particular socket object is
automatically selected based on the address family specified when the socket
object was created.
For IPv4 addresses, two special forms are accepted instead of a host address:
the empty string represents :const:`INADDR_ANY`, and the string
``'<broadcast>'`` represents :const:`INADDR_BROADCAST`. The behavior is not
available for IPv6 for backward compatibility, therefore, you may want to avoid
these if you intend to support IPv6 with your Python programs.
If you use a hostname in the *host* portion of IPv4/v6 socket address, the
program may show a nondeterministic behavior, as Python uses the first address
returned from the DNS resolution. The socket address will be resolved
differently into an actual IPv4/v6 address, depending on the results from DNS
resolution and/or the host configuration. For deterministic behavior use a
numeric address in *host* portion.
.. versionadded:: 2.5
AF_NETLINK sockets are represented as pairs ``pid, groups``.
.. versionadded:: 2.6
Linux-only support for TIPC is also available using the :const:`AF_TIPC`
address family. TIPC is an open, non-IP based networked protocol designed
for use in clustered computer environments. Addresses are represented by a
tuple, and the fields depend on the address type. The general tuple form is
``(addr_type, v1, v2, v3 [, scope])``, where:
- *addr_type* is one of :const:`TIPC_ADDR_NAMESEQ`, :const:`TIPC_ADDR_NAME`,
or :const:`TIPC_ADDR_ID`.
- *scope* is one of :const:`TIPC_ZONE_SCOPE`, :const:`TIPC_CLUSTER_SCOPE`,
and :const:`TIPC_NODE_SCOPE`.
- If *addr_type* is :const:`TIPC_ADDR_NAME`, then *v1* is the server type, *v2* is
the port identifier, and *v3* should be 0.
If *addr_type* is :const:`TIPC_ADDR_NAMESEQ`, then *v1* is the server type, *v2*
is the lower port number, and *v3* is the upper port number.
If *addr_type* is :const:`TIPC_ADDR_ID`, then *v1* is the node, *v2* is the
reference, and *v3* should be set to 0.
All errors raise exceptions. The normal exceptions for invalid argument types
and out-of-memory conditions can be raised; errors related to socket or address
semantics raise the error :exc:`socket.error`.
Non-blocking mode is supported through :meth:`~socket.setblocking`. A
generalization of this based on timeouts is supported through
:meth:`~socket.settimeout`.
The module :mod:`socket` exports the following constants and functions:
.. exception:: error
.. index:: module: errno
This exception is raised for socket-related errors. The accompanying value is
either a string telling what went wrong or a pair ``(errno, string)``
representing an error returned by a system call, similar to the value
accompanying :exc:`os.error`. See the module :mod:`errno`, which contains names
for the error codes defined by the underlying operating system.
.. versionchanged:: 2.6
:exc:`socket.error` is now a child class of :exc:`IOError`.
.. exception:: herror
This exception is raised for address-related errors, i.e. for functions that use
*h_errno* in the C API, including :func:`gethostbyname_ex` and
:func:`gethostbyaddr`.
The accompanying value is a pair ``(h_errno, string)`` representing an error
returned by a library call. *string* represents the description of *h_errno*, as
returned by the :c:func:`hstrerror` C function.
.. exception:: gaierror
This exception is raised for address-related errors, for :func:`getaddrinfo` and
:func:`getnameinfo`. The accompanying value is a pair ``(error, string)``
representing an error returned by a library call. *string* represents the
description of *error*, as returned by the :c:func:`gai_strerror` C function. The
*error* value will match one of the :const:`EAI_\*` constants defined in this
module.
.. exception:: timeout
This exception is raised when a timeout occurs on a socket which has had
timeouts enabled via a prior call to :meth:`settimeout`. The accompanying value
is a string whose value is currently always "timed out".
.. versionadded:: 2.3
.. data:: AF_UNIX
AF_INET
AF_INET6
These constants represent the address (and protocol) families, used for the
first argument to :func:`.socket`. If the :const:`AF_UNIX` constant is not
defined then this protocol is unsupported.
.. data:: SOCK_STREAM
SOCK_DGRAM
SOCK_RAW
SOCK_RDM
SOCK_SEQPACKET
These constants represent the socket types, used for the second argument to
:func:`socket`. (Only :const:`SOCK_STREAM` and :const:`SOCK_DGRAM` appear to be
generally useful.)
.. data:: SO_*
SOMAXCONN
MSG_*
SOL_*
IPPROTO_*
IPPORT_*
INADDR_*
IP_*
IPV6_*
EAI_*
AI_*
NI_*
TCP_*
Many constants of these forms, documented in the Unix documentation on sockets
and/or the IP protocol, are also defined in the socket module. They are
generally used in arguments to the :meth:`setsockopt` and :meth:`getsockopt`
methods of socket objects. In most cases, only those symbols that are defined
in the Unix header files are defined; for a few symbols, default values are
provided.
.. data:: SIO_*
RCVALL_*
Constants for Windows' WSAIoctl(). The constants are used as arguments to the
:meth:`~socket.socket.ioctl` method of socket objects.
.. versionadded:: 2.6
.. data:: TIPC_*
TIPC related constants, matching the ones exported by the C socket API. See
the TIPC documentation for more information.
.. versionadded:: 2.6
.. data:: has_ipv6
This constant contains a boolean value which indicates if IPv6 is supported on
this platform.
.. versionadded:: 2.3
.. function:: create_connection(address[, timeout[, source_address]])
Connect to a TCP service listening on the Internet *address* (a 2-tuple
``(host, port)``), and return the socket object. This is a higher-level
function than :meth:`socket.connect`: if *host* is a non-numeric hostname,
it will try to resolve it for both :data:`AF_INET` and :data:`AF_INET6`,
and then try to connect to all possible addresses in turn until a
connection succeeds. This makes it easy to write clients that are
compatible to both IPv4 and IPv6.
Passing the optional *timeout* parameter will set the timeout on the
socket instance before attempting to connect. If no *timeout* is
supplied, the global default timeout setting returned by
:func:`getdefaulttimeout` is used.
If supplied, *source_address* must be a 2-tuple ``(host, port)`` for the
socket to bind to as its source address before connecting. If host or port
are '' or 0 respectively the OS default behavior will be used.
.. versionadded:: 2.6
.. versionchanged:: 2.7
*source_address* was added.
.. function:: getaddrinfo(host, port[, family[, socktype[, proto[, flags]]]])
Translate the *host*/*port* argument into a sequence of 5-tuples that contain
all the necessary arguments for creating a socket connected to that service.
*host* is a domain name, a string representation of an IPv4/v6 address
or ``None``. *port* is a string service name such as ``'http'``, a numeric
port number or ``None``. By passing ``None`` as the value of *host*
and *port*, you can pass ``NULL`` to the underlying C API.
The *family*, *socktype* and *proto* arguments can be optionally specified
in order to narrow the list of addresses returned. By default, their value
is ``0``, meaning that the full range of results is selected.
The *flags* argument can be one or several of the ``AI_*`` constants,
and will influence how results are computed and returned. Its default value
is ``0``. For example, :const:`AI_NUMERICHOST` will disable domain name
resolution and will raise an error if *host* is a domain name.
The function returns a list of 5-tuples with the following structure:
``(family, socktype, proto, canonname, sockaddr)``
In these tuples, *family*, *socktype*, *proto* are all integers and are
meant to be passed to the :func:`.socket` function. *canonname* will be
a string representing the canonical name of the *host* if
:const:`AI_CANONNAME` is part of the *flags* argument; else *canonname*
will be empty. *sockaddr* is a tuple describing a socket address, whose
format depends on the returned *family* (a ``(address, port)`` 2-tuple for
:const:`AF_INET`, a ``(address, port, flow info, scope id)`` 4-tuple for
:const:`AF_INET6`), and is meant to be passed to the :meth:`socket.connect`
method.
The following example fetches address information for a hypothetical TCP
connection to ``example.org`` on port 80 (results may differ on your
system if IPv6 isn't enabled)::
>>> socket.getaddrinfo("example.org", 80, 0, 0, socket.IPPROTO_TCP)
[(10, 1, 6, '', ('2606:2800:220:1:248:1893:25c8:1946', 80, 0, 0)),
(2, 1, 6, '', ('93.184.216.34', 80))]
.. versionadded:: 2.2
.. function:: getfqdn([name])
Return a fully qualified domain name for *name*. If *name* is omitted or empty,
it is interpreted as the local host. To find the fully qualified name, the
hostname returned by :func:`gethostbyaddr` is checked, followed by aliases for the
host, if available. The first name which includes a period is selected. In
case no fully qualified domain name is available, the hostname as returned by
:func:`gethostname` is returned.
.. versionadded:: 2.0
.. function:: gethostbyname(hostname)
Translate a host name to IPv4 address format. The IPv4 address is returned as a
string, such as ``'100.50.200.5'``. If the host name is an IPv4 address itself
it is returned unchanged. See :func:`gethostbyname_ex` for a more complete
interface. :func:`gethostbyname` does not support IPv6 name resolution, and
:func:`getaddrinfo` should be used instead for IPv4/v6 dual stack support.
.. function:: gethostbyname_ex(hostname)
Translate a host name to IPv4 address format, extended interface. Return a
triple ``(hostname, aliaslist, ipaddrlist)`` where *hostname* is the primary
host name responding to the given *ip_address*, *aliaslist* is a (possibly
empty) list of alternative host names for the same address, and *ipaddrlist* is
a list of IPv4 addresses for the same interface on the same host (often but not
always a single address). :func:`gethostbyname_ex` does not support IPv6 name
resolution, and :func:`getaddrinfo` should be used instead for IPv4/v6 dual
stack support.
.. function:: gethostname()
Return a string containing the hostname of the machine where the Python
interpreter is currently executing.
If you want to know the current machine's IP address, you may want to use
``gethostbyname(gethostname())``. This operation assumes that there is a
valid address-to-host mapping for the host, and the assumption does not
always hold.
Note: :func:`gethostname` doesn't always return the fully qualified domain
name; use ``getfqdn()`` (see above).
.. function:: gethostbyaddr(ip_address)
Return a triple ``(hostname, aliaslist, ipaddrlist)`` where *hostname* is the
primary host name responding to the given *ip_address*, *aliaslist* is a
(possibly empty) list of alternative host names for the same address, and
*ipaddrlist* is a list of IPv4/v6 addresses for the same interface on the same
host (most likely containing only a single address). To find the fully qualified
domain name, use the function :func:`getfqdn`. :func:`gethostbyaddr` supports
both IPv4 and IPv6.
.. function:: getnameinfo(sockaddr, flags)
Translate a socket address *sockaddr* into a 2-tuple ``(host, port)``. Depending
on the settings of *flags*, the result can contain a fully-qualified domain name
or numeric address representation in *host*. Similarly, *port* can contain a
string port name or a numeric port number.
.. versionadded:: 2.2
.. function:: getprotobyname(protocolname)
Translate an Internet protocol name (for example, ``'icmp'``) to a constant
suitable for passing as the (optional) third argument to the :func:`.socket`
function. This is usually only needed for sockets opened in "raw" mode
(:const:`SOCK_RAW`); for the normal socket modes, the correct protocol is chosen
automatically if the protocol is omitted or zero.
.. function:: getservbyname(servicename[, protocolname])
Translate an Internet service name and protocol name to a port number for that
service. The optional protocol name, if given, should be ``'tcp'`` or
``'udp'``, otherwise any protocol will match.
.. function:: getservbyport(port[, protocolname])
Translate an Internet port number and protocol name to a service name for that
service. The optional protocol name, if given, should be ``'tcp'`` or
``'udp'``, otherwise any protocol will match.
.. function:: socket([family[, type[, proto]]])
Create a new socket using the given address family, socket type and protocol
number. The address family should be :const:`AF_INET` (the default),
:const:`AF_INET6` or :const:`AF_UNIX`. The socket type should be
:const:`SOCK_STREAM` (the default), :const:`SOCK_DGRAM` or perhaps one of the
other ``SOCK_`` constants. The protocol number is usually zero and may be
omitted in that case.
.. function:: socketpair([family[, type[, proto]]])
Build a pair of connected socket objects using the given address family, socket
type, and protocol number. Address family, socket type, and protocol number are
as for the :func:`.socket` function above. The default family is :const:`AF_UNIX`
if defined on the platform; otherwise, the default is :const:`AF_INET`.
Availability: Unix.
.. versionadded:: 2.4
.. function:: fromfd(fd, family, type[, proto])
Duplicate the file descriptor *fd* (an integer as returned by a file object's
:meth:`fileno` method) and build a socket object from the result. Address
family, socket type and protocol number are as for the :func:`.socket` function
above. The file descriptor should refer to a socket, but this is not checked ---
subsequent operations on the object may fail if the file descriptor is invalid.
This function is rarely needed, but can be used to get or set socket options on
a socket passed to a program as standard input or output (such as a server
started by the Unix inet daemon). The socket is assumed to be in blocking mode.
Availability: Unix.
.. function:: ntohl(x)
Convert 32-bit positive integers from network to host byte order. On machines
where the host byte order is the same as network byte order, this is a no-op;
otherwise, it performs a 4-byte swap operation.
.. function:: ntohs(x)
Convert 16-bit positive integers from network to host byte order. On machines
where the host byte order is the same as network byte order, this is a no-op;
otherwise, it performs a 2-byte swap operation.
.. function:: htonl(x)
Convert 32-bit positive integers from host to network byte order. On machines
where the host byte order is the same as network byte order, this is a no-op;
otherwise, it performs a 4-byte swap operation.
.. function:: htons(x)
Convert 16-bit positive integers from host to network byte order. On machines
where the host byte order is the same as network byte order, this is a no-op;
otherwise, it performs a 2-byte swap operation.
.. function:: inet_aton(ip_string)
Convert an IPv4 address from dotted-quad string format (for example,
'123.45.67.89') to 32-bit packed binary format, as a string four characters in
length. This is useful when conversing with a program that uses the standard C
library and needs objects of type :c:type:`struct in_addr`, which is the C type
for the 32-bit packed binary this function returns.
:func:`inet_aton` also accepts strings with less than three dots; see the
Unix manual page :manpage:`inet(3)` for details.
If the IPv4 address string passed to this function is invalid,
:exc:`socket.error` will be raised. Note that exactly what is valid depends on
the underlying C implementation of :c:func:`inet_aton`.
:func:`inet_aton` does not support IPv6, and :func:`inet_pton` should be used
instead for IPv4/v6 dual stack support.
.. function:: inet_ntoa(packed_ip)
Convert a 32-bit packed IPv4 address (a string four characters in length) to its
standard dotted-quad string representation (for example, '123.45.67.89'). This
is useful when conversing with a program that uses the standard C library and
needs objects of type :c:type:`struct in_addr`, which is the C type for the
32-bit packed binary data this function takes as an argument.
If the string passed to this function is not exactly 4 bytes in length,
:exc:`socket.error` will be raised. :func:`inet_ntoa` does not support IPv6, and
:func:`inet_ntop` should be used instead for IPv4/v6 dual stack support.
.. function:: inet_pton(address_family, ip_string)
Convert an IP address from its family-specific string format to a packed, binary
format. :func:`inet_pton` is useful when a library or network protocol calls for
an object of type :c:type:`struct in_addr` (similar to :func:`inet_aton`) or
:c:type:`struct in6_addr`.
Supported values for *address_family* are currently :const:`AF_INET` and
:const:`AF_INET6`. If the IP address string *ip_string* is invalid,
:exc:`socket.error` will be raised. Note that exactly what is valid depends on
both the value of *address_family* and the underlying implementation of
:c:func:`inet_pton`.
Availability: Unix (maybe not all platforms).
.. versionadded:: 2.3
.. function:: inet_ntop(address_family, packed_ip)
Convert a packed IP address (a string of some number of characters) to its
standard, family-specific string representation (for example, ``'7.10.0.5'`` or
``'5aef:2b::8'``) :func:`inet_ntop` is useful when a library or network protocol
returns an object of type :c:type:`struct in_addr` (similar to :func:`inet_ntoa`)
or :c:type:`struct in6_addr`.
Supported values for *address_family* are currently :const:`AF_INET` and
:const:`AF_INET6`. If the string *packed_ip* is not the correct length for the
specified address family, :exc:`ValueError` will be raised. A
:exc:`socket.error` is raised for errors from the call to :func:`inet_ntop`.
Availability: Unix (maybe not all platforms).
.. versionadded:: 2.3
.. function:: getdefaulttimeout()
Return the default timeout in seconds (float) for new socket objects. A value
of ``None`` indicates that new socket objects have no timeout. When the socket
module is first imported, the default is ``None``.
.. versionadded:: 2.3
.. function:: setdefaulttimeout(timeout)
Set the default timeout in seconds (float) for new socket objects. A value of
``None`` indicates that new socket objects have no timeout. When the socket
module is first imported, the default is ``None``.
.. versionadded:: 2.3
.. data:: SocketType
This is a Python type object that represents the socket object type. It is the
same as ``type(socket(...))``.
.. seealso::
Module :mod:`SocketServer`
Classes that simplify writing network servers.
Module :mod:`ssl`
A TLS/SSL wrapper for socket objects.
.. _socket-objects:
Socket Objects
--------------
Socket objects have the following methods. Except for :meth:`makefile` these
correspond to Unix system calls applicable to sockets.
.. method:: socket.accept()
Accept a connection. The socket must be bound to an address and listening for
connections. The return value is a pair ``(conn, address)`` where *conn* is a
*new* socket object usable to send and receive data on the connection, and
*address* is the address bound to the socket on the other end of the connection.
.. method:: socket.bind(address)
Bind the socket to *address*. The socket must not already be bound. (The format
of *address* depends on the address family --- see above.)
.. note::
This method has historically accepted a pair of parameters for :const:`AF_INET`
addresses instead of only a tuple. This was never intentional and is no longer
available in Python 2.0 and later.
.. method:: socket.close()
Close the socket. All future operations on the socket object will fail. The
remote end will receive no more data (after queued data is flushed). Sockets are
automatically closed when they are garbage-collected.
.. note::
:meth:`close()` releases the resource associated with a connection but
does not necessarily close the connection immediately. If you want
to close the connection in a timely fashion, call :meth:`shutdown()`
before :meth:`close()`.
.. method:: socket.connect(address)
Connect to a remote socket at *address*. (The format of *address* depends on the
address family --- see above.)
.. note::
This method has historically accepted a pair of parameters for :const:`AF_INET`
addresses instead of only a tuple. This was never intentional and is no longer
available in Python 2.0 and later.
.. method:: socket.connect_ex(address)
Like ``connect(address)``, but return an error indicator instead of raising an
exception for errors returned by the C-level :c:func:`connect` call (other
problems, such as "host not found," can still raise exceptions). The error
indicator is ``0`` if the operation succeeded, otherwise the value of the
:c:data:`errno` variable. This is useful to support, for example, asynchronous
connects.
.. note::
This method has historically accepted a pair of parameters for :const:`AF_INET`
addresses instead of only a tuple. This was never intentional and is no longer
available in Python 2.0 and later.
.. method:: socket.fileno()
Return the socket's file descriptor (a small integer). This is useful with
:func:`select.select`.
Under Windows the small integer returned by this method cannot be used where a
file descriptor can be used (such as :func:`os.fdopen`). Unix does not have
this limitation.
.. method:: socket.getpeername()
Return the remote address to which the socket is connected. This is useful to
find out the port number of a remote IPv4/v6 socket, for instance. (The format
of the address returned depends on the address family --- see above.) On some
systems this function is not supported.
.. method:: socket.getsockname()
Return the socket's own address. This is useful to find out the port number of
an IPv4/v6 socket, for instance. (The format of the address returned depends on
the address family --- see above.)
.. method:: socket.getsockopt(level, optname[, buflen])
Return the value of the given socket option (see the Unix man page
:manpage:`getsockopt(2)`). The needed symbolic constants (:const:`SO_\*` etc.)
are defined in this module. If *buflen* is absent, an integer option is assumed
and its integer value is returned by the function. If *buflen* is present, it
specifies the maximum length of the buffer used to receive the option in, and
this buffer is returned as a string. It is up to the caller to decode the
contents of the buffer (see the optional built-in module :mod:`struct` for a way
to decode C structures encoded as strings).
.. method:: socket.ioctl(control, option)
:platform: Windows
The :meth:`ioctl` method is a limited interface to the WSAIoctl system
interface. Please refer to the `Win32 documentation
<https://msdn.microsoft.com/en-us/library/ms741621%28VS.85%29.aspx>`_ for more
information.
On other platforms, the generic :func:`fcntl.fcntl` and :func:`fcntl.ioctl`
functions may be used; they accept a socket object as their first argument.
.. versionadded:: 2.6
.. method:: socket.listen(backlog)
Listen for connections made to the socket. The *backlog* argument specifies the
maximum number of queued connections and should be at least 0; the maximum value
is system-dependent (usually 5), the minimum value is forced to 0.
.. method:: socket.makefile([mode[, bufsize]])
.. index:: single: I/O control; buffering
Return a :dfn:`file object` associated with the socket. (File objects are
described in :ref:`bltin-file-objects`.) The file object does not close the
socket explicitly when its :meth:`close` method is called, but only removes
its reference to the socket object, so that the socket will be closed if it
is not referenced from anywhere else.
The socket must be in blocking mode (it can not have a timeout). The optional
*mode* and *bufsize* arguments are interpreted the same way as by the built-in
:func:`file` function.
.. note::
On Windows, the file-like object created by :meth:`makefile` cannot be
used where a file object with a file descriptor is expected, such as the
stream arguments of :meth:`subprocess.Popen`.
.. method:: socket.recv(bufsize[, flags])
Receive data from the socket. The return value is a string representing the
data received. The maximum amount of data to be received at once is specified
by *bufsize*. See the Unix manual page :manpage:`recv(2)` for the meaning of
the optional argument *flags*; it defaults to zero.
.. note::
For best match with hardware and network realities, the value of *bufsize*
should be a relatively small power of 2, for example, 4096.
.. method:: socket.recvfrom(bufsize[, flags])
Receive data from the socket. The return value is a pair ``(string, address)``
where *string* is a string representing the data received and *address* is the
address of the socket sending the data. See the Unix manual page
:manpage:`recv(2)` for the meaning of the optional argument *flags*; it defaults
to zero. (The format of *address* depends on the address family --- see above.)
.. method:: socket.recvfrom_into(buffer[, nbytes[, flags]])
Receive data from the socket, writing it into *buffer* instead of creating a
new string. The return value is a pair ``(nbytes, address)`` where *nbytes* is
the number of bytes received and *address* is the address of the socket sending
the data. See the Unix manual page :manpage:`recv(2)` for the meaning of the
optional argument *flags*; it defaults to zero. (The format of *address*
depends on the address family --- see above.)
.. versionadded:: 2.5
.. method:: socket.recv_into(buffer[, nbytes[, flags]])
Receive up to *nbytes* bytes from the socket, storing the data into a buffer
rather than creating a new string. If *nbytes* is not specified (or 0),
receive up to the size available in the given buffer. Returns the number of
bytes received. See the Unix manual page :manpage:`recv(2)` for the meaning
of the optional argument *flags*; it defaults to zero.
.. versionadded:: 2.5
.. method:: socket.send(string[, flags])
Send data to the socket. The socket must be connected to a remote socket. The
optional *flags* argument has the same meaning as for :meth:`recv` above.
Returns the number of bytes sent. Applications are responsible for checking that
all data has been sent; if only some of the data was transmitted, the
application needs to attempt delivery of the remaining data. For further
information on this concept, consult the :ref:`socket-howto`.
.. method:: socket.sendall(string[, flags])
Send data to the socket. The socket must be connected to a remote socket. The
optional *flags* argument has the same meaning as for :meth:`recv` above.
Unlike :meth:`send`, this method continues to send data from *string* until
either all data has been sent or an error occurs. ``None`` is returned on
success. On error, an exception is raised, and there is no way to determine how
much data, if any, was successfully sent.
.. method:: socket.sendto(string, address)
socket.sendto(string, flags, address)
Send data to the socket. The socket should not be connected to a remote socket,
since the destination socket is specified by *address*. The optional *flags*
argument has the same meaning as for :meth:`recv` above. Return the number of
bytes sent. (The format of *address* depends on the address family --- see
above.)
.. method:: socket.setblocking(flag)
Set blocking or non-blocking mode of the socket: if *flag* is 0, the socket is
set to non-blocking, else to blocking mode. Initially all sockets are in
blocking mode. In non-blocking mode, if a :meth:`recv` call doesn't find any
data, or if a :meth:`send` call can't immediately dispose of the data, an
:exc:`error` exception is raised; in blocking mode, the calls block until they
can proceed. ``s.setblocking(0)`` is equivalent to ``s.settimeout(0.0)``;
``s.setblocking(1)`` is equivalent to ``s.settimeout(None)``.
.. method:: socket.settimeout(value)
Set a timeout on blocking socket operations. The *value* argument can be a
nonnegative float expressing seconds, or ``None``. If a float is given,
subsequent socket operations will raise a :exc:`timeout` exception if the
timeout period *value* has elapsed before the operation has completed. Setting
a timeout of ``None`` disables timeouts on socket operations.
``s.settimeout(0.0)`` is equivalent to ``s.setblocking(0)``;
``s.settimeout(None)`` is equivalent to ``s.setblocking(1)``.
.. versionadded:: 2.3
.. method:: socket.gettimeout()
Return the timeout in seconds (float) associated with socket operations, or
``None`` if no timeout is set. This reflects the last call to
:meth:`setblocking` or :meth:`settimeout`.
.. versionadded:: 2.3
Some notes on socket blocking and timeouts: A socket object can be in one of
three modes: blocking, non-blocking, or timeout. Sockets are always created in
blocking mode. In blocking mode, operations block until complete or
the system returns an error (such as connection timed out). In
non-blocking mode, operations fail (with an error that is unfortunately
system-dependent) if they cannot be completed immediately. In timeout mode,
operations fail if they cannot be completed within the timeout specified for the
socket or if the system returns an error. The :meth:`~socket.setblocking`
method is simply a shorthand for certain :meth:`~socket.settimeout` calls.
Timeout mode internally sets the socket in non-blocking mode. The blocking and
timeout modes are shared between file descriptors and socket objects that refer
to the same network endpoint. A consequence of this is that file objects
returned by the :meth:`~socket.makefile` method must only be used when the
socket is in blocking mode; in timeout or non-blocking mode file operations
that cannot be completed immediately will fail.
Note that the :meth:`~socket.connect` operation is subject to the timeout
setting, and in general it is recommended to call :meth:`~socket.settimeout`
before calling :meth:`~socket.connect` or pass a timeout parameter to
:meth:`create_connection`. The system network stack may return a connection
timeout error of its own regardless of any Python socket timeout setting.
.. method:: socket.setsockopt(level, optname, value)
.. index:: module: struct
Set the value of the given socket option (see the Unix manual page
:manpage:`setsockopt(2)`). The needed symbolic constants are defined in the
:mod:`socket` module (:const:`SO_\*` etc.). The value can be an integer or a
string representing a buffer. In the latter case it is up to the caller to
ensure that the string contains the proper bits (see the optional built-in
module :mod:`struct` for a way to encode C structures as strings).
.. method:: socket.shutdown(how)
Shut down one or both halves of the connection. If *how* is :const:`SHUT_RD`,
further receives are disallowed. If *how* is :const:`SHUT_WR`, further sends
are disallowed. If *how* is :const:`SHUT_RDWR`, further sends and receives are
disallowed. Depending on the platform, shutting down one half of the connection
can also close the opposite half (e.g. on Mac OS X, ``shutdown(SHUT_WR)`` does
not allow further reads on the other end of the connection).
Note that there are no methods :meth:`read` or :meth:`write`; use
:meth:`~socket.recv` and :meth:`~socket.send` without *flags* argument instead.
Socket objects also have these (read-only) attributes that correspond to the
values given to the :class:`~socket.socket` constructor.
.. attribute:: socket.family
The socket family.
.. versionadded:: 2.5
.. attribute:: socket.type
The socket type.
.. versionadded:: 2.5
.. attribute:: socket.proto
The socket protocol.
.. versionadded:: 2.5
.. _socket-example:
Example
-------
Here are four minimal example programs using the TCP/IP protocol: a server that
echoes all data that it receives back (servicing only one client), and a client
using it. Note that a server must perform the sequence :func:`.socket`,
:meth:`~socket.bind`, :meth:`~socket.listen`, :meth:`~socket.accept` (possibly
repeating the :meth:`~socket.accept` to service more than one client), while a
client only needs the sequence :func:`.socket`, :meth:`~socket.connect`. Also
note that the server does not :meth:`~socket.sendall`/:meth:`~socket.recv` on
the socket it is listening on but on the new socket returned by
:meth:`~socket.accept`.
The first two examples support IPv4 only. ::
# Echo server program
import socket
HOST = '' # Symbolic name meaning all available interfaces
PORT = 50007 # Arbitrary non-privileged port
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
s.bind((HOST, PORT))
s.listen(1)
conn, addr = s.accept()
print 'Connected by', addr
while 1:
data = conn.recv(1024)
if not data: break
conn.sendall(data)
conn.close()
::
# Echo client program
import socket
HOST = 'daring.cwi.nl' # The remote host
PORT = 50007 # The same port as used by the server
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
s.connect((HOST, PORT))
s.sendall('Hello, world')
data = s.recv(1024)
s.close()
print 'Received', repr(data)
The next two examples are identical to the above two, but support both IPv4 and
IPv6. The server side will listen to the first address family available (it
should listen to both instead). On most of IPv6-ready systems, IPv6 will take
precedence and the server may not accept IPv4 traffic. The client side will try
to connect to the all addresses returned as a result of the name resolution, and
sends traffic to the first one connected successfully. ::
# Echo server program
import socket
import sys
HOST = None # Symbolic name meaning all available interfaces
PORT = 50007 # Arbitrary non-privileged port
s = None
for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC,
socket.SOCK_STREAM, 0, socket.AI_PASSIVE):
af, socktype, proto, canonname, sa = res
try:
s = socket.socket(af, socktype, proto)
except socket.error as msg:
s = None
continue
try:
s.bind(sa)
s.listen(1)
except socket.error as msg:
s.close()
s = None
continue
break
if s is None:
print 'could not open socket'
sys.exit(1)
conn, addr = s.accept()
print 'Connected by', addr
while 1:
data = conn.recv(1024)
if not data: break
conn.send(data)
conn.close()
::
# Echo client program
import socket
import sys
HOST = 'daring.cwi.nl' # The remote host
PORT = 50007 # The same port as used by the server
s = None
for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM):
af, socktype, proto, canonname, sa = res
try:
s = socket.socket(af, socktype, proto)
except socket.error as msg:
s = None
continue
try:
s.connect(sa)
except socket.error as msg:
s.close()
s = None
continue
break
if s is None:
print 'could not open socket'
sys.exit(1)
s.sendall('Hello, world')
data = s.recv(1024)
s.close()
print 'Received', repr(data)
The last example shows how to write a very simple network sniffer with raw
sockets on Windows. The example requires administrator privileges to modify
the interface::
import socket
# the public network interface
HOST = socket.gethostbyname(socket.gethostname())
# create a raw socket and bind it to the public interface
s = socket.socket(socket.AF_INET, socket.SOCK_RAW, socket.IPPROTO_IP)
s.bind((HOST, 0))
# Include IP headers
s.setsockopt(socket.IPPROTO_IP, socket.IP_HDRINCL, 1)
# receive all packages
s.ioctl(socket.SIO_RCVALL, socket.RCVALL_ON)
# receive a package
print s.recvfrom(65565)
# disabled promiscuous mode
s.ioctl(socket.SIO_RCVALL, socket.RCVALL_OFF)
Running an example several times with too small delay between executions, could
lead to this error::
socket.error: [Errno 98] Address already in use
This is because the previous execution has left the socket in a ``TIME_WAIT``
state, and can't be immediately reused.
There is a :mod:`socket` flag to set, in order to prevent this,
:data:`socket.SO_REUSEADDR`::
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
s.bind((HOST, PORT))
the :data:`SO_REUSEADDR` flag tells the kernel to reuse a local socket in
``TIME_WAIT`` state, without waiting for its natural timeout to expire.
PK
%�\�=�W �W * html/_sources/library/socketserver.rst.txtnu �[��� :mod:`SocketServer` --- A framework for network servers
=======================================================
.. module:: SocketServer
:synopsis: A framework for network servers.
.. note::
The :mod:`SocketServer` module has been renamed to :mod:`socketserver` in
Python 3. The :term:`2to3` tool will automatically adapt imports when
converting your sources to Python 3.
**Source code:** :source:`Lib/SocketServer.py`
--------------
The :mod:`SocketServer` module simplifies the task of writing network servers.
There are four basic concrete server classes:
.. class:: TCPServer(server_address, RequestHandlerClass, bind_and_activate=True)
This uses the Internet TCP protocol, which provides for
continuous streams of data between the client and server.
If *bind_and_activate* is true, the constructor automatically attempts to
invoke :meth:`~BaseServer.server_bind` and
:meth:`~BaseServer.server_activate`. The other parameters are passed to
the :class:`BaseServer` base class.
.. class:: UDPServer(server_address, RequestHandlerClass, bind_and_activate=True)
This uses datagrams, which are discrete packets of information that may
arrive out of order or be lost while in transit. The parameters are
the same as for :class:`TCPServer`.
.. class:: UnixStreamServer(server_address, RequestHandlerClass, bind_and_activate=True)
UnixDatagramServer(server_address, RequestHandlerClass, bind_and_activate=True)
These more infrequently used classes are similar to the TCP and
UDP classes, but use Unix domain sockets; they're not available on
non-Unix platforms. The parameters are the same as for
:class:`TCPServer`.
These four classes process requests :dfn:`synchronously`; each request must be
completed before the next request can be started. This isn't suitable if each
request takes a long time to complete, because it requires a lot of computation,
or because it returns a lot of data which the client is slow to process. The
solution is to create a separate process or thread to handle each request; the
:class:`ForkingMixIn` and :class:`ThreadingMixIn` mix-in classes can be used to
support asynchronous behaviour.
Creating a server requires several steps. First, you must create a request
handler class by subclassing the :class:`BaseRequestHandler` class and
overriding its :meth:`~BaseRequestHandler.handle` method;
this method will process incoming
requests. Second, you must instantiate one of the server classes, passing it
the server's address and the request handler class. Then call the
:meth:`~BaseServer.handle_request` or
:meth:`~BaseServer.serve_forever` method of the server object to
process one or many requests. Finally, call :meth:`~BaseServer.server_close`
to close the socket.
When inheriting from :class:`ThreadingMixIn` for threaded connection behavior,
you should explicitly declare how you want your threads to behave on an abrupt
shutdown. The :class:`ThreadingMixIn` class defines an attribute
*daemon_threads*, which indicates whether or not the server should wait for
thread termination. You should set the flag explicitly if you would like threads
to behave autonomously; the default is :const:`False`, meaning that Python will
not exit until all threads created by :class:`ThreadingMixIn` have exited.
Server classes have the same external methods and attributes, no matter what
network protocol they use.
Server Creation Notes
---------------------
There are five classes in an inheritance diagram, four of which represent
synchronous servers of four types::
+------------+
| BaseServer |
+------------+
|
v
+-----------+ +------------------+
| TCPServer |------->| UnixStreamServer |
+-----------+ +------------------+
|
v
+-----------+ +--------------------+
| UDPServer |------->| UnixDatagramServer |
+-----------+ +--------------------+
Note that :class:`UnixDatagramServer` derives from :class:`UDPServer`, not from
:class:`UnixStreamServer` --- the only difference between an IP and a Unix
stream server is the address family, which is simply repeated in both Unix
server classes.
.. class:: ForkingMixIn
ThreadingMixIn
Forking and threading versions of each type of server can be created
using these mix-in classes. For instance, :class:`ThreadingUDPServer`
is created as follows::
class ThreadingUDPServer(ThreadingMixIn, UDPServer):
pass
The mix-in class comes first, since it overrides a method defined in
:class:`UDPServer`. Setting the various attributes also changes the
behavior of the underlying server mechanism.
:class:`ForkingMixIn` and the Forking classes mentioned below are
only available on POSIX platforms that support :func:`~os.fork`.
.. class:: ForkingTCPServer
ForkingUDPServer
ThreadingTCPServer
ThreadingUDPServer
These classes are pre-defined using the mix-in classes.
To implement a service, you must derive a class from :class:`BaseRequestHandler`
and redefine its :meth:`~BaseRequestHandler.handle` method.
You can then run various versions of
the service by combining one of the server classes with your request handler
class. The request handler class must be different for datagram or stream
services. This can be hidden by using the handler subclasses
:class:`StreamRequestHandler` or :class:`DatagramRequestHandler`.
Of course, you still have to use your head! For instance, it makes no sense to
use a forking server if the service contains state in memory that can be
modified by different requests, since the modifications in the child process
would never reach the initial state kept in the parent process and passed to
each child. In this case, you can use a threading server, but you will probably
have to use locks to protect the integrity of the shared data.
On the other hand, if you are building an HTTP server where all data is stored
externally (for instance, in the file system), a synchronous class will
essentially render the service "deaf" while one request is being handled --
which may be for a very long time if a client is slow to receive all the data it
has requested. Here a threading or forking server is appropriate.
In some cases, it may be appropriate to process part of a request synchronously,
but to finish processing in a forked child depending on the request data. This
can be implemented by using a synchronous server and doing an explicit fork in
the request handler class :meth:`~BaseRequestHandler.handle` method.
Another approach to handling multiple simultaneous requests in an environment
that supports neither threads nor :func:`~os.fork` (or where these are too
expensive or inappropriate for the service) is to maintain an explicit table of
partially finished requests and to use :func:`~select.select` to decide which
request to work on next (or whether to handle a new incoming request). This is
particularly important for stream services where each client can potentially be
connected for a long time (if threads or subprocesses cannot be used). See
:mod:`asyncore` for another way to manage this.
.. XXX should data and methods be intermingled, or separate?
how should the distinction between class and instance variables be drawn?
Server Objects
--------------
.. class:: BaseServer(server_address, RequestHandlerClass)
This is the superclass of all Server objects in the module. It defines the
interface, given below, but does not implement most of the methods, which is
done in subclasses. The two parameters are stored in the respective
:attr:`server_address` and :attr:`RequestHandlerClass` attributes.
.. method:: fileno()
Return an integer file descriptor for the socket on which the server is
listening. This function is most commonly passed to :func:`select.select`, to
allow monitoring multiple servers in the same process.
.. method:: handle_request()
Process a single request. This function calls the following methods in
order: :meth:`get_request`, :meth:`verify_request`, and
:meth:`process_request`. If the user-provided
:meth:`~BaseRequestHandler.handle` method of the
handler class raises an exception, the server's :meth:`handle_error` method
will be called. If no request is received within :attr:`timeout`
seconds, :meth:`handle_timeout` will be called and :meth:`handle_request`
will return.
.. method:: serve_forever(poll_interval=0.5)
Handle requests until an explicit :meth:`shutdown` request. Poll for
shutdown every *poll_interval* seconds.
Ignores the :attr:`timeout` attribute.
If you need to do periodic tasks, do them in another thread.
.. method:: shutdown()
Tell the :meth:`serve_forever` loop to stop and wait until it does.
.. versionadded:: 2.6
.. method:: server_close()
Clean up the server. May be overridden.
.. versionadded:: 2.6
.. attribute:: address_family
The family of protocols to which the server's socket belongs.
Common examples are :const:`socket.AF_INET` and :const:`socket.AF_UNIX`.
.. attribute:: RequestHandlerClass
The user-provided request handler class; an instance of this class is created
for each request.
.. attribute:: server_address
The address on which the server is listening. The format of addresses varies
depending on the protocol family;
see the documentation for the :mod:`socket` module
for details. For Internet protocols, this is a tuple containing a string giving
the address, and an integer port number: ``('127.0.0.1', 80)``, for example.
.. attribute:: socket
The socket object on which the server will listen for incoming requests.
The server classes support the following class variables:
.. XXX should class variables be covered before instance variables, or vice versa?
.. attribute:: allow_reuse_address
Whether the server will allow the reuse of an address. This defaults to
:const:`False`, and can be set in subclasses to change the policy.
.. attribute:: request_queue_size
The size of the request queue. If it takes a long time to process a single
request, any requests that arrive while the server is busy are placed into a
queue, up to :attr:`request_queue_size` requests. Once the queue is full,
further requests from clients will get a "Connection denied" error. The default
value is usually 5, but this can be overridden by subclasses.
.. attribute:: socket_type
The type of socket used by the server; :const:`socket.SOCK_STREAM` and
:const:`socket.SOCK_DGRAM` are two common values.
.. attribute:: timeout
Timeout duration, measured in seconds, or :const:`None` if no timeout is
desired. If :meth:`handle_request` receives no incoming requests within the
timeout period, the :meth:`handle_timeout` method is called.
There are various server methods that can be overridden by subclasses of base
server classes like :class:`TCPServer`; these methods aren't useful to external
users of the server object.
.. XXX should the default implementations of these be documented, or should
it be assumed that the user will look at SocketServer.py?
.. method:: finish_request(request, client_address)
Actually processes the request by instantiating :attr:`RequestHandlerClass` and
calling its :meth:`~BaseRequestHandler.handle` method.
.. method:: get_request()
Must accept a request from the socket, and return a 2-tuple containing the *new*
socket object to be used to communicate with the client, and the client's
address.
.. method:: handle_error(request, client_address)
This function is called if the :meth:`~BaseRequestHandler.handle`
method of a :attr:`RequestHandlerClass` instance raises
an exception. The default action is to print the traceback to
standard output and continue handling further requests.
.. method:: handle_timeout()
This function is called when the :attr:`timeout` attribute has been set to a
value other than :const:`None` and the timeout period has passed with no
requests being received. The default action for forking servers is
to collect the status of any child processes that have exited, while
in threading servers this method does nothing.
.. method:: process_request(request, client_address)
Calls :meth:`finish_request` to create an instance of the
:attr:`RequestHandlerClass`. If desired, this function can create a new process
or thread to handle the request; the :class:`ForkingMixIn` and
:class:`ThreadingMixIn` classes do this.
.. Is there any point in documenting the following two functions?
What would the purpose of overriding them be: initializing server
instance variables, adding new network families?
.. method:: server_activate()
Called by the server's constructor to activate the server. The default behavior
for a TCP server just invokes :meth:`~socket.socket.listen`
on the server's socket. May be overridden.
.. method:: server_bind()
Called by the server's constructor to bind the socket to the desired address.
May be overridden.
.. method:: verify_request(request, client_address)
Must return a Boolean value; if the value is :const:`True`, the request will be
processed, and if it's :const:`False`, the request will be denied. This function
can be overridden to implement access controls for a server. The default
implementation always returns :const:`True`.
Request Handler Objects
-----------------------
.. class:: BaseRequestHandler
This is the superclass of all request handler objects. It defines
the interface, given below. A concrete request handler subclass must
define a new :meth:`handle` method, and can override any of
the other methods. A new instance of the subclass is created for each
request.
.. method:: setup()
Called before the :meth:`handle` method to perform any initialization actions
required. The default implementation does nothing.
.. method:: handle()
This function must do all the work required to service a request. The
default implementation does nothing. Several instance attributes are
available to it; the request is available as :attr:`self.request`; the client
address as :attr:`self.client_address`; and the server instance as
:attr:`self.server`, in case it needs access to per-server information.
The type of :attr:`self.request` is different for datagram or stream
services. For stream services, :attr:`self.request` is a socket object; for
datagram services, :attr:`self.request` is a pair of string and socket.
.. method:: finish()
Called after the :meth:`handle` method to perform any clean-up actions
required. The default implementation does nothing. If :meth:`setup`
raises an exception, this function will not be called.
.. class:: StreamRequestHandler
DatagramRequestHandler
These :class:`BaseRequestHandler` subclasses override the
:meth:`~BaseRequestHandler.setup` and :meth:`~BaseRequestHandler.finish`
methods, and provide :attr:`self.rfile` and :attr:`self.wfile` attributes.
The :attr:`self.rfile` and :attr:`self.wfile` attributes can be
read or written, respectively, to get the request data or return data
to the client.
Examples
--------
:class:`SocketServer.TCPServer` Example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is the server side::
import SocketServer
class MyTCPHandler(SocketServer.BaseRequestHandler):
"""
The request handler class for our server.
It is instantiated once per connection to the server, and must
override the handle() method to implement communication to the
client.
"""
def handle(self):
# self.request is the TCP socket connected to the client
self.data = self.request.recv(1024).strip()
print "{} wrote:".format(self.client_address[0])
print self.data
# just send back the same data, but upper-cased
self.request.sendall(self.data.upper())
if __name__ == "__main__":
HOST, PORT = "localhost", 9999
# Create the server, binding to localhost on port 9999
server = SocketServer.TCPServer((HOST, PORT), MyTCPHandler)
# Activate the server; this will keep running until you
# interrupt the program with Ctrl-C
server.serve_forever()
An alternative request handler class that makes use of streams (file-like
objects that simplify communication by providing the standard file interface)::
class MyTCPHandler(SocketServer.StreamRequestHandler):
def handle(self):
# self.rfile is a file-like object created by the handler;
# we can now use e.g. readline() instead of raw recv() calls
self.data = self.rfile.readline().strip()
print "{} wrote:".format(self.client_address[0])
print self.data
# Likewise, self.wfile is a file-like object used to write back
# to the client
self.wfile.write(self.data.upper())
The difference is that the ``readline()`` call in the second handler will call
``recv()`` multiple times until it encounters a newline character, while the
single ``recv()`` call in the first handler will just return what has been sent
from the client in one ``sendall()`` call.
This is the client side::
import socket
import sys
HOST, PORT = "localhost", 9999
data = " ".join(sys.argv[1:])
# Create a socket (SOCK_STREAM means a TCP socket)
sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
try:
# Connect to server and send data
sock.connect((HOST, PORT))
sock.sendall(data + "\n")
# Receive data from the server and shut down
received = sock.recv(1024)
finally:
sock.close()
print "Sent: {}".format(data)
print "Received: {}".format(received)
The output of the example should look something like this:
Server:
.. code-block:: shell-session
$ python TCPServer.py
127.0.0.1 wrote:
hello world with TCP
127.0.0.1 wrote:
python is nice
Client:
.. code-block:: shell-session
$ python TCPClient.py hello world with TCP
Sent: hello world with TCP
Received: HELLO WORLD WITH TCP
$ python TCPClient.py python is nice
Sent: python is nice
Received: PYTHON IS NICE
:class:`SocketServer.UDPServer` Example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is the server side::
import SocketServer
class MyUDPHandler(SocketServer.BaseRequestHandler):
"""
This class works similar to the TCP handler class, except that
self.request consists of a pair of data and client socket, and since
there is no connection the client address must be given explicitly
when sending data back via sendto().
"""
def handle(self):
data = self.request[0].strip()
socket = self.request[1]
print "{} wrote:".format(self.client_address[0])
print data
socket.sendto(data.upper(), self.client_address)
if __name__ == "__main__":
HOST, PORT = "localhost", 9999
server = SocketServer.UDPServer((HOST, PORT), MyUDPHandler)
server.serve_forever()
This is the client side::
import socket
import sys
HOST, PORT = "localhost", 9999
data = " ".join(sys.argv[1:])
# SOCK_DGRAM is the socket type to use for UDP sockets
sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
# As you can see, there is no connect() call; UDP has no connections.
# Instead, data is directly sent to the recipient via sendto().
sock.sendto(data + "\n", (HOST, PORT))
received = sock.recv(1024)
print "Sent: {}".format(data)
print "Received: {}".format(received)
The output of the example should look exactly like for the TCP server example.
Asynchronous Mixins
~~~~~~~~~~~~~~~~~~~
To build asynchronous handlers, use the :class:`ThreadingMixIn` and
:class:`ForkingMixIn` classes.
An example for the :class:`ThreadingMixIn` class::
import socket
import threading
import SocketServer
class ThreadedTCPRequestHandler(SocketServer.BaseRequestHandler):
def handle(self):
data = self.request.recv(1024)
cur_thread = threading.current_thread()
response = "{}: {}".format(cur_thread.name, data)
self.request.sendall(response)
class ThreadedTCPServer(SocketServer.ThreadingMixIn, SocketServer.TCPServer):
pass
def client(ip, port, message):
sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
sock.connect((ip, port))
try:
sock.sendall(message)
response = sock.recv(1024)
print "Received: {}".format(response)
finally:
sock.close()
if __name__ == "__main__":
# Port 0 means to select an arbitrary unused port
HOST, PORT = "localhost", 0
server = ThreadedTCPServer((HOST, PORT), ThreadedTCPRequestHandler)
ip, port = server.server_address
# Start a thread with the server -- that thread will then start one
# more thread for each request
server_thread = threading.Thread(target=server.serve_forever)
# Exit the server thread when the main thread terminates
server_thread.daemon = True
server_thread.start()
print "Server loop running in thread:", server_thread.name
client(ip, port, "Hello World 1")
client(ip, port, "Hello World 2")
client(ip, port, "Hello World 3")
server.shutdown()
server.server_close()
The output of the example should look something like this:
.. code-block:: shell-session
$ python ThreadedTCPServer.py
Server loop running in thread: Thread-1
Received: Thread-2: Hello World 1
Received: Thread-3: Hello World 2
Received: Thread-4: Hello World 3
The :class:`ForkingMixIn` class is used in the same way, except that the server
will spawn a new process for each request.
Available only on POSIX platforms that support :func:`~os.fork`.
PK
%�\� �\W W $ html/_sources/library/someos.rst.txtnu �[���
.. _someos:
**********************************
Optional Operating System Services
**********************************
The modules described in this chapter provide interfaces to operating system
features that are available on selected operating systems only. The interfaces
are generally modeled after the Unix or C interfaces but they are available on
some other systems as well (e.g. Windows or NT). Here's an overview:
.. toctree::
select.rst
threading.rst
thread.rst
dummy_threading.rst
dummy_thread.rst
multiprocessing.rst
mmap.rst
readline.rst
rlcompleter.rst
PK
%�\
��� " html/_sources/library/spwd.rst.txtnu �[���
:mod:`spwd` --- The shadow password database
============================================
.. module:: spwd
:platform: Unix
:synopsis: The shadow password database (getspnam() and friends).
.. versionadded:: 2.5
This module provides access to the Unix shadow password database. It is
available on various Unix versions.
You must have enough privileges to access the shadow password database (this
usually means you have to be root).
Shadow password database entries are reported as a tuple-like object, whose
attributes correspond to the members of the ``spwd`` structure (Attribute field
below, see ``<shadow.h>``):
+-------+---------------+---------------------------------+
| Index | Attribute | Meaning |
+=======+===============+=================================+
| 0 | ``sp_nam`` | Login name |
+-------+---------------+---------------------------------+
| 1 | ``sp_pwd`` | Encrypted password |
+-------+---------------+---------------------------------+
| 2 | ``sp_lstchg`` | Date of last change |
+-------+---------------+---------------------------------+
| 3 | ``sp_min`` | Minimal number of days between |
| | | changes |
+-------+---------------+---------------------------------+
| 4 | ``sp_max`` | Maximum number of days between |
| | | changes |
+-------+---------------+---------------------------------+
| 5 | ``sp_warn`` | Number of days before password |
| | | expires to warn user about it |
+-------+---------------+---------------------------------+
| 6 | ``sp_inact`` | Number of days after password |
| | | expires until account is |
| | | blocked |
+-------+---------------+---------------------------------+
| 7 | ``sp_expire`` | Number of days since 1970-01-01 |
| | | until account is disabled |
+-------+---------------+---------------------------------+
| 8 | ``sp_flag`` | Reserved |
+-------+---------------+---------------------------------+
The sp_nam and sp_pwd items are strings, all others are integers.
:exc:`KeyError` is raised if the entry asked for cannot be found.
It defines the following items:
.. function:: getspnam(name)
Return the shadow password database entry for the given user name.
.. function:: getspall()
Return a list of all available shadow password database entries, in arbitrary
order.
.. seealso::
Module :mod:`grp`
An interface to the group database, similar to this.
Module :mod:`pwd`
An interface to the normal password database, similar to this.
PK
%�\ F�x� x� % html/_sources/library/sqlite3.rst.txtnu �[��� :mod:`sqlite3` --- DB-API 2.0 interface for SQLite databases
============================================================
.. module:: sqlite3
:synopsis: A DB-API 2.0 implementation using SQLite 3.x.
.. sectionauthor:: Gerhard Häring <gh@ghaering.de>
.. versionadded:: 2.5
SQLite is a C library that provides a lightweight disk-based database that
doesn't require a separate server process and allows accessing the database
using a nonstandard variant of the SQL query language. Some applications can use
SQLite for internal data storage. It's also possible to prototype an
application using SQLite and then port the code to a larger database such as
PostgreSQL or Oracle.
The sqlite3 module was written by Gerhard Häring. It provides a SQL interface
compliant with the DB-API 2.0 specification described by :pep:`249`.
To use the module, you must first create a :class:`Connection` object that
represents the database. Here the data will be stored in the
:file:`example.db` file::
import sqlite3
conn = sqlite3.connect('example.db')
You can also supply the special name ``:memory:`` to create a database in RAM.
Once you have a :class:`Connection`, you can create a :class:`Cursor` object
and call its :meth:`~Cursor.execute` method to perform SQL commands::
c = conn.cursor()
# Create table
c.execute('''CREATE TABLE stocks
(date text, trans text, symbol text, qty real, price real)''')
# Insert a row of data
c.execute("INSERT INTO stocks VALUES ('2006-01-05','BUY','RHAT',100,35.14)")
# Save (commit) the changes
conn.commit()
# We can also close the connection if we are done with it.
# Just be sure any changes have been committed or they will be lost.
conn.close()
The data you've saved is persistent and is available in subsequent sessions::
import sqlite3
conn = sqlite3.connect('example.db')
c = conn.cursor()
Usually your SQL operations will need to use values from Python variables. You
shouldn't assemble your query using Python's string operations because doing so
is insecure; it makes your program vulnerable to an SQL injection attack
(see https://xkcd.com/327/ for humorous example of what can go wrong).
Instead, use the DB-API's parameter substitution. Put ``?`` as a placeholder
wherever you want to use a value, and then provide a tuple of values as the
second argument to the cursor's :meth:`~Cursor.execute` method. (Other database
modules may use a different placeholder, such as ``%s`` or ``:1``.) For
example::
# Never do this -- insecure!
symbol = 'RHAT'
c.execute("SELECT * FROM stocks WHERE symbol = '%s'" % symbol)
# Do this instead
t = ('RHAT',)
c.execute('SELECT * FROM stocks WHERE symbol=?', t)
print c.fetchone()
# Larger example that inserts many records at a time
purchases = [('2006-03-28', 'BUY', 'IBM', 1000, 45.00),
('2006-04-05', 'BUY', 'MSFT', 1000, 72.00),
('2006-04-06', 'SELL', 'IBM', 500, 53.00),
]
c.executemany('INSERT INTO stocks VALUES (?,?,?,?,?)', purchases)
To retrieve data after executing a SELECT statement, you can either treat the
cursor as an :term:`iterator`, call the cursor's :meth:`~Cursor.fetchone` method to
retrieve a single matching row, or call :meth:`~Cursor.fetchall` to get a list of the
matching rows.
This example uses the iterator form::
>>> for row in c.execute('SELECT * FROM stocks ORDER BY price'):
print row
(u'2006-01-05', u'BUY', u'RHAT', 100, 35.14)
(u'2006-03-28', u'BUY', u'IBM', 1000, 45.0)
(u'2006-04-06', u'SELL', u'IBM', 500, 53.0)
(u'2006-04-05', u'BUY', u'MSFT', 1000, 72.0)
.. seealso::
https://github.com/ghaering/pysqlite
The pysqlite web page -- sqlite3 is developed externally under the name
"pysqlite".
https://www.sqlite.org
The SQLite web page; the documentation describes the syntax and the
available data types for the supported SQL dialect.
http://www.w3schools.com/sql/
Tutorial, reference and examples for learning SQL syntax.
:pep:`249` - Database API Specification 2.0
PEP written by Marc-André Lemburg.
.. _sqlite3-module-contents:
Module functions and constants
------------------------------
.. data:: version
The version number of this module, as a string. This is not the version of
the SQLite library.
.. data:: version_info
The version number of this module, as a tuple of integers. This is not the
version of the SQLite library.
.. data:: sqlite_version
The version number of the run-time SQLite library, as a string.
.. data:: sqlite_version_info
The version number of the run-time SQLite library, as a tuple of integers.
.. data:: PARSE_DECLTYPES
This constant is meant to be used with the *detect_types* parameter of the
:func:`connect` function.
Setting it makes the :mod:`sqlite3` module parse the declared type for each
column it returns. It will parse out the first word of the declared type,
i. e. for "integer primary key", it will parse out "integer", or for
"number(10)" it will parse out "number". Then for that column, it will look
into the converters dictionary and use the converter function registered for
that type there.
.. data:: PARSE_COLNAMES
This constant is meant to be used with the *detect_types* parameter of the
:func:`connect` function.
Setting this makes the SQLite interface parse the column name for each column it
returns. It will look for a string formed [mytype] in there, and then decide
that 'mytype' is the type of the column. It will try to find an entry of
'mytype' in the converters dictionary and then use the converter function found
there to return the value. The column name found in :attr:`Cursor.description`
is only the first word of the column name, i. e. if you use something like
``'as "x [datetime]"'`` in your SQL, then we will parse out everything until the
first blank for the column name: the column name would simply be "x".
.. function:: connect(database[, timeout, detect_types, isolation_level, check_same_thread, factory, cached_statements])
Opens a connection to the SQLite database file *database*. You can use
``":memory:"`` to open a database connection to a database that resides in RAM
instead of on disk.
When a database is accessed by multiple connections, and one of the processes
modifies the database, the SQLite database is locked until that transaction is
committed. The *timeout* parameter specifies how long the connection should wait
for the lock to go away until raising an exception. The default for the timeout
parameter is 5.0 (five seconds).
For the *isolation_level* parameter, please see the
:attr:`Connection.isolation_level` property of :class:`Connection` objects.
SQLite natively supports only the types TEXT, INTEGER, REAL, BLOB and NULL. If
you want to use other types you must add support for them yourself. The
*detect_types* parameter and the using custom **converters** registered with the
module-level :func:`register_converter` function allow you to easily do that.
*detect_types* defaults to 0 (i. e. off, no type detection), you can set it to
any combination of :const:`PARSE_DECLTYPES` and :const:`PARSE_COLNAMES` to turn
type detection on.
By default, the :mod:`sqlite3` module uses its :class:`Connection` class for the
connect call. You can, however, subclass the :class:`Connection` class and make
:func:`connect` use your class instead by providing your class for the *factory*
parameter.
Consult the section :ref:`sqlite3-types` of this manual for details.
The :mod:`sqlite3` module internally uses a statement cache to avoid SQL parsing
overhead. If you want to explicitly set the number of statements that are cached
for the connection, you can set the *cached_statements* parameter. The currently
implemented default is to cache 100 statements.
.. function:: register_converter(typename, callable)
Registers a callable to convert a bytestring from the database into a custom
Python type. The callable will be invoked for all database values that are of
the type *typename*. Confer the parameter *detect_types* of the :func:`connect`
function for how the type detection works. Note that *typename* and the name of
the type in your query are matched in case-insensitive manner.
.. function:: register_adapter(type, callable)
Registers a callable to convert the custom Python type *type* into one of
SQLite's supported types. The callable *callable* accepts as single parameter
the Python value, and must return a value of the following types: int, long,
float, str (UTF-8 encoded), unicode or buffer.
.. function:: complete_statement(sql)
Returns :const:`True` if the string *sql* contains one or more complete SQL
statements terminated by semicolons. It does not verify that the SQL is
syntactically correct, only that there are no unclosed string literals and the
statement is terminated by a semicolon.
This can be used to build a shell for SQLite, as in the following example:
.. literalinclude:: ../includes/sqlite3/complete_statement.py
.. function:: enable_callback_tracebacks(flag)
By default you will not get any tracebacks in user-defined functions,
aggregates, converters, authorizer callbacks etc. If you want to debug them,
you can call this function with *flag* set to ``True``. Afterwards, you will
get tracebacks from callbacks on ``sys.stderr``. Use :const:`False` to
disable the feature again.
.. _sqlite3-connection-objects:
Connection Objects
------------------
.. class:: Connection
A SQLite database connection has the following attributes and methods:
.. attribute:: isolation_level
Get or set the current isolation level. :const:`None` for autocommit mode or
one of "DEFERRED", "IMMEDIATE" or "EXCLUSIVE". See section
:ref:`sqlite3-controlling-transactions` for a more detailed explanation.
.. method:: cursor(factory=Cursor)
The cursor method accepts a single optional parameter *factory*. If
supplied, this must be a callable returning an instance of :class:`Cursor`
or its subclasses.
.. method:: commit()
This method commits the current transaction. If you don't call this method,
anything you did since the last call to ``commit()`` is not visible from
other database connections. If you wonder why you don't see the data you've
written to the database, please check you didn't forget to call this method.
.. method:: rollback()
This method rolls back any changes to the database since the last call to
:meth:`commit`.
.. method:: close()
This closes the database connection. Note that this does not automatically
call :meth:`commit`. If you just close your database connection without
calling :meth:`commit` first, your changes will be lost!
.. method:: execute(sql, [parameters])
This is a nonstandard shortcut that creates an intermediate cursor object by
calling the cursor method, then calls the cursor's :meth:`execute
<Cursor.execute>` method with the parameters given.
.. method:: executemany(sql, [parameters])
This is a nonstandard shortcut that creates an intermediate cursor object by
calling the cursor method, then calls the cursor's :meth:`executemany
<Cursor.executemany>` method with the parameters given.
.. method:: executescript(sql_script)
This is a nonstandard shortcut that creates an intermediate cursor object by
calling the cursor method, then calls the cursor's :meth:`executescript
<Cursor.executescript>` method with the parameters given.
.. method:: create_function(name, num_params, func)
Creates a user-defined function that you can later use from within SQL
statements under the function name *name*. *num_params* is the number of
parameters the function accepts, and *func* is a Python callable that is called
as the SQL function.
The function can return any of the types supported by SQLite: unicode, str, int,
long, float, buffer and ``None``.
Example:
.. literalinclude:: ../includes/sqlite3/md5func.py
.. method:: create_aggregate(name, num_params, aggregate_class)
Creates a user-defined aggregate function.
The aggregate class must implement a ``step`` method, which accepts the number
of parameters *num_params*, and a ``finalize`` method which will return the
final result of the aggregate.
The ``finalize`` method can return any of the types supported by SQLite:
unicode, str, int, long, float, buffer and ``None``.
Example:
.. literalinclude:: ../includes/sqlite3/mysumaggr.py
.. method:: create_collation(name, callable)
Creates a collation with the specified *name* and *callable*. The callable will
be passed two string arguments. It should return -1 if the first is ordered
lower than the second, 0 if they are ordered equal and 1 if the first is ordered
higher than the second. Note that this controls sorting (ORDER BY in SQL) so
your comparisons don't affect other SQL operations.
Note that the callable will get its parameters as Python bytestrings, which will
normally be encoded in UTF-8.
The following example shows a custom collation that sorts "the wrong way":
.. literalinclude:: ../includes/sqlite3/collation_reverse.py
To remove a collation, call ``create_collation`` with ``None`` as callable::
con.create_collation("reverse", None)
.. method:: interrupt()
You can call this method from a different thread to abort any queries that might
be executing on the connection. The query will then abort and the caller will
get an exception.
.. method:: set_authorizer(authorizer_callback)
This routine registers a callback. The callback is invoked for each attempt to
access a column of a table in the database. The callback should return
:const:`SQLITE_OK` if access is allowed, :const:`SQLITE_DENY` if the entire SQL
statement should be aborted with an error and :const:`SQLITE_IGNORE` if the
column should be treated as a NULL value. These constants are available in the
:mod:`sqlite3` module.
The first argument to the callback signifies what kind of operation is to be
authorized. The second and third argument will be arguments or :const:`None`
depending on the first argument. The 4th argument is the name of the database
("main", "temp", etc.) if applicable. The 5th argument is the name of the
inner-most trigger or view that is responsible for the access attempt or
:const:`None` if this access attempt is directly from input SQL code.
Please consult the SQLite documentation about the possible values for the first
argument and the meaning of the second and third argument depending on the first
one. All necessary constants are available in the :mod:`sqlite3` module.
.. method:: set_progress_handler(handler, n)
This routine registers a callback. The callback is invoked for every *n*
instructions of the SQLite virtual machine. This is useful if you want to
get called from SQLite during long-running operations, for example to update
a GUI.
If you want to clear any previously installed progress handler, call the
method with :const:`None` for *handler*.
.. versionadded:: 2.6
.. method:: enable_load_extension(enabled)
This routine allows/disallows the SQLite engine to load SQLite extensions
from shared libraries. SQLite extensions can define new functions,
aggregates or whole new virtual table implementations. One well-known
extension is the fulltext-search extension distributed with SQLite.
Loadable extensions are disabled by default. See [#f1]_.
.. versionadded:: 2.7
.. literalinclude:: ../includes/sqlite3/load_extension.py
.. method:: load_extension(path)
This routine loads a SQLite extension from a shared library. You have to
enable extension loading with :meth:`enable_load_extension` before you can
use this routine.
Loadable extensions are disabled by default. See [#f1]_.
.. versionadded:: 2.7
.. attribute:: row_factory
You can change this attribute to a callable that accepts the cursor and the
original row as a tuple and will return the real result row. This way, you can
implement more advanced ways of returning results, such as returning an object
that can also access columns by name.
Example:
.. literalinclude:: ../includes/sqlite3/row_factory.py
If returning a tuple doesn't suffice and you want name-based access to
columns, you should consider setting :attr:`row_factory` to the
highly-optimized :class:`sqlite3.Row` type. :class:`Row` provides both
index-based and case-insensitive name-based access to columns with almost no
memory overhead. It will probably be better than your own custom
dictionary-based approach or even a db_row based solution.
.. XXX what's a db_row-based solution?
.. attribute:: text_factory
Using this attribute you can control what objects are returned for the ``TEXT``
data type. By default, this attribute is set to :class:`unicode` and the
:mod:`sqlite3` module will return Unicode objects for ``TEXT``. If you want to
return bytestrings instead, you can set it to :class:`str`.
For efficiency reasons, there's also a way to return Unicode objects only for
non-ASCII data, and bytestrings otherwise. To activate it, set this attribute to
:const:`sqlite3.OptimizedUnicode`.
You can also set it to any other callable that accepts a single bytestring
parameter and returns the resulting object.
See the following example code for illustration:
.. literalinclude:: ../includes/sqlite3/text_factory.py
.. attribute:: total_changes
Returns the total number of database rows that have been modified, inserted, or
deleted since the database connection was opened.
.. attribute:: iterdump
Returns an iterator to dump the database in an SQL text format. Useful when
saving an in-memory database for later restoration. This function provides
the same capabilities as the :kbd:`.dump` command in the :program:`sqlite3`
shell.
.. versionadded:: 2.6
Example::
# Convert file existing_db.db to SQL dump file dump.sql
import sqlite3, os
con = sqlite3.connect('existing_db.db')
with open('dump.sql', 'w') as f:
for line in con.iterdump():
f.write('%s\n' % line)
.. _sqlite3-cursor-objects:
Cursor Objects
--------------
.. class:: Cursor
A :class:`Cursor` instance has the following attributes and methods.
.. method:: execute(sql, [parameters])
Executes an SQL statement. The SQL statement may be parameterized (i. e.
placeholders instead of SQL literals). The :mod:`sqlite3` module supports two
kinds of placeholders: question marks (qmark style) and named placeholders
(named style).
Here's an example of both styles:
.. literalinclude:: ../includes/sqlite3/execute_1.py
:meth:`execute` will only execute a single SQL statement. If you try to execute
more than one statement with it, it will raise a Warning. Use
:meth:`executescript` if you want to execute multiple SQL statements with one
call.
.. method:: executemany(sql, seq_of_parameters)
Executes an SQL command against all parameter sequences or mappings found in
the sequence *sql*. The :mod:`sqlite3` module also allows using an
:term:`iterator` yielding parameters instead of a sequence.
.. literalinclude:: ../includes/sqlite3/executemany_1.py
Here's a shorter example using a :term:`generator`:
.. literalinclude:: ../includes/sqlite3/executemany_2.py
.. method:: executescript(sql_script)
This is a nonstandard convenience method for executing multiple SQL statements
at once. It issues a ``COMMIT`` statement first, then executes the SQL script it
gets as a parameter.
*sql_script* can be a bytestring or a Unicode string.
Example:
.. literalinclude:: ../includes/sqlite3/executescript.py
.. method:: fetchone()
Fetches the next row of a query result set, returning a single sequence,
or :const:`None` when no more data is available.
.. method:: fetchmany([size=cursor.arraysize])
Fetches the next set of rows of a query result, returning a list. An empty
list is returned when no more rows are available.
The number of rows to fetch per call is specified by the *size* parameter.
If it is not given, the cursor's arraysize determines the number of rows
to be fetched. The method should try to fetch as many rows as indicated by
the size parameter. If this is not possible due to the specified number of
rows not being available, fewer rows may be returned.
Note there are performance considerations involved with the *size* parameter.
For optimal performance, it is usually best to use the arraysize attribute.
If the *size* parameter is used, then it is best for it to retain the same
value from one :meth:`fetchmany` call to the next.
.. method:: fetchall()
Fetches all (remaining) rows of a query result, returning a list. Note that
the cursor's arraysize attribute can affect the performance of this operation.
An empty list is returned when no rows are available.
.. attribute:: rowcount
Although the :class:`Cursor` class of the :mod:`sqlite3` module implements this
attribute, the database engine's own support for the determination of "rows
affected"/"rows selected" is quirky.
For :meth:`executemany` statements, the number of modifications are summed up
into :attr:`rowcount`.
As required by the Python DB API Spec, the :attr:`rowcount` attribute "is -1 in
case no ``executeXX()`` has been performed on the cursor or the rowcount of the
last operation is not determinable by the interface". This includes ``SELECT``
statements because we cannot determine the number of rows a query produced
until all rows were fetched.
With SQLite versions before 3.6.5, :attr:`rowcount` is set to 0 if
you make a ``DELETE FROM table`` without any condition.
.. attribute:: lastrowid
This read-only attribute provides the rowid of the last modified row. It is
only set if you issued an ``INSERT`` statement using the :meth:`execute`
method. For operations other than ``INSERT`` or when :meth:`executemany` is
called, :attr:`lastrowid` is set to :const:`None`.
.. attribute:: description
This read-only attribute provides the column names of the last query. To
remain compatible with the Python DB API, it returns a 7-tuple for each
column where the last six items of each tuple are :const:`None`.
It is set for ``SELECT`` statements without any matching rows as well.
.. attribute:: connection
This read-only attribute provides the SQLite database :class:`Connection`
used by the :class:`Cursor` object. A :class:`Cursor` object created by
calling :meth:`con.cursor() <Connection.cursor>` will have a
:attr:`connection` attribute that refers to *con*::
>>> con = sqlite3.connect(":memory:")
>>> cur = con.cursor()
>>> cur.connection == con
True
.. _sqlite3-row-objects:
Row Objects
-----------
.. class:: Row
A :class:`Row` instance serves as a highly optimized
:attr:`~Connection.row_factory` for :class:`Connection` objects.
It tries to mimic a tuple in most of its features.
It supports mapping access by column name and index, iteration,
representation, equality testing and :func:`len`.
If two :class:`Row` objects have exactly the same columns and their
members are equal, they compare equal.
.. versionchanged:: 2.6
Added iteration and equality (hashability).
.. method:: keys
This method returns a list of column names. Immediately after a query,
it is the first member of each tuple in :attr:`Cursor.description`.
.. versionadded:: 2.6
Let's assume we initialize a table as in the example given above::
conn = sqlite3.connect(":memory:")
c = conn.cursor()
c.execute('''create table stocks
(date text, trans text, symbol text,
qty real, price real)''')
c.execute("""insert into stocks
values ('2006-01-05','BUY','RHAT',100,35.14)""")
conn.commit()
c.close()
Now we plug :class:`Row` in::
>>> conn.row_factory = sqlite3.Row
>>> c = conn.cursor()
>>> c.execute('select * from stocks')
<sqlite3.Cursor object at 0x7f4e7dd8fa80>
>>> r = c.fetchone()
>>> type(r)
<type 'sqlite3.Row'>
>>> r
(u'2006-01-05', u'BUY', u'RHAT', 100.0, 35.14)
>>> len(r)
5
>>> r[2]
u'RHAT'
>>> r.keys()
['date', 'trans', 'symbol', 'qty', 'price']
>>> r['qty']
100.0
>>> for member in r:
... print member
...
2006-01-05
BUY
RHAT
100.0
35.14
.. _sqlite3-types:
SQLite and Python types
-----------------------
Introduction
^^^^^^^^^^^^
SQLite natively supports the following types: ``NULL``, ``INTEGER``,
``REAL``, ``TEXT``, ``BLOB``.
The following Python types can thus be sent to SQLite without any problem:
+-----------------------------+-------------+
| Python type | SQLite type |
+=============================+=============+
| :const:`None` | ``NULL`` |
+-----------------------------+-------------+
| :class:`int` | ``INTEGER`` |
+-----------------------------+-------------+
| :class:`long` | ``INTEGER`` |
+-----------------------------+-------------+
| :class:`float` | ``REAL`` |
+-----------------------------+-------------+
| :class:`str` (UTF8-encoded) | ``TEXT`` |
+-----------------------------+-------------+
| :class:`unicode` | ``TEXT`` |
+-----------------------------+-------------+
| :class:`buffer` | ``BLOB`` |
+-----------------------------+-------------+
This is how SQLite types are converted to Python types by default:
+-------------+----------------------------------------------+
| SQLite type | Python type |
+=============+==============================================+
| ``NULL`` | :const:`None` |
+-------------+----------------------------------------------+
| ``INTEGER`` | :class:`int` or :class:`long`, |
| | depending on size |
+-------------+----------------------------------------------+
| ``REAL`` | :class:`float` |
+-------------+----------------------------------------------+
| ``TEXT`` | depends on :attr:`~Connection.text_factory`, |
| | :class:`unicode` by default |
+-------------+----------------------------------------------+
| ``BLOB`` | :class:`buffer` |
+-------------+----------------------------------------------+
The type system of the :mod:`sqlite3` module is extensible in two ways: you can
store additional Python types in a SQLite database via object adaptation, and
you can let the :mod:`sqlite3` module convert SQLite types to different Python
types via converters.
Using adapters to store additional Python types in SQLite databases
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
As described before, SQLite supports only a limited set of types natively. To
use other Python types with SQLite, you must **adapt** them to one of the
sqlite3 module's supported types for SQLite: one of NoneType, int, long, float,
str, unicode, buffer.
There are two ways to enable the :mod:`sqlite3` module to adapt a custom Python
type to one of the supported ones.
Letting your object adapt itself
""""""""""""""""""""""""""""""""
This is a good approach if you write the class yourself. Let's suppose you have
a class like this::
class Point(object):
def __init__(self, x, y):
self.x, self.y = x, y
Now you want to store the point in a single SQLite column. First you'll have to
choose one of the supported types first to be used for representing the point.
Let's just use str and separate the coordinates using a semicolon. Then you need
to give your class a method ``__conform__(self, protocol)`` which must return
the converted value. The parameter *protocol* will be :class:`PrepareProtocol`.
.. literalinclude:: ../includes/sqlite3/adapter_point_1.py
Registering an adapter callable
"""""""""""""""""""""""""""""""
The other possibility is to create a function that converts the type to the
string representation and register the function with :meth:`register_adapter`.
.. note::
The type/class to adapt must be a :term:`new-style class`, i. e. it must have
:class:`object` as one of its bases.
.. literalinclude:: ../includes/sqlite3/adapter_point_2.py
The :mod:`sqlite3` module has two default adapters for Python's built-in
:class:`datetime.date` and :class:`datetime.datetime` types. Now let's suppose
we want to store :class:`datetime.datetime` objects not in ISO representation,
but as a Unix timestamp.
.. literalinclude:: ../includes/sqlite3/adapter_datetime.py
Converting SQLite values to custom Python types
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Writing an adapter lets you send custom Python types to SQLite. But to make it
really useful we need to make the Python to SQLite to Python roundtrip work.
Enter converters.
Let's go back to the :class:`Point` class. We stored the x and y coordinates
separated via semicolons as strings in SQLite.
First, we'll define a converter function that accepts the string as a parameter
and constructs a :class:`Point` object from it.
.. note::
Converter functions **always** get called with a string, no matter under which
data type you sent the value to SQLite.
::
def convert_point(s):
x, y = map(float, s.split(";"))
return Point(x, y)
Now you need to make the :mod:`sqlite3` module know that what you select from
the database is actually a point. There are two ways of doing this:
* Implicitly via the declared type
* Explicitly via the column name
Both ways are described in section :ref:`sqlite3-module-contents`, in the entries
for the constants :const:`PARSE_DECLTYPES` and :const:`PARSE_COLNAMES`.
The following example illustrates both approaches.
.. literalinclude:: ../includes/sqlite3/converter_point.py
Default adapters and converters
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
There are default adapters for the date and datetime types in the datetime
module. They will be sent as ISO dates/ISO timestamps to SQLite.
The default converters are registered under the name "date" for
:class:`datetime.date` and under the name "timestamp" for
:class:`datetime.datetime`.
This way, you can use date/timestamps from Python without any additional
fiddling in most cases. The format of the adapters is also compatible with the
experimental SQLite date/time functions.
The following example demonstrates this.
.. literalinclude:: ../includes/sqlite3/pysqlite_datetime.py
If a timestamp stored in SQLite has a fractional part longer than 6
numbers, its value will be truncated to microsecond precision by the
timestamp converter.
.. _sqlite3-controlling-transactions:
Controlling Transactions
------------------------
By default, the :mod:`sqlite3` module opens transactions implicitly before a
Data Modification Language (DML) statement (i.e.
``INSERT``/``UPDATE``/``DELETE``/``REPLACE``), and commits transactions
implicitly before a non-DML, non-query statement (i. e.
anything other than ``SELECT`` or the aforementioned).
So if you are within a transaction and issue a command like ``CREATE TABLE
...``, ``VACUUM``, ``PRAGMA``, the :mod:`sqlite3` module will commit implicitly
before executing that command. There are two reasons for doing that. The first
is that some of these commands don't work within transactions. The other reason
is that sqlite3 needs to keep track of the transaction state (if a transaction
is active or not).
You can control which kind of ``BEGIN`` statements sqlite3 implicitly executes
(or none at all) via the *isolation_level* parameter to the :func:`connect`
call, or via the :attr:`isolation_level` property of connections.
If you want **autocommit mode**, then set :attr:`isolation_level` to ``None``.
Otherwise leave it at its default, which will result in a plain "BEGIN"
statement, or set it to one of SQLite's supported isolation levels: "DEFERRED",
"IMMEDIATE" or "EXCLUSIVE".
Using :mod:`sqlite3` efficiently
--------------------------------
Using shortcut methods
^^^^^^^^^^^^^^^^^^^^^^
Using the nonstandard :meth:`execute`, :meth:`executemany` and
:meth:`executescript` methods of the :class:`Connection` object, your code can
be written more concisely because you don't have to create the (often
superfluous) :class:`Cursor` objects explicitly. Instead, the :class:`Cursor`
objects are created implicitly and these shortcut methods return the cursor
objects. This way, you can execute a ``SELECT`` statement and iterate over it
directly using only a single call on the :class:`Connection` object.
.. literalinclude:: ../includes/sqlite3/shortcut_methods.py
Accessing columns by name instead of by index
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
One useful feature of the :mod:`sqlite3` module is the built-in
:class:`sqlite3.Row` class designed to be used as a row factory.
Rows wrapped with this class can be accessed both by index (like tuples) and
case-insensitively by name:
.. literalinclude:: ../includes/sqlite3/rowclass.py
Using the connection as a context manager
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. versionadded:: 2.6
Connection objects can be used as context managers
that automatically commit or rollback transactions. In the event of an
exception, the transaction is rolled back; otherwise, the transaction is
committed:
.. literalinclude:: ../includes/sqlite3/ctx_manager.py
Common issues
-------------
Multithreading
^^^^^^^^^^^^^^
Older SQLite versions had issues with sharing connections between threads.
That's why the Python module disallows sharing connections and cursors between
threads. If you still try to do so, you will get an exception at runtime.
The only exception is calling the :meth:`~Connection.interrupt` method, which
only makes sense to call from a different thread.
.. rubric:: Footnotes
.. [#f1] The sqlite3 module is not built with loadable extension support by
default, because some platforms (notably Mac OS X) have SQLite libraries
which are compiled without this feature. To get loadable extension support,
you must modify setup.py and remove the line that sets
SQLITE_OMIT_LOAD_EXTENSION.
PK
%�\v��_
+
+ ! html/_sources/library/ssl.rst.txtnu �[��� :mod:`ssl` --- TLS/SSL wrapper for socket objects
=================================================
.. module:: ssl
:synopsis: TLS/SSL wrapper for socket objects
.. moduleauthor:: Bill Janssen <bill.janssen@gmail.com>
.. sectionauthor:: Bill Janssen <bill.janssen@gmail.com>
.. index:: single: OpenSSL; (use in module ssl)
.. index:: TLS, SSL, Transport Layer Security, Secure Sockets Layer
.. versionadded:: 2.6
**Source code:** :source:`Lib/ssl.py`
--------------
This module provides access to Transport Layer Security (often known as "Secure
Sockets Layer") encryption and peer authentication facilities for network
sockets, both client-side and server-side. This module uses the OpenSSL
library. It is available on all modern Unix systems, Windows, Mac OS X, and
probably additional platforms, as long as OpenSSL is installed on that platform.
.. versionchanged:: 2.7.13
Updated to support linking with OpenSSL 1.1.0
.. note::
Some behavior may be platform dependent, since calls are made to the
operating system socket APIs. The installed version of OpenSSL may also
cause variations in behavior. For example, TLSv1.1 and TLSv1.2 come with
openssl version 1.0.1.
.. warning::
Don't use this module without reading the :ref:`ssl-security`. Doing so
may lead to a false sense of security, as the default settings of the
ssl module are not necessarily appropriate for your application.
This section documents the objects and functions in the ``ssl`` module; for more
general information about TLS, SSL, and certificates, the reader is referred to
the documents in the "See Also" section at the bottom.
This module provides a class, :class:`ssl.SSLSocket`, which is derived from the
:class:`socket.socket` type, and provides a socket-like wrapper that also
encrypts and decrypts the data going over the socket with SSL. It supports
additional methods such as :meth:`getpeercert`, which retrieves the
certificate of the other side of the connection, and :meth:`cipher`,which
retrieves the cipher being used for the secure connection.
For more sophisticated applications, the :class:`ssl.SSLContext` class
helps manage settings and certificates, which can then be inherited
by SSL sockets created through the :meth:`SSLContext.wrap_socket` method.
Functions, Constants, and Exceptions
------------------------------------
.. exception:: SSLError
Raised to signal an error from the underlying SSL implementation (currently
provided by the OpenSSL library). This signifies some problem in the
higher-level encryption and authentication layer that's superimposed on the
underlying network connection. This error is a subtype of
:exc:`socket.error`, which in turn is a subtype of :exc:`IOError`. The
error code and message of :exc:`SSLError` instances are provided by the
OpenSSL library.
.. attribute:: library
A string mnemonic designating the OpenSSL submodule in which the error
occurred, such as ``SSL``, ``PEM`` or ``X509``. The range of possible
values depends on the OpenSSL version.
.. versionadded:: 2.7.9
.. attribute:: reason
A string mnemonic designating the reason this error occurred, for
example ``CERTIFICATE_VERIFY_FAILED``. The range of possible
values depends on the OpenSSL version.
.. versionadded:: 2.7.9
.. exception:: SSLZeroReturnError
A subclass of :exc:`SSLError` raised when trying to read or write and
the SSL connection has been closed cleanly. Note that this doesn't
mean that the underlying transport (read TCP) has been closed.
.. versionadded:: 2.7.9
.. exception:: SSLWantReadError
A subclass of :exc:`SSLError` raised by a :ref:`non-blocking SSL socket
<ssl-nonblocking>` when trying to read or write data, but more data needs
to be received on the underlying TCP transport before the request can be
fulfilled.
.. versionadded:: 2.7.9
.. exception:: SSLWantWriteError
A subclass of :exc:`SSLError` raised by a :ref:`non-blocking SSL socket
<ssl-nonblocking>` when trying to read or write data, but more data needs
to be sent on the underlying TCP transport before the request can be
fulfilled.
.. versionadded:: 2.7.9
.. exception:: SSLSyscallError
A subclass of :exc:`SSLError` raised when a system error was encountered
while trying to fulfill an operation on a SSL socket. Unfortunately,
there is no easy way to inspect the original errno number.
.. versionadded:: 2.7.9
.. exception:: SSLEOFError
A subclass of :exc:`SSLError` raised when the SSL connection has been
terminated abruptly. Generally, you shouldn't try to reuse the underlying
transport when this error is encountered.
.. versionadded:: 2.7.9
.. exception:: CertificateError
Raised to signal an error with a certificate (such as mismatching
hostname). Certificate errors detected by OpenSSL, though, raise
an :exc:`SSLError`.
Socket creation
^^^^^^^^^^^^^^^
The following function allows for standalone socket creation. Starting from
Python 2.7.9, it can be more flexible to use :meth:`SSLContext.wrap_socket`
instead.
.. function:: wrap_socket(sock, keyfile=None, certfile=None, server_side=False, cert_reqs=CERT_NONE, ssl_version={see docs}, ca_certs=None, do_handshake_on_connect=True, suppress_ragged_eofs=True, ciphers=None)
Takes an instance ``sock`` of :class:`socket.socket`, and returns an instance
of :class:`ssl.SSLSocket`, a subtype of :class:`socket.socket`, which wraps
the underlying socket in an SSL context. ``sock`` must be a
:data:`~socket.SOCK_STREAM` socket; other socket types are unsupported.
For client-side sockets, the context construction is lazy; if the
underlying socket isn't connected yet, the context construction will be
performed after :meth:`connect` is called on the socket. For
server-side sockets, if the socket has no remote peer, it is assumed
to be a listening socket, and the server-side SSL wrapping is
automatically performed on client connections accepted via the
:meth:`accept` method. :func:`wrap_socket` may raise :exc:`SSLError`.
The ``keyfile`` and ``certfile`` parameters specify optional files which
contain a certificate to be used to identify the local side of the
connection. See the discussion of :ref:`ssl-certificates` for more
information on how the certificate is stored in the ``certfile``.
The parameter ``server_side`` is a boolean which identifies whether
server-side or client-side behavior is desired from this socket.
The parameter ``cert_reqs`` specifies whether a certificate is required from
the other side of the connection, and whether it will be validated if
provided. It must be one of the three values :const:`CERT_NONE`
(certificates ignored), :const:`CERT_OPTIONAL` (not required, but validated
if provided), or :const:`CERT_REQUIRED` (required and validated). If the
value of this parameter is not :const:`CERT_NONE`, then the ``ca_certs``
parameter must point to a file of CA certificates.
The ``ca_certs`` file contains a set of concatenated "certification
authority" certificates, which are used to validate certificates passed from
the other end of the connection. See the discussion of
:ref:`ssl-certificates` for more information about how to arrange the
certificates in this file.
The parameter ``ssl_version`` specifies which version of the SSL protocol to
use. Typically, the server chooses a particular protocol version, and the
client must adapt to the server's choice. Most of the versions are not
interoperable with the other versions. If not specified, the default is
:data:`PROTOCOL_SSLv23`; it provides the most compatibility with other
versions.
Here's a table showing which versions in a client (down the side) can connect
to which versions in a server (along the top):
.. table::
======================== ========= ========= ========== ========= =========== ===========
*client* / **server** **SSLv2** **SSLv3** **SSLv23** **TLSv1** **TLSv1.1** **TLSv1.2**
------------------------ --------- --------- ---------- --------- ----------- -----------
*SSLv2* yes no yes no no no
*SSLv3* no yes yes no no no
*SSLv23* [1]_ no yes yes yes yes yes
*TLSv1* no no yes yes no no
*TLSv1.1* no no yes no yes no
*TLSv1.2* no no yes no no yes
======================== ========= ========= ========== ========= =========== ===========
.. rubric:: Footnotes
.. [1] TLS 1.3 protocol will be available with :data:`PROTOCOL_SSLv23` in
OpenSSL >= 1.1.1. There is no dedicated PROTOCOL constant for just
TLS 1.3.
.. note::
Which connections succeed will vary depending on the version of
OpenSSL. For example, before OpenSSL 1.0.0, an SSLv23 client
would always attempt SSLv2 connections.
The *ciphers* parameter sets the available ciphers for this SSL object.
It should be a string in the `OpenSSL cipher list format
<https://www.openssl.org/docs/manmaster/man1/ciphers.html>`_.
The parameter ``do_handshake_on_connect`` specifies whether to do the SSL
handshake automatically after doing a :meth:`socket.connect`, or whether the
application program will call it explicitly, by invoking the
:meth:`SSLSocket.do_handshake` method. Calling
:meth:`SSLSocket.do_handshake` explicitly gives the program control over the
blocking behavior of the socket I/O involved in the handshake.
The parameter ``suppress_ragged_eofs`` specifies how the
:meth:`SSLSocket.read` method should signal unexpected EOF from the other end
of the connection. If specified as :const:`True` (the default), it returns a
normal EOF (an empty bytes object) in response to unexpected EOF errors
raised from the underlying socket; if :const:`False`, it will raise the
exceptions back to the caller.
.. versionchanged:: 2.7
New optional argument *ciphers*.
Context creation
^^^^^^^^^^^^^^^^
A convenience function helps create :class:`SSLContext` objects for common
purposes.
.. function:: create_default_context(purpose=Purpose.SERVER_AUTH, cafile=None, capath=None, cadata=None)
Return a new :class:`SSLContext` object with default settings for
the given *purpose*. The settings are chosen by the :mod:`ssl` module,
and usually represent a higher security level than when calling the
:class:`SSLContext` constructor directly.
*cafile*, *capath*, *cadata* represent optional CA certificates to
trust for certificate verification, as in
:meth:`SSLContext.load_verify_locations`. If all three are
:const:`None`, this function can choose to trust the system's default
CA certificates instead.
The settings are: :data:`PROTOCOL_SSLv23`, :data:`OP_NO_SSLv2`, and
:data:`OP_NO_SSLv3` with high encryption cipher suites without RC4 and
without unauthenticated cipher suites. Passing :data:`~Purpose.SERVER_AUTH`
as *purpose* sets :data:`~SSLContext.verify_mode` to :data:`CERT_REQUIRED`
and either loads CA certificates (when at least one of *cafile*, *capath* or
*cadata* is given) or uses :meth:`SSLContext.load_default_certs` to load
default CA certificates.
.. note::
The protocol, options, cipher and other settings may change to more
restrictive values anytime without prior deprecation. The values
represent a fair balance between compatibility and security.
If your application needs specific settings, you should create a
:class:`SSLContext` and apply the settings yourself.
.. note::
If you find that when certain older clients or servers attempt to connect
with a :class:`SSLContext` created by this function that they get an error
stating "Protocol or cipher suite mismatch", it may be that they only
support SSL3.0 which this function excludes using the
:data:`OP_NO_SSLv3`. SSL3.0 is widely considered to be `completely broken
<https://en.wikipedia.org/wiki/POODLE>`_. If you still wish to continue to
use this function but still allow SSL 3.0 connections you can re-enable
them using::
ctx = ssl.create_default_context(Purpose.CLIENT_AUTH)
ctx.options &= ~ssl.OP_NO_SSLv3
.. versionadded:: 2.7.9
.. versionchanged:: 2.7.10
RC4 was dropped from the default cipher string.
.. versionchanged:: 2.7.13
ChaCha20/Poly1305 was added to the default cipher string.
3DES was dropped from the default cipher string.
.. function:: _https_verify_certificates(enable=True)
Specifies whether or not server certificates are verified when creating
client HTTPS connections without specifying a particular SSL context.
Starting with Python 2.7.9, :mod:`httplib` and modules which use it, such as
:mod:`urllib2` and :mod:`xmlrpclib`, default to verifying remote server
certificates received when establishing client HTTPS connections. This
default verification checks that the certificate is signed by a Certificate
Authority in the system trust store and that the Common Name (or Subject
Alternate Name) on the presented certificate matches the requested host.
Setting *enable* to :const:`True` ensures this default behaviour is in
effect.
Setting *enable* to :const:`False` reverts the default HTTPS certificate
handling to that of Python 2.7.8 and earlier, allowing connections to
servers using self-signed certificates, servers using certificates signed
by a Certicate Authority not present in the system trust store, and servers
where the hostname does not match the presented server certificate.
The leading underscore on this function denotes that it intentionally does
not exist in any implementation of Python 3 and may not be present in all
Python 2.7 implementations. The portable approach to bypassing certificate
checks or the system trust store when necessary is for tools to enable that
on a case-by-case basis by explicitly passing in a suitably configured SSL
context, rather than reverting the default behaviour of the standard library
client modules.
.. versionadded:: 2.7.12
.. seealso::
* `CVE-2014-9365 <http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-9365>`_
-- HTTPS man-in-the-middle attack against Python clients using default settings
* :pep:`476` -- Enabling certificate verification by default for HTTPS
* :pep:`493` -- HTTPS verification migration tools for Python 2.7
Random generation
^^^^^^^^^^^^^^^^^
.. deprecated:: 2.7.13
OpenSSL has deprecated :func:`ssl.RAND_pseudo_bytes`, use
:func:`ssl.RAND_bytes` instead.
.. function:: RAND_status()
Return ``True`` if the SSL pseudo-random number generator has been seeded
with 'enough' randomness, and ``False`` otherwise. You can use
:func:`ssl.RAND_egd` and :func:`ssl.RAND_add` to increase the randomness of
the pseudo-random number generator.
.. function:: RAND_egd(path)
If you are running an entropy-gathering daemon (EGD) somewhere, and *path*
is the pathname of a socket connection open to it, this will read 256 bytes
of randomness from the socket, and add it to the SSL pseudo-random number
generator to increase the security of generated secret keys. This is
typically only necessary on systems without better sources of randomness.
See http://egd.sourceforge.net/ or http://prngd.sourceforge.net/ for sources
of entropy-gathering daemons.
Availability: not available with LibreSSL and OpenSSL > 1.1.0
.. function:: RAND_add(bytes, entropy)
Mix the given *bytes* into the SSL pseudo-random number generator. The
parameter *entropy* (a float) is a lower bound on the entropy contained in
string (so you can always use :const:`0.0`). See :rfc:`1750` for more
information on sources of entropy.
Certificate handling
^^^^^^^^^^^^^^^^^^^^
.. function:: match_hostname(cert, hostname)
Verify that *cert* (in decoded format as returned by
:meth:`SSLSocket.getpeercert`) matches the given *hostname*. The rules
applied are those for checking the identity of HTTPS servers as outlined
in :rfc:`2818` and :rfc:`6125`, except that IP addresses are not currently
supported. In addition to HTTPS, this function should be suitable for
checking the identity of servers in various SSL-based protocols such as
FTPS, IMAPS, POPS and others.
:exc:`CertificateError` is raised on failure. On success, the function
returns nothing::
>>> cert = {'subject': ((('commonName', 'example.com'),),)}
>>> ssl.match_hostname(cert, "example.com")
>>> ssl.match_hostname(cert, "example.org")
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "/home/py3k/Lib/ssl.py", line 130, in match_hostname
ssl.CertificateError: hostname 'example.org' doesn't match 'example.com'
.. versionadded:: 2.7.9
.. function:: cert_time_to_seconds(cert_time)
Return the time in seconds since the Epoch, given the ``cert_time``
string representing the "notBefore" or "notAfter" date from a
certificate in ``"%b %d %H:%M:%S %Y %Z"`` strptime format (C
locale).
Here's an example:
.. doctest:: newcontext
>>> import ssl
>>> timestamp = ssl.cert_time_to_seconds("Jan 5 09:34:43 2018 GMT")
>>> timestamp
1515144883
>>> from datetime import datetime
>>> print(datetime.utcfromtimestamp(timestamp))
2018-01-05 09:34:43
"notBefore" or "notAfter" dates must use GMT (:rfc:`5280`).
.. versionchanged:: 2.7.9
Interpret the input time as a time in UTC as specified by 'GMT'
timezone in the input string. Local timezone was used
previously. Return an integer (no fractions of a second in the
input format)
.. function:: get_server_certificate(addr, ssl_version=PROTOCOL_SSLv23, ca_certs=None)
Given the address ``addr`` of an SSL-protected server, as a (*hostname*,
*port-number*) pair, fetches the server's certificate, and returns it as a
PEM-encoded string. If ``ssl_version`` is specified, uses that version of
the SSL protocol to attempt to connect to the server. If ``ca_certs`` is
specified, it should be a file containing a list of root certificates, the
same format as used for the same parameter in :func:`wrap_socket`. The call
will attempt to validate the server certificate against that set of root
certificates, and will fail if the validation attempt fails.
.. versionchanged:: 2.7.9
This function is now IPv6-compatible, and the default *ssl_version* is
changed from :data:`PROTOCOL_SSLv3` to :data:`PROTOCOL_SSLv23` for
maximum compatibility with modern servers.
.. function:: DER_cert_to_PEM_cert(DER_cert_bytes)
Given a certificate as a DER-encoded blob of bytes, returns a PEM-encoded
string version of the same certificate.
.. function:: PEM_cert_to_DER_cert(PEM_cert_string)
Given a certificate as an ASCII PEM string, returns a DER-encoded sequence of
bytes for that same certificate.
.. function:: get_default_verify_paths()
Returns a named tuple with paths to OpenSSL's default cafile and capath.
The paths are the same as used by
:meth:`SSLContext.set_default_verify_paths`. The return value is a
:term:`named tuple` ``DefaultVerifyPaths``:
* :attr:`cafile` - resolved path to cafile or ``None`` if the file doesn't exist,
* :attr:`capath` - resolved path to capath or ``None`` if the directory doesn't exist,
* :attr:`openssl_cafile_env` - OpenSSL's environment key that points to a cafile,
* :attr:`openssl_cafile` - hard coded path to a cafile,
* :attr:`openssl_capath_env` - OpenSSL's environment key that points to a capath,
* :attr:`openssl_capath` - hard coded path to a capath directory
Availability: LibreSSL ignores the environment vars
:attr:`openssl_cafile_env` and :attr:`openssl_capath_env`
.. versionadded:: 2.7.9
.. function:: enum_certificates(store_name)
Retrieve certificates from Windows' system cert store. *store_name* may be
one of ``CA``, ``ROOT`` or ``MY``. Windows may provide additional cert
stores, too.
The function returns a list of (cert_bytes, encoding_type, trust) tuples.
The encoding_type specifies the encoding of cert_bytes. It is either
:const:`x509_asn` for X.509 ASN.1 data or :const:`pkcs_7_asn` for
PKCS#7 ASN.1 data. Trust specifies the purpose of the certificate as a set
of OIDS or exactly ``True`` if the certificate is trustworthy for all
purposes.
Example::
>>> ssl.enum_certificates("CA")
[(b'data...', 'x509_asn', {'1.3.6.1.5.5.7.3.1', '1.3.6.1.5.5.7.3.2'}),
(b'data...', 'x509_asn', True)]
Availability: Windows.
.. versionadded:: 2.7.9
.. function:: enum_crls(store_name)
Retrieve CRLs from Windows' system cert store. *store_name* may be
one of ``CA``, ``ROOT`` or ``MY``. Windows may provide additional cert
stores, too.
The function returns a list of (cert_bytes, encoding_type, trust) tuples.
The encoding_type specifies the encoding of cert_bytes. It is either
:const:`x509_asn` for X.509 ASN.1 data or :const:`pkcs_7_asn` for
PKCS#7 ASN.1 data.
Availability: Windows.
.. versionadded:: 2.7.9
Constants
^^^^^^^^^
.. data:: CERT_NONE
Possible value for :attr:`SSLContext.verify_mode`, or the ``cert_reqs``
parameter to :func:`wrap_socket`. In this mode (the default), no
certificates will be required from the other side of the socket connection.
If a certificate is received from the other end, no attempt to validate it
is made.
See the discussion of :ref:`ssl-security` below.
.. data:: CERT_OPTIONAL
Possible value for :attr:`SSLContext.verify_mode`, or the ``cert_reqs``
parameter to :func:`wrap_socket`. In this mode no certificates will be
required from the other side of the socket connection; but if they
are provided, validation will be attempted and an :class:`SSLError`
will be raised on failure.
Use of this setting requires a valid set of CA certificates to
be passed, either to :meth:`SSLContext.load_verify_locations` or as a
value of the ``ca_certs`` parameter to :func:`wrap_socket`.
.. data:: CERT_REQUIRED
Possible value for :attr:`SSLContext.verify_mode`, or the ``cert_reqs``
parameter to :func:`wrap_socket`. In this mode, certificates are
required from the other side of the socket connection; an :class:`SSLError`
will be raised if no certificate is provided, or if its validation fails.
Use of this setting requires a valid set of CA certificates to
be passed, either to :meth:`SSLContext.load_verify_locations` or as a
value of the ``ca_certs`` parameter to :func:`wrap_socket`.
.. data:: VERIFY_DEFAULT
Possible value for :attr:`SSLContext.verify_flags`. In this mode, certificate
revocation lists (CRLs) are not checked. By default OpenSSL does neither
require nor verify CRLs.
.. versionadded:: 2.7.9
.. data:: VERIFY_CRL_CHECK_LEAF
Possible value for :attr:`SSLContext.verify_flags`. In this mode, only the
peer cert is check but non of the intermediate CA certificates. The mode
requires a valid CRL that is signed by the peer cert's issuer (its direct
ancestor CA). If no proper has been loaded
:attr:`SSLContext.load_verify_locations`, validation will fail.
.. versionadded:: 2.7.9
.. data:: VERIFY_CRL_CHECK_CHAIN
Possible value for :attr:`SSLContext.verify_flags`. In this mode, CRLs of
all certificates in the peer cert chain are checked.
.. versionadded:: 2.7.9
.. data:: VERIFY_X509_STRICT
Possible value for :attr:`SSLContext.verify_flags` to disable workarounds
for broken X.509 certificates.
.. versionadded:: 2.7.9
.. data:: VERIFY_X509_TRUSTED_FIRST
Possible value for :attr:`SSLContext.verify_flags`. It instructs OpenSSL to
prefer trusted certificates when building the trust chain to validate a
certificate. This flag is enabled by default.
.. versionadded:: 2.7.10
.. data:: PROTOCOL_TLS
Selects the highest protocol version that both the client and server support.
Despite the name, this option can select "TLS" protocols as well as "SSL".
.. versionadded:: 2.7.13
.. data:: PROTOCOL_SSLv23
Alias for ``PROTOCOL_TLS``.
.. deprecated:: 2.7.13 Use ``PROTOCOL_TLS`` instead.
.. data:: PROTOCOL_SSLv2
Selects SSL version 2 as the channel encryption protocol.
This protocol is not available if OpenSSL is compiled with the
``OPENSSL_NO_SSL2`` flag.
.. warning::
SSL version 2 is insecure. Its use is highly discouraged.
.. deprecated:: 2.7.13 OpenSSL has removed support for SSLv2.
.. data:: PROTOCOL_SSLv3
Selects SSL version 3 as the channel encryption protocol.
This protocol is not be available if OpenSSL is compiled with the
``OPENSSL_NO_SSLv3`` flag.
.. warning::
SSL version 3 is insecure. Its use is highly discouraged.
.. deprecated:: 2.7.13
OpenSSL has deprecated all version specific protocols. Use the default
protocol with flags like ``OP_NO_SSLv3`` instead.
.. data:: PROTOCOL_TLSv1
Selects TLS version 1.0 as the channel encryption protocol.
.. deprecated:: 2.7.13
OpenSSL has deprecated all version specific protocols. Use the default
protocol with flags like ``OP_NO_SSLv3`` instead.
.. data:: PROTOCOL_TLSv1_1
Selects TLS version 1.1 as the channel encryption protocol.
Available only with openssl version 1.0.1+.
.. versionadded:: 2.7.9
.. deprecated:: 2.7.13
OpenSSL has deprecated all version specific protocols. Use the default
protocol with flags like ``OP_NO_SSLv3`` instead.
.. data:: PROTOCOL_TLSv1_2
Selects TLS version 1.2 as the channel encryption protocol. This is the
most modern version, and probably the best choice for maximum protection,
if both sides can speak it. Available only with openssl version 1.0.1+.
.. versionadded:: 2.7.9
.. deprecated:: 2.7.13
OpenSSL has deprecated all version specific protocols. Use the default
protocol with flags like ``OP_NO_SSLv3`` instead.
.. data:: OP_ALL
Enables workarounds for various bugs present in other SSL implementations.
This option is set by default. It does not necessarily set the same
flags as OpenSSL's ``SSL_OP_ALL`` constant.
.. versionadded:: 2.7.9
.. data:: OP_NO_SSLv2
Prevents an SSLv2 connection. This option is only applicable in
conjunction with :const:`PROTOCOL_SSLv23`. It prevents the peers from
choosing SSLv2 as the protocol version.
.. versionadded:: 2.7.9
.. data:: OP_NO_SSLv3
Prevents an SSLv3 connection. This option is only applicable in
conjunction with :const:`PROTOCOL_SSLv23`. It prevents the peers from
choosing SSLv3 as the protocol version.
.. versionadded:: 2.7.9
.. data:: OP_NO_TLSv1
Prevents a TLSv1 connection. This option is only applicable in
conjunction with :const:`PROTOCOL_SSLv23`. It prevents the peers from
choosing TLSv1 as the protocol version.
.. versionadded:: 2.7.9
.. data:: OP_NO_TLSv1_1
Prevents a TLSv1.1 connection. This option is only applicable in conjunction
with :const:`PROTOCOL_SSLv23`. It prevents the peers from choosing TLSv1.1 as
the protocol version. Available only with openssl version 1.0.1+.
.. versionadded:: 2.7.9
.. data:: OP_NO_TLSv1_2
Prevents a TLSv1.2 connection. This option is only applicable in conjunction
with :const:`PROTOCOL_SSLv23`. It prevents the peers from choosing TLSv1.2 as
the protocol version. Available only with openssl version 1.0.1+.
.. versionadded:: 2.7.9
.. data:: OP_NO_TLSv1_3
Prevents a TLSv1.3 connection. This option is only applicable in conjunction
with :const:`PROTOCOL_TLS`. It prevents the peers from choosing TLSv1.3 as
the protocol version. TLS 1.3 is available with OpenSSL 1.1.1 or later.
When Python has been compiled against an older version of OpenSSL, the
flag defaults to *0*.
.. versionadded:: 2.7.15
.. data:: OP_CIPHER_SERVER_PREFERENCE
Use the server's cipher ordering preference, rather than the client's.
This option has no effect on client sockets and SSLv2 server sockets.
.. versionadded:: 2.7.9
.. data:: OP_SINGLE_DH_USE
Prevents re-use of the same DH key for distinct SSL sessions. This
improves forward secrecy but requires more computational resources.
This option only applies to server sockets.
.. versionadded:: 2.7.9
.. data:: OP_SINGLE_ECDH_USE
Prevents re-use of the same ECDH key for distinct SSL sessions. This
improves forward secrecy but requires more computational resources.
This option only applies to server sockets.
.. versionadded:: 2.7.9
.. data:: OP_ENABLE_MIDDLEBOX_COMPAT
Send dummy Change Cipher Spec (CCS) messages in TLS 1.3 handshake to make
a TLS 1.3 connection look more like a TLS 1.2 connection.
This option is only available with OpenSSL 1.1.1 and later.
.. versionadded:: 2.7.16
.. data:: OP_NO_COMPRESSION
Disable compression on the SSL channel. This is useful if the application
protocol supports its own compression scheme.
This option is only available with OpenSSL 1.0.0 and later.
.. versionadded:: 2.7.9
.. data:: HAS_ALPN
Whether the OpenSSL library has built-in support for the *Application-Layer
Protocol Negotiation* TLS extension as described in :rfc:`7301`.
.. versionadded:: 2.7.10
.. data:: HAS_ECDH
Whether the OpenSSL library has built-in support for Elliptic Curve-based
Diffie-Hellman key exchange. This should be true unless the feature was
explicitly disabled by the distributor.
.. versionadded:: 2.7.9
.. data:: HAS_SNI
Whether the OpenSSL library has built-in support for the *Server Name
Indication* extension (as defined in :rfc:`4366`).
.. versionadded:: 2.7.9
.. data:: HAS_NPN
Whether the OpenSSL library has built-in support for *Next Protocol
Negotiation* as described in the `NPN draft specification
<https://tools.ietf.org/html/draft-agl-tls-nextprotoneg>`_. When true,
you can use the :meth:`SSLContext.set_npn_protocols` method to advertise
which protocols you want to support.
.. versionadded:: 2.7.9
.. data:: HAS_TLSv1_3
Whether the OpenSSL library has built-in support for the TLS 1.3 protocol.
.. versionadded:: 2.7.15
.. data:: CHANNEL_BINDING_TYPES
List of supported TLS channel binding types. Strings in this list
can be used as arguments to :meth:`SSLSocket.get_channel_binding`.
.. versionadded:: 2.7.9
.. data:: OPENSSL_VERSION
The version string of the OpenSSL library loaded by the interpreter::
>>> ssl.OPENSSL_VERSION
'OpenSSL 0.9.8k 25 Mar 2009'
.. versionadded:: 2.7
.. data:: OPENSSL_VERSION_INFO
A tuple of five integers representing version information about the
OpenSSL library::
>>> ssl.OPENSSL_VERSION_INFO
(0, 9, 8, 11, 15)
.. versionadded:: 2.7
.. data:: OPENSSL_VERSION_NUMBER
The raw version number of the OpenSSL library, as a single integer::
>>> ssl.OPENSSL_VERSION_NUMBER
9470143L
>>> hex(ssl.OPENSSL_VERSION_NUMBER)
'0x9080bfL'
.. versionadded:: 2.7
.. data:: ALERT_DESCRIPTION_HANDSHAKE_FAILURE
ALERT_DESCRIPTION_INTERNAL_ERROR
ALERT_DESCRIPTION_*
Alert Descriptions from :rfc:`5246` and others. The `IANA TLS Alert Registry
<https://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-6>`_
contains this list and references to the RFCs where their meaning is defined.
Used as the return value of the callback function in
:meth:`SSLContext.set_servername_callback`.
.. versionadded:: 2.7.9
.. data:: Purpose.SERVER_AUTH
Option for :func:`create_default_context` and
:meth:`SSLContext.load_default_certs`. This value indicates that the
context may be used to authenticate Web servers (therefore, it will
be used to create client-side sockets).
.. versionadded:: 2.7.9
.. data:: Purpose.CLIENT_AUTH
Option for :func:`create_default_context` and
:meth:`SSLContext.load_default_certs`. This value indicates that the
context may be used to authenticate Web clients (therefore, it will
be used to create server-side sockets).
.. versionadded:: 2.7.9
SSL Sockets
-----------
SSL sockets provide the following methods of :ref:`socket-objects`:
- :meth:`~socket.socket.accept()`
- :meth:`~socket.socket.bind()`
- :meth:`~socket.socket.close()`
- :meth:`~socket.socket.connect()`
- :meth:`~socket.socket.fileno()`
- :meth:`~socket.socket.getpeername()`, :meth:`~socket.socket.getsockname()`
- :meth:`~socket.socket.getsockopt()`, :meth:`~socket.socket.setsockopt()`
- :meth:`~socket.socket.gettimeout()`, :meth:`~socket.socket.settimeout()`,
:meth:`~socket.socket.setblocking()`
- :meth:`~socket.socket.listen()`
- :meth:`~socket.socket.makefile()`
- :meth:`~socket.socket.recv()`, :meth:`~socket.socket.recv_into()`
(but passing a non-zero ``flags`` argument is not allowed)
- :meth:`~socket.socket.send()`, :meth:`~socket.socket.sendall()` (with
the same limitation)
- :meth:`~socket.socket.shutdown()`
However, since the SSL (and TLS) protocol has its own framing atop
of TCP, the SSL sockets abstraction can, in certain respects, diverge from
the specification of normal, OS-level sockets. See especially the
:ref:`notes on non-blocking sockets <ssl-nonblocking>`.
SSL sockets also have the following additional methods and attributes:
.. method:: SSLSocket.do_handshake()
Perform the SSL setup handshake.
.. versionchanged:: 2.7.9
The handshake method also performs :func:`match_hostname` when the
:attr:`~SSLContext.check_hostname` attribute of the socket's
:attr:`~SSLSocket.context` is true.
.. method:: SSLSocket.getpeercert(binary_form=False)
If there is no certificate for the peer on the other end of the connection,
return ``None``. If the SSL handshake hasn't been done yet, raise
:exc:`ValueError`.
If the ``binary_form`` parameter is :const:`False`, and a certificate was
received from the peer, this method returns a :class:`dict` instance. If the
certificate was not validated, the dict is empty. If the certificate was
validated, it returns a dict with several keys, amongst them ``subject``
(the principal for which the certificate was issued) and ``issuer``
(the principal issuing the certificate). If a certificate contains an
instance of the *Subject Alternative Name* extension (see :rfc:`3280`),
there will also be a ``subjectAltName`` key in the dictionary.
The ``subject`` and ``issuer`` fields are tuples containing the sequence
of relative distinguished names (RDNs) given in the certificate's data
structure for the respective fields, and each RDN is a sequence of
name-value pairs. Here is a real-world example::
{'issuer': ((('countryName', 'IL'),),
(('organizationName', 'StartCom Ltd.'),),
(('organizationalUnitName',
'Secure Digital Certificate Signing'),),
(('commonName',
'StartCom Class 2 Primary Intermediate Server CA'),)),
'notAfter': 'Nov 22 08:15:19 2013 GMT',
'notBefore': 'Nov 21 03:09:52 2011 GMT',
'serialNumber': '95F0',
'subject': ((('description', '571208-SLe257oHY9fVQ07Z'),),
(('countryName', 'US'),),
(('stateOrProvinceName', 'California'),),
(('localityName', 'San Francisco'),),
(('organizationName', 'Electronic Frontier Foundation, Inc.'),),
(('commonName', '*.eff.org'),),
(('emailAddress', 'hostmaster@eff.org'),)),
'subjectAltName': (('DNS', '*.eff.org'), ('DNS', 'eff.org')),
'version': 3}
.. note::
To validate a certificate for a particular service, you can use the
:func:`match_hostname` function.
If the ``binary_form`` parameter is :const:`True`, and a certificate was
provided, this method returns the DER-encoded form of the entire certificate
as a sequence of bytes, or :const:`None` if the peer did not provide a
certificate. Whether the peer provides a certificate depends on the SSL
socket's role:
* for a client SSL socket, the server will always provide a certificate,
regardless of whether validation was required;
* for a server SSL socket, the client will only provide a certificate
when requested by the server; therefore :meth:`getpeercert` will return
:const:`None` if you used :const:`CERT_NONE` (rather than
:const:`CERT_OPTIONAL` or :const:`CERT_REQUIRED`).
.. versionchanged:: 2.7.9
The returned dictionary includes additional items such as ``issuer`` and
``notBefore``. Additionall :exc:`ValueError` is raised when the handshake
isn't done. The returned dictionary includes additional X509v3 extension
items such as ``crlDistributionPoints``, ``caIssuers`` and ``OCSP`` URIs.
.. method:: SSLSocket.cipher()
Returns a three-value tuple containing the name of the cipher being used, the
version of the SSL protocol that defines its use, and the number of secret
bits being used. If no connection has been established, returns ``None``.
.. method:: SSLSocket.compression()
Return the compression algorithm being used as a string, or ``None``
if the connection isn't compressed.
If the higher-level protocol supports its own compression mechanism,
you can use :data:`OP_NO_COMPRESSION` to disable SSL-level compression.
.. versionadded:: 2.7.9
.. method:: SSLSocket.get_channel_binding(cb_type="tls-unique")
Get channel binding data for current connection, as a bytes object. Returns
``None`` if not connected or the handshake has not been completed.
The *cb_type* parameter allow selection of the desired channel binding
type. Valid channel binding types are listed in the
:data:`CHANNEL_BINDING_TYPES` list. Currently only the 'tls-unique' channel
binding, defined by :rfc:`5929`, is supported. :exc:`ValueError` will be
raised if an unsupported channel binding type is requested.
.. versionadded:: 2.7.9
.. method:: SSLSocket.selected_alpn_protocol()
Return the protocol that was selected during the TLS handshake. If
:meth:`SSLContext.set_alpn_protocols` was not called, if the other party does
not support ALPN, if this socket does not support any of the client's
proposed protocols, or if the handshake has not happened yet, ``None`` is
returned.
.. versionadded:: 2.7.10
.. method:: SSLSocket.selected_npn_protocol()
Return the higher-level protocol that was selected during the TLS/SSL
handshake. If :meth:`SSLContext.set_npn_protocols` was not called, or
if the other party does not support NPN, or if the handshake has not yet
happened, this will return ``None``.
.. versionadded:: 2.7.9
.. method:: SSLSocket.unwrap()
Performs the SSL shutdown handshake, which removes the TLS layer from the
underlying socket, and returns the underlying socket object. This can be
used to go from encrypted operation over a connection to unencrypted. The
returned socket should always be used for further communication with the
other side of the connection, rather than the original socket.
.. method:: SSLSocket.version()
Return the actual SSL protocol version negotiated by the connection
as a string, or ``None`` is no secure connection is established.
As of this writing, possible return values include ``"SSLv2"``,
``"SSLv3"``, ``"TLSv1"``, ``"TLSv1.1"`` and ``"TLSv1.2"``.
Recent OpenSSL versions may define more return values.
.. versionadded:: 2.7.9
.. attribute:: SSLSocket.context
The :class:`SSLContext` object this SSL socket is tied to. If the SSL
socket was created using the top-level :func:`wrap_socket` function
(rather than :meth:`SSLContext.wrap_socket`), this is a custom context
object created for this SSL socket.
.. versionadded:: 2.7.9
SSL Contexts
------------
.. versionadded:: 2.7.9
An SSL context holds various data longer-lived than single SSL connections,
such as SSL configuration options, certificate(s) and private key(s).
It also manages a cache of SSL sessions for server-side sockets, in order
to speed up repeated connections from the same clients.
.. class:: SSLContext(protocol)
Create a new SSL context. You must pass *protocol* which must be one
of the ``PROTOCOL_*`` constants defined in this module.
:data:`PROTOCOL_SSLv23` is currently recommended for maximum
interoperability.
.. seealso::
:func:`create_default_context` lets the :mod:`ssl` module choose
security settings for a given purpose.
.. versionchanged:: 2.7.16
The context is created with secure default values. The options
:data:`OP_NO_COMPRESSION`, :data:`OP_CIPHER_SERVER_PREFERENCE`,
:data:`OP_SINGLE_DH_USE`, :data:`OP_SINGLE_ECDH_USE`,
:data:`OP_NO_SSLv2` (except for :data:`PROTOCOL_SSLv2`),
and :data:`OP_NO_SSLv3` (except for :data:`PROTOCOL_SSLv3`) are
set by default. The initial cipher suite list contains only ``HIGH``
ciphers, no ``NULL`` ciphers and no ``MD5`` ciphers (except for
:data:`PROTOCOL_SSLv2`).
:class:`SSLContext` objects have the following methods and attributes:
.. method:: SSLContext.cert_store_stats()
Get statistics about quantities of loaded X.509 certificates, count of
X.509 certificates flagged as CA certificates and certificate revocation
lists as dictionary.
Example for a context with one CA cert and one other cert::
>>> context.cert_store_stats()
{'crl': 0, 'x509_ca': 1, 'x509': 2}
.. method:: SSLContext.load_cert_chain(certfile, keyfile=None, password=None)
Load a private key and the corresponding certificate. The *certfile*
string must be the path to a single file in PEM format containing the
certificate as well as any number of CA certificates needed to establish
the certificate's authenticity. The *keyfile* string, if present, must
point to a file containing the private key in. Otherwise the private
key will be taken from *certfile* as well. See the discussion of
:ref:`ssl-certificates` for more information on how the certificate
is stored in the *certfile*.
The *password* argument may be a function to call to get the password for
decrypting the private key. It will only be called if the private key is
encrypted and a password is necessary. It will be called with no arguments,
and it should return a string, bytes, or bytearray. If the return value is
a string it will be encoded as UTF-8 before using it to decrypt the key.
Alternatively a string, bytes, or bytearray value may be supplied directly
as the *password* argument. It will be ignored if the private key is not
encrypted and no password is needed.
If the *password* argument is not specified and a password is required,
OpenSSL's built-in password prompting mechanism will be used to
interactively prompt the user for a password.
An :class:`SSLError` is raised if the private key doesn't
match with the certificate.
.. method:: SSLContext.load_default_certs(purpose=Purpose.SERVER_AUTH)
Load a set of default "certification authority" (CA) certificates from
default locations. On Windows it loads CA certs from the ``CA`` and
``ROOT`` system stores. On other systems it calls
:meth:`SSLContext.set_default_verify_paths`. In the future the method may
load CA certificates from other locations, too.
The *purpose* flag specifies what kind of CA certificates are loaded. The
default settings :data:`Purpose.SERVER_AUTH` loads certificates, that are
flagged and trusted for TLS web server authentication (client side
sockets). :data:`Purpose.CLIENT_AUTH` loads CA certificates for client
certificate verification on the server side.
.. method:: SSLContext.load_verify_locations(cafile=None, capath=None, cadata=None)
Load a set of "certification authority" (CA) certificates used to validate
other peers' certificates when :data:`verify_mode` is other than
:data:`CERT_NONE`. At least one of *cafile* or *capath* must be specified.
This method can also load certification revocation lists (CRLs) in PEM or
DER format. In order to make use of CRLs, :attr:`SSLContext.verify_flags`
must be configured properly.
The *cafile* string, if present, is the path to a file of concatenated
CA certificates in PEM format. See the discussion of
:ref:`ssl-certificates` for more information about how to arrange the
certificates in this file.
The *capath* string, if present, is
the path to a directory containing several CA certificates in PEM format,
following an `OpenSSL specific layout
<https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_load_verify_locations.html>`_.
The *cadata* object, if present, is either an ASCII string of one or more
PEM-encoded certificates or a bytes-like object of DER-encoded
certificates. Like with *capath* extra lines around PEM-encoded
certificates are ignored but at least one certificate must be present.
.. method:: SSLContext.get_ca_certs(binary_form=False)
Get a list of loaded "certification authority" (CA) certificates. If the
``binary_form`` parameter is :const:`False` each list
entry is a dict like the output of :meth:`SSLSocket.getpeercert`. Otherwise
the method returns a list of DER-encoded certificates. The returned list
does not contain certificates from *capath* unless a certificate was
requested and loaded by a SSL connection.
.. note::
Certificates in a capath directory aren't loaded unless they have
been used at least once.
.. method:: SSLContext.set_default_verify_paths()
Load a set of default "certification authority" (CA) certificates from
a filesystem path defined when building the OpenSSL library. Unfortunately,
there's no easy way to know whether this method succeeds: no error is
returned if no certificates are to be found. When the OpenSSL library is
provided as part of the operating system, though, it is likely to be
configured properly.
.. method:: SSLContext.set_ciphers(ciphers)
Set the available ciphers for sockets created with this context.
It should be a string in the `OpenSSL cipher list format
<https://www.openssl.org/docs/manmaster/man1/ciphers.html>`_.
If no cipher can be selected (because compile-time options or other
configuration forbids use of all the specified ciphers), an
:class:`SSLError` will be raised.
.. note::
when connected, the :meth:`SSLSocket.cipher` method of SSL sockets will
give the currently selected cipher.
OpenSSL 1.1.1 has TLS 1.3 cipher suites enabled by default. The suites
cannot be disabled with :meth:`~SSLContext.set_ciphers`.
.. method:: SSLContext.set_alpn_protocols(protocols)
Specify which protocols the socket should advertise during the SSL/TLS
handshake. It should be a list of ASCII strings, like ``['http/1.1',
'spdy/2']``, ordered by preference. The selection of a protocol will happen
during the handshake, and will play out according to :rfc:`7301`. After a
successful handshake, the :meth:`SSLSocket.selected_alpn_protocol` method will
return the agreed-upon protocol.
This method will raise :exc:`NotImplementedError` if :data:`HAS_ALPN` is
False.
OpenSSL 1.1.0 to 1.1.0e will abort the handshake and raise :exc:`SSLError`
when both sides support ALPN but cannot agree on a protocol. 1.1.0f+
behaves like 1.0.2, :meth:`SSLSocket.selected_alpn_protocol` returns None.
.. versionadded:: 2.7.10
.. method:: SSLContext.set_npn_protocols(protocols)
Specify which protocols the socket should advertise during the SSL/TLS
handshake. It should be a list of strings, like ``['http/1.1', 'spdy/2']``,
ordered by preference. The selection of a protocol will happen during the
handshake, and will play out according to the `NPN draft specification
<https://tools.ietf.org/html/draft-agl-tls-nextprotoneg>`_. After a
successful handshake, the :meth:`SSLSocket.selected_npn_protocol` method will
return the agreed-upon protocol.
This method will raise :exc:`NotImplementedError` if :data:`HAS_NPN` is
False.
.. method:: SSLContext.set_servername_callback(server_name_callback)
Register a callback function that will be called after the TLS Client Hello
handshake message has been received by the SSL/TLS server when the TLS client
specifies a server name indication. The server name indication mechanism
is specified in :rfc:`6066` section 3 - Server Name Indication.
Only one callback can be set per ``SSLContext``. If *server_name_callback*
is ``None`` then the callback is disabled. Calling this function a
subsequent time will disable the previously registered callback.
The callback function, *server_name_callback*, will be called with three
arguments; the first being the :class:`ssl.SSLSocket`, the second is a string
that represents the server name that the client is intending to communicate
(or :const:`None` if the TLS Client Hello does not contain a server name)
and the third argument is the original :class:`SSLContext`. The server name
argument is the IDNA decoded server name.
A typical use of this callback is to change the :class:`ssl.SSLSocket`'s
:attr:`SSLSocket.context` attribute to a new object of type
:class:`SSLContext` representing a certificate chain that matches the server
name.
Due to the early negotiation phase of the TLS connection, only limited
methods and attributes are usable like
:meth:`SSLSocket.selected_alpn_protocol` and :attr:`SSLSocket.context`.
:meth:`SSLSocket.getpeercert`, :meth:`SSLSocket.getpeercert`,
:meth:`SSLSocket.cipher` and :meth:`SSLSocket.compress` methods require that
the TLS connection has progressed beyond the TLS Client Hello and therefore
will not contain return meaningful values nor can they be called safely.
The *server_name_callback* function must return ``None`` to allow the
TLS negotiation to continue. If a TLS failure is required, a constant
:const:`ALERT_DESCRIPTION_* <ALERT_DESCRIPTION_INTERNAL_ERROR>` can be
returned. Other return values will result in a TLS fatal error with
:const:`ALERT_DESCRIPTION_INTERNAL_ERROR`.
If there is an IDNA decoding error on the server name, the TLS connection
will terminate with an :const:`ALERT_DESCRIPTION_INTERNAL_ERROR` fatal TLS
alert message to the client.
If an exception is raised from the *server_name_callback* function the TLS
connection will terminate with a fatal TLS alert message
:const:`ALERT_DESCRIPTION_HANDSHAKE_FAILURE`.
This method will raise :exc:`NotImplementedError` if the OpenSSL library
had OPENSSL_NO_TLSEXT defined when it was built.
.. method:: SSLContext.load_dh_params(dhfile)
Load the key generation parameters for Diffie-Helman (DH) key exchange.
Using DH key exchange improves forward secrecy at the expense of
computational resources (both on the server and on the client).
The *dhfile* parameter should be the path to a file containing DH
parameters in PEM format.
This setting doesn't apply to client sockets. You can also use the
:data:`OP_SINGLE_DH_USE` option to further improve security.
.. method:: SSLContext.set_ecdh_curve(curve_name)
Set the curve name for Elliptic Curve-based Diffie-Hellman (ECDH) key
exchange. ECDH is significantly faster than regular DH while arguably
as secure. The *curve_name* parameter should be a string describing
a well-known elliptic curve, for example ``prime256v1`` for a widely
supported curve.
This setting doesn't apply to client sockets. You can also use the
:data:`OP_SINGLE_ECDH_USE` option to further improve security.
This method is not available if :data:`HAS_ECDH` is ``False``.
.. seealso::
`SSL/TLS & Perfect Forward Secrecy <http://vincent.bernat.im/en/blog/2011-ssl-perfect-forward-secrecy.html>`_
Vincent Bernat.
.. method:: SSLContext.wrap_socket(sock, server_side=False, \
do_handshake_on_connect=True, suppress_ragged_eofs=True, \
server_hostname=None)
Wrap an existing Python socket *sock* and return an :class:`SSLSocket`
object. *sock* must be a :data:`~socket.SOCK_STREAM` socket; other socket
types are unsupported.
The returned SSL socket is tied to the context, its settings and
certificates. The parameters *server_side*, *do_handshake_on_connect*
and *suppress_ragged_eofs* have the same meaning as in the top-level
:func:`wrap_socket` function.
On client connections, the optional parameter *server_hostname* specifies
the hostname of the service which we are connecting to. This allows a
single server to host multiple SSL-based services with distinct certificates,
quite similarly to HTTP virtual hosts. Specifying *server_hostname* will
raise a :exc:`ValueError` if *server_side* is true.
.. versionchanged:: 2.7.9
Always allow a server_hostname to be passed, even if OpenSSL does not
have SNI.
.. method:: SSLContext.session_stats()
Get statistics about the SSL sessions created or managed by this context.
A dictionary is returned which maps the names of each `piece of information
<https://www.openssl.org/docs/man1.1.0/ssl/SSL_CTX_sess_number.html>`_ to their
numeric values. For example, here is the total number of hits and misses
in the session cache since the context was created::
>>> stats = context.session_stats()
>>> stats['hits'], stats['misses']
(0, 0)
.. attribute:: SSLContext.check_hostname
Wether to match the peer cert's hostname with :func:`match_hostname` in
:meth:`SSLSocket.do_handshake`. The context's
:attr:`~SSLContext.verify_mode` must be set to :data:`CERT_OPTIONAL` or
:data:`CERT_REQUIRED`, and you must pass *server_hostname* to
:meth:`~SSLContext.wrap_socket` in order to match the hostname.
Example::
import socket, ssl
context = ssl.SSLContext(ssl.PROTOCOL_TLS)
context.verify_mode = ssl.CERT_REQUIRED
context.check_hostname = True
context.load_default_certs()
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
ssl_sock = context.wrap_socket(s, server_hostname='www.verisign.com')
ssl_sock.connect(('www.verisign.com', 443))
.. note::
This features requires OpenSSL 0.9.8f or newer.
.. attribute:: SSLContext.options
An integer representing the set of SSL options enabled on this context.
The default value is :data:`OP_ALL`, but you can specify other options
such as :data:`OP_NO_SSLv2` by ORing them together.
.. note::
With versions of OpenSSL older than 0.9.8m, it is only possible
to set options, not to clear them. Attempting to clear an option
(by resetting the corresponding bits) will raise a ``ValueError``.
.. attribute:: SSLContext.protocol
The protocol version chosen when constructing the context. This attribute
is read-only.
.. attribute:: SSLContext.verify_flags
The flags for certificate verification operations. You can set flags like
:data:`VERIFY_CRL_CHECK_LEAF` by ORing them together. By default OpenSSL
does neither require nor verify certificate revocation lists (CRLs).
Available only with openssl version 0.9.8+.
.. attribute:: SSLContext.verify_mode
Whether to try to verify other peers' certificates and how to behave
if verification fails. This attribute must be one of
:data:`CERT_NONE`, :data:`CERT_OPTIONAL` or :data:`CERT_REQUIRED`.
.. index:: single: certificates
.. index:: single: X509 certificate
.. _ssl-certificates:
Certificates
------------
Certificates in general are part of a public-key / private-key system. In this
system, each *principal*, (which may be a machine, or a person, or an
organization) is assigned a unique two-part encryption key. One part of the key
is public, and is called the *public key*; the other part is kept secret, and is
called the *private key*. The two parts are related, in that if you encrypt a
message with one of the parts, you can decrypt it with the other part, and
**only** with the other part.
A certificate contains information about two principals. It contains the name
of a *subject*, and the subject's public key. It also contains a statement by a
second principal, the *issuer*, that the subject is who they claim to be, and
that this is indeed the subject's public key. The issuer's statement is signed
with the issuer's private key, which only the issuer knows. However, anyone can
verify the issuer's statement by finding the issuer's public key, decrypting the
statement with it, and comparing it to the other information in the certificate.
The certificate also contains information about the time period over which it is
valid. This is expressed as two fields, called "notBefore" and "notAfter".
In the Python use of certificates, a client or server can use a certificate to
prove who they are. The other side of a network connection can also be required
to produce a certificate, and that certificate can be validated to the
satisfaction of the client or server that requires such validation. The
connection attempt can be set to raise an exception if the validation fails.
Validation is done automatically, by the underlying OpenSSL framework; the
application need not concern itself with its mechanics. But the application
does usually need to provide sets of certificates to allow this process to take
place.
Python uses files to contain certificates. They should be formatted as "PEM"
(see :rfc:`1422`), which is a base-64 encoded form wrapped with a header line
and a footer line::
-----BEGIN CERTIFICATE-----
... (certificate in base64 PEM encoding) ...
-----END CERTIFICATE-----
Certificate chains
^^^^^^^^^^^^^^^^^^
The Python files which contain certificates can contain a sequence of
certificates, sometimes called a *certificate chain*. This chain should start
with the specific certificate for the principal who "is" the client or server,
and then the certificate for the issuer of that certificate, and then the
certificate for the issuer of *that* certificate, and so on up the chain till
you get to a certificate which is *self-signed*, that is, a certificate which
has the same subject and issuer, sometimes called a *root certificate*. The
certificates should just be concatenated together in the certificate file. For
example, suppose we had a three certificate chain, from our server certificate
to the certificate of the certification authority that signed our server
certificate, to the root certificate of the agency which issued the
certification authority's certificate::
-----BEGIN CERTIFICATE-----
... (certificate for your server)...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
... (the certificate for the CA)...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
... (the root certificate for the CA's issuer)...
-----END CERTIFICATE-----
CA certificates
^^^^^^^^^^^^^^^
If you are going to require validation of the other side of the connection's
certificate, you need to provide a "CA certs" file, filled with the certificate
chains for each issuer you are willing to trust. Again, this file just contains
these chains concatenated together. For validation, Python will use the first
chain it finds in the file which matches. The platform's certificates file can
be used by calling :meth:`SSLContext.load_default_certs`, this is done
automatically with :func:`.create_default_context`.
Combined key and certificate
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Often the private key is stored in the same file as the certificate; in this
case, only the ``certfile`` parameter to :meth:`SSLContext.load_cert_chain`
and :func:`wrap_socket` needs to be passed. If the private key is stored
with the certificate, it should come before the first certificate in
the certificate chain::
-----BEGIN RSA PRIVATE KEY-----
... (private key in base64 encoding) ...
-----END RSA PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
... (certificate in base64 PEM encoding) ...
-----END CERTIFICATE-----
Self-signed certificates
^^^^^^^^^^^^^^^^^^^^^^^^
If you are going to create a server that provides SSL-encrypted connection
services, you will need to acquire a certificate for that service. There are
many ways of acquiring appropriate certificates, such as buying one from a
certification authority. Another common practice is to generate a self-signed
certificate. The simplest way to do this is with the OpenSSL package, using
something like the following::
% openssl req -new -x509 -days 365 -nodes -out cert.pem -keyout cert.pem
Generating a 1024 bit RSA private key
.......++++++
.............................++++++
writing new private key to 'cert.pem'
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:MyState
Locality Name (eg, city) []:Some City
Organization Name (eg, company) [Internet Widgits Pty Ltd]:My Organization, Inc.
Organizational Unit Name (eg, section) []:My Group
Common Name (eg, YOUR name) []:myserver.mygroup.myorganization.com
Email Address []:ops@myserver.mygroup.myorganization.com
%
The disadvantage of a self-signed certificate is that it is its own root
certificate, and no one else will have it in their cache of known (and trusted)
root certificates.
Examples
--------
Testing for SSL support
^^^^^^^^^^^^^^^^^^^^^^^
To test for the presence of SSL support in a Python installation, user code
should use the following idiom::
try:
import ssl
except ImportError:
pass
else:
... # do something that requires SSL support
Client-side operation
^^^^^^^^^^^^^^^^^^^^^
This example creates a SSL context with the recommended security settings
for client sockets, including automatic certificate verification::
>>> context = ssl.create_default_context()
If you prefer to tune security settings yourself, you might create
a context from scratch (but beware that you might not get the settings
right)::
>>> context = ssl.SSLContext(ssl.PROTOCOL_TLS)
>>> context.verify_mode = ssl.CERT_REQUIRED
>>> context.check_hostname = True
>>> context.load_verify_locations("/etc/ssl/certs/ca-bundle.crt")
(this snippet assumes your operating system places a bundle of all CA
certificates in ``/etc/ssl/certs/ca-bundle.crt``; if not, you'll get an
error and have to adjust the location)
When you use the context to connect to a server, :const:`CERT_REQUIRED`
validates the server certificate: it ensures that the server certificate
was signed with one of the CA certificates, and checks the signature for
correctness::
>>> conn = context.wrap_socket(socket.socket(socket.AF_INET),
... server_hostname="www.python.org")
>>> conn.connect(("www.python.org", 443))
You may then fetch the certificate::
>>> cert = conn.getpeercert()
Visual inspection shows that the certificate does identify the desired service
(that is, the HTTPS host ``www.python.org``)::
>>> pprint.pprint(cert)
{'OCSP': ('http://ocsp.digicert.com',),
'caIssuers': ('http://cacerts.digicert.com/DigiCertSHA2ExtendedValidationServerCA.crt',),
'crlDistributionPoints': ('http://crl3.digicert.com/sha2-ev-server-g1.crl',
'http://crl4.digicert.com/sha2-ev-server-g1.crl'),
'issuer': ((('countryName', 'US'),),
(('organizationName', 'DigiCert Inc'),),
(('organizationalUnitName', 'www.digicert.com'),),
(('commonName', 'DigiCert SHA2 Extended Validation Server CA'),)),
'notAfter': 'Sep 9 12:00:00 2016 GMT',
'notBefore': 'Sep 5 00:00:00 2014 GMT',
'serialNumber': '01BB6F00122B177F36CAB49CEA8B6B26',
'subject': ((('businessCategory', 'Private Organization'),),
(('1.3.6.1.4.1.311.60.2.1.3', 'US'),),
(('1.3.6.1.4.1.311.60.2.1.2', 'Delaware'),),
(('serialNumber', '3359300'),),
(('streetAddress', '16 Allen Rd'),),
(('postalCode', '03894-4801'),),
(('countryName', 'US'),),
(('stateOrProvinceName', 'NH'),),
(('localityName', 'Wolfeboro,'),),
(('organizationName', 'Python Software Foundation'),),
(('commonName', 'www.python.org'),)),
'subjectAltName': (('DNS', 'www.python.org'),
('DNS', 'python.org'),
('DNS', 'pypi.org'),
('DNS', 'docs.python.org'),
('DNS', 'testpypi.python.org'),
('DNS', 'bugs.python.org'),
('DNS', 'wiki.python.org'),
('DNS', 'hg.python.org'),
('DNS', 'mail.python.org'),
('DNS', 'packaging.python.org'),
('DNS', 'pythonhosted.org'),
('DNS', 'www.pythonhosted.org'),
('DNS', 'test.pythonhosted.org'),
('DNS', 'us.pycon.org'),
('DNS', 'id.python.org')),
'version': 3}
Now the SSL channel is established and the certificate verified, you can
proceed to talk with the server::
>>> conn.sendall(b"HEAD / HTTP/1.0\r\nHost: linuxfr.org\r\n\r\n")
>>> pprint.pprint(conn.recv(1024).split(b"\r\n"))
[b'HTTP/1.1 200 OK',
b'Date: Sat, 18 Oct 2014 18:27:20 GMT',
b'Server: nginx',
b'Content-Type: text/html; charset=utf-8',
b'X-Frame-Options: SAMEORIGIN',
b'Content-Length: 45679',
b'Accept-Ranges: bytes',
b'Via: 1.1 varnish',
b'Age: 2188',
b'X-Served-By: cache-lcy1134-LCY',
b'X-Cache: HIT',
b'X-Cache-Hits: 11',
b'Vary: Cookie',
b'Strict-Transport-Security: max-age=63072000; includeSubDomains',
b'Connection: close',
b'',
b'']
See the discussion of :ref:`ssl-security` below.
Server-side operation
^^^^^^^^^^^^^^^^^^^^^
For server operation, typically you'll need to have a server certificate, and
private key, each in a file. You'll first create a context holding the key
and the certificate, so that clients can check your authenticity. Then
you'll open a socket, bind it to a port, call :meth:`listen` on it, and start
waiting for clients to connect::
import socket, ssl
context = ssl.create_default_context(ssl.Purpose.CLIENT_AUTH)
context.load_cert_chain(certfile="mycertfile", keyfile="mykeyfile")
bindsocket = socket.socket()
bindsocket.bind(('myaddr.mydomain.com', 10023))
bindsocket.listen(5)
When a client connects, you'll call :meth:`accept` on the socket to get the
new socket from the other end, and use the context's :meth:`SSLContext.wrap_socket`
method to create a server-side SSL socket for the connection::
while True:
newsocket, fromaddr = bindsocket.accept()
connstream = context.wrap_socket(newsocket, server_side=True)
try:
deal_with_client(connstream)
finally:
connstream.shutdown(socket.SHUT_RDWR)
connstream.close()
Then you'll read data from the ``connstream`` and do something with it till you
are finished with the client (or the client is finished with you)::
def deal_with_client(connstream):
data = connstream.read()
# null data means the client is finished with us
while data:
if not do_something(connstream, data):
# we'll assume do_something returns False
# when we're finished with client
break
data = connstream.read()
# finished with client
And go back to listening for new client connections (of course, a real server
would probably handle each client connection in a separate thread, or put
the sockets in non-blocking mode and use an event loop).
.. _ssl-nonblocking:
Notes on non-blocking sockets
-----------------------------
When working with non-blocking sockets, there are several things you need
to be aware of:
- Calling :func:`~select.select` tells you that the OS-level socket can be
read from (or written to), but it does not imply that there is sufficient
data at the upper SSL layer. For example, only part of an SSL frame might
have arrived. Therefore, you must be ready to handle :meth:`SSLSocket.recv`
and :meth:`SSLSocket.send` failures, and retry after another call to
:func:`~select.select`.
- Conversely, since the SSL layer has its own framing, a SSL socket may
still have data available for reading without :func:`~select.select`
being aware of it. Therefore, you should first call
:meth:`SSLSocket.recv` to drain any potentially available data, and then
only block on a :func:`~select.select` call if still necessary.
(of course, similar provisions apply when using other primitives such as
:func:`~select.poll`, or those in the :mod:`selectors` module)
- The SSL handshake itself will be non-blocking: the
:meth:`SSLSocket.do_handshake` method has to be retried until it returns
successfully. Here is a synopsis using :func:`~select.select` to wait for
the socket's readiness::
while True:
try:
sock.do_handshake()
break
except ssl.SSLWantReadError:
select.select([sock], [], [])
except ssl.SSLWantWriteError:
select.select([], [sock], [])
.. _ssl-security:
Security considerations
-----------------------
Best defaults
^^^^^^^^^^^^^
For **client use**, if you don't have any special requirements for your
security policy, it is highly recommended that you use the
:func:`create_default_context` function to create your SSL context.
It will load the system's trusted CA certificates, enable certificate
validation and hostname checking, and try to choose reasonably secure
protocol and cipher settings.
If a client certificate is needed for the connection, it can be added with
:meth:`SSLContext.load_cert_chain`.
By contrast, if you create the SSL context by calling the :class:`SSLContext`
constructor yourself, it will not have certificate validation nor hostname
checking enabled by default. If you do so, please read the paragraphs below
to achieve a good security level.
Manual settings
^^^^^^^^^^^^^^^
Verifying certificates
''''''''''''''''''''''
When calling the :class:`SSLContext` constructor directly,
:const:`CERT_NONE` is the default. Since it does not authenticate the other
peer, it can be insecure, especially in client mode where most of time you
would like to ensure the authenticity of the server you're talking to.
Therefore, when in client mode, it is highly recommended to use
:const:`CERT_REQUIRED`. However, it is in itself not sufficient; you also
have to check that the server certificate, which can be obtained by calling
:meth:`SSLSocket.getpeercert`, matches the desired service. For many
protocols and applications, the service can be identified by the hostname;
in this case, the :func:`match_hostname` function can be used. This common
check is automatically performed when :attr:`SSLContext.check_hostname` is
enabled.
In server mode, if you want to authenticate your clients using the SSL layer
(rather than using a higher-level authentication mechanism), you'll also have
to specify :const:`CERT_REQUIRED` and similarly check the client certificate.
.. note::
In client mode, :const:`CERT_OPTIONAL` and :const:`CERT_REQUIRED` are
equivalent unless anonymous ciphers are enabled (they are disabled
by default).
Protocol versions
'''''''''''''''''
SSL versions 2 and 3 are considered insecure and are therefore dangerous to
use. If you want maximum compatibility between clients and servers, it is
recommended to use :const:`PROTOCOL_SSLv23` as the protocol version and then
disable SSLv2 and SSLv3 explicitly using the :data:`SSLContext.options`
attribute::
context = ssl.SSLContext(ssl.PROTOCOL_SSLv23)
context.options |= ssl.OP_NO_SSLv2
context.options |= ssl.OP_NO_SSLv3
The SSL context created above will only allow TLSv1 and later (if
supported by your system) connections.
Cipher selection
''''''''''''''''
If you have advanced security requirements, fine-tuning of the ciphers
enabled when negotiating a SSL session is possible through the
:meth:`SSLContext.set_ciphers` method. Starting from Python 2.7.9, the
ssl module disables certain weak ciphers by default, but you may want
to further restrict the cipher choice. Be sure to read OpenSSL's documentation
about the `cipher list format <https://www.openssl.org/docs/apps/ciphers.html#CIPHER-LIST-FORMAT>`_.
If you want to check which ciphers are enabled by a given cipher list, use the
``openssl ciphers`` command on your system.
Multi-processing
^^^^^^^^^^^^^^^^
If using this module as part of a multi-processed application (using,
for example the :mod:`multiprocessing` or :mod:`concurrent.futures` modules),
be aware that OpenSSL's internal random number generator does not properly
handle forked processes. Applications must change the PRNG state of the
parent process if they use any SSL feature with :func:`os.fork`. Any
successful call of :func:`~ssl.RAND_add`, :func:`~ssl.RAND_bytes` or
:func:`~ssl.RAND_pseudo_bytes` is sufficient.
.. ssl-libressl:
LibreSSL support
----------------
LibreSSL is a fork of OpenSSL 1.0.1. The ssl module has limited support for
LibreSSL. Some features are not available when the ssl module is compiled
with LibreSSL.
* LibreSSL >= 2.6.1 no longer supports NPN. The methods
:meth:`SSLContext.set_npn_protocols` and
:meth:`SSLSocket.selected_npn_protocol` are not available.
* :meth:`SSLContext.set_default_verify_paths` ignores the env vars
:envvar:`SSL_CERT_FILE` and :envvar:`SSL_CERT_PATH` although
:func:`get_default_verify_paths` still reports them.
.. seealso::
Class :class:`socket.socket`
Documentation of underlying :mod:`socket` class
`SSL/TLS Strong Encryption: An Introduction <https://httpd.apache.org/docs/trunk/en/ssl/ssl_intro.html>`_
Intro from the Apache webserver documentation
`RFC 1422: Privacy Enhancement for Internet Electronic Mail: Part II: Certificate-Based Key Management <https://www.ietf.org/rfc/rfc1422>`_
Steve Kent
`RFC 1750: Randomness Recommendations for Security <https://www.ietf.org/rfc/rfc1750>`_
D. Eastlake et. al.
`RFC 3280: Internet X.509 Public Key Infrastructure Certificate and CRL Profile <https://www.ietf.org/rfc/rfc3280>`_
Housley et. al.
`RFC 4366: Transport Layer Security (TLS) Extensions <https://www.ietf.org/rfc/rfc4366>`_
Blake-Wilson et. al.
`RFC 5246: The Transport Layer Security (TLS) Protocol Version 1.2 <https://tools.ietf.org/html/rfc5246>`_
T. Dierks et. al.
`RFC 6066: Transport Layer Security (TLS) Extensions <https://tools.ietf.org/html/rfc6066>`_
D. Eastlake
`IANA TLS: Transport Layer Security (TLS) Parameters <https://www.iana.org/assignments/tls-parameters/tls-parameters.xml>`_
IANA
`RFC 7525: Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS) <https://tools.ietf.org/html/rfc7525>`_
IETF
`Mozilla's Server Side TLS recommendations <https://wiki.mozilla.org/Security/Server_Side_TLS>`_
Mozilla
PK
%�\���b b " html/_sources/library/stat.rst.txtnu �[��� :mod:`stat` --- Interpreting :func:`~os.stat` results
=====================================================
.. module:: stat
:synopsis: Utilities for interpreting the results of os.stat(), os.lstat() and os.fstat().
.. sectionauthor:: Skip Montanaro <skip@automatrix.com>
**Source code:** :source:`Lib/stat.py`
--------------
The :mod:`stat` module defines constants and functions for interpreting the
results of :func:`os.stat`, :func:`os.fstat` and :func:`os.lstat` (if they
exist). For complete details about the :c:func:`stat`, :c:func:`fstat` and
:c:func:`lstat` calls, consult the documentation for your system.
The :mod:`stat` module defines the following functions to test for specific file
types:
.. function:: S_ISDIR(mode)
Return non-zero if the mode is from a directory.
.. function:: S_ISCHR(mode)
Return non-zero if the mode is from a character special device file.
.. function:: S_ISBLK(mode)
Return non-zero if the mode is from a block special device file.
.. function:: S_ISREG(mode)
Return non-zero if the mode is from a regular file.
.. function:: S_ISFIFO(mode)
Return non-zero if the mode is from a FIFO (named pipe).
.. function:: S_ISLNK(mode)
Return non-zero if the mode is from a symbolic link.
.. function:: S_ISSOCK(mode)
Return non-zero if the mode is from a socket.
Two additional functions are defined for more general manipulation of the file's
mode:
.. function:: S_IMODE(mode)
Return the portion of the file's mode that can be set by :func:`os.chmod`\
---that is, the file's permission bits, plus the sticky bit, set-group-id, and
set-user-id bits (on systems that support them).
.. function:: S_IFMT(mode)
Return the portion of the file's mode that describes the file type (used by the
:func:`S_IS\*` functions above).
Normally, you would use the :func:`os.path.is\*` functions for testing the type
of a file; the functions here are useful when you are doing multiple tests of
the same file and wish to avoid the overhead of the :c:func:`stat` system call
for each test. These are also useful when checking for information about a file
that isn't handled by :mod:`os.path`, like the tests for block and character
devices.
Example::
import os, sys
from stat import *
def walktree(top, callback):
'''recursively descend the directory tree rooted at top,
calling the callback function for each regular file'''
for f in os.listdir(top):
pathname = os.path.join(top, f)
mode = os.stat(pathname).st_mode
if S_ISDIR(mode):
# It's a directory, recurse into it
walktree(pathname, callback)
elif S_ISREG(mode):
# It's a file, call the callback function
callback(pathname)
else:
# Unknown file type, print a message
print 'Skipping %s' % pathname
def visitfile(file):
print 'visiting', file
if __name__ == '__main__':
walktree(sys.argv[1], visitfile)
All the variables below are simply symbolic indexes into the 10-tuple returned
by :func:`os.stat`, :func:`os.fstat` or :func:`os.lstat`.
.. data:: ST_MODE
Inode protection mode.
.. data:: ST_INO
Inode number.
.. data:: ST_DEV
Device inode resides on.
.. data:: ST_NLINK
Number of links to the inode.
.. data:: ST_UID
User id of the owner.
.. data:: ST_GID
Group id of the owner.
.. data:: ST_SIZE
Size in bytes of a plain file; amount of data waiting on some special files.
.. data:: ST_ATIME
Time of last access.
.. data:: ST_MTIME
Time of last modification.
.. data:: ST_CTIME
The "ctime" as reported by the operating system. On some systems (like Unix) is
the time of the last metadata change, and, on others (like Windows), is the
creation time (see platform documentation for details).
The interpretation of "file size" changes according to the file type. For plain
files this is the size of the file in bytes. For FIFOs and sockets under most
flavors of Unix (including Linux in particular), the "size" is the number of
bytes waiting to be read at the time of the call to :func:`os.stat`,
:func:`os.fstat`, or :func:`os.lstat`; this can sometimes be useful, especially
for polling one of these special files after a non-blocking open. The meaning
of the size field for other character and block devices varies more, depending
on the implementation of the underlying system call.
The variables below define the flags used in the :data:`ST_MODE` field.
Use of the functions above is more portable than use of the first set of flags:
.. data:: S_IFSOCK
Socket.
.. data:: S_IFLNK
Symbolic link.
.. data:: S_IFREG
Regular file.
.. data:: S_IFBLK
Block device.
.. data:: S_IFDIR
Directory.
.. data:: S_IFCHR
Character device.
.. data:: S_IFIFO
FIFO.
The following flags can also be used in the *mode* argument of :func:`os.chmod`:
.. data:: S_ISUID
Set UID bit.
.. data:: S_ISGID
Set-group-ID bit. This bit has several special uses. For a directory
it indicates that BSD semantics is to be used for that directory:
files created there inherit their group ID from the directory, not
from the effective group ID of the creating process, and directories
created there will also get the :data:`S_ISGID` bit set. For a
file that does not have the group execution bit (:data:`S_IXGRP`)
set, the set-group-ID bit indicates mandatory file/record locking
(see also :data:`S_ENFMT`).
.. data:: S_ISVTX
Sticky bit. When this bit is set on a directory it means that a file
in that directory can be renamed or deleted only by the owner of the
file, by the owner of the directory, or by a privileged process.
.. data:: S_IRWXU
Mask for file owner permissions.
.. data:: S_IRUSR
Owner has read permission.
.. data:: S_IWUSR
Owner has write permission.
.. data:: S_IXUSR
Owner has execute permission.
.. data:: S_IRWXG
Mask for group permissions.
.. data:: S_IRGRP
Group has read permission.
.. data:: S_IWGRP
Group has write permission.
.. data:: S_IXGRP
Group has execute permission.
.. data:: S_IRWXO
Mask for permissions for others (not in group).
.. data:: S_IROTH
Others have read permission.
.. data:: S_IWOTH
Others have write permission.
.. data:: S_IXOTH
Others have execute permission.
.. data:: S_ENFMT
System V file locking enforcement. This flag is shared with :data:`S_ISGID`:
file/record locking is enforced on files that do not have the group
execution bit (:data:`S_IXGRP`) set.
.. data:: S_IREAD
Unix V7 synonym for :data:`S_IRUSR`.
.. data:: S_IWRITE
Unix V7 synonym for :data:`S_IWUSR`.
.. data:: S_IEXEC
Unix V7 synonym for :data:`S_IXUSR`.
The following flags can be used in the *flags* argument of :func:`os.chflags`:
.. data:: UF_NODUMP
Do not dump the file.
.. data:: UF_IMMUTABLE
The file may not be changed.
.. data:: UF_APPEND
The file may only be appended to.
.. data:: UF_OPAQUE
The directory is opaque when viewed through a union stack.
.. data:: UF_NOUNLINK
The file may not be renamed or deleted.
.. data:: UF_COMPRESSED
The file is stored compressed (Mac OS X 10.6+).
.. data:: UF_HIDDEN
The file should not be displayed in a GUI (Mac OS X 10.5+).
.. data:: SF_ARCHIVED
The file may be archived.
.. data:: SF_IMMUTABLE
The file may not be changed.
.. data:: SF_APPEND
The file may only be appended to.
.. data:: SF_NOUNLINK
The file may not be renamed or deleted.
.. data:: SF_SNAPSHOT
The file is a snapshot file.
See the \*BSD or Mac OS systems man page :manpage:`chflags(2)` for more information.
PK
%�\�X.� % html/_sources/library/statvfs.rst.txtnu �[��� :mod:`statvfs` --- Constants used with :func:`os.statvfs`
=========================================================
.. module:: statvfs
:synopsis: Constants for interpreting the result of os.statvfs().
:deprecated:
.. deprecated:: 2.6
The :mod:`statvfs` module has been removed in Python 3.
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
The :mod:`statvfs` module defines constants so interpreting the result if
:func:`os.statvfs`, which returns a tuple, can be made without remembering
"magic numbers." Each of the constants defined in this module is the *index* of
the entry in the tuple returned by :func:`os.statvfs` that contains the
specified information.
.. data:: F_BSIZE
Preferred file system block size.
.. data:: F_FRSIZE
Fundamental file system block size.
.. data:: F_BLOCKS
Total number of blocks in the filesystem.
.. data:: F_BFREE
Total number of free blocks.
.. data:: F_BAVAIL
Free blocks available to non-super user.
.. data:: F_FILES
Total number of file nodes.
.. data:: F_FFREE
Total number of free file nodes.
.. data:: F_FAVAIL
Free nodes available to non-super user.
.. data:: F_FLAG
Flags. System dependent: see :c:func:`statvfs` man page.
.. data:: F_NAMEMAX
Maximum file name length.
PK
%�\��#�,� ,� & html/_sources/library/stdtypes.rst.txtnu �[��� .. XXX: reference/datamodel and this have quite a few overlaps!
.. _bltin-types:
**************
Built-in Types
**************
The following sections describe the standard types that are built into the
interpreter.
.. note::
Historically (until release 2.2), Python's built-in types have differed from
user-defined types because it was not possible to use the built-in types as the
basis for object-oriented inheritance. This limitation no longer
exists.
.. index:: pair: built-in; types
The principal built-in types are numerics, sequences, mappings, files, classes,
instances and exceptions.
.. index:: statement: print
Some operations are supported by several object types; in particular,
practically all objects can be compared, tested for truth value, and converted
to a string (with the :ref:`repr() <func-repr>` function or the slightly different
:func:`str` function). The latter function is implicitly used when an object is
written by the :func:`print` function.
.. _truth:
Truth Value Testing
===================
.. index::
statement: if
statement: while
pair: truth; value
pair: Boolean; operations
single: false
Any object can be tested for truth value, for use in an :keyword:`if` or
:keyword:`while` condition or as operand of the Boolean operations below. The
following values are considered false:
.. index:: single: None (Built-in object)
* ``None``
.. index:: single: False (Built-in object)
* ``False``
* zero of any numeric type, for example, ``0``, ``0L``, ``0.0``, ``0j``.
* any empty sequence, for example, ``''``, ``()``, ``[]``.
* any empty mapping, for example, ``{}``.
* instances of user-defined classes, if the class defines a :meth:`__nonzero__`
or :meth:`__len__` method, when that method returns the integer zero or
:class:`bool` value ``False``. [1]_
.. index:: single: true
All other values are considered true --- so objects of many types are always
true.
.. index::
operator: or
operator: and
single: False
single: True
Operations and built-in functions that have a Boolean result always return ``0``
or ``False`` for false and ``1`` or ``True`` for true, unless otherwise stated.
(Important exception: the Boolean operations ``or`` and ``and`` always return
one of their operands.)
.. _boolean:
Boolean Operations --- :keyword:`and`, :keyword:`or`, :keyword:`not`
====================================================================
.. index:: pair: Boolean; operations
These are the Boolean operations, ordered by ascending priority:
+-------------+---------------------------------+-------+
| Operation | Result | Notes |
+=============+=================================+=======+
| ``x or y`` | if *x* is false, then *y*, else | \(1) |
| | *x* | |
+-------------+---------------------------------+-------+
| ``x and y`` | if *x* is false, then *x*, else | \(2) |
| | *y* | |
+-------------+---------------------------------+-------+
| ``not x`` | if *x* is false, then ``True``, | \(3) |
| | else ``False`` | |
+-------------+---------------------------------+-------+
.. index::
operator: and
operator: or
operator: not
Notes:
(1)
This is a short-circuit operator, so it only evaluates the second
argument if the first one is false.
(2)
This is a short-circuit operator, so it only evaluates the second
argument if the first one is true.
(3)
``not`` has a lower priority than non-Boolean operators, so ``not a == b`` is
interpreted as ``not (a == b)``, and ``a == not b`` is a syntax error.
.. _stdcomparisons:
Comparisons
===========
.. index::
pair: chaining; comparisons
pair: operator; comparison
operator: ==
operator: <
operator: <=
operator: >
operator: >=
operator: !=
operator: is
operator: is not
Comparison operations are supported by all objects. They all have the same
priority (which is higher than that of the Boolean operations). Comparisons can
be chained arbitrarily; for example, ``x < y <= z`` is equivalent to ``x < y and
y <= z``, except that *y* is evaluated only once (but in both cases *z* is not
evaluated at all when ``x < y`` is found to be false).
This table summarizes the comparison operations:
+------------+-------------------------+-------+
| Operation | Meaning | Notes |
+============+=========================+=======+
| ``<`` | strictly less than | |
+------------+-------------------------+-------+
| ``<=`` | less than or equal | |
+------------+-------------------------+-------+
| ``>`` | strictly greater than | |
+------------+-------------------------+-------+
| ``>=`` | greater than or equal | |
+------------+-------------------------+-------+
| ``==`` | equal | |
+------------+-------------------------+-------+
| ``!=`` | not equal | \(1) |
+------------+-------------------------+-------+
| ``is`` | object identity | |
+------------+-------------------------+-------+
| ``is not`` | negated object identity | |
+------------+-------------------------+-------+
Notes:
(1)
``!=`` can also be written ``<>``, but this is an obsolete usage
kept for backwards compatibility only. New code should always use
``!=``.
.. index::
pair: object; numeric
pair: objects; comparing
Objects of different types, except different numeric types and different string
types, never compare equal; such objects are ordered consistently but
arbitrarily (so that sorting a heterogeneous array yields a consistent result).
Furthermore, some types (for example, file objects) support only a degenerate
notion of comparison where any two objects of that type are unequal. Again,
such objects are ordered arbitrarily but consistently. The ``<``, ``<=``, ``>``
and ``>=`` operators will raise a :exc:`TypeError` exception when any operand is
a complex number.
.. index::
single: __cmp__() (instance method)
single: __eq__() (instance method)
single: __ne__() (instance method)
single: __lt__() (instance method)
single: __le__() (instance method)
single: __gt__() (instance method)
single: __ge__() (instance method)
Non-identical instances of a class normally compare as non-equal unless the
class defines the :meth:`__eq__` method or the :meth:`__cmp__` method.
Instances of a class cannot be ordered with respect to other instances of the
same class, or other types of object, unless the class defines either enough of
the rich comparison methods (:meth:`__lt__`, :meth:`__le__`, :meth:`__gt__`, and
:meth:`__ge__`) or the :meth:`__cmp__` method.
.. impl-detail::
Objects of different types except numbers are ordered by their type names;
objects of the same types that don't support proper comparison are ordered by
their address.
.. index::
operator: in
operator: not in
Two more operations with the same syntactic priority, ``in`` and ``not in``, are
supported only by sequence types (below).
.. _typesnumeric:
Numeric Types --- :class:`int`, :class:`float`, :class:`long`, :class:`complex`
===============================================================================
.. index::
object: numeric
object: Boolean
object: integer
object: long integer
object: floating point
object: complex number
pair: C; language
There are four distinct numeric types: :dfn:`plain integers`, :dfn:`long
integers`, :dfn:`floating point numbers`, and :dfn:`complex numbers`. In
addition, Booleans are a subtype of plain integers. Plain integers (also just
called :dfn:`integers`) are implemented using :c:type:`long` in C, which gives
them at least 32 bits of precision (``sys.maxint`` is always set to the maximum
plain integer value for the current platform, the minimum value is
``-sys.maxint - 1``). Long integers have unlimited precision. Floating point
numbers are usually implemented using :c:type:`double` in C; information about
the precision and internal representation of floating point numbers for the
machine on which your program is running is available in
:data:`sys.float_info`. Complex numbers have a real and imaginary part, which
are each a floating point number. To extract these parts from a complex number
*z*, use ``z.real`` and ``z.imag``. (The standard library includes additional
numeric types, :mod:`fractions` that hold rationals, and :mod:`decimal` that
hold floating-point numbers with user-definable precision.)
.. index::
pair: numeric; literals
pair: integer; literals
triple: long; integer; literals
pair: floating point; literals
pair: complex number; literals
pair: hexadecimal; literals
pair: octal; literals
Numbers are created by numeric literals or as the result of built-in functions
and operators. Unadorned integer literals (including binary, hex, and octal
numbers) yield plain integers unless the value they denote is too large to be
represented as a plain integer, in which case they yield a long integer.
Integer literals with an ``'L'`` or ``'l'`` suffix yield long integers (``'L'``
is preferred because ``1l`` looks too much like eleven!). Numeric literals
containing a decimal point or an exponent sign yield floating point numbers.
Appending ``'j'`` or ``'J'`` to a numeric literal yields an imaginary number
(a complex number with a zero real part) which you can add to an integer or
float to get a complex number with real and imaginary parts.
.. index::
single: arithmetic
builtin: int
builtin: long
builtin: float
builtin: complex
operator: +
operator: -
operator: *
operator: /
operator: //
operator: %
operator: **
Python fully supports mixed arithmetic: when a binary arithmetic operator has
operands of different numeric types, the operand with the "narrower" type is
widened to that of the other, where plain integer is narrower than long integer
is narrower than floating point is narrower than complex. Comparisons between
numbers of mixed type use the same rule. [2]_ The constructors :func:`int`,
:func:`long`, :func:`float`, and :func:`complex` can be used to produce numbers
of a specific type.
All built-in numeric types support the following operations. See
:ref:`power` and later sections for the operators' priorities.
+--------------------+---------------------------------+--------+
| Operation | Result | Notes |
+====================+=================================+========+
| ``x + y`` | sum of *x* and *y* | |
+--------------------+---------------------------------+--------+
| ``x - y`` | difference of *x* and *y* | |
+--------------------+---------------------------------+--------+
| ``x * y`` | product of *x* and *y* | |
+--------------------+---------------------------------+--------+
| ``x / y`` | quotient of *x* and *y* | \(1) |
+--------------------+---------------------------------+--------+
| ``x // y`` | (floored) quotient of *x* and | (4)(5) |
| | *y* | |
+--------------------+---------------------------------+--------+
| ``x % y`` | remainder of ``x / y`` | \(4) |
+--------------------+---------------------------------+--------+
| ``-x`` | *x* negated | |
+--------------------+---------------------------------+--------+
| ``+x`` | *x* unchanged | |
+--------------------+---------------------------------+--------+
| ``abs(x)`` | absolute value or magnitude of | \(3) |
| | *x* | |
+--------------------+---------------------------------+--------+
| ``int(x)`` | *x* converted to integer | \(2) |
+--------------------+---------------------------------+--------+
| ``long(x)`` | *x* converted to long integer | \(2) |
+--------------------+---------------------------------+--------+
| ``float(x)`` | *x* converted to floating point | \(6) |
+--------------------+---------------------------------+--------+
| ``complex(re,im)`` | a complex number with real part | |
| | *re*, imaginary part *im*. | |
| | *im* defaults to zero. | |
+--------------------+---------------------------------+--------+
| ``c.conjugate()`` | conjugate of the complex number | |
| | *c*. (Identity on real numbers) | |
+--------------------+---------------------------------+--------+
| ``divmod(x, y)`` | the pair ``(x // y, x % y)`` | (3)(4) |
+--------------------+---------------------------------+--------+
| ``pow(x, y)`` | *x* to the power *y* | (3)(7) |
+--------------------+---------------------------------+--------+
| ``x ** y`` | *x* to the power *y* | \(7) |
+--------------------+---------------------------------+--------+
.. index::
triple: operations on; numeric; types
single: conjugate() (complex number method)
Notes:
(1)
.. index::
pair: integer; division
triple: long; integer; division
For (plain or long) integer division, the result is an integer. The result is
always rounded towards minus infinity: 1/2 is 0, (-1)/2 is -1, 1/(-2) is -1, and
(-1)/(-2) is 0. Note that the result is a long integer if either operand is a
long integer, regardless of the numeric value.
(2)
.. index::
module: math
single: floor() (in module math)
single: ceil() (in module math)
single: trunc() (in module math)
pair: numeric; conversions
Conversion from floats using :func:`int` or :func:`long` truncates toward
zero like the related function, :func:`math.trunc`. Use the function
:func:`math.floor` to round downward and :func:`math.ceil` to round
upward.
(3)
See :ref:`built-in-funcs` for a full description.
(4)
.. deprecated:: 2.3
The floor division operator, the modulo operator, and the :func:`divmod`
function are no longer defined for complex numbers. Instead, convert to
a floating point number using the :func:`abs` function if appropriate.
(5)
Also referred to as integer division. The resultant value is a whole integer,
though the result's type is not necessarily int.
(6)
float also accepts the strings "nan" and "inf" with an optional prefix "+"
or "-" for Not a Number (NaN) and positive or negative infinity.
.. versionadded:: 2.6
(7)
Python defines ``pow(0, 0)`` and ``0 ** 0`` to be ``1``, as is common for
programming languages.
All :class:`numbers.Real` types (:class:`int`, :class:`long`, and
:class:`float`) also include the following operations:
+--------------------+---------------------------------------------+
| Operation | Result |
+====================+=============================================+
| :func:`math.trunc(\| *x* truncated to :class:`~numbers.Integral` |
| x) <math.trunc>` | |
+--------------------+---------------------------------------------+
| :func:`round(x[, | *x* rounded to *n* digits, |
| n]) <round>` | rounding ties away from zero. If *n* |
| | is omitted, it defaults to 0. |
+--------------------+---------------------------------------------+
| :func:`math.floor(\| the greatest integer as a float <= *x* |
| x) <math.floor>` | |
+--------------------+---------------------------------------------+
| :func:`math.ceil(x)| the least integer as a float >= *x* |
| <math.ceil>` | |
+--------------------+---------------------------------------------+
.. XXXJH exceptions: overflow (when? what operations?) zerodivision
.. _bitstring-ops:
Bitwise Operations on Integer Types
--------------------------------------
.. index::
triple: operations on; integer; types
pair: bitwise; operations
pair: shifting; operations
pair: masking; operations
operator: |
operator: ^
operator: &
operator: <<
operator: >>
operator: ~
Bitwise operations only make sense for integers. Negative numbers are treated
as their 2's complement value (this assumes a sufficiently large number of bits
that no overflow occurs during the operation).
The priorities of the binary bitwise operations are all lower than the numeric
operations and higher than the comparisons; the unary operation ``~`` has the
same priority as the other unary numeric operations (``+`` and ``-``).
This table lists the bitwise operations sorted in ascending priority:
+------------+--------------------------------+----------+
| Operation | Result | Notes |
+============+================================+==========+
| ``x | y`` | bitwise :dfn:`or` of *x* and | |
| | *y* | |
+------------+--------------------------------+----------+
| ``x ^ y`` | bitwise :dfn:`exclusive or` of | |
| | *x* and *y* | |
+------------+--------------------------------+----------+
| ``x & y`` | bitwise :dfn:`and` of *x* and | |
| | *y* | |
+------------+--------------------------------+----------+
| ``x << n`` | *x* shifted left by *n* bits | (1)(2) |
+------------+--------------------------------+----------+
| ``x >> n`` | *x* shifted right by *n* bits | (1)(3) |
+------------+--------------------------------+----------+
| ``~x`` | the bits of *x* inverted | |
+------------+--------------------------------+----------+
Notes:
(1)
Negative shift counts are illegal and cause a :exc:`ValueError` to be raised.
(2)
A left shift by *n* bits is equivalent to multiplication by ``pow(2, n)``. A
long integer is returned if the result exceeds the range of plain integers.
(3)
A right shift by *n* bits is equivalent to division by ``pow(2, n)``.
Additional Methods on Integer Types
-----------------------------------
The integer types implement the :class:`numbers.Integral` :term:`abstract base
class`. In addition, they provide one more method:
.. method:: int.bit_length()
.. method:: long.bit_length()
Return the number of bits necessary to represent an integer in binary,
excluding the sign and leading zeros::
>>> n = -37
>>> bin(n)
'-0b100101'
>>> n.bit_length()
6
More precisely, if ``x`` is nonzero, then ``x.bit_length()`` is the
unique positive integer ``k`` such that ``2**(k-1) <= abs(x) < 2**k``.
Equivalently, when ``abs(x)`` is small enough to have a correctly
rounded logarithm, then ``k = 1 + int(log(abs(x), 2))``.
If ``x`` is zero, then ``x.bit_length()`` returns ``0``.
Equivalent to::
def bit_length(self):
s = bin(self) # binary representation: bin(-37) --> '-0b100101'
s = s.lstrip('-0b') # remove leading zeros and minus sign
return len(s) # len('100101') --> 6
.. versionadded:: 2.7
Additional Methods on Float
---------------------------
The float type implements the :class:`numbers.Real` :term:`abstract base
class`. float also has the following additional methods.
.. method:: float.as_integer_ratio()
Return a pair of integers whose ratio is exactly equal to the
original float and with a positive denominator. Raises
:exc:`OverflowError` on infinities and a :exc:`ValueError` on
NaNs.
.. versionadded:: 2.6
.. method:: float.is_integer()
Return ``True`` if the float instance is finite with integral
value, and ``False`` otherwise::
>>> (-2.0).is_integer()
True
>>> (3.2).is_integer()
False
.. versionadded:: 2.6
Two methods support conversion to
and from hexadecimal strings. Since Python's floats are stored
internally as binary numbers, converting a float to or from a
*decimal* string usually involves a small rounding error. In
contrast, hexadecimal strings allow exact representation and
specification of floating-point numbers. This can be useful when
debugging, and in numerical work.
.. method:: float.hex()
Return a representation of a floating-point number as a hexadecimal
string. For finite floating-point numbers, this representation
will always include a leading ``0x`` and a trailing ``p`` and
exponent.
.. versionadded:: 2.6
.. method:: float.fromhex(s)
Class method to return the float represented by a hexadecimal
string *s*. The string *s* may have leading and trailing
whitespace.
.. versionadded:: 2.6
Note that :meth:`float.hex` is an instance method, while
:meth:`float.fromhex` is a class method.
A hexadecimal string takes the form::
[sign] ['0x'] integer ['.' fraction] ['p' exponent]
where the optional ``sign`` may by either ``+`` or ``-``, ``integer``
and ``fraction`` are strings of hexadecimal digits, and ``exponent``
is a decimal integer with an optional leading sign. Case is not
significant, and there must be at least one hexadecimal digit in
either the integer or the fraction. This syntax is similar to the
syntax specified in section 6.4.4.2 of the C99 standard, and also to
the syntax used in Java 1.5 onwards. In particular, the output of
:meth:`float.hex` is usable as a hexadecimal floating-point literal in
C or Java code, and hexadecimal strings produced by C's ``%a`` format
character or Java's ``Double.toHexString`` are accepted by
:meth:`float.fromhex`.
Note that the exponent is written in decimal rather than hexadecimal,
and that it gives the power of 2 by which to multiply the coefficient.
For example, the hexadecimal string ``0x3.a7p10`` represents the
floating-point number ``(3 + 10./16 + 7./16**2) * 2.0**10``, or
``3740.0``::
>>> float.fromhex('0x3.a7p10')
3740.0
Applying the reverse conversion to ``3740.0`` gives a different
hexadecimal string representing the same number::
>>> float.hex(3740.0)
'0x1.d380000000000p+11'
.. _typeiter:
Iterator Types
==============
.. versionadded:: 2.2
.. index::
single: iterator protocol
single: protocol; iterator
single: sequence; iteration
single: container; iteration over
Python supports a concept of iteration over containers. This is implemented
using two distinct methods; these are used to allow user-defined classes to
support iteration. Sequences, described below in more detail, always support
the iteration methods.
One method needs to be defined for container objects to provide iteration
support:
.. XXX duplicated in reference/datamodel!
.. method:: container.__iter__()
Return an iterator object. The object is required to support the iterator
protocol described below. If a container supports different types of
iteration, additional methods can be provided to specifically request
iterators for those iteration types. (An example of an object supporting
multiple forms of iteration would be a tree structure which supports both
breadth-first and depth-first traversal.) This method corresponds to the
:c:member:`~PyTypeObject.tp_iter` slot of the type structure for Python objects in the Python/C
API.
The iterator objects themselves are required to support the following two
methods, which together form the :dfn:`iterator protocol`:
.. method:: iterator.__iter__()
Return the iterator object itself. This is required to allow both containers
and iterators to be used with the :keyword:`for` and :keyword:`in` statements.
This method corresponds to the :c:member:`~PyTypeObject.tp_iter` slot of the type structure for
Python objects in the Python/C API.
.. method:: iterator.next()
Return the next item from the container. If there are no further items, raise
the :exc:`StopIteration` exception. This method corresponds to the
:c:member:`~PyTypeObject.tp_iternext` slot of the type structure for Python objects in the
Python/C API.
Python defines several iterator objects to support iteration over general and
specific sequence types, dictionaries, and other more specialized forms. The
specific types are not important beyond their implementation of the iterator
protocol.
The intention of the protocol is that once an iterator's :meth:`~iterator.next` method
raises :exc:`StopIteration`, it will continue to do so on subsequent calls.
Implementations that do not obey this property are deemed broken. (This
constraint was added in Python 2.3; in Python 2.2, various iterators are broken
according to this rule.)
.. _generator-types:
Generator Types
---------------
Python's :term:`generator`\s provide a convenient way to implement the iterator
protocol. If a container object's :meth:`__iter__` method is implemented as a
generator, it will automatically return an iterator object (technically, a
generator object) supplying the :meth:`~iterator.__iter__` and
:meth:`~iterator.next` methods. More information about generators can be found
in :ref:`the documentation for the yield expression <yieldexpr>`.
.. _typesseq:
Sequence Types --- :class:`str`, :class:`unicode`, :class:`list`, :class:`tuple`, :class:`bytearray`, :class:`buffer`, :class:`xrange`
======================================================================================================================================
There are seven sequence types: strings, Unicode strings, lists, tuples,
bytearrays, buffers, and xrange objects.
For other containers see the built in :class:`dict` and :class:`set` classes,
and the :mod:`collections` module.
.. index::
object: sequence
object: string
object: Unicode
object: tuple
object: list
object: bytearray
object: buffer
object: xrange
String literals are written in single or double quotes: ``'xyzzy'``,
``"frobozz"``. See :ref:`strings` for more about string literals.
Unicode strings are much like strings, but are specified in the syntax
using a preceding ``'u'`` character: ``u'abc'``, ``u"def"``. In addition
to the functionality described here, there are also string-specific
methods described in the :ref:`string-methods` section. Lists are
constructed with square brackets, separating items with commas: ``[a, b, c]``.
Tuples are constructed by the comma operator (not within square
brackets), with or without enclosing parentheses, but an empty tuple
must have the enclosing parentheses, such as ``a, b, c`` or ``()``. A
single item tuple must have a trailing comma, such as ``(d,)``.
Bytearray objects are created with the built-in function :func:`bytearray`.
Buffer objects are not directly supported by Python syntax, but can be created
by calling the built-in function :func:`buffer`. They don't support
concatenation or repetition.
Objects of type xrange are similar to buffers in that there is no specific syntax to
create them, but they are created using the :func:`xrange` function. They don't
support slicing, concatenation or repetition, and using ``in``, ``not in``,
:func:`min` or :func:`max` on them is inefficient.
Most sequence types support the following operations. The ``in`` and ``not in``
operations have the same priorities as the comparison operations. The ``+`` and
``*`` operations have the same priority as the corresponding numeric operations.
[3]_ Additional methods are provided for :ref:`typesseq-mutable`.
This table lists the sequence operations sorted in ascending priority.
In the table, *s* and *t* are sequences of the same type; *n*, *i* and *j* are integers:
+------------------+--------------------------------+----------+
| Operation | Result | Notes |
+==================+================================+==========+
| ``x in s`` | ``True`` if an item of *s* is | \(1) |
| | equal to *x*, else ``False`` | |
+------------------+--------------------------------+----------+
| ``x not in s`` | ``False`` if an item of *s* is | \(1) |
| | equal to *x*, else ``True`` | |
+------------------+--------------------------------+----------+
| ``s + t`` | the concatenation of *s* and | \(6) |
| | *t* | |
+------------------+--------------------------------+----------+
| ``s * n, n * s`` | equivalent to adding *s* to | \(2) |
| | itself *n* times | |
+------------------+--------------------------------+----------+
| ``s[i]`` | *i*\ th item of *s*, origin 0 | \(3) |
+------------------+--------------------------------+----------+
| ``s[i:j]`` | slice of *s* from *i* to *j* | (3)(4) |
+------------------+--------------------------------+----------+
| ``s[i:j:k]`` | slice of *s* from *i* to *j* | (3)(5) |
| | with step *k* | |
+------------------+--------------------------------+----------+
| ``len(s)`` | length of *s* | |
+------------------+--------------------------------+----------+
| ``min(s)`` | smallest item of *s* | |
+------------------+--------------------------------+----------+
| ``max(s)`` | largest item of *s* | |
+------------------+--------------------------------+----------+
| ``s.index(x)`` | index of the first occurrence | |
| | of *x* in *s* | |
+------------------+--------------------------------+----------+
| ``s.count(x)`` | total number of occurrences of | |
| | *x* in *s* | |
+------------------+--------------------------------+----------+
Sequence types also support comparisons. In particular, tuples and lists
are compared lexicographically by comparing corresponding
elements. This means that to compare equal, every element must compare
equal and the two sequences must be of the same type and have the same
length. (For full details see :ref:`comparisons` in the language
reference.)
.. index::
triple: operations on; sequence; types
builtin: len
builtin: min
builtin: max
pair: concatenation; operation
pair: repetition; operation
pair: subscript; operation
pair: slice; operation
pair: extended slice; operation
operator: in
operator: not in
Notes:
(1)
When *s* is a string or Unicode string object the ``in`` and ``not in``
operations act like a substring test. In Python versions before 2.3, *x* had to
be a string of length 1. In Python 2.3 and beyond, *x* may be a string of any
length.
(2)
Values of *n* less than ``0`` are treated as ``0`` (which yields an empty
sequence of the same type as *s*). Note that items in the sequence *s*
are not copied; they are referenced multiple times. This often haunts
new Python programmers; consider:
>>> lists = [[]] * 3
>>> lists
[[], [], []]
>>> lists[0].append(3)
>>> lists
[[3], [3], [3]]
What has happened is that ``[[]]`` is a one-element list containing an empty
list, so all three elements of ``[[]] * 3`` are references to this single empty
list. Modifying any of the elements of ``lists`` modifies this single list.
You can create a list of different lists this way:
>>> lists = [[] for i in range(3)]
>>> lists[0].append(3)
>>> lists[1].append(5)
>>> lists[2].append(7)
>>> lists
[[3], [5], [7]]
Further explanation is available in the FAQ entry
:ref:`faq-multidimensional-list`.
(3)
If *i* or *j* is negative, the index is relative to the end of sequence *s*:
``len(s) + i`` or ``len(s) + j`` is substituted. But note that ``-0`` is still
``0``.
(4)
The slice of *s* from *i* to *j* is defined as the sequence of items with index
*k* such that ``i <= k < j``. If *i* or *j* is greater than ``len(s)``, use
``len(s)``. If *i* is omitted or ``None``, use ``0``. If *j* is omitted or
``None``, use ``len(s)``. If *i* is greater than or equal to *j*, the slice is
empty.
(5)
The slice of *s* from *i* to *j* with step *k* is defined as the sequence of
items with index ``x = i + n*k`` such that ``0 <= n < (j-i)/k``. In other words,
the indices are ``i``, ``i+k``, ``i+2*k``, ``i+3*k`` and so on, stopping when
*j* is reached (but never including *j*). When *k* is positive,
*i* and *j* are reduced to ``len(s)`` if they are greater.
When *k* is negative, *i* and *j* are reduced to ``len(s) - 1`` if
they are greater. If *i* or *j* are omitted or ``None``, they become
"end" values (which end depends on the sign of *k*). Note, *k* cannot be zero.
If *k* is ``None``, it is treated like ``1``.
(6)
.. impl-detail::
If *s* and *t* are both strings, some Python implementations such as
CPython can usually perform an in-place optimization for assignments of
the form ``s = s + t`` or ``s += t``. When applicable, this optimization
makes quadratic run-time much less likely. This optimization is both
version and implementation dependent. For performance sensitive code, it
is preferable to use the :meth:`str.join` method which assures consistent
linear concatenation performance across versions and implementations.
.. versionchanged:: 2.4
Formerly, string concatenation never occurred in-place.
.. _string-methods:
String Methods
--------------
.. index:: pair: string; methods
Below are listed the string methods which both 8-bit strings and
Unicode objects support. Some of them are also available on :class:`bytearray`
objects.
In addition, Python's strings support the sequence type methods
described in the :ref:`typesseq` section. To output formatted strings
use template strings or the ``%`` operator described in the
:ref:`string-formatting` section. Also, see the :mod:`re` module for
string functions based on regular expressions.
.. method:: str.capitalize()
Return a copy of the string with its first character capitalized and the
rest lowercased.
For 8-bit strings, this method is locale-dependent.
.. method:: str.center(width[, fillchar])
Return centered in a string of length *width*. Padding is done using the
specified *fillchar* (default is a space).
.. versionchanged:: 2.4
Support for the *fillchar* argument.
.. method:: str.count(sub[, start[, end]])
Return the number of non-overlapping occurrences of substring *sub* in the
range [*start*, *end*]. Optional arguments *start* and *end* are
interpreted as in slice notation.
.. method:: str.decode([encoding[, errors]])
Decodes the string using the codec registered for *encoding*. *encoding*
defaults to the default string encoding. *errors* may be given to set a
different error handling scheme. The default is ``'strict'``, meaning that
encoding errors raise :exc:`UnicodeError`. Other possible values are
``'ignore'``, ``'replace'`` and any other name registered via
:func:`codecs.register_error`, see section :ref:`codec-base-classes`.
.. versionadded:: 2.2
.. versionchanged:: 2.3
Support for other error handling schemes added.
.. versionchanged:: 2.7
Support for keyword arguments added.
.. method:: str.encode([encoding[,errors]])
Return an encoded version of the string. Default encoding is the current
default string encoding. *errors* may be given to set a different error
handling scheme. The default for *errors* is ``'strict'``, meaning that
encoding errors raise a :exc:`UnicodeError`. Other possible values are
``'ignore'``, ``'replace'``, ``'xmlcharrefreplace'``, ``'backslashreplace'`` and
any other name registered via :func:`codecs.register_error`, see section
:ref:`codec-base-classes`. For a list of possible encodings, see section
:ref:`standard-encodings`.
.. versionadded:: 2.0
.. versionchanged:: 2.3
Support for ``'xmlcharrefreplace'`` and ``'backslashreplace'`` and other error
handling schemes added.
.. versionchanged:: 2.7
Support for keyword arguments added.
.. method:: str.endswith(suffix[, start[, end]])
Return ``True`` if the string ends with the specified *suffix*, otherwise return
``False``. *suffix* can also be a tuple of suffixes to look for. With optional
*start*, test beginning at that position. With optional *end*, stop comparing
at that position.
.. versionchanged:: 2.5
Accept tuples as *suffix*.
.. method:: str.expandtabs([tabsize])
Return a copy of the string where all tab characters are replaced by one or
more spaces, depending on the current column and the given tab size. Tab
positions occur every *tabsize* characters (default is 8, giving tab
positions at columns 0, 8, 16 and so on). To expand the string, the current
column is set to zero and the string is examined character by character. If
the character is a tab (``\t``), one or more space characters are inserted
in the result until the current column is equal to the next tab position.
(The tab character itself is not copied.) If the character is a newline
(``\n``) or return (``\r``), it is copied and the current column is reset to
zero. Any other character is copied unchanged and the current column is
incremented by one regardless of how the character is represented when
printed.
>>> '01\t012\t0123\t01234'.expandtabs()
'01 012 0123 01234'
>>> '01\t012\t0123\t01234'.expandtabs(4)
'01 012 0123 01234'
.. method:: str.find(sub[, start[, end]])
Return the lowest index in the string where substring *sub* is found within
the slice ``s[start:end]``. Optional arguments *start* and *end* are
interpreted as in slice notation. Return ``-1`` if *sub* is not found.
.. note::
The :meth:`~str.find` method should be used only if you need to know the
position of *sub*. To check if *sub* is a substring or not, use the
:keyword:`in` operator::
>>> 'Py' in 'Python'
True
.. method:: str.format(*args, **kwargs)
Perform a string formatting operation. The string on which this method is
called can contain literal text or replacement fields delimited by braces
``{}``. Each replacement field contains either the numeric index of a
positional argument, or the name of a keyword argument. Returns a copy of
the string where each replacement field is replaced with the string value of
the corresponding argument.
>>> "The sum of 1 + 2 is {0}".format(1+2)
'The sum of 1 + 2 is 3'
See :ref:`formatstrings` for a description of the various formatting options
that can be specified in format strings.
This method of string formatting is the new standard in Python 3, and
should be preferred to the ``%`` formatting described in
:ref:`string-formatting` in new code.
.. versionadded:: 2.6
.. method:: str.index(sub[, start[, end]])
Like :meth:`find`, but raise :exc:`ValueError` when the substring is not found.
.. method:: str.isalnum()
Return true if all characters in the string are alphanumeric and there is at
least one character, false otherwise.
For 8-bit strings, this method is locale-dependent.
.. method:: str.isalpha()
Return true if all characters in the string are alphabetic and there is at least
one character, false otherwise.
For 8-bit strings, this method is locale-dependent.
.. method:: str.isdigit()
Return true if all characters in the string are digits and there is at least one
character, false otherwise.
For 8-bit strings, this method is locale-dependent.
.. method:: str.islower()
Return true if all cased characters [4]_ in the string are lowercase and there is at
least one cased character, false otherwise.
For 8-bit strings, this method is locale-dependent.
.. method:: str.isspace()
Return true if there are only whitespace characters in the string and there is
at least one character, false otherwise.
For 8-bit strings, this method is locale-dependent.
.. method:: str.istitle()
Return true if the string is a titlecased string and there is at least one
character, for example uppercase characters may only follow uncased characters
and lowercase characters only cased ones. Return false otherwise.
For 8-bit strings, this method is locale-dependent.
.. method:: str.isupper()
Return true if all cased characters [4]_ in the string are uppercase and there is at
least one cased character, false otherwise.
For 8-bit strings, this method is locale-dependent.
.. method:: str.join(iterable)
Return a string which is the concatenation of the strings in *iterable*.
If there is any Unicode object in *iterable*, return a Unicode instead.
A :exc:`TypeError` will be raised if there are any non-string or non Unicode
object values in *iterable*. The separator between elements is the string
providing this method.
.. method:: str.ljust(width[, fillchar])
Return the string left justified in a string of length *width*. Padding is done
using the specified *fillchar* (default is a space). The original string is
returned if *width* is less than or equal to ``len(s)``.
.. versionchanged:: 2.4
Support for the *fillchar* argument.
.. method:: str.lower()
Return a copy of the string with all the cased characters [4]_ converted to
lowercase.
For 8-bit strings, this method is locale-dependent.
.. method:: str.lstrip([chars])
Return a copy of the string with leading characters removed. The *chars*
argument is a string specifying the set of characters to be removed. If omitted
or ``None``, the *chars* argument defaults to removing whitespace. The *chars*
argument is not a prefix; rather, all combinations of its values are stripped:
>>> ' spacious '.lstrip()
'spacious '
>>> 'www.example.com'.lstrip('cmowz.')
'example.com'
.. versionchanged:: 2.2.2
Support for the *chars* argument.
.. method:: str.partition(sep)
Split the string at the first occurrence of *sep*, and return a 3-tuple
containing the part before the separator, the separator itself, and the part
after the separator. If the separator is not found, return a 3-tuple containing
the string itself, followed by two empty strings.
.. versionadded:: 2.5
.. method:: str.replace(old, new[, count])
Return a copy of the string with all occurrences of substring *old* replaced by
*new*. If the optional argument *count* is given, only the first *count*
occurrences are replaced.
.. method:: str.rfind(sub [,start [,end]])
Return the highest index in the string where substring *sub* is found, such
that *sub* is contained within ``s[start:end]``. Optional arguments *start*
and *end* are interpreted as in slice notation. Return ``-1`` on failure.
.. method:: str.rindex(sub[, start[, end]])
Like :meth:`rfind` but raises :exc:`ValueError` when the substring *sub* is not
found.
.. method:: str.rjust(width[, fillchar])
Return the string right justified in a string of length *width*. Padding is done
using the specified *fillchar* (default is a space). The original string is
returned if *width* is less than or equal to ``len(s)``.
.. versionchanged:: 2.4
Support for the *fillchar* argument.
.. method:: str.rpartition(sep)
Split the string at the last occurrence of *sep*, and return a 3-tuple
containing the part before the separator, the separator itself, and the part
after the separator. If the separator is not found, return a 3-tuple containing
two empty strings, followed by the string itself.
.. versionadded:: 2.5
.. method:: str.rsplit([sep [,maxsplit]])
Return a list of the words in the string, using *sep* as the delimiter string.
If *maxsplit* is given, at most *maxsplit* splits are done, the *rightmost*
ones. If *sep* is not specified or ``None``, any whitespace string is a
separator. Except for splitting from the right, :meth:`rsplit` behaves like
:meth:`split` which is described in detail below.
.. versionadded:: 2.4
.. method:: str.rstrip([chars])
Return a copy of the string with trailing characters removed. The *chars*
argument is a string specifying the set of characters to be removed. If omitted
or ``None``, the *chars* argument defaults to removing whitespace. The *chars*
argument is not a suffix; rather, all combinations of its values are stripped:
>>> ' spacious '.rstrip()
' spacious'
>>> 'mississippi'.rstrip('ipz')
'mississ'
.. versionchanged:: 2.2.2
Support for the *chars* argument.
.. method:: str.split([sep[, maxsplit]])
Return a list of the words in the string, using *sep* as the delimiter
string. If *maxsplit* is given, at most *maxsplit* splits are done (thus,
the list will have at most ``maxsplit+1`` elements). If *maxsplit* is not
specified or ``-1``, then there is no limit on the number of splits
(all possible splits are made).
If *sep* is given, consecutive delimiters are not grouped together and are
deemed to delimit empty strings (for example, ``'1,,2'.split(',')`` returns
``['1', '', '2']``). The *sep* argument may consist of multiple characters
(for example, ``'1<>2<>3'.split('<>')`` returns ``['1', '2', '3']``).
Splitting an empty string with a specified separator returns ``['']``.
If *sep* is not specified or is ``None``, a different splitting algorithm is
applied: runs of consecutive whitespace are regarded as a single separator,
and the result will contain no empty strings at the start or end if the
string has leading or trailing whitespace. Consequently, splitting an empty
string or a string consisting of just whitespace with a ``None`` separator
returns ``[]``.
For example, ``' 1 2 3 '.split()`` returns ``['1', '2', '3']``, and
``' 1 2 3 '.split(None, 1)`` returns ``['1', '2 3 ']``.
.. index::
single: universal newlines; str.splitlines method
.. method:: str.splitlines([keepends])
Return a list of the lines in the string, breaking at line boundaries.
This method uses the :term:`universal newlines` approach to splitting lines.
Line breaks are not included in the resulting list unless *keepends* is
given and true.
Python recognizes ``"\r"``, ``"\n"``, and ``"\r\n"`` as line boundaries for
8-bit strings.
For example::
>>> 'ab c\n\nde fg\rkl\r\n'.splitlines()
['ab c', '', 'de fg', 'kl']
>>> 'ab c\n\nde fg\rkl\r\n'.splitlines(True)
['ab c\n', '\n', 'de fg\r', 'kl\r\n']
Unlike :meth:`~str.split` when a delimiter string *sep* is given, this
method returns an empty list for the empty string, and a terminal line
break does not result in an extra line::
>>> "".splitlines()
[]
>>> "One line\n".splitlines()
['One line']
For comparison, ``split('\n')`` gives::
>>> ''.split('\n')
['']
>>> 'Two lines\n'.split('\n')
['Two lines', '']
.. method:: unicode.splitlines([keepends])
Return a list of the lines in the string, like :meth:`str.splitlines`.
However, the Unicode method splits on the following line boundaries,
which are a superset of the :term:`universal newlines` recognized for
8-bit strings.
+-----------------------+-----------------------------+
| Representation | Description |
+=======================+=============================+
| ``\n`` | Line Feed |
+-----------------------+-----------------------------+
| ``\r`` | Carriage Return |
+-----------------------+-----------------------------+
| ``\r\n`` | Carriage Return + Line Feed |
+-----------------------+-----------------------------+
| ``\v`` or ``\x0b`` | Line Tabulation |
+-----------------------+-----------------------------+
| ``\f`` or ``\x0c`` | Form Feed |
+-----------------------+-----------------------------+
| ``\x1c`` | File Separator |
+-----------------------+-----------------------------+
| ``\x1d`` | Group Separator |
+-----------------------+-----------------------------+
| ``\x1e`` | Record Separator |
+-----------------------+-----------------------------+
| ``\x85`` | Next Line (C1 Control Code) |
+-----------------------+-----------------------------+
| ``\u2028`` | Line Separator |
+-----------------------+-----------------------------+
| ``\u2029`` | Paragraph Separator |
+-----------------------+-----------------------------+
.. versionchanged:: 2.7
``\v`` and ``\f`` added to list of line boundaries.
.. method:: str.startswith(prefix[, start[, end]])
Return ``True`` if string starts with the *prefix*, otherwise return ``False``.
*prefix* can also be a tuple of prefixes to look for. With optional *start*,
test string beginning at that position. With optional *end*, stop comparing
string at that position.
.. versionchanged:: 2.5
Accept tuples as *prefix*.
.. method:: str.strip([chars])
Return a copy of the string with the leading and trailing characters removed.
The *chars* argument is a string specifying the set of characters to be removed.
If omitted or ``None``, the *chars* argument defaults to removing whitespace.
The *chars* argument is not a prefix or suffix; rather, all combinations of its
values are stripped:
>>> ' spacious '.strip()
'spacious'
>>> 'www.example.com'.strip('cmowz.')
'example'
.. versionchanged:: 2.2.2
Support for the *chars* argument.
.. method:: str.swapcase()
Return a copy of the string with uppercase characters converted to lowercase and
vice versa.
For 8-bit strings, this method is locale-dependent.
.. method:: str.title()
Return a titlecased version of the string where words start with an uppercase
character and the remaining characters are lowercase.
The algorithm uses a simple language-independent definition of a word as
groups of consecutive letters. The definition works in many contexts but
it means that apostrophes in contractions and possessives form word
boundaries, which may not be the desired result::
>>> "they're bill's friends from the UK".title()
"They'Re Bill'S Friends From The Uk"
A workaround for apostrophes can be constructed using regular expressions::
>>> import re
>>> def titlecase(s):
... return re.sub(r"[A-Za-z]+('[A-Za-z]+)?",
... lambda mo: mo.group(0)[0].upper() +
... mo.group(0)[1:].lower(),
... s)
...
>>> titlecase("they're bill's friends.")
"They're Bill's Friends."
For 8-bit strings, this method is locale-dependent.
.. method:: str.translate(table[, deletechars])
Return a copy of the string where all characters occurring in the optional
argument *deletechars* are removed, and the remaining characters have been
mapped through the given translation table, which must be a string of length
256.
You can use the :func:`~string.maketrans` helper function in the :mod:`string`
module to create a translation table. For string objects, set the *table*
argument to ``None`` for translations that only delete characters:
>>> 'read this short text'.translate(None, 'aeiou')
'rd ths shrt txt'
.. versionadded:: 2.6
Support for a ``None`` *table* argument.
For Unicode objects, the :meth:`translate` method does not accept the optional
*deletechars* argument. Instead, it returns a copy of the *s* where all
characters have been mapped through the given translation table which must be a
mapping of Unicode ordinals to Unicode ordinals, Unicode strings or ``None``.
Unmapped characters are left untouched. Characters mapped to ``None`` are
deleted. Note, a more flexible approach is to create a custom character mapping
codec using the :mod:`codecs` module (see :mod:`encodings.cp1251` for an
example).
.. method:: str.upper()
Return a copy of the string with all the cased characters [4]_ converted to
uppercase. Note that ``s.upper().isupper()`` might be ``False`` if ``s``
contains uncased characters or if the Unicode category of the resulting
character(s) is not "Lu" (Letter, uppercase), but e.g. "Lt" (Letter, titlecase).
For 8-bit strings, this method is locale-dependent.
.. method:: str.zfill(width)
Return the numeric string left filled with zeros in a string of length
*width*. A sign prefix is handled correctly. The original string is
returned if *width* is less than or equal to ``len(s)``.
.. versionadded:: 2.2.2
The following methods are present only on unicode objects:
.. method:: unicode.isnumeric()
Return ``True`` if there are only numeric characters in S, ``False``
otherwise. Numeric characters include digit characters, and all characters
that have the Unicode numeric value property, e.g. U+2155,
VULGAR FRACTION ONE FIFTH.
.. method:: unicode.isdecimal()
Return ``True`` if there are only decimal characters in S, ``False``
otherwise. Decimal characters include digit characters, and all characters
that can be used to form decimal-radix numbers, e.g. U+0660,
ARABIC-INDIC DIGIT ZERO.
.. _string-formatting:
String Formatting Operations
----------------------------
.. index::
single: formatting, string (%)
single: interpolation, string (%)
single: string; formatting
single: string; interpolation
single: printf-style formatting
single: sprintf-style formatting
single: % formatting
single: % interpolation
String and Unicode objects have one unique built-in operation: the ``%``
operator (modulo). This is also known as the string *formatting* or
*interpolation* operator. Given ``format % values`` (where *format* is a string
or Unicode object), ``%`` conversion specifications in *format* are replaced
with zero or more elements of *values*. The effect is similar to the using
:c:func:`sprintf` in the C language. If *format* is a Unicode object, or if any
of the objects being converted using the ``%s`` conversion are Unicode objects,
the result will also be a Unicode object.
If *format* requires a single argument, *values* may be a single non-tuple
object. [5]_ Otherwise, *values* must be a tuple with exactly the number of
items specified by the format string, or a single mapping object (for example, a
dictionary).
A conversion specifier contains two or more characters and has the following
components, which must occur in this order:
#. The ``'%'`` character, which marks the start of the specifier.
#. Mapping key (optional), consisting of a parenthesised sequence of characters
(for example, ``(somename)``).
#. Conversion flags (optional), which affect the result of some conversion
types.
#. Minimum field width (optional). If specified as an ``'*'`` (asterisk), the
actual width is read from the next element of the tuple in *values*, and the
object to convert comes after the minimum field width and optional precision.
#. Precision (optional), given as a ``'.'`` (dot) followed by the precision. If
specified as ``'*'`` (an asterisk), the actual width is read from the next
element of the tuple in *values*, and the value to convert comes after the
precision.
#. Length modifier (optional).
#. Conversion type.
When the right argument is a dictionary (or other mapping type), then the
formats in the string *must* include a parenthesised mapping key into that
dictionary inserted immediately after the ``'%'`` character. The mapping key
selects the value to be formatted from the mapping. For example:
>>> print '%(language)s has %(number)03d quote types.' % \
... {"language": "Python", "number": 2}
Python has 002 quote types.
In this case no ``*`` specifiers may occur in a format (since they require a
sequential parameter list).
The conversion flag characters are:
+---------+---------------------------------------------------------------------+
| Flag | Meaning |
+=========+=====================================================================+
| ``'#'`` | The value conversion will use the "alternate form" (where defined |
| | below). |
+---------+---------------------------------------------------------------------+
| ``'0'`` | The conversion will be zero padded for numeric values. |
+---------+---------------------------------------------------------------------+
| ``'-'`` | The converted value is left adjusted (overrides the ``'0'`` |
| | conversion if both are given). |
+---------+---------------------------------------------------------------------+
| ``' '`` | (a space) A blank should be left before a positive number (or empty |
| | string) produced by a signed conversion. |
+---------+---------------------------------------------------------------------+
| ``'+'`` | A sign character (``'+'`` or ``'-'``) will precede the conversion |
| | (overrides a "space" flag). |
+---------+---------------------------------------------------------------------+
A length modifier (``h``, ``l``, or ``L``) may be present, but is ignored as it
is not necessary for Python -- so e.g. ``%ld`` is identical to ``%d``.
The conversion types are:
+------------+-----------------------------------------------------+-------+
| Conversion | Meaning | Notes |
+============+=====================================================+=======+
| ``'d'`` | Signed integer decimal. | |
+------------+-----------------------------------------------------+-------+
| ``'i'`` | Signed integer decimal. | |
+------------+-----------------------------------------------------+-------+
| ``'o'`` | Signed octal value. | \(1) |
+------------+-----------------------------------------------------+-------+
| ``'u'`` | Obsolete type -- it is identical to ``'d'``. | \(7) |
+------------+-----------------------------------------------------+-------+
| ``'x'`` | Signed hexadecimal (lowercase). | \(2) |
+------------+-----------------------------------------------------+-------+
| ``'X'`` | Signed hexadecimal (uppercase). | \(2) |
+------------+-----------------------------------------------------+-------+
| ``'e'`` | Floating point exponential format (lowercase). | \(3) |
+------------+-----------------------------------------------------+-------+
| ``'E'`` | Floating point exponential format (uppercase). | \(3) |
+------------+-----------------------------------------------------+-------+
| ``'f'`` | Floating point decimal format. | \(3) |
+------------+-----------------------------------------------------+-------+
| ``'F'`` | Floating point decimal format. | \(3) |
+------------+-----------------------------------------------------+-------+
| ``'g'`` | Floating point format. Uses lowercase exponential | \(4) |
| | format if exponent is less than -4 or not less than | |
| | precision, decimal format otherwise. | |
+------------+-----------------------------------------------------+-------+
| ``'G'`` | Floating point format. Uses uppercase exponential | \(4) |
| | format if exponent is less than -4 or not less than | |
| | precision, decimal format otherwise. | |
+------------+-----------------------------------------------------+-------+
| ``'c'`` | Single character (accepts integer or single | |
| | character string). | |
+------------+-----------------------------------------------------+-------+
| ``'r'`` | String (converts any Python object using | \(5) |
| | :ref:`repr() <func-repr>`). | |
+------------+-----------------------------------------------------+-------+
| ``'s'`` | String (converts any Python object using | \(6) |
| | :func:`str`). | |
+------------+-----------------------------------------------------+-------+
| ``'%'`` | No argument is converted, results in a ``'%'`` | |
| | character in the result. | |
+------------+-----------------------------------------------------+-------+
Notes:
(1)
The alternate form causes a leading zero (``'0'``) to be inserted between
left-hand padding and the formatting of the number if the leading character
of the result is not already a zero.
(2)
The alternate form causes a leading ``'0x'`` or ``'0X'`` (depending on whether
the ``'x'`` or ``'X'`` format was used) to be inserted before the first digit.
(3)
The alternate form causes the result to always contain a decimal point, even if
no digits follow it.
The precision determines the number of digits after the decimal point and
defaults to 6.
(4)
The alternate form causes the result to always contain a decimal point, and
trailing zeroes are not removed as they would otherwise be.
The precision determines the number of significant digits before and after the
decimal point and defaults to 6.
(5)
The ``%r`` conversion was added in Python 2.0.
The precision determines the maximal number of characters used.
(6)
If the object or format provided is a :class:`unicode` string, the resulting
string will also be :class:`unicode`.
The precision determines the maximal number of characters used.
(7)
See :pep:`237`.
Since Python strings have an explicit length, ``%s`` conversions do not assume
that ``'\0'`` is the end of the string.
.. XXX Examples?
.. versionchanged:: 2.7
``%f`` conversions for numbers whose absolute value is over 1e50 are no
longer replaced by ``%g`` conversions.
.. index::
module: string
module: re
Additional string operations are defined in standard modules :mod:`string` and
:mod:`re`.
.. _typesseq-xrange:
XRange Type
-----------
.. index:: object: xrange
The :class:`xrange` type is an immutable sequence which is commonly used for
looping. The advantage of the :class:`xrange` type is that an :class:`xrange`
object will always take the same amount of memory, no matter the size of the
range it represents. There are no consistent performance advantages.
XRange objects have very little behavior: they only support indexing, iteration,
and the :func:`len` function.
.. _typesseq-mutable:
Mutable Sequence Types
----------------------
.. index::
triple: mutable; sequence; types
object: list
List and :class:`bytearray` objects support additional operations that allow
in-place modification of the object. Other mutable sequence types (when added
to the language) should also support these operations. Strings and tuples
are immutable sequence types: such objects cannot be modified once created.
The following operations are defined on mutable sequence types (where *x* is
an arbitrary object):
.. index::
triple: operations on; sequence; types
triple: operations on; list; type
pair: subscript; assignment
pair: slice; assignment
pair: extended slice; assignment
statement: del
single: append() (list method)
single: extend() (list method)
single: count() (list method)
single: index() (list method)
single: insert() (list method)
single: pop() (list method)
single: remove() (list method)
single: reverse() (list method)
single: sort() (list method)
+------------------------------+--------------------------------+---------------------+
| Operation | Result | Notes |
+==============================+================================+=====================+
| ``s[i] = x`` | item *i* of *s* is replaced by | |
| | *x* | |
+------------------------------+--------------------------------+---------------------+
| ``s[i:j] = t`` | slice of *s* from *i* to *j* | |
| | is replaced by the contents of | |
| | the iterable *t* | |
+------------------------------+--------------------------------+---------------------+
| ``del s[i:j]`` | same as ``s[i:j] = []`` | |
+------------------------------+--------------------------------+---------------------+
| ``s[i:j:k] = t`` | the elements of ``s[i:j:k]`` | \(1) |
| | are replaced by those of *t* | |
+------------------------------+--------------------------------+---------------------+
| ``del s[i:j:k]`` | removes the elements of | |
| | ``s[i:j:k]`` from the list | |
+------------------------------+--------------------------------+---------------------+
| ``s.append(x)`` | same as ``s[len(s):len(s)] = | \(2) |
| | [x]`` | |
+------------------------------+--------------------------------+---------------------+
| ``s.extend(t)`` or | for the most part the same as | \(3) |
| ``s += t`` | ``s[len(s):len(s)] = t`` | |
+------------------------------+--------------------------------+---------------------+
| ``s *= n`` | updates *s* with its contents | \(11) |
| | repeated *n* times | |
+------------------------------+--------------------------------+---------------------+
| ``s.count(x)`` | return number of *i*'s for | |
| | which ``s[i] == x`` | |
+------------------------------+--------------------------------+---------------------+
| ``s.index(x[, i[, j]])`` | return smallest *k* such that | \(4) |
| | ``s[k] == x`` and ``i <= k < | |
| | j`` | |
+------------------------------+--------------------------------+---------------------+
| ``s.insert(i, x)`` | same as ``s[i:i] = [x]`` | \(5) |
+------------------------------+--------------------------------+---------------------+
| ``s.pop([i])`` | same as ``x = s[i]; del s[i]; | \(6) |
| | return x`` | |
+------------------------------+--------------------------------+---------------------+
| ``s.remove(x)`` | same as ``del s[s.index(x)]`` | \(4) |
+------------------------------+--------------------------------+---------------------+
| ``s.reverse()`` | reverses the items of *s* in | \(7) |
| | place | |
+------------------------------+--------------------------------+---------------------+
| ``s.sort([cmp[, key[, | sort the items of *s* in place | (7)(8)(9)(10) |
| reverse]]])`` | | |
+------------------------------+--------------------------------+---------------------+
Notes:
(1)
*t* must have the same length as the slice it is replacing.
(2)
The C implementation of Python has historically accepted multiple parameters and
implicitly joined them into a tuple; this no longer works in Python 2.0. Use of
this misfeature has been deprecated since Python 1.4.
(3)
*t* can be any iterable object.
(4)
Raises :exc:`ValueError` when *x* is not found in *s*. When a negative index is
passed as the second or third parameter to the :meth:`index` method, the list
length is added, as for slice indices. If it is still negative, it is truncated
to zero, as for slice indices.
.. versionchanged:: 2.3
Previously, :meth:`index` didn't have arguments for specifying start and stop
positions.
(5)
When a negative index is passed as the first parameter to the :meth:`insert`
method, the list length is added, as for slice indices. If it is still
negative, it is truncated to zero, as for slice indices.
.. versionchanged:: 2.3
Previously, all negative indices were truncated to zero.
(6)
The :meth:`pop` method's optional argument *i* defaults to ``-1``, so that
by default the last item is removed and returned.
(7)
The :meth:`sort` and :meth:`reverse` methods modify the list in place for
economy of space when sorting or reversing a large list. To remind you that
they operate by side effect, they don't return the sorted or reversed list.
(8)
The :meth:`sort` method takes optional arguments for controlling the
comparisons.
*cmp* specifies a custom comparison function of two arguments (list items) which
should return a negative, zero or positive number depending on whether the first
argument is considered smaller than, equal to, or larger than the second
argument: ``cmp=lambda x,y: cmp(x.lower(), y.lower())``. The default value
is ``None``.
*key* specifies a function of one argument that is used to extract a comparison
key from each list element: ``key=str.lower``. The default value is ``None``.
*reverse* is a boolean value. If set to ``True``, then the list elements are
sorted as if each comparison were reversed.
In general, the *key* and *reverse* conversion processes are much faster than
specifying an equivalent *cmp* function. This is because *cmp* is called
multiple times for each list element while *key* and *reverse* touch each
element only once. Use :func:`functools.cmp_to_key` to convert an
old-style *cmp* function to a *key* function.
.. versionchanged:: 2.3
Support for ``None`` as an equivalent to omitting *cmp* was added.
.. versionchanged:: 2.4
Support for *key* and *reverse* was added.
(9)
Starting with Python 2.3, the :meth:`sort` method is guaranteed to be stable. A
sort is stable if it guarantees not to change the relative order of elements
that compare equal --- this is helpful for sorting in multiple passes (for
example, sort by department, then by salary grade).
(10)
.. impl-detail::
While a list is being sorted, the effect of attempting to mutate, or even
inspect, the list is undefined. The C implementation of Python 2.3 and
newer makes the list appear empty for the duration, and raises
:exc:`ValueError` if it can detect that the list has been mutated during a
sort.
(11)
The value *n* is an integer, or an object implementing
:meth:`~object.__index__`. Zero and negative values of *n* clear
the sequence. Items in the sequence are not copied; they are referenced
multiple times, as explained for ``s * n`` under :ref:`typesseq`.
.. _types-set:
Set Types --- :class:`set`, :class:`frozenset`
==============================================
.. index:: object: set
A :dfn:`set` object is an unordered collection of distinct :term:`hashable` objects.
Common uses include membership testing, removing duplicates from a sequence, and
computing mathematical operations such as intersection, union, difference, and
symmetric difference.
(For other containers see the built in :class:`dict`, :class:`list`,
and :class:`tuple` classes, and the :mod:`collections` module.)
.. versionadded:: 2.4
Like other collections, sets support ``x in set``, ``len(set)``, and ``for x in
set``. Being an unordered collection, sets do not record element position or
order of insertion. Accordingly, sets do not support indexing, slicing, or
other sequence-like behavior.
There are currently two built-in set types, :class:`set` and :class:`frozenset`.
The :class:`set` type is mutable --- the contents can be changed using methods
like :meth:`~set.add` and :meth:`~set.remove`. Since it is mutable, it has no
hash value and cannot be used as either a dictionary key or as an element of
another set. The :class:`frozenset` type is immutable and :term:`hashable` ---
its contents cannot be altered after it is created; it can therefore be used as
a dictionary key or as an element of another set.
As of Python 2.7, non-empty sets (not frozensets) can be created by placing a
comma-separated list of elements within braces, for example: ``{'jack',
'sjoerd'}``, in addition to the :class:`set` constructor.
The constructors for both classes work the same:
.. class:: set([iterable])
frozenset([iterable])
Return a new set or frozenset object whose elements are taken from
*iterable*. The elements of a set must be :term:`hashable`. To
represent sets of sets, the inner sets must be :class:`frozenset`
objects. If *iterable* is not specified, a new empty set is
returned.
Instances of :class:`set` and :class:`frozenset` provide the following
operations:
.. describe:: len(s)
Return the number of elements in set *s* (cardinality of *s*).
.. describe:: x in s
Test *x* for membership in *s*.
.. describe:: x not in s
Test *x* for non-membership in *s*.
.. method:: isdisjoint(other)
Return ``True`` if the set has no elements in common with *other*. Sets are
disjoint if and only if their intersection is the empty set.
.. versionadded:: 2.6
.. method:: issubset(other)
set <= other
Test whether every element in the set is in *other*.
.. method:: set < other
Test whether the set is a proper subset of *other*, that is,
``set <= other and set != other``.
.. method:: issuperset(other)
set >= other
Test whether every element in *other* is in the set.
.. method:: set > other
Test whether the set is a proper superset of *other*, that is, ``set >=
other and set != other``.
.. method:: union(*others)
set | other | ...
Return a new set with elements from the set and all others.
.. versionchanged:: 2.6
Accepts multiple input iterables.
.. method:: intersection(*others)
set & other & ...
Return a new set with elements common to the set and all others.
.. versionchanged:: 2.6
Accepts multiple input iterables.
.. method:: difference(*others)
set - other - ...
Return a new set with elements in the set that are not in the others.
.. versionchanged:: 2.6
Accepts multiple input iterables.
.. method:: symmetric_difference(other)
set ^ other
Return a new set with elements in either the set or *other* but not both.
.. method:: copy()
Return a new set with a shallow copy of *s*.
Note, the non-operator versions of :meth:`union`, :meth:`intersection`,
:meth:`difference`, and :meth:`symmetric_difference`, :meth:`issubset`, and
:meth:`issuperset` methods will accept any iterable as an argument. In
contrast, their operator based counterparts require their arguments to be
sets. This precludes error-prone constructions like ``set('abc') & 'cbs'``
in favor of the more readable ``set('abc').intersection('cbs')``.
Both :class:`set` and :class:`frozenset` support set to set comparisons. Two
sets are equal if and only if every element of each set is contained in the
other (each is a subset of the other). A set is less than another set if and
only if the first set is a proper subset of the second set (is a subset, but
is not equal). A set is greater than another set if and only if the first set
is a proper superset of the second set (is a superset, but is not equal).
Instances of :class:`set` are compared to instances of :class:`frozenset`
based on their members. For example, ``set('abc') == frozenset('abc')``
returns ``True`` and so does ``set('abc') in set([frozenset('abc')])``.
The subset and equality comparisons do not generalize to a total ordering
function. For example, any two non-empty disjoint sets are not equal and are not
subsets of each other, so *all* of the following return ``False``: ``a<b``,
``a==b``, or ``a>b``. Accordingly, sets do not implement the :meth:`__cmp__`
method.
Since sets only define partial ordering (subset relationships), the output of
the :meth:`list.sort` method is undefined for lists of sets.
Set elements, like dictionary keys, must be :term:`hashable`.
Binary operations that mix :class:`set` instances with :class:`frozenset`
return the type of the first operand. For example: ``frozenset('ab') |
set('bc')`` returns an instance of :class:`frozenset`.
The following table lists operations available for :class:`set` that do not
apply to immutable instances of :class:`frozenset`:
.. method:: update(*others)
set |= other | ...
Update the set, adding elements from all others.
.. versionchanged:: 2.6
Accepts multiple input iterables.
.. method:: intersection_update(*others)
set &= other & ...
Update the set, keeping only elements found in it and all others.
.. versionchanged:: 2.6
Accepts multiple input iterables.
.. method:: difference_update(*others)
set -= other | ...
Update the set, removing elements found in others.
.. versionchanged:: 2.6
Accepts multiple input iterables.
.. method:: symmetric_difference_update(other)
set ^= other
Update the set, keeping only elements found in either set, but not in both.
.. method:: add(elem)
Add element *elem* to the set.
.. method:: remove(elem)
Remove element *elem* from the set. Raises :exc:`KeyError` if *elem* is
not contained in the set.
.. method:: discard(elem)
Remove element *elem* from the set if it is present.
.. method:: pop()
Remove and return an arbitrary element from the set. Raises
:exc:`KeyError` if the set is empty.
.. method:: clear()
Remove all elements from the set.
Note, the non-operator versions of the :meth:`update`,
:meth:`intersection_update`, :meth:`difference_update`, and
:meth:`symmetric_difference_update` methods will accept any iterable as an
argument.
Note, the *elem* argument to the :meth:`__contains__`, :meth:`remove`, and
:meth:`discard` methods may be a set. To support searching for an equivalent
frozenset, a temporary one is created from *elem*.
.. seealso::
:ref:`comparison-to-builtin-set`
Differences between the :mod:`sets` module and the built-in set types.
.. _typesmapping:
Mapping Types --- :class:`dict`
===============================
.. index::
object: mapping
object: dictionary
triple: operations on; mapping; types
triple: operations on; dictionary; type
statement: del
builtin: len
A :term:`mapping` object maps :term:`hashable` values to arbitrary objects.
Mappings are mutable objects. There is currently only one standard mapping
type, the :dfn:`dictionary`. (For other containers see the built in
:class:`list`, :class:`set`, and :class:`tuple` classes, and the
:mod:`collections` module.)
A dictionary's keys are *almost* arbitrary values. Values that are not
:term:`hashable`, that is, values containing lists, dictionaries or other
mutable types (that are compared by value rather than by object identity) may
not be used as keys. Numeric types used for keys obey the normal rules for
numeric comparison: if two numbers compare equal (such as ``1`` and ``1.0``)
then they can be used interchangeably to index the same dictionary entry. (Note
however, that since computers store floating-point numbers as approximations it
is usually unwise to use them as dictionary keys.)
Dictionaries can be created by placing a comma-separated list of ``key: value``
pairs within braces, for example: ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098:
'jack', 4127: 'sjoerd'}``, or by the :class:`dict` constructor.
.. class:: dict(**kwarg)
dict(mapping, **kwarg)
dict(iterable, **kwarg)
Return a new dictionary initialized from an optional positional argument
and a possibly empty set of keyword arguments.
If no positional argument is given, an empty dictionary is created.
If a positional argument is given and it is a mapping object, a dictionary
is created with the same key-value pairs as the mapping object. Otherwise,
the positional argument must be an :term:`iterable` object. Each item in
the iterable must itself be an iterable with exactly two objects. The
first object of each item becomes a key in the new dictionary, and the
second object the corresponding value. If a key occurs more than once, the
last value for that key becomes the corresponding value in the new
dictionary.
If keyword arguments are given, the keyword arguments and their values are
added to the dictionary created from the positional argument. If a key
being added is already present, the value from the keyword argument
replaces the value from the positional argument.
To illustrate, the following examples all return a dictionary equal to
``{"one": 1, "two": 2, "three": 3}``::
>>> a = dict(one=1, two=2, three=3)
>>> b = {'one': 1, 'two': 2, 'three': 3}
>>> c = dict(zip(['one', 'two', 'three'], [1, 2, 3]))
>>> d = dict([('two', 2), ('one', 1), ('three', 3)])
>>> e = dict({'three': 3, 'one': 1, 'two': 2})
>>> a == b == c == d == e
True
Providing keyword arguments as in the first example only works for keys that
are valid Python identifiers. Otherwise, any valid keys can be used.
.. versionadded:: 2.2
.. versionchanged:: 2.3
Support for building a dictionary from keyword arguments added.
These are the operations that dictionaries support (and therefore, custom
mapping types should support too):
.. describe:: len(d)
Return the number of items in the dictionary *d*.
.. describe:: d[key]
Return the item of *d* with key *key*. Raises a :exc:`KeyError` if *key*
is not in the map.
.. index:: __missing__()
If a subclass of dict defines a method :meth:`__missing__` and *key*
is not present, the ``d[key]`` operation calls that method with the key *key*
as argument. The ``d[key]`` operation then returns or raises whatever is
returned or raised by the ``__missing__(key)`` call.
No other operations or methods invoke :meth:`__missing__`. If
:meth:`__missing__` is not defined, :exc:`KeyError` is raised.
:meth:`__missing__` must be a method; it cannot be an instance variable::
>>> class Counter(dict):
... def __missing__(self, key):
... return 0
>>> c = Counter()
>>> c['red']
0
>>> c['red'] += 1
>>> c['red']
1
The example above shows part of the implementation of
:class:`collections.Counter`. A different ``__missing__`` method is used
by :class:`collections.defaultdict`.
.. versionadded:: 2.5
Recognition of __missing__ methods of dict subclasses.
.. describe:: d[key] = value
Set ``d[key]`` to *value*.
.. describe:: del d[key]
Remove ``d[key]`` from *d*. Raises a :exc:`KeyError` if *key* is not in the
map.
.. describe:: key in d
Return ``True`` if *d* has a key *key*, else ``False``.
.. versionadded:: 2.2
.. describe:: key not in d
Equivalent to ``not key in d``.
.. versionadded:: 2.2
.. describe:: iter(d)
Return an iterator over the keys of the dictionary. This is a shortcut
for :meth:`iterkeys`.
.. method:: clear()
Remove all items from the dictionary.
.. method:: copy()
Return a shallow copy of the dictionary.
.. method:: fromkeys(seq[, value])
Create a new dictionary with keys from *seq* and values set to *value*.
:func:`fromkeys` is a class method that returns a new dictionary. *value*
defaults to ``None``.
.. versionadded:: 2.3
.. method:: get(key[, default])
Return the value for *key* if *key* is in the dictionary, else *default*.
If *default* is not given, it defaults to ``None``, so that this method
never raises a :exc:`KeyError`.
.. method:: has_key(key)
Test for the presence of *key* in the dictionary. :meth:`has_key` is
deprecated in favor of ``key in d``.
.. method:: items()
Return a copy of the dictionary's list of ``(key, value)`` pairs.
.. impl-detail::
Keys and values are listed in an arbitrary order which is non-random,
varies across Python implementations, and depends on the dictionary's
history of insertions and deletions.
If :meth:`items`, :meth:`keys`, :meth:`values`, :meth:`iteritems`,
:meth:`iterkeys`, and :meth:`itervalues` are called with no intervening
modifications to the dictionary, the lists will directly correspond. This
allows the creation of ``(value, key)`` pairs using :func:`zip`: ``pairs =
zip(d.values(), d.keys())``. The same relationship holds for the
:meth:`iterkeys` and :meth:`itervalues` methods: ``pairs =
zip(d.itervalues(), d.iterkeys())`` provides the same value for
``pairs``. Another way to create the same list is ``pairs = [(v, k) for
(k, v) in d.iteritems()]``.
.. method:: iteritems()
Return an iterator over the dictionary's ``(key, value)`` pairs. See the
note for :meth:`dict.items`.
Using :meth:`iteritems` while adding or deleting entries in the dictionary
may raise a :exc:`RuntimeError` or fail to iterate over all entries.
.. versionadded:: 2.2
.. method:: iterkeys()
Return an iterator over the dictionary's keys. See the note for
:meth:`dict.items`.
Using :meth:`iterkeys` while adding or deleting entries in the dictionary
may raise a :exc:`RuntimeError` or fail to iterate over all entries.
.. versionadded:: 2.2
.. method:: itervalues()
Return an iterator over the dictionary's values. See the note for
:meth:`dict.items`.
Using :meth:`itervalues` while adding or deleting entries in the
dictionary may raise a :exc:`RuntimeError` or fail to iterate over all
entries.
.. versionadded:: 2.2
.. method:: keys()
Return a copy of the dictionary's list of keys. See the note for
:meth:`dict.items`.
.. method:: pop(key[, default])
If *key* is in the dictionary, remove it and return its value, else return
*default*. If *default* is not given and *key* is not in the dictionary,
a :exc:`KeyError` is raised.
.. versionadded:: 2.3
.. method:: popitem()
Remove and return an arbitrary ``(key, value)`` pair from the dictionary.
:func:`popitem` is useful to destructively iterate over a dictionary, as
often used in set algorithms. If the dictionary is empty, calling
:func:`popitem` raises a :exc:`KeyError`.
.. method:: setdefault(key[, default])
If *key* is in the dictionary, return its value. If not, insert *key*
with a value of *default* and return *default*. *default* defaults to
``None``.
.. method:: update([other])
Update the dictionary with the key/value pairs from *other*, overwriting
existing keys. Return ``None``.
:func:`update` accepts either another dictionary object or an iterable of
key/value pairs (as tuples or other iterables of length two). If keyword
arguments are specified, the dictionary is then updated with those
key/value pairs: ``d.update(red=1, blue=2)``.
.. versionchanged:: 2.4
Allowed the argument to be an iterable of key/value pairs and allowed
keyword arguments.
.. method:: values()
Return a copy of the dictionary's list of values. See the note for
:meth:`dict.items`.
.. method:: viewitems()
Return a new view of the dictionary's items (``(key, value)`` pairs). See
below for documentation of view objects.
.. versionadded:: 2.7
.. method:: viewkeys()
Return a new view of the dictionary's keys. See below for documentation of
view objects.
.. versionadded:: 2.7
.. method:: viewvalues()
Return a new view of the dictionary's values. See below for documentation of
view objects.
.. versionadded:: 2.7
Dictionaries compare equal if and only if they have the same ``(key,
value)`` pairs.
.. _dict-views:
Dictionary view objects
-----------------------
The objects returned by :meth:`dict.viewkeys`, :meth:`dict.viewvalues` and
:meth:`dict.viewitems` are *view objects*. They provide a dynamic view on the
dictionary's entries, which means that when the dictionary changes, the view
reflects these changes.
Dictionary views can be iterated over to yield their respective data, and
support membership tests:
.. describe:: len(dictview)
Return the number of entries in the dictionary.
.. describe:: iter(dictview)
Return an iterator over the keys, values or items (represented as tuples of
``(key, value)``) in the dictionary.
Keys and values are iterated over in an arbitrary order which is non-random,
varies across Python implementations, and depends on the dictionary's history
of insertions and deletions. If keys, values and items views are iterated
over with no intervening modifications to the dictionary, the order of items
will directly correspond. This allows the creation of ``(value, key)`` pairs
using :func:`zip`: ``pairs = zip(d.values(), d.keys())``. Another way to
create the same list is ``pairs = [(v, k) for (k, v) in d.items()]``.
Iterating views while adding or deleting entries in the dictionary may raise
a :exc:`RuntimeError` or fail to iterate over all entries.
.. describe:: x in dictview
Return ``True`` if *x* is in the underlying dictionary's keys, values or
items (in the latter case, *x* should be a ``(key, value)`` tuple).
Keys views are set-like since their entries are unique and hashable. If all
values are hashable, so that (key, value) pairs are unique and hashable, then
the items view is also set-like. (Values views are not treated as set-like
since the entries are generally not unique.) Then these set operations are
available ("other" refers either to another view or a set):
.. describe:: dictview & other
Return the intersection of the dictview and the other object as a new set.
.. describe:: dictview | other
Return the union of the dictview and the other object as a new set.
.. describe:: dictview - other
Return the difference between the dictview and the other object (all elements
in *dictview* that aren't in *other*) as a new set.
.. describe:: dictview ^ other
Return the symmetric difference (all elements either in *dictview* or
*other*, but not in both) of the dictview and the other object as a new set.
An example of dictionary view usage::
>>> dishes = {'eggs': 2, 'sausage': 1, 'bacon': 1, 'spam': 500}
>>> keys = dishes.viewkeys()
>>> values = dishes.viewvalues()
>>> # iteration
>>> n = 0
>>> for val in values:
... n += val
>>> print(n)
504
>>> # keys and values are iterated over in the same order
>>> list(keys)
['eggs', 'bacon', 'sausage', 'spam']
>>> list(values)
[2, 1, 1, 500]
>>> # view objects are dynamic and reflect dict changes
>>> del dishes['eggs']
>>> del dishes['sausage']
>>> list(keys)
['spam', 'bacon']
>>> # set operations
>>> keys & {'eggs', 'bacon', 'salad'}
{'bacon'}
.. _bltin-file-objects:
File Objects
============
.. index::
object: file
builtin: file
module: os
module: socket
File objects are implemented using C's ``stdio`` package and can be
created with the built-in :func:`open` function. File
objects are also returned by some other built-in functions and methods,
such as :func:`os.popen` and :func:`os.fdopen` and the :meth:`makefile`
method of socket objects. Temporary files can be created using the
:mod:`tempfile` module, and high-level file operations such as copying,
moving, and deleting files and directories can be achieved with the
:mod:`shutil` module.
When a file operation fails for an I/O-related reason, the exception
:exc:`IOError` is raised. This includes situations where the operation is not
defined for some reason, like :meth:`seek` on a tty device or writing a file
opened for reading.
Files have the following methods:
.. method:: file.close()
Close the file. A closed file cannot be read or written any more. Any operation
which requires that the file be open will raise a :exc:`ValueError` after the
file has been closed. Calling :meth:`close` more than once is allowed.
As of Python 2.5, you can avoid having to call this method explicitly if you use
the :keyword:`with` statement. For example, the following code will
automatically close *f* when the :keyword:`with` block is exited::
from __future__ import with_statement # This isn't required in Python 2.6
with open("hello.txt") as f:
for line in f:
print line,
In older versions of Python, you would have needed to do this to get the same
effect::
f = open("hello.txt")
try:
for line in f:
print line,
finally:
f.close()
.. note::
Not all "file-like" types in Python support use as a context manager for the
:keyword:`with` statement. If your code is intended to work with any file-like
object, you can use the function :func:`contextlib.closing` instead of using
the object directly.
.. method:: file.flush()
Flush the internal buffer, like ``stdio``'s :c:func:`fflush`. This may be a
no-op on some file-like objects.
.. note::
:meth:`flush` does not necessarily write the file's data to disk. Use
:meth:`flush` followed by :func:`os.fsync` to ensure this behavior.
.. method:: file.fileno()
.. index::
pair: file; descriptor
module: fcntl
Return the integer "file descriptor" that is used by the underlying
implementation to request I/O operations from the operating system. This can be
useful for other, lower level interfaces that use file descriptors, such as the
:mod:`fcntl` module or :func:`os.read` and friends.
.. note::
File-like objects which do not have a real file descriptor should *not* provide
this method!
.. method:: file.isatty()
Return ``True`` if the file is connected to a tty(-like) device, else ``False``.
.. note::
If a file-like object is not associated with a real file, this method should
*not* be implemented.
.. method:: file.next()
A file object is its own iterator, for example ``iter(f)`` returns *f* (unless
*f* is closed). When a file is used as an iterator, typically in a
:keyword:`for` loop (for example, ``for line in f: print line.strip()``), the
:meth:`~file.next` method is called repeatedly. This method returns the next input
line, or raises :exc:`StopIteration` when EOF is hit when the file is open for
reading (behavior is undefined when the file is open for writing). In order to
make a :keyword:`for` loop the most efficient way of looping over the lines of a
file (a very common operation), the :meth:`~file.next` method uses a hidden read-ahead
buffer. As a consequence of using a read-ahead buffer, combining :meth:`~file.next`
with other file methods (like :meth:`~file.readline`) does not work right. However,
using :meth:`seek` to reposition the file to an absolute position will flush the
read-ahead buffer.
.. versionadded:: 2.3
.. method:: file.read([size])
Read at most *size* bytes from the file (less if the read hits EOF before
obtaining *size* bytes). If the *size* argument is negative or omitted, read
all data until EOF is reached. The bytes are returned as a string object. An
empty string is returned when EOF is encountered immediately. (For certain
files, like ttys, it makes sense to continue reading after an EOF is hit.) Note
that this method may call the underlying C function :c:func:`fread` more than
once in an effort to acquire as close to *size* bytes as possible. Also note
that when in non-blocking mode, less data than was requested may be
returned, even if no *size* parameter was given.
.. note::
This function is simply a wrapper for the underlying
:c:func:`fread` C function, and will behave the same in corner cases,
such as whether the EOF value is cached.
.. method:: file.readline([size])
Read one entire line from the file. A trailing newline character is kept in
the string (but may be absent when a file ends with an incomplete line). [6]_
If the *size* argument is present and non-negative, it is a maximum byte
count (including the trailing newline) and an incomplete line may be
returned. When *size* is not 0, an empty string is returned *only* when EOF
is encountered immediately.
.. note::
Unlike ``stdio``'s :c:func:`fgets`, the returned string contains null characters
(``'\0'``) if they occurred in the input.
.. method:: file.readlines([sizehint])
Read until EOF using :meth:`~file.readline` and return a list containing the lines
thus read. If the optional *sizehint* argument is present, instead of
reading up to EOF, whole lines totalling approximately *sizehint* bytes
(possibly after rounding up to an internal buffer size) are read. Objects
implementing a file-like interface may choose to ignore *sizehint* if it
cannot be implemented, or cannot be implemented efficiently.
.. method:: file.xreadlines()
This method returns the same thing as ``iter(f)``.
.. versionadded:: 2.1
.. deprecated:: 2.3
Use ``for line in file`` instead.
.. method:: file.seek(offset[, whence])
Set the file's current position, like ``stdio``'s :c:func:`fseek`. The *whence*
argument is optional and defaults to ``os.SEEK_SET`` or ``0`` (absolute file
positioning); other values are ``os.SEEK_CUR`` or ``1`` (seek relative to the
current position) and ``os.SEEK_END`` or ``2`` (seek relative to the file's
end). There is no return value.
For example, ``f.seek(2, os.SEEK_CUR)`` advances the position by two and
``f.seek(-3, os.SEEK_END)`` sets the position to the third to last.
Note that if the file is opened for appending
(mode ``'a'`` or ``'a+'``), any :meth:`seek` operations will be undone at the
next write. If the file is only opened for writing in append mode (mode
``'a'``), this method is essentially a no-op, but it remains useful for files
opened in append mode with reading enabled (mode ``'a+'``). If the file is
opened in text mode (without ``'b'``), only offsets returned by :meth:`tell` are
legal. Use of other offsets causes undefined behavior.
Note that not all file objects are seekable.
.. versionchanged:: 2.6
Passing float values as offset has been deprecated.
.. method:: file.tell()
Return the file's current position, like ``stdio``'s :c:func:`ftell`.
.. note::
On Windows, :meth:`tell` can return illegal values (after an :c:func:`fgets`)
when reading files with Unix-style line-endings. Use binary mode (``'rb'``) to
circumvent this problem.
.. method:: file.truncate([size])
Truncate the file's size. If the optional *size* argument is present, the file
is truncated to (at most) that size. The size defaults to the current position.
The current file position is not changed. Note that if a specified size exceeds
the file's current size, the result is platform-dependent: possibilities
include that the file may remain unchanged, increase to the specified size as if
zero-filled, or increase to the specified size with undefined new content.
Availability: Windows, many Unix variants.
.. method:: file.write(str)
Write a string to the file. There is no return value. Due to buffering, the
string may not actually show up in the file until the :meth:`flush` or
:meth:`close` method is called.
.. method:: file.writelines(sequence)
Write a sequence of strings to the file. The sequence can be any iterable
object producing strings, typically a list of strings. There is no return value.
(The name is intended to match :meth:`readlines`; :meth:`writelines` does not
add line separators.)
Files support the iterator protocol. Each iteration returns the same result as
:meth:`~file.readline`, and iteration ends when the :meth:`~file.readline` method returns
an empty string.
File objects also offer a number of other interesting attributes. These are not
required for file-like objects, but should be implemented if they make sense for
the particular object.
.. attribute:: file.closed
bool indicating the current state of the file object. This is a read-only
attribute; the :meth:`close` method changes the value. It may not be available
on all file-like objects.
.. attribute:: file.encoding
The encoding that this file uses. When Unicode strings are written to a file,
they will be converted to byte strings using this encoding. In addition, when
the file is connected to a terminal, the attribute gives the encoding that the
terminal is likely to use (that information might be incorrect if the user has
misconfigured the terminal). The attribute is read-only and may not be present
on all file-like objects. It may also be ``None``, in which case the file uses
the system default encoding for converting Unicode strings.
.. versionadded:: 2.3
.. attribute:: file.errors
The Unicode error handler used along with the encoding.
.. versionadded:: 2.6
.. attribute:: file.mode
The I/O mode for the file. If the file was created using the :func:`open`
built-in function, this will be the value of the *mode* parameter. This is a
read-only attribute and may not be present on all file-like objects.
.. attribute:: file.name
If the file object was created using :func:`open`, the name of the file.
Otherwise, some string that indicates the source of the file object, of the
form ``<...>``. This is a read-only attribute and may not be present on all
file-like objects.
.. index::
single: universal newlines; file.newlines attribute
.. attribute:: file.newlines
If Python was built with :term:`universal newlines` enabled (the default) this
read-only attribute exists, and for files opened in universal newline read
mode it keeps track of the types of newlines encountered while reading the
file. The values it can take are ``'\r'``, ``'\n'``, ``'\r\n'``, ``None``
(unknown, no newlines read yet) or a tuple containing all the newline types
seen, to indicate that multiple newline conventions were encountered. For
files not opened in universal newlines read mode the value of this attribute
will be ``None``.
.. attribute:: file.softspace
Boolean that indicates whether a space character needs to be printed before
another value when using the :keyword:`print` statement. Classes that are trying
to simulate a file object should also have a writable :attr:`softspace`
attribute, which should be initialized to zero. This will be automatic for most
classes implemented in Python (care may be needed for objects that override
attribute access); types implemented in C will have to provide a writable
:attr:`softspace` attribute.
.. note::
This attribute is not used to control the :keyword:`print` statement, but to
allow the implementation of :keyword:`print` to keep track of its internal
state.
.. _typememoryview:
memoryview type
===============
.. versionadded:: 2.7
:class:`memoryview` objects allow Python code to access the internal data
of an object that supports the buffer protocol without copying. Memory
is generally interpreted as simple bytes.
.. class:: memoryview(obj)
Create a :class:`memoryview` that references *obj*. *obj* must support the
buffer protocol. Built-in objects that support the buffer protocol include
:class:`str` and :class:`bytearray` (but not :class:`unicode`).
A :class:`memoryview` has the notion of an *element*, which is the
atomic memory unit handled by the originating object *obj*. For many
simple types such as :class:`str` and :class:`bytearray`, an element
is a single byte, but other third-party types may expose larger elements.
``len(view)`` returns the total number of elements in the memoryview,
*view*. The :class:`~memoryview.itemsize` attribute will give you the
number of bytes in a single element.
A :class:`memoryview` supports slicing to expose its data. Taking a single
index will return a single element as a :class:`str` object. Full
slicing will result in a subview::
>>> v = memoryview('abcefg')
>>> v[1]
'b'
>>> v[-1]
'g'
>>> v[1:4]
<memory at 0x77ab28>
>>> v[1:4].tobytes()
'bce'
If the object the memoryview is over supports changing its data, the
memoryview supports slice assignment::
>>> data = bytearray('abcefg')
>>> v = memoryview(data)
>>> v.readonly
False
>>> v[0] = 'z'
>>> data
bytearray(b'zbcefg')
>>> v[1:4] = '123'
>>> data
bytearray(b'z123fg')
>>> v[2] = 'spam'
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ValueError: cannot modify size of memoryview object
Notice how the size of the memoryview object cannot be changed.
:class:`memoryview` has two methods:
.. method:: tobytes()
Return the data in the buffer as a bytestring (an object of class
:class:`str`). ::
>>> m = memoryview("abc")
>>> m.tobytes()
'abc'
.. method:: tolist()
Return the data in the buffer as a list of integers. ::
>>> memoryview("abc").tolist()
[97, 98, 99]
There are also several readonly attributes available:
.. attribute:: format
A string containing the format (in :mod:`struct` module style) for each
element in the view. This defaults to ``'B'``, a simple bytestring.
.. attribute:: itemsize
The size in bytes of each element of the memoryview.
.. attribute:: shape
A tuple of integers the length of :attr:`ndim` giving the shape of the
memory as an N-dimensional array.
.. attribute:: ndim
An integer indicating how many dimensions of a multi-dimensional array the
memory represents.
.. attribute:: strides
A tuple of integers the length of :attr:`ndim` giving the size in bytes to
access each element for each dimension of the array.
.. attribute:: readonly
A bool indicating whether the memory is read only.
.. memoryview.suboffsets isn't documented because it only seems useful for C
.. _typecontextmanager:
Context Manager Types
=====================
.. versionadded:: 2.5
.. index::
single: context manager
single: context management protocol
single: protocol; context management
Python's :keyword:`with` statement supports the concept of a runtime context
defined by a context manager. This is implemented using two separate methods
that allow user-defined classes to define a runtime context that is entered
before the statement body is executed and exited when the statement ends.
The :dfn:`context management protocol` consists of a pair of methods that need
to be provided for a context manager object to define a runtime context:
.. method:: contextmanager.__enter__()
Enter the runtime context and return either this object or another object
related to the runtime context. The value returned by this method is bound to
the identifier in the :keyword:`as` clause of :keyword:`with` statements using
this context manager.
An example of a context manager that returns itself is a file object. File
objects return themselves from __enter__() to allow :func:`open` to be used as
the context expression in a :keyword:`with` statement.
An example of a context manager that returns a related object is the one
returned by :func:`decimal.localcontext`. These managers set the active
decimal context to a copy of the original decimal context and then return the
copy. This allows changes to be made to the current decimal context in the body
of the :keyword:`with` statement without affecting code outside the
:keyword:`with` statement.
.. method:: contextmanager.__exit__(exc_type, exc_val, exc_tb)
Exit the runtime context and return a Boolean flag indicating if any exception
that occurred should be suppressed. If an exception occurred while executing the
body of the :keyword:`with` statement, the arguments contain the exception type,
value and traceback information. Otherwise, all three arguments are ``None``.
Returning a true value from this method will cause the :keyword:`with` statement
to suppress the exception and continue execution with the statement immediately
following the :keyword:`with` statement. Otherwise the exception continues
propagating after this method has finished executing. Exceptions that occur
during execution of this method will replace any exception that occurred in the
body of the :keyword:`with` statement.
The exception passed in should never be reraised explicitly - instead, this
method should return a false value to indicate that the method completed
successfully and does not want to suppress the raised exception. This allows
context management code (such as ``contextlib.nested``) to easily detect whether
or not an :meth:`__exit__` method has actually failed.
Python defines several context managers to support easy thread synchronisation,
prompt closure of files or other objects, and simpler manipulation of the active
decimal arithmetic context. The specific types are not treated specially beyond
their implementation of the context management protocol. See the
:mod:`contextlib` module for some examples.
Python's :term:`generator`\s and the ``contextlib.contextmanager`` :term:`decorator`
provide a convenient way to implement these protocols. If a generator function is
decorated with the ``contextlib.contextmanager`` decorator, it will return a
context manager implementing the necessary :meth:`__enter__` and
:meth:`__exit__` methods, rather than the iterator produced by an undecorated
generator function.
Note that there is no specific slot for any of these methods in the type
structure for Python objects in the Python/C API. Extension types wanting to
define these methods must provide them as a normal Python accessible method.
Compared to the overhead of setting up the runtime context, the overhead of a
single class dictionary lookup is negligible.
.. _typesother:
Other Built-in Types
====================
The interpreter supports several other kinds of objects. Most of these support
only one or two operations.
.. _typesmodules:
Modules
-------
The only special operation on a module is attribute access: ``m.name``, where
*m* is a module and *name* accesses a name defined in *m*'s symbol table.
Module attributes can be assigned to. (Note that the :keyword:`import`
statement is not, strictly speaking, an operation on a module object; ``import
foo`` does not require a module object named *foo* to exist, rather it requires
an (external) *definition* for a module named *foo* somewhere.)
A special attribute of every module is :attr:`~object.__dict__`. This is the
dictionary containing the module's symbol table. Modifying this dictionary will
actually change the module's symbol table, but direct assignment to the
:attr:`~object.__dict__` attribute is not possible (you can write
``m.__dict__['a'] = 1``, which defines ``m.a`` to be ``1``, but you can't write
``m.__dict__ = {}``). Modifying :attr:`~object.__dict__` directly is
not recommended.
Modules built into the interpreter are written like this: ``<module 'sys'
(built-in)>``. If loaded from a file, they are written as ``<module 'os' from
'/usr/local/lib/pythonX.Y/os.pyc'>``.
.. _typesobjects:
Classes and Class Instances
---------------------------
See :ref:`objects` and :ref:`class` for these.
.. _typesfunctions:
Functions
---------
Function objects are created by function definitions. The only operation on a
function object is to call it: ``func(argument-list)``.
There are really two flavors of function objects: built-in functions and
user-defined functions. Both support the same operation (to call the function),
but the implementation is different, hence the different object types.
See :ref:`function` for more information.
.. _typesmethods:
Methods
-------
.. index:: object: method
Methods are functions that are called using the attribute notation. There are
two flavors: built-in methods (such as :meth:`append` on lists) and class
instance methods. Built-in methods are described with the types that support
them.
The implementation adds two special read-only attributes to class instance
methods: ``m.im_self`` is the object on which the method operates, and
``m.im_func`` is the function implementing the method. Calling ``m(arg-1,
arg-2, ..., arg-n)`` is completely equivalent to calling ``m.im_func(m.im_self,
arg-1, arg-2, ..., arg-n)``.
Class instance methods are either *bound* or *unbound*, referring to whether the
method was accessed through an instance or a class, respectively. When a method
is unbound, its ``im_self`` attribute will be ``None`` and if called, an
explicit ``self`` object must be passed as the first argument. In this case,
``self`` must be an instance of the unbound method's class (or a subclass of
that class), otherwise a :exc:`TypeError` is raised.
Like function objects, methods objects support getting arbitrary attributes.
However, since method attributes are actually stored on the underlying function
object (``meth.im_func``), setting method attributes on either bound or unbound
methods is disallowed. Attempting to set an attribute on a method results in
an :exc:`AttributeError` being raised. In order to set a method attribute, you
need to explicitly set it on the underlying function object::
>>> class C:
... def method(self):
... pass
...
>>> c = C()
>>> c.method.whoami = 'my name is method' # can't set on the method
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
AttributeError: 'instancemethod' object has no attribute 'whoami'
>>> c.method.im_func.whoami = 'my name is method'
>>> c.method.whoami
'my name is method'
See :ref:`types` for more information.
.. index:: object; code, code object
.. _bltin-code-objects:
Code Objects
------------
.. index::
builtin: compile
single: func_code (function object attribute)
Code objects are used by the implementation to represent "pseudo-compiled"
executable Python code such as a function body. They differ from function
objects because they don't contain a reference to their global execution
environment. Code objects are returned by the built-in :func:`compile` function
and can be extracted from function objects through their :attr:`func_code`
attribute. See also the :mod:`code` module.
.. index::
statement: exec
builtin: eval
A code object can be executed or evaluated by passing it (instead of a source
string) to the :keyword:`exec` statement or the built-in :func:`eval` function.
See :ref:`types` for more information.
.. _bltin-type-objects:
Type Objects
------------
.. index::
builtin: type
module: types
Type objects represent the various object types. An object's type is accessed
by the built-in function :func:`type`. There are no special operations on
types. The standard module :mod:`types` defines names for all standard built-in
types.
Types are written like this: ``<type 'int'>``.
.. _bltin-null-object:
The Null Object
---------------
This object is returned by functions that don't explicitly return a value. It
supports no special operations. There is exactly one null object, named
``None`` (a built-in name).
It is written as ``None``.
.. _bltin-ellipsis-object:
The Ellipsis Object
-------------------
This object is used by extended slice notation (see :ref:`slicings`). It
supports no special operations. There is exactly one ellipsis object, named
:const:`Ellipsis` (a built-in name).
It is written as ``Ellipsis``. When in a subscript, it can also be written as
``...``, for example ``seq[...]``.
The NotImplemented Object
-------------------------
This object is returned from comparisons and binary operations when they are
asked to operate on types they don't support. See :ref:`comparisons` for more
information.
It is written as ``NotImplemented``.
Boolean Values
--------------
Boolean values are the two constant objects ``False`` and ``True``. They are
used to represent truth values (although other values can also be considered
false or true). In numeric contexts (for example when used as the argument to
an arithmetic operator), they behave like the integers 0 and 1, respectively.
The built-in function :func:`bool` can be used to convert any value to a
Boolean, if the value can be interpreted as a truth value (see section
:ref:`truth` above).
.. index::
single: False
single: True
pair: Boolean; values
They are written as ``False`` and ``True``, respectively.
.. _typesinternal:
Internal Objects
----------------
See :ref:`types` for this information. It describes stack frame objects,
traceback objects, and slice objects.
.. _specialattrs:
Special Attributes
==================
The implementation adds a few special read-only attributes to several object
types, where they are relevant. Some of these are not reported by the
:func:`dir` built-in function.
.. attribute:: object.__dict__
A dictionary or other mapping object used to store an object's (writable)
attributes.
.. attribute:: object.__methods__
.. deprecated:: 2.2
Use the built-in function :func:`dir` to get a list of an object's attributes.
This attribute is no longer available.
.. attribute:: object.__members__
.. deprecated:: 2.2
Use the built-in function :func:`dir` to get a list of an object's attributes.
This attribute is no longer available.
.. attribute:: instance.__class__
The class to which a class instance belongs.
.. attribute:: class.__bases__
The tuple of base classes of a class object.
.. attribute:: definition.__name__
The name of the class, type, function, method, descriptor, or
generator instance.
The following attributes are only supported by :term:`new-style class`\ es.
.. attribute:: class.__mro__
This attribute is a tuple of classes that are considered when looking for
base classes during method resolution.
.. method:: class.mro()
This method can be overridden by a metaclass to customize the method
resolution order for its instances. It is called at class instantiation, and
its result is stored in :attr:`~class.__mro__`.
.. method:: class.__subclasses__
Each new-style class keeps a list of weak references to its immediate
subclasses. This method returns a list of all those references still alive.
Example::
>>> int.__subclasses__()
[<type 'bool'>]
.. rubric:: Footnotes
.. [1] Additional information on these special methods may be found in the Python
Reference Manual (:ref:`customization`).
.. [2] As a consequence, the list ``[1, 2]`` is considered equal to ``[1.0, 2.0]``, and
similarly for tuples.
.. [3] They must have since the parser can't tell the type of the operands.
.. [4] Cased characters are those with general category property being one of
"Lu" (Letter, uppercase), "Ll" (Letter, lowercase), or "Lt" (Letter, titlecase).
.. [5] To format only a tuple you should therefore provide a singleton tuple whose only
element is the tuple to be formatted.
.. [6] The advantage of leaving the newline on is that returning an empty string is
then an unambiguous EOF indication. It is also possible (in cases where it
might matter, for example, if you want to make an exact copy of a file while
scanning its lines) to tell whether the last line of a file ended in a newline
or not (yes this happens!).
PK
%�\�8S�5� 5� $ html/_sources/library/string.rst.txtnu �[��� :mod:`string` --- Common string operations
==========================================
.. module:: string
:synopsis: Common string operations.
.. index:: module: re
**Source code:** :source:`Lib/string.py`
--------------
The :mod:`string` module contains a number of useful constants and
classes, as well as some deprecated legacy functions that are also
available as methods on strings. In addition, Python's built-in string
classes support the sequence type methods described in the
:ref:`typesseq` section, and also the string-specific methods described
in the :ref:`string-methods` section. To output formatted strings use
template strings or the ``%`` operator described in the
:ref:`string-formatting` section. Also, see the :mod:`re` module for
string functions based on regular expressions.
String constants
----------------
The constants defined in this module are:
.. data:: ascii_letters
The concatenation of the :const:`ascii_lowercase` and :const:`ascii_uppercase`
constants described below. This value is not locale-dependent.
.. data:: ascii_lowercase
The lowercase letters ``'abcdefghijklmnopqrstuvwxyz'``. This value is not
locale-dependent and will not change.
.. data:: ascii_uppercase
The uppercase letters ``'ABCDEFGHIJKLMNOPQRSTUVWXYZ'``. This value is not
locale-dependent and will not change.
.. data:: digits
The string ``'0123456789'``.
.. data:: hexdigits
The string ``'0123456789abcdefABCDEF'``.
.. data:: letters
The concatenation of the strings :const:`lowercase` and :const:`uppercase`
described below. The specific value is locale-dependent, and will be updated
when :func:`locale.setlocale` is called.
.. data:: lowercase
A string containing all the characters that are considered lowercase letters.
On most systems this is the string ``'abcdefghijklmnopqrstuvwxyz'``. The
specific value is locale-dependent, and will be updated when
:func:`locale.setlocale` is called.
.. data:: octdigits
The string ``'01234567'``.
.. data:: punctuation
String of ASCII characters which are considered punctuation characters in the
``C`` locale.
.. data:: printable
String of characters which are considered printable. This is a combination of
:const:`digits`, :const:`letters`, :const:`punctuation`, and
:const:`whitespace`.
.. data:: uppercase
A string containing all the characters that are considered uppercase letters.
On most systems this is the string ``'ABCDEFGHIJKLMNOPQRSTUVWXYZ'``. The
specific value is locale-dependent, and will be updated when
:func:`locale.setlocale` is called.
.. data:: whitespace
A string containing all characters that are considered whitespace. On most
systems this includes the characters space, tab, linefeed, return, formfeed, and
vertical tab.
.. _new-string-formatting:
Custom String Formatting
------------------------
.. versionadded:: 2.6
The built-in str and unicode classes provide the ability
to do complex variable substitutions and value formatting via the
:meth:`str.format` method described in :pep:`3101`. The :class:`Formatter`
class in the :mod:`string` module allows you to create and customize your own
string formatting behaviors using the same implementation as the built-in
:meth:`~str.format` method.
.. class:: Formatter
The :class:`Formatter` class has the following public methods:
.. method:: format(format_string, *args, **kwargs)
The primary API method. It takes a format string and
an arbitrary set of positional and keyword arguments.
It is just a wrapper that calls :meth:`vformat`.
.. method:: vformat(format_string, args, kwargs)
This function does the actual work of formatting. It is exposed as a
separate function for cases where you want to pass in a predefined
dictionary of arguments, rather than unpacking and repacking the
dictionary as individual arguments using the ``*args`` and ``**kwargs``
syntax. :meth:`vformat` does the work of breaking up the format string
into character data and replacement fields. It calls the various
methods described below.
In addition, the :class:`Formatter` defines a number of methods that are
intended to be replaced by subclasses:
.. method:: parse(format_string)
Loop over the format_string and return an iterable of tuples
(*literal_text*, *field_name*, *format_spec*, *conversion*). This is used
by :meth:`vformat` to break the string into either literal text, or
replacement fields.
The values in the tuple conceptually represent a span of literal text
followed by a single replacement field. If there is no literal text
(which can happen if two replacement fields occur consecutively), then
*literal_text* will be a zero-length string. If there is no replacement
field, then the values of *field_name*, *format_spec* and *conversion*
will be ``None``.
.. method:: get_field(field_name, args, kwargs)
Given *field_name* as returned by :meth:`parse` (see above), convert it to
an object to be formatted. Returns a tuple (obj, used_key). The default
version takes strings of the form defined in :pep:`3101`, such as
"0[name]" or "label.title". *args* and *kwargs* are as passed in to
:meth:`vformat`. The return value *used_key* has the same meaning as the
*key* parameter to :meth:`get_value`.
.. method:: get_value(key, args, kwargs)
Retrieve a given field value. The *key* argument will be either an
integer or a string. If it is an integer, it represents the index of the
positional argument in *args*; if it is a string, then it represents a
named argument in *kwargs*.
The *args* parameter is set to the list of positional arguments to
:meth:`vformat`, and the *kwargs* parameter is set to the dictionary of
keyword arguments.
For compound field names, these functions are only called for the first
component of the field name; Subsequent components are handled through
normal attribute and indexing operations.
So for example, the field expression '0.name' would cause
:meth:`get_value` to be called with a *key* argument of 0. The ``name``
attribute will be looked up after :meth:`get_value` returns by calling the
built-in :func:`getattr` function.
If the index or keyword refers to an item that does not exist, then an
:exc:`IndexError` or :exc:`KeyError` should be raised.
.. method:: check_unused_args(used_args, args, kwargs)
Implement checking for unused arguments if desired. The arguments to this
function is the set of all argument keys that were actually referred to in
the format string (integers for positional arguments, and strings for
named arguments), and a reference to the *args* and *kwargs* that was
passed to vformat. The set of unused args can be calculated from these
parameters. :meth:`check_unused_args` is assumed to raise an exception if
the check fails.
.. method:: format_field(value, format_spec)
:meth:`format_field` simply calls the global :func:`format` built-in. The
method is provided so that subclasses can override it.
.. method:: convert_field(value, conversion)
Converts the value (returned by :meth:`get_field`) given a conversion type
(as in the tuple returned by the :meth:`parse` method). The default
version understands 's' (str), 'r' (repr) and 'a' (ascii) conversion
types.
.. _formatstrings:
Format String Syntax
--------------------
The :meth:`str.format` method and the :class:`Formatter` class share the same
syntax for format strings (although in the case of :class:`Formatter`,
subclasses can define their own format string syntax).
Format strings contain "replacement fields" surrounded by curly braces ``{}``.
Anything that is not contained in braces is considered literal text, which is
copied unchanged to the output. If you need to include a brace character in the
literal text, it can be escaped by doubling: ``{{`` and ``}}``.
The grammar for a replacement field is as follows:
.. productionlist:: sf
replacement_field: "{" [`field_name`] ["!" `conversion`] [":" `format_spec`] "}"
field_name: arg_name ("." `attribute_name` | "[" `element_index` "]")*
arg_name: [`identifier` | `integer`]
attribute_name: `identifier`
element_index: `integer` | `index_string`
index_string: <any source character except "]"> +
conversion: "r" | "s"
format_spec: <described in the next section>
In less formal terms, the replacement field can start with a *field_name* that specifies
the object whose value is to be formatted and inserted
into the output instead of the replacement field.
The *field_name* is optionally followed by a *conversion* field, which is
preceded by an exclamation point ``'!'``, and a *format_spec*, which is preceded
by a colon ``':'``. These specify a non-default format for the replacement value.
See also the :ref:`formatspec` section.
The *field_name* itself begins with an *arg_name* that is either a number or a
keyword. If it's a number, it refers to a positional argument, and if it's a keyword,
it refers to a named keyword argument. If the numerical arg_names in a format string
are 0, 1, 2, ... in sequence, they can all be omitted (not just some)
and the numbers 0, 1, 2, ... will be automatically inserted in that order.
Because *arg_name* is not quote-delimited, it is not possible to specify arbitrary
dictionary keys (e.g., the strings ``'10'`` or ``':-]'``) within a format string.
The *arg_name* can be followed by any number of index or
attribute expressions. An expression of the form ``'.name'`` selects the named
attribute using :func:`getattr`, while an expression of the form ``'[index]'``
does an index lookup using :func:`__getitem__`.
.. versionchanged:: 2.7
The positional argument specifiers can be omitted for :meth:`str.format` and
:meth:`unicode.format`, so ``'{} {}'`` is equivalent to ``'{0} {1}'``,
``u'{} {}'`` is equivalent to ``u'{0} {1}'``.
Some simple format string examples::
"First, thou shalt count to {0}" # References first positional argument
"Bring me a {}" # Implicitly references the first positional argument
"From {} to {}" # Same as "From {0} to {1}"
"My quest is {name}" # References keyword argument 'name'
"Weight in tons {0.weight}" # 'weight' attribute of first positional arg
"Units destroyed: {players[0]}" # First element of keyword argument 'players'.
The *conversion* field causes a type coercion before formatting. Normally, the
job of formatting a value is done by the :meth:`__format__` method of the value
itself. However, in some cases it is desirable to force a type to be formatted
as a string, overriding its own definition of formatting. By converting the
value to a string before calling :meth:`__format__`, the normal formatting logic
is bypassed.
Two conversion flags are currently supported: ``'!s'`` which calls :func:`str`
on the value, and ``'!r'`` which calls :func:`repr`.
Some examples::
"Harold's a clever {0!s}" # Calls str() on the argument first
"Bring out the holy {name!r}" # Calls repr() on the argument first
The *format_spec* field contains a specification of how the value should be
presented, including such details as field width, alignment, padding, decimal
precision and so on. Each value type can define its own "formatting
mini-language" or interpretation of the *format_spec*.
Most built-in types support a common formatting mini-language, which is
described in the next section.
A *format_spec* field can also include nested replacement fields within it.
These nested replacement fields may contain a field name, conversion flag
and format specification, but deeper nesting is
not allowed. The replacement fields within the
format_spec are substituted before the *format_spec* string is interpreted.
This allows the formatting of a value to be dynamically specified.
See the :ref:`formatexamples` section for some examples.
.. _formatspec:
Format Specification Mini-Language
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
"Format specifications" are used within replacement fields contained within a
format string to define how individual values are presented (see
:ref:`formatstrings`). They can also be passed directly to the built-in
:func:`format` function. Each formattable type may define how the format
specification is to be interpreted.
Most built-in types implement the following options for format specifications,
although some of the formatting options are only supported by the numeric types.
A general convention is that an empty format string (``""``) produces
the same result as if you had called :func:`str` on the value. A
non-empty format string typically modifies the result.
The general form of a *standard format specifier* is:
.. productionlist:: sf
format_spec: [[`fill`]`align`][`sign`][#][0][`width`][,][.`precision`][`type`]
fill: <any character>
align: "<" | ">" | "=" | "^"
sign: "+" | "-" | " "
width: `integer`
precision: `integer`
type: "b" | "c" | "d" | "e" | "E" | "f" | "F" | "g" | "G" | "n" | "o" | "s" | "x" | "X" | "%"
If a valid *align* value is specified, it can be preceded by a *fill*
character that can be any character and defaults to a space if omitted.
It is not possible to use a literal curly brace ("``{``" or "``}``") as
the *fill* character when using the :meth:`str.format`
method. However, it is possible to insert a curly brace
with a nested replacement field. This limitation doesn't
affect the :func:`format` function.
The meaning of the various alignment options is as follows:
+---------+----------------------------------------------------------+
| Option | Meaning |
+=========+==========================================================+
| ``'<'`` | Forces the field to be left-aligned within the available |
| | space (this is the default for most objects). |
+---------+----------------------------------------------------------+
| ``'>'`` | Forces the field to be right-aligned within the |
| | available space (this is the default for numbers). |
+---------+----------------------------------------------------------+
| ``'='`` | Forces the padding to be placed after the sign (if any) |
| | but before the digits. This is used for printing fields |
| | in the form '+000000120'. This alignment option is only |
| | valid for numeric types. It becomes the default when '0'|
| | immediately precedes the field width. |
+---------+----------------------------------------------------------+
| ``'^'`` | Forces the field to be centered within the available |
| | space. |
+---------+----------------------------------------------------------+
Note that unless a minimum field width is defined, the field width will always
be the same size as the data to fill it, so that the alignment option has no
meaning in this case.
The *sign* option is only valid for number types, and can be one of the
following:
+---------+----------------------------------------------------------+
| Option | Meaning |
+=========+==========================================================+
| ``'+'`` | indicates that a sign should be used for both |
| | positive as well as negative numbers. |
+---------+----------------------------------------------------------+
| ``'-'`` | indicates that a sign should be used only for negative |
| | numbers (this is the default behavior). |
+---------+----------------------------------------------------------+
| space | indicates that a leading space should be used on |
| | positive numbers, and a minus sign on negative numbers. |
+---------+----------------------------------------------------------+
The ``'#'`` option is only valid for integers, and only for binary, octal, or
hexadecimal output. If present, it specifies that the output will be prefixed
by ``'0b'``, ``'0o'``, or ``'0x'``, respectively.
The ``','`` option signals the use of a comma for a thousands separator.
For a locale aware separator, use the ``'n'`` integer presentation type
instead.
.. versionchanged:: 2.7
Added the ``','`` option (see also :pep:`378`).
*width* is a decimal integer defining the minimum field width. If not
specified, then the field width will be determined by the content.
When no explicit alignment is given, preceding the *width* field by a zero
(``'0'``) character enables
sign-aware zero-padding for numeric types. This is equivalent to a *fill*
character of ``'0'`` with an *alignment* type of ``'='``.
The *precision* is a decimal number indicating how many digits should be
displayed after the decimal point for a floating point value formatted with
``'f'`` and ``'F'``, or before and after the decimal point for a floating point
value formatted with ``'g'`` or ``'G'``. For non-number types the field
indicates the maximum field size - in other words, how many characters will be
used from the field content. The *precision* is not allowed for integer values.
Finally, the *type* determines how the data should be presented.
The available string presentation types are:
+---------+----------------------------------------------------------+
| Type | Meaning |
+=========+==========================================================+
| ``'s'`` | String format. This is the default type for strings and |
| | may be omitted. |
+---------+----------------------------------------------------------+
| None | The same as ``'s'``. |
+---------+----------------------------------------------------------+
The available integer presentation types are:
+---------+----------------------------------------------------------+
| Type | Meaning |
+=========+==========================================================+
| ``'b'`` | Binary format. Outputs the number in base 2. |
+---------+----------------------------------------------------------+
| ``'c'`` | Character. Converts the integer to the corresponding |
| | unicode character before printing. |
+---------+----------------------------------------------------------+
| ``'d'`` | Decimal Integer. Outputs the number in base 10. |
+---------+----------------------------------------------------------+
| ``'o'`` | Octal format. Outputs the number in base 8. |
+---------+----------------------------------------------------------+
| ``'x'`` | Hex format. Outputs the number in base 16, using lower- |
| | case letters for the digits above 9. |
+---------+----------------------------------------------------------+
| ``'X'`` | Hex format. Outputs the number in base 16, using upper- |
| | case letters for the digits above 9. |
+---------+----------------------------------------------------------+
| ``'n'`` | Number. This is the same as ``'d'``, except that it uses |
| | the current locale setting to insert the appropriate |
| | number separator characters. |
+---------+----------------------------------------------------------+
| None | The same as ``'d'``. |
+---------+----------------------------------------------------------+
In addition to the above presentation types, integers can be formatted
with the floating point presentation types listed below (except
``'n'`` and ``None``). When doing so, :func:`float` is used to convert the
integer to a floating point number before formatting.
The available presentation types for floating point and decimal values are:
+---------+----------------------------------------------------------+
| Type | Meaning |
+=========+==========================================================+
| ``'e'`` | Exponent notation. Prints the number in scientific |
| | notation using the letter 'e' to indicate the exponent. |
| | The default precision is ``6``. |
+---------+----------------------------------------------------------+
| ``'E'`` | Exponent notation. Same as ``'e'`` except it uses an |
| | upper case 'E' as the separator character. |
+---------+----------------------------------------------------------+
| ``'f'`` | Fixed-point notation. Displays the number as a |
| | fixed-point number. The default precision is ``6``. |
+---------+----------------------------------------------------------+
| ``'F'`` | Fixed point notation. Same as ``'f'``. |
+---------+----------------------------------------------------------+
| ``'g'`` | General format. For a given precision ``p >= 1``, |
| | this rounds the number to ``p`` significant digits and |
| | then formats the result in either fixed-point format |
| | or in scientific notation, depending on its magnitude. |
| | |
| | The precise rules are as follows: suppose that the |
| | result formatted with presentation type ``'e'`` and |
| | precision ``p-1`` would have exponent ``exp``. Then |
| | if ``-4 <= exp < p``, the number is formatted |
| | with presentation type ``'f'`` and precision |
| | ``p-1-exp``. Otherwise, the number is formatted |
| | with presentation type ``'e'`` and precision ``p-1``. |
| | In both cases insignificant trailing zeros are removed |
| | from the significand, and the decimal point is also |
| | removed if there are no remaining digits following it. |
| | |
| | Positive and negative infinity, positive and negative |
| | zero, and nans, are formatted as ``inf``, ``-inf``, |
| | ``0``, ``-0`` and ``nan`` respectively, regardless of |
| | the precision. |
| | |
| | A precision of ``0`` is treated as equivalent to a |
| | precision of ``1``. The default precision is ``6``. |
+---------+----------------------------------------------------------+
| ``'G'`` | General format. Same as ``'g'`` except switches to |
| | ``'E'`` if the number gets too large. The |
| | representations of infinity and NaN are uppercased, too. |
+---------+----------------------------------------------------------+
| ``'n'`` | Number. This is the same as ``'g'``, except that it uses |
| | the current locale setting to insert the appropriate |
| | number separator characters. |
+---------+----------------------------------------------------------+
| ``'%'`` | Percentage. Multiplies the number by 100 and displays |
| | in fixed (``'f'``) format, followed by a percent sign. |
+---------+----------------------------------------------------------+
| None | The same as ``'g'``. |
+---------+----------------------------------------------------------+
.. _formatexamples:
Format examples
^^^^^^^^^^^^^^^
This section contains examples of the :meth:`str.format` syntax and
comparison with the old ``%``-formatting.
In most of the cases the syntax is similar to the old ``%``-formatting, with the
addition of the ``{}`` and with ``:`` used instead of ``%``.
For example, ``'%03.2f'`` can be translated to ``'{:03.2f}'``.
The new format syntax also supports new and different options, shown in the
following examples.
Accessing arguments by position::
>>> '{0}, {1}, {2}'.format('a', 'b', 'c')
'a, b, c'
>>> '{}, {}, {}'.format('a', 'b', 'c') # 2.7+ only
'a, b, c'
>>> '{2}, {1}, {0}'.format('a', 'b', 'c')
'c, b, a'
>>> '{2}, {1}, {0}'.format(*'abc') # unpacking argument sequence
'c, b, a'
>>> '{0}{1}{0}'.format('abra', 'cad') # arguments' indices can be repeated
'abracadabra'
Accessing arguments by name::
>>> 'Coordinates: {latitude}, {longitude}'.format(latitude='37.24N', longitude='-115.81W')
'Coordinates: 37.24N, -115.81W'
>>> coord = {'latitude': '37.24N', 'longitude': '-115.81W'}
>>> 'Coordinates: {latitude}, {longitude}'.format(**coord)
'Coordinates: 37.24N, -115.81W'
Accessing arguments' attributes::
>>> c = 3-5j
>>> ('The complex number {0} is formed from the real part {0.real} '
... 'and the imaginary part {0.imag}.').format(c)
'The complex number (3-5j) is formed from the real part 3.0 and the imaginary part -5.0.'
>>> class Point(object):
... def __init__(self, x, y):
... self.x, self.y = x, y
... def __str__(self):
... return 'Point({self.x}, {self.y})'.format(self=self)
...
>>> str(Point(4, 2))
'Point(4, 2)'
Accessing arguments' items::
>>> coord = (3, 5)
>>> 'X: {0[0]}; Y: {0[1]}'.format(coord)
'X: 3; Y: 5'
Replacing ``%s`` and ``%r``::
>>> "repr() shows quotes: {!r}; str() doesn't: {!s}".format('test1', 'test2')
"repr() shows quotes: 'test1'; str() doesn't: test2"
Aligning the text and specifying a width::
>>> '{:<30}'.format('left aligned')
'left aligned '
>>> '{:>30}'.format('right aligned')
' right aligned'
>>> '{:^30}'.format('centered')
' centered '
>>> '{:*^30}'.format('centered') # use '*' as a fill char
'***********centered***********'
Replacing ``%+f``, ``%-f``, and ``% f`` and specifying a sign::
>>> '{:+f}; {:+f}'.format(3.14, -3.14) # show it always
'+3.140000; -3.140000'
>>> '{: f}; {: f}'.format(3.14, -3.14) # show a space for positive numbers
' 3.140000; -3.140000'
>>> '{:-f}; {:-f}'.format(3.14, -3.14) # show only the minus -- same as '{:f}; {:f}'
'3.140000; -3.140000'
Replacing ``%x`` and ``%o`` and converting the value to different bases::
>>> # format also supports binary numbers
>>> "int: {0:d}; hex: {0:x}; oct: {0:o}; bin: {0:b}".format(42)
'int: 42; hex: 2a; oct: 52; bin: 101010'
>>> # with 0x, 0o, or 0b as prefix:
>>> "int: {0:d}; hex: {0:#x}; oct: {0:#o}; bin: {0:#b}".format(42)
'int: 42; hex: 0x2a; oct: 0o52; bin: 0b101010'
Using the comma as a thousands separator::
>>> '{:,}'.format(1234567890)
'1,234,567,890'
Expressing a percentage::
>>> points = 19.5
>>> total = 22
>>> 'Correct answers: {:.2%}'.format(points/total)
'Correct answers: 88.64%'
Using type-specific formatting::
>>> import datetime
>>> d = datetime.datetime(2010, 7, 4, 12, 15, 58)
>>> '{:%Y-%m-%d %H:%M:%S}'.format(d)
'2010-07-04 12:15:58'
Nesting arguments and more complex examples::
>>> for align, text in zip('<^>', ['left', 'center', 'right']):
... '{0:{fill}{align}16}'.format(text, fill=align, align=align)
...
'left<<<<<<<<<<<<'
'^^^^^center^^^^^'
'>>>>>>>>>>>right'
>>>
>>> octets = [192, 168, 0, 1]
>>> '{:02X}{:02X}{:02X}{:02X}'.format(*octets)
'C0A80001'
>>> int(_, 16)
3232235521
>>>
>>> width = 5
>>> for num in range(5,12):
... for base in 'dXob':
... print '{0:{width}{base}}'.format(num, base=base, width=width),
... print
...
5 5 5 101
6 6 6 110
7 7 7 111
8 8 10 1000
9 9 11 1001
10 A 12 1010
11 B 13 1011
Template strings
----------------
.. versionadded:: 2.4
Templates provide simpler string substitutions as described in :pep:`292`.
Instead of the normal ``%``\ -based substitutions, Templates support ``$``\
-based substitutions, using the following rules:
* ``$$`` is an escape; it is replaced with a single ``$``.
* ``$identifier`` names a substitution placeholder matching a mapping key of
``"identifier"``. By default, ``"identifier"`` must spell a Python
identifier. The first non-identifier character after the ``$`` character
terminates this placeholder specification.
* ``${identifier}`` is equivalent to ``$identifier``. It is required when valid
identifier characters follow the placeholder but are not part of the
placeholder, such as ``"${noun}ification"``.
Any other appearance of ``$`` in the string will result in a :exc:`ValueError`
being raised.
The :mod:`string` module provides a :class:`Template` class that implements
these rules. The methods of :class:`Template` are:
.. class:: Template(template)
The constructor takes a single argument which is the template string.
.. method:: substitute(mapping[, **kws])
Performs the template substitution, returning a new string. *mapping* is
any dictionary-like object with keys that match the placeholders in the
template. Alternatively, you can provide keyword arguments, where the
keywords are the placeholders. When both *mapping* and *kws* are given
and there are duplicates, the placeholders from *kws* take precedence.
.. method:: safe_substitute(mapping[, **kws])
Like :meth:`substitute`, except that if placeholders are missing from
*mapping* and *kws*, instead of raising a :exc:`KeyError` exception, the
original placeholder will appear in the resulting string intact. Also,
unlike with :meth:`substitute`, any other appearances of the ``$`` will
simply return ``$`` instead of raising :exc:`ValueError`.
While other exceptions may still occur, this method is called "safe"
because it always tries to return a usable string instead of
raising an exception. In another sense, :meth:`safe_substitute` may be
anything other than safe, since it will silently ignore malformed
templates containing dangling delimiters, unmatched braces, or
placeholders that are not valid Python identifiers.
:class:`Template` instances also provide one public data attribute:
.. attribute:: template
This is the object passed to the constructor's *template* argument. In
general, you shouldn't change it, but read-only access is not enforced.
Here is an example of how to use a Template::
>>> from string import Template
>>> s = Template('$who likes $what')
>>> s.substitute(who='tim', what='kung pao')
'tim likes kung pao'
>>> d = dict(who='tim')
>>> Template('Give $who $100').substitute(d)
Traceback (most recent call last):
...
ValueError: Invalid placeholder in string: line 1, col 11
>>> Template('$who likes $what').substitute(d)
Traceback (most recent call last):
...
KeyError: 'what'
>>> Template('$who likes $what').safe_substitute(d)
'tim likes $what'
Advanced usage: you can derive subclasses of :class:`Template` to customize the
placeholder syntax, delimiter character, or the entire regular expression used
to parse template strings. To do this, you can override these class attributes:
* *delimiter* -- This is the literal string describing a placeholder introducing
delimiter. The default value is ``$``. Note that this should *not* be a
regular expression, as the implementation will call :meth:`re.escape` on this
string as needed.
* *idpattern* -- This is the regular expression describing the pattern for
non-braced placeholders (the braces will be added automatically as
appropriate). The default value is the regular expression
``[_a-z][_a-z0-9]*``.
Alternatively, you can provide the entire regular expression pattern by
overriding the class attribute *pattern*. If you do this, the value must be a
regular expression object with four named capturing groups. The capturing
groups correspond to the rules given above, along with the invalid placeholder
rule:
* *escaped* -- This group matches the escape sequence, e.g. ``$$``, in the
default pattern.
* *named* -- This group matches the unbraced placeholder name; it should not
include the delimiter in capturing group.
* *braced* -- This group matches the brace enclosed placeholder name; it should
not include either the delimiter or braces in the capturing group.
* *invalid* -- This group matches any other delimiter pattern (usually a single
delimiter), and it should appear last in the regular expression.
String functions
----------------
The following functions are available to operate on string and Unicode objects.
They are not available as string methods.
.. function:: capwords(s[, sep])
Split the argument into words using :meth:`str.split`, capitalize each word
using :meth:`str.capitalize`, and join the capitalized words using
:meth:`str.join`. If the optional second argument *sep* is absent
or ``None``, runs of whitespace characters are replaced by a single space
and leading and trailing whitespace are removed, otherwise *sep* is used to
split and join the words.
.. function:: maketrans(from, to)
Return a translation table suitable for passing to :func:`translate`, that will
map each character in *from* into the character at the same position in *to*;
*from* and *to* must have the same length.
.. note::
Don't use strings derived from :const:`lowercase` and :const:`uppercase` as
arguments; in some locales, these don't have the same length. For case
conversions, always use :meth:`str.lower` and :meth:`str.upper`.
Deprecated string functions
---------------------------
The following list of functions are also defined as methods of string and
Unicode objects; see section :ref:`string-methods` for more information on
those. You should consider these functions as deprecated, although they will
not be removed until Python 3. The functions defined in this module are:
.. function:: atof(s)
.. deprecated:: 2.0
Use the :func:`float` built-in function.
.. index:: builtin: float
Convert a string to a floating point number. The string must have the standard
syntax for a floating point literal in Python, optionally preceded by a sign
(``+`` or ``-``). Note that this behaves identical to the built-in function
:func:`float` when passed a string.
.. note::
.. index::
single: NaN
single: Infinity
When passing in a string, values for NaN and Infinity may be returned, depending
on the underlying C library. The specific set of strings accepted which cause
these values to be returned depends entirely on the C library and is known to
vary.
.. function:: atoi(s[, base])
.. deprecated:: 2.0
Use the :func:`int` built-in function.
.. index:: builtin: eval
Convert string *s* to an integer in the given *base*. The string must consist
of one or more digits, optionally preceded by a sign (``+`` or ``-``). The
*base* defaults to 10. If it is 0, a default base is chosen depending on the
leading characters of the string (after stripping the sign): ``0x`` or ``0X``
means 16, ``0`` means 8, anything else means 10. If *base* is 16, a leading
``0x`` or ``0X`` is always accepted, though not required. This behaves
identically to the built-in function :func:`int` when passed a string. (Also
note: for a more flexible interpretation of numeric literals, use the built-in
function :func:`eval`.)
.. function:: atol(s[, base])
.. deprecated:: 2.0
Use the :func:`long` built-in function.
.. index:: builtin: long
Convert string *s* to a long integer in the given *base*. The string must
consist of one or more digits, optionally preceded by a sign (``+`` or ``-``).
The *base* argument has the same meaning as for :func:`atoi`. A trailing ``l``
or ``L`` is not allowed, except if the base is 0. Note that when invoked
without *base* or with *base* set to 10, this behaves identical to the built-in
function :func:`long` when passed a string.
.. function:: capitalize(word)
Return a copy of *word* with only its first character capitalized.
.. function:: expandtabs(s[, tabsize])
Expand tabs in a string replacing them by one or more spaces, depending on the
current column and the given tab size. The column number is reset to zero after
each newline occurring in the string. This doesn't understand other non-printing
characters or escape sequences. The tab size defaults to 8.
.. function:: find(s, sub[, start[,end]])
Return the lowest index in *s* where the substring *sub* is found such that
*sub* is wholly contained in ``s[start:end]``. Return ``-1`` on failure.
Defaults for *start* and *end* and interpretation of negative values is the same
as for slices.
.. function:: rfind(s, sub[, start[, end]])
Like :func:`find` but find the highest index.
.. function:: index(s, sub[, start[, end]])
Like :func:`find` but raise :exc:`ValueError` when the substring is not found.
.. function:: rindex(s, sub[, start[, end]])
Like :func:`rfind` but raise :exc:`ValueError` when the substring is not found.
.. function:: count(s, sub[, start[, end]])
Return the number of (non-overlapping) occurrences of substring *sub* in string
``s[start:end]``. Defaults for *start* and *end* and interpretation of negative
values are the same as for slices.
.. function:: lower(s)
Return a copy of *s*, but with upper case letters converted to lower case.
.. function:: split(s[, sep[, maxsplit]])
Return a list of the words of the string *s*. If the optional second argument
*sep* is absent or ``None``, the words are separated by arbitrary strings of
whitespace characters (space, tab, newline, return, formfeed). If the second
argument *sep* is present and not ``None``, it specifies a string to be used as
the word separator. The returned list will then have one more item than the
number of non-overlapping occurrences of the separator in the string.
If *maxsplit* is given, at most *maxsplit* number of splits occur, and the
remainder of the string is returned as the final element of the list (thus,
the list will have at most ``maxsplit+1`` elements). If *maxsplit* is not
specified or ``-1``, then there is no limit on the number of splits (all
possible splits are made).
The behavior of split on an empty string depends on the value of *sep*. If *sep*
is not specified, or specified as ``None``, the result will be an empty list.
If *sep* is specified as any string, the result will be a list containing one
element which is an empty string.
.. function:: rsplit(s[, sep[, maxsplit]])
Return a list of the words of the string *s*, scanning *s* from the end. To all
intents and purposes, the resulting list of words is the same as returned by
:func:`split`, except when the optional third argument *maxsplit* is explicitly
specified and nonzero. If *maxsplit* is given, at most *maxsplit* number of
splits -- the *rightmost* ones -- occur, and the remainder of the string is
returned as the first element of the list (thus, the list will have at most
``maxsplit+1`` elements).
.. versionadded:: 2.4
.. function:: splitfields(s[, sep[, maxsplit]])
This function behaves identically to :func:`split`. (In the past, :func:`split`
was only used with one argument, while :func:`splitfields` was only used with
two arguments.)
.. function:: join(words[, sep])
Concatenate a list or tuple of words with intervening occurrences of *sep*.
The default value for *sep* is a single space character. It is always true that
``string.join(string.split(s, sep), sep)`` equals *s*.
.. function:: joinfields(words[, sep])
This function behaves identically to :func:`join`. (In the past, :func:`join`
was only used with one argument, while :func:`joinfields` was only used with two
arguments.) Note that there is no :meth:`joinfields` method on string objects;
use the :meth:`join` method instead.
.. function:: lstrip(s[, chars])
Return a copy of the string with leading characters removed. If *chars* is
omitted or ``None``, whitespace characters are removed. If given and not
``None``, *chars* must be a string; the characters in the string will be
stripped from the beginning of the string this method is called on.
.. versionchanged:: 2.2.3
The *chars* parameter was added. The *chars* parameter cannot be passed in
earlier 2.2 versions.
.. function:: rstrip(s[, chars])
Return a copy of the string with trailing characters removed. If *chars* is
omitted or ``None``, whitespace characters are removed. If given and not
``None``, *chars* must be a string; the characters in the string will be
stripped from the end of the string this method is called on.
.. versionchanged:: 2.2.3
The *chars* parameter was added. The *chars* parameter cannot be passed in
earlier 2.2 versions.
.. function:: strip(s[, chars])
Return a copy of the string with leading and trailing characters removed. If
*chars* is omitted or ``None``, whitespace characters are removed. If given and
not ``None``, *chars* must be a string; the characters in the string will be
stripped from the both ends of the string this method is called on.
.. versionchanged:: 2.2.3
The *chars* parameter was added. The *chars* parameter cannot be passed in
earlier 2.2 versions.
.. function:: swapcase(s)
Return a copy of *s*, but with lower case letters converted to upper case and
vice versa.
.. function:: translate(s, table[, deletechars])
Delete all characters from *s* that are in *deletechars* (if present), and then
translate the characters using *table*, which must be a 256-character string
giving the translation for each character value, indexed by its ordinal. If
*table* is ``None``, then only the character deletion step is performed.
.. function:: upper(s)
Return a copy of *s*, but with lower case letters converted to upper case.
.. function:: ljust(s, width[, fillchar])
rjust(s, width[, fillchar])
center(s, width[, fillchar])
These functions respectively left-justify, right-justify and center a string in
a field of given width. They return a string that is at least *width*
characters wide, created by padding the string *s* with the character *fillchar*
(default is a space) until the given width on the right, left or both sides.
The string is never truncated.
.. function:: zfill(s, width)
Pad a numeric string *s* on the left with zero digits until the
given *width* is reached. Strings starting with a sign are handled
correctly.
.. function:: replace(s, old, new[, maxreplace])
Return a copy of string *s* with all occurrences of substring *old* replaced
by *new*. If the optional argument *maxreplace* is given, the first
*maxreplace* occurrences are replaced.
PK
%�\
8 QF F & html/_sources/library/stringio.rst.txtnu �[���
:mod:`StringIO` --- Read and write strings as files
===================================================
.. module:: StringIO
:synopsis: Read and write strings as if they were files.
This module implements a file-like class, :class:`~StringIO.StringIO`, that reads and
writes a string buffer (also known as *memory files*). See the description of
file objects for operations (section :ref:`bltin-file-objects`). (For
standard strings, see :class:`str` and :class:`unicode`.)
.. class:: StringIO([buffer])
When a :class:`~StringIO.StringIO` object is created, it can be initialized to an existing
string by passing the string to the constructor. If no string is given, the
:class:`~StringIO.StringIO` will start empty. In both cases, the initial file position
starts at zero.
The :class:`~StringIO.StringIO` object can accept either Unicode or 8-bit strings, but
mixing the two may take some care. If both are used, 8-bit strings that cannot
be interpreted as 7-bit ASCII (that use the 8th bit) will cause a
:exc:`UnicodeError` to be raised when :meth:`getvalue` is called.
The following methods of :class:`~StringIO.StringIO` objects require special mention:
.. method:: StringIO.getvalue()
Retrieve the entire contents of the "file" at any time before the
:class:`~StringIO.StringIO` object's :meth:`close` method is called. See the note above
for information about mixing Unicode and 8-bit strings; such mixing can cause
this method to raise :exc:`UnicodeError`.
.. method:: StringIO.close()
Free the memory buffer. Attempting to do further operations with a closed
:class:`~StringIO.StringIO` object will raise a :exc:`ValueError`.
Example usage::
import StringIO
output = StringIO.StringIO()
output.write('First line.\n')
print >>output, 'Second line.'
# Retrieve file contents -- this will be
# 'First line.\nSecond line.\n'
contents = output.getvalue()
# Close object and discard memory buffer --
# .getvalue() will now raise an exception.
output.close()
:mod:`cStringIO` --- Faster version of :mod:`StringIO`
======================================================
.. module:: cStringIO
:synopsis: Faster version of StringIO, but not subclassable.
.. moduleauthor:: Jim Fulton <jim@zope.com>
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
The module :mod:`cStringIO` provides an interface similar to that of the
:mod:`StringIO` module. Heavy use of :class:`StringIO.StringIO` objects can be
made more efficient by using the function :func:`StringIO` from this module
instead.
.. function:: StringIO([s])
Return a StringIO-like stream for reading or writing.
Since this is a factory function which returns objects of built-in types,
there's no way to build your own version using subclassing. It's not
possible to set attributes on it. Use the original :mod:`StringIO` module in
those cases.
Unlike the :mod:`StringIO` module, this module is not able to accept Unicode
strings that cannot be encoded as plain ASCII strings.
Another difference from the :mod:`StringIO` module is that calling
:func:`StringIO` with a string parameter creates a read-only object. Unlike an
object created without a string parameter, it does not have write methods.
These objects are not generally visible. They turn up in tracebacks as
:class:`StringI` and :class:`StringO`.
The following data objects are provided as well:
.. data:: InputType
The type object of the objects created by calling :func:`StringIO` with a string
parameter.
.. data:: OutputType
The type object of the objects returned by calling :func:`StringIO` with no
parameters.
There is a C API to the module as well; refer to the module source for more
information.
Example usage::
import cStringIO
output = cStringIO.StringIO()
output.write('First line.\n')
print >>output, 'Second line.'
# Retrieve file contents -- this will be
# 'First line.\nSecond line.\n'
contents = output.getvalue()
# Close object and discard memory buffer --
# .getvalue() will now raise an exception.
output.close()
PK
%�\�lЎ � ( html/_sources/library/stringprep.rst.txtnu �[���
:mod:`stringprep` --- Internet String Preparation
=================================================
.. module:: stringprep
:synopsis: String preparation, as per RFC 3453
.. moduleauthor:: Martin v. Löwis <martin@v.loewis.de>
.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
.. versionadded:: 2.3
When identifying things (such as host names) in the internet, it is often
necessary to compare such identifications for "equality". Exactly how this
comparison is executed may depend on the application domain, e.g. whether it
should be case-insensitive or not. It may be also necessary to restrict the
possible identifications, to allow only identifications consisting of
"printable" characters.
:rfc:`3454` defines a procedure for "preparing" Unicode strings in internet
protocols. Before passing strings onto the wire, they are processed with the
preparation procedure, after which they have a certain normalized form. The RFC
defines a set of tables, which can be combined into profiles. Each profile must
define which tables it uses, and what other optional parts of the ``stringprep``
procedure are part of the profile. One example of a ``stringprep`` profile is
``nameprep``, which is used for internationalized domain names.
The module :mod:`stringprep` only exposes the tables from RFC 3454. As these
tables would be very large to represent them as dictionaries or lists, the
module uses the Unicode character database internally. The module source code
itself was generated using the ``mkstringprep.py`` utility.
As a result, these tables are exposed as functions, not as data structures.
There are two kinds of tables in the RFC: sets and mappings. For a set,
:mod:`stringprep` provides the "characteristic function", i.e. a function that
returns true if the parameter is part of the set. For mappings, it provides the
mapping function: given the key, it returns the associated value. Below is a
list of all functions available in the module.
.. function:: in_table_a1(code)
Determine whether *code* is in tableA.1 (Unassigned code points in Unicode 3.2).
.. function:: in_table_b1(code)
Determine whether *code* is in tableB.1 (Commonly mapped to nothing).
.. function:: map_table_b2(code)
Return the mapped value for *code* according to tableB.2 (Mapping for
case-folding used with NFKC).
.. function:: map_table_b3(code)
Return the mapped value for *code* according to tableB.3 (Mapping for
case-folding used with no normalization).
.. function:: in_table_c11(code)
Determine whether *code* is in tableC.1.1 (ASCII space characters).
.. function:: in_table_c12(code)
Determine whether *code* is in tableC.1.2 (Non-ASCII space characters).
.. function:: in_table_c11_c12(code)
Determine whether *code* is in tableC.1 (Space characters, union of C.1.1 and
C.1.2).
.. function:: in_table_c21(code)
Determine whether *code* is in tableC.2.1 (ASCII control characters).
.. function:: in_table_c22(code)
Determine whether *code* is in tableC.2.2 (Non-ASCII control characters).
.. function:: in_table_c21_c22(code)
Determine whether *code* is in tableC.2 (Control characters, union of C.2.1 and
C.2.2).
.. function:: in_table_c3(code)
Determine whether *code* is in tableC.3 (Private use).
.. function:: in_table_c4(code)
Determine whether *code* is in tableC.4 (Non-character code points).
.. function:: in_table_c5(code)
Determine whether *code* is in tableC.5 (Surrogate codes).
.. function:: in_table_c6(code)
Determine whether *code* is in tableC.6 (Inappropriate for plain text).
.. function:: in_table_c7(code)
Determine whether *code* is in tableC.7 (Inappropriate for canonical
representation).
.. function:: in_table_c8(code)
Determine whether *code* is in tableC.8 (Change display properties or are
deprecated).
.. function:: in_table_c9(code)
Determine whether *code* is in tableC.9 (Tagging characters).
.. function:: in_table_d1(code)
Determine whether *code* is in tableD.1 (Characters with bidirectional property
"R" or "AL").
.. function:: in_table_d2(code)
Determine whether *code* is in tableD.2 (Characters with bidirectional property
"L").
PK
%�\���� � % html/_sources/library/strings.rst.txtnu �[���
.. _stringservices:
***************
String Services
***************
The modules described in this chapter provide a wide range of string
manipulation operations.
In addition, Python's built-in string classes support the sequence type
methods described in the :ref:`typesseq` section, and also the
string-specific methods described in the :ref:`string-methods` section.
To output formatted strings use template strings or the ``%`` operator
described in the :ref:`string-formatting` section. Also, see the
:mod:`re` module for string functions based on regular expressions.
.. toctree::
string.rst
re.rst
struct.rst
difflib.rst
stringio.rst
textwrap.rst
codecs.rst
unicodedata.rst
stringprep.rst
fpformat.rst
PK
%�\٦� �B �B $ html/_sources/library/struct.rst.txtnu �[���
:mod:`struct` --- Interpret strings as packed binary data
=========================================================
.. module:: struct
:synopsis: Interpret strings as packed binary data.
.. index::
pair: C; structures
triple: packing; binary; data
This module performs conversions between Python values and C structs represented
as Python strings. This can be used in handling binary data stored in files or
from network connections, among other sources. It uses
:ref:`struct-format-strings` as compact descriptions of the layout of the C
structs and the intended conversion to/from Python values.
.. note::
By default, the result of packing a given C struct includes pad bytes in
order to maintain proper alignment for the C types involved; similarly,
alignment is taken into account when unpacking. This behavior is chosen so
that the bytes of a packed struct correspond exactly to the layout in memory
of the corresponding C struct. To handle platform-independent data formats
or omit implicit pad bytes, use ``standard`` size and alignment instead of
``native`` size and alignment: see :ref:`struct-alignment` for details.
Functions and Exceptions
------------------------
The module defines the following exception and functions:
.. exception:: error
Exception raised on various occasions; argument is a string describing what
is wrong.
.. function:: pack(fmt, v1, v2, ...)
Return a string containing the values ``v1, v2, ...`` packed according to the
given format. The arguments must match the values required by the format
exactly.
.. function:: pack_into(fmt, buffer, offset, v1, v2, ...)
Pack the values ``v1, v2, ...`` according to the given format, write the
packed bytes into the writable *buffer* starting at *offset*. Note that the
offset is a required argument.
.. versionadded:: 2.5
.. function:: unpack(fmt, string)
Unpack the string (presumably packed by ``pack(fmt, ...)``) according to the
given format. The result is a tuple even if it contains exactly one item.
The string must contain exactly the amount of data required by the format
(``len(string)`` must equal ``calcsize(fmt)``).
.. function:: unpack_from(fmt, buffer[,offset=0])
Unpack the *buffer* according to the given format. The result is a tuple even
if it contains exactly one item. The *buffer* must contain at least the
amount of data required by the format (``len(buffer[offset:])`` must be at
least ``calcsize(fmt)``).
.. versionadded:: 2.5
.. function:: calcsize(fmt)
Return the size of the struct (and hence of the string) corresponding to the
given format.
.. _struct-format-strings:
Format Strings
--------------
Format strings are the mechanism used to specify the expected layout when
packing and unpacking data. They are built up from :ref:`format-characters`,
which specify the type of data being packed/unpacked. In addition, there are
special characters for controlling the :ref:`struct-alignment`.
.. _struct-alignment:
Byte Order, Size, and Alignment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
By default, C types are represented in the machine's native format and byte
order, and properly aligned by skipping pad bytes if necessary (according to the
rules used by the C compiler).
Alternatively, the first character of the format string can be used to indicate
the byte order, size and alignment of the packed data, according to the
following table:
+-----------+------------------------+----------+-----------+
| Character | Byte order | Size | Alignment |
+===========+========================+==========+===========+
| ``@`` | native | native | native |
+-----------+------------------------+----------+-----------+
| ``=`` | native | standard | none |
+-----------+------------------------+----------+-----------+
| ``<`` | little-endian | standard | none |
+-----------+------------------------+----------+-----------+
| ``>`` | big-endian | standard | none |
+-----------+------------------------+----------+-----------+
| ``!`` | network (= big-endian) | standard | none |
+-----------+------------------------+----------+-----------+
If the first character is not one of these, ``'@'`` is assumed.
Native byte order is big-endian or little-endian, depending on the host
system. For example, Intel x86 and AMD64 (x86-64) are little-endian;
Motorola 68000 and PowerPC G5 are big-endian; ARM and Intel Itanium feature
switchable endianness (bi-endian). Use ``sys.byteorder`` to check the
endianness of your system.
Native size and alignment are determined using the C compiler's
``sizeof`` expression. This is always combined with native byte order.
Standard size depends only on the format character; see the table in
the :ref:`format-characters` section.
Note the difference between ``'@'`` and ``'='``: both use native byte order, but
the size and alignment of the latter is standardized.
The form ``'!'`` is available for those poor souls who claim they can't remember
whether network byte order is big-endian or little-endian.
There is no way to indicate non-native byte order (force byte-swapping); use the
appropriate choice of ``'<'`` or ``'>'``.
Notes:
(1) Padding is only automatically added between successive structure members.
No padding is added at the beginning or the end of the encoded struct.
(2) No padding is added when using non-native size and alignment, e.g.
with '<', '>', '=', and '!'.
(3) To align the end of a structure to the alignment requirement of a
particular type, end the format with the code for that type with a repeat
count of zero. See :ref:`struct-examples`.
.. _format-characters:
Format Characters
^^^^^^^^^^^^^^^^^
Format characters have the following meaning; the conversion between C and
Python values should be obvious given their types. The 'Standard size' column
refers to the size of the packed value in bytes when using standard size; that
is, when the format string starts with one of ``'<'``, ``'>'``, ``'!'`` or
``'='``. When using native size, the size of the packed value is
platform-dependent.
+--------+--------------------------+--------------------+----------------+------------+
| Format | C Type | Python type | Standard size | Notes |
+========+==========================+====================+================+============+
| ``x`` | pad byte | no value | | |
+--------+--------------------------+--------------------+----------------+------------+
| ``c`` | :c:type:`char` | string of length 1 | 1 | |
+--------+--------------------------+--------------------+----------------+------------+
| ``b`` | :c:type:`signed char` | integer | 1 | \(3) |
+--------+--------------------------+--------------------+----------------+------------+
| ``B`` | :c:type:`unsigned char` | integer | 1 | \(3) |
+--------+--------------------------+--------------------+----------------+------------+
| ``?`` | :c:type:`_Bool` | bool | 1 | \(1) |
+--------+--------------------------+--------------------+----------------+------------+
| ``h`` | :c:type:`short` | integer | 2 | \(3) |
+--------+--------------------------+--------------------+----------------+------------+
| ``H`` | :c:type:`unsigned short` | integer | 2 | \(3) |
+--------+--------------------------+--------------------+----------------+------------+
| ``i`` | :c:type:`int` | integer | 4 | \(3) |
+--------+--------------------------+--------------------+----------------+------------+
| ``I`` | :c:type:`unsigned int` | integer | 4 | \(3) |
+--------+--------------------------+--------------------+----------------+------------+
| ``l`` | :c:type:`long` | integer | 4 | \(3) |
+--------+--------------------------+--------------------+----------------+------------+
| ``L`` | :c:type:`unsigned long` | integer | 4 | \(3) |
+--------+--------------------------+--------------------+----------------+------------+
| ``q`` | :c:type:`long long` | integer | 8 | \(2), \(3) |
+--------+--------------------------+--------------------+----------------+------------+
| ``Q`` | :c:type:`unsigned long | integer | 8 | \(2), \(3) |
| | long` | | | |
+--------+--------------------------+--------------------+----------------+------------+
| ``f`` | :c:type:`float` | float | 4 | \(4) |
+--------+--------------------------+--------------------+----------------+------------+
| ``d`` | :c:type:`double` | float | 8 | \(4) |
+--------+--------------------------+--------------------+----------------+------------+
| ``s`` | :c:type:`char[]` | string | | |
+--------+--------------------------+--------------------+----------------+------------+
| ``p`` | :c:type:`char[]` | string | | |
+--------+--------------------------+--------------------+----------------+------------+
| ``P`` | :c:type:`void \*` | integer | | \(5), \(3) |
+--------+--------------------------+--------------------+----------------+------------+
Notes:
(1)
The ``'?'`` conversion code corresponds to the :c:type:`_Bool` type defined by
C99. If this type is not available, it is simulated using a :c:type:`char`. In
standard mode, it is always represented by one byte.
.. versionadded:: 2.6
(2)
The ``'q'`` and ``'Q'`` conversion codes are available in native mode only if
the platform C compiler supports C :c:type:`long long`, or, on Windows,
:c:type:`__int64`. They are always available in standard modes.
.. versionadded:: 2.2
(3)
When attempting to pack a non-integer using any of the integer conversion
codes, if the non-integer has a :meth:`__index__` method then that method is
called to convert the argument to an integer before packing. If no
:meth:`__index__` method exists, or the call to :meth:`__index__` raises
:exc:`TypeError`, then the :meth:`__int__` method is tried. However, the use
of :meth:`__int__` is deprecated, and will raise :exc:`DeprecationWarning`.
.. versionchanged:: 2.7
Use of the :meth:`__index__` method for non-integers is new in 2.7.
.. versionchanged:: 2.7
Prior to version 2.7, not all integer conversion codes would use the
:meth:`__int__` method to convert, and :exc:`DeprecationWarning` was
raised only for float arguments.
(4)
For the ``'f'`` and ``'d'`` conversion codes, the packed representation uses
the IEEE 754 binary32 (for ``'f'``) or binary64 (for ``'d'``) format,
regardless of the floating-point format used by the platform.
(5)
The ``'P'`` format character is only available for the native byte ordering
(selected as the default or with the ``'@'`` byte order character). The byte
order character ``'='`` chooses to use little- or big-endian ordering based
on the host system. The struct module does not interpret this as native
ordering, so the ``'P'`` format is not available.
A format character may be preceded by an integral repeat count. For example,
the format string ``'4h'`` means exactly the same as ``'hhhh'``.
Whitespace characters between formats are ignored; a count and its format must
not contain whitespace though.
For the ``'s'`` format character, the count is interpreted as the size of the
string, not a repeat count like for the other format characters; for example,
``'10s'`` means a single 10-byte string, while ``'10c'`` means 10 characters.
If a count is not given, it defaults to 1. For packing, the string is
truncated or padded with null bytes as appropriate to make it fit. For
unpacking, the resulting string always has exactly the specified number of
bytes. As a special case, ``'0s'`` means a single, empty string (while
``'0c'`` means 0 characters).
The ``'p'`` format character encodes a "Pascal string", meaning a short
variable-length string stored in a *fixed number of bytes*, given by the count.
The first byte stored is the length of the string, or 255, whichever is smaller.
The bytes of the string follow. If the string passed in to :func:`pack` is too
long (longer than the count minus 1), only the leading ``count-1`` bytes of the
string are stored. If the string is shorter than ``count-1``, it is padded with
null bytes so that exactly count bytes in all are used. Note that for
:func:`unpack`, the ``'p'`` format character consumes count bytes, but that the
string returned can never contain more than 255 characters.
For the ``'P'`` format character, the return value is a Python integer or long
integer, depending on the size needed to hold a pointer when it has been cast to
an integer type. A *NULL* pointer will always be returned as the Python integer
``0``. When packing pointer-sized values, Python integer or long integer objects
may be used. For example, the Alpha and Merced processors use 64-bit pointer
values, meaning a Python long integer will be used to hold the pointer; other
platforms use 32-bit pointers and will use a Python integer.
For the ``'?'`` format character, the return value is either :const:`True` or
:const:`False`. When packing, the truth value of the argument object is used.
Either 0 or 1 in the native or standard bool representation will be packed, and
any non-zero value will be ``True`` when unpacking.
.. _struct-examples:
Examples
^^^^^^^^
.. note::
All examples assume a native byte order, size, and alignment with a
big-endian machine.
A basic example of packing/unpacking three integers::
>>> from struct import *
>>> pack('hhl', 1, 2, 3)
'\x00\x01\x00\x02\x00\x00\x00\x03'
>>> unpack('hhl', '\x00\x01\x00\x02\x00\x00\x00\x03')
(1, 2, 3)
>>> calcsize('hhl')
8
Unpacked fields can be named by assigning them to variables or by wrapping
the result in a named tuple::
>>> record = 'raymond \x32\x12\x08\x01\x08'
>>> name, serialnum, school, gradelevel = unpack('<10sHHb', record)
>>> from collections import namedtuple
>>> Student = namedtuple('Student', 'name serialnum school gradelevel')
>>> Student._make(unpack('<10sHHb', record))
Student(name='raymond ', serialnum=4658, school=264, gradelevel=8)
The ordering of format characters may have an impact on size since the padding
needed to satisfy alignment requirements is different::
>>> pack('ci', '*', 0x12131415)
'*\x00\x00\x00\x12\x13\x14\x15'
>>> pack('ic', 0x12131415, '*')
'\x12\x13\x14\x15*'
>>> calcsize('ci')
8
>>> calcsize('ic')
5
The following format ``'llh0l'`` specifies two pad bytes at the end, assuming
longs are aligned on 4-byte boundaries::
>>> pack('llh0l', 1, 2, 3)
'\x00\x00\x00\x01\x00\x00\x00\x02\x00\x03\x00\x00'
This only works when native size and alignment are in effect; standard size and
alignment does not enforce any alignment.
.. seealso::
Module :mod:`array`
Packed binary storage of homogeneous data.
Module :mod:`xdrlib`
Packing and unpacking of XDR data.
.. _struct-objects:
Classes
-------
The :mod:`struct` module also defines the following type:
.. class:: Struct(format)
Return a new Struct object which writes and reads binary data according to
the format string *format*. Creating a Struct object once and calling its
methods is more efficient than calling the :mod:`struct` functions with the
same format since the format string only needs to be compiled once.
.. versionadded:: 2.5
Compiled Struct objects support the following methods and attributes:
.. method:: pack(v1, v2, ...)
Identical to the :func:`pack` function, using the compiled format.
(``len(result)`` will equal :attr:`self.size`.)
.. method:: pack_into(buffer, offset, v1, v2, ...)
Identical to the :func:`pack_into` function, using the compiled format.
.. method:: unpack(string)
Identical to the :func:`unpack` function, using the compiled format.
(``len(string)`` must equal :attr:`self.size`).
.. method:: unpack_from(buffer, offset=0)
Identical to the :func:`unpack_from` function, using the compiled format.
(``len(buffer[offset:])`` must be at least :attr:`self.size`).
.. attribute:: format
The format string used to construct this Struct object.
.. attribute:: size
The calculated size of the struct (and hence of the string) corresponding
to :attr:`format`.
PK
%�\
p� p� ( html/_sources/library/subprocess.rst.txtnu �[���
:mod:`subprocess` --- Subprocess management
===========================================
.. module:: subprocess
:synopsis: Subprocess management.
.. moduleauthor:: Peter Åstrand <astrand@lysator.liu.se>
.. sectionauthor:: Peter Åstrand <astrand@lysator.liu.se>
.. versionadded:: 2.4
The :mod:`subprocess` module allows you to spawn new processes, connect to their
input/output/error pipes, and obtain their return codes. This module intends to
replace several older modules and functions::
os.system
os.spawn*
os.popen*
popen2.*
commands.*
Information about how this module can be used to replace the older
functions can be found in the subprocess-replacements_ section.
.. seealso::
POSIX users (Linux, BSD, etc.) are strongly encouraged to install
and use the much more recent subprocess32_ module instead of the
version included with python 2.7. It is a drop in replacement with
better behavior in many situations.
:pep:`324` -- PEP proposing the subprocess module
.. _subprocess32: https://pypi.org/project/subprocess32/
Using the :mod:`subprocess` Module
----------------------------------
The recommended way to launch subprocesses is to use the following
convenience functions. For more advanced use cases when these do not
meet your needs, use the underlying :class:`Popen` interface.
.. function:: call(args, *, stdin=None, stdout=None, stderr=None, shell=False)
Run the command described by *args*. Wait for command to complete, then
return the :attr:`returncode` attribute.
The arguments shown above are merely the most common ones, described below
in :ref:`frequently-used-arguments` (hence the slightly odd notation in
the abbreviated signature). The full function signature is the same as
that of the :class:`Popen` constructor - this functions passes all
supplied arguments directly through to that interface.
Examples::
>>> subprocess.call(["ls", "-l"])
0
>>> subprocess.call("exit 1", shell=True)
1
.. warning::
Using ``shell=True`` can be a security hazard. See the warning
under :ref:`frequently-used-arguments` for details.
.. note::
Do not use ``stdout=PIPE`` or ``stderr=PIPE`` with this function
as that can deadlock based on the child process output volume.
Use :class:`Popen` with the :meth:`communicate` method when you
need pipes.
.. function:: check_call(args, *, stdin=None, stdout=None, stderr=None, shell=False)
Run command with arguments. Wait for command to complete. If the return
code was zero then return, otherwise raise :exc:`CalledProcessError`. The
:exc:`CalledProcessError` object will have the return code in the
:attr:`~CalledProcessError.returncode` attribute.
The arguments shown above are merely the most common ones, described below
in :ref:`frequently-used-arguments` (hence the slightly odd notation in
the abbreviated signature). The full function signature is the same as
that of the :class:`Popen` constructor - this functions passes all
supplied arguments directly through to that interface.
Examples::
>>> subprocess.check_call(["ls", "-l"])
0
>>> subprocess.check_call("exit 1", shell=True)
Traceback (most recent call last):
...
subprocess.CalledProcessError: Command 'exit 1' returned non-zero exit status 1
.. versionadded:: 2.5
.. warning::
Using ``shell=True`` can be a security hazard. See the warning
under :ref:`frequently-used-arguments` for details.
.. note::
Do not use ``stdout=PIPE`` or ``stderr=PIPE`` with this function
as that can deadlock based on the child process output volume.
Use :class:`Popen` with the :meth:`communicate` method when you
need pipes.
.. function:: check_output(args, *, stdin=None, stderr=None, shell=False, universal_newlines=False)
Run command with arguments and return its output as a byte string.
If the return code was non-zero it raises a :exc:`CalledProcessError`. The
:exc:`CalledProcessError` object will have the return code in the
:attr:`~CalledProcessError.returncode` attribute and any output in the
:attr:`~CalledProcessError.output` attribute.
The arguments shown above are merely the most common ones, described below
in :ref:`frequently-used-arguments` (hence the slightly odd notation in
the abbreviated signature). The full function signature is largely the
same as that of the :class:`Popen` constructor, except that *stdout* is
not permitted as it is used internally. All other supplied arguments are
passed directly through to the :class:`Popen` constructor.
Examples::
>>> subprocess.check_output(["echo", "Hello World!"])
'Hello World!\n'
>>> subprocess.check_output("exit 1", shell=True)
Traceback (most recent call last):
...
subprocess.CalledProcessError: Command 'exit 1' returned non-zero exit status 1
To also capture standard error in the result, use
``stderr=subprocess.STDOUT``::
>>> subprocess.check_output(
... "ls non_existent_file; exit 0",
... stderr=subprocess.STDOUT,
... shell=True)
'ls: non_existent_file: No such file or directory\n'
.. versionadded:: 2.7
.. warning::
Using ``shell=True`` can be a security hazard. See the warning
under :ref:`frequently-used-arguments` for details.
.. note::
Do not use ``stderr=PIPE`` with this function as that can deadlock
based on the child process error volume. Use :class:`Popen` with
the :meth:`communicate` method when you need a stderr pipe.
.. data:: PIPE
Special value that can be used as the *stdin*, *stdout* or *stderr* argument
to :class:`Popen` and indicates that a pipe to the standard stream should be
opened.
.. data:: STDOUT
Special value that can be used as the *stderr* argument to :class:`Popen` and
indicates that standard error should go into the same handle as standard
output.
.. exception:: CalledProcessError
Exception raised when a process run by :func:`check_call` or
:func:`check_output` returns a non-zero exit status.
.. attribute:: returncode
Exit status of the child process.
.. attribute:: cmd
Command that was used to spawn the child process.
.. attribute:: output
Output of the child process if this exception is raised by
:func:`check_output`. Otherwise, ``None``.
.. _frequently-used-arguments:
Frequently Used Arguments
^^^^^^^^^^^^^^^^^^^^^^^^^
To support a wide variety of use cases, the :class:`Popen` constructor (and
the convenience functions) accept a large number of optional arguments. For
most typical use cases, many of these arguments can be safely left at their
default values. The arguments that are most commonly needed are:
*args* is required for all calls and should be a string, or a sequence of
program arguments. Providing a sequence of arguments is generally
preferred, as it allows the module to take care of any required escaping
and quoting of arguments (e.g. to permit spaces in file names). If passing
a single string, either *shell* must be :const:`True` (see below) or else
the string must simply name the program to be executed without specifying
any arguments.
*stdin*, *stdout* and *stderr* specify the executed program's standard input,
standard output and standard error file handles, respectively. Valid values
are :data:`PIPE`, an existing file descriptor (a positive integer), an
existing file object, and ``None``. :data:`PIPE` indicates that a new pipe
to the child should be created. With the default settings of ``None``, no
redirection will occur; the child's file handles will be inherited from the
parent. Additionally, *stderr* can be :data:`STDOUT`, which indicates that
the stderr data from the child process should be captured into the same file
handle as for stdout.
.. index::
single: universal newlines; subprocess module
When *stdout* or *stderr* are pipes and *universal_newlines* is
``True`` then all line endings will be converted to ``'\n'`` as described
for the :term:`universal newlines` ``'U'`` mode argument to :func:`open`.
If *shell* is ``True``, the specified command will be executed through
the shell. This can be useful if you are using Python primarily for the
enhanced control flow it offers over most system shells and still want
convenient access to other shell features such as shell pipes, filename
wildcards, environment variable expansion, and expansion of ``~`` to a
user's home directory. However, note that Python itself offers
implementations of many shell-like features (in particular, :mod:`glob`,
:mod:`fnmatch`, :func:`os.walk`, :func:`os.path.expandvars`,
:func:`os.path.expanduser`, and :mod:`shutil`).
.. warning::
Executing shell commands that incorporate unsanitized input from an
untrusted source makes a program vulnerable to `shell injection
<http://en.wikipedia.org/wiki/Shell_injection#Shell_injection>`_,
a serious security flaw which can result in arbitrary command execution.
For this reason, the use of ``shell=True`` is **strongly discouraged**
in cases where the command string is constructed from external input::
>>> from subprocess import call
>>> filename = input("What file would you like to display?\n")
What file would you like to display?
non_existent; rm -rf / #
>>> call("cat " + filename, shell=True) # Uh-oh. This will end badly...
``shell=False`` disables all shell based features, but does not suffer
from this vulnerability; see the Note in the :class:`Popen` constructor
documentation for helpful hints in getting ``shell=False`` to work.
When using ``shell=True``, :func:`pipes.quote` can be used to properly
escape whitespace and shell metacharacters in strings that are going to
be used to construct shell commands.
These options, along with all of the other options, are described in more
detail in the :class:`Popen` constructor documentation.
Popen Constructor
^^^^^^^^^^^^^^^^^
The underlying process creation and management in this module is handled by
the :class:`Popen` class. It offers a lot of flexibility so that developers
are able to handle the less common cases not covered by the convenience
functions.
.. class:: Popen(args, bufsize=0, executable=None, stdin=None, stdout=None, \
stderr=None, preexec_fn=None, close_fds=False, shell=False, \
cwd=None, env=None, universal_newlines=False, \
startupinfo=None, creationflags=0)
Execute a child program in a new process. On Unix, the class uses
:meth:`os.execvp`-like behavior to execute the child program. On Windows,
the class uses the Windows ``CreateProcess()`` function. The arguments to
:class:`Popen` are as follows.
*args* should be a sequence of program arguments or else a single string.
By default, the program to execute is the first item in *args* if *args* is
a sequence. If *args* is a string, the interpretation is
platform-dependent and described below. See the *shell* and *executable*
arguments for additional differences from the default behavior. Unless
otherwise stated, it is recommended to pass *args* as a sequence.
On Unix, if *args* is a string, the string is interpreted as the name or
path of the program to execute. However, this can only be done if not
passing arguments to the program.
.. note::
:meth:`shlex.split` can be useful when determining the correct
tokenization for *args*, especially in complex cases::
>>> import shlex, subprocess
>>> command_line = raw_input()
/bin/vikings -input eggs.txt -output "spam spam.txt" -cmd "echo '$MONEY'"
>>> args = shlex.split(command_line)
>>> print args
['/bin/vikings', '-input', 'eggs.txt', '-output', 'spam spam.txt', '-cmd', "echo '$MONEY'"]
>>> p = subprocess.Popen(args) # Success!
Note in particular that options (such as *-input*) and arguments (such
as *eggs.txt*) that are separated by whitespace in the shell go in separate
list elements, while arguments that need quoting or backslash escaping when
used in the shell (such as filenames containing spaces or the *echo* command
shown above) are single list elements.
On Windows, if *args* is a sequence, it will be converted to a string in a
manner described in :ref:`converting-argument-sequence`. This is because
the underlying ``CreateProcess()`` operates on strings.
The *shell* argument (which defaults to ``False``) specifies whether to use
the shell as the program to execute. If *shell* is ``True``, it is
recommended to pass *args* as a string rather than as a sequence.
On Unix with ``shell=True``, the shell defaults to :file:`/bin/sh`. If
*args* is a string, the string specifies the command
to execute through the shell. This means that the string must be
formatted exactly as it would be when typed at the shell prompt. This
includes, for example, quoting or backslash escaping filenames with spaces in
them. If *args* is a sequence, the first item specifies the command string, and
any additional items will be treated as additional arguments to the shell
itself. That is to say, :class:`Popen` does the equivalent of::
Popen(['/bin/sh', '-c', args[0], args[1], ...])
On Windows with ``shell=True``, the :envvar:`COMSPEC` environment variable
specifies the default shell. The only time you need to specify
``shell=True`` on Windows is when the command you wish to execute is built
into the shell (e.g. :command:`dir` or :command:`copy`). You do not need
``shell=True`` to run a batch file or console-based executable.
.. warning::
Passing ``shell=True`` can be a security hazard if combined with
untrusted input. See the warning under :ref:`frequently-used-arguments`
for details.
*bufsize*, if given, has the same meaning as the corresponding argument to the
built-in open() function: :const:`0` means unbuffered, :const:`1` means line
buffered, any other positive value means use a buffer of (approximately) that
size. A negative *bufsize* means to use the system default, which usually means
fully buffered. The default value for *bufsize* is :const:`0` (unbuffered).
.. note::
If you experience performance issues, it is recommended that you try to
enable buffering by setting *bufsize* to either -1 or a large enough
positive value (such as 4096).
The *executable* argument specifies a replacement program to execute. It
is very seldom needed. When ``shell=False``, *executable* replaces the
program to execute specified by *args*. However, the original *args* is
still passed to the program. Most programs treat the program specified
by *args* as the command name, which can then be different from the program
actually executed. On Unix, the *args* name
becomes the display name for the executable in utilities such as
:program:`ps`. If ``shell=True``, on Unix the *executable* argument
specifies a replacement shell for the default :file:`/bin/sh`.
*stdin*, *stdout* and *stderr* specify the executed program's standard input,
standard output and standard error file handles, respectively. Valid values
are :data:`PIPE`, an existing file descriptor (a positive integer), an
existing file object, and ``None``. :data:`PIPE` indicates that a new pipe
to the child should be created. With the default settings of ``None``, no
redirection will occur; the child's file handles will be inherited from the
parent. Additionally, *stderr* can be :data:`STDOUT`, which indicates that
the stderr data from the child process should be captured into the same file
handle as for stdout.
If *preexec_fn* is set to a callable object, this object will be called in the
child process just before the child is executed. (Unix only)
If *close_fds* is true, all file descriptors except :const:`0`, :const:`1` and
:const:`2` will be closed before the child process is executed. (Unix only).
Or, on Windows, if *close_fds* is true then no handles will be inherited by the
child process. Note that on Windows, you cannot set *close_fds* to true and
also redirect the standard handles by setting *stdin*, *stdout* or *stderr*.
If *cwd* is not ``None``, the child's current directory will be changed to *cwd*
before it is executed. Note that this directory is not considered when
searching the executable, so you can't specify the program's path relative to
*cwd*.
If *env* is not ``None``, it must be a mapping that defines the environment
variables for the new process; these are used instead of inheriting the current
process' environment, which is the default behavior.
.. note::
If specified, *env* must provide any variables required
for the program to execute. On Windows, in order to run a
`side-by-side assembly`_ the specified *env* **must** include a valid
:envvar:`SystemRoot`.
.. _side-by-side assembly: https://en.wikipedia.org/wiki/Side-by-Side_Assembly
If *universal_newlines* is ``True``, the file objects *stdout* and *stderr*
are opened as text files in :term:`universal newlines` mode. Lines may be
terminated by any of ``'\n'``, the Unix end-of-line convention, ``'\r'``,
the old Macintosh convention or ``'\r\n'``, the Windows convention. All of
these external representations are seen as ``'\n'`` by the Python program.
.. note::
This feature is only available if Python is built with universal newline
support (the default). Also, the newlines attribute of the file objects
:attr:`stdout`, :attr:`stdin` and :attr:`stderr` are not updated by the
communicate() method.
If given, *startupinfo* will be a :class:`STARTUPINFO` object, which is
passed to the underlying ``CreateProcess`` function.
*creationflags*, if given, can be :data:`CREATE_NEW_CONSOLE` or
:data:`CREATE_NEW_PROCESS_GROUP`. (Windows only)
Exceptions
^^^^^^^^^^
Exceptions raised in the child process, before the new program has started to
execute, will be re-raised in the parent. Additionally, the exception object
will have one extra attribute called :attr:`child_traceback`, which is a string
containing traceback information from the child's point of view.
The most common exception raised is :exc:`OSError`. This occurs, for example,
when trying to execute a non-existent file. Applications should prepare for
:exc:`OSError` exceptions.
A :exc:`ValueError` will be raised if :class:`Popen` is called with invalid
arguments.
:func:`check_call` and :func:`check_output` will raise
:exc:`CalledProcessError` if the called process returns a non-zero return
code.
Security
^^^^^^^^
Unlike some other popen functions, this implementation will never call a
system shell implicitly. This means that all characters, including shell
metacharacters, can safely be passed to child processes. Obviously, if the
shell is invoked explicitly, then it is the application's responsibility to
ensure that all whitespace and metacharacters are quoted appropriately.
Popen Objects
-------------
Instances of the :class:`Popen` class have the following methods:
.. method:: Popen.poll()
Check if child process has terminated. Set and return
:attr:`~Popen.returncode` attribute.
.. method:: Popen.wait()
Wait for child process to terminate. Set and return
:attr:`~Popen.returncode` attribute.
.. warning::
This will deadlock when using ``stdout=PIPE`` and/or
``stderr=PIPE`` and the child process generates enough output to
a pipe such that it blocks waiting for the OS pipe buffer to
accept more data. Use :meth:`communicate` to avoid that.
.. method:: Popen.communicate(input=None)
Interact with process: Send data to stdin. Read data from stdout and stderr,
until end-of-file is reached. Wait for process to terminate. The optional
*input* argument should be a string to be sent to the child process, or
``None``, if no data should be sent to the child.
:meth:`communicate` returns a tuple ``(stdoutdata, stderrdata)``.
Note that if you want to send data to the process's stdin, you need to create
the Popen object with ``stdin=PIPE``. Similarly, to get anything other than
``None`` in the result tuple, you need to give ``stdout=PIPE`` and/or
``stderr=PIPE`` too.
.. note::
The data read is buffered in memory, so do not use this method if the data
size is large or unlimited.
.. method:: Popen.send_signal(signal)
Sends the signal *signal* to the child.
.. note::
On Windows, SIGTERM is an alias for :meth:`terminate`. CTRL_C_EVENT and
CTRL_BREAK_EVENT can be sent to processes started with a *creationflags*
parameter which includes `CREATE_NEW_PROCESS_GROUP`.
.. versionadded:: 2.6
.. method:: Popen.terminate()
Stop the child. On Posix OSs the method sends SIGTERM to the
child. On Windows the Win32 API function :c:func:`TerminateProcess` is called
to stop the child.
.. versionadded:: 2.6
.. method:: Popen.kill()
Kills the child. On Posix OSs the function sends SIGKILL to the child.
On Windows :meth:`kill` is an alias for :meth:`terminate`.
.. versionadded:: 2.6
The following attributes are also available:
.. warning::
Use :meth:`~Popen.communicate` rather than :attr:`.stdin.write <Popen.stdin>`,
:attr:`.stdout.read <Popen.stdout>` or :attr:`.stderr.read <Popen.stderr>` to avoid
deadlocks due to any of the other OS pipe buffers filling up and blocking the
child process.
.. attribute:: Popen.stdin
If the *stdin* argument was :data:`PIPE`, this attribute is a file object
that provides input to the child process. Otherwise, it is ``None``.
.. attribute:: Popen.stdout
If the *stdout* argument was :data:`PIPE`, this attribute is a file object
that provides output from the child process. Otherwise, it is ``None``.
.. attribute:: Popen.stderr
If the *stderr* argument was :data:`PIPE`, this attribute is a file object
that provides error output from the child process. Otherwise, it is
``None``.
.. attribute:: Popen.pid
The process ID of the child process.
Note that if you set the *shell* argument to ``True``, this is the process ID
of the spawned shell.
.. attribute:: Popen.returncode
The child return code, set by :meth:`poll` and :meth:`wait` (and indirectly
by :meth:`communicate`). A ``None`` value indicates that the process
hasn't terminated yet.
A negative value ``-N`` indicates that the child was terminated by signal
``N`` (Unix only).
Windows Popen Helpers
---------------------
The :class:`STARTUPINFO` class and following constants are only available
on Windows.
.. class:: STARTUPINFO()
Partial support of the Windows
`STARTUPINFO <https://msdn.microsoft.com/en-us/library/ms686331(v=vs.85).aspx>`__
structure is used for :class:`Popen` creation.
.. attribute:: dwFlags
A bit field that determines whether certain :class:`STARTUPINFO`
attributes are used when the process creates a window. ::
si = subprocess.STARTUPINFO()
si.dwFlags = subprocess.STARTF_USESTDHANDLES | subprocess.STARTF_USESHOWWINDOW
.. attribute:: hStdInput
If :attr:`dwFlags` specifies :data:`STARTF_USESTDHANDLES`, this attribute
is the standard input handle for the process. If
:data:`STARTF_USESTDHANDLES` is not specified, the default for standard
input is the keyboard buffer.
.. attribute:: hStdOutput
If :attr:`dwFlags` specifies :data:`STARTF_USESTDHANDLES`, this attribute
is the standard output handle for the process. Otherwise, this attribute
is ignored and the default for standard output is the console window's
buffer.
.. attribute:: hStdError
If :attr:`dwFlags` specifies :data:`STARTF_USESTDHANDLES`, this attribute
is the standard error handle for the process. Otherwise, this attribute is
ignored and the default for standard error is the console window's buffer.
.. attribute:: wShowWindow
If :attr:`dwFlags` specifies :data:`STARTF_USESHOWWINDOW`, this attribute
can be any of the values that can be specified in the ``nCmdShow``
parameter for the
`ShowWindow <https://msdn.microsoft.com/en-us/library/ms633548(v=vs.85).aspx>`__
function, except for ``SW_SHOWDEFAULT``. Otherwise, this attribute is
ignored.
:data:`SW_HIDE` is provided for this attribute. It is used when
:class:`Popen` is called with ``shell=True``.
Constants
^^^^^^^^^
The :mod:`subprocess` module exposes the following constants.
.. data:: STD_INPUT_HANDLE
The standard input device. Initially, this is the console input buffer,
``CONIN$``.
.. data:: STD_OUTPUT_HANDLE
The standard output device. Initially, this is the active console screen
buffer, ``CONOUT$``.
.. data:: STD_ERROR_HANDLE
The standard error device. Initially, this is the active console screen
buffer, ``CONOUT$``.
.. data:: SW_HIDE
Hides the window. Another window will be activated.
.. data:: STARTF_USESTDHANDLES
Specifies that the :attr:`STARTUPINFO.hStdInput`,
:attr:`STARTUPINFO.hStdOutput`, and :attr:`STARTUPINFO.hStdError` attributes
contain additional information.
.. data:: STARTF_USESHOWWINDOW
Specifies that the :attr:`STARTUPINFO.wShowWindow` attribute contains
additional information.
.. data:: CREATE_NEW_CONSOLE
The new process has a new console, instead of inheriting its parent's
console (the default).
This flag is always set when :class:`Popen` is created with ``shell=True``.
.. data:: CREATE_NEW_PROCESS_GROUP
A :class:`Popen` ``creationflags`` parameter to specify that a new process
group will be created. This flag is necessary for using :func:`os.kill`
on the subprocess.
This flag is ignored if :data:`CREATE_NEW_CONSOLE` is specified.
.. _subprocess-replacements:
Replacing Older Functions with the :mod:`subprocess` Module
-----------------------------------------------------------
In this section, "a becomes b" means that b can be used as a replacement for a.
.. note::
All "a" functions in this section fail (more or less) silently if the
executed program cannot be found; the "b" replacements raise :exc:`OSError`
instead.
In addition, the replacements using :func:`check_output` will fail with a
:exc:`CalledProcessError` if the requested operation produces a non-zero
return code. The output is still available as the
:attr:`~CalledProcessError.output` attribute of the raised exception.
In the following examples, we assume that the relevant functions have already
been imported from the :mod:`subprocess` module.
Replacing /bin/sh shell backquote
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: bash
output=`mycmd myarg`
becomes::
output = check_output(["mycmd", "myarg"])
Replacing shell pipeline
^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: bash
output=`dmesg | grep hda`
becomes::
p1 = Popen(["dmesg"], stdout=PIPE)
p2 = Popen(["grep", "hda"], stdin=p1.stdout, stdout=PIPE)
p1.stdout.close() # Allow p1 to receive a SIGPIPE if p2 exits.
output = p2.communicate()[0]
The p1.stdout.close() call after starting the p2 is important in order for p1
to receive a SIGPIPE if p2 exits before p1.
Alternatively, for trusted input, the shell's own pipeline support may still
be used directly:
.. code-block:: bash
output=`dmesg | grep hda`
becomes::
output=check_output("dmesg | grep hda", shell=True)
Replacing :func:`os.system`
^^^^^^^^^^^^^^^^^^^^^^^^^^^
::
status = os.system("mycmd" + " myarg")
# becomes
status = subprocess.call("mycmd" + " myarg", shell=True)
Notes:
* Calling the program through the shell is usually not required.
A more realistic example would look like this::
try:
retcode = call("mycmd" + " myarg", shell=True)
if retcode < 0:
print >>sys.stderr, "Child was terminated by signal", -retcode
else:
print >>sys.stderr, "Child returned", retcode
except OSError as e:
print >>sys.stderr, "Execution failed:", e
Replacing the :func:`os.spawn <os.spawnl>` family
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
P_NOWAIT example::
pid = os.spawnlp(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg")
==>
pid = Popen(["/bin/mycmd", "myarg"]).pid
P_WAIT example::
retcode = os.spawnlp(os.P_WAIT, "/bin/mycmd", "mycmd", "myarg")
==>
retcode = call(["/bin/mycmd", "myarg"])
Vector example::
os.spawnvp(os.P_NOWAIT, path, args)
==>
Popen([path] + args[1:])
Environment example::
os.spawnlpe(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg", env)
==>
Popen(["/bin/mycmd", "myarg"], env={"PATH": "/usr/bin"})
Replacing :func:`os.popen`, :func:`os.popen2`, :func:`os.popen3`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
::
pipe = os.popen("cmd", 'r', bufsize)
==>
pipe = Popen("cmd", shell=True, bufsize=bufsize, stdout=PIPE).stdout
::
pipe = os.popen("cmd", 'w', bufsize)
==>
pipe = Popen("cmd", shell=True, bufsize=bufsize, stdin=PIPE).stdin
::
(child_stdin, child_stdout) = os.popen2("cmd", mode, bufsize)
==>
p = Popen("cmd", shell=True, bufsize=bufsize,
stdin=PIPE, stdout=PIPE, close_fds=True)
(child_stdin, child_stdout) = (p.stdin, p.stdout)
::
(child_stdin,
child_stdout,
child_stderr) = os.popen3("cmd", mode, bufsize)
==>
p = Popen("cmd", shell=True, bufsize=bufsize,
stdin=PIPE, stdout=PIPE, stderr=PIPE, close_fds=True)
(child_stdin,
child_stdout,
child_stderr) = (p.stdin, p.stdout, p.stderr)
::
(child_stdin, child_stdout_and_stderr) = os.popen4("cmd", mode,
bufsize)
==>
p = Popen("cmd", shell=True, bufsize=bufsize,
stdin=PIPE, stdout=PIPE, stderr=STDOUT, close_fds=True)
(child_stdin, child_stdout_and_stderr) = (p.stdin, p.stdout)
On Unix, os.popen2, os.popen3 and os.popen4 also accept a sequence as
the command to execute, in which case arguments will be passed
directly to the program without shell intervention. This usage can be
replaced as follows::
(child_stdin, child_stdout) = os.popen2(["/bin/ls", "-l"], mode,
bufsize)
==>
p = Popen(["/bin/ls", "-l"], bufsize=bufsize, stdin=PIPE, stdout=PIPE)
(child_stdin, child_stdout) = (p.stdin, p.stdout)
Return code handling translates as follows::
pipe = os.popen("cmd", 'w')
...
rc = pipe.close()
if rc is not None and rc >> 8:
print "There were some errors"
==>
process = Popen("cmd", shell=True, stdin=PIPE)
...
process.stdin.close()
if process.wait() != 0:
print "There were some errors"
Replacing functions from the :mod:`popen2` module
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
::
(child_stdout, child_stdin) = popen2.popen2("somestring", bufsize, mode)
==>
p = Popen("somestring", shell=True, bufsize=bufsize,
stdin=PIPE, stdout=PIPE, close_fds=True)
(child_stdout, child_stdin) = (p.stdout, p.stdin)
On Unix, popen2 also accepts a sequence as the command to execute, in
which case arguments will be passed directly to the program without
shell intervention. This usage can be replaced as follows::
(child_stdout, child_stdin) = popen2.popen2(["mycmd", "myarg"], bufsize,
mode)
==>
p = Popen(["mycmd", "myarg"], bufsize=bufsize,
stdin=PIPE, stdout=PIPE, close_fds=True)
(child_stdout, child_stdin) = (p.stdout, p.stdin)
:class:`popen2.Popen3` and :class:`popen2.Popen4` basically work as
:class:`subprocess.Popen`, except that:
* :class:`Popen` raises an exception if the execution fails.
* the *capturestderr* argument is replaced with the *stderr* argument.
* ``stdin=PIPE`` and ``stdout=PIPE`` must be specified.
* popen2 closes all file descriptors by default, but you have to specify
``close_fds=True`` with :class:`Popen`.
Notes
-----
.. _converting-argument-sequence:
Converting an argument sequence to a string on Windows
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
On Windows, an *args* sequence is converted to a string that can be parsed
using the following rules (which correspond to the rules used by the MS C
runtime):
1. Arguments are delimited by white space, which is either a
space or a tab.
2. A string surrounded by double quotation marks is
interpreted as a single argument, regardless of white space
contained within. A quoted string can be embedded in an
argument.
3. A double quotation mark preceded by a backslash is
interpreted as a literal double quotation mark.
4. Backslashes are interpreted literally, unless they
immediately precede a double quotation mark.
5. If backslashes immediately precede a double quotation mark,
every pair of backslashes is interpreted as a literal
backslash. If the number of backslashes is odd, the last
backslash escapes the next double quotation mark as
described in rule 3.
PK
%�\�3��� � ! html/_sources/library/sun.rst.txtnu �[���
.. _sunos:
***********************
SunOS Specific Services
***********************
The modules described in this chapter provide interfaces to features that are
unique to SunOS 5 (also known as Solaris version 2).
.. toctree::
sunaudio.rst
PK
%�\�E!� � # html/_sources/library/sunau.rst.txtnu �[��� :mod:`sunau` --- Read and write Sun AU files
============================================
.. module:: sunau
:synopsis: Provide an interface to the Sun AU sound format.
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
**Source code:** :source:`Lib/sunau.py`
--------------
The :mod:`sunau` module provides a convenient interface to the Sun AU sound
format. Note that this module is interface-compatible with the modules
:mod:`aifc` and :mod:`wave`.
An audio file consists of a header followed by the data. The fields of the
header are:
+---------------+-----------------------------------------------+
| Field | Contents |
+===============+===============================================+
| magic word | The four bytes ``.snd``. |
+---------------+-----------------------------------------------+
| header size | Size of the header, including info, in bytes. |
+---------------+-----------------------------------------------+
| data size | Physical size of the data, in bytes. |
+---------------+-----------------------------------------------+
| encoding | Indicates how the audio samples are encoded. |
+---------------+-----------------------------------------------+
| sample rate | The sampling rate. |
+---------------+-----------------------------------------------+
| # of channels | The number of channels in the samples. |
+---------------+-----------------------------------------------+
| info | ASCII string giving a description of the |
| | audio file (padded with null bytes). |
+---------------+-----------------------------------------------+
Apart from the info field, all header fields are 4 bytes in size. They are all
32-bit unsigned integers encoded in big-endian byte order.
The :mod:`sunau` module defines the following functions:
.. function:: open(file, mode)
If *file* is a string, open the file by that name, otherwise treat it as a
seekable file-like object. *mode* can be any of
``'r'``
Read only mode.
``'w'``
Write only mode.
Note that it does not allow read/write files.
A *mode* of ``'r'`` returns an :class:`AU_read` object, while a *mode* of ``'w'``
or ``'wb'`` returns an :class:`AU_write` object.
.. function:: openfp(file, mode)
A synonym for :func:`.open`, maintained for backwards compatibility.
The :mod:`sunau` module defines the following exception:
.. exception:: Error
An error raised when something is impossible because of Sun AU specs or
implementation deficiency.
The :mod:`sunau` module defines the following data items:
.. data:: AUDIO_FILE_MAGIC
An integer every valid Sun AU file begins with, stored in big-endian form. This
is the string ``.snd`` interpreted as an integer.
.. data:: AUDIO_FILE_ENCODING_MULAW_8
AUDIO_FILE_ENCODING_LINEAR_8
AUDIO_FILE_ENCODING_LINEAR_16
AUDIO_FILE_ENCODING_LINEAR_24
AUDIO_FILE_ENCODING_LINEAR_32
AUDIO_FILE_ENCODING_ALAW_8
Values of the encoding field from the AU header which are supported by this
module.
.. data:: AUDIO_FILE_ENCODING_FLOAT
AUDIO_FILE_ENCODING_DOUBLE
AUDIO_FILE_ENCODING_ADPCM_G721
AUDIO_FILE_ENCODING_ADPCM_G722
AUDIO_FILE_ENCODING_ADPCM_G723_3
AUDIO_FILE_ENCODING_ADPCM_G723_5
Additional known values of the encoding field from the AU header, but which are
not supported by this module.
.. _au-read-objects:
AU_read Objects
---------------
AU_read objects, as returned by :func:`.open` above, have the following methods:
.. method:: AU_read.close()
Close the stream, and make the instance unusable. (This is called automatically
on deletion.)
.. method:: AU_read.getnchannels()
Returns number of audio channels (1 for mono, 2 for stereo).
.. method:: AU_read.getsampwidth()
Returns sample width in bytes.
.. method:: AU_read.getframerate()
Returns sampling frequency.
.. method:: AU_read.getnframes()
Returns number of audio frames.
.. method:: AU_read.getcomptype()
Returns compression type. Supported compression types are ``'ULAW'``, ``'ALAW'``
and ``'NONE'``.
.. method:: AU_read.getcompname()
Human-readable version of :meth:`getcomptype`. The supported types have the
respective names ``'CCITT G.711 u-law'``, ``'CCITT G.711 A-law'`` and ``'not
compressed'``.
.. method:: AU_read.getparams()
Returns a tuple ``(nchannels, sampwidth, framerate, nframes, comptype,
compname)``, equivalent to output of the :meth:`get\*` methods.
.. method:: AU_read.readframes(n)
Reads and returns at most *n* frames of audio, as a string of bytes. The data
will be returned in linear format. If the original data is in u-LAW format, it
will be converted.
.. method:: AU_read.rewind()
Rewind the file pointer to the beginning of the audio stream.
The following two methods define a term "position" which is compatible between
them, and is otherwise implementation dependent.
.. method:: AU_read.setpos(pos)
Set the file pointer to the specified position. Only values returned from
:meth:`tell` should be used for *pos*.
.. method:: AU_read.tell()
Return current file pointer position. Note that the returned value has nothing
to do with the actual position in the file.
The following two functions are defined for compatibility with the :mod:`aifc`,
and don't do anything interesting.
.. method:: AU_read.getmarkers()
Returns ``None``.
.. method:: AU_read.getmark(id)
Raise an error.
.. _au-write-objects:
AU_write Objects
----------------
AU_write objects, as returned by :func:`.open` above, have the following methods:
.. method:: AU_write.setnchannels(n)
Set the number of channels.
.. method:: AU_write.setsampwidth(n)
Set the sample width (in bytes.)
.. method:: AU_write.setframerate(n)
Set the frame rate.
.. method:: AU_write.setnframes(n)
Set the number of frames. This can be later changed, when and if more frames
are written.
.. method:: AU_write.setcomptype(type, name)
Set the compression type and description. Only ``'NONE'`` and ``'ULAW'`` are
supported on output.
.. method:: AU_write.setparams(tuple)
The *tuple* should be ``(nchannels, sampwidth, framerate, nframes, comptype,
compname)``, with values valid for the :meth:`set\*` methods. Set all
parameters.
.. method:: AU_write.tell()
Return current position in the file, with the same disclaimer for the
:meth:`AU_read.tell` and :meth:`AU_read.setpos` methods.
.. method:: AU_write.writeframesraw(data)
Write audio frames, without correcting *nframes*.
.. method:: AU_write.writeframes(data)
Write audio frames and make sure *nframes* is correct.
.. method:: AU_write.close()
Make sure *nframes* is correct, and close the file.
This method is called upon deletion.
Note that it is invalid to set any parameters after calling :meth:`writeframes`
or :meth:`writeframesraw`.
PK
%�\�:� � & html/_sources/library/sunaudio.rst.txtnu �[���
:mod:`sunaudiodev` --- Access to Sun audio hardware
===================================================
.. module:: sunaudiodev
:platform: SunOS
:synopsis: Access to Sun audio hardware.
:deprecated:
.. deprecated:: 2.6
The :mod:`sunaudiodev` module has been removed in Python 3.
.. index:: single: u-LAW
This module allows you to access the Sun audio interface. The Sun audio hardware
is capable of recording and playing back audio data in u-LAW format with a
sample rate of 8K per second. A full description can be found in the
:manpage:`audio(7I)` manual page.
.. index:: module: SUNAUDIODEV
The module :mod:`SUNAUDIODEV` defines constants which may be used with this
module.
This module defines the following variables and functions:
.. exception:: error
This exception is raised on all errors. The argument is a string describing what
went wrong.
.. function:: open(mode)
This function opens the audio device and returns a Sun audio device object. This
object can then be used to do I/O on. The *mode* parameter is one of ``'r'`` for
record-only access, ``'w'`` for play-only access, ``'rw'`` for both and
``'control'`` for access to the control device. Since only one process is
allowed to have the recorder or player open at the same time it is a good idea
to open the device only for the activity needed. See :manpage:`audio(7I)` for
details.
As per the manpage, this module first looks in the environment variable
``AUDIODEV`` for the base audio device filename. If not found, it falls back to
:file:`/dev/audio`. The control device is calculated by appending "ctl" to the
base audio device.
.. _audio-device-objects:
Audio Device Objects
--------------------
The audio device objects are returned by :func:`.open` define the following
methods (except ``control`` objects which only provide :meth:`getinfo`,
:meth:`setinfo`, :meth:`fileno`, and :meth:`drain`):
.. method:: audio device.close()
This method explicitly closes the device. It is useful in situations where
deleting the object does not immediately close it since there are other
references to it. A closed device should not be used again.
.. method:: audio device.fileno()
Returns the file descriptor associated with the device. This can be used to set
up ``SIGPOLL`` notification, as described below.
.. method:: audio device.drain()
This method waits until all pending output is processed and then returns.
Calling this method is often not necessary: destroying the object will
automatically close the audio device and this will do an implicit drain.
.. method:: audio device.flush()
This method discards all pending output. It can be used avoid the slow response
to a user's stop request (due to buffering of up to one second of sound).
.. method:: audio device.getinfo()
This method retrieves status information like input and output volume, etc. and
returns it in the form of an audio status object. This object has no methods but
it contains a number of attributes describing the current device status. The
names and meanings of the attributes are described in ``<sun/audioio.h>`` and in
the :manpage:`audio(7I)` manual page. Member names are slightly different from
their C counterparts: a status object is only a single structure. Members of the
:c:data:`play` substructure have ``o_`` prepended to their name and members of
the :c:data:`record` structure have ``i_``. So, the C member
:c:data:`play.sample_rate` is accessed as :attr:`o_sample_rate`,
:c:data:`record.gain` as :attr:`i_gain` and :c:data:`monitor_gain` plainly as
:attr:`monitor_gain`.
.. method:: audio device.ibufcount()
This method returns the number of samples that are buffered on the recording
side, i.e. the program will not block on a :func:`read` call of so many samples.
.. method:: audio device.obufcount()
This method returns the number of samples buffered on the playback side.
Unfortunately, this number cannot be used to determine a number of samples that
can be written without blocking since the kernel output queue length seems to be
variable.
.. method:: audio device.read(size)
This method reads *size* samples from the audio input and returns them as a
Python string. The function blocks until enough data is available.
.. method:: audio device.setinfo(status)
This method sets the audio device status parameters. The *status* parameter is
a device status object as returned by :func:`getinfo` and possibly modified by
the program.
.. method:: audio device.write(samples)
Write is passed a Python string containing audio samples to be played. If there
is enough buffer space free it will immediately return, otherwise it will block.
The audio device supports asynchronous notification of various events, through
the SIGPOLL signal. Here's an example of how you might enable this in Python::
def handle_sigpoll(signum, frame):
print 'I got a SIGPOLL update'
import fcntl, signal, STROPTS
signal.signal(signal.SIGPOLL, handle_sigpoll)
fcntl.ioctl(audio_obj.fileno(), STROPTS.I_SETSIG, STROPTS.S_MSG)
:mod:`SUNAUDIODEV` --- Constants used with :mod:`sunaudiodev`
=============================================================
.. module:: SUNAUDIODEV
:platform: SunOS
:synopsis: Constants for use with sunaudiodev.
:deprecated:
.. deprecated:: 2.6
The :mod:`SUNAUDIODEV` module has been removed in Python 3.
.. index:: module: sunaudiodev
This is a companion module to :mod:`sunaudiodev` which defines useful symbolic
constants like :const:`MIN_GAIN`, :const:`MAX_GAIN`, :const:`SPEAKER`, etc. The
names of the constants are the same names as used in the C include file
``<sun/audioio.h>``, with the leading string ``AUDIO_`` stripped.
PK
%�\J�$W� � $ html/_sources/library/symbol.rst.txtnu �[��� :mod:`symbol` --- Constants used with Python parse trees
========================================================
.. module:: symbol
:synopsis: Constants representing internal nodes of the parse tree.
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
**Source code:** :source:`Lib/symbol.py`
--------------
This module provides constants which represent the numeric values of internal
nodes of the parse tree. Unlike most Python constants, these use lower-case
names. Refer to the file :file:`Grammar/Grammar` in the Python distribution for
the definitions of the names in the context of the language grammar. The
specific numeric values which the names map to may change between Python
versions.
This module also provides one additional data object:
.. data:: sym_name
Dictionary mapping the numeric values of the constants defined in this module
back to name strings, allowing more human-readable representation of parse trees
to be generated.
PK
%�\�ɘ� � & html/_sources/library/symtable.rst.txtnu �[��� :mod:`symtable` --- Access to the compiler's symbol tables
==========================================================
.. module:: symtable
:synopsis: Interface to the compiler's internal symbol tables.
**Source code:** :source:`Lib/symtable.py`
--------------
.. moduleauthor:: Jeremy Hylton <jeremy@alum.mit.edu>
.. sectionauthor:: Benjamin Peterson <benjamin@python.org>
Symbol tables are generated by the compiler from AST just before bytecode is
generated. The symbol table is responsible for calculating the scope of every
identifier in the code. :mod:`symtable` provides an interface to examine these
tables.
Generating Symbol Tables
------------------------
.. function:: symtable(code, filename, compile_type)
Return the toplevel :class:`SymbolTable` for the Python source *code*.
*filename* is the name of the file containing the code. *compile_type* is
like the *mode* argument to :func:`compile`.
Examining Symbol Tables
-----------------------
.. class:: SymbolTable
A namespace table for a block. The constructor is not public.
.. method:: get_type()
Return the type of the symbol table. Possible values are ``'class'``,
``'module'``, and ``'function'``.
.. method:: get_id()
Return the table's identifier.
.. method:: get_name()
Return the table's name. This is the name of the class if the table is
for a class, the name of the function if the table is for a function, or
``'top'`` if the table is global (:meth:`get_type` returns ``'module'``).
.. method:: get_lineno()
Return the number of the first line in the block this table represents.
.. method:: is_optimized()
Return ``True`` if the locals in this table can be optimized.
.. method:: is_nested()
Return ``True`` if the block is a nested class or function.
.. method:: has_children()
Return ``True`` if the block has nested namespaces within it. These can
be obtained with :meth:`get_children`.
.. method:: has_exec()
Return ``True`` if the block uses ``exec``.
.. method:: has_import_star()
Return ``True`` if the block uses a starred from-import.
.. method:: get_identifiers()
Return a list of names of symbols in this table.
.. method:: lookup(name)
Lookup *name* in the table and return a :class:`Symbol` instance.
.. method:: get_symbols()
Return a list of :class:`Symbol` instances for names in the table.
.. method:: get_children()
Return a list of the nested symbol tables.
.. class:: Function
A namespace for a function or method. This class inherits
:class:`SymbolTable`.
.. method:: get_parameters()
Return a tuple containing names of parameters to this function.
.. method:: get_locals()
Return a tuple containing names of locals in this function.
.. method:: get_globals()
Return a tuple containing names of globals in this function.
.. method:: get_frees()
Return a tuple containing names of free variables in this function.
.. class:: Class
A namespace of a class. This class inherits :class:`SymbolTable`.
.. method:: get_methods()
Return a tuple containing the names of methods declared in the class.
.. class:: Symbol
An entry in a :class:`SymbolTable` corresponding to an identifier in the
source. The constructor is not public.
.. method:: get_name()
Return the symbol's name.
.. method:: is_referenced()
Return ``True`` if the symbol is used in its block.
.. method:: is_imported()
Return ``True`` if the symbol is created from an import statement.
.. method:: is_parameter()
Return ``True`` if the symbol is a parameter.
.. method:: is_global()
Return ``True`` if the symbol is global.
.. method:: is_declared_global()
Return ``True`` if the symbol is declared global with a global statement.
.. method:: is_local()
Return ``True`` if the symbol is local to its block.
.. method:: is_free()
Return ``True`` if the symbol is referenced in its block, but not assigned
to.
.. method:: is_assigned()
Return ``True`` if the symbol is assigned to in its block.
.. method:: is_namespace()
Return ``True`` if name binding introduces new namespace.
If the name is used as the target of a function or class statement, this
will be true.
For example::
>>> table = symtable.symtable("def some_func(): pass", "string", "exec")
>>> table.lookup("some_func").is_namespace()
True
Note that a single name can be bound to multiple objects. If the result
is ``True``, the name may also be bound to other objects, like an int or
list, that does not introduce a new namespace.
.. method:: get_namespaces()
Return a list of namespaces bound to this name.
.. method:: get_namespace()
Return the namespace bound to this name. If more than one namespace is
bound, a :exc:`ValueError` is raised.
PK
%�\{�a � �� ! html/_sources/library/sys.rst.txtnu �[��� :mod:`sys` --- System-specific parameters and functions
=======================================================
.. module:: sys
:synopsis: Access system-specific parameters and functions.
This module provides access to some variables used or maintained by the
interpreter and to functions that interact strongly with the interpreter. It is
always available.
.. data:: argv
The list of command line arguments passed to a Python script. ``argv[0]`` is the
script name (it is operating system dependent whether this is a full pathname or
not). If the command was executed using the :option:`-c` command line option to
the interpreter, ``argv[0]`` is set to the string ``'-c'``. If no script name
was passed to the Python interpreter, ``argv[0]`` is the empty string.
To loop over the standard input, or the list of files given on the
command line, see the :mod:`fileinput` module.
.. data:: byteorder
An indicator of the native byte order. This will have the value ``'big'`` on
big-endian (most-significant byte first) platforms, and ``'little'`` on
little-endian (least-significant byte first) platforms.
.. versionadded:: 2.0
.. data:: builtin_module_names
A tuple of strings giving the names of all modules that are compiled into this
Python interpreter. (This information is not available in any other way ---
``modules.keys()`` only lists the imported modules.)
.. function:: call_tracing(func, args)
Call ``func(*args)``, while tracing is enabled. The tracing state is saved,
and restored afterwards. This is intended to be called from a debugger from
a checkpoint, to recursively debug some other code.
.. data:: copyright
A string containing the copyright pertaining to the Python interpreter.
.. function:: _clear_type_cache()
Clear the internal type cache. The type cache is used to speed up attribute
and method lookups. Use the function *only* to drop unnecessary references
during reference leak debugging.
This function should be used for internal and specialized purposes only.
.. versionadded:: 2.6
.. function:: _current_frames()
Return a dictionary mapping each thread's identifier to the topmost stack frame
currently active in that thread at the time the function is called. Note that
functions in the :mod:`traceback` module can build the call stack given such a
frame.
This is most useful for debugging deadlock: this function does not require the
deadlocked threads' cooperation, and such threads' call stacks are frozen for as
long as they remain deadlocked. The frame returned for a non-deadlocked thread
may bear no relationship to that thread's current activity by the time calling
code examines the frame.
This function should be used for internal and specialized purposes only.
.. versionadded:: 2.5
.. data:: dllhandle
Integer specifying the handle of the Python DLL. Availability: Windows.
.. function:: displayhook(value)
If *value* is not ``None``, this function prints it to ``sys.stdout``, and saves
it in ``__builtin__._``.
``sys.displayhook`` is called on the result of evaluating an :term:`expression`
entered in an interactive Python session. The display of these values can be
customized by assigning another one-argument function to ``sys.displayhook``.
.. data:: dont_write_bytecode
If this is true, Python won't try to write ``.pyc`` or ``.pyo`` files on the
import of source modules. This value is initially set to ``True`` or
``False`` depending on the :option:`-B` command line option and the
:envvar:`PYTHONDONTWRITEBYTECODE` environment variable, but you can set it
yourself to control bytecode file generation.
.. versionadded:: 2.6
.. function:: excepthook(type, value, traceback)
This function prints out a given traceback and exception to ``sys.stderr``.
When an exception is raised and uncaught, the interpreter calls
``sys.excepthook`` with three arguments, the exception class, exception
instance, and a traceback object. In an interactive session this happens just
before control is returned to the prompt; in a Python program this happens just
before the program exits. The handling of such top-level exceptions can be
customized by assigning another three-argument function to ``sys.excepthook``.
.. data:: __displayhook__
__excepthook__
These objects contain the original values of ``displayhook`` and ``excepthook``
at the start of the program. They are saved so that ``displayhook`` and
``excepthook`` can be restored in case they happen to get replaced with broken
objects.
.. function:: exc_info()
This function returns a tuple of three values that give information about the
exception that is currently being handled. The information returned is specific
both to the current thread and to the current stack frame. If the current stack
frame is not handling an exception, the information is taken from the calling
stack frame, or its caller, and so on until a stack frame is found that is
handling an exception. Here, "handling an exception" is defined as "executing
or having executed an except clause." For any stack frame, only information
about the most recently handled exception is accessible.
.. index:: object: traceback
If no exception is being handled anywhere on the stack, a tuple containing three
``None`` values is returned. Otherwise, the values returned are ``(type, value,
traceback)``. Their meaning is: *type* gets the exception type of the exception
being handled (a class object); *value* gets the exception parameter (its
:dfn:`associated value` or the second argument to :keyword:`raise`, which is
always a class instance if the exception type is a class object); *traceback*
gets a traceback object (see the Reference Manual) which encapsulates the call
stack at the point where the exception originally occurred.
If :func:`exc_clear` is called, this function will return three ``None`` values
until either another exception is raised in the current thread or the execution
stack returns to a frame where another exception is being handled.
.. warning::
Assigning the *traceback* return value to a local variable in a function that is
handling an exception will cause a circular reference. This will prevent
anything referenced by a local variable in the same function or by the traceback
from being garbage collected. Since most functions don't need access to the
traceback, the best solution is to use something like ``exctype, value =
sys.exc_info()[:2]`` to extract only the exception type and value. If you do
need the traceback, make sure to delete it after use (best done with a
:keyword:`try` ... :keyword:`finally` statement) or to call :func:`exc_info` in
a function that does not itself handle an exception.
.. note::
Beginning with Python 2.2, such cycles are automatically reclaimed when garbage
collection is enabled and they become unreachable, but it remains more efficient
to avoid creating cycles.
.. function:: exc_clear()
This function clears all information relating to the current or last exception
that occurred in the current thread. After calling this function,
:func:`exc_info` will return three ``None`` values until another exception is
raised in the current thread or the execution stack returns to a frame where
another exception is being handled.
This function is only needed in only a few obscure situations. These include
logging and error handling systems that report information on the last or
current exception. This function can also be used to try to free resources and
trigger object finalization, though no guarantee is made as to what objects will
be freed, if any.
.. versionadded:: 2.3
.. data:: exc_type
exc_value
exc_traceback
.. deprecated:: 1.5
Use :func:`exc_info` instead.
Since they are global variables, they are not specific to the current thread, so
their use is not safe in a multi-threaded program. When no exception is being
handled, ``exc_type`` is set to ``None`` and the other two are undefined.
.. data:: exec_prefix
A string giving the site-specific directory prefix where the platform-dependent
Python files are installed; by default, this is also ``'/usr/local'``. This can
be set at build time with the ``--exec-prefix`` argument to the
:program:`configure` script. Specifically, all configuration files (e.g. the
:file:`pyconfig.h` header file) are installed in the directory
:file:`{exec_prefix}/lib/python{X.Y}/config`, and shared library modules are
installed in :file:`{exec_prefix}/lib/python{X.Y}/lib-dynload`, where *X.Y*
is the version number of Python, for example ``2.7``.
.. data:: executable
A string giving the absolute path of the executable binary for the Python
interpreter, on systems where this makes sense. If Python is unable to retrieve
the real path to its executable, :data:`sys.executable` will be an empty string
or ``None``.
.. function:: exit([arg])
Exit from Python. This is implemented by raising the :exc:`SystemExit`
exception, so cleanup actions specified by finally clauses of :keyword:`try`
statements are honored, and it is possible to intercept the exit attempt at
an outer level.
The optional argument *arg* can be an integer giving the exit status
(defaulting to zero), or another type of object. If it is an integer, zero
is considered "successful termination" and any nonzero value is considered
"abnormal termination" by shells and the like. Most systems require it to be
in the range 0--127, and produce undefined results otherwise. Some systems
have a convention for assigning specific meanings to specific exit codes, but
these are generally underdeveloped; Unix programs generally use 2 for command
line syntax errors and 1 for all other kind of errors. If another type of
object is passed, ``None`` is equivalent to passing zero, and any other
object is printed to :data:`stderr` and results in an exit code of 1. In
particular, ``sys.exit("some error message")`` is a quick way to exit a
program when an error occurs.
Since :func:`exit` ultimately "only" raises an exception, it will only exit
the process when called from the main thread, and the exception is not
intercepted.
.. data:: exitfunc
This value is not actually defined by the module, but can be set by the user (or
by a program) to specify a clean-up action at program exit. When set, it should
be a parameterless function. This function will be called when the interpreter
exits. Only one function may be installed in this way; to allow multiple
functions which will be called at termination, use the :mod:`atexit` module.
.. note::
The exit function is not called when the program is killed by a signal, when a
Python fatal internal error is detected, or when ``os._exit()`` is called.
.. deprecated:: 2.4
Use :mod:`atexit` instead.
.. data:: flags
The struct sequence *flags* exposes the status of command line flags. The
attributes are read only.
============================= ===================================
attribute flag
============================= ===================================
:const:`debug` :option:`-d`
:const:`py3k_warning` :option:`-3`
:const:`division_warning` :option:`-Q`
:const:`division_new` :option:`-Qnew <-Q>`
:const:`inspect` :option:`-i`
:const:`interactive` :option:`-i`
:const:`optimize` :option:`-O` or :option:`-OO`
:const:`dont_write_bytecode` :option:`-B`
:const:`no_user_site` :option:`-s`
:const:`no_site` :option:`-S`
:const:`ignore_environment` :option:`-E`
:const:`tabcheck` :option:`-t` or :option:`-tt <-t>`
:const:`verbose` :option:`-v`
:const:`unicode` :option:`-U`
:const:`bytes_warning` :option:`-b`
:const:`hash_randomization` :option:`-R`
============================= ===================================
.. versionadded:: 2.6
.. versionadded:: 2.7.3
The ``hash_randomization`` attribute.
.. data:: float_info
A structseq holding information about the float type. It contains low level
information about the precision and internal representation. The values
correspond to the various floating-point constants defined in the standard
header file :file:`float.h` for the 'C' programming language; see section
5.2.4.2.2 of the 1999 ISO/IEC C standard [C99]_, 'Characteristics of
floating types', for details.
.. tabularcolumns:: |l|l|L|
+---------------------+----------------+--------------------------------------------------+
| attribute | float.h macro | explanation |
+=====================+================+==================================================+
| :const:`epsilon` | DBL_EPSILON | difference between 1 and the least value greater |
| | | than 1 that is representable as a float |
+---------------------+----------------+--------------------------------------------------+
| :const:`dig` | DBL_DIG | maximum number of decimal digits that can be |
| | | faithfully represented in a float; see below |
+---------------------+----------------+--------------------------------------------------+
| :const:`mant_dig` | DBL_MANT_DIG | float precision: the number of base-``radix`` |
| | | digits in the significand of a float |
+---------------------+----------------+--------------------------------------------------+
| :const:`max` | DBL_MAX | maximum representable finite float |
+---------------------+----------------+--------------------------------------------------+
| :const:`max_exp` | DBL_MAX_EXP | maximum integer e such that ``radix**(e-1)`` is |
| | | a representable finite float |
+---------------------+----------------+--------------------------------------------------+
| :const:`max_10_exp` | DBL_MAX_10_EXP | maximum integer e such that ``10**e`` is in the |
| | | range of representable finite floats |
+---------------------+----------------+--------------------------------------------------+
| :const:`min` | DBL_MIN | minimum positive normalized float |
+---------------------+----------------+--------------------------------------------------+
| :const:`min_exp` | DBL_MIN_EXP | minimum integer e such that ``radix**(e-1)`` is |
| | | a normalized float |
+---------------------+----------------+--------------------------------------------------+
| :const:`min_10_exp` | DBL_MIN_10_EXP | minimum integer e such that ``10**e`` is a |
| | | normalized float |
+---------------------+----------------+--------------------------------------------------+
| :const:`radix` | FLT_RADIX | radix of exponent representation |
+---------------------+----------------+--------------------------------------------------+
| :const:`rounds` | FLT_ROUNDS | integer constant representing the rounding mode |
| | | used for arithmetic operations. This reflects |
| | | the value of the system FLT_ROUNDS macro at |
| | | interpreter startup time. See section 5.2.4.2.2 |
| | | of the C99 standard for an explanation of the |
| | | possible values and their meanings. |
+---------------------+----------------+--------------------------------------------------+
The attribute :attr:`sys.float_info.dig` needs further explanation. If
``s`` is any string representing a decimal number with at most
:attr:`sys.float_info.dig` significant digits, then converting ``s`` to a
float and back again will recover a string representing the same decimal
value::
>>> import sys
>>> sys.float_info.dig
15
>>> s = '3.14159265358979' # decimal string with 15 significant digits
>>> format(float(s), '.15g') # convert to float and back -> same value
'3.14159265358979'
But for strings with more than :attr:`sys.float_info.dig` significant digits,
this isn't always true::
>>> s = '9876543211234567' # 16 significant digits is too many!
>>> format(float(s), '.16g') # conversion changes value
'9876543211234568'
.. versionadded:: 2.6
.. data:: float_repr_style
A string indicating how the :func:`repr` function behaves for
floats. If the string has value ``'short'`` then for a finite
float ``x``, ``repr(x)`` aims to produce a short string with the
property that ``float(repr(x)) == x``. This is the usual behaviour
in Python 2.7 and later. Otherwise, ``float_repr_style`` has value
``'legacy'`` and ``repr(x)`` behaves in the same way as it did in
versions of Python prior to 2.7.
.. versionadded:: 2.7
.. function:: getcheckinterval()
Return the interpreter's "check interval"; see :func:`setcheckinterval`.
.. versionadded:: 2.3
.. function:: getdefaultencoding()
Return the name of the current default string encoding used by the Unicode
implementation.
.. versionadded:: 2.0
.. function:: getdlopenflags()
Return the current value of the flags that are used for :c:func:`dlopen` calls.
The flag constants are defined in the :mod:`dl` and :mod:`DLFCN` modules.
Availability: Unix.
.. versionadded:: 2.2
.. function:: getfilesystemencoding()
Return the name of the encoding used to convert Unicode filenames into system
file names, or ``None`` if the system default encoding is used. The result value
depends on the operating system:
* On Mac OS X, the encoding is ``'utf-8'``.
* On Unix, the encoding is the user's preference according to the result of
nl_langinfo(CODESET), or ``None`` if the ``nl_langinfo(CODESET)``
failed.
* On Windows NT+, file names are Unicode natively, so no conversion is
performed. :func:`getfilesystemencoding` still returns ``'mbcs'``, as
this is the encoding that applications should use when they explicitly
want to convert Unicode strings to byte strings that are equivalent when
used as file names.
* On Windows 9x, the encoding is ``'mbcs'``.
.. versionadded:: 2.3
.. function:: getrefcount(object)
Return the reference count of the *object*. The count returned is generally one
higher than you might expect, because it includes the (temporary) reference as
an argument to :func:`getrefcount`.
.. function:: getrecursionlimit()
Return the current value of the recursion limit, the maximum depth of the Python
interpreter stack. This limit prevents infinite recursion from causing an
overflow of the C stack and crashing Python. It can be set by
:func:`setrecursionlimit`.
.. function:: getsizeof(object[, default])
Return the size of an object in bytes. The object can be any type of
object. All built-in objects will return correct results, but this
does not have to hold true for third-party extensions as it is implementation
specific.
If given, *default* will be returned if the object does not provide means to
retrieve the size. Otherwise a :exc:`TypeError` will be raised.
:func:`getsizeof` calls the object's ``__sizeof__`` method and adds an
additional garbage collector overhead if the object is managed by the garbage
collector.
.. versionadded:: 2.6
.. function:: _getframe([depth])
Return a frame object from the call stack. If optional integer *depth* is
given, return the frame object that many calls below the top of the stack. If
that is deeper than the call stack, :exc:`ValueError` is raised. The default
for *depth* is zero, returning the frame at the top of the call stack.
.. impl-detail::
This function should be used for internal and specialized purposes only.
It is not guaranteed to exist in all implementations of Python.
.. function:: getprofile()
.. index::
single: profile function
single: profiler
Get the profiler function as set by :func:`setprofile`.
.. versionadded:: 2.6
.. function:: gettrace()
.. index::
single: trace function
single: debugger
Get the trace function as set by :func:`settrace`.
.. impl-detail::
The :func:`gettrace` function is intended only for implementing debuggers,
profilers, coverage tools and the like. Its behavior is part of the
implementation platform, rather than part of the language definition, and
thus may not be available in all Python implementations.
.. versionadded:: 2.6
.. function:: getwindowsversion()
Return a named tuple describing the Windows version
currently running. The named elements are *major*, *minor*,
*build*, *platform*, *service_pack*, *service_pack_minor*,
*service_pack_major*, *suite_mask*, and *product_type*.
*service_pack* contains a string while all other values are
integers. The components can also be accessed by name, so
``sys.getwindowsversion()[0]`` is equivalent to
``sys.getwindowsversion().major``. For compatibility with prior
versions, only the first 5 elements are retrievable by indexing.
*platform* may be one of the following values:
+-----------------------------------------+-------------------------+
| Constant | Platform |
+=========================================+=========================+
| :const:`0 (VER_PLATFORM_WIN32s)` | Win32s on Windows 3.1 |
+-----------------------------------------+-------------------------+
| :const:`1 (VER_PLATFORM_WIN32_WINDOWS)` | Windows 95/98/ME |
+-----------------------------------------+-------------------------+
| :const:`2 (VER_PLATFORM_WIN32_NT)` | Windows NT/2000/XP/x64 |
+-----------------------------------------+-------------------------+
| :const:`3 (VER_PLATFORM_WIN32_CE)` | Windows CE |
+-----------------------------------------+-------------------------+
*product_type* may be one of the following values:
+---------------------------------------+---------------------------------+
| Constant | Meaning |
+=======================================+=================================+
| :const:`1 (VER_NT_WORKSTATION)` | The system is a workstation. |
+---------------------------------------+---------------------------------+
| :const:`2 (VER_NT_DOMAIN_CONTROLLER)` | The system is a domain |
| | controller. |
+---------------------------------------+---------------------------------+
| :const:`3 (VER_NT_SERVER)` | The system is a server, but not |
| | a domain controller. |
+---------------------------------------+---------------------------------+
This function wraps the Win32 :c:func:`GetVersionEx` function; see the
Microsoft documentation on :c:func:`OSVERSIONINFOEX` for more information
about these fields.
Availability: Windows.
.. versionadded:: 2.3
.. versionchanged:: 2.7
Changed to a named tuple and added *service_pack_minor*,
*service_pack_major*, *suite_mask*, and *product_type*.
.. data:: hexversion
The version number encoded as a single integer. This is guaranteed to increase
with each version, including proper support for non-production releases. For
example, to test that the Python interpreter is at least version 1.5.2, use::
if sys.hexversion >= 0x010502F0:
# use some advanced feature
...
else:
# use an alternative implementation or warn the user
...
This is called ``hexversion`` since it only really looks meaningful when viewed
as the result of passing it to the built-in :func:`hex` function. The
``version_info`` value may be used for a more human-friendly encoding of the
same information.
The ``hexversion`` is a 32-bit number with the following layout:
+-------------------------+------------------------------------------------+
| Bits (big endian order) | Meaning |
+=========================+================================================+
| :const:`1-8` | ``PY_MAJOR_VERSION`` (the ``2`` in |
| | ``2.1.0a3``) |
+-------------------------+------------------------------------------------+
| :const:`9-16` | ``PY_MINOR_VERSION`` (the ``1`` in |
| | ``2.1.0a3``) |
+-------------------------+------------------------------------------------+
| :const:`17-24` | ``PY_MICRO_VERSION`` (the ``0`` in |
| | ``2.1.0a3``) |
+-------------------------+------------------------------------------------+
| :const:`25-28` | ``PY_RELEASE_LEVEL`` (``0xA`` for alpha, |
| | ``0xB`` for beta, ``0xC`` for release |
| | candidate and ``0xF`` for final) |
+-------------------------+------------------------------------------------+
| :const:`29-32` | ``PY_RELEASE_SERIAL`` (the ``3`` in |
| | ``2.1.0a3``, zero for final releases) |
+-------------------------+------------------------------------------------+
Thus ``2.1.0a3`` is hexversion ``0x020100a3``.
.. versionadded:: 1.5.2
.. data:: long_info
A struct sequence that holds information about Python's
internal representation of integers. The attributes are read only.
.. tabularcolumns:: |l|L|
+-------------------------+----------------------------------------------+
| Attribute | Explanation |
+=========================+==============================================+
| :const:`bits_per_digit` | number of bits held in each digit. Python |
| | integers are stored internally in base |
| | ``2**long_info.bits_per_digit`` |
+-------------------------+----------------------------------------------+
| :const:`sizeof_digit` | size in bytes of the C type used to |
| | represent a digit |
+-------------------------+----------------------------------------------+
.. versionadded:: 2.7
.. data:: last_type
last_value
last_traceback
These three variables are not always defined; they are set when an exception is
not handled and the interpreter prints an error message and a stack traceback.
Their intended use is to allow an interactive user to import a debugger module
and engage in post-mortem debugging without having to re-execute the command
that caused the error. (Typical use is ``import pdb; pdb.pm()`` to enter the
post-mortem debugger; see chapter :ref:`debugger` for
more information.)
The meaning of the variables is the same as that of the return values from
:func:`exc_info` above. (Since there is only one interactive thread,
thread-safety is not a concern for these variables, unlike for ``exc_type``
etc.)
.. data:: maxint
The largest positive integer supported by Python's regular integer type. This
is at least 2\*\*31-1. The largest negative integer is ``-maxint-1`` --- the
asymmetry results from the use of 2's complement binary arithmetic.
.. data:: maxsize
The largest positive integer supported by the platform's Py_ssize_t type,
and thus the maximum size lists, strings, dicts, and many other containers
can have.
.. data:: maxunicode
An integer giving the largest supported code point for a Unicode character. The
value of this depends on the configuration option that specifies whether Unicode
characters are stored as UCS-2 or UCS-4.
.. data:: meta_path
A list of :term:`finder` objects that have their :meth:`find_module`
methods called to see if one of the objects can find the module to be
imported. The :meth:`find_module` method is called at least with the
absolute name of the module being imported. If the module to be imported is
contained in package then the parent package's :attr:`__path__` attribute
is passed in as a second argument. The method returns ``None`` if
the module cannot be found, else returns a :term:`loader`.
:data:`sys.meta_path` is searched before any implicit default finders or
:data:`sys.path`.
See :pep:`302` for the original specification.
.. data:: modules
.. index:: builtin: reload
This is a dictionary that maps module names to modules which have already been
loaded. This can be manipulated to force reloading of modules and other tricks.
Note that removing a module from this dictionary is *not* the same as calling
:func:`reload` on the corresponding module object.
.. data:: path
.. index:: triple: module; search; path
A list of strings that specifies the search path for modules. Initialized from
the environment variable :envvar:`PYTHONPATH`, plus an installation-dependent
default.
As initialized upon program startup, the first item of this list, ``path[0]``,
is the directory containing the script that was used to invoke the Python
interpreter. If the script directory is not available (e.g. if the interpreter
is invoked interactively or if the script is read from standard input),
``path[0]`` is the empty string, which directs Python to search modules in the
current directory first. Notice that the script directory is inserted *before*
the entries inserted as a result of :envvar:`PYTHONPATH`.
A program is free to modify this list for its own purposes.
.. versionchanged:: 2.3
Unicode strings are no longer ignored.
.. seealso::
Module :mod:`site` This describes how to use .pth files to extend
:data:`sys.path`.
.. data:: path_hooks
A list of callables that take a path argument to try to create a
:term:`finder` for the path. If a finder can be created, it is to be
returned by the callable, else raise :exc:`ImportError`.
Originally specified in :pep:`302`.
.. data:: path_importer_cache
A dictionary acting as a cache for :term:`finder` objects. The keys are
paths that have been passed to :data:`sys.path_hooks` and the values are
the finders that are found. If a path is a valid file system path but no
explicit finder is found on :data:`sys.path_hooks` then ``None`` is
stored to represent the implicit default finder should be used. If the path
is not an existing path then :class:`imp.NullImporter` is set.
Originally specified in :pep:`302`.
.. data:: platform
This string contains a platform identifier that can be used to append
platform-specific components to :data:`sys.path`, for instance.
For most Unix systems, this is the lowercased OS name as returned by ``uname
-s`` with the first part of the version as returned by ``uname -r`` appended,
e.g. ``'sunos5'``, *at the time when Python was built*. Unless you want to
test for a specific system version, it is therefore recommended to use the
following idiom::
if sys.platform.startswith('freebsd'):
# FreeBSD-specific code here...
elif sys.platform.startswith('linux'):
# Linux-specific code here...
.. versionchanged:: 2.7.3
Since lots of code check for ``sys.platform == 'linux2'``, and there is
no essential change between Linux 2.x and 3.x, ``sys.platform`` is always
set to ``'linux2'``, even on Linux 3.x. In Python 3.3 and later, the
value will always be set to ``'linux'``, so it is recommended to always
use the ``startswith`` idiom presented above.
For other systems, the values are:
===================== ===========================
System :data:`platform` value
===================== ===========================
Linux (2.x *and* 3.x) ``'linux2'``
Windows ``'win32'``
Windows/Cygwin ``'cygwin'``
Mac OS X ``'darwin'``
OS/2 ``'os2'``
OS/2 EMX ``'os2emx'``
RiscOS ``'riscos'``
AtheOS ``'atheos'``
===================== ===========================
.. seealso::
:attr:`os.name` has a coarser granularity. :func:`os.uname` gives
system-dependent version information.
The :mod:`platform` module provides detailed checks for the
system's identity.
.. data:: prefix
A string giving the site-specific directory prefix where the platform
independent Python files are installed; by default, this is the string
``'/usr/local'``. This can be set at build time with the ``--prefix``
argument to the :program:`configure` script. The main collection of Python
library modules is installed in the directory :file:`{prefix}/lib/python{X.Y}`
while the platform independent header files (all except :file:`pyconfig.h`) are
stored in :file:`{prefix}/include/python{X.Y}`, where *X.Y* is the version
number of Python, for example ``2.7``.
.. data:: ps1
ps2
.. index::
single: interpreter prompts
single: prompts, interpreter
Strings specifying the primary and secondary prompt of the interpreter. These
are only defined if the interpreter is in interactive mode. Their initial
values in this case are ``'>>> '`` and ``'... '``. If a non-string object is
assigned to either variable, its :func:`str` is re-evaluated each time the
interpreter prepares to read a new interactive command; this can be used to
implement a dynamic prompt.
.. data:: py3kwarning
Bool containing the status of the Python 3 warning flag. It's ``True``
when Python is started with the -3 option. (This should be considered
read-only; setting it to a different value doesn't have an effect on
Python 3 warnings.)
.. versionadded:: 2.6
.. function:: setcheckinterval(interval)
Set the interpreter's "check interval". This integer value determines how often
the interpreter checks for periodic things such as thread switches and signal
handlers. The default is ``100``, meaning the check is performed every 100
Python virtual instructions. Setting it to a larger value may increase
performance for programs using threads. Setting it to a value ``<=`` 0 checks
every virtual instruction, maximizing responsiveness as well as overhead.
.. function:: setdefaultencoding(name)
Set the current default string encoding used by the Unicode implementation. If
*name* does not match any available encoding, :exc:`LookupError` is raised.
This function is only intended to be used by the :mod:`site` module
implementation and, where needed, by :mod:`sitecustomize`. Once used by the
:mod:`site` module, it is removed from the :mod:`sys` module's namespace.
.. Note that :mod:`site` is not imported if the :option:`-S` option is passed
to the interpreter, in which case this function will remain available.
.. versionadded:: 2.0
.. function:: setdlopenflags(n)
Set the flags used by the interpreter for :c:func:`dlopen` calls, such as when
the interpreter loads extension modules. Among other things, this will enable a
lazy resolving of symbols when importing a module, if called as
``sys.setdlopenflags(0)``. To share symbols across extension modules, call as
``sys.setdlopenflags(dl.RTLD_NOW | dl.RTLD_GLOBAL)``. Symbolic names for the
flag modules can be either found in the :mod:`dl` module, or in the :mod:`DLFCN`
module. If :mod:`DLFCN` is not available, it can be generated from
:file:`/usr/include/dlfcn.h` using the :program:`h2py` script. Availability:
Unix.
.. versionadded:: 2.2
.. function:: setprofile(profilefunc)
.. index::
single: profile function
single: profiler
Set the system's profile function, which allows you to implement a Python source
code profiler in Python. See chapter :ref:`profile` for more information on the
Python profiler. The system's profile function is called similarly to the
system's trace function (see :func:`settrace`), but it is called with different events,
for example it isn't called for each executed line of code (only on call and return,
but the return event is reported even when an exception has been set). The function is
thread-specific, but there is no way for the profiler to know about context switches between
threads, so it does not make sense to use this in the presence of multiple threads. Also,
its return value is not used, so it can simply return ``None``.
Profile functions should have three arguments: *frame*, *event*, and
*arg*. *frame* is the current stack frame. *event* is a string: ``'call'``,
``'return'``, ``'c_call'``, ``'c_return'``, or ``'c_exception'``. *arg* depends
on the event type.
The events have the following meaning:
``'call'``
A function is called (or some other code block entered). The
profile function is called; *arg* is ``None``.
``'return'``
A function (or other code block) is about to return. The profile
function is called; *arg* is the value that will be returned, or ``None``
if the event is caused by an exception being raised.
``'c_call'``
A C function is about to be called. This may be an extension function or
a built-in. *arg* is the C function object.
``'c_return'``
A C function has returned. *arg* is the C function object.
``'c_exception'``
A C function has raised an exception. *arg* is the C function object.
.. function:: setrecursionlimit(limit)
Set the maximum depth of the Python interpreter stack to *limit*. This limit
prevents infinite recursion from causing an overflow of the C stack and crashing
Python.
The highest possible limit is platform-dependent. A user may need to set the
limit higher when she has a program that requires deep recursion and a platform
that supports a higher limit. This should be done with care, because a too-high
limit can lead to a crash.
.. function:: settrace(tracefunc)
.. index::
single: trace function
single: debugger
Set the system's trace function, which allows you to implement a Python
source code debugger in Python. The function is thread-specific; for a
debugger to support multiple threads, it must be registered using
:func:`settrace` for each thread being debugged.
Trace functions should have three arguments: *frame*, *event*, and
*arg*. *frame* is the current stack frame. *event* is a string: ``'call'``,
``'line'``, ``'return'`` or ``'exception'``. *arg* depends on
the event type.
The trace function is invoked (with *event* set to ``'call'``) whenever a new
local scope is entered; it should return a reference to a local trace
function to be used that scope, or ``None`` if the scope shouldn't be traced.
The local trace function should return a reference to itself (or to another
function for further tracing in that scope), or ``None`` to turn off tracing
in that scope.
The events have the following meaning:
``'call'``
A function is called (or some other code block entered). The
global trace function is called; *arg* is ``None``; the return value
specifies the local trace function.
``'line'``
The interpreter is about to execute a new line of code or re-execute the
condition of a loop. The local trace function is called; *arg* is
``None``; the return value specifies the new local trace function. See
:file:`Objects/lnotab_notes.txt` for a detailed explanation of how this
works.
``'return'``
A function (or other code block) is about to return. The local trace
function is called; *arg* is the value that will be returned, or ``None``
if the event is caused by an exception being raised. The trace function's
return value is ignored.
``'exception'``
An exception has occurred. The local trace function is called; *arg* is a
tuple ``(exception, value, traceback)``; the return value specifies the
new local trace function.
Note that as an exception is propagated down the chain of callers, an
``'exception'`` event is generated at each level.
For more information on code and frame objects, refer to :ref:`types`.
.. impl-detail::
The :func:`settrace` function is intended only for implementing debuggers,
profilers, coverage tools and the like. Its behavior is part of the
implementation platform, rather than part of the language definition, and
thus may not be available in all Python implementations.
.. function:: settscdump(on_flag)
Activate dumping of VM measurements using the Pentium timestamp counter, if
*on_flag* is true. Deactivate these dumps if *on_flag* is off. The function is
available only if Python was compiled with ``--with-tsc``. To understand
the output of this dump, read :file:`Python/ceval.c` in the Python sources.
.. versionadded:: 2.4
.. impl-detail::
This function is intimately bound to CPython implementation details and
thus not likely to be implemented elsewhere.
.. data:: stdin
stdout
stderr
.. index::
builtin: input
builtin: raw_input
File objects corresponding to the interpreter's standard input, output and error
streams. ``stdin`` is used for all interpreter input except for scripts but
including calls to :func:`input` and :func:`raw_input`. ``stdout`` is used for
the output of :keyword:`print` and :term:`expression` statements and for the
prompts of :func:`input` and :func:`raw_input`. The interpreter's own prompts
and (almost all of) its error messages go to ``stderr``. ``stdout`` and
``stderr`` needn't be built-in file objects: any object is acceptable as long
as it has a :meth:`write` method that takes a string argument. (Changing these
objects doesn't affect the standard I/O streams of processes executed by
:func:`os.popen`, :func:`os.system` or the :func:`exec\*` family of functions in
the :mod:`os` module.)
.. data:: __stdin__
__stdout__
__stderr__
These objects contain the original values of ``stdin``, ``stderr`` and
``stdout`` at the start of the program. They are used during finalization,
and could be useful to print to the actual standard stream no matter if the
``sys.std*`` object has been redirected.
It can also be used to restore the actual files to known working file objects
in case they have been overwritten with a broken object. However, the
preferred way to do this is to explicitly save the previous stream before
replacing it, and restore the saved object.
.. data:: subversion
A triple (repo, branch, version) representing the Subversion information of the
Python interpreter. *repo* is the name of the repository, ``'CPython'``.
*branch* is a string of one of the forms ``'trunk'``, ``'branches/name'`` or
``'tags/name'``. *version* is the output of ``svnversion``, if the interpreter
was built from a Subversion checkout; it contains the revision number (range)
and possibly a trailing 'M' if there were local modifications. If the tree was
exported (or svnversion was not available), it is the revision of
``Include/patchlevel.h`` if the branch is a tag. Otherwise, it is ``None``.
.. versionadded:: 2.5
.. note::
Python is now `developed <https://docs.python.org/devguide/>`_ using
Mercurial. In recent Python 2.7 bugfix releases, :data:`subversion`
therefore contains placeholder information. It is removed in Python
3.3.
.. data:: tracebacklimit
When this variable is set to an integer value, it determines the maximum number
of levels of traceback information printed when an unhandled exception occurs.
The default is ``1000``. When set to ``0`` or less, all traceback information
is suppressed and only the exception type and value are printed.
.. data:: version
A string containing the version number of the Python interpreter plus additional
information on the build number and compiler used. This string is displayed
when the interactive interpreter is started. Do not extract version information
out of it, rather, use :data:`version_info` and the functions provided by the
:mod:`platform` module.
.. data:: api_version
The C API version for this interpreter. Programmers may find this useful when
debugging version conflicts between Python and extension modules.
.. versionadded:: 2.3
.. data:: version_info
A tuple containing the five components of the version number: *major*, *minor*,
*micro*, *releaselevel*, and *serial*. All values except *releaselevel* are
integers; the release level is ``'alpha'``, ``'beta'``, ``'candidate'``, or
``'final'``. The ``version_info`` value corresponding to the Python version 2.0
is ``(2, 0, 0, 'final', 0)``. The components can also be accessed by name,
so ``sys.version_info[0]`` is equivalent to ``sys.version_info.major``
and so on.
.. versionadded:: 2.0
.. versionchanged:: 2.7
Added named component attributes
.. data:: warnoptions
This is an implementation detail of the warnings framework; do not modify this
value. Refer to the :mod:`warnings` module for more information on the warnings
framework.
.. data:: winver
The version number used to form registry keys on Windows platforms. This is
stored as string resource 1000 in the Python DLL. The value is normally the
first three characters of :const:`version`. It is provided in the :mod:`sys`
module for informational purposes; modifying this value has no effect on the
registry keys used by Python. Availability: Windows.
.. rubric:: Citations
.. [C99] ISO/IEC 9899:1999. "Programming languages -- C." A public draft of this standard is available at http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1256.pdf\ .
PK
%�\|���� � ' html/_sources/library/sysconfig.rst.txtnu �[��� :mod:`sysconfig` --- Provide access to Python's configuration information
=========================================================================
.. module:: sysconfig
:synopsis: Python's configuration information
.. moduleauthor:: Tarek Ziade <tarek@ziade.org>
.. sectionauthor:: Tarek Ziade <tarek@ziade.org>
.. index::
single: configuration information
.. versionadded:: 2.7
**Source code:** :source:`Lib/sysconfig.py`
--------------
The :mod:`sysconfig` module provides access to Python's configuration
information like the list of installation paths and the configuration variables
relevant for the current platform.
Configuration variables
-----------------------
A Python distribution contains a :file:`Makefile` and a :file:`pyconfig.h`
header file that are necessary to build both the Python binary itself and
third-party C extensions compiled using :mod:`distutils`.
:mod:`sysconfig` puts all variables found in these files in a dictionary that
can be accessed using :func:`get_config_vars` or :func:`get_config_var`.
Notice that on Windows, it's a much smaller set.
.. function:: get_config_vars(\*args)
With no arguments, return a dictionary of all configuration variables
relevant for the current platform.
With arguments, return a list of values that result from looking up each
argument in the configuration variable dictionary.
For each argument, if the value is not found, return ``None``.
.. function:: get_config_var(name)
Return the value of a single variable *name*. Equivalent to
``get_config_vars().get(name)``.
If *name* is not found, return ``None``.
Example of usage::
>>> import sysconfig
>>> sysconfig.get_config_var('Py_ENABLE_SHARED')
0
>>> sysconfig.get_config_var('LIBDIR')
'/usr/local/lib'
>>> sysconfig.get_config_vars('AR', 'CXX')
['ar', 'g++']
Installation paths
------------------
Python uses an installation scheme that differs depending on the platform and on
the installation options. These schemes are stored in :mod:`sysconfig` under
unique identifiers based on the value returned by :const:`os.name`.
Every new component that is installed using :mod:`distutils` or a
Distutils-based system will follow the same scheme to copy its file in the right
places.
Python currently supports seven schemes:
- *posix_prefix*: scheme for Posix platforms like Linux or Mac OS X. This is
the default scheme used when Python or a component is installed.
- *posix_home*: scheme for Posix platforms used when a *home* option is used
upon installation. This scheme is used when a component is installed through
Distutils with a specific home prefix.
- *posix_user*: scheme for Posix platforms used when a component is installed
through Distutils and the *user* option is used. This scheme defines paths
located under the user home directory.
- *nt*: scheme for NT platforms like Windows.
- *nt_user*: scheme for NT platforms, when the *user* option is used.
- *os2*: scheme for OS/2 platforms.
- *os2_home*: scheme for OS/2 platforms, when the *user* option is used.
Each scheme is itself composed of a series of paths and each path has a unique
identifier. Python currently uses eight paths:
- *stdlib*: directory containing the standard Python library files that are not
platform-specific.
- *platstdlib*: directory containing the standard Python library files that are
platform-specific.
- *platlib*: directory for site-specific, platform-specific files.
- *purelib*: directory for site-specific, non-platform-specific files.
- *include*: directory for non-platform-specific header files.
- *platinclude*: directory for platform-specific header files.
- *scripts*: directory for script files.
- *data*: directory for data files.
:mod:`sysconfig` provides some functions to determine these paths.
.. function:: get_scheme_names()
Return a tuple containing all schemes currently supported in
:mod:`sysconfig`.
.. function:: get_path_names()
Return a tuple containing all path names currently supported in
:mod:`sysconfig`.
.. function:: get_path(name, [scheme, [vars, [expand]]])
Return an installation path corresponding to the path *name*, from the
install scheme named *scheme*.
*name* has to be a value from the list returned by :func:`get_path_names`.
:mod:`sysconfig` stores installation paths corresponding to each path name,
for each platform, with variables to be expanded. For instance the *stdlib*
path for the *nt* scheme is: ``{base}/Lib``.
:func:`get_path` will use the variables returned by :func:`get_config_vars`
to expand the path. All variables have default values for each platform so
one may call this function and get the default value.
If *scheme* is provided, it must be a value from the list returned by
:func:`get_scheme_names`. Otherwise, the default scheme for the current
platform is used.
If *vars* is provided, it must be a dictionary of variables that will update
the dictionary return by :func:`get_config_vars`.
If *expand* is set to ``False``, the path will not be expanded using the
variables.
If *name* is not found, return ``None``.
.. function:: get_paths([scheme, [vars, [expand]]])
Return a dictionary containing all installation paths corresponding to an
installation scheme. See :func:`get_path` for more information.
If *scheme* is not provided, will use the default scheme for the current
platform.
If *vars* is provided, it must be a dictionary of variables that will
update the dictionary used to expand the paths.
If *expand* is set to false, the paths will not be expanded.
If *scheme* is not an existing scheme, :func:`get_paths` will raise a
:exc:`KeyError`.
Other functions
---------------
.. function:: get_python_version()
Return the ``MAJOR.MINOR`` Python version number as a string. Similar to
``sys.version[:3]``.
.. function:: get_platform()
Return a string that identifies the current platform.
This is used mainly to distinguish platform-specific build directories and
platform-specific built distributions. Typically includes the OS name and
version and the architecture (as supplied by :func:`os.uname`), although the
exact information included depends on the OS; e.g. for IRIX the architecture
isn't particularly important (IRIX only runs on SGI hardware), but for Linux
the kernel version isn't particularly important.
Examples of returned values:
- linux-i586
- linux-alpha (?)
- solaris-2.6-sun4u
- irix-5.3
- irix64-6.2
Windows will return one of:
- win-amd64 (64bit Windows on AMD64, aka x86_64, Intel64, and EM64T)
- win-ia64 (64bit Windows on Itanium)
- win32 (all others - specifically, sys.platform is returned)
Mac OS X can return:
- macosx-10.6-ppc
- macosx-10.4-ppc64
- macosx-10.3-i386
- macosx-10.4-fat
For other non-POSIX platforms, currently just returns :data:`sys.platform`.
.. function:: is_python_build()
Return ``True`` if the current Python installation was built from source.
.. function:: parse_config_h(fp[, vars])
Parse a :file:`config.h`\-style file.
*fp* is a file-like object pointing to the :file:`config.h`\-like file.
A dictionary containing name/value pairs is returned. If an optional
dictionary is passed in as the second argument, it is used instead of a new
dictionary, and updated with the values read in the file.
.. function:: get_config_h_filename()
Return the path of :file:`pyconfig.h`.
.. function:: get_makefile_filename()
Return the path of :file:`Makefile`.
PK
%�\$���[ [ $ html/_sources/library/syslog.rst.txtnu �[��� :mod:`syslog` --- Unix syslog library routines
==============================================
.. module:: syslog
:platform: Unix
:synopsis: An interface to the Unix syslog library routines.
This module provides an interface to the Unix ``syslog`` library routines.
Refer to the Unix manual pages for a detailed description of the ``syslog``
facility.
This module wraps the system ``syslog`` family of routines. A pure Python
library that can speak to a syslog server is available in the
:mod:`logging.handlers` module as :class:`SysLogHandler`.
The module defines the following functions:
.. function:: syslog(message)
syslog(priority, message)
Send the string *message* to the system logger. A trailing newline is added
if necessary. Each message is tagged with a priority composed of a
*facility* and a *level*. The optional *priority* argument, which defaults
to :const:`LOG_INFO`, determines the message priority. If the facility is
not encoded in *priority* using logical-or (``LOG_INFO | LOG_USER``), the
value given in the :func:`openlog` call is used.
If :func:`openlog` has not been called prior to the call to :func:`syslog`,
``openlog()`` will be called with no arguments.
.. function:: openlog([ident[, logoption[, facility]]])
Logging options of subsequent :func:`syslog` calls can be set by calling
:func:`openlog`. :func:`syslog` will call :func:`openlog` with no arguments
if the log is not currently open.
The optional *ident* keyword argument is a string which is prepended to every
message, and defaults to ``sys.argv[0]`` with leading path components
stripped. The optional *logoption* keyword argument (default is 0) is a bit
field -- see below for possible values to combine. The optional *facility*
keyword argument (default is :const:`LOG_USER`) sets the default facility for
messages which do not have a facility explicitly encoded.
.. function:: closelog()
Reset the syslog module values and call the system library ``closelog()``.
This causes the module to behave as it does when initially imported. For
example, :func:`openlog` will be called on the first :func:`syslog` call (if
:func:`openlog` hasn't already been called), and *ident* and other
:func:`openlog` parameters are reset to defaults.
.. function:: setlogmask(maskpri)
Set the priority mask to *maskpri* and return the previous mask value. Calls
to :func:`syslog` with a priority level not set in *maskpri* are ignored.
The default is to log all priorities. The function ``LOG_MASK(pri)``
calculates the mask for the individual priority *pri*. The function
``LOG_UPTO(pri)`` calculates the mask for all priorities up to and including
*pri*.
The module defines the following constants:
Priority levels (high to low):
:const:`LOG_EMERG`, :const:`LOG_ALERT`, :const:`LOG_CRIT`, :const:`LOG_ERR`,
:const:`LOG_WARNING`, :const:`LOG_NOTICE`, :const:`LOG_INFO`,
:const:`LOG_DEBUG`.
Facilities:
:const:`LOG_KERN`, :const:`LOG_USER`, :const:`LOG_MAIL`, :const:`LOG_DAEMON`,
:const:`LOG_AUTH`, :const:`LOG_LPR`, :const:`LOG_NEWS`, :const:`LOG_UUCP`,
:const:`LOG_CRON`, :const:`LOG_SYSLOG` and :const:`LOG_LOCAL0` to
:const:`LOG_LOCAL7`.
Log options:
:const:`LOG_PID`, :const:`LOG_CONS`, :const:`LOG_NDELAY`, :const:`LOG_NOWAIT`
and :const:`LOG_PERROR` if defined in ``<syslog.h>``.
Examples
--------
Simple example
~~~~~~~~~~~~~~
A simple set of examples::
import syslog
syslog.syslog('Processing started')
if error:
syslog.syslog(syslog.LOG_ERR, 'Processing started')
An example of setting some log options, these would include the process ID in
logged messages, and write the messages to the destination facility used for
mail logging::
syslog.openlog(logoption=syslog.LOG_PID, facility=syslog.LOG_MAIL)
syslog.syslog('E-mail processing initiated...')
PK
%�\tB��� � & html/_sources/library/tabnanny.rst.txtnu �[��� :mod:`tabnanny` --- Detection of ambiguous indentation
======================================================
.. module:: tabnanny
:synopsis: Tool for detecting white space related problems in Python source files in a
directory tree.
.. moduleauthor:: Tim Peters <tim_one@users.sourceforge.net>
.. sectionauthor:: Peter Funk <pf@artcom-gmbh.de>
.. rudimentary documentation based on module comments
**Source code:** :source:`Lib/tabnanny.py`
--------------
For the time being this module is intended to be called as a script. However it
is possible to import it into an IDE and use the function :func:`check`
described below.
.. note::
The API provided by this module is likely to change in future releases; such
changes may not be backward compatible.
.. function:: check(file_or_dir)
If *file_or_dir* is a directory and not a symbolic link, then recursively
descend the directory tree named by *file_or_dir*, checking all :file:`.py`
files along the way. If *file_or_dir* is an ordinary Python source file, it is
checked for whitespace related problems. The diagnostic messages are written to
standard output using the print statement.
.. data:: verbose
Flag indicating whether to print verbose messages. This is incremented by the
``-v`` option if called as a script.
.. data:: filename_only
Flag indicating whether to print only the filenames of files containing
whitespace related problems. This is set to true by the ``-q`` option if called
as a script.
.. exception:: NannyNag
Raised by :func:`process_tokens` if detecting an ambiguous indent. Captured and
handled in :func:`check`.
.. function:: process_tokens(tokens)
This function is used by :func:`check` to process tokens generated by the
:mod:`tokenize` module.
.. XXX document errprint, format_witnesses, Whitespace, check_equal, indents,
reset_globals
.. seealso::
Module :mod:`tokenize`
Lexical scanner for Python source code.
PK
%�\sS�/6n 6n % html/_sources/library/tarfile.rst.txtnu �[��� :mod:`tarfile` --- Read and write tar archive files
===================================================
.. module:: tarfile
:synopsis: Read and write tar-format archive files.
.. versionadded:: 2.3
.. moduleauthor:: Lars Gustäbel <lars@gustaebel.de>
.. sectionauthor:: Lars Gustäbel <lars@gustaebel.de>
**Source code:** :source:`Lib/tarfile.py`
--------------
The :mod:`tarfile` module makes it possible to read and write tar
archives, including those using gzip or bz2 compression.
Use the :mod:`zipfile` module to read or write :file:`.zip` files, or the
higher-level functions in :ref:`shutil <archiving-operations>`.
Some facts and figures:
* reads and writes :mod:`gzip` and :mod:`bz2` compressed archives
if the respective modules are available.
* read/write support for the POSIX.1-1988 (ustar) format.
* read/write support for the GNU tar format including *longname* and *longlink*
extensions, read-only support for the *sparse* extension.
* read/write support for the POSIX.1-2001 (pax) format.
.. versionadded:: 2.6
* handles directories, regular files, hardlinks, symbolic links, fifos,
character devices and block devices and is able to acquire and restore file
information like timestamp, access permissions and owner.
.. note::
Handling of multi-stream bzip2 files is not supported. Modules such as
`bz2file <https://github.com/nvawda/bz2file>`_ let you overcome this.
.. function:: open(name=None, mode='r', fileobj=None, bufsize=10240, \*\*kwargs)
Return a :class:`TarFile` object for the pathname *name*. For detailed
information on :class:`TarFile` objects and the keyword arguments that are
allowed, see :ref:`tarfile-objects`.
*mode* has to be a string of the form ``'filemode[:compression]'``, it defaults
to ``'r'``. Here is a full list of mode combinations:
+------------------+---------------------------------------------+
| mode | action |
+==================+=============================================+
| ``'r' or 'r:*'`` | Open for reading with transparent |
| | compression (recommended). |
+------------------+---------------------------------------------+
| ``'r:'`` | Open for reading exclusively without |
| | compression. |
+------------------+---------------------------------------------+
| ``'r:gz'`` | Open for reading with gzip compression. |
+------------------+---------------------------------------------+
| ``'r:bz2'`` | Open for reading with bzip2 compression. |
+------------------+---------------------------------------------+
| ``'a' or 'a:'`` | Open for appending with no compression. The |
| | file is created if it does not exist. |
+------------------+---------------------------------------------+
| ``'w' or 'w:'`` | Open for uncompressed writing. |
+------------------+---------------------------------------------+
| ``'w:gz'`` | Open for gzip compressed writing. |
+------------------+---------------------------------------------+
| ``'w:bz2'`` | Open for bzip2 compressed writing. |
+------------------+---------------------------------------------+
Note that ``'a:gz'`` or ``'a:bz2'`` is not possible. If *mode* is not suitable
to open a certain (compressed) file for reading, :exc:`ReadError` is raised. Use
*mode* ``'r'`` to avoid this. If a compression method is not supported,
:exc:`CompressionError` is raised.
If *fileobj* is specified, it is used as an alternative to a file object opened
for *name*. It is supposed to be at position 0.
For modes ``'w:gz'``, ``'r:gz'``, ``'w:bz2'``, ``'r:bz2'``, :func:`tarfile.open`
accepts the keyword argument *compresslevel* (default ``9``) to
specify the compression level of the file.
For special purposes, there is a second format for *mode*:
``'filemode|[compression]'``. :func:`tarfile.open` will return a :class:`TarFile`
object that processes its data as a stream of blocks. No random seeking will
be done on the file. If given, *fileobj* may be any object that has a
:meth:`read` or :meth:`write` method (depending on the *mode*). *bufsize*
specifies the blocksize and defaults to ``20 * 512`` bytes. Use this variant
in combination with e.g. ``sys.stdin``, a socket file object or a tape
device. However, such a :class:`TarFile` object is limited in that it does
not allow random access, see :ref:`tar-examples`. The currently
possible modes:
+-------------+--------------------------------------------+
| Mode | Action |
+=============+============================================+
| ``'r|*'`` | Open a *stream* of tar blocks for reading |
| | with transparent compression. |
+-------------+--------------------------------------------+
| ``'r|'`` | Open a *stream* of uncompressed tar blocks |
| | for reading. |
+-------------+--------------------------------------------+
| ``'r|gz'`` | Open a gzip compressed *stream* for |
| | reading. |
+-------------+--------------------------------------------+
| ``'r|bz2'`` | Open a bzip2 compressed *stream* for |
| | reading. |
+-------------+--------------------------------------------+
| ``'w|'`` | Open an uncompressed *stream* for writing. |
+-------------+--------------------------------------------+
| ``'w|gz'`` | Open a gzip compressed *stream* for |
| | writing. |
+-------------+--------------------------------------------+
| ``'w|bz2'`` | Open a bzip2 compressed *stream* for |
| | writing. |
+-------------+--------------------------------------------+
.. class:: TarFile
Class for reading and writing tar archives. Do not use this class directly,
better use :func:`tarfile.open` instead. See :ref:`tarfile-objects`.
.. function:: is_tarfile(name)
Return :const:`True` if *name* is a tar archive file, that the :mod:`tarfile`
module can read.
.. class:: TarFileCompat(filename, mode='r', compression=TAR_PLAIN)
Class for limited access to tar archives with a :mod:`zipfile`\ -like interface.
Please consult the documentation of the :mod:`zipfile` module for more details.
*compression* must be one of the following constants:
.. data:: TAR_PLAIN
Constant for an uncompressed tar archive.
.. data:: TAR_GZIPPED
Constant for a :mod:`gzip` compressed tar archive.
.. deprecated:: 2.6
The :class:`TarFileCompat` class has been removed in Python 3.
.. exception:: TarError
Base class for all :mod:`tarfile` exceptions.
.. exception:: ReadError
Is raised when a tar archive is opened, that either cannot be handled by the
:mod:`tarfile` module or is somehow invalid.
.. exception:: CompressionError
Is raised when a compression method is not supported or when the data cannot be
decoded properly.
.. exception:: StreamError
Is raised for the limitations that are typical for stream-like :class:`TarFile`
objects.
.. exception:: ExtractError
Is raised for *non-fatal* errors when using :meth:`TarFile.extract`, but only if
:attr:`TarFile.errorlevel`\ ``== 2``.
The following constants are available at the module level:
.. data:: ENCODING
The default character encoding: ``'utf-8'`` on Windows, the value returned by
:func:`sys.getfilesystemencoding` otherwise.
.. exception:: HeaderError
Is raised by :meth:`TarInfo.frombuf` if the buffer it gets is invalid.
.. versionadded:: 2.6
Each of the following constants defines a tar archive format that the
:mod:`tarfile` module is able to create. See section :ref:`tar-formats` for
details.
.. data:: USTAR_FORMAT
POSIX.1-1988 (ustar) format.
.. data:: GNU_FORMAT
GNU tar format.
.. data:: PAX_FORMAT
POSIX.1-2001 (pax) format.
.. data:: DEFAULT_FORMAT
The default format for creating archives. This is currently :const:`GNU_FORMAT`.
.. seealso::
Module :mod:`zipfile`
Documentation of the :mod:`zipfile` standard module.
:ref:`archiving-operations`
Documentation of the higher-level archiving facilities provided by the
standard :mod:`shutil` module.
`GNU tar manual, Basic Tar Format <https://www.gnu.org/software/tar/manual/html_node/Standard.html>`_
Documentation for tar archive files, including GNU tar extensions.
.. _tarfile-objects:
TarFile Objects
---------------
The :class:`TarFile` object provides an interface to a tar archive. A tar
archive is a sequence of blocks. An archive member (a stored file) is made up of
a header block followed by data blocks. It is possible to store a file in a tar
archive several times. Each archive member is represented by a :class:`TarInfo`
object, see :ref:`tarinfo-objects` for details.
A :class:`TarFile` object can be used as a context manager in a :keyword:`with`
statement. It will automatically be closed when the block is completed. Please
note that in the event of an exception an archive opened for writing will not
be finalized; only the internally used file object will be closed. See the
:ref:`tar-examples` section for a use case.
.. versionadded:: 2.7
Added support for the context management protocol.
.. class:: TarFile(name=None, mode='r', fileobj=None, format=DEFAULT_FORMAT, tarinfo=TarInfo, dereference=False, ignore_zeros=False, encoding=ENCODING, errors=None, pax_headers=None, debug=0, errorlevel=0)
All following arguments are optional and can be accessed as instance attributes
as well.
*name* is the pathname of the archive. It can be omitted if *fileobj* is given.
In this case, the file object's :attr:`name` attribute is used if it exists.
*mode* is either ``'r'`` to read from an existing archive, ``'a'`` to append
data to an existing file or ``'w'`` to create a new file overwriting an existing
one.
If *fileobj* is given, it is used for reading or writing data. If it can be
determined, *mode* is overridden by *fileobj*'s mode. *fileobj* will be used
from position 0.
.. note::
*fileobj* is not closed, when :class:`TarFile` is closed.
*format* controls the archive format. It must be one of the constants
:const:`USTAR_FORMAT`, :const:`GNU_FORMAT` or :const:`PAX_FORMAT` that are
defined at module level.
.. versionadded:: 2.6
The *tarinfo* argument can be used to replace the default :class:`TarInfo` class
with a different one.
.. versionadded:: 2.6
If *dereference* is :const:`False`, add symbolic and hard links to the archive. If it
is :const:`True`, add the content of the target files to the archive. This has no
effect on systems that do not support symbolic links.
If *ignore_zeros* is :const:`False`, treat an empty block as the end of the archive.
If it is :const:`True`, skip empty (and invalid) blocks and try to get as many members
as possible. This is only useful for reading concatenated or damaged archives.
*debug* can be set from ``0`` (no debug messages) up to ``3`` (all debug
messages). The messages are written to ``sys.stderr``.
If *errorlevel* is ``0``, all errors are ignored when using :meth:`TarFile.extract`.
Nevertheless, they appear as error messages in the debug output, when debugging
is enabled. If ``1``, all *fatal* errors are raised as :exc:`OSError` or
:exc:`IOError` exceptions. If ``2``, all *non-fatal* errors are raised as
:exc:`TarError` exceptions as well.
The *encoding* and *errors* arguments control the way strings are converted to
unicode objects and vice versa. The default settings will work for most users.
See section :ref:`tar-unicode` for in-depth information.
.. versionadded:: 2.6
The *pax_headers* argument is an optional dictionary of unicode strings which
will be added as a pax global header if *format* is :const:`PAX_FORMAT`.
.. versionadded:: 2.6
.. classmethod:: TarFile.open(...)
Alternative constructor. The :func:`tarfile.open` function is actually a
shortcut to this classmethod.
.. method:: TarFile.getmember(name)
Return a :class:`TarInfo` object for member *name*. If *name* can not be found
in the archive, :exc:`KeyError` is raised.
.. note::
If a member occurs more than once in the archive, its last occurrence is assumed
to be the most up-to-date version.
.. method:: TarFile.getmembers()
Return the members of the archive as a list of :class:`TarInfo` objects. The
list has the same order as the members in the archive.
.. method:: TarFile.getnames()
Return the members as a list of their names. It has the same order as the list
returned by :meth:`getmembers`.
.. method:: TarFile.list(verbose=True)
Print a table of contents to ``sys.stdout``. If *verbose* is :const:`False`,
only the names of the members are printed. If it is :const:`True`, output
similar to that of :program:`ls -l` is produced.
.. method:: TarFile.next()
Return the next member of the archive as a :class:`TarInfo` object, when
:class:`TarFile` is opened for reading. Return :const:`None` if there is no more
available.
.. method:: TarFile.extractall(path=".", members=None)
Extract all members from the archive to the current working directory or
directory *path*. If optional *members* is given, it must be a subset of the
list returned by :meth:`getmembers`. Directory information like owner,
modification time and permissions are set after all members have been extracted.
This is done to work around two problems: A directory's modification time is
reset each time a file is created in it. And, if a directory's permissions do
not allow writing, extracting files to it will fail.
.. warning::
Never extract archives from untrusted sources without prior inspection.
It is possible that files are created outside of *path*, e.g. members
that have absolute filenames starting with ``"/"`` or filenames with two
dots ``".."``.
.. versionadded:: 2.5
.. method:: TarFile.extract(member, path="")
Extract a member from the archive to the current working directory, using its
full name. Its file information is extracted as accurately as possible. *member*
may be a filename or a :class:`TarInfo` object. You can specify a different
directory using *path*.
.. note::
The :meth:`extract` method does not take care of several extraction issues.
In most cases you should consider using the :meth:`extractall` method.
.. warning::
See the warning for :meth:`extractall`.
.. method:: TarFile.extractfile(member)
Extract a member from the archive as a file object. *member* may be a filename
or a :class:`TarInfo` object. If *member* is a regular file, a file-like object
is returned. If *member* is a link, a file-like object is constructed from the
link's target. If *member* is none of the above, :const:`None` is returned.
.. note::
The file-like object is read-only. It provides the methods
:meth:`read`, :meth:`readline`, :meth:`readlines`, :meth:`seek`, :meth:`tell`,
and :meth:`close`, and also supports iteration over its lines.
.. method:: TarFile.add(name, arcname=None, recursive=True, exclude=None, filter=None)
Add the file *name* to the archive. *name* may be any type of file (directory,
fifo, symbolic link, etc.). If given, *arcname* specifies an alternative name
for the file in the archive. Directories are added recursively by default. This
can be avoided by setting *recursive* to :const:`False`. If *exclude* is given
it must be a function that takes one filename argument and returns a boolean
value. Depending on this value the respective file is either excluded
(:const:`True`) or added (:const:`False`). If *filter* is specified it must
be a function that takes a :class:`TarInfo` object argument and returns the
changed :class:`TarInfo` object. If it instead returns :const:`None` the :class:`TarInfo`
object will be excluded from the archive. See :ref:`tar-examples` for an
example.
.. versionchanged:: 2.6
Added the *exclude* parameter.
.. versionchanged:: 2.7
Added the *filter* parameter.
.. deprecated:: 2.7
The *exclude* parameter is deprecated, please use the *filter* parameter
instead. For maximum portability, *filter* should be used as a keyword
argument rather than as a positional argument so that code won't be
affected when *exclude* is ultimately removed.
.. method:: TarFile.addfile(tarinfo, fileobj=None)
Add the :class:`TarInfo` object *tarinfo* to the archive. If *fileobj* is given,
``tarinfo.size`` bytes are read from it and added to the archive. You can
create :class:`TarInfo` objects directly, or by using :meth:`gettarinfo`.
.. note::
On Windows platforms, *fileobj* should always be opened with mode ``'rb'`` to
avoid irritation about the file size.
.. method:: TarFile.gettarinfo(name=None, arcname=None, fileobj=None)
Create a :class:`TarInfo` object from the result of :func:`os.stat` or
equivalent on an existing file. The file is either named by *name*, or
specified as a file object *fileobj* with a file descriptor. If
given, *arcname* specifies an alternative name for the file in the
archive, otherwise, the name is taken from *fileobj*’s
:attr:`~file.name` attribute, or the *name* argument.
You can modify some
of the :class:`TarInfo`’s attributes before you add it using :meth:`addfile`.
If the file object is not an ordinary file object positioned at the
beginning of the file, attributes such as :attr:`~TarInfo.size` may need
modifying. This is the case for objects such as :class:`~gzip.GzipFile`.
The :attr:`~TarInfo.name` may also be modified, in which case *arcname*
could be a dummy string.
.. method:: TarFile.close()
Close the :class:`TarFile`. In write mode, two finishing zero blocks are
appended to the archive.
.. attribute:: TarFile.posix
Setting this to :const:`True` is equivalent to setting the :attr:`format`
attribute to :const:`USTAR_FORMAT`, :const:`False` is equivalent to
:const:`GNU_FORMAT`.
.. versionchanged:: 2.4
*posix* defaults to :const:`False`.
.. deprecated:: 2.6
Use the :attr:`format` attribute instead.
.. attribute:: TarFile.pax_headers
A dictionary containing key-value pairs of pax global headers.
.. versionadded:: 2.6
.. _tarinfo-objects:
TarInfo Objects
---------------
A :class:`TarInfo` object represents one member in a :class:`TarFile`. Aside
from storing all required attributes of a file (like file type, size, time,
permissions, owner etc.), it provides some useful methods to determine its type.
It does *not* contain the file's data itself.
:class:`TarInfo` objects are returned by :class:`TarFile`'s methods
:meth:`getmember`, :meth:`getmembers` and :meth:`gettarinfo`.
.. class:: TarInfo(name="")
Create a :class:`TarInfo` object.
.. method:: TarInfo.frombuf(buf)
Create and return a :class:`TarInfo` object from string buffer *buf*.
.. versionadded:: 2.6
Raises :exc:`HeaderError` if the buffer is invalid..
.. method:: TarInfo.fromtarfile(tarfile)
Read the next member from the :class:`TarFile` object *tarfile* and return it as
a :class:`TarInfo` object.
.. versionadded:: 2.6
.. method:: TarInfo.tobuf(format=DEFAULT_FORMAT, encoding=ENCODING, errors='strict')
Create a string buffer from a :class:`TarInfo` object. For information on the
arguments see the constructor of the :class:`TarFile` class.
.. versionchanged:: 2.6
The arguments were added.
A ``TarInfo`` object has the following public data attributes:
.. attribute:: TarInfo.name
Name of the archive member.
.. attribute:: TarInfo.size
Size in bytes.
.. attribute:: TarInfo.mtime
Time of last modification.
.. attribute:: TarInfo.mode
Permission bits.
.. attribute:: TarInfo.type
File type. *type* is usually one of these constants: :const:`REGTYPE`,
:const:`AREGTYPE`, :const:`LNKTYPE`, :const:`SYMTYPE`, :const:`DIRTYPE`,
:const:`FIFOTYPE`, :const:`CONTTYPE`, :const:`CHRTYPE`, :const:`BLKTYPE`,
:const:`GNUTYPE_SPARSE`. To determine the type of a :class:`TarInfo` object
more conveniently, use the ``is*()`` methods below.
.. attribute:: TarInfo.linkname
Name of the target file name, which is only present in :class:`TarInfo` objects
of type :const:`LNKTYPE` and :const:`SYMTYPE`.
.. attribute:: TarInfo.uid
User ID of the user who originally stored this member.
.. attribute:: TarInfo.gid
Group ID of the user who originally stored this member.
.. attribute:: TarInfo.uname
User name.
.. attribute:: TarInfo.gname
Group name.
.. attribute:: TarInfo.pax_headers
A dictionary containing key-value pairs of an associated pax extended header.
.. versionadded:: 2.6
A :class:`TarInfo` object also provides some convenient query methods:
.. method:: TarInfo.isfile()
Return :const:`True` if the :class:`Tarinfo` object is a regular file.
.. method:: TarInfo.isreg()
Same as :meth:`isfile`.
.. method:: TarInfo.isdir()
Return :const:`True` if it is a directory.
.. method:: TarInfo.issym()
Return :const:`True` if it is a symbolic link.
.. method:: TarInfo.islnk()
Return :const:`True` if it is a hard link.
.. method:: TarInfo.ischr()
Return :const:`True` if it is a character device.
.. method:: TarInfo.isblk()
Return :const:`True` if it is a block device.
.. method:: TarInfo.isfifo()
Return :const:`True` if it is a FIFO.
.. method:: TarInfo.isdev()
Return :const:`True` if it is one of character device, block device or FIFO.
.. _tar-examples:
Examples
--------
How to extract an entire tar archive to the current working directory::
import tarfile
tar = tarfile.open("sample.tar.gz")
tar.extractall()
tar.close()
How to extract a subset of a tar archive with :meth:`TarFile.extractall` using
a generator function instead of a list::
import os
import tarfile
def py_files(members):
for tarinfo in members:
if os.path.splitext(tarinfo.name)[1] == ".py":
yield tarinfo
tar = tarfile.open("sample.tar.gz")
tar.extractall(members=py_files(tar))
tar.close()
How to create an uncompressed tar archive from a list of filenames::
import tarfile
tar = tarfile.open("sample.tar", "w")
for name in ["foo", "bar", "quux"]:
tar.add(name)
tar.close()
The same example using the :keyword:`with` statement::
import tarfile
with tarfile.open("sample.tar", "w") as tar:
for name in ["foo", "bar", "quux"]:
tar.add(name)
How to read a gzip compressed tar archive and display some member information::
import tarfile
tar = tarfile.open("sample.tar.gz", "r:gz")
for tarinfo in tar:
print tarinfo.name, "is", tarinfo.size, "bytes in size and is",
if tarinfo.isreg():
print "a regular file."
elif tarinfo.isdir():
print "a directory."
else:
print "something else."
tar.close()
How to create an archive and reset the user information using the *filter*
parameter in :meth:`TarFile.add`::
import tarfile
def reset(tarinfo):
tarinfo.uid = tarinfo.gid = 0
tarinfo.uname = tarinfo.gname = "root"
return tarinfo
tar = tarfile.open("sample.tar.gz", "w:gz")
tar.add("foo", filter=reset)
tar.close()
.. _tar-formats:
Supported tar formats
---------------------
There are three tar formats that can be created with the :mod:`tarfile` module:
* The POSIX.1-1988 ustar format (:const:`USTAR_FORMAT`). It supports filenames
up to a length of at best 256 characters and linknames up to 100 characters. The
maximum file size is 8 gigabytes. This is an old and limited but widely
supported format.
* The GNU tar format (:const:`GNU_FORMAT`). It supports long filenames and
linknames, files bigger than 8 gigabytes and sparse files. It is the de facto
standard on GNU/Linux systems. :mod:`tarfile` fully supports the GNU tar
extensions for long names, sparse file support is read-only.
* The POSIX.1-2001 pax format (:const:`PAX_FORMAT`). It is the most flexible
format with virtually no limits. It supports long filenames and linknames, large
files and stores pathnames in a portable way. However, not all tar
implementations today are able to handle pax archives properly.
The *pax* format is an extension to the existing *ustar* format. It uses extra
headers for information that cannot be stored otherwise. There are two flavours
of pax headers: Extended headers only affect the subsequent file header, global
headers are valid for the complete archive and affect all following files. All
the data in a pax header is encoded in *UTF-8* for portability reasons.
There are some more variants of the tar format which can be read, but not
created:
* The ancient V7 format. This is the first tar format from Unix Seventh Edition,
storing only regular files and directories. Names must not be longer than 100
characters, there is no user/group name information. Some archives have
miscalculated header checksums in case of fields with non-ASCII characters.
* The SunOS tar extended format. This format is a variant of the POSIX.1-2001
pax format, but is not compatible.
.. _tar-unicode:
Unicode issues
--------------
The tar format was originally conceived to make backups on tape drives with the
main focus on preserving file system information. Nowadays tar archives are
commonly used for file distribution and exchanging archives over networks. One
problem of the original format (that all other formats are merely variants of)
is that there is no concept of supporting different character encodings. For
example, an ordinary tar archive created on a *UTF-8* system cannot be read
correctly on a *Latin-1* system if it contains non-ASCII characters. Names (i.e.
filenames, linknames, user/group names) containing these characters will appear
damaged. Unfortunately, there is no way to autodetect the encoding of an
archive.
The pax format was designed to solve this problem. It stores non-ASCII names
using the universal character encoding *UTF-8*. When a pax archive is read,
these *UTF-8* names are converted to the encoding of the local file system.
The details of unicode conversion are controlled by the *encoding* and *errors*
keyword arguments of the :class:`TarFile` class.
The default value for *encoding* is the local character encoding. It is deduced
from :func:`sys.getfilesystemencoding` and :func:`sys.getdefaultencoding`. In
read mode, *encoding* is used exclusively to convert unicode names from a pax
archive to strings in the local character encoding. In write mode, the use of
*encoding* depends on the chosen archive format. In case of :const:`PAX_FORMAT`,
input names that contain non-ASCII characters need to be decoded before being
stored as *UTF-8* strings. The other formats do not make use of *encoding*
unless unicode objects are used as input names. These are converted to 8-bit
character strings before they are added to the archive.
The *errors* argument defines how characters are treated that cannot be
converted to or from *encoding*. Possible values are listed in section
:ref:`codec-base-classes`. In read mode, there is an additional scheme
``'utf-8'`` which means that bad characters are replaced by their *UTF-8*
representation. This is the default scheme. In write mode the default value for
*errors* is ``'strict'`` to ensure that name information is not altered
unnoticed.
PK
%�\S�S�: : ' html/_sources/library/telnetlib.rst.txtnu �[��� :mod:`telnetlib` --- Telnet client
==================================
.. module:: telnetlib
:synopsis: Telnet client class.
.. sectionauthor:: Skip Montanaro <skip@pobox.com>
.. index:: single: protocol; Telnet
**Source code:** :source:`Lib/telnetlib.py`
--------------
The :mod:`telnetlib` module provides a :class:`Telnet` class that implements the
Telnet protocol. See :rfc:`854` for details about the protocol. In addition, it
provides symbolic constants for the protocol characters (see below), and for the
telnet options. The symbolic names of the telnet options follow the definitions
in ``arpa/telnet.h``, with the leading ``TELOPT_`` removed. For symbolic names
of options which are traditionally not included in ``arpa/telnet.h``, see the
module source itself.
The symbolic constants for the telnet commands are: IAC, DONT, DO, WONT, WILL,
SE (Subnegotiation End), NOP (No Operation), DM (Data Mark), BRK (Break), IP
(Interrupt process), AO (Abort output), AYT (Are You There), EC (Erase
Character), EL (Erase Line), GA (Go Ahead), SB (Subnegotiation Begin).
.. class:: Telnet([host[, port[, timeout]]])
:class:`Telnet` represents a connection to a Telnet server. The instance is
initially not connected by default; the :meth:`open` method must be used to
establish a connection. Alternatively, the host name and optional port
number can be passed to the constructor, to, in which case the connection to
the server will be established before the constructor returns. The optional
*timeout* parameter specifies a timeout in seconds for blocking operations
like the connection attempt (if not specified, the global default timeout
setting will be used).
Do not reopen an already connected instance.
This class has many :meth:`read_\*` methods. Note that some of them raise
:exc:`EOFError` when the end of the connection is read, because they can return
an empty string for other reasons. See the individual descriptions below.
.. versionchanged:: 2.6
*timeout* was added.
.. seealso::
:rfc:`854` - Telnet Protocol Specification
Definition of the Telnet protocol.
.. _telnet-objects:
Telnet Objects
--------------
:class:`Telnet` instances have the following methods:
.. method:: Telnet.read_until(expected[, timeout])
Read until a given string, *expected*, is encountered or until *timeout* seconds
have passed.
When no match is found, return whatever is available instead, possibly the empty
string. Raise :exc:`EOFError` if the connection is closed and no cooked data is
available.
.. method:: Telnet.read_all()
Read all data until EOF; block until connection closed.
.. method:: Telnet.read_some()
Read at least one byte of cooked data unless EOF is hit. Return ``''`` if EOF is
hit. Block if no data is immediately available.
.. method:: Telnet.read_very_eager()
Read everything that can be without blocking in I/O (eager).
Raise :exc:`EOFError` if connection closed and no cooked data available. Return
``''`` if no cooked data available otherwise. Do not block unless in the midst
of an IAC sequence.
.. method:: Telnet.read_eager()
Read readily available data.
Raise :exc:`EOFError` if connection closed and no cooked data available. Return
``''`` if no cooked data available otherwise. Do not block unless in the midst
of an IAC sequence.
.. method:: Telnet.read_lazy()
Process and return data already in the queues (lazy).
Raise :exc:`EOFError` if connection closed and no data available. Return ``''``
if no cooked data available otherwise. Do not block unless in the midst of an
IAC sequence.
.. method:: Telnet.read_very_lazy()
Return any data available in the cooked queue (very lazy).
Raise :exc:`EOFError` if connection closed and no data available. Return ``''``
if no cooked data available otherwise. This method never blocks.
.. method:: Telnet.read_sb_data()
Return the data collected between a SB/SE pair (suboption begin/end). The
callback should access these data when it was invoked with a ``SE`` command.
This method never blocks.
.. versionadded:: 2.3
.. method:: Telnet.open(host[, port[, timeout]])
Connect to a host. The optional second argument is the port number, which
defaults to the standard Telnet port (23). The optional *timeout* parameter
specifies a timeout in seconds for blocking operations like the connection
attempt (if not specified, the global default timeout setting will be used).
Do not try to reopen an already connected instance.
.. versionchanged:: 2.6
*timeout* was added.
.. method:: Telnet.msg(msg[, *args])
Print a debug message when the debug level is ``>`` 0. If extra arguments are
present, they are substituted in the message using the standard string
formatting operator.
.. method:: Telnet.set_debuglevel(debuglevel)
Set the debug level. The higher the value of *debuglevel*, the more debug
output you get (on ``sys.stdout``).
.. method:: Telnet.close()
Close the connection.
.. method:: Telnet.get_socket()
Return the socket object used internally.
.. method:: Telnet.fileno()
Return the file descriptor of the socket object used internally.
.. method:: Telnet.write(buffer)
Write a string to the socket, doubling any IAC characters. This can block if the
connection is blocked. May raise :exc:`socket.error` if the connection is
closed.
.. method:: Telnet.interact()
Interaction function, emulates a very dumb Telnet client.
.. method:: Telnet.mt_interact()
Multithreaded version of :meth:`interact`.
.. method:: Telnet.expect(list[, timeout])
Read until one from a list of a regular expressions matches.
The first argument is a list of regular expressions, either compiled
(:class:`regex objects <re-objects>`) or uncompiled (strings). The optional second
argument is a timeout, in seconds; the default is to block indefinitely.
Return a tuple of three items: the index in the list of the first regular
expression that matches; the match object returned; and the text read up till
and including the match.
If end of file is found and no text was read, raise :exc:`EOFError`. Otherwise,
when nothing matches, return ``(-1, None, text)`` where *text* is the text
received so far (may be the empty string if a timeout happened).
If a regular expression ends with a greedy match (such as ``.*``) or if more
than one expression can match the same input, the results are
non-deterministic, and may depend on the I/O timing.
.. method:: Telnet.set_option_negotiation_callback(callback)
Each time a telnet option is read on the input flow, this *callback* (if set) is
called with the following parameters: callback(telnet socket, command
(DO/DONT/WILL/WONT), option). No other action is done afterwards by telnetlib.
.. _telnet-example:
Telnet Example
--------------
.. sectionauthor:: Peter Funk <pf@artcom-gmbh.de>
A simple example illustrating typical use::
import getpass
import sys
import telnetlib
HOST = "localhost"
user = raw_input("Enter your remote account: ")
password = getpass.getpass()
tn = telnetlib.Telnet(HOST)
tn.read_until("login: ")
tn.write(user + "\n")
if password:
tn.read_until("Password: ")
tn.write(password + "\n")
tn.write("ls\n")
tn.write("exit\n")
print tn.read_all()
PK
%�\-� ) ) & html/_sources/library/tempfile.rst.txtnu �[��� :mod:`tempfile` --- Generate temporary files and directories
============================================================
.. sectionauthor:: Zack Weinberg <zack@codesourcery.com>
.. module:: tempfile
:synopsis: Generate temporary files and directories.
.. index::
pair: temporary; file name
pair: temporary; file
**Source code:** :source:`Lib/tempfile.py`
--------------
This module generates temporary files and directories. It works on all
supported platforms.
In version 2.3 of Python, this module was overhauled for enhanced security. It
now provides three new functions, :func:`NamedTemporaryFile`, :func:`mkstemp`,
and :func:`mkdtemp`, which should eliminate all remaining need to use the
insecure :func:`mktemp` function. Temporary file names created by this module
no longer contain the process ID; instead a string of six random characters is
used.
Also, all the user-callable functions now take additional arguments which
allow direct control over the location and name of temporary files. It is
no longer necessary to use the global *tempdir* and *template* variables.
To maintain backward compatibility, the argument order is somewhat odd; it
is recommended to use keyword arguments for clarity.
The module defines the following user-callable functions:
.. function:: TemporaryFile([mode='w+b'[, bufsize=-1[, suffix=''[, prefix='tmp'[, dir=None]]]]])
Return a file-like object that can be used as a temporary storage area.
The file is created using :func:`mkstemp`. It will be destroyed as soon
as it is closed (including an implicit close when the object is garbage
collected). Under Unix, the directory entry for the file is removed
immediately after the file is created. Other platforms do not support
this; your code should not rely on a temporary file created using this
function having or not having a visible name in the file system.
The *mode* parameter defaults to ``'w+b'`` so that the file created can
be read and written without being closed. Binary mode is used so that it
behaves consistently on all platforms without regard for the data that is
stored. *bufsize* defaults to ``-1``, meaning that the operating system
default is used.
The *dir*, *prefix* and *suffix* parameters are passed to :func:`mkstemp`.
The returned object is a true file object on POSIX platforms. On other
platforms, it is a file-like object whose :attr:`!file` attribute is the
underlying true file object. This file-like object can be used in a
:keyword:`with` statement, just like a normal file.
.. function:: NamedTemporaryFile([mode='w+b'[, bufsize=-1[, suffix=''[, prefix='tmp'[, dir=None[, delete=True]]]]]])
This function operates exactly as :func:`TemporaryFile` does, except that
the file is guaranteed to have a visible name in the file system (on
Unix, the directory entry is not unlinked). That name can be retrieved
from the :attr:`name` attribute of the returned
file-like object. Whether the name can be
used to open the file a second time, while the named temporary file is
still open, varies across platforms (it can be so used on Unix; it cannot
on Windows NT or later). If *delete* is true (the default), the file is
deleted as soon as it is closed.
The returned object is always a file-like object whose :attr:`!file`
attribute is the underlying true file object. This file-like object can
be used in a :keyword:`with` statement, just like a normal file.
.. versionadded:: 2.3
.. versionadded:: 2.6
The *delete* parameter.
.. function:: SpooledTemporaryFile([max_size=0, [mode='w+b'[, bufsize=-1[, suffix=''[, prefix='tmp'[, dir=None]]]]]])
This function operates exactly as :func:`TemporaryFile` does, except that
data is spooled in memory until the file size exceeds *max_size*, or
until the file's :func:`fileno` method is called, at which point the
contents are written to disk and operation proceeds as with
:func:`TemporaryFile`. Also, it's ``truncate`` method does not
accept a ``size`` argument.
The resulting file has one additional method, :func:`rollover`, which
causes the file to roll over to an on-disk file regardless of its size.
The returned object is a file-like object whose :attr:`_file` attribute
is either a :class:`~StringIO.StringIO` object or a true file object, depending on
whether :func:`rollover` has been called. This file-like object can be
used in a :keyword:`with` statement, just like a normal file.
.. versionadded:: 2.6
.. function:: mkstemp([suffix=''[, prefix='tmp'[, dir=None[, text=False]]]])
Creates a temporary file in the most secure manner possible. There are
no race conditions in the file's creation, assuming that the platform
properly implements the :const:`os.O_EXCL` flag for :func:`os.open`. The
file is readable and writable only by the creating user ID. If the
platform uses permission bits to indicate whether a file is executable,
the file is executable by no one. The file descriptor is not inherited
by child processes.
Unlike :func:`TemporaryFile`, the user of :func:`mkstemp` is responsible
for deleting the temporary file when done with it.
If *suffix* is specified, the file name will end with that suffix,
otherwise there will be no suffix. :func:`mkstemp` does not put a dot
between the file name and the suffix; if you need one, put it at the
beginning of *suffix*.
If *prefix* is specified, the file name will begin with that prefix;
otherwise, a default prefix is used.
If *dir* is specified, the file will be created in that directory;
otherwise, a default directory is used. The default directory is chosen
from a platform-dependent list, but the user of the application can
control the directory location by setting the *TMPDIR*, *TEMP* or *TMP*
environment variables. There is thus no guarantee that the generated
filename will have any nice properties, such as not requiring quoting
when passed to external commands via ``os.popen()``.
If *text* is specified, it indicates whether to open the file in binary
mode (the default) or text mode. On some platforms, this makes no
difference.
:func:`mkstemp` returns a tuple containing an OS-level handle to an open
file (as would be returned by :func:`os.open`) and the absolute pathname
of that file, in that order.
.. versionadded:: 2.3
.. function:: mkdtemp([suffix=''[, prefix='tmp'[, dir=None]]])
Creates a temporary directory in the most secure manner possible. There
are no race conditions in the directory's creation. The directory is
readable, writable, and searchable only by the creating user ID.
The user of :func:`mkdtemp` is responsible for deleting the temporary
directory and its contents when done with it.
The *prefix*, *suffix*, and *dir* arguments are the same as for
:func:`mkstemp`.
:func:`mkdtemp` returns the absolute pathname of the new directory.
.. versionadded:: 2.3
.. function:: mktemp([suffix=''[, prefix='tmp'[, dir=None]]])
.. deprecated:: 2.3
Use :func:`mkstemp` instead.
Return an absolute pathname of a file that did not exist at the time the
call is made. The *prefix*, *suffix*, and *dir* arguments are the same
as for :func:`mkstemp`.
.. warning::
Use of this function may introduce a security hole in your program. By
the time you get around to doing anything with the file name it returns,
someone else may have beaten you to the punch. :func:`mktemp` usage can
be replaced easily with :func:`NamedTemporaryFile`, passing it the
``delete=False`` parameter::
>>> f = NamedTemporaryFile(delete=False)
>>> f
<open file '<fdopen>', mode 'w+b' at 0x384698>
>>> f.name
'/var/folders/5q/5qTPn6xq2RaWqk+1Ytw3-U+++TI/-Tmp-/tmpG7V1Y0'
>>> f.write("Hello World!\n")
>>> f.close()
>>> os.unlink(f.name)
>>> os.path.exists(f.name)
False
The module uses a global variable that tell it how to construct a
temporary name. They are initialized at the first call to any of the
functions above. The caller may change them, but this is discouraged; use
the appropriate function arguments, instead.
.. data:: tempdir
When set to a value other than ``None``, this variable defines the
default value for the *dir* argument to all the functions defined in this
module.
If ``tempdir`` is unset or ``None`` at any call to any of the above
functions, Python searches a standard list of directories and sets
*tempdir* to the first one which the calling user can create files in.
The list is:
#. The directory named by the :envvar:`TMPDIR` environment variable.
#. The directory named by the :envvar:`TEMP` environment variable.
#. The directory named by the :envvar:`TMP` environment variable.
#. A platform-specific location:
* On RiscOS, the directory named by the :envvar:`Wimp$ScrapDir` environment
variable.
* On Windows, the directories :file:`C:\\TEMP`, :file:`C:\\TMP`,
:file:`\\TEMP`, and :file:`\\TMP`, in that order.
* On all other platforms, the directories :file:`/tmp`, :file:`/var/tmp`, and
:file:`/usr/tmp`, in that order.
#. As a last resort, the current working directory.
.. function:: gettempdir()
Return the directory currently selected to create temporary files in. If
:data:`tempdir` is not ``None``, this simply returns its contents; otherwise,
the search described above is performed, and the result returned.
.. versionadded:: 2.3
.. data:: template
.. deprecated:: 2.0
Use :func:`gettempprefix` instead.
When set to a value other than ``None``, this variable defines the prefix of the
final component of the filenames returned by :func:`mktemp`. A string of six
random letters and digits is appended to the prefix to make the filename unique.
The default prefix is :file:`tmp`.
Older versions of this module used to require that ``template`` be set to
``None`` after a call to :func:`os.fork`; this has not been necessary since
version 1.5.2.
.. function:: gettempprefix()
Return the filename prefix used to create temporary files. This does not
contain the directory component. Using this function is preferred over reading
the *template* variable directly.
.. versionadded:: 1.5.2
PK
%�\��� � % html/_sources/library/termios.rst.txtnu �[���
:mod:`termios` --- POSIX style tty control
==========================================
.. module:: termios
:platform: Unix
:synopsis: POSIX style tty control.
.. index::
pair: POSIX; I/O control
pair: tty; I/O control
This module provides an interface to the POSIX calls for tty I/O control. For a
complete description of these calls, see :manpage:`termios(2)` Unix manual
page. It is only available for those Unix versions that support POSIX
*termios* style tty I/O control configured during installation.
All functions in this module take a file descriptor *fd* as their first
argument. This can be an integer file descriptor, such as returned by
``sys.stdin.fileno()``, or a file object, such as ``sys.stdin`` itself.
This module also defines all the constants needed to work with the functions
provided here; these have the same name as their counterparts in C. Please
refer to your system documentation for more information on using these terminal
control interfaces.
The module defines the following functions:
.. function:: tcgetattr(fd)
Return a list containing the tty attributes for file descriptor *fd*, as
follows: ``[iflag, oflag, cflag, lflag, ispeed, ospeed, cc]`` where *cc* is a
list of the tty special characters (each a string of length 1, except the
items with indices :const:`VMIN` and :const:`VTIME`, which are integers when
these fields are defined). The interpretation of the flags and the speeds as
well as the indexing in the *cc* array must be done using the symbolic
constants defined in the :mod:`termios` module.
.. function:: tcsetattr(fd, when, attributes)
Set the tty attributes for file descriptor *fd* from the *attributes*, which is
a list like the one returned by :func:`tcgetattr`. The *when* argument
determines when the attributes are changed: :const:`TCSANOW` to change
immediately, :const:`TCSADRAIN` to change after transmitting all queued output,
or :const:`TCSAFLUSH` to change after transmitting all queued output and
discarding all queued input.
.. function:: tcsendbreak(fd, duration)
Send a break on file descriptor *fd*. A zero *duration* sends a break for 0.25
--0.5 seconds; a nonzero *duration* has a system dependent meaning.
.. function:: tcdrain(fd)
Wait until all output written to file descriptor *fd* has been transmitted.
.. function:: tcflush(fd, queue)
Discard queued data on file descriptor *fd*. The *queue* selector specifies
which queue: :const:`TCIFLUSH` for the input queue, :const:`TCOFLUSH` for the
output queue, or :const:`TCIOFLUSH` for both queues.
.. function:: tcflow(fd, action)
Suspend or resume input or output on file descriptor *fd*. The *action*
argument can be :const:`TCOOFF` to suspend output, :const:`TCOON` to restart
output, :const:`TCIOFF` to suspend input, or :const:`TCION` to restart input.
.. seealso::
Module :mod:`tty`
Convenience functions for common terminal control operations.
Example
-------
.. _termios-example:
Here's a function that prompts for a password with echoing turned off. Note the
technique using a separate :func:`tcgetattr` call and a :keyword:`try` ...
:keyword:`finally` statement to ensure that the old tty attributes are restored
exactly no matter what happens::
def getpass(prompt="Password: "):
import termios, sys
fd = sys.stdin.fileno()
old = termios.tcgetattr(fd)
new = termios.tcgetattr(fd)
new[3] = new[3] & ~termios.ECHO # lflags
try:
termios.tcsetattr(fd, termios.TCSADRAIN, new)
passwd = raw_input(prompt)
finally:
termios.tcsetattr(fd, termios.TCSADRAIN, old)
return passwd
PK
%�\o��P�D �D " html/_sources/library/test.rst.txtnu �[���
:mod:`test` --- Regression tests package for Python
===================================================
.. module:: test
:synopsis: Regression tests package containing the testing suite for Python.
.. sectionauthor:: Brett Cannon <brett@python.org>
.. note::
The :mod:`test` package is meant for internal use by Python only. It is
documented for the benefit of the core developers of Python. Any use of
this package outside of Python's standard library is discouraged as code
mentioned here can change or be removed without notice between releases of
Python.
The :mod:`test` package contains all regression tests for Python as well as the
modules :mod:`test.support` and :mod:`test.regrtest`.
:mod:`test.support` is used to enhance your tests while
:mod:`test.regrtest` drives the testing suite.
Each module in the :mod:`test` package whose name starts with ``test_`` is a
testing suite for a specific module or feature. All new tests should be written
using the :mod:`unittest` or :mod:`doctest` module. Some older tests are
written using a "traditional" testing style that compares output printed to
``sys.stdout``; this style of test is considered deprecated.
.. seealso::
Module :mod:`unittest`
Writing PyUnit regression tests.
Module :mod:`doctest`
Tests embedded in documentation strings.
.. _writing-tests:
Writing Unit Tests for the :mod:`test` package
----------------------------------------------
It is preferred that tests that use the :mod:`unittest` module follow a few
guidelines. One is to name the test module by starting it with ``test_`` and end
it with the name of the module being tested. The test methods in the test module
should start with ``test_`` and end with a description of what the method is
testing. This is needed so that the methods are recognized by the test driver as
test methods. Also, no documentation string for the method should be included. A
comment (such as ``# Tests function returns only True or False``) should be used
to provide documentation for test methods. This is done because documentation
strings get printed out if they exist and thus what test is being run is not
stated.
A basic boilerplate is often used::
import unittest
from test import support
class MyTestCase1(unittest.TestCase):
# Only use setUp() and tearDown() if necessary
def setUp(self):
... code to execute in preparation for tests ...
def tearDown(self):
... code to execute to clean up after tests ...
def test_feature_one(self):
# Test feature one.
... testing code ...
def test_feature_two(self):
# Test feature two.
... testing code ...
... more test methods ...
class MyTestCase2(unittest.TestCase):
... same structure as MyTestCase1 ...
... more test classes ...
def test_main():
support.run_unittest(MyTestCase1,
MyTestCase2,
... list other tests ...
)
if __name__ == '__main__':
test_main()
This boilerplate code allows the testing suite to be run by :mod:`test.regrtest`
as well as on its own as a script.
The goal for regression testing is to try to break code. This leads to a few
guidelines to be followed:
* The testing suite should exercise all classes, functions, and constants. This
includes not just the external API that is to be presented to the outside
world but also "private" code.
* Whitebox testing (examining the code being tested when the tests are being
written) is preferred. Blackbox testing (testing only the published user
interface) is not complete enough to make sure all boundary and edge cases
are tested.
* Make sure all possible values are tested including invalid ones. This makes
sure that not only all valid values are acceptable but also that improper
values are handled correctly.
* Exhaust as many code paths as possible. Test where branching occurs and thus
tailor input to make sure as many different paths through the code are taken.
* Add an explicit test for any bugs discovered for the tested code. This will
make sure that the error does not crop up again if the code is changed in the
future.
* Make sure to clean up after your tests (such as close and remove all temporary
files).
* If a test is dependent on a specific condition of the operating system then
verify the condition already exists before attempting the test.
* Import as few modules as possible and do it as soon as possible. This
minimizes external dependencies of tests and also minimizes possible anomalous
behavior from side-effects of importing a module.
* Try to maximize code reuse. On occasion, tests will vary by something as small
as what type of input is used. Minimize code duplication by subclassing a
basic test class with a class that specifies the input::
class TestFuncAcceptsSequences(unittest.TestCase):
func = mySuperWhammyFunction
def test_func(self):
self.func(self.arg)
class AcceptLists(TestFuncAcceptsSequences):
arg = [1, 2, 3]
class AcceptStrings(TestFuncAcceptsSequences):
arg = 'abc'
class AcceptTuples(TestFuncAcceptsSequences):
arg = (1, 2, 3)
.. seealso::
Test Driven Development
A book by Kent Beck on writing tests before code.
.. _regrtest:
Running tests using the command-line interface
----------------------------------------------
The :mod:`test.regrtest` module can be run as a script to drive Python's regression
test suite, thanks to the :option:`-m` option: :program:`python -m test.regrtest`.
Running the script by itself automatically starts running all regression
tests in the :mod:`test` package. It does this by finding all modules in the
package whose name starts with ``test_``, importing them, and executing the
function :func:`test_main` if present. The names of tests to execute may also
be passed to the script. Specifying a single regression test (:program:`python
-m test.regrtest test_spam`) will minimize output and only print whether
the test passed or failed and thus minimize output.
Running :mod:`test.regrtest` directly allows what resources are available for
tests to use to be set. You do this by using the ``-u`` command-line
option. Specifying ``all`` as the value for the ``-u`` option enables all
possible resources: :program:`python -m test.regrtest -uall`.
If all but one resource is desired (a more common case), a
comma-separated list of resources that are not desired may be listed after
``all``. The command :program:`python -m test.regrtest -uall,-audio,-largefile`
will run :mod:`test.regrtest` with all resources except the ``audio`` and
``largefile`` resources. For a list of all resources and more command-line
options, run :program:`python -m test.regrtest -h`.
Some other ways to execute the regression tests depend on what platform the
tests are being executed on. On Unix, you can run :program:`make test` at the
top-level directory where Python was built. On Windows, executing
:program:`rt.bat` from your :file:`PCBuild` directory will run all regression
tests.
.. versionchanged:: 2.7.14
The :mod:`test` package can be run as a script: :program:`python -m test`.
This works the same as running the :mod:`test.regrtest` module.
:mod:`test.support` --- Utility functions for tests
===================================================
.. module:: test.support
:synopsis: Support for Python regression tests.
.. note::
The :mod:`test.test_support` module has been renamed to :mod:`test.support`
in Python 3.x and 2.7.14. The name ``test.test_support`` has been retained
as an alias in 2.7.
The :mod:`test.support` module provides support for Python's regression
tests.
This module defines the following exceptions:
.. exception:: TestFailed
Exception to be raised when a test fails. This is deprecated in favor of
:mod:`unittest`\ -based tests and :class:`unittest.TestCase`'s assertion
methods.
.. exception:: ResourceDenied
Subclass of :exc:`unittest.SkipTest`. Raised when a resource (such as a
network connection) is not available. Raised by the :func:`requires`
function.
The :mod:`test.support` module defines the following constants:
.. data:: verbose
:const:`True` when verbose output is enabled. Should be checked when more
detailed information is desired about a running test. *verbose* is set by
:mod:`test.regrtest`.
.. data:: have_unicode
:const:`True` when Unicode support is available.
.. data:: is_jython
:const:`True` if the running interpreter is Jython.
.. data:: TESTFN
Set to a name that is safe to use as the name of a temporary file. Any
temporary file that is created should be closed and unlinked (removed).
The :mod:`test.support` module defines the following functions:
.. function:: forget(module_name)
Remove the module named *module_name* from ``sys.modules`` and delete any
byte-compiled files of the module.
.. function:: is_resource_enabled(resource)
Return :const:`True` if *resource* is enabled and available. The list of
available resources is only set when :mod:`test.regrtest` is executing the
tests.
.. function:: requires(resource[, msg])
Raise :exc:`ResourceDenied` if *resource* is not available. *msg* is the
argument to :exc:`ResourceDenied` if it is raised. Always returns
:const:`True` if called by a function whose ``__name__`` is ``'__main__'``.
Used when tests are executed by :mod:`test.regrtest`.
.. function:: findfile(filename)
Return the path to the file named *filename*. If no match is found
*filename* is returned. This does not equal a failure since it could be the
path to the file.
.. function:: run_unittest(*classes)
Execute :class:`unittest.TestCase` subclasses passed to the function. The
function scans the classes for methods starting with the prefix ``test_``
and executes the tests individually.
It is also legal to pass strings as parameters; these should be keys in
``sys.modules``. Each associated module will be scanned by
``unittest.TestLoader.loadTestsFromModule()``. This is usually seen in the
following :func:`test_main` function::
def test_main():
support.run_unittest(__name__)
This will run all tests defined in the named module.
.. function:: check_warnings(*filters, quiet=True)
A convenience wrapper for :func:`warnings.catch_warnings()` that makes it
easier to test that a warning was correctly raised. It is approximately
equivalent to calling ``warnings.catch_warnings(record=True)`` with
:meth:`warnings.simplefilter` set to ``always`` and with the option to
automatically validate the results that are recorded.
``check_warnings`` accepts 2-tuples of the form ``("message regexp",
WarningCategory)`` as positional arguments. If one or more *filters* are
provided, or if the optional keyword argument *quiet* is :const:`False`,
it checks to make sure the warnings are as expected: each specified filter
must match at least one of the warnings raised by the enclosed code or the
test fails, and if any warnings are raised that do not match any of the
specified filters the test fails. To disable the first of these checks,
set *quiet* to :const:`True`.
If no arguments are specified, it defaults to::
check_warnings(("", Warning), quiet=True)
In this case all warnings are caught and no errors are raised.
On entry to the context manager, a :class:`WarningRecorder` instance is
returned. The underlying warnings list from
:func:`~warnings.catch_warnings` is available via the recorder object's
:attr:`warnings` attribute. As a convenience, the attributes of the object
representing the most recent warning can also be accessed directly through
the recorder object (see example below). If no warning has been raised,
then any of the attributes that would otherwise be expected on an object
representing a warning will return :const:`None`.
The recorder object also has a :meth:`reset` method, which clears the
warnings list.
The context manager is designed to be used like this::
with check_warnings(("assertion is always true", SyntaxWarning),
("", UserWarning)):
exec('assert(False, "Hey!")')
warnings.warn(UserWarning("Hide me!"))
In this case if either warning was not raised, or some other warning was
raised, :func:`check_warnings` would raise an error.
When a test needs to look more deeply into the warnings, rather than
just checking whether or not they occurred, code like this can be used::
with check_warnings(quiet=True) as w:
warnings.warn("foo")
assert str(w.args[0]) == "foo"
warnings.warn("bar")
assert str(w.args[0]) == "bar"
assert str(w.warnings[0].args[0]) == "foo"
assert str(w.warnings[1].args[0]) == "bar"
w.reset()
assert len(w.warnings) == 0
Here all warnings will be caught, and the test code tests the captured
warnings directly.
.. versionadded:: 2.6
.. versionchanged:: 2.7
New optional arguments *filters* and *quiet*.
.. function:: check_py3k_warnings(*filters, quiet=False)
Similar to :func:`check_warnings`, but for Python 3 compatibility warnings.
If ``sys.py3kwarning == 1``, it checks if the warning is effectively raised.
If ``sys.py3kwarning == 0``, it checks that no warning is raised. It
accepts 2-tuples of the form ``("message regexp", WarningCategory)`` as
positional arguments. When the optional keyword argument *quiet* is
:const:`True`, it does not fail if a filter catches nothing. Without
arguments, it defaults to::
check_py3k_warnings(("", DeprecationWarning), quiet=False)
.. versionadded:: 2.7
.. function:: captured_stdout()
This is a context manager that runs the :keyword:`with` statement body using
a :class:`StringIO.StringIO` object as sys.stdout. That object can be
retrieved using the ``as`` clause of the :keyword:`with` statement.
Example use::
with captured_stdout() as s:
print "hello"
assert s.getvalue() == "hello\n"
.. versionadded:: 2.6
.. function:: import_module(name, deprecated=False)
This function imports and returns the named module. Unlike a normal
import, this function raises :exc:`unittest.SkipTest` if the module
cannot be imported.
Module and package deprecation messages are suppressed during this import
if *deprecated* is :const:`True`.
.. versionadded:: 2.7
.. function:: import_fresh_module(name, fresh=(), blocked=(), deprecated=False)
This function imports and returns a fresh copy of the named Python module
by removing the named module from ``sys.modules`` before doing the import.
Note that unlike :func:`reload`, the original module is not affected by
this operation.
*fresh* is an iterable of additional module names that are also removed
from the ``sys.modules`` cache before doing the import.
*blocked* is an iterable of module names that are replaced with :const:`0`
in the module cache during the import to ensure that attempts to import
them raise :exc:`ImportError`.
The named module and any modules named in the *fresh* and *blocked*
parameters are saved before starting the import and then reinserted into
``sys.modules`` when the fresh import is complete.
Module and package deprecation messages are suppressed during this import
if *deprecated* is :const:`True`.
This function will raise :exc:`unittest.SkipTest` if the named module
cannot be imported.
Example use::
# Get copies of the warnings module for testing without
# affecting the version being used by the rest of the test suite
# One copy uses the C implementation, the other is forced to use
# the pure Python fallback implementation
py_warnings = import_fresh_module('warnings', blocked=['_warnings'])
c_warnings = import_fresh_module('warnings', fresh=['_warnings'])
.. versionadded:: 2.7
The :mod:`test.support` module defines the following classes:
.. class:: TransientResource(exc[, **kwargs])
Instances are a context manager that raises :exc:`ResourceDenied` if the
specified exception type is raised. Any keyword arguments are treated as
attribute/value pairs to be compared against any exception raised within the
:keyword:`with` statement. Only if all pairs match properly against
attributes on the exception is :exc:`ResourceDenied` raised.
.. versionadded:: 2.6
.. class:: EnvironmentVarGuard()
Class used to temporarily set or unset environment variables. Instances can
be used as a context manager and have a complete dictionary interface for
querying/modifying the underlying ``os.environ``. After exit from the
context manager all changes to environment variables done through this
instance will be rolled back.
.. versionadded:: 2.6
.. versionchanged:: 2.7
Added dictionary interface.
.. method:: EnvironmentVarGuard.set(envvar, value)
Temporarily set the environment variable ``envvar`` to the value of
``value``.
.. method:: EnvironmentVarGuard.unset(envvar)
Temporarily unset the environment variable ``envvar``.
.. class:: WarningsRecorder()
Class used to record warnings for unit tests. See documentation of
:func:`check_warnings` above for more details.
.. versionadded:: 2.6
PK
%�\<,��h! h! & html/_sources/library/textwrap.rst.txtnu �[��� :mod:`textwrap` --- Text wrapping and filling
=============================================
.. module:: textwrap
:synopsis: Text wrapping and filling
.. moduleauthor:: Greg Ward <gward@python.net>
.. sectionauthor:: Greg Ward <gward@python.net>
.. versionadded:: 2.3
**Source code:** :source:`Lib/textwrap.py`
--------------
The :mod:`textwrap` module provides two convenience functions, :func:`wrap` and
:func:`fill`, as well as :class:`TextWrapper`, the class that does all the work,
and a utility function :func:`dedent`. If you're just wrapping or filling one
or two text strings, the convenience functions should be good enough;
otherwise, you should use an instance of :class:`TextWrapper` for efficiency.
.. function:: wrap(text[, width[, ...]])
Wraps the single paragraph in *text* (a string) so every line is at most *width*
characters long. Returns a list of output lines, without final newlines.
Optional keyword arguments correspond to the instance attributes of
:class:`TextWrapper`, documented below. *width* defaults to ``70``.
See the :meth:`TextWrapper.wrap` method for additional details on how
:func:`wrap` behaves.
.. function:: fill(text[, width[, ...]])
Wraps the single paragraph in *text*, and returns a single string containing the
wrapped paragraph. :func:`fill` is shorthand for ::
"\n".join(wrap(text, ...))
In particular, :func:`fill` accepts exactly the same keyword arguments as
:func:`wrap`.
Both :func:`wrap` and :func:`fill` work by creating a :class:`TextWrapper`
instance and calling a single method on it. That instance is not reused, so for
applications that wrap/fill many text strings, it will be more efficient for you
to create your own :class:`TextWrapper` object.
Text is preferably wrapped on whitespaces and right after the hyphens in
hyphenated words; only then will long words be broken if necessary, unless
:attr:`TextWrapper.break_long_words` is set to false.
An additional utility function, :func:`dedent`, is provided to remove
indentation from strings that have unwanted whitespace to the left of the text.
.. function:: dedent(text)
Remove any common leading whitespace from every line in *text*.
This can be used to make triple-quoted strings line up with the left edge of the
display, while still presenting them in the source code in indented form.
Note that tabs and spaces are both treated as whitespace, but they are not
equal: the lines ``" hello"`` and ``"\thello"`` are considered to have no
common leading whitespace. (This behaviour is new in Python 2.5; older versions
of this module incorrectly expanded tabs before searching for common leading
whitespace.)
For example::
def test():
# end first line with \ to avoid the empty line!
s = '''\
hello
world
'''
print repr(s) # prints ' hello\n world\n '
print repr(dedent(s)) # prints 'hello\n world\n'
.. class:: TextWrapper(...)
The :class:`TextWrapper` constructor accepts a number of optional keyword
arguments. Each argument corresponds to one instance attribute, so for example
::
wrapper = TextWrapper(initial_indent="* ")
is the same as ::
wrapper = TextWrapper()
wrapper.initial_indent = "* "
You can re-use the same :class:`TextWrapper` object many times, and you can
change any of its options through direct assignment to instance attributes
between uses.
The :class:`TextWrapper` instance attributes (and keyword arguments to the
constructor) are as follows:
.. attribute:: width
(default: ``70``) The maximum length of wrapped lines. As long as there
are no individual words in the input text longer than :attr:`width`,
:class:`TextWrapper` guarantees that no output line will be longer than
:attr:`width` characters.
.. attribute:: expand_tabs
(default: ``True``) If true, then all tab characters in *text* will be
expanded to spaces using the :meth:`expandtabs` method of *text*.
.. attribute:: replace_whitespace
(default: ``True``) If true, after tab expansion but before wrapping,
the :meth:`wrap` method will replace each whitespace character
with a single space. The whitespace characters replaced are
as follows: tab, newline, vertical tab, formfeed, and carriage
return (``'\t\n\v\f\r'``).
.. note::
If :attr:`expand_tabs` is false and :attr:`replace_whitespace` is true,
each tab character will be replaced by a single space, which is *not*
the same as tab expansion.
.. note::
If :attr:`replace_whitespace` is false, newlines may appear in the
middle of a line and cause strange output. For this reason, text should
be split into paragraphs (using :meth:`str.splitlines` or similar)
which are wrapped separately.
.. attribute:: drop_whitespace
(default: ``True``) If true, whitespace at the beginning and ending of
every line (after wrapping but before indenting) is dropped.
Whitespace at the beginning of the paragraph, however, is not dropped
if non-whitespace follows it. If whitespace being dropped takes up an
entire line, the whole line is dropped.
.. versionadded:: 2.6
Whitespace was always dropped in earlier versions.
.. attribute:: initial_indent
(default: ``''``) String that will be prepended to the first line of
wrapped output. Counts towards the length of the first line. The empty
string is not indented.
.. attribute:: subsequent_indent
(default: ``''``) String that will be prepended to all lines of wrapped
output except the first. Counts towards the length of each line except
the first.
.. attribute:: fix_sentence_endings
(default: ``False``) If true, :class:`TextWrapper` attempts to detect
sentence endings and ensure that sentences are always separated by exactly
two spaces. This is generally desired for text in a monospaced font.
However, the sentence detection algorithm is imperfect: it assumes that a
sentence ending consists of a lowercase letter followed by one of ``'.'``,
``'!'``, or ``'?'``, possibly followed by one of ``'"'`` or ``"'"``,
followed by a space. One problem with this is algorithm is that it is
unable to detect the difference between "Dr." in ::
[...] Dr. Frankenstein's monster [...]
and "Spot." in ::
[...] See Spot. See Spot run [...]
:attr:`fix_sentence_endings` is false by default.
Since the sentence detection algorithm relies on ``string.lowercase`` for
the definition of "lowercase letter," and a convention of using two spaces
after a period to separate sentences on the same line, it is specific to
English-language texts.
.. attribute:: break_long_words
(default: ``True``) If true, then words longer than :attr:`width` will be
broken in order to ensure that no lines are longer than :attr:`width`. If
it is false, long words will not be broken, and some lines may be longer
than :attr:`width`. (Long words will be put on a line by themselves, in
order to minimize the amount by which :attr:`width` is exceeded.)
.. attribute:: break_on_hyphens
(default: ``True``) If true, wrapping will occur preferably on whitespaces
and right after hyphens in compound words, as it is customary in English.
If false, only whitespaces will be considered as potentially good places
for line breaks, but you need to set :attr:`break_long_words` to false if
you want truly insecable words. Default behaviour in previous versions
was to always allow breaking hyphenated words.
.. versionadded:: 2.6
:class:`TextWrapper` also provides two public methods, analogous to the
module-level convenience functions:
.. method:: wrap(text)
Wraps the single paragraph in *text* (a string) so every line is at most
:attr:`width` characters long. All wrapping options are taken from
instance attributes of the :class:`TextWrapper` instance. Returns a list
of output lines, without final newlines. If the wrapped output has no
content, the returned list is empty.
.. method:: fill(text)
Wraps the single paragraph in *text*, and returns a single string
containing the wrapped paragraph.
PK
%�\үͳ� � $ html/_sources/library/thread.rst.txtnu �[��� :mod:`thread` --- Multiple threads of control
=============================================
.. module:: thread
:synopsis: Create multiple threads of control within one interpreter.
.. note::
The :mod:`thread` module has been renamed to :mod:`_thread` in Python 3.
The :term:`2to3` tool will automatically adapt imports when converting your
sources to Python 3; however, you should consider using the high-level
:mod:`threading` module instead.
.. index::
single: light-weight processes
single: processes, light-weight
single: binary semaphores
single: semaphores, binary
This module provides low-level primitives for working with multiple threads
(also called :dfn:`light-weight processes` or :dfn:`tasks`) --- multiple threads of
control sharing their global data space. For synchronization, simple locks
(also called :dfn:`mutexes` or :dfn:`binary semaphores`) are provided.
The :mod:`threading` module provides an easier to use and higher-level
threading API built on top of this module.
.. index::
single: pthreads
pair: threads; POSIX
The module is optional. It is supported on Windows, Linux, SGI IRIX, Solaris
2.x, as well as on systems that have a POSIX thread (a.k.a. "pthread")
implementation. For systems lacking the :mod:`thread` module, the
:mod:`dummy_thread` module is available. It duplicates this module's interface
and can be used as a drop-in replacement.
It defines the following constant and functions:
.. exception:: error
Raised on thread-specific errors.
.. data:: LockType
This is the type of lock objects.
.. function:: start_new_thread(function, args[, kwargs])
Start a new thread and return its identifier. The thread executes the function
*function* with the argument list *args* (which must be a tuple). The optional
*kwargs* argument specifies a dictionary of keyword arguments. When the function
returns, the thread silently exits. When the function terminates with an
unhandled exception, a stack trace is printed and then the thread exits (but
other threads continue to run).
.. function:: interrupt_main()
Raise a :exc:`KeyboardInterrupt` exception in the main thread. A subthread can
use this function to interrupt the main thread.
.. versionadded:: 2.3
.. function:: exit()
Raise the :exc:`SystemExit` exception. When not caught, this will cause the
thread to exit silently.
..
function:: exit_prog(status)
Exit all threads and report the value of the integer argument
*status* as the exit status of the entire program.
**Caveat:** code in pending :keyword:`finally` clauses, in this thread
or in other threads, is not executed.
.. function:: allocate_lock()
Return a new lock object. Methods of locks are described below. The lock is
initially unlocked.
.. function:: get_ident()
Return the 'thread identifier' of the current thread. This is a nonzero
integer. Its value has no direct meaning; it is intended as a magic cookie to
be used e.g. to index a dictionary of thread-specific data. Thread identifiers
may be recycled when a thread exits and another thread is created.
.. function:: stack_size([size])
Return the thread stack size used when creating new threads. The optional
*size* argument specifies the stack size to be used for subsequently created
threads, and must be 0 (use platform or configured default) or a positive
integer value of at least 32,768 (32kB). If *size* is not specified,
0 is used. If changing the thread stack size is
unsupported, the :exc:`error` exception is raised. If the specified stack size is
invalid, a :exc:`ValueError` is raised and the stack size is unmodified. 32kB
is currently the minimum supported stack size value to guarantee sufficient
stack space for the interpreter itself. Note that some platforms may have
particular restrictions on values for the stack size, such as requiring a
minimum stack size > 32kB or requiring allocation in multiples of the system
memory page size - platform documentation should be referred to for more
information (4kB pages are common; using multiples of 4096 for the stack size is
the suggested approach in the absence of more specific information).
Availability: Windows, systems with POSIX threads.
.. versionadded:: 2.5
Lock objects have the following methods:
.. method:: lock.acquire([waitflag])
Without the optional argument, this method acquires the lock unconditionally, if
necessary waiting until it is released by another thread (only one thread at a
time can acquire a lock --- that's their reason for existence). If the integer
*waitflag* argument is present, the action depends on its value: if it is zero,
the lock is only acquired if it can be acquired immediately without waiting,
while if it is nonzero, the lock is acquired unconditionally as before. The
return value is ``True`` if the lock is acquired successfully, ``False`` if not.
.. method:: lock.release()
Releases the lock. The lock must have been acquired earlier, but not
necessarily by the same thread.
.. method:: lock.locked()
Return the status of the lock: ``True`` if it has been acquired by some thread,
``False`` if not.
In addition to these methods, lock objects can also be used via the
:keyword:`with` statement, e.g.::
import thread
a_lock = thread.allocate_lock()
with a_lock:
print "a_lock is locked while this executes"
**Caveats:**
.. index:: module: signal
* Threads interact strangely with interrupts: the :exc:`KeyboardInterrupt`
exception will be received by an arbitrary thread. (When the :mod:`signal`
module is available, interrupts always go to the main thread.)
* Calling :func:`sys.exit` or raising the :exc:`SystemExit` exception is
equivalent to calling :func:`thread.exit`.
* It is not possible to interrupt the :meth:`acquire` method on a lock --- the
:exc:`KeyboardInterrupt` exception will happen after the lock has been acquired.
.. index:: pair: threads; IRIX
* When the main thread exits, it is system defined whether the other threads
survive. On SGI IRIX using the native thread implementation, they survive. On
most other systems, they are killed without executing :keyword:`try` ...
:keyword:`finally` clauses or executing object destructors.
* When the main thread exits, it does not do any of its usual cleanup (except
that :keyword:`try` ... :keyword:`finally` clauses are honored), and the
standard I/O files are not flushed.
PK
%�\�n}�~ �~ ' html/_sources/library/threading.rst.txtnu �[��� :mod:`threading` --- Higher-level threading interface
=====================================================
.. module:: threading
:synopsis: Higher-level threading interface.
**Source code:** :source:`Lib/threading.py`
--------------
This module constructs higher-level threading interfaces on top of the lower
level :mod:`thread` module.
See also the :mod:`mutex` and :mod:`Queue` modules.
The :mod:`dummy_threading` module is provided for situations where
:mod:`threading` cannot be used because :mod:`thread` is missing.
.. note::
Starting with Python 2.6, this module provides :pep:`8` compliant aliases and
properties to replace the ``camelCase`` names that were inspired by Java's
threading API. This updated API is compatible with that of the
:mod:`multiprocessing` module. However, no schedule has been set for the
deprecation of the ``camelCase`` names and they remain fully supported in
both Python 2.x and 3.x.
.. note::
Starting with Python 2.5, several Thread methods raise :exc:`RuntimeError`
instead of :exc:`AssertionError` if called erroneously.
.. impl-detail::
In CPython, due to the :term:`Global Interpreter Lock`, only one thread
can execute Python code at once (even though certain performance-oriented
libraries might overcome this limitation).
If you want your application to make better use of the computational
resources of multi-core machines, you are advised to use
:mod:`multiprocessing`. However, threading is still an appropriate model
if you want to run multiple I/O-bound tasks simultaneously.
This module defines the following functions and objects:
.. function:: active_count()
activeCount()
Return the number of :class:`Thread` objects currently alive. The returned
count is equal to the length of the list returned by :func:`.enumerate`.
.. versionchanged:: 2.6
Added ``active_count()`` spelling.
.. function:: Condition()
:noindex:
A factory function that returns a new condition variable object. A condition
variable allows one or more threads to wait until they are notified by another
thread.
See :ref:`condition-objects`.
.. function:: current_thread()
currentThread()
Return the current :class:`Thread` object, corresponding to the caller's thread
of control. If the caller's thread of control was not created through the
:mod:`threading` module, a dummy thread object with limited functionality is
returned.
.. versionchanged:: 2.6
Added ``current_thread()`` spelling.
.. function:: enumerate()
Return a list of all :class:`Thread` objects currently alive. The list
includes daemonic threads, dummy thread objects created by
:func:`current_thread`, and the main thread. It excludes terminated threads
and threads that have not yet been started.
.. function:: Event()
:noindex:
A factory function that returns a new event object. An event manages a flag
that can be set to true with the :meth:`~Event.set` method and reset to false
with the :meth:`clear` method. The :meth:`wait` method blocks until the flag
is true.
See :ref:`event-objects`.
.. class:: local
A class that represents thread-local data. Thread-local data are data whose
values are thread specific. To manage thread-local data, just create an
instance of :class:`local` (or a subclass) and store attributes on it::
mydata = threading.local()
mydata.x = 1
The instance's values will be different for separate threads.
For more details and extensive examples, see the documentation string of the
:mod:`_threading_local` module.
.. versionadded:: 2.4
.. function:: Lock()
A factory function that returns a new primitive lock object. Once a thread has
acquired it, subsequent attempts to acquire it block, until it is released; any
thread may release it.
See :ref:`lock-objects`.
.. function:: RLock()
A factory function that returns a new reentrant lock object. A reentrant lock
must be released by the thread that acquired it. Once a thread has acquired a
reentrant lock, the same thread may acquire it again without blocking; the
thread must release it once for each time it has acquired it.
See :ref:`rlock-objects`.
.. function:: Semaphore([value])
:noindex:
A factory function that returns a new semaphore object. A semaphore manages a
counter representing the number of :meth:`release` calls minus the number of
:meth:`acquire` calls, plus an initial value. The :meth:`acquire` method blocks
if necessary until it can return without making the counter negative. If not
given, *value* defaults to 1.
See :ref:`semaphore-objects`.
.. function:: BoundedSemaphore([value])
A factory function that returns a new bounded semaphore object. A bounded
semaphore checks to make sure its current value doesn't exceed its initial
value. If it does, :exc:`ValueError` is raised. In most situations semaphores
are used to guard resources with limited capacity. If the semaphore is released
too many times it's a sign of a bug. If not given, *value* defaults to 1.
.. class:: Thread
:noindex:
A class that represents a thread of control. This class can be safely
subclassed in a limited fashion.
See :ref:`thread-objects`.
.. class:: Timer
:noindex:
A thread that executes a function after a specified interval has passed.
See :ref:`timer-objects`.
.. function:: settrace(func)
.. index:: single: trace function
Set a trace function for all threads started from the :mod:`threading` module.
The *func* will be passed to :func:`sys.settrace` for each thread, before its
:meth:`~Thread.run` method is called.
.. versionadded:: 2.3
.. function:: setprofile(func)
.. index:: single: profile function
Set a profile function for all threads started from the :mod:`threading` module.
The *func* will be passed to :func:`sys.setprofile` for each thread, before its
:meth:`~Thread.run` method is called.
.. versionadded:: 2.3
.. function:: stack_size([size])
Return the thread stack size used when creating new threads. The optional
*size* argument specifies the stack size to be used for subsequently created
threads, and must be 0 (use platform or configured default) or a positive
integer value of at least 32,768 (32 KiB). If *size* is not specified,
0 is used. If changing the thread stack size is
unsupported, a :exc:`ThreadError` is raised. If the specified stack size is
invalid, a :exc:`ValueError` is raised and the stack size is unmodified. 32kB
is currently the minimum supported stack size value to guarantee sufficient
stack space for the interpreter itself. Note that some platforms may have
particular restrictions on values for the stack size, such as requiring a
minimum stack size > 32kB or requiring allocation in multiples of the system
memory page size - platform documentation should be referred to for more
information (4kB pages are common; using multiples of 4096 for the stack size is
the suggested approach in the absence of more specific information).
Availability: Windows, systems with POSIX threads.
.. versionadded:: 2.5
.. exception:: ThreadError
Raised for various threading-related errors as described below. Note that
many interfaces use :exc:`RuntimeError` instead of :exc:`ThreadError`.
Detailed interfaces for the objects are documented below.
The design of this module is loosely based on Java's threading model. However,
where Java makes locks and condition variables basic behavior of every object,
they are separate objects in Python. Python's :class:`Thread` class supports a
subset of the behavior of Java's Thread class; currently, there are no
priorities, no thread groups, and threads cannot be destroyed, stopped,
suspended, resumed, or interrupted. The static methods of Java's Thread class,
when implemented, are mapped to module-level functions.
All of the methods described below are executed atomically.
.. _thread-objects:
Thread Objects
--------------
This class represents an activity that is run in a separate thread of control.
There are two ways to specify the activity: by passing a callable object to the
constructor, or by overriding the :meth:`run` method in a subclass. No other
methods (except for the constructor) should be overridden in a subclass. In
other words, *only* override the :meth:`__init__` and :meth:`run` methods of
this class.
Once a thread object is created, its activity must be started by calling the
thread's :meth:`start` method. This invokes the :meth:`run` method in a
separate thread of control.
Once the thread's activity is started, the thread is considered 'alive'. It
stops being alive when its :meth:`run` method terminates -- either normally, or
by raising an unhandled exception. The :meth:`is_alive` method tests whether the
thread is alive.
Other threads can call a thread's :meth:`join` method. This blocks the calling
thread until the thread whose :meth:`join` method is called is terminated.
A thread has a name. The name can be passed to the constructor, and read or
changed through the :attr:`name` attribute.
A thread can be flagged as a "daemon thread". The significance of this flag is
that the entire Python program exits when only daemon threads are left. The
initial value is inherited from the creating thread. The flag can be set
through the :attr:`daemon` property.
.. note::
Daemon threads are abruptly stopped at shutdown. Their resources (such
as open files, database transactions, etc.) may not be released properly.
If you want your threads to stop gracefully, make them non-daemonic and
use a suitable signalling mechanism such as an :class:`Event`.
There is a "main thread" object; this corresponds to the initial thread of
control in the Python program. It is not a daemon thread.
There is the possibility that "dummy thread objects" are created. These are
thread objects corresponding to "alien threads", which are threads of control
started outside the threading module, such as directly from C code. Dummy
thread objects have limited functionality; they are always considered alive and
daemonic, and cannot be :meth:`join`\ ed. They are never deleted, since it is
impossible to detect the termination of alien threads.
.. class:: Thread(group=None, target=None, name=None, args=(), kwargs={})
This constructor should always be called with keyword arguments. Arguments
are:
*group* should be ``None``; reserved for future extension when a
:class:`ThreadGroup` class is implemented.
*target* is the callable object to be invoked by the :meth:`run` method.
Defaults to ``None``, meaning nothing is called.
*name* is the thread name. By default, a unique name is constructed of the
form "Thread-*N*" where *N* is a small decimal number.
*args* is the argument tuple for the target invocation. Defaults to ``()``.
*kwargs* is a dictionary of keyword arguments for the target invocation.
Defaults to ``{}``.
If the subclass overrides the constructor, it must make sure to invoke the
base class constructor (``Thread.__init__()``) before doing anything else to
the thread.
.. method:: start()
Start the thread's activity.
It must be called at most once per thread object. It arranges for the
object's :meth:`run` method to be invoked in a separate thread of control.
This method will raise a :exc:`RuntimeError` if called more than once
on the same thread object.
.. method:: run()
Method representing the thread's activity.
You may override this method in a subclass. The standard :meth:`run`
method invokes the callable object passed to the object's constructor as
the *target* argument, if any, with sequential and keyword arguments taken
from the *args* and *kwargs* arguments, respectively.
.. method:: join([timeout])
Wait until the thread terminates. This blocks the calling thread until the
thread whose :meth:`join` method is called terminates -- either normally
or through an unhandled exception -- or until the optional timeout occurs.
When the *timeout* argument is present and not ``None``, it should be a
floating point number specifying a timeout for the operation in seconds
(or fractions thereof). As :meth:`join` always returns ``None``, you must
call :meth:`isAlive` after :meth:`join` to decide whether a timeout
happened -- if the thread is still alive, the :meth:`join` call timed out.
When the *timeout* argument is not present or ``None``, the operation will
block until the thread terminates.
A thread can be :meth:`join`\ ed many times.
:meth:`join` raises a :exc:`RuntimeError` if an attempt is made to join
the current thread as that would cause a deadlock. It is also an error to
:meth:`join` a thread before it has been started and attempts to do so
raises the same exception.
.. attribute:: name
A string used for identification purposes only. It has no semantics.
Multiple threads may be given the same name. The initial name is set by
the constructor.
.. versionadded:: 2.6
.. method:: getName()
setName()
Pre-2.6 API for :attr:`~Thread.name`.
.. attribute:: ident
The 'thread identifier' of this thread or ``None`` if the thread has not
been started. This is a nonzero integer. See the
:func:`thread.get_ident()` function. Thread identifiers may be recycled
when a thread exits and another thread is created. The identifier is
available even after the thread has exited.
.. versionadded:: 2.6
.. method:: is_alive()
isAlive()
Return whether the thread is alive.
This method returns ``True`` just before the :meth:`run` method starts
until just after the :meth:`run` method terminates. The module function
:func:`.enumerate` returns a list of all alive threads.
.. versionchanged:: 2.6
Added ``is_alive()`` spelling.
.. attribute:: daemon
A boolean value indicating whether this thread is a daemon thread (True)
or not (False). This must be set before :meth:`start` is called,
otherwise :exc:`RuntimeError` is raised. Its initial value is inherited
from the creating thread; the main thread is not a daemon thread and
therefore all threads created in the main thread default to :attr:`daemon`
= ``False``.
The entire Python program exits when no alive non-daemon threads are left.
.. versionadded:: 2.6
.. method:: isDaemon()
setDaemon()
Pre-2.6 API for :attr:`~Thread.daemon`.
.. _lock-objects:
Lock Objects
------------
A primitive lock is a synchronization primitive that is not owned by a
particular thread when locked. In Python, it is currently the lowest level
synchronization primitive available, implemented directly by the :mod:`thread`
extension module.
A primitive lock is in one of two states, "locked" or "unlocked". It is created
in the unlocked state. It has two basic methods, :meth:`acquire` and
:meth:`release`. When the state is unlocked, :meth:`acquire` changes the state
to locked and returns immediately. When the state is locked, :meth:`acquire`
blocks until a call to :meth:`release` in another thread changes it to unlocked,
then the :meth:`acquire` call resets it to locked and returns. The
:meth:`release` method should only be called in the locked state; it changes the
state to unlocked and returns immediately. If an attempt is made to release an
unlocked lock, a :exc:`ThreadError` will be raised.
When more than one thread is blocked in :meth:`acquire` waiting for the state to
turn to unlocked, only one thread proceeds when a :meth:`release` call resets
the state to unlocked; which one of the waiting threads proceeds is not defined,
and may vary across implementations.
All methods are executed atomically.
.. method:: Lock.acquire([blocking])
Acquire a lock, blocking or non-blocking.
When invoked with the *blocking* argument set to ``True`` (the default),
block until the lock is unlocked, then set it to locked and return ``True``.
When invoked with the *blocking* argument set to ``False``, do not block.
If a call with *blocking* set to ``True`` would block, return ``False``
immediately; otherwise, set the lock to locked and return ``True``.
.. method:: Lock.release()
Release a lock.
When the lock is locked, reset it to unlocked, and return. If any other threads
are blocked waiting for the lock to become unlocked, allow exactly one of them
to proceed.
When invoked on an unlocked lock, a :exc:`ThreadError` is raised.
There is no return value.
.. _rlock-objects:
RLock Objects
-------------
A reentrant lock is a synchronization primitive that may be acquired multiple
times by the same thread. Internally, it uses the concepts of "owning thread"
and "recursion level" in addition to the locked/unlocked state used by primitive
locks. In the locked state, some thread owns the lock; in the unlocked state,
no thread owns it.
To lock the lock, a thread calls its :meth:`acquire` method; this returns once
the thread owns the lock. To unlock the lock, a thread calls its
:meth:`release` method. :meth:`acquire`/:meth:`release` call pairs may be
nested; only the final :meth:`release` (the :meth:`release` of the outermost
pair) resets the lock to unlocked and allows another thread blocked in
:meth:`acquire` to proceed.
.. method:: RLock.acquire([blocking=1])
Acquire a lock, blocking or non-blocking.
When invoked without arguments: if this thread already owns the lock, increment
the recursion level by one, and return immediately. Otherwise, if another
thread owns the lock, block until the lock is unlocked. Once the lock is
unlocked (not owned by any thread), then grab ownership, set the recursion level
to one, and return. If more than one thread is blocked waiting until the lock
is unlocked, only one at a time will be able to grab ownership of the lock.
There is no return value in this case.
When invoked with the *blocking* argument set to true, do the same thing as when
called without arguments, and return true.
When invoked with the *blocking* argument set to false, do not block. If a call
without an argument would block, return false immediately; otherwise, do the
same thing as when called without arguments, and return true.
.. method:: RLock.release()
Release a lock, decrementing the recursion level. If after the decrement it is
zero, reset the lock to unlocked (not owned by any thread), and if any other
threads are blocked waiting for the lock to become unlocked, allow exactly one
of them to proceed. If after the decrement the recursion level is still
nonzero, the lock remains locked and owned by the calling thread.
Only call this method when the calling thread owns the lock. A
:exc:`RuntimeError` is raised if this method is called when the lock is
unlocked.
There is no return value.
.. _condition-objects:
Condition Objects
-----------------
A condition variable is always associated with some kind of lock; this can be
passed in or one will be created by default. (Passing one in is useful when
several condition variables must share the same lock.)
A condition variable has :meth:`acquire` and :meth:`release` methods that call
the corresponding methods of the associated lock. It also has a :meth:`wait`
method, and :meth:`notify` and :meth:`notifyAll` methods. These three must only
be called when the calling thread has acquired the lock, otherwise a
:exc:`RuntimeError` is raised.
The :meth:`wait` method releases the lock, and then blocks until it is awakened
by a :meth:`notify` or :meth:`notifyAll` call for the same condition variable in
another thread. Once awakened, it re-acquires the lock and returns. It is also
possible to specify a timeout.
The :meth:`notify` method wakes up one of the threads waiting for the condition
variable, if any are waiting. The :meth:`notifyAll` method wakes up all threads
waiting for the condition variable.
Note: the :meth:`notify` and :meth:`notifyAll` methods don't release the lock;
this means that the thread or threads awakened will not return from their
:meth:`wait` call immediately, but only when the thread that called
:meth:`notify` or :meth:`notifyAll` finally relinquishes ownership of the lock.
Tip: the typical programming style using condition variables uses the lock to
synchronize access to some shared state; threads that are interested in a
particular change of state call :meth:`wait` repeatedly until they see the
desired state, while threads that modify the state call :meth:`notify` or
:meth:`notifyAll` when they change the state in such a way that it could
possibly be a desired state for one of the waiters. For example, the following
code is a generic producer-consumer situation with unlimited buffer capacity::
# Consume one item
cv.acquire()
while not an_item_is_available():
cv.wait()
get_an_available_item()
cv.release()
# Produce one item
cv.acquire()
make_an_item_available()
cv.notify()
cv.release()
To choose between :meth:`notify` and :meth:`notifyAll`, consider whether one
state change can be interesting for only one or several waiting threads. E.g.
in a typical producer-consumer situation, adding one item to the buffer only
needs to wake up one consumer thread.
.. class:: Condition([lock])
If the *lock* argument is given and not ``None``, it must be a :class:`Lock`
or :class:`RLock` object, and it is used as the underlying lock. Otherwise,
a new :class:`RLock` object is created and used as the underlying lock.
.. method:: acquire(*args)
Acquire the underlying lock. This method calls the corresponding method on
the underlying lock; the return value is whatever that method returns.
.. method:: release()
Release the underlying lock. This method calls the corresponding method on
the underlying lock; there is no return value.
.. method:: wait([timeout])
Wait until notified or until a timeout occurs. If the calling thread has not
acquired the lock when this method is called, a :exc:`RuntimeError` is raised.
This method releases the underlying lock, and then blocks until it is
awakened by a :meth:`notify` or :meth:`notifyAll` call for the same
condition variable in another thread, or until the optional timeout
occurs. Once awakened or timed out, it re-acquires the lock and returns.
When the *timeout* argument is present and not ``None``, it should be a
floating point number specifying a timeout for the operation in seconds
(or fractions thereof).
When the underlying lock is an :class:`RLock`, it is not released using
its :meth:`release` method, since this may not actually unlock the lock
when it was acquired multiple times recursively. Instead, an internal
interface of the :class:`RLock` class is used, which really unlocks it
even when it has been recursively acquired several times. Another internal
interface is then used to restore the recursion level when the lock is
reacquired.
.. method:: notify(n=1)
By default, wake up one thread waiting on this condition, if any. If the
calling thread has not acquired the lock when this method is called, a
:exc:`RuntimeError` is raised.
This method wakes up at most *n* of the threads waiting for the condition
variable; it is a no-op if no threads are waiting.
The current implementation wakes up exactly *n* threads, if at least *n*
threads are waiting. However, it's not safe to rely on this behavior.
A future, optimized implementation may occasionally wake up more than
*n* threads.
Note: an awakened thread does not actually return from its :meth:`wait`
call until it can reacquire the lock. Since :meth:`notify` does not
release the lock, its caller should.
.. method:: notify_all()
notifyAll()
Wake up all threads waiting on this condition. This method acts like
:meth:`notify`, but wakes up all waiting threads instead of one. If the
calling thread has not acquired the lock when this method is called, a
:exc:`RuntimeError` is raised.
.. versionchanged:: 2.6
Added ``notify_all()`` spelling.
.. _semaphore-objects:
Semaphore Objects
-----------------
This is one of the oldest synchronization primitives in the history of computer
science, invented by the early Dutch computer scientist Edsger W. Dijkstra (he
used :meth:`P` and :meth:`V` instead of :meth:`acquire` and :meth:`release`).
A semaphore manages an internal counter which is decremented by each
:meth:`acquire` call and incremented by each :meth:`release` call. The counter
can never go below zero; when :meth:`acquire` finds that it is zero, it blocks,
waiting until some other thread calls :meth:`release`.
.. class:: Semaphore([value])
The optional argument gives the initial *value* for the internal counter; it
defaults to ``1``. If the *value* given is less than 0, :exc:`ValueError` is
raised.
.. method:: acquire([blocking])
Acquire a semaphore.
When invoked without arguments: if the internal counter is larger than
zero on entry, decrement it by one and return immediately. If it is zero
on entry, block, waiting until some other thread has called
:meth:`release` to make it larger than zero. This is done with proper
interlocking so that if multiple :meth:`acquire` calls are blocked,
:meth:`release` will wake exactly one of them up. The implementation may
pick one at random, so the order in which blocked threads are awakened
should not be relied on. There is no return value in this case.
When invoked with *blocking* set to true, do the same thing as when called
without arguments, and return true.
When invoked with *blocking* set to false, do not block. If a call
without an argument would block, return false immediately; otherwise, do
the same thing as when called without arguments, and return true.
.. method:: release()
Release a semaphore, incrementing the internal counter by one. When it
was zero on entry and another thread is waiting for it to become larger
than zero again, wake up that thread.
.. _semaphore-examples:
:class:`Semaphore` Example
^^^^^^^^^^^^^^^^^^^^^^^^^^
Semaphores are often used to guard resources with limited capacity, for example,
a database server. In any situation where the size of the resource is fixed,
you should use a bounded semaphore. Before spawning any worker threads, your
main thread would initialize the semaphore::
maxconnections = 5
...
pool_sema = BoundedSemaphore(value=maxconnections)
Once spawned, worker threads call the semaphore's acquire and release methods
when they need to connect to the server::
pool_sema.acquire()
conn = connectdb()
... use connection ...
conn.close()
pool_sema.release()
The use of a bounded semaphore reduces the chance that a programming error which
causes the semaphore to be released more than it's acquired will go undetected.
.. _event-objects:
Event Objects
-------------
This is one of the simplest mechanisms for communication between threads: one
thread signals an event and other threads wait for it.
An event object manages an internal flag that can be set to true with the
:meth:`~Event.set` method and reset to false with the :meth:`~Event.clear`
method. The :meth:`~Event.wait` method blocks until the flag is true.
.. class:: Event()
The internal flag is initially false.
.. method:: is_set()
isSet()
Return true if and only if the internal flag is true.
.. versionchanged:: 2.6
Added ``is_set()`` spelling.
.. method:: set()
Set the internal flag to true. All threads waiting for it to become true
are awakened. Threads that call :meth:`wait` once the flag is true will
not block at all.
.. method:: clear()
Reset the internal flag to false. Subsequently, threads calling
:meth:`wait` will block until :meth:`.set` is called to set the internal
flag to true again.
.. method:: wait([timeout])
Block until the internal flag is true. If the internal flag is true on
entry, return immediately. Otherwise, block until another thread calls
:meth:`.set` to set the flag to true, or until the optional timeout
occurs.
When the timeout argument is present and not ``None``, it should be a
floating point number specifying a timeout for the operation in seconds
(or fractions thereof).
This method returns the internal flag on exit, so it will always return
``True`` except if a timeout is given and the operation times out.
.. versionchanged:: 2.7
Previously, the method always returned ``None``.
.. _timer-objects:
Timer Objects
-------------
This class represents an action that should be run only after a certain amount
of time has passed --- a timer. :class:`Timer` is a subclass of :class:`Thread`
and as such also functions as an example of creating custom threads.
Timers are started, as with threads, by calling their :meth:`~Timer.start`
method. The timer can be stopped (before its action has begun) by calling the
:meth:`~Timer.cancel` method. The interval the timer will wait before
executing its action may not be exactly the same as the interval specified by
the user.
For example::
def hello():
print "hello, world"
t = Timer(30.0, hello)
t.start() # after 30 seconds, "hello, world" will be printed
.. class:: Timer(interval, function, args=[], kwargs={})
Create a timer that will run *function* with arguments *args* and keyword
arguments *kwargs*, after *interval* seconds have passed.
.. method:: cancel()
Stop the timer, and cancel the execution of the timer's action. This will
only work if the timer is still in its waiting stage.
.. _with-locks:
Using locks, conditions, and semaphores in the :keyword:`with` statement
------------------------------------------------------------------------
All of the objects provided by this module that have :meth:`acquire` and
:meth:`release` methods can be used as context managers for a :keyword:`with`
statement. The :meth:`acquire` method will be called when the block is entered,
and :meth:`release` will be called when the block is exited.
Currently, :class:`Lock`, :class:`RLock`, :class:`Condition`,
:class:`Semaphore`, and :class:`BoundedSemaphore` objects may be used as
:keyword:`with` statement context managers. For example::
import threading
some_rlock = threading.RLock()
with some_rlock:
print "some_rlock is locked while this executes"
.. _threaded-imports:
Importing in threaded code
--------------------------
While the import machinery is thread-safe, there are two key restrictions on
threaded imports due to inherent limitations in the way that thread-safety is
provided:
* Firstly, other than in the main module, an import should not have the
side effect of spawning a new thread and then waiting for that thread in
any way. Failing to abide by this restriction can lead to a deadlock if
the spawned thread directly or indirectly attempts to import a module.
* Secondly, all import attempts must be completed before the interpreter
starts shutting itself down. This can be most easily achieved by only
performing imports from non-daemon threads created through the threading
module. Daemon threads and threads created directly with the thread
module will require some other form of synchronization to ensure they do
not attempt imports after system shutdown has commenced. Failure to
abide by this restriction will lead to intermittent exceptions and
crashes during interpreter shutdown (as the late imports attempt to
access machinery which is no longer in a valid state).
PK
%�\�Wm�e �e " html/_sources/library/time.rst.txtnu �[���
:mod:`time` --- Time access and conversions
===========================================
.. module:: time
:synopsis: Time access and conversions.
This module provides various time-related functions. For related
functionality, see also the :mod:`datetime` and :mod:`calendar` modules.
Although this module is always available,
not all functions are available on all platforms. Most of the functions
defined in this module call platform C library functions with the same name. It
may sometimes be helpful to consult the platform documentation, because the
semantics of these functions varies among platforms.
An explanation of some terminology and conventions is in order.
.. index:: single: epoch
* The :dfn:`epoch` is the point where the time starts. On January 1st of that
year, at 0 hours, the "time since the epoch" is zero. For Unix, the epoch is
1970. To find out what the epoch is, look at ``gmtime(0)``.
.. index:: single: Year 2038
* The functions in this module do not handle dates and times before the epoch or
far in the future. The cut-off point in the future is determined by the C
library; for Unix, it is typically in 2038.
.. index::
single: Year 2000
single: Y2K
.. _time-y2kissues:
* **Year 2000 (Y2K) issues**: Python depends on the platform's C library, which
generally doesn't have year 2000 issues, since all dates and times are
represented internally as seconds since the epoch. Functions accepting a
:class:`struct_time` (see below) generally require a 4-digit year. For backward
compatibility, 2-digit years are supported if the module variable
``accept2dyear`` is a non-zero integer; this variable is initialized to ``1``
unless the environment variable :envvar:`PYTHONY2K` is set to a non-empty
string, in which case it is initialized to ``0``. Thus, you can set
:envvar:`PYTHONY2K` to a non-empty string in the environment to require 4-digit
years for all year input. When 2-digit years are accepted, they are converted
according to the POSIX or X/Open standard: values 69-99 are mapped to 1969-1999,
and values 0--68 are mapped to 2000--2068. Values 100--1899 are always illegal.
.. index::
single: UTC
single: Coordinated Universal Time
single: Greenwich Mean Time
* UTC is Coordinated Universal Time (formerly known as Greenwich Mean Time, or
GMT). The acronym UTC is not a mistake but a compromise between English and
French.
.. index:: single: Daylight Saving Time
* DST is Daylight Saving Time, an adjustment of the timezone by (usually) one
hour during part of the year. DST rules are magic (determined by local law) and
can change from year to year. The C library has a table containing the local
rules (often it is read from a system file for flexibility) and is the only
source of True Wisdom in this respect.
* The precision of the various real-time functions may be less than suggested by
the units in which their value or argument is expressed. E.g. on most Unix
systems, the clock "ticks" only 50 or 100 times a second.
* On the other hand, the precision of :func:`.time` and :func:`sleep` is better
than their Unix equivalents: times are expressed as floating point numbers,
:func:`.time` returns the most accurate time available (using Unix
:c:func:`gettimeofday` where available), and :func:`sleep` will accept a time
with a nonzero fraction (Unix :c:func:`select` is used to implement this, where
available).
* The time value as returned by :func:`gmtime`, :func:`localtime`, and
:func:`strptime`, and accepted by :func:`asctime`, :func:`mktime` and
:func:`strftime`, may be considered as a sequence of 9 integers. The return
values of :func:`gmtime`, :func:`localtime`, and :func:`strptime` also offer
attribute names for individual fields.
See :class:`struct_time` for a description of these objects.
.. versionchanged:: 2.2
The time value sequence was changed from a tuple to a :class:`struct_time`, with
the addition of attribute names for the fields.
* Use the following functions to convert between time representations:
+-------------------------+-------------------------+-------------------------+
| From | To | Use |
+=========================+=========================+=========================+
| seconds since the epoch | :class:`struct_time` in | :func:`gmtime` |
| | UTC | |
+-------------------------+-------------------------+-------------------------+
| seconds since the epoch | :class:`struct_time` in | :func:`localtime` |
| | local time | |
+-------------------------+-------------------------+-------------------------+
| :class:`struct_time` in | seconds since the epoch | :func:`calendar.timegm` |
| UTC | | |
+-------------------------+-------------------------+-------------------------+
| :class:`struct_time` in | seconds since the epoch | :func:`mktime` |
| local time | | |
+-------------------------+-------------------------+-------------------------+
The module defines the following functions and data items:
.. data:: accept2dyear
Boolean value indicating whether two-digit year values will be accepted. This
is true by default, but will be set to false if the environment variable
:envvar:`PYTHONY2K` has been set to a non-empty string. It may also be modified
at run time.
.. data:: altzone
The offset of the local DST timezone, in seconds west of UTC, if one is defined.
This is negative if the local DST timezone is east of UTC (as in Western Europe,
including the UK). Only use this if ``daylight`` is nonzero.
.. function:: asctime([t])
Convert a tuple or :class:`struct_time` representing a time as returned by
:func:`gmtime` or :func:`localtime` to a 24-character string of the following
form: ``'Sun Jun 20 23:21:05 1993'``. If *t* is not provided, the current time
as returned by :func:`localtime` is used. Locale information is not used by
:func:`asctime`.
.. note::
Unlike the C function of the same name, there is no trailing newline.
.. versionchanged:: 2.1
Allowed *t* to be omitted.
.. function:: clock()
.. index::
single: CPU time
single: processor time
single: benchmarking
On Unix, return the current processor time as a floating point number expressed
in seconds. The precision, and in fact the very definition of the meaning of
"processor time", depends on that of the C function of the same name, but in any
case, this is the function to use for benchmarking Python or timing algorithms.
On Windows, this function returns wall-clock seconds elapsed since the first
call to this function, as a floating point number, based on the Win32 function
:c:func:`QueryPerformanceCounter`. The resolution is typically better than one
microsecond.
.. function:: ctime([secs])
Convert a time expressed in seconds since the epoch to a string representing
local time. If *secs* is not provided or :const:`None`, the current time as
returned by :func:`.time` is used. ``ctime(secs)`` is equivalent to
``asctime(localtime(secs))``. Locale information is not used by :func:`ctime`.
.. versionchanged:: 2.1
Allowed *secs* to be omitted.
.. versionchanged:: 2.4
If *secs* is :const:`None`, the current time is used.
.. data:: daylight
Nonzero if a DST timezone is defined.
.. function:: gmtime([secs])
Convert a time expressed in seconds since the epoch to a :class:`struct_time` in
UTC in which the dst flag is always zero. If *secs* is not provided or
:const:`None`, the current time as returned by :func:`.time` is used. Fractions
of a second are ignored. See above for a description of the
:class:`struct_time` object. See :func:`calendar.timegm` for the inverse of this
function.
.. versionchanged:: 2.1
Allowed *secs* to be omitted.
.. versionchanged:: 2.4
If *secs* is :const:`None`, the current time is used.
.. function:: localtime([secs])
Like :func:`gmtime` but converts to local time. If *secs* is not provided or
:const:`None`, the current time as returned by :func:`.time` is used. The dst
flag is set to ``1`` when DST applies to the given time.
.. versionchanged:: 2.1
Allowed *secs* to be omitted.
.. versionchanged:: 2.4
If *secs* is :const:`None`, the current time is used.
.. function:: mktime(t)
This is the inverse function of :func:`localtime`. Its argument is the
:class:`struct_time` or full 9-tuple (since the dst flag is needed; use ``-1``
as the dst flag if it is unknown) which expresses the time in *local* time, not
UTC. It returns a floating point number, for compatibility with :func:`.time`.
If the input value cannot be represented as a valid time, either
:exc:`OverflowError` or :exc:`ValueError` will be raised (which depends on
whether the invalid value is caught by Python or the underlying C libraries).
The earliest date for which it can generate a time is platform-dependent.
.. function:: sleep(secs)
Suspend execution of the current thread for the given number of seconds.
The argument may be a floating point number to indicate a more precise sleep
time. The actual suspension time may be less than that requested because any
caught signal will terminate the :func:`sleep` following execution of that
signal's catching routine. Also, the suspension time may be longer than
requested by an arbitrary amount because of the scheduling of other activity
in the system.
.. function:: strftime(format[, t])
Convert a tuple or :class:`struct_time` representing a time as returned by
:func:`gmtime` or :func:`localtime` to a string as specified by the *format*
argument. If *t* is not provided, the current time as returned by
:func:`localtime` is used. *format* must be a string. :exc:`ValueError` is
raised if any field in *t* is outside of the allowed range. :func:`strftime`
returns a locale dependent byte string; the result may be converted to unicode
by doing ``strftime(<myformat>).decode(locale.getlocale()[1])``.
.. versionchanged:: 2.1
Allowed *t* to be omitted.
.. versionchanged:: 2.4
:exc:`ValueError` raised if a field in *t* is out of range.
.. versionchanged:: 2.5
0 is now a legal argument for any position in the time tuple; if it is normally
illegal the value is forced to a correct one.
The following directives can be embedded in the *format* string. They are shown
without the optional field width and precision specification, and are replaced
by the indicated characters in the :func:`strftime` result:
+-----------+--------------------------------+-------+
| Directive | Meaning | Notes |
+===========+================================+=======+
| ``%a`` | Locale's abbreviated weekday | |
| | name. | |
+-----------+--------------------------------+-------+
| ``%A`` | Locale's full weekday name. | |
+-----------+--------------------------------+-------+
| ``%b`` | Locale's abbreviated month | |
| | name. | |
+-----------+--------------------------------+-------+
| ``%B`` | Locale's full month name. | |
+-----------+--------------------------------+-------+
| ``%c`` | Locale's appropriate date and | |
| | time representation. | |
+-----------+--------------------------------+-------+
| ``%d`` | Day of the month as a decimal | |
| | number [01,31]. | |
+-----------+--------------------------------+-------+
| ``%H`` | Hour (24-hour clock) as a | |
| | decimal number [00,23]. | |
+-----------+--------------------------------+-------+
| ``%I`` | Hour (12-hour clock) as a | |
| | decimal number [01,12]. | |
+-----------+--------------------------------+-------+
| ``%j`` | Day of the year as a decimal | |
| | number [001,366]. | |
+-----------+--------------------------------+-------+
| ``%m`` | Month as a decimal number | |
| | [01,12]. | |
+-----------+--------------------------------+-------+
| ``%M`` | Minute as a decimal number | |
| | [00,59]. | |
+-----------+--------------------------------+-------+
| ``%p`` | Locale's equivalent of either | \(1) |
| | AM or PM. | |
+-----------+--------------------------------+-------+
| ``%S`` | Second as a decimal number | \(2) |
| | [00,61]. | |
+-----------+--------------------------------+-------+
| ``%U`` | Week number of the year | \(3) |
| | (Sunday as the first day of | |
| | the week) as a decimal number | |
| | [00,53]. All days in a new | |
| | year preceding the first | |
| | Sunday are considered to be in | |
| | week 0. | |
+-----------+--------------------------------+-------+
| ``%w`` | Weekday as a decimal number | |
| | [0(Sunday),6]. | |
+-----------+--------------------------------+-------+
| ``%W`` | Week number of the year | \(3) |
| | (Monday as the first day of | |
| | the week) as a decimal number | |
| | [00,53]. All days in a new | |
| | year preceding the first | |
| | Monday are considered to be in | |
| | week 0. | |
+-----------+--------------------------------+-------+
| ``%x`` | Locale's appropriate date | |
| | representation. | |
+-----------+--------------------------------+-------+
| ``%X`` | Locale's appropriate time | |
| | representation. | |
+-----------+--------------------------------+-------+
| ``%y`` | Year without century as a | |
| | decimal number [00,99]. | |
+-----------+--------------------------------+-------+
| ``%Y`` | Year with century as a decimal | |
| | number. | |
+-----------+--------------------------------+-------+
| ``%Z`` | Time zone name (no characters | |
| | if no time zone exists). | |
+-----------+--------------------------------+-------+
| ``%%`` | A literal ``'%'`` character. | |
+-----------+--------------------------------+-------+
Notes:
(1)
When used with the :func:`strptime` function, the ``%p`` directive only affects
the output hour field if the ``%I`` directive is used to parse the hour.
(2)
The range really is ``0`` to ``61``; this accounts for leap seconds and the
(very rare) double leap seconds.
(3)
When used with the :func:`strptime` function, ``%U`` and ``%W`` are only used in
calculations when the day of the week and the year are specified.
Here is an example, a format for dates compatible with that specified in the
:rfc:`2822` Internet email standard. [#]_ ::
>>> from time import gmtime, strftime
>>> strftime("%a, %d %b %Y %H:%M:%S +0000", gmtime())
'Thu, 28 Jun 2001 14:17:15 +0000'
Additional directives may be supported on certain platforms, but only the
ones listed here have a meaning standardized by ANSI C. To see the full set
of format codes supported on your platform, consult the :manpage:`strftime(3)`
documentation.
On some platforms, an optional field width and precision specification can
immediately follow the initial ``'%'`` of a directive in the following order;
this is also not portable. The field width is normally 2 except for ``%j`` where
it is 3.
.. function:: strptime(string[, format])
Parse a string representing a time according to a format. The return value is
a :class:`struct_time` as returned by :func:`gmtime` or :func:`localtime`.
The *format* parameter uses the same directives as those used by
:func:`strftime`; it defaults to ``"%a %b %d %H:%M:%S %Y"`` which matches the
formatting returned by :func:`ctime`. If *string* cannot be parsed according to
*format*, or if it has excess data after parsing, :exc:`ValueError` is raised.
The default values used to fill in any missing data when more accurate values
cannot be inferred are ``(1900, 1, 1, 0, 0, 0, 0, 1, -1)``.
For example:
>>> import time
>>> time.strptime("30 Nov 00", "%d %b %y") # doctest: +NORMALIZE_WHITESPACE
time.struct_time(tm_year=2000, tm_mon=11, tm_mday=30, tm_hour=0, tm_min=0,
tm_sec=0, tm_wday=3, tm_yday=335, tm_isdst=-1)
Support for the ``%Z`` directive is based on the values contained in ``tzname``
and whether ``daylight`` is true. Because of this, it is platform-specific
except for recognizing UTC and GMT which are always known (and are considered to
be non-daylight savings timezones).
Only the directives specified in the documentation are supported. Because
``strftime()`` is implemented per platform it can sometimes offer more
directives than those listed. But ``strptime()`` is independent of any platform
and thus does not necessarily support all directives available that are not
documented as supported.
.. class:: struct_time
The type of the time value sequence returned by :func:`gmtime`,
:func:`localtime`, and :func:`strptime`. It is an object with a :term:`named
tuple` interface: values can be accessed by index and by attribute name. The
following values are present:
+-------+-------------------+---------------------------------+
| Index | Attribute | Values |
+=======+===================+=================================+
| 0 | :attr:`tm_year` | (for example, 1993) |
+-------+-------------------+---------------------------------+
| 1 | :attr:`tm_mon` | range [1, 12] |
+-------+-------------------+---------------------------------+
| 2 | :attr:`tm_mday` | range [1, 31] |
+-------+-------------------+---------------------------------+
| 3 | :attr:`tm_hour` | range [0, 23] |
+-------+-------------------+---------------------------------+
| 4 | :attr:`tm_min` | range [0, 59] |
+-------+-------------------+---------------------------------+
| 5 | :attr:`tm_sec` | range [0, 61]; see **(2)** in |
| | | :func:`strftime` description |
+-------+-------------------+---------------------------------+
| 6 | :attr:`tm_wday` | range [0, 6], Monday is 0 |
+-------+-------------------+---------------------------------+
| 7 | :attr:`tm_yday` | range [1, 366] |
+-------+-------------------+---------------------------------+
| 8 | :attr:`tm_isdst` | 0, 1 or -1; see below |
+-------+-------------------+---------------------------------+
.. versionadded:: 2.2
Note that unlike the C structure, the month value is a range of [1, 12], not
[0, 11]. A year value will be handled as described under :ref:`Year 2000
(Y2K) issues <time-y2kissues>` above.
In calls to :func:`mktime`, :attr:`tm_isdst` may be set to 1 when daylight
savings time is in effect, and 0 when it is not. A value of -1 indicates
that this is not known, and will usually result in the correct state being
filled in.
When a tuple with an incorrect length is passed to a function expecting a
:class:`struct_time`, or having elements of the wrong type, a
:exc:`TypeError` is raised.
.. function:: time()
Return the time in seconds since the epoch as a floating point number.
Note that even though the time is always returned as a floating point
number, not all systems provide time with a better precision than 1 second.
While this function normally returns non-decreasing values, it can return a
lower value than a previous call if the system clock has been set back between
the two calls.
.. data:: timezone
The offset of the local (non-DST) timezone, in seconds west of UTC (negative in
most of Western Europe, positive in the US, zero in the UK).
.. data:: tzname
A tuple of two strings: the first is the name of the local non-DST timezone, the
second is the name of the local DST timezone. If no DST timezone is defined,
the second string should not be used.
.. function:: tzset()
Reset the time conversion rules used by the library routines. The environment
variable :envvar:`TZ` specifies how this is done. It will also set the variables
``tzname`` (from the :envvar:`TZ` environment variable), ``timezone`` (non-DST
seconds West of UTC), ``altzone`` (DST seconds west of UTC) and ``daylight``
(to 0 if this timezone does not have any daylight saving time rules, or to
nonzero if there is a time, past, present or future when daylight saving time
applies).
.. versionadded:: 2.3
Availability: Unix.
.. note::
Although in many cases, changing the :envvar:`TZ` environment variable may
affect the output of functions like :func:`localtime` without calling
:func:`tzset`, this behavior should not be relied on.
The :envvar:`TZ` environment variable should contain no whitespace.
The standard format of the :envvar:`TZ` environment variable is (whitespace
added for clarity)::
std offset [dst [offset [,start[/time], end[/time]]]]
Where the components are:
``std`` and ``dst``
Three or more alphanumerics giving the timezone abbreviations. These will be
propagated into time.tzname
``offset``
The offset has the form: ``± hh[:mm[:ss]]``. This indicates the value
added the local time to arrive at UTC. If preceded by a '-', the timezone
is east of the Prime Meridian; otherwise, it is west. If no offset follows
dst, summer time is assumed to be one hour ahead of standard time.
``start[/time], end[/time]``
Indicates when to change to and back from DST. The format of the
start and end dates are one of the following:
:samp:`J{n}`
The Julian day *n* (1 <= *n* <= 365). Leap days are not counted, so in
all years February 28 is day 59 and March 1 is day 60.
:samp:`{n}`
The zero-based Julian day (0 <= *n* <= 365). Leap days are counted, and
it is possible to refer to February 29.
:samp:`M{m}.{n}.{d}`
The *d*'th day (0 <= *d* <= 6) or week *n* of month *m* of the year (1
<= *n* <= 5, 1 <= *m* <= 12, where week 5 means "the last *d* day in
month *m*" which may occur in either the fourth or the fifth
week). Week 1 is the first week in which the *d*'th day occurs. Day
zero is Sunday.
``time`` has the same format as ``offset`` except that no leading sign
('-' or '+') is allowed. The default, if time is not given, is 02:00:00.
::
>>> os.environ['TZ'] = 'EST+05EDT,M4.1.0,M10.5.0'
>>> time.tzset()
>>> time.strftime('%X %x %Z')
'02:07:36 05/08/03 EDT'
>>> os.environ['TZ'] = 'AEST-10AEDT-11,M10.5.0,M3.5.0'
>>> time.tzset()
>>> time.strftime('%X %x %Z')
'16:08:12 05/08/03 AEST'
On many Unix systems (including \*BSD, Linux, Solaris, and Darwin), it is more
convenient to use the system's zoneinfo (:manpage:`tzfile(5)`) database to
specify the timezone rules. To do this, set the :envvar:`TZ` environment
variable to the path of the required timezone datafile, relative to the root of
the systems 'zoneinfo' timezone database, usually located at
:file:`/usr/share/zoneinfo`. For example, ``'US/Eastern'``,
``'Australia/Melbourne'``, ``'Egypt'`` or ``'Europe/Amsterdam'``. ::
>>> os.environ['TZ'] = 'US/Eastern'
>>> time.tzset()
>>> time.tzname
('EST', 'EDT')
>>> os.environ['TZ'] = 'Egypt'
>>> time.tzset()
>>> time.tzname
('EET', 'EEST')
.. seealso::
Module :mod:`datetime`
More object-oriented interface to dates and times.
Module :mod:`locale`
Internationalization services. The locale setting affects the interpretation
of many format specifiers in :func:`strftime` and :func:`strptime`.
Module :mod:`calendar`
General calendar-related functions. :func:`~calendar.timegm` is the
inverse of :func:`gmtime` from this module.
.. rubric:: Footnotes
.. [#] The use of ``%Z`` is now deprecated, but the ``%z`` escape that expands to the
preferred hour/minute offset is not supported by all ANSI C libraries. Also, a
strict reading of the original 1982 :rfc:`822` standard calls for a two-digit
year (%y rather than %Y), but practice moved to 4-digit years long before the
year 2000. After that, :rfc:`822` became obsolete and the 4-digit year has
been first recommended by :rfc:`1123` and then mandated by :rfc:`2822`.
PK
%�\� ��N- N- $ html/_sources/library/timeit.rst.txtnu �[��� :mod:`timeit` --- Measure execution time of small code snippets
===============================================================
.. module:: timeit
:synopsis: Measure the execution time of small code snippets.
.. versionadded:: 2.3
.. index::
single: Benchmarking
single: Performance
**Source code:** :source:`Lib/timeit.py`
--------------
This module provides a simple way to time small bits of Python code. It has both
a :ref:`timeit-command-line-interface` as well as a :ref:`callable <python-interface>`
one. It avoids a number of common traps for measuring execution times.
See also Tim Peters' introduction to the "Algorithms" chapter in the *Python
Cookbook*, published by O'Reilly.
Basic Examples
--------------
The following example shows how the :ref:`timeit-command-line-interface`
can be used to compare three different expressions:
.. code-block:: sh
$ python -m timeit '"-".join(str(n) for n in range(100))'
10000 loops, best of 3: 40.3 usec per loop
$ python -m timeit '"-".join([str(n) for n in range(100)])'
10000 loops, best of 3: 33.4 usec per loop
$ python -m timeit '"-".join(map(str, range(100)))'
10000 loops, best of 3: 25.2 usec per loop
This can be achieved from the :ref:`python-interface` with::
>>> import timeit
>>> timeit.timeit('"-".join(str(n) for n in range(100))', number=10000)
0.8187260627746582
>>> timeit.timeit('"-".join([str(n) for n in range(100)])', number=10000)
0.7288308143615723
>>> timeit.timeit('"-".join(map(str, range(100)))', number=10000)
0.5858950614929199
Note however that :mod:`timeit` will automatically determine the number of
repetitions only when the command-line interface is used. In the
:ref:`timeit-examples` section you can find more advanced examples.
.. _python-interface:
Python Interface
----------------
The module defines three convenience functions and a public class:
.. function:: timeit(stmt='pass', setup='pass', timer=<default timer>, number=1000000)
Create a :class:`Timer` instance with the given statement, *setup* code and
*timer* function and run its :meth:`.timeit` method with *number* executions.
.. versionadded:: 2.6
.. function:: repeat(stmt='pass', setup='pass', timer=<default timer>, repeat=3, number=1000000)
Create a :class:`Timer` instance with the given statement, *setup* code and
*timer* function and run its :meth:`.repeat` method with the given *repeat*
count and *number* executions.
.. versionadded:: 2.6
.. function:: default_timer()
Define a default timer, in a platform-specific manner. On Windows,
:func:`time.clock` has microsecond granularity, but :func:`time.time`'s
granularity is 1/60th of a second. On Unix, :func:`time.clock` has 1/100th of
a second granularity, and :func:`time.time` is much more precise. On either
platform, :func:`default_timer` measures wall clock time, not the CPU
time. This means that other processes running on the same computer may
interfere with the timing.
.. class:: Timer(stmt='pass', setup='pass', timer=<timer function>)
Class for timing execution speed of small code snippets.
The constructor takes a statement to be timed, an additional statement used
for setup, and a timer function. Both statements default to ``'pass'``;
the timer function is platform-dependent (see the module doc string).
*stmt* and *setup* may also contain multiple statements separated by ``;``
or newlines, as long as they don't contain multi-line string literals.
To measure the execution time of the first statement, use the :meth:`.timeit`
method. The :meth:`.repeat` method is a convenience to call :meth:`.timeit`
multiple times and return a list of results.
.. versionchanged:: 2.6
The *stmt* and *setup* parameters can now also take objects that are
callable without arguments. This will embed calls to them in a timer
function that will then be executed by :meth:`.timeit`. Note that the
timing overhead is a little larger in this case because of the extra
function calls.
.. method:: Timer.timeit(number=1000000)
Time *number* executions of the main statement. This executes the setup
statement once, and then returns the time it takes to execute the main
statement a number of times, measured in seconds as a float.
The argument is the number of times through the loop, defaulting to one
million. The main statement, the setup statement and the timer function
to be used are passed to the constructor.
.. note::
By default, :meth:`.timeit` temporarily turns off :term:`garbage
collection` during the timing. The advantage of this approach is that
it makes independent timings more comparable. This disadvantage is
that GC may be an important component of the performance of the
function being measured. If so, GC can be re-enabled as the first
statement in the *setup* string. For example::
timeit.Timer('for i in xrange(10): oct(i)', 'gc.enable()').timeit()
.. method:: Timer.repeat(repeat=3, number=1000000)
Call :meth:`.timeit` a few times.
This is a convenience function that calls the :meth:`.timeit` repeatedly,
returning a list of results. The first argument specifies how many times
to call :meth:`.timeit`. The second argument specifies the *number*
argument for :meth:`.timeit`.
.. note::
It's tempting to calculate mean and standard deviation from the result
vector and report these. However, this is not very useful.
In a typical case, the lowest value gives a lower bound for how fast
your machine can run the given code snippet; higher values in the
result vector are typically not caused by variability in Python's
speed, but by other processes interfering with your timing accuracy.
So the :func:`min` of the result is probably the only number you
should be interested in. After that, you should look at the entire
vector and apply common sense rather than statistics.
.. method:: Timer.print_exc(file=None)
Helper to print a traceback from the timed code.
Typical use::
t = Timer(...) # outside the try/except
try:
t.timeit(...) # or t.repeat(...)
except:
t.print_exc()
The advantage over the standard traceback is that source lines in the
compiled template will be displayed. The optional *file* argument directs
where the traceback is sent; it defaults to :data:`sys.stderr`.
.. _timeit-command-line-interface:
Command-Line Interface
----------------------
When called as a program from the command line, the following form is used::
python -m timeit [-n N] [-r N] [-s S] [-t] [-c] [-h] [statement ...]
Where the following options are understood:
.. program:: timeit
.. cmdoption:: -n N, --number=N
how many times to execute 'statement'
.. cmdoption:: -r N, --repeat=N
how many times to repeat the timer (default 3)
.. cmdoption:: -s S, --setup=S
statement to be executed once initially (default ``pass``)
.. cmdoption:: -t, --time
use :func:`time.time` (default on all platforms but Windows)
.. cmdoption:: -c, --clock
use :func:`time.clock` (default on Windows)
.. cmdoption:: -v, --verbose
print raw timing results; repeat for more digits precision
.. cmdoption:: -h, --help
print a short usage message and exit
A multi-line statement may be given by specifying each line as a separate
statement argument; indented lines are possible by enclosing an argument in
quotes and using leading spaces. Multiple :option:`-s` options are treated
similarly.
If :option:`-n` is not given, a suitable number of loops is calculated by trying
successive powers of 10 until the total time is at least 0.2 seconds.
:func:`default_timer` measurations can be affected by other programs running on
the same machine, so
the best thing to do when accurate timing is necessary is to repeat
the timing a few times and use the best time. The :option:`-r` option is good
for this; the default of 3 repetitions is probably enough in most cases. On
Unix, you can use :func:`time.clock` to measure CPU time.
.. note::
There is a certain baseline overhead associated with executing a pass statement.
The code here doesn't try to hide it, but you should be aware of it. The
baseline overhead can be measured by invoking the program without arguments, and
it might differ between Python versions. Also, to fairly compare older Python
versions to Python 2.3, you may want to use Python's :option:`!-O`
option (see :ref:`Optimizations <using-on-optimizations>`) for
the older versions to avoid timing ``SET_LINENO`` instructions.
.. _timeit-examples:
Examples
--------
It is possible to provide a setup statement that is executed only once at the beginning:
.. code-block:: sh
$ python -m timeit -s 'text = "sample string"; char = "g"' 'char in text'
10000000 loops, best of 3: 0.0877 usec per loop
$ python -m timeit -s 'text = "sample string"; char = "g"' 'text.find(char)'
1000000 loops, best of 3: 0.342 usec per loop
::
>>> import timeit
>>> timeit.timeit('char in text', setup='text = "sample string"; char = "g"')
0.41440500499993504
>>> timeit.timeit('text.find(char)', setup='text = "sample string"; char = "g"')
1.7246671520006203
The same can be done using the :class:`Timer` class and its methods::
>>> import timeit
>>> t = timeit.Timer('char in text', setup='text = "sample string"; char = "g"')
>>> t.timeit()
0.3955516149999312
>>> t.repeat()
[0.40193588800002544, 0.3960157959998014, 0.39594301399984033]
The following examples show how to time expressions that contain multiple lines.
Here we compare the cost of using :func:`hasattr` vs. :keyword:`try`/:keyword:`except`
to test for missing and present object attributes:
.. code-block:: sh
$ python -m timeit 'try:' ' str.__nonzero__' 'except AttributeError:' ' pass'
100000 loops, best of 3: 15.7 usec per loop
$ python -m timeit 'if hasattr(str, "__nonzero__"): pass'
100000 loops, best of 3: 4.26 usec per loop
$ python -m timeit 'try:' ' int.__nonzero__' 'except AttributeError:' ' pass'
1000000 loops, best of 3: 1.43 usec per loop
$ python -m timeit 'if hasattr(int, "__nonzero__"): pass'
100000 loops, best of 3: 2.23 usec per loop
::
>>> import timeit
>>> # attribute is missing
>>> s = """\
... try:
... str.__nonzero__
... except AttributeError:
... pass
... """
>>> timeit.timeit(stmt=s, number=100000)
0.9138244460009446
>>> s = "if hasattr(str, '__bool__'): pass"
>>> timeit.timeit(stmt=s, number=100000)
0.5829014980008651
>>>
>>> # attribute is present
>>> s = """\
... try:
... int.__nonzero__
... except AttributeError:
... pass
... """
>>> timeit.timeit(stmt=s, number=100000)
0.04215312199994514
>>> s = "if hasattr(int, '__bool__'): pass"
>>> timeit.timeit(stmt=s, number=100000)
0.08588060699912603
To give the :mod:`timeit` module access to functions you define, you can pass a
*setup* parameter which contains an import statement::
def test():
"""Stupid test function"""
L = []
for i in range(100):
L.append(i)
if __name__ == '__main__':
import timeit
print(timeit.timeit("test()", setup="from __main__ import test"))
PK
%�\���X �X ! html/_sources/library/tix.rst.txtnu �[��� :mod:`Tix` --- Extension widgets for Tk
=======================================
.. module:: Tix
:synopsis: Tk Extension Widgets for Tkinter
.. sectionauthor:: Mike Clarkson <mikeclarkson@users.sourceforge.net>
.. index:: single: Tix
The :mod:`Tix` (Tk Interface Extension) module provides an additional rich set
of widgets. Although the standard Tk library has many useful widgets, they are
far from complete. The :mod:`Tix` library provides most of the commonly needed
widgets that are missing from standard Tk: :class:`HList`, :class:`ComboBox`,
:class:`Control` (a.k.a. SpinBox) and an assortment of scrollable widgets.
:mod:`Tix` also includes many more widgets that are generally useful in a wide
range of applications: :class:`NoteBook`, :class:`FileEntry`,
:class:`PanedWindow`, etc; there are more than 40 of them.
With all these new widgets, you can introduce new interaction techniques into
applications, creating more useful and more intuitive user interfaces. You can
design your application by choosing the most appropriate widgets to match the
special needs of your application and users.
.. note::
:mod:`Tix` has been renamed to :mod:`tkinter.tix` in Python 3. The
:term:`2to3` tool will automatically adapt imports when converting your
sources to Python 3.
.. seealso::
`Tix Homepage <http://tix.sourceforge.net/>`_
The home page for :mod:`Tix`. This includes links to additional documentation
and downloads.
`Tix Man Pages <http://tix.sourceforge.net/dist/current/man/>`_
On-line version of the man pages and reference material.
`Tix Programming Guide <http://tix.sourceforge.net/dist/current/docs/tix-book/tix.book.html>`_
On-line version of the programmer's reference material.
`Tix Development Applications <http://tix.sourceforge.net/Tixapps/src/Tide.html>`_
Tix applications for development of Tix and Tkinter programs. Tide applications
work under Tk or Tkinter, and include :program:`TixInspect`, an inspector to
remotely modify and debug Tix/Tk/Tkinter applications.
Using Tix
---------
.. class:: Tix(screenName[, baseName[, className]])
Toplevel widget of Tix which represents mostly the main window of an
application. It has an associated Tcl interpreter.
Classes in the :mod:`Tix` module subclasses the classes in the :mod:`Tkinter`
module. The former imports the latter, so to use :mod:`Tix` with Tkinter, all
you need to do is to import one module. In general, you can just import
:mod:`Tix`, and replace the toplevel call to :class:`Tkinter.Tk` with
:class:`Tix.Tk`::
import Tix
from Tkconstants import *
root = Tix.Tk()
To use :mod:`Tix`, you must have the :mod:`Tix` widgets installed, usually
alongside your installation of the Tk widgets. To test your installation, try
the following::
import Tix
root = Tix.Tk()
root.tk.eval('package require Tix')
If this fails, you have a Tk installation problem which must be resolved before
proceeding. Use the environment variable :envvar:`TIX_LIBRARY` to point to the
installed :mod:`Tix` library directory, and make sure you have the dynamic
object library (:file:`tix8183.dll` or :file:`libtix8183.so`) in the same
directory that contains your Tk dynamic object library (:file:`tk8183.dll` or
:file:`libtk8183.so`). The directory with the dynamic object library should also
have a file called :file:`pkgIndex.tcl` (case sensitive), which contains the
line::
package ifneeded Tix 8.1 [list load "[file join $dir tix8183.dll]" Tix]
Tix Widgets
-----------
`Tix <http://tix.sourceforge.net/dist/current/man/html/TixCmd/TixIntro.htm>`_
introduces over 40 widget classes to the :mod:`Tkinter` repertoire. There is a
demo of all the :mod:`Tix` widgets in the :file:`Demo/tix` directory of the
standard distribution.
.. The Python sample code is still being added to Python, hence commented out
Basic Widgets
^^^^^^^^^^^^^
.. class:: Balloon()
A `Balloon
<http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixBalloon.htm>`_ that
pops up over a widget to provide help. When the user moves the cursor inside a
widget to which a Balloon widget has been bound, a small pop-up window with a
descriptive message will be shown on the screen.
.. Python Demo of:
.. \ulink{Balloon}{http://tix.sourceforge.net/dist/current/demos/samples/Balloon.tcl}
.. class:: ButtonBox()
The `ButtonBox
<http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixButtonBox.htm>`_
widget creates a box of buttons, such as is commonly used for ``Ok Cancel``.
.. Python Demo of:
.. \ulink{ButtonBox}{http://tix.sourceforge.net/dist/current/demos/samples/BtnBox.tcl}
.. class:: ComboBox()
The `ComboBox
<http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixComboBox.htm>`_
widget is similar to the combo box control in MS Windows. The user can select a
choice by either typing in the entry subwidget or selecting from the listbox
subwidget.
.. Python Demo of:
.. \ulink{ComboBox}{http://tix.sourceforge.net/dist/current/demos/samples/ComboBox.tcl}
.. class:: Control()
The `Control
<http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixControl.htm>`_
widget is also known as the :class:`SpinBox` widget. The user can adjust the
value by pressing the two arrow buttons or by entering the value directly into
the entry. The new value will be checked against the user-defined upper and
lower limits.
.. Python Demo of:
.. \ulink{Control}{http://tix.sourceforge.net/dist/current/demos/samples/Control.tcl}
.. class:: LabelEntry()
The `LabelEntry
<http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixLabelEntry.htm>`_
widget packages an entry widget and a label into one mega widget. It can
be used to simplify the creation of "entry-form" type of interface.
.. Python Demo of:
.. \ulink{LabelEntry}{http://tix.sourceforge.net/dist/current/demos/samples/LabEntry.tcl}
.. class:: LabelFrame()
The `LabelFrame
<http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixLabelFrame.htm>`_
widget packages a frame widget and a label into one mega widget. To create
widgets inside a LabelFrame widget, one creates the new widgets relative to the
:attr:`frame` subwidget and manage them inside the :attr:`frame` subwidget.
.. Python Demo of:
.. \ulink{LabelFrame}{http://tix.sourceforge.net/dist/current/demos/samples/LabFrame.tcl}
.. class:: Meter()
The `Meter
<http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixMeter.htm>`_ widget
can be used to show the progress of a background job which may take a long time
to execute.
.. Python Demo of:
.. \ulink{Meter}{http://tix.sourceforge.net/dist/current/demos/samples/Meter.tcl}
.. class:: OptionMenu()
The `OptionMenu
<http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixOptionMenu.htm>`_
creates a menu button of options.
.. Python Demo of:
.. \ulink{OptionMenu}{http://tix.sourceforge.net/dist/current/demos/samples/OptMenu.tcl}
.. class:: PopupMenu()
The `PopupMenu
<http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixPopupMenu.htm>`_
widget can be used as a replacement of the ``tk_popup`` command. The advantage
of the :mod:`Tix` :class:`PopupMenu` widget is it requires less application code
to manipulate.
.. Python Demo of:
.. \ulink{PopupMenu}{http://tix.sourceforge.net/dist/current/demos/samples/PopMenu.tcl}
.. class:: Select()
The `Select
<http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixSelect.htm>`_ widget
is a container of button subwidgets. It can be used to provide radio-box or
check-box style of selection options for the user.
.. Python Demo of:
.. \ulink{Select}{http://tix.sourceforge.net/dist/current/demos/samples/Select.tcl}
.. class:: StdButtonBox()
The `StdButtonBox
<http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixStdButtonBox.htm>`_
widget is a group of standard buttons for Motif-like dialog boxes.
.. Python Demo of:
.. \ulink{StdButtonBox}{http://tix.sourceforge.net/dist/current/demos/samples/StdBBox.tcl}
File Selectors
^^^^^^^^^^^^^^
.. class:: DirList()
The `DirList
<http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirList.htm>`_
widget displays a list view of a directory, its previous directories and its
sub-directories. The user can choose one of the directories displayed in the
list or change to another directory.
.. Python Demo of:
.. \ulink{DirList}{http://tix.sourceforge.net/dist/current/demos/samples/DirList.tcl}
.. class:: DirTree()
The `DirTree
<http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirTree.htm>`_
widget displays a tree view of a directory, its previous directories and its
sub-directories. The user can choose one of the directories displayed in the
list or change to another directory.
.. Python Demo of:
.. \ulink{DirTree}{http://tix.sourceforge.net/dist/current/demos/samples/DirTree.tcl}
.. class:: DirSelectDialog()
The `DirSelectDialog
<http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixDirSelectDialog.htm>`_
widget presents the directories in the file system in a dialog window. The user
can use this dialog window to navigate through the file system to select the
desired directory.
.. Python Demo of:
.. \ulink{DirSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/DirDlg.tcl}
.. class:: DirSelectBox()
The :class:`DirSelectBox` is similar to the standard Motif(TM)
directory-selection box. It is generally used for the user to choose a
directory. DirSelectBox stores the directories mostly recently selected into
a ComboBox widget so that they can be quickly selected again.
.. class:: ExFileSelectBox()
The `ExFileSelectBox
<http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixExFileSelectBox.htm>`_
widget is usually embedded in a tixExFileSelectDialog widget. It provides a
convenient method for the user to select files. The style of the
:class:`ExFileSelectBox` widget is very similar to the standard file dialog on
MS Windows 3.1.
.. Python Demo of:
.. \ulink{ExFileSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/EFileDlg.tcl}
.. class:: FileSelectBox()
The `FileSelectBox
<http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixFileSelectBox.htm>`_
is similar to the standard Motif(TM) file-selection box. It is generally used
for the user to choose a file. FileSelectBox stores the files mostly recently
selected into a :class:`ComboBox` widget so that they can be quickly selected
again.
.. Python Demo of:
.. \ulink{FileSelectDialog}{http://tix.sourceforge.net/dist/current/demos/samples/FileDlg.tcl}
.. class:: FileEntry()
The `FileEntry
<http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixFileEntry.htm>`_
widget can be used to input a filename. The user can type in the filename
manually. Alternatively, the user can press the button widget that sits next to
the entry, which will bring up a file selection dialog.
.. Python Demo of:
.. \ulink{FileEntry}{http://tix.sourceforge.net/dist/current/demos/samples/FileEnt.tcl}
Hierarchical ListBox
^^^^^^^^^^^^^^^^^^^^
.. class:: HList()
The `HList
<http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixHList.htm>`_ widget
can be used to display any data that have a hierarchical structure, for example,
file system directory trees. The list entries are indented and connected by
branch lines according to their places in the hierarchy.
.. Python Demo of:
.. \ulink{HList}{http://tix.sourceforge.net/dist/current/demos/samples/HList1.tcl}
.. class:: CheckList()
The `CheckList
<http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixCheckList.htm>`_
widget displays a list of items to be selected by the user. CheckList acts
similarly to the Tk checkbutton or radiobutton widgets, except it is capable of
handling many more items than checkbuttons or radiobuttons.
.. Python Demo of:
.. \ulink{ CheckList}{http://tix.sourceforge.net/dist/current/demos/samples/ChkList.tcl}
.. Python Demo of:
.. \ulink{ScrolledHList (1)}{http://tix.sourceforge.net/dist/current/demos/samples/SHList.tcl}
.. Python Demo of:
.. \ulink{ScrolledHList (2)}{http://tix.sourceforge.net/dist/current/demos/samples/SHList2.tcl}
.. class:: Tree()
The `Tree
<http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixTree.htm>`_ widget
can be used to display hierarchical data in a tree form. The user can adjust the
view of the tree by opening or closing parts of the tree.
.. Python Demo of:
.. \ulink{Tree}{http://tix.sourceforge.net/dist/current/demos/samples/Tree.tcl}
.. Python Demo of:
.. \ulink{Tree (Dynamic)}{http://tix.sourceforge.net/dist/current/demos/samples/DynTree.tcl}
Tabular ListBox
^^^^^^^^^^^^^^^
.. class:: TList()
The `TList
<http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixTList.htm>`_ widget
can be used to display data in a tabular format. The list entries of a
:class:`TList` widget are similar to the entries in the Tk listbox widget. The
main differences are (1) the :class:`TList` widget can display the list entries
in a two dimensional format and (2) you can use graphical images as well as
multiple colors and fonts for the list entries.
.. Python Demo of:
.. \ulink{ScrolledTList (1)}{http://tix.sourceforge.net/dist/current/demos/samples/STList1.tcl}
.. Python Demo of:
.. \ulink{ScrolledTList (2)}{http://tix.sourceforge.net/dist/current/demos/samples/STList2.tcl}
.. Grid has yet to be added to Python
.. \subsubsection{Grid Widget}
.. Python Demo of:
.. \ulink{Simple Grid}{http://tix.sourceforge.net/dist/current/demos/samples/SGrid0.tcl}
.. Python Demo of:
.. \ulink{ScrolledGrid}{http://tix.sourceforge.net/dist/current/demos/samples/SGrid1.tcl}
.. Python Demo of:
.. \ulink{Editable Grid}{http://tix.sourceforge.net/dist/current/demos/samples/EditGrid.tcl}
Manager Widgets
^^^^^^^^^^^^^^^
.. class:: PanedWindow()
The `PanedWindow
<http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixPanedWindow.htm>`_
widget allows the user to interactively manipulate the sizes of several panes.
The panes can be arranged either vertically or horizontally. The user changes
the sizes of the panes by dragging the resize handle between two panes.
.. Python Demo of:
.. \ulink{PanedWindow}{http://tix.sourceforge.net/dist/current/demos/samples/PanedWin.tcl}
.. class:: ListNoteBook()
The `ListNoteBook
<http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixListNoteBook.htm>`_
widget is very similar to the :class:`TixNoteBook` widget: it can be used to
display many windows in a limited space using a notebook metaphor. The notebook
is divided into a stack of pages (windows). At one time only one of these pages
can be shown. The user can navigate through these pages by choosing the name of
the desired page in the :attr:`hlist` subwidget.
.. Python Demo of:
.. \ulink{ListNoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/ListNBK.tcl}
.. class:: NoteBook()
The `NoteBook
<http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixNoteBook.htm>`_
widget can be used to display many windows in a limited space using a notebook
metaphor. The notebook is divided into a stack of pages. At one time only one of
these pages can be shown. The user can navigate through these pages by choosing
the visual "tabs" at the top of the NoteBook widget.
.. Python Demo of:
.. \ulink{NoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/NoteBook.tcl}
.. \subsubsection{Scrolled Widgets}
.. Python Demo of:
.. \ulink{ScrolledListBox}{http://tix.sourceforge.net/dist/current/demos/samples/SListBox.tcl}
.. Python Demo of:
.. \ulink{ScrolledText}{http://tix.sourceforge.net/dist/current/demos/samples/SText.tcl}
.. Python Demo of:
.. \ulink{ScrolledWindow}{http://tix.sourceforge.net/dist/current/demos/samples/SWindow.tcl}
.. Python Demo of:
.. \ulink{Canvas Object View}{http://tix.sourceforge.net/dist/current/demos/samples/CObjView.tcl}
Image Types
^^^^^^^^^^^
The :mod:`Tix` module adds:
* `pixmap <http://tix.sourceforge.net/dist/current/man/html/TixCmd/pixmap.htm>`_
capabilities to all :mod:`Tix` and :mod:`Tkinter` widgets to create color images
from XPM files.
.. Python Demo of:
.. \ulink{XPM Image In Button}{http://tix.sourceforge.net/dist/current/demos/samples/Xpm.tcl}
.. Python Demo of:
.. \ulink{XPM Image In Menu}{http://tix.sourceforge.net/dist/current/demos/samples/Xpm1.tcl}
* `Compound
<http://tix.sourceforge.net/dist/current/man/html/TixCmd/compound.htm>`_ image
types can be used to create images that consists of multiple horizontal lines;
each line is composed of a series of items (texts, bitmaps, images or spaces)
arranged from left to right. For example, a compound image can be used to
display a bitmap and a text string simultaneously in a Tk :class:`Button`
widget.
.. Python Demo of:
.. \ulink{Compound Image In Buttons}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg.tcl}
.. Python Demo of:
.. \ulink{Compound Image In NoteBook}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg2.tcl}
.. Python Demo of:
.. \ulink{Compound Image Notebook Color Tabs}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg4.tcl}
.. Python Demo of:
.. \ulink{Compound Image Icons}{http://tix.sourceforge.net/dist/current/demos/samples/CmpImg3.tcl}
Miscellaneous Widgets
^^^^^^^^^^^^^^^^^^^^^
.. class:: InputOnly()
The `InputOnly
<http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixInputOnly.htm>`_
widgets are to accept inputs from the user, which can be done with the ``bind``
command (Unix only).
Form Geometry Manager
^^^^^^^^^^^^^^^^^^^^^
In addition, :mod:`Tix` augments :mod:`Tkinter` by providing:
.. class:: Form()
The `Form
<http://tix.sourceforge.net/dist/current/man/html/TixCmd/tixForm.htm>`_ geometry
manager based on attachment rules for all Tk widgets.
Tix Commands
------------
.. class:: tixCommand()
The `tix commands
<http://tix.sourceforge.net/dist/current/man/html/TixCmd/tix.htm>`_ provide
access to miscellaneous elements of :mod:`Tix`'s internal state and the
:mod:`Tix` application context. Most of the information manipulated by these
methods pertains to the application as a whole, or to a screen or display,
rather than to a particular window.
To view the current settings, the common usage is::
import Tix
root = Tix.Tk()
print root.tix_configure()
.. method:: tixCommand.tix_configure(cnf=None **kw)
Query or modify the configuration options of the Tix application context. If no
option is specified, returns a dictionary all of the available options. If
option is specified with no value, then the method returns a list describing the
one named option (this list will be identical to the corresponding sublist of
the value returned if no option is specified). If one or more option-value
pairs are specified, then the method modifies the given option(s) to have the
given value(s); in this case the method returns an empty string. Option may be
any of the configuration options.
.. method:: tixCommand.tix_cget(option)
Returns the current value of the configuration option given by *option*. Option
may be any of the configuration options.
.. method:: tixCommand.tix_getbitmap(name)
Locates a bitmap file of the name ``name.xpm`` or ``name`` in one of the bitmap
directories (see the :meth:`tix_addbitmapdir` method). By using
:meth:`tix_getbitmap`, you can avoid hard coding the pathnames of the bitmap
files in your application. When successful, it returns the complete pathname of
the bitmap file, prefixed with the character ``@``. The returned value can be
used to configure the ``bitmap`` option of the Tk and Tix widgets.
.. method:: tixCommand.tix_addbitmapdir(directory)
Tix maintains a list of directories under which the :meth:`tix_getimage` and
:meth:`tix_getbitmap` methods will search for image files. The standard bitmap
directory is :file:`$TIX_LIBRARY/bitmaps`. The :meth:`tix_addbitmapdir` method
adds *directory* into this list. By using this method, the image files of an
applications can also be located using the :meth:`tix_getimage` or
:meth:`tix_getbitmap` method.
.. method:: tixCommand.tix_filedialog([dlgclass])
Returns the file selection dialog that may be shared among different calls from
this application. This method will create a file selection dialog widget when
it is called the first time. This dialog will be returned by all subsequent
calls to :meth:`tix_filedialog`. An optional dlgclass parameter can be passed
as a string to specified what type of file selection dialog widget is desired.
Possible options are ``tix``, ``FileSelectDialog`` or ``tixExFileSelectDialog``.
.. method:: tixCommand.tix_getimage(self, name)
Locates an image file of the name :file:`name.xpm`, :file:`name.xbm` or
:file:`name.ppm` in one of the bitmap directories (see the
:meth:`tix_addbitmapdir` method above). If more than one file with the same name
(but different extensions) exist, then the image type is chosen according to the
depth of the X display: xbm images are chosen on monochrome displays and color
images are chosen on color displays. By using :meth:`tix_getimage`, you can
avoid hard coding the pathnames of the image files in your application. When
successful, this method returns the name of the newly created image, which can
be used to configure the ``image`` option of the Tk and Tix widgets.
.. method:: tixCommand.tix_option_get(name)
Gets the options maintained by the Tix scheme mechanism.
.. method:: tixCommand.tix_resetoptions(newScheme, newFontSet[, newScmPrio])
Resets the scheme and fontset of the Tix application to *newScheme* and
*newFontSet*, respectively. This affects only those widgets created after this
call. Therefore, it is best to call the resetoptions method before the creation
of any widgets in a Tix application.
The optional parameter *newScmPrio* can be given to reset the priority level of
the Tk options set by the Tix schemes.
Because of the way Tk handles the X option database, after Tix has been has
imported and inited, it is not possible to reset the color schemes and font sets
using the :meth:`tix_config` method. Instead, the :meth:`tix_resetoptions`
method must be used.
PK
%�\W��L L html/_sources/library/tk.rst.txtnu �[��� .. _tkinter:
*********************************
Graphical User Interfaces with Tk
*********************************
.. index::
single: GUI
single: Graphical User Interface
single: Tkinter
single: Tk
Tk/Tcl has long been an integral part of Python. It provides a robust and
platform independent windowing toolkit, that is available to Python programmers
using the :mod:`Tkinter` module, and its extensions, the :mod:`Tix` and
the :mod:`ttk` modules.
The :mod:`Tkinter` module is a thin object-oriented layer on top of Tcl/Tk. To
use :mod:`Tkinter`, you don't need to write Tcl code, but you will need to
consult the Tk documentation, and occasionally the Tcl documentation.
:mod:`Tkinter` is a set of wrappers that implement the Tk widgets as Python
classes. In addition, the internal module :mod:`_tkinter` provides a threadsafe
mechanism which allows Python and Tcl to interact.
:mod:`Tkinter`'s chief virtues are that it is fast, and that it usually comes
bundled with Python. Although its standard documentation is weak, good
material is available, which includes: references, tutorials, a book and
others. :mod:`Tkinter` is also famous for having an outdated look and feel,
which has been vastly improved in Tk 8.5. Nevertheless, there are many other
GUI libraries that you could be interested in. For more information about
alternatives, see the :ref:`other-gui-packages` section.
.. toctree::
tkinter.rst
ttk.rst
tix.rst
scrolledtext.rst
turtle.rst
idle.rst
othergui.rst
.. Other sections I have in mind are
Tkinter internals
Freezing Tkinter applications
PK
%�\����� �� % html/_sources/library/tkinter.rst.txtnu �[��� :mod:`Tkinter` --- Python interface to Tcl/Tk
=============================================
.. module:: Tkinter
:synopsis: Interface to Tcl/Tk for graphical user interfaces
.. moduleauthor:: Guido van Rossum <guido@Python.org>
The :mod:`Tkinter` module ("Tk interface") is the standard Python interface to
the Tk GUI toolkit. Both Tk and :mod:`Tkinter` are available on most Unix
platforms, as well as on Windows systems. (Tk itself is not part of Python; it
is maintained at ActiveState.)
Running ``python -m Tkinter`` from the command line should open a window
demonstrating a simple Tk interface, letting you know that :mod:`Tkinter` is
properly installed on your system, and also showing what version of Tcl/Tk is
installed, so you can read the Tcl/Tk documentation specific to that version.
.. note::
:mod:`Tkinter` has been renamed to :mod:`tkinter` in Python 3. The
:term:`2to3` tool will automatically adapt imports when converting your
sources to Python 3.
.. seealso::
Tkinter documentation:
`Python Tkinter Resources <https://wiki.python.org/moin/TkInter>`_
The Python Tkinter Topic Guide provides a great deal of information on using Tk
from Python and links to other sources of information on Tk.
`TKDocs <http://www.tkdocs.com/>`_
Extensive tutorial plus friendlier widget pages for some of the widgets.
`Tkinter reference: a GUI for Python <https://infohost.nmt.edu/tcc/help/pubs/tkinter/web/index.html>`_
On-line reference material.
`Tkinter docs from effbot <http://effbot.org/tkinterbook/>`_
Online reference for tkinter supported by effbot.org.
`Programming Python <http://learning-python.com/about-pp4e.html>`_
Book by Mark Lutz, has excellent coverage of Tkinter.
`Modern Tkinter for Busy Python Developers <https://www.amazon.com/Modern-Tkinter-Python-Developers-ebook/dp/B0071QDNLO/>`_
Book by Mark Rozerman about building attractive and modern graphical user interfaces with Python and Tkinter.
`Python and Tkinter Programming <https://www.manning.com/books/python-and-tkinter-programming>`_
Book by John Grayson (ISBN 1-884777-81-3).
Tcl/Tk documentation:
`Tk commands <https://www.tcl.tk/man/tcl8.6/TkCmd/contents.htm>`_
Most commands are available as :mod:`Tkinter` or :mod:`Tkinter.ttk` classes.
Change '8.6' to match the version of your Tcl/Tk installation.
`Tcl/Tk recent man pages <https://www.tcl.tk/doc/>`_
Recent Tcl/Tk manuals on www.tcl.tk.
`ActiveState Tcl Home Page <http://tcl.activestate.com/>`_
The Tk/Tcl development is largely taking place at ActiveState.
`Tcl and the Tk Toolkit <https://www.amazon.com/exec/obidos/ASIN/020163337X>`_
Book by John Ousterhout, the inventor of Tcl.
`Practical Programming in Tcl and Tk <http://www.beedub.com/book/>`_
Brent Welch's encyclopedic book.
Tkinter Modules
---------------
Most of the time, the :mod:`Tkinter` module is all you really need, but a number
of additional modules are available as well. The Tk interface is located in a
binary module named :mod:`_tkinter`. This module contains the low-level
interface to Tk, and should never be used directly by application programmers.
It is usually a shared library (or DLL), but might in some cases be statically
linked with the Python interpreter.
In addition to the Tk interface module, :mod:`Tkinter` includes a number of
Python modules. The two most important modules are the :mod:`Tkinter` module
itself, and a module called :mod:`Tkconstants`. The former automatically imports
the latter, so to use Tkinter, all you need to do is to import one module::
import Tkinter
Or, more often::
from Tkinter import *
.. class:: Tk(screenName=None, baseName=None, className='Tk', useTk=1)
The :class:`Tk` class is instantiated without arguments. This creates a toplevel
widget of Tk which usually is the main window of an application. Each instance
has its own associated Tcl interpreter.
.. FIXME: The following keyword arguments are currently recognized:
.. versionchanged:: 2.4
The *useTk* parameter was added.
.. function:: Tcl(screenName=None, baseName=None, className='Tk', useTk=0)
The :func:`Tcl` function is a factory function which creates an object much like
that created by the :class:`Tk` class, except that it does not initialize the Tk
subsystem. This is most often useful when driving the Tcl interpreter in an
environment where one doesn't want to create extraneous toplevel windows, or
where one cannot (such as Unix/Linux systems without an X server). An object
created by the :func:`Tcl` object can have a Toplevel window created (and the Tk
subsystem initialized) by calling its :meth:`loadtk` method.
.. versionadded:: 2.4
Other modules that provide Tk support include:
:mod:`ScrolledText`
Text widget with a vertical scroll bar built in.
:mod:`tkColorChooser`
Dialog to let the user choose a color.
:mod:`tkCommonDialog`
Base class for the dialogs defined in the other modules listed here.
:mod:`tkFileDialog`
Common dialogs to allow the user to specify a file to open or save.
:mod:`tkFont`
Utilities to help work with fonts.
:mod:`tkMessageBox`
Access to standard Tk dialog boxes.
:mod:`tkSimpleDialog`
Basic dialogs and convenience functions.
:mod:`Tkdnd`
Drag-and-drop support for :mod:`Tkinter`. This is experimental and should become
deprecated when it is replaced with the Tk DND.
:mod:`turtle`
Turtle graphics in a Tk window.
These have been renamed as well in Python 3; they were all made submodules of
the new ``tkinter`` package.
Tkinter Life Preserver
----------------------
.. sectionauthor:: Matt Conway
This section is not designed to be an exhaustive tutorial on either Tk or
Tkinter. Rather, it is intended as a stop gap, providing some introductory
orientation on the system.
Credits:
* Tkinter was written by Steen Lumholt and Guido van Rossum.
* Tk was written by John Ousterhout while at Berkeley.
* This Life Preserver was written by Matt Conway at the University of Virginia.
* The html rendering, and some liberal editing, was produced from a FrameMaker
version by Ken Manheimer.
* Fredrik Lundh elaborated and revised the class interface descriptions, to get
them current with Tk 4.2.
* Mike Clarkson converted the documentation to LaTeX, and compiled the User
Interface chapter of the reference manual.
How To Use This Section
^^^^^^^^^^^^^^^^^^^^^^^
This section is designed in two parts: the first half (roughly) covers
background material, while the second half can be taken to the keyboard as a
handy reference.
When trying to answer questions of the form "how do I do blah", it is often best
to find out how to do "blah" in straight Tk, and then convert this back into the
corresponding :mod:`Tkinter` call. Python programmers can often guess at the
correct Python command by looking at the Tk documentation. This means that in
order to use Tkinter, you will have to know a little bit about Tk. This document
can't fulfill that role, so the best we can do is point you to the best
documentation that exists. Here are some hints:
* The authors strongly suggest getting a copy of the Tk man pages. Specifically,
the man pages in the ``mann`` directory are most useful. The ``man3`` man pages
describe the C interface to the Tk library and thus are not especially helpful
for script writers.
* Addison-Wesley publishes a book called Tcl and the Tk Toolkit by John
Ousterhout (ISBN 0-201-63337-X) which is a good introduction to Tcl and Tk for
the novice. The book is not exhaustive, and for many details it defers to the
man pages.
* :file:`Tkinter.py` is a last resort for most, but can be a good place to go
when nothing else makes sense.
A Simple Hello World Program
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
::
from Tkinter import *
class Application(Frame):
def say_hi(self):
print "hi there, everyone!"
def createWidgets(self):
self.QUIT = Button(self)
self.QUIT["text"] = "QUIT"
self.QUIT["fg"] = "red"
self.QUIT["command"] = self.quit
self.QUIT.pack({"side": "left"})
self.hi_there = Button(self)
self.hi_there["text"] = "Hello",
self.hi_there["command"] = self.say_hi
self.hi_there.pack({"side": "left"})
def __init__(self, master=None):
Frame.__init__(self, master)
self.pack()
self.createWidgets()
root = Tk()
app = Application(master=root)
app.mainloop()
root.destroy()
A (Very) Quick Look at Tcl/Tk
-----------------------------
The class hierarchy looks complicated, but in actual practice, application
programmers almost always refer to the classes at the very bottom of the
hierarchy.
Notes:
* These classes are provided for the purposes of organizing certain functions
under one namespace. They aren't meant to be instantiated independently.
* The :class:`Tk` class is meant to be instantiated only once in an application.
Application programmers need not instantiate one explicitly, the system creates
one whenever any of the other classes are instantiated.
* The :class:`Widget` class is not meant to be instantiated, it is meant only
for subclassing to make "real" widgets (in C++, this is called an 'abstract
class').
To make use of this reference material, there will be times when you will need
to know how to read short passages of Tk and how to identify the various parts
of a Tk command. (See section :ref:`tkinter-basic-mapping` for the
:mod:`Tkinter` equivalents of what's below.)
Tk scripts are Tcl programs. Like all Tcl programs, Tk scripts are just lists
of tokens separated by spaces. A Tk widget is just its *class*, the *options*
that help configure it, and the *actions* that make it do useful things.
To make a widget in Tk, the command is always of the form::
classCommand newPathname options
*classCommand*
denotes which kind of widget to make (a button, a label, a menu...)
*newPathname*
is the new name for this widget. All names in Tk must be unique. To help
enforce this, widgets in Tk are named with *pathnames*, just like files in a
file system. The top level widget, the *root*, is called ``.`` (period) and
children are delimited by more periods. For example,
``.myApp.controlPanel.okButton`` might be the name of a widget.
*options*
configure the widget's appearance and in some cases, its behavior. The options
come in the form of a list of flags and values. Flags are preceded by a '-',
like Unix shell command flags, and values are put in quotes if they are more
than one word.
For example::
button .fred -fg red -text "hi there"
^ ^ \_____________________/
| | |
class new options
command widget (-opt val -opt val ...)
Once created, the pathname to the widget becomes a new command. This new
*widget command* is the programmer's handle for getting the new widget to
perform some *action*. In C, you'd express this as someAction(fred,
someOptions), in C++, you would express this as fred.someAction(someOptions),
and in Tk, you say::
.fred someAction someOptions
Note that the object name, ``.fred``, starts with a dot.
As you'd expect, the legal values for *someAction* will depend on the widget's
class: ``.fred disable`` works if fred is a button (fred gets greyed out), but
does not work if fred is a label (disabling of labels is not supported in Tk).
The legal values of *someOptions* is action dependent. Some actions, like
``disable``, require no arguments, others, like a text-entry box's ``delete``
command, would need arguments to specify what range of text to delete.
.. _tkinter-basic-mapping:
Mapping Basic Tk into Tkinter
-----------------------------
Class commands in Tk correspond to class constructors in Tkinter. ::
button .fred =====> fred = Button()
The master of an object is implicit in the new name given to it at creation
time. In Tkinter, masters are specified explicitly. ::
button .panel.fred =====> fred = Button(panel)
The configuration options in Tk are given in lists of hyphened tags followed by
values. In Tkinter, options are specified as keyword-arguments in the instance
constructor, and keyword-args for configure calls or as instance indices, in
dictionary style, for established instances. See section
:ref:`tkinter-setting-options` on setting options. ::
button .fred -fg red =====> fred = Button(panel, fg = "red")
.fred configure -fg red =====> fred["fg"] = red
OR ==> fred.config(fg = "red")
In Tk, to perform an action on a widget, use the widget name as a command, and
follow it with an action name, possibly with arguments (options). In Tkinter,
you call methods on the class instance to invoke actions on the widget. The
actions (methods) that a given widget can perform are listed in the Tkinter.py
module. ::
.fred invoke =====> fred.invoke()
To give a widget to the packer (geometry manager), you call pack with optional
arguments. In Tkinter, the Pack class holds all this functionality, and the
various forms of the pack command are implemented as methods. All widgets in
:mod:`Tkinter` are subclassed from the Packer, and so inherit all the packing
methods. See the :mod:`Tix` module documentation for additional information on
the Form geometry manager. ::
pack .fred -side left =====> fred.pack(side = "left")
How Tk and Tkinter are Related
------------------------------
From the top down:
Your App Here (Python)
A Python application makes a :mod:`Tkinter` call.
Tkinter (Python Module)
This call (say, for example, creating a button widget), is implemented in the
*Tkinter* module, which is written in Python. This Python function will parse
the commands and the arguments and convert them into a form that makes them look
as if they had come from a Tk script instead of a Python script.
tkinter (C)
These commands and their arguments will be passed to a C function in the
*tkinter* - note the lowercase - extension module.
Tk Widgets (C and Tcl)
This C function is able to make calls into other C modules, including the C
functions that make up the Tk library. Tk is implemented in C and some Tcl.
The Tcl part of the Tk widgets is used to bind certain default behaviors to
widgets, and is executed once at the point where the Python :mod:`Tkinter`
module is imported. (The user never sees this stage).
Tk (C)
The Tk part of the Tk Widgets implement the final mapping to ...
Xlib (C)
the Xlib library to draw graphics on the screen.
Handy Reference
---------------
.. _tkinter-setting-options:
Setting Options
^^^^^^^^^^^^^^^
Options control things like the color and border width of a widget. Options can
be set in three ways:
At object creation time, using keyword arguments
::
fred = Button(self, fg = "red", bg = "blue")
After object creation, treating the option name like a dictionary index
::
fred["fg"] = "red"
fred["bg"] = "blue"
Use the config() method to update multiple attrs subsequent to object creation
::
fred.config(fg = "red", bg = "blue")
For a complete explanation of a given option and its behavior, see the Tk man
pages for the widget in question.
Note that the man pages list "STANDARD OPTIONS" and "WIDGET SPECIFIC OPTIONS"
for each widget. The former is a list of options that are common to many
widgets, the latter are the options that are idiosyncratic to that particular
widget. The Standard Options are documented on the :manpage:`options(3)` man
page.
No distinction between standard and widget-specific options is made in this
document. Some options don't apply to some kinds of widgets. Whether a given
widget responds to a particular option depends on the class of the widget;
buttons have a ``command`` option, labels do not.
The options supported by a given widget are listed in that widget's man page, or
can be queried at runtime by calling the :meth:`config` method without
arguments, or by calling the :meth:`keys` method on that widget. The return
value of these calls is a dictionary whose key is the name of the option as a
string (for example, ``'relief'``) and whose values are 5-tuples.
Some options, like ``bg`` are synonyms for common options with long names
(``bg`` is shorthand for "background"). Passing the ``config()`` method the name
of a shorthand option will return a 2-tuple, not 5-tuple. The 2-tuple passed
back will contain the name of the synonym and the "real" option (such as
``('bg', 'background')``).
+-------+---------------------------------+--------------+
| Index | Meaning | Example |
+=======+=================================+==============+
| 0 | option name | ``'relief'`` |
+-------+---------------------------------+--------------+
| 1 | option name for database lookup | ``'relief'`` |
+-------+---------------------------------+--------------+
| 2 | option class for database | ``'Relief'`` |
| | lookup | |
+-------+---------------------------------+--------------+
| 3 | default value | ``'raised'`` |
+-------+---------------------------------+--------------+
| 4 | current value | ``'groove'`` |
+-------+---------------------------------+--------------+
Example::
>>> print fred.config()
{'relief': ('relief', 'relief', 'Relief', 'raised', 'groove')}
Of course, the dictionary printed will include all the options available and
their values. This is meant only as an example.
The Packer
^^^^^^^^^^
.. index:: single: packing (widgets)
The packer is one of Tk's geometry-management mechanisms. Geometry managers
are used to specify the relative positioning of the positioning of widgets
within their container - their mutual *master*. In contrast to the more
cumbersome *placer* (which is used less commonly, and we do not cover here), the
packer takes qualitative relationship specification - *above*, *to the left of*,
*filling*, etc - and works everything out to determine the exact placement
coordinates for you.
The size of any *master* widget is determined by the size of the "slave widgets"
inside. The packer is used to control where slave widgets appear inside the
master into which they are packed. You can pack widgets into frames, and frames
into other frames, in order to achieve the kind of layout you desire.
Additionally, the arrangement is dynamically adjusted to accommodate incremental
changes to the configuration, once it is packed.
Note that widgets do not appear until they have had their geometry specified
with a geometry manager. It's a common early mistake to leave out the geometry
specification, and then be surprised when the widget is created but nothing
appears. A widget will appear only after it has had, for example, the packer's
:meth:`pack` method applied to it.
The pack() method can be called with keyword-option/value pairs that control
where the widget is to appear within its container, and how it is to behave when
the main application window is resized. Here are some examples::
fred.pack() # defaults to side = "top"
fred.pack(side = "left")
fred.pack(expand = 1)
Packer Options
^^^^^^^^^^^^^^
For more extensive information on the packer and the options that it can take,
see the man pages and page 183 of John Ousterhout's book.
anchor
Anchor type. Denotes where the packer is to place each slave in its parcel.
expand
Boolean, ``0`` or ``1``.
fill
Legal values: ``'x'``, ``'y'``, ``'both'``, ``'none'``.
ipadx and ipady
A distance - designating internal padding on each side of the slave widget.
padx and pady
A distance - designating external padding on each side of the slave widget.
side
Legal values are: ``'left'``, ``'right'``, ``'top'``, ``'bottom'``.
Coupling Widget Variables
^^^^^^^^^^^^^^^^^^^^^^^^^
The current-value setting of some widgets (like text entry widgets) can be
connected directly to application variables by using special options. These
options are ``variable``, ``textvariable``, ``onvalue``, ``offvalue``, and
``value``. This connection works both ways: if the variable changes for any
reason, the widget it's connected to will be updated to reflect the new value.
Unfortunately, in the current implementation of :mod:`Tkinter` it is not
possible to hand over an arbitrary Python variable to a widget through a
``variable`` or ``textvariable`` option. The only kinds of variables for which
this works are variables that are subclassed from a class called Variable,
defined in the :mod:`Tkinter` module.
There are many useful subclasses of Variable already defined:
:class:`StringVar`, :class:`IntVar`, :class:`DoubleVar`, and
:class:`BooleanVar`. To read the current value of such a variable, call the
:meth:`get` method on it, and to change its value you call the :meth:`!set`
method. If you follow this protocol, the widget will always track the value of
the variable, with no further intervention on your part.
For example::
class App(Frame):
def __init__(self, master=None):
Frame.__init__(self, master)
self.pack()
self.entrythingy = Entry()
self.entrythingy.pack()
# here is the application variable
self.contents = StringVar()
# set it to some value
self.contents.set("this is a variable")
# tell the entry widget to watch this variable
self.entrythingy["textvariable"] = self.contents
# and here we get a callback when the user hits return.
# we will have the program print out the value of the
# application variable when the user hits return
self.entrythingy.bind('<Key-Return>',
self.print_contents)
def print_contents(self, event):
print "hi. contents of entry is now ---->", \
self.contents.get()
The Window Manager
^^^^^^^^^^^^^^^^^^
.. index:: single: window manager (widgets)
In Tk, there is a utility command, ``wm``, for interacting with the window
manager. Options to the ``wm`` command allow you to control things like titles,
placement, icon bitmaps, and the like. In :mod:`Tkinter`, these commands have
been implemented as methods on the :class:`Wm` class. Toplevel widgets are
subclassed from the :class:`Wm` class, and so can call the :class:`Wm` methods
directly.
To get at the toplevel window that contains a given widget, you can often just
refer to the widget's master. Of course if the widget has been packed inside of
a frame, the master won't represent a toplevel window. To get at the toplevel
window that contains an arbitrary widget, you can call the :meth:`_root` method.
This method begins with an underscore to denote the fact that this function is
part of the implementation, and not an interface to Tk functionality.
Here are some examples of typical usage::
from Tkinter import *
class App(Frame):
def __init__(self, master=None):
Frame.__init__(self, master)
self.pack()
# create the application
myapp = App()
#
# here are method calls to the window manager class
#
myapp.master.title("My Do-Nothing Application")
myapp.master.maxsize(1000, 400)
# start the program
myapp.mainloop()
Tk Option Data Types
^^^^^^^^^^^^^^^^^^^^
.. index:: single: Tk Option Data Types
anchor
Legal values are points of the compass: ``"n"``, ``"ne"``, ``"e"``, ``"se"``,
``"s"``, ``"sw"``, ``"w"``, ``"nw"``, and also ``"center"``.
bitmap
There are eight built-in, named bitmaps: ``'error'``, ``'gray25'``,
``'gray50'``, ``'hourglass'``, ``'info'``, ``'questhead'``, ``'question'``,
``'warning'``. To specify an X bitmap filename, give the full path to the file,
preceded with an ``@``, as in ``"@/usr/contrib/bitmap/gumby.bit"``.
boolean
You can pass integers 0 or 1 or the strings ``"yes"`` or ``"no"``.
callback
This is any Python function that takes no arguments. For example::
def print_it():
print "hi there"
fred["command"] = print_it
color
Colors can be given as the names of X colors in the rgb.txt file, or as strings
representing RGB values in 4 bit: ``"#RGB"``, 8 bit: ``"#RRGGBB"``, 12 bit"
``"#RRRGGGBBB"``, or 16 bit ``"#RRRRGGGGBBBB"`` ranges, where R,G,B here
represent any legal hex digit. See page 160 of Ousterhout's book for details.
cursor
The standard X cursor names from :file:`cursorfont.h` can be used, without the
``XC_`` prefix. For example to get a hand cursor (:const:`XC_hand2`), use the
string ``"hand2"``. You can also specify a bitmap and mask file of your own.
See page 179 of Ousterhout's book.
distance
Screen distances can be specified in either pixels or absolute distances.
Pixels are given as numbers and absolute distances as strings, with the trailing
character denoting units: ``c`` for centimetres, ``i`` for inches, ``m`` for
millimetres, ``p`` for printer's points. For example, 3.5 inches is expressed
as ``"3.5i"``.
font
Tk uses a list font name format, such as ``{courier 10 bold}``. Font sizes with
positive numbers are measured in points; sizes with negative numbers are
measured in pixels.
geometry
This is a string of the form ``widthxheight``, where width and height are
measured in pixels for most widgets (in characters for widgets displaying text).
For example: ``fred["geometry"] = "200x100"``.
justify
Legal values are the strings: ``"left"``, ``"center"``, ``"right"``, and
``"fill"``.
region
This is a string with four space-delimited elements, each of which is a legal
distance (see above). For example: ``"2 3 4 5"`` and ``"3i 2i 4.5i 2i"`` and
``"3c 2c 4c 10.43c"`` are all legal regions.
relief
Determines what the border style of a widget will be. Legal values are:
``"raised"``, ``"sunken"``, ``"flat"``, ``"groove"``, and ``"ridge"``.
scrollcommand
This is almost always the :meth:`!set` method of some scrollbar widget, but can
be any widget method that takes a single argument. Refer to the file
:file:`Demo/tkinter/matt/canvas-with-scrollbars.py` in the Python source
distribution for an example.
wrap:
Must be one of: ``"none"``, ``"char"``, or ``"word"``.
Bindings and Events
^^^^^^^^^^^^^^^^^^^
.. index::
single: bind (widgets)
single: events (widgets)
The bind method from the widget command allows you to watch for certain events
and to have a callback function trigger when that event type occurs. The form
of the bind method is::
def bind(self, sequence, func, add=''):
where:
sequence
is a string that denotes the target kind of event. (See the bind man page and
page 201 of John Ousterhout's book for details).
func
is a Python function, taking one argument, to be invoked when the event occurs.
An Event instance will be passed as the argument. (Functions deployed this way
are commonly known as *callbacks*.)
add
is optional, either ``''`` or ``'+'``. Passing an empty string denotes that
this binding is to replace any other bindings that this event is associated
with. Passing a ``'+'`` means that this function is to be added to the list
of functions bound to this event type.
For example::
def turnRed(self, event):
event.widget["activeforeground"] = "red"
self.button.bind("<Enter>", self.turnRed)
Notice how the widget field of the event is being accessed in the
:meth:`turnRed` callback. This field contains the widget that caught the X
event. The following table lists the other event fields you can access, and how
they are denoted in Tk, which can be useful when referring to the Tk man pages.
::
Tk Tkinter Event Field Tk Tkinter Event Field
-- ------------------- -- -------------------
%f focus %A char
%h height %E send_event
%k keycode %K keysym
%s state %N keysym_num
%t time %T type
%w width %W widget
%x x %X x_root
%y y %Y y_root
The index Parameter
^^^^^^^^^^^^^^^^^^^
A number of widgets require"index" parameters to be passed. These are used to
point at a specific place in a Text widget, or to particular characters in an
Entry widget, or to particular menu items in a Menu widget.
Entry widget indexes (index, view index, etc.)
Entry widgets have options that refer to character positions in the text being
displayed. You can use these :mod:`Tkinter` functions to access these special
points in text widgets:
AtEnd()
refers to the last position in the text
AtInsert()
refers to the point where the text cursor is
AtSelFirst()
indicates the beginning point of the selected text
AtSelLast()
denotes the last point of the selected text and finally
At(x[, y])
refers to the character at pixel location *x*, *y* (with *y* not used in the
case of a text entry widget, which contains a single line of text).
Text widget indexes
The index notation for Text widgets is very rich and is best described in the Tk
man pages.
Menu indexes (menu.invoke(), menu.entryconfig(), etc.)
Some options and methods for menus manipulate specific menu entries. Anytime a
menu index is needed for an option or a parameter, you may pass in:
* an integer which refers to the numeric position of the entry in the widget,
counted from the top, starting with 0;
* the string ``'active'``, which refers to the menu position that is currently
under the cursor;
* the string ``"last"`` which refers to the last menu item;
* An integer preceded by ``@``, as in ``@6``, where the integer is interpreted
as a y pixel coordinate in the menu's coordinate system;
* the string ``"none"``, which indicates no menu entry at all, most often used
with menu.activate() to deactivate all entries, and finally,
* a text string that is pattern matched against the label of the menu entry, as
scanned from the top of the menu to the bottom. Note that this index type is
considered after all the others, which means that matches for menu items
labelled ``last``, ``active``, or ``none`` may be interpreted as the above
literals, instead.
Images
^^^^^^
Images of different formats can be created through the corresponding subclass
of :class:`Tkinter.Image`:
* :class:`BitmapImage` for images in XBM format.
* :class:`PhotoImage` for images in PGM, PPM, GIF and PNG formats. The latter
is supported starting with Tk 8.6.
Either type of image is created through either the ``file`` or the ``data``
option (other options are available as well).
The image object can then be used wherever an ``image`` option is supported by
some widget (e.g. labels, buttons, menus). In these cases, Tk will not keep a
reference to the image. When the last Python reference to the image object is
deleted, the image data is deleted as well, and Tk will display an empty box
wherever the image was used.
.. seealso::
The `Pillow <http://python-pillow.org/>`_ package adds support for
formats such as BMP, JPEG, TIFF, and WebP, among others.
.. _tkinter-file-handlers:
File Handlers
-------------
Tk allows you to register and unregister a callback function which will be
called from the Tk mainloop when I/O is possible on a file descriptor.
Only one handler may be registered per file descriptor. Example code::
import Tkinter
widget = Tkinter.Tk()
mask = Tkinter.READABLE | Tkinter.WRITABLE
widget.tk.createfilehandler(file, mask, callback)
...
widget.tk.deletefilehandler(file)
This feature is not available on Windows.
Since you don't know how many bytes are available for reading, you may not
want to use the :class:`~io.BufferedIOBase` or :class:`~io.TextIOBase`
:meth:`~io.BufferedIOBase.read` or :meth:`~io.IOBase.readline` methods,
since these will insist on reading a predefined number of bytes.
For sockets, the :meth:`~socket.socket.recv` or
:meth:`~socket.socket.recvfrom` methods will work fine; for other files,
use raw reads or ``os.read(file.fileno(), maxbytecount)``.
.. method:: Widget.tk.createfilehandler(file, mask, func)
Registers the file handler callback function *func*. The *file* argument
may either be an object with a :meth:`~io.IOBase.fileno` method (such as
a file or socket object), or an integer file descriptor. The *mask*
argument is an ORed combination of any of the three constants below.
The callback is called as follows::
callback(file, mask)
.. method:: Widget.tk.deletefilehandler(file)
Unregisters a file handler.
.. data:: READABLE
WRITABLE
EXCEPTION
Constants used in the *mask* arguments.
PK
%�\8�1� � # html/_sources/library/token.rst.txtnu �[��� :mod:`token` --- Constants used with Python parse trees
=======================================================
.. module:: token
:synopsis: Constants representing terminal nodes of the parse tree.
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
**Source code:** :source:`Lib/token.py`
--------------
This module provides constants which represent the numeric values of leaf nodes
of the parse tree (terminal tokens). Refer to the file :file:`Grammar/Grammar`
in the Python distribution for the definitions of the names in the context of
the language grammar. The specific numeric values which the names map to may
change between Python versions.
The module also provides a mapping from numeric codes to names and some
functions. The functions mirror definitions in the Python C header files.
.. data:: tok_name
Dictionary mapping the numeric values of the constants defined in this module
back to name strings, allowing more human-readable representation of parse trees
to be generated.
.. function:: ISTERMINAL(x)
Return true for terminal token values.
.. function:: ISNONTERMINAL(x)
Return true for non-terminal token values.
.. function:: ISEOF(x)
Return true if *x* is the marker indicating the end of input.
The token constants are:
.. data:: ENDMARKER
NAME
NUMBER
STRING
NEWLINE
INDENT
DEDENT
LPAR
RPAR
LSQB
RSQB
COLON
COMMA
SEMI
PLUS
MINUS
STAR
SLASH
VBAR
AMPER
LESS
GREATER
EQUAL
DOT
PERCENT
BACKQUOTE
LBRACE
RBRACE
EQEQUAL
NOTEQUAL
LESSEQUAL
GREATEREQUAL
TILDE
CIRCUMFLEX
LEFTSHIFT
RIGHTSHIFT
DOUBLESTAR
PLUSEQUAL
MINEQUAL
STAREQUAL
SLASHEQUAL
PERCENTEQUAL
AMPEREQUAL
VBAREQUAL
CIRCUMFLEXEQUAL
LEFTSHIFTEQUAL
RIGHTSHIFTEQUAL
DOUBLESTAREQUAL
DOUBLESLASH
DOUBLESLASHEQUAL
AT
OP
ERRORTOKEN
N_TOKENS
NT_OFFSET
.. seealso::
Module :mod:`parser`
The second example for the :mod:`parser` module shows how to use the
:mod:`symbol` module.
PK
%�\�=��� � & html/_sources/library/tokenize.rst.txtnu �[��� :mod:`tokenize` --- Tokenizer for Python source
===============================================
.. module:: tokenize
:synopsis: Lexical scanner for Python source code.
.. moduleauthor:: Ka Ping Yee
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
**Source code:** :source:`Lib/tokenize.py`
--------------
The :mod:`tokenize` module provides a lexical scanner for Python source code,
implemented in Python. The scanner in this module returns comments as tokens as
well, making it useful for implementing "pretty-printers," including colorizers
for on-screen displays.
To simplify token stream handling, all :ref:`operators` and :ref:`delimiters`
tokens are returned using the generic :data:`token.OP` token type. The exact
type can be determined by checking the second field (containing the actual
token string matched) of the tuple returned from
:func:`tokenize.generate_tokens` for the character sequence that identifies a
specific operator token.
The primary entry point is a :term:`generator`:
.. function:: generate_tokens(readline)
The :func:`generate_tokens` generator requires one argument, *readline*,
which must be a callable object which provides the same interface as the
:meth:`~file.readline` method of built-in file objects (see section
:ref:`bltin-file-objects`). Each call to the function should return one line
of input as a string. Alternately, *readline* may be a callable object that
signals completion by raising :exc:`StopIteration`.
The generator produces 5-tuples with these members: the token type; the token
string; a 2-tuple ``(srow, scol)`` of ints specifying the row and column
where the token begins in the source; a 2-tuple ``(erow, ecol)`` of ints
specifying the row and column where the token ends in the source; and the
line on which the token was found. The line passed (the last tuple item) is
the *logical* line; continuation lines are included.
.. versionadded:: 2.2
An older entry point is retained for backward compatibility:
.. function:: tokenize(readline[, tokeneater])
The :func:`.tokenize` function accepts two parameters: one representing the input
stream, and one providing an output mechanism for :func:`.tokenize`.
The first parameter, *readline*, must be a callable object which provides the
same interface as the :meth:`~file.readline` method of built-in file objects (see
section :ref:`bltin-file-objects`). Each call to the function should return one
line of input as a string. Alternately, *readline* may be a callable object that
signals completion by raising :exc:`StopIteration`.
.. versionchanged:: 2.5
Added :exc:`StopIteration` support.
The second parameter, *tokeneater*, must also be a callable object. It is
called once for each token, with five arguments, corresponding to the tuples
generated by :func:`generate_tokens`.
All constants from the :mod:`token` module are also exported from
:mod:`tokenize`, as are two additional token type values that might be passed to
the *tokeneater* function by :func:`.tokenize`:
.. data:: COMMENT
Token value used to indicate a comment.
.. data:: NL
Token value used to indicate a non-terminating newline. The NEWLINE token
indicates the end of a logical line of Python code; NL tokens are generated when
a logical line of code is continued over multiple physical lines.
Another function is provided to reverse the tokenization process. This is useful
for creating tools that tokenize a script, modify the token stream, and write
back the modified script.
.. function:: untokenize(iterable)
Converts tokens back into Python source code. The *iterable* must return
sequences with at least two elements, the token type and the token string. Any
additional sequence elements are ignored.
The reconstructed script is returned as a single string. The result is
guaranteed to tokenize back to match the input so that the conversion is
lossless and round-trips are assured. The guarantee applies only to the token
type and token string as the spacing between tokens (column positions) may
change.
.. versionadded:: 2.5
.. exception:: TokenError
Raised when either a docstring or expression that may be split over several
lines is not completed anywhere in the file, for example::
"""Beginning of
docstring
or::
[1,
2,
3
Note that unclosed single-quoted strings do not cause an error to be
raised. They are tokenized as ``ERRORTOKEN``, followed by the tokenization of
their contents.
Example of a script re-writer that transforms float literals into Decimal
objects::
def decistmt(s):
"""Substitute Decimals for floats in a string of statements.
>>> from decimal import Decimal
>>> s = 'print +21.3e-5*-.1234/81.7'
>>> decistmt(s)
"print +Decimal ('21.3e-5')*-Decimal ('.1234')/Decimal ('81.7')"
>>> exec(s)
-3.21716034272e-007
>>> exec(decistmt(s))
-3.217160342717258261933904529E-7
"""
result = []
g = generate_tokens(StringIO(s).readline) # tokenize the string
for toknum, tokval, _, _, _ in g:
if toknum == NUMBER and '.' in tokval: # replace NUMBER tokens
result.extend([
(NAME, 'Decimal'),
(OP, '('),
(STRING, repr(tokval)),
(OP, ')')
])
else:
result.append((toknum, tokval))
return untokenize(result)
PK
%�\ ��D D # html/_sources/library/trace.rst.txtnu �[��� :mod:`trace` --- Trace or track Python statement execution
==========================================================
.. module:: trace
:synopsis: Trace or track Python statement execution.
**Source code:** :source:`Lib/trace.py`
--------------
The :mod:`trace` module allows you to trace program execution, generate
annotated statement coverage listings, print caller/callee relationships and
list functions executed during a program run. It can be used in another program
or from the command line.
.. _trace-cli:
Command-Line Usage
------------------
The :mod:`trace` module can be invoked from the command line. It can be as
simple as ::
python -m trace --count -C . somefile.py ...
The above will execute :file:`somefile.py` and generate annotated listings of
all Python modules imported during the execution into the current directory.
.. program:: trace
.. cmdoption:: --help
Display usage and exit.
.. cmdoption:: --version
Display the version of the module and exit.
Main options
^^^^^^^^^^^^
At least one of the following options must be specified when invoking
:mod:`trace`. The :option:`--listfuncs <-l>` option is mutually exclusive with
the :option:`--trace <-t>` and :option:`--count <-c>` options. When
:option:`--listfuncs <-l>` is provided, neither :option:`--count <-c>` nor
:option:`--trace <-t>` are accepted, and vice versa.
.. program:: trace
.. cmdoption:: -c, --count
Produce a set of annotated listing files upon program completion that shows
how many times each statement was executed. See also
:option:`--coverdir <-C>`, :option:`--file <-f>` and
:option:`--no-report <-R>` below.
.. cmdoption:: -t, --trace
Display lines as they are executed.
.. cmdoption:: -l, --listfuncs
Display the functions executed by running the program.
.. cmdoption:: -r, --report
Produce an annotated list from an earlier program run that used the
:option:`--count <-c>` and :option:`--file <-f>` option. This does not
execute any code.
.. cmdoption:: -T, --trackcalls
Display the calling relationships exposed by running the program.
Modifiers
^^^^^^^^^
.. program:: trace
.. cmdoption:: -f, --file=<file>
Name of a file to accumulate counts over several tracing runs. Should be
used with the :option:`--count <-c>` option.
.. cmdoption:: -C, --coverdir=<dir>
Directory where the report files go. The coverage report for
``package.module`` is written to file :file:`{dir}/{package}/{module}.cover`.
.. cmdoption:: -m, --missing
When generating annotated listings, mark lines which were not executed with
``>>>>>>``.
.. cmdoption:: -s, --summary
When using :option:`--count <-c>` or :option:`--report <-r>`, write a brief
summary to stdout for each file processed.
.. cmdoption:: -R, --no-report
Do not generate annotated listings. This is useful if you intend to make
several runs with :option:`--count <-c>`, and then produce a single set of
annotated listings at the end.
.. cmdoption:: -g, --timing
Prefix each line with the time since the program started. Only used while
tracing.
Filters
^^^^^^^
These options may be repeated multiple times.
.. program:: trace
.. cmdoption:: --ignore-module=<mod>
Ignore each of the given module names and its submodules (if it is a
package). The argument can be a list of names separated by a comma.
.. cmdoption:: --ignore-dir=<dir>
Ignore all modules and packages in the named directory and subdirectories.
The argument can be a list of directories separated by :data:`os.pathsep`.
.. _trace-api:
Programmatic Interface
----------------------
.. class:: Trace([count=1[, trace=1[, countfuncs=0[, countcallers=0[, ignoremods=()[, ignoredirs=()[, infile=None[, outfile=None[, timing=False]]]]]]]]])
Create an object to trace execution of a single statement or expression. All
parameters are optional. *count* enables counting of line numbers. *trace*
enables line execution tracing. *countfuncs* enables listing of the
functions called during the run. *countcallers* enables call relationship
tracking. *ignoremods* is a list of modules or packages to ignore.
*ignoredirs* is a list of directories whose modules or packages should be
ignored. *infile* is the name of the file from which to read stored count
information. *outfile* is the name of the file in which to write updated
count information. *timing* enables a timestamp relative to when tracing was
started to be displayed.
.. method:: run(cmd)
Execute the command and gather statistics from the execution with
the current tracing parameters. *cmd* must be a string or code object,
suitable for passing into :func:`exec`.
.. method:: runctx(cmd, globals=None, locals=None)
Execute the command and gather statistics from the execution with the
current tracing parameters, in the defined global and local
environments. If not defined, *globals* and *locals* default to empty
dictionaries.
.. method:: runfunc(func, *args, **kwds)
Call *func* with the given arguments under control of the :class:`Trace`
object with the current tracing parameters.
.. method:: results()
Return a :class:`CoverageResults` object that contains the cumulative
results of all previous calls to ``run``, ``runctx`` and ``runfunc``
for the given :class:`Trace` instance. Does not reset the accumulated
trace results.
.. class:: CoverageResults
A container for coverage results, created by :meth:`Trace.results`. Should
not be created directly by the user.
.. method:: update(other)
Merge in data from another :class:`CoverageResults` object.
.. method:: write_results([show_missing=True[, summary=False[, coverdir=None]]])
Write coverage results. Set *show_missing* to show lines that had no
hits. Set *summary* to include in the output the coverage summary per
module. *coverdir* specifies the directory into which the coverage
result files will be output. If ``None``, the results for each source
file are placed in its directory.
A simple example demonstrating the use of the programmatic interface::
import sys
import trace
# create a Trace object, telling it what to ignore, and whether to
# do tracing or line-counting or both.
tracer = trace.Trace(
ignoredirs=[sys.prefix, sys.exec_prefix],
trace=0,
count=1)
# run the new command using the given tracer
tracer.run('main()')
# make a report, placing output in the current directory
r = tracer.results()
r.write_results(show_missing=True, coverdir=".")
PK
%�\�
>��) �) ' html/_sources/library/traceback.rst.txtnu �[��� :mod:`traceback` --- Print or retrieve a stack traceback
========================================================
.. module:: traceback
:synopsis: Print or retrieve a stack traceback.
This module provides a standard interface to extract, format and print stack
traces of Python programs. It exactly mimics the behavior of the Python
interpreter when it prints a stack trace. This is useful when you want to print
stack traces under program control, such as in a "wrapper" around the
interpreter.
.. index:: object: traceback
The module uses traceback objects --- this is the object type that is stored in
the variables :data:`sys.exc_traceback` (deprecated) and
:data:`sys.last_traceback` and returned as the third item from
:func:`sys.exc_info`.
The module defines the following functions:
.. function:: print_tb(tb[, limit[, file]])
Print up to *limit* stack trace entries from the traceback object *tb*. If
*limit* is omitted or ``None``, all entries are printed. If *file* is omitted
or ``None``, the output goes to ``sys.stderr``; otherwise it should be an
open file or file-like object to receive the output.
.. function:: print_exception(etype, value, tb[, limit[, file]])
Print exception information and up to *limit* stack trace entries from the
traceback *tb* to *file*. This differs from :func:`print_tb` in the following
ways: (1) if *tb* is not ``None``, it prints a header ``Traceback (most
recent call last):``; (2) it prints the exception *etype* and *value* after
the stack trace; (3) if *etype* is :exc:`SyntaxError` and *value* has the
appropriate format, it prints the line where the syntax error occurred with a
caret indicating the approximate position of the error.
.. function:: print_exc([limit[, file]])
This is a shorthand for ``print_exception(sys.exc_type, sys.exc_value,
sys.exc_traceback, limit, file)``. (In fact, it uses :func:`sys.exc_info` to
retrieve the same information in a thread-safe way instead of using the
deprecated variables.)
.. function:: format_exc([limit])
This is like ``print_exc(limit)`` but returns a string instead of printing to
a file.
.. versionadded:: 2.4
.. function:: print_last([limit[, file]])
This is a shorthand for ``print_exception(sys.last_type, sys.last_value,
sys.last_traceback, limit, file)``. In general it will work only after
an exception has reached an interactive prompt (see :data:`sys.last_type`).
.. function:: print_stack([f[, limit[, file]]])
This function prints a stack trace from its invocation point. The optional
*f* argument can be used to specify an alternate stack frame to start. The
optional *limit* and *file* arguments have the same meaning as for
:func:`print_exception`.
.. function:: extract_tb(tb[, limit])
Return a list of up to *limit* "pre-processed" stack trace entries extracted
from the traceback object *tb*. It is useful for alternate formatting of
stack traces. If *limit* is omitted or ``None``, all entries are extracted.
A "pre-processed" stack trace entry is a 4-tuple (*filename*, *line number*,
function name*, *text*) representing the information that is usually printed
for a stack trace. The *text* is a string with leading and trailing
whitespace stripped; if the source is not available it is ``None``.
.. function:: extract_stack([f[, limit]])
Extract the raw traceback from the current stack frame. The return value has
the same format as for :func:`extract_tb`. The optional *f* and *limit*
arguments have the same meaning as for :func:`print_stack`.
.. function:: format_list(extracted_list)
Given a list of tuples as returned by :func:`extract_tb` or
:func:`extract_stack`, return a list of strings ready for printing. Each
string in the resulting list corresponds to the item with the same index in
the argument list. Each string ends in a newline; the strings may contain
internal newlines as well, for those items whose source text line is not
``None``.
.. function:: format_exception_only(etype, value)
Format the exception part of a traceback. The arguments are the exception
type, *etype* and *value* such as given by ``sys.last_type`` and
``sys.last_value``. The return value is a list of strings, each ending in a
newline. Normally, the list contains a single string; however, for
:exc:`SyntaxError` exceptions, it contains several lines that (when printed)
display detailed information about where the syntax error occurred. The
message indicating which exception occurred is the always last string in the
list.
.. function:: format_exception(etype, value, tb[, limit])
Format a stack trace and the exception information. The arguments have the
same meaning as the corresponding arguments to :func:`print_exception`. The
return value is a list of strings, each ending in a newline and some
containing internal newlines. When these lines are concatenated and printed,
exactly the same text is printed as does :func:`print_exception`.
.. function:: format_tb(tb[, limit])
A shorthand for ``format_list(extract_tb(tb, limit))``.
.. function:: format_stack([f[, limit]])
A shorthand for ``format_list(extract_stack(f, limit))``.
.. function:: tb_lineno(tb)
This function returns the current line number set in the traceback object.
This function was necessary because in versions of Python prior to 2.3 when
the :option:`-O` flag was passed to Python the ``tb.tb_lineno`` was not
updated correctly. This function has no use in versions past 2.3.
.. _traceback-example:
Traceback Examples
------------------
This simple example implements a basic read-eval-print loop, similar to (but
less useful than) the standard Python interactive interpreter loop. For a more
complete implementation of the interpreter loop, refer to the :mod:`code`
module. ::
import sys, traceback
def run_user_code(envdir):
source = raw_input(">>> ")
try:
exec source in envdir
except:
print "Exception in user code:"
print '-'*60
traceback.print_exc(file=sys.stdout)
print '-'*60
envdir = {}
while 1:
run_user_code(envdir)
The following example demonstrates the different ways to print and format the
exception and traceback::
import sys, traceback
def lumberjack():
bright_side_of_death()
def bright_side_of_death():
return tuple()[0]
try:
lumberjack()
except IndexError:
exc_type, exc_value, exc_traceback = sys.exc_info()
print "*** print_tb:"
traceback.print_tb(exc_traceback, limit=1, file=sys.stdout)
print "*** print_exception:"
traceback.print_exception(exc_type, exc_value, exc_traceback,
limit=2, file=sys.stdout)
print "*** print_exc:"
traceback.print_exc()
print "*** format_exc, first and last line:"
formatted_lines = traceback.format_exc().splitlines()
print formatted_lines[0]
print formatted_lines[-1]
print "*** format_exception:"
print repr(traceback.format_exception(exc_type, exc_value,
exc_traceback))
print "*** extract_tb:"
print repr(traceback.extract_tb(exc_traceback))
print "*** format_tb:"
print repr(traceback.format_tb(exc_traceback))
print "*** tb_lineno:", exc_traceback.tb_lineno
The output for the example would look similar to this::
*** print_tb:
File "<doctest...>", line 10, in <module>
lumberjack()
*** print_exception:
Traceback (most recent call last):
File "<doctest...>", line 10, in <module>
lumberjack()
File "<doctest...>", line 4, in lumberjack
bright_side_of_death()
IndexError: tuple index out of range
*** print_exc:
Traceback (most recent call last):
File "<doctest...>", line 10, in <module>
lumberjack()
File "<doctest...>", line 4, in lumberjack
bright_side_of_death()
IndexError: tuple index out of range
*** format_exc, first and last line:
Traceback (most recent call last):
IndexError: tuple index out of range
*** format_exception:
['Traceback (most recent call last):\n',
' File "<doctest...>", line 10, in <module>\n lumberjack()\n',
' File "<doctest...>", line 4, in lumberjack\n bright_side_of_death()\n',
' File "<doctest...>", line 7, in bright_side_of_death\n return tuple()[0]\n',
'IndexError: tuple index out of range\n']
*** extract_tb:
[('<doctest...>', 10, '<module>', 'lumberjack()'),
('<doctest...>', 4, 'lumberjack', 'bright_side_of_death()'),
('<doctest...>', 7, 'bright_side_of_death', 'return tuple()[0]')]
*** format_tb:
[' File "<doctest...>", line 10, in <module>\n lumberjack()\n',
' File "<doctest...>", line 4, in lumberjack\n bright_side_of_death()\n',
' File "<doctest...>", line 7, in bright_side_of_death\n return tuple()[0]\n']
*** tb_lineno: 10
The following example shows the different ways to print and format the stack::
>>> import traceback
>>> def another_function():
... lumberstack()
...
>>> def lumberstack():
... traceback.print_stack()
... print repr(traceback.extract_stack())
... print repr(traceback.format_stack())
...
>>> another_function()
File "<doctest>", line 10, in <module>
another_function()
File "<doctest>", line 3, in another_function
lumberstack()
File "<doctest>", line 6, in lumberstack
traceback.print_stack()
[('<doctest>', 10, '<module>', 'another_function()'),
('<doctest>', 3, 'another_function', 'lumberstack()'),
('<doctest>', 7, 'lumberstack', 'print repr(traceback.extract_stack())')]
[' File "<doctest>", line 10, in <module>\n another_function()\n',
' File "<doctest>", line 3, in another_function\n lumberstack()\n',
' File "<doctest>", line 8, in lumberstack\n print repr(traceback.format_stack())\n']
This last example demonstrates the final few formatting functions:
.. doctest::
:options: +NORMALIZE_WHITESPACE
>>> import traceback
>>> traceback.format_list([('spam.py', 3, '<module>', 'spam.eggs()'),
... ('eggs.py', 42, 'eggs', 'return "bacon"')])
[' File "spam.py", line 3, in <module>\n spam.eggs()\n',
' File "eggs.py", line 42, in eggs\n return "bacon"\n']
>>> an_error = IndexError('tuple index out of range')
>>> traceback.format_exception_only(type(an_error), an_error)
['IndexError: tuple index out of range\n']
PK
%�\�#
C� C� ! html/_sources/library/ttk.rst.txtnu �[��� :mod:`ttk` --- Tk themed widgets
================================
.. module:: ttk
:synopsis: Tk themed widget set
.. sectionauthor:: Guilherme Polo <ggpolo@gmail.com>
.. index:: single: ttk
The :mod:`ttk` module provides access to the Tk themed widget set, which has
been introduced in Tk 8.5. If Python is not compiled against Tk 8.5 code may
still use this module as long as Tile is installed. However, some features
provided by the new Tk, like anti-aliased font rendering under X11, window
transparency (on X11 you will need a composition window manager) will be
missing.
The basic idea of :mod:`ttk` is to separate, to the extent possible, the code
implementing a widget's behavior from the code implementing its appearance.
.. seealso::
`Tk Widget Styling Support <https://www.tcl.tk/cgi-bin/tct/tip/48>`_
The document which brought up theming support for Tk
Using Ttk
---------
To start using Ttk, import its module::
import ttk
But code like this::
from Tkinter import *
may optionally want to use this::
from Tkinter import *
from ttk import *
And then several :mod:`ttk` widgets (:class:`Button`, :class:`Checkbutton`,
:class:`Entry`, :class:`Frame`, :class:`Label`, :class:`LabelFrame`,
:class:`Menubutton`, :class:`PanedWindow`, :class:`Radiobutton`, :class:`Scale`
and :class:`Scrollbar`) will automatically substitute for the Tk widgets.
This has the direct benefit of using the new widgets, giving better look & feel
across platforms, but be aware that they are not totally compatible. The main
difference is that widget options such as "fg", "bg" and others related to
widget styling are no longer present in Ttk widgets. Use :class:`ttk.Style` to
achieve the same (or better) styling.
.. seealso::
`Converting existing applications to use the Tile widgets <http://tktable.sourceforge.net/tile/doc/converting.txt>`_
A text which talks in Tcl terms about differences typically found when
converting applications to use the new widgets.
Ttk Widgets
-----------
Ttk comes with 17 widgets, 11 of which already exist in Tkinter:
:class:`Button`, :class:`Checkbutton`, :class:`Entry`, :class:`Frame`,
:class:`Label`, :class:`LabelFrame`, :class:`Menubutton`,
:class:`PanedWindow`, :class:`Radiobutton`, :class:`Scale` and
:class:`Scrollbar`. The 6 new widget classes are: :class:`Combobox`,
:class:`Notebook`, :class:`Progressbar`, :class:`Separator`,
:class:`Sizegrip` and :class:`Treeview`. All of these classes are
subclasses of :class:`Widget`.
As said previously, you will notice changes in look-and-feel as well in the
styling code. To demonstrate the latter, a very simple example is shown below.
Tk code::
l1 = Tkinter.Label(text="Test", fg="black", bg="white")
l2 = Tkinter.Label(text="Test", fg="black", bg="white")
Corresponding Ttk code::
style = ttk.Style()
style.configure("BW.TLabel", foreground="black", background="white")
l1 = ttk.Label(text="Test", style="BW.TLabel")
l2 = ttk.Label(text="Test", style="BW.TLabel")
For more information about TtkStyling_ read the :class:`Style` class
documentation.
Widget
------
:class:`ttk.Widget` defines standard options and methods supported by Tk
themed widgets and is not supposed to be directly instantiated.
Standard Options
^^^^^^^^^^^^^^^^
All the :mod:`ttk` widgets accept the following options:
+-----------+--------------------------------------------------------------+
| Option | Description |
+===========+==============================================================+
| class | Specifies the window class. The class is used when querying |
| | the option database for the window's other options, to |
| | determine the default bindtags for the window, and to select |
| | the widget's default layout and style. This is a read-only |
| | option which may only be specified when the window is |
| | created. |
+-----------+--------------------------------------------------------------+
| cursor | Specifies the mouse cursor to be used for the widget. If set |
| | to the empty string (the default), the cursor is inherited |
| | from the parent widget. |
+-----------+--------------------------------------------------------------+
| takefocus | Determines whether the window accepts the focus during |
| | keyboard traversal. 0, 1 or an empty string is returned. |
| | If 0, the window should be skipped entirely |
| | during keyboard traversal. If 1, the window |
| | should receive the input focus as long as it is viewable. |
| | An empty string means that the traversal scripts make the |
| | decision about whether or not to focus on the window. |
+-----------+--------------------------------------------------------------+
| style | May be used to specify a custom widget style. |
+-----------+--------------------------------------------------------------+
Scrollable Widget Options
^^^^^^^^^^^^^^^^^^^^^^^^^
The following options are supported by widgets that are controlled by a
scrollbar.
+----------------+---------------------------------------------------------+
| option | description |
+================+=========================================================+
| xscrollcommand | Used to communicate with horizontal scrollbars. |
| | |
| | When the view in the widget's window changes, the widget|
| | will generate a Tcl command based on the scrollcommand. |
| | |
| | Usually this option consists of the |
| | :meth:`Scrollbar.set` method of some scrollbar. This |
| | will cause |
| | the scrollbar to be updated whenever the view in the |
| | window changes. |
+----------------+---------------------------------------------------------+
| yscrollcommand | Used to communicate with vertical scrollbars. |
| | For more information, see above. |
+----------------+---------------------------------------------------------+
Label Options
^^^^^^^^^^^^^
The following options are supported by labels, buttons and other button-like
widgets.
.. tabularcolumns:: |p{0.2\textwidth}|p{0.7\textwidth}|
..
+--------------+-----------------------------------------------------------+
| option | description |
+==============+===========================================================+
| text | Specifies a text string to be displayed inside the widget.|
+--------------+-----------------------------------------------------------+
| textvariable | Specifies a name whose value will be used in place of the |
| | text option resource. |
+--------------+-----------------------------------------------------------+
| underline | If set, specifies the index (0-based) of a character to |
| | underline in the text string. The underline character is |
| | used for mnemonic activation. |
+--------------+-----------------------------------------------------------+
| image | Specifies an image to display. This is a list of 1 or more|
| | elements. The first element is the default image name. The|
| | rest of the list is a sequence of statespec/value pairs as|
| | defined by :meth:`Style.map`, specifying different images |
| | to use when the widget is in a particular state or a |
| | combination of states. All images in the list should have |
| | the same size. |
+--------------+-----------------------------------------------------------+
| compound | Specifies how to display the image relative to the text, |
| | in the case both text and image options are present. |
| | Valid values are: |
| | |
| | * text: display text only |
| | * image: display image only |
| | * top, bottom, left, right: display image above, below, |
| | left of, or right of the text, respectively. |
| | * none: the default. display the image if present, |
| | otherwise the text. |
+--------------+-----------------------------------------------------------+
| width | If greater than zero, specifies how much space, in |
| | character widths, to allocate for the text label; if less |
| | than zero, specifies a minimum width. If zero or |
| | unspecified, the natural width of the text label is used. |
+--------------+-----------------------------------------------------------+
Compatibility Options
^^^^^^^^^^^^^^^^^^^^^
+--------+----------------------------------------------------------------+
| option | description |
+========+================================================================+
| state | May be set to "normal" or "disabled" to control the "disabled" |
| | state bit. This is a write-only option: setting it changes the |
| | widget state, but the :meth:`Widget.state` method does not |
| | affect this option. |
+--------+----------------------------------------------------------------+
Widget States
^^^^^^^^^^^^^
The widget state is a bitmap of independent state flags.
+------------+-------------------------------------------------------------+
| flag | description |
+============+=============================================================+
| active | The mouse cursor is over the widget and pressing a mouse |
| | button will cause some action to occur. |
+------------+-------------------------------------------------------------+
| disabled | Widget is disabled under program control. |
+------------+-------------------------------------------------------------+
| focus | Widget has keyboard focus. |
+------------+-------------------------------------------------------------+
| pressed | Widget is being pressed. |
+------------+-------------------------------------------------------------+
| selected | "On", "true", or "current" for things like Checkbuttons and |
| | radiobuttons. |
+------------+-------------------------------------------------------------+
| background | Windows and Mac have a notion of an "active" or foreground |
| | window. The *background* state is set for widgets in a |
| | background window, and cleared for those in the foreground |
| | window. |
+------------+-------------------------------------------------------------+
| readonly | Widget should not allow user modification. |
+------------+-------------------------------------------------------------+
| alternate | A widget-specific alternate display format. |
+------------+-------------------------------------------------------------+
| invalid | The widget's value is invalid. |
+------------+-------------------------------------------------------------+
A state specification is a sequence of state names, optionally prefixed with
an exclamation point indicating that the bit is off.
ttk.Widget
^^^^^^^^^^
Besides the methods described below, the :class:`ttk.Widget` class supports the
:meth:`Tkinter.Widget.cget` and :meth:`Tkinter.Widget.configure` methods.
.. class:: Widget
.. method:: identify(x, y)
Returns the name of the element at position *x* *y*, or the empty string
if the point does not lie within any element.
*x* and *y* are pixel coordinates relative to the widget.
.. method:: instate(statespec, callback=None, *args, **kw)
Test the widget's state. If a callback is not specified, returns ``True``
if the widget state matches *statespec* and ``False`` otherwise. If callback
is specified then it is called with *args* if widget state matches
*statespec*.
.. method:: state([statespec=None])
Modify or read widget state. If *statespec* is specified, sets the
widget state accordingly and returns a new *statespec* indicating
which flags were changed. If *statespec* is not specified, returns
the currently-enabled state flags.
*statespec* will usually be a list or a tuple.
Combobox
--------
The :class:`ttk.Combobox` widget combines a text field with a pop-down list of
values. This widget is a subclass of :class:`Entry`.
Besides the methods inherited from :class:`Widget` (:meth:`Widget.cget`,
:meth:`Widget.configure`, :meth:`Widget.identify`, :meth:`Widget.instate`
and :meth:`Widget.state`) and those inherited from :class:`Entry`
(:meth:`Entry.bbox`, :meth:`Entry.delete`, :meth:`Entry.icursor`,
:meth:`Entry.index`, :meth:`Entry.insert`, :meth:`Entry.selection`,
:meth:`Entry.xview`), this class has some other methods, described at
:class:`ttk.Combobox`.
Options
^^^^^^^
This widget accepts the following options:
+-----------------+--------------------------------------------------------+
| option | description |
+=================+========================================================+
| exportselection | Boolean value. If set, the widget selection is linked |
| | to the Window Manager selection (which can be returned |
| | by invoking :meth:`Misc.selection_get`, for example). |
+-----------------+--------------------------------------------------------+
| justify | Specifies how the text is aligned within the widget. |
| | One of "left", "center", or "right". |
+-----------------+--------------------------------------------------------+
| height | Specifies the height of the pop-down listbox, in rows. |
+-----------------+--------------------------------------------------------+
| postcommand | A script (possibly registered with |
| | :meth:`Misc.register`) that |
| | is called immediately before displaying the values. It |
| | may specify which values to display. |
+-----------------+--------------------------------------------------------+
| state | One of "normal", "readonly", or "disabled". In the |
| | "readonly" state, the value may not be edited directly,|
| | and the user can only select one of the values from the|
| | dropdown list. In the "normal" state, the text field is|
| | directly editable. In the "disabled" state, no |
| | interaction is possible. |
+-----------------+--------------------------------------------------------+
| textvariable | Specifies a name whose value is linked to the widget |
| | value. Whenever the value associated with that name |
| | changes, the widget value is updated, and vice versa. |
| | See :class:`Tkinter.StringVar`. |
+-----------------+--------------------------------------------------------+
| values | Specifies the list of values to display in the |
| | drop-down listbox. |
+-----------------+--------------------------------------------------------+
| width | Specifies an integer value indicating the desired width|
| | of the entry window, in average-size characters of the |
| | widget's font. |
+-----------------+--------------------------------------------------------+
Virtual events
^^^^^^^^^^^^^^
The combobox widget generates a **<<ComboboxSelected>>** virtual event
when the user selects an element from the list of values.
ttk.Combobox
^^^^^^^^^^^^
.. class:: Combobox
.. method:: current([newindex=None])
If *newindex* is specified, sets the combobox value to the element
position *newindex*. Otherwise, returns the index of the current value or
-1 if the current value is not in the values list.
.. method:: get()
Returns the current value of the combobox.
.. method:: set(value)
Sets the value of the combobox to *value*.
Notebook
--------
The Ttk Notebook widget manages a collection of windows and displays a single
one at a time. Each child window is associated with a tab, which the user
may select to change the currently-displayed window.
Options
^^^^^^^
This widget accepts the following specific options:
+---------+----------------------------------------------------------------+
| option | description |
+=========+================================================================+
| height | If present and greater than zero, specifies the desired height |
| | of the pane area (not including internal padding or tabs). |
| | Otherwise, the maximum height of all panes is used. |
+---------+----------------------------------------------------------------+
| padding | Specifies the amount of extra space to add around the outside |
| | of the notebook. The padding is a list of up to four length |
| | specifications: left top right bottom. If fewer than four |
| | elements are specified, bottom defaults to top, right defaults |
| | to left, and top defaults to left. |
+---------+----------------------------------------------------------------+
| width | If present and greater than zero, specifies the desired width |
| | of the pane area (not including internal padding). Otherwise, |
| | the maximum width of all panes is used. |
+---------+----------------------------------------------------------------+
Tab Options
^^^^^^^^^^^
There are also specific options for tabs:
+-----------+--------------------------------------------------------------+
| option | description |
+===========+==============================================================+
| state | Either "normal", "disabled" or "hidden". If "disabled", then |
| | the tab is not selectable. If "hidden", then the tab is not |
| | shown. |
+-----------+--------------------------------------------------------------+
| sticky | Specifies how the child window is positioned within the pane |
| | area. Value is a string containing zero or more of the |
| | characters "n", "s", "e" or "w". Each letter refers to a |
| | side (north, south, east or west) that the child window will |
| | stick to, as per the :meth:`grid` geometry manager. |
+-----------+--------------------------------------------------------------+
| padding | Specifies the amount of extra space to add between the |
| | notebook and this pane. Syntax is the same as for the option |
| | padding used by this widget. |
+-----------+--------------------------------------------------------------+
| text | Specifies a text to be displayed in the tab. |
+-----------+--------------------------------------------------------------+
| image | Specifies an image to display in the tab. See the option |
| | image described in :class:`Widget`. |
+-----------+--------------------------------------------------------------+
| compound | Specifies how to display the image relative to the text, in |
| | the case both text and image options are present. See |
| | `Label Options`_ for legal values. |
+-----------+--------------------------------------------------------------+
| underline | Specifies the index (0-based) of a character to underline in |
| | the text string. The underlined character is used for |
| | mnemonic activation if :meth:`Notebook.enable_traversal` is |
| | called. |
+-----------+--------------------------------------------------------------+
Tab Identifiers
^^^^^^^^^^^^^^^
The *tab_id* present in several methods of :class:`ttk.Notebook` may take any
of the following forms:
* An integer between zero and the number of tabs.
* The name of a child window.
* A positional specification of the form "@x,y", which identifies the tab.
* The literal string "current", which identifies the currently-selected tab.
* The literal string "end", which returns the number of tabs (only valid for
:meth:`Notebook.index`).
Virtual Events
^^^^^^^^^^^^^^
This widget generates a **<<NotebookTabChanged>>** virtual event after a new
tab is selected.
ttk.Notebook
^^^^^^^^^^^^
.. class:: Notebook
.. method:: add(child, **kw)
Adds a new tab to the notebook.
If window is currently managed by the notebook but hidden, it is
restored to its previous position.
See `Tab Options`_ for the list of available options.
.. method:: forget(tab_id)
Removes the tab specified by *tab_id*, unmaps and unmanages the
associated window.
.. method:: hide(tab_id)
Hides the tab specified by *tab_id*.
The tab will not be displayed, but the associated window remains
managed by the notebook and its configuration remembered. Hidden tabs
may be restored with the :meth:`add` command.
.. method:: identify(x, y)
Returns the name of the tab element at position *x*, *y*, or the empty
string if none.
.. method:: index(tab_id)
Returns the numeric index of the tab specified by *tab_id*, or the total
number of tabs if *tab_id* is the string "end".
.. method:: insert(pos, child, **kw)
Inserts a pane at the specified position.
*pos* is either the string "end", an integer index, or the name of a
managed child. If *child* is already managed by the notebook, moves it to
the specified position.
See `Tab Options`_ for the list of available options.
.. method:: select([tab_id])
Selects the specified *tab_id*.
The associated child window will be displayed, and the
previously-selected window (if different) is unmapped. If *tab_id* is
omitted, returns the widget name of the currently selected pane.
.. method:: tab(tab_id, option=None, **kw)
Query or modify the options of the specific *tab_id*.
If *kw* is not given, returns a dictionary of the tab option values. If
*option* is specified, returns the value of that *option*. Otherwise,
sets the options to the corresponding values.
.. method:: tabs()
Returns a list of windows managed by the notebook.
.. method:: enable_traversal()
Enable keyboard traversal for a toplevel window containing this notebook.
This will extend the bindings for the toplevel window containing the
notebook as follows:
* :kbd:`Control-Tab`: selects the tab following the currently selected one.
* :kbd:`Shift-Control-Tab`: selects the tab preceding the currently selected one.
* :kbd:`Alt-K`: where *K* is the mnemonic (underlined) character of any tab, will
select that tab.
Multiple notebooks in a single toplevel may be enabled for traversal,
including nested notebooks. However, notebook traversal only works
properly if all panes have the notebook they are in as master.
Progressbar
-----------
The :class:`ttk.Progressbar` widget shows the status of a long-running
operation. It can operate in two modes: determinate mode shows the amount
completed relative to the total amount of work to be done, and indeterminate
mode provides an animated display to let the user know that something is
happening.
Options
^^^^^^^
This widget accepts the following specific options:
+----------+---------------------------------------------------------------+
| option | description |
+==========+===============================================================+
| orient | One of "horizontal" or "vertical". Specifies the orientation |
| | of the progress bar. |
+----------+---------------------------------------------------------------+
| length | Specifies the length of the long axis of the progress bar |
| | (width if horizontal, height if vertical). |
+----------+---------------------------------------------------------------+
| mode | One of "determinate" or "indeterminate". |
+----------+---------------------------------------------------------------+
| maximum | A number specifying the maximum value. Defaults to 100. |
+----------+---------------------------------------------------------------+
| value | The current value of the progress bar. In "determinate" mode, |
| | this represents the amount of work completed. In |
| | "indeterminate" mode, it is interpreted as modulo *maximum*; |
| | that is, the progress bar completes one "cycle" when its value|
| | increases by *maximum*. |
+----------+---------------------------------------------------------------+
| variable | A name which is linked to the option value. If specified, the |
| | value of the progress bar is automatically set to the value of|
| | this name whenever the latter is modified. |
+----------+---------------------------------------------------------------+
| phase | Read-only option. The widget periodically increments the value|
| | of this option whenever its value is greater than 0 and, in |
| | determinate mode, less than maximum. This option may be used |
| | by the current theme to provide additional animation effects. |
+----------+---------------------------------------------------------------+
ttk.Progressbar
^^^^^^^^^^^^^^^
.. class:: Progressbar
.. method:: start([interval])
Begin autoincrement mode: schedules a recurring timer event that calls
:meth:`Progressbar.step` every *interval* milliseconds. If omitted,
*interval* defaults to 50 milliseconds.
.. method:: step([amount])
Increments the progress bar's value by *amount*.
*amount* defaults to 1.0 if omitted.
.. method:: stop()
Stop autoincrement mode: cancels any recurring timer event initiated by
:meth:`Progressbar.start` for this progress bar.
Separator
---------
The :class:`ttk.Separator` widget displays a horizontal or vertical separator
bar.
It has no other methods besides the ones inherited from :class:`ttk.Widget`.
Options
^^^^^^^
This widget accepts the following specific option:
+--------+----------------------------------------------------------------+
| option | description |
+========+================================================================+
| orient | One of "horizontal" or "vertical". Specifies the orientation of|
| | the separator. |
+--------+----------------------------------------------------------------+
Sizegrip
--------
The :class:`ttk.Sizegrip` widget (also known as a grow box) allows the user to
resize the containing toplevel window by pressing and dragging the grip.
This widget has neither specific options nor specific methods, besides the
ones inherited from :class:`ttk.Widget`.
Platform-specific notes
^^^^^^^^^^^^^^^^^^^^^^^
* On Mac OS X, toplevel windows automatically include a built-in size grip
by default. Adding a :class:`Sizegrip` is harmless, since the built-in
grip will just mask the widget.
Bugs
^^^^
* If the containing toplevel's position was specified relative to the right
or bottom of the screen (e.g. ....), the :class:`Sizegrip` widget will
not resize the window.
* This widget supports only "southeast" resizing.
Treeview
--------
The :class:`ttk.Treeview` widget displays a hierarchical collection of items.
Each item has a textual label, an optional image, and an optional list of data
values. The data values are displayed in successive columns after the tree
label.
The order in which data values are displayed may be controlled by setting
the widget option ``displaycolumns``. The tree widget can also display column
headings. Columns may be accessed by number or symbolic names listed in the
widget option columns. See `Column Identifiers`_.
Each item is identified by a unique name. The widget will generate item IDs
if they are not supplied by the caller. There is a distinguished root item,
named ``{}``. The root item itself is not displayed; its children appear at the
top level of the hierarchy.
Each item also has a list of tags, which can be used to associate event bindings
with individual items and control the appearance of the item.
The Treeview widget supports horizontal and vertical scrolling, according to
the options described in `Scrollable Widget Options`_ and the methods
:meth:`Treeview.xview` and :meth:`Treeview.yview`.
Options
^^^^^^^
This widget accepts the following specific options:
.. tabularcolumns:: |p{0.2\textwidth}|p{0.7\textwidth}|
..
+----------------+--------------------------------------------------------+
| option | description |
+================+========================================================+
| columns | A list of column identifiers, specifying the number of |
| | columns and their names. |
+----------------+--------------------------------------------------------+
| displaycolumns | A list of column identifiers (either symbolic or |
| | integer indices) specifying which data columns are |
| | displayed and the order in which they appear, or the |
| | string "#all". |
+----------------+--------------------------------------------------------+
| height | Specifies the number of rows which should be visible. |
| | Note: the requested width is determined from the sum |
| | of the column widths. |
+----------------+--------------------------------------------------------+
| padding | Specifies the internal padding for the widget. The |
| | padding is a list of up to four length specifications. |
+----------------+--------------------------------------------------------+
| selectmode | Controls how the built-in class bindings manage the |
| | selection. One of "extended", "browse" or "none". |
| | If set to "extended" (the default), multiple items may |
| | be selected. If "browse", only a single item will be |
| | selected at a time. If "none", the selection will not |
| | be changed. |
| | |
| | Note that the application code and tag bindings can set|
| | the selection however they wish, regardless of the |
| | value of this option. |
+----------------+--------------------------------------------------------+
| show | A list containing zero or more of the following values,|
| | specifying which elements of the tree to display. |
| | |
| | * tree: display tree labels in column #0. |
| | * headings: display the heading row. |
| | |
| | The default is "tree headings", i.e., show all |
| | elements. |
| | |
| | **Note**: Column #0 always refers to the tree column, |
| | even if show="tree" is not specified. |
+----------------+--------------------------------------------------------+
Item Options
^^^^^^^^^^^^
The following item options may be specified for items in the insert and item
widget commands.
+--------+---------------------------------------------------------------+
| option | description |
+========+===============================================================+
| text | The textual label to display for the item. |
+--------+---------------------------------------------------------------+
| image | A Tk Image, displayed to the left of the label. |
+--------+---------------------------------------------------------------+
| values | The list of values associated with the item. |
| | |
| | Each item should have the same number of values as the widget |
| | option columns. If there are fewer values than columns, the |
| | remaining values are assumed empty. If there are more values |
| | than columns, the extra values are ignored. |
+--------+---------------------------------------------------------------+
| open | True/False value indicating whether the item's children should|
| | be displayed or hidden. |
+--------+---------------------------------------------------------------+
| tags | A list of tags associated with this item. |
+--------+---------------------------------------------------------------+
Tag Options
^^^^^^^^^^^
The following options may be specified on tags:
+------------+-----------------------------------------------------------+
| option | description |
+============+===========================================================+
| foreground | Specifies the text foreground color. |
+------------+-----------------------------------------------------------+
| background | Specifies the cell or item background color. |
+------------+-----------------------------------------------------------+
| font | Specifies the font to use when drawing text. |
+------------+-----------------------------------------------------------+
| image | Specifies the item image, in case the item's image option |
| | is empty. |
+------------+-----------------------------------------------------------+
Column Identifiers
^^^^^^^^^^^^^^^^^^
Column identifiers take any of the following forms:
* A symbolic name from the list of columns option.
* An integer n, specifying the nth data column.
* A string of the form #n, where n is an integer, specifying the nth display
column.
Notes:
* Item's option values may be displayed in a different order than the order
in which they are stored.
* Column #0 always refers to the tree column, even if show="tree" is not
specified.
A data column number is an index into an item's option values list; a display
column number is the column number in the tree where the values are displayed.
Tree labels are displayed in column #0. If option displaycolumns is not set,
then data column n is displayed in column #n+1. Again, **column #0 always
refers to the tree column**.
Virtual Events
^^^^^^^^^^^^^^
The Treeview widget generates the following virtual events.
+--------------------+--------------------------------------------------+
| event | description |
+====================+==================================================+
| <<TreeviewSelect>> | Generated whenever the selection changes. |
+--------------------+--------------------------------------------------+
| <<TreeviewOpen>> | Generated just before settings the focus item to |
| | open=True. |
+--------------------+--------------------------------------------------+
| <<TreeviewClose>> | Generated just after setting the focus item to |
| | open=False. |
+--------------------+--------------------------------------------------+
The :meth:`Treeview.focus` and :meth:`Treeview.selection` methods can be used
to determine the affected item or items.
ttk.Treeview
^^^^^^^^^^^^
.. class:: Treeview
.. method:: bbox(item, column=None)
Returns the bounding box (relative to the treeview widget's window) of
the specified *item* in the form (x, y, width, height).
If *column* is specified, returns the bounding box of that cell. If the
*item* is not visible (i.e., if it is a descendant of a closed item or is
scrolled offscreen), returns an empty string.
.. method:: get_children([item])
Returns the list of children belonging to *item*.
If *item* is not specified, returns root children.
.. method:: set_children(item, *newchildren)
Replaces *item*'s child with *newchildren*.
Children present in *item* that are not present in *newchildren* are
detached from the tree. No items in *newchildren* may be an ancestor of
*item*. Note that not specifying *newchildren* results in detaching
*item*'s children.
.. method:: column(column, option=None, **kw)
Query or modify the options for the specified *column*.
If *kw* is not given, returns a dict of the column option values. If
*option* is specified then the value for that *option* is returned.
Otherwise, sets the options to the corresponding values.
The valid options/values are:
* id
Returns the column name. This is a read-only option.
* anchor: One of the standard Tk anchor values.
Specifies how the text in this column should be aligned with respect
to the cell.
* minwidth: width
The minimum width of the column in pixels. The treeview widget will
not make the column any smaller than specified by this option when
the widget is resized or the user drags a column.
* stretch: True/False
Specifies whether the column's width should be adjusted when
the widget is resized.
* width: width
The width of the column in pixels.
To configure the tree column, call this with column = "#0"
.. method:: delete(*items)
Delete all specified *items* and all their descendants.
The root item may not be deleted.
.. method:: detach(*items)
Unlinks all of the specified *items* from the tree.
The items and all of their descendants are still present, and may be
reinserted at another point in the tree, but will not be displayed.
The root item may not be detached.
.. method:: exists(item)
Returns ``True`` if the specified *item* is present in the tree.
.. method:: focus([item=None])
If *item* is specified, sets the focus item to *item*. Otherwise, returns
the current focus item, or '' if there is none.
.. method:: heading(column, option=None, **kw)
Query or modify the heading options for the specified *column*.
If *kw* is not given, returns a dict of the heading option values. If
*option* is specified then the value for that *option* is returned.
Otherwise, sets the options to the corresponding values.
The valid options/values are:
* text: text
The text to display in the column heading.
* image: imageName
Specifies an image to display to the right of the column heading.
* anchor: anchor
Specifies how the heading text should be aligned. One of the standard
Tk anchor values.
* command: callback
A callback to be invoked when the heading label is pressed.
To configure the tree column heading, call this with column = "#0".
.. method:: identify(component, x, y)
Returns a description of the specified *component* under the point given
by *x* and *y*, or the empty string if no such *component* is present at
that position.
.. method:: identify_row(y)
Returns the item ID of the item at position *y*.
.. method:: identify_column(x)
Returns the data column identifier of the cell at position *x*.
The tree column has ID #0.
.. method:: identify_region(x, y)
Returns one of:
+-----------+--------------------------------------+
| region | meaning |
+===========+======================================+
| heading | Tree heading area. |
+-----------+--------------------------------------+
| separator | Space between two columns headings. |
+-----------+--------------------------------------+
| tree | The tree area. |
+-----------+--------------------------------------+
| cell | A data cell. |
+-----------+--------------------------------------+
Availability: Tk 8.6.
.. method:: identify_element(x, y)
Returns the element at position *x*, *y*.
Availability: Tk 8.6.
.. method:: index(item)
Returns the integer index of *item* within its parent's list of children.
.. method:: insert(parent, index, iid=None, **kw)
Creates a new item and returns the item identifier of the newly created
item.
*parent* is the item ID of the parent item, or the empty string to create
a new top-level item. *index* is an integer, or the value "end",
specifying where in the list of parent's children to insert the new item.
If *index* is less than or equal to zero, the new node is inserted at
the beginning; if *index* is greater than or equal to the current number
of children, it is inserted at the end. If *iid* is specified, it is used
as the item identifier; *iid* must not already exist in the tree.
Otherwise, a new unique identifier is generated.
See `Item Options`_ for the list of available points.
.. method:: item(item[, option[, **kw]])
Query or modify the options for the specified *item*.
If no options are given, a dict with options/values for the item is
returned.
If *option* is specified then the value for that option is returned.
Otherwise, sets the options to the corresponding values as given by *kw*.
.. method:: move(item, parent, index)
Moves *item* to position *index* in *parent*'s list of children.
It is illegal to move an item under one of its descendants. If *index* is
less than or equal to zero, *item* is moved to the beginning; if greater
than or equal to the number of children, it is moved to the end. If *item*
was detached it is reattached.
.. method:: next(item)
Returns the identifier of *item*'s next sibling, or '' if *item* is the
last child of its parent.
.. method:: parent(item)
Returns the ID of the parent of *item*, or '' if *item* is at the top
level of the hierarchy.
.. method:: prev(item)
Returns the identifier of *item*'s previous sibling, or '' if *item* is
the first child of its parent.
.. method:: reattach(item, parent, index)
An alias for :meth:`Treeview.move`.
.. method:: see(item)
Ensure that *item* is visible.
Sets all of *item*'s ancestors open option to ``True``, and scrolls the
widget if necessary so that *item* is within the visible portion of
the tree.
.. method:: selection([selop=None[, items=None]])
If *selop* is not specified, returns selected items. Otherwise, it will
act according to the following selection methods.
.. method:: selection_set(items)
*items* becomes the new selection.
.. method:: selection_add(items)
Add *items* to the selection.
.. method:: selection_remove(items)
Remove *items* from the selection.
.. method:: selection_toggle(items)
Toggle the selection state of each item in *items*.
.. method:: set(item, column=None, value=None)
With one argument, returns a dictionary of column/value pairs for the
specified *item*. With two arguments, returns the current value of the
specified *column*. With three arguments, sets the value of given
*column* in given *item* to the specified *value*.
.. method:: tag_bind(tagname, sequence=None, callback=None)
Bind a callback for the given event *sequence* to the tag *tagname*.
When an event is delivered to an item, the callbacks for each of the
item's tags option are called.
.. method:: tag_configure(tagname, option=None, **kw)
Query or modify the options for the specified *tagname*.
If *kw* is not given, returns a dict of the option settings for
*tagname*. If *option* is specified, returns the value for that *option*
for the specified *tagname*. Otherwise, sets the options to the
corresponding values for the given *tagname*.
.. method:: tag_has(tagname[, item])
If *item* is specified, returns 1 or 0 depending on whether the specified
*item* has the given *tagname*. Otherwise, returns a list of all items
that have the specified tag.
Availability: Tk 8.6
.. method:: xview(*args)
Query or modify horizontal position of the treeview.
.. method:: yview(*args)
Query or modify vertical position of the treeview.
.. _TtkStyling:
Ttk Styling
-----------
Each widget in :mod:`ttk` is assigned a style, which specifies the set of
elements making up the widget and how they are arranged, along with dynamic and
default settings for element options. By default the style name is the same as
the widget's class name, but it may be overridden by the widget's style
option. If the class name of a widget is unknown, use the method
:meth:`Misc.winfo_class` (somewidget.winfo_class()).
.. seealso::
`Tcl'2004 conference presentation <http://tktable.sourceforge.net/tile/tile-tcl2004.pdf>`_
This document explains how the theme engine works
.. class:: Style
This class is used to manipulate the style database.
.. method:: configure(style, query_opt=None, **kw)
Query or set the default value of the specified option(s) in *style*.
Each key in *kw* is an option and each value is a string identifying
the value for that option.
For example, to change every default button to be a flat button with some
padding and a different background color do::
import ttk
import Tkinter
root = Tkinter.Tk()
ttk.Style().configure("TButton", padding=6, relief="flat",
background="#ccc")
btn = ttk.Button(text="Sample")
btn.pack()
root.mainloop()
.. method:: map(style, query_opt=None, **kw)
Query or sets dynamic values of the specified option(s) in *style*.
Each key in *kw* is an option and each value should be a list or a
tuple (usually) containing statespecs grouped in tuples, lists, or
something else of your preference. A statespec is a compound of one
or more states and then a value.
An example::
import Tkinter
import ttk
root = Tkinter.Tk()
style = ttk.Style()
style.map("C.TButton",
foreground=[('pressed', 'red'), ('active', 'blue')],
background=[('pressed', '!disabled', 'black'), ('active', 'white')]
)
colored_btn = ttk.Button(text="Test", style="C.TButton").pack()
root.mainloop()
Note that the order of the (states, value) sequences for an
option matters. In the previous example, if you change the
order to ``[('active', 'blue'), ('pressed', 'red')]`` in the
foreground option, for example, you would get a blue foreground
when the widget is in the active or pressed states.
.. method:: lookup(style, option, state=None, default=None)
Returns the value specified for *option* in *style*.
If *state* is specified, it is expected to be a sequence of one or more
states. If the *default* argument is set, it is used as a fallback value
in case no specification for option is found.
To check what font a Button uses by default, do::
import ttk
print ttk.Style().lookup("TButton", "font")
.. method:: layout(style, layoutspec=None)
Define the widget layout for given *style*. If *layoutspec* is omitted,
return the layout specification for given style.
*layoutspec*, if specified, is expected to be a list or some other
sequence type (excluding strings), where each item should be a tuple and
the first item is the layout name and the second item should have the
format described in `Layouts`_.
To understand the format, see the following example (it is not
intended to do anything useful)::
import ttk
import Tkinter
root = Tkinter.Tk()
style = ttk.Style()
style.layout("TMenubutton", [
("Menubutton.background", None),
("Menubutton.button", {"children":
[("Menubutton.focus", {"children":
[("Menubutton.padding", {"children":
[("Menubutton.label", {"side": "left", "expand": 1})]
})]
})]
}),
])
mbtn = ttk.Menubutton(text='Text')
mbtn.pack()
root.mainloop()
.. method:: element_create(elementname, etype, *args, **kw)
Create a new element in the current theme, of the given *etype* which is
expected to be either "image", "from" or "vsapi". The latter is only
available in Tk 8.6a for Windows XP and Vista and is not described here.
If "image" is used, *args* should contain the default image name followed
by statespec/value pairs (this is the imagespec), and *kw* may have the
following options:
* border=padding
padding is a list of up to four integers, specifying the left, top,
right, and bottom borders, respectively.
* height=height
Specifies a minimum height for the element. If less than zero, the
base image's height is used as a default.
* padding=padding
Specifies the element's interior padding. Defaults to border's value
if not specified.
* sticky=spec
Specifies how the image is placed within the final parcel. spec
contains zero or more characters "n", "s", "w", or "e".
* width=width
Specifies a minimum width for the element. If less than zero, the
base image's width is used as a default.
If "from" is used as the value of *etype*,
:meth:`element_create` will clone an existing
element. *args* is expected to contain a themename, from which
the element will be cloned, and optionally an element to clone from.
If this element to clone from is not specified, an empty element will
be used. *kw* is discarded.
.. method:: element_names()
Returns the list of elements defined in the current theme.
.. method:: element_options(elementname)
Returns the list of *elementname*'s options.
.. method:: theme_create(themename, parent=None, settings=None)
Create a new theme.
It is an error if *themename* already exists. If *parent* is specified,
the new theme will inherit styles, elements and layouts from the parent
theme. If *settings* are present they are expected to have the same
syntax used for :meth:`theme_settings`.
.. method:: theme_settings(themename, settings)
Temporarily sets the current theme to *themename*, apply specified
*settings* and then restore the previous theme.
Each key in *settings* is a style and each value may contain the keys
'configure', 'map', 'layout' and 'element create' and they are expected
to have the same format as specified by the methods
:meth:`Style.configure`, :meth:`Style.map`, :meth:`Style.layout` and
:meth:`Style.element_create` respectively.
As an example, let's change the Combobox for the default theme a bit::
import ttk
import Tkinter
root = Tkinter.Tk()
style = ttk.Style()
style.theme_settings("default", {
"TCombobox": {
"configure": {"padding": 5},
"map": {
"background": [("active", "green2"),
("!disabled", "green4")],
"fieldbackground": [("!disabled", "green3")],
"foreground": [("focus", "OliveDrab1"),
("!disabled", "OliveDrab2")]
}
}
})
combo = ttk.Combobox().pack()
root.mainloop()
.. method:: theme_names()
Returns a list of all known themes.
.. method:: theme_use([themename])
If *themename* is not given, returns the theme in use. Otherwise, sets
the current theme to *themename*, refreshes all widgets and emits a
<<ThemeChanged>> event.
Layouts
^^^^^^^
A layout can be just ``None``, if it takes no options, or a dict of
options specifying how to arrange the element. The layout mechanism
uses a simplified version of the pack geometry manager: given an
initial cavity, each element is allocated a parcel. Valid
options/values are:
* side: whichside
Specifies which side of the cavity to place the element; one of
top, right, bottom or left. If omitted, the element occupies the
entire cavity.
* sticky: nswe
Specifies where the element is placed inside its allocated parcel.
* unit: 0 or 1
If set to 1, causes the element and all of its descendants to be treated as
a single element for the purposes of :meth:`Widget.identify` et al. It's
used for things like scrollbar thumbs with grips.
* children: [sublayout... ]
Specifies a list of elements to place inside the element. Each
element is a tuple (or other sequence type) where the first item is
the layout name, and the other is a `Layout`_.
.. _Layout: `Layouts`_
PK
%�\M��T� � ! html/_sources/library/tty.rst.txtnu �[���
:mod:`tty` --- Terminal control functions
=========================================
.. module:: tty
:platform: Unix
:synopsis: Utility functions that perform common terminal control operations.
.. moduleauthor:: Steen Lumholt
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
The :mod:`tty` module defines functions for putting the tty into cbreak and raw
modes.
Because it requires the :mod:`termios` module, it will work only on Unix.
The :mod:`tty` module defines the following functions:
.. function:: setraw(fd[, when])
Change the mode of the file descriptor *fd* to raw. If *when* is omitted, it
defaults to :const:`termios.TCSAFLUSH`, and is passed to
:func:`termios.tcsetattr`.
.. function:: setcbreak(fd[, when])
Change the mode of file descriptor *fd* to cbreak. If *when* is omitted, it
defaults to :const:`termios.TCSAFLUSH`, and is passed to
:func:`termios.tcsetattr`.
.. seealso::
Module :mod:`termios`
Low-level terminal control interface.
PK
%�\h� a� a� $ html/_sources/library/turtle.rst.txtnu �[��� ========================================
:mod:`turtle` --- Turtle graphics for Tk
========================================
.. module:: turtle
:synopsis: Turtle graphics for Tk
.. sectionauthor:: Gregor Lingl <gregor.lingl@aon.at>
.. testsetup:: default
from turtle import *
turtle = Turtle()
Introduction
============
Turtle graphics is a popular way for introducing programming to kids. It was
part of the original Logo programming language developed by Wally Feurzig and
Seymour Papert in 1966.
Imagine a robotic turtle starting at (0, 0) in the x-y plane. After an ``import turtle``, give it the
command ``turtle.forward(15)``, and it moves (on-screen!) 15 pixels in the
direction it is facing, drawing a line as it moves. Give it the command
``turtle.right(25)``, and it rotates in-place 25 degrees clockwise.
By combining together these and similar commands, intricate shapes and pictures
can easily be drawn.
The :mod:`turtle` module is an extended reimplementation of the same-named
module from the Python standard distribution up to version Python 2.5.
It tries to keep the merits of the old turtle module and to be (nearly) 100%
compatible with it. This means in the first place to enable the learning
programmer to use all the commands, classes and methods interactively when using
the module from within IDLE run with the ``-n`` switch.
The turtle module provides turtle graphics primitives, in both object-oriented
and procedure-oriented ways. Because it uses :mod:`Tkinter` for the underlying
graphics, it needs a version of Python installed with Tk support.
The object-oriented interface uses essentially two+two classes:
1. The :class:`TurtleScreen` class defines graphics windows as a playground for
the drawing turtles. Its constructor needs a :class:`Tkinter.Canvas` or a
:class:`ScrolledCanvas` as argument. It should be used when :mod:`turtle` is
used as part of some application.
The function :func:`Screen` returns a singleton object of a
:class:`TurtleScreen` subclass. This function should be used when
:mod:`turtle` is used as a standalone tool for doing graphics.
As a singleton object, inheriting from its class is not possible.
All methods of TurtleScreen/Screen also exist as functions, i.e. as part of
the procedure-oriented interface.
2. :class:`RawTurtle` (alias: :class:`RawPen`) defines Turtle objects which draw
on a :class:`TurtleScreen`. Its constructor needs a Canvas, ScrolledCanvas
or TurtleScreen as argument, so the RawTurtle objects know where to draw.
Derived from RawTurtle is the subclass :class:`Turtle` (alias: :class:`Pen`),
which draws on "the" :class:`Screen` - instance which is automatically
created, if not already present.
All methods of RawTurtle/Turtle also exist as functions, i.e. part of the
procedure-oriented interface.
The procedural interface provides functions which are derived from the methods
of the classes :class:`Screen` and :class:`Turtle`. They have the same names as
the corresponding methods. A screen object is automatically created whenever a
function derived from a Screen method is called. An (unnamed) turtle object is
automatically created whenever any of the functions derived from a Turtle method
is called.
To use multiple turtles an a screen one has to use the object-oriented interface.
.. note::
In the following documentation the argument list for functions is given.
Methods, of course, have the additional first argument *self* which is
omitted here.
Overview over available Turtle and Screen methods
=================================================
Turtle methods
--------------
Turtle motion
Move and draw
| :func:`forward` | :func:`fd`
| :func:`backward` | :func:`bk` | :func:`back`
| :func:`right` | :func:`rt`
| :func:`left` | :func:`lt`
| :func:`goto` | :func:`setpos` | :func:`setposition`
| :func:`setx`
| :func:`sety`
| :func:`setheading` | :func:`seth`
| :func:`home`
| :func:`circle`
| :func:`dot`
| :func:`stamp`
| :func:`clearstamp`
| :func:`clearstamps`
| :func:`undo`
| :func:`speed`
Tell Turtle's state
| :func:`position` | :func:`pos`
| :func:`towards`
| :func:`xcor`
| :func:`ycor`
| :func:`heading`
| :func:`distance`
Setting and measurement
| :func:`degrees`
| :func:`radians`
Pen control
Drawing state
| :func:`pendown` | :func:`pd` | :func:`down`
| :func:`penup` | :func:`pu` | :func:`up`
| :func:`pensize` | :func:`width`
| :func:`pen`
| :func:`isdown`
Color control
| :func:`color`
| :func:`pencolor`
| :func:`fillcolor`
Filling
| :func:`fill`
| :func:`begin_fill`
| :func:`end_fill`
More drawing control
| :func:`reset`
| :func:`clear`
| :func:`write`
Turtle state
Visibility
| :func:`showturtle` | :func:`st`
| :func:`hideturtle` | :func:`ht`
| :func:`isvisible`
Appearance
| :func:`shape`
| :func:`resizemode`
| :func:`shapesize` | :func:`turtlesize`
| :func:`settiltangle`
| :func:`tiltangle`
| :func:`tilt`
Using events
| :func:`onclick`
| :func:`onrelease`
| :func:`ondrag`
| :func:`mainloop` | :func:`done`
Special Turtle methods
| :func:`begin_poly`
| :func:`end_poly`
| :func:`get_poly`
| :func:`clone`
| :func:`getturtle` | :func:`getpen`
| :func:`getscreen`
| :func:`setundobuffer`
| :func:`undobufferentries`
| :func:`tracer`
| :func:`window_width`
| :func:`window_height`
Methods of TurtleScreen/Screen
------------------------------
Window control
| :func:`bgcolor`
| :func:`bgpic`
| :func:`clear` | :func:`clearscreen`
| :func:`reset` | :func:`resetscreen`
| :func:`screensize`
| :func:`setworldcoordinates`
Animation control
| :func:`delay`
| :func:`tracer`
| :func:`update`
Using screen events
| :func:`listen`
| :func:`onkey`
| :func:`onclick` | :func:`onscreenclick`
| :func:`ontimer`
Settings and special methods
| :func:`mode`
| :func:`colormode`
| :func:`getcanvas`
| :func:`getshapes`
| :func:`register_shape` | :func:`addshape`
| :func:`turtles`
| :func:`window_height`
| :func:`window_width`
Methods specific to Screen
| :func:`bye`
| :func:`exitonclick`
| :func:`setup`
| :func:`title`
Methods of RawTurtle/Turtle and corresponding functions
=======================================================
Most of the examples in this section refer to a Turtle instance called
``turtle``.
Turtle motion
-------------
.. function:: forward(distance)
fd(distance)
:param distance: a number (integer or float)
Move the turtle forward by the specified *distance*, in the direction the
turtle is headed.
.. doctest::
>>> turtle.position()
(0.00,0.00)
>>> turtle.forward(25)
>>> turtle.position()
(25.00,0.00)
>>> turtle.forward(-75)
>>> turtle.position()
(-50.00,0.00)
.. function:: back(distance)
bk(distance)
backward(distance)
:param distance: a number
Move the turtle backward by *distance*, opposite to the direction the
turtle is headed. Do not change the turtle's heading.
.. doctest::
:hide:
>>> turtle.goto(0, 0)
.. doctest::
>>> turtle.position()
(0.00,0.00)
>>> turtle.backward(30)
>>> turtle.position()
(-30.00,0.00)
.. function:: right(angle)
rt(angle)
:param angle: a number (integer or float)
Turn turtle right by *angle* units. (Units are by default degrees, but
can be set via the :func:`degrees` and :func:`radians` functions.) Angle
orientation depends on the turtle mode, see :func:`mode`.
.. doctest::
:hide:
>>> turtle.setheading(22)
.. doctest::
>>> turtle.heading()
22.0
>>> turtle.right(45)
>>> turtle.heading()
337.0
.. function:: left(angle)
lt(angle)
:param angle: a number (integer or float)
Turn turtle left by *angle* units. (Units are by default degrees, but
can be set via the :func:`degrees` and :func:`radians` functions.) Angle
orientation depends on the turtle mode, see :func:`mode`.
.. doctest::
:hide:
>>> turtle.setheading(22)
.. doctest::
>>> turtle.heading()
22.0
>>> turtle.left(45)
>>> turtle.heading()
67.0
.. function:: goto(x, y=None)
setpos(x, y=None)
setposition(x, y=None)
:param x: a number or a pair/vector of numbers
:param y: a number or ``None``
If *y* is ``None``, *x* must be a pair of coordinates or a :class:`Vec2D`
(e.g. as returned by :func:`pos`).
Move turtle to an absolute position. If the pen is down, draw line. Do
not change the turtle's orientation.
.. doctest::
:hide:
>>> turtle.goto(0, 0)
.. doctest::
>>> tp = turtle.pos()
>>> tp
(0.00,0.00)
>>> turtle.setpos(60,30)
>>> turtle.pos()
(60.00,30.00)
>>> turtle.setpos((20,80))
>>> turtle.pos()
(20.00,80.00)
>>> turtle.setpos(tp)
>>> turtle.pos()
(0.00,0.00)
.. function:: setx(x)
:param x: a number (integer or float)
Set the turtle's first coordinate to *x*, leave second coordinate
unchanged.
.. doctest::
:hide:
>>> turtle.goto(0, 240)
.. doctest::
>>> turtle.position()
(0.00,240.00)
>>> turtle.setx(10)
>>> turtle.position()
(10.00,240.00)
.. function:: sety(y)
:param y: a number (integer or float)
Set the turtle's second coordinate to *y*, leave first coordinate unchanged.
.. doctest::
:hide:
>>> turtle.goto(0, 40)
.. doctest::
>>> turtle.position()
(0.00,40.00)
>>> turtle.sety(-10)
>>> turtle.position()
(0.00,-10.00)
.. function:: setheading(to_angle)
seth(to_angle)
:param to_angle: a number (integer or float)
Set the orientation of the turtle to *to_angle*. Here are some common
directions in degrees:
=================== ====================
standard mode logo mode
=================== ====================
0 - east 0 - north
90 - north 90 - east
180 - west 180 - south
270 - south 270 - west
=================== ====================
.. doctest::
>>> turtle.setheading(90)
>>> turtle.heading()
90.0
.. function:: home()
Move turtle to the origin -- coordinates (0,0) -- and set its heading to
its start-orientation (which depends on the mode, see :func:`mode`).
.. doctest::
:hide:
>>> turtle.setheading(90)
>>> turtle.goto(0, -10)
.. doctest::
>>> turtle.heading()
90.0
>>> turtle.position()
(0.00,-10.00)
>>> turtle.home()
>>> turtle.position()
(0.00,0.00)
>>> turtle.heading()
0.0
.. function:: circle(radius, extent=None, steps=None)
:param radius: a number
:param extent: a number (or ``None``)
:param steps: an integer (or ``None``)
Draw a circle with given *radius*. The center is *radius* units left of
the turtle; *extent* -- an angle -- determines which part of the circle
is drawn. If *extent* is not given, draw the entire circle. If *extent*
is not a full circle, one endpoint of the arc is the current pen
position. Draw the arc in counterclockwise direction if *radius* is
positive, otherwise in clockwise direction. Finally the direction of the
turtle is changed by the amount of *extent*.
As the circle is approximated by an inscribed regular polygon, *steps*
determines the number of steps to use. If not given, it will be
calculated automatically. May be used to draw regular polygons.
.. doctest::
>>> turtle.home()
>>> turtle.position()
(0.00,0.00)
>>> turtle.heading()
0.0
>>> turtle.circle(50)
>>> turtle.position()
(-0.00,0.00)
>>> turtle.heading()
0.0
>>> turtle.circle(120, 180) # draw a semicircle
>>> turtle.position()
(0.00,240.00)
>>> turtle.heading()
180.0
.. function:: dot(size=None, *color)
:param size: an integer >= 1 (if given)
:param color: a colorstring or a numeric color tuple
Draw a circular dot with diameter *size*, using *color*. If *size* is
not given, the maximum of pensize+4 and 2*pensize is used.
.. doctest::
>>> turtle.home()
>>> turtle.dot()
>>> turtle.fd(50); turtle.dot(20, "blue"); turtle.fd(50)
>>> turtle.position()
(100.00,-0.00)
>>> turtle.heading()
0.0
.. function:: stamp()
Stamp a copy of the turtle shape onto the canvas at the current turtle
position. Return a stamp_id for that stamp, which can be used to delete
it by calling ``clearstamp(stamp_id)``.
.. doctest::
>>> turtle.color("blue")
>>> turtle.stamp()
11
>>> turtle.fd(50)
.. function:: clearstamp(stampid)
:param stampid: an integer, must be return value of previous
:func:`stamp` call
Delete stamp with given *stampid*.
.. doctest::
>>> turtle.position()
(150.00,-0.00)
>>> turtle.color("blue")
>>> astamp = turtle.stamp()
>>> turtle.fd(50)
>>> turtle.position()
(200.00,-0.00)
>>> turtle.clearstamp(astamp)
>>> turtle.position()
(200.00,-0.00)
.. function:: clearstamps(n=None)
:param n: an integer (or ``None``)
Delete all or first/last *n* of turtle's stamps. If *n* is ``None``, delete
all stamps, if *n* > 0 delete first *n* stamps, else if *n* < 0 delete
last *n* stamps.
.. doctest::
>>> for i in range(8):
... turtle.stamp(); turtle.fd(30)
13
14
15
16
17
18
19
20
>>> turtle.clearstamps(2)
>>> turtle.clearstamps(-2)
>>> turtle.clearstamps()
.. function:: undo()
Undo (repeatedly) the last turtle action(s). Number of available
undo actions is determined by the size of the undobuffer.
.. doctest::
>>> for i in range(4):
... turtle.fd(50); turtle.lt(80)
...
>>> for i in range(8):
... turtle.undo()
.. function:: speed(speed=None)
:param speed: an integer in the range 0..10 or a speedstring (see below)
Set the turtle's speed to an integer value in the range 0..10. If no
argument is given, return current speed.
If input is a number greater than 10 or smaller than 0.5, speed is set
to 0. Speedstrings are mapped to speedvalues as follows:
* "fastest": 0
* "fast": 10
* "normal": 6
* "slow": 3
* "slowest": 1
Speeds from 1 to 10 enforce increasingly faster animation of line drawing
and turtle turning.
Attention: *speed* = 0 means that *no* animation takes
place. forward/back makes turtle jump and likewise left/right make the
turtle turn instantly.
.. doctest::
>>> turtle.speed()
3
>>> turtle.speed('normal')
>>> turtle.speed()
6
>>> turtle.speed(9)
>>> turtle.speed()
9
Tell Turtle's state
-------------------
.. function:: position()
pos()
Return the turtle's current location (x,y) (as a :class:`Vec2D` vector).
.. doctest::
>>> turtle.pos()
(440.00,-0.00)
.. function:: towards(x, y=None)
:param x: a number or a pair/vector of numbers or a turtle instance
:param y: a number if *x* is a number, else ``None``
Return the angle between the line from turtle position to position specified
by (x,y), the vector or the other turtle. This depends on the turtle's start
orientation which depends on the mode - "standard"/"world" or "logo").
.. doctest::
>>> turtle.goto(10, 10)
>>> turtle.towards(0,0)
225.0
.. function:: xcor()
Return the turtle's x coordinate.
.. doctest::
>>> turtle.home()
>>> turtle.left(50)
>>> turtle.forward(100)
>>> turtle.pos()
(64.28,76.60)
>>> print turtle.xcor()
64.2787609687
.. function:: ycor()
Return the turtle's y coordinate.
.. doctest::
>>> turtle.home()
>>> turtle.left(60)
>>> turtle.forward(100)
>>> print turtle.pos()
(50.00,86.60)
>>> print turtle.ycor()
86.6025403784
.. function:: heading()
Return the turtle's current heading (value depends on the turtle mode, see
:func:`mode`).
.. doctest::
>>> turtle.home()
>>> turtle.left(67)
>>> turtle.heading()
67.0
.. function:: distance(x, y=None)
:param x: a number or a pair/vector of numbers or a turtle instance
:param y: a number if *x* is a number, else ``None``
Return the distance from the turtle to (x,y), the given vector, or the given
other turtle, in turtle step units.
.. doctest::
>>> turtle.home()
>>> turtle.distance(30,40)
50.0
>>> turtle.distance((30,40))
50.0
>>> joe = Turtle()
>>> joe.forward(77)
>>> turtle.distance(joe)
77.0
Settings for measurement
------------------------
.. function:: degrees(fullcircle=360.0)
:param fullcircle: a number
Set angle measurement units, i.e. set number of "degrees" for a full circle.
Default value is 360 degrees.
.. doctest::
>>> turtle.home()
>>> turtle.left(90)
>>> turtle.heading()
90.0
Change angle measurement unit to grad (also known as gon,
grade, or gradian and equals 1/100-th of the right angle.)
>>> turtle.degrees(400.0)
>>> turtle.heading()
100.0
>>> turtle.degrees(360)
>>> turtle.heading()
90.0
.. function:: radians()
Set the angle measurement units to radians. Equivalent to
``degrees(2*math.pi)``.
.. doctest::
>>> turtle.home()
>>> turtle.left(90)
>>> turtle.heading()
90.0
>>> turtle.radians()
>>> turtle.heading()
1.5707963267948966
.. doctest::
:hide:
>>> turtle.degrees(360)
Pen control
-----------
Drawing state
~~~~~~~~~~~~~
.. function:: pendown()
pd()
down()
Pull the pen down -- drawing when moving.
.. function:: penup()
pu()
up()
Pull the pen up -- no drawing when moving.
.. function:: pensize(width=None)
width(width=None)
:param width: a positive number
Set the line thickness to *width* or return it. If resizemode is set to
"auto" and turtleshape is a polygon, that polygon is drawn with the same line
thickness. If no argument is given, the current pensize is returned.
.. doctest::
>>> turtle.pensize()
1
>>> turtle.pensize(10) # from here on lines of width 10 are drawn
.. function:: pen(pen=None, **pendict)
:param pen: a dictionary with some or all of the below listed keys
:param pendict: one or more keyword-arguments with the below listed keys as keywords
Return or set the pen's attributes in a "pen-dictionary" with the following
key/value pairs:
* "shown": True/False
* "pendown": True/False
* "pencolor": color-string or color-tuple
* "fillcolor": color-string or color-tuple
* "pensize": positive number
* "speed": number in range 0..10
* "resizemode": "auto" or "user" or "noresize"
* "stretchfactor": (positive number, positive number)
* "outline": positive number
* "tilt": number
This dictionary can be used as argument for a subsequent call to :func:`pen`
to restore the former pen-state. Moreover one or more of these attributes
can be provided as keyword-arguments. This can be used to set several pen
attributes in one statement.
.. doctest::
:options: +NORMALIZE_WHITESPACE
>>> turtle.pen(fillcolor="black", pencolor="red", pensize=10)
>>> sorted(turtle.pen().items())
[('fillcolor', 'black'), ('outline', 1), ('pencolor', 'red'),
('pendown', True), ('pensize', 10), ('resizemode', 'noresize'),
('shown', True), ('speed', 9), ('stretchfactor', (1, 1)), ('tilt', 0)]
>>> penstate=turtle.pen()
>>> turtle.color("yellow", "")
>>> turtle.penup()
>>> sorted(turtle.pen().items())
[('fillcolor', ''), ('outline', 1), ('pencolor', 'yellow'),
('pendown', False), ('pensize', 10), ('resizemode', 'noresize'),
('shown', True), ('speed', 9), ('stretchfactor', (1, 1)), ('tilt', 0)]
>>> turtle.pen(penstate, fillcolor="green")
>>> sorted(turtle.pen().items())
[('fillcolor', 'green'), ('outline', 1), ('pencolor', 'red'),
('pendown', True), ('pensize', 10), ('resizemode', 'noresize'),
('shown', True), ('speed', 9), ('stretchfactor', (1, 1)), ('tilt', 0)]
.. function:: isdown()
Return ``True`` if pen is down, ``False`` if it's up.
.. doctest::
>>> turtle.penup()
>>> turtle.isdown()
False
>>> turtle.pendown()
>>> turtle.isdown()
True
Color control
~~~~~~~~~~~~~
.. function:: pencolor(*args)
Return or set the pencolor.
Four input formats are allowed:
``pencolor()``
Return the current pencolor as color specification string or
as a tuple (see example). May be used as input to another
color/pencolor/fillcolor call.
``pencolor(colorstring)``
Set pencolor to *colorstring*, which is a Tk color specification string,
such as ``"red"``, ``"yellow"``, or ``"#33cc8c"``.
``pencolor((r, g, b))``
Set pencolor to the RGB color represented by the tuple of *r*, *g*, and
*b*. Each of *r*, *g*, and *b* must be in the range 0..colormode, where
colormode is either 1.0 or 255 (see :func:`colormode`).
``pencolor(r, g, b)``
Set pencolor to the RGB color represented by *r*, *g*, and *b*. Each of
*r*, *g*, and *b* must be in the range 0..colormode.
If turtleshape is a polygon, the outline of that polygon is drawn with the
newly set pencolor.
.. doctest::
>>> colormode()
1.0
>>> turtle.pencolor()
'red'
>>> turtle.pencolor("brown")
>>> turtle.pencolor()
'brown'
>>> tup = (0.2, 0.8, 0.55)
>>> turtle.pencolor(tup)
>>> turtle.pencolor()
(0.2, 0.8, 0.5490196078431373)
>>> colormode(255)
>>> turtle.pencolor()
(51, 204, 140)
>>> turtle.pencolor('#32c18f')
>>> turtle.pencolor()
(50, 193, 143)
.. function:: fillcolor(*args)
Return or set the fillcolor.
Four input formats are allowed:
``fillcolor()``
Return the current fillcolor as color specification string, possibly
in tuple format (see example). May be used as input to another
color/pencolor/fillcolor call.
``fillcolor(colorstring)``
Set fillcolor to *colorstring*, which is a Tk color specification string,
such as ``"red"``, ``"yellow"``, or ``"#33cc8c"``.
``fillcolor((r, g, b))``
Set fillcolor to the RGB color represented by the tuple of *r*, *g*, and
*b*. Each of *r*, *g*, and *b* must be in the range 0..colormode, where
colormode is either 1.0 or 255 (see :func:`colormode`).
``fillcolor(r, g, b)``
Set fillcolor to the RGB color represented by *r*, *g*, and *b*. Each of
*r*, *g*, and *b* must be in the range 0..colormode.
If turtleshape is a polygon, the interior of that polygon is drawn
with the newly set fillcolor.
.. doctest::
>>> turtle.fillcolor("violet")
>>> turtle.fillcolor()
'violet'
>>> col = turtle.pencolor()
>>> col
(50, 193, 143)
>>> turtle.fillcolor(col)
>>> turtle.fillcolor()
(50, 193, 143)
>>> turtle.fillcolor('#ffffff')
>>> turtle.fillcolor()
(255, 255, 255)
.. function:: color(*args)
Return or set pencolor and fillcolor.
Several input formats are allowed. They use 0 to 3 arguments as
follows:
``color()``
Return the current pencolor and the current fillcolor as a pair of color
specification strings or tuples as returned by :func:`pencolor` and
:func:`fillcolor`.
``color(colorstring)``, ``color((r,g,b))``, ``color(r,g,b)``
Inputs as in :func:`pencolor`, set both, fillcolor and pencolor, to the
given value.
``color(colorstring1, colorstring2)``, ``color((r1,g1,b1), (r2,g2,b2))``
Equivalent to ``pencolor(colorstring1)`` and ``fillcolor(colorstring2)``
and analogously if the other input format is used.
If turtleshape is a polygon, outline and interior of that polygon is drawn
with the newly set colors.
.. doctest::
>>> turtle.color("red", "green")
>>> turtle.color()
('red', 'green')
>>> color("#285078", "#a0c8f0")
>>> color()
((40, 80, 120), (160, 200, 240))
See also: Screen method :func:`colormode`.
Filling
~~~~~~~
.. doctest::
:hide:
>>> turtle.home()
.. function:: fill(flag)
:param flag: True/False (or 1/0 respectively)
Call ``fill(True)`` before drawing the shape you want to fill, and
``fill(False)`` when done. When used without argument: return fillstate
(``True`` if filling, ``False`` else).
.. doctest::
>>> turtle.fill(True)
>>> for _ in range(3):
... turtle.forward(100)
... turtle.left(120)
...
>>> turtle.fill(False)
.. function:: begin_fill()
Call just before drawing a shape to be filled. Equivalent to ``fill(True)``.
.. function:: end_fill()
Fill the shape drawn after the last call to :func:`begin_fill`. Equivalent
to ``fill(False)``.
.. doctest::
>>> turtle.color("black", "red")
>>> turtle.begin_fill()
>>> turtle.circle(80)
>>> turtle.end_fill()
More drawing control
~~~~~~~~~~~~~~~~~~~~
.. function:: reset()
Delete the turtle's drawings from the screen, re-center the turtle and set
variables to the default values.
.. doctest::
>>> turtle.goto(0,-22)
>>> turtle.left(100)
>>> turtle.position()
(0.00,-22.00)
>>> turtle.heading()
100.0
>>> turtle.reset()
>>> turtle.position()
(0.00,0.00)
>>> turtle.heading()
0.0
.. function:: clear()
Delete the turtle's drawings from the screen. Do not move turtle. State and
position of the turtle as well as drawings of other turtles are not affected.
.. function:: write(arg, move=False, align="left", font=("Arial", 8, "normal"))
:param arg: object to be written to the TurtleScreen
:param move: True/False
:param align: one of the strings "left", "center" or right"
:param font: a triple (fontname, fontsize, fonttype)
Write text - the string representation of *arg* - at the current turtle
position according to *align* ("left", "center" or right") and with the given
font. If *move* is true, the pen is moved to the bottom-right corner of the
text. By default, *move* is ``False``.
>>> turtle.write("Home = ", True, align="center")
>>> turtle.write((0,0), True)
Turtle state
------------
Visibility
~~~~~~~~~~
.. function:: hideturtle()
ht()
Make the turtle invisible. It's a good idea to do this while you're in the
middle of doing some complex drawing, because hiding the turtle speeds up the
drawing observably.
.. doctest::
>>> turtle.hideturtle()
.. function:: showturtle()
st()
Make the turtle visible.
.. doctest::
>>> turtle.showturtle()
.. function:: isvisible()
Return ``True`` if the Turtle is shown, ``False`` if it's hidden.
>>> turtle.hideturtle()
>>> turtle.isvisible()
False
>>> turtle.showturtle()
>>> turtle.isvisible()
True
Appearance
~~~~~~~~~~
.. function:: shape(name=None)
:param name: a string which is a valid shapename
Set turtle shape to shape with given *name* or, if name is not given, return
name of current shape. Shape with *name* must exist in the TurtleScreen's
shape dictionary. Initially there are the following polygon shapes: "arrow",
"turtle", "circle", "square", "triangle", "classic". To learn about how to
deal with shapes see Screen method :func:`register_shape`.
.. doctest::
>>> turtle.shape()
'classic'
>>> turtle.shape("turtle")
>>> turtle.shape()
'turtle'
.. function:: resizemode(rmode=None)
:param rmode: one of the strings "auto", "user", "noresize"
Set resizemode to one of the values: "auto", "user", "noresize". If *rmode*
is not given, return current resizemode. Different resizemodes have the
following effects:
- "auto": adapts the appearance of the turtle corresponding to the value of pensize.
- "user": adapts the appearance of the turtle according to the values of
stretchfactor and outlinewidth (outline), which are set by
:func:`shapesize`.
- "noresize": no adaption of the turtle's appearance takes place.
resizemode("user") is called by :func:`shapesize` when used with arguments.
.. doctest::
>>> turtle.resizemode()
'noresize'
>>> turtle.resizemode("auto")
>>> turtle.resizemode()
'auto'
.. function:: shapesize(stretch_wid=None, stretch_len=None, outline=None)
turtlesize(stretch_wid=None, stretch_len=None, outline=None)
:param stretch_wid: positive number
:param stretch_len: positive number
:param outline: positive number
Return or set the pen's attributes x/y-stretchfactors and/or outline. Set
resizemode to "user". If and only if resizemode is set to "user", the turtle
will be displayed stretched according to its stretchfactors: *stretch_wid* is
stretchfactor perpendicular to its orientation, *stretch_len* is
stretchfactor in direction of its orientation, *outline* determines the width
of the shapes's outline.
.. doctest::
>>> turtle.shapesize()
(1, 1, 1)
>>> turtle.resizemode("user")
>>> turtle.shapesize(5, 5, 12)
>>> turtle.shapesize()
(5, 5, 12)
>>> turtle.shapesize(outline=8)
>>> turtle.shapesize()
(5, 5, 8)
.. function:: tilt(angle)
:param angle: a number
Rotate the turtleshape by *angle* from its current tilt-angle, but do *not*
change the turtle's heading (direction of movement).
.. doctest::
>>> turtle.reset()
>>> turtle.shape("circle")
>>> turtle.shapesize(5,2)
>>> turtle.tilt(30)
>>> turtle.fd(50)
>>> turtle.tilt(30)
>>> turtle.fd(50)
.. function:: settiltangle(angle)
:param angle: a number
Rotate the turtleshape to point in the direction specified by *angle*,
regardless of its current tilt-angle. *Do not* change the turtle's heading
(direction of movement).
.. doctest::
>>> turtle.reset()
>>> turtle.shape("circle")
>>> turtle.shapesize(5,2)
>>> turtle.settiltangle(45)
>>> turtle.fd(50)
>>> turtle.settiltangle(-45)
>>> turtle.fd(50)
.. function:: tiltangle()
Return the current tilt-angle, i.e. the angle between the orientation of the
turtleshape and the heading of the turtle (its direction of movement).
.. doctest::
>>> turtle.reset()
>>> turtle.shape("circle")
>>> turtle.shapesize(5,2)
>>> turtle.tilt(45)
>>> turtle.tiltangle()
45.0
Using events
------------
.. function:: onclick(fun, btn=1, add=None)
:param fun: a function with two arguments which will be called with the
coordinates of the clicked point on the canvas
:param btn: number of the mouse-button, defaults to 1 (left mouse button)
:param add: ``True`` or ``False`` -- if ``True``, a new binding will be
added, otherwise it will replace a former binding
Bind *fun* to mouse-click events on this turtle. If *fun* is ``None``,
existing bindings are removed. Example for the anonymous turtle, i.e. the
procedural way:
.. doctest::
>>> def turn(x, y):
... left(180)
...
>>> onclick(turn) # Now clicking into the turtle will turn it.
>>> onclick(None) # event-binding will be removed
.. function:: onrelease(fun, btn=1, add=None)
:param fun: a function with two arguments which will be called with the
coordinates of the clicked point on the canvas
:param btn: number of the mouse-button, defaults to 1 (left mouse button)
:param add: ``True`` or ``False`` -- if ``True``, a new binding will be
added, otherwise it will replace a former binding
Bind *fun* to mouse-button-release events on this turtle. If *fun* is
``None``, existing bindings are removed.
.. doctest::
>>> class MyTurtle(Turtle):
... def glow(self,x,y):
... self.fillcolor("red")
... def unglow(self,x,y):
... self.fillcolor("")
...
>>> turtle = MyTurtle()
>>> turtle.onclick(turtle.glow) # clicking on turtle turns fillcolor red,
>>> turtle.onrelease(turtle.unglow) # releasing turns it to transparent.
.. function:: ondrag(fun, btn=1, add=None)
:param fun: a function with two arguments which will be called with the
coordinates of the clicked point on the canvas
:param btn: number of the mouse-button, defaults to 1 (left mouse button)
:param add: ``True`` or ``False`` -- if ``True``, a new binding will be
added, otherwise it will replace a former binding
Bind *fun* to mouse-move events on this turtle. If *fun* is ``None``,
existing bindings are removed.
Remark: Every sequence of mouse-move-events on a turtle is preceded by a
mouse-click event on that turtle.
.. doctest::
>>> turtle.ondrag(turtle.goto)
Subsequently, clicking and dragging the Turtle will move it across
the screen thereby producing handdrawings (if pen is down).
.. function:: mainloop()
done()
Starts event loop - calling Tkinter's mainloop function. Must be the last
statement in a turtle graphics program.
>>> turtle.mainloop()
Special Turtle methods
----------------------
.. function:: begin_poly()
Start recording the vertices of a polygon. Current turtle position is first
vertex of polygon.
.. function:: end_poly()
Stop recording the vertices of a polygon. Current turtle position is last
vertex of polygon. This will be connected with the first vertex.
.. function:: get_poly()
Return the last recorded polygon.
.. doctest::
>>> turtle.home()
>>> turtle.begin_poly()
>>> turtle.fd(100)
>>> turtle.left(20)
>>> turtle.fd(30)
>>> turtle.left(60)
>>> turtle.fd(50)
>>> turtle.end_poly()
>>> p = turtle.get_poly()
>>> register_shape("myFavouriteShape", p)
.. function:: clone()
Create and return a clone of the turtle with same position, heading and
turtle properties.
.. doctest::
>>> mick = Turtle()
>>> joe = mick.clone()
.. function:: getturtle()
getpen()
Return the Turtle object itself. Only reasonable use: as a function to
return the "anonymous turtle":
.. doctest::
>>> pet = getturtle()
>>> pet.fd(50)
>>> pet
<turtle.Turtle object at 0x...>
.. function:: getscreen()
Return the :class:`TurtleScreen` object the turtle is drawing on.
TurtleScreen methods can then be called for that object.
.. doctest::
>>> ts = turtle.getscreen()
>>> ts
<turtle._Screen object at 0x...>
>>> ts.bgcolor("pink")
.. function:: setundobuffer(size)
:param size: an integer or ``None``
Set or disable undobuffer. If *size* is an integer an empty undobuffer of
given size is installed. *size* gives the maximum number of turtle actions
that can be undone by the :func:`undo` method/function. If *size* is
``None``, the undobuffer is disabled.
.. doctest::
>>> turtle.setundobuffer(42)
.. function:: undobufferentries()
Return number of entries in the undobuffer.
.. doctest::
>>> while undobufferentries():
... undo()
.. function:: tracer(flag=None, delay=None)
A replica of the corresponding TurtleScreen method.
.. deprecated:: 2.6
.. function:: window_width()
window_height()
Both are replicas of the corresponding TurtleScreen methods.
.. deprecated:: 2.6
.. _compoundshapes:
Excursus about the use of compound shapes
-----------------------------------------
To use compound turtle shapes, which consist of several polygons of different
color, you must use the helper class :class:`Shape` explicitly as described
below:
1. Create an empty Shape object of type "compound".
2. Add as many components to this object as desired, using the
:meth:`addcomponent` method.
For example:
.. doctest::
>>> s = Shape("compound")
>>> poly1 = ((0,0),(10,-5),(0,10),(-10,-5))
>>> s.addcomponent(poly1, "red", "blue")
>>> poly2 = ((0,0),(10,-5),(-10,-5))
>>> s.addcomponent(poly2, "blue", "red")
3. Now add the Shape to the Screen's shapelist and use it:
.. doctest::
>>> register_shape("myshape", s)
>>> shape("myshape")
.. note::
The :class:`Shape` class is used internally by the :func:`register_shape`
method in different ways. The application programmer has to deal with the
Shape class *only* when using compound shapes like shown above!
Methods of TurtleScreen/Screen and corresponding functions
==========================================================
Most of the examples in this section refer to a TurtleScreen instance called
``screen``.
.. doctest::
:hide:
>>> screen = Screen()
Window control
--------------
.. function:: bgcolor(*args)
:param args: a color string or three numbers in the range 0..colormode or a
3-tuple of such numbers
Set or return background color of the TurtleScreen.
.. doctest::
>>> screen.bgcolor("orange")
>>> screen.bgcolor()
'orange'
>>> screen.bgcolor("#800080")
>>> screen.bgcolor()
(128, 0, 128)
.. function:: bgpic(picname=None)
:param picname: a string, name of a gif-file or ``"nopic"``, or ``None``
Set background image or return name of current backgroundimage. If *picname*
is a filename, set the corresponding image as background. If *picname* is
``"nopic"``, delete background image, if present. If *picname* is ``None``,
return the filename of the current backgroundimage. ::
>>> screen.bgpic()
'nopic'
>>> screen.bgpic("landscape.gif")
>>> screen.bgpic()
"landscape.gif"
.. function:: clear()
clearscreen()
Delete all drawings and all turtles from the TurtleScreen. Reset the now
empty TurtleScreen to its initial state: white background, no background
image, no event bindings and tracing on.
.. note::
This TurtleScreen method is available as a global function only under the
name ``clearscreen``. The global function ``clear`` is another one
derived from the Turtle method ``clear``.
.. function:: reset()
resetscreen()
Reset all Turtles on the Screen to their initial state.
.. note::
This TurtleScreen method is available as a global function only under the
name ``resetscreen``. The global function ``reset`` is another one
derived from the Turtle method ``reset``.
.. function:: screensize(canvwidth=None, canvheight=None, bg=None)
:param canvwidth: positive integer, new width of canvas in pixels
:param canvheight: positive integer, new height of canvas in pixels
:param bg: colorstring or color-tuple, new background color
If no arguments are given, return current (canvaswidth, canvasheight). Else
resize the canvas the turtles are drawing on. Do not alter the drawing
window. To observe hidden parts of the canvas, use the scrollbars. With this
method, one can make visible those parts of a drawing which were outside the
canvas before.
>>> screen.screensize()
(400, 300)
>>> screen.screensize(2000,1500)
>>> screen.screensize()
(2000, 1500)
e.g. to search for an erroneously escaped turtle ;-)
.. function:: setworldcoordinates(llx, lly, urx, ury)
:param llx: a number, x-coordinate of lower left corner of canvas
:param lly: a number, y-coordinate of lower left corner of canvas
:param urx: a number, x-coordinate of upper right corner of canvas
:param ury: a number, y-coordinate of upper right corner of canvas
Set up user-defined coordinate system and switch to mode "world" if
necessary. This performs a ``screen.reset()``. If mode "world" is already
active, all drawings are redrawn according to the new coordinates.
**ATTENTION**: in user-defined coordinate systems angles may appear
distorted.
.. doctest::
>>> screen.reset()
>>> screen.setworldcoordinates(-50,-7.5,50,7.5)
>>> for _ in range(72):
... left(10)
...
>>> for _ in range(8):
... left(45); fd(2) # a regular octagon
.. doctest::
:hide:
>>> screen.reset()
>>> for t in turtles():
... t.reset()
Animation control
-----------------
.. function:: delay(delay=None)
:param delay: positive integer
Set or return the drawing *delay* in milliseconds. (This is approximately
the time interval between two consecutive canvas updates.) The longer the
drawing delay, the slower the animation.
Optional argument:
.. doctest::
>>> screen.delay()
10
>>> screen.delay(5)
>>> screen.delay()
5
.. function:: tracer(n=None, delay=None)
:param n: nonnegative integer
:param delay: nonnegative integer
Turn turtle animation on/off and set delay for update drawings. If *n* is
given, only each n-th regular screen update is really performed. (Can be
used to accelerate the drawing of complex graphics.) Second argument sets
delay value (see :func:`delay`).
.. doctest::
>>> screen.tracer(8, 25)
>>> dist = 2
>>> for i in range(200):
... fd(dist)
... rt(90)
... dist += 2
.. function:: update()
Perform a TurtleScreen update. To be used when tracer is turned off.
See also the RawTurtle/Turtle method :func:`speed`.
Using screen events
-------------------
.. function:: listen(xdummy=None, ydummy=None)
Set focus on TurtleScreen (in order to collect key-events). Dummy arguments
are provided in order to be able to pass :func:`listen` to the onclick method.
.. function:: onkey(fun, key)
:param fun: a function with no arguments or ``None``
:param key: a string: key (e.g. "a") or key-symbol (e.g. "space")
Bind *fun* to key-release event of key. If *fun* is ``None``, event bindings
are removed. Remark: in order to be able to register key-events, TurtleScreen
must have the focus. (See method :func:`listen`.)
.. doctest::
>>> def f():
... fd(50)
... lt(60)
...
>>> screen.onkey(f, "Up")
>>> screen.listen()
.. function:: onclick(fun, btn=1, add=None)
onscreenclick(fun, btn=1, add=None)
:param fun: a function with two arguments which will be called with the
coordinates of the clicked point on the canvas
:param btn: number of the mouse-button, defaults to 1 (left mouse button)
:param add: ``True`` or ``False`` -- if ``True``, a new binding will be
added, otherwise it will replace a former binding
Bind *fun* to mouse-click events on this screen. If *fun* is ``None``,
existing bindings are removed.
Example for a TurtleScreen instance named ``screen`` and a Turtle instance
named turtle:
.. doctest::
>>> screen.onclick(turtle.goto) # Subsequently clicking into the TurtleScreen will
>>> # make the turtle move to the clicked point.
>>> screen.onclick(None) # remove event binding again
.. note::
This TurtleScreen method is available as a global function only under the
name ``onscreenclick``. The global function ``onclick`` is another one
derived from the Turtle method ``onclick``.
.. function:: ontimer(fun, t=0)
:param fun: a function with no arguments
:param t: a number >= 0
Install a timer that calls *fun* after *t* milliseconds.
.. doctest::
>>> running = True
>>> def f():
... if running:
... fd(50)
... lt(60)
... screen.ontimer(f, 250)
>>> f() ### makes the turtle march around
>>> running = False
Settings and special methods
----------------------------
.. function:: mode(mode=None)
:param mode: one of the strings "standard", "logo" or "world"
Set turtle mode ("standard", "logo" or "world") and perform reset. If mode
is not given, current mode is returned.
Mode "standard" is compatible with old :mod:`turtle`. Mode "logo" is
compatible with most Logo turtle graphics. Mode "world" uses user-defined
"world coordinates". **Attention**: in this mode angles appear distorted if
``x/y`` unit-ratio doesn't equal 1.
============ ========================= ===================
Mode Initial turtle heading positive angles
============ ========================= ===================
"standard" to the right (east) counterclockwise
"logo" upward (north) clockwise
============ ========================= ===================
.. doctest::
>>> mode("logo") # resets turtle heading to north
>>> mode()
'logo'
.. function:: colormode(cmode=None)
:param cmode: one of the values 1.0 or 255
Return the colormode or set it to 1.0 or 255. Subsequently *r*, *g*, *b*
values of color triples have to be in the range 0..\ *cmode*.
.. doctest::
>>> screen.colormode(1)
>>> turtle.pencolor(240, 160, 80)
Traceback (most recent call last):
...
TurtleGraphicsError: bad color sequence: (240, 160, 80)
>>> screen.colormode()
1.0
>>> screen.colormode(255)
>>> screen.colormode()
255
>>> turtle.pencolor(240,160,80)
.. function:: getcanvas()
Return the Canvas of this TurtleScreen. Useful for insiders who know what to
do with a Tkinter Canvas.
.. doctest::
>>> cv = screen.getcanvas()
>>> cv
<turtle.ScrolledCanvas instance at 0x...>
.. function:: getshapes()
Return a list of names of all currently available turtle shapes.
.. doctest::
>>> screen.getshapes()
['arrow', 'blank', 'circle', ..., 'turtle']
.. function:: register_shape(name, shape=None)
addshape(name, shape=None)
There are three different ways to call this function:
(1) *name* is the name of a gif-file and *shape* is ``None``: Install the
corresponding image shape. ::
>>> screen.register_shape("turtle.gif")
.. note::
Image shapes *do not* rotate when turning the turtle, so they do not
display the heading of the turtle!
(2) *name* is an arbitrary string and *shape* is a tuple of pairs of
coordinates: Install the corresponding polygon shape.
.. doctest::
>>> screen.register_shape("triangle", ((5,-3), (0,5), (-5,-3)))
(3) *name* is an arbitrary string and shape is a (compound) :class:`Shape`
object: Install the corresponding compound shape.
Add a turtle shape to TurtleScreen's shapelist. Only thusly registered
shapes can be used by issuing the command ``shape(shapename)``.
.. function:: turtles()
Return the list of turtles on the screen.
.. doctest::
>>> for turtle in screen.turtles():
... turtle.color("red")
.. function:: window_height()
Return the height of the turtle window. ::
>>> screen.window_height()
480
.. function:: window_width()
Return the width of the turtle window. ::
>>> screen.window_width()
640
.. _screenspecific:
Methods specific to Screen, not inherited from TurtleScreen
-----------------------------------------------------------
.. function:: bye()
Shut the turtlegraphics window.
.. function:: exitonclick()
Bind bye() method to mouse clicks on the Screen.
If the value "using_IDLE" in the configuration dictionary is ``False``
(default value), also enter mainloop. Remark: If IDLE with the ``-n`` switch
(no subprocess) is used, this value should be set to ``True`` in
:file:`turtle.cfg`. In this case IDLE's own mainloop is active also for the
client script.
.. function:: setup(width=_CFG["width"], height=_CFG["height"], startx=_CFG["leftright"], starty=_CFG["topbottom"])
Set the size and position of the main window. Default values of arguments
are stored in the configuration dictionary and can be changed via a
:file:`turtle.cfg` file.
:param width: if an integer, a size in pixels, if a float, a fraction of the
screen; default is 50% of screen
:param height: if an integer, the height in pixels, if a float, a fraction of
the screen; default is 75% of screen
:param startx: if positive, starting position in pixels from the left
edge of the screen, if negative from the right edge, if ``None``,
center window horizontally
:param starty: if positive, starting position in pixels from the top
edge of the screen, if negative from the bottom edge, if ``None``,
center window vertically
.. doctest::
>>> screen.setup (width=200, height=200, startx=0, starty=0)
>>> # sets window to 200x200 pixels, in upper left of screen
>>> screen.setup(width=.75, height=0.5, startx=None, starty=None)
>>> # sets window to 75% of screen by 50% of screen and centers
.. function:: title(titlestring)
:param titlestring: a string that is shown in the titlebar of the turtle
graphics window
Set title of turtle window to *titlestring*.
.. doctest::
>>> screen.title("Welcome to the turtle zoo!")
The public classes of the module :mod:`turtle`
==============================================
.. class:: RawTurtle(canvas)
RawPen(canvas)
:param canvas: a :class:`Tkinter.Canvas`, a :class:`ScrolledCanvas` or a
:class:`TurtleScreen`
Create a turtle. The turtle has all methods described above as "methods of
Turtle/RawTurtle".
.. class:: Turtle()
Subclass of RawTurtle, has the same interface but draws on a default
:class:`Screen` object created automatically when needed for the first time.
.. class:: TurtleScreen(cv)
:param cv: a :class:`Tkinter.Canvas`
Provides screen oriented methods like :func:`setbg` etc. that are described
above.
.. class:: Screen()
Subclass of TurtleScreen, with :ref:`four methods added <screenspecific>`.
.. class:: ScrolledCanvas(master)
:param master: some Tkinter widget to contain the ScrolledCanvas, i.e.
a Tkinter-canvas with scrollbars added
Used by class Screen, which thus automatically provides a ScrolledCanvas as
playground for the turtles.
.. class:: Shape(type_, data)
:param type\_: one of the strings "polygon", "image", "compound"
Data structure modeling shapes. The pair ``(type_, data)`` must follow this
specification:
=========== ===========
*type_* *data*
=========== ===========
"polygon" a polygon-tuple, i.e. a tuple of pairs of coordinates
"image" an image (in this form only used internally!)
"compound" ``None`` (a compound shape has to be constructed using the
:meth:`addcomponent` method)
=========== ===========
.. method:: addcomponent(poly, fill, outline=None)
:param poly: a polygon, i.e. a tuple of pairs of numbers
:param fill: a color the *poly* will be filled with
:param outline: a color for the poly's outline (if given)
Example:
.. doctest::
>>> poly = ((0,0),(10,-5),(0,10),(-10,-5))
>>> s = Shape("compound")
>>> s.addcomponent(poly, "red", "blue")
>>> # ... add more components and then use register_shape()
See :ref:`compoundshapes`.
.. class:: Vec2D(x, y)
A two-dimensional vector class, used as a helper class for implementing
turtle graphics. May be useful for turtle graphics programs too. Derived
from tuple, so a vector is a tuple!
Provides (for *a*, *b* vectors, *k* number):
* ``a + b`` vector addition
* ``a - b`` vector subtraction
* ``a * b`` inner product
* ``k * a`` and ``a * k`` multiplication with scalar
* ``abs(a)`` absolute value of a
* ``a.rotate(angle)`` rotation
Help and configuration
======================
How to use help
---------------
The public methods of the Screen and Turtle classes are documented extensively
via docstrings. So these can be used as online-help via the Python help
facilities:
- When using IDLE, tooltips show the signatures and first lines of the
docstrings of typed in function-/method calls.
- Calling :func:`help` on methods or functions displays the docstrings::
>>> help(Screen.bgcolor)
Help on method bgcolor in module turtle:
bgcolor(self, *args) unbound turtle.Screen method
Set or return backgroundcolor of the TurtleScreen.
Arguments (if given): a color string or three numbers
in the range 0..colormode or a 3-tuple of such numbers.
>>> screen.bgcolor("orange")
>>> screen.bgcolor()
"orange"
>>> screen.bgcolor(0.5,0,0.5)
>>> screen.bgcolor()
"#800080"
>>> help(Turtle.penup)
Help on method penup in module turtle:
penup(self) unbound turtle.Turtle method
Pull the pen up -- no drawing when moving.
Aliases: penup | pu | up
No argument
>>> turtle.penup()
- The docstrings of the functions which are derived from methods have a modified
form::
>>> help(bgcolor)
Help on function bgcolor in module turtle:
bgcolor(*args)
Set or return backgroundcolor of the TurtleScreen.
Arguments (if given): a color string or three numbers
in the range 0..colormode or a 3-tuple of such numbers.
Example::
>>> bgcolor("orange")
>>> bgcolor()
"orange"
>>> bgcolor(0.5,0,0.5)
>>> bgcolor()
"#800080"
>>> help(penup)
Help on function penup in module turtle:
penup()
Pull the pen up -- no drawing when moving.
Aliases: penup | pu | up
No argument
Example:
>>> penup()
These modified docstrings are created automatically together with the function
definitions that are derived from the methods at import time.
Translation of docstrings into different languages
--------------------------------------------------
There is a utility to create a dictionary the keys of which are the method names
and the values of which are the docstrings of the public methods of the classes
Screen and Turtle.
.. function:: write_docstringdict(filename="turtle_docstringdict")
:param filename: a string, used as filename
Create and write docstring-dictionary to a Python script with the given
filename. This function has to be called explicitly (it is not used by the
turtle graphics classes). The docstring dictionary will be written to the
Python script :file:`{filename}.py`. It is intended to serve as a template
for translation of the docstrings into different languages.
If you (or your students) want to use :mod:`turtle` with online help in your
native language, you have to translate the docstrings and save the resulting
file as e.g. :file:`turtle_docstringdict_german.py`.
If you have an appropriate entry in your :file:`turtle.cfg` file this dictionary
will be read in at import time and will replace the original English docstrings.
At the time of this writing there are docstring dictionaries in German and in
Italian. (Requests please to glingl@aon.at.)
How to configure Screen and Turtles
-----------------------------------
The built-in default configuration mimics the appearance and behaviour of the
old turtle module in order to retain best possible compatibility with it.
If you want to use a different configuration which better reflects the features
of this module or which better fits to your needs, e.g. for use in a classroom,
you can prepare a configuration file ``turtle.cfg`` which will be read at import
time and modify the configuration according to its settings.
The built in configuration would correspond to the following turtle.cfg::
width = 0.5
height = 0.75
leftright = None
topbottom = None
canvwidth = 400
canvheight = 300
mode = standard
colormode = 1.0
delay = 10
undobuffersize = 1000
shape = classic
pencolor = black
fillcolor = black
resizemode = noresize
visible = True
language = english
exampleturtle = turtle
examplescreen = screen
title = Python Turtle Graphics
using_IDLE = False
Short explanation of selected entries:
- The first four lines correspond to the arguments of the :meth:`Screen.setup`
method.
- Line 5 and 6 correspond to the arguments of the method
:meth:`Screen.screensize`.
- *shape* can be any of the built-in shapes, e.g: arrow, turtle, etc. For more
info try ``help(shape)``.
- If you want to use no fillcolor (i.e. make the turtle transparent), you have
to write ``fillcolor = ""`` (but all nonempty strings must not have quotes in
the cfg-file).
- If you want to reflect the turtle its state, you have to use ``resizemode =
auto``.
- If you set e.g. ``language = italian`` the docstringdict
:file:`turtle_docstringdict_italian.py` will be loaded at import time (if
present on the import path, e.g. in the same directory as :mod:`turtle`.
- The entries *exampleturtle* and *examplescreen* define the names of these
objects as they occur in the docstrings. The transformation of
method-docstrings to function-docstrings will delete these names from the
docstrings.
- *using_IDLE*: Set this to ``True`` if you regularly work with IDLE and its -n
switch ("no subprocess"). This will prevent :func:`exitonclick` to enter the
mainloop.
There can be a :file:`turtle.cfg` file in the directory where :mod:`turtle` is
stored and an additional one in the current working directory. The latter will
override the settings of the first one.
The :file:`Demo/turtle` directory contains a :file:`turtle.cfg` file. You can
study it as an example and see its effects when running the demos (preferably
not from within the demo-viewer).
Demo scripts
============
There is a set of demo scripts in the turtledemo directory located in the
:file:`Demo/turtle` directory in the source distribution.
It contains:
- a set of 15 demo scripts demonstrating different features of the new module
:mod:`turtle`
- a demo viewer :file:`turtleDemo.py` which can be used to view the sourcecode
of the scripts and run them at the same time. 14 of the examples can be
accessed via the Examples menu; all of them can also be run standalone.
- The example :file:`turtledemo_two_canvases.py` demonstrates the simultaneous
use of two canvases with the turtle module. Therefore it only can be run
standalone.
- There is a :file:`turtle.cfg` file in this directory, which also serves as an
example for how to write and use such files.
The demoscripts are:
.. tabularcolumns:: |l|L|L|
+----------------+------------------------------+-----------------------+
| Name | Description | Features |
+================+==============================+=======================+
| bytedesign | complex classical | :func:`tracer`, delay,|
| | turtlegraphics pattern | :func:`update` |
+----------------+------------------------------+-----------------------+
| chaos | graphs Verhulst dynamics, | world coordinates |
| | shows that computer's | |
| | computations can generate | |
| | results sometimes against the| |
| | common sense expectations | |
+----------------+------------------------------+-----------------------+
| clock | analog clock showing time | turtles as clock's |
| | of your computer | hands, ontimer |
+----------------+------------------------------+-----------------------+
| colormixer | experiment with r, g, b | :func:`ondrag` |
+----------------+------------------------------+-----------------------+
| fractalcurves | Hilbert & Koch curves | recursion |
+----------------+------------------------------+-----------------------+
| lindenmayer | ethnomathematics | L-System |
| | (indian kolams) | |
+----------------+------------------------------+-----------------------+
| minimal_hanoi | Towers of Hanoi | Rectangular Turtles |
| | | as Hanoi discs |
| | | (shape, shapesize) |
+----------------+------------------------------+-----------------------+
| paint | super minimalistic | :func:`onclick` |
| | drawing program | |
+----------------+------------------------------+-----------------------+
| peace | elementary | turtle: appearance |
| | | and animation |
+----------------+------------------------------+-----------------------+
| penrose | aperiodic tiling with | :func:`stamp` |
| | kites and darts | |
+----------------+------------------------------+-----------------------+
| planet_and_moon| simulation of | compound shapes, |
| | gravitational system | :class:`Vec2D` |
+----------------+------------------------------+-----------------------+
| tree | a (graphical) breadth | :func:`clone` |
| | first tree (using generators)| |
+----------------+------------------------------+-----------------------+
| wikipedia | a pattern from the wikipedia | :func:`clone`, |
| | article on turtle graphics | :func:`undo` |
+----------------+------------------------------+-----------------------+
| yinyang | another elementary example | :func:`circle` |
+----------------+------------------------------+-----------------------+
Have fun!
.. doctest::
:hide:
>>> for turtle in turtles():
... turtle.reset()
>>> turtle.penup()
>>> turtle.goto(-200,25)
>>> turtle.pendown()
>>> turtle.write("No one expects the Spanish Inquisition!",
... font=("Arial", 20, "normal"))
>>> turtle.penup()
>>> turtle.goto(-100,-50)
>>> turtle.pendown()
>>> turtle.write("Our two chief Turtles are...",
... font=("Arial", 16, "normal"))
>>> turtle.penup()
>>> turtle.goto(-450,-75)
>>> turtle.write(str(turtles()))
PK
%�\�&�8 8 # html/_sources/library/types.rst.txtnu �[��� :mod:`types` --- Names for built-in types
=========================================
.. module:: types
:synopsis: Names for built-in types.
**Source code:** :source:`Lib/types.py`
--------------
This module defines names for some object types that are used by the standard
Python interpreter, but not for the types defined by various extension modules.
Also, it does not include some of the types that arise during processing such as
the ``listiterator`` type. It is safe to use ``from types import *`` --- the
module does not export any names besides the ones listed here. New names
exported by future versions of this module will all end in ``Type``.
Typical use is for functions that do different things depending on their
argument types, like the following::
from types import *
def delete(mylist, item):
if type(item) is IntType:
del mylist[item]
else:
mylist.remove(item)
Starting in Python 2.2, built-in factory functions such as :func:`int` and
:func:`str` are also names for the corresponding types. This is now the
preferred way to access the type instead of using the :mod:`types` module.
Accordingly, the example above should be written as follows::
def delete(mylist, item):
if isinstance(item, int):
del mylist[item]
else:
mylist.remove(item)
The module defines the following names:
.. data:: NoneType
The type of ``None``.
.. data:: TypeType
.. index:: builtin: type
The type of type objects (such as returned by :func:`type`); alias of the
built-in :class:`type`.
.. data:: BooleanType
The type of the :class:`bool` values ``True`` and ``False``; alias of the
built-in :class:`bool`.
.. versionadded:: 2.3
.. data:: IntType
The type of integers (e.g. ``1``); alias of the built-in :class:`int`.
.. data:: LongType
The type of long integers (e.g. ``1L``); alias of the built-in :class:`long`.
.. data:: FloatType
The type of floating point numbers (e.g. ``1.0``); alias of the built-in
:class:`float`.
.. data:: ComplexType
The type of complex numbers (e.g. ``1.0j``). This is not defined if Python was
built without complex number support.
.. data:: StringType
The type of character strings (e.g. ``'Spam'``); alias of the built-in
:class:`str`.
.. data:: UnicodeType
The type of Unicode character strings (e.g. ``u'Spam'``). This is not defined
if Python was built without Unicode support. It's an alias of the built-in
:class:`unicode`.
.. data:: TupleType
The type of tuples (e.g. ``(1, 2, 3, 'Spam')``); alias of the built-in
:class:`tuple`.
.. data:: ListType
The type of lists (e.g. ``[0, 1, 2, 3]``); alias of the built-in
:class:`list`.
.. data:: DictType
The type of dictionaries (e.g. ``{'Bacon': 1, 'Ham': 0}``); alias of the
built-in :class:`dict`.
.. data:: DictionaryType
An alternate name for ``DictType``.
.. data:: FunctionType
LambdaType
The type of user-defined functions and functions created by :keyword:`lambda`
expressions.
.. data:: GeneratorType
The type of :term:`generator`-iterator objects, produced by calling a
generator function.
.. versionadded:: 2.2
.. data:: CodeType
.. index:: builtin: compile
The type for code objects such as returned by :func:`compile`.
.. data:: ClassType
The type of user-defined old-style classes.
.. data:: InstanceType
The type of instances of user-defined old-style classes.
.. data:: MethodType
The type of methods of user-defined class instances.
.. data:: UnboundMethodType
An alternate name for ``MethodType``.
.. data:: BuiltinFunctionType
BuiltinMethodType
The type of built-in functions like :func:`len` or :func:`sys.exit`, and
methods of built-in classes. (Here, the term "built-in" means "written in
C".)
.. data:: ModuleType
The type of modules.
.. data:: FileType
The type of open file objects such as ``sys.stdout``; alias of the built-in
:class:`file`.
.. data:: XRangeType
.. index:: builtin: xrange
The type of range objects returned by :func:`xrange`; alias of the built-in
:class:`xrange`.
.. data:: SliceType
.. index:: builtin: slice
The type of objects returned by :func:`slice`; alias of the built-in
:class:`slice`.
.. data:: EllipsisType
The type of ``Ellipsis``.
.. data:: TracebackType
The type of traceback objects such as found in ``sys.exc_traceback``.
.. data:: FrameType
The type of frame objects such as found in ``tb.tb_frame`` if ``tb`` is a
traceback object.
.. data:: BufferType
.. index:: builtin: buffer
The type of buffer objects created by the :func:`buffer` function.
.. data:: DictProxyType
The type of dict proxies, such as ``TypeType.__dict__``.
.. data:: NotImplementedType
The type of ``NotImplemented``
.. data:: GetSetDescriptorType
The type of objects defined in extension modules with ``PyGetSetDef``, such
as ``FrameType.f_locals`` or ``array.array.typecode``. This type is used as
descriptor for object attributes; it has the same purpose as the
:class:`property` type, but for classes defined in extension modules.
.. versionadded:: 2.5
.. data:: MemberDescriptorType
The type of objects defined in extension modules with ``PyMemberDef``, such
as ``datetime.timedelta.days``. This type is used as descriptor for simple C
data members which use standard conversion functions; it has the same purpose
as the :class:`property` type, but for classes defined in extension modules.
.. impl-detail::
In other implementations of Python, this type may be identical to
``GetSetDescriptorType``.
.. versionadded:: 2.5
.. data:: StringTypes
A sequence containing ``StringType`` and ``UnicodeType`` used to facilitate
easier checking for any string object. Using this is more portable than using a
sequence of the two string types constructed elsewhere since it only contains
``UnicodeType`` if it has been built in the running version of Python. For
example: ``isinstance(s, types.StringTypes)``.
.. versionadded:: 2.2
PK
%�\�z�(� � # html/_sources/library/undoc.rst.txtnu �[���
.. _undoc:
********************
Undocumented Modules
********************
Here's a quick listing of modules that are currently undocumented, but that
should be documented. Feel free to contribute documentation for them! (Send
via email to docs@python.org.)
The idea and original contents for this chapter were taken from a posting by
Fredrik Lundh; the specific contents of this chapter have been substantially
revised.
Miscellaneous useful utilities
==============================
Some of these are very old and/or not very robust; marked with "hmm."
:mod:`ihooks`
--- Import hook support (for :mod:`rexec`; may become obsolete). Removed in
Python 3.x.
Platform specific modules
=========================
These modules are used to implement the :mod:`os.path` module, and are not
documented beyond this mention. There's little need to document these.
:mod:`ntpath`
--- Implementation of :mod:`os.path` on Win32, Win64, WinCE, and OS/2 platforms.
:mod:`posixpath`
--- Implementation of :mod:`os.path` on POSIX.
:mod:`bsddb185`
--- Backwards compatibility module for systems which still use the Berkeley DB
1.85 module. It is normally only available on certain BSD Unix-based systems.
It should never be used directly.
Multimedia
==========
:mod:`audiodev`
--- Platform-independent API for playing audio data. Removed in Python 3.x.
:mod:`linuxaudiodev`
--- Play audio data on the Linux audio device. Replaced in Python 2.3 by the
:mod:`ossaudiodev` module. Removed in Python 3.x.
:mod:`sunaudio`
--- Interpret Sun audio headers (may become obsolete or a tool/demo).
Removed in Python 3.x.
:mod:`toaiff`
--- Convert "arbitrary" sound files to AIFF files; should probably become a tool
or demo. Requires the external program :program:`sox`. Removed in Python 3.x.
.. _undoc-mac-modules:
Undocumented Mac OS modules
===========================
:mod:`applesingle` --- AppleSingle decoder
------------------------------------------
.. module:: applesingle
:platform: Mac
:synopsis: Rudimentary decoder for AppleSingle format files.
:deprecated:
.. deprecated:: 2.6
:mod:`buildtools` --- Helper module for BuildApplet and Friends
---------------------------------------------------------------
.. module:: buildtools
:platform: Mac
:synopsis: Helper module for BuildApplet, BuildApplication and macfreeze.
:deprecated:
.. deprecated:: 2.4
:mod:`cfmfile` --- Code Fragment Resource module
------------------------------------------------
.. module:: cfmfile
:platform: Mac
:synopsis: Code Fragment Resource module.
:deprecated:
:mod:`cfmfile` is a module that understands Code Fragments and the accompanying
"cfrg" resources. It can parse them and merge them, and is used by
BuildApplication to combine all plugin modules to a single executable.
.. deprecated:: 2.4
:mod:`icopen` --- Internet Config replacement for :meth:`open`
--------------------------------------------------------------
.. module:: icopen
:platform: Mac
:synopsis: Internet Config replacement for open().
:deprecated:
Importing :mod:`icopen` will replace the built-in :meth:`open` with a version
that uses Internet Config to set file type and creator for new files.
.. deprecated:: 2.6
:mod:`macerrors` --- Mac OS Errors
----------------------------------
.. module:: macerrors
:platform: Mac
:synopsis: Constant definitions for many Mac OS error codes.
:deprecated:
:mod:`macerrors` contains constant definitions for many Mac OS error codes.
.. deprecated:: 2.6
:mod:`macresource` --- Locate script resources
----------------------------------------------
.. module:: macresource
:platform: Mac
:synopsis: Locate script resources.
:deprecated:
:mod:`macresource` helps scripts finding their resources, such as dialogs and
menus, without requiring special case code for when the script is run under
MacPython, as a MacPython applet or under OSX Python.
.. deprecated:: 2.6
:mod:`Nav` --- NavServices calls
--------------------------------
.. module:: Nav
:platform: Mac
:synopsis: Interface to Navigation Services.
:deprecated:
A low-level interface to Navigation Services.
.. deprecated:: 2.6
:mod:`PixMapWrapper` --- Wrapper for PixMap objects
---------------------------------------------------
.. module:: PixMapWrapper
:platform: Mac
:synopsis: Wrapper for PixMap objects.
:deprecated:
:mod:`PixMapWrapper` wraps a PixMap object with a Python object that allows
access to the fields by name. It also has methods to convert to and from
:mod:`PIL` images.
.. deprecated:: 2.6
:mod:`videoreader` --- Read QuickTime movies
--------------------------------------------
.. module:: videoreader
:platform: Mac
:synopsis: Read QuickTime movies frame by frame for further processing.
:deprecated:
:mod:`videoreader` reads and decodes QuickTime movies and passes a stream of
images to your program. It also provides some support for audio tracks.
.. deprecated:: 2.6
:mod:`W` --- Widgets built on :mod:`FrameWork`
----------------------------------------------
.. module:: W
:platform: Mac
:synopsis: Widgets for the Mac, built on top of FrameWork.
:deprecated:
The :mod:`W` widgets are used extensively in the :program:`IDE`.
.. deprecated:: 2.6
.. _obsolete-modules:
Obsolete
========
These modules are not normally available for import; additional work must be
done to make them available.
These extension modules written in C are not built by default. Under Unix, these
must be enabled by uncommenting the appropriate lines in :file:`Modules/Setup`
in the build tree and either rebuilding Python if the modules are statically
linked, or building and installing the shared object if using dynamically-loaded
extensions.
.. (lib-old is empty as of Python 2.5)
Those which are written in Python will be installed into the directory
\file{lib-old/} installed as part of the standard library. To use
these, the directory must be added to \code{sys.path}, possibly using
\envvar{PYTHONPATH}.
:mod:`timing`
--- Measure time intervals to high resolution (use :func:`time.clock`
instead). Removed in Python 3.x.
SGI-specific Extension modules
==============================
The following are SGI specific, and may be out of touch with the current version
of reality.
:mod:`cl`
--- Interface to the SGI compression library.
:mod:`sv`
--- Interface to the "simple video" board on SGI Indigo (obsolete hardware).
Removed in Python 3.x.
PK
%�\��h h ) html/_sources/library/unicodedata.rst.txtnu �[���
:mod:`unicodedata` --- Unicode Database
=======================================
.. module:: unicodedata
:synopsis: Access the Unicode Database.
.. moduleauthor:: Marc-Andre Lemburg <mal@lemburg.com>
.. sectionauthor:: Marc-Andre Lemburg <mal@lemburg.com>
.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
.. index::
single: Unicode
single: character
pair: Unicode; database
This module provides access to the Unicode Character Database which defines
character properties for all Unicode characters. The data in this database is
based on the :file:`UnicodeData.txt` file version 5.2.0 which is publicly
available from ftp://ftp.unicode.org/.
The module uses the same names and symbols as defined by the UnicodeData File
Format 5.2.0 (see http://www.unicode.org/reports/tr44/tr44-4.html).
It defines the following functions:
.. function:: lookup(name)
Look up character by name. If a character with the given name is found, return
the corresponding Unicode character. If not found, :exc:`KeyError` is raised.
.. function:: name(unichr[, default])
Returns the name assigned to the Unicode character *unichr* as a string. If no
name is defined, *default* is returned, or, if not given, :exc:`ValueError` is
raised.
.. function:: decimal(unichr[, default])
Returns the decimal value assigned to the Unicode character *unichr* as integer.
If no such value is defined, *default* is returned, or, if not given,
:exc:`ValueError` is raised.
.. function:: digit(unichr[, default])
Returns the digit value assigned to the Unicode character *unichr* as integer.
If no such value is defined, *default* is returned, or, if not given,
:exc:`ValueError` is raised.
.. function:: numeric(unichr[, default])
Returns the numeric value assigned to the Unicode character *unichr* as float.
If no such value is defined, *default* is returned, or, if not given,
:exc:`ValueError` is raised.
.. function:: category(unichr)
Returns the general category assigned to the Unicode character *unichr* as
string.
.. function:: bidirectional(unichr)
Returns the bidirectional class assigned to the Unicode character *unichr* as
string. If no such value is defined, an empty string is returned.
.. function:: combining(unichr)
Returns the canonical combining class assigned to the Unicode character *unichr*
as integer. Returns ``0`` if no combining class is defined.
.. function:: east_asian_width(unichr)
Returns the east asian width assigned to the Unicode character *unichr* as
string.
.. versionadded:: 2.4
.. function:: mirrored(unichr)
Returns the mirrored property assigned to the Unicode character *unichr* as
integer. Returns ``1`` if the character has been identified as a "mirrored"
character in bidirectional text, ``0`` otherwise.
.. function:: decomposition(unichr)
Returns the character decomposition mapping assigned to the Unicode character
*unichr* as string. An empty string is returned in case no such mapping is
defined.
.. function:: normalize(form, unistr)
Return the normal form *form* for the Unicode string *unistr*. Valid values for
*form* are 'NFC', 'NFKC', 'NFD', and 'NFKD'.
The Unicode standard defines various normalization forms of a Unicode string,
based on the definition of canonical equivalence and compatibility equivalence.
In Unicode, several characters can be expressed in various way. For example, the
character U+00C7 (LATIN CAPITAL LETTER C WITH CEDILLA) can also be expressed as
the sequence U+0043 (LATIN CAPITAL LETTER C) U+0327 (COMBINING CEDILLA).
For each character, there are two normal forms: normal form C and normal form D.
Normal form D (NFD) is also known as canonical decomposition, and translates
each character into its decomposed form. Normal form C (NFC) first applies a
canonical decomposition, then composes pre-combined characters again.
In addition to these two forms, there are two additional normal forms based on
compatibility equivalence. In Unicode, certain characters are supported which
normally would be unified with other characters. For example, U+2160 (ROMAN
NUMERAL ONE) is really the same thing as U+0049 (LATIN CAPITAL LETTER I).
However, it is supported in Unicode for compatibility with existing character
sets (e.g. gb2312).
The normal form KD (NFKD) will apply the compatibility decomposition, i.e.
replace all compatibility characters with their equivalents. The normal form KC
(NFKC) first applies the compatibility decomposition, followed by the canonical
composition.
Even if two unicode strings are normalized and look the same to
a human reader, if one has combining characters and the other
doesn't, they may not compare equal.
.. versionadded:: 2.3
In addition, the module exposes the following constant:
.. data:: unidata_version
The version of the Unicode database used in this module.
.. versionadded:: 2.3
.. data:: ucd_3_2_0
This is an object that has the same methods as the entire module, but uses the
Unicode database version 3.2 instead, for applications that require this
specific version of the Unicode database (such as IDNA).
.. versionadded:: 2.5
Examples:
>>> import unicodedata
>>> unicodedata.lookup('LEFT CURLY BRACKET')
u'{'
>>> unicodedata.name(u'/')
'SOLIDUS'
>>> unicodedata.decimal(u'9')
9
>>> unicodedata.decimal(u'a')
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ValueError: not a decimal
>>> unicodedata.category(u'A') # 'L'etter, 'u'ppercase
'Lu'
>>> unicodedata.bidirectional(u'\u0660') # 'A'rabic, 'N'umber
'AN'
PK
%�\����D D & html/_sources/library/unittest.rst.txtnu �[��� :mod:`unittest` --- Unit testing framework
==========================================
.. module:: unittest
:synopsis: Unit testing framework for Python.
.. moduleauthor:: Steve Purcell <stephen_purcell@yahoo.com>
.. sectionauthor:: Steve Purcell <stephen_purcell@yahoo.com>
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
.. sectionauthor:: Raymond Hettinger <python@rcn.com>
.. versionadded:: 2.1
(If you are already familiar with the basic concepts of testing, you might want
to skip to :ref:`the list of assert methods <assert-methods>`.)
The Python unit testing framework, sometimes referred to as "PyUnit," is a
Python language version of JUnit, by Kent Beck and Erich Gamma. JUnit is, in
turn, a Java version of Kent's Smalltalk testing framework. Each is the de
facto standard unit testing framework for its respective language.
:mod:`unittest` supports test automation, sharing of setup and shutdown code for
tests, aggregation of tests into collections, and independence of the tests from
the reporting framework. The :mod:`unittest` module provides classes that make
it easy to support these qualities for a set of tests.
To achieve this, :mod:`unittest` supports some important concepts:
test fixture
A :dfn:`test fixture` represents the preparation needed to perform one or more
tests, and any associate cleanup actions. This may involve, for example,
creating temporary or proxy databases, directories, or starting a server
process.
test case
A :dfn:`test case` is the smallest unit of testing. It checks for a specific
response to a particular set of inputs. :mod:`unittest` provides a base class,
:class:`TestCase`, which may be used to create new test cases.
test suite
A :dfn:`test suite` is a collection of test cases, test suites, or both. It is
used to aggregate tests that should be executed together.
test runner
A :dfn:`test runner` is a component which orchestrates the execution of tests
and provides the outcome to the user. The runner may use a graphical interface,
a textual interface, or return a special value to indicate the results of
executing the tests.
The test case and test fixture concepts are supported through the
:class:`TestCase` and :class:`FunctionTestCase` classes; the former should be
used when creating new tests, and the latter can be used when integrating
existing test code with a :mod:`unittest`\ -driven framework. When building test
fixtures using :class:`TestCase`, the :meth:`~TestCase.setUp` and
:meth:`~TestCase.tearDown` methods can be overridden to provide initialization
and cleanup for the fixture. With :class:`FunctionTestCase`, existing functions
can be passed to the constructor for these purposes. When the test is run, the
fixture initialization is run first; if it succeeds, the cleanup method is run
after the test has been executed, regardless of the outcome of the test. Each
instance of the :class:`TestCase` will only be used to run a single test method,
so a new fixture is created for each test.
Test suites are implemented by the :class:`TestSuite` class. This class allows
individual tests and test suites to be aggregated; when the suite is executed,
all tests added directly to the suite and in "child" test suites are run.
A test runner is an object that provides a single method,
:meth:`~TestRunner.run`, which accepts a :class:`TestCase` or :class:`TestSuite`
object as a parameter, and returns a result object. The class
:class:`TestResult` is provided for use as the result object. :mod:`unittest`
provides the :class:`TextTestRunner` as an example test runner which reports
test results on the standard error stream by default. Alternate runners can be
implemented for other environments (such as graphical environments) without any
need to derive from a specific class.
.. seealso::
Module :mod:`doctest`
Another test-support module with a very different flavor.
`unittest2: A backport of new unittest features for Python 2.4-2.6 <https://pypi.org/project/unittest2>`_
Many new features were added to unittest in Python 2.7, including test
discovery. unittest2 allows you to use these features with earlier
versions of Python.
`Simple Smalltalk Testing: With Patterns <https://web.archive.org/web/20150315073817/http://www.xprogramming.com/testfram.htm>`_
Kent Beck's original paper on testing frameworks using the pattern shared
by :mod:`unittest`.
`Nose <https://nose.readthedocs.io/>`_ and `pytest <https://docs.pytest.org/>`_
Third-party unittest frameworks with a lighter-weight syntax for writing
tests. For example, ``assert func(10) == 42``.
`The Python Testing Tools Taxonomy <https://wiki.python.org/moin/PythonTestingToolsTaxonomy>`_
An extensive list of Python testing tools including functional testing
frameworks and mock object libraries.
`Testing in Python Mailing List <http://lists.idyll.org/listinfo/testing-in-python>`_
A special-interest-group for discussion of testing, and testing tools,
in Python.
.. _unittest-minimal-example:
Basic example
-------------
The :mod:`unittest` module provides a rich set of tools for constructing and
running tests. This section demonstrates that a small subset of the tools
suffice to meet the needs of most users.
Here is a short script to test three string methods::
import unittest
class TestStringMethods(unittest.TestCase):
def test_upper(self):
self.assertEqual('foo'.upper(), 'FOO')
def test_isupper(self):
self.assertTrue('FOO'.isupper())
self.assertFalse('Foo'.isupper())
def test_split(self):
s = 'hello world'
self.assertEqual(s.split(), ['hello', 'world'])
# check that s.split fails when the separator is not a string
with self.assertRaises(TypeError):
s.split(2)
if __name__ == '__main__':
unittest.main()
A testcase is created by subclassing :class:`unittest.TestCase`. The three
individual tests are defined with methods whose names start with the letters
``test``. This naming convention informs the test runner about which methods
represent tests.
The crux of each test is a call to :meth:`~TestCase.assertEqual` to check for an
expected result; :meth:`~TestCase.assertTrue` or :meth:`~TestCase.assertFalse`
to verify a condition; or :meth:`~TestCase.assertRaises` to verify that a
specific exception gets raised. These methods are used instead of the
:keyword:`assert` statement so the test runner can accumulate all test results
and produce a report.
The :meth:`~TestCase.setUp` and :meth:`~TestCase.tearDown` methods allow you
to define instructions that will be executed before and after each test method.
They are covered in more detail in the section :ref:`organizing-tests`.
The final block shows a simple way to run the tests. :func:`unittest.main`
provides a command-line interface to the test script. When run from the command
line, the above script produces an output that looks like this::
...
----------------------------------------------------------------------
Ran 3 tests in 0.000s
OK
Instead of :func:`unittest.main`, there are other ways to run the tests with a
finer level of control, less terse output, and no requirement to be run from the
command line. For example, the last two lines may be replaced with::
suite = unittest.TestLoader().loadTestsFromTestCase(TestStringMethods)
unittest.TextTestRunner(verbosity=2).run(suite)
Running the revised script from the interpreter or another script produces the
following output::
test_isupper (__main__.TestStringMethods) ... ok
test_split (__main__.TestStringMethods) ... ok
test_upper (__main__.TestStringMethods) ... ok
----------------------------------------------------------------------
Ran 3 tests in 0.001s
OK
The above examples show the most commonly used :mod:`unittest` features which
are sufficient to meet many everyday testing needs. The remainder of the
documentation explores the full feature set from first principles.
.. _unittest-command-line-interface:
Command-Line Interface
----------------------
The unittest module can be used from the command line to run tests from
modules, classes or even individual test methods::
python -m unittest test_module1 test_module2
python -m unittest test_module.TestClass
python -m unittest test_module.TestClass.test_method
You can pass in a list with any combination of module names, and fully
qualified class or method names.
You can run tests with more detail (higher verbosity) by passing in the -v flag::
python -m unittest -v test_module
For a list of all the command-line options::
python -m unittest -h
.. versionchanged:: 2.7
In earlier versions it was only possible to run individual test methods and
not modules or classes.
Command-line options
~~~~~~~~~~~~~~~~~~~~
:program:`unittest` supports these command-line options:
.. program:: unittest
.. cmdoption:: -b, --buffer
The standard output and standard error streams are buffered during the test
run. Output during a passing test is discarded. Output is echoed normally
on test fail or error and is added to the failure messages.
.. cmdoption:: -c, --catch
:kbd:`Control-C` during the test run waits for the current test to end and then
reports all the results so far. A second :kbd:`Control-C` raises the normal
:exc:`KeyboardInterrupt` exception.
See `Signal Handling`_ for the functions that provide this functionality.
.. cmdoption:: -f, --failfast
Stop the test run on the first error or failure.
.. versionadded:: 2.7
The command-line options ``-b``, ``-c`` and ``-f`` were added.
The command line can also be used for test discovery, for running all of the
tests in a project or just a subset.
.. _unittest-test-discovery:
Test Discovery
--------------
.. versionadded:: 2.7
Unittest supports simple test discovery. In order to be compatible with test
discovery, all of the test files must be :ref:`modules <tut-modules>` or
:ref:`packages <tut-packages>` importable from the top-level directory of
the project (this means that their filenames must be valid
:ref:`identifiers <identifiers>`).
Test discovery is implemented in :meth:`TestLoader.discover`, but can also be
used from the command line. The basic command-line usage is::
cd project_directory
python -m unittest discover
The ``discover`` sub-command has the following options:
.. program:: unittest discover
.. cmdoption:: -v, --verbose
Verbose output
.. cmdoption:: -s, --start-directory directory
Directory to start discovery (``.`` default)
.. cmdoption:: -p, --pattern pattern
Pattern to match test files (``test*.py`` default)
.. cmdoption:: -t, --top-level-directory directory
Top level directory of project (defaults to start directory)
The :option:`-s`, :option:`-p`, and :option:`-t` options can be passed in
as positional arguments in that order. The following two command lines
are equivalent::
python -m unittest discover -s project_directory -p "*_test.py"
python -m unittest discover project_directory "*_test.py"
As well as being a path it is possible to pass a package name, for example
``myproject.subpackage.test``, as the start directory. The package name you
supply will then be imported and its location on the filesystem will be used
as the start directory.
.. caution::
Test discovery loads tests by importing them. Once test discovery has
found all the test files from the start directory you specify it turns the
paths into package names to import. For example :file:`foo/bar/baz.py` will be
imported as ``foo.bar.baz``.
If you have a package installed globally and attempt test discovery on
a different copy of the package then the import *could* happen from the
wrong place. If this happens test discovery will warn you and exit.
If you supply the start directory as a package name rather than a
path to a directory then discover assumes that whichever location it
imports from is the location you intended, so you will not get the
warning.
Test modules and packages can customize test loading and discovery by through
the `load_tests protocol`_.
.. _organizing-tests:
Organizing test code
--------------------
The basic building blocks of unit testing are :dfn:`test cases` --- single
scenarios that must be set up and checked for correctness. In :mod:`unittest`,
test cases are represented by instances of :mod:`unittest`'s :class:`TestCase`
class. To make your own test cases you must write subclasses of
:class:`TestCase`, or use :class:`FunctionTestCase`.
An instance of a :class:`TestCase`\ -derived class is an object that can
completely run a single test method, together with optional set-up and tidy-up
code.
The testing code of a :class:`TestCase` instance should be entirely self
contained, such that it can be run either in isolation or in arbitrary
combination with any number of other test cases.
The simplest :class:`TestCase` subclass will simply override the
:meth:`~TestCase.runTest` method in order to perform specific testing code::
import unittest
class DefaultWidgetSizeTestCase(unittest.TestCase):
def runTest(self):
widget = Widget('The widget')
self.assertEqual(widget.size(), (50, 50), 'incorrect default size')
Note that in order to test something, we use one of the :meth:`assert\*`
methods provided by the :class:`TestCase` base class. If the test fails, an
exception will be raised, and :mod:`unittest` will identify the test case as a
:dfn:`failure`. Any other exceptions will be treated as :dfn:`errors`. This
helps you identify where the problem is: :dfn:`failures` are caused by incorrect
results - a 5 where you expected a 6. :dfn:`Errors` are caused by incorrect
code - e.g., a :exc:`TypeError` caused by an incorrect function call.
The way to run a test case will be described later. For now, note that to
construct an instance of such a test case, we call its constructor without
arguments::
testCase = DefaultWidgetSizeTestCase()
Now, such test cases can be numerous, and their set-up can be repetitive. In
the above case, constructing a :class:`Widget` in each of 100 Widget test case
subclasses would mean unsightly duplication.
Luckily, we can factor out such set-up code by implementing a method called
:meth:`~TestCase.setUp`, which the testing framework will automatically call for
us when we run the test::
import unittest
class SimpleWidgetTestCase(unittest.TestCase):
def setUp(self):
self.widget = Widget('The widget')
class DefaultWidgetSizeTestCase(SimpleWidgetTestCase):
def runTest(self):
self.assertEqual(self.widget.size(), (50,50),
'incorrect default size')
class WidgetResizeTestCase(SimpleWidgetTestCase):
def runTest(self):
self.widget.resize(100,150)
self.assertEqual(self.widget.size(), (100,150),
'wrong size after resize')
If the :meth:`~TestCase.setUp` method raises an exception while the test is
running, the framework will consider the test to have suffered an error, and the
:meth:`~TestCase.runTest` method will not be executed.
Similarly, we can provide a :meth:`~TestCase.tearDown` method that tidies up
after the :meth:`~TestCase.runTest` method has been run::
import unittest
class SimpleWidgetTestCase(unittest.TestCase):
def setUp(self):
self.widget = Widget('The widget')
def tearDown(self):
self.widget.dispose()
self.widget = None
If :meth:`~TestCase.setUp` succeeded, the :meth:`~TestCase.tearDown` method will
be run whether :meth:`~TestCase.runTest` succeeded or not.
Such a working environment for the testing code is called a :dfn:`fixture`.
Often, many small test cases will use the same fixture. In this case, we would
end up subclassing :class:`SimpleWidgetTestCase` into many small one-method
classes such as :class:`DefaultWidgetSizeTestCase`. This is time-consuming and
discouraging, so in the same vein as JUnit, :mod:`unittest` provides a simpler
mechanism::
import unittest
class WidgetTestCase(unittest.TestCase):
def setUp(self):
self.widget = Widget('The widget')
def tearDown(self):
self.widget.dispose()
self.widget = None
def test_default_size(self):
self.assertEqual(self.widget.size(), (50,50),
'incorrect default size')
def test_resize(self):
self.widget.resize(100,150)
self.assertEqual(self.widget.size(), (100,150),
'wrong size after resize')
Here we have not provided a :meth:`~TestCase.runTest` method, but have instead
provided two different test methods. Class instances will now each run one of
the :meth:`test_\*` methods, with ``self.widget`` created and destroyed
separately for each instance. When creating an instance we must specify the
test method it is to run. We do this by passing the method name in the
constructor::
defaultSizeTestCase = WidgetTestCase('test_default_size')
resizeTestCase = WidgetTestCase('test_resize')
Test case instances are grouped together according to the features they test.
:mod:`unittest` provides a mechanism for this: the :dfn:`test suite`,
represented by :mod:`unittest`'s :class:`TestSuite` class::
widgetTestSuite = unittest.TestSuite()
widgetTestSuite.addTest(WidgetTestCase('test_default_size'))
widgetTestSuite.addTest(WidgetTestCase('test_resize'))
For the ease of running tests, as we will see later, it is a good idea to
provide in each test module a callable object that returns a pre-built test
suite::
def suite():
suite = unittest.TestSuite()
suite.addTest(WidgetTestCase('test_default_size'))
suite.addTest(WidgetTestCase('test_resize'))
return suite
or even::
def suite():
tests = ['test_default_size', 'test_resize']
return unittest.TestSuite(map(WidgetTestCase, tests))
Since it is a common pattern to create a :class:`TestCase` subclass with many
similarly named test functions, :mod:`unittest` provides a :class:`TestLoader`
class that can be used to automate the process of creating a test suite and
populating it with individual tests. For example, ::
suite = unittest.TestLoader().loadTestsFromTestCase(WidgetTestCase)
will create a test suite that will run ``WidgetTestCase.test_default_size()`` and
``WidgetTestCase.test_resize``. :class:`TestLoader` uses the ``'test'`` method
name prefix to identify test methods automatically.
Note that the order in which the various test cases will be run is
determined by sorting the test function names with respect to the
built-in ordering for strings.
Often it is desirable to group suites of test cases together, so as to run tests
for the whole system at once. This is easy, since :class:`TestSuite` instances
can be added to a :class:`TestSuite` just as :class:`TestCase` instances can be
added to a :class:`TestSuite`::
suite1 = module1.TheTestSuite()
suite2 = module2.TheTestSuite()
alltests = unittest.TestSuite([suite1, suite2])
You can place the definitions of test cases and test suites in the same modules
as the code they are to test (such as :file:`widget.py`), but there are several
advantages to placing the test code in a separate module, such as
:file:`test_widget.py`:
* The test module can be run standalone from the command line.
* The test code can more easily be separated from shipped code.
* There is less temptation to change test code to fit the code it tests without
a good reason.
* Test code should be modified much less frequently than the code it tests.
* Tested code can be refactored more easily.
* Tests for modules written in C must be in separate modules anyway, so why not
be consistent?
* If the testing strategy changes, there is no need to change the source code.
.. _legacy-unit-tests:
Re-using old test code
----------------------
Some users will find that they have existing test code that they would like to
run from :mod:`unittest`, without converting every old test function to a
:class:`TestCase` subclass.
For this reason, :mod:`unittest` provides a :class:`FunctionTestCase` class.
This subclass of :class:`TestCase` can be used to wrap an existing test
function. Set-up and tear-down functions can also be provided.
Given the following test function::
def testSomething():
something = makeSomething()
assert something.name is not None
# ...
one can create an equivalent test case instance as follows::
testcase = unittest.FunctionTestCase(testSomething)
If there are additional set-up and tear-down methods that should be called as
part of the test case's operation, they can also be provided like so::
testcase = unittest.FunctionTestCase(testSomething,
setUp=makeSomethingDB,
tearDown=deleteSomethingDB)
To make migrating existing test suites easier, :mod:`unittest` supports tests
raising :exc:`AssertionError` to indicate test failure. However, it is
recommended that you use the explicit :meth:`TestCase.fail\*` and
:meth:`TestCase.assert\*` methods instead, as future versions of :mod:`unittest`
may treat :exc:`AssertionError` differently.
.. note::
Even though :class:`FunctionTestCase` can be used to quickly convert an
existing test base over to a :mod:`unittest`\ -based system, this approach is
not recommended. Taking the time to set up proper :class:`TestCase`
subclasses will make future test refactorings infinitely easier.
In some cases, the existing tests may have been written using the :mod:`doctest`
module. If so, :mod:`doctest` provides a :class:`DocTestSuite` class that can
automatically build :class:`unittest.TestSuite` instances from the existing
:mod:`doctest`\ -based tests.
.. _unittest-skipping:
Skipping tests and expected failures
------------------------------------
.. versionadded:: 2.7
Unittest supports skipping individual test methods and even whole classes of
tests. In addition, it supports marking a test as an "expected failure," a test
that is broken and will fail, but shouldn't be counted as a failure on a
:class:`TestResult`.
Skipping a test is simply a matter of using the :func:`skip` :term:`decorator`
or one of its conditional variants.
Basic skipping looks like this::
class MyTestCase(unittest.TestCase):
@unittest.skip("demonstrating skipping")
def test_nothing(self):
self.fail("shouldn't happen")
@unittest.skipIf(mylib.__version__ < (1, 3),
"not supported in this library version")
def test_format(self):
# Tests that work for only a certain version of the library.
pass
@unittest.skipUnless(sys.platform.startswith("win"), "requires Windows")
def test_windows_support(self):
# windows specific testing code
pass
This is the output of running the example above in verbose mode::
test_format (__main__.MyTestCase) ... skipped 'not supported in this library version'
test_nothing (__main__.MyTestCase) ... skipped 'demonstrating skipping'
test_windows_support (__main__.MyTestCase) ... skipped 'requires Windows'
----------------------------------------------------------------------
Ran 3 tests in 0.005s
OK (skipped=3)
Classes can be skipped just like methods::
@unittest.skip("showing class skipping")
class MySkippedTestCase(unittest.TestCase):
def test_not_run(self):
pass
:meth:`TestCase.setUp` can also skip the test. This is useful when a resource
that needs to be set up is not available.
Expected failures use the :func:`expectedFailure` decorator. ::
class ExpectedFailureTestCase(unittest.TestCase):
@unittest.expectedFailure
def test_fail(self):
self.assertEqual(1, 0, "broken")
It's easy to roll your own skipping decorators by making a decorator that calls
:func:`skip` on the test when it wants it to be skipped. This decorator skips
the test unless the passed object has a certain attribute::
def skipUnlessHasattr(obj, attr):
if hasattr(obj, attr):
return lambda func: func
return unittest.skip("{!r} doesn't have {!r}".format(obj, attr))
The following decorators implement test skipping and expected failures:
.. function:: skip(reason)
Unconditionally skip the decorated test. *reason* should describe why the
test is being skipped.
.. function:: skipIf(condition, reason)
Skip the decorated test if *condition* is true.
.. function:: skipUnless(condition, reason)
Skip the decorated test unless *condition* is true.
.. function:: expectedFailure
Mark the test as an expected failure. If the test fails when run, the test
is not counted as a failure.
.. exception:: SkipTest(reason)
This exception is raised to skip a test.
Usually you can use :meth:`TestCase.skipTest` or one of the skipping
decorators instead of raising this directly.
Skipped tests will not have :meth:`setUp` or :meth:`tearDown` run around them.
Skipped classes will not have :meth:`setUpClass` or :meth:`tearDownClass` run.
.. _unittest-contents:
Classes and functions
---------------------
This section describes in depth the API of :mod:`unittest`.
.. _testcase-objects:
Test cases
~~~~~~~~~~
.. class:: TestCase(methodName='runTest')
Instances of the :class:`TestCase` class represent the smallest testable units
in the :mod:`unittest` universe. This class is intended to be used as a base
class, with specific tests being implemented by concrete subclasses. This class
implements the interface needed by the test runner to allow it to drive the
test, and methods that the test code can use to check for and report various
kinds of failure.
Each instance of :class:`TestCase` will run a single test method: the method
named *methodName*. If you remember, we had an earlier example that went
something like this::
def suite():
suite = unittest.TestSuite()
suite.addTest(WidgetTestCase('test_default_size'))
suite.addTest(WidgetTestCase('test_resize'))
return suite
Here, we create two instances of :class:`WidgetTestCase`, each of which runs a
single test.
*methodName* defaults to :meth:`runTest`.
:class:`TestCase` instances provide three groups of methods: one group used
to run the test, another used by the test implementation to check conditions
and report failures, and some inquiry methods allowing information about the
test itself to be gathered.
Methods in the first group (running the test) are:
.. method:: setUp()
Method called to prepare the test fixture. This is called immediately
before calling the test method; other than :exc:`AssertionError` or :exc:`SkipTest`,
any exception raised by this method will be considered an error rather than
a test failure. The default implementation does nothing.
.. method:: tearDown()
Method called immediately after the test method has been called and the
result recorded. This is called even if the test method raised an
exception, so the implementation in subclasses may need to be particularly
careful about checking internal state. Any exception, other than
:exc:`AssertionError` or :exc:`SkipTest`, raised by this method will be
considered an additional error rather than a test failure (thus increasing
the total number of reported errors). This method will only be called if
the :meth:`setUp` succeeds, regardless of the outcome of the test method.
The default implementation does nothing.
.. method:: setUpClass()
A class method called before tests in an individual class are run.
``setUpClass`` is called with the class as the only argument
and must be decorated as a :func:`classmethod`::
@classmethod
def setUpClass(cls):
...
See `Class and Module Fixtures`_ for more details.
.. versionadded:: 2.7
.. method:: tearDownClass()
A class method called after tests in an individual class have run.
``tearDownClass`` is called with the class as the only argument
and must be decorated as a :meth:`classmethod`::
@classmethod
def tearDownClass(cls):
...
See `Class and Module Fixtures`_ for more details.
.. versionadded:: 2.7
.. method:: run(result=None)
Run the test, collecting the result into the test result object passed as
*result*. If *result* is omitted or ``None``, a temporary result
object is created (by calling the :meth:`defaultTestResult` method) and
used. The result object is not returned to :meth:`run`'s caller.
The same effect may be had by simply calling the :class:`TestCase`
instance.
.. method:: skipTest(reason)
Calling this during a test method or :meth:`setUp` skips the current
test. See :ref:`unittest-skipping` for more information.
.. versionadded:: 2.7
.. method:: debug()
Run the test without collecting the result. This allows exceptions raised
by the test to be propagated to the caller, and can be used to support
running tests under a debugger.
.. _assert-methods:
The :class:`TestCase` class provides several assert methods to check for and
report failures. The following table lists the most commonly used methods
(see the tables below for more assert methods):
+-----------------------------------------+-----------------------------+---------------+
| Method | Checks that | New in |
+=========================================+=============================+===============+
| :meth:`assertEqual(a, b) | ``a == b`` | |
| <TestCase.assertEqual>` | | |
+-----------------------------------------+-----------------------------+---------------+
| :meth:`assertNotEqual(a, b) | ``a != b`` | |
| <TestCase.assertNotEqual>` | | |
+-----------------------------------------+-----------------------------+---------------+
| :meth:`assertTrue(x) | ``bool(x) is True`` | |
| <TestCase.assertTrue>` | | |
+-----------------------------------------+-----------------------------+---------------+
| :meth:`assertFalse(x) | ``bool(x) is False`` | |
| <TestCase.assertFalse>` | | |
+-----------------------------------------+-----------------------------+---------------+
| :meth:`assertIs(a, b) | ``a is b`` | 2.7 |
| <TestCase.assertIs>` | | |
+-----------------------------------------+-----------------------------+---------------+
| :meth:`assertIsNot(a, b) | ``a is not b`` | 2.7 |
| <TestCase.assertIsNot>` | | |
+-----------------------------------------+-----------------------------+---------------+
| :meth:`assertIsNone(x) | ``x is None`` | 2.7 |
| <TestCase.assertIsNone>` | | |
+-----------------------------------------+-----------------------------+---------------+
| :meth:`assertIsNotNone(x) | ``x is not None`` | 2.7 |
| <TestCase.assertIsNotNone>` | | |
+-----------------------------------------+-----------------------------+---------------+
| :meth:`assertIn(a, b) | ``a in b`` | 2.7 |
| <TestCase.assertIn>` | | |
+-----------------------------------------+-----------------------------+---------------+
| :meth:`assertNotIn(a, b) | ``a not in b`` | 2.7 |
| <TestCase.assertNotIn>` | | |
+-----------------------------------------+-----------------------------+---------------+
| :meth:`assertIsInstance(a, b) | ``isinstance(a, b)`` | 2.7 |
| <TestCase.assertIsInstance>` | | |
+-----------------------------------------+-----------------------------+---------------+
| :meth:`assertNotIsInstance(a, b) | ``not isinstance(a, b)`` | 2.7 |
| <TestCase.assertNotIsInstance>` | | |
+-----------------------------------------+-----------------------------+---------------+
All the assert methods (except :meth:`assertRaises`,
:meth:`assertRaisesRegexp`)
accept a *msg* argument that, if specified, is used as the error message on
failure (see also :data:`longMessage`).
.. method:: assertEqual(first, second, msg=None)
Test that *first* and *second* are equal. If the values do not compare
equal, the test will fail.
In addition, if *first* and *second* are the exact same type and one of
list, tuple, dict, set, frozenset or unicode or any type that a subclass
registers with :meth:`addTypeEqualityFunc` the type-specific equality
function will be called in order to generate a more useful default
error message (see also the :ref:`list of type-specific methods
<type-specific-methods>`).
.. versionchanged:: 2.7
Added the automatic calling of type-specific equality function.
.. method:: assertNotEqual(first, second, msg=None)
Test that *first* and *second* are not equal. If the values do compare
equal, the test will fail.
.. method:: assertTrue(expr, msg=None)
assertFalse(expr, msg=None)
Test that *expr* is true (or false).
Note that this is equivalent to ``bool(expr) is True`` and not to ``expr
is True`` (use ``assertIs(expr, True)`` for the latter). This method
should also be avoided when more specific methods are available (e.g.
``assertEqual(a, b)`` instead of ``assertTrue(a == b)``), because they
provide a better error message in case of failure.
.. method:: assertIs(first, second, msg=None)
assertIsNot(first, second, msg=None)
Test that *first* and *second* evaluate (or don't evaluate) to the same object.
.. versionadded:: 2.7
.. method:: assertIsNone(expr, msg=None)
assertIsNotNone(expr, msg=None)
Test that *expr* is (or is not) ``None``.
.. versionadded:: 2.7
.. method:: assertIn(first, second, msg=None)
assertNotIn(first, second, msg=None)
Test that *first* is (or is not) in *second*.
.. versionadded:: 2.7
.. method:: assertIsInstance(obj, cls, msg=None)
assertNotIsInstance(obj, cls, msg=None)
Test that *obj* is (or is not) an instance of *cls* (which can be a
class or a tuple of classes, as supported by :func:`isinstance`).
To check for the exact type, use :func:`assertIs(type(obj), cls) <assertIs>`.
.. versionadded:: 2.7
It is also possible to check that exceptions and warnings are raised using
the following methods:
+---------------------------------------------------------+--------------------------------------+------------+
| Method | Checks that | New in |
+=========================================================+======================================+============+
| :meth:`assertRaises(exc, fun, *args, **kwds) | ``fun(*args, **kwds)`` raises *exc* | |
| <TestCase.assertRaises>` | | |
+---------------------------------------------------------+--------------------------------------+------------+
| :meth:`assertRaisesRegexp(exc, r, fun, *args, **kwds) | ``fun(*args, **kwds)`` raises *exc* | 2.7 |
| <TestCase.assertRaisesRegexp>` | and the message matches regex *r* | |
+---------------------------------------------------------+--------------------------------------+------------+
.. method:: assertRaises(exception, callable, *args, **kwds)
assertRaises(exception)
Test that an exception is raised when *callable* is called with any
positional or keyword arguments that are also passed to
:meth:`assertRaises`. The test passes if *exception* is raised, is an
error if another exception is raised, or fails if no exception is raised.
To catch any of a group of exceptions, a tuple containing the exception
classes may be passed as *exception*.
If only the *exception* argument is given, returns a context manager so
that the code under test can be written inline rather than as a function::
with self.assertRaises(SomeException):
do_something()
The context manager will store the caught exception object in its
:attr:`exception` attribute. This can be useful if the intention
is to perform additional checks on the exception raised::
with self.assertRaises(SomeException) as cm:
do_something()
the_exception = cm.exception
self.assertEqual(the_exception.error_code, 3)
.. versionchanged:: 2.7
Added the ability to use :meth:`assertRaises` as a context manager.
.. method:: assertRaisesRegexp(exception, regexp, callable, *args, **kwds)
assertRaisesRegexp(exception, regexp)
Like :meth:`assertRaises` but also tests that *regexp* matches
on the string representation of the raised exception. *regexp* may be
a regular expression object or a string containing a regular expression
suitable for use by :func:`re.search`. Examples::
self.assertRaisesRegexp(ValueError, "invalid literal for.*XYZ'$",
int, 'XYZ')
or::
with self.assertRaisesRegexp(ValueError, 'literal'):
int('XYZ')
.. versionadded:: 2.7
There are also other methods used to perform more specific checks, such as:
+---------------------------------------+--------------------------------+--------------+
| Method | Checks that | New in |
+=======================================+================================+==============+
| :meth:`assertAlmostEqual(a, b) | ``round(a-b, 7) == 0`` | |
| <TestCase.assertAlmostEqual>` | | |
+---------------------------------------+--------------------------------+--------------+
| :meth:`assertNotAlmostEqual(a, b) | ``round(a-b, 7) != 0`` | |
| <TestCase.assertNotAlmostEqual>` | | |
+---------------------------------------+--------------------------------+--------------+
| :meth:`assertGreater(a, b) | ``a > b`` | 2.7 |
| <TestCase.assertGreater>` | | |
+---------------------------------------+--------------------------------+--------------+
| :meth:`assertGreaterEqual(a, b) | ``a >= b`` | 2.7 |
| <TestCase.assertGreaterEqual>` | | |
+---------------------------------------+--------------------------------+--------------+
| :meth:`assertLess(a, b) | ``a < b`` | 2.7 |
| <TestCase.assertLess>` | | |
+---------------------------------------+--------------------------------+--------------+
| :meth:`assertLessEqual(a, b) | ``a <= b`` | 2.7 |
| <TestCase.assertLessEqual>` | | |
+---------------------------------------+--------------------------------+--------------+
| :meth:`assertRegexpMatches(s, r) | ``r.search(s)`` | 2.7 |
| <TestCase.assertRegexpMatches>` | | |
+---------------------------------------+--------------------------------+--------------+
| :meth:`assertNotRegexpMatches(s, r) | ``not r.search(s)`` | 2.7 |
| <TestCase.assertNotRegexpMatches>` | | |
+---------------------------------------+--------------------------------+--------------+
| :meth:`assertItemsEqual(a, b) | sorted(a) == sorted(b) and | 2.7 |
| <TestCase.assertItemsEqual>` | works with unhashable objs | |
+---------------------------------------+--------------------------------+--------------+
| :meth:`assertDictContainsSubset(a, b) | all the key/value pairs | 2.7 |
| <TestCase.assertDictContainsSubset>` | in *a* exist in *b* | |
+---------------------------------------+--------------------------------+--------------+
.. method:: assertAlmostEqual(first, second, places=7, msg=None, delta=None)
assertNotAlmostEqual(first, second, places=7, msg=None, delta=None)
Test that *first* and *second* are approximately (or not approximately)
equal by computing the difference, rounding to the given number of
decimal *places* (default 7), and comparing to zero. Note that these
methods round the values to the given number of *decimal places* (i.e.
like the :func:`round` function) and not *significant digits*.
If *delta* is supplied instead of *places* then the difference
between *first* and *second* must be less or equal to (or greater than) *delta*.
Supplying both *delta* and *places* raises a ``TypeError``.
.. versionchanged:: 2.7
:meth:`assertAlmostEqual` automatically considers almost equal objects
that compare equal. :meth:`assertNotAlmostEqual` automatically fails
if the objects compare equal. Added the *delta* keyword argument.
.. method:: assertGreater(first, second, msg=None)
assertGreaterEqual(first, second, msg=None)
assertLess(first, second, msg=None)
assertLessEqual(first, second, msg=None)
Test that *first* is respectively >, >=, < or <= than *second* depending
on the method name. If not, the test will fail::
>>> self.assertGreaterEqual(3, 4)
AssertionError: "3" unexpectedly not greater than or equal to "4"
.. versionadded:: 2.7
.. method:: assertRegexpMatches(text, regexp, msg=None)
Test that a *regexp* search matches *text*. In case
of failure, the error message will include the pattern and the *text* (or
the pattern and the part of *text* that unexpectedly matched). *regexp*
may be a regular expression object or a string containing a regular
expression suitable for use by :func:`re.search`.
.. versionadded:: 2.7
.. method:: assertNotRegexpMatches(text, regexp, msg=None)
Verifies that a *regexp* search does not match *text*. Fails with an error
message including the pattern and the part of *text* that matches. *regexp*
may be a regular expression object or a string containing a regular
expression suitable for use by :func:`re.search`.
.. versionadded:: 2.7
.. method:: assertItemsEqual(actual, expected, msg=None)
Test that sequence *expected* contains the same elements as *actual*,
regardless of their order. When they don't, an error message listing the
differences between the sequences will be generated.
Duplicate elements are *not* ignored when comparing *actual* and
*expected*. It verifies if each element has the same count in both
sequences. It is the equivalent of ``assertEqual(sorted(expected),
sorted(actual))`` but it works with sequences of unhashable objects as
well.
In Python 3, this method is named ``assertCountEqual``.
.. versionadded:: 2.7
.. method:: assertDictContainsSubset(expected, actual, msg=None)
Tests whether the key/value pairs in dictionary *actual* are a
superset of those in *expected*. If not, an error message listing
the missing keys and mismatched values is generated.
.. versionadded:: 2.7
.. deprecated:: 3.2
.. _type-specific-methods:
The :meth:`assertEqual` method dispatches the equality check for objects of
the same type to different type-specific methods. These methods are already
implemented for most of the built-in types, but it's also possible to
register new methods using :meth:`addTypeEqualityFunc`:
.. method:: addTypeEqualityFunc(typeobj, function)
Registers a type-specific method called by :meth:`assertEqual` to check
if two objects of exactly the same *typeobj* (not subclasses) compare
equal. *function* must take two positional arguments and a third msg=None
keyword argument just as :meth:`assertEqual` does. It must raise
:data:`self.failureException(msg) <failureException>` when inequality
between the first two parameters is detected -- possibly providing useful
information and explaining the inequalities in details in the error
message.
.. versionadded:: 2.7
The list of type-specific methods automatically used by
:meth:`~TestCase.assertEqual` are summarized in the following table. Note
that it's usually not necessary to invoke these methods directly.
+-----------------------------------------+-----------------------------+--------------+
| Method | Used to compare | New in |
+=========================================+=============================+==============+
| :meth:`assertMultiLineEqual(a, b) | strings | 2.7 |
| <TestCase.assertMultiLineEqual>` | | |
+-----------------------------------------+-----------------------------+--------------+
| :meth:`assertSequenceEqual(a, b) | sequences | 2.7 |
| <TestCase.assertSequenceEqual>` | | |
+-----------------------------------------+-----------------------------+--------------+
| :meth:`assertListEqual(a, b) | lists | 2.7 |
| <TestCase.assertListEqual>` | | |
+-----------------------------------------+-----------------------------+--------------+
| :meth:`assertTupleEqual(a, b) | tuples | 2.7 |
| <TestCase.assertTupleEqual>` | | |
+-----------------------------------------+-----------------------------+--------------+
| :meth:`assertSetEqual(a, b) | sets or frozensets | 2.7 |
| <TestCase.assertSetEqual>` | | |
+-----------------------------------------+-----------------------------+--------------+
| :meth:`assertDictEqual(a, b) | dicts | 2.7 |
| <TestCase.assertDictEqual>` | | |
+-----------------------------------------+-----------------------------+--------------+
.. method:: assertMultiLineEqual(first, second, msg=None)
Test that the multiline string *first* is equal to the string *second*.
When not equal a diff of the two strings highlighting the differences
will be included in the error message. This method is used by default
when comparing Unicode strings with :meth:`assertEqual`.
.. versionadded:: 2.7
.. method:: assertSequenceEqual(seq1, seq2, msg=None, seq_type=None)
Tests that two sequences are equal. If a *seq_type* is supplied, both
*seq1* and *seq2* must be instances of *seq_type* or a failure will
be raised. If the sequences are different an error message is
constructed that shows the difference between the two.
This method is not called directly by :meth:`assertEqual`, but
it's used to implement :meth:`assertListEqual` and
:meth:`assertTupleEqual`.
.. versionadded:: 2.7
.. method:: assertListEqual(list1, list2, msg=None)
assertTupleEqual(tuple1, tuple2, msg=None)
Tests that two lists or tuples are equal. If not, an error message is
constructed that shows only the differences between the two. An error
is also raised if either of the parameters are of the wrong type.
These methods are used by default when comparing lists or tuples with
:meth:`assertEqual`.
.. versionadded:: 2.7
.. method:: assertSetEqual(set1, set2, msg=None)
Tests that two sets are equal. If not, an error message is constructed
that lists the differences between the sets. This method is used by
default when comparing sets or frozensets with :meth:`assertEqual`.
Fails if either of *set1* or *set2* does not have a :meth:`set.difference`
method.
.. versionadded:: 2.7
.. method:: assertDictEqual(expected, actual, msg=None)
Test that two dictionaries are equal. If not, an error message is
constructed that shows the differences in the dictionaries. This
method will be used by default to compare dictionaries in
calls to :meth:`assertEqual`.
.. versionadded:: 2.7
.. _other-methods-and-attrs:
Finally the :class:`TestCase` provides the following methods and attributes:
.. method:: fail(msg=None)
Signals a test failure unconditionally, with *msg* or ``None`` for
the error message.
.. attribute:: failureException
This class attribute gives the exception raised by the test method. If a
test framework needs to use a specialized exception, possibly to carry
additional information, it must subclass this exception in order to "play
fair" with the framework. The initial value of this attribute is
:exc:`AssertionError`.
.. attribute:: longMessage
If set to ``True`` then any explicit failure message you pass in to the
:ref:`assert methods <assert-methods>` will be appended to the end of the
normal failure message. The normal messages contain useful information
about the objects involved, for example the message from assertEqual
shows you the repr of the two unequal objects. Setting this attribute
to ``True`` allows you to have a custom error message in addition to the
normal one.
This attribute defaults to ``False``, meaning that a custom message passed
to an assert method will silence the normal message.
The class setting can be overridden in individual tests by assigning an
instance attribute to ``True`` or ``False`` before calling the assert methods.
.. versionadded:: 2.7
.. attribute:: maxDiff
This attribute controls the maximum length of diffs output by assert
methods that report diffs on failure. It defaults to 80*8 characters.
Assert methods affected by this attribute are
:meth:`assertSequenceEqual` (including all the sequence comparison
methods that delegate to it), :meth:`assertDictEqual` and
:meth:`assertMultiLineEqual`.
Setting ``maxDiff`` to ``None`` means that there is no maximum length of
diffs.
.. versionadded:: 2.7
Testing frameworks can use the following methods to collect information on
the test:
.. method:: countTestCases()
Return the number of tests represented by this test object. For
:class:`TestCase` instances, this will always be ``1``.
.. method:: defaultTestResult()
Return an instance of the test result class that should be used for this
test case class (if no other result instance is provided to the
:meth:`run` method).
For :class:`TestCase` instances, this will always be an instance of
:class:`TestResult`; subclasses of :class:`TestCase` should override this
as necessary.
.. method:: id()
Return a string identifying the specific test case. This is usually the
full name of the test method, including the module and class name.
.. method:: shortDescription()
Returns a description of the test, or ``None`` if no description
has been provided. The default implementation of this method
returns the first line of the test method's docstring, if available,
or :const:`None`.
.. method:: addCleanup(function, *args, **kwargs)
Add a function to be called after :meth:`tearDown` to cleanup resources
used during the test. Functions will be called in reverse order to the
order they are added (LIFO). They are called with any arguments and
keyword arguments passed into :meth:`addCleanup` when they are
added.
If :meth:`setUp` fails, meaning that :meth:`tearDown` is not called,
then any cleanup functions added will still be called.
.. versionadded:: 2.7
.. method:: doCleanups()
This method is called unconditionally after :meth:`tearDown`, or
after :meth:`setUp` if :meth:`setUp` raises an exception.
It is responsible for calling all the cleanup functions added by
:meth:`addCleanup`. If you need cleanup functions to be called
*prior* to :meth:`tearDown` then you can call :meth:`doCleanups`
yourself.
:meth:`doCleanups` pops methods off the stack of cleanup
functions one at a time, so it can be called at any time.
.. versionadded:: 2.7
.. class:: FunctionTestCase(testFunc, setUp=None, tearDown=None, description=None)
This class implements the portion of the :class:`TestCase` interface which
allows the test runner to drive the test, but does not provide the methods
which test code can use to check and report errors. This is used to create
test cases using legacy test code, allowing it to be integrated into a
:mod:`unittest`-based test framework.
Deprecated aliases
##################
For historical reasons, some of the :class:`TestCase` methods had one or more
aliases that are now deprecated. The following table lists the correct names
along with their deprecated aliases:
============================== ===============================
Method Name Deprecated alias(es)
============================== ===============================
:meth:`.assertEqual` failUnlessEqual, assertEquals
:meth:`.assertNotEqual` failIfEqual
:meth:`.assertTrue` failUnless, assert\_
:meth:`.assertFalse` failIf
:meth:`.assertRaises` failUnlessRaises
:meth:`.assertAlmostEqual` failUnlessAlmostEqual
:meth:`.assertNotAlmostEqual` failIfAlmostEqual
============================== ===============================
.. deprecated:: 2.7
the aliases listed in the second column
.. _testsuite-objects:
Grouping tests
~~~~~~~~~~~~~~
.. class:: TestSuite(tests=())
This class represents an aggregation of individual test cases and test suites.
The class presents the interface needed by the test runner to allow it to be run
as any other test case. Running a :class:`TestSuite` instance is the same as
iterating over the suite, running each test individually.
If *tests* is given, it must be an iterable of individual test cases or other
test suites that will be used to build the suite initially. Additional methods
are provided to add test cases and suites to the collection later on.
:class:`TestSuite` objects behave much like :class:`TestCase` objects, except
they do not actually implement a test. Instead, they are used to aggregate
tests into groups of tests that should be run together. Some additional
methods are available to add tests to :class:`TestSuite` instances:
.. method:: TestSuite.addTest(test)
Add a :class:`TestCase` or :class:`TestSuite` to the suite.
.. method:: TestSuite.addTests(tests)
Add all the tests from an iterable of :class:`TestCase` and :class:`TestSuite`
instances to this test suite.
This is equivalent to iterating over *tests*, calling :meth:`addTest` for
each element.
:class:`TestSuite` shares the following methods with :class:`TestCase`:
.. method:: run(result)
Run the tests associated with this suite, collecting the result into the
test result object passed as *result*. Note that unlike
:meth:`TestCase.run`, :meth:`TestSuite.run` requires the result object to
be passed in.
.. method:: debug()
Run the tests associated with this suite without collecting the
result. This allows exceptions raised by the test to be propagated to the
caller and can be used to support running tests under a debugger.
.. method:: countTestCases()
Return the number of tests represented by this test object, including all
individual tests and sub-suites.
.. method:: __iter__()
Tests grouped by a :class:`TestSuite` are always accessed by iteration.
Subclasses can lazily provide tests by overriding :meth:`__iter__`. Note
that this method maybe called several times on a single suite
(for example when counting tests or comparing for equality)
so the tests returned must be the same for repeated iterations.
.. versionchanged:: 2.7
In earlier versions the :class:`TestSuite` accessed tests directly rather
than through iteration, so overriding :meth:`__iter__` wasn't sufficient
for providing tests.
In the typical usage of a :class:`TestSuite` object, the :meth:`run` method
is invoked by a :class:`TestRunner` rather than by the end-user test harness.
Loading and running tests
~~~~~~~~~~~~~~~~~~~~~~~~~
.. class:: TestLoader()
The :class:`TestLoader` class is used to create test suites from classes and
modules. Normally, there is no need to create an instance of this class; the
:mod:`unittest` module provides an instance that can be shared as
:data:`unittest.defaultTestLoader`. Using a subclass or instance, however,
allows customization of some configurable properties.
:class:`TestLoader` objects have the following methods:
.. method:: loadTestsFromTestCase(testCaseClass)
Return a suite of all test cases contained in the :class:`TestCase`\ -derived
:class:`testCaseClass`.
.. method:: loadTestsFromModule(module)
Return a suite of all test cases contained in the given module. This
method searches *module* for classes derived from :class:`TestCase` and
creates an instance of the class for each test method defined for the
class.
.. note::
While using a hierarchy of :class:`TestCase`\ -derived classes can be
convenient in sharing fixtures and helper functions, defining test
methods on base classes that are not intended to be instantiated
directly does not play well with this method. Doing so, however, can
be useful when the fixtures are different and defined in subclasses.
If a module provides a ``load_tests`` function it will be called to
load the tests. This allows modules to customize test loading.
This is the `load_tests protocol`_.
.. versionchanged:: 2.7
Support for ``load_tests`` added.
.. method:: loadTestsFromName(name, module=None)
Return a suite of all test cases given a string specifier.
The specifier *name* is a "dotted name" that may resolve either to a
module, a test case class, a test method within a test case class, a
:class:`TestSuite` instance, or a callable object which returns a
:class:`TestCase` or :class:`TestSuite` instance. These checks are
applied in the order listed here; that is, a method on a possible test
case class will be picked up as "a test method within a test case class",
rather than "a callable object".
For example, if you have a module :mod:`SampleTests` containing a
:class:`TestCase`\ -derived class :class:`SampleTestCase` with three test
methods (:meth:`test_one`, :meth:`test_two`, and :meth:`test_three`), the
specifier ``'SampleTests.SampleTestCase'`` would cause this method to
return a suite which will run all three test methods. Using the specifier
``'SampleTests.SampleTestCase.test_two'`` would cause it to return a test
suite which will run only the :meth:`test_two` test method. The specifier
can refer to modules and packages which have not been imported; they will
be imported as a side-effect.
The method optionally resolves *name* relative to the given *module*.
.. method:: loadTestsFromNames(names, module=None)
Similar to :meth:`loadTestsFromName`, but takes a sequence of names rather
than a single name. The return value is a test suite which supports all
the tests defined for each name.
.. method:: getTestCaseNames(testCaseClass)
Return a sorted sequence of method names found within *testCaseClass*;
this should be a subclass of :class:`TestCase`.
.. method:: discover(start_dir, pattern='test*.py', top_level_dir=None)
Find all the test modules by recursing into subdirectories from the
specified start directory, and return a TestSuite object containing them.
Only test files that match *pattern* will be loaded. (Using shell style
pattern matching.) Only module names that are importable (i.e. are valid
Python identifiers) will be loaded.
All test modules must be importable from the top level of the project. If
the start directory is not the top level directory then the top level
directory must be specified separately.
If importing a module fails, for example due to a syntax error, then this
will be recorded as a single error and discovery will continue.
If a test package name (directory with :file:`__init__.py`) matches the
pattern then the package will be checked for a ``load_tests``
function. If this exists then it will be called with *loader*, *tests*,
*pattern*.
If load_tests exists then discovery does *not* recurse into the package,
``load_tests`` is responsible for loading all tests in the package.
The pattern is deliberately not stored as a loader attribute so that
packages can continue discovery themselves. *top_level_dir* is stored so
``load_tests`` does not need to pass this argument in to
``loader.discover()``.
*start_dir* can be a dotted module name as well as a directory.
.. versionadded:: 2.7
The following attributes of a :class:`TestLoader` can be configured either by
subclassing or assignment on an instance:
.. attribute:: testMethodPrefix
String giving the prefix of method names which will be interpreted as test
methods. The default value is ``'test'``.
This affects :meth:`getTestCaseNames` and all the :meth:`loadTestsFrom\*`
methods.
.. attribute:: sortTestMethodsUsing
Function to be used to compare method names when sorting them in
:meth:`getTestCaseNames` and all the :meth:`loadTestsFrom\*` methods. The
default value is the built-in :func:`cmp` function; the attribute can also
be set to :const:`None` to disable the sort.
.. attribute:: suiteClass
Callable object that constructs a test suite from a list of tests. No
methods on the resulting object are needed. The default value is the
:class:`TestSuite` class.
This affects all the :meth:`loadTestsFrom\*` methods.
.. class:: TestResult
This class is used to compile information about which tests have succeeded
and which have failed.
A :class:`TestResult` object stores the results of a set of tests. The
:class:`TestCase` and :class:`TestSuite` classes ensure that results are
properly recorded; test authors do not need to worry about recording the
outcome of tests.
Testing frameworks built on top of :mod:`unittest` may want access to the
:class:`TestResult` object generated by running a set of tests for reporting
purposes; a :class:`TestResult` instance is returned by the
:meth:`TestRunner.run` method for this purpose.
:class:`TestResult` instances have the following attributes that will be of
interest when inspecting the results of running a set of tests:
.. attribute:: errors
A list containing 2-tuples of :class:`TestCase` instances and strings
holding formatted tracebacks. Each tuple represents a test which raised an
unexpected exception.
.. versionchanged:: 2.2
Contains formatted tracebacks instead of :func:`sys.exc_info` results.
.. attribute:: failures
A list containing 2-tuples of :class:`TestCase` instances and strings
holding formatted tracebacks. Each tuple represents a test where a failure
was explicitly signalled using the :meth:`TestCase.assert\*` methods.
.. versionchanged:: 2.2
Contains formatted tracebacks instead of :func:`sys.exc_info` results.
.. attribute:: skipped
A list containing 2-tuples of :class:`TestCase` instances and strings
holding the reason for skipping the test.
.. versionadded:: 2.7
.. attribute:: expectedFailures
A list containing 2-tuples of :class:`TestCase` instances and strings
holding formatted tracebacks. Each tuple represents an expected failure
of the test case.
.. attribute:: unexpectedSuccesses
A list containing :class:`TestCase` instances that were marked as expected
failures, but succeeded.
.. attribute:: shouldStop
Set to ``True`` when the execution of tests should stop by :meth:`stop`.
.. attribute:: testsRun
The total number of tests run so far.
.. attribute:: buffer
If set to true, ``sys.stdout`` and ``sys.stderr`` will be buffered in between
:meth:`startTest` and :meth:`stopTest` being called. Collected output will
only be echoed onto the real ``sys.stdout`` and ``sys.stderr`` if the test
fails or errors. Any output is also attached to the failure / error message.
.. versionadded:: 2.7
.. attribute:: failfast
If set to true :meth:`stop` will be called on the first failure or error,
halting the test run.
.. versionadded:: 2.7
.. method:: wasSuccessful()
Return ``True`` if all tests run so far have passed, otherwise returns
``False``.
.. method:: stop()
This method can be called to signal that the set of tests being run should
be aborted by setting the :attr:`shouldStop` attribute to ``True``.
:class:`TestRunner` objects should respect this flag and return without
running any additional tests.
For example, this feature is used by the :class:`TextTestRunner` class to
stop the test framework when the user signals an interrupt from the
keyboard. Interactive tools which provide :class:`TestRunner`
implementations can use this in a similar manner.
The following methods of the :class:`TestResult` class are used to maintain
the internal data structures, and may be extended in subclasses to support
additional reporting requirements. This is particularly useful in building
tools which support interactive reporting while tests are being run.
.. method:: startTest(test)
Called when the test case *test* is about to be run.
.. method:: stopTest(test)
Called after the test case *test* has been executed, regardless of the
outcome.
.. method:: startTestRun()
Called once before any tests are executed.
.. versionadded:: 2.7
.. method:: stopTestRun()
Called once after all tests are executed.
.. versionadded:: 2.7
.. method:: addError(test, err)
Called when the test case *test* raises an unexpected exception. *err* is a
tuple of the form returned by :func:`sys.exc_info`: ``(type, value,
traceback)``.
The default implementation appends a tuple ``(test, formatted_err)`` to
the instance's :attr:`errors` attribute, where *formatted_err* is a
formatted traceback derived from *err*.
.. method:: addFailure(test, err)
Called when the test case *test* signals a failure. *err* is a tuple of
the form returned by :func:`sys.exc_info`: ``(type, value, traceback)``.
The default implementation appends a tuple ``(test, formatted_err)`` to
the instance's :attr:`failures` attribute, where *formatted_err* is a
formatted traceback derived from *err*.
.. method:: addSuccess(test)
Called when the test case *test* succeeds.
The default implementation does nothing.
.. method:: addSkip(test, reason)
Called when the test case *test* is skipped. *reason* is the reason the
test gave for skipping.
The default implementation appends a tuple ``(test, reason)`` to the
instance's :attr:`skipped` attribute.
.. method:: addExpectedFailure(test, err)
Called when the test case *test* fails, but was marked with the
:func:`expectedFailure` decorator.
The default implementation appends a tuple ``(test, formatted_err)`` to
the instance's :attr:`expectedFailures` attribute, where *formatted_err*
is a formatted traceback derived from *err*.
.. method:: addUnexpectedSuccess(test)
Called when the test case *test* was marked with the
:func:`expectedFailure` decorator, but succeeded.
The default implementation appends the test to the instance's
:attr:`unexpectedSuccesses` attribute.
.. class:: TextTestResult(stream, descriptions, verbosity)
A concrete implementation of :class:`TestResult` used by the
:class:`TextTestRunner`.
.. versionadded:: 2.7
This class was previously named ``_TextTestResult``. The old name still
exists as an alias but is deprecated.
.. data:: defaultTestLoader
Instance of the :class:`TestLoader` class intended to be shared. If no
customization of the :class:`TestLoader` is needed, this instance can be used
instead of repeatedly creating new instances.
.. class:: TextTestRunner(stream=sys.stderr, descriptions=True, verbosity=1, \
failfast=False, buffer=False, resultclass=None)
A basic test runner implementation which prints results on standard error. It
has a few configurable parameters, but is essentially very simple. Graphical
applications which run test suites should provide alternate implementations.
.. method:: _makeResult()
This method returns the instance of ``TestResult`` used by :meth:`run`.
It is not intended to be called directly, but can be overridden in
subclasses to provide a custom ``TestResult``.
``_makeResult()`` instantiates the class or callable passed in the
``TextTestRunner`` constructor as the ``resultclass`` argument. It
defaults to :class:`TextTestResult` if no ``resultclass`` is provided.
The result class is instantiated with the following arguments::
stream, descriptions, verbosity
.. function:: main([module[, defaultTest[, argv[, testRunner[, testLoader[, exit[, verbosity[, failfast[, catchbreak[, buffer]]]]]]]]]])
A command-line program that loads a set of tests from *module* and runs them;
this is primarily for making test modules conveniently executable.
The simplest use for this function is to include the following line at the
end of a test script::
if __name__ == '__main__':
unittest.main()
You can run tests with more detailed information by passing in the verbosity
argument::
if __name__ == '__main__':
unittest.main(verbosity=2)
The *defaultTest* argument is the name of the test to run if no test names
are specified via *argv*. If not specified or ``None`` and no test names are
provided via *argv*, all tests found in *module* are run.
The *argv* argument can be a list of options passed to the program, with the
first element being the program name. If not specified or ``None``,
the values of :data:`sys.argv` are used.
The *testRunner* argument can either be a test runner class or an already
created instance of it. By default ``main`` calls :func:`sys.exit` with
an exit code indicating success or failure of the tests run.
The *testLoader* argument has to be a :class:`TestLoader` instance,
and defaults to :data:`defaultTestLoader`.
``main`` supports being used from the interactive interpreter by passing in the
argument ``exit=False``. This displays the result on standard output without
calling :func:`sys.exit`::
>>> from unittest import main
>>> main(module='test_module', exit=False)
The *failfast*, *catchbreak* and *buffer* parameters have the same
effect as the same-name `command-line options`_.
Calling ``main`` actually returns an instance of the ``TestProgram`` class.
This stores the result of the tests run as the ``result`` attribute.
.. versionchanged:: 2.7
The *exit*, *verbosity*, *failfast*, *catchbreak* and *buffer*
parameters were added.
load_tests Protocol
###################
.. versionadded:: 2.7
Modules or packages can customize how tests are loaded from them during normal
test runs or test discovery by implementing a function called ``load_tests``.
If a test module defines ``load_tests`` it will be called by
:meth:`TestLoader.loadTestsFromModule` with the following arguments::
load_tests(loader, standard_tests, None)
It should return a :class:`TestSuite`.
*loader* is the instance of :class:`TestLoader` doing the loading.
*standard_tests* are the tests that would be loaded by default from the
module. It is common for test modules to only want to add or remove tests
from the standard set of tests.
The third argument is used when loading packages as part of test discovery.
A typical ``load_tests`` function that loads tests from a specific set of
:class:`TestCase` classes may look like::
test_cases = (TestCase1, TestCase2, TestCase3)
def load_tests(loader, tests, pattern):
suite = TestSuite()
for test_class in test_cases:
tests = loader.loadTestsFromTestCase(test_class)
suite.addTests(tests)
return suite
If discovery is started, either from the command line or by calling
:meth:`TestLoader.discover`, with a pattern that matches a package
name then the package :file:`__init__.py` will be checked for ``load_tests``.
.. note::
The default pattern is ``'test*.py'``. This matches all Python files
that start with ``'test'`` but *won't* match any test directories.
A pattern like ``'test*'`` will match test packages as well as
modules.
If the package :file:`__init__.py` defines ``load_tests`` then it will be
called and discovery not continued into the package. ``load_tests``
is called with the following arguments::
load_tests(loader, standard_tests, pattern)
This should return a :class:`TestSuite` representing all the tests
from the package. (``standard_tests`` will only contain tests
collected from :file:`__init__.py`.)
Because the pattern is passed into ``load_tests`` the package is free to
continue (and potentially modify) test discovery. A 'do nothing'
``load_tests`` function for a test package would look like::
def load_tests(loader, standard_tests, pattern):
# top level directory cached on loader instance
this_dir = os.path.dirname(__file__)
package_tests = loader.discover(start_dir=this_dir, pattern=pattern)
standard_tests.addTests(package_tests)
return standard_tests
Class and Module Fixtures
-------------------------
Class and module level fixtures are implemented in :class:`TestSuite`. When
the test suite encounters a test from a new class then :meth:`tearDownClass`
from the previous class (if there is one) is called, followed by
:meth:`setUpClass` from the new class.
Similarly if a test is from a different module from the previous test then
``tearDownModule`` from the previous module is run, followed by
``setUpModule`` from the new module.
After all the tests have run the final ``tearDownClass`` and
``tearDownModule`` are run.
Note that shared fixtures do not play well with [potential] features like test
parallelization and they break test isolation. They should be used with care.
The default ordering of tests created by the unittest test loaders is to group
all tests from the same modules and classes together. This will lead to
``setUpClass`` / ``setUpModule`` (etc) being called exactly once per class and
module. If you randomize the order, so that tests from different modules and
classes are adjacent to each other, then these shared fixture functions may be
called multiple times in a single test run.
Shared fixtures are not intended to work with suites with non-standard
ordering. A ``BaseTestSuite`` still exists for frameworks that don't want to
support shared fixtures.
If there are any exceptions raised during one of the shared fixture functions
the test is reported as an error. Because there is no corresponding test
instance an ``_ErrorHolder`` object (that has the same interface as a
:class:`TestCase`) is created to represent the error. If you are just using
the standard unittest test runner then this detail doesn't matter, but if you
are a framework author it may be relevant.
setUpClass and tearDownClass
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These must be implemented as class methods::
import unittest
class Test(unittest.TestCase):
@classmethod
def setUpClass(cls):
cls._connection = createExpensiveConnectionObject()
@classmethod
def tearDownClass(cls):
cls._connection.destroy()
If you want the ``setUpClass`` and ``tearDownClass`` on base classes called
then you must call up to them yourself. The implementations in
:class:`TestCase` are empty.
If an exception is raised during a ``setUpClass`` then the tests in the class
are not run and the ``tearDownClass`` is not run. Skipped classes will not
have ``setUpClass`` or ``tearDownClass`` run. If the exception is a
:exc:`SkipTest` exception then the class will be reported as having been skipped
instead of as an error.
setUpModule and tearDownModule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These should be implemented as functions::
def setUpModule():
createConnection()
def tearDownModule():
closeConnection()
If an exception is raised in a ``setUpModule`` then none of the tests in the
module will be run and the ``tearDownModule`` will not be run. If the exception is a
:exc:`SkipTest` exception then the module will be reported as having been skipped
instead of as an error.
Signal Handling
---------------
The :option:`-c/--catch <unittest -c>` command-line option to unittest,
along with the ``catchbreak`` parameter to :func:`unittest.main()`, provide
more friendly handling of control-C during a test run. With catch break
behavior enabled control-C will allow the currently running test to complete,
and the test run will then end and report all the results so far. A second
control-c will raise a :exc:`KeyboardInterrupt` in the usual way.
The control-c handling signal handler attempts to remain compatible with code or
tests that install their own :const:`signal.SIGINT` handler. If the ``unittest``
handler is called but *isn't* the installed :const:`signal.SIGINT` handler,
i.e. it has been replaced by the system under test and delegated to, then it
calls the default handler. This will normally be the expected behavior by code
that replaces an installed handler and delegates to it. For individual tests
that need ``unittest`` control-c handling disabled the :func:`removeHandler`
decorator can be used.
There are a few utility functions for framework authors to enable control-c
handling functionality within test frameworks.
.. function:: installHandler()
Install the control-c handler. When a :const:`signal.SIGINT` is received
(usually in response to the user pressing control-c) all registered results
have :meth:`~TestResult.stop` called.
.. versionadded:: 2.7
.. function:: registerResult(result)
Register a :class:`TestResult` object for control-c handling. Registering a
result stores a weak reference to it, so it doesn't prevent the result from
being garbage collected.
Registering a :class:`TestResult` object has no side-effects if control-c
handling is not enabled, so test frameworks can unconditionally register
all results they create independently of whether or not handling is enabled.
.. versionadded:: 2.7
.. function:: removeResult(result)
Remove a registered result. Once a result has been removed then
:meth:`~TestResult.stop` will no longer be called on that result object in
response to a control-c.
.. versionadded:: 2.7
.. function:: removeHandler(function=None)
When called without arguments this function removes the control-c handler
if it has been installed. This function can also be used as a test decorator
to temporarily remove the handler while the test is being executed::
@unittest.removeHandler
def test_signal_handling(self):
...
.. versionadded:: 2.7
PK
%�\}2$� � " html/_sources/library/unix.rst.txtnu �[���
.. _unix:
**********************
Unix Specific Services
**********************
The modules described in this chapter provide interfaces to features that are
unique to the Unix operating system, or in some cases to some or many variants
of it. Here's an overview:
.. toctree::
posix.rst
pwd.rst
spwd.rst
grp.rst
crypt.rst
dl.rst
termios.rst
tty.rst
pty.rst
fcntl.rst
pipes.rst
posixfile.rst
resource.rst
nis.rst
syslog.rst
commands.rst
PK
%�\�:#�a �a $ html/_sources/library/urllib.rst.txtnu �[��� :mod:`urllib` --- Open arbitrary resources by URL
=================================================
.. module:: urllib
:synopsis: Open an arbitrary network resource by URL (requires sockets).
.. note::
The :mod:`urllib` module has been split into parts and renamed in
Python 3 to :mod:`urllib.request`, :mod:`urllib.parse`,
and :mod:`urllib.error`. The :term:`2to3` tool will automatically adapt
imports when converting your sources to Python 3.
Also note that the :func:`urllib.request.urlopen` function in Python 3 is
equivalent to :func:`urllib2.urlopen` and that :func:`urllib.urlopen` has
been removed.
.. index::
single: WWW
single: World Wide Web
single: URL
This module provides a high-level interface for fetching data across the World
Wide Web. In particular, the :func:`urlopen` function is similar to the
built-in function :func:`open`, but accepts Universal Resource Locators (URLs)
instead of filenames. Some restrictions apply --- it can only open URLs for
reading, and no seek operations are available.
.. seealso::
The `Requests package <http://docs.python-requests.org/>`_
is recommended for a higher-level HTTP client interface.
.. versionchanged:: 2.7.9
For HTTPS URIs, :mod:`urllib` performs all the neccessary certificate and hostname checks by default.
.. warning::
For Python versions earlier than 2.7.9, urllib does not attempt to validate the server certificates of HTTPS URIs. Use at your own risk!
High-level interface
--------------------
.. function:: urlopen(url[, data[, proxies[, context]]])
Open a network object denoted by a URL for reading. If the URL does not
have a scheme identifier, or if it has :file:`file:` as its scheme
identifier, this opens a local file (without :term:`universal newlines`);
otherwise it opens a socket to a server somewhere on the network. If the
connection cannot be made the :exc:`IOError` exception is raised. If all
went well, a file-like object is returned. This supports the following
methods: :meth:`read`, :meth:`readline`, :meth:`readlines`, :meth:`fileno`,
:meth:`close`, :meth:`info`, :meth:`getcode` and :meth:`geturl`. It also
has proper support for the :term:`iterator` protocol. One caveat: the
:meth:`read` method, if the size argument is omitted or negative, may not
read until the end of the data stream; there is no good way to determine
that the entire stream from a socket has been read in the general case.
Except for the :meth:`info`, :meth:`getcode` and :meth:`geturl` methods,
these methods have the same interface as for file objects --- see section
:ref:`bltin-file-objects` in this manual. (It is not a built-in file object,
however, so it can't be used at those few places where a true built-in file
object is required.)
.. index:: module: mimetools
The :meth:`info` method returns an instance of the class
:class:`mimetools.Message` containing meta-information associated with the
URL. When the method is HTTP, these headers are those returned by the server
at the head of the retrieved HTML page (including Content-Length and
Content-Type). When the method is FTP, a Content-Length header will be
present if (as is now usual) the server passed back a file length in response
to the FTP retrieval request. A Content-Type header will be present if the
MIME type can be guessed. When the method is local-file, returned headers
will include a Date representing the file's last-modified time, a
Content-Length giving file size, and a Content-Type containing a guess at the
file's type. See also the description of the :mod:`mimetools` module.
The :meth:`geturl` method returns the real URL of the page. In some cases, the
HTTP server redirects a client to another URL. The :func:`urlopen` function
handles this transparently, but in some cases the caller needs to know which URL
the client was redirected to. The :meth:`geturl` method can be used to get at
this redirected URL.
The :meth:`getcode` method returns the HTTP status code that was sent with the
response, or ``None`` if the URL is no HTTP URL.
If the *url* uses the :file:`http:` scheme identifier, the optional *data*
argument may be given to specify a ``POST`` request (normally the request type
is ``GET``). The *data* argument must be in standard
:mimetype:`application/x-www-form-urlencoded` format; see the :func:`urlencode`
function below.
The :func:`urlopen` function works transparently with proxies which do not
require authentication. In a Unix or Windows environment, set the
:envvar:`http_proxy`, or :envvar:`ftp_proxy` environment variables to a URL that
identifies the proxy server before starting the Python interpreter. For example
(the ``'%'`` is the command prompt)::
% http_proxy="http://www.someproxy.com:3128"
% export http_proxy
% python
...
The :envvar:`no_proxy` environment variable can be used to specify hosts which
shouldn't be reached via proxy; if set, it should be a comma-separated list
of hostname suffixes, optionally with ``:port`` appended, for example
``cern.ch,ncsa.uiuc.edu,some.host:8080``.
In a Windows environment, if no proxy environment variables are set, proxy
settings are obtained from the registry's Internet Settings section.
.. index:: single: Internet Config
In a Mac OS X environment, :func:`urlopen` will retrieve proxy information
from the OS X System Configuration Framework, which can be managed with
Network System Preferences panel.
Alternatively, the optional *proxies* argument may be used to explicitly specify
proxies. It must be a dictionary mapping scheme names to proxy URLs, where an
empty dictionary causes no proxies to be used, and ``None`` (the default value)
causes environmental proxy settings to be used as discussed above. For
example::
# Use http://www.someproxy.com:3128 for HTTP proxying
proxies = {'http': 'http://www.someproxy.com:3128'}
filehandle = urllib.urlopen(some_url, proxies=proxies)
# Don't use any proxies
filehandle = urllib.urlopen(some_url, proxies={})
# Use proxies from environment - both versions are equivalent
filehandle = urllib.urlopen(some_url, proxies=None)
filehandle = urllib.urlopen(some_url)
Proxies which require authentication for use are not currently supported;
this is considered an implementation limitation.
The *context* parameter may be set to a :class:`ssl.SSLContext` instance to
configure the SSL settings that are used if :func:`urlopen` makes a HTTPS
connection.
.. versionchanged:: 2.3
Added the *proxies* support.
.. versionchanged:: 2.6
Added :meth:`getcode` to returned object and support for the
:envvar:`no_proxy` environment variable.
.. versionchanged:: 2.7.9
The *context* parameter was added. All the neccessary certificate and hostname
checks are done by default.
.. deprecated:: 2.6
The :func:`urlopen` function has been removed in Python 3 in favor
of :func:`urllib2.urlopen`.
.. function:: urlretrieve(url[, filename[, reporthook[, data[, context]]]])
Copy a network object denoted by a URL to a local file, if necessary. If the URL
points to a local file, or a valid cached copy of the object exists, the object
is not copied. Return a tuple ``(filename, headers)`` where *filename* is the
local file name under which the object can be found, and *headers* is whatever
the :meth:`info` method of the object returned by :func:`urlopen` returned (for
a remote object, possibly cached). Exceptions are the same as for
:func:`urlopen`.
The second argument, if present, specifies the file location to copy to (if
absent, the location will be a tempfile with a generated name). The third
argument, if present, is a callable that will be called once on
establishment of the network connection and once after each block read
thereafter. The callable will be passed three arguments; a count of blocks
transferred so far, a block size in bytes, and the total size of the file. The
third argument may be ``-1`` on older FTP servers which do not return a file
size in response to a retrieval request.
If the *url* uses the :file:`http:` scheme identifier, the optional *data*
argument may be given to specify a ``POST`` request (normally the request type
is ``GET``). The *data* argument must in standard
:mimetype:`application/x-www-form-urlencoded` format; see the :func:`urlencode`
function below.
The *context* parameter may be set to a :class:`ssl.SSLContext` instance to
configure the SSL settings that are used if :func:`urlretrieve` makes a HTTPS
connection.
.. versionchanged:: 2.5
:func:`urlretrieve` will raise :exc:`ContentTooShortError` when it detects that
the amount of data available was less than the expected amount (which is the
size reported by a *Content-Length* header). This can occur, for example, when
the download is interrupted.
The *Content-Length* is treated as a lower bound: if there's more data to read,
:func:`urlretrieve` reads more data, but if less data is available, it raises
the exception.
You can still retrieve the downloaded data in this case, it is stored in the
:attr:`content` attribute of the exception instance.
If no *Content-Length* header was supplied, :func:`urlretrieve` can not check
the size of the data it has downloaded, and just returns it. In this case you
just have to assume that the download was successful.
.. versionchanged:: 2.7.9
The *context* parameter was added. All the neccessary certificate and hostname
checks are done by default.
.. data:: _urlopener
The public functions :func:`urlopen` and :func:`urlretrieve` create an instance
of the :class:`FancyURLopener` class and use it to perform their requested
actions. To override this functionality, programmers can create a subclass of
:class:`URLopener` or :class:`FancyURLopener`, then assign an instance of that
class to the ``urllib._urlopener`` variable before calling the desired function.
For example, applications may want to specify a different
:mailheader:`User-Agent` header than :class:`URLopener` defines. This can be
accomplished with the following code::
import urllib
class AppURLopener(urllib.FancyURLopener):
version = "App/1.7"
urllib._urlopener = AppURLopener()
.. function:: urlcleanup()
Clear the cache that may have been built up by previous calls to
:func:`urlretrieve`.
Utility functions
-----------------
.. function:: quote(string[, safe])
Replace special characters in *string* using the ``%xx`` escape. Letters,
digits, and the characters ``'_.-'`` are never quoted. By default, this
function is intended for quoting the path section of the URL. The optional
*safe* parameter specifies additional characters that should not be quoted
--- its default value is ``'/'``.
Example: ``quote('/~connolly/')`` yields ``'/%7econnolly/'``.
.. function:: quote_plus(string[, safe])
Like :func:`quote`, but also replaces spaces by plus signs, as required for
quoting HTML form values when building up a query string to go into a URL.
Plus signs in the original string are escaped unless they are included in
*safe*. It also does not have *safe* default to ``'/'``.
.. function:: unquote(string)
Replace ``%xx`` escapes by their single-character equivalent.
Example: ``unquote('/%7Econnolly/')`` yields ``'/~connolly/'``.
.. function:: unquote_plus(string)
Like :func:`unquote`, but also replaces plus signs by spaces, as required for
unquoting HTML form values.
.. function:: urlencode(query[, doseq])
Convert a mapping object or a sequence of two-element tuples to a
"percent-encoded" string, suitable to pass to :func:`urlopen` above as the
optional *data* argument. This is useful to pass a dictionary of form
fields to a ``POST`` request. The resulting string is a series of
``key=value`` pairs separated by ``'&'`` characters, where both *key* and
*value* are quoted using :func:`quote_plus` above. When a sequence of
two-element tuples is used as the *query* argument, the first element of
each tuple is a key and the second is a value. The value element in itself
can be a sequence and in that case, if the optional parameter *doseq* is
evaluates to ``True``, individual ``key=value`` pairs separated by ``'&'`` are
generated for each element of the value sequence for the key. The order of
parameters in the encoded string will match the order of parameter tuples in
the sequence. The :mod:`urlparse` module provides the functions
:func:`parse_qs` and :func:`parse_qsl` which are used to parse query strings
into Python data structures.
.. function:: pathname2url(path)
Convert the pathname *path* from the local syntax for a path to the form used in
the path component of a URL. This does not produce a complete URL. The return
value will already be quoted using the :func:`quote` function.
.. function:: url2pathname(path)
Convert the path component *path* from a percent-encoded URL to the local syntax for a
path. This does not accept a complete URL. This function uses :func:`unquote`
to decode *path*.
.. function:: getproxies()
This helper function returns a dictionary of scheme to proxy server URL
mappings. It scans the environment for variables named ``<scheme>_proxy``,
in case insensitive way, for all operating systems first, and when it cannot
find it, looks for proxy information from Mac OSX System Configuration for
Mac OS X and Windows Systems Registry for Windows.
If both lowercase and uppercase environment variables exist (and disagree),
lowercase is preferred.
.. note::
If the environment variable ``REQUEST_METHOD`` is set, which usually
indicates your script is running in a CGI environment, the environment
variable ``HTTP_PROXY`` (uppercase ``_PROXY``) will be ignored. This is
because that variable can be injected by a client using the "Proxy:" HTTP
header. If you need to use an HTTP proxy in a CGI environment, either use
``ProxyHandler`` explicitly, or make sure the variable name is in
lowercase (or at least the ``_proxy`` suffix).
.. note::
urllib also exposes certain utility functions like splittype, splithost and
others parsing URL into various components. But it is recommended to use
:mod:`urlparse` for parsing URLs rather than using these functions directly.
Python 3 does not expose these helper functions from :mod:`urllib.parse`
module.
URL Opener objects
------------------
.. class:: URLopener([proxies[, context[, **x509]]])
Base class for opening and reading URLs. Unless you need to support opening
objects using schemes other than :file:`http:`, :file:`ftp:`, or :file:`file:`,
you probably want to use :class:`FancyURLopener`.
By default, the :class:`URLopener` class sends a :mailheader:`User-Agent` header
of ``urllib/VVV``, where *VVV* is the :mod:`urllib` version number.
Applications can define their own :mailheader:`User-Agent` header by subclassing
:class:`URLopener` or :class:`FancyURLopener` and setting the class attribute
:attr:`version` to an appropriate string value in the subclass definition.
The optional *proxies* parameter should be a dictionary mapping scheme names to
proxy URLs, where an empty dictionary turns proxies off completely. Its default
value is ``None``, in which case environmental proxy settings will be used if
present, as discussed in the definition of :func:`urlopen`, above.
The *context* parameter may be a :class:`ssl.SSLContext` instance. If given,
it defines the SSL settings the opener uses to make HTTPS connections.
Additional keyword parameters, collected in *x509*, may be used for
authentication of the client when using the :file:`https:` scheme. The keywords
*key_file* and *cert_file* are supported to provide an SSL key and certificate;
both are needed to support client authentication.
:class:`URLopener` objects will raise an :exc:`IOError` exception if the server
returns an error code.
.. versionchanged:: 2.7.9
The *context* parameter was added. All the neccessary certificate and hostname
checks are done by default.
.. method:: open(fullurl[, data])
Open *fullurl* using the appropriate protocol. This method sets up cache and
proxy information, then calls the appropriate open method with its input
arguments. If the scheme is not recognized, :meth:`open_unknown` is called.
The *data* argument has the same meaning as the *data* argument of
:func:`urlopen`.
.. method:: open_unknown(fullurl[, data])
Overridable interface to open unknown URL types.
.. method:: retrieve(url[, filename[, reporthook[, data]]])
Retrieves the contents of *url* and places it in *filename*. The return value
is a tuple consisting of a local filename and either a
:class:`mimetools.Message` object containing the response headers (for remote
URLs) or ``None`` (for local URLs). The caller must then open and read the
contents of *filename*. If *filename* is not given and the URL refers to a
local file, the input filename is returned. If the URL is non-local and
*filename* is not given, the filename is the output of :func:`tempfile.mktemp`
with a suffix that matches the suffix of the last path component of the input
URL. If *reporthook* is given, it must be a function accepting three numeric
parameters. It will be called after each chunk of data is read from the
network. *reporthook* is ignored for local URLs.
If the *url* uses the :file:`http:` scheme identifier, the optional *data*
argument may be given to specify a ``POST`` request (normally the request type
is ``GET``). The *data* argument must in standard
:mimetype:`application/x-www-form-urlencoded` format; see the :func:`urlencode`
function below.
.. attribute:: version
Variable that specifies the user agent of the opener object. To get
:mod:`urllib` to tell servers that it is a particular user agent, set this in a
subclass as a class variable or in the constructor before calling the base
constructor.
.. class:: FancyURLopener(...)
:class:`FancyURLopener` subclasses :class:`URLopener` providing default handling
for the following HTTP response codes: 301, 302, 303, 307 and 401. For the 30x
response codes listed above, the :mailheader:`Location` header is used to fetch
the actual URL. For 401 response codes (authentication required), basic HTTP
authentication is performed. For the 30x response codes, recursion is bounded
by the value of the *maxtries* attribute, which defaults to 10.
For all other response codes, the method :meth:`http_error_default` is called
which you can override in subclasses to handle the error appropriately.
.. note::
According to the letter of :rfc:`2616`, 301 and 302 responses to POST requests
must not be automatically redirected without confirmation by the user. In
reality, browsers do allow automatic redirection of these responses, changing
the POST to a GET, and :mod:`urllib` reproduces this behaviour.
The parameters to the constructor are the same as those for :class:`URLopener`.
.. note::
When performing basic authentication, a :class:`FancyURLopener` instance calls
its :meth:`prompt_user_passwd` method. The default implementation asks the
users for the required information on the controlling terminal. A subclass may
override this method to support more appropriate behavior if needed.
The :class:`FancyURLopener` class offers one additional method that should be
overloaded to provide the appropriate behavior:
.. method:: prompt_user_passwd(host, realm)
Return information needed to authenticate the user at the given host in the
specified security realm. The return value should be a tuple, ``(user,
password)``, which can be used for basic authentication.
The implementation prompts for this information on the terminal; an application
should override this method to use an appropriate interaction model in the local
environment.
.. exception:: ContentTooShortError(msg[, content])
This exception is raised when the :func:`urlretrieve` function detects that the
amount of the downloaded data is less than the expected amount (given by the
*Content-Length* header). The :attr:`content` attribute stores the downloaded
(and supposedly truncated) data.
.. versionadded:: 2.5
:mod:`urllib` Restrictions
--------------------------
.. index::
pair: HTTP; protocol
pair: FTP; protocol
* Currently, only the following protocols are supported: HTTP, (versions 0.9 and
1.0), FTP, and local files.
* The caching feature of :func:`urlretrieve` has been disabled until I find the
time to hack proper processing of Expiration time headers.
* There should be a function to query whether a particular URL is in the cache.
* For backward compatibility, if a URL appears to point to a local file but the
file can't be opened, the URL is re-interpreted using the FTP protocol. This
can sometimes cause confusing error messages.
* The :func:`urlopen` and :func:`urlretrieve` functions can cause arbitrarily
long delays while waiting for a network connection to be set up. This means
that it is difficult to build an interactive Web client using these functions
without using threads.
.. index::
single: HTML
pair: HTTP; protocol
module: htmllib
* The data returned by :func:`urlopen` or :func:`urlretrieve` is the raw data
returned by the server. This may be binary data (such as an image), plain text
or (for example) HTML. The HTTP protocol provides type information in the reply
header, which can be inspected by looking at the :mailheader:`Content-Type`
header. If the returned data is HTML, you can use the module :mod:`htmllib` to
parse it.
.. index:: single: FTP
* The code handling the FTP protocol cannot differentiate between a file and a
directory. This can lead to unexpected behavior when attempting to read a URL
that points to a file that is not accessible. If the URL ends in a ``/``, it is
assumed to refer to a directory and will be handled accordingly. But if an
attempt to read a file leads to a 550 error (meaning the URL cannot be found or
is not accessible, often for permission reasons), then the path is treated as a
directory in order to handle the case when a directory is specified by a URL but
the trailing ``/`` has been left off. This can cause misleading results when
you try to fetch a file whose read permissions make it inaccessible; the FTP
code will try to read it, fail with a 550 error, and then perform a directory
listing for the unreadable file. If fine-grained control is needed, consider
using the :mod:`ftplib` module, subclassing :class:`FancyURLopener`, or changing
*_urlopener* to meet your needs.
* This module does not support the use of proxies which require authentication.
This may be implemented in the future.
.. index:: module: urlparse
* Although the :mod:`urllib` module contains (undocumented) routines to parse
and unparse URL strings, the recommended interface for URL manipulation is in
module :mod:`urlparse`.
.. _urllib-examples:
Examples
--------
Here is an example session that uses the ``GET`` method to retrieve a URL
containing parameters::
>>> import urllib
>>> params = urllib.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
>>> f = urllib.urlopen("http://www.musi-cal.com/cgi-bin/query?%s" % params)
>>> print f.read()
The following example uses the ``POST`` method instead::
>>> import urllib
>>> params = urllib.urlencode({'spam': 1, 'eggs': 2, 'bacon': 0})
>>> f = urllib.urlopen("http://www.musi-cal.com/cgi-bin/query", params)
>>> print f.read()
The following example uses an explicitly specified HTTP proxy, overriding
environment settings::
>>> import urllib
>>> proxies = {'http': 'http://proxy.example.com:8080/'}
>>> opener = urllib.FancyURLopener(proxies)
>>> f = opener.open("http://www.python.org")
>>> f.read()
The following example uses no proxies at all, overriding environment settings::
>>> import urllib
>>> opener = urllib.FancyURLopener({})
>>> f = opener.open("http://www.python.org/")
>>> f.read()
PK
%�\;��3�� �� % html/_sources/library/urllib2.rst.txtnu �[��� :mod:`urllib2` --- extensible library for opening URLs
======================================================
.. module:: urllib2
:synopsis: Next generation URL opening library.
.. moduleauthor:: Jeremy Hylton <jhylton@users.sourceforge.net>
.. sectionauthor:: Moshe Zadka <moshez@users.sourceforge.net>
.. note::
The :mod:`urllib2` module has been split across several modules in
Python 3 named :mod:`urllib.request` and :mod:`urllib.error`.
The :term:`2to3` tool will automatically adapt imports when converting
your sources to Python 3.
The :mod:`urllib2` module defines functions and classes which help in opening
URLs (mostly HTTP) in a complex world --- basic and digest authentication,
redirections, cookies and more.
.. seealso::
The `Requests package <http://requests.readthedocs.org/>`_
is recommended for a higher-level HTTP client interface.
The :mod:`urllib2` module defines the following functions:
.. function:: urlopen(url[, data[, timeout[, cafile[, capath[, cadefault[, context]]]]])
Open the URL *url*, which can be either a string or a :class:`Request` object.
*data* may be a string specifying additional data to send to the server, or
``None`` if no such data is needed. Currently HTTP requests are the only ones
that use *data*; the HTTP request will be a POST instead of a GET when the
*data* parameter is provided. *data* should be a buffer in the standard
:mimetype:`application/x-www-form-urlencoded` format. The
:func:`urllib.urlencode` function takes a mapping or sequence of 2-tuples and
returns a string in this format. urllib2 module sends HTTP/1.1 requests with
``Connection:close`` header included.
The optional *timeout* parameter specifies a timeout in seconds for blocking
operations like the connection attempt (if not specified, the global default
timeout setting will be used). This actually only works for HTTP, HTTPS and
FTP connections.
If *context* is specified, it must be a :class:`ssl.SSLContext` instance
describing the various SSL options. See :class:`~httplib.HTTPSConnection` for
more details.
The optional *cafile* and *capath* parameters specify a set of trusted CA
certificates for HTTPS requests. *cafile* should point to a single file
containing a bundle of CA certificates, whereas *capath* should point to a
directory of hashed certificate files. More information can be found in
:meth:`ssl.SSLContext.load_verify_locations`.
The *cadefault* parameter is ignored.
This function returns a file-like object with three additional methods:
* :meth:`geturl` --- return the URL of the resource retrieved, commonly used to
determine if a redirect was followed
* :meth:`info` --- return the meta-information of the page, such as headers,
in the form of an :class:`mimetools.Message` instance
(see `Quick Reference to HTTP Headers <https://www.cs.tut.fi/~jkorpela/http.html>`_)
* :meth:`getcode` --- return the HTTP status code of the response.
Raises :exc:`URLError` on errors.
Note that ``None`` may be returned if no handler handles the request (though the
default installed global :class:`OpenerDirector` uses :class:`UnknownHandler` to
ensure this never happens).
In addition, if proxy settings are detected (for example, when a ``*_proxy``
environment variable like :envvar:`http_proxy` is set),
:class:`ProxyHandler` is default installed and makes sure the requests are
handled through the proxy.
.. versionchanged:: 2.6
*timeout* was added.
.. versionchanged:: 2.7.9
*cafile*, *capath*, *cadefault*, and *context* were added.
.. function:: install_opener(opener)
Install an :class:`OpenerDirector` instance as the default global opener.
Installing an opener is only necessary if you want urlopen to use that opener;
otherwise, simply call :meth:`OpenerDirector.open` instead of :func:`urlopen`.
The code does not check for a real :class:`OpenerDirector`, and any class with
the appropriate interface will work.
.. function:: build_opener([handler, ...])
Return an :class:`OpenerDirector` instance, which chains the handlers in the
order given. *handler*\s can be either instances of :class:`BaseHandler`, or
subclasses of :class:`BaseHandler` (in which case it must be possible to call
the constructor without any parameters). Instances of the following classes
will be in front of the *handler*\s, unless the *handler*\s contain them,
instances of them or subclasses of them: :class:`ProxyHandler` (if proxy
settings are detected),
:class:`UnknownHandler`, :class:`HTTPHandler`, :class:`HTTPDefaultErrorHandler`,
:class:`HTTPRedirectHandler`, :class:`FTPHandler`, :class:`FileHandler`,
:class:`HTTPErrorProcessor`.
If the Python installation has SSL support (i.e., if the :mod:`ssl` module can be imported),
:class:`HTTPSHandler` will also be added.
Beginning in Python 2.3, a :class:`BaseHandler` subclass may also change its
:attr:`handler_order` attribute to modify its position in the handlers
list.
The following exceptions are raised as appropriate:
.. exception:: URLError
The handlers raise this exception (or derived exceptions) when they run into a
problem. It is a subclass of :exc:`IOError`.
.. attribute:: reason
The reason for this error. It can be a message string or another exception
instance (:exc:`socket.error` for remote URLs, :exc:`OSError` for local
URLs).
.. exception:: HTTPError
Though being an exception (a subclass of :exc:`URLError`), an :exc:`HTTPError`
can also function as a non-exceptional file-like return value (the same thing
that :func:`urlopen` returns). This is useful when handling exotic HTTP
errors, such as requests for authentication.
.. attribute:: code
An HTTP status code as defined in `RFC 2616 <http://www.faqs.org/rfcs/rfc2616.html>`_.
This numeric value corresponds to a value found in the dictionary of
codes as found in :attr:`BaseHTTPServer.BaseHTTPRequestHandler.responses`.
.. attribute:: reason
The reason for this error. It can be a message string or another exception
instance.
The following classes are provided:
.. class:: Request(url[, data][, headers][, origin_req_host][, unverifiable])
This class is an abstraction of a URL request.
*url* should be a string containing a valid URL.
*data* may be a string specifying additional data to send to the server, or
``None`` if no such data is needed. Currently HTTP requests are the only ones
that use *data*; the HTTP request will be a POST instead of a GET when the
*data* parameter is provided. *data* should be a buffer in the standard
:mimetype:`application/x-www-form-urlencoded` format. The
:func:`urllib.urlencode` function takes a mapping or sequence of 2-tuples and
returns a string in this format.
*headers* should be a dictionary, and will be treated as if :meth:`add_header`
was called with each key and value as arguments. This is often used to "spoof"
the ``User-Agent`` header value, which is used by a browser to identify itself --
some HTTP servers only allow requests coming from common browsers as opposed
to scripts. For example, Mozilla Firefox may identify itself as ``"Mozilla/5.0
(X11; U; Linux i686) Gecko/20071127 Firefox/2.0.0.11"``, while :mod:`urllib2`'s
default user agent string is ``"Python-urllib/2.6"`` (on Python 2.6).
The final two arguments are only of interest for correct handling of third-party
HTTP cookies:
*origin_req_host* should be the request-host of the origin transaction, as
defined by :rfc:`2965`. It defaults to ``cookielib.request_host(self)``. This
is the host name or IP address of the original request that was initiated by the
user. For example, if the request is for an image in an HTML document, this
should be the request-host of the request for the page containing the image.
*unverifiable* should indicate whether the request is unverifiable, as defined
by RFC 2965. It defaults to ``False``. An unverifiable request is one whose URL
the user did not have the option to approve. For example, if the request is for
an image in an HTML document, and the user had no option to approve the
automatic fetching of the image, this should be true.
.. class:: OpenerDirector()
The :class:`OpenerDirector` class opens URLs via :class:`BaseHandler`\ s chained
together. It manages the chaining of handlers, and recovery from errors.
.. class:: BaseHandler()
This is the base class for all registered handlers --- and handles only the
simple mechanics of registration.
.. class:: HTTPDefaultErrorHandler()
A class which defines a default handler for HTTP error responses; all responses
are turned into :exc:`HTTPError` exceptions.
.. class:: HTTPRedirectHandler()
A class to handle redirections.
.. class:: HTTPCookieProcessor([cookiejar])
A class to handle HTTP Cookies.
.. class:: ProxyHandler([proxies])
Cause requests to go through a proxy. If *proxies* is given, it must be a
dictionary mapping protocol names to URLs of proxies. The default is to read
the list of proxies from the environment variables
:envvar:`<protocol>_proxy`. If no proxy environment variables are set, then
in a Windows environment proxy settings are obtained from the registry's
Internet Settings section, and in a Mac OS X environment proxy information
is retrieved from the OS X System Configuration Framework.
To disable autodetected proxy pass an empty dictionary.
.. note::
``HTTP_PROXY`` will be ignored if a variable ``REQUEST_METHOD`` is set;
see the documentation on :func:`~urllib.getproxies`.
.. class:: HTTPPasswordMgr()
Keep a database of ``(realm, uri) -> (user, password)`` mappings.
.. class:: HTTPPasswordMgrWithDefaultRealm()
Keep a database of ``(realm, uri) -> (user, password)`` mappings. A realm of
``None`` is considered a catch-all realm, which is searched if no other realm
fits.
.. class:: AbstractBasicAuthHandler([password_mgr])
This is a mixin class that helps with HTTP authentication, both to the remote
host and to a proxy. *password_mgr*, if given, should be something that is
compatible with :class:`HTTPPasswordMgr`; refer to section
:ref:`http-password-mgr` for information on the interface that must be
supported.
.. class:: HTTPBasicAuthHandler([password_mgr])
Handle authentication with the remote host. *password_mgr*, if given, should be
something that is compatible with :class:`HTTPPasswordMgr`; refer to section
:ref:`http-password-mgr` for information on the interface that must be
supported.
.. class:: ProxyBasicAuthHandler([password_mgr])
Handle authentication with the proxy. *password_mgr*, if given, should be
something that is compatible with :class:`HTTPPasswordMgr`; refer to section
:ref:`http-password-mgr` for information on the interface that must be
supported.
.. class:: AbstractDigestAuthHandler([password_mgr])
This is a mixin class that helps with HTTP authentication, both to the remote
host and to a proxy. *password_mgr*, if given, should be something that is
compatible with :class:`HTTPPasswordMgr`; refer to section
:ref:`http-password-mgr` for information on the interface that must be
supported.
.. class:: HTTPDigestAuthHandler([password_mgr])
Handle authentication with the remote host. *password_mgr*, if given, should be
something that is compatible with :class:`HTTPPasswordMgr`; refer to section
:ref:`http-password-mgr` for information on the interface that must be
supported.
.. class:: ProxyDigestAuthHandler([password_mgr])
Handle authentication with the proxy. *password_mgr*, if given, should be
something that is compatible with :class:`HTTPPasswordMgr`; refer to section
:ref:`http-password-mgr` for information on the interface that must be
supported.
.. class:: HTTPHandler()
A class to handle opening of HTTP URLs.
.. class:: HTTPSHandler([debuglevel[, context]])
A class to handle opening of HTTPS URLs. *context* has the same meaning as
for :class:`httplib.HTTPSConnection`.
.. versionchanged:: 2.7.9
*context* added.
.. class:: FileHandler()
Open local files.
.. class:: FTPHandler()
Open FTP URLs.
.. class:: CacheFTPHandler()
Open FTP URLs, keeping a cache of open FTP connections to minimize delays.
.. class:: UnknownHandler()
A catch-all class to handle unknown URLs.
.. class:: HTTPErrorProcessor()
Process HTTP error responses.
.. _request-objects:
Request Objects
---------------
The following methods describe all of :class:`Request`'s public interface, and
so all must be overridden in subclasses.
.. method:: Request.add_data(data)
Set the :class:`Request` data to *data*. This is ignored by all handlers except
HTTP handlers --- and there it should be a byte string, and will change the
request to be ``POST`` rather than ``GET``.
.. method:: Request.get_method()
Return a string indicating the HTTP request method. This is only meaningful for
HTTP requests, and currently always returns ``'GET'`` or ``'POST'``.
.. method:: Request.has_data()
Return whether the instance has a non-\ ``None`` data.
.. method:: Request.get_data()
Return the instance's data.
.. method:: Request.add_header(key, val)
Add another header to the request. Headers are currently ignored by all
handlers except HTTP handlers, where they are added to the list of headers sent
to the server. Note that there cannot be more than one header with the same
name, and later calls will overwrite previous calls in case the *key* collides.
Currently, this is no loss of HTTP functionality, since all headers which have
meaning when used more than once have a (header-specific) way of gaining the
same functionality using only one header.
.. method:: Request.add_unredirected_header(key, header)
Add a header that will not be added to a redirected request.
.. versionadded:: 2.4
.. method:: Request.has_header(header)
Return whether the instance has the named header (checks both regular and
unredirected).
.. versionadded:: 2.4
.. method:: Request.get_full_url()
Return the URL given in the constructor.
.. method:: Request.get_type()
Return the type of the URL --- also known as the scheme.
.. method:: Request.get_host()
Return the host to which a connection will be made.
.. method:: Request.get_selector()
Return the selector --- the part of the URL that is sent to the server.
.. method:: Request.get_header(header_name, default=None)
Return the value of the given header. If the header is not present, return
the default value.
.. method:: Request.header_items()
Return a list of tuples (header_name, header_value) of the Request headers.
.. method:: Request.set_proxy(host, type)
Prepare the request by connecting to a proxy server. The *host* and *type* will
replace those of the instance, and the instance's selector will be the original
URL given in the constructor.
.. method:: Request.get_origin_req_host()
Return the request-host of the origin transaction, as defined by :rfc:`2965`.
See the documentation for the :class:`Request` constructor.
.. method:: Request.is_unverifiable()
Return whether the request is unverifiable, as defined by RFC 2965. See the
documentation for the :class:`Request` constructor.
.. _opener-director-objects:
OpenerDirector Objects
----------------------
:class:`OpenerDirector` instances have the following methods:
.. method:: OpenerDirector.add_handler(handler)
*handler* should be an instance of :class:`BaseHandler`. The following
methods are searched, and added to the possible chains (note that HTTP errors
are a special case).
* :samp:`{protocol}_open` --- signal that the handler knows how to open
*protocol* URLs.
* :samp:`http_error_{type}` --- signal that the handler knows how to handle
HTTP errors with HTTP error code *type*.
* :samp:`{protocol}_error` --- signal that the handler knows how to handle
errors from (non-\ ``http``) *protocol*.
* :samp:`{protocol}_request` --- signal that the handler knows how to
pre-process *protocol* requests.
* :samp:`{protocol}_response` --- signal that the handler knows how to
post-process *protocol* responses.
.. method:: OpenerDirector.open(url[, data][, timeout])
Open the given *url* (which can be a request object or a string), optionally
passing the given *data*. Arguments, return values and exceptions raised are
the same as those of :func:`urlopen` (which simply calls the :meth:`open`
method on the currently installed global :class:`OpenerDirector`). The
optional *timeout* parameter specifies a timeout in seconds for blocking
operations like the connection attempt (if not specified, the global default
timeout setting will be used). The timeout feature actually works only for
HTTP, HTTPS and FTP connections).
.. versionchanged:: 2.6
*timeout* was added.
.. method:: OpenerDirector.error(proto[, arg[, ...]])
Handle an error of the given protocol. This will call the registered error
handlers for the given protocol with the given arguments (which are protocol
specific). The HTTP protocol is a special case which uses the HTTP response
code to determine the specific error handler; refer to the :meth:`http_error_\*`
methods of the handler classes.
Return values and exceptions raised are the same as those of :func:`urlopen`.
OpenerDirector objects open URLs in three stages:
The order in which these methods are called within each stage is determined by
sorting the handler instances.
#. Every handler with a method named like :samp:`{protocol}_request` has that
method called to pre-process the request.
#. Handlers with a method named like :samp:`{protocol}_open` are called to handle
the request. This stage ends when a handler either returns a non-\ :const:`None`
value (ie. a response), or raises an exception (usually :exc:`URLError`).
Exceptions are allowed to propagate.
In fact, the above algorithm is first tried for methods named
:meth:`default_open`. If all such methods return :const:`None`, the
algorithm is repeated for methods named like :samp:`{protocol}_open`. If all
such methods return :const:`None`, the algorithm is repeated for methods
named :meth:`unknown_open`.
Note that the implementation of these methods may involve calls of the parent
:class:`OpenerDirector` instance's :meth:`~OpenerDirector.open` and
:meth:`~OpenerDirector.error` methods.
#. Every handler with a method named like :samp:`{protocol}_response` has that
method called to post-process the response.
.. _base-handler-objects:
BaseHandler Objects
-------------------
:class:`BaseHandler` objects provide a couple of methods that are directly
useful, and others that are meant to be used by derived classes. These are
intended for direct use:
.. method:: BaseHandler.add_parent(director)
Add a director as parent.
.. method:: BaseHandler.close()
Remove any parents.
The following attributes and methods should only be used by classes derived from
:class:`BaseHandler`.
.. note::
The convention has been adopted that subclasses defining
:meth:`protocol_request` or :meth:`protocol_response` methods are named
:class:`\*Processor`; all others are named :class:`\*Handler`.
.. attribute:: BaseHandler.parent
A valid :class:`OpenerDirector`, which can be used to open using a different
protocol, or handle errors.
.. method:: BaseHandler.default_open(req)
This method is *not* defined in :class:`BaseHandler`, but subclasses should
define it if they want to catch all URLs.
This method, if implemented, will be called by the parent
:class:`OpenerDirector`. It should return a file-like object as described in
the return value of the :meth:`open` of :class:`OpenerDirector`, or ``None``.
It should raise :exc:`URLError`, unless a truly exceptional thing happens (for
example, :exc:`MemoryError` should not be mapped to :exc:`URLError`).
This method will be called before any protocol-specific open method.
.. method:: BaseHandler.protocol_open(req)
:noindex:
("protocol" is to be replaced by the protocol name.)
This method is *not* defined in :class:`BaseHandler`, but subclasses should
define it if they want to handle URLs with the given *protocol*.
This method, if defined, will be called by the parent :class:`OpenerDirector`.
Return values should be the same as for :meth:`default_open`.
.. method:: BaseHandler.unknown_open(req)
This method is *not* defined in :class:`BaseHandler`, but subclasses should
define it if they want to catch all URLs with no specific registered handler to
open it.
This method, if implemented, will be called by the :attr:`parent`
:class:`OpenerDirector`. Return values should be the same as for
:meth:`default_open`.
.. method:: BaseHandler.http_error_default(req, fp, code, msg, hdrs)
This method is *not* defined in :class:`BaseHandler`, but subclasses should
override it if they intend to provide a catch-all for otherwise unhandled HTTP
errors. It will be called automatically by the :class:`OpenerDirector` getting
the error, and should not normally be called in other circumstances.
*req* will be a :class:`Request` object, *fp* will be a file-like object with
the HTTP error body, *code* will be the three-digit code of the error, *msg*
will be the user-visible explanation of the code and *hdrs* will be a mapping
object with the headers of the error.
Return values and exceptions raised should be the same as those of
:func:`urlopen`.
.. method:: BaseHandler.http_error_nnn(req, fp, code, msg, hdrs)
*nnn* should be a three-digit HTTP error code. This method is also not defined
in :class:`BaseHandler`, but will be called, if it exists, on an instance of a
subclass, when an HTTP error with code *nnn* occurs.
Subclasses should override this method to handle specific HTTP errors.
Arguments, return values and exceptions raised should be the same as for
:meth:`http_error_default`.
.. method:: BaseHandler.protocol_request(req)
:noindex:
("protocol" is to be replaced by the protocol name.)
This method is *not* defined in :class:`BaseHandler`, but subclasses should
define it if they want to pre-process requests of the given *protocol*.
This method, if defined, will be called by the parent :class:`OpenerDirector`.
*req* will be a :class:`Request` object. The return value should be a
:class:`Request` object.
.. method:: BaseHandler.protocol_response(req, response)
:noindex:
("protocol" is to be replaced by the protocol name.)
This method is *not* defined in :class:`BaseHandler`, but subclasses should
define it if they want to post-process responses of the given *protocol*.
This method, if defined, will be called by the parent :class:`OpenerDirector`.
*req* will be a :class:`Request` object. *response* will be an object
implementing the same interface as the return value of :func:`urlopen`. The
return value should implement the same interface as the return value of
:func:`urlopen`.
.. _http-redirect-handler:
HTTPRedirectHandler Objects
---------------------------
.. note::
Some HTTP redirections require action from this module's client code. If this
is the case, :exc:`HTTPError` is raised. See :rfc:`2616` for details of the
precise meanings of the various redirection codes.
.. method:: HTTPRedirectHandler.redirect_request(req, fp, code, msg, hdrs, newurl)
Return a :class:`Request` or ``None`` in response to a redirect. This is called
by the default implementations of the :meth:`http_error_30\*` methods when a
redirection is received from the server. If a redirection should take place,
return a new :class:`Request` to allow :meth:`http_error_30\*` to perform the
redirect to *newurl*. Otherwise, raise :exc:`HTTPError` if no other handler
should try to handle this URL, or return ``None`` if you can't but another
handler might.
.. note::
The default implementation of this method does not strictly follow :rfc:`2616`,
which says that 301 and 302 responses to ``POST`` requests must not be
automatically redirected without confirmation by the user. In reality, browsers
do allow automatic redirection of these responses, changing the POST to a
``GET``, and the default implementation reproduces this behavior.
.. method:: HTTPRedirectHandler.http_error_301(req, fp, code, msg, hdrs)
Redirect to the ``Location:`` or ``URI:`` URL. This method is called by the
parent :class:`OpenerDirector` when getting an HTTP 'moved permanently' response.
.. method:: HTTPRedirectHandler.http_error_302(req, fp, code, msg, hdrs)
The same as :meth:`http_error_301`, but called for the 'found' response.
.. method:: HTTPRedirectHandler.http_error_303(req, fp, code, msg, hdrs)
The same as :meth:`http_error_301`, but called for the 'see other' response.
.. method:: HTTPRedirectHandler.http_error_307(req, fp, code, msg, hdrs)
The same as :meth:`http_error_301`, but called for the 'temporary redirect'
response.
.. _http-cookie-processor:
HTTPCookieProcessor Objects
---------------------------
.. versionadded:: 2.4
:class:`HTTPCookieProcessor` instances have one attribute:
.. attribute:: HTTPCookieProcessor.cookiejar
The :class:`cookielib.CookieJar` in which cookies are stored.
.. _proxy-handler:
ProxyHandler Objects
--------------------
.. method:: ProxyHandler.protocol_open(request)
:noindex:
("protocol" is to be replaced by the protocol name.)
The :class:`ProxyHandler` will have a method :samp:`{protocol}_open` for every
*protocol* which has a proxy in the *proxies* dictionary given in the
constructor. The method will modify requests to go through the proxy, by
calling ``request.set_proxy()``, and call the next handler in the chain to
actually execute the protocol.
.. _http-password-mgr:
HTTPPasswordMgr Objects
-----------------------
These methods are available on :class:`HTTPPasswordMgr` and
:class:`HTTPPasswordMgrWithDefaultRealm` objects.
.. method:: HTTPPasswordMgr.add_password(realm, uri, user, passwd)
*uri* can be either a single URI, or a sequence of URIs. *realm*, *user* and
*passwd* must be strings. This causes ``(user, passwd)`` to be used as
authentication tokens when authentication for *realm* and a super-URI of any of
the given URIs is given.
.. method:: HTTPPasswordMgr.find_user_password(realm, authuri)
Get user/password for given realm and URI, if any. This method will return
``(None, None)`` if there is no matching user/password.
For :class:`HTTPPasswordMgrWithDefaultRealm` objects, the realm ``None`` will be
searched if the given *realm* has no matching user/password.
.. _abstract-basic-auth-handler:
AbstractBasicAuthHandler Objects
--------------------------------
.. method:: AbstractBasicAuthHandler.http_error_auth_reqed(authreq, host, req, headers)
Handle an authentication request by getting a user/password pair, and re-trying
the request. *authreq* should be the name of the header where the information
about the realm is included in the request, *host* specifies the URL and path to
authenticate for, *req* should be the (failed) :class:`Request` object, and
*headers* should be the error headers.
*host* is either an authority (e.g. ``"python.org"``) or a URL containing an
authority component (e.g. ``"http://python.org/"``). In either case, the
authority must not contain a userinfo component (so, ``"python.org"`` and
``"python.org:80"`` are fine, ``"joe:password@python.org"`` is not).
.. _http-basic-auth-handler:
HTTPBasicAuthHandler Objects
----------------------------
.. method:: HTTPBasicAuthHandler.http_error_401(req, fp, code, msg, hdrs)
Retry the request with authentication information, if available.
.. _proxy-basic-auth-handler:
ProxyBasicAuthHandler Objects
-----------------------------
.. method:: ProxyBasicAuthHandler.http_error_407(req, fp, code, msg, hdrs)
Retry the request with authentication information, if available.
.. _abstract-digest-auth-handler:
AbstractDigestAuthHandler Objects
---------------------------------
.. method:: AbstractDigestAuthHandler.http_error_auth_reqed(authreq, host, req, headers)
*authreq* should be the name of the header where the information about the realm
is included in the request, *host* should be the host to authenticate to, *req*
should be the (failed) :class:`Request` object, and *headers* should be the
error headers.
.. _http-digest-auth-handler:
HTTPDigestAuthHandler Objects
-----------------------------
.. method:: HTTPDigestAuthHandler.http_error_401(req, fp, code, msg, hdrs)
Retry the request with authentication information, if available.
.. _proxy-digest-auth-handler:
ProxyDigestAuthHandler Objects
------------------------------
.. method:: ProxyDigestAuthHandler.http_error_407(req, fp, code, msg, hdrs)
Retry the request with authentication information, if available.
.. _http-handler-objects:
HTTPHandler Objects
-------------------
.. method:: HTTPHandler.http_open(req)
Send an HTTP request, which can be either GET or POST, depending on
``req.has_data()``.
.. _https-handler-objects:
HTTPSHandler Objects
--------------------
.. method:: HTTPSHandler.https_open(req)
Send an HTTPS request, which can be either GET or POST, depending on
``req.has_data()``.
.. _file-handler-objects:
FileHandler Objects
-------------------
.. method:: FileHandler.file_open(req)
Open the file locally, if there is no host name, or the host name is
``'localhost'``. Change the protocol to ``ftp`` otherwise, and retry opening it
using :attr:`parent`.
.. _ftp-handler-objects:
FTPHandler Objects
------------------
.. method:: FTPHandler.ftp_open(req)
Open the FTP file indicated by *req*. The login is always done with empty
username and password.
.. _cacheftp-handler-objects:
CacheFTPHandler Objects
-----------------------
:class:`CacheFTPHandler` objects are :class:`FTPHandler` objects with the
following additional methods:
.. method:: CacheFTPHandler.setTimeout(t)
Set timeout of connections to *t* seconds.
.. method:: CacheFTPHandler.setMaxConns(m)
Set maximum number of cached connections to *m*.
.. _unknown-handler-objects:
UnknownHandler Objects
----------------------
.. method:: UnknownHandler.unknown_open()
Raise a :exc:`URLError` exception.
.. _http-error-processor-objects:
HTTPErrorProcessor Objects
--------------------------
.. versionadded:: 2.4
.. method:: HTTPErrorProcessor.http_response()
Process HTTP error responses.
For 200 error codes, the response object is returned immediately.
For non-200 error codes, this simply passes the job on to the
:samp:`{protocol}_error_code` handler methods, via
:meth:`OpenerDirector.error`. Eventually,
:class:`urllib2.HTTPDefaultErrorHandler` will raise an :exc:`HTTPError` if no
other handler handles the error.
.. method:: HTTPErrorProcessor.https_response()
Process HTTPS error responses.
The behavior is same as :meth:`http_response`.
.. _urllib2-examples:
Examples
--------
In addition to the examples below, more examples are given in
:ref:`urllib-howto`.
This example gets the python.org main page and displays the first 100 bytes of
it::
>>> import urllib2
>>> f = urllib2.urlopen('http://www.python.org/')
>>> print f.read(100)
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<?xml-stylesheet href="./css/ht2html
Here we are sending a data-stream to the stdin of a CGI and reading the data it
returns to us. Note that this example will only work when the Python
installation supports SSL. ::
>>> import urllib2
>>> req = urllib2.Request(url='https://localhost/cgi-bin/test.cgi',
... data='This data is passed to stdin of the CGI')
>>> f = urllib2.urlopen(req)
>>> print f.read()
Got Data: "This data is passed to stdin of the CGI"
The code for the sample CGI used in the above example is::
#!/usr/bin/env python
import sys
data = sys.stdin.read()
print 'Content-type: text-plain\n\nGot Data: "%s"' % data
Use of Basic HTTP Authentication::
import urllib2
# Create an OpenerDirector with support for Basic HTTP Authentication...
auth_handler = urllib2.HTTPBasicAuthHandler()
auth_handler.add_password(realm='PDQ Application',
uri='https://mahler:8092/site-updates.py',
user='klem',
passwd='kadidd!ehopper')
opener = urllib2.build_opener(auth_handler)
# ...and install it globally so it can be used with urlopen.
urllib2.install_opener(opener)
urllib2.urlopen('http://www.example.com/login.html')
:func:`build_opener` provides many handlers by default, including a
:class:`ProxyHandler`. By default, :class:`ProxyHandler` uses the environment
variables named ``<scheme>_proxy``, where ``<scheme>`` is the URL scheme
involved. For example, the :envvar:`http_proxy` environment variable is read to
obtain the HTTP proxy's URL.
This example replaces the default :class:`ProxyHandler` with one that uses
programmatically-supplied proxy URLs, and adds proxy authorization support with
:class:`ProxyBasicAuthHandler`. ::
proxy_handler = urllib2.ProxyHandler({'http': 'http://www.example.com:3128/'})
proxy_auth_handler = urllib2.ProxyBasicAuthHandler()
proxy_auth_handler.add_password('realm', 'host', 'username', 'password')
opener = urllib2.build_opener(proxy_handler, proxy_auth_handler)
# This time, rather than install the OpenerDirector, we use it directly:
opener.open('http://www.example.com/login.html')
Adding HTTP headers:
Use the *headers* argument to the :class:`Request` constructor, or::
import urllib2
req = urllib2.Request('http://www.example.com/')
req.add_header('Referer', 'http://www.python.org/')
# Customize the default User-Agent header value:
req.add_header('User-Agent', 'urllib-example/0.1 (Contact: . . .)')
r = urllib2.urlopen(req)
:class:`OpenerDirector` automatically adds a :mailheader:`User-Agent` header to
every :class:`Request`. To change this::
import urllib2
opener = urllib2.build_opener()
opener.addheaders = [('User-agent', 'Mozilla/5.0')]
opener.open('http://www.example.com/')
Also, remember that a few standard headers (:mailheader:`Content-Length`,
:mailheader:`Content-Type` and :mailheader:`Host`) are added when the
:class:`Request` is passed to :func:`urlopen` (or :meth:`OpenerDirector.open`).
PK
%�\�Vt��> �> & html/_sources/library/urlparse.rst.txtnu �[��� :mod:`urlparse` --- Parse URLs into components
==============================================
.. module:: urlparse
:synopsis: Parse URLs into or assemble them from components.
.. index::
single: WWW
single: World Wide Web
single: URL
pair: URL; parsing
pair: relative; URL
.. note::
The :mod:`urlparse` module is renamed to :mod:`urllib.parse` in Python 3.
The :term:`2to3` tool will automatically adapt imports when converting
your sources to Python 3.
**Source code:** :source:`Lib/urlparse.py`
--------------
This module defines a standard interface to break Uniform Resource Locator (URL)
strings up in components (addressing scheme, network location, path etc.), to
combine the components back into a URL string, and to convert a "relative URL"
to an absolute URL given a "base URL."
The module has been designed to match the Internet RFC on Relative Uniform
Resource Locators. It supports the following URL schemes: ``file``, ``ftp``,
``gopher``, ``hdl``, ``http``, ``https``, ``imap``, ``mailto``, ``mms``,
``news``, ``nntp``, ``prospero``, ``rsync``, ``rtsp``, ``rtspu``, ``sftp``,
``shttp``, ``sip``, ``sips``, ``snews``, ``svn``, ``svn+ssh``, ``telnet``,
``wais``.
.. versionadded:: 2.5
Support for the ``sftp`` and ``sips`` schemes.
The :mod:`urlparse` module defines the following functions:
.. function:: urlparse(urlstring[, scheme[, allow_fragments]])
Parse a URL into six components, returning a 6-tuple. This corresponds to the
general structure of a URL: ``scheme://netloc/path;parameters?query#fragment``.
Each tuple item is a string, possibly empty. The components are not broken up in
smaller parts (for example, the network location is a single string), and %
escapes are not expanded. The delimiters as shown above are not part of the
result, except for a leading slash in the *path* component, which is retained if
present. For example:
>>> from urlparse import urlparse
>>> o = urlparse('http://www.cwi.nl:80/%7Eguido/Python.html')
>>> o # doctest: +NORMALIZE_WHITESPACE
ParseResult(scheme='http', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
params='', query='', fragment='')
>>> o.scheme
'http'
>>> o.port
80
>>> o.geturl()
'http://www.cwi.nl:80/%7Eguido/Python.html'
Following the syntax specifications in :rfc:`1808`, urlparse recognizes
a netloc only if it is properly introduced by '//'. Otherwise the
input is presumed to be a relative URL and thus to start with
a path component.
>>> from urlparse import urlparse
>>> urlparse('//www.cwi.nl:80/%7Eguido/Python.html')
ParseResult(scheme='', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
params='', query='', fragment='')
>>> urlparse('www.cwi.nl/%7Eguido/Python.html')
ParseResult(scheme='', netloc='', path='www.cwi.nl/%7Eguido/Python.html',
params='', query='', fragment='')
>>> urlparse('help/Python.html')
ParseResult(scheme='', netloc='', path='help/Python.html', params='',
query='', fragment='')
If the *scheme* argument is specified, it gives the default addressing
scheme, to be used only if the URL does not specify one. The default value for
this argument is the empty string.
If the *allow_fragments* argument is false, fragment identifiers are not
recognized and parsed as part of the preceding component, even if the URL's
addressing scheme normally does support them. The default value for this
argument is :const:`True`.
The return value is actually an instance of a subclass of :class:`tuple`. This
class has the following additional read-only convenience attributes:
+------------------+-------+--------------------------+----------------------+
| Attribute | Index | Value | Value if not present |
+==================+=======+==========================+======================+
| :attr:`scheme` | 0 | URL scheme specifier | *scheme* parameter |
+------------------+-------+--------------------------+----------------------+
| :attr:`netloc` | 1 | Network location part | empty string |
+------------------+-------+--------------------------+----------------------+
| :attr:`path` | 2 | Hierarchical path | empty string |
+------------------+-------+--------------------------+----------------------+
| :attr:`params` | 3 | Parameters for last path | empty string |
| | | element | |
+------------------+-------+--------------------------+----------------------+
| :attr:`query` | 4 | Query component | empty string |
+------------------+-------+--------------------------+----------------------+
| :attr:`fragment` | 5 | Fragment identifier | empty string |
+------------------+-------+--------------------------+----------------------+
| :attr:`username` | | User name | :const:`None` |
+------------------+-------+--------------------------+----------------------+
| :attr:`password` | | Password | :const:`None` |
+------------------+-------+--------------------------+----------------------+
| :attr:`hostname` | | Host name (lower case) | :const:`None` |
+------------------+-------+--------------------------+----------------------+
| :attr:`port` | | Port number as integer, | :const:`None` |
| | | if present | |
+------------------+-------+--------------------------+----------------------+
See section :ref:`urlparse-result-object` for more information on the result
object.
.. versionchanged:: 2.5
Added attributes to return value.
.. versionchanged:: 2.7
Added IPv6 URL parsing capabilities.
.. function:: parse_qs(qs[, keep_blank_values[, strict_parsing[, max_num_fields]]])
Parse a query string given as a string argument (data of type
:mimetype:`application/x-www-form-urlencoded`). Data are returned as a
dictionary. The dictionary keys are the unique query variable names and the
values are lists of values for each name.
The optional argument *keep_blank_values* is a flag indicating whether blank
values in percent-encoded queries should be treated as blank strings. A true value
indicates that blanks should be retained as blank strings. The default false
value indicates that blank values are to be ignored and treated as if they were
not included.
The optional argument *strict_parsing* is a flag indicating what to do with
parsing errors. If false (the default), errors are silently ignored. If true,
errors raise a :exc:`ValueError` exception.
The optional argument *max_num_fields* is the maximum number of fields to
read. If set, then throws a :exc:`ValueError` if there are more than
*max_num_fields* fields read.
Use the :func:`urllib.urlencode` function to convert such dictionaries into
query strings.
.. versionadded:: 2.6
Copied from the :mod:`cgi` module.
.. versionchanged:: 2.7.16
Added *max_num_fields* parameter.
.. function:: parse_qsl(qs[, keep_blank_values[, strict_parsing[, max_num_fields]]])
Parse a query string given as a string argument (data of type
:mimetype:`application/x-www-form-urlencoded`). Data are returned as a list of
name, value pairs.
The optional argument *keep_blank_values* is a flag indicating whether blank
values in percent-encoded queries should be treated as blank strings. A true value
indicates that blanks should be retained as blank strings. The default false
value indicates that blank values are to be ignored and treated as if they were
not included.
The optional argument *strict_parsing* is a flag indicating what to do with
parsing errors. If false (the default), errors are silently ignored. If true,
errors raise a :exc:`ValueError` exception.
The optional argument *max_num_fields* is the maximum number of fields to
read. If set, then throws a :exc:`ValueError` if there are more than
*max_num_fields* fields read.
Use the :func:`urllib.urlencode` function to convert such lists of pairs into
query strings.
.. versionadded:: 2.6
Copied from the :mod:`cgi` module.
.. versionchanged:: 2.7.16
Added *max_num_fields* parameter.
.. function:: urlunparse(parts)
Construct a URL from a tuple as returned by ``urlparse()``. The *parts* argument
can be any six-item iterable. This may result in a slightly different, but
equivalent URL, if the URL that was parsed originally had unnecessary delimiters
(for example, a ? with an empty query; the RFC states that these are
equivalent).
.. function:: urlsplit(urlstring[, scheme[, allow_fragments]])
This is similar to :func:`urlparse`, but does not split the params from the URL.
This should generally be used instead of :func:`urlparse` if the more recent URL
syntax allowing parameters to be applied to each segment of the *path* portion
of the URL (see :rfc:`2396`) is wanted. A separate function is needed to
separate the path segments and parameters. This function returns a 5-tuple:
(addressing scheme, network location, path, query, fragment identifier).
The return value is actually an instance of a subclass of :class:`tuple`. This
class has the following additional read-only convenience attributes:
+------------------+-------+-------------------------+----------------------+
| Attribute | Index | Value | Value if not present |
+==================+=======+=========================+======================+
| :attr:`scheme` | 0 | URL scheme specifier | *scheme* parameter |
+------------------+-------+-------------------------+----------------------+
| :attr:`netloc` | 1 | Network location part | empty string |
+------------------+-------+-------------------------+----------------------+
| :attr:`path` | 2 | Hierarchical path | empty string |
+------------------+-------+-------------------------+----------------------+
| :attr:`query` | 3 | Query component | empty string |
+------------------+-------+-------------------------+----------------------+
| :attr:`fragment` | 4 | Fragment identifier | empty string |
+------------------+-------+-------------------------+----------------------+
| :attr:`username` | | User name | :const:`None` |
+------------------+-------+-------------------------+----------------------+
| :attr:`password` | | Password | :const:`None` |
+------------------+-------+-------------------------+----------------------+
| :attr:`hostname` | | Host name (lower case) | :const:`None` |
+------------------+-------+-------------------------+----------------------+
| :attr:`port` | | Port number as integer, | :const:`None` |
| | | if present | |
+------------------+-------+-------------------------+----------------------+
See section :ref:`urlparse-result-object` for more information on the result
object.
.. versionadded:: 2.2
.. versionchanged:: 2.5
Added attributes to return value.
.. function:: urlunsplit(parts)
Combine the elements of a tuple as returned by :func:`urlsplit` into a complete
URL as a string. The *parts* argument can be any five-item iterable. This may
result in a slightly different, but equivalent URL, if the URL that was parsed
originally had unnecessary delimiters (for example, a ? with an empty query; the
RFC states that these are equivalent).
.. versionadded:: 2.2
.. function:: urljoin(base, url[, allow_fragments])
Construct a full ("absolute") URL by combining a "base URL" (*base*) with
another URL (*url*). Informally, this uses components of the base URL, in
particular the addressing scheme, the network location and (part of) the path,
to provide missing components in the relative URL. For example:
>>> from urlparse import urljoin
>>> urljoin('http://www.cwi.nl/%7Eguido/Python.html', 'FAQ.html')
'http://www.cwi.nl/%7Eguido/FAQ.html'
The *allow_fragments* argument has the same meaning and default as for
:func:`urlparse`.
.. note::
If *url* is an absolute URL (that is, starting with ``//`` or ``scheme://``),
the *url*'s host name and/or scheme will be present in the result. For example:
.. doctest::
>>> urljoin('http://www.cwi.nl/%7Eguido/Python.html',
... '//www.python.org/%7Eguido')
'http://www.python.org/%7Eguido'
If you do not want that behavior, preprocess the *url* with :func:`urlsplit` and
:func:`urlunsplit`, removing possible *scheme* and *netloc* parts.
.. function:: urldefrag(url)
If *url* contains a fragment identifier, returns a modified version of *url*
with no fragment identifier, and the fragment identifier as a separate string.
If there is no fragment identifier in *url*, returns *url* unmodified and an
empty string.
.. seealso::
:rfc:`3986` - Uniform Resource Identifiers
This is the current standard (STD66). Any changes to urlparse module
should conform to this. Certain deviations could be observed, which are
mostly for backward compatibility purposes and for certain de-facto
parsing requirements as commonly observed in major browsers.
:rfc:`2732` - Format for Literal IPv6 Addresses in URL's.
This specifies the parsing requirements of IPv6 URLs.
:rfc:`2396` - Uniform Resource Identifiers (URI): Generic Syntax
Document describing the generic syntactic requirements for both Uniform Resource
Names (URNs) and Uniform Resource Locators (URLs).
:rfc:`2368` - The mailto URL scheme.
Parsing requirements for mailto URL schemes.
:rfc:`1808` - Relative Uniform Resource Locators
This Request For Comments includes the rules for joining an absolute and a
relative URL, including a fair number of "Abnormal Examples" which govern the
treatment of border cases.
:rfc:`1738` - Uniform Resource Locators (URL)
This specifies the formal syntax and semantics of absolute URLs.
.. _urlparse-result-object:
Results of :func:`urlparse` and :func:`urlsplit`
------------------------------------------------
The result objects from the :func:`urlparse` and :func:`urlsplit` functions are
subclasses of the :class:`tuple` type. These subclasses add the attributes
described in those functions, as well as provide an additional method:
.. method:: ParseResult.geturl()
Return the re-combined version of the original URL as a string. This may differ
from the original URL in that the scheme will always be normalized to lower case
and empty components may be dropped. Specifically, empty parameters, queries,
and fragment identifiers will be removed.
The result of this method is a fixpoint if passed back through the original
parsing function:
>>> import urlparse
>>> url = 'HTTP://www.Python.org/doc/#'
>>> r1 = urlparse.urlsplit(url)
>>> r1.geturl()
'http://www.Python.org/doc/'
>>> r2 = urlparse.urlsplit(r1.geturl())
>>> r2.geturl()
'http://www.Python.org/doc/'
.. versionadded:: 2.5
The following classes provide the implementations of the parse results:
.. class:: ParseResult(scheme, netloc, path, params, query, fragment)
Concrete class for :func:`urlparse` results.
.. class:: SplitResult(scheme, netloc, path, query, fragment)
Concrete class for :func:`urlsplit` results.
PK
%�\v'�
�
" html/_sources/library/user.rst.txtnu �[���
:mod:`user` --- User-specific configuration hook
================================================
.. module:: user
:synopsis: A standard way to reference user-specific modules.
:deprecated:
.. deprecated:: 2.6
The :mod:`user` module has been removed in Python 3.
.. index::
pair: .pythonrc.py; file
triple: user; configuration; file
As a policy, Python doesn't run user-specified code on startup of Python
programs. (Only interactive sessions execute the script specified in the
:envvar:`PYTHONSTARTUP` environment variable if it exists).
However, some programs or sites may find it convenient to allow users to have a
standard customization file, which gets run when a program requests it. This
module implements such a mechanism. A program that wishes to use the mechanism
must execute the statement ::
import user
.. index:: builtin: execfile
The :mod:`user` module looks for a file :file:`.pythonrc.py` in the user's home
directory and if it can be opened, executes it (using :func:`execfile`) in its
own (the module :mod:`user`'s) global namespace. Errors during this phase are
not caught; that's up to the program that imports the :mod:`user` module, if it
wishes. The home directory is assumed to be named by the :envvar:`HOME`
environment variable; if this is not set, the current directory is used.
The user's :file:`.pythonrc.py` could conceivably test for ``sys.version`` if it
wishes to do different things depending on the Python version.
A warning to users: be very conservative in what you place in your
:file:`.pythonrc.py` file. Since you don't know which programs will use it,
changing the behavior of standard modules or functions is generally not a good
idea.
A suggestion for programmers who wish to use this mechanism: a simple way to let
users specify options for your package is to have them define variables in their
:file:`.pythonrc.py` file that you test in your module. For example, a module
:mod:`spam` that has a verbosity level can look for a variable
``user.spam_verbose``, as follows::
import user
verbose = bool(getattr(user, "spam_verbose", 0))
(The three-argument form of :func:`getattr` is used in case the user has not
defined ``spam_verbose`` in their :file:`.pythonrc.py` file.)
Programs with extensive customization needs are better off reading a
program-specific customization file.
Programs with security or privacy concerns should *not* import this module; a
user can easily break into a program by placing arbitrary code in the
:file:`.pythonrc.py` file.
Modules for general use should *not* import this module; it may interfere with
the operation of the importing program.
.. seealso::
Module :mod:`site`
Site-wide customization mechanism.
PK
%�\�z �J$ J$ & html/_sources/library/userdict.rst.txtnu �[��� :mod:`UserDict` --- Class wrapper for dictionary objects
========================================================
.. module:: UserDict
:synopsis: Class wrapper for dictionary objects.
**Source code:** :source:`Lib/UserDict.py`
--------------
The module defines a mixin, :class:`DictMixin`, defining all dictionary methods
for classes that already have a minimum mapping interface. This greatly
simplifies writing classes that need to be substitutable for dictionaries (such
as the shelve module).
This module also defines a class, :class:`~UserDict.UserDict`, that acts as a wrapper
around dictionary objects. The need for this class has been largely supplanted
by the ability to subclass directly from :class:`dict` (a feature that became
available starting with Python version 2.2). Prior to the introduction of
:class:`dict`, the :class:`~UserDict.UserDict` class was used to create dictionary-like
sub-classes that obtained new behaviors by overriding existing methods or adding
new ones.
The :mod:`UserDict` module defines the :class:`~UserDict.UserDict` class and
:class:`DictMixin`:
.. class:: UserDict([initialdata])
Class that simulates a dictionary. The instance's contents are kept in a
regular dictionary, which is accessible via the :attr:`data` attribute of
:class:`~UserDict.UserDict` instances. If *initialdata* is provided, :attr:`data` is
initialized with its contents; note that a reference to *initialdata* will not
be kept, allowing it be used for other purposes.
.. note::
For backward compatibility, instances of :class:`~UserDict.UserDict` are not iterable.
.. class:: IterableUserDict([initialdata])
Subclass of :class:`~UserDict.UserDict` that supports direct iteration (e.g. ``for key in
myDict``).
In addition to supporting the methods and operations of mappings (see section
:ref:`typesmapping`), :class:`~UserDict.UserDict` and :class:`IterableUserDict` instances
provide the following attribute:
.. attribute:: IterableUserDict.data
A real dictionary used to store the contents of the :class:`~UserDict.UserDict` class.
.. class:: DictMixin()
Mixin defining all dictionary methods for classes that already have a minimum
dictionary interface including :meth:`__getitem__`, :meth:`__setitem__`,
:meth:`__delitem__`, and :meth:`keys`.
This mixin should be used as a superclass. Adding each of the above methods
adds progressively more functionality. For instance, defining all but
:meth:`__delitem__` will preclude only :meth:`pop` and :meth:`popitem` from the
full interface.
In addition to the four base methods, progressively more efficiency comes with
defining :meth:`__contains__`, :meth:`__iter__`, and :meth:`iteritems`.
Since the mixin has no knowledge of the subclass constructor, it does not define
:meth:`__init__` or :meth:`copy`.
Starting with Python version 2.6, it is recommended to use
:class:`collections.MutableMapping` instead of :class:`DictMixin`.
Note that DictMixin does not implement the :meth:`~dict.viewkeys`,
:meth:`~dict.viewvalues`, or :meth:`~dict.viewitems` methods.
:mod:`UserList` --- Class wrapper for list objects
==================================================
.. module:: UserList
:synopsis: Class wrapper for list objects.
.. note::
When Python 2.2 was released, many of the use cases for this class were
subsumed by the ability to subclass :class:`list` directly. However, a
handful of use cases remain.
This module provides a list-interface around an underlying data store. By
default, that data store is a :class:`list`; however, it can be used to wrap
a list-like interface around other objects (such as persistent storage).
In addition, this class can be mixed-in with built-in classes using multiple
inheritance. This can sometimes be useful. For example, you can inherit
from :class:`~UserList.UserList` and :class:`str` at the same time. That would not be
possible with both a real :class:`list` and a real :class:`str`.
This module defines a class that acts as a wrapper around list objects. It is a
useful base class for your own list-like classes, which can inherit from them
and override existing methods or add new ones. In this way one can add new
behaviors to lists.
The :mod:`UserList` module defines the :class:`~UserList.UserList` class:
.. class:: UserList([list])
Class that simulates a list. The instance's contents are kept in a regular
list, which is accessible via the :attr:`data` attribute of :class:`~UserList.UserList`
instances. The instance's contents are initially set to a copy of *list*,
defaulting to the empty list ``[]``. *list* can be any iterable, e.g. a
real Python list or a :class:`~UserList.UserList` object.
.. note::
The :class:`~UserList.UserList` class has been moved to the :mod:`collections`
module in Python 3. The :term:`2to3` tool will automatically adapt
imports when converting your sources to Python 3.
In addition to supporting the methods and operations of mutable sequences (see
section :ref:`typesseq`), :class:`~UserList.UserList` instances provide the following
attribute:
.. attribute:: UserList.data
A real Python list object used to store the contents of the :class:`~UserList.UserList`
class.
**Subclassing requirements:** Subclasses of :class:`~UserList.UserList` are expected to
offer a constructor which can be called with either no arguments or one
argument. List operations which return a new sequence attempt to create an
instance of the actual implementation class. To do so, it assumes that the
constructor can be called with a single parameter, which is a sequence object
used as a data source.
If a derived class does not wish to comply with this requirement, all of the
special methods supported by this class will need to be overridden; please
consult the sources for information about the methods which need to be provided
in that case.
.. versionchanged:: 2.0
Python versions 1.5.2 and 1.6 also required that the constructor be callable
with no parameters, and offer a mutable :attr:`data` attribute. Earlier
versions of Python did not attempt to create instances of the derived class.
:mod:`UserString` --- Class wrapper for string objects
======================================================
.. module:: UserString
:synopsis: Class wrapper for string objects.
.. moduleauthor:: Peter Funk <pf@artcom-gmbh.de>
.. sectionauthor:: Peter Funk <pf@artcom-gmbh.de>
.. note::
This :class:`~UserString.UserString` class from this module is available for backward
compatibility only. If you are writing code that does not need to work with
versions of Python earlier than Python 2.2, please consider subclassing directly
from the built-in :class:`str` type instead of using :class:`~UserString.UserString` (there
is no built-in equivalent to :class:`MutableString`).
This module defines a class that acts as a wrapper around string objects. It is
a useful base class for your own string-like classes, which can inherit from
them and override existing methods or add new ones. In this way one can add new
behaviors to strings.
It should be noted that these classes are highly inefficient compared to real
string or Unicode objects; this is especially the case for
:class:`MutableString`.
The :mod:`UserString` module defines the following classes:
.. class:: UserString([sequence])
Class that simulates a string or a Unicode string object. The instance's
content is kept in a regular string or Unicode string object, which is
accessible via the :attr:`data` attribute of :class:`~UserString.UserString` instances. The
instance's contents are initially set to a copy of *sequence*. *sequence* can
be either a regular Python string or Unicode string, an instance of
:class:`~UserString.UserString` (or a subclass) or an arbitrary sequence which can be
converted into a string using the built-in :func:`str` function.
.. note::
The :class:`~UserString.UserString` class has been moved to the :mod:`collections`
module in Python 3. The :term:`2to3` tool will automatically adapt
imports when converting your sources to Python 3.
.. class:: MutableString([sequence])
This class is derived from the :class:`~UserString.UserString` above and redefines strings
to be *mutable*. Mutable strings can't be used as dictionary keys, because
dictionaries require *immutable* objects as keys. The main intention of this
class is to serve as an educational example for inheritance and necessity to
remove (override) the :meth:`__hash__` method in order to trap attempts to use a
mutable object as dictionary key, which would be otherwise very error prone and
hard to track down.
.. deprecated:: 2.6
The :class:`MutableString` class has been removed in Python 3.
In addition to supporting the methods and operations of string and Unicode
objects (see section :ref:`string-methods`), :class:`~UserString.UserString` instances
provide the following attribute:
.. attribute:: MutableString.data
A real Python string or Unicode object used to store the content of the
:class:`~UserString.UserString` class.
PK
%�\F�{�A A html/_sources/library/uu.rst.txtnu �[��� :mod:`uu` --- Encode and decode uuencode files
==============================================
.. module:: uu
:synopsis: Encode and decode files in uuencode format.
.. moduleauthor:: Lance Ellinghouse
**Source code:** :source:`Lib/uu.py`
--------------
This module encodes and decodes files in uuencode format, allowing arbitrary
binary data to be transferred over ASCII-only connections. Wherever a file
argument is expected, the methods accept a file-like object. For backwards
compatibility, a string containing a pathname is also accepted, and the
corresponding file will be opened for reading and writing; the pathname ``'-'``
is understood to mean the standard input or output. However, this interface is
deprecated; it's better for the caller to open the file itself, and be sure
that, when required, the mode is ``'rb'`` or ``'wb'`` on Windows.
.. index::
single: Jansen, Jack
single: Ellinghouse, Lance
This code was contributed by Lance Ellinghouse, and modified by Jack Jansen.
The :mod:`uu` module defines the following functions:
.. function:: encode(in_file, out_file[, name[, mode]])
Uuencode file *in_file* into file *out_file*. The uuencoded file will have the
header specifying *name* and *mode* as the defaults for the results of decoding
the file. The default defaults are taken from *in_file*, or ``'-'`` and ``0666``
respectively.
.. function:: decode(in_file[, out_file[, mode[, quiet]]])
This call decodes uuencoded file *in_file* placing the result on file
*out_file*. If *out_file* is a pathname, *mode* is used to set the permission
bits if the file must be created. Defaults for *out_file* and *mode* are taken
from the uuencode header. However, if the file specified in the header already
exists, a :exc:`uu.Error` is raised.
:func:`decode` may print a warning to standard error if the input was produced
by an incorrect uuencoder and Python could recover from that error. Setting
*quiet* to a true value silences this warning.
.. exception:: Error()
Subclass of :exc:`Exception`, this can be raised by :func:`uu.decode` under
various situations, such as described above, but also including a badly
formatted header, or truncated input file.
.. seealso::
Module :mod:`binascii`
Support module containing ASCII-to-binary and binary-to-ASCII conversions.
PK
%�\ux� � " html/_sources/library/uuid.rst.txtnu �[���
:mod:`uuid` --- UUID objects according to RFC 4122
==================================================
.. module:: uuid
:synopsis: UUID objects (universally unique identifiers) according to RFC 4122
.. moduleauthor:: Ka-Ping Yee <ping@zesty.ca>
.. sectionauthor:: George Yoshida <quiver@users.sourceforge.net>
.. versionadded:: 2.5
This module provides immutable :class:`UUID` objects (the :class:`UUID` class)
and the functions :func:`uuid1`, :func:`uuid3`, :func:`uuid4`, :func:`uuid5` for
generating version 1, 3, 4, and 5 UUIDs as specified in :rfc:`4122`.
If all you want is a unique ID, you should probably call :func:`uuid1` or
:func:`uuid4`. Note that :func:`uuid1` may compromise privacy since it creates
a UUID containing the computer's network address. :func:`uuid4` creates a
random UUID.
.. class:: UUID([hex[, bytes[, bytes_le[, fields[, int[, version]]]]]])
Create a UUID from either a string of 32 hexadecimal digits, a string of 16
bytes in big-endian order as the *bytes* argument, a string of 16 bytes in
little-endian order as the *bytes_le* argument, a tuple of six integers
(32-bit *time_low*, 16-bit *time_mid*, 16-bit *time_hi_version*,
8-bit *clock_seq_hi_variant*, 8-bit *clock_seq_low*, 48-bit *node*) as the
*fields* argument, or a single 128-bit integer as the *int* argument.
When a string of hex digits is given, curly braces, hyphens,
and a URN prefix are all optional. For example, these
expressions all yield the same UUID::
UUID('{12345678-1234-5678-1234-567812345678}')
UUID('12345678123456781234567812345678')
UUID('urn:uuid:12345678-1234-5678-1234-567812345678')
UUID(bytes='\x12\x34\x56\x78'*4)
UUID(bytes_le='\x78\x56\x34\x12\x34\x12\x78\x56' +
'\x12\x34\x56\x78\x12\x34\x56\x78')
UUID(fields=(0x12345678, 0x1234, 0x5678, 0x12, 0x34, 0x567812345678))
UUID(int=0x12345678123456781234567812345678)
Exactly one of *hex*, *bytes*, *bytes_le*, *fields*, or *int* must be given.
The *version* argument is optional; if given, the resulting UUID will have its
variant and version number set according to RFC 4122, overriding bits in the
given *hex*, *bytes*, *bytes_le*, *fields*, or *int*.
:class:`UUID` instances have these read-only attributes:
.. attribute:: UUID.bytes
The UUID as a 16-byte string (containing the six integer fields in big-endian
byte order).
.. attribute:: UUID.bytes_le
The UUID as a 16-byte string (with *time_low*, *time_mid*, and *time_hi_version*
in little-endian byte order).
.. attribute:: UUID.fields
A tuple of the six integer fields of the UUID, which are also available as six
individual attributes and two derived attributes:
+------------------------------+-------------------------------+
| Field | Meaning |
+==============================+===============================+
| :attr:`time_low` | the first 32 bits of the UUID |
+------------------------------+-------------------------------+
| :attr:`time_mid` | the next 16 bits of the UUID |
+------------------------------+-------------------------------+
| :attr:`time_hi_version` | the next 16 bits of the UUID |
+------------------------------+-------------------------------+
| :attr:`clock_seq_hi_variant` | the next 8 bits of the UUID |
+------------------------------+-------------------------------+
| :attr:`clock_seq_low` | the next 8 bits of the UUID |
+------------------------------+-------------------------------+
| :attr:`node` | the last 48 bits of the UUID |
+------------------------------+-------------------------------+
| :attr:`time` | the 60-bit timestamp |
+------------------------------+-------------------------------+
| :attr:`clock_seq` | the 14-bit sequence number |
+------------------------------+-------------------------------+
.. attribute:: UUID.hex
The UUID as a 32-character hexadecimal string.
.. attribute:: UUID.int
The UUID as a 128-bit integer.
.. attribute:: UUID.urn
The UUID as a URN as specified in RFC 4122.
.. attribute:: UUID.variant
The UUID variant, which determines the internal layout of the UUID. This will be
one of the constants :const:`RESERVED_NCS`, :const:`RFC_4122`,
:const:`RESERVED_MICROSOFT`, or :const:`RESERVED_FUTURE`.
.. attribute:: UUID.version
The UUID version number (1 through 5, meaningful only when the variant is
:const:`RFC_4122`).
The :mod:`uuid` module defines the following functions:
.. function:: getnode()
Get the hardware address as a 48-bit positive integer. The first time this
runs, it may launch a separate program, which could be quite slow. If all
attempts to obtain the hardware address fail, we choose a random 48-bit number
with its eighth bit set to 1 as recommended in RFC 4122. "Hardware address"
means the MAC address of a network interface, and on a machine with multiple
network interfaces the MAC address of any one of them may be returned.
.. index:: single: getnode
.. function:: uuid1([node[, clock_seq]])
Generate a UUID from a host ID, sequence number, and the current time. If *node*
is not given, :func:`getnode` is used to obtain the hardware address. If
*clock_seq* is given, it is used as the sequence number; otherwise a random
14-bit sequence number is chosen.
.. index:: single: uuid1
.. function:: uuid3(namespace, name)
Generate a UUID based on the MD5 hash of a namespace identifier (which is a
UUID) and a name (which is a string).
.. index:: single: uuid3
.. function:: uuid4()
Generate a random UUID.
.. index:: single: uuid4
.. function:: uuid5(namespace, name)
Generate a UUID based on the SHA-1 hash of a namespace identifier (which is a
UUID) and a name (which is a string).
.. index:: single: uuid5
The :mod:`uuid` module defines the following namespace identifiers for use with
:func:`uuid3` or :func:`uuid5`.
.. data:: NAMESPACE_DNS
When this namespace is specified, the *name* string is a fully-qualified domain
name.
.. data:: NAMESPACE_URL
When this namespace is specified, the *name* string is a URL.
.. data:: NAMESPACE_OID
When this namespace is specified, the *name* string is an ISO OID.
.. data:: NAMESPACE_X500
When this namespace is specified, the *name* string is an X.500 DN in DER or a
text output format.
The :mod:`uuid` module defines the following constants for the possible values
of the :attr:`variant` attribute:
.. data:: RESERVED_NCS
Reserved for NCS compatibility.
.. data:: RFC_4122
Specifies the UUID layout given in :rfc:`4122`.
.. data:: RESERVED_MICROSOFT
Reserved for Microsoft compatibility.
.. data:: RESERVED_FUTURE
Reserved for future definition.
.. seealso::
:rfc:`4122` - A Universally Unique IDentifier (UUID) URN Namespace
This specification defines a Uniform Resource Name namespace for UUIDs, the
internal format of UUIDs, and methods of generating UUIDs.
.. _uuid-example:
Example
-------
Here are some examples of typical usage of the :mod:`uuid` module::
>>> import uuid
>>> # make a UUID based on the host ID and current time
>>> uuid.uuid1()
UUID('a8098c1a-f86e-11da-bd1a-00112444be1e')
>>> # make a UUID using an MD5 hash of a namespace UUID and a name
>>> uuid.uuid3(uuid.NAMESPACE_DNS, 'python.org')
UUID('6fa459ea-ee8a-3ca4-894e-db77e160355e')
>>> # make a random UUID
>>> uuid.uuid4()
UUID('16fd2706-8baf-433b-82eb-8c7fada847da')
>>> # make a UUID using a SHA-1 hash of a namespace UUID and a name
>>> uuid.uuid5(uuid.NAMESPACE_DNS, 'python.org')
UUID('886313e1-3b8a-5372-9b90-0c9aee199e5d')
>>> # make a UUID from a string of hex digits (braces and hyphens ignored)
>>> x = uuid.UUID('{00010203-0405-0607-0809-0a0b0c0d0e0f}')
>>> # convert a UUID to a string of hex digits in standard form
>>> str(x)
'00010203-0405-0607-0809-0a0b0c0d0e0f'
>>> # get the raw 16 bytes of the UUID
>>> x.bytes
'\x00\x01\x02\x03\x04\x05\x06\x07\x08\t\n\x0b\x0c\r\x0e\x0f'
>>> # make a UUID from a 16-byte string
>>> uuid.UUID(bytes=x.bytes)
UUID('00010203-0405-0607-0809-0a0b0c0d0e0f')
PK
%�\���6gM gM & html/_sources/library/warnings.rst.txtnu �[��� :mod:`warnings` --- Warning control
===================================
.. index:: single: warnings
.. module:: warnings
:synopsis: Issue warning messages and control their disposition.
.. versionadded:: 2.1
**Source code:** :source:`Lib/warnings.py`
--------------
Warning messages are typically issued in situations where it is useful to alert
the user of some condition in a program, where that condition (normally) doesn't
warrant raising an exception and terminating the program. For example, one
might want to issue a warning when a program uses an obsolete module.
Python programmers issue warnings by calling the :func:`warn` function defined
in this module. (C programmers use :c:func:`PyErr_WarnEx`; see
:ref:`exceptionhandling` for details).
Warning messages are normally written to ``sys.stderr``, but their disposition
can be changed flexibly, from ignoring all warnings to turning them into
exceptions. The disposition of warnings can vary based on the warning category
(see below), the text of the warning message, and the source location where it
is issued. Repetitions of a particular warning for the same source location are
typically suppressed.
There are two stages in warning control: first, each time a warning is issued, a
determination is made whether a message should be issued or not; next, if a
message is to be issued, it is formatted and printed using a user-settable hook.
The determination whether to issue a warning message is controlled by the
warning filter, which is a sequence of matching rules and actions. Rules can be
added to the filter by calling :func:`filterwarnings` and reset to its default
state by calling :func:`resetwarnings`.
The printing of warning messages is done by calling :func:`showwarning`, which
may be overridden; the default implementation of this function formats the
message by calling :func:`formatwarning`, which is also available for use by
custom implementations.
.. seealso::
:func:`logging.captureWarnings` allows you to handle all warnings with
the standard logging infrastructure.
.. _warning-categories:
Warning Categories
------------------
There are a number of built-in exceptions that represent warning categories.
This categorization is useful to be able to filter out groups of warnings. The
following warnings category classes are currently defined:
.. tabularcolumns:: |l|p{0.6\linewidth}|
+----------------------------------+-----------------------------------------------+
| Class | Description |
+==================================+===============================================+
| :exc:`Warning` | This is the base class of all warning |
| | category classes. It is a subclass of |
| | :exc:`Exception`. |
+----------------------------------+-----------------------------------------------+
| :exc:`UserWarning` | The default category for :func:`warn`. |
+----------------------------------+-----------------------------------------------+
| :exc:`DeprecationWarning` | Base category for warnings about deprecated |
| | features (ignored by default). |
+----------------------------------+-----------------------------------------------+
| :exc:`SyntaxWarning` | Base category for warnings about dubious |
| | syntactic features. |
+----------------------------------+-----------------------------------------------+
| :exc:`RuntimeWarning` | Base category for warnings about dubious |
| | runtime features. |
+----------------------------------+-----------------------------------------------+
| :exc:`FutureWarning` | Base category for warnings about constructs |
| | that will change semantically in the future. |
+----------------------------------+-----------------------------------------------+
| :exc:`PendingDeprecationWarning` | Base category for warnings about features |
| | that will be deprecated in the future |
| | (ignored by default). |
+----------------------------------+-----------------------------------------------+
| :exc:`ImportWarning` | Base category for warnings triggered during |
| | the process of importing a module (ignored by |
| | default). |
+----------------------------------+-----------------------------------------------+
| :exc:`UnicodeWarning` | Base category for warnings related to |
| | Unicode. |
+----------------------------------+-----------------------------------------------+
While these are technically built-in exceptions, they are documented here,
because conceptually they belong to the warnings mechanism.
User code can define additional warning categories by subclassing one of the
standard warning categories. A warning category must always be a subclass of
the :exc:`Warning` class.
.. versionchanged:: 2.7
:exc:`DeprecationWarning` is ignored by default.
.. _warning-filter:
The Warnings Filter
-------------------
The warnings filter controls whether warnings are ignored, displayed, or turned
into errors (raising an exception).
Conceptually, the warnings filter maintains an ordered list of filter
specifications; any specific warning is matched against each filter
specification in the list in turn until a match is found; the match determines
the disposition of the match. Each entry is a tuple of the form (*action*,
*message*, *category*, *module*, *lineno*), where:
* *action* is one of the following strings:
+---------------+----------------------------------------------+
| Value | Disposition |
+===============+==============================================+
| ``"error"`` | turn matching warnings into exceptions |
+---------------+----------------------------------------------+
| ``"ignore"`` | never print matching warnings |
+---------------+----------------------------------------------+
| ``"always"`` | always print matching warnings |
+---------------+----------------------------------------------+
| ``"default"`` | print the first occurrence of matching |
| | warnings for each location where the warning |
| | is issued |
+---------------+----------------------------------------------+
| ``"module"`` | print the first occurrence of matching |
| | warnings for each module where the warning |
| | is issued |
+---------------+----------------------------------------------+
| ``"once"`` | print only the first occurrence of matching |
| | warnings, regardless of location |
+---------------+----------------------------------------------+
* *message* is a string containing a regular expression that the start of
the warning message must match. The expression is compiled to always be
case-insensitive.
* *category* is a class (a subclass of :exc:`Warning`) of which the warning
category must be a subclass in order to match.
* *module* is a string containing a regular expression that the module name must
match. The expression is compiled to be case-sensitive.
* *lineno* is an integer that the line number where the warning occurred must
match, or ``0`` to match all line numbers.
Since the :exc:`Warning` class is derived from the built-in :exc:`Exception`
class, to turn a warning into an error we simply raise ``category(message)``.
The warnings filter is initialized by :option:`-W` options passed to the Python
interpreter command line. The interpreter saves the arguments for all
:option:`-W` options without interpretation in ``sys.warnoptions``; the
:mod:`warnings` module parses these when it is first imported (invalid options
are ignored, after printing a message to ``sys.stderr``).
Default Warning Filters
~~~~~~~~~~~~~~~~~~~~~~~
By default, Python installs several warning filters, which can be overridden by
the command-line options passed to :option:`-W` and calls to
:func:`filterwarnings`.
* :exc:`DeprecationWarning` and :exc:`PendingDeprecationWarning`, and
:exc:`ImportWarning` are ignored.
* :exc:`BytesWarning` is ignored unless the :option:`-b` option is given once or
twice; in this case this warning is either printed (``-b``) or turned into an
exception (``-bb``).
.. _warning-suppress:
Temporarily Suppressing Warnings
--------------------------------
If you are using code that you know will raise a warning, such as a deprecated
function, but do not want to see the warning, then it is possible to suppress
the warning using the :class:`catch_warnings` context manager::
import warnings
def fxn():
warnings.warn("deprecated", DeprecationWarning)
with warnings.catch_warnings():
warnings.simplefilter("ignore")
fxn()
While within the context manager all warnings will simply be ignored. This
allows you to use known-deprecated code without having to see the warning while
not suppressing the warning for other code that might not be aware of its use
of deprecated code. Note: this can only be guaranteed in a single-threaded
application. If two or more threads use the :class:`catch_warnings` context
manager at the same time, the behavior is undefined.
.. _warning-testing:
Testing Warnings
----------------
To test warnings raised by code, use the :class:`catch_warnings` context
manager. With it you can temporarily mutate the warnings filter to facilitate
your testing. For instance, do the following to capture all raised warnings to
check::
import warnings
def fxn():
warnings.warn("deprecated", DeprecationWarning)
with warnings.catch_warnings(record=True) as w:
# Cause all warnings to always be triggered.
warnings.simplefilter("always")
# Trigger a warning.
fxn()
# Verify some things
assert len(w) == 1
assert issubclass(w[-1].category, DeprecationWarning)
assert "deprecated" in str(w[-1].message)
One can also cause all warnings to be exceptions by using ``error`` instead of
``always``. One thing to be aware of is that if a warning has already been
raised because of a ``once``/``default`` rule, then no matter what filters are
set the warning will not be seen again unless the warnings registry related to
the warning has been cleared.
Once the context manager exits, the warnings filter is restored to its state
when the context was entered. This prevents tests from changing the warnings
filter in unexpected ways between tests and leading to indeterminate test
results. The :func:`showwarning` function in the module is also restored to
its original value. Note: this can only be guaranteed in a single-threaded
application. If two or more threads use the :class:`catch_warnings` context
manager at the same time, the behavior is undefined.
When testing multiple operations that raise the same kind of warning, it
is important to test them in a manner that confirms each operation is raising
a new warning (e.g. set warnings to be raised as exceptions and check the
operations raise exceptions, check that the length of the warning list
continues to increase after each operation, or else delete the previous
entries from the warnings list before each new operation).
Updating Code For New Versions of Python
----------------------------------------
Warnings that are only of interest to the developer are ignored by default. As
such you should make sure to test your code with typically ignored warnings
made visible. You can do this from the command-line by passing :option:`-Wd <-W>`
to the interpreter (this is shorthand for :option:`!-W default`). This enables
default handling for all warnings, including those that are ignored by default.
To change what action is taken for encountered warnings you simply change what
argument is passed to :option:`-W`, e.g. :option:`!-W error`. See the
:option:`-W` flag for more details on what is possible.
To programmatically do the same as :option:`!-Wd`, use::
warnings.simplefilter('default')
Make sure to execute this code as soon as possible. This prevents the
registering of what warnings have been raised from unexpectedly influencing how
future warnings are treated.
Having certain warnings ignored by default is done to prevent a user from
seeing warnings that are only of interest to the developer. As you do not
necessarily have control over what interpreter a user uses to run their code,
it is possible that a new version of Python will be released between your
release cycles. The new interpreter release could trigger new warnings in your
code that were not there in an older interpreter, e.g.
:exc:`DeprecationWarning` for a module that you are using. While you as a
developer want to be notified that your code is using a deprecated module, to a
user this information is essentially noise and provides no benefit to them.
.. _warning-functions:
Available Functions
-------------------
.. function:: warn(message[, category[, stacklevel]])
Issue a warning, or maybe ignore it or raise an exception. The *category*
argument, if given, must be a warning category class (see above); it defaults to
:exc:`UserWarning`. Alternatively *message* can be a :exc:`Warning` instance,
in which case *category* will be ignored and ``message.__class__`` will be used.
In this case the message text will be ``str(message)``. This function raises an
exception if the particular warning issued is changed into an error by the
warnings filter see above. The *stacklevel* argument can be used by wrapper
functions written in Python, like this::
def deprecation(message):
warnings.warn(message, DeprecationWarning, stacklevel=2)
This makes the warning refer to :func:`deprecation`'s caller, rather than to the
source of :func:`deprecation` itself (since the latter would defeat the purpose
of the warning message).
.. function:: warn_explicit(message, category, filename, lineno[, module[, registry[, module_globals]]])
This is a low-level interface to the functionality of :func:`warn`, passing in
explicitly the message, category, filename and line number, and optionally the
module name and the registry (which should be the ``__warningregistry__``
dictionary of the module). The module name defaults to the filename with
``.py`` stripped; if no registry is passed, the warning is never suppressed.
*message* must be a string and *category* a subclass of :exc:`Warning` or
*message* may be a :exc:`Warning` instance, in which case *category* will be
ignored.
*module_globals*, if supplied, should be the global namespace in use by the code
for which the warning is issued. (This argument is used to support displaying
source for modules found in zipfiles or other non-filesystem import
sources).
.. versionchanged:: 2.5
Added the *module_globals* parameter.
.. function:: warnpy3k(message[, category[, stacklevel]])
Issue a warning related to Python 3.x deprecation. Warnings are only shown
when Python is started with the -3 option. Like :func:`warn` *message* must
be a string and *category* a subclass of :exc:`Warning`. :func:`warnpy3k`
is using :exc:`DeprecationWarning` as default warning class.
.. versionadded:: 2.6
.. function:: showwarning(message, category, filename, lineno[, file[, line]])
Write a warning to a file. The default implementation calls
``formatwarning(message, category, filename, lineno, line)`` and writes the
resulting string to *file*, which defaults to ``sys.stderr``. You may replace
this function with an alternative implementation by assigning to
``warnings.showwarning``.
*line* is a line of source code to be included in the warning
message; if *line* is not supplied, :func:`showwarning` will
try to read the line specified by *filename* and *lineno*.
.. versionchanged:: 2.7
The *line* argument is required to be supported.
.. function:: formatwarning(message, category, filename, lineno[, line])
Format a warning the standard way. This returns a string which may contain
embedded newlines and ends in a newline. *line* is a line of source code to
be included in the warning message; if *line* is not supplied,
:func:`formatwarning` will try to read the line specified by *filename* and
*lineno*.
.. versionchanged:: 2.6
Added the *line* argument.
.. function:: filterwarnings(action[, message[, category[, module[, lineno[, append]]]]])
Insert an entry into the list of :ref:`warnings filter specifications
<warning-filter>`. The entry is inserted at the front by default; if
*append* is true, it is inserted at the end. This checks the types of the
arguments, compiles the *message* and *module* regular expressions, and
inserts them as a tuple in the list of warnings filters. Entries closer to
the front of the list override entries later in the list, if both match a
particular warning. Omitted arguments default to a value that matches
everything.
.. function:: simplefilter(action[, category[, lineno[, append]]])
Insert a simple entry into the list of :ref:`warnings filter specifications
<warning-filter>`. The meaning of the function parameters is as for
:func:`filterwarnings`, but regular expressions are not needed as the filter
inserted always matches any message in any module as long as the category and
line number match.
.. function:: resetwarnings()
Reset the warnings filter. This discards the effect of all previous calls to
:func:`filterwarnings`, including that of the :option:`-W` command line options
and calls to :func:`simplefilter`.
Available Context Managers
--------------------------
.. class:: catch_warnings([\*, record=False, module=None])
A context manager that copies and, upon exit, restores the warnings filter
and the :func:`showwarning` function.
If the *record* argument is :const:`False` (the default) the context manager
returns :class:`None` on entry. If *record* is :const:`True`, a list is
returned that is progressively populated with objects as seen by a custom
:func:`showwarning` function (which also suppresses output to ``sys.stdout``).
Each object in the list has attributes with the same names as the arguments to
:func:`showwarning`.
The *module* argument takes a module that will be used instead of the
module returned when you import :mod:`warnings` whose filter will be
protected. This argument exists primarily for testing the :mod:`warnings`
module itself.
.. note::
The :class:`catch_warnings` manager works by replacing and
then later restoring the module's
:func:`showwarning` function and internal list of filter
specifications. This means the context manager is modifying
global state and therefore is not thread-safe.
.. note::
In Python 3, the arguments to the constructor for
:class:`catch_warnings` are keyword-only arguments.
.. versionadded:: 2.6
PK
%�\G)D�� � " html/_sources/library/wave.rst.txtnu �[��� :mod:`wave` --- Read and write WAV files
========================================
.. module:: wave
:synopsis: Provide an interface to the WAV sound format.
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
.. Documentations stolen from comments in file.
**Source code:** :source:`Lib/wave.py`
--------------
The :mod:`wave` module provides a convenient interface to the WAV sound format.
It does not support compression/decompression, but it does support mono/stereo.
The :mod:`wave` module defines the following function and exception:
.. function:: open(file[, mode])
If *file* is a string, open the file by that name, otherwise treat it as a
seekable file-like object. *mode* can be any of
``'r'``, ``'rb'``
Read only mode.
``'w'``, ``'wb'``
Write only mode.
Note that it does not allow read/write WAV files.
A *mode* of ``'r'`` or ``'rb'`` returns a :class:`Wave_read` object, while a
*mode* of ``'w'`` or ``'wb'`` returns a :class:`Wave_write` object. If
*mode* is omitted and a file-like object is passed as *file*, ``file.mode``
is used as the default value for *mode* (the ``'b'`` flag is still added if
necessary).
If you pass in a file-like object, the wave object will not close it when its
:meth:`close` method is called; it is the caller's responsibility to close
the file object.
.. function:: openfp(file, mode)
A synonym for :func:`.open`, maintained for backwards compatibility.
.. exception:: Error
An error raised when something is impossible because it violates the WAV
specification or hits an implementation deficiency.
.. _wave-read-objects:
Wave_read Objects
-----------------
Wave_read objects, as returned by :func:`.open`, have the following methods:
.. method:: Wave_read.close()
Close the stream if it was opened by :mod:`wave`, and make the instance
unusable. This is called automatically on object collection.
.. method:: Wave_read.getnchannels()
Returns number of audio channels (``1`` for mono, ``2`` for stereo).
.. method:: Wave_read.getsampwidth()
Returns sample width in bytes.
.. method:: Wave_read.getframerate()
Returns sampling frequency.
.. method:: Wave_read.getnframes()
Returns number of audio frames.
.. method:: Wave_read.getcomptype()
Returns compression type (``'NONE'`` is the only supported type).
.. method:: Wave_read.getcompname()
Human-readable version of :meth:`getcomptype`. Usually ``'not compressed'``
parallels ``'NONE'``.
.. method:: Wave_read.getparams()
Returns a tuple ``(nchannels, sampwidth, framerate, nframes, comptype,
compname)``, equivalent to output of the :meth:`get\*` methods.
.. method:: Wave_read.readframes(n)
Reads and returns at most *n* frames of audio, as a string of bytes.
.. method:: Wave_read.rewind()
Rewind the file pointer to the beginning of the audio stream.
The following two methods are defined for compatibility with the :mod:`aifc`
module, and don't do anything interesting.
.. method:: Wave_read.getmarkers()
Returns ``None``.
.. method:: Wave_read.getmark(id)
Raise an error.
The following two methods define a term "position" which is compatible between
them, and is otherwise implementation dependent.
.. method:: Wave_read.setpos(pos)
Set the file pointer to the specified position.
.. method:: Wave_read.tell()
Return current file pointer position.
.. _wave-write-objects:
Wave_write Objects
------------------
Wave_write objects, as returned by :func:`.open`, have the following methods:
.. method:: Wave_write.close()
Make sure *nframes* is correct, and close the file if it was opened by
:mod:`wave`. This method is called upon object collection.
.. method:: Wave_write.setnchannels(n)
Set the number of channels.
.. method:: Wave_write.setsampwidth(n)
Set the sample width to *n* bytes.
.. method:: Wave_write.setframerate(n)
Set the frame rate to *n*.
.. method:: Wave_write.setnframes(n)
Set the number of frames to *n*. This will be changed later if more frames are
written.
.. method:: Wave_write.setcomptype(type, name)
Set the compression type and description. At the moment, only compression type
``NONE`` is supported, meaning no compression.
.. method:: Wave_write.setparams(tuple)
The *tuple* should be ``(nchannels, sampwidth, framerate, nframes, comptype,
compname)``, with values valid for the :meth:`set\*` methods. Sets all
parameters.
.. method:: Wave_write.tell()
Return current position in the file, with the same disclaimer for the
:meth:`Wave_read.tell` and :meth:`Wave_read.setpos` methods.
.. method:: Wave_write.writeframesraw(data)
Write audio frames, without correcting *nframes*.
.. method:: Wave_write.writeframes(data)
Write audio frames and make sure *nframes* is correct.
Note that it is invalid to set any parameters after calling :meth:`writeframes`
or :meth:`writeframesraw`, and any attempt to do so will raise
:exc:`wave.Error`.
PK
%�\�1�W~2 ~2 % html/_sources/library/weakref.rst.txtnu �[��� :mod:`weakref` --- Weak references
==================================
.. module:: weakref
:synopsis: Support for weak references and weak dictionaries.
.. moduleauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
.. moduleauthor:: Neil Schemenauer <nas@arctrix.com>
.. moduleauthor:: Martin von Löwis <martin@loewis.home.cs.tu-berlin.de>
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
.. versionadded:: 2.1
**Source code:** :source:`Lib/weakref.py`
--------------
The :mod:`weakref` module allows the Python programmer to create :dfn:`weak
references` to objects.
.. When making changes to the examples in this file, be sure to update
Lib/test/test_weakref.py::libreftest too!
In the following, the term :dfn:`referent` means the object which is referred to
by a weak reference.
A weak reference to an object is not enough to keep the object alive: when the
only remaining references to a referent are weak references,
:term:`garbage collection` is free to destroy the referent and reuse its memory
for something else. A primary use for weak references is to implement caches or
mappings holding large objects, where it's desired that a large object not be
kept alive solely because it appears in a cache or mapping.
For example, if you have a number of large binary image objects, you may wish to
associate a name with each. If you used a Python dictionary to map names to
images, or images to names, the image objects would remain alive just because
they appeared as values or keys in the dictionaries. The
:class:`WeakKeyDictionary` and :class:`WeakValueDictionary` classes supplied by
the :mod:`weakref` module are an alternative, using weak references to construct
mappings that don't keep objects alive solely because they appear in the mapping
objects. If, for example, an image object is a value in a
:class:`WeakValueDictionary`, then when the last remaining references to that
image object are the weak references held by weak mappings, garbage collection
can reclaim the object, and its corresponding entries in weak mappings are
simply deleted.
:class:`WeakKeyDictionary` and :class:`WeakValueDictionary` use weak references
in their implementation, setting up callback functions on the weak references
that notify the weak dictionaries when a key or value has been reclaimed by
garbage collection. Most programs should find that using one of these weak
dictionary types is all they need -- it's not usually necessary to create your
own weak references directly. The low-level machinery used by the weak
dictionary implementations is exposed by the :mod:`weakref` module for the
benefit of advanced uses.
Not all objects can be weakly referenced; those objects which can include class
instances, functions written in Python (but not in C), methods (both bound and
unbound), sets, frozensets, file objects, :term:`generator`\s, type objects,
:class:`DBcursor` objects from the :mod:`bsddb` module, sockets, arrays, deques,
regular expression pattern objects, and code objects.
.. versionchanged:: 2.4
Added support for files, sockets, arrays, and patterns.
.. versionchanged:: 2.7
Added support for thread.lock, threading.Lock, and code objects.
Several built-in types such as :class:`list` and :class:`dict` do not directly
support weak references but can add support through subclassing::
class Dict(dict):
pass
obj = Dict(red=1, green=2, blue=3) # this object is weak referenceable
.. impl-detail::
Other built-in types such as :class:`tuple` and :class:`long` do not support
weak references even when subclassed.
Extension types can easily be made to support weak references; see
:ref:`weakref-support`.
.. class:: ref(object[, callback])
Return a weak reference to *object*. The original object can be retrieved by
calling the reference object if the referent is still alive; if the referent is
no longer alive, calling the reference object will cause :const:`None` to be
returned. If *callback* is provided and not :const:`None`, and the returned
weakref object is still alive, the callback will be called when the object is
about to be finalized; the weak reference object will be passed as the only
parameter to the callback; the referent will no longer be available.
It is allowable for many weak references to be constructed for the same object.
Callbacks registered for each weak reference will be called from the most
recently registered callback to the oldest registered callback.
Exceptions raised by the callback will be noted on the standard error output,
but cannot be propagated; they are handled in exactly the same way as exceptions
raised from an object's :meth:`__del__` method.
Weak references are :term:`hashable` if the *object* is hashable. They will maintain
their hash value even after the *object* was deleted. If :func:`hash` is called
the first time only after the *object* was deleted, the call will raise
:exc:`TypeError`.
Weak references support tests for equality, but not ordering. If the referents
are still alive, two references have the same equality relationship as their
referents (regardless of the *callback*). If either referent has been deleted,
the references are equal only if the reference objects are the same object.
.. versionchanged:: 2.4
This is now a subclassable type rather than a factory function; it derives from
:class:`object`.
.. function:: proxy(object[, callback])
Return a proxy to *object* which uses a weak reference. This supports use of
the proxy in most contexts instead of requiring the explicit dereferencing used
with weak reference objects. The returned object will have a type of either
``ProxyType`` or ``CallableProxyType``, depending on whether *object* is
callable. Proxy objects are not :term:`hashable` regardless of the referent; this
avoids a number of problems related to their fundamentally mutable nature, and
prevent their use as dictionary keys. *callback* is the same as the parameter
of the same name to the :func:`ref` function.
.. function:: getweakrefcount(object)
Return the number of weak references and proxies which refer to *object*.
.. function:: getweakrefs(object)
Return a list of all weak reference and proxy objects which refer to *object*.
.. class:: WeakKeyDictionary([dict])
Mapping class that references keys weakly. Entries in the dictionary will be
discarded when there is no longer a strong reference to the key. This can be
used to associate additional data with an object owned by other parts of an
application without adding attributes to those objects. This can be especially
useful with objects that override attribute accesses.
.. note::
Caution: Because a :class:`WeakKeyDictionary` is built on top of a Python
dictionary, it must not change size when iterating over it. This can be
difficult to ensure for a :class:`WeakKeyDictionary` because actions
performed by the program during iteration may cause items in the
dictionary to vanish "by magic" (as a side effect of garbage collection).
:class:`WeakKeyDictionary` objects have the following additional methods. These
expose the internal references directly. The references are not guaranteed to
be "live" at the time they are used, so the result of calling the references
needs to be checked before being used. This can be used to avoid creating
references that will cause the garbage collector to keep the keys around longer
than needed.
.. method:: WeakKeyDictionary.iterkeyrefs()
Return an iterable of the weak references to the keys.
.. versionadded:: 2.5
.. method:: WeakKeyDictionary.keyrefs()
Return a list of weak references to the keys.
.. versionadded:: 2.5
.. class:: WeakValueDictionary([dict])
Mapping class that references values weakly. Entries in the dictionary will be
discarded when no strong reference to the value exists any more.
.. note::
Caution: Because a :class:`WeakValueDictionary` is built on top of a Python
dictionary, it must not change size when iterating over it. This can be
difficult to ensure for a :class:`WeakValueDictionary` because actions performed
by the program during iteration may cause items in the dictionary to vanish "by
magic" (as a side effect of garbage collection).
:class:`WeakValueDictionary` objects have the following additional methods.
These methods have the same issues as the :meth:`iterkeyrefs` and
:meth:`keyrefs` methods of :class:`WeakKeyDictionary` objects.
.. method:: WeakValueDictionary.itervaluerefs()
Return an iterable of the weak references to the values.
.. versionadded:: 2.5
.. method:: WeakValueDictionary.valuerefs()
Return a list of weak references to the values.
.. versionadded:: 2.5
.. class:: WeakSet([elements])
Set class that keeps weak references to its elements. An element will be
discarded when no strong reference to it exists any more.
.. versionadded:: 2.7
.. data:: ReferenceType
The type object for weak references objects.
.. data:: ProxyType
The type object for proxies of objects which are not callable.
.. data:: CallableProxyType
The type object for proxies of callable objects.
.. data:: ProxyTypes
Sequence containing all the type objects for proxies. This can make it simpler
to test if an object is a proxy without being dependent on naming both proxy
types.
.. exception:: ReferenceError
Exception raised when a proxy object is used but the underlying object has been
collected. This is the same as the standard :exc:`ReferenceError` exception.
.. seealso::
:pep:`205` - Weak References
The proposal and rationale for this feature, including links to earlier
implementations and information about similar features in other languages.
.. _weakref-objects:
Weak Reference Objects
----------------------
Weak reference objects have no attributes or methods, but do allow the referent
to be obtained, if it still exists, by calling it:
>>> import weakref
>>> class Object:
... pass
...
>>> o = Object()
>>> r = weakref.ref(o)
>>> o2 = r()
>>> o is o2
True
If the referent no longer exists, calling the reference object returns
:const:`None`:
>>> del o, o2
>>> print r()
None
Testing that a weak reference object is still live should be done using the
expression ``ref() is not None``. Normally, application code that needs to use
a reference object should follow this pattern::
# r is a weak reference object
o = r()
if o is None:
# referent has been garbage collected
print "Object has been deallocated; can't frobnicate."
else:
print "Object is still live!"
o.do_something_useful()
Using a separate test for "liveness" creates race conditions in threaded
applications; another thread can cause a weak reference to become invalidated
before the weak reference is called; the idiom shown above is safe in threaded
applications as well as single-threaded applications.
Specialized versions of :class:`ref` objects can be created through subclassing.
This is used in the implementation of the :class:`WeakValueDictionary` to reduce
the memory overhead for each entry in the mapping. This may be most useful to
associate additional information with a reference, but could also be used to
insert additional processing on calls to retrieve the referent.
This example shows how a subclass of :class:`ref` can be used to store
additional information about an object and affect the value that's returned when
the referent is accessed::
import weakref
class ExtendedRef(weakref.ref):
def __init__(self, ob, callback=None, **annotations):
super(ExtendedRef, self).__init__(ob, callback)
self.__counter = 0
for k, v in annotations.iteritems():
setattr(self, k, v)
def __call__(self):
"""Return a pair containing the referent and the number of
times the reference has been called.
"""
ob = super(ExtendedRef, self).__call__()
if ob is not None:
self.__counter += 1
ob = (ob, self.__counter)
return ob
.. _weakref-example:
Example
-------
This simple example shows how an application can use object IDs to retrieve
objects that it has seen before. The IDs of the objects can then be used in
other data structures without forcing the objects to remain alive, but the
objects can still be retrieved by ID if they do.
.. Example contributed by Tim Peters.
::
import weakref
_id2obj_dict = weakref.WeakValueDictionary()
def remember(obj):
oid = id(obj)
_id2obj_dict[oid] = obj
return oid
def id2obj(oid):
return _id2obj_dict[oid]
PK
%�\ �Ň& �& ( html/_sources/library/webbrowser.rst.txtnu �[��� :mod:`webbrowser` --- Convenient Web-browser controller
=======================================================
.. module:: webbrowser
:synopsis: Easy-to-use controller for Web browsers.
.. moduleauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
**Source code:** :source:`Lib/webbrowser.py`
--------------
The :mod:`webbrowser` module provides a high-level interface to allow displaying
Web-based documents to users. Under most circumstances, simply calling the
:func:`.open` function from this module will do the right thing.
Under Unix, graphical browsers are preferred under X11, but text-mode browsers
will be used if graphical browsers are not available or an X11 display isn't
available. If text-mode browsers are used, the calling process will block until
the user exits the browser.
If the environment variable :envvar:`BROWSER` exists, it is interpreted to
override the platform default list of browsers, as an :data:`os.pathsep`-separated
list of browsers to try in order. When the value of a list part contains the
string ``%s``, then it is interpreted as a literal browser command line to be
used with the argument URL substituted for ``%s``; if the part does not contain
``%s``, it is simply interpreted as the name of the browser to launch. [1]_
For non-Unix platforms, or when a remote browser is available on Unix, the
controlling process will not wait for the user to finish with the browser, but
allow the remote browser to maintain its own windows on the display. If remote
browsers are not available on Unix, the controlling process will launch a new
browser and wait.
The script :program:`webbrowser` can be used as a command-line interface for the
module. It accepts a URL as the argument. It accepts the following optional
parameters: ``-n`` opens the URL in a new browser window, if possible;
``-t`` opens the URL in a new browser page ("tab"). The options are,
naturally, mutually exclusive. Usage example::
python -m webbrowser -t "http://www.python.org"
The following exception is defined:
.. exception:: Error
Exception raised when a browser control error occurs.
The following functions are defined:
.. function:: open(url, new=0, autoraise=True)
Display *url* using the default browser. If *new* is 0, the *url* is opened
in the same browser window if possible. If *new* is 1, a new browser window
is opened if possible. If *new* is 2, a new browser page ("tab") is opened
if possible. If *autoraise* is ``True``, the window is raised if possible
(note that under many window managers this will occur regardless of the
setting of this variable).
Note that on some platforms, trying to open a filename using this function,
may work and start the operating system's associated program. However, this
is neither supported nor portable.
.. versionchanged:: 2.5
*new* can now be 2.
.. function:: open_new(url)
Open *url* in a new window of the default browser, if possible, otherwise, open
*url* in the only browser window.
.. function:: open_new_tab(url)
Open *url* in a new page ("tab") of the default browser, if possible, otherwise
equivalent to :func:`open_new`.
.. versionadded:: 2.5
.. function:: get([name])
Return a controller object for the browser type *name*. If *name* is empty,
return a controller for a default browser appropriate to the caller's
environment.
.. function:: register(name, constructor[, instance])
Register the browser type *name*. Once a browser type is registered, the
:func:`get` function can return a controller for that browser type. If
*instance* is not provided, or is ``None``, *constructor* will be called without
parameters to create an instance when needed. If *instance* is provided,
*constructor* will never be called, and may be ``None``.
This entry point is only useful if you plan to either set the :envvar:`BROWSER`
variable or call :func:`get` with a nonempty argument matching the name of a
handler you declare.
A number of browser types are predefined. This table gives the type names that
may be passed to the :func:`get` function and the corresponding instantiations
for the controller classes, all defined in this module.
+-----------------------+-----------------------------------------+-------+
| Type Name | Class Name | Notes |
+=======================+=========================================+=======+
| ``'mozilla'`` | :class:`Mozilla('mozilla')` | |
+-----------------------+-----------------------------------------+-------+
| ``'firefox'`` | :class:`Mozilla('mozilla')` | |
+-----------------------+-----------------------------------------+-------+
| ``'netscape'`` | :class:`Mozilla('netscape')` | |
+-----------------------+-----------------------------------------+-------+
| ``'galeon'`` | :class:`Galeon('galeon')` | |
+-----------------------+-----------------------------------------+-------+
| ``'epiphany'`` | :class:`Galeon('epiphany')` | |
+-----------------------+-----------------------------------------+-------+
| ``'skipstone'`` | :class:`BackgroundBrowser('skipstone')` | |
+-----------------------+-----------------------------------------+-------+
| ``'kfmclient'`` | :class:`Konqueror()` | \(1) |
+-----------------------+-----------------------------------------+-------+
| ``'konqueror'`` | :class:`Konqueror()` | \(1) |
+-----------------------+-----------------------------------------+-------+
| ``'kfm'`` | :class:`Konqueror()` | \(1) |
+-----------------------+-----------------------------------------+-------+
| ``'mosaic'`` | :class:`BackgroundBrowser('mosaic')` | |
+-----------------------+-----------------------------------------+-------+
| ``'opera'`` | :class:`Opera()` | |
+-----------------------+-----------------------------------------+-------+
| ``'grail'`` | :class:`Grail()` | |
+-----------------------+-----------------------------------------+-------+
| ``'links'`` | :class:`GenericBrowser('links')` | |
+-----------------------+-----------------------------------------+-------+
| ``'elinks'`` | :class:`Elinks('elinks')` | |
+-----------------------+-----------------------------------------+-------+
| ``'lynx'`` | :class:`GenericBrowser('lynx')` | |
+-----------------------+-----------------------------------------+-------+
| ``'w3m'`` | :class:`GenericBrowser('w3m')` | |
+-----------------------+-----------------------------------------+-------+
| ``'windows-default'`` | :class:`WindowsDefault` | \(2) |
+-----------------------+-----------------------------------------+-------+
| ``'macosx'`` | :class:`MacOSX('default')` | \(3) |
+-----------------------+-----------------------------------------+-------+
| ``'safari'`` | :class:`MacOSX('safari')` | \(3) |
+-----------------------+-----------------------------------------+-------+
| ``'google-chrome'`` | :class:`Chrome('google-chrome')` | \(4) |
+-----------------------+-----------------------------------------+-------+
| ``'chrome'`` | :class:`Chrome('chrome')` | \(4) |
+-----------------------+-----------------------------------------+-------+
| ``'chromium'`` | :class:`Chromium('chromium')` | \(4) |
+-----------------------+-----------------------------------------+-------+
| ``'chromium-browser'``| :class:`Chromium('chromium-browser')` | \(4) |
+-----------------------+-----------------------------------------+-------+
Notes:
(1)
"Konqueror" is the file manager for the KDE desktop environment for Unix, and
only makes sense to use if KDE is running. Some way of reliably detecting KDE
would be nice; the :envvar:`KDEDIR` variable is not sufficient. Note also that
the name "kfm" is used even when using the :program:`konqueror` command with KDE
2 --- the implementation selects the best strategy for running Konqueror.
(2)
Only on Windows platforms.
(3)
Only on Mac OS X platform.
(4)
Support for Chrome/Chromium has been added in version 2.7.5.
Here are some simple examples::
url = 'http://www.python.org/'
# Open URL in a new tab, if a browser window is already open.
webbrowser.open_new_tab(url + 'doc/')
# Open URL in new window, raising the window if possible.
webbrowser.open_new(url)
.. _browser-controllers:
Browser Controller Objects
--------------------------
Browser controllers provide these methods which parallel three of the
module-level convenience functions:
.. method:: controller.open(url, new=0, autoraise=True)
Display *url* using the browser handled by this controller. If *new* is 1, a new
browser window is opened if possible. If *new* is 2, a new browser page ("tab")
is opened if possible.
.. method:: controller.open_new(url)
Open *url* in a new window of the browser handled by this controller, if
possible, otherwise, open *url* in the only browser window. Alias
:func:`open_new`.
.. method:: controller.open_new_tab(url)
Open *url* in a new page ("tab") of the browser handled by this controller, if
possible, otherwise equivalent to :func:`open_new`.
.. versionadded:: 2.5
.. rubric:: Footnotes
.. [1] Executables named here without a full path will be searched in the
directories given in the :envvar:`PATH` environment variable.
PK
%�\3�p_� � % html/_sources/library/whichdb.rst.txtnu �[��� :mod:`whichdb` --- Guess which DBM module created a database
============================================================
.. module:: whichdb
:synopsis: Guess which DBM-style module created a given database.
.. note::
The :mod:`whichdb` module's only function has been put into the :mod:`dbm`
module in Python 3. The :term:`2to3` tool will automatically adapt imports
when converting your sources to Python 3.
The single function in this module attempts to guess which of the several simple
database modules available—:mod:`dbm`, :mod:`gdbm`, or :mod:`dbhash`\
—should be used to open a given file.
.. function:: whichdb(filename)
Returns one of the following values: ``None`` if the file can't be opened
because it's unreadable or doesn't exist; the empty string (``''``) if the
file's format can't be guessed; or a string containing the required module name,
such as ``'dbm'`` or ``'gdbm'``.
PK
%�\(#Bf % html/_sources/library/windows.rst.txtnu �[��� .. _mswin-specific-services:
****************************
MS Windows Specific Services
****************************
This chapter describes modules that are only available on MS Windows platforms.
.. toctree::
msilib.rst
msvcrt.rst
_winreg.rst
winsound.rst
PK
%�\ԐVC� � & html/_sources/library/winsound.rst.txtnu �[���
:mod:`winsound` --- Sound-playing interface for Windows
=======================================================
.. module:: winsound
:platform: Windows
:synopsis: Access to the sound-playing machinery for Windows.
.. moduleauthor:: Toby Dickenson <htrd90@zepler.org>
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
.. versionadded:: 1.5.2
The :mod:`winsound` module provides access to the basic sound-playing machinery
provided by Windows platforms. It includes functions and several constants.
.. function:: Beep(frequency, duration)
Beep the PC's speaker. The *frequency* parameter specifies frequency, in hertz,
of the sound, and must be in the range 37 through 32,767. The *duration*
parameter specifies the number of milliseconds the sound should last. If the
system is not able to beep the speaker, :exc:`RuntimeError` is raised.
.. versionadded:: 1.6
.. function:: PlaySound(sound, flags)
Call the underlying :c:func:`PlaySound` function from the Platform API. The
*sound* parameter may be a filename, audio data as a string, or ``None``. Its
interpretation depends on the value of *flags*, which can be a bitwise ORed
combination of the constants described below. If the *sound* parameter is
``None``, any currently playing waveform sound is stopped. If the system
indicates an error, :exc:`RuntimeError` is raised.
.. function:: MessageBeep([type=MB_OK])
Call the underlying :c:func:`MessageBeep` function from the Platform API. This
plays a sound as specified in the registry. The *type* argument specifies which
sound to play; possible values are ``-1``, ``MB_ICONASTERISK``,
``MB_ICONEXCLAMATION``, ``MB_ICONHAND``, ``MB_ICONQUESTION``, and ``MB_OK``, all
described below. The value ``-1`` produces a "simple beep"; this is the final
fallback if a sound cannot be played otherwise.
.. versionadded:: 2.3
.. data:: SND_FILENAME
The *sound* parameter is the name of a WAV file. Do not use with
:const:`SND_ALIAS`.
.. data:: SND_ALIAS
The *sound* parameter is a sound association name from the registry. If the
registry contains no such name, play the system default sound unless
:const:`SND_NODEFAULT` is also specified. If no default sound is registered,
raise :exc:`RuntimeError`. Do not use with :const:`SND_FILENAME`.
All Win32 systems support at least the following; most systems support many
more:
+--------------------------+----------------------------------------+
| :func:`PlaySound` *name* | Corresponding Control Panel Sound name |
+==========================+========================================+
| ``'SystemAsterisk'`` | Asterisk |
+--------------------------+----------------------------------------+
| ``'SystemExclamation'`` | Exclamation |
+--------------------------+----------------------------------------+
| ``'SystemExit'`` | Exit Windows |
+--------------------------+----------------------------------------+
| ``'SystemHand'`` | Critical Stop |
+--------------------------+----------------------------------------+
| ``'SystemQuestion'`` | Question |
+--------------------------+----------------------------------------+
For example::
import winsound
# Play Windows exit sound.
winsound.PlaySound("SystemExit", winsound.SND_ALIAS)
# Probably play Windows default sound, if any is registered (because
# "*" probably isn't the registered name of any sound).
winsound.PlaySound("*", winsound.SND_ALIAS)
.. data:: SND_LOOP
Play the sound repeatedly. The :const:`SND_ASYNC` flag must also be used to
avoid blocking. Cannot be used with :const:`SND_MEMORY`.
.. data:: SND_MEMORY
The *sound* parameter to :func:`PlaySound` is a memory image of a WAV file, as a
string.
.. note::
This module does not support playing from a memory image asynchronously, so a
combination of this flag and :const:`SND_ASYNC` will raise :exc:`RuntimeError`.
.. data:: SND_PURGE
Stop playing all instances of the specified sound.
.. note::
This flag is not supported on modern Windows platforms.
.. data:: SND_ASYNC
Return immediately, allowing sounds to play asynchronously.
.. data:: SND_NODEFAULT
If the specified sound cannot be found, do not play the system default sound.
.. data:: SND_NOSTOP
Do not interrupt sounds currently playing.
.. data:: SND_NOWAIT
Return immediately if the sound driver is busy.
.. note::
This flag is not supported on modern Windows platforms.
.. data:: MB_ICONASTERISK
Play the ``SystemDefault`` sound.
.. data:: MB_ICONEXCLAMATION
Play the ``SystemExclamation`` sound.
.. data:: MB_ICONHAND
Play the ``SystemHand`` sound.
.. data:: MB_ICONQUESTION
Play the ``SystemQuestion`` sound.
.. data:: MB_OK
Play the ``SystemDefault`` sound.
PK
%�\y��mgw gw % html/_sources/library/wsgiref.rst.txtnu �[��� :mod:`wsgiref` --- WSGI Utilities and Reference Implementation
==============================================================
.. module:: wsgiref
:synopsis: WSGI Utilities and Reference Implementation.
.. moduleauthor:: Phillip J. Eby <pje@telecommunity.com>
.. sectionauthor:: Phillip J. Eby <pje@telecommunity.com>
.. versionadded:: 2.5
The Web Server Gateway Interface (WSGI) is a standard interface between web
server software and web applications written in Python. Having a standard
interface makes it easy to use an application that supports WSGI with a number
of different web servers.
Only authors of web servers and programming frameworks need to know every detail
and corner case of the WSGI design. You don't need to understand every detail
of WSGI just to install a WSGI application or to write a web application using
an existing framework.
:mod:`wsgiref` is a reference implementation of the WSGI specification that can
be used to add WSGI support to a web server or framework. It provides utilities
for manipulating WSGI environment variables and response headers, base classes
for implementing WSGI servers, a demo HTTP server that serves WSGI applications,
and a validation tool that checks WSGI servers and applications for conformance
to the WSGI specification (:pep:`333`).
See https://wsgi.readthedocs.org/ for more information about WSGI, and links to
tutorials and other resources.
.. XXX If you're just trying to write a web application...
:mod:`wsgiref.util` -- WSGI environment utilities
-------------------------------------------------
.. module:: wsgiref.util
:synopsis: WSGI environment utilities.
This module provides a variety of utility functions for working with WSGI
environments. A WSGI environment is a dictionary containing HTTP request
variables as described in :pep:`333`. All of the functions taking an *environ*
parameter expect a WSGI-compliant dictionary to be supplied; please see
:pep:`333` for a detailed specification.
.. function:: guess_scheme(environ)
Return a guess for whether ``wsgi.url_scheme`` should be "http" or "https", by
checking for a ``HTTPS`` environment variable in the *environ* dictionary. The
return value is a string.
This function is useful when creating a gateway that wraps CGI or a CGI-like
protocol such as FastCGI. Typically, servers providing such protocols will
include a ``HTTPS`` variable with a value of "1" "yes", or "on" when a request
is received via SSL. So, this function returns "https" if such a value is
found, and "http" otherwise.
.. function:: request_uri(environ, include_query=1)
Return the full request URI, optionally including the query string, using the
algorithm found in the "URL Reconstruction" section of :pep:`333`. If
*include_query* is false, the query string is not included in the resulting URI.
.. function:: application_uri(environ)
Similar to :func:`request_uri`, except that the ``PATH_INFO`` and
``QUERY_STRING`` variables are ignored. The result is the base URI of the
application object addressed by the request.
.. function:: shift_path_info(environ)
Shift a single name from ``PATH_INFO`` to ``SCRIPT_NAME`` and return the name.
The *environ* dictionary is *modified* in-place; use a copy if you need to keep
the original ``PATH_INFO`` or ``SCRIPT_NAME`` intact.
If there are no remaining path segments in ``PATH_INFO``, ``None`` is returned.
Typically, this routine is used to process each portion of a request URI path,
for example to treat the path as a series of dictionary keys. This routine
modifies the passed-in environment to make it suitable for invoking another WSGI
application that is located at the target URI. For example, if there is a WSGI
application at ``/foo``, and the request URI path is ``/foo/bar/baz``, and the
WSGI application at ``/foo`` calls :func:`shift_path_info`, it will receive the
string "bar", and the environment will be updated to be suitable for passing to
a WSGI application at ``/foo/bar``. That is, ``SCRIPT_NAME`` will change from
``/foo`` to ``/foo/bar``, and ``PATH_INFO`` will change from ``/bar/baz`` to
``/baz``.
When ``PATH_INFO`` is just a "/", this routine returns an empty string and
appends a trailing slash to ``SCRIPT_NAME``, even though empty path segments are
normally ignored, and ``SCRIPT_NAME`` doesn't normally end in a slash. This is
intentional behavior, to ensure that an application can tell the difference
between URIs ending in ``/x`` from ones ending in ``/x/`` when using this
routine to do object traversal.
.. function:: setup_testing_defaults(environ)
Update *environ* with trivial defaults for testing purposes.
This routine adds various parameters required for WSGI, including ``HTTP_HOST``,
``SERVER_NAME``, ``SERVER_PORT``, ``REQUEST_METHOD``, ``SCRIPT_NAME``,
``PATH_INFO``, and all of the :pep:`333`\ -defined ``wsgi.*`` variables. It
only supplies default values, and does not replace any existing settings for
these variables.
This routine is intended to make it easier for unit tests of WSGI servers and
applications to set up dummy environments. It should NOT be used by actual WSGI
servers or applications, since the data is fake!
Example usage::
from wsgiref.util import setup_testing_defaults
from wsgiref.simple_server import make_server
# A relatively simple WSGI application. It's going to print out the
# environment dictionary after being updated by setup_testing_defaults
def simple_app(environ, start_response):
setup_testing_defaults(environ)
status = '200 OK'
headers = [('Content-type', 'text/plain')]
start_response(status, headers)
ret = ["%s: %s\n" % (key, value)
for key, value in environ.iteritems()]
return ret
httpd = make_server('', 8000, simple_app)
print "Serving on port 8000..."
httpd.serve_forever()
In addition to the environment functions above, the :mod:`wsgiref.util` module
also provides these miscellaneous utilities:
.. function:: is_hop_by_hop(header_name)
Return true if 'header_name' is an HTTP/1.1 "Hop-by-Hop" header, as defined by
:rfc:`2616`.
.. class:: FileWrapper(filelike, blksize=8192)
A wrapper to convert a file-like object to an :term:`iterator`. The resulting objects
support both :meth:`__getitem__` and :meth:`__iter__` iteration styles, for
compatibility with Python 2.1 and Jython. As the object is iterated over, the
optional *blksize* parameter will be repeatedly passed to the *filelike*
object's :meth:`read` method to obtain strings to yield. When :meth:`read`
returns an empty string, iteration is ended and is not resumable.
If *filelike* has a :meth:`close` method, the returned object will also have a
:meth:`close` method, and it will invoke the *filelike* object's :meth:`close`
method when called.
Example usage::
from StringIO import StringIO
from wsgiref.util import FileWrapper
# We're using a StringIO-buffer for as the file-like object
filelike = StringIO("This is an example file-like object"*10)
wrapper = FileWrapper(filelike, blksize=5)
for chunk in wrapper:
print chunk
:mod:`wsgiref.headers` -- WSGI response header tools
----------------------------------------------------
.. module:: wsgiref.headers
:synopsis: WSGI response header tools.
This module provides a single class, :class:`Headers`, for convenient
manipulation of WSGI response headers using a mapping-like interface.
.. class:: Headers(headers)
Create a mapping-like object wrapping *headers*, which must be a list of header
name/value tuples as described in :pep:`333`. Any changes made to the new
:class:`Headers` object will directly update the *headers* list it was created
with.
:class:`Headers` objects support typical mapping operations including
:meth:`__getitem__`, :meth:`get`, :meth:`__setitem__`, :meth:`setdefault`,
:meth:`__delitem__`, :meth:`__contains__` and :meth:`has_key`. For each of
these methods, the key is the header name (treated case-insensitively), and the
value is the first value associated with that header name. Setting a header
deletes any existing values for that header, then adds a new value at the end of
the wrapped header list. Headers' existing order is generally maintained, with
new headers added to the end of the wrapped list.
Unlike a dictionary, :class:`Headers` objects do not raise an error when you try
to get or delete a key that isn't in the wrapped header list. Getting a
nonexistent header just returns ``None``, and deleting a nonexistent header does
nothing.
:class:`Headers` objects also support :meth:`keys`, :meth:`values`, and
:meth:`items` methods. The lists returned by :meth:`keys` and :meth:`items` can
include the same key more than once if there is a multi-valued header. The
``len()`` of a :class:`Headers` object is the same as the length of its
:meth:`items`, which is the same as the length of the wrapped header list. In
fact, the :meth:`items` method just returns a copy of the wrapped header list.
Calling ``str()`` on a :class:`Headers` object returns a formatted string
suitable for transmission as HTTP response headers. Each header is placed on a
line with its value, separated by a colon and a space. Each line is terminated
by a carriage return and line feed, and the string is terminated with a blank
line.
In addition to their mapping interface and formatting features, :class:`Headers`
objects also have the following methods for querying and adding multi-valued
headers, and for adding headers with MIME parameters:
.. method:: Headers.get_all(name)
Return a list of all the values for the named header.
The returned list will be sorted in the order they appeared in the original
header list or were added to this instance, and may contain duplicates. Any
fields deleted and re-inserted are always appended to the header list. If no
fields exist with the given name, returns an empty list.
.. method:: Headers.add_header(name, value, **_params)
Add a (possibly multi-valued) header, with optional MIME parameters specified
via keyword arguments.
*name* is the header field to add. Keyword arguments can be used to set MIME
parameters for the header field. Each parameter must be a string or ``None``.
Underscores in parameter names are converted to dashes, since dashes are illegal
in Python identifiers, but many MIME parameter names include dashes. If the
parameter value is a string, it is added to the header value parameters in the
form ``name="value"``. If it is ``None``, only the parameter name is added.
(This is used for MIME parameters without a value.) Example usage::
h.add_header('content-disposition', 'attachment', filename='bud.gif')
The above will add a header that looks like this::
Content-Disposition: attachment; filename="bud.gif"
:mod:`wsgiref.simple_server` -- a simple WSGI HTTP server
---------------------------------------------------------
.. module:: wsgiref.simple_server
:synopsis: A simple WSGI HTTP server.
This module implements a simple HTTP server (based on :mod:`BaseHTTPServer`)
that serves WSGI applications. Each server instance serves a single WSGI
application on a given host and port. If you want to serve multiple
applications on a single host and port, you should create a WSGI application
that parses ``PATH_INFO`` to select which application to invoke for each
request. (E.g., using the :func:`shift_path_info` function from
:mod:`wsgiref.util`.)
.. function:: make_server(host, port, app, server_class=WSGIServer, handler_class=WSGIRequestHandler)
Create a new WSGI server listening on *host* and *port*, accepting connections
for *app*. The return value is an instance of the supplied *server_class*, and
will process requests using the specified *handler_class*. *app* must be a WSGI
application object, as defined by :pep:`333`.
Example usage::
from wsgiref.simple_server import make_server, demo_app
httpd = make_server('', 8000, demo_app)
print "Serving HTTP on port 8000..."
# Respond to requests until process is killed
httpd.serve_forever()
# Alternative: serve one request, then exit
httpd.handle_request()
.. function:: demo_app(environ, start_response)
This function is a small but complete WSGI application that returns a text page
containing the message "Hello world!" and a list of the key/value pairs provided
in the *environ* parameter. It's useful for verifying that a WSGI server (such
as :mod:`wsgiref.simple_server`) is able to run a simple WSGI application
correctly.
.. class:: WSGIServer(server_address, RequestHandlerClass)
Create a :class:`WSGIServer` instance. *server_address* should be a
``(host,port)`` tuple, and *RequestHandlerClass* should be the subclass of
:class:`BaseHTTPServer.BaseHTTPRequestHandler` that will be used to process
requests.
You do not normally need to call this constructor, as the :func:`make_server`
function can handle all the details for you.
:class:`WSGIServer` is a subclass of :class:`BaseHTTPServer.HTTPServer`, so all
of its methods (such as :meth:`serve_forever` and :meth:`handle_request`) are
available. :class:`WSGIServer` also provides these WSGI-specific methods:
.. method:: WSGIServer.set_app(application)
Sets the callable *application* as the WSGI application that will receive
requests.
.. method:: WSGIServer.get_app()
Returns the currently-set application callable.
Normally, however, you do not need to use these additional methods, as
:meth:`set_app` is normally called by :func:`make_server`, and the
:meth:`get_app` exists mainly for the benefit of request handler instances.
.. class:: WSGIRequestHandler(request, client_address, server)
Create an HTTP handler for the given *request* (i.e. a socket), *client_address*
(a ``(host,port)`` tuple), and *server* (:class:`WSGIServer` instance).
You do not need to create instances of this class directly; they are
automatically created as needed by :class:`WSGIServer` objects. You can,
however, subclass this class and supply it as a *handler_class* to the
:func:`make_server` function. Some possibly relevant methods for overriding in
subclasses:
.. method:: WSGIRequestHandler.get_environ()
Returns a dictionary containing the WSGI environment for a request. The default
implementation copies the contents of the :class:`WSGIServer` object's
:attr:`base_environ` dictionary attribute and then adds various headers derived
from the HTTP request. Each call to this method should return a new dictionary
containing all of the relevant CGI environment variables as specified in
:pep:`333`.
.. method:: WSGIRequestHandler.get_stderr()
Return the object that should be used as the ``wsgi.errors`` stream. The default
implementation just returns ``sys.stderr``.
.. method:: WSGIRequestHandler.handle()
Process the HTTP request. The default implementation creates a handler instance
using a :mod:`wsgiref.handlers` class to implement the actual WSGI application
interface.
:mod:`wsgiref.validate` --- WSGI conformance checker
----------------------------------------------------
.. module:: wsgiref.validate
:synopsis: WSGI conformance checker.
When creating new WSGI application objects, frameworks, servers, or middleware,
it can be useful to validate the new code's conformance using
:mod:`wsgiref.validate`. This module provides a function that creates WSGI
application objects that validate communications between a WSGI server or
gateway and a WSGI application object, to check both sides for protocol
conformance.
Note that this utility does not guarantee complete :pep:`333` compliance; an
absence of errors from this module does not necessarily mean that errors do not
exist. However, if this module does produce an error, then it is virtually
certain that either the server or application is not 100% compliant.
This module is based on the :mod:`paste.lint` module from Ian Bicking's "Python
Paste" library.
.. function:: validator(application)
Wrap *application* and return a new WSGI application object. The returned
application will forward all requests to the original *application*, and will
check that both the *application* and the server invoking it are conforming to
the WSGI specification and to RFC 2616.
Any detected nonconformance results in an :exc:`AssertionError` being raised;
note, however, that how these errors are handled is server-dependent. For
example, :mod:`wsgiref.simple_server` and other servers based on
:mod:`wsgiref.handlers` (that don't override the error handling methods to do
something else) will simply output a message that an error has occurred, and
dump the traceback to ``sys.stderr`` or some other error stream.
This wrapper may also generate output using the :mod:`warnings` module to
indicate behaviors that are questionable but which may not actually be
prohibited by :pep:`333`. Unless they are suppressed using Python command-line
options or the :mod:`warnings` API, any such warnings will be written to
``sys.stderr`` (*not* ``wsgi.errors``, unless they happen to be the same
object).
Example usage::
from wsgiref.validate import validator
from wsgiref.simple_server import make_server
# Our callable object which is intentionally not compliant to the
# standard, so the validator is going to break
def simple_app(environ, start_response):
status = '200 OK' # HTTP Status
headers = [('Content-type', 'text/plain')] # HTTP Headers
start_response(status, headers)
# This is going to break because we need to return a list, and
# the validator is going to inform us
return "Hello World"
# This is the application wrapped in a validator
validator_app = validator(simple_app)
httpd = make_server('', 8000, validator_app)
print "Listening on port 8000...."
httpd.serve_forever()
:mod:`wsgiref.handlers` -- server/gateway base classes
------------------------------------------------------
.. module:: wsgiref.handlers
:synopsis: WSGI server/gateway base classes.
This module provides base handler classes for implementing WSGI servers and
gateways. These base classes handle most of the work of communicating with a
WSGI application, as long as they are given a CGI-like environment, along with
input, output, and error streams.
.. class:: CGIHandler()
CGI-based invocation via ``sys.stdin``, ``sys.stdout``, ``sys.stderr`` and
``os.environ``. This is useful when you have a WSGI application and want to run
it as a CGI script. Simply invoke ``CGIHandler().run(app)``, where ``app`` is
the WSGI application object you wish to invoke.
This class is a subclass of :class:`BaseCGIHandler` that sets ``wsgi.run_once``
to true, ``wsgi.multithread`` to false, and ``wsgi.multiprocess`` to true, and
always uses :mod:`sys` and :mod:`os` to obtain the necessary CGI streams and
environment.
.. class:: BaseCGIHandler(stdin, stdout, stderr, environ, multithread=True, multiprocess=False)
Similar to :class:`CGIHandler`, but instead of using the :mod:`sys` and
:mod:`os` modules, the CGI environment and I/O streams are specified explicitly.
The *multithread* and *multiprocess* values are used to set the
``wsgi.multithread`` and ``wsgi.multiprocess`` flags for any applications run by
the handler instance.
This class is a subclass of :class:`SimpleHandler` intended for use with
software other than HTTP "origin servers". If you are writing a gateway
protocol implementation (such as CGI, FastCGI, SCGI, etc.) that uses a
``Status:`` header to send an HTTP status, you probably want to subclass this
instead of :class:`SimpleHandler`.
.. class:: SimpleHandler(stdin, stdout, stderr, environ, multithread=True, multiprocess=False)
Similar to :class:`BaseCGIHandler`, but designed for use with HTTP origin
servers. If you are writing an HTTP server implementation, you will probably
want to subclass this instead of :class:`BaseCGIHandler`.
This class is a subclass of :class:`BaseHandler`. It overrides the
:meth:`__init__`, :meth:`get_stdin`, :meth:`get_stderr`, :meth:`add_cgi_vars`,
:meth:`_write`, and :meth:`_flush` methods to support explicitly setting the
environment and streams via the constructor. The supplied environment and
streams are stored in the :attr:`stdin`, :attr:`stdout`, :attr:`stderr`, and
:attr:`environ` attributes.
.. class:: BaseHandler()
This is an abstract base class for running WSGI applications. Each instance
will handle a single HTTP request, although in principle you could create a
subclass that was reusable for multiple requests.
:class:`BaseHandler` instances have only one method intended for external use:
.. method:: BaseHandler.run(app)
Run the specified WSGI application, *app*.
All of the other :class:`BaseHandler` methods are invoked by this method in the
process of running the application, and thus exist primarily to allow
customizing the process.
The following methods MUST be overridden in a subclass:
.. method:: BaseHandler._write(data)
Buffer the string *data* for transmission to the client. It's okay if this
method actually transmits the data; :class:`BaseHandler` just separates write
and flush operations for greater efficiency when the underlying system actually
has such a distinction.
.. method:: BaseHandler._flush()
Force buffered data to be transmitted to the client. It's okay if this method
is a no-op (i.e., if :meth:`_write` actually sends the data).
.. method:: BaseHandler.get_stdin()
Return an input stream object suitable for use as the ``wsgi.input`` of the
request currently being processed.
.. method:: BaseHandler.get_stderr()
Return an output stream object suitable for use as the ``wsgi.errors`` of the
request currently being processed.
.. method:: BaseHandler.add_cgi_vars()
Insert CGI variables for the current request into the :attr:`environ` attribute.
Here are some other methods and attributes you may wish to override. This list
is only a summary, however, and does not include every method that can be
overridden. You should consult the docstrings and source code for additional
information before attempting to create a customized :class:`BaseHandler`
subclass.
Attributes and methods for customizing the WSGI environment:
.. attribute:: BaseHandler.wsgi_multithread
The value to be used for the ``wsgi.multithread`` environment variable. It
defaults to true in :class:`BaseHandler`, but may have a different default (or
be set by the constructor) in the other subclasses.
.. attribute:: BaseHandler.wsgi_multiprocess
The value to be used for the ``wsgi.multiprocess`` environment variable. It
defaults to true in :class:`BaseHandler`, but may have a different default (or
be set by the constructor) in the other subclasses.
.. attribute:: BaseHandler.wsgi_run_once
The value to be used for the ``wsgi.run_once`` environment variable. It
defaults to false in :class:`BaseHandler`, but :class:`CGIHandler` sets it to
true by default.
.. attribute:: BaseHandler.os_environ
The default environment variables to be included in every request's WSGI
environment. By default, this is a copy of ``os.environ`` at the time that
:mod:`wsgiref.handlers` was imported, but subclasses can either create their own
at the class or instance level. Note that the dictionary should be considered
read-only, since the default value is shared between multiple classes and
instances.
.. attribute:: BaseHandler.server_software
If the :attr:`origin_server` attribute is set, this attribute's value is used to
set the default ``SERVER_SOFTWARE`` WSGI environment variable, and also to set a
default ``Server:`` header in HTTP responses. It is ignored for handlers (such
as :class:`BaseCGIHandler` and :class:`CGIHandler`) that are not HTTP origin
servers.
.. method:: BaseHandler.get_scheme()
Return the URL scheme being used for the current request. The default
implementation uses the :func:`guess_scheme` function from :mod:`wsgiref.util`
to guess whether the scheme should be "http" or "https", based on the current
request's :attr:`environ` variables.
.. method:: BaseHandler.setup_environ()
Set the :attr:`environ` attribute to a fully-populated WSGI environment. The
default implementation uses all of the above methods and attributes, plus the
:meth:`get_stdin`, :meth:`get_stderr`, and :meth:`add_cgi_vars` methods and the
:attr:`wsgi_file_wrapper` attribute. It also inserts a ``SERVER_SOFTWARE`` key
if not present, as long as the :attr:`origin_server` attribute is a true value
and the :attr:`server_software` attribute is set.
Methods and attributes for customizing exception handling:
.. method:: BaseHandler.log_exception(exc_info)
Log the *exc_info* tuple in the server log. *exc_info* is a ``(type, value,
traceback)`` tuple. The default implementation simply writes the traceback to
the request's ``wsgi.errors`` stream and flushes it. Subclasses can override
this method to change the format or retarget the output, mail the traceback to
an administrator, or whatever other action may be deemed suitable.
.. attribute:: BaseHandler.traceback_limit
The maximum number of frames to include in tracebacks output by the default
:meth:`log_exception` method. If ``None``, all frames are included.
.. method:: BaseHandler.error_output(environ, start_response)
This method is a WSGI application to generate an error page for the user. It is
only invoked if an error occurs before headers are sent to the client.
This method can access the current error information using ``sys.exc_info()``,
and should pass that information to *start_response* when calling it (as
described in the "Error Handling" section of :pep:`333`).
The default implementation just uses the :attr:`error_status`,
:attr:`error_headers`, and :attr:`error_body` attributes to generate an output
page. Subclasses can override this to produce more dynamic error output.
Note, however, that it's not recommended from a security perspective to spit out
diagnostics to any old user; ideally, you should have to do something special to
enable diagnostic output, which is why the default implementation doesn't
include any.
.. attribute:: BaseHandler.error_status
The HTTP status used for error responses. This should be a status string as
defined in :pep:`333`; it defaults to a 500 code and message.
.. attribute:: BaseHandler.error_headers
The HTTP headers used for error responses. This should be a list of WSGI
response headers (``(name, value)`` tuples), as described in :pep:`333`. The
default list just sets the content type to ``text/plain``.
.. attribute:: BaseHandler.error_body
The error response body. This should be an HTTP response body string. It
defaults to the plain text, "A server error occurred. Please contact the
administrator."
Methods and attributes for :pep:`333`'s "Optional Platform-Specific File
Handling" feature:
.. attribute:: BaseHandler.wsgi_file_wrapper
A ``wsgi.file_wrapper`` factory, or ``None``. The default value of this
attribute is the :class:`FileWrapper` class from :mod:`wsgiref.util`.
.. method:: BaseHandler.sendfile()
Override to implement platform-specific file transmission. This method is
called only if the application's return value is an instance of the class
specified by the :attr:`wsgi_file_wrapper` attribute. It should return a true
value if it was able to successfully transmit the file, so that the default
transmission code will not be executed. The default implementation of this
method just returns a false value.
Miscellaneous methods and attributes:
.. attribute:: BaseHandler.origin_server
This attribute should be set to a true value if the handler's :meth:`_write` and
:meth:`_flush` are being used to communicate directly to the client, rather than
via a CGI-like gateway protocol that wants the HTTP status in a special
``Status:`` header.
This attribute's default value is true in :class:`BaseHandler`, but false in
:class:`BaseCGIHandler` and :class:`CGIHandler`.
.. attribute:: BaseHandler.http_version
If :attr:`origin_server` is true, this string attribute is used to set the HTTP
version of the response set to the client. It defaults to ``"1.0"``.
Examples
--------
This is a working "Hello World" WSGI application::
from wsgiref.simple_server import make_server
# Every WSGI application must have an application object - a callable
# object that accepts two arguments. For that purpose, we're going to
# use a function (note that you're not limited to a function, you can
# use a class for example). The first argument passed to the function
# is a dictionary containing CGI-style environment variables and the
# second variable is the callable object (see PEP 333).
def hello_world_app(environ, start_response):
status = '200 OK' # HTTP Status
headers = [('Content-type', 'text/plain')] # HTTP Headers
start_response(status, headers)
# The returned object is going to be printed
return ["Hello World"]
httpd = make_server('', 8000, hello_world_app)
print "Serving on port 8000..."
# Serve until process is killed
httpd.serve_forever()
PK
%�\�>�[� � $ html/_sources/library/xdrlib.rst.txtnu �[��� :mod:`xdrlib` --- Encode and decode XDR data
============================================
.. module:: xdrlib
:synopsis: Encoders and decoders for the External Data Representation (XDR).
.. index::
single: XDR
single: External Data Representation
**Source code:** :source:`Lib/xdrlib.py`
--------------
The :mod:`xdrlib` module supports the External Data Representation Standard as
described in :rfc:`1014`, written by Sun Microsystems, Inc. June 1987. It
supports most of the data types described in the RFC.
The :mod:`xdrlib` module defines two classes, one for packing variables into XDR
representation, and another for unpacking from XDR representation. There are
also two exception classes.
.. class:: Packer()
:class:`Packer` is the class for packing data into XDR representation. The
:class:`Packer` class is instantiated with no arguments.
.. class:: Unpacker(data)
``Unpacker`` is the complementary class which unpacks XDR data values from a
string buffer. The input buffer is given as *data*.
.. seealso::
:rfc:`1014` - XDR: External Data Representation Standard
This RFC defined the encoding of data which was XDR at the time this module was
originally written. It has apparently been obsoleted by :rfc:`1832`.
:rfc:`1832` - XDR: External Data Representation Standard
Newer RFC that provides a revised definition of XDR.
.. _xdr-packer-objects:
Packer Objects
--------------
:class:`Packer` instances have the following methods:
.. method:: Packer.get_buffer()
Returns the current pack buffer as a string.
.. method:: Packer.reset()
Resets the pack buffer to the empty string.
In general, you can pack any of the most common XDR data types by calling the
appropriate ``pack_type()`` method. Each method takes a single argument, the
value to pack. The following simple data type packing methods are supported:
:meth:`pack_uint`, :meth:`pack_int`, :meth:`pack_enum`, :meth:`pack_bool`,
:meth:`pack_uhyper`, and :meth:`pack_hyper`.
.. method:: Packer.pack_float(value)
Packs the single-precision floating point number *value*.
.. method:: Packer.pack_double(value)
Packs the double-precision floating point number *value*.
The following methods support packing strings, bytes, and opaque data:
.. method:: Packer.pack_fstring(n, s)
Packs a fixed length string, *s*. *n* is the length of the string but it is
*not* packed into the data buffer. The string is padded with null bytes if
necessary to guaranteed 4 byte alignment.
.. method:: Packer.pack_fopaque(n, data)
Packs a fixed length opaque data stream, similarly to :meth:`pack_fstring`.
.. method:: Packer.pack_string(s)
Packs a variable length string, *s*. The length of the string is first packed
as an unsigned integer, then the string data is packed with
:meth:`pack_fstring`.
.. method:: Packer.pack_opaque(data)
Packs a variable length opaque data string, similarly to :meth:`pack_string`.
.. method:: Packer.pack_bytes(bytes)
Packs a variable length byte stream, similarly to :meth:`pack_string`.
The following methods support packing arrays and lists:
.. method:: Packer.pack_list(list, pack_item)
Packs a *list* of homogeneous items. This method is useful for lists with an
indeterminate size; i.e. the size is not available until the entire list has
been walked. For each item in the list, an unsigned integer ``1`` is packed
first, followed by the data value from the list. *pack_item* is the function
that is called to pack the individual item. At the end of the list, an unsigned
integer ``0`` is packed.
For example, to pack a list of integers, the code might appear like this::
import xdrlib
p = xdrlib.Packer()
p.pack_list([1, 2, 3], p.pack_int)
.. method:: Packer.pack_farray(n, array, pack_item)
Packs a fixed length list (*array*) of homogeneous items. *n* is the length of
the list; it is *not* packed into the buffer, but a :exc:`ValueError` exception
is raised if ``len(array)`` is not equal to *n*. As above, *pack_item* is the
function used to pack each element.
.. method:: Packer.pack_array(list, pack_item)
Packs a variable length *list* of homogeneous items. First, the length of the
list is packed as an unsigned integer, then each element is packed as in
:meth:`pack_farray` above.
.. _xdr-unpacker-objects:
Unpacker Objects
----------------
The :class:`Unpacker` class offers the following methods:
.. method:: Unpacker.reset(data)
Resets the string buffer with the given *data*.
.. method:: Unpacker.get_position()
Returns the current unpack position in the data buffer.
.. method:: Unpacker.set_position(position)
Sets the data buffer unpack position to *position*. You should be careful about
using :meth:`get_position` and :meth:`set_position`.
.. method:: Unpacker.get_buffer()
Returns the current unpack data buffer as a string.
.. method:: Unpacker.done()
Indicates unpack completion. Raises an :exc:`Error` exception if all of the
data has not been unpacked.
In addition, every data type that can be packed with a :class:`Packer`, can be
unpacked with an :class:`Unpacker`. Unpacking methods are of the form
``unpack_type()``, and take no arguments. They return the unpacked object.
.. method:: Unpacker.unpack_float()
Unpacks a single-precision floating point number.
.. method:: Unpacker.unpack_double()
Unpacks a double-precision floating point number, similarly to
:meth:`unpack_float`.
In addition, the following methods unpack strings, bytes, and opaque data:
.. method:: Unpacker.unpack_fstring(n)
Unpacks and returns a fixed length string. *n* is the number of characters
expected. Padding with null bytes to guaranteed 4 byte alignment is assumed.
.. method:: Unpacker.unpack_fopaque(n)
Unpacks and returns a fixed length opaque data stream, similarly to
:meth:`unpack_fstring`.
.. method:: Unpacker.unpack_string()
Unpacks and returns a variable length string. The length of the string is first
unpacked as an unsigned integer, then the string data is unpacked with
:meth:`unpack_fstring`.
.. method:: Unpacker.unpack_opaque()
Unpacks and returns a variable length opaque data string, similarly to
:meth:`unpack_string`.
.. method:: Unpacker.unpack_bytes()
Unpacks and returns a variable length byte stream, similarly to
:meth:`unpack_string`.
The following methods support unpacking arrays and lists:
.. method:: Unpacker.unpack_list(unpack_item)
Unpacks and returns a list of homogeneous items. The list is unpacked one
element at a time by first unpacking an unsigned integer flag. If the flag is
``1``, then the item is unpacked and appended to the list. A flag of ``0``
indicates the end of the list. *unpack_item* is the function that is called to
unpack the items.
.. method:: Unpacker.unpack_farray(n, unpack_item)
Unpacks and returns (as a list) a fixed length array of homogeneous items. *n*
is number of list elements to expect in the buffer. As above, *unpack_item* is
the function used to unpack each element.
.. method:: Unpacker.unpack_array(unpack_item)
Unpacks and returns a variable length *list* of homogeneous items. First, the
length of the list is unpacked as an unsigned integer, then each element is
unpacked as in :meth:`unpack_farray` above.
.. _xdr-exceptions:
Exceptions
----------
Exceptions in this module are coded as class instances:
.. exception:: Error
The base exception class. :exc:`Error` has a single public attribute
:attr:`msg` containing the description of the error.
.. exception:: ConversionError
Class derived from :exc:`Error`. Contains no additional instance variables.
Here is an example of how you would catch one of these exceptions::
import xdrlib
p = xdrlib.Packer()
try:
p.pack_double(8.01)
except xdrlib.ConversionError as instance:
print 'packing the double failed:', instance.msg
PK
%�\)v���+ �+ - html/_sources/library/xml.dom.minidom.rst.txtnu �[��� :mod:`xml.dom.minidom` --- Minimal DOM implementation
=====================================================
.. module:: xml.dom.minidom
:synopsis: Minimal Document Object Model (DOM) implementation.
.. moduleauthor:: Paul Prescod <paul@prescod.net>
.. sectionauthor:: Paul Prescod <paul@prescod.net>
.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
.. versionadded:: 2.0
**Source code:** :source:`Lib/xml/dom/minidom.py`
--------------
:mod:`xml.dom.minidom` is a minimal implementation of the Document Object
Model interface, with an API similar to that in other languages. It is intended
to be simpler than the full DOM and also significantly smaller. Users who are
not already proficient with the DOM should consider using the
:mod:`xml.etree.ElementTree` module for their XML processing instead.
.. warning::
The :mod:`xml.dom.minidom` module is not secure against
maliciously constructed data. If you need to parse untrusted or
unauthenticated data see :ref:`xml-vulnerabilities`.
DOM applications typically start by parsing some XML into a DOM. With
:mod:`xml.dom.minidom`, this is done through the parse functions::
from xml.dom.minidom import parse, parseString
dom1 = parse('c:\\temp\\mydata.xml') # parse an XML file by name
datasource = open('c:\\temp\\mydata.xml')
dom2 = parse(datasource) # parse an open file
dom3 = parseString('<myxml>Some data<empty/> some more data</myxml>')
The :func:`parse` function can take either a filename or an open file object.
.. function:: parse(filename_or_file[, parser[, bufsize]])
Return a :class:`Document` from the given input. *filename_or_file* may be
either a file name, or a file-like object. *parser*, if given, must be a SAX2
parser object. This function will change the document handler of the parser and
activate namespace support; other parser configuration (like setting an entity
resolver) must have been done in advance.
If you have XML in a string, you can use the :func:`parseString` function
instead:
.. function:: parseString(string[, parser])
Return a :class:`Document` that represents the *string*. This method creates a
:class:`~StringIO.StringIO` object for the string and passes that on to :func:`parse`.
Both functions return a :class:`Document` object representing the content of the
document.
What the :func:`parse` and :func:`parseString` functions do is connect an XML
parser with a "DOM builder" that can accept parse events from any SAX parser and
convert them into a DOM tree. The name of the functions are perhaps misleading,
but are easy to grasp when learning the interfaces. The parsing of the document
will be completed before these functions return; it's simply that these
functions do not provide a parser implementation themselves.
You can also create a :class:`Document` by calling a method on a "DOM
Implementation" object. You can get this object either by calling the
:func:`getDOMImplementation` function in the :mod:`xml.dom` package or the
:mod:`xml.dom.minidom` module. Using the implementation from the
:mod:`xml.dom.minidom` module will always return a :class:`Document` instance
from the minidom implementation, while the version from :mod:`xml.dom` may
provide an alternate implementation (this is likely if you have the `PyXML
package <http://pyxml.sourceforge.net/>`_ installed). Once you have a
:class:`Document`, you can add child nodes to it to populate the DOM::
from xml.dom.minidom import getDOMImplementation
impl = getDOMImplementation()
newdoc = impl.createDocument(None, "some_tag", None)
top_element = newdoc.documentElement
text = newdoc.createTextNode('Some textual content.')
top_element.appendChild(text)
Once you have a DOM document object, you can access the parts of your XML
document through its properties and methods. These properties are defined in
the DOM specification. The main property of the document object is the
:attr:`documentElement` property. It gives you the main element in the XML
document: the one that holds all others. Here is an example program::
dom3 = parseString("<myxml>Some data</myxml>")
assert dom3.documentElement.tagName == "myxml"
When you are finished with a DOM tree, you may optionally call the
:meth:`unlink` method to encourage early cleanup of the now-unneeded
objects. :meth:`unlink` is an :mod:`xml.dom.minidom`\ -specific
extension to the DOM API that renders the node and its descendants are
essentially useless. Otherwise, Python's garbage collector will
eventually take care of the objects in the tree.
.. seealso::
`Document Object Model (DOM) Level 1 Specification <https://www.w3.org/TR/REC-DOM-Level-1/>`_
The W3C recommendation for the DOM supported by :mod:`xml.dom.minidom`.
.. _minidom-objects:
DOM Objects
-----------
The definition of the DOM API for Python is given as part of the :mod:`xml.dom`
module documentation. This section lists the differences between the API and
:mod:`xml.dom.minidom`.
.. method:: Node.unlink()
Break internal references within the DOM so that it will be garbage collected on
versions of Python without cyclic GC. Even when cyclic GC is available, using
this can make large amounts of memory available sooner, so calling this on DOM
objects as soon as they are no longer needed is good practice. This only needs
to be called on the :class:`Document` object, but may be called on child nodes
to discard children of that node.
.. method:: Node.writexml(writer, indent="", addindent="", newl="")
Write XML to the writer object. The writer should have a :meth:`write` method
which matches that of the file object interface. The *indent* parameter is the
indentation of the current node. The *addindent* parameter is the incremental
indentation to use for subnodes of the current one. The *newl* parameter
specifies the string to use to terminate newlines.
For the :class:`Document` node, an additional keyword argument *encoding* can
be used to specify the encoding field of the XML header.
.. versionchanged:: 2.1
The optional keyword parameters *indent*, *addindent*, and *newl* were added to
support pretty output.
.. versionchanged:: 2.3
For the :class:`Document` node, an additional keyword argument
*encoding* can be used to specify the encoding field of the XML header.
.. method:: Node.toxml([encoding])
Return the XML that the DOM represents as a string.
With no argument, the XML header does not specify an encoding, and the result is
Unicode string if the default encoding cannot represent all characters in the
document. Encoding this string in an encoding other than UTF-8 is likely
incorrect, since UTF-8 is the default encoding of XML.
With an explicit *encoding* [1]_ argument, the result is a byte string in the
specified encoding. It is recommended that this argument is always specified. To
avoid :exc:`UnicodeError` exceptions in case of unrepresentable text data, the
encoding argument should be specified as "utf-8".
.. versionchanged:: 2.3
the *encoding* argument was introduced; see :meth:`writexml`.
.. method:: Node.toprettyxml(indent="\\t", newl="\\n", encoding=None)
Return a pretty-printed version of the document. *indent* specifies the
indentation string and defaults to a tabulator; *newl* specifies the string
emitted at the end of each line and defaults to ``\n``.
.. versionadded:: 2.1
.. versionchanged:: 2.3
the encoding argument was introduced; see :meth:`writexml`.
The following standard DOM methods have special considerations with
:mod:`xml.dom.minidom`:
.. method:: Node.cloneNode(deep)
Although this method was present in the version of :mod:`xml.dom.minidom`
packaged with Python 2.0, it was seriously broken. This has been corrected for
subsequent releases.
.. _dom-example:
DOM Example
-----------
This example program is a fairly realistic example of a simple program. In this
particular case, we do not take much advantage of the flexibility of the DOM.
.. literalinclude:: ../includes/minidom-example.py
.. _minidom-and-dom:
minidom and the DOM standard
----------------------------
The :mod:`xml.dom.minidom` module is essentially a DOM 1.0-compatible DOM with
some DOM 2 features (primarily namespace features).
Usage of the DOM interface in Python is straight-forward. The following mapping
rules apply:
* Interfaces are accessed through instance objects. Applications should not
instantiate the classes themselves; they should use the creator functions
available on the :class:`Document` object. Derived interfaces support all
operations (and attributes) from the base interfaces, plus any new operations.
* Operations are used as methods. Since the DOM uses only :keyword:`in`
parameters, the arguments are passed in normal order (from left to right).
There are no optional arguments. ``void`` operations return ``None``.
* IDL attributes map to instance attributes. For compatibility with the OMG IDL
language mapping for Python, an attribute ``foo`` can also be accessed through
accessor methods :meth:`_get_foo` and :meth:`_set_foo`. ``readonly``
attributes must not be changed; this is not enforced at runtime.
* The types ``short int``, ``unsigned int``, ``unsigned long long``, and
``boolean`` all map to Python integer objects.
* The type ``DOMString`` maps to Python strings. :mod:`xml.dom.minidom` supports
either byte or Unicode strings, but will normally produce Unicode strings.
Values of type ``DOMString`` may also be ``None`` where allowed to have the IDL
``null`` value by the DOM specification from the W3C.
* ``const`` declarations map to variables in their respective scope (e.g.
``xml.dom.minidom.Node.PROCESSING_INSTRUCTION_NODE``); they must not be changed.
* ``DOMException`` is currently not supported in :mod:`xml.dom.minidom`.
Instead, :mod:`xml.dom.minidom` uses standard Python exceptions such as
:exc:`TypeError` and :exc:`AttributeError`.
* :class:`NodeList` objects are implemented using Python's built-in list type.
Starting with Python 2.2, these objects provide the interface defined in the DOM
specification, but with earlier versions of Python they do not support the
official API. They are, however, much more "Pythonic" than the interface
defined in the W3C recommendations.
The following interfaces have no implementation in :mod:`xml.dom.minidom`:
* :class:`DOMTimeStamp`
* :class:`DocumentType` (added in Python 2.1)
* :class:`DOMImplementation` (added in Python 2.1)
* :class:`CharacterData`
* :class:`CDATASection`
* :class:`Notation`
* :class:`Entity`
* :class:`EntityReference`
* :class:`DocumentFragment`
Most of these reflect information in the XML document that is not of general
utility to most DOM users.
.. rubric:: Footnotes
.. [1] The encoding string included in XML output should conform to the
appropriate standards. For example, "UTF-8" is valid, but "UTF8" is
not. See https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl
and https://www.iana.org/assignments/character-sets/character-sets.xhtml.
PK
%�\��# # - html/_sources/library/xml.dom.pulldom.rst.txtnu �[��� :mod:`xml.dom.pulldom` --- Support for building partial DOM trees
=================================================================
.. module:: xml.dom.pulldom
:synopsis: Support for building partial DOM trees from SAX events.
.. moduleauthor:: Paul Prescod <paul@prescod.net>
.. versionadded:: 2.0
**Source code:** :source:`Lib/xml/dom/pulldom.py`
--------------
:mod:`xml.dom.pulldom` allows building only selected portions of a Document
Object Model representation of a document from SAX events.
.. warning::
The :mod:`xml.dom.pulldom` module is not secure against
maliciously constructed data. If you need to parse untrusted or
unauthenticated data see :ref:`xml-vulnerabilities`.
.. class:: PullDOM([documentFactory])
:class:`xml.sax.handler.ContentHandler` implementation that ...
.. class:: DOMEventStream(stream, parser, bufsize)
...
.. class:: SAX2DOM([documentFactory])
:class:`xml.sax.handler.ContentHandler` implementation that ...
.. function:: parse(stream_or_string[, parser[, bufsize]])
...
.. function:: parseString(string[, parser])
...
.. data:: default_bufsize
Default value for the *bufsize* parameter to :func:`parse`.
.. versionchanged:: 2.1
The value of this variable can be changed before calling :func:`parse` and the
new value will take effect.
.. _domeventstream-objects:
DOMEventStream Objects
----------------------
.. method:: DOMEventStream.getEvent()
...
.. method:: DOMEventStream.expandNode(node)
...
.. method:: DOMEventStream.reset()
...
PK
%�\ծ�� �� % html/_sources/library/xml.dom.rst.txtnu �[���
:mod:`xml.dom` --- The Document Object Model API
================================================
.. module:: xml.dom
:synopsis: Document Object Model API for Python.
.. sectionauthor:: Paul Prescod <paul@prescod.net>
.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
.. versionadded:: 2.0
The Document Object Model, or "DOM," is a cross-language API from the World Wide
Web Consortium (W3C) for accessing and modifying XML documents. A DOM
implementation presents an XML document as a tree structure, or allows client
code to build such a structure from scratch. It then gives access to the
structure through a set of objects which provided well-known interfaces.
The DOM is extremely useful for random-access applications. SAX only allows you
a view of one bit of the document at a time. If you are looking at one SAX
element, you have no access to another. If you are looking at a text node, you
have no access to a containing element. When you write a SAX application, you
need to keep track of your program's position in the document somewhere in your
own code. SAX does not do it for you. Also, if you need to look ahead in the
XML document, you are just out of luck.
Some applications are simply impossible in an event driven model with no access
to a tree. Of course you could build some sort of tree yourself in SAX events,
but the DOM allows you to avoid writing that code. The DOM is a standard tree
representation for XML data.
The Document Object Model is being defined by the W3C in stages, or "levels" in
their terminology. The Python mapping of the API is substantially based on the
DOM Level 2 recommendation.
.. XXX PyXML is dead...
.. The mapping of the Level 3 specification, currently
only available in draft form, is being developed by the `Python XML Special
Interest Group <https://www.python.org/sigs/xml-sig/>`_ as part of the `PyXML
package <http://pyxml.sourceforge.net/>`_. Refer to the documentation bundled
with that package for information on the current state of DOM Level 3 support.
.. What if your needs are somewhere between SAX and the DOM? Perhaps
you cannot afford to load the entire tree in memory but you find the
SAX model somewhat cumbersome and low-level. There is also a module
called xml.dom.pulldom that allows you to build trees of only the
parts of a document that you need structured access to. It also has
features that allow you to find your way around the DOM.
See http://www.prescod.net/python/pulldom
DOM applications typically start by parsing some XML into a DOM. How this is
accomplished is not covered at all by DOM Level 1, and Level 2 provides only
limited improvements: There is a :class:`DOMImplementation` object class which
provides access to :class:`Document` creation methods, but no way to access an
XML reader/parser/Document builder in an implementation-independent way. There
is also no well-defined way to access these methods without an existing
:class:`Document` object. In Python, each DOM implementation will provide a
function :func:`getDOMImplementation`. DOM Level 3 adds a Load/Store
specification, which defines an interface to the reader, but this is not yet
available in the Python standard library.
Once you have a DOM document object, you can access the parts of your XML
document through its properties and methods. These properties are defined in
the DOM specification; this portion of the reference manual describes the
interpretation of the specification in Python.
The specification provided by the W3C defines the DOM API for Java, ECMAScript,
and OMG IDL. The Python mapping defined here is based in large part on the IDL
version of the specification, but strict compliance is not required (though
implementations are free to support the strict mapping from IDL). See section
:ref:`dom-conformance` for a detailed discussion of mapping requirements.
.. seealso::
`Document Object Model (DOM) Level 2 Specification <https://www.w3.org/TR/DOM-Level-2-Core/>`_
The W3C recommendation upon which the Python DOM API is based.
`Document Object Model (DOM) Level 1 Specification <https://www.w3.org/TR/REC-DOM-Level-1/>`_
The W3C recommendation for the DOM supported by :mod:`xml.dom.minidom`.
`Python Language Mapping Specification <http://www.omg.org/spec/PYTH/1.2/PDF>`_
This specifies the mapping from OMG IDL to Python.
Module Contents
---------------
The :mod:`xml.dom` contains the following functions:
.. function:: registerDOMImplementation(name, factory)
Register the *factory* function with the name *name*. The factory function
should return an object which implements the :class:`DOMImplementation`
interface. The factory function can return the same object every time, or a new
one for each call, as appropriate for the specific implementation (e.g. if that
implementation supports some customization).
.. function:: getDOMImplementation([name[, features]])
Return a suitable DOM implementation. The *name* is either well-known, the
module name of a DOM implementation, or ``None``. If it is not ``None``, imports
the corresponding module and returns a :class:`DOMImplementation` object if the
import succeeds. If no name is given, and if the environment variable
:envvar:`PYTHON_DOM` is set, this variable is used to find the implementation.
If name is not given, this examines the available implementations to find one
with the required feature set. If no implementation can be found, raise an
:exc:`ImportError`. The features list must be a sequence of ``(feature,
version)`` pairs which are passed to the :meth:`hasFeature` method on available
:class:`DOMImplementation` objects.
Some convenience constants are also provided:
.. data:: EMPTY_NAMESPACE
The value used to indicate that no namespace is associated with a node in the
DOM. This is typically found as the :attr:`namespaceURI` of a node, or used as
the *namespaceURI* parameter to a namespaces-specific method.
.. versionadded:: 2.2
.. data:: XML_NAMESPACE
The namespace URI associated with the reserved prefix ``xml``, as defined by
`Namespaces in XML <https://www.w3.org/TR/REC-xml-names/>`_ (section 4).
.. versionadded:: 2.2
.. data:: XMLNS_NAMESPACE
The namespace URI for namespace declarations, as defined by `Document Object
Model (DOM) Level 2 Core Specification
<https://www.w3.org/TR/DOM-Level-2-Core/core.html>`_ (section 1.1.8).
.. versionadded:: 2.2
.. data:: XHTML_NAMESPACE
The URI of the XHTML namespace as defined by `XHTML 1.0: The Extensible
HyperText Markup Language <https://www.w3.org/TR/xhtml1/>`_ (section 3.1.1).
.. versionadded:: 2.2
In addition, :mod:`xml.dom` contains a base :class:`Node` class and the DOM
exception classes. The :class:`Node` class provided by this module does not
implement any of the methods or attributes defined by the DOM specification;
concrete DOM implementations must provide those. The :class:`Node` class
provided as part of this module does provide the constants used for the
:attr:`nodeType` attribute on concrete :class:`Node` objects; they are located
within the class rather than at the module level to conform with the DOM
specifications.
.. Should the Node documentation go here?
.. _dom-objects:
Objects in the DOM
------------------
The definitive documentation for the DOM is the DOM specification from the W3C.
Note that DOM attributes may also be manipulated as nodes instead of as simple
strings. It is fairly rare that you must do this, however, so this usage is not
yet documented.
+--------------------------------+-----------------------------------+---------------------------------+
| Interface | Section | Purpose |
+================================+===================================+=================================+
| :class:`DOMImplementation` | :ref:`dom-implementation-objects` | Interface to the underlying |
| | | implementation. |
+--------------------------------+-----------------------------------+---------------------------------+
| :class:`Node` | :ref:`dom-node-objects` | Base interface for most objects |
| | | in a document. |
+--------------------------------+-----------------------------------+---------------------------------+
| :class:`NodeList` | :ref:`dom-nodelist-objects` | Interface for a sequence of |
| | | nodes. |
+--------------------------------+-----------------------------------+---------------------------------+
| :class:`DocumentType` | :ref:`dom-documenttype-objects` | Information about the |
| | | declarations needed to process |
| | | a document. |
+--------------------------------+-----------------------------------+---------------------------------+
| :class:`Document` | :ref:`dom-document-objects` | Object which represents an |
| | | entire document. |
+--------------------------------+-----------------------------------+---------------------------------+
| :class:`Element` | :ref:`dom-element-objects` | Element nodes in the document |
| | | hierarchy. |
+--------------------------------+-----------------------------------+---------------------------------+
| :class:`Attr` | :ref:`dom-attr-objects` | Attribute value nodes on |
| | | element nodes. |
+--------------------------------+-----------------------------------+---------------------------------+
| :class:`Comment` | :ref:`dom-comment-objects` | Representation of comments in |
| | | the source document. |
+--------------------------------+-----------------------------------+---------------------------------+
| :class:`Text` | :ref:`dom-text-objects` | Nodes containing textual |
| | | content from the document. |
+--------------------------------+-----------------------------------+---------------------------------+
| :class:`ProcessingInstruction` | :ref:`dom-pi-objects` | Processing instruction |
| | | representation. |
+--------------------------------+-----------------------------------+---------------------------------+
An additional section describes the exceptions defined for working with the DOM
in Python.
.. _dom-implementation-objects:
DOMImplementation Objects
^^^^^^^^^^^^^^^^^^^^^^^^^
The :class:`DOMImplementation` interface provides a way for applications to
determine the availability of particular features in the DOM they are using.
DOM Level 2 added the ability to create new :class:`Document` and
:class:`DocumentType` objects using the :class:`DOMImplementation` as well.
.. method:: DOMImplementation.hasFeature(feature, version)
Return true if the feature identified by the pair of strings *feature* and
*version* is implemented.
.. method:: DOMImplementation.createDocument(namespaceUri, qualifiedName, doctype)
Return a new :class:`Document` object (the root of the DOM), with a child
:class:`Element` object having the given *namespaceUri* and *qualifiedName*. The
*doctype* must be a :class:`DocumentType` object created by
:meth:`createDocumentType`, or ``None``. In the Python DOM API, the first two
arguments can also be ``None`` in order to indicate that no :class:`Element`
child is to be created.
.. method:: DOMImplementation.createDocumentType(qualifiedName, publicId, systemId)
Return a new :class:`DocumentType` object that encapsulates the given
*qualifiedName*, *publicId*, and *systemId* strings, representing the
information contained in an XML document type declaration.
.. _dom-node-objects:
Node Objects
^^^^^^^^^^^^
All of the components of an XML document are subclasses of :class:`Node`.
.. attribute:: Node.nodeType
An integer representing the node type. Symbolic constants for the types are on
the :class:`Node` object: :const:`ELEMENT_NODE`, :const:`ATTRIBUTE_NODE`,
:const:`TEXT_NODE`, :const:`CDATA_SECTION_NODE`, :const:`ENTITY_NODE`,
:const:`PROCESSING_INSTRUCTION_NODE`, :const:`COMMENT_NODE`,
:const:`DOCUMENT_NODE`, :const:`DOCUMENT_TYPE_NODE`, :const:`NOTATION_NODE`.
This is a read-only attribute.
.. attribute:: Node.parentNode
The parent of the current node, or ``None`` for the document node. The value is
always a :class:`Node` object or ``None``. For :class:`Element` nodes, this
will be the parent element, except for the root element, in which case it will
be the :class:`Document` object. For :class:`Attr` nodes, this is always
``None``. This is a read-only attribute.
.. attribute:: Node.attributes
A :class:`NamedNodeMap` of attribute objects. Only elements have actual values
for this; others provide ``None`` for this attribute. This is a read-only
attribute.
.. attribute:: Node.previousSibling
The node that immediately precedes this one with the same parent. For
instance the element with an end-tag that comes just before the *self*
element's start-tag. Of course, XML documents are made up of more than just
elements so the previous sibling could be text, a comment, or something else.
If this node is the first child of the parent, this attribute will be
``None``. This is a read-only attribute.
.. attribute:: Node.nextSibling
The node that immediately follows this one with the same parent. See also
:attr:`previousSibling`. If this is the last child of the parent, this
attribute will be ``None``. This is a read-only attribute.
.. attribute:: Node.childNodes
A list of nodes contained within this node. This is a read-only attribute.
.. attribute:: Node.firstChild
The first child of the node, if there are any, or ``None``. This is a read-only
attribute.
.. attribute:: Node.lastChild
The last child of the node, if there are any, or ``None``. This is a read-only
attribute.
.. attribute:: Node.localName
The part of the :attr:`tagName` following the colon if there is one, else the
entire :attr:`tagName`. The value is a string.
.. attribute:: Node.prefix
The part of the :attr:`tagName` preceding the colon if there is one, else the
empty string. The value is a string, or ``None``.
.. attribute:: Node.namespaceURI
The namespace associated with the element name. This will be a string or
``None``. This is a read-only attribute.
.. attribute:: Node.nodeName
This has a different meaning for each node type; see the DOM specification for
details. You can always get the information you would get here from another
property such as the :attr:`tagName` property for elements or the :attr:`name`
property for attributes. For all node types, the value of this attribute will be
either a string or ``None``. This is a read-only attribute.
.. attribute:: Node.nodeValue
This has a different meaning for each node type; see the DOM specification for
details. The situation is similar to that with :attr:`nodeName`. The value is
a string or ``None``.
.. method:: Node.hasAttributes()
Returns true if the node has any attributes.
.. method:: Node.hasChildNodes()
Returns true if the node has any child nodes.
.. method:: Node.isSameNode(other)
Returns true if *other* refers to the same node as this node. This is especially
useful for DOM implementations which use any sort of proxy architecture (because
more than one object can refer to the same node).
.. note::
This is based on a proposed DOM Level 3 API which is still in the "working
draft" stage, but this particular interface appears uncontroversial. Changes
from the W3C will not necessarily affect this method in the Python DOM interface
(though any new W3C API for this would also be supported).
.. method:: Node.appendChild(newChild)
Add a new child node to this node at the end of the list of
children, returning *newChild*. If the node was already in
the tree, it is removed first.
.. method:: Node.insertBefore(newChild, refChild)
Insert a new child node before an existing child. It must be the case that
*refChild* is a child of this node; if not, :exc:`ValueError` is raised.
*newChild* is returned. If *refChild* is ``None``, it inserts *newChild* at the
end of the children's list.
.. method:: Node.removeChild(oldChild)
Remove a child node. *oldChild* must be a child of this node; if not,
:exc:`ValueError` is raised. *oldChild* is returned on success. If *oldChild*
will not be used further, its :meth:`unlink` method should be called.
.. method:: Node.replaceChild(newChild, oldChild)
Replace an existing node with a new node. It must be the case that *oldChild*
is a child of this node; if not, :exc:`ValueError` is raised.
.. method:: Node.normalize()
Join adjacent text nodes so that all stretches of text are stored as single
:class:`Text` instances. This simplifies processing text from a DOM tree for
many applications.
.. versionadded:: 2.1
.. method:: Node.cloneNode(deep)
Clone this node. Setting *deep* means to clone all child nodes as well. This
returns the clone.
.. _dom-nodelist-objects:
NodeList Objects
^^^^^^^^^^^^^^^^
A :class:`NodeList` represents a sequence of nodes. These objects are used in
two ways in the DOM Core recommendation: an :class:`Element` object provides
one as its list of child nodes, and the :meth:`getElementsByTagName` and
:meth:`getElementsByTagNameNS` methods of :class:`Node` return objects with this
interface to represent query results.
The DOM Level 2 recommendation defines one method and one attribute for these
objects:
.. method:: NodeList.item(i)
Return the *i*'th item from the sequence, if there is one, or ``None``. The
index *i* is not allowed to be less than zero or greater than or equal to the
length of the sequence.
.. attribute:: NodeList.length
The number of nodes in the sequence.
In addition, the Python DOM interface requires that some additional support is
provided to allow :class:`NodeList` objects to be used as Python sequences. All
:class:`NodeList` implementations must include support for
:meth:`~object.__len__` and
:meth:`~object.__getitem__`; this allows iteration over the :class:`NodeList` in
:keyword:`for` statements and proper support for the :func:`len` built-in
function.
If a DOM implementation supports modification of the document, the
:class:`NodeList` implementation must also support the
:meth:`~object.__setitem__` and :meth:`~object.__delitem__` methods.
.. _dom-documenttype-objects:
DocumentType Objects
^^^^^^^^^^^^^^^^^^^^
Information about the notations and entities declared by a document (including
the external subset if the parser uses it and can provide the information) is
available from a :class:`DocumentType` object. The :class:`DocumentType` for a
document is available from the :class:`Document` object's :attr:`doctype`
attribute; if there is no ``DOCTYPE`` declaration for the document, the
document's :attr:`doctype` attribute will be set to ``None`` instead of an
instance of this interface.
:class:`DocumentType` is a specialization of :class:`Node`, and adds the
following attributes:
.. attribute:: DocumentType.publicId
The public identifier for the external subset of the document type definition.
This will be a string or ``None``.
.. attribute:: DocumentType.systemId
The system identifier for the external subset of the document type definition.
This will be a URI as a string, or ``None``.
.. attribute:: DocumentType.internalSubset
A string giving the complete internal subset from the document. This does not
include the brackets which enclose the subset. If the document has no internal
subset, this should be ``None``.
.. attribute:: DocumentType.name
The name of the root element as given in the ``DOCTYPE`` declaration, if
present.
.. attribute:: DocumentType.entities
This is a :class:`NamedNodeMap` giving the definitions of external entities.
For entity names defined more than once, only the first definition is provided
(others are ignored as required by the XML recommendation). This may be
``None`` if the information is not provided by the parser, or if no entities are
defined.
.. attribute:: DocumentType.notations
This is a :class:`NamedNodeMap` giving the definitions of notations. For
notation names defined more than once, only the first definition is provided
(others are ignored as required by the XML recommendation). This may be
``None`` if the information is not provided by the parser, or if no notations
are defined.
.. _dom-document-objects:
Document Objects
^^^^^^^^^^^^^^^^
A :class:`Document` represents an entire XML document, including its constituent
elements, attributes, processing instructions, comments etc. Remember that it
inherits properties from :class:`Node`.
.. attribute:: Document.documentElement
The one and only root element of the document.
.. method:: Document.createElement(tagName)
Create and return a new element node. The element is not inserted into the
document when it is created. You need to explicitly insert it with one of the
other methods such as :meth:`insertBefore` or :meth:`appendChild`.
.. method:: Document.createElementNS(namespaceURI, tagName)
Create and return a new element with a namespace. The *tagName* may have a
prefix. The element is not inserted into the document when it is created. You
need to explicitly insert it with one of the other methods such as
:meth:`insertBefore` or :meth:`appendChild`.
.. method:: Document.createTextNode(data)
Create and return a text node containing the data passed as a parameter. As
with the other creation methods, this one does not insert the node into the
tree.
.. method:: Document.createComment(data)
Create and return a comment node containing the data passed as a parameter. As
with the other creation methods, this one does not insert the node into the
tree.
.. method:: Document.createProcessingInstruction(target, data)
Create and return a processing instruction node containing the *target* and
*data* passed as parameters. As with the other creation methods, this one does
not insert the node into the tree.
.. method:: Document.createAttribute(name)
Create and return an attribute node. This method does not associate the
attribute node with any particular element. You must use
:meth:`setAttributeNode` on the appropriate :class:`Element` object to use the
newly created attribute instance.
.. method:: Document.createAttributeNS(namespaceURI, qualifiedName)
Create and return an attribute node with a namespace. The *tagName* may have a
prefix. This method does not associate the attribute node with any particular
element. You must use :meth:`setAttributeNode` on the appropriate
:class:`Element` object to use the newly created attribute instance.
.. method:: Document.getElementsByTagName(tagName)
Search for all descendants (direct children, children's children, etc.) with a
particular element type name.
.. method:: Document.getElementsByTagNameNS(namespaceURI, localName)
Search for all descendants (direct children, children's children, etc.) with a
particular namespace URI and localname. The localname is the part of the
namespace after the prefix.
.. _dom-element-objects:
Element Objects
^^^^^^^^^^^^^^^
:class:`Element` is a subclass of :class:`Node`, so inherits all the attributes
of that class.
.. attribute:: Element.tagName
The element type name. In a namespace-using document it may have colons in it.
The value is a string.
.. method:: Element.getElementsByTagName(tagName)
Same as equivalent method in the :class:`Document` class.
.. method:: Element.getElementsByTagNameNS(namespaceURI, localName)
Same as equivalent method in the :class:`Document` class.
.. method:: Element.hasAttribute(name)
Returns true if the element has an attribute named by *name*.
.. method:: Element.hasAttributeNS(namespaceURI, localName)
Returns true if the element has an attribute named by *namespaceURI* and
*localName*.
.. method:: Element.getAttribute(name)
Return the value of the attribute named by *name* as a string. If no such
attribute exists, an empty string is returned, as if the attribute had no value.
.. method:: Element.getAttributeNode(attrname)
Return the :class:`Attr` node for the attribute named by *attrname*.
.. method:: Element.getAttributeNS(namespaceURI, localName)
Return the value of the attribute named by *namespaceURI* and *localName* as a
string. If no such attribute exists, an empty string is returned, as if the
attribute had no value.
.. method:: Element.getAttributeNodeNS(namespaceURI, localName)
Return an attribute value as a node, given a *namespaceURI* and *localName*.
.. method:: Element.removeAttribute(name)
Remove an attribute by name. If there is no matching attribute, a
:exc:`NotFoundErr` is raised.
.. method:: Element.removeAttributeNode(oldAttr)
Remove and return *oldAttr* from the attribute list, if present. If *oldAttr* is
not present, :exc:`NotFoundErr` is raised.
.. method:: Element.removeAttributeNS(namespaceURI, localName)
Remove an attribute by name. Note that it uses a localName, not a qname. No
exception is raised if there is no matching attribute.
.. method:: Element.setAttribute(name, value)
Set an attribute value from a string.
.. method:: Element.setAttributeNode(newAttr)
Add a new attribute node to the element, replacing an existing attribute if
necessary if the :attr:`name` attribute matches. If a replacement occurs, the
old attribute node will be returned. If *newAttr* is already in use,
:exc:`InuseAttributeErr` will be raised.
.. method:: Element.setAttributeNodeNS(newAttr)
Add a new attribute node to the element, replacing an existing attribute if
necessary if the :attr:`namespaceURI` and :attr:`localName` attributes match.
If a replacement occurs, the old attribute node will be returned. If *newAttr*
is already in use, :exc:`InuseAttributeErr` will be raised.
.. method:: Element.setAttributeNS(namespaceURI, qname, value)
Set an attribute value from a string, given a *namespaceURI* and a *qname*.
Note that a qname is the whole attribute name. This is different than above.
.. _dom-attr-objects:
Attr Objects
^^^^^^^^^^^^
:class:`Attr` inherits from :class:`Node`, so inherits all its attributes.
.. attribute:: Attr.name
The attribute name.
In a namespace-using document it may include a colon.
.. attribute:: Attr.localName
The part of the name following the colon if there is one, else the
entire name.
This is a read-only attribute.
.. attribute:: Attr.prefix
The part of the name preceding the colon if there is one, else the
empty string.
.. attribute:: Attr.value
The text value of the attribute. This is a synonym for the
:attr:`nodeValue` attribute.
.. _dom-attributelist-objects:
NamedNodeMap Objects
^^^^^^^^^^^^^^^^^^^^
:class:`NamedNodeMap` does *not* inherit from :class:`Node`.
.. attribute:: NamedNodeMap.length
The length of the attribute list.
.. method:: NamedNodeMap.item(index)
Return an attribute with a particular index. The order you get the attributes
in is arbitrary but will be consistent for the life of a DOM. Each item is an
attribute node. Get its value with the :attr:`value` attribute.
There are also experimental methods that give this class more mapping behavior.
You can use them or you can use the standardized :meth:`getAttribute\*` family
of methods on the :class:`Element` objects.
.. _dom-comment-objects:
Comment Objects
^^^^^^^^^^^^^^^
:class:`Comment` represents a comment in the XML document. It is a subclass of
:class:`Node`, but cannot have child nodes.
.. attribute:: Comment.data
The content of the comment as a string. The attribute contains all characters
between the leading ``<!-``\ ``-`` and trailing ``-``\ ``->``, but does not
include them.
.. _dom-text-objects:
Text and CDATASection Objects
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The :class:`Text` interface represents text in the XML document. If the parser
and DOM implementation support the DOM's XML extension, portions of the text
enclosed in CDATA marked sections are stored in :class:`CDATASection` objects.
These two interfaces are identical, but provide different values for the
:attr:`nodeType` attribute.
These interfaces extend the :class:`Node` interface. They cannot have child
nodes.
.. attribute:: Text.data
The content of the text node as a string.
.. note::
The use of a :class:`CDATASection` node does not indicate that the node
represents a complete CDATA marked section, only that the content of the node
was part of a CDATA section. A single CDATA section may be represented by more
than one node in the document tree. There is no way to determine whether two
adjacent :class:`CDATASection` nodes represent different CDATA marked sections.
.. _dom-pi-objects:
ProcessingInstruction Objects
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Represents a processing instruction in the XML document; this inherits from the
:class:`Node` interface and cannot have child nodes.
.. attribute:: ProcessingInstruction.target
The content of the processing instruction up to the first whitespace character.
This is a read-only attribute.
.. attribute:: ProcessingInstruction.data
The content of the processing instruction following the first whitespace
character.
.. _dom-exceptions:
Exceptions
^^^^^^^^^^
.. versionadded:: 2.1
The DOM Level 2 recommendation defines a single exception, :exc:`DOMException`,
and a number of constants that allow applications to determine what sort of
error occurred. :exc:`DOMException` instances carry a :attr:`code` attribute
that provides the appropriate value for the specific exception.
The Python DOM interface provides the constants, but also expands the set of
exceptions so that a specific exception exists for each of the exception codes
defined by the DOM. The implementations must raise the appropriate specific
exception, each of which carries the appropriate value for the :attr:`code`
attribute.
.. exception:: DOMException
Base exception class used for all specific DOM exceptions. This exception class
cannot be directly instantiated.
.. exception:: DomstringSizeErr
Raised when a specified range of text does not fit into a string. This is not
known to be used in the Python DOM implementations, but may be received from DOM
implementations not written in Python.
.. exception:: HierarchyRequestErr
Raised when an attempt is made to insert a node where the node type is not
allowed.
.. exception:: IndexSizeErr
Raised when an index or size parameter to a method is negative or exceeds the
allowed values.
.. exception:: InuseAttributeErr
Raised when an attempt is made to insert an :class:`Attr` node that is already
present elsewhere in the document.
.. exception:: InvalidAccessErr
Raised if a parameter or an operation is not supported on the underlying object.
.. exception:: InvalidCharacterErr
This exception is raised when a string parameter contains a character that is
not permitted in the context it's being used in by the XML 1.0 recommendation.
For example, attempting to create an :class:`Element` node with a space in the
element type name will cause this error to be raised.
.. exception:: InvalidModificationErr
Raised when an attempt is made to modify the type of a node.
.. exception:: InvalidStateErr
Raised when an attempt is made to use an object that is not defined or is no
longer usable.
.. exception:: NamespaceErr
If an attempt is made to change any object in a way that is not permitted with
regard to the `Namespaces in XML <https://www.w3.org/TR/REC-xml-names/>`_
recommendation, this exception is raised.
.. exception:: NotFoundErr
Exception when a node does not exist in the referenced context. For example,
:meth:`NamedNodeMap.removeNamedItem` will raise this if the node passed in does
not exist in the map.
.. exception:: NotSupportedErr
Raised when the implementation does not support the requested type of object or
operation.
.. exception:: NoDataAllowedErr
This is raised if data is specified for a node which does not support data.
.. XXX a better explanation is needed!
.. exception:: NoModificationAllowedErr
Raised on attempts to modify an object where modifications are not allowed (such
as for read-only nodes).
.. exception:: SyntaxErr
Raised when an invalid or illegal string is specified.
.. XXX how is this different from InvalidCharacterErr?
.. exception:: WrongDocumentErr
Raised when a node is inserted in a different document than it currently belongs
to, and the implementation does not support migrating the node from one document
to the other.
The exception codes defined in the DOM recommendation map to the exceptions
described above according to this table:
+--------------------------------------+---------------------------------+
| Constant | Exception |
+======================================+=================================+
| :const:`DOMSTRING_SIZE_ERR` | :exc:`DomstringSizeErr` |
+--------------------------------------+---------------------------------+
| :const:`HIERARCHY_REQUEST_ERR` | :exc:`HierarchyRequestErr` |
+--------------------------------------+---------------------------------+
| :const:`INDEX_SIZE_ERR` | :exc:`IndexSizeErr` |
+--------------------------------------+---------------------------------+
| :const:`INUSE_ATTRIBUTE_ERR` | :exc:`InuseAttributeErr` |
+--------------------------------------+---------------------------------+
| :const:`INVALID_ACCESS_ERR` | :exc:`InvalidAccessErr` |
+--------------------------------------+---------------------------------+
| :const:`INVALID_CHARACTER_ERR` | :exc:`InvalidCharacterErr` |
+--------------------------------------+---------------------------------+
| :const:`INVALID_MODIFICATION_ERR` | :exc:`InvalidModificationErr` |
+--------------------------------------+---------------------------------+
| :const:`INVALID_STATE_ERR` | :exc:`InvalidStateErr` |
+--------------------------------------+---------------------------------+
| :const:`NAMESPACE_ERR` | :exc:`NamespaceErr` |
+--------------------------------------+---------------------------------+
| :const:`NOT_FOUND_ERR` | :exc:`NotFoundErr` |
+--------------------------------------+---------------------------------+
| :const:`NOT_SUPPORTED_ERR` | :exc:`NotSupportedErr` |
+--------------------------------------+---------------------------------+
| :const:`NO_DATA_ALLOWED_ERR` | :exc:`NoDataAllowedErr` |
+--------------------------------------+---------------------------------+
| :const:`NO_MODIFICATION_ALLOWED_ERR` | :exc:`NoModificationAllowedErr` |
+--------------------------------------+---------------------------------+
| :const:`SYNTAX_ERR` | :exc:`SyntaxErr` |
+--------------------------------------+---------------------------------+
| :const:`WRONG_DOCUMENT_ERR` | :exc:`WrongDocumentErr` |
+--------------------------------------+---------------------------------+
.. _dom-conformance:
Conformance
-----------
This section describes the conformance requirements and relationships between
the Python DOM API, the W3C DOM recommendations, and the OMG IDL mapping for
Python.
.. _dom-type-mapping:
Type Mapping
^^^^^^^^^^^^
The primitive IDL types used in the DOM specification are mapped to Python types
according to the following table.
+------------------+-------------------------------------------+
| IDL Type | Python Type |
+==================+===========================================+
| ``boolean`` | ``IntegerType`` (with a value of ``0`` or |
| | ``1``) |
+------------------+-------------------------------------------+
| ``int`` | ``IntegerType`` |
+------------------+-------------------------------------------+
| ``long int`` | ``IntegerType`` |
+------------------+-------------------------------------------+
| ``unsigned int`` | ``IntegerType`` |
+------------------+-------------------------------------------+
Additionally, the :class:`DOMString` defined in the recommendation is mapped to
a Python string or Unicode string. Applications should be able to handle
Unicode whenever a string is returned from the DOM.
The IDL ``null`` value is mapped to ``None``, which may be accepted or
provided by the implementation whenever ``null`` is allowed by the API.
.. _dom-accessor-methods:
Accessor Methods
^^^^^^^^^^^^^^^^
The mapping from OMG IDL to Python defines accessor functions for IDL
``attribute`` declarations in much the way the Java mapping does.
Mapping the IDL declarations ::
readonly attribute string someValue;
attribute string anotherValue;
yields three accessor functions: a "get" method for :attr:`someValue`
(:meth:`_get_someValue`), and "get" and "set" methods for :attr:`anotherValue`
(:meth:`_get_anotherValue` and :meth:`_set_anotherValue`). The mapping, in
particular, does not require that the IDL attributes are accessible as normal
Python attributes: ``object.someValue`` is *not* required to work, and may
raise an :exc:`AttributeError`.
The Python DOM API, however, *does* require that normal attribute access work.
This means that the typical surrogates generated by Python IDL compilers are not
likely to work, and wrapper objects may be needed on the client if the DOM
objects are accessed via CORBA. While this does require some additional
consideration for CORBA DOM clients, the implementers with experience using DOM
over CORBA from Python do not consider this a problem. Attributes that are
declared ``readonly`` may not restrict write access in all DOM
implementations.
In the Python DOM API, accessor functions are not required. If provided, they
should take the form defined by the Python IDL mapping, but these methods are
considered unnecessary since the attributes are accessible directly from Python.
"Set" accessors should never be provided for ``readonly`` attributes.
The IDL definitions do not fully embody the requirements of the W3C DOM API,
such as the notion of certain objects, such as the return value of
:meth:`getElementsByTagName`, being "live". The Python DOM API does not require
implementations to enforce such requirements.
PK
%�\b�~�{� {� 3 html/_sources/library/xml.etree.elementtree.rst.txtnu �[��� :mod:`xml.etree.ElementTree` --- The ElementTree XML API
========================================================
.. module:: xml.etree.ElementTree
:synopsis: Implementation of the ElementTree API.
.. moduleauthor:: Fredrik Lundh <fredrik@pythonware.com>
.. versionadded:: 2.5
**Source code:** :source:`Lib/xml/etree/ElementTree.py`
--------------
The :class:`Element` type is a flexible container object, designed to store
hierarchical data structures in memory. The type can be described as a cross
between a list and a dictionary.
.. warning::
The :mod:`xml.etree.ElementTree` module is not secure against
maliciously constructed data. If you need to parse untrusted or
unauthenticated data see :ref:`xml-vulnerabilities`.
Each element has a number of properties associated with it:
* a tag which is a string identifying what kind of data this element represents
(the element type, in other words).
* a number of attributes, stored in a Python dictionary.
* a text string.
* an optional tail string.
* a number of child elements, stored in a Python sequence
To create an element instance, use the :class:`Element` constructor or the
:func:`SubElement` factory function.
The :class:`ElementTree` class can be used to wrap an element structure, and
convert it from and to XML.
A C implementation of this API is available as :mod:`xml.etree.cElementTree`.
See http://effbot.org/zone/element-index.htm for tutorials and links to other
docs. Fredrik Lundh's page is also the location of the development version of
the xml.etree.ElementTree.
.. versionchanged:: 2.7
The ElementTree API is updated to 1.3. For more information, see
`Introducing ElementTree 1.3
<http://effbot.org/zone/elementtree-13-intro.htm>`_.
Tutorial
--------
This is a short tutorial for using :mod:`xml.etree.ElementTree` (``ET`` in
short). The goal is to demonstrate some of the building blocks and basic
concepts of the module.
XML tree and elements
^^^^^^^^^^^^^^^^^^^^^
XML is an inherently hierarchical data format, and the most natural way to
represent it is with a tree. ``ET`` has two classes for this purpose -
:class:`ElementTree` represents the whole XML document as a tree, and
:class:`Element` represents a single node in this tree. Interactions with
the whole document (reading and writing to/from files) are usually done
on the :class:`ElementTree` level. Interactions with a single XML element
and its sub-elements are done on the :class:`Element` level.
.. _elementtree-parsing-xml:
Parsing XML
^^^^^^^^^^^
We'll be using the following XML document as the sample data for this section:
.. code-block:: xml
<?xml version="1.0"?>
<data>
<country name="Liechtenstein">
<rank>1</rank>
<year>2008</year>
<gdppc>141100</gdppc>
<neighbor name="Austria" direction="E"/>
<neighbor name="Switzerland" direction="W"/>
</country>
<country name="Singapore">
<rank>4</rank>
<year>2011</year>
<gdppc>59900</gdppc>
<neighbor name="Malaysia" direction="N"/>
</country>
<country name="Panama">
<rank>68</rank>
<year>2011</year>
<gdppc>13600</gdppc>
<neighbor name="Costa Rica" direction="W"/>
<neighbor name="Colombia" direction="E"/>
</country>
</data>
We have a number of ways to import the data. Reading the file from disk::
import xml.etree.ElementTree as ET
tree = ET.parse('country_data.xml')
root = tree.getroot()
Reading the data from a string::
root = ET.fromstring(country_data_as_string)
:func:`fromstring` parses XML from a string directly into an :class:`Element`,
which is the root element of the parsed tree. Other parsing functions may
create an :class:`ElementTree`. Check the documentation to be sure.
As an :class:`Element`, ``root`` has a tag and a dictionary of attributes::
>>> root.tag
'data'
>>> root.attrib
{}
It also has children nodes over which we can iterate::
>>> for child in root:
... print child.tag, child.attrib
...
country {'name': 'Liechtenstein'}
country {'name': 'Singapore'}
country {'name': 'Panama'}
Children are nested, and we can access specific child nodes by index::
>>> root[0][1].text
'2008'
Finding interesting elements
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
:class:`Element` has some useful methods that help iterate recursively over all
the sub-tree below it (its children, their children, and so on). For example,
:meth:`Element.iter`::
>>> for neighbor in root.iter('neighbor'):
... print neighbor.attrib
...
{'name': 'Austria', 'direction': 'E'}
{'name': 'Switzerland', 'direction': 'W'}
{'name': 'Malaysia', 'direction': 'N'}
{'name': 'Costa Rica', 'direction': 'W'}
{'name': 'Colombia', 'direction': 'E'}
:meth:`Element.findall` finds only elements with a tag which are direct
children of the current element. :meth:`Element.find` finds the *first* child
with a particular tag, and :attr:`Element.text` accesses the element's text
content. :meth:`Element.get` accesses the element's attributes::
>>> for country in root.findall('country'):
... rank = country.find('rank').text
... name = country.get('name')
... print name, rank
...
Liechtenstein 1
Singapore 4
Panama 68
More sophisticated specification of which elements to look for is possible by
using :ref:`XPath <elementtree-xpath>`.
Modifying an XML File
^^^^^^^^^^^^^^^^^^^^^
:class:`ElementTree` provides a simple way to build XML documents and write them to files.
The :meth:`ElementTree.write` method serves this purpose.
Once created, an :class:`Element` object may be manipulated by directly changing
its fields (such as :attr:`Element.text`), adding and modifying attributes
(:meth:`Element.set` method), as well as adding new children (for example
with :meth:`Element.append`).
Let's say we want to add one to each country's rank, and add an ``updated``
attribute to the rank element::
>>> for rank in root.iter('rank'):
... new_rank = int(rank.text) + 1
... rank.text = str(new_rank)
... rank.set('updated', 'yes')
...
>>> tree.write('output.xml')
Our XML now looks like this:
.. code-block:: xml
<?xml version="1.0"?>
<data>
<country name="Liechtenstein">
<rank updated="yes">2</rank>
<year>2008</year>
<gdppc>141100</gdppc>
<neighbor name="Austria" direction="E"/>
<neighbor name="Switzerland" direction="W"/>
</country>
<country name="Singapore">
<rank updated="yes">5</rank>
<year>2011</year>
<gdppc>59900</gdppc>
<neighbor name="Malaysia" direction="N"/>
</country>
<country name="Panama">
<rank updated="yes">69</rank>
<year>2011</year>
<gdppc>13600</gdppc>
<neighbor name="Costa Rica" direction="W"/>
<neighbor name="Colombia" direction="E"/>
</country>
</data>
We can remove elements using :meth:`Element.remove`. Let's say we want to
remove all countries with a rank higher than 50::
>>> for country in root.findall('country'):
... rank = int(country.find('rank').text)
... if rank > 50:
... root.remove(country)
...
>>> tree.write('output.xml')
Our XML now looks like this:
.. code-block:: xml
<?xml version="1.0"?>
<data>
<country name="Liechtenstein">
<rank updated="yes">2</rank>
<year>2008</year>
<gdppc>141100</gdppc>
<neighbor name="Austria" direction="E"/>
<neighbor name="Switzerland" direction="W"/>
</country>
<country name="Singapore">
<rank updated="yes">5</rank>
<year>2011</year>
<gdppc>59900</gdppc>
<neighbor name="Malaysia" direction="N"/>
</country>
</data>
Building XML documents
^^^^^^^^^^^^^^^^^^^^^^
The :func:`SubElement` function also provides a convenient way to create new
sub-elements for a given element::
>>> a = ET.Element('a')
>>> b = ET.SubElement(a, 'b')
>>> c = ET.SubElement(a, 'c')
>>> d = ET.SubElement(c, 'd')
>>> ET.dump(a)
<a><b /><c><d /></c></a>
Parsing XML with Namespaces
^^^^^^^^^^^^^^^^^^^^^^^^^^^
If the XML input has `namespaces
<https://en.wikipedia.org/wiki/XML_namespace>`__, tags and attributes
with prefixes in the form ``prefix:sometag`` get expanded to
``{uri}sometag`` where the *prefix* is replaced by the full *URI*.
Also, if there is a `default namespace
<https://www.w3.org/TR/xml-names/#defaulting>`__,
that full URI gets prepended to all of the non-prefixed tags.
Here is an XML example that incorporates two namespaces, one with the
prefix "fictional" and the other serving as the default namespace:
.. code-block:: xml
<?xml version="1.0"?>
<actors xmlns:fictional="http://characters.example.com"
xmlns="http://people.example.com">
<actor>
<name>John Cleese</name>
<fictional:character>Lancelot</fictional:character>
<fictional:character>Archie Leach</fictional:character>
</actor>
<actor>
<name>Eric Idle</name>
<fictional:character>Sir Robin</fictional:character>
<fictional:character>Gunther</fictional:character>
<fictional:character>Commander Clement</fictional:character>
</actor>
</actors>
One way to search and explore this XML example is to manually add the
URI to every tag or attribute in the xpath of a
:meth:`~Element.find` or :meth:`~Element.findall`::
root = fromstring(xml_text)
for actor in root.findall('{http://people.example.com}actor'):
name = actor.find('{http://people.example.com}name')
print name.text
for char in actor.findall('{http://characters.example.com}character'):
print ' |-->', char.text
A better way to search the namespaced XML example is to create a
dictionary with your own prefixes and use those in the search functions::
ns = {'real_person': 'http://people.example.com',
'role': 'http://characters.example.com'}
for actor in root.findall('real_person:actor', ns):
name = actor.find('real_person:name', ns)
print name.text
for char in actor.findall('role:character', ns):
print ' |-->', char.text
These two approaches both output::
John Cleese
|--> Lancelot
|--> Archie Leach
Eric Idle
|--> Sir Robin
|--> Gunther
|--> Commander Clement
Additional resources
^^^^^^^^^^^^^^^^^^^^
See http://effbot.org/zone/element-index.htm for tutorials and links to other
docs.
.. _elementtree-xpath:
XPath support
-------------
This module provides limited support for
`XPath expressions <https://www.w3.org/TR/xpath>`_ for locating elements in a
tree. The goal is to support a small subset of the abbreviated syntax; a full
XPath engine is outside the scope of the module.
Example
^^^^^^^
Here's an example that demonstrates some of the XPath capabilities of the
module. We'll be using the ``countrydata`` XML document from the
:ref:`Parsing XML <elementtree-parsing-xml>` section::
import xml.etree.ElementTree as ET
root = ET.fromstring(countrydata)
# Top-level elements
root.findall(".")
# All 'neighbor' grand-children of 'country' children of the top-level
# elements
root.findall("./country/neighbor")
# Nodes with name='Singapore' that have a 'year' child
root.findall(".//year/..[@name='Singapore']")
# 'year' nodes that are children of nodes with name='Singapore'
root.findall(".//*[@name='Singapore']/year")
# All 'neighbor' nodes that are the second child of their parent
root.findall(".//neighbor[2]")
Supported XPath syntax
^^^^^^^^^^^^^^^^^^^^^^
.. tabularcolumns:: |l|L|
+-----------------------+------------------------------------------------------+
| Syntax | Meaning |
+=======================+======================================================+
| ``tag`` | Selects all child elements with the given tag. |
| | For example, ``spam`` selects all child elements |
| | named ``spam``, and ``spam/egg`` selects all |
| | grandchildren named ``egg`` in all children named |
| | ``spam``. |
+-----------------------+------------------------------------------------------+
| ``*`` | Selects all child elements. For example, ``*/egg`` |
| | selects all grandchildren named ``egg``. |
+-----------------------+------------------------------------------------------+
| ``.`` | Selects the current node. This is mostly useful |
| | at the beginning of the path, to indicate that it's |
| | a relative path. |
+-----------------------+------------------------------------------------------+
| ``//`` | Selects all subelements, on all levels beneath the |
| | current element. For example, ``.//egg`` selects |
| | all ``egg`` elements in the entire tree. |
+-----------------------+------------------------------------------------------+
| ``..`` | Selects the parent element. |
+-----------------------+------------------------------------------------------+
| ``[@attrib]`` | Selects all elements that have the given attribute. |
+-----------------------+------------------------------------------------------+
| ``[@attrib='value']`` | Selects all elements for which the given attribute |
| | has the given value. The value cannot contain |
| | quotes. |
+-----------------------+------------------------------------------------------+
| ``[tag]`` | Selects all elements that have a child named |
| | ``tag``. Only immediate children are supported. |
+-----------------------+------------------------------------------------------+
| ``[tag='text']`` | Selects all elements that have a child named |
| | ``tag`` whose complete text content, including |
| | descendants, equals the given ``text``. |
+-----------------------+------------------------------------------------------+
| ``[position]`` | Selects all elements that are located at the given |
| | position. The position can be either an integer |
| | (1 is the first position), the expression ``last()`` |
| | (for the last position), or a position relative to |
| | the last position (e.g. ``last()-1``). |
+-----------------------+------------------------------------------------------+
Predicates (expressions within square brackets) must be preceded by a tag
name, an asterisk, or another predicate. ``position`` predicates must be
preceded by a tag name.
Reference
---------
.. _elementtree-functions:
Functions
^^^^^^^^^
.. function:: Comment(text=None)
Comment element factory. This factory function creates a special element
that will be serialized as an XML comment by the standard serializer. The
comment string can be either a bytestring or a Unicode string. *text* is a
string containing the comment string. Returns an element instance
representing a comment.
.. function:: dump(elem)
Writes an element tree or element structure to sys.stdout. This function
should be used for debugging only.
The exact output format is implementation dependent. In this version, it's
written as an ordinary XML file.
*elem* is an element tree or an individual element.
.. function:: fromstring(text)
Parses an XML section from a string constant. Same as :func:`XML`. *text*
is a string containing XML data. Returns an :class:`Element` instance.
.. function:: fromstringlist(sequence, parser=None)
Parses an XML document from a sequence of string fragments. *sequence* is a
list or other sequence containing XML data fragments. *parser* is an
optional parser instance. If not given, the standard :class:`XMLParser`
parser is used. Returns an :class:`Element` instance.
.. versionadded:: 2.7
.. function:: iselement(element)
Checks if an object appears to be a valid element object. *element* is an
element instance. Returns a true value if this is an element object.
.. function:: iterparse(source, events=None, parser=None)
Parses an XML section into an element tree incrementally, and reports what's
going on to the user. *source* is a filename or file object containing XML
data. *events* is a list of events to report back. If omitted, only "end"
events are reported. *parser* is an optional parser instance. If not
given, the standard :class:`XMLParser` parser is used. *parser* is not
supported by ``cElementTree``. Returns an :term:`iterator` providing
``(event, elem)`` pairs.
.. note::
:func:`iterparse` only guarantees that it has seen the ">"
character of a starting tag when it emits a "start" event, so the
attributes are defined, but the contents of the text and tail attributes
are undefined at that point. The same applies to the element children;
they may or may not be present.
If you need a fully populated element, look for "end" events instead.
.. function:: parse(source, parser=None)
Parses an XML section into an element tree. *source* is a filename or file
object containing XML data. *parser* is an optional parser instance. If
not given, the standard :class:`XMLParser` parser is used. Returns an
:class:`ElementTree` instance.
.. function:: ProcessingInstruction(target, text=None)
PI element factory. This factory function creates a special element that
will be serialized as an XML processing instruction. *target* is a string
containing the PI target. *text* is a string containing the PI contents, if
given. Returns an element instance, representing a processing instruction.
.. function:: register_namespace(prefix, uri)
Registers a namespace prefix. The registry is global, and any existing
mapping for either the given prefix or the namespace URI will be removed.
*prefix* is a namespace prefix. *uri* is a namespace uri. Tags and
attributes in this namespace will be serialized with the given prefix, if at
all possible.
.. versionadded:: 2.7
.. function:: SubElement(parent, tag, attrib={}, **extra)
Subelement factory. This function creates an element instance, and appends
it to an existing element.
The element name, attribute names, and attribute values can be either
bytestrings or Unicode strings. *parent* is the parent element. *tag* is
the subelement name. *attrib* is an optional dictionary, containing element
attributes. *extra* contains additional attributes, given as keyword
arguments. Returns an element instance.
.. function:: tostring(element, encoding="us-ascii", method="xml")
Generates a string representation of an XML element, including all
subelements. *element* is an :class:`Element` instance. *encoding* [1]_ is
the output encoding (default is US-ASCII). *method* is either ``"xml"``,
``"html"`` or ``"text"`` (default is ``"xml"``). Returns an encoded string
containing the XML data.
.. function:: tostringlist(element, encoding="us-ascii", method="xml")
Generates a string representation of an XML element, including all
subelements. *element* is an :class:`Element` instance. *encoding* [1]_ is
the output encoding (default is US-ASCII). *method* is either ``"xml"``,
``"html"`` or ``"text"`` (default is ``"xml"``). Returns a list of encoded
strings containing the XML data. It does not guarantee any specific
sequence, except that ``"".join(tostringlist(element)) ==
tostring(element)``.
.. versionadded:: 2.7
.. function:: XML(text, parser=None)
Parses an XML section from a string constant. This function can be used to
embed "XML literals" in Python code. *text* is a string containing XML
data. *parser* is an optional parser instance. If not given, the standard
:class:`XMLParser` parser is used. Returns an :class:`Element` instance.
.. function:: XMLID(text, parser=None)
Parses an XML section from a string constant, and also returns a dictionary
which maps from element id:s to elements. *text* is a string containing XML
data. *parser* is an optional parser instance. If not given, the standard
:class:`XMLParser` parser is used. Returns a tuple containing an
:class:`Element` instance and a dictionary.
.. _elementtree-element-objects:
Element Objects
^^^^^^^^^^^^^^^
.. class:: Element(tag, attrib={}, **extra)
Element class. This class defines the Element interface, and provides a
reference implementation of this interface.
The element name, attribute names, and attribute values can be either
bytestrings or Unicode strings. *tag* is the element name. *attrib* is
an optional dictionary, containing element attributes. *extra* contains
additional attributes, given as keyword arguments.
.. attribute:: tag
A string identifying what kind of data this element represents (the
element type, in other words).
.. attribute:: text
tail
These attributes can be used to hold additional data associated with
the element. Their values are usually strings but may be any
application-specific object. If the element is created from
an XML file, the *text* attribute holds either the text between
the element's start tag and its first child or end tag, or ``None``, and
the *tail* attribute holds either the text between the element's
end tag and the next tag, or ``None``. For the XML data
.. code-block:: xml
<a><b>1<c>2<d/>3</c></b>4</a>
the *a* element has ``None`` for both *text* and *tail* attributes,
the *b* element has *text* ``"1"`` and *tail* ``"4"``,
the *c* element has *text* ``"2"`` and *tail* ``None``,
and the *d* element has *text* ``None`` and *tail* ``"3"``.
To collect the inner text of an element, see :meth:`itertext`, for
example ``"".join(element.itertext())``.
Applications may store arbitrary objects in these attributes.
.. attribute:: attrib
A dictionary containing the element's attributes. Note that while the
*attrib* value is always a real mutable Python dictionary, an ElementTree
implementation may choose to use another internal representation, and
create the dictionary only if someone asks for it. To take advantage of
such implementations, use the dictionary methods below whenever possible.
The following dictionary-like methods work on the element attributes.
.. method:: clear()
Resets an element. This function removes all subelements, clears all
attributes, and sets the text and tail attributes to ``None``.
.. method:: get(key, default=None)
Gets the element attribute named *key*.
Returns the attribute value, or *default* if the attribute was not found.
.. method:: items()
Returns the element attributes as a sequence of (name, value) pairs. The
attributes are returned in an arbitrary order.
.. method:: keys()
Returns the elements attribute names as a list. The names are returned
in an arbitrary order.
.. method:: set(key, value)
Set the attribute *key* on the element to *value*.
The following methods work on the element's children (subelements).
.. method:: append(subelement)
Adds the element *subelement* to the end of this elements internal list
of subelements.
.. method:: extend(subelements)
Appends *subelements* from a sequence object with zero or more elements.
Raises :exc:`AssertionError` if a subelement is not a valid object.
.. versionadded:: 2.7
.. method:: find(match)
Finds the first subelement matching *match*. *match* may be a tag name
or path. Returns an element instance or ``None``.
.. method:: findall(match)
Finds all matching subelements, by tag name or path. Returns a list
containing all matching elements in document order.
.. method:: findtext(match, default=None)
Finds text for the first subelement matching *match*. *match* may be
a tag name or path. Returns the text content of the first matching
element, or *default* if no element was found. Note that if the matching
element has no text content an empty string is returned.
.. method:: getchildren()
.. deprecated:: 2.7
Use ``list(elem)`` or iteration.
.. method:: getiterator(tag=None)
.. deprecated:: 2.7
Use method :meth:`Element.iter` instead.
.. method:: insert(index, element)
Inserts a subelement at the given position in this element.
.. method:: iter(tag=None)
Creates a tree :term:`iterator` with the current element as the root.
The iterator iterates over this element and all elements below it, in
document (depth first) order. If *tag* is not ``None`` or ``'*'``, only
elements whose tag equals *tag* are returned from the iterator. If the
tree structure is modified during iteration, the result is undefined.
.. versionadded:: 2.7
.. method:: iterfind(match)
Finds all matching subelements, by tag name or path. Returns an iterable
yielding all matching elements in document order.
.. versionadded:: 2.7
.. method:: itertext()
Creates a text iterator. The iterator loops over this element and all
subelements, in document order, and returns all inner text.
.. versionadded:: 2.7
.. method:: makeelement(tag, attrib)
Creates a new element object of the same type as this element. Do not
call this method, use the :func:`SubElement` factory function instead.
.. method:: remove(subelement)
Removes *subelement* from the element. Unlike the find\* methods this
method compares elements based on the instance identity, not on tag value
or contents.
:class:`Element` objects also support the following sequence type methods
for working with subelements: :meth:`~object.__delitem__`,
:meth:`~object.__getitem__`, :meth:`~object.__setitem__`,
:meth:`~object.__len__`.
Caution: Elements with no subelements will test as ``False``. This behavior
will change in future versions. Use specific ``len(elem)`` or ``elem is
None`` test instead. ::
element = root.find('foo')
if not element: # careful!
print "element not found, or element has no subelements"
if element is None:
print "element not found"
.. _elementtree-elementtree-objects:
ElementTree Objects
^^^^^^^^^^^^^^^^^^^
.. class:: ElementTree(element=None, file=None)
ElementTree wrapper class. This class represents an entire element
hierarchy, and adds some extra support for serialization to and from
standard XML.
*element* is the root element. The tree is initialized with the contents
of the XML *file* if given.
.. method:: _setroot(element)
Replaces the root element for this tree. This discards the current
contents of the tree, and replaces it with the given element. Use with
care. *element* is an element instance.
.. method:: find(match)
Same as :meth:`Element.find`, starting at the root of the tree.
.. method:: findall(match)
Same as :meth:`Element.findall`, starting at the root of the tree.
.. method:: findtext(match, default=None)
Same as :meth:`Element.findtext`, starting at the root of the tree.
.. method:: getiterator(tag=None)
.. deprecated:: 2.7
Use method :meth:`ElementTree.iter` instead.
.. method:: getroot()
Returns the root element for this tree.
.. method:: iter(tag=None)
Creates and returns a tree iterator for the root element. The iterator
loops over all elements in this tree, in section order. *tag* is the tag
to look for (default is to return all elements).
.. method:: iterfind(match)
Finds all matching subelements, by tag name or path. Same as
getroot().iterfind(match). Returns an iterable yielding all matching
elements in document order.
.. versionadded:: 2.7
.. method:: parse(source, parser=None)
Loads an external XML section into this element tree. *source* is a file
name or file object. *parser* is an optional parser instance. If not
given, the standard XMLParser parser is used. Returns the section
root element.
.. method:: write(file, encoding="us-ascii", xml_declaration=None, \
default_namespace=None, method="xml")
Writes the element tree to a file, as XML. *file* is a file name, or a
file object opened for writing. *encoding* [1]_ is the output encoding
(default is US-ASCII). *xml_declaration* controls if an XML declaration
should be added to the file. Use ``False`` for never, ``True`` for always, ``None``
for only if not US-ASCII or UTF-8 (default is ``None``). *default_namespace*
sets the default XML namespace (for "xmlns"). *method* is either
``"xml"``, ``"html"`` or ``"text"`` (default is ``"xml"``). Returns an
encoded string.
This is the XML file that is going to be manipulated::
<html>
<head>
<title>Example page</title>
</head>
<body>
<p>Moved to <a href="http://example.org/">example.org</a>
or <a href="http://example.com/">example.com</a>.</p>
</body>
</html>
Example of changing the attribute "target" of every link in first paragraph::
>>> from xml.etree.ElementTree import ElementTree
>>> tree = ElementTree()
>>> tree.parse("index.xhtml")
<Element 'html' at 0xb77e6fac>
>>> p = tree.find("body/p") # Finds first occurrence of tag p in body
>>> p
<Element 'p' at 0xb77ec26c>
>>> links = list(p.iter("a")) # Returns list of all links
>>> links
[<Element 'a' at 0xb77ec2ac>, <Element 'a' at 0xb77ec1cc>]
>>> for i in links: # Iterates through all found links
... i.attrib["target"] = "blank"
...
>>> tree.write("output.xhtml")
.. _elementtree-qname-objects:
QName Objects
^^^^^^^^^^^^^
.. class:: QName(text_or_uri, tag=None)
QName wrapper. This can be used to wrap a QName attribute value, in order
to get proper namespace handling on output. *text_or_uri* is a string
containing the QName value, in the form {uri}local, or, if the tag argument
is given, the URI part of a QName. If *tag* is given, the first argument is
interpreted as a URI, and this argument is interpreted as a local name.
:class:`QName` instances are opaque.
.. _elementtree-treebuilder-objects:
TreeBuilder Objects
^^^^^^^^^^^^^^^^^^^
.. class:: TreeBuilder(element_factory=None)
Generic element structure builder. This builder converts a sequence of
start, data, and end method calls to a well-formed element structure. You
can use this class to build an element structure using a custom XML parser,
or a parser for some other XML-like format. The *element_factory* is called
to create new :class:`Element` instances when given.
.. method:: close()
Flushes the builder buffers, and returns the toplevel document
element. Returns an :class:`Element` instance.
.. method:: data(data)
Adds text to the current element. *data* is a string. This should be
either a bytestring, or a Unicode string.
.. method:: end(tag)
Closes the current element. *tag* is the element name. Returns the
closed element.
.. method:: start(tag, attrs)
Opens a new element. *tag* is the element name. *attrs* is a dictionary
containing element attributes. Returns the opened element.
In addition, a custom :class:`TreeBuilder` object can provide the
following method:
.. method:: doctype(name, pubid, system)
Handles a doctype declaration. *name* is the doctype name. *pubid* is
the public identifier. *system* is the system identifier. This method
does not exist on the default :class:`TreeBuilder` class.
.. versionadded:: 2.7
.. _elementtree-xmlparser-objects:
XMLParser Objects
^^^^^^^^^^^^^^^^^
.. class:: XMLParser(html=0, target=None, encoding=None)
:class:`Element` structure builder for XML source data, based on the expat
parser. *html* are predefined HTML entities. This flag is not supported by
the current implementation. *target* is the target object. If omitted, the
builder uses an instance of the standard TreeBuilder class. *encoding* [1]_
is optional. If given, the value overrides the encoding specified in the
XML file.
.. method:: close()
Finishes feeding data to the parser. Returns an element structure.
.. method:: doctype(name, pubid, system)
.. deprecated:: 2.7
Define the :meth:`TreeBuilder.doctype` method on a custom TreeBuilder
target.
.. method:: feed(data)
Feeds data to the parser. *data* is encoded data.
:meth:`XMLParser.feed` calls *target*\'s :meth:`start` method
for each opening tag, its :meth:`end` method for each closing tag,
and data is processed by method :meth:`data`. :meth:`XMLParser.close`
calls *target*\'s method :meth:`close`.
:class:`XMLParser` can be used not only for building a tree structure.
This is an example of counting the maximum depth of an XML file::
>>> from xml.etree.ElementTree import XMLParser
>>> class MaxDepth: # The target object of the parser
... maxDepth = 0
... depth = 0
... def start(self, tag, attrib): # Called for each opening tag.
... self.depth += 1
... if self.depth > self.maxDepth:
... self.maxDepth = self.depth
... def end(self, tag): # Called for each closing tag.
... self.depth -= 1
... def data(self, data):
... pass # We do not need to do anything with data.
... def close(self): # Called when all data has been parsed.
... return self.maxDepth
...
>>> target = MaxDepth()
>>> parser = XMLParser(target=target)
>>> exampleXml = """
... <a>
... <b>
... </b>
... <b>
... <c>
... <d>
... </d>
... </c>
... </b>
... </a>"""
>>> parser.feed(exampleXml)
>>> parser.close()
4
.. rubric:: Footnotes
.. [1] The encoding string included in XML output should conform to the
appropriate standards. For example, "UTF-8" is valid, but "UTF8" is
not. See https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl
and https://www.iana.org/assignments/character-sets/character-sets.xhtml.
PK
%�\~E�x� � ! html/_sources/library/xml.rst.txtnu �[��� .. _xml:
XML Processing Modules
======================
.. module:: xml
:synopsis: Package containing XML processing modules
.. sectionauthor:: Christian Heimes <christian@python.org>
.. sectionauthor:: Georg Brandl <georg@python.org>
Python's interfaces for processing XML are grouped in the ``xml`` package.
.. warning::
The XML modules are not secure against erroneous or maliciously
constructed data. If you need to parse untrusted or unauthenticated data see
:ref:`xml-vulnerabilities`.
It is important to note that modules in the :mod:`xml` package require that
there be at least one SAX-compliant XML parser available. The Expat parser is
included with Python, so the :mod:`xml.parsers.expat` module will always be
available.
The documentation for the :mod:`xml.dom` and :mod:`xml.sax` packages are the
definition of the Python bindings for the DOM and SAX interfaces.
The XML handling submodules are:
* :mod:`xml.etree.ElementTree`: the ElementTree API, a simple and lightweight
XML processor
..
* :mod:`xml.dom`: the DOM API definition
* :mod:`xml.dom.minidom`: a minimal DOM implementation
* :mod:`xml.dom.pulldom`: support for building partial DOM trees
..
* :mod:`xml.sax`: SAX2 base classes and convenience functions
* :mod:`xml.parsers.expat`: the Expat parser binding
.. _xml-vulnerabilities:
XML vulnerabilities
===================
The XML processing modules are not secure against maliciously constructed data.
An attacker can abuse vulnerabilities for e.g. denial of service attacks, to
access local files, to generate network connections to other machines, or
to or circumvent firewalls. The attacks on XML abuse unfamiliar features
like inline `DTD`_ (document type definition) with entities.
The following table gives an overview of the known attacks and if the various
modules are vulnerable to them.
========================= ============== =============== ============== ============== ==============
kind sax etree minidom pulldom xmlrpc
========================= ============== =============== ============== ============== ==============
billion laughs **Vulnerable** **Vulnerable** **Vulnerable** **Vulnerable** **Vulnerable**
quadratic blowup **Vulnerable** **Vulnerable** **Vulnerable** **Vulnerable** **Vulnerable**
external entity expansion **Vulnerable** Safe (1) Safe (2) **Vulnerable** Safe (3)
`DTD`_ retrieval **Vulnerable** Safe Safe **Vulnerable** Safe
decompression bomb Safe Safe Safe Safe **Vulnerable**
========================= ============== =============== ============== ============== ==============
1. :mod:`xml.etree.ElementTree` doesn't expand external entities and raises a
ParserError when an entity occurs.
2. :mod:`xml.dom.minidom` doesn't expand external entities and simply returns
the unexpanded entity verbatim.
3. :mod:`xmlrpclib` doesn't expand external entities and omits them.
billion laughs / exponential entity expansion
The `Billion Laughs`_ attack -- also known as exponential entity expansion --
uses multiple levels of nested entities. Each entity refers to another entity
several times, the final entity definition contains a small string. Eventually
the small string is expanded to several gigabytes. The exponential expansion
consumes lots of CPU time, too.
quadratic blowup entity expansion
A quadratic blowup attack is similar to a `Billion Laughs`_ attack; it abuses
entity expansion, too. Instead of nested entities it repeats one large entity
with a couple of thousand chars over and over again. The attack isn't as
efficient as the exponential case but it avoids triggering countermeasures of
parsers against heavily nested entities.
external entity expansion
Entity declarations can contain more than just text for replacement. They can
also point to external resources by public identifiers or system identifiers.
System identifiers are standard URIs or can refer to local files. The XML
parser retrieves the resource with e.g. HTTP or FTP requests and embeds the
content into the XML document.
`DTD`_ retrieval
Some XML libraries like Python's :mod:`xml.dom.pulldom` retrieve document type
definitions from remote or local locations. The feature has similar
implications as the external entity expansion issue.
decompression bomb
The issue of decompression bombs (aka `ZIP bomb`_) apply to all XML libraries
that can parse compressed XML stream like gzipped HTTP streams or LZMA-ed
files. For an attacker it can reduce the amount of transmitted data by three
magnitudes or more.
The documentation of `defusedxml`_ on PyPI has further information about
all known attack vectors with examples and references.
defused packages
----------------
These external packages are recommended for any code that parses
untrusted XML data.
`defusedxml`_ is a pure Python package with modified subclasses of all stdlib
XML parsers that prevent any potentially malicious operation. The
package also ships with example exploits and extended documentation on more
XML exploits like xpath injection.
`defusedexpat`_ provides a modified libexpat and patched replacement
:mod:`pyexpat` extension module with countermeasures against entity expansion
DoS attacks. Defusedexpat still allows a sane and configurable amount of entity
expansions. The modifications will be merged into future releases of Python.
The workarounds and modifications are not included in patch releases as they
break backward compatibility. After all inline DTD and entity expansion are
well-defined XML features.
.. _defusedxml: https://pypi.org/project/defusedxml/
.. _defusedexpat: https://pypi.org/project/defusedexpat/
.. _Billion Laughs: https://en.wikipedia.org/wiki/Billion_laughs
.. _ZIP bomb: https://en.wikipedia.org/wiki/Zip_bomb
.. _DTD: https://en.wikipedia.org/wiki/Document_type_definition
PK
%�\Xm�o < < - html/_sources/library/xml.sax.handler.rst.txtnu �[���
:mod:`xml.sax.handler` --- Base classes for SAX handlers
========================================================
.. module:: xml.sax.handler
:synopsis: Base classes for SAX event handlers.
.. moduleauthor:: Lars Marius Garshol <larsga@garshol.priv.no>
.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
.. versionadded:: 2.0
The SAX API defines four kinds of handlers: content handlers, DTD handlers,
error handlers, and entity resolvers. Applications normally only need to
implement those interfaces whose events they are interested in; they can
implement the interfaces in a single object or in multiple objects. Handler
implementations should inherit from the base classes provided in the module
:mod:`xml.sax.handler`, so that all methods get default implementations.
.. class:: ContentHandler
This is the main callback interface in SAX, and the one most important to
applications. The order of events in this interface mirrors the order of the
information in the document.
.. class:: DTDHandler
Handle DTD events.
This interface specifies only those DTD events required for basic parsing
(unparsed entities and attributes).
.. class:: EntityResolver
Basic interface for resolving entities. If you create an object implementing
this interface, then register the object with your Parser, the parser will call
the method in your object to resolve all external entities.
.. class:: ErrorHandler
Interface used by the parser to present error and warning messages to the
application. The methods of this object control whether errors are immediately
converted to exceptions or are handled in some other way.
In addition to these classes, :mod:`xml.sax.handler` provides symbolic constants
for the feature and property names.
.. data:: feature_namespaces
| value: ``"http://xml.org/sax/features/namespaces"``
| true: Perform Namespace processing.
| false: Optionally do not perform Namespace processing (implies
namespace-prefixes; default).
| access: (parsing) read-only; (not parsing) read/write
.. data:: feature_namespace_prefixes
| value: ``"http://xml.org/sax/features/namespace-prefixes"``
| true: Report the original prefixed names and attributes used for Namespace
declarations.
| false: Do not report attributes used for Namespace declarations, and
optionally do not report original prefixed names (default).
| access: (parsing) read-only; (not parsing) read/write
.. data:: feature_string_interning
| value: ``"http://xml.org/sax/features/string-interning"``
| true: All element names, prefixes, attribute names, Namespace URIs, and
local names are interned using the built-in intern function.
| false: Names are not necessarily interned, although they may be (default).
| access: (parsing) read-only; (not parsing) read/write
.. data:: feature_validation
| value: ``"http://xml.org/sax/features/validation"``
| true: Report all validation errors (implies external-general-entities and
external-parameter-entities).
| false: Do not report validation errors.
| access: (parsing) read-only; (not parsing) read/write
.. data:: feature_external_ges
| value: ``"http://xml.org/sax/features/external-general-entities"``
| true: Include all external general (text) entities.
| false: Do not include external general entities.
| access: (parsing) read-only; (not parsing) read/write
.. data:: feature_external_pes
| value: ``"http://xml.org/sax/features/external-parameter-entities"``
| true: Include all external parameter entities, including the external DTD
subset.
| false: Do not include any external parameter entities, even the external
DTD subset.
| access: (parsing) read-only; (not parsing) read/write
.. data:: all_features
List of all features.
.. data:: property_lexical_handler
| value: ``"http://xml.org/sax/properties/lexical-handler"``
| data type: xml.sax.sax2lib.LexicalHandler (not supported in Python 2)
| description: An optional extension handler for lexical events like
comments.
| access: read/write
.. data:: property_declaration_handler
| value: ``"http://xml.org/sax/properties/declaration-handler"``
| data type: xml.sax.sax2lib.DeclHandler (not supported in Python 2)
| description: An optional extension handler for DTD-related events other
than notations and unparsed entities.
| access: read/write
.. data:: property_dom_node
| value: ``"http://xml.org/sax/properties/dom-node"``
| data type: org.w3c.dom.Node (not supported in Python 2)
| description: When parsing, the current DOM node being visited if this is
a DOM iterator; when not parsing, the root DOM node for iteration.
| access: (parsing) read-only; (not parsing) read/write
.. data:: property_xml_string
| value: ``"http://xml.org/sax/properties/xml-string"``
| data type: String
| description: The literal string of characters that was the source for the
current event.
| access: read-only
.. data:: all_properties
List of all known property names.
.. _content-handler-objects:
ContentHandler Objects
----------------------
Users are expected to subclass :class:`ContentHandler` to support their
application. The following methods are called by the parser on the appropriate
events in the input document:
.. method:: ContentHandler.setDocumentLocator(locator)
Called by the parser to give the application a locator for locating the origin
of document events.
SAX parsers are strongly encouraged (though not absolutely required) to supply a
locator: if it does so, it must supply the locator to the application by
invoking this method before invoking any of the other methods in the
DocumentHandler interface.
The locator allows the application to determine the end position of any
document-related event, even if the parser is not reporting an error. Typically,
the application will use this information for reporting its own errors (such as
character content that does not match an application's business rules). The
information returned by the locator is probably not sufficient for use with a
search engine.
Note that the locator will return correct information only during the invocation
of the events in this interface. The application should not attempt to use it at
any other time.
.. method:: ContentHandler.startDocument()
Receive notification of the beginning of a document.
The SAX parser will invoke this method only once, before any other methods in
this interface or in DTDHandler (except for :meth:`setDocumentLocator`).
.. method:: ContentHandler.endDocument()
Receive notification of the end of a document.
The SAX parser will invoke this method only once, and it will be the last method
invoked during the parse. The parser shall not invoke this method until it has
either abandoned parsing (because of an unrecoverable error) or reached the end
of input.
.. method:: ContentHandler.startPrefixMapping(prefix, uri)
Begin the scope of a prefix-URI Namespace mapping.
The information from this event is not necessary for normal Namespace
processing: the SAX XML reader will automatically replace prefixes for element
and attribute names when the ``feature_namespaces`` feature is enabled (the
default).
There are cases, however, when applications need to use prefixes in character
data or in attribute values, where they cannot safely be expanded automatically;
the :meth:`startPrefixMapping` and :meth:`endPrefixMapping` events supply the
information to the application to expand prefixes in those contexts itself, if
necessary.
.. XXX This is not really the default, is it? MvL
Note that :meth:`startPrefixMapping` and :meth:`endPrefixMapping` events are not
guaranteed to be properly nested relative to each-other: all
:meth:`startPrefixMapping` events will occur before the corresponding
:meth:`startElement` event, and all :meth:`endPrefixMapping` events will occur
after the corresponding :meth:`endElement` event, but their order is not
guaranteed.
.. method:: ContentHandler.endPrefixMapping(prefix)
End the scope of a prefix-URI mapping.
See :meth:`startPrefixMapping` for details. This event will always occur after
the corresponding :meth:`endElement` event, but the order of
:meth:`endPrefixMapping` events is not otherwise guaranteed.
.. method:: ContentHandler.startElement(name, attrs)
Signals the start of an element in non-namespace mode.
The *name* parameter contains the raw XML 1.0 name of the element type as a
string and the *attrs* parameter holds an object of the
:class:`~xml.sax.xmlreader.Attributes`
interface (see :ref:`attributes-objects`) containing the attributes of
the element. The object passed as *attrs* may be re-used by the parser; holding
on to a reference to it is not a reliable way to keep a copy of the attributes.
To keep a copy of the attributes, use the :meth:`copy` method of the *attrs*
object.
.. method:: ContentHandler.endElement(name)
Signals the end of an element in non-namespace mode.
The *name* parameter contains the name of the element type, just as with the
:meth:`startElement` event.
.. method:: ContentHandler.startElementNS(name, qname, attrs)
Signals the start of an element in namespace mode.
The *name* parameter contains the name of the element type as a ``(uri,
localname)`` tuple, the *qname* parameter contains the raw XML 1.0 name used in
the source document, and the *attrs* parameter holds an instance of the
:class:`~xml.sax.xmlreader.AttributesNS` interface (see
:ref:`attributes-ns-objects`)
containing the attributes of the element. If no namespace is associated with
the element, the *uri* component of *name* will be ``None``. The object passed
as *attrs* may be re-used by the parser; holding on to a reference to it is not
a reliable way to keep a copy of the attributes. To keep a copy of the
attributes, use the :meth:`copy` method of the *attrs* object.
Parsers may set the *qname* parameter to ``None``, unless the
``feature_namespace_prefixes`` feature is activated.
.. method:: ContentHandler.endElementNS(name, qname)
Signals the end of an element in namespace mode.
The *name* parameter contains the name of the element type, just as with the
:meth:`startElementNS` method, likewise the *qname* parameter.
.. method:: ContentHandler.characters(content)
Receive notification of character data.
The Parser will call this method to report each chunk of character data. SAX
parsers may return all contiguous character data in a single chunk, or they may
split it into several chunks; however, all of the characters in any single event
must come from the same external entity so that the Locator provides useful
information.
*content* may be a Unicode string or a byte string; the ``expat`` reader module
produces always Unicode strings.
.. note::
The earlier SAX 1 interface provided by the Python XML Special Interest Group
used a more Java-like interface for this method. Since most parsers used from
Python did not take advantage of the older interface, the simpler signature was
chosen to replace it. To convert old code to the new interface, use *content*
instead of slicing content with the old *offset* and *length* parameters.
.. method:: ContentHandler.ignorableWhitespace(whitespace)
Receive notification of ignorable whitespace in element content.
Validating Parsers must use this method to report each chunk of ignorable
whitespace (see the W3C XML 1.0 recommendation, section 2.10): non-validating
parsers may also use this method if they are capable of parsing and using
content models.
SAX parsers may return all contiguous whitespace in a single chunk, or they may
split it into several chunks; however, all of the characters in any single event
must come from the same external entity, so that the Locator provides useful
information.
.. method:: ContentHandler.processingInstruction(target, data)
Receive notification of a processing instruction.
The Parser will invoke this method once for each processing instruction found:
note that processing instructions may occur before or after the main document
element.
A SAX parser should never report an XML declaration (XML 1.0, section 2.8) or a
text declaration (XML 1.0, section 4.3.1) using this method.
.. method:: ContentHandler.skippedEntity(name)
Receive notification of a skipped entity.
The Parser will invoke this method once for each entity skipped. Non-validating
processors may skip entities if they have not seen the declarations (because,
for example, the entity was declared in an external DTD subset). All processors
may skip external entities, depending on the values of the
``feature_external_ges`` and the ``feature_external_pes`` properties.
.. _dtd-handler-objects:
DTDHandler Objects
------------------
:class:`DTDHandler` instances provide the following methods:
.. method:: DTDHandler.notationDecl(name, publicId, systemId)
Handle a notation declaration event.
.. method:: DTDHandler.unparsedEntityDecl(name, publicId, systemId, ndata)
Handle an unparsed entity declaration event.
.. _entity-resolver-objects:
EntityResolver Objects
----------------------
.. method:: EntityResolver.resolveEntity(publicId, systemId)
Resolve the system identifier of an entity and return either the system
identifier to read from as a string, or an InputSource to read from. The default
implementation returns *systemId*.
.. _sax-error-handler:
ErrorHandler Objects
--------------------
Objects with this interface are used to receive error and warning information
from the :class:`~xml.sax.xmlreader.XMLReader`. If you create an object that
implements this interface, then register the object with your
:class:`~xml.sax.xmlreader.XMLReader`, the parser
will call the methods in your object to report all warnings and errors. There
are three levels of errors available: warnings, (possibly) recoverable errors,
and unrecoverable errors. All methods take a :exc:`SAXParseException` as the
only parameter. Errors and warnings may be converted to an exception by raising
the passed-in exception object.
.. method:: ErrorHandler.error(exception)
Called when the parser encounters a recoverable error. If this method does not
raise an exception, parsing may continue, but further document information
should not be expected by the application. Allowing the parser to continue may
allow additional errors to be discovered in the input document.
.. method:: ErrorHandler.fatalError(exception)
Called when the parser encounters an error it cannot recover from; parsing is
expected to terminate when this method returns.
.. method:: ErrorHandler.warning(exception)
Called when the parser presents minor warning information to the application.
Parsing is expected to continue when this method returns, and document
information will continue to be passed to the application. Raising an exception
in this method will cause parsing to end.
PK
%�\�I��/ �/ , html/_sources/library/xml.sax.reader.rst.txtnu �[���
:mod:`xml.sax.xmlreader` --- Interface for XML parsers
======================================================
.. module:: xml.sax.xmlreader
:synopsis: Interface which SAX-compliant XML parsers must implement.
.. moduleauthor:: Lars Marius Garshol <larsga@garshol.priv.no>
.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
.. versionadded:: 2.0
SAX parsers implement the :class:`XMLReader` interface. They are implemented in
a Python module, which must provide a function :func:`create_parser`. This
function is invoked by :func:`xml.sax.make_parser` with no arguments to create
a new parser object.
.. class:: XMLReader()
Base class which can be inherited by SAX parsers.
.. class:: IncrementalParser()
In some cases, it is desirable not to parse an input source at once, but to feed
chunks of the document as they get available. Note that the reader will normally
not read the entire file, but read it in chunks as well; still :meth:`parse`
won't return until the entire document is processed. So these interfaces should
be used if the blocking behaviour of :meth:`parse` is not desirable.
When the parser is instantiated it is ready to begin accepting data from the
feed method immediately. After parsing has been finished with a call to close
the reset method must be called to make the parser ready to accept new data,
either from feed or using the parse method.
Note that these methods must *not* be called during parsing, that is, after
parse has been called and before it returns.
By default, the class also implements the parse method of the XMLReader
interface using the feed, close and reset methods of the IncrementalParser
interface as a convenience to SAX 2.0 driver writers.
.. class:: Locator()
Interface for associating a SAX event with a document location. A locator object
will return valid results only during calls to DocumentHandler methods; at any
other time, the results are unpredictable. If information is not available,
methods may return ``None``.
.. class:: InputSource([systemId])
Encapsulation of the information needed by the :class:`XMLReader` to read
entities.
This class may include information about the public identifier, system
identifier, byte stream (possibly with character encoding information) and/or
the character stream of an entity.
Applications will create objects of this class for use in the
:meth:`XMLReader.parse` method and for returning from
EntityResolver.resolveEntity.
An :class:`InputSource` belongs to the application, the :class:`XMLReader` is
not allowed to modify :class:`InputSource` objects passed to it from the
application, although it may make copies and modify those.
.. class:: AttributesImpl(attrs)
This is an implementation of the :class:`Attributes` interface (see section
:ref:`attributes-objects`). This is a dictionary-like object which
represents the element attributes in a :meth:`startElement` call. In addition
to the most useful dictionary operations, it supports a number of other
methods as described by the interface. Objects of this class should be
instantiated by readers; *attrs* must be a dictionary-like object containing
a mapping from attribute names to attribute values.
.. class:: AttributesNSImpl(attrs, qnames)
Namespace-aware variant of :class:`AttributesImpl`, which will be passed to
:meth:`startElementNS`. It is derived from :class:`AttributesImpl`, but
understands attribute names as two-tuples of *namespaceURI* and
*localname*. In addition, it provides a number of methods expecting qualified
names as they appear in the original document. This class implements the
:class:`AttributesNS` interface (see section :ref:`attributes-ns-objects`).
.. _xmlreader-objects:
XMLReader Objects
-----------------
The :class:`XMLReader` interface supports the following methods:
.. method:: XMLReader.parse(source)
Process an input source, producing SAX events. The *source* object can be a
system identifier (a string identifying the input source -- typically a file
name or a URL), a file-like object, or an :class:`InputSource` object. When
:meth:`parse` returns, the input is completely processed, and the parser object
can be discarded or reset. As a limitation, the current implementation only
accepts byte streams; processing of character streams is for further study.
.. method:: XMLReader.getContentHandler()
Return the current :class:`~xml.sax.handler.ContentHandler`.
.. method:: XMLReader.setContentHandler(handler)
Set the current :class:`~xml.sax.handler.ContentHandler`. If no
:class:`~xml.sax.handler.ContentHandler` is set, content events will be
discarded.
.. method:: XMLReader.getDTDHandler()
Return the current :class:`~xml.sax.handler.DTDHandler`.
.. method:: XMLReader.setDTDHandler(handler)
Set the current :class:`~xml.sax.handler.DTDHandler`. If no
:class:`~xml.sax.handler.DTDHandler` is set, DTD
events will be discarded.
.. method:: XMLReader.getEntityResolver()
Return the current :class:`~xml.sax.handler.EntityResolver`.
.. method:: XMLReader.setEntityResolver(handler)
Set the current :class:`~xml.sax.handler.EntityResolver`. If no
:class:`~xml.sax.handler.EntityResolver` is set,
attempts to resolve an external entity will result in opening the system
identifier for the entity, and fail if it is not available.
.. method:: XMLReader.getErrorHandler()
Return the current :class:`~xml.sax.handler.ErrorHandler`.
.. method:: XMLReader.setErrorHandler(handler)
Set the current error handler. If no :class:`~xml.sax.handler.ErrorHandler`
is set, errors will be raised as exceptions, and warnings will be printed.
.. method:: XMLReader.setLocale(locale)
Allow an application to set the locale for errors and warnings.
SAX parsers are not required to provide localization for errors and warnings; if
they cannot support the requested locale, however, they must raise a SAX
exception. Applications may request a locale change in the middle of a parse.
.. method:: XMLReader.getFeature(featurename)
Return the current setting for feature *featurename*. If the feature is not
recognized, :exc:`SAXNotRecognizedException` is raised. The well-known
featurenames are listed in the module :mod:`xml.sax.handler`.
.. method:: XMLReader.setFeature(featurename, value)
Set the *featurename* to *value*. If the feature is not recognized,
:exc:`SAXNotRecognizedException` is raised. If the feature or its setting is not
supported by the parser, *SAXNotSupportedException* is raised.
.. method:: XMLReader.getProperty(propertyname)
Return the current setting for property *propertyname*. If the property is not
recognized, a :exc:`SAXNotRecognizedException` is raised. The well-known
propertynames are listed in the module :mod:`xml.sax.handler`.
.. method:: XMLReader.setProperty(propertyname, value)
Set the *propertyname* to *value*. If the property is not recognized,
:exc:`SAXNotRecognizedException` is raised. If the property or its setting is
not supported by the parser, *SAXNotSupportedException* is raised.
.. _incremental-parser-objects:
IncrementalParser Objects
-------------------------
Instances of :class:`IncrementalParser` offer the following additional methods:
.. method:: IncrementalParser.feed(data)
Process a chunk of *data*.
.. method:: IncrementalParser.close()
Assume the end of the document. That will check well-formedness conditions that
can be checked only at the end, invoke handlers, and may clean up resources
allocated during parsing.
.. method:: IncrementalParser.reset()
This method is called after close has been called to reset the parser so that it
is ready to parse new documents. The results of calling parse or feed after
close without calling reset are undefined.
.. _locator-objects:
Locator Objects
---------------
Instances of :class:`Locator` provide these methods:
.. method:: Locator.getColumnNumber()
Return the column number where the current event begins.
.. method:: Locator.getLineNumber()
Return the line number where the current event begins.
.. method:: Locator.getPublicId()
Return the public identifier for the current event.
.. method:: Locator.getSystemId()
Return the system identifier for the current event.
.. _input-source-objects:
InputSource Objects
-------------------
.. method:: InputSource.setPublicId(id)
Sets the public identifier of this :class:`InputSource`.
.. method:: InputSource.getPublicId()
Returns the public identifier of this :class:`InputSource`.
.. method:: InputSource.setSystemId(id)
Sets the system identifier of this :class:`InputSource`.
.. method:: InputSource.getSystemId()
Returns the system identifier of this :class:`InputSource`.
.. method:: InputSource.setEncoding(encoding)
Sets the character encoding of this :class:`InputSource`.
The encoding must be a string acceptable for an XML encoding declaration (see
section 4.3.3 of the XML recommendation).
The encoding attribute of the :class:`InputSource` is ignored if the
:class:`InputSource` also contains a character stream.
.. method:: InputSource.getEncoding()
Get the character encoding of this InputSource.
.. method:: InputSource.setByteStream(bytefile)
Set the byte stream (a Python file-like object which does not perform
byte-to-character conversion) for this input source.
The SAX parser will ignore this if there is also a character stream specified,
but it will use a byte stream in preference to opening a URI connection itself.
If the application knows the character encoding of the byte stream, it should
set it with the setEncoding method.
.. method:: InputSource.getByteStream()
Get the byte stream for this input source.
The getEncoding method will return the character encoding for this byte stream,
or ``None`` if unknown.
.. method:: InputSource.setCharacterStream(charfile)
Set the character stream for this input source. (The stream must be a Python 1.6
Unicode-wrapped file-like that performs conversion to Unicode strings.)
If there is a character stream specified, the SAX parser will ignore any byte
stream and will not attempt to open a URI connection to the system identifier.
.. method:: InputSource.getCharacterStream()
Get the character stream for this input source.
.. _attributes-objects:
The :class:`Attributes` Interface
---------------------------------
:class:`Attributes` objects implement a portion of the mapping protocol,
including the methods :meth:`~collections.Mapping.copy`,
:meth:`~collections.Mapping.get`,
:meth:`~collections.Mapping.has_key`,
:meth:`~collections.Mapping.items`,
:meth:`~collections.Mapping.keys`,
and :meth:`~collections.Mapping.values`. The following methods
are also provided:
.. method:: Attributes.getLength()
Return the number of attributes.
.. method:: Attributes.getNames()
Return the names of the attributes.
.. method:: Attributes.getType(name)
Returns the type of the attribute *name*, which is normally ``'CDATA'``.
.. method:: Attributes.getValue(name)
Return the value of attribute *name*.
.. getValueByQName, getNameByQName, getQNameByName, getQNames available
.. here already, but documented only for derived class.
.. _attributes-ns-objects:
The :class:`AttributesNS` Interface
-----------------------------------
This interface is a subtype of the :class:`Attributes` interface (see section
:ref:`attributes-objects`). All methods supported by that interface are also
available on :class:`AttributesNS` objects.
The following methods are also available:
.. method:: AttributesNS.getValueByQName(name)
Return the value for a qualified name.
.. method:: AttributesNS.getNameByQName(name)
Return the ``(namespace, localname)`` pair for a qualified *name*.
.. method:: AttributesNS.getQNameByName(name)
Return the qualified name for a ``(namespace, localname)`` pair.
.. method:: AttributesNS.getQNames()
Return the qualified names of all attributes.
PK
%�\��p< < % html/_sources/library/xml.sax.rst.txtnu �[���
:mod:`xml.sax` --- Support for SAX2 parsers
===========================================
.. module:: xml.sax
:synopsis: Package containing SAX2 base classes and convenience functions.
.. moduleauthor:: Lars Marius Garshol <larsga@garshol.priv.no>
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
.. versionadded:: 2.0
The :mod:`xml.sax` package provides a number of modules which implement the
Simple API for XML (SAX) interface for Python. The package itself provides the
SAX exceptions and the convenience functions which will be most used by users of
the SAX API.
.. warning::
The :mod:`xml.sax` module is not secure against maliciously
constructed data. If you need to parse untrusted or unauthenticated data see
:ref:`xml-vulnerabilities`.
The convenience functions are:
.. function:: make_parser([parser_list])
Create and return a SAX :class:`~xml.sax.xmlreader.XMLReader` object. The
first parser found will
be used. If *parser_list* is provided, it must be a list of strings which
name modules that have a function named :func:`create_parser`. Modules listed
in *parser_list* will be used before modules in the default list of parsers.
.. function:: parse(filename_or_stream, handler[, error_handler])
Create a SAX parser and use it to parse a document. The document, passed in as
*filename_or_stream*, can be a filename or a file object. The *handler*
parameter needs to be a SAX :class:`~handler.ContentHandler` instance. If
*error_handler* is given, it must be a SAX :class:`~handler.ErrorHandler`
instance; if
omitted, :exc:`SAXParseException` will be raised on all errors. There is no
return value; all work must be done by the *handler* passed in.
.. function:: parseString(string, handler[, error_handler])
Similar to :func:`parse`, but parses from a buffer *string* received as a
parameter.
A typical SAX application uses three kinds of objects: readers, handlers and
input sources. "Reader" in this context is another term for parser, i.e. some
piece of code that reads the bytes or characters from the input source, and
produces a sequence of events. The events then get distributed to the handler
objects, i.e. the reader invokes a method on the handler. A SAX application
must therefore obtain a reader object, create or open the input sources, create
the handlers, and connect these objects all together. As the final step of
preparation, the reader is called to parse the input. During parsing, methods on
the handler objects are called based on structural and syntactic events from the
input data.
For these objects, only the interfaces are relevant; they are normally not
instantiated by the application itself. Since Python does not have an explicit
notion of interface, they are formally introduced as classes, but applications
may use implementations which do not inherit from the provided classes. The
:class:`~xml.sax.xmlreader.InputSource`, :class:`~xml.sax.xmlreader.Locator`,
:class:`~xml.sax.xmlreader.Attributes`, :class:`~xml.sax.xmlreader.AttributesNS`,
and :class:`~xml.sax.xmlreader.XMLReader` interfaces are defined in the
module :mod:`xml.sax.xmlreader`. The handler interfaces are defined in
:mod:`xml.sax.handler`. For convenience,
:class:`~xml.sax.xmlreader.InputSource` (which is often
instantiated directly) and the handler classes are also available from
:mod:`xml.sax`. These interfaces are described below.
In addition to these classes, :mod:`xml.sax` provides the following exception
classes.
.. exception:: SAXException(msg[, exception])
Encapsulate an XML error or warning. This class can contain basic error or
warning information from either the XML parser or the application: it can be
subclassed to provide additional functionality or to add localization. Note
that although the handlers defined in the
:class:`~xml.sax.handler.ErrorHandler` interface
receive instances of this exception, it is not required to actually raise the
exception --- it is also useful as a container for information.
When instantiated, *msg* should be a human-readable description of the error.
The optional *exception* parameter, if given, should be ``None`` or an exception
that was caught by the parsing code and is being passed along as information.
This is the base class for the other SAX exception classes.
.. exception:: SAXParseException(msg, exception, locator)
Subclass of :exc:`SAXException` raised on parse errors. Instances of this
class are passed to the methods of the SAX
:class:`~xml.sax.handler.ErrorHandler` interface to provide information
about the parse error. This class supports the SAX
:class:`~xml.sax.xmlreader.Locator` interface as well as the
:class:`SAXException` interface.
.. exception:: SAXNotRecognizedException(msg[, exception])
Subclass of :exc:`SAXException` raised when a SAX
:class:`~xml.sax.xmlreader.XMLReader` is
confronted with an unrecognized feature or property. SAX applications and
extensions may use this class for similar purposes.
.. exception:: SAXNotSupportedException(msg[, exception])
Subclass of :exc:`SAXException` raised when a SAX
:class:`~xml.sax.xmlreader.XMLReader` is asked to
enable a feature that is not supported, or to set a property to a value that the
implementation does not support. SAX applications and extensions may use this
class for similar purposes.
.. seealso::
`SAX: The Simple API for XML <http://www.saxproject.org/>`_
This site is the focal point for the definition of the SAX API. It provides a
Java implementation and online documentation. Links to implementations and
historical information are also available.
Module :mod:`xml.sax.handler`
Definitions of the interfaces for application-provided objects.
Module :mod:`xml.sax.saxutils`
Convenience functions for use in SAX applications.
Module :mod:`xml.sax.xmlreader`
Definitions of the interfaces for parser-provided objects.
.. _sax-exception-objects:
SAXException Objects
--------------------
The :class:`SAXException` exception class supports the following methods:
.. method:: SAXException.getMessage()
Return a human-readable message describing the error condition.
.. method:: SAXException.getException()
Return an encapsulated exception object, or ``None``.
PK
%�\M����
�
+ html/_sources/library/xml.sax.utils.rst.txtnu �[���
:mod:`xml.sax.saxutils` --- SAX Utilities
=========================================
.. module:: xml.sax.saxutils
:synopsis: Convenience functions and classes for use with SAX.
.. moduleauthor:: Lars Marius Garshol <larsga@garshol.priv.no>
.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
.. versionadded:: 2.0
The module :mod:`xml.sax.saxutils` contains a number of classes and functions
that are commonly useful when creating SAX applications, either in direct use,
or as base classes.
.. function:: escape(data[, entities])
Escape ``'&'``, ``'<'``, and ``'>'`` in a string of data.
You can escape other strings of data by passing a dictionary as the optional
*entities* parameter. The keys and values must all be strings; each key will be
replaced with its corresponding value. The characters ``'&'``, ``'<'`` and
``'>'`` are always escaped, even if *entities* is provided.
.. function:: unescape(data[, entities])
Unescape ``'&'``, ``'<'``, and ``'>'`` in a string of data.
You can unescape other strings of data by passing a dictionary as the optional
*entities* parameter. The keys and values must all be strings; each key will be
replaced with its corresponding value. ``'&'``, ``'<'``, and ``'>'``
are always unescaped, even if *entities* is provided.
.. versionadded:: 2.3
.. function:: quoteattr(data[, entities])
Similar to :func:`escape`, but also prepares *data* to be used as an
attribute value. The return value is a quoted version of *data* with any
additional required replacements. :func:`quoteattr` will select a quote
character based on the content of *data*, attempting to avoid encoding any
quote characters in the string. If both single- and double-quote characters
are already in *data*, the double-quote characters will be encoded and *data*
will be wrapped in double-quotes. The resulting string can be used directly
as an attribute value::
>>> print "<element attr=%s>" % quoteattr("ab ' cd \" ef")
<element attr="ab ' cd " ef">
This function is useful when generating attribute values for HTML or any SGML
using the reference concrete syntax.
.. versionadded:: 2.2
.. class:: XMLGenerator([out[, encoding]])
This class implements the :class:`~xml.sax.handler.ContentHandler` interface
by writing SAX
events back into an XML document. In other words, using an :class:`XMLGenerator`
as the content handler will reproduce the original document being parsed. *out*
should be a file-like object which will default to *sys.stdout*. *encoding* is
the encoding of the output stream which defaults to ``'iso-8859-1'``.
.. class:: XMLFilterBase(base)
This class is designed to sit between an
:class:`~xml.sax.xmlreader.XMLReader` and the client
application's event handlers. By default, it does nothing but pass requests up
to the reader and events on to the handlers unmodified, but subclasses can
override specific methods to modify the event stream or the configuration
requests as they pass through.
.. function:: prepare_input_source(source[, base])
This function takes an input source and an optional base URL and returns a
fully resolved :class:`~xml.sax.xmlreader.InputSource` object ready for
reading. The input source can be given as a string, a file-like object, or
an :class:`~xml.sax.xmlreader.InputSource` object; parsers will use this
function to implement the polymorphic *source* argument to their
:meth:`parse` method.
PK
%�\�w�% X X ' html/_sources/library/xmlrpclib.rst.txtnu �[��� :mod:`xmlrpclib` --- XML-RPC client access
==========================================
.. module:: xmlrpclib
:synopsis: XML-RPC client access.
.. moduleauthor:: Fredrik Lundh <fredrik@pythonware.com>
.. sectionauthor:: Eric S. Raymond <esr@snark.thyrsus.com>
.. note::
The :mod:`xmlrpclib` module has been renamed to :mod:`xmlrpc.client` in
Python 3. The :term:`2to3` tool will automatically adapt imports when
converting your sources to Python 3.
.. XXX Not everything is documented yet. It might be good to describe
Marshaller, Unmarshaller, getparser, dumps, loads, and Transport.
.. versionadded:: 2.2
**Source code:** :source:`Lib/xmlrpclib.py`
--------------
XML-RPC is a Remote Procedure Call method that uses XML passed via HTTP(S) as a
transport. With it, a client can call methods with parameters on a remote
server (the server is named by a URI) and get back structured data. This module
supports writing XML-RPC client code; it handles all the details of translating
between conformable Python objects and XML on the wire.
.. warning::
The :mod:`xmlrpclib` module is not secure against maliciously
constructed data. If you need to parse untrusted or unauthenticated data see
:ref:`xml-vulnerabilities`.
.. versionchanged:: 2.7.9
For HTTPS URIs, :mod:`xmlrpclib` now performs all the necessary certificate
and hostname checks by default.
.. class:: ServerProxy(uri[, transport[, encoding[, verbose[, allow_none[, use_datetime[, context]]]]]])
A :class:`ServerProxy` instance is an object that manages communication with a
remote XML-RPC server. The required first argument is a URI (Uniform Resource
Indicator), and will normally be the URL of the server. The optional second
argument is a transport factory instance; by default it is an internal
:class:`SafeTransport` instance for https: URLs and an internal HTTP
:class:`Transport` instance otherwise. The optional third argument is an
encoding, by default UTF-8. The optional fourth argument is a debugging flag.
The following parameters govern the use of the returned proxy instance.
If *allow_none* is true, the Python constant ``None`` will be translated into
XML; the default behaviour is for ``None`` to raise a :exc:`TypeError`. This is
a commonly-used extension to the XML-RPC specification, but isn't supported by
all clients and servers; see `http://ontosys.com/xml-rpc/extensions.php
<https://web.archive.org/web/20130120074804/http://ontosys.com/xml-rpc/extensions.php>`_
for a description.
The *use_datetime* flag can be used to cause date/time values to
be presented as :class:`datetime.datetime` objects; this is false by default.
:class:`datetime.datetime` objects may be passed to calls.
Both the HTTP and HTTPS transports support the URL syntax extension for HTTP
Basic Authentication: ``http://user:pass@host:port/path``. The ``user:pass``
portion will be base64-encoded as an HTTP 'Authorization' header, and sent to
the remote server as part of the connection process when invoking an XML-RPC
method. You only need to use this if the remote server requires a Basic
Authentication user and password. If an HTTPS URL is provided, *context* may
be :class:`ssl.SSLContext` and configures the SSL settings of the underlying
HTTPS connection.
The returned instance is a proxy object with methods that can be used to invoke
corresponding RPC calls on the remote server. If the remote server supports the
introspection API, the proxy can also be used to query the remote server for the
methods it supports (service discovery) and fetch other server-associated
metadata.
Types that are conformable (e.g. that can be marshalled through XML),
include the following (and except where noted, they are unmarshalled
as the same Python type):
.. tabularcolumns:: |l|L|
+----------------------+-------------------------------------------------------+
| XML-RPC type | Python type |
+======================+=======================================================+
| ``boolean`` | :class:`bool` |
+----------------------+-------------------------------------------------------+
| ``int`` or ``i4`` | :class:`int` or :class:`long` in range from |
| | -2147483648 to 2147483647. |
+----------------------+-------------------------------------------------------+
| ``double`` | :class:`float` |
+----------------------+-------------------------------------------------------+
| ``string`` | :class:`str` or :class:`unicode` |
+----------------------+-------------------------------------------------------+
| ``array`` | :class:`list` or :class:`tuple` containing |
| | conformable elements. Arrays are returned as |
| | :class:`lists <list>`. |
+----------------------+-------------------------------------------------------+
| ``struct`` | :class:`dict`. Keys must be strings, values may be |
| | any conformable type. Objects of user-defined |
| | classes can be passed in; only their |
| | :attr:`~object.__dict__` attribute is transmitted. |
+----------------------+-------------------------------------------------------+
| ``dateTime.iso8601`` | :class:`DateTime` or :class:`datetime.datetime`. |
| | Returned type depends on values of the *use_datetime* |
| | flags. |
+----------------------+-------------------------------------------------------+
| ``base64`` | :class:`Binary` |
+----------------------+-------------------------------------------------------+
| ``nil`` | The ``None`` constant. Passing is allowed only if |
| | *allow_none* is true. |
+----------------------+-------------------------------------------------------+
This is the full set of data types supported by XML-RPC. Method calls may also
raise a special :exc:`Fault` instance, used to signal XML-RPC server errors, or
:exc:`ProtocolError` used to signal an error in the HTTP/HTTPS transport layer.
Both :exc:`Fault` and :exc:`ProtocolError` derive from a base class called
:exc:`Error`. Note that even though starting with Python 2.2 you can subclass
built-in types, the xmlrpclib module currently does not marshal instances of such
subclasses.
When passing strings, characters special to XML such as ``<``, ``>``, and ``&``
will be automatically escaped. However, it's the caller's responsibility to
ensure that the string is free of characters that aren't allowed in XML, such as
the control characters with ASCII values between 0 and 31 (except, of course,
tab, newline and carriage return); failing to do this will result in an XML-RPC
request that isn't well-formed XML. If you have to pass arbitrary strings via
XML-RPC, use the :class:`Binary` wrapper class described below.
:class:`Server` is retained as an alias for :class:`ServerProxy` for backwards
compatibility. New code should use :class:`ServerProxy`.
.. versionchanged:: 2.5
The *use_datetime* flag was added.
.. versionchanged:: 2.6
Instances of :term:`new-style class`\es can be passed in if they have an
*__dict__* attribute and don't have a base class that is marshalled in a
special way.
.. versionchanged:: 2.7.9
Added the *context* argument.
.. seealso::
`XML-RPC HOWTO <http://www.tldp.org/HOWTO/XML-RPC-HOWTO/index.html>`_
A good description of XML-RPC operation and client software in several languages.
Contains pretty much everything an XML-RPC client developer needs to know.
`XML-RPC Introspection <http://xmlrpc-c.sourceforge.net/introspection.html>`_
Describes the XML-RPC protocol extension for introspection.
`XML-RPC Specification <http://www.xmlrpc.com/spec>`_
The official specification.
`Unofficial XML-RPC Errata <http://effbot.org/zone/xmlrpc-errata.htm>`_
Fredrik Lundh's "unofficial errata, intended to clarify certain
details in the XML-RPC specification, as well as hint at
'best practices' to use when designing your own XML-RPC
implementations."
.. _serverproxy-objects:
ServerProxy Objects
-------------------
A :class:`ServerProxy` instance has a method corresponding to each remote
procedure call accepted by the XML-RPC server. Calling the method performs an
RPC, dispatched by both name and argument signature (e.g. the same method name
can be overloaded with multiple argument signatures). The RPC finishes by
returning a value, which may be either returned data in a conformant type or a
:class:`Fault` or :class:`ProtocolError` object indicating an error.
Servers that support the XML introspection API support some common methods
grouped under the reserved :attr:`~ServerProxy.system` attribute:
.. method:: ServerProxy.system.listMethods()
This method returns a list of strings, one for each (non-system) method
supported by the XML-RPC server.
.. method:: ServerProxy.system.methodSignature(name)
This method takes one parameter, the name of a method implemented by the XML-RPC
server. It returns an array of possible signatures for this method. A signature
is an array of types. The first of these types is the return type of the method,
the rest are parameters.
Because multiple signatures (ie. overloading) is permitted, this method returns
a list of signatures rather than a singleton.
Signatures themselves are restricted to the top level parameters expected by a
method. For instance if a method expects one array of structs as a parameter,
and it returns a string, its signature is simply "string, array". If it expects
three integers and returns a string, its signature is "string, int, int, int".
If no signature is defined for the method, a non-array value is returned. In
Python this means that the type of the returned value will be something other
than list.
.. method:: ServerProxy.system.methodHelp(name)
This method takes one parameter, the name of a method implemented by the XML-RPC
server. It returns a documentation string describing the use of that method. If
no such string is available, an empty string is returned. The documentation
string may contain HTML markup.
.. _boolean-objects:
Boolean Objects
---------------
This class may be initialized from any Python value; the instance returned
depends only on its truth value. It supports various Python operators through
:meth:`__cmp__`, :meth:`__repr__`, :meth:`__int__`, and :meth:`__nonzero__`
methods, all implemented in the obvious ways.
It also has the following method, supported mainly for internal use by the
unmarshalling code:
.. method:: Boolean.encode(out)
Write the XML-RPC encoding of this Boolean item to the out stream object.
A working example follows. The server code::
import xmlrpclib
from SimpleXMLRPCServer import SimpleXMLRPCServer
def is_even(n):
return n % 2 == 0
server = SimpleXMLRPCServer(("localhost", 8000))
print "Listening on port 8000..."
server.register_function(is_even, "is_even")
server.serve_forever()
The client code for the preceding server::
import xmlrpclib
proxy = xmlrpclib.ServerProxy("http://localhost:8000/")
print "3 is even: %s" % str(proxy.is_even(3))
print "100 is even: %s" % str(proxy.is_even(100))
.. _datetime-objects:
DateTime Objects
----------------
.. class:: DateTime
This class may be initialized with seconds since the epoch, a time
tuple, an ISO 8601 time/date string, or a :class:`datetime.datetime`
instance. It has the following methods, supported mainly for internal
use by the marshalling/unmarshalling code:
.. method:: decode(string)
Accept a string as the instance's new time value.
.. method:: encode(out)
Write the XML-RPC encoding of this :class:`DateTime` item to the *out* stream
object.
It also supports certain of Python's built-in operators through :meth:`__cmp__`
and :meth:`__repr__` methods.
A working example follows. The server code::
import datetime
from SimpleXMLRPCServer import SimpleXMLRPCServer
import xmlrpclib
def today():
today = datetime.datetime.today()
return xmlrpclib.DateTime(today)
server = SimpleXMLRPCServer(("localhost", 8000))
print "Listening on port 8000..."
server.register_function(today, "today")
server.serve_forever()
The client code for the preceding server::
import xmlrpclib
import datetime
proxy = xmlrpclib.ServerProxy("http://localhost:8000/")
today = proxy.today()
# convert the ISO8601 string to a datetime object
converted = datetime.datetime.strptime(today.value, "%Y%m%dT%H:%M:%S")
print "Today: %s" % converted.strftime("%d.%m.%Y, %H:%M")
.. _binary-objects:
Binary Objects
--------------
.. class:: Binary
This class may be initialized from string data (which may include NULs). The
primary access to the content of a :class:`Binary` object is provided by an
attribute:
.. attribute:: data
The binary data encapsulated by the :class:`Binary` instance. The data is
provided as an 8-bit string.
:class:`Binary` objects have the following methods, supported mainly for
internal use by the marshalling/unmarshalling code:
.. method:: decode(string)
Accept a base64 string and decode it as the instance's new data.
.. method:: encode(out)
Write the XML-RPC base 64 encoding of this binary item to the *out* stream object.
The encoded data will have newlines every 76 characters as per
`RFC 2045 section 6.8 <https://tools.ietf.org/html/rfc2045#section-6.8>`_,
which was the de facto standard base64 specification when the
XML-RPC spec was written.
It also supports certain of Python's built-in operators through a
:meth:`__cmp__` method.
Example usage of the binary objects. We're going to transfer an image over
XMLRPC::
from SimpleXMLRPCServer import SimpleXMLRPCServer
import xmlrpclib
def python_logo():
with open("python_logo.jpg", "rb") as handle:
return xmlrpclib.Binary(handle.read())
server = SimpleXMLRPCServer(("localhost", 8000))
print "Listening on port 8000..."
server.register_function(python_logo, 'python_logo')
server.serve_forever()
The client gets the image and saves it to a file::
import xmlrpclib
proxy = xmlrpclib.ServerProxy("http://localhost:8000/")
with open("fetched_python_logo.jpg", "wb") as handle:
handle.write(proxy.python_logo().data)
.. _fault-objects:
Fault Objects
-------------
.. class:: Fault
A :class:`Fault` object encapsulates the content of an XML-RPC fault tag. Fault
objects have the following attributes:
.. attribute:: faultCode
A string indicating the fault type.
.. attribute:: faultString
A string containing a diagnostic message associated with the fault.
In the following example we're going to intentionally cause a :exc:`Fault` by
returning a complex type object. The server code::
from SimpleXMLRPCServer import SimpleXMLRPCServer
# A marshalling error is going to occur because we're returning a
# complex number
def add(x, y):
return x+y+0j
server = SimpleXMLRPCServer(("localhost", 8000))
print "Listening on port 8000..."
server.register_function(add, 'add')
server.serve_forever()
The client code for the preceding server::
import xmlrpclib
proxy = xmlrpclib.ServerProxy("http://localhost:8000/")
try:
proxy.add(2, 5)
except xmlrpclib.Fault as err:
print "A fault occurred"
print "Fault code: %d" % err.faultCode
print "Fault string: %s" % err.faultString
.. _protocol-error-objects:
ProtocolError Objects
---------------------
.. class:: ProtocolError
A :class:`ProtocolError` object describes a protocol error in the underlying
transport layer (such as a 404 'not found' error if the server named by the URI
does not exist). It has the following attributes:
.. attribute:: url
The URI or URL that triggered the error.
.. attribute:: errcode
The error code.
.. attribute:: errmsg
The error message or diagnostic string.
.. attribute:: headers
A string containing the headers of the HTTP/HTTPS request that triggered the
error.
In the following example we're going to intentionally cause a :exc:`ProtocolError`
by providing a URI that doesn't point to an XMLRPC server::
import xmlrpclib
# create a ServerProxy with a URI that doesn't respond to XMLRPC requests
proxy = xmlrpclib.ServerProxy("http://www.google.com/")
try:
proxy.some_method()
except xmlrpclib.ProtocolError as err:
print "A protocol error occurred"
print "URL: %s" % err.url
print "HTTP/HTTPS headers: %s" % err.headers
print "Error code: %d" % err.errcode
print "Error message: %s" % err.errmsg
MultiCall Objects
-----------------
.. versionadded:: 2.4
The :class:`MultiCall` object provides a way to encapsulate multiple calls to a
remote server into a single request [#]_.
.. class:: MultiCall(server)
Create an object used to boxcar method calls. *server* is the eventual target of
the call. Calls can be made to the result object, but they will immediately
return ``None``, and only store the call name and parameters in the
:class:`MultiCall` object. Calling the object itself causes all stored calls to
be transmitted as a single ``system.multicall`` request. The result of this call
is a :term:`generator`; iterating over this generator yields the individual
results.
A usage example of this class follows. The server code ::
from SimpleXMLRPCServer import SimpleXMLRPCServer
def add(x,y):
return x+y
def subtract(x, y):
return x-y
def multiply(x, y):
return x*y
def divide(x, y):
return x/y
# A simple server with simple arithmetic functions
server = SimpleXMLRPCServer(("localhost", 8000))
print "Listening on port 8000..."
server.register_multicall_functions()
server.register_function(add, 'add')
server.register_function(subtract, 'subtract')
server.register_function(multiply, 'multiply')
server.register_function(divide, 'divide')
server.serve_forever()
The client code for the preceding server::
import xmlrpclib
proxy = xmlrpclib.ServerProxy("http://localhost:8000/")
multicall = xmlrpclib.MultiCall(proxy)
multicall.add(7,3)
multicall.subtract(7,3)
multicall.multiply(7,3)
multicall.divide(7,3)
result = multicall()
print "7+3=%d, 7-3=%d, 7*3=%d, 7/3=%d" % tuple(result)
Convenience Functions
---------------------
.. function:: boolean(value)
Convert any Python value to one of the XML-RPC Boolean constants, ``True`` or
``False``.
.. function:: dumps(params[, methodname[, methodresponse[, encoding[, allow_none]]]])
Convert *params* into an XML-RPC request. or into a response if *methodresponse*
is true. *params* can be either a tuple of arguments or an instance of the
:exc:`Fault` exception class. If *methodresponse* is true, only a single value
can be returned, meaning that *params* must be of length 1. *encoding*, if
supplied, is the encoding to use in the generated XML; the default is UTF-8.
Python's :const:`None` value cannot be used in standard XML-RPC; to allow using
it via an extension, provide a true value for *allow_none*.
.. function:: loads(data[, use_datetime])
Convert an XML-RPC request or response into Python objects, a ``(params,
methodname)``. *params* is a tuple of argument; *methodname* is a string, or
``None`` if no method name is present in the packet. If the XML-RPC packet
represents a fault condition, this function will raise a :exc:`Fault` exception.
The *use_datetime* flag can be used to cause date/time values to be presented as
:class:`datetime.datetime` objects; this is false by default.
.. versionchanged:: 2.5
The *use_datetime* flag was added.
.. _xmlrpc-client-example:
Example of Client Usage
-----------------------
::
# simple test program (from the XML-RPC specification)
from xmlrpclib import ServerProxy, Error
# server = ServerProxy("http://localhost:8000") # local server
server = ServerProxy("http://betty.userland.com")
print server
try:
print server.examples.getStateName(41)
except Error as v:
print "ERROR", v
To access an XML-RPC server through a HTTP proxy, you need to define a custom
transport. The following example shows how:
.. Example taken from http://lowlife.jp/nobonobo/wiki/xmlrpcwithproxy.html
::
import xmlrpclib, httplib
class ProxiedTransport(xmlrpclib.Transport):
def set_proxy(self, proxy):
self.proxy = proxy
def make_connection(self, host):
self.realhost = host
h = httplib.HTTPConnection(self.proxy)
return h
def send_request(self, connection, handler, request_body):
connection.putrequest("POST", 'http://%s%s' % (self.realhost, handler))
def send_host(self, connection, host):
connection.putheader('Host', self.realhost)
p = ProxiedTransport()
p.set_proxy('proxy-server:8080')
server = xmlrpclib.ServerProxy('http://time.xmlrpc.com/RPC2', transport=p)
print server.currentTime.getCurrentTime()
Example of Client and Server Usage
----------------------------------
See :ref:`simplexmlrpcserver-example`.
.. rubric:: Footnotes
.. [#] This approach has been first presented in `a discussion on xmlrpc.com
<https://web.archive.org/web/20060624230303/http://www.xmlrpc.com/discuss/msgReader$1208?mode=topic>`_.
.. the link now points to webarchive since the one at
.. http://www.xmlrpc.com/discuss/msgReader%241208 is broken (and webadmin
.. doesn't reply)
PK
%�\�U�p�I �I % html/_sources/library/zipfile.rst.txtnu �[��� :mod:`zipfile` --- Work with ZIP archives
=========================================
.. module:: zipfile
:synopsis: Read and write ZIP-format archive files.
.. moduleauthor:: James C. Ahlstrom <jim@interet.com>
.. sectionauthor:: James C. Ahlstrom <jim@interet.com>
.. versionadded:: 1.6
**Source code:** :source:`Lib/zipfile.py`
--------------
The ZIP file format is a common archive and compression standard. This module
provides tools to create, read, write, append, and list a ZIP file. Any
advanced use of this module will require an understanding of the format, as
defined in `PKZIP Application Note`_.
This module does not currently handle multi-disk ZIP files.
It can handle ZIP files that use the ZIP64 extensions
(that is ZIP files that are more than 4 GByte in size). It supports
decryption of encrypted files in ZIP archives, but it currently cannot
create an encrypted file. Decryption is extremely slow as it is
implemented in native Python rather than C.
The module defines the following items:
.. exception:: BadZipfile
The error raised for bad ZIP files (old name: ``zipfile.error``).
.. exception:: LargeZipFile
The error raised when a ZIP file would require ZIP64 functionality but that has
not been enabled.
.. class:: ZipFile
:noindex:
The class for reading and writing ZIP files. See section
:ref:`zipfile-objects` for constructor details.
.. class:: PyZipFile
Class for creating ZIP archives containing Python libraries.
.. class:: ZipInfo([filename[, date_time]])
Class used to represent information about a member of an archive. Instances
of this class are returned by the :meth:`.getinfo` and :meth:`.infolist`
methods of :class:`ZipFile` objects. Most users of the :mod:`zipfile` module
will not need to create these, but only use those created by this
module. *filename* should be the full name of the archive member, and
*date_time* should be a tuple containing six fields which describe the time
of the last modification to the file; the fields are described in section
:ref:`zipinfo-objects`.
.. function:: is_zipfile(filename)
Returns ``True`` if *filename* is a valid ZIP file based on its magic number,
otherwise returns ``False``. *filename* may be a file or file-like object too.
.. versionchanged:: 2.7
Support for file and file-like objects.
.. data:: ZIP_STORED
The numeric constant for an uncompressed archive member.
.. data:: ZIP_DEFLATED
The numeric constant for the usual ZIP compression method. This requires the
:mod:`zlib` module. No other compression methods are currently supported.
.. seealso::
`PKZIP Application Note`_
Documentation on the ZIP file format by Phil Katz, the creator of the format and
algorithms used.
`Info-ZIP Home Page <http://www.info-zip.org/>`_
Information about the Info-ZIP project's ZIP archive programs and development
libraries.
.. _zipfile-objects:
ZipFile Objects
---------------
.. class:: ZipFile(file[, mode[, compression[, allowZip64]]])
Open a ZIP file, where *file* can be either a path to a file (a string) or a
file-like object. The *mode* parameter should be ``'r'`` to read an existing
file, ``'w'`` to truncate and write a new file, or ``'a'`` to append to an
existing file. If *mode* is ``'a'`` and *file* refers to an existing ZIP
file, then additional files are added to it. If *file* does not refer to a
ZIP file, then a new ZIP archive is appended to the file. This is meant for
adding a ZIP archive to another file (such as :file:`python.exe`).
.. versionchanged:: 2.6
If *mode* is ``a`` and the file does not exist at all, it is created.
*compression* is the ZIP compression method to use when writing the archive,
and should be :const:`ZIP_STORED` or :const:`ZIP_DEFLATED`; unrecognized
values will cause :exc:`RuntimeError` to be raised. If :const:`ZIP_DEFLATED`
is specified but the :mod:`zlib` module is not available, :exc:`RuntimeError`
is also raised. The default is :const:`ZIP_STORED`. If *allowZip64* is
``True`` zipfile will create ZIP files that use the ZIP64 extensions when
the zipfile is larger than 2 GB. If it is false (the default) :mod:`zipfile`
will raise an exception when the ZIP file would require ZIP64 extensions.
ZIP64 extensions are disabled by default because the default :program:`zip`
and :program:`unzip` commands on Unix (the InfoZIP utilities) don't support
these extensions.
.. versionchanged:: 2.7.1
If the file is created with mode ``'a'`` or ``'w'`` and then
:meth:`closed <close>` without adding any files to the archive, the appropriate
ZIP structures for an empty archive will be written to the file.
ZipFile is also a context manager and therefore supports the
:keyword:`with` statement. In the example, *myzip* is closed after the
:keyword:`with` statement's suite is finished---even if an exception occurs::
with ZipFile('spam.zip', 'w') as myzip:
myzip.write('eggs.txt')
.. versionadded:: 2.7
Added the ability to use :class:`ZipFile` as a context manager.
.. method:: ZipFile.close()
Close the archive file. You must call :meth:`close` before exiting your program
or essential records will not be written.
.. method:: ZipFile.getinfo(name)
Return a :class:`ZipInfo` object with information about the archive member
*name*. Calling :meth:`getinfo` for a name not currently contained in the
archive will raise a :exc:`KeyError`.
.. method:: ZipFile.infolist()
Return a list containing a :class:`ZipInfo` object for each member of the
archive. The objects are in the same order as their entries in the actual ZIP
file on disk if an existing archive was opened.
.. method:: ZipFile.namelist()
Return a list of archive members by name.
.. index::
single: universal newlines; zipfile.ZipFile.open method
.. method:: ZipFile.open(name[, mode[, pwd]])
Extract a member from the archive as a file-like object (ZipExtFile). *name* is
the name of the file in the archive, or a :class:`ZipInfo` object. The *mode*
parameter, if included, must be one of the following: ``'r'`` (the default),
``'U'``, or ``'rU'``. Choosing ``'U'`` or ``'rU'`` will enable
:term:`universal newline <universal newlines>`
support in the read-only object. *pwd* is the password used for encrypted files.
Calling :meth:`.open` on a closed ZipFile will raise a :exc:`RuntimeError`.
.. note::
The file-like object is read-only and provides the following methods:
:meth:`~file.read`, :meth:`~file.readline`,
:meth:`~file.readlines`, :meth:`__iter__`,
:meth:`~object.next`.
.. note::
If the ZipFile was created by passing in a file-like object as the first
argument to the constructor, then the object returned by :meth:`.open` shares the
ZipFile's file pointer. Under these circumstances, the object returned by
:meth:`.open` should not be used after any additional operations are performed
on the ZipFile object. If the ZipFile was created by passing in a string (the
filename) as the first argument to the constructor, then :meth:`.open` will
create a new file object that will be held by the ZipExtFile, allowing it to
operate independently of the ZipFile.
.. note::
The :meth:`.open`, :meth:`read` and :meth:`extract` methods can take a filename
or a :class:`ZipInfo` object. You will appreciate this when trying to read a
ZIP file that contains members with duplicate names.
.. versionadded:: 2.6
.. method:: ZipFile.extract(member[, path[, pwd]])
Extract a member from the archive to the current working directory; *member*
must be its full name or a :class:`ZipInfo` object). Its file information is
extracted as accurately as possible. *path* specifies a different directory
to extract to. *member* can be a filename or a :class:`ZipInfo` object.
*pwd* is the password used for encrypted files.
Returns the normalized path created (a directory or new file).
.. versionadded:: 2.6
.. note::
If a member filename is an absolute path, a drive/UNC sharepoint and
leading (back)slashes will be stripped, e.g.: ``///foo/bar`` becomes
``foo/bar`` on Unix, and ``C:\foo\bar`` becomes ``foo\bar`` on Windows.
And all ``".."`` components in a member filename will be removed, e.g.:
``../../foo../../ba..r`` becomes ``foo../ba..r``. On Windows illegal
characters (``:``, ``<``, ``>``, ``|``, ``"``, ``?``, and ``*``)
replaced by underscore (``_``).
.. method:: ZipFile.extractall([path[, members[, pwd]]])
Extract all members from the archive to the current working directory. *path*
specifies a different directory to extract to. *members* is optional and must
be a subset of the list returned by :meth:`namelist`. *pwd* is the password
used for encrypted files.
.. warning::
Never extract archives from untrusted sources without prior inspection.
It is possible that files are created outside of *path*, e.g. members
that have absolute filenames starting with ``"/"`` or filenames with two
dots ``".."``.
.. versionchanged:: 2.7.4
The zipfile module attempts to prevent that. See :meth:`extract` note.
.. versionadded:: 2.6
.. method:: ZipFile.printdir()
Print a table of contents for the archive to ``sys.stdout``.
.. method:: ZipFile.setpassword(pwd)
Set *pwd* as default password to extract encrypted files.
.. versionadded:: 2.6
.. method:: ZipFile.read(name[, pwd])
Return the bytes of the file *name* in the archive. *name* is the name of the
file in the archive, or a :class:`ZipInfo` object. The archive must be open for
read or append. *pwd* is the password used for encrypted files and, if specified,
it will override the default password set with :meth:`setpassword`. Calling
:meth:`read` on a closed ZipFile will raise a :exc:`RuntimeError`.
.. versionchanged:: 2.6
*pwd* was added, and *name* can now be a :class:`ZipInfo` object.
.. method:: ZipFile.testzip()
Read all the files in the archive and check their CRC's and file headers.
Return the name of the first bad file, or else return ``None``. Calling
:meth:`testzip` on a closed ZipFile will raise a :exc:`RuntimeError`.
.. method:: ZipFile.write(filename[, arcname[, compress_type]])
Write the file named *filename* to the archive, giving it the archive name
*arcname* (by default, this will be the same as *filename*, but without a drive
letter and with leading path separators removed). If given, *compress_type*
overrides the value given for the *compression* parameter to the constructor for
the new entry. The archive must be open with mode ``'w'`` or ``'a'`` -- calling
:meth:`write` on a ZipFile created with mode ``'r'`` will raise a
:exc:`RuntimeError`. Calling :meth:`write` on a closed ZipFile will raise a
:exc:`RuntimeError`.
.. note::
There is no official file name encoding for ZIP files. If you have unicode file
names, you must convert them to byte strings in your desired encoding before
passing them to :meth:`write`. WinZip interprets all file names as encoded in
CP437, also known as DOS Latin.
.. note::
Archive names should be relative to the archive root, that is, they should not
start with a path separator.
.. note::
If ``arcname`` (or ``filename``, if ``arcname`` is not given) contains a null
byte, the name of the file in the archive will be truncated at the null byte.
.. method:: ZipFile.writestr(zinfo_or_arcname, bytes[, compress_type])
Write the string *bytes* to the archive; *zinfo_or_arcname* is either the file
name it will be given in the archive, or a :class:`ZipInfo` instance. If it's
an instance, at least the filename, date, and time must be given. If it's a
name, the date and time is set to the current date and time. The archive must be
opened with mode ``'w'`` or ``'a'`` -- calling :meth:`writestr` on a ZipFile
created with mode ``'r'`` will raise a :exc:`RuntimeError`. Calling
:meth:`writestr` on a closed ZipFile will raise a :exc:`RuntimeError`.
If given, *compress_type* overrides the value given for the *compression*
parameter to the constructor for the new entry, or in the *zinfo_or_arcname*
(if that is a :class:`ZipInfo` instance).
.. note::
When passing a :class:`ZipInfo` instance as the *zinfo_or_arcname* parameter,
the compression method used will be that specified in the *compress_type*
member of the given :class:`ZipInfo` instance. By default, the
:class:`ZipInfo` constructor sets this member to :const:`ZIP_STORED`.
.. versionchanged:: 2.7
The *compress_type* argument.
The following data attributes are also available:
.. attribute:: ZipFile.debug
The level of debug output to use. This may be set from ``0`` (the default, no
output) to ``3`` (the most output). Debugging information is written to
``sys.stdout``.
.. attribute:: ZipFile.comment
The comment text associated with the ZIP file. If assigning a comment to a
:class:`ZipFile` instance created with mode 'a' or 'w', this should be a
string no longer than 65535 bytes. Comments longer than this will be
truncated in the written archive when :meth:`.close` is called.
.. _pyzipfile-objects:
PyZipFile Objects
-----------------
The :class:`PyZipFile` constructor takes the same parameters as the
:class:`ZipFile` constructor. Instances have one method in addition to those of
:class:`ZipFile` objects.
.. method:: PyZipFile.writepy(pathname[, basename])
Search for files :file:`\*.py` and add the corresponding file to the archive.
The corresponding file is a :file:`\*.pyo` file if available, else a
:file:`\*.pyc` file, compiling if necessary. If the pathname is a file, the
filename must end with :file:`.py`, and just the (corresponding
:file:`\*.py[co]`) file is added at the top level (no path information). If the
pathname is a file that does not end with :file:`.py`, a :exc:`RuntimeError`
will be raised. If it is a directory, and the directory is not a package
directory, then all the files :file:`\*.py[co]` are added at the top level. If
the directory is a package directory, then all :file:`\*.py[co]` are added under
the package name as a file path, and if any subdirectories are package
directories, all of these are added recursively. *basename* is intended for
internal use only. The :meth:`writepy` method makes archives with file names
like this::
string.pyc # Top level name
test/__init__.pyc # Package directory
test/test_support.pyc # Module test.test_support
test/bogus/__init__.pyc # Subpackage directory
test/bogus/myfile.pyc # Submodule test.bogus.myfile
.. _zipinfo-objects:
ZipInfo Objects
---------------
Instances of the :class:`ZipInfo` class are returned by the :meth:`.getinfo` and
:meth:`.infolist` methods of :class:`ZipFile` objects. Each object stores
information about a single member of the ZIP archive.
Instances have the following attributes:
.. attribute:: ZipInfo.filename
Name of the file in the archive.
.. attribute:: ZipInfo.date_time
The time and date of the last modification to the archive member. This is a
tuple of six values:
+-------+--------------------------+
| Index | Value |
+=======+==========================+
| ``0`` | Year (>= 1980) |
+-------+--------------------------+
| ``1`` | Month (one-based) |
+-------+--------------------------+
| ``2`` | Day of month (one-based) |
+-------+--------------------------+
| ``3`` | Hours (zero-based) |
+-------+--------------------------+
| ``4`` | Minutes (zero-based) |
+-------+--------------------------+
| ``5`` | Seconds (zero-based) |
+-------+--------------------------+
.. note::
The ZIP file format does not support timestamps before 1980.
.. attribute:: ZipInfo.compress_type
Type of compression for the archive member.
.. attribute:: ZipInfo.comment
Comment for the individual archive member.
.. attribute:: ZipInfo.extra
Expansion field data. The `PKZIP Application Note`_ contains
some comments on the internal structure of the data contained in this string.
.. attribute:: ZipInfo.create_system
System which created ZIP archive.
.. attribute:: ZipInfo.create_version
PKZIP version which created ZIP archive.
.. attribute:: ZipInfo.extract_version
PKZIP version needed to extract archive.
.. attribute:: ZipInfo.reserved
Must be zero.
.. attribute:: ZipInfo.flag_bits
ZIP flag bits.
.. attribute:: ZipInfo.volume
Volume number of file header.
.. attribute:: ZipInfo.internal_attr
Internal attributes.
.. attribute:: ZipInfo.external_attr
External file attributes.
.. attribute:: ZipInfo.header_offset
Byte offset to the file header.
.. attribute:: ZipInfo.CRC
CRC-32 of the uncompressed file.
.. attribute:: ZipInfo.compress_size
Size of the compressed data.
.. attribute:: ZipInfo.file_size
Size of the uncompressed file.
.. _zipfile-commandline:
.. program:: zipfile
Command-Line Interface
----------------------
The :mod:`zipfile` module provides a simple command-line interface to interact
with ZIP archives.
If you want to create a new ZIP archive, specify its name after the :option:`-c`
option and then list the filename(s) that should be included:
.. code-block:: shell-session
$ python -m zipfile -c monty.zip spam.txt eggs.txt
Passing a directory is also acceptable:
.. code-block:: shell-session
$ python -m zipfile -c monty.zip life-of-brian_1979/
If you want to extract a ZIP archive into the specified directory, use
the :option:`-e` option:
.. code-block:: shell-session
$ python -m zipfile -e monty.zip target-dir/
For a list of the files in a ZIP archive, use the :option:`-l` option:
.. code-block:: shell-session
$ python -m zipfile -l monty.zip
Command-line options
~~~~~~~~~~~~~~~~~~~~
.. cmdoption:: -l <zipfile>
List files in a zipfile.
.. cmdoption:: -c <zipfile> <source1> ... <sourceN>
Create zipfile from source files.
.. cmdoption:: -e <zipfile> <output_dir>
Extract zipfile into target directory.
.. cmdoption:: -t <zipfile>
Test whether the zipfile is valid or not.
.. _PKZIP Application Note: https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT
PK
%�\6a��E E ' html/_sources/library/zipimport.rst.txtnu �[���
:mod:`zipimport` --- Import modules from Zip archives
=====================================================
.. module:: zipimport
:synopsis: support for importing Python modules from ZIP archives.
.. moduleauthor:: Just van Rossum <just@letterror.com>
.. versionadded:: 2.3
This module adds the ability to import Python modules (:file:`\*.py`,
:file:`\*.py[co]`) and packages from ZIP-format archives. It is usually not
needed to use the :mod:`zipimport` module explicitly; it is automatically used
by the built-in :keyword:`import` mechanism for :data:`sys.path` items that are paths
to ZIP archives.
Typically, :data:`sys.path` is a list of directory names as strings. This module
also allows an item of :data:`sys.path` to be a string naming a ZIP file archive.
The ZIP archive can contain a subdirectory structure to support package imports,
and a path within the archive can be specified to only import from a
subdirectory. For example, the path :file:`example.zip/lib/` would only
import from the :file:`lib/` subdirectory within the archive.
Any files may be present in the ZIP archive, but only files :file:`.py` and
:file:`.py[co]` are available for import. ZIP import of dynamic modules
(:file:`.pyd`, :file:`.so`) is disallowed. Note that if an archive only contains
:file:`.py` files, Python will not attempt to modify the archive by adding the
corresponding :file:`.pyc` or :file:`.pyo` file, meaning that if a ZIP archive
doesn't contain :file:`.pyc` files, importing may be rather slow.
Using the built-in :func:`reload` function will fail if called on a module
loaded from a ZIP archive; it is unlikely that :func:`reload` would be needed,
since this would imply that the ZIP has been altered during runtime.
ZIP archives with an archive comment are currently not supported.
.. seealso::
`PKZIP Application Note <https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT>`_
Documentation on the ZIP file format by Phil Katz, the creator of the format and
algorithms used.
:pep:`273` - Import Modules from Zip Archives
Written by James C. Ahlstrom, who also provided an implementation. Python 2.3
follows the specification in PEP 273, but uses an implementation written by Just
van Rossum that uses the import hooks described in PEP 302.
:pep:`302` - New Import Hooks
The PEP to add the import hooks that help this module work.
This module defines an exception:
.. exception:: ZipImportError
Exception raised by zipimporter objects. It's a subclass of :exc:`ImportError`,
so it can be caught as :exc:`ImportError`, too.
.. _zipimporter-objects:
zipimporter Objects
-------------------
:class:`zipimporter` is the class for importing ZIP files.
.. class:: zipimporter(archivepath)
Create a new zipimporter instance. *archivepath* must be a path to a ZIP
file, or to a specific path within a ZIP file. For example, an *archivepath*
of :file:`foo/bar.zip/lib` will look for modules in the :file:`lib` directory
inside the ZIP file :file:`foo/bar.zip` (provided that it exists).
:exc:`ZipImportError` is raised if *archivepath* doesn't point to a valid ZIP
archive.
.. method:: find_module(fullname[, path])
Search for a module specified by *fullname*. *fullname* must be the fully
qualified (dotted) module name. It returns the zipimporter instance itself
if the module was found, or :const:`None` if it wasn't. The optional
*path* argument is ignored---it's there for compatibility with the
importer protocol.
.. method:: get_code(fullname)
Return the code object for the specified module. Raise
:exc:`ZipImportError` if the module couldn't be found.
.. method:: get_data(pathname)
Return the data associated with *pathname*. Raise :exc:`IOError` if the
file wasn't found.
.. method:: get_filename(fullname)
Return the value ``__file__`` would be set to if the specified module
was imported. Raise :exc:`ZipImportError` if the module couldn't be
found.
.. versionadded:: 2.7
.. method:: get_source(fullname)
Return the source code for the specified module. Raise
:exc:`ZipImportError` if the module couldn't be found, return
:const:`None` if the archive does contain the module, but has no source
for it.
.. method:: is_package(fullname)
Return ``True`` if the module specified by *fullname* is a package. Raise
:exc:`ZipImportError` if the module couldn't be found.
.. method:: load_module(fullname)
Load the module specified by *fullname*. *fullname* must be the fully
qualified (dotted) module name. It returns the imported module, or raises
:exc:`ZipImportError` if it wasn't found.
.. attribute:: archive
The file name of the importer's associated ZIP file, without a possible
subpath.
.. attribute:: prefix
The subpath within the ZIP file where modules are searched. This is the
empty string for zipimporter objects which point to the root of the ZIP
file.
The :attr:`archive` and :attr:`prefix` attributes, when combined with a
slash, equal the original *archivepath* argument given to the
:class:`zipimporter` constructor.
.. _zipimport-examples:
Examples
--------
Here is an example that imports a module from a ZIP archive - note that the
:mod:`zipimport` module is not explicitly used.
.. code-block:: shell-session
$ unzip -l example.zip
Archive: example.zip
Length Date Time Name
-------- ---- ---- ----
8467 11-26-02 22:30 jwzthreading.py
-------- -------
8467 1 file
$ ./python
Python 2.3 (#1, Aug 1 2003, 19:54:32)
>>> import sys
>>> sys.path.insert(0, 'example.zip') # Add .zip file to front of path
>>> import jwzthreading
>>> jwzthreading.__file__
'example.zip/jwzthreading.py'
PK
%�\lZݦ�1 �1 " html/_sources/library/zlib.rst.txtnu �[���
:mod:`zlib` --- Compression compatible with :program:`gzip`
===========================================================
.. module:: zlib
:synopsis: Low-level interface to compression and decompression routines compatible with
gzip.
For applications that require data compression, the functions in this module
allow compression and decompression, using the zlib library. The zlib library
has its own home page at http://www.zlib.net. There are known
incompatibilities between the Python module and versions of the zlib library
earlier than 1.1.3; 1.1.3 has a security vulnerability, so we recommend using
1.1.4 or later.
zlib's functions have many options and often need to be used in a particular
order. This documentation doesn't attempt to cover all of the permutations;
consult the zlib manual at http://www.zlib.net/manual.html for authoritative
information.
For reading and writing ``.gz`` files see the :mod:`gzip` module.
The available exception and functions in this module are:
.. exception:: error
Exception raised on compression and decompression errors.
.. function:: adler32(data[, value])
Computes an Adler-32 checksum of *data*. (An Adler-32 checksum is almost as
reliable as a CRC32 but can be computed much more quickly.) If *value* is
present, it is used as the starting value of the checksum; otherwise, a fixed
default value is used. This allows computing a running checksum over the
concatenation of several inputs. The algorithm is not cryptographically
strong, and should not be used for authentication or digital signatures. Since
the algorithm is designed for use as a checksum algorithm, it is not suitable
for use as a general hash algorithm.
This function always returns an integer object.
.. note::
To generate the same numeric value across all Python versions and
platforms use adler32(data) & 0xffffffff. If you are only using
the checksum in packed binary format this is not necessary as the
return value is the correct 32bit binary representation
regardless of sign.
.. versionchanged:: 2.6
The return value is in the range [-2**31, 2**31-1]
regardless of platform. In older versions the value is
signed on some platforms and unsigned on others.
.. versionchanged:: 3.0
The return value is unsigned and in the range [0, 2**32-1]
regardless of platform.
.. function:: compress(string[, level])
Compresses the data in *string*, returning a string contained compressed data.
*level* is an integer from ``0`` to ``9`` controlling the level of compression;
``1`` is fastest and produces the least compression, ``9`` is slowest and
produces the most. ``0`` is no compression. The default value is ``6``.
Raises the :exc:`error` exception if any error occurs.
.. function:: compressobj([level[, method[, wbits[, memlevel[, strategy]]]]])
Returns a compression object, to be used for compressing data streams that won't
fit into memory at once. *level* is an integer from
``0`` to ``9`` or ``-1``, controlling
the level of compression; ``1`` is fastest and produces the least compression,
``9`` is slowest and produces the most. ``0`` is no compression. The default
value is ``-1`` (Z_DEFAULT_COMPRESSION). Z_DEFAULT_COMPRESSION represents a default
compromise between speed and compression (currently equivalent to level 6).
*method* is the compression algorithm. Currently, the only supported value is
``DEFLATED``.
The *wbits* argument controls the size of the history buffer (or the
"window size") used when compressing data, and whether a header and
trailer is included in the output. It can take several ranges of values.
The default is 15.
* +9 to +15: The base-two logarithm of the window size, which
therefore ranges between 512 and 32768. Larger values produce
better compression at the expense of greater memory usage. The
resulting output will include a zlib-specific header and trailer.
* −9 to −15: Uses the absolute value of *wbits* as the
window size logarithm, while producing a raw output stream with no
header or trailing checksum.
* +25 to +31 = 16 + (9 to 15): Uses the low 4 bits of the value as the
window size logarithm, while including a basic :program:`gzip` header
and trailing checksum in the output.
*memlevel* controls the amount of memory used for internal compression state.
Valid values range from ``1`` to ``9``. Higher values using more memory,
but are faster and produce smaller output. The default is 8.
*strategy* is used to tune the compression algorithm. Possible values are
``Z_DEFAULT_STRATEGY``, ``Z_FILTERED``, and ``Z_HUFFMAN_ONLY``. The default
is ``Z_DEFAULT_STRATEGY``.
.. function:: crc32(data[, value])
.. index::
single: Cyclic Redundancy Check
single: checksum; Cyclic Redundancy Check
Computes a CRC (Cyclic Redundancy Check) checksum of *data*. If *value* is
present, it is used as the starting value of the checksum; otherwise, a fixed
default value is used. This allows computing a running checksum over the
concatenation of several inputs. The algorithm is not cryptographically
strong, and should not be used for authentication or digital signatures. Since
the algorithm is designed for use as a checksum algorithm, it is not suitable
for use as a general hash algorithm.
This function always returns an integer object.
.. note::
To generate the same numeric value across all Python versions and
platforms use crc32(data) & 0xffffffff. If you are only using
the checksum in packed binary format this is not necessary as the
return value is the correct 32bit binary representation
regardless of sign.
.. versionchanged:: 2.6
The return value is in the range [-2**31, 2**31-1]
regardless of platform. In older versions the value would be
signed on some platforms and unsigned on others.
.. versionchanged:: 3.0
The return value is unsigned and in the range [0, 2**32-1]
regardless of platform.
.. function:: decompress(string[, wbits[, bufsize]])
Decompresses the data in *string*, returning a string containing the
uncompressed data. The *wbits* parameter depends on
the format of *string*, and is discussed further below.
If *bufsize* is given, it is used as the initial size of the output
buffer. Raises the :exc:`error` exception if any error occurs.
.. _decompress-wbits:
The *wbits* parameter controls the size of the history buffer
(or "window size"), and what header and trailer format is expected.
It is similar to the parameter for :func:`compressobj`, but accepts
more ranges of values:
* +8 to +15: The base-two logarithm of the window size. The input
must include a zlib header and trailer.
* 0: Automatically determine the window size from the zlib header.
Only supported since zlib 1.2.3.5.
* −8 to −15: Uses the absolute value of *wbits* as the window size
logarithm. The input must be a raw stream with no header or trailer.
* +24 to +31 = 16 + (8 to 15): Uses the low 4 bits of the value as
the window size logarithm. The input must include a gzip header and
trailer.
* +40 to +47 = 32 + (8 to 15): Uses the low 4 bits of the value as
the window size logarithm, and automatically accepts either
the zlib or gzip format.
When decompressing a stream, the window size must not be smaller
than the size originally used to compress the stream; using a too-small
value may result in an :exc:`error` exception. The default *wbits* value
is 15, which corresponds to the largest window size and requires a zlib
header and trailer to be included.
*bufsize* is the initial size of the buffer used to hold decompressed data. If
more space is required, the buffer size will be increased as needed, so you
don't have to get this value exactly right; tuning it will only save a few calls
to :c:func:`malloc`. The default size is 16384.
.. function:: decompressobj([wbits])
Returns a decompression object, to be used for decompressing data streams that
won't fit into memory at once.
The *wbits* parameter controls the size of the history buffer (or the
"window size"), and what header and trailer format is expected. It has
the same meaning as `described for decompress() <#decompress-wbits>`__.
Compression objects support the following methods:
.. method:: Compress.compress(string)
Compress *string*, returning a string containing compressed data for at least
part of the data in *string*. This data should be concatenated to the output
produced by any preceding calls to the :meth:`compress` method. Some input may
be kept in internal buffers for later processing.
.. method:: Compress.flush([mode])
All pending input is processed, and a string containing the remaining compressed
output is returned. *mode* can be selected from the constants
:const:`Z_SYNC_FLUSH`, :const:`Z_FULL_FLUSH`, or :const:`Z_FINISH`,
defaulting to :const:`Z_FINISH`. :const:`Z_SYNC_FLUSH` and
:const:`Z_FULL_FLUSH` allow compressing further strings of data, while
:const:`Z_FINISH` finishes the compressed stream and prevents compressing any
more data. After calling :meth:`flush` with *mode* set to :const:`Z_FINISH`,
the :meth:`compress` method cannot be called again; the only realistic action is
to delete the object.
.. method:: Compress.copy()
Returns a copy of the compression object. This can be used to efficiently
compress a set of data that share a common initial prefix.
.. versionadded:: 2.5
Decompression objects support the following methods, and two attributes:
.. attribute:: Decompress.unused_data
A string which contains any bytes past the end of the compressed data. That is,
this remains ``""`` until the last byte that contains compression data is
available. If the whole string turned out to contain compressed data, this is
``""``, the empty string.
The only way to determine where a string of compressed data ends is by actually
decompressing it. This means that when compressed data is contained part of a
larger file, you can only find the end of it by reading data and feeding it
followed by some non-empty string into a decompression object's
:meth:`decompress` method until the :attr:`unused_data` attribute is no longer
the empty string.
.. attribute:: Decompress.unconsumed_tail
A string that contains any data that was not consumed by the last
:meth:`decompress` call because it exceeded the limit for the uncompressed data
buffer. This data has not yet been seen by the zlib machinery, so you must feed
it (possibly with further data concatenated to it) back to a subsequent
:meth:`decompress` method call in order to get correct output.
.. method:: Decompress.decompress(string[, max_length])
Decompress *string*, returning a string containing the uncompressed data
corresponding to at least part of the data in *string*. This data should be
concatenated to the output produced by any preceding calls to the
:meth:`decompress` method. Some of the input data may be preserved in internal
buffers for later processing.
If the optional parameter *max_length* is non-zero then the return value will be
no longer than *max_length*. This may mean that not all of the compressed input
can be processed; and unconsumed data will be stored in the attribute
:attr:`unconsumed_tail`. This string must be passed to a subsequent call to
:meth:`decompress` if decompression is to continue. If *max_length* is not
supplied then the whole input is decompressed, and :attr:`unconsumed_tail` is an
empty string.
.. method:: Decompress.flush([length])
All pending input is processed, and a string containing the remaining
uncompressed output is returned. After calling :meth:`flush`, the
:meth:`decompress` method cannot be called again; the only realistic action is
to delete the object.
The optional parameter *length* sets the initial size of the output buffer.
.. method:: Decompress.copy()
Returns a copy of the decompression object. This can be used to save the state
of the decompressor midway through the data stream in order to speed up random
seeks into the stream at a future point.
.. versionadded:: 2.5
.. seealso::
Module :mod:`gzip`
Reading and writing :program:`gzip`\ -format files.
http://www.zlib.net
The zlib library home page.
http://www.zlib.net/manual.html
The zlib manual explains the semantics and usage of the library's many
functions.
PK
%�\[��� \ \ . html/_sources/reference/compound_stmts.rst.txtnu �[��� .. _compound:
*******************
Compound statements
*******************
.. index:: pair: compound; statement
Compound statements contain (groups of) other statements; they affect or control
the execution of those other statements in some way. In general, compound
statements span multiple lines, although in simple incarnations a whole compound
statement may be contained in one line.
The :keyword:`if`, :keyword:`while` and :keyword:`for` statements implement
traditional control flow constructs. :keyword:`try` specifies exception
handlers and/or cleanup code for a group of statements. Function and class
definitions are also syntactically compound statements.
.. index::
single: clause
single: suite
Compound statements consist of one or more 'clauses.' A clause consists of a
header and a 'suite.' The clause headers of a particular compound statement are
all at the same indentation level. Each clause header begins with a uniquely
identifying keyword and ends with a colon. A suite is a group of statements
controlled by a clause. A suite can be one or more semicolon-separated simple
statements on the same line as the header, following the header's colon, or it
can be one or more indented statements on subsequent lines. Only the latter
form of suite can contain nested compound statements; the following is illegal,
mostly because it wouldn't be clear to which :keyword:`if` clause a following
:keyword:`else` clause would belong: ::
if test1: if test2: print x
Also note that the semicolon binds tighter than the colon in this context, so
that in the following example, either all or none of the :keyword:`print`
statements are executed::
if x < y < z: print x; print y; print z
Summarizing:
.. productionlist::
compound_stmt: `if_stmt`
: | `while_stmt`
: | `for_stmt`
: | `try_stmt`
: | `with_stmt`
: | `funcdef`
: | `classdef`
: | `decorated`
suite: `stmt_list` NEWLINE | NEWLINE INDENT `statement`+ DEDENT
statement: `stmt_list` NEWLINE | `compound_stmt`
stmt_list: `simple_stmt` (";" `simple_stmt`)* [";"]
.. index::
single: NEWLINE token
single: DEDENT token
pair: dangling; else
Note that statements always end in a ``NEWLINE`` possibly followed by a
``DEDENT``. Also note that optional continuation clauses always begin with a
keyword that cannot start a statement, thus there are no ambiguities (the
'dangling :keyword:`else`' problem is solved in Python by requiring nested
:keyword:`if` statements to be indented).
The formatting of the grammar rules in the following sections places each clause
on a separate line for clarity.
.. _if:
.. _elif:
.. _else:
The :keyword:`if` statement
===========================
.. index::
statement: if
keyword: elif
keyword: else
The :keyword:`if` statement is used for conditional execution:
.. productionlist::
if_stmt: "if" `expression` ":" `suite`
: ( "elif" `expression` ":" `suite` )*
: ["else" ":" `suite`]
It selects exactly one of the suites by evaluating the expressions one by one
until one is found to be true (see section :ref:`booleans` for the definition of
true and false); then that suite is executed (and no other part of the
:keyword:`if` statement is executed or evaluated). If all expressions are
false, the suite of the :keyword:`else` clause, if present, is executed.
.. _while:
The :keyword:`while` statement
==============================
.. index::
statement: while
pair: loop; statement
keyword: else
The :keyword:`while` statement is used for repeated execution as long as an
expression is true:
.. productionlist::
while_stmt: "while" `expression` ":" `suite`
: ["else" ":" `suite`]
This repeatedly tests the expression and, if it is true, executes the first
suite; if the expression is false (which may be the first time it is tested) the
suite of the :keyword:`else` clause, if present, is executed and the loop
terminates.
.. index::
statement: break
statement: continue
A :keyword:`break` statement executed in the first suite terminates the loop
without executing the :keyword:`else` clause's suite. A :keyword:`continue`
statement executed in the first suite skips the rest of the suite and goes back
to testing the expression.
.. _for:
The :keyword:`for` statement
============================
.. index::
statement: for
pair: loop; statement
keyword: in
keyword: else
pair: target; list
object: sequence
The :keyword:`for` statement is used to iterate over the elements of a sequence
(such as a string, tuple or list) or other iterable object:
.. productionlist::
for_stmt: "for" `target_list` "in" `expression_list` ":" `suite`
: ["else" ":" `suite`]
The expression list is evaluated once; it should yield an iterable object. An
iterator is created for the result of the ``expression_list``. The suite is
then executed once for each item provided by the iterator, in the order of
ascending indices. Each item in turn is assigned to the target list using the
standard rules for assignments, and then the suite is executed. When the items
are exhausted (which is immediately when the sequence is empty), the suite in
the :keyword:`else` clause, if present, is executed, and the loop terminates.
.. index::
statement: break
statement: continue
A :keyword:`break` statement executed in the first suite terminates the loop
without executing the :keyword:`else` clause's suite. A :keyword:`continue`
statement executed in the first suite skips the rest of the suite and continues
with the next item, or with the :keyword:`else` clause if there was no next
item.
The suite may assign to the variable(s) in the target list; this does not affect
the next item assigned to it.
.. index::
builtin: range
pair: Pascal; language
The target list is not deleted when the loop is finished, but if the sequence is
empty, it will not have been assigned to at all by the loop. Hint: the built-in
function :func:`range` returns a sequence of integers suitable to emulate the
effect of Pascal's ``for i := a to b do``; e.g., ``range(3)`` returns the list
``[0, 1, 2]``.
.. note::
.. index::
single: loop; over mutable sequence
single: mutable sequence; loop over
There is a subtlety when the sequence is being modified by the loop (this can
only occur for mutable sequences, e.g. lists). An internal counter is used to
keep track of which item is used next, and this is incremented on each
iteration. When this counter has reached the length of the sequence the loop
terminates. This means that if the suite deletes the current (or a previous)
item from the sequence, the next item will be skipped (since it gets the index
of the current item which has already been treated). Likewise, if the suite
inserts an item in the sequence before the current item, the current item will
be treated again the next time through the loop. This can lead to nasty bugs
that can be avoided by making a temporary copy using a slice of the whole
sequence, e.g., ::
for x in a[:]:
if x < 0: a.remove(x)
.. _try:
.. _except:
.. _finally:
The :keyword:`try` statement
============================
.. index::
statement: try
keyword: except
keyword: finally
The :keyword:`try` statement specifies exception handlers and/or cleanup code
for a group of statements:
.. productionlist::
try_stmt: try1_stmt | try2_stmt
try1_stmt: "try" ":" `suite`
: ("except" [`expression` [("as" | ",") `identifier`]] ":" `suite`)+
: ["else" ":" `suite`]
: ["finally" ":" `suite`]
try2_stmt: "try" ":" `suite`
: "finally" ":" `suite`
.. versionchanged:: 2.5
In previous versions of Python, :keyword:`try`...\ :keyword:`except`...\
:keyword:`finally` did not work. :keyword:`try`...\ :keyword:`except` had to be
nested in :keyword:`try`...\ :keyword:`finally`.
The :keyword:`except` clause(s) specify one or more exception handlers. When no
exception occurs in the :keyword:`try` clause, no exception handler is executed.
When an exception occurs in the :keyword:`try` suite, a search for an exception
handler is started. This search inspects the except clauses in turn until one
is found that matches the exception. An expression-less except clause, if
present, must be last; it matches any exception. For an except clause with an
expression, that expression is evaluated, and the clause matches the exception
if the resulting object is "compatible" with the exception. An object is
compatible with an exception if it is the class or a base class of the exception
object, or a tuple containing an item compatible with the exception.
If no except clause matches the exception, the search for an exception handler
continues in the surrounding code and on the invocation stack. [#]_
If the evaluation of an expression in the header of an except clause raises an
exception, the original search for a handler is canceled and a search starts for
the new exception in the surrounding code and on the call stack (it is treated
as if the entire :keyword:`try` statement raised the exception).
When a matching except clause is found, the exception is assigned to the target
specified in that except clause, if present, and the except clause's suite is
executed. All except clauses must have an executable block. When the end of
this block is reached, execution continues normally after the entire try
statement. (This means that if two nested handlers exist for the same
exception, and the exception occurs in the try clause of the inner handler, the
outer handler will not handle the exception.)
.. index::
module: sys
object: traceback
single: exc_type (in module sys)
single: exc_value (in module sys)
single: exc_traceback (in module sys)
Before an except clause's suite is executed, details about the exception are
assigned to three variables in the :mod:`sys` module: ``sys.exc_type`` receives
the object identifying the exception; ``sys.exc_value`` receives the exception's
parameter; ``sys.exc_traceback`` receives a traceback object (see section
:ref:`types`) identifying the point in the program where the exception
occurred. These details are also available through the :func:`sys.exc_info`
function, which returns a tuple ``(exc_type, exc_value, exc_traceback)``. Use
of the corresponding variables is deprecated in favor of this function, since
their use is unsafe in a threaded program. As of Python 1.5, the variables are
restored to their previous values (before the call) when returning from a
function that handled an exception.
.. index::
keyword: else
statement: return
statement: break
statement: continue
The optional :keyword:`else` clause is executed if the control flow leaves the
:keyword:`try` suite, no exception was raised, and no :keyword:`return`,
:keyword:`continue`, or :keyword:`break` statement was executed. Exceptions in
the :keyword:`else` clause are not handled by the preceding :keyword:`except`
clauses.
.. index:: keyword: finally
If :keyword:`finally` is present, it specifies a 'cleanup' handler. The
:keyword:`try` clause is executed, including any :keyword:`except` and
:keyword:`else` clauses. If an exception occurs in any of the clauses and is
not handled, the exception is temporarily saved. The :keyword:`finally` clause
is executed. If there is a saved exception, it is re-raised at the end of the
:keyword:`finally` clause. If the :keyword:`finally` clause raises another
exception or executes a :keyword:`return` or :keyword:`break` statement, the
saved exception is discarded::
>>> def f():
... try:
... 1/0
... finally:
... return 42
...
>>> f()
42
The exception information is not available to the program during execution of
the :keyword:`finally` clause.
.. index::
statement: return
statement: break
statement: continue
When a :keyword:`return`, :keyword:`break` or :keyword:`continue` statement is
executed in the :keyword:`try` suite of a :keyword:`try`...\ :keyword:`finally`
statement, the :keyword:`finally` clause is also executed 'on the way out.' A
:keyword:`continue` statement is illegal in the :keyword:`finally` clause. (The
reason is a problem with the current implementation --- this restriction may be
lifted in the future).
The return value of a function is determined by the last :keyword:`return`
statement executed. Since the :keyword:`finally` clause always executes, a
:keyword:`return` statement executed in the :keyword:`finally` clause will
always be the last one executed::
>>> def foo():
... try:
... return 'try'
... finally:
... return 'finally'
...
>>> foo()
'finally'
Additional information on exceptions can be found in section :ref:`exceptions`,
and information on using the :keyword:`raise` statement to generate exceptions
may be found in section :ref:`raise`.
.. _with:
.. _as:
The :keyword:`with` statement
=============================
.. index::
statement: with
single: as; with statement
.. versionadded:: 2.5
The :keyword:`with` statement is used to wrap the execution of a block with
methods defined by a context manager (see section :ref:`context-managers`). This
allows common :keyword:`try`...\ :keyword:`except`...\ :keyword:`finally` usage
patterns to be encapsulated for convenient reuse.
.. productionlist::
with_stmt: "with" with_item ("," with_item)* ":" `suite`
with_item: `expression` ["as" `target`]
The execution of the :keyword:`with` statement with one "item" proceeds as follows:
#. The context expression (the expression given in the :token:`with_item`) is
evaluated to obtain a context manager.
#. The context manager's :meth:`__exit__` is loaded for later use.
#. The context manager's :meth:`__enter__` method is invoked.
#. If a target was included in the :keyword:`with` statement, the return value
from :meth:`__enter__` is assigned to it.
.. note::
The :keyword:`with` statement guarantees that if the :meth:`__enter__` method
returns without an error, then :meth:`__exit__` will always be called. Thus, if
an error occurs during the assignment to the target list, it will be treated the
same as an error occurring within the suite would be. See step 6 below.
#. The suite is executed.
#. The context manager's :meth:`__exit__` method is invoked. If an exception
caused the suite to be exited, its type, value, and traceback are passed as
arguments to :meth:`__exit__`. Otherwise, three :const:`None` arguments are
supplied.
If the suite was exited due to an exception, and the return value from the
:meth:`__exit__` method was false, the exception is reraised. If the return
value was true, the exception is suppressed, and execution continues with the
statement following the :keyword:`with` statement.
If the suite was exited for any reason other than an exception, the return value
from :meth:`__exit__` is ignored, and execution proceeds at the normal location
for the kind of exit that was taken.
With more than one item, the context managers are processed as if multiple
:keyword:`with` statements were nested::
with A() as a, B() as b:
suite
is equivalent to ::
with A() as a:
with B() as b:
suite
.. note::
In Python 2.5, the :keyword:`with` statement is only allowed when the
``with_statement`` feature has been enabled. It is always enabled in
Python 2.6.
.. versionchanged:: 2.7
Support for multiple context expressions.
.. seealso::
:pep:`343` - The "with" statement
The specification, background, and examples for the Python :keyword:`with`
statement.
.. index::
single: parameter; function definition
.. _function:
.. _def:
Function definitions
====================
.. index::
statement: def
pair: function; definition
pair: function; name
pair: name; binding
object: user-defined function
object: function
A function definition defines a user-defined function object (see section
:ref:`types`):
.. productionlist::
decorated: decorators (classdef | funcdef)
decorators: `decorator`+
decorator: "@" `dotted_name` ["(" [`argument_list` [","]] ")"] NEWLINE
funcdef: "def" `funcname` "(" [`parameter_list`] ")" ":" `suite`
dotted_name: `identifier` ("." `identifier`)*
parameter_list: (`defparameter` ",")*
: ( "*" `identifier` ["," "**" `identifier`]
: | "**" `identifier`
: | `defparameter` [","] )
defparameter: `parameter` ["=" `expression`]
sublist: `parameter` ("," `parameter`)* [","]
parameter: `identifier` | "(" `sublist` ")"
funcname: `identifier`
A function definition is an executable statement. Its execution binds the
function name in the current local namespace to a function object (a wrapper
around the executable code for the function). This function object contains a
reference to the current global namespace as the global namespace to be used
when the function is called.
The function definition does not execute the function body; this gets executed
only when the function is called. [#]_
.. index::
statement: @
A function definition may be wrapped by one or more :term:`decorator` expressions.
Decorator expressions are evaluated when the function is defined, in the scope
that contains the function definition. The result must be a callable, which is
invoked with the function object as the only argument. The returned value is
bound to the function name instead of the function object. Multiple decorators
are applied in nested fashion. For example, the following code::
@f1(arg)
@f2
def func(): pass
is equivalent to::
def func(): pass
func = f1(arg)(f2(func))
.. index::
triple: default; parameter; value
single: argument; function definition
When one or more top-level :term:`parameters <parameter>` have the form
*parameter* ``=`` *expression*, the function is said to have "default parameter
values." For a parameter with a default value, the corresponding
:term:`argument` may be omitted from a call, in which
case the parameter's default value is substituted. If a
parameter has a default value, all following parameters must also have a default
value --- this is a syntactic restriction that is not expressed by the grammar.
**Default parameter values are evaluated when the function definition is
executed.** This means that the expression is evaluated once, when the function
is defined, and that the same "pre-computed" value is used for each call. This
is especially important to understand when a default parameter is a mutable
object, such as a list or a dictionary: if the function modifies the object
(e.g. by appending an item to a list), the default value is in effect modified.
This is generally not what was intended. A way around this is to use ``None``
as the default, and explicitly test for it in the body of the function, e.g.::
def whats_on_the_telly(penguin=None):
if penguin is None:
penguin = []
penguin.append("property of the zoo")
return penguin
.. index::
statement: *
statement: **
Function call semantics are described in more detail in section :ref:`calls`. A
function call always assigns values to all parameters mentioned in the parameter
list, either from position arguments, from keyword arguments, or from default
values. If the form "``*identifier``" is present, it is initialized to a tuple
receiving any excess positional parameters, defaulting to the empty tuple. If
the form "``**identifier``" is present, it is initialized to a new dictionary
receiving any excess keyword arguments, defaulting to a new empty dictionary.
.. index:: pair: lambda; expression
It is also possible to create anonymous functions (functions not bound to a
name), for immediate use in expressions. This uses lambda expressions, described in
section :ref:`lambda`. Note that the lambda expression is merely a shorthand for a
simplified function definition; a function defined in a ":keyword:`def`"
statement can be passed around or assigned to another name just like a function
defined by a lambda expression. The ":keyword:`def`" form is actually more powerful
since it allows the execution of multiple statements.
**Programmer's note:** Functions are first-class objects. A "``def``" form
executed inside a function definition defines a local function that can be
returned or passed around. Free variables used in the nested function can
access the local variables of the function containing the def. See section
:ref:`naming` for details.
.. _class:
Class definitions
=================
.. index::
object: class
statement: class
pair: class; definition
pair: class; name
pair: name; binding
pair: execution; frame
single: inheritance
single: docstring
A class definition defines a class object (see section :ref:`types`):
.. productionlist::
classdef: "class" `classname` [`inheritance`] ":" `suite`
inheritance: "(" [`expression_list`] ")"
classname: `identifier`
A class definition is an executable statement. It first evaluates the
inheritance list, if present. Each item in the inheritance list should evaluate
to a class object or class type which allows subclassing. The class's suite is
then executed in a new execution frame (see section :ref:`naming`), using a
newly created local namespace and the original global namespace. (Usually, the
suite contains only function definitions.) When the class's suite finishes
execution, its execution frame is discarded but its local namespace is
saved. [#]_ A class object is then created using the inheritance list for the
base classes and the saved local namespace for the attribute dictionary. The
class name is bound to this class object in the original local namespace.
**Programmer's note:** Variables defined in the class definition are class
variables; they are shared by all instances. To create instance variables, they
can be set in a method with ``self.name = value``. Both class and instance
variables are accessible through the notation "``self.name``", and an instance
variable hides a class variable with the same name when accessed in this way.
Class variables can be used as defaults for instance variables, but using
mutable values there can lead to unexpected results. For :term:`new-style
class`\es, descriptors can be used to create instance variables with different
implementation details.
Class definitions, like function definitions, may be wrapped by one or more
:term:`decorator` expressions. The evaluation rules for the decorator
expressions are the same as for functions. The result must be a class object,
which is then bound to the class name.
.. rubric:: Footnotes
.. [#] The exception is propagated to the invocation stack unless
there is a :keyword:`finally` clause which happens to raise another
exception. That new exception causes the old one to be lost.
.. [#] A string literal appearing as the first statement in the function body is
transformed into the function's ``__doc__`` attribute and therefore the
function's :term:`docstring`.
.. [#] A string literal appearing as the first statement in the class body is
transformed into the namespace's ``__doc__`` item and therefore the class's
:term:`docstring`.
PK
%�\��J��� �� ) html/_sources/reference/datamodel.rst.txtnu �[���
.. _datamodel:
**********
Data model
**********
.. _objects:
Objects, values and types
=========================
.. index::
single: object
single: data
:dfn:`Objects` are Python's abstraction for data. All data in a Python program
is represented by objects or by relations between objects. (In a sense, and in
conformance to Von Neumann's model of a "stored program computer," code is also
represented by objects.)
.. index::
builtin: id
builtin: type
single: identity of an object
single: value of an object
single: type of an object
single: mutable object
single: immutable object
Every object has an identity, a type and a value. An object's *identity* never
changes once it has been created; you may think of it as the object's address in
memory. The ':keyword:`is`' operator compares the identity of two objects; the
:func:`id` function returns an integer representing its identity (currently
implemented as its address). An object's :dfn:`type` is also unchangeable. [#]_
An object's type determines the operations that the object supports (e.g., "does
it have a length?") and also defines the possible values for objects of that
type. The :func:`type` function returns an object's type (which is an object
itself). The *value* of some objects can change. Objects whose value can
change are said to be *mutable*; objects whose value is unchangeable once they
are created are called *immutable*. (The value of an immutable container object
that contains a reference to a mutable object can change when the latter's value
is changed; however the container is still considered immutable, because the
collection of objects it contains cannot be changed. So, immutability is not
strictly the same as having an unchangeable value, it is more subtle.) An
object's mutability is determined by its type; for instance, numbers, strings
and tuples are immutable, while dictionaries and lists are mutable.
.. index::
single: garbage collection
single: reference counting
single: unreachable object
Objects are never explicitly destroyed; however, when they become unreachable
they may be garbage-collected. An implementation is allowed to postpone garbage
collection or omit it altogether --- it is a matter of implementation quality
how garbage collection is implemented, as long as no objects are collected that
are still reachable.
.. impl-detail::
CPython currently uses a reference-counting scheme with (optional) delayed
detection of cyclically linked garbage, which collects most objects as soon
as they become unreachable, but is not guaranteed to collect garbage
containing circular references. See the documentation of the :mod:`gc`
module for information on controlling the collection of cyclic garbage.
Other implementations act differently and CPython may change.
Do not depend on immediate finalization of objects when they become
unreachable (ex: always close files).
Note that the use of the implementation's tracing or debugging facilities may
keep objects alive that would normally be collectable. Also note that catching
an exception with a ':keyword:`try`...\ :keyword:`except`' statement may keep
objects alive.
Some objects contain references to "external" resources such as open files or
windows. It is understood that these resources are freed when the object is
garbage-collected, but since garbage collection is not guaranteed to happen,
such objects also provide an explicit way to release the external resource,
usually a :meth:`close` method. Programs are strongly recommended to explicitly
close such objects. The ':keyword:`try`...\ :keyword:`finally`' statement
provides a convenient way to do this.
.. index:: single: container
Some objects contain references to other objects; these are called *containers*.
Examples of containers are tuples, lists and dictionaries. The references are
part of a container's value. In most cases, when we talk about the value of a
container, we imply the values, not the identities of the contained objects;
however, when we talk about the mutability of a container, only the identities
of the immediately contained objects are implied. So, if an immutable container
(like a tuple) contains a reference to a mutable object, its value changes if
that mutable object is changed.
Types affect almost all aspects of object behavior. Even the importance of
object identity is affected in some sense: for immutable types, operations that
compute new values may actually return a reference to any existing object with
the same type and value, while for mutable objects this is not allowed. E.g.,
after ``a = 1; b = 1``, ``a`` and ``b`` may or may not refer to the same object
with the value one, depending on the implementation, but after ``c = []; d =
[]``, ``c`` and ``d`` are guaranteed to refer to two different, unique, newly
created empty lists. (Note that ``c = d = []`` assigns the same object to both
``c`` and ``d``.)
.. _types:
The standard type hierarchy
===========================
.. index::
single: type
pair: data; type
pair: type; hierarchy
pair: extension; module
pair: C; language
Below is a list of the types that are built into Python. Extension modules
(written in C, Java, or other languages, depending on the implementation) can
define additional types. Future versions of Python may add types to the type
hierarchy (e.g., rational numbers, efficiently stored arrays of integers, etc.).
.. index::
single: attribute
pair: special; attribute
triple: generic; special; attribute
Some of the type descriptions below contain a paragraph listing 'special
attributes.' These are attributes that provide access to the implementation and
are not intended for general use. Their definition may change in the future.
None
.. index:: object: None
This type has a single value. There is a single object with this value. This
object is accessed through the built-in name ``None``. It is used to signify the
absence of a value in many situations, e.g., it is returned from functions that
don't explicitly return anything. Its truth value is false.
NotImplemented
.. index:: object: NotImplemented
This type has a single value. There is a single object with this value. This
object is accessed through the built-in name ``NotImplemented``. Numeric methods
and rich comparison methods may return this value if they do not implement the
operation for the operands provided. (The interpreter will then try the
reflected operation, or some other fallback, depending on the operator.) Its
truth value is true.
Ellipsis
.. index:: object: Ellipsis
This type has a single value. There is a single object with this value. This
object is accessed through the built-in name ``Ellipsis``. It is used to
indicate the presence of the ``...`` syntax in a slice. Its truth value is
true.
:class:`numbers.Number`
.. index:: object: numeric
These are created by numeric literals and returned as results by arithmetic
operators and arithmetic built-in functions. Numeric objects are immutable;
once created their value never changes. Python numbers are of course strongly
related to mathematical numbers, but subject to the limitations of numerical
representation in computers.
Python distinguishes between integers, floating point numbers, and complex
numbers:
:class:`numbers.Integral`
.. index:: object: integer
These represent elements from the mathematical set of integers (positive and
negative).
There are three types of integers:
Plain integers
.. index::
object: plain integer
single: OverflowError (built-in exception)
These represent numbers in the range -2147483648 through 2147483647.
(The range may be larger on machines with a larger natural word size,
but not smaller.) When the result of an operation would fall outside
this range, the result is normally returned as a long integer (in some
cases, the exception :exc:`OverflowError` is raised instead). For the
purpose of shift and mask operations, integers are assumed to have a
binary, 2's complement notation using 32 or more bits, and hiding no
bits from the user (i.e., all 4294967296 different bit patterns
correspond to different values).
Long integers
.. index:: object: long integer
These represent numbers in an unlimited range, subject to available
(virtual) memory only. For the purpose of shift and mask operations, a
binary representation is assumed, and negative numbers are represented
in a variant of 2's complement which gives the illusion of an infinite
string of sign bits extending to the left.
Booleans
.. index::
object: Boolean
single: False
single: True
These represent the truth values False and True. The two objects
representing the values ``False`` and ``True`` are the only Boolean objects.
The Boolean type is a subtype of plain integers, and Boolean values
behave like the values 0 and 1, respectively, in almost all contexts,
the exception being that when converted to a string, the strings
``"False"`` or ``"True"`` are returned, respectively.
.. index:: pair: integer; representation
The rules for integer representation are intended to give the most
meaningful interpretation of shift and mask operations involving negative
integers and the least surprises when switching between the plain and long
integer domains. Any operation, if it yields a result in the plain
integer domain, will yield the same result in the long integer domain or
when using mixed operands. The switch between domains is transparent to
the programmer.
:class:`numbers.Real` (:class:`float`)
.. index::
object: floating point
pair: floating point; number
pair: C; language
pair: Java; language
These represent machine-level double precision floating point numbers. You are
at the mercy of the underlying machine architecture (and C or Java
implementation) for the accepted range and handling of overflow. Python does not
support single-precision floating point numbers; the savings in processor and
memory usage that are usually the reason for using these are dwarfed by the
overhead of using objects in Python, so there is no reason to complicate the
language with two kinds of floating point numbers.
:class:`numbers.Complex`
.. index::
object: complex
pair: complex; number
These represent complex numbers as a pair of machine-level double precision
floating point numbers. The same caveats apply as for floating point numbers.
The real and imaginary parts of a complex number ``z`` can be retrieved through
the read-only attributes ``z.real`` and ``z.imag``.
Sequences
.. index::
builtin: len
object: sequence
single: index operation
single: item selection
single: subscription
These represent finite ordered sets indexed by non-negative numbers. The
built-in function :func:`len` returns the number of items of a sequence. When
the length of a sequence is *n*, the index set contains the numbers 0, 1,
..., *n*-1. Item *i* of sequence *a* is selected by ``a[i]``.
.. index:: single: slicing
Sequences also support slicing: ``a[i:j]`` selects all items with index *k* such
that *i* ``<=`` *k* ``<`` *j*. When used as an expression, a slice is a
sequence of the same type. This implies that the index set is renumbered so
that it starts at 0.
.. index:: single: extended slicing
Some sequences also support "extended slicing" with a third "step" parameter:
``a[i:j:k]`` selects all items of *a* with index *x* where ``x = i + n*k``, *n*
``>=`` ``0`` and *i* ``<=`` *x* ``<`` *j*.
Sequences are distinguished according to their mutability:
Immutable sequences
.. index::
object: immutable sequence
object: immutable
An object of an immutable sequence type cannot change once it is created. (If
the object contains references to other objects, these other objects may be
mutable and may be changed; however, the collection of objects directly
referenced by an immutable object cannot change.)
The following types are immutable sequences:
Strings
.. index::
builtin: chr
builtin: ord
object: string
single: character
single: byte
single: ASCII@ASCII
The items of a string are characters. There is no separate character type; a
character is represented by a string of one item. Characters represent (at
least) 8-bit bytes. The built-in functions :func:`chr` and :func:`ord` convert
between characters and nonnegative integers representing the byte values. Bytes
with the values 0--127 usually represent the corresponding ASCII values, but the
interpretation of values is up to the program. The string data type is also
used to represent arrays of bytes, e.g., to hold data read from a file.
.. index::
single: ASCII@ASCII
single: EBCDIC
single: character set
pair: string; comparison
builtin: chr
builtin: ord
(On systems whose native character set is not ASCII, strings may use EBCDIC in
their internal representation, provided the functions :func:`chr` and
:func:`ord` implement a mapping between ASCII and EBCDIC, and string comparison
preserves the ASCII order. Or perhaps someone can propose a better rule?)
Unicode
.. index::
builtin: unichr
builtin: ord
builtin: unicode
object: unicode
single: character
single: integer
single: Unicode
The items of a Unicode object are Unicode code units. A Unicode code unit is
represented by a Unicode object of one item and can hold either a 16-bit or
32-bit value representing a Unicode ordinal (the maximum value for the ordinal
is given in ``sys.maxunicode``, and depends on how Python is configured at
compile time). Surrogate pairs may be present in the Unicode object, and will
be reported as two separate items. The built-in functions :func:`unichr` and
:func:`ord` convert between code units and nonnegative integers representing the
Unicode ordinals as defined in the Unicode Standard 3.0. Conversion from and to
other encodings are possible through the Unicode method :meth:`encode` and the
built-in function :func:`unicode`.
Tuples
.. index::
object: tuple
pair: singleton; tuple
pair: empty; tuple
The items of a tuple are arbitrary Python objects. Tuples of two or more items
are formed by comma-separated lists of expressions. A tuple of one item (a
'singleton') can be formed by affixing a comma to an expression (an expression
by itself does not create a tuple, since parentheses must be usable for grouping
of expressions). An empty tuple can be formed by an empty pair of parentheses.
Mutable sequences
.. index::
object: mutable sequence
object: mutable
pair: assignment; statement
single: subscription
single: slicing
Mutable sequences can be changed after they are created. The subscription and
slicing notations can be used as the target of assignment and :keyword:`del`
(delete) statements.
There are currently two intrinsic mutable sequence types:
Lists
.. index:: object: list
The items of a list are arbitrary Python objects. Lists are formed by placing a
comma-separated list of expressions in square brackets. (Note that there are no
special cases needed to form lists of length 0 or 1.)
Byte Arrays
.. index:: bytearray
A bytearray object is a mutable array. They are created by the built-in
:func:`bytearray` constructor. Aside from being mutable (and hence
unhashable), byte arrays otherwise provide the same interface and
functionality as immutable bytes objects.
.. index:: module: array
The extension module :mod:`array` provides an additional example of a mutable
sequence type.
Set types
.. index::
builtin: len
object: set type
These represent unordered, finite sets of unique, immutable objects. As such,
they cannot be indexed by any subscript. However, they can be iterated over, and
the built-in function :func:`len` returns the number of items in a set. Common
uses for sets are fast membership testing, removing duplicates from a sequence,
and computing mathematical operations such as intersection, union, difference,
and symmetric difference.
For set elements, the same immutability rules apply as for dictionary keys. Note
that numeric types obey the normal rules for numeric comparison: if two numbers
compare equal (e.g., ``1`` and ``1.0``), only one of them can be contained in a
set.
There are currently two intrinsic set types:
Sets
.. index:: object: set
These represent a mutable set. They are created by the built-in :func:`set`
constructor and can be modified afterwards by several methods, such as
:meth:`~set.add`.
Frozen sets
.. index:: object: frozenset
These represent an immutable set. They are created by the built-in
:func:`frozenset` constructor. As a frozenset is immutable and
:term:`hashable`, it can be used again as an element of another set, or as
a dictionary key.
Mappings
.. index::
builtin: len
single: subscription
object: mapping
These represent finite sets of objects indexed by arbitrary index sets. The
subscript notation ``a[k]`` selects the item indexed by ``k`` from the mapping
``a``; this can be used in expressions and as the target of assignments or
:keyword:`del` statements. The built-in function :func:`len` returns the number
of items in a mapping.
There is currently a single intrinsic mapping type:
Dictionaries
.. index:: object: dictionary
These represent finite sets of objects indexed by nearly arbitrary values. The
only types of values not acceptable as keys are values containing lists or
dictionaries or other mutable types that are compared by value rather than by
object identity, the reason being that the efficient implementation of
dictionaries requires a key's hash value to remain constant. Numeric types used
for keys obey the normal rules for numeric comparison: if two numbers compare
equal (e.g., ``1`` and ``1.0``) then they can be used interchangeably to index
the same dictionary entry.
Dictionaries are mutable; they can be created by the ``{...}`` notation (see
section :ref:`dict`).
.. index::
module: dbm
module: gdbm
module: bsddb
The extension modules :mod:`dbm`, :mod:`gdbm`, and :mod:`bsddb` provide
additional examples of mapping types.
Callable types
.. index::
object: callable
pair: function; call
single: invocation
pair: function; argument
These are the types to which the function call operation (see section
:ref:`calls`) can be applied:
User-defined functions
.. index::
pair: user-defined; function
object: function
object: user-defined function
A user-defined function object is created by a function definition (see
section :ref:`function`). It should be called with an argument list
containing the same number of items as the function's formal parameter
list.
Special attributes:
.. tabularcolumns:: |l|L|l|
.. index::
single: __doc__ (function attribute)
single: __name__ (function attribute)
single: __module__ (function attribute)
single: __dict__ (function attribute)
single: __defaults__ (function attribute)
single: __code__ (function attribute)
single: __globals__ (function attribute)
single: __closure__ (function attribute)
single: func_doc (function attribute)
single: func_name (function attribute)
single: func_dict (function attribute)
single: func_defaults (function attribute)
single: func_code (function attribute)
single: func_globals (function attribute)
single: func_closure (function attribute)
pair: global; namespace
+-----------------------+-------------------------------+-----------+
| Attribute | Meaning | |
+=======================+===============================+===========+
| :attr:`__doc__` | The function's documentation | Writable |
| :attr:`func_doc` | string, or ``None`` if | |
| | unavailable. | |
+-----------------------+-------------------------------+-----------+
| :attr:`~definition.\ | The function's name | Writable |
| __name__` | | |
| :attr:`func_name` | | |
+-----------------------+-------------------------------+-----------+
| :attr:`__module__` | The name of the module the | Writable |
| | function was defined in, or | |
| | ``None`` if unavailable. | |
+-----------------------+-------------------------------+-----------+
| :attr:`__defaults__` | A tuple containing default | Writable |
| :attr:`func_defaults` | argument values for those | |
| | arguments that have defaults, | |
| | or ``None`` if no arguments | |
| | have a default value. | |
+-----------------------+-------------------------------+-----------+
| :attr:`__code__` | The code object representing | Writable |
| :attr:`func_code` | the compiled function body. | |
+-----------------------+-------------------------------+-----------+
| :attr:`__globals__` | A reference to the dictionary | Read-only |
| :attr:`func_globals` | that holds the function's | |
| | global variables --- the | |
| | global namespace of the | |
| | module in which the function | |
| | was defined. | |
+-----------------------+-------------------------------+-----------+
| :attr:`~object.\ | The namespace supporting | Writable |
| __dict__` | arbitrary function | |
| :attr:`func_dict` | attributes. | |
+-----------------------+-------------------------------+-----------+
| :attr:`__closure__` | ``None`` or a tuple of cells | Read-only |
| :attr:`func_closure` | that contain bindings for the | |
| | function's free variables. | |
+-----------------------+-------------------------------+-----------+
Most of the attributes labelled "Writable" check the type of the assigned value.
.. versionchanged:: 2.4
``func_name`` is now writable.
.. versionchanged:: 2.6
The double-underscore attributes ``__closure__``, ``__code__``,
``__defaults__``, and ``__globals__`` were introduced as aliases for
the corresponding ``func_*`` attributes for forwards compatibility
with Python 3.
Function objects also support getting and setting arbitrary attributes, which
can be used, for example, to attach metadata to functions. Regular attribute
dot-notation is used to get and set such attributes. *Note that the current
implementation only supports function attributes on user-defined functions.
Function attributes on built-in functions may be supported in the future.*
Additional information about a function's definition can be retrieved from its
code object; see the description of internal types below.
User-defined methods
.. index::
object: method
object: user-defined method
pair: user-defined; method
A user-defined method object combines a class, a class instance (or ``None``)
and any callable object (normally a user-defined function).
Special read-only attributes: :attr:`im_self` is the class instance object,
:attr:`im_func` is the function object; :attr:`im_class` is the class of
:attr:`im_self` for bound methods or the class that asked for the method for
unbound methods; :attr:`__doc__` is the method's documentation (same as
``im_func.__doc__``); :attr:`~definition.__name__` is the method name (same as
``im_func.__name__``); :attr:`__module__` is the name of the module the method
was defined in, or ``None`` if unavailable.
.. versionchanged:: 2.2
:attr:`im_self` used to refer to the class that defined the method.
.. versionchanged:: 2.6
For Python 3 forward-compatibility, :attr:`im_func` is also available as
:attr:`__func__`, and :attr:`im_self` as :attr:`__self__`.
.. index::
single: __doc__ (method attribute)
single: __name__ (method attribute)
single: __module__ (method attribute)
single: im_func (method attribute)
single: im_self (method attribute)
Methods also support accessing (but not setting) the arbitrary function
attributes on the underlying function object.
User-defined method objects may be created when getting an attribute of a class
(perhaps via an instance of that class), if that attribute is a user-defined
function object, an unbound user-defined method object, or a class method
object. When the attribute is a user-defined method object, a new method object
is only created if the class from which it is being retrieved is the same as, or
a derived class of, the class stored in the original method object; otherwise,
the original method object is used as it is.
.. index::
single: im_class (method attribute)
single: im_func (method attribute)
single: im_self (method attribute)
When a user-defined method object is created by retrieving a user-defined
function object from a class, its :attr:`im_self` attribute is ``None``
and the method object is said to be unbound. When one is created by
retrieving a user-defined function object from a class via one of its
instances, its :attr:`im_self` attribute is the instance, and the method
object is said to be bound. In either case, the new method's
:attr:`im_class` attribute is the class from which the retrieval takes
place, and its :attr:`im_func` attribute is the original function object.
.. index:: single: im_func (method attribute)
When a user-defined method object is created by retrieving another method object
from a class or instance, the behaviour is the same as for a function object,
except that the :attr:`im_func` attribute of the new instance is not the
original method object but its :attr:`im_func` attribute.
.. index::
single: im_class (method attribute)
single: im_func (method attribute)
single: im_self (method attribute)
When a user-defined method object is created by retrieving a class method object
from a class or instance, its :attr:`im_self` attribute is the class itself, and
its :attr:`im_func` attribute is the function object underlying the class method.
When an unbound user-defined method object is called, the underlying function
(:attr:`im_func`) is called, with the restriction that the first argument must
be an instance of the proper class (:attr:`im_class`) or of a derived class
thereof.
When a bound user-defined method object is called, the underlying function
(:attr:`im_func`) is called, inserting the class instance (:attr:`im_self`) in
front of the argument list. For instance, when :class:`C` is a class which
contains a definition for a function :meth:`f`, and ``x`` is an instance of
:class:`C`, calling ``x.f(1)`` is equivalent to calling ``C.f(x, 1)``.
When a user-defined method object is derived from a class method object, the
"class instance" stored in :attr:`im_self` will actually be the class itself, so
that calling either ``x.f(1)`` or ``C.f(1)`` is equivalent to calling ``f(C,1)``
where ``f`` is the underlying function.
Note that the transformation from function object to (unbound or bound) method
object happens each time the attribute is retrieved from the class or instance.
In some cases, a fruitful optimization is to assign the attribute to a local
variable and call that local variable. Also notice that this transformation only
happens for user-defined functions; other callable objects (and all non-callable
objects) are retrieved without transformation. It is also important to note
that user-defined functions which are attributes of a class instance are not
converted to bound methods; this *only* happens when the function is an
attribute of the class.
Generator functions
.. index::
single: generator; function
single: generator; iterator
A function or method which uses the :keyword:`yield` statement (see section
:ref:`yield`) is called a :dfn:`generator
function`. Such a function, when called, always returns an iterator object
which can be used to execute the body of the function: calling the iterator's
:meth:`~iterator.next` method will cause the function to execute until
it provides a value
using the :keyword:`yield` statement. When the function executes a
:keyword:`return` statement or falls off the end, a :exc:`StopIteration`
exception is raised and the iterator will have reached the end of the set of
values to be returned.
Built-in functions
.. index::
object: built-in function
object: function
pair: C; language
A built-in function object is a wrapper around a C function. Examples of
built-in functions are :func:`len` and :func:`math.sin` (:mod:`math` is a
standard built-in module). The number and type of the arguments are
determined by the C function. Special read-only attributes:
:attr:`__doc__` is the function's documentation string, or ``None`` if
unavailable; :attr:`~definition.__name__` is the function's name; :attr:`__self__` is
set to ``None`` (but see the next item); :attr:`__module__` is the name of
the module the function was defined in or ``None`` if unavailable.
Built-in methods
.. index::
object: built-in method
object: method
pair: built-in; method
This is really a different disguise of a built-in function, this time containing
an object passed to the C function as an implicit extra argument. An example of
a built-in method is ``alist.append()``, assuming *alist* is a list object. In
this case, the special read-only attribute :attr:`__self__` is set to the object
denoted by *alist*.
Class Types
Class types, or "new-style classes," are callable. These objects normally act
as factories for new instances of themselves, but variations are possible for
class types that override :meth:`__new__`. The arguments of the call are passed
to :meth:`__new__` and, in the typical case, to :meth:`__init__` to initialize
the new instance.
Classic Classes
.. index::
single: __init__() (object method)
object: class
object: class instance
object: instance
pair: class object; call
Class objects are described below. When a class object is called, a new class
instance (also described below) is created and returned. This implies a call to
the class's :meth:`__init__` method if it has one. Any arguments are passed on
to the :meth:`__init__` method. If there is no :meth:`__init__` method, the
class must be called without arguments.
Class instances
Class instances are described below. Class instances are callable only when the
class has a :meth:`__call__` method; ``x(arguments)`` is a shorthand for
``x.__call__(arguments)``.
Modules
.. index::
statement: import
object: module
Modules are imported by the :keyword:`import` statement (see section
:ref:`import`). A module object has a
namespace implemented by a dictionary object (this is the dictionary referenced
by the func_globals attribute of functions defined in the module). Attribute
references are translated to lookups in this dictionary, e.g., ``m.x`` is
equivalent to ``m.__dict__["x"]``. A module object does not contain the code
object used to initialize the module (since it isn't needed once the
initialization is done).
Attribute assignment updates the module's namespace dictionary, e.g., ``m.x =
1`` is equivalent to ``m.__dict__["x"] = 1``.
.. index:: single: __dict__ (module attribute)
Special read-only attribute: :attr:`~object.__dict__` is the module's namespace as a
dictionary object.
.. impl-detail::
Because of the way CPython clears module dictionaries, the module
dictionary will be cleared when the module falls out of scope even if the
dictionary still has live references. To avoid this, copy the dictionary
or keep the module around while using its dictionary directly.
.. index::
single: __name__ (module attribute)
single: __doc__ (module attribute)
single: __file__ (module attribute)
pair: module; namespace
Predefined (writable) attributes: :attr:`__name__` is the module's name;
:attr:`__doc__` is the module's documentation string, or ``None`` if
unavailable; :attr:`__file__` is the pathname of the file from which the module
was loaded, if it was loaded from a file. The :attr:`__file__` attribute is not
present for C modules that are statically linked into the interpreter; for
extension modules loaded dynamically from a shared library, it is the pathname
of the shared library file.
Classes
Both class types (new-style classes) and class objects (old-style/classic
classes) are typically created by class definitions (see section
:ref:`class`). A class has a namespace implemented by a dictionary object.
Class attribute references are translated to lookups in this dictionary, e.g.,
``C.x`` is translated to ``C.__dict__["x"]`` (although for new-style classes
in particular there are a number of hooks which allow for other means of
locating attributes). When the attribute name is not found there, the
attribute search continues in the base classes. For old-style classes, the
search is depth-first, left-to-right in the order of occurrence in the base
class list. New-style classes use the more complex C3 method resolution
order which behaves correctly even in the presence of 'diamond'
inheritance structures where there are multiple inheritance paths
leading back to a common ancestor. Additional details on the C3 MRO used by
new-style classes can be found in the documentation accompanying the
2.3 release at https://www.python.org/download/releases/2.3/mro/.
.. XXX: Could we add that MRO doc as an appendix to the language ref?
.. index::
object: class
object: class instance
object: instance
pair: class object; call
single: container
object: dictionary
pair: class; attribute
When a class attribute reference (for class :class:`C`, say) would yield a
user-defined function object or an unbound user-defined method object whose
associated class is either :class:`C` or one of its base classes, it is
transformed into an unbound user-defined method object whose :attr:`im_class`
attribute is :class:`C`. When it would yield a class method object, it is
transformed into a bound user-defined method object whose
:attr:`im_self` attribute is :class:`C`. When it would yield a
static method object, it is transformed into the object wrapped by the static
method object. See section :ref:`descriptors` for another way in which
attributes retrieved from a class may differ from those actually contained in
its :attr:`~object.__dict__` (note that only new-style classes support descriptors).
.. index:: triple: class; attribute; assignment
Class attribute assignments update the class's dictionary, never the dictionary
of a base class.
.. index:: pair: class object; call
A class object can be called (see above) to yield a class instance (see below).
.. index::
single: __name__ (class attribute)
single: __module__ (class attribute)
single: __dict__ (class attribute)
single: __bases__ (class attribute)
single: __doc__ (class attribute)
Special attributes: :attr:`~definition.__name__` is the class name; :attr:`__module__` is
the module name in which the class was defined; :attr:`~object.__dict__` is the
dictionary containing the class's namespace; :attr:`~class.__bases__` is a
tuple (possibly empty or a singleton) containing the base classes, in the
order of their occurrence in the base class list; :attr:`__doc__` is the
class's documentation string, or ``None`` if undefined.
Class instances
.. index::
object: class instance
object: instance
pair: class; instance
pair: class instance; attribute
A class instance is created by calling a class object (see above). A class
instance has a namespace implemented as a dictionary which is the first place in
which attribute references are searched. When an attribute is not found there,
and the instance's class has an attribute by that name, the search continues
with the class attributes. If a class attribute is found that is a user-defined
function object or an unbound user-defined method object whose associated class
is the class (call it :class:`C`) of the instance for which the attribute
reference was initiated or one of its bases, it is transformed into a bound
user-defined method object whose :attr:`im_class` attribute is :class:`C` and
whose :attr:`im_self` attribute is the instance. Static method and class method
objects are also transformed, as if they had been retrieved from class
:class:`C`; see above under "Classes". See section :ref:`descriptors` for
another way in which attributes of a class retrieved via its instances may
differ from the objects actually stored in the class's :attr:`~object.__dict__`. If no
class attribute is found, and the object's class has a :meth:`__getattr__`
method, that is called to satisfy the lookup.
.. index:: triple: class instance; attribute; assignment
Attribute assignments and deletions update the instance's dictionary, never a
class's dictionary. If the class has a :meth:`__setattr__` or
:meth:`__delattr__` method, this is called instead of updating the instance
dictionary directly.
.. index::
object: numeric
object: sequence
object: mapping
Class instances can pretend to be numbers, sequences, or mappings if they have
methods with certain special names. See section :ref:`specialnames`.
.. index::
single: __dict__ (instance attribute)
single: __class__ (instance attribute)
Special attributes: :attr:`~object.__dict__` is the attribute dictionary;
:attr:`~instance.__class__` is the instance's class.
Files
.. index::
object: file
builtin: open
single: popen() (in module os)
single: makefile() (socket method)
single: sys.stdin
single: sys.stdout
single: sys.stderr
single: stdio
single: stdin (in module sys)
single: stdout (in module sys)
single: stderr (in module sys)
A file object represents an open file. File objects are created by the
:func:`open` built-in function, and also by :func:`os.popen`,
:func:`os.fdopen`, and the :meth:`makefile` method of socket objects (and
perhaps by other functions or methods provided by extension modules). The
objects ``sys.stdin``, ``sys.stdout`` and ``sys.stderr`` are initialized to
file objects corresponding to the interpreter's standard input, output and
error streams. See :ref:`bltin-file-objects` for complete documentation of
file objects.
Internal types
.. index::
single: internal type
single: types, internal
A few types used internally by the interpreter are exposed to the user. Their
definitions may change with future versions of the interpreter, but they are
mentioned here for completeness.
.. index:: bytecode, object; code, code object
Code objects
Code objects represent *byte-compiled* executable Python code, or :term:`bytecode`.
The difference between a code object and a function object is that the function
object contains an explicit reference to the function's globals (the module in
which it was defined), while a code object contains no context; also the default
argument values are stored in the function object, not in the code object
(because they represent values calculated at run-time). Unlike function
objects, code objects are immutable and contain no references (directly or
indirectly) to mutable objects.
.. index::
single: co_argcount (code object attribute)
single: co_code (code object attribute)
single: co_consts (code object attribute)
single: co_filename (code object attribute)
single: co_firstlineno (code object attribute)
single: co_flags (code object attribute)
single: co_lnotab (code object attribute)
single: co_name (code object attribute)
single: co_names (code object attribute)
single: co_nlocals (code object attribute)
single: co_stacksize (code object attribute)
single: co_varnames (code object attribute)
single: co_cellvars (code object attribute)
single: co_freevars (code object attribute)
Special read-only attributes: :attr:`co_name` gives the function name;
:attr:`co_argcount` is the number of positional arguments (including arguments
with default values); :attr:`co_nlocals` is the number of local variables used
by the function (including arguments); :attr:`co_varnames` is a tuple containing
the names of the local variables (starting with the argument names);
:attr:`co_cellvars` is a tuple containing the names of local variables that are
referenced by nested functions; :attr:`co_freevars` is a tuple containing the
names of free variables; :attr:`co_code` is a string representing the sequence
of bytecode instructions; :attr:`co_consts` is a tuple containing the literals
used by the bytecode; :attr:`co_names` is a tuple containing the names used by
the bytecode; :attr:`co_filename` is the filename from which the code was
compiled; :attr:`co_firstlineno` is the first line number of the function;
:attr:`co_lnotab` is a string encoding the mapping from bytecode offsets to
line numbers (for details see the source code of the interpreter);
:attr:`co_stacksize` is the required stack size (including local variables);
:attr:`co_flags` is an integer encoding a number of flags for the interpreter.
.. index:: object: generator
The following flag bits are defined for :attr:`co_flags`: bit ``0x04`` is set if
the function uses the ``*arguments`` syntax to accept an arbitrary number of
positional arguments; bit ``0x08`` is set if the function uses the
``**keywords`` syntax to accept arbitrary keyword arguments; bit ``0x20`` is set
if the function is a generator.
Future feature declarations (``from __future__ import division``) also use bits
in :attr:`co_flags` to indicate whether a code object was compiled with a
particular feature enabled: bit ``0x2000`` is set if the function was compiled
with future division enabled; bits ``0x10`` and ``0x1000`` were used in earlier
versions of Python.
Other bits in :attr:`co_flags` are reserved for internal use.
.. index:: single: documentation string
If a code object represents a function, the first item in :attr:`co_consts` is
the documentation string of the function, or ``None`` if undefined.
.. _frame-objects:
Frame objects
.. index:: object: frame
Frame objects represent execution frames. They may occur in traceback objects
(see below).
.. index::
single: f_back (frame attribute)
single: f_code (frame attribute)
single: f_globals (frame attribute)
single: f_locals (frame attribute)
single: f_lasti (frame attribute)
single: f_builtins (frame attribute)
single: f_restricted (frame attribute)
Special read-only attributes: :attr:`f_back` is to the previous stack frame
(towards the caller), or ``None`` if this is the bottom stack frame;
:attr:`f_code` is the code object being executed in this frame; :attr:`f_locals`
is the dictionary used to look up local variables; :attr:`f_globals` is used for
global variables; :attr:`f_builtins` is used for built-in (intrinsic) names;
:attr:`f_restricted` is a flag indicating whether the function is executing in
restricted execution mode; :attr:`f_lasti` gives the precise instruction (this
is an index into the bytecode string of the code object).
.. index::
single: f_trace (frame attribute)
single: f_exc_type (frame attribute)
single: f_exc_value (frame attribute)
single: f_exc_traceback (frame attribute)
single: f_lineno (frame attribute)
Special writable attributes: :attr:`f_trace`, if not ``None``, is a function
called at the start of each source code line (this is used by the debugger);
:attr:`f_exc_type`, :attr:`f_exc_value`, :attr:`f_exc_traceback` represent the
last exception raised in the parent frame provided another exception was ever
raised in the current frame (in all other cases they are ``None``); :attr:`f_lineno`
is the current line number of the frame --- writing to this from within a trace
function jumps to the given line (only for the bottom-most frame). A debugger
can implement a Jump command (aka Set Next Statement) by writing to f_lineno.
Traceback objects
.. index::
object: traceback
pair: stack; trace
pair: exception; handler
pair: execution; stack
single: exc_info (in module sys)
single: exc_traceback (in module sys)
single: last_traceback (in module sys)
single: sys.exc_info
single: sys.exc_traceback
single: sys.last_traceback
Traceback objects represent a stack trace of an exception. A traceback object
is created when an exception occurs. When the search for an exception handler
unwinds the execution stack, at each unwound level a traceback object is
inserted in front of the current traceback. When an exception handler is
entered, the stack trace is made available to the program. (See section
:ref:`try`.) It is accessible as ``sys.exc_traceback``,
and also as the third item of the tuple returned by ``sys.exc_info()``. The
latter is the preferred interface, since it works correctly when the program is
using multiple threads. When the program contains no suitable handler, the stack
trace is written (nicely formatted) to the standard error stream; if the
interpreter is interactive, it is also made available to the user as
``sys.last_traceback``.
.. index::
single: tb_next (traceback attribute)
single: tb_frame (traceback attribute)
single: tb_lineno (traceback attribute)
single: tb_lasti (traceback attribute)
statement: try
Special read-only attributes: :attr:`tb_next` is the next level in the stack
trace (towards the frame where the exception occurred), or ``None`` if there is
no next level; :attr:`tb_frame` points to the execution frame of the current
level; :attr:`tb_lineno` gives the line number where the exception occurred;
:attr:`tb_lasti` indicates the precise instruction. The line number and last
instruction in the traceback may differ from the line number of its frame object
if the exception occurred in a :keyword:`try` statement with no matching except
clause or with a finally clause.
Slice objects
.. index:: builtin: slice
Slice objects are used to represent slices when *extended slice syntax* is used.
This is a slice using two colons, or multiple slices or ellipses separated by
commas, e.g., ``a[i:j:step]``, ``a[i:j, k:l]``, or ``a[..., i:j]``. They are
also created by the built-in :func:`slice` function.
.. index::
single: start (slice object attribute)
single: stop (slice object attribute)
single: step (slice object attribute)
Special read-only attributes: :attr:`~slice.start` is the lower bound;
:attr:`~slice.stop` is the upper bound; :attr:`~slice.step` is the step
value; each is ``None`` if omitted. These attributes can have any type.
Slice objects support one method:
.. method:: slice.indices(self, length)
This method takes a single integer argument *length* and computes information
about the extended slice that the slice object would describe if applied to a
sequence of *length* items. It returns a tuple of three integers; respectively
these are the *start* and *stop* indices and the *step* or stride length of the
slice. Missing or out-of-bounds indices are handled in a manner consistent with
regular slices.
.. versionadded:: 2.3
Static method objects
Static method objects provide a way of defeating the transformation of function
objects to method objects described above. A static method object is a wrapper
around any other object, usually a user-defined method object. When a static
method object is retrieved from a class or a class instance, the object actually
returned is the wrapped object, which is not subject to any further
transformation. Static method objects are not themselves callable, although the
objects they wrap usually are. Static method objects are created by the built-in
:func:`staticmethod` constructor.
Class method objects
A class method object, like a static method object, is a wrapper around another
object that alters the way in which that object is retrieved from classes and
class instances. The behaviour of class method objects upon such retrieval is
described above, under "User-defined methods". Class method objects are created
by the built-in :func:`classmethod` constructor.
.. _newstyle:
New-style and classic classes
=============================
Classes and instances come in two flavors: old-style (or classic) and new-style.
Up to Python 2.1 the concept of ``class`` was unrelated to the concept of
``type``, and old-style classes were the only flavor available. For an
old-style class, the statement ``x.__class__`` provides the class of *x*, but
``type(x)`` is always ``<type 'instance'>``. This reflects the fact that all
old-style instances, independent of their class, are implemented with a single
built-in type, called ``instance``.
New-style classes were introduced in Python 2.2 to unify the concepts of
``class`` and ``type``. A new-style class is simply a user-defined type,
no more, no less. If *x* is an instance of a new-style class, then ``type(x)``
is typically the same as ``x.__class__`` (although this is not guaranteed -- a
new-style class instance is permitted to override the value returned for
``x.__class__``).
The major motivation for introducing new-style classes is to provide a unified
object model with a full meta-model. It also has a number of practical
benefits, like the ability to subclass most built-in types, or the introduction
of "descriptors", which enable computed properties.
For compatibility reasons, classes are still old-style by default. New-style
classes are created by specifying another new-style class (i.e. a type) as a
parent class, or the "top-level type" :class:`object` if no other parent is
needed. The behaviour of new-style classes differs from that of old-style
classes in a number of important details in addition to what :func:`type`
returns. Some of these changes are fundamental to the new object model, like
the way special methods are invoked. Others are "fixes" that could not be
implemented before for compatibility concerns, like the method resolution order
in case of multiple inheritance.
While this manual aims to provide comprehensive coverage of Python's class
mechanics, it may still be lacking in some areas when it comes to its coverage
of new-style classes. Please see https://www.python.org/doc/newstyle/ for
sources of additional information.
.. index::
single: class; new-style
single: class; classic
single: class; old-style
Old-style classes are removed in Python 3, leaving only new-style classes.
.. _specialnames:
Special method names
====================
.. index::
pair: operator; overloading
single: __getitem__() (mapping object method)
A class can implement certain operations that are invoked by special syntax
(such as arithmetic operations or subscripting and slicing) by defining methods
with special names. This is Python's approach to :dfn:`operator overloading`,
allowing classes to define their own behavior with respect to language
operators. For instance, if a class defines a method named :meth:`__getitem__`,
and ``x`` is an instance of this class, then ``x[i]`` is roughly equivalent
to ``x.__getitem__(i)`` for old-style classes and ``type(x).__getitem__(x, i)``
for new-style classes. Except where mentioned, attempts to execute an
operation raise an exception when no appropriate method is defined (typically
:exc:`AttributeError` or :exc:`TypeError`).
When implementing a class that emulates any built-in type, it is important that
the emulation only be implemented to the degree that it makes sense for the
object being modelled. For example, some sequences may work well with retrieval
of individual elements, but extracting a slice may not make sense. (One example
of this is the :class:`~xml.dom.NodeList` interface in the W3C's Document
Object Model.)
.. _customization:
Basic customization
-------------------
.. method:: object.__new__(cls[, ...])
.. index:: pair: subclassing; immutable types
Called to create a new instance of class *cls*. :meth:`__new__` is a static
method (special-cased so you need not declare it as such) that takes the class
of which an instance was requested as its first argument. The remaining
arguments are those passed to the object constructor expression (the call to the
class). The return value of :meth:`__new__` should be the new object instance
(usually an instance of *cls*).
Typical implementations create a new instance of the class by invoking the
superclass's :meth:`__new__` method using ``super(currentclass,
cls).__new__(cls[, ...])`` with appropriate arguments and then modifying the
newly-created instance as necessary before returning it.
If :meth:`__new__` returns an instance of *cls*, then the new instance's
:meth:`__init__` method will be invoked like ``__init__(self[, ...])``, where
*self* is the new instance and the remaining arguments are the same as were
passed to :meth:`__new__`.
If :meth:`__new__` does not return an instance of *cls*, then the new instance's
:meth:`__init__` method will not be invoked.
:meth:`__new__` is intended mainly to allow subclasses of immutable types (like
int, str, or tuple) to customize instance creation. It is also commonly
overridden in custom metaclasses in order to customize class creation.
.. method:: object.__init__(self[, ...])
.. index:: pair: class; constructor
Called after the instance has been created (by :meth:`__new__`), but before
it is returned to the caller. The arguments are those passed to the
class constructor expression. If a base class has an :meth:`__init__` method,
the derived class's :meth:`__init__` method, if any, must explicitly call it to
ensure proper initialization of the base class part of the instance; for
example: ``BaseClass.__init__(self, [args...])``.
Because :meth:`__new__` and :meth:`__init__` work together in constructing
objects (:meth:`__new__` to create it, and :meth:`__init__` to customise it),
no non-``None`` value may be returned by :meth:`__init__`; doing so will
cause a :exc:`TypeError` to be raised at runtime.
.. method:: object.__del__(self)
.. index::
single: destructor
statement: del
Called when the instance is about to be destroyed. This is also called a
destructor. If a base class has a :meth:`__del__` method, the derived class's
:meth:`__del__` method, if any, must explicitly call it to ensure proper
deletion of the base class part of the instance. Note that it is possible
(though not recommended!) for the :meth:`__del__` method to postpone destruction
of the instance by creating a new reference to it. It may then be called at a
later time when this new reference is deleted. It is not guaranteed that
:meth:`__del__` methods are called for objects that still exist when the
interpreter exits.
.. note::
``del x`` doesn't directly call ``x.__del__()`` --- the former decrements
the reference count for ``x`` by one, and the latter is only called when
``x``'s reference count reaches zero. Some common situations that may
prevent the reference count of an object from going to zero include:
circular references between objects (e.g., a doubly-linked list or a tree
data structure with parent and child pointers); a reference to the object
on the stack frame of a function that caught an exception (the traceback
stored in ``sys.exc_traceback`` keeps the stack frame alive); or a
reference to the object on the stack frame that raised an unhandled
exception in interactive mode (the traceback stored in
``sys.last_traceback`` keeps the stack frame alive). The first situation
can only be remedied by explicitly breaking the cycles; the latter two
situations can be resolved by storing ``None`` in ``sys.exc_traceback`` or
``sys.last_traceback``. Circular references which are garbage are
detected when the option cycle detector is enabled (it's on by default),
but can only be cleaned up if there are no Python-level :meth:`__del__`
methods involved. Refer to the documentation for the :mod:`gc` module for
more information about how :meth:`__del__` methods are handled by the
cycle detector, particularly the description of the ``garbage`` value.
.. warning::
Due to the precarious circumstances under which :meth:`__del__` methods are
invoked, exceptions that occur during their execution are ignored, and a warning
is printed to ``sys.stderr`` instead. Also, when :meth:`__del__` is invoked in
response to a module being deleted (e.g., when execution of the program is
done), other globals referenced by the :meth:`__del__` method may already have
been deleted or in the process of being torn down (e.g. the import
machinery shutting down). For this reason, :meth:`__del__` methods
should do the absolute
minimum needed to maintain external invariants. Starting with version 1.5,
Python guarantees that globals whose name begins with a single underscore are
deleted from their module before other globals are deleted; if no other
references to such globals exist, this may help in assuring that imported
modules are still available at the time when the :meth:`__del__` method is
called.
See also the :option:`-R` command-line option.
.. method:: object.__repr__(self)
.. index:: builtin: repr
Called by the :func:`repr` built-in function and by string conversions (reverse
quotes) to compute the "official" string representation of an object. If at all
possible, this should look like a valid Python expression that could be used to
recreate an object with the same value (given an appropriate environment). If
this is not possible, a string of the form ``<...some useful description...>``
should be returned. The return value must be a string object. If a class
defines :meth:`__repr__` but not :meth:`__str__`, then :meth:`__repr__` is also
used when an "informal" string representation of instances of that class is
required.
.. index::
pair: string; conversion
pair: reverse; quotes
pair: backward; quotes
single: back-quotes
This is typically used for debugging, so it is important that the representation
is information-rich and unambiguous.
.. method:: object.__str__(self)
.. index::
builtin: str
statement: print
Called by the :func:`str` built-in function and by the :keyword:`print`
statement to compute the "informal" string representation of an object. This
differs from :meth:`__repr__` in that it does not have to be a valid Python
expression: a more convenient or concise representation may be used instead.
The return value must be a string object.
.. method:: object.__lt__(self, other)
object.__le__(self, other)
object.__eq__(self, other)
object.__ne__(self, other)
object.__gt__(self, other)
object.__ge__(self, other)
.. versionadded:: 2.1
.. index::
single: comparisons
These are the so-called "rich comparison" methods, and are called for comparison
operators in preference to :meth:`__cmp__` below. The correspondence between
operator symbols and method names is as follows: ``x<y`` calls ``x.__lt__(y)``,
``x<=y`` calls ``x.__le__(y)``, ``x==y`` calls ``x.__eq__(y)``, ``x!=y`` and
``x<>y`` call ``x.__ne__(y)``, ``x>y`` calls ``x.__gt__(y)``, and ``x>=y`` calls
``x.__ge__(y)``.
A rich comparison method may return the singleton ``NotImplemented`` if it does
not implement the operation for a given pair of arguments. By convention,
``False`` and ``True`` are returned for a successful comparison. However, these
methods can return any value, so if the comparison operator is used in a Boolean
context (e.g., in the condition of an ``if`` statement), Python will call
:func:`bool` on the value to determine if the result is true or false.
There are no implied relationships among the comparison operators. The truth
of ``x==y`` does not imply that ``x!=y`` is false. Accordingly, when
defining :meth:`__eq__`, one should also define :meth:`__ne__` so that the
operators will behave as expected. See the paragraph on :meth:`__hash__` for
some important notes on creating :term:`hashable` objects which support
custom comparison operations and are usable as dictionary keys.
There are no swapped-argument versions of these methods (to be used when the
left argument does not support the operation but the right argument does);
rather, :meth:`__lt__` and :meth:`__gt__` are each other's reflection,
:meth:`__le__` and :meth:`__ge__` are each other's reflection, and
:meth:`__eq__` and :meth:`__ne__` are their own reflection.
Arguments to rich comparison methods are never coerced.
To automatically generate ordering operations from a single root operation,
see :func:`functools.total_ordering`.
.. method:: object.__cmp__(self, other)
.. index::
builtin: cmp
single: comparisons
Called by comparison operations if rich comparison (see above) is not
defined. Should return a negative integer if ``self < other``, zero if
``self == other``, a positive integer if ``self > other``. If no
:meth:`__cmp__`, :meth:`__eq__` or :meth:`__ne__` operation is defined, class
instances are compared by object identity ("address"). See also the
description of :meth:`__hash__` for some important notes on creating
:term:`hashable` objects which support custom comparison operations and are
usable as dictionary keys. (Note: the restriction that exceptions are not
propagated by :meth:`__cmp__` has been removed since Python 1.5.)
.. method:: object.__rcmp__(self, other)
.. versionchanged:: 2.1
No longer supported.
.. method:: object.__hash__(self)
.. index::
object: dictionary
builtin: hash
Called by built-in function :func:`hash` and for operations on members of
hashed collections including :class:`set`, :class:`frozenset`, and
:class:`dict`. :meth:`__hash__` should return an integer. The only required
property is that objects which compare equal have the same hash value; it is
advised to mix together the hash values of the components of the object that
also play a part in comparison of objects by packing them into a tuple and
hashing the tuple. Example::
def __hash__(self):
return hash((self.name, self.nick, self.color))
If a class does not define a :meth:`__cmp__` or :meth:`__eq__` method it
should not define a :meth:`__hash__` operation either; if it defines
:meth:`__cmp__` or :meth:`__eq__` but not :meth:`__hash__`, its instances
will not be usable in hashed collections. If a class defines mutable objects
and implements a :meth:`__cmp__` or :meth:`__eq__` method, it should not
implement :meth:`__hash__`, since hashable collection implementations require
that an object's hash value is immutable (if the object's hash value changes,
it will be in the wrong hash bucket).
User-defined classes have :meth:`__cmp__` and :meth:`__hash__` methods
by default; with them, all objects compare unequal (except with themselves)
and ``x.__hash__()`` returns a result derived from ``id(x)``.
Classes which inherit a :meth:`__hash__` method from a parent class but
change the meaning of :meth:`__cmp__` or :meth:`__eq__` such that the hash
value returned is no longer appropriate (e.g. by switching to a value-based
concept of equality instead of the default identity based equality) can
explicitly flag themselves as being unhashable by setting ``__hash__ = None``
in the class definition. Doing so means that not only will instances of the
class raise an appropriate :exc:`TypeError` when a program attempts to
retrieve their hash value, but they will also be correctly identified as
unhashable when checking ``isinstance(obj, collections.Hashable)`` (unlike
classes which define their own :meth:`__hash__` to explicitly raise
:exc:`TypeError`).
.. versionchanged:: 2.5
:meth:`__hash__` may now also return a long integer object; the 32-bit
integer is then derived from the hash of that object.
.. versionchanged:: 2.6
:attr:`__hash__` may now be set to :const:`None` to explicitly flag
instances of a class as unhashable.
.. method:: object.__nonzero__(self)
.. index:: single: __len__() (mapping object method)
Called to implement truth value testing and the built-in operation ``bool()``;
should return ``False`` or ``True``, or their integer equivalents ``0`` or
``1``. When this method is not defined, :meth:`__len__` is called, if it is
defined, and the object is considered true if its result is nonzero.
If a class defines neither :meth:`__len__` nor :meth:`__nonzero__`, all its
instances are considered true.
.. method:: object.__unicode__(self)
.. index:: builtin: unicode
Called to implement :func:`unicode` built-in; should return a Unicode object.
When this method is not defined, string conversion is attempted, and the result
of string conversion is converted to Unicode using the system default encoding.
.. _attribute-access:
Customizing attribute access
----------------------------
The following methods can be defined to customize the meaning of attribute
access (use of, assignment to, or deletion of ``x.name``) for class instances.
.. method:: object.__getattr__(self, name)
Called when an attribute lookup has not found the attribute in the usual places
(i.e. it is not an instance attribute nor is it found in the class tree for
``self``). ``name`` is the attribute name. This method should return the
(computed) attribute value or raise an :exc:`AttributeError` exception.
.. index:: single: __setattr__() (object method)
Note that if the attribute is found through the normal mechanism,
:meth:`__getattr__` is not called. (This is an intentional asymmetry between
:meth:`__getattr__` and :meth:`__setattr__`.) This is done both for efficiency
reasons and because otherwise :meth:`__getattr__` would have no way to access
other attributes of the instance. Note that at least for instance variables,
you can fake total control by not inserting any values in the instance attribute
dictionary (but instead inserting them in another object). See the
:meth:`__getattribute__` method below for a way to actually get total control in
new-style classes.
.. method:: object.__setattr__(self, name, value)
Called when an attribute assignment is attempted. This is called instead of the
normal mechanism (i.e. store the value in the instance dictionary). *name* is
the attribute name, *value* is the value to be assigned to it.
.. index:: single: __dict__ (instance attribute)
If :meth:`__setattr__` wants to assign to an instance attribute, it should not
simply execute ``self.name = value`` --- this would cause a recursive call to
itself. Instead, it should insert the value in the dictionary of instance
attributes, e.g., ``self.__dict__[name] = value``. For new-style classes,
rather than accessing the instance dictionary, it should call the base class
method with the same name, for example, ``object.__setattr__(self, name,
value)``.
.. method:: object.__delattr__(self, name)
Like :meth:`__setattr__` but for attribute deletion instead of assignment. This
should only be implemented if ``del obj.name`` is meaningful for the object.
.. _new-style-attribute-access:
More attribute access for new-style classes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following methods only apply to new-style classes.
.. method:: object.__getattribute__(self, name)
Called unconditionally to implement attribute accesses for instances of the
class. If the class also defines :meth:`__getattr__`, the latter will not be
called unless :meth:`__getattribute__` either calls it explicitly or raises an
:exc:`AttributeError`. This method should return the (computed) attribute value
or raise an :exc:`AttributeError` exception. In order to avoid infinite
recursion in this method, its implementation should always call the base class
method with the same name to access any attributes it needs, for example,
``object.__getattribute__(self, name)``.
.. note::
This method may still be bypassed when looking up special methods as the
result of implicit invocation via language syntax or built-in functions.
See :ref:`new-style-special-lookup`.
.. _descriptors:
Implementing Descriptors
^^^^^^^^^^^^^^^^^^^^^^^^
The following methods only apply when an instance of the class containing the
method (a so-called *descriptor* class) appears in an *owner* class (the
descriptor must be in either the owner's class dictionary or in the class
dictionary for one of its parents). In the examples below, "the attribute"
refers to the attribute whose name is the key of the property in the owner
class' :attr:`~object.__dict__`.
.. method:: object.__get__(self, instance, owner)
Called to get the attribute of the owner class (class attribute access) or of an
instance of that class (instance attribute access). *owner* is always the owner
class, while *instance* is the instance that the attribute was accessed through,
or ``None`` when the attribute is accessed through the *owner*. This method
should return the (computed) attribute value or raise an :exc:`AttributeError`
exception.
.. method:: object.__set__(self, instance, value)
Called to set the attribute on an instance *instance* of the owner class to a
new value, *value*.
.. method:: object.__delete__(self, instance)
Called to delete the attribute on an instance *instance* of the owner class.
.. _descriptor-invocation:
Invoking Descriptors
^^^^^^^^^^^^^^^^^^^^
In general, a descriptor is an object attribute with "binding behavior", one
whose attribute access has been overridden by methods in the descriptor
protocol: :meth:`__get__`, :meth:`__set__`, and :meth:`__delete__`. If any of
those methods are defined for an object, it is said to be a descriptor.
The default behavior for attribute access is to get, set, or delete the
attribute from an object's dictionary. For instance, ``a.x`` has a lookup chain
starting with ``a.__dict__['x']``, then ``type(a).__dict__['x']``, and
continuing through the base classes of ``type(a)`` excluding metaclasses.
However, if the looked-up value is an object defining one of the descriptor
methods, then Python may override the default behavior and invoke the descriptor
method instead. Where this occurs in the precedence chain depends on which
descriptor methods were defined and how they were called. Note that descriptors
are only invoked for new style objects or classes (ones that subclass
:class:`object()` or :class:`type()`).
The starting point for descriptor invocation is a binding, ``a.x``. How the
arguments are assembled depends on ``a``:
Direct Call
The simplest and least common call is when user code directly invokes a
descriptor method: ``x.__get__(a)``.
Instance Binding
If binding to a new-style object instance, ``a.x`` is transformed into the call:
``type(a).__dict__['x'].__get__(a, type(a))``.
Class Binding
If binding to a new-style class, ``A.x`` is transformed into the call:
``A.__dict__['x'].__get__(None, A)``.
Super Binding
If ``a`` is an instance of :class:`super`, then the binding ``super(B,
obj).m()`` searches ``obj.__class__.__mro__`` for the base class ``A``
immediately preceding ``B`` and then invokes the descriptor with the call:
``A.__dict__['m'].__get__(obj, obj.__class__)``.
For instance bindings, the precedence of descriptor invocation depends on the
which descriptor methods are defined. A descriptor can define any combination
of :meth:`__get__`, :meth:`__set__` and :meth:`__delete__`. If it does not
define :meth:`__get__`, then accessing the attribute will return the descriptor
object itself unless there is a value in the object's instance dictionary. If
the descriptor defines :meth:`__set__` and/or :meth:`__delete__`, it is a data
descriptor; if it defines neither, it is a non-data descriptor. Normally, data
descriptors define both :meth:`__get__` and :meth:`__set__`, while non-data
descriptors have just the :meth:`__get__` method. Data descriptors with
:meth:`__set__` and :meth:`__get__` defined always override a redefinition in an
instance dictionary. In contrast, non-data descriptors can be overridden by
instances.
Python methods (including :func:`staticmethod` and :func:`classmethod`) are
implemented as non-data descriptors. Accordingly, instances can redefine and
override methods. This allows individual instances to acquire behaviors that
differ from other instances of the same class.
The :func:`property` function is implemented as a data descriptor. Accordingly,
instances cannot override the behavior of a property.
.. _slots:
__slots__
^^^^^^^^^
By default, instances of both old and new-style classes have a dictionary for
attribute storage. This wastes space for objects having very few instance
variables. The space consumption can become acute when creating large numbers
of instances.
The default can be overridden by defining *__slots__* in a new-style class
definition. The *__slots__* declaration takes a sequence of instance variables
and reserves just enough space in each instance to hold a value for each
variable. Space is saved because *__dict__* is not created for each instance.
.. data:: __slots__
This class variable can be assigned a string, iterable, or sequence of strings
with variable names used by instances. If defined in a new-style class,
*__slots__* reserves space for the declared variables and prevents the automatic
creation of *__dict__* and *__weakref__* for each instance.
.. versionadded:: 2.2
Notes on using *__slots__*
* When inheriting from a class without *__slots__*, the *__dict__* attribute of
that class will always be accessible, so a *__slots__* definition in the
subclass is meaningless.
* Without a *__dict__* variable, instances cannot be assigned new variables not
listed in the *__slots__* definition. Attempts to assign to an unlisted
variable name raises :exc:`AttributeError`. If dynamic assignment of new
variables is desired, then add ``'__dict__'`` to the sequence of strings in the
*__slots__* declaration.
.. versionchanged:: 2.3
Previously, adding ``'__dict__'`` to the *__slots__* declaration would not
enable the assignment of new attributes not specifically listed in the sequence
of instance variable names.
* Without a *__weakref__* variable for each instance, classes defining
*__slots__* do not support weak references to its instances. If weak reference
support is needed, then add ``'__weakref__'`` to the sequence of strings in the
*__slots__* declaration.
.. versionchanged:: 2.3
Previously, adding ``'__weakref__'`` to the *__slots__* declaration would not
enable support for weak references.
* *__slots__* are implemented at the class level by creating descriptors
(:ref:`descriptors`) for each variable name. As a result, class attributes
cannot be used to set default values for instance variables defined by
*__slots__*; otherwise, the class attribute would overwrite the descriptor
assignment.
* The action of a *__slots__* declaration is limited to the class where it is
defined. As a result, subclasses will have a *__dict__* unless they also define
*__slots__* (which must only contain names of any *additional* slots).
* If a class defines a slot also defined in a base class, the instance variable
defined by the base class slot is inaccessible (except by retrieving its
descriptor directly from the base class). This renders the meaning of the
program undefined. In the future, a check may be added to prevent this.
* Nonempty *__slots__* does not work for classes derived from "variable-length"
built-in types such as :class:`long`, :class:`str` and :class:`tuple`.
* Any non-string iterable may be assigned to *__slots__*. Mappings may also be
used; however, in the future, special meaning may be assigned to the values
corresponding to each key.
* *__class__* assignment works only if both classes have the same *__slots__*.
.. versionchanged:: 2.6
Previously, *__class__* assignment raised an error if either new or old class
had *__slots__*.
.. _metaclasses:
Customizing class creation
--------------------------
By default, new-style classes are constructed using :func:`type`. A class
definition is read into a separate namespace and the value of class name is
bound to the result of ``type(name, bases, dict)``.
When the class definition is read, if *__metaclass__* is defined then the
callable assigned to it will be called instead of :func:`type`. This allows
classes or functions to be written which monitor or alter the class creation
process:
* Modifying the class dictionary prior to the class being created.
* Returning an instance of another class -- essentially performing the role of a
factory function.
These steps will have to be performed in the metaclass's :meth:`__new__` method
-- :meth:`type.__new__` can then be called from this method to create a class
with different properties. This example adds a new element to the class
dictionary before creating the class::
class metacls(type):
def __new__(mcs, name, bases, dict):
dict['foo'] = 'metacls was here'
return type.__new__(mcs, name, bases, dict)
You can of course also override other class methods (or add new methods); for
example defining a custom :meth:`__call__` method in the metaclass allows custom
behavior when the class is called, e.g. not always creating a new instance.
.. data:: __metaclass__
This variable can be any callable accepting arguments for ``name``, ``bases``,
and ``dict``. Upon class creation, the callable is used instead of the built-in
:func:`type`.
.. versionadded:: 2.2
The appropriate metaclass is determined by the following precedence rules:
* If ``dict['__metaclass__']`` exists, it is used.
* Otherwise, if there is at least one base class, its metaclass is used (this
looks for a *__class__* attribute first and if not found, uses its type).
* Otherwise, if a global variable named __metaclass__ exists, it is used.
* Otherwise, the old-style, classic metaclass (types.ClassType) is used.
The potential uses for metaclasses are boundless. Some ideas that have been
explored including logging, interface checking, automatic delegation, automatic
property creation, proxies, frameworks, and automatic resource
locking/synchronization.
Customizing instance and subclass checks
----------------------------------------
.. versionadded:: 2.6
The following methods are used to override the default behavior of the
:func:`isinstance` and :func:`issubclass` built-in functions.
In particular, the metaclass :class:`abc.ABCMeta` implements these methods in
order to allow the addition of Abstract Base Classes (ABCs) as "virtual base
classes" to any class or type (including built-in types), including other
ABCs.
.. method:: class.__instancecheck__(self, instance)
Return true if *instance* should be considered a (direct or indirect)
instance of *class*. If defined, called to implement ``isinstance(instance,
class)``.
.. method:: class.__subclasscheck__(self, subclass)
Return true if *subclass* should be considered a (direct or indirect)
subclass of *class*. If defined, called to implement ``issubclass(subclass,
class)``.
Note that these methods are looked up on the type (metaclass) of a class. They
cannot be defined as class methods in the actual class. This is consistent with
the lookup of special methods that are called on instances, only in this
case the instance is itself a class.
.. seealso::
:pep:`3119` - Introducing Abstract Base Classes
Includes the specification for customizing :func:`isinstance` and
:func:`issubclass` behavior through :meth:`~class.__instancecheck__` and
:meth:`~class.__subclasscheck__`, with motivation for this functionality
in the context of adding Abstract Base Classes (see the :mod:`abc`
module) to the language.
.. _callable-types:
Emulating callable objects
--------------------------
.. method:: object.__call__(self[, args...])
.. index:: pair: call; instance
Called when the instance is "called" as a function; if this method is defined,
``x(arg1, arg2, ...)`` is a shorthand for ``x.__call__(arg1, arg2, ...)``.
.. _sequence-types:
Emulating container types
-------------------------
The following methods can be defined to implement container objects. Containers
usually are sequences (such as lists or tuples) or mappings (like dictionaries),
but can represent other containers as well. The first set of methods is used
either to emulate a sequence or to emulate a mapping; the difference is that for
a sequence, the allowable keys should be the integers *k* for which ``0 <= k <
N`` where *N* is the length of the sequence, or slice objects, which define a
range of items. (For backwards compatibility, the method :meth:`__getslice__`
(see below) can also be defined to handle simple, but not extended slices.) It
is also recommended that mappings provide the methods :meth:`keys`,
:meth:`values`, :meth:`items`, :meth:`has_key`, :meth:`get`, :meth:`clear`,
:meth:`setdefault`, :meth:`iterkeys`, :meth:`itervalues`, :meth:`iteritems`,
:meth:`pop`, :meth:`popitem`, :meth:`!copy`, and :meth:`update` behaving similar
to those for Python's standard dictionary objects. The :mod:`UserDict` module
provides a :class:`DictMixin` class to help create those methods from a base set
of :meth:`__getitem__`, :meth:`__setitem__`, :meth:`__delitem__`, and
:meth:`keys`. Mutable sequences should provide methods :meth:`append`,
:meth:`count`, :meth:`index`, :meth:`extend`, :meth:`insert`, :meth:`pop`,
:meth:`remove`, :meth:`reverse` and :meth:`sort`, like Python standard list
objects. Finally, sequence types should implement addition (meaning
concatenation) and multiplication (meaning repetition) by defining the methods
:meth:`__add__`, :meth:`__radd__`, :meth:`__iadd__`, :meth:`__mul__`,
:meth:`__rmul__` and :meth:`__imul__` described below; they should not define
:meth:`__coerce__` or other numerical operators. It is recommended that both
mappings and sequences implement the :meth:`__contains__` method to allow
efficient use of the ``in`` operator; for mappings, ``in`` should be equivalent
of :meth:`has_key`; for sequences, it should search through the values. It is
further recommended that both mappings and sequences implement the
:meth:`__iter__` method to allow efficient iteration through the container; for
mappings, :meth:`__iter__` should be the same as :meth:`iterkeys`; for
sequences, it should iterate through the values.
.. method:: object.__len__(self)
.. index::
builtin: len
single: __nonzero__() (object method)
Called to implement the built-in function :func:`len`. Should return the length
of the object, an integer ``>=`` 0. Also, an object that doesn't define a
:meth:`__nonzero__` method and whose :meth:`__len__` method returns zero is
considered to be false in a Boolean context.
.. impl-detail::
In CPython, the length is required to be at most :attr:`sys.maxsize`.
If the length is larger than :attr:`!sys.maxsize` some features (such as
:func:`len`) may raise :exc:`OverflowError`. To prevent raising
:exc:`!OverflowError` by truth value testing, an object must define a
:meth:`__nonzero__` method.
.. method:: object.__getitem__(self, key)
.. index:: object: slice
Called to implement evaluation of ``self[key]``. For sequence types, the
accepted keys should be integers and slice objects. Note that the special
interpretation of negative indexes (if the class wishes to emulate a sequence
type) is up to the :meth:`__getitem__` method. If *key* is of an inappropriate
type, :exc:`TypeError` may be raised; if of a value outside the set of indexes
for the sequence (after any special interpretation of negative values),
:exc:`IndexError` should be raised. For mapping types, if *key* is missing (not
in the container), :exc:`KeyError` should be raised.
.. note::
:keyword:`for` loops expect that an :exc:`IndexError` will be raised for illegal
indexes to allow proper detection of the end of the sequence.
.. method:: object.__setitem__(self, key, value)
Called to implement assignment to ``self[key]``. Same note as for
:meth:`__getitem__`. This should only be implemented for mappings if the
objects support changes to the values for keys, or if new keys can be added, or
for sequences if elements can be replaced. The same exceptions should be raised
for improper *key* values as for the :meth:`__getitem__` method.
.. method:: object.__delitem__(self, key)
Called to implement deletion of ``self[key]``. Same note as for
:meth:`__getitem__`. This should only be implemented for mappings if the
objects support removal of keys, or for sequences if elements can be removed
from the sequence. The same exceptions should be raised for improper *key*
values as for the :meth:`__getitem__` method.
.. method:: object.__missing__(self, key)
Called by :class:`dict`\ .\ :meth:`__getitem__` to implement ``self[key]`` for dict subclasses
when key is not in the dictionary.
.. method:: object.__iter__(self)
This method is called when an iterator is required for a container. This method
should return a new iterator object that can iterate over all the objects in the
container. For mappings, it should iterate over the keys of the container, and
should also be made available as the method :meth:`iterkeys`.
Iterator objects also need to implement this method; they are required to return
themselves. For more information on iterator objects, see :ref:`typeiter`.
.. method:: object.__reversed__(self)
Called (if present) by the :func:`reversed` built-in to implement
reverse iteration. It should return a new iterator object that iterates
over all the objects in the container in reverse order.
If the :meth:`__reversed__` method is not provided, the :func:`reversed`
built-in will fall back to using the sequence protocol (:meth:`__len__` and
:meth:`__getitem__`). Objects that support the sequence protocol should
only provide :meth:`__reversed__` if they can provide an implementation
that is more efficient than the one provided by :func:`reversed`.
.. versionadded:: 2.6
The membership test operators (:keyword:`in` and :keyword:`not in`) are normally
implemented as an iteration through a sequence. However, container objects can
supply the following special method with a more efficient implementation, which
also does not require the object be a sequence.
.. method:: object.__contains__(self, item)
Called to implement membership test operators. Should return true if *item*
is in *self*, false otherwise. For mapping objects, this should consider the
keys of the mapping rather than the values or the key-item pairs.
For objects that don't define :meth:`__contains__`, the membership test first
tries iteration via :meth:`__iter__`, then the old sequence iteration
protocol via :meth:`__getitem__`, see :ref:`this section in the language
reference <membership-test-details>`.
.. _sequence-methods:
Additional methods for emulation of sequence types
--------------------------------------------------
The following optional methods can be defined to further emulate sequence
objects. Immutable sequences methods should at most only define
:meth:`__getslice__`; mutable sequences might define all three methods.
.. method:: object.__getslice__(self, i, j)
.. deprecated:: 2.0
Support slice objects as parameters to the :meth:`__getitem__` method.
(However, built-in types in CPython currently still implement
:meth:`__getslice__`. Therefore, you have to override it in derived
classes when implementing slicing.)
Called to implement evaluation of ``self[i:j]``. The returned object should
be of the same type as *self*. Note that missing *i* or *j* in the slice
expression are replaced by zero or :attr:`sys.maxsize`, respectively. If
negative indexes are used in the slice, the length of the sequence is added
to that index. If the instance does not implement the :meth:`__len__` method,
an :exc:`AttributeError` is raised. No guarantee is made that indexes
adjusted this way are not still negative. Indexes which are greater than the
length of the sequence are not modified. If no :meth:`__getslice__` is found,
a slice object is created instead, and passed to :meth:`__getitem__` instead.
.. method:: object.__setslice__(self, i, j, sequence)
Called to implement assignment to ``self[i:j]``. Same notes for *i* and *j* as
for :meth:`__getslice__`.
This method is deprecated. If no :meth:`__setslice__` is found, or for extended
slicing of the form ``self[i:j:k]``, a slice object is created, and passed to
:meth:`__setitem__`, instead of :meth:`__setslice__` being called.
.. method:: object.__delslice__(self, i, j)
Called to implement deletion of ``self[i:j]``. Same notes for *i* and *j* as for
:meth:`__getslice__`. This method is deprecated. If no :meth:`__delslice__` is
found, or for extended slicing of the form ``self[i:j:k]``, a slice object is
created, and passed to :meth:`__delitem__`, instead of :meth:`__delslice__`
being called.
Notice that these methods are only invoked when a single slice with a single
colon is used, and the slice method is available. For slice operations
involving extended slice notation, or in absence of the slice methods,
:meth:`__getitem__`, :meth:`__setitem__` or :meth:`__delitem__` is called with a
slice object as argument.
The following example demonstrate how to make your program or module compatible
with earlier versions of Python (assuming that methods :meth:`__getitem__`,
:meth:`__setitem__` and :meth:`__delitem__` support slice objects as
arguments)::
class MyClass:
...
def __getitem__(self, index):
...
def __setitem__(self, index, value):
...
def __delitem__(self, index):
...
if sys.version_info < (2, 0):
# They won't be defined if version is at least 2.0 final
def __getslice__(self, i, j):
return self[max(0, i):max(0, j):]
def __setslice__(self, i, j, seq):
self[max(0, i):max(0, j):] = seq
def __delslice__(self, i, j):
del self[max(0, i):max(0, j):]
...
Note the calls to :func:`max`; these are necessary because of the handling of
negative indices before the :meth:`__\*slice__` methods are called. When
negative indexes are used, the :meth:`__\*item__` methods receive them as
provided, but the :meth:`__\*slice__` methods get a "cooked" form of the index
values. For each negative index value, the length of the sequence is added to
the index before calling the method (which may still result in a negative
index); this is the customary handling of negative indexes by the built-in
sequence types, and the :meth:`__\*item__` methods are expected to do this as
well. However, since they should already be doing that, negative indexes cannot
be passed in; they must be constrained to the bounds of the sequence before
being passed to the :meth:`__\*item__` methods. Calling ``max(0, i)``
conveniently returns the proper value.
.. _numeric-types:
Emulating numeric types
-----------------------
The following methods can be defined to emulate numeric objects. Methods
corresponding to operations that are not supported by the particular kind of
number implemented (e.g., bitwise operations for non-integral numbers) should be
left undefined.
.. method:: object.__add__(self, other)
object.__sub__(self, other)
object.__mul__(self, other)
object.__floordiv__(self, other)
object.__mod__(self, other)
object.__divmod__(self, other)
object.__pow__(self, other[, modulo])
object.__lshift__(self, other)
object.__rshift__(self, other)
object.__and__(self, other)
object.__xor__(self, other)
object.__or__(self, other)
.. index::
builtin: divmod
builtin: pow
builtin: pow
These methods are called to implement the binary arithmetic operations (``+``,
``-``, ``*``, ``//``, ``%``, :func:`divmod`, :func:`pow`, ``**``, ``<<``,
``>>``, ``&``, ``^``, ``|``). For instance, to evaluate the expression
``x + y``, where *x* is an instance of a class that has an :meth:`__add__`
method, ``x.__add__(y)`` is called. The :meth:`__divmod__` method should be the
equivalent to using :meth:`__floordiv__` and :meth:`__mod__`; it should not be
related to :meth:`__truediv__` (described below). Note that :meth:`__pow__`
should be defined to accept an optional third argument if the ternary version of
the built-in :func:`pow` function is to be supported.
If one of those methods does not support the operation with the supplied
arguments, it should return ``NotImplemented``.
.. method:: object.__div__(self, other)
object.__truediv__(self, other)
The division operator (``/``) is implemented by these methods. The
:meth:`__truediv__` method is used when ``__future__.division`` is in effect,
otherwise :meth:`__div__` is used. If only one of these two methods is defined,
the object will not support division in the alternate context; :exc:`TypeError`
will be raised instead.
.. method:: object.__radd__(self, other)
object.__rsub__(self, other)
object.__rmul__(self, other)
object.__rdiv__(self, other)
object.__rtruediv__(self, other)
object.__rfloordiv__(self, other)
object.__rmod__(self, other)
object.__rdivmod__(self, other)
object.__rpow__(self, other)
object.__rlshift__(self, other)
object.__rrshift__(self, other)
object.__rand__(self, other)
object.__rxor__(self, other)
object.__ror__(self, other)
.. index::
builtin: divmod
builtin: pow
These methods are called to implement the binary arithmetic operations (``+``,
``-``, ``*``, ``/``, ``%``, :func:`divmod`, :func:`pow`, ``**``, ``<<``, ``>>``,
``&``, ``^``, ``|``) with reflected (swapped) operands. These functions are
only called if the left operand does not support the corresponding operation and
the operands are of different types. [#]_ For instance, to evaluate the
expression ``x - y``, where *y* is an instance of a class that has an
:meth:`__rsub__` method, ``y.__rsub__(x)`` is called if ``x.__sub__(y)`` returns
*NotImplemented*.
.. index:: builtin: pow
Note that ternary :func:`pow` will not try calling :meth:`__rpow__` (the
coercion rules would become too complicated).
.. note::
If the right operand's type is a subclass of the left operand's type and that
subclass provides the reflected method for the operation, this method will be
called before the left operand's non-reflected method. This behavior allows
subclasses to override their ancestors' operations.
.. method:: object.__iadd__(self, other)
object.__isub__(self, other)
object.__imul__(self, other)
object.__idiv__(self, other)
object.__itruediv__(self, other)
object.__ifloordiv__(self, other)
object.__imod__(self, other)
object.__ipow__(self, other[, modulo])
object.__ilshift__(self, other)
object.__irshift__(self, other)
object.__iand__(self, other)
object.__ixor__(self, other)
object.__ior__(self, other)
These methods are called to implement the augmented arithmetic assignments
(``+=``, ``-=``, ``*=``, ``/=``, ``//=``, ``%=``, ``**=``, ``<<=``, ``>>=``,
``&=``, ``^=``, ``|=``). These methods should attempt to do the operation
in-place (modifying *self*) and return the result (which could be, but does
not have to be, *self*). If a specific method is not defined, the augmented
assignment falls back to the normal methods. For instance, to execute the
statement ``x += y``, where *x* is an instance of a class that has an
:meth:`__iadd__` method, ``x.__iadd__(y)`` is called. If *x* is an instance
of a class that does not define a :meth:`__iadd__` method, ``x.__add__(y)``
and ``y.__radd__(x)`` are considered, as with the evaluation of ``x + y``.
.. method:: object.__neg__(self)
object.__pos__(self)
object.__abs__(self)
object.__invert__(self)
.. index:: builtin: abs
Called to implement the unary arithmetic operations (``-``, ``+``, :func:`abs`
and ``~``).
.. method:: object.__complex__(self)
object.__int__(self)
object.__long__(self)
object.__float__(self)
.. index::
builtin: complex
builtin: int
builtin: long
builtin: float
Called to implement the built-in functions :func:`complex`, :func:`int`,
:func:`long`, and :func:`float`. Should return a value of the appropriate type.
.. method:: object.__oct__(self)
object.__hex__(self)
.. index::
builtin: oct
builtin: hex
Called to implement the built-in functions :func:`oct` and :func:`hex`. Should
return a string value.
.. method:: object.__index__(self)
Called to implement :func:`operator.index`. Also called whenever Python needs
an integer object (such as in slicing). Must return an integer (int or long).
.. versionadded:: 2.5
.. method:: object.__coerce__(self, other)
Called to implement "mixed-mode" numeric arithmetic. Should either return a
2-tuple containing *self* and *other* converted to a common numeric type, or
``None`` if conversion is impossible. When the common type would be the type of
``other``, it is sufficient to return ``None``, since the interpreter will also
ask the other object to attempt a coercion (but sometimes, if the implementation
of the other type cannot be changed, it is useful to do the conversion to the
other type here). A return value of ``NotImplemented`` is equivalent to
returning ``None``.
.. _coercion-rules:
Coercion rules
--------------
This section used to document the rules for coercion. As the language has
evolved, the coercion rules have become hard to document precisely; documenting
what one version of one particular implementation does is undesirable. Instead,
here are some informal guidelines regarding coercion. In Python 3, coercion
will not be supported.
*
If the left operand of a % operator is a string or Unicode object, no coercion
takes place and the string formatting operation is invoked instead.
*
It is no longer recommended to define a coercion operation. Mixed-mode
operations on types that don't define coercion pass the original arguments to
the operation.
*
New-style classes (those derived from :class:`object`) never invoke the
:meth:`__coerce__` method in response to a binary operator; the only time
:meth:`__coerce__` is invoked is when the built-in function :func:`coerce` is
called.
*
For most intents and purposes, an operator that returns ``NotImplemented`` is
treated the same as one that is not implemented at all.
*
Below, :meth:`__op__` and :meth:`__rop__` are used to signify the generic method
names corresponding to an operator; :meth:`__iop__` is used for the
corresponding in-place operator. For example, for the operator '``+``',
:meth:`__add__` and :meth:`__radd__` are used for the left and right variant of
the binary operator, and :meth:`__iadd__` for the in-place variant.
*
For objects *x* and *y*, first ``x.__op__(y)`` is tried. If this is not
implemented or returns ``NotImplemented``, ``y.__rop__(x)`` is tried. If this
is also not implemented or returns ``NotImplemented``, a :exc:`TypeError`
exception is raised. But see the following exception:
*
Exception to the previous item: if the left operand is an instance of a built-in
type or a new-style class, and the right operand is an instance of a proper
subclass of that type or class and overrides the base's :meth:`__rop__` method,
the right operand's :meth:`__rop__` method is tried *before* the left operand's
:meth:`__op__` method.
This is done so that a subclass can completely override binary operators.
Otherwise, the left operand's :meth:`__op__` method would always accept the
right operand: when an instance of a given class is expected, an instance of a
subclass of that class is always acceptable.
*
When either operand type defines a coercion, this coercion is called before that
type's :meth:`__op__` or :meth:`__rop__` method is called, but no sooner. If
the coercion returns an object of a different type for the operand whose
coercion is invoked, part of the process is redone using the new object.
*
When an in-place operator (like '``+=``') is used, if the left operand
implements :meth:`__iop__`, it is invoked without any coercion. When the
operation falls back to :meth:`__op__` and/or :meth:`__rop__`, the normal
coercion rules apply.
*
In ``x + y``, if *x* is a sequence that implements sequence concatenation,
sequence concatenation is invoked.
*
In ``x * y``, if one operand is a sequence that implements sequence
repetition, and the other is an integer (:class:`int` or :class:`long`),
sequence repetition is invoked.
*
Rich comparisons (implemented by methods :meth:`__eq__` and so on) never use
coercion. Three-way comparison (implemented by :meth:`__cmp__`) does use
coercion under the same conditions as other binary operations use it.
*
In the current implementation, the built-in numeric types :class:`int`,
:class:`long`, :class:`float`, and :class:`complex` do not use coercion.
All these types implement a :meth:`__coerce__` method, for use by the built-in
:func:`coerce` function.
.. versionchanged:: 2.7
The complex type no longer makes implicit calls to the :meth:`__coerce__`
method for mixed-type binary arithmetic operations.
.. _context-managers:
With Statement Context Managers
-------------------------------
.. versionadded:: 2.5
A :dfn:`context manager` is an object that defines the runtime context to be
established when executing a :keyword:`with` statement. The context manager
handles the entry into, and the exit from, the desired runtime context for the
execution of the block of code. Context managers are normally invoked using the
:keyword:`with` statement (described in section :ref:`with`), but can also be
used by directly invoking their methods.
.. index::
statement: with
single: context manager
Typical uses of context managers include saving and restoring various kinds of
global state, locking and unlocking resources, closing opened files, etc.
For more information on context managers, see :ref:`typecontextmanager`.
.. method:: object.__enter__(self)
Enter the runtime context related to this object. The :keyword:`with` statement
will bind this method's return value to the target(s) specified in the
:keyword:`as` clause of the statement, if any.
.. method:: object.__exit__(self, exc_type, exc_value, traceback)
Exit the runtime context related to this object. The parameters describe the
exception that caused the context to be exited. If the context was exited
without an exception, all three arguments will be :const:`None`.
If an exception is supplied, and the method wishes to suppress the exception
(i.e., prevent it from being propagated), it should return a true value.
Otherwise, the exception will be processed normally upon exit from this method.
Note that :meth:`__exit__` methods should not reraise the passed-in exception;
this is the caller's responsibility.
.. seealso::
:pep:`343` - The "with" statement
The specification, background, and examples for the Python :keyword:`with`
statement.
.. _old-style-special-lookup:
Special method lookup for old-style classes
-------------------------------------------
For old-style classes, special methods are always looked up in exactly the
same way as any other method or attribute. This is the case regardless of
whether the method is being looked up explicitly as in ``x.__getitem__(i)``
or implicitly as in ``x[i]``.
This behaviour means that special methods may exhibit different behaviour
for different instances of a single old-style class if the appropriate
special attributes are set differently::
>>> class C:
... pass
...
>>> c1 = C()
>>> c2 = C()
>>> c1.__len__ = lambda: 5
>>> c2.__len__ = lambda: 9
>>> len(c1)
5
>>> len(c2)
9
.. _new-style-special-lookup:
Special method lookup for new-style classes
-------------------------------------------
For new-style classes, implicit invocations of special methods are only guaranteed
to work correctly if defined on an object's type, not in the object's instance
dictionary. That behaviour is the reason why the following code raises an
exception (unlike the equivalent example with old-style classes)::
>>> class C(object):
... pass
...
>>> c = C()
>>> c.__len__ = lambda: 5
>>> len(c)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: object of type 'C' has no len()
The rationale behind this behaviour lies with a number of special methods such
as :meth:`__hash__` and :meth:`__repr__` that are implemented by all objects,
including type objects. If the implicit lookup of these methods used the
conventional lookup process, they would fail when invoked on the type object
itself::
>>> 1 .__hash__() == hash(1)
True
>>> int.__hash__() == hash(int)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: descriptor '__hash__' of 'int' object needs an argument
Incorrectly attempting to invoke an unbound method of a class in this way is
sometimes referred to as 'metaclass confusion', and is avoided by bypassing
the instance when looking up special methods::
>>> type(1).__hash__(1) == hash(1)
True
>>> type(int).__hash__(int) == hash(int)
True
In addition to bypassing any instance attributes in the interest of
correctness, implicit special method lookup generally also bypasses the
:meth:`__getattribute__` method even of the object's metaclass::
>>> class Meta(type):
... def __getattribute__(*args):
... print "Metaclass getattribute invoked"
... return type.__getattribute__(*args)
...
>>> class C(object):
... __metaclass__ = Meta
... def __len__(self):
... return 10
... def __getattribute__(*args):
... print "Class getattribute invoked"
... return object.__getattribute__(*args)
...
>>> c = C()
>>> c.__len__() # Explicit lookup via instance
Class getattribute invoked
10
>>> type(c).__len__(c) # Explicit lookup via type
Metaclass getattribute invoked
10
>>> len(c) # Implicit lookup
10
Bypassing the :meth:`__getattribute__` machinery in this fashion
provides significant scope for speed optimisations within the
interpreter, at the cost of some flexibility in the handling of
special methods (the special method *must* be set on the class
object itself in order to be consistently invoked by the interpreter).
.. rubric:: Footnotes
.. [#] It *is* possible in some cases to change an object's type, under certain
controlled conditions. It generally isn't a good idea though, since it can
lead to some very strange behaviour if it is handled incorrectly.
.. [#] For operands of the same type, it is assumed that if the non-reflected method
(such as :meth:`__add__`) fails the operation is not supported, which is why the
reflected method is not called.
PK
%�\��{��* �* . html/_sources/reference/executionmodel.rst.txtnu �[���
.. _execmodel:
***************
Execution model
***************
.. index:: single: execution model
.. _naming:
Naming and binding
==================
.. index::
pair: code; block
single: namespace
single: scope
.. index::
single: name
pair: binding; name
:dfn:`Names` refer to objects. Names are introduced by name binding operations.
Each occurrence of a name in the program text refers to the :dfn:`binding` of
that name established in the innermost function block containing the use.
.. index:: single: block
A :dfn:`block` is a piece of Python program text that is executed as a unit.
The following are blocks: a module, a function body, and a class definition.
Each command typed interactively is a block. A script file (a file given as
standard input to the interpreter or specified on the interpreter command line
the first argument) is a code block. A script command (a command specified on
the interpreter command line with the '**-c**' option) is a code block. The
file read by the built-in function :func:`execfile` is a code block. The string
argument passed to the built-in function :func:`eval` and to the :keyword:`exec`
statement is a code block. The expression read and evaluated by the built-in
function :func:`input` is a code block.
.. index:: pair: execution; frame
A code block is executed in an :dfn:`execution frame`. A frame contains some
administrative information (used for debugging) and determines where and how
execution continues after the code block's execution has completed.
.. index:: single: scope
A :dfn:`scope` defines the visibility of a name within a block. If a local
variable is defined in a block, its scope includes that block. If the
definition occurs in a function block, the scope extends to any blocks contained
within the defining one, unless a contained block introduces a different binding
for the name. The scope of names defined in a class block is limited to the
class block; it does not extend to the code blocks of methods -- this includes
generator expressions since they are implemented using a function scope. This
means that the following will fail::
class A:
a = 42
b = list(a + i for i in range(10))
.. index:: single: environment
When a name is used in a code block, it is resolved using the nearest enclosing
scope. The set of all such scopes visible to a code block is called the block's
:dfn:`environment`.
.. index:: pair: free; variable
If a name is bound in a block, it is a local variable of that block. If a name
is bound at the module level, it is a global variable. (The variables of the
module code block are local and global.) If a variable is used in a code block
but not defined there, it is a :dfn:`free variable`.
.. index::
single: NameError (built-in exception)
single: UnboundLocalError
When a name is not found at all, a :exc:`NameError` exception is raised. If the
name refers to a local variable that has not been bound, a
:exc:`UnboundLocalError` exception is raised. :exc:`UnboundLocalError` is a
subclass of :exc:`NameError`.
.. index:: statement: from
The following constructs bind names: formal parameters to functions,
:keyword:`import` statements, class and function definitions (these bind the
class or function name in the defining block), and targets that are identifiers
if occurring in an assignment, :keyword:`for` loop header, in the second
position of an :keyword:`except` clause header or after :keyword:`as` in a
:keyword:`with` statement. The :keyword:`import` statement
of the form ``from ... import *`` binds all names defined in the imported
module, except those beginning with an underscore. This form may only be used
at the module level.
A target occurring in a :keyword:`del` statement is also considered bound for
this purpose (though the actual semantics are to unbind the name). It is
illegal to unbind a name that is referenced by an enclosing scope; the compiler
will report a :exc:`SyntaxError`.
Each assignment or import statement occurs within a block defined by a class or
function definition or at the module level (the top-level code block).
If a name binding operation occurs anywhere within a code block, all uses of the
name within the block are treated as references to the current block. This can
lead to errors when a name is used within a block before it is bound. This rule
is subtle. Python lacks declarations and allows name binding operations to
occur anywhere within a code block. The local variables of a code block can be
determined by scanning the entire text of the block for name binding operations.
If the global statement occurs within a block, all uses of the name specified in
the statement refer to the binding of that name in the top-level namespace.
Names are resolved in the top-level namespace by searching the global namespace,
i.e. the namespace of the module containing the code block, and the builtins
namespace, the namespace of the module :mod:`__builtin__`. The global namespace
is searched first. If the name is not found there, the builtins namespace is
searched. The global statement must precede all uses of the name.
.. index:: pair: restricted; execution
The builtins namespace associated with the execution of a code block is actually
found by looking up the name ``__builtins__`` in its global namespace; this
should be a dictionary or a module (in the latter case the module's dictionary
is used). By default, when in the :mod:`__main__` module, ``__builtins__`` is
the built-in module :mod:`__builtin__` (note: no 's'); when in any other module,
``__builtins__`` is an alias for the dictionary of the :mod:`__builtin__` module
itself. ``__builtins__`` can be set to a user-created dictionary to create a
weak form of restricted execution.
.. impl-detail::
Users should not touch ``__builtins__``; it is strictly an implementation
detail. Users wanting to override values in the builtins namespace should
:keyword:`import` the :mod:`__builtin__` (no 's') module and modify its
attributes appropriately.
.. index:: module: __main__
The namespace for a module is automatically created the first time a module is
imported. The main module for a script is always called :mod:`__main__`.
The :keyword:`global` statement has the same scope as a name binding operation
in the same block. If the nearest enclosing scope for a free variable contains
a global statement, the free variable is treated as a global.
A class definition is an executable statement that may use and define names.
These references follow the normal rules for name resolution. The namespace of
the class definition becomes the attribute dictionary of the class. Names
defined at the class scope are not visible in methods.
.. _dynamic-features:
Interaction with dynamic features
---------------------------------
There are several cases where Python statements are illegal when used in
conjunction with nested scopes that contain free variables.
If a variable is referenced in an enclosing scope, it is illegal to delete the
name. An error will be reported at compile time.
If the wild card form of import --- ``import *`` --- is used in a function and
the function contains or is a nested block with free variables, the compiler
will raise a :exc:`SyntaxError`.
If :keyword:`exec` is used in a function and the function contains or is a
nested block with free variables, the compiler will raise a :exc:`SyntaxError`
unless the exec explicitly specifies the local namespace for the
:keyword:`exec`. (In other words, ``exec obj`` would be illegal, but ``exec obj
in ns`` would be legal.)
The :func:`eval`, :func:`execfile`, and :func:`input` functions and the
:keyword:`exec` statement do not have access to the full environment for
resolving names. Names may be resolved in the local and global namespaces of
the caller. Free variables are not resolved in the nearest enclosing namespace,
but in the global namespace. [#]_ The :keyword:`exec` statement and the
:func:`eval` and :func:`execfile` functions have optional arguments to override
the global and local namespace. If only one namespace is specified, it is used
for both.
.. _exceptions:
Exceptions
==========
.. index:: single: exception
.. index::
single: raise an exception
single: handle an exception
single: exception handler
single: errors
single: error handling
Exceptions are a means of breaking out of the normal flow of control of a code
block in order to handle errors or other exceptional conditions. An exception
is *raised* at the point where the error is detected; it may be *handled* by the
surrounding code block or by any code block that directly or indirectly invoked
the code block where the error occurred.
The Python interpreter raises an exception when it detects a run-time error
(such as division by zero). A Python program can also explicitly raise an
exception with the :keyword:`raise` statement. Exception handlers are specified
with the :keyword:`try` ... :keyword:`except` statement. The :keyword:`finally`
clause of such a statement can be used to specify cleanup code which does not
handle the exception, but is executed whether an exception occurred or not in
the preceding code.
.. index:: single: termination model
Python uses the "termination" model of error handling: an exception handler can
find out what happened and continue execution at an outer level, but it cannot
repair the cause of the error and retry the failing operation (except by
re-entering the offending piece of code from the top).
.. index:: single: SystemExit (built-in exception)
When an exception is not handled at all, the interpreter terminates execution of
the program, or returns to its interactive main loop. In either case, it prints
a stack backtrace, except when the exception is :exc:`SystemExit`.
Exceptions are identified by class instances. The :keyword:`except` clause is
selected depending on the class of the instance: it must reference the class of
the instance or a base class thereof. The instance can be received by the
handler and can carry additional information about the exceptional condition.
Exceptions can also be identified by strings, in which case the
:keyword:`except` clause is selected by object identity. An arbitrary value can
be raised along with the identifying string which can be passed to the handler.
.. note::
Messages to exceptions are not part of the Python API. Their contents may
change from one version of Python to the next without warning and should not be
relied on by code which will run under multiple versions of the interpreter.
See also the description of the :keyword:`try` statement in section :ref:`try`
and :keyword:`raise` statement in section :ref:`raise`.
.. rubric:: Footnotes
.. [#] This limitation occurs because the code that is executed by these operations is
not available at the time the module is compiled.
PK
%�\�mW&]� ]� + html/_sources/reference/expressions.rst.txtnu �[���
.. _expressions:
***********
Expressions
***********
.. index:: single: expression
This chapter explains the meaning of the elements of expressions in Python.
.. index:: single: BNF
**Syntax Notes:** In this and the following chapters, extended BNF notation will
be used to describe syntax, not lexical analysis. When (one alternative of) a
syntax rule has the form
.. productionlist:: *
name: `othername`
.. index:: single: syntax
and no semantics are given, the semantics of this form of ``name`` are the same
as for ``othername``.
.. _conversions:
Arithmetic conversions
======================
.. index:: pair: arithmetic; conversion
When a description of an arithmetic operator below uses the phrase "the numeric
arguments are converted to a common type," the arguments are coerced using the
coercion rules listed at :ref:`coercion-rules`. If both arguments are standard
numeric types, the following coercions are applied:
* If either argument is a complex number, the other is converted to complex;
* otherwise, if either argument is a floating point number, the other is
converted to floating point;
* otherwise, if either argument is a long integer, the other is converted to
long integer;
* otherwise, both must be plain integers and no conversion is necessary.
Some additional rules apply for certain operators (e.g., a string left argument
to the '%' operator). Extensions can define their own coercions.
.. _atoms:
Atoms
=====
.. index:: single: atom
Atoms are the most basic elements of expressions. The simplest atoms are
identifiers or literals. Forms enclosed in reverse quotes or in parentheses,
brackets or braces are also categorized syntactically as atoms. The syntax for
atoms is:
.. productionlist::
atom: `identifier` | `literal` | `enclosure`
enclosure: `parenth_form` | `list_display`
: | `generator_expression` | `dict_display` | `set_display`
: | `string_conversion` | `yield_atom`
.. _atom-identifiers:
Identifiers (Names)
-------------------
.. index::
single: name
single: identifier
An identifier occurring as an atom is a name. See section :ref:`identifiers`
for lexical definition and section :ref:`naming` for documentation of naming and
binding.
.. index:: exception: NameError
When the name is bound to an object, evaluation of the atom yields that object.
When a name is not bound, an attempt to evaluate it raises a :exc:`NameError`
exception.
.. index::
pair: name; mangling
pair: private; names
**Private name mangling:** When an identifier that textually occurs in a class
definition begins with two or more underscore characters and does not end in two
or more underscores, it is considered a :dfn:`private name` of that class.
Private names are transformed to a longer form before code is generated for
them. The transformation inserts the class name, with leading underscores
removed and a single underscore inserted, in front of the name. For example,
the identifier ``__spam`` occurring in a class named ``Ham`` will be transformed
to ``_Ham__spam``. This transformation is independent of the syntactical
context in which the identifier is used. If the transformed name is extremely
long (longer than 255 characters), implementation defined truncation may happen.
If the class name consists only of underscores, no transformation is done.
.. _atom-literals:
Literals
--------
.. index:: single: literal
Python supports string literals and various numeric literals:
.. productionlist::
literal: `stringliteral` | `integer` | `longinteger`
: | `floatnumber` | `imagnumber`
Evaluation of a literal yields an object of the given type (string, integer,
long integer, floating point number, complex number) with the given value. The
value may be approximated in the case of floating point and imaginary (complex)
literals. See section :ref:`literals` for details.
.. index::
triple: immutable; data; type
pair: immutable; object
All literals correspond to immutable data types, and hence the object's identity
is less important than its value. Multiple evaluations of literals with the
same value (either the same occurrence in the program text or a different
occurrence) may obtain the same object or a different object with the same
value.
.. _parenthesized:
Parenthesized forms
-------------------
.. index:: single: parenthesized form
A parenthesized form is an optional expression list enclosed in parentheses:
.. productionlist::
parenth_form: "(" [`expression_list`] ")"
A parenthesized expression list yields whatever that expression list yields: if
the list contains at least one comma, it yields a tuple; otherwise, it yields
the single expression that makes up the expression list.
.. index:: pair: empty; tuple
An empty pair of parentheses yields an empty tuple object. Since tuples are
immutable, the rules for literals apply (i.e., two occurrences of the empty
tuple may or may not yield the same object).
.. index::
single: comma
pair: tuple; display
Note that tuples are not formed by the parentheses, but rather by use of the
comma operator. The exception is the empty tuple, for which parentheses *are*
required --- allowing unparenthesized "nothing" in expressions would cause
ambiguities and allow common typos to pass uncaught.
.. _lists:
List displays
-------------
.. index::
pair: list; display
pair: list; comprehensions
A list display is a possibly empty series of expressions enclosed in square
brackets:
.. productionlist::
list_display: "[" [`expression_list` | `list_comprehension`] "]"
list_comprehension: `expression` `list_for`
list_for: "for" `target_list` "in" `old_expression_list` [`list_iter`]
old_expression_list: `old_expression` [("," `old_expression`)+ [","]]
old_expression: `or_test` | `old_lambda_expr`
list_iter: `list_for` | `list_if`
list_if: "if" `old_expression` [`list_iter`]
.. index::
pair: list; comprehensions
object: list
pair: empty; list
A list display yields a new list object. Its contents are specified by
providing either a list of expressions or a list comprehension. When a
comma-separated list of expressions is supplied, its elements are evaluated from
left to right and placed into the list object in that order. When a list
comprehension is supplied, it consists of a single expression followed by at
least one :keyword:`for` clause and zero or more :keyword:`for` or :keyword:`if`
clauses. In this case, the elements of the new list are those that would be
produced by considering each of the :keyword:`for` or :keyword:`if` clauses a
block, nesting from left to right, and evaluating the expression to produce a
list element each time the innermost block is reached [#]_.
.. _comprehensions:
Displays for sets and dictionaries
----------------------------------
For constructing a set or a dictionary Python provides special syntax
called "displays", each of them in two flavors:
* either the container contents are listed explicitly, or
* they are computed via a set of looping and filtering instructions, called a
:dfn:`comprehension`.
Common syntax elements for comprehensions are:
.. productionlist::
comprehension: `expression` `comp_for`
comp_for: "for" `target_list` "in" `or_test` [`comp_iter`]
comp_iter: `comp_for` | `comp_if`
comp_if: "if" `expression_nocond` [`comp_iter`]
The comprehension consists of a single expression followed by at least one
:keyword:`for` clause and zero or more :keyword:`for` or :keyword:`if` clauses.
In this case, the elements of the new container are those that would be produced
by considering each of the :keyword:`for` or :keyword:`if` clauses a block,
nesting from left to right, and evaluating the expression to produce an element
each time the innermost block is reached.
Note that the comprehension is executed in a separate scope, so names assigned
to in the target list don't "leak" in the enclosing scope.
.. _genexpr:
Generator expressions
---------------------
.. index:: pair: generator; expression
object: generator
A generator expression is a compact generator notation in parentheses:
.. productionlist::
generator_expression: "(" `expression` `comp_for` ")"
A generator expression yields a new generator object. Its syntax is the same as
for comprehensions, except that it is enclosed in parentheses instead of
brackets or curly braces.
Variables used in the generator expression are evaluated lazily when the
:meth:`__next__` method is called for generator object (in the same fashion as
normal generators). However, the leftmost :keyword:`for` clause is immediately
evaluated, so that an error produced by it can be seen before any other possible
error in the code that handles the generator expression. Subsequent
:keyword:`for` clauses cannot be evaluated immediately since they may depend on
the previous :keyword:`for` loop. For example: ``(x*y for x in range(10) for y
in bar(x))``.
The parentheses can be omitted on calls with only one argument. See section
:ref:`calls` for the detail.
.. _dict:
Dictionary displays
-------------------
.. index:: pair: dictionary; display
key, datum, key/datum pair
object: dictionary
A dictionary display is a possibly empty series of key/datum pairs enclosed in
curly braces:
.. productionlist::
dict_display: "{" [`key_datum_list` | `dict_comprehension`] "}"
key_datum_list: `key_datum` ("," `key_datum`)* [","]
key_datum: `expression` ":" `expression`
dict_comprehension: `expression` ":" `expression` `comp_for`
A dictionary display yields a new dictionary object.
If a comma-separated sequence of key/datum pairs is given, they are evaluated
from left to right to define the entries of the dictionary: each key object is
used as a key into the dictionary to store the corresponding datum. This means
that you can specify the same key multiple times in the key/datum list, and the
final dictionary's value for that key will be the last one given.
A dict comprehension, in contrast to list and set comprehensions, needs two
expressions separated with a colon followed by the usual "for" and "if" clauses.
When the comprehension is run, the resulting key and value elements are inserted
in the new dictionary in the order they are produced.
.. index:: pair: immutable; object
hashable
Restrictions on the types of the key values are listed earlier in section
:ref:`types`. (To summarize, the key type should be :term:`hashable`, which excludes
all mutable objects.) Clashes between duplicate keys are not detected; the last
datum (textually rightmost in the display) stored for a given key value
prevails.
.. _set:
Set displays
------------
.. index:: pair: set; display
object: set
A set display is denoted by curly braces and distinguishable from dictionary
displays by the lack of colons separating keys and values:
.. productionlist::
set_display: "{" (`expression_list` | `comprehension`) "}"
A set display yields a new mutable set object, the contents being specified by
either a sequence of expressions or a comprehension. When a comma-separated
list of expressions is supplied, its elements are evaluated from left to right
and added to the set object. When a comprehension is supplied, the set is
constructed from the elements resulting from the comprehension.
An empty set cannot be constructed with ``{}``; this literal constructs an empty
dictionary.
.. _string-conversions:
String conversions
------------------
.. index::
pair: string; conversion
pair: reverse; quotes
pair: backward; quotes
single: back-quotes
A string conversion is an expression list enclosed in reverse (a.k.a. backward)
quotes:
.. productionlist::
string_conversion: "`" `expression_list` "`"
A string conversion evaluates the contained expression list and converts the
resulting object into a string according to rules specific to its type.
If the object is a string, a number, ``None``, or a tuple, list or dictionary
containing only objects whose type is one of these, the resulting string is a
valid Python expression which can be passed to the built-in function
:func:`eval` to yield an expression with the same value (or an approximation, if
floating point numbers are involved).
(In particular, converting a string adds quotes around it and converts "funny"
characters to escape sequences that are safe to print.)
.. index:: object: recursive
Recursive objects (for example, lists or dictionaries that contain a reference
to themselves, directly or indirectly) use ``...`` to indicate a recursive
reference, and the result cannot be passed to :func:`eval` to get an equal value
(:exc:`SyntaxError` will be raised instead).
.. index::
builtin: repr
builtin: str
The built-in function :func:`repr` performs exactly the same conversion in its
argument as enclosing it in parentheses and reverse quotes does. The built-in
function :func:`str` performs a similar but more user-friendly conversion.
.. _yieldexpr:
Yield expressions
-----------------
.. index::
keyword: yield
pair: yield; expression
pair: generator; function
.. productionlist::
yield_atom: "(" `yield_expression` ")"
yield_expression: "yield" [`expression_list`]
.. versionadded:: 2.5
The :keyword:`yield` expression is only used when defining a generator function,
and can only be used in the body of a function definition. Using a
:keyword:`yield` expression in a function definition is sufficient to cause that
definition to create a generator function instead of a normal function.
When a generator function is called, it returns an iterator known as a
generator. That generator then controls the execution of a generator function.
The execution starts when one of the generator's methods is called. At that
time, the execution proceeds to the first :keyword:`yield` expression, where it
is suspended again, returning the value of :token:`expression_list` to
generator's caller. By suspended we mean that all local state is retained,
including the current bindings of local variables, the instruction pointer, and
the internal evaluation stack. When the execution is resumed by calling one of
the generator's methods, the function can proceed exactly as if the
:keyword:`yield` expression was just another external call. The value of the
:keyword:`yield` expression after resuming depends on the method which resumed
the execution.
.. index:: single: coroutine
All of this makes generator functions quite similar to coroutines; they yield
multiple times, they have more than one entry point and their execution can be
suspended. The only difference is that a generator function cannot control
where should the execution continue after it yields; the control is always
transferred to the generator's caller.
.. index:: object: generator
Generator-iterator methods
^^^^^^^^^^^^^^^^^^^^^^^^^^
This subsection describes the methods of a generator iterator. They can
be used to control the execution of a generator function.
Note that calling any of the generator methods below when the generator
is already executing raises a :exc:`ValueError` exception.
.. index:: exception: StopIteration
.. method:: generator.next()
Starts the execution of a generator function or resumes it at the last executed
:keyword:`yield` expression. When a generator function is resumed with a
:meth:`~generator.next` method, the current :keyword:`yield` expression
always evaluates to
:const:`None`. The execution then continues to the next :keyword:`yield`
expression, where the generator is suspended again, and the value of the
:token:`expression_list` is returned to :meth:`~generator.next`'s caller.
If the generator
exits without yielding another value, a :exc:`StopIteration` exception is
raised.
.. method:: generator.send(value)
Resumes the execution and "sends" a value into the generator function. The
``value`` argument becomes the result of the current :keyword:`yield`
expression. The :meth:`send` method returns the next value yielded by the
generator, or raises :exc:`StopIteration` if the generator exits without
yielding another value. When :meth:`send` is called to start the generator, it
must be called with :const:`None` as the argument, because there is no
:keyword:`yield` expression that could receive the value.
.. method:: generator.throw(type[, value[, traceback]])
Raises an exception of type ``type`` at the point where generator was paused,
and returns the next value yielded by the generator function. If the generator
exits without yielding another value, a :exc:`StopIteration` exception is
raised. If the generator function does not catch the passed-in exception, or
raises a different exception, then that exception propagates to the caller.
.. index:: exception: GeneratorExit
.. method:: generator.close()
Raises a :exc:`GeneratorExit` at the point where the generator function was
paused. If the generator function then raises :exc:`StopIteration` (by exiting
normally, or due to already being closed) or :exc:`GeneratorExit` (by not
catching the exception), close returns to its caller. If the generator yields a
value, a :exc:`RuntimeError` is raised. If the generator raises any other
exception, it is propagated to the caller. :meth:`close` does nothing if the
generator has already exited due to an exception or normal exit.
Here is a simple example that demonstrates the behavior of generators and
generator functions::
>>> def echo(value=None):
... print "Execution starts when 'next()' is called for the first time."
... try:
... while True:
... try:
... value = (yield value)
... except Exception, e:
... value = e
... finally:
... print "Don't forget to clean up when 'close()' is called."
...
>>> generator = echo(1)
>>> print generator.next()
Execution starts when 'next()' is called for the first time.
1
>>> print generator.next()
None
>>> print generator.send(2)
2
>>> generator.throw(TypeError, "spam")
TypeError('spam',)
>>> generator.close()
Don't forget to clean up when 'close()' is called.
.. seealso::
:pep:`342` - Coroutines via Enhanced Generators
The proposal to enhance the API and syntax of generators, making them usable as
simple coroutines.
.. _primaries:
Primaries
=========
.. index:: single: primary
Primaries represent the most tightly bound operations of the language. Their
syntax is:
.. productionlist::
primary: `atom` | `attributeref` | `subscription` | `slicing` | `call`
.. _attribute-references:
Attribute references
--------------------
.. index:: pair: attribute; reference
An attribute reference is a primary followed by a period and a name:
.. productionlist::
attributeref: `primary` "." `identifier`
.. index::
exception: AttributeError
object: module
object: list
The primary must evaluate to an object of a type that supports attribute
references, e.g., a module, list, or an instance. This object is then asked to
produce the attribute whose name is the identifier. If this attribute is not
available, the exception :exc:`AttributeError` is raised. Otherwise, the type
and value of the object produced is determined by the object. Multiple
evaluations of the same attribute reference may yield different objects.
.. _subscriptions:
Subscriptions
-------------
.. index:: single: subscription
.. index::
object: sequence
object: mapping
object: string
object: tuple
object: list
object: dictionary
pair: sequence; item
A subscription selects an item of a sequence (string, tuple or list) or mapping
(dictionary) object:
.. productionlist::
subscription: `primary` "[" `expression_list` "]"
The primary must evaluate to an object of a sequence or mapping type.
If the primary is a mapping, the expression list must evaluate to an object
whose value is one of the keys of the mapping, and the subscription selects the
value in the mapping that corresponds to that key. (The expression list is a
tuple except if it has exactly one item.)
If the primary is a sequence, the expression list must evaluate to a plain
integer. If this value is negative, the length of the sequence is added to it
(so that, e.g., ``x[-1]`` selects the last item of ``x``.) The resulting value
must be a nonnegative integer less than the number of items in the sequence, and
the subscription selects the item whose index is that value (counting from
zero).
.. index::
single: character
pair: string; item
A string's items are characters. A character is not a separate data type but a
string of exactly one character.
.. _slicings:
Slicings
--------
.. index::
single: slicing
single: slice
.. index::
object: sequence
object: string
object: tuple
object: list
A slicing selects a range of items in a sequence object (e.g., a string, tuple
or list). Slicings may be used as expressions or as targets in assignment or
:keyword:`del` statements. The syntax for a slicing:
.. productionlist::
slicing: `simple_slicing` | `extended_slicing`
simple_slicing: `primary` "[" `short_slice` "]"
extended_slicing: `primary` "[" `slice_list` "]"
slice_list: `slice_item` ("," `slice_item`)* [","]
slice_item: `expression` | `proper_slice` | `ellipsis`
proper_slice: `short_slice` | `long_slice`
short_slice: [`lower_bound`] ":" [`upper_bound`]
long_slice: `short_slice` ":" [`stride`]
lower_bound: `expression`
upper_bound: `expression`
stride: `expression`
ellipsis: "..."
.. index:: pair: extended; slicing
There is ambiguity in the formal syntax here: anything that looks like an
expression list also looks like a slice list, so any subscription can be
interpreted as a slicing. Rather than further complicating the syntax, this is
disambiguated by defining that in this case the interpretation as a subscription
takes priority over the interpretation as a slicing (this is the case if the
slice list contains no proper slice nor ellipses). Similarly, when the slice
list has exactly one short slice and no trailing comma, the interpretation as a
simple slicing takes priority over that as an extended slicing.
The semantics for a simple slicing are as follows. The primary must evaluate to
a sequence object. The lower and upper bound expressions, if present, must
evaluate to plain integers; defaults are zero and the ``sys.maxint``,
respectively. If either bound is negative, the sequence's length is added to
it. The slicing now selects all items with index *k* such that ``i <= k < j``
where *i* and *j* are the specified lower and upper bounds. This may be an
empty sequence. It is not an error if *i* or *j* lie outside the range of valid
indexes (such items don't exist so they aren't selected).
.. index::
single: start (slice object attribute)
single: stop (slice object attribute)
single: step (slice object attribute)
The semantics for an extended slicing are as follows. The primary must evaluate
to a mapping object, and it is indexed with a key that is constructed from the
slice list, as follows. If the slice list contains at least one comma, the key
is a tuple containing the conversion of the slice items; otherwise, the
conversion of the lone slice item is the key. The conversion of a slice item
that is an expression is that expression. The conversion of an ellipsis slice
item is the built-in ``Ellipsis`` object. The conversion of a proper slice is a
slice object (see section :ref:`types`) whose :attr:`~slice.start`,
:attr:`~slice.stop` and :attr:`~slice.step` attributes are the values of the
expressions given as lower bound, upper bound and stride, respectively,
substituting ``None`` for missing expressions.
.. index::
object: callable
single: call
single: argument; call semantics
.. _calls:
Calls
-----
A call calls a callable object (e.g., a :term:`function`) with a possibly empty
series of :term:`arguments <argument>`:
.. productionlist::
call: `primary` "(" [`argument_list` [","]
: | `expression` `genexpr_for`] ")"
argument_list: `positional_arguments` ["," `keyword_arguments`]
: ["," "*" `expression`] ["," `keyword_arguments`]
: ["," "**" `expression`]
: | `keyword_arguments` ["," "*" `expression`]
: ["," "**" `expression`]
: | "*" `expression` ["," `keyword_arguments`] ["," "**" `expression`]
: | "**" `expression`
positional_arguments: `expression` ("," `expression`)*
keyword_arguments: `keyword_item` ("," `keyword_item`)*
keyword_item: `identifier` "=" `expression`
A trailing comma may be present after the positional and keyword arguments but
does not affect the semantics.
.. index::
single: parameter; call semantics
The primary must evaluate to a callable object (user-defined functions, built-in
functions, methods of built-in objects, class objects, methods of class
instances, and certain class instances themselves are callable; extensions may
define additional callable object types). All argument expressions are
evaluated before the call is attempted. Please refer to section :ref:`function`
for the syntax of formal :term:`parameter` lists.
If keyword arguments are present, they are first converted to positional
arguments, as follows. First, a list of unfilled slots is created for the
formal parameters. If there are N positional arguments, they are placed in the
first N slots. Next, for each keyword argument, the identifier is used to
determine the corresponding slot (if the identifier is the same as the first
formal parameter name, the first slot is used, and so on). If the slot is
already filled, a :exc:`TypeError` exception is raised. Otherwise, the value of
the argument is placed in the slot, filling it (even if the expression is
``None``, it fills the slot). When all arguments have been processed, the slots
that are still unfilled are filled with the corresponding default value from the
function definition. (Default values are calculated, once, when the function is
defined; thus, a mutable object such as a list or dictionary used as default
value will be shared by all calls that don't specify an argument value for the
corresponding slot; this should usually be avoided.) If there are any unfilled
slots for which no default value is specified, a :exc:`TypeError` exception is
raised. Otherwise, the list of filled slots is used as the argument list for
the call.
.. impl-detail::
An implementation may provide built-in functions whose positional parameters
do not have names, even if they are 'named' for the purpose of documentation,
and which therefore cannot be supplied by keyword. In CPython, this is the
case for functions implemented in C that use :c:func:`PyArg_ParseTuple` to
parse their arguments.
If there are more positional arguments than there are formal parameter slots, a
:exc:`TypeError` exception is raised, unless a formal parameter using the syntax
``*identifier`` is present; in this case, that formal parameter receives a tuple
containing the excess positional arguments (or an empty tuple if there were no
excess positional arguments).
If any keyword argument does not correspond to a formal parameter name, a
:exc:`TypeError` exception is raised, unless a formal parameter using the syntax
``**identifier`` is present; in this case, that formal parameter receives a
dictionary containing the excess keyword arguments (using the keywords as keys
and the argument values as corresponding values), or a (new) empty dictionary if
there were no excess keyword arguments.
.. index::
single: *; in function calls
If the syntax ``*expression`` appears in the function call, ``expression`` must
evaluate to an iterable. Elements from this iterable are treated as if they
were additional positional arguments; if there are positional arguments
*x1*, ..., *xN*, and ``expression`` evaluates to a sequence *y1*, ..., *yM*, this
is equivalent to a call with M+N positional arguments *x1*, ..., *xN*, *y1*,
..., *yM*.
A consequence of this is that although the ``*expression`` syntax may appear
*after* some keyword arguments, it is processed *before* the keyword arguments
(and the ``**expression`` argument, if any -- see below). So::
>>> def f(a, b):
... print a, b
...
>>> f(b=1, *(2,))
2 1
>>> f(a=1, *(2,))
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: f() got multiple values for keyword argument 'a'
>>> f(1, *(2,))
1 2
It is unusual for both keyword arguments and the ``*expression`` syntax to be
used in the same call, so in practice this confusion does not arise.
.. index::
single: **; in function calls
If the syntax ``**expression`` appears in the function call, ``expression`` must
evaluate to a mapping, the contents of which are treated as additional keyword
arguments. In the case of a keyword appearing in both ``expression`` and as an
explicit keyword argument, a :exc:`TypeError` exception is raised.
Formal parameters using the syntax ``*identifier`` or ``**identifier`` cannot be
used as positional argument slots or as keyword argument names. Formal
parameters using the syntax ``(sublist)`` cannot be used as keyword argument
names; the outermost sublist corresponds to a single unnamed argument slot, and
the argument value is assigned to the sublist using the usual tuple assignment
rules after all other parameter processing is done.
A call always returns some value, possibly ``None``, unless it raises an
exception. How this value is computed depends on the type of the callable
object.
If it is---
a user-defined function:
.. index::
pair: function; call
triple: user-defined; function; call
object: user-defined function
object: function
The code block for the function is executed, passing it the argument list. The
first thing the code block will do is bind the formal parameters to the
arguments; this is described in section :ref:`function`. When the code block
executes a :keyword:`return` statement, this specifies the return value of the
function call.
a built-in function or method:
.. index::
pair: function; call
pair: built-in function; call
pair: method; call
pair: built-in method; call
object: built-in method
object: built-in function
object: method
object: function
The result is up to the interpreter; see :ref:`built-in-funcs` for the
descriptions of built-in functions and methods.
a class object:
.. index::
object: class
pair: class object; call
A new instance of that class is returned.
a class instance method:
.. index::
object: class instance
object: instance
pair: class instance; call
The corresponding user-defined function is called, with an argument list that is
one longer than the argument list of the call: the instance becomes the first
argument.
a class instance:
.. index::
pair: instance; call
single: __call__() (object method)
The class must define a :meth:`__call__` method; the effect is then the same as
if that method was called.
.. _power:
The power operator
==================
The power operator binds more tightly than unary operators on its left; it binds
less tightly than unary operators on its right. The syntax is:
.. productionlist::
power: `primary` ["**" `u_expr`]
Thus, in an unparenthesized sequence of power and unary operators, the operators
are evaluated from right to left (this does not constrain the evaluation order
for the operands): ``-1**2`` results in ``-1``.
The power operator has the same semantics as the built-in :func:`pow` function,
when called with two arguments: it yields its left argument raised to the power
of its right argument. The numeric arguments are first converted to a common
type. The result type is that of the arguments after coercion.
With mixed operand types, the coercion rules for binary arithmetic operators
apply. For int and long int operands, the result has the same type as the
operands (after coercion) unless the second argument is negative; in that case,
all arguments are converted to float and a float result is delivered. For
example, ``10**2`` returns ``100``, but ``10**-2`` returns ``0.01``. (This last
feature was added in Python 2.2. In Python 2.1 and before, if both arguments
were of integer types and the second argument was negative, an exception was
raised).
Raising ``0.0`` to a negative power results in a :exc:`ZeroDivisionError`.
Raising a negative number to a fractional power results in a :exc:`ValueError`.
.. _unary:
Unary arithmetic and bitwise operations
=======================================
.. index::
triple: unary; arithmetic; operation
triple: unary; bitwise; operation
All unary arithmetic and bitwise operations have the same priority:
.. productionlist::
u_expr: `power` | "-" `u_expr` | "+" `u_expr` | "~" `u_expr`
.. index::
single: negation
single: minus
The unary ``-`` (minus) operator yields the negation of its numeric argument.
.. index:: single: plus
The unary ``+`` (plus) operator yields its numeric argument unchanged.
.. index:: single: inversion
The unary ``~`` (invert) operator yields the bitwise inversion of its plain or
long integer argument. The bitwise inversion of ``x`` is defined as
``-(x+1)``. It only applies to integral numbers.
.. index:: exception: TypeError
In all three cases, if the argument does not have the proper type, a
:exc:`TypeError` exception is raised.
.. _binary:
Binary arithmetic operations
============================
.. index:: triple: binary; arithmetic; operation
The binary arithmetic operations have the conventional priority levels. Note
that some of these operations also apply to certain non-numeric types. Apart
from the power operator, there are only two levels, one for multiplicative
operators and one for additive operators:
.. productionlist::
m_expr: `u_expr` | `m_expr` "*" `u_expr` | `m_expr` "//" `u_expr` | `m_expr` "/" `u_expr`
: | `m_expr` "%" `u_expr`
a_expr: `m_expr` | `a_expr` "+" `m_expr` | `a_expr` "-" `m_expr`
.. index:: single: multiplication
The ``*`` (multiplication) operator yields the product of its arguments. The
arguments must either both be numbers, or one argument must be an integer (plain
or long) and the other must be a sequence. In the former case, the numbers are
converted to a common type and then multiplied together. In the latter case,
sequence repetition is performed; a negative repetition factor yields an empty
sequence.
.. index::
exception: ZeroDivisionError
single: division
The ``/`` (division) and ``//`` (floor division) operators yield the quotient of
their arguments. The numeric arguments are first converted to a common type.
Plain or long integer division yields an integer of the same type; the result is
that of mathematical division with the 'floor' function applied to the result.
Division by zero raises the :exc:`ZeroDivisionError` exception.
.. index:: single: modulo
The ``%`` (modulo) operator yields the remainder from the division of the first
argument by the second. The numeric arguments are first converted to a common
type. A zero right argument raises the :exc:`ZeroDivisionError` exception. The
arguments may be floating point numbers, e.g., ``3.14%0.7`` equals ``0.34``
(since ``3.14`` equals ``4*0.7 + 0.34``.) The modulo operator always yields a
result with the same sign as its second operand (or zero); the absolute value of
the result is strictly smaller than the absolute value of the second operand
[#]_.
The integer division and modulo operators are connected by the following
identity: ``x == (x/y)*y + (x%y)``. Integer division and modulo are also
connected with the built-in function :func:`divmod`: ``divmod(x, y) == (x/y,
x%y)``. These identities don't hold for floating point numbers; there similar
identities hold approximately where ``x/y`` is replaced by ``floor(x/y)`` or
``floor(x/y) - 1`` [#]_.
In addition to performing the modulo operation on numbers, the ``%`` operator is
also overloaded by string and unicode objects to perform string formatting (also
known as interpolation). The syntax for string formatting is described in the
Python Library Reference, section :ref:`string-formatting`.
.. deprecated:: 2.3
The floor division operator, the modulo operator, and the :func:`divmod`
function are no longer defined for complex numbers. Instead, convert to a
floating point number using the :func:`abs` function if appropriate.
.. index:: single: addition
The ``+`` (addition) operator yields the sum of its arguments. The arguments
must either both be numbers or both sequences of the same type. In the former
case, the numbers are converted to a common type and then added together. In
the latter case, the sequences are concatenated.
.. index:: single: subtraction
The ``-`` (subtraction) operator yields the difference of its arguments. The
numeric arguments are first converted to a common type.
.. _shifting:
Shifting operations
===================
.. index:: pair: shifting; operation
The shifting operations have lower priority than the arithmetic operations:
.. productionlist::
shift_expr: `a_expr` | `shift_expr` ( "<<" | ">>" ) `a_expr`
These operators accept plain or long integers as arguments. The arguments are
converted to a common type. They shift the first argument to the left or right
by the number of bits given by the second argument.
.. index:: exception: ValueError
A right shift by *n* bits is defined as division by ``pow(2, n)``. A left shift
by *n* bits is defined as multiplication with ``pow(2, n)``. Negative shift
counts raise a :exc:`ValueError` exception.
.. note::
In the current implementation, the right-hand operand is required
to be at most :attr:`sys.maxsize`. If the right-hand operand is larger than
:attr:`sys.maxsize` an :exc:`OverflowError` exception is raised.
.. _bitwise:
Binary bitwise operations
=========================
.. index:: triple: binary; bitwise; operation
Each of the three bitwise operations has a different priority level:
.. productionlist::
and_expr: `shift_expr` | `and_expr` "&" `shift_expr`
xor_expr: `and_expr` | `xor_expr` "^" `and_expr`
or_expr: `xor_expr` | `or_expr` "|" `xor_expr`
.. index:: pair: bitwise; and
The ``&`` operator yields the bitwise AND of its arguments, which must be plain
or long integers. The arguments are converted to a common type.
.. index::
pair: bitwise; xor
pair: exclusive; or
The ``^`` operator yields the bitwise XOR (exclusive OR) of its arguments, which
must be plain or long integers. The arguments are converted to a common type.
.. index::
pair: bitwise; or
pair: inclusive; or
The ``|`` operator yields the bitwise (inclusive) OR of its arguments, which
must be plain or long integers. The arguments are converted to a common type.
.. _comparisons:
Comparisons
===========
.. index:: single: comparison
.. index:: pair: C; language
Unlike C, all comparison operations in Python have the same priority, which is
lower than that of any arithmetic, shifting or bitwise operation. Also unlike
C, expressions like ``a < b < c`` have the interpretation that is conventional
in mathematics:
.. productionlist::
comparison: `or_expr` ( `comp_operator` `or_expr` )*
comp_operator: "<" | ">" | "==" | ">=" | "<=" | "<>" | "!="
: | "is" ["not"] | ["not"] "in"
Comparisons yield boolean values: ``True`` or ``False``.
.. index:: pair: chaining; comparisons
Comparisons can be chained arbitrarily, e.g., ``x < y <= z`` is equivalent to
``x < y and y <= z``, except that ``y`` is evaluated only once (but in both
cases ``z`` is not evaluated at all when ``x < y`` is found to be false).
Formally, if *a*, *b*, *c*, ..., *y*, *z* are expressions and *op1*, *op2*, ...,
*opN* are comparison operators, then ``a op1 b op2 c ... y opN z`` is equivalent
to ``a op1 b and b op2 c and ... y opN z``, except that each expression is
evaluated at most once.
Note that ``a op1 b op2 c`` doesn't imply any kind of comparison between *a* and
*c*, so that, e.g., ``x < y > z`` is perfectly legal (though perhaps not
pretty).
The forms ``<>`` and ``!=`` are equivalent; for consistency with C, ``!=`` is
preferred; where ``!=`` is mentioned below ``<>`` is also accepted. The ``<>``
spelling is considered obsolescent.
Value comparisons
-----------------
The operators ``<``, ``>``, ``==``, ``>=``, ``<=``, and ``!=`` compare the
values of two objects. The objects do not need to have the same type.
Chapter :ref:`objects` states that objects have a value (in addition to type
and identity). The value of an object is a rather abstract notion in Python:
For example, there is no canonical access method for an object's value. Also,
there is no requirement that the value of an object should be constructed in a
particular way, e.g. comprised of all its data attributes. Comparison operators
implement a particular notion of what the value of an object is. One can think
of them as defining the value of an object indirectly, by means of their
comparison implementation.
Types can customize their comparison behavior by implementing
a :meth:`__cmp__` method or
:dfn:`rich comparison methods` like :meth:`__lt__`, described in
:ref:`customization`.
The default behavior for equality comparison (``==`` and ``!=``) is based on
the identity of the objects. Hence, equality comparison of instances with the
same identity results in equality, and equality comparison of instances with
different identities results in inequality. A motivation for this default
behavior is the desire that all objects should be reflexive (i.e. ``x is y``
implies ``x == y``).
The default order comparison (``<``, ``>``, ``<=``, and ``>=``) gives a
consistent but arbitrary order.
(This unusual definition of comparison was used to simplify the definition of
operations like sorting and the :keyword:`in` and :keyword:`not in` operators.
In the future, the comparison rules for objects of different types are likely to
change.)
The behavior of the default equality comparison, that instances with different
identities are always unequal, may be in contrast to what types will need that
have a sensible definition of object value and value-based equality. Such
types will need to customize their comparison behavior, and in fact, a number
of built-in types have done that.
The following list describes the comparison behavior of the most important
built-in types.
* Numbers of built-in numeric types (:ref:`typesnumeric`) and of the standard
library types :class:`fractions.Fraction` and :class:`decimal.Decimal` can be
compared within and across their types, with the restriction that complex
numbers do not support order comparison. Within the limits of the types
involved, they compare mathematically (algorithmically) correct without loss
of precision.
* Strings (instances of :class:`str` or :class:`unicode`)
compare lexicographically using the numeric equivalents (the
result of the built-in function :func:`ord`) of their characters. [#]_
When comparing an 8-bit string and a Unicode string, the 8-bit string
is converted to Unicode. If the conversion fails, the strings
are considered unequal.
* Instances of :class:`tuple` or :class:`list` can be compared only
within each of their types. Equality comparison across these types
results in unequality, and ordering comparison across these types
gives an arbitrary order.
These sequences compare lexicographically using comparison of corresponding
elements, whereby reflexivity of the elements is enforced.
In enforcing reflexivity of elements, the comparison of collections assumes
that for a collection element ``x``, ``x == x`` is always true. Based on
that assumption, element identity is compared first, and element comparison
is performed only for distinct elements. This approach yields the same
result as a strict element comparison would, if the compared elements are
reflexive. For non-reflexive elements, the result is different than for
strict element comparison.
Lexicographical comparison between built-in collections works as follows:
- For two collections to compare equal, they must be of the same type, have
the same length, and each pair of corresponding elements must compare
equal (for example, ``[1,2] == (1,2)`` is false because the type is not the
same).
- Collections are ordered the same as their
first unequal elements (for example, ``cmp([1,2,x], [1,2,y])`` returns the
same as ``cmp(x,y)``). If a corresponding element does not exist, the
shorter collection is ordered first (for example, ``[1,2] < [1,2,3]`` is
true).
* Mappings (instances of :class:`dict`) compare equal if and only if they have
equal `(key, value)` pairs. Equality comparison of the keys and values
enforces reflexivity.
Outcomes other than equality are resolved
consistently, but are not otherwise defined. [#]_
* Most other objects of built-in types compare unequal unless they are the same
object; the choice whether one object is considered smaller or larger than
another one is made arbitrarily but consistently within one execution of a
program.
User-defined classes that customize their comparison behavior should follow
some consistency rules, if possible:
* Equality comparison should be reflexive.
In other words, identical objects should compare equal:
``x is y`` implies ``x == y``
* Comparison should be symmetric.
In other words, the following expressions should have the same result:
``x == y`` and ``y == x``
``x != y`` and ``y != x``
``x < y`` and ``y > x``
``x <= y`` and ``y >= x``
* Comparison should be transitive.
The following (non-exhaustive) examples illustrate that:
``x > y and y > z`` implies ``x > z``
``x < y and y <= z`` implies ``x < z``
* Inverse comparison should result in the boolean negation.
In other words, the following expressions should have the same result:
``x == y`` and ``not x != y``
``x < y`` and ``not x >= y`` (for total ordering)
``x > y`` and ``not x <= y`` (for total ordering)
The last two expressions apply to totally ordered collections (e.g. to
sequences, but not to sets or mappings). See also the
:func:`~functools.total_ordering` decorator.
* The :func:`hash` result should be consistent with equality.
Objects that are equal should either have the same hash value,
or be marked as unhashable.
Python does not enforce these consistency rules.
.. _in:
.. _not in:
.. _membership-test-details:
Membership test operations
--------------------------
The operators :keyword:`in` and :keyword:`not in` test for membership. ``x in
s`` evaluates to ``True`` if *x* is a member of *s*, and ``False`` otherwise.
``x not in s`` returns the negation of ``x in s``. All built-in sequences and
set types support this as well as dictionary, for which :keyword:`in` tests
whether the dictionary has a given key. For container types such as list, tuple,
set, frozenset, dict, or collections.deque, the expression ``x in y`` is equivalent
to ``any(x is e or x == e for e in y)``.
For the string and bytes types, ``x in y`` is ``True`` if and only if *x* is a
substring of *y*. An equivalent test is ``y.find(x) != -1``. Empty strings are
always considered to be a substring of any other string, so ``"" in "abc"`` will
return ``True``.
For user-defined classes which define the :meth:`__contains__` method, ``x in
y`` returns ``True`` if ``y.__contains__(x)`` returns a true value, and
``False`` otherwise.
For user-defined classes which do not define :meth:`__contains__` but do define
:meth:`__iter__`, ``x in y`` is ``True`` if some value ``z`` with ``x == z`` is
produced while iterating over ``y``. If an exception is raised during the
iteration, it is as if :keyword:`in` raised that exception.
Lastly, the old-style iteration protocol is tried: if a class defines
:meth:`__getitem__`, ``x in y`` is ``True`` if and only if there is a non-negative
integer index *i* such that ``x == y[i]``, and all lower integer indices do not
raise :exc:`IndexError` exception. (If any other exception is raised, it is as
if :keyword:`in` raised that exception).
.. index::
operator: in
operator: not in
pair: membership; test
object: sequence
The operator :keyword:`not in` is defined to have the inverse true value of
:keyword:`in`.
.. index::
operator: is
operator: is not
pair: identity; test
.. _is:
.. _is not:
Identity comparisons
--------------------
The operators :keyword:`is` and :keyword:`is not` test for object identity: ``x
is y`` is true if and only if *x* and *y* are the same object. ``x is not y``
yields the inverse truth value. [#]_
.. _booleans:
.. _and:
.. _or:
.. _not:
Boolean operations
==================
.. index::
pair: Conditional; expression
pair: Boolean; operation
.. productionlist::
or_test: `and_test` | `or_test` "or" `and_test`
and_test: `not_test` | `and_test` "and" `not_test`
not_test: `comparison` | "not" `not_test`
In the context of Boolean operations, and also when expressions are used by
control flow statements, the following values are interpreted as false:
``False``, ``None``, numeric zero of all types, and empty strings and containers
(including strings, tuples, lists, dictionaries, sets and frozensets). All
other values are interpreted as true. (See the :meth:`~object.__nonzero__`
special method for a way to change this.)
.. index:: operator: not
The operator :keyword:`not` yields ``True`` if its argument is false, ``False``
otherwise.
.. index:: operator: and
The expression ``x and y`` first evaluates *x*; if *x* is false, its value is
returned; otherwise, *y* is evaluated and the resulting value is returned.
.. index:: operator: or
The expression ``x or y`` first evaluates *x*; if *x* is true, its value is
returned; otherwise, *y* is evaluated and the resulting value is returned.
(Note that neither :keyword:`and` nor :keyword:`or` restrict the value and type
they return to ``False`` and ``True``, but rather return the last evaluated
argument. This is sometimes useful, e.g., if ``s`` is a string that should be
replaced by a default value if it is empty, the expression ``s or 'foo'`` yields
the desired value. Because :keyword:`not` has to invent a value anyway, it does
not bother to return a value of the same type as its argument, so e.g., ``not
'foo'`` yields ``False``, not ``''``.)
Conditional Expressions
=======================
.. versionadded:: 2.5
.. index::
pair: conditional; expression
pair: ternary; operator
.. productionlist::
conditional_expression: `or_test` ["if" `or_test` "else" `expression`]
expression: `conditional_expression` | `lambda_expr`
Conditional expressions (sometimes called a "ternary operator") have the lowest
priority of all Python operations.
The expression ``x if C else y`` first evaluates the condition, *C* (*not* *x*);
if *C* is true, *x* is evaluated and its value is returned; otherwise, *y* is
evaluated and its value is returned.
See :pep:`308` for more details about conditional expressions.
.. _lambdas:
.. _lambda:
Lambdas
=======
.. index::
pair: lambda; expression
pair: anonymous; function
.. productionlist::
lambda_expr: "lambda" [`parameter_list`]: `expression`
old_lambda_expr: "lambda" [`parameter_list`]: `old_expression`
Lambda expressions (sometimes called lambda forms) have the same syntactic position as
expressions. They are a shorthand to create anonymous functions; the expression
``lambda parameters: expression`` yields a function object. The unnamed object
behaves like a function object defined with ::
def <lambda>(parameters):
return expression
See section :ref:`function` for the syntax of parameter lists. Note that
functions created with lambda expressions cannot contain statements.
.. _exprlists:
Expression lists
================
.. index:: pair: expression; list
.. productionlist::
expression_list: `expression` ( "," `expression` )* [","]
.. index:: object: tuple
An expression list containing at least one comma yields a tuple. The length of
the tuple is the number of expressions in the list. The expressions are
evaluated from left to right.
.. index:: pair: trailing; comma
The trailing comma is required only to create a single tuple (a.k.a. a
*singleton*); it is optional in all other cases. A single expression without a
trailing comma doesn't create a tuple, but rather yields the value of that
expression. (To create an empty tuple, use an empty pair of parentheses:
``()``.)
.. _evalorder:
Evaluation order
================
.. index:: pair: evaluation; order
Python evaluates expressions from left to right. Notice that while evaluating an
assignment, the right-hand side is evaluated before the left-hand side.
In the following lines, expressions will be evaluated in the arithmetic order of
their suffixes::
expr1, expr2, expr3, expr4
(expr1, expr2, expr3, expr4)
{expr1: expr2, expr3: expr4}
expr1 + expr2 * (expr3 - expr4)
expr1(expr2, expr3, *expr4, **expr5)
expr3, expr4 = expr1, expr2
.. _operator-summary:
Operator precedence
===================
.. index:: pair: operator; precedence
The following table summarizes the operator precedences in Python, from lowest
precedence (least binding) to highest precedence (most binding). Operators in
the same box have the same precedence. Unless the syntax is explicitly given,
operators are binary. Operators in the same box group left to right (except for
comparisons, including tests, which all have the same precedence and chain from
left to right --- see section :ref:`comparisons` --- and exponentiation, which
groups from right to left).
+-----------------------------------------------+-------------------------------------+
| Operator | Description |
+===============================================+=====================================+
| :keyword:`lambda` | Lambda expression |
+-----------------------------------------------+-------------------------------------+
| :keyword:`if` -- :keyword:`else` | Conditional expression |
+-----------------------------------------------+-------------------------------------+
| :keyword:`or` | Boolean OR |
+-----------------------------------------------+-------------------------------------+
| :keyword:`and` | Boolean AND |
+-----------------------------------------------+-------------------------------------+
| :keyword:`not` ``x`` | Boolean NOT |
+-----------------------------------------------+-------------------------------------+
| :keyword:`in`, :keyword:`not in`, | Comparisons, including membership |
| :keyword:`is`, :keyword:`is not`, ``<``, | tests and identity tests |
| ``<=``, ``>``, ``>=``, ``<>``, ``!=``, ``==`` | |
+-----------------------------------------------+-------------------------------------+
| ``|`` | Bitwise OR |
+-----------------------------------------------+-------------------------------------+
| ``^`` | Bitwise XOR |
+-----------------------------------------------+-------------------------------------+
| ``&`` | Bitwise AND |
+-----------------------------------------------+-------------------------------------+
| ``<<``, ``>>`` | Shifts |
+-----------------------------------------------+-------------------------------------+
| ``+``, ``-`` | Addition and subtraction |
+-----------------------------------------------+-------------------------------------+
| ``*``, ``/``, ``//``, ``%`` | Multiplication, division, remainder |
| | [#]_ |
+-----------------------------------------------+-------------------------------------+
| ``+x``, ``-x``, ``~x`` | Positive, negative, bitwise NOT |
+-----------------------------------------------+-------------------------------------+
| ``**`` | Exponentiation [#]_ |
+-----------------------------------------------+-------------------------------------+
| ``x[index]``, ``x[index:index]``, | Subscription, slicing, |
| ``x(arguments...)``, ``x.attribute`` | call, attribute reference |
+-----------------------------------------------+-------------------------------------+
| ``(expressions...)``, | Binding or tuple display, |
| ``[expressions...]``, | list display, |
| ``{key: value...}``, | dictionary display, |
| ```expressions...``` | string conversion |
+-----------------------------------------------+-------------------------------------+
.. rubric:: Footnotes
.. [#] In Python 2.3 and later releases, a list comprehension "leaks" the control
variables of each ``for`` it contains into the containing scope. However, this
behavior is deprecated, and relying on it will not work in Python 3.
.. [#] While ``abs(x%y) < abs(y)`` is true mathematically, for floats it may not be
true numerically due to roundoff. For example, and assuming a platform on which
a Python float is an IEEE 754 double-precision number, in order that ``-1e-100 %
1e100`` have the same sign as ``1e100``, the computed result is ``-1e-100 +
1e100``, which is numerically exactly equal to ``1e100``. The function
:func:`math.fmod` returns a result whose sign matches the sign of the
first argument instead, and so returns ``-1e-100`` in this case. Which approach
is more appropriate depends on the application.
.. [#] If x is very close to an exact integer multiple of y, it's possible for
``floor(x/y)`` to be one larger than ``(x-x%y)/y`` due to rounding. In such
cases, Python returns the latter result, in order to preserve that
``divmod(x,y)[0] * y + x % y`` be very close to ``x``.
.. [#] The Unicode standard distinguishes between :dfn:`code points`
(e.g. U+0041) and :dfn:`abstract characters` (e.g. "LATIN CAPITAL LETTER A").
While most abstract characters in Unicode are only represented using one
code point, there is a number of abstract characters that can in addition be
represented using a sequence of more than one code point. For example, the
abstract character "LATIN CAPITAL LETTER C WITH CEDILLA" can be represented
as a single :dfn:`precomposed character` at code position U+00C7, or as a
sequence of a :dfn:`base character` at code position U+0043 (LATIN CAPITAL
LETTER C), followed by a :dfn:`combining character` at code position U+0327
(COMBINING CEDILLA).
The comparison operators on unicode strings compare at the level of Unicode code
points. This may be counter-intuitive to humans. For example,
``u"\u00C7" == u"\u0043\u0327"`` is ``False``, even though both strings
represent the same abstract character "LATIN CAPITAL LETTER C WITH CEDILLA".
To compare strings at the level of abstract characters (that is, in a way
intuitive to humans), use :func:`unicodedata.normalize`.
.. [#] Earlier versions of Python used lexicographic comparison of the sorted (key,
value) lists, but this was very expensive for the common case of comparing for
equality. An even earlier version of Python compared dictionaries by identity
only, but this caused surprises because people expected to be able to test a
dictionary for emptiness by comparing it to ``{}``.
.. [#] Due to automatic garbage-collection, free lists, and the dynamic nature of
descriptors, you may notice seemingly unusual behaviour in certain uses of
the :keyword:`is` operator, like those involving comparisons between instance
methods, or constants. Check their documentation for more info.
.. [#] The ``%`` operator is also used for string formatting; the same
precedence applies.
.. [#] The power operator ``**`` binds less tightly than an arithmetic or
bitwise unary operator on its right, that is, ``2**-1`` is ``0.5``.
PK
%�\6�� � � ' html/_sources/reference/grammar.rst.txtnu �[��� Full Grammar specification
==========================
This is the full Python grammar, as it is read by the parser generator and used
to parse Python source files:
.. literalinclude:: ../../Grammar/Grammar
PK
%�\]lh_� � % html/_sources/reference/index.rst.txtnu �[��� .. _reference-index:
#################################
The Python Language Reference
#################################
This reference manual describes the syntax and "core semantics" of the
language. It is terse, but attempts to be exact and complete. The semantics of
non-essential built-in object types and of the built-in functions and modules
are described in :ref:`library-index`. For an informal introduction to the
language, see :ref:`tutorial-index`. For C or C++ programmers, two additional
manuals exist: :ref:`extending-index` describes the high-level picture of how to
write a Python extension module, and the :ref:`c-api-index` describes the
interfaces available to C/C++ programmers in detail.
.. toctree::
:maxdepth: 2
:numbered:
introduction.rst
lexical_analysis.rst
datamodel.rst
executionmodel.rst
expressions.rst
simple_stmts.rst
compound_stmts.rst
toplevel_components.rst
grammar.rst
PK
%�\�)�1� � , html/_sources/reference/introduction.rst.txtnu �[���
.. _introduction:
************
Introduction
************
This reference manual describes the Python programming language. It is not
intended as a tutorial.
While I am trying to be as precise as possible, I chose to use English rather
than formal specifications for everything except syntax and lexical analysis.
This should make the document more understandable to the average reader, but
will leave room for ambiguities. Consequently, if you were coming from Mars and
tried to re-implement Python from this document alone, you might have to guess
things and in fact you would probably end up implementing quite a different
language. On the other hand, if you are using Python and wonder what the precise
rules about a particular area of the language are, you should definitely be able
to find them here. If you would like to see a more formal definition of the
language, maybe you could volunteer your time --- or invent a cloning machine
:-).
It is dangerous to add too many implementation details to a language reference
document --- the implementation may change, and other implementations of the
same language may work differently. On the other hand, there is currently only
one Python implementation in widespread use (although alternate implementations
exist), and its particular quirks are sometimes worth being mentioned,
especially where the implementation imposes additional limitations. Therefore,
you'll find short "implementation notes" sprinkled throughout the text.
Every Python implementation comes with a number of built-in and standard
modules. These are documented in :ref:`library-index`. A few built-in modules
are mentioned when they interact in a significant way with the language
definition.
.. _implementations:
Alternate Implementations
=========================
Though there is one Python implementation which is by far the most popular,
there are some alternate implementations which are of particular interest to
different audiences.
Known implementations include:
CPython
This is the original and most-maintained implementation of Python, written in C.
New language features generally appear here first.
Jython
Python implemented in Java. This implementation can be used as a scripting
language for Java applications, or can be used to create applications using the
Java class libraries. It is also often used to create tests for Java libraries.
More information can be found at `the Jython website <http://www.jython.org/>`_.
Python for .NET
This implementation actually uses the CPython implementation, but is a managed
.NET application and makes .NET libraries available. It was created by Brian
Lloyd. For more information, see the `Python for .NET home page
<https://pythonnet.github.io/>`_.
IronPython
An alternate Python for .NET. Unlike Python.NET, this is a complete Python
implementation that generates IL, and compiles Python code directly to .NET
assemblies. It was created by Jim Hugunin, the original creator of Jython. For
more information, see `the IronPython website <http://ironpython.net/>`_.
PyPy
An implementation of Python written completely in Python. It supports several
advanced features not found in other implementations like stackless support
and a Just in Time compiler. One of the goals of the project is to encourage
experimentation with the language itself by making it easier to modify the
interpreter (since it is written in Python). Additional information is
available on `the PyPy project's home page <http://pypy.org/>`_.
Each of these implementations varies in some way from the language as documented
in this manual, or introduces specific information beyond what's covered in the
standard Python documentation. Please refer to the implementation-specific
documentation to determine what else you need to know about the specific
implementation you're using.
.. _notation:
Notation
========
.. index::
single: BNF
single: grammar
single: syntax
single: notation
The descriptions of lexical analysis and syntax use a modified BNF grammar
notation. This uses the following style of definition:
.. productionlist:: *
name: `lc_letter` (`lc_letter` | "_")*
lc_letter: "a"..."z"
The first line says that a ``name`` is an ``lc_letter`` followed by a sequence
of zero or more ``lc_letter``\ s and underscores. An ``lc_letter`` in turn is
any of the single characters ``'a'`` through ``'z'``. (This rule is actually
adhered to for the names defined in lexical and grammar rules in this document.)
Each rule begins with a name (which is the name defined by the rule) and
``::=``. A vertical bar (``|``) is used to separate alternatives; it is the
least binding operator in this notation. A star (``*``) means zero or more
repetitions of the preceding item; likewise, a plus (``+``) means one or more
repetitions, and a phrase enclosed in square brackets (``[ ]``) means zero or
one occurrences (in other words, the enclosed phrase is optional). The ``*``
and ``+`` operators bind as tightly as possible; parentheses are used for
grouping. Literal strings are enclosed in quotes. White space is only
meaningful to separate tokens. Rules are normally contained on a single line;
rules with many alternatives may be formatted alternatively with each line after
the first beginning with a vertical bar.
.. index::
single: lexical definitions
single: ASCII@ASCII
In lexical definitions (as the example above), two more conventions are used:
Two literal characters separated by three dots mean a choice of any single
character in the given (inclusive) range of ASCII characters. A phrase between
angular brackets (``<...>``) gives an informal description of the symbol
defined; e.g., this could be used to describe the notion of 'control character'
if needed.
Even though the notation used is almost the same, there is a big difference
between the meaning of lexical and syntactic definitions: a lexical definition
operates on the individual characters of the input source, while a syntax
definition operates on the stream of tokens generated by the lexical analysis.
All uses of BNF in the next chapter ("Lexical Analysis") are lexical
definitions; uses in subsequent chapters are syntactic definitions.
PK
%�\�F~`�q �q 0 html/_sources/reference/lexical_analysis.rst.txtnu �[���
.. _lexical:
****************
Lexical analysis
****************
.. index::
single: lexical analysis
single: parser
single: token
A Python program is read by a *parser*. Input to the parser is a stream of
*tokens*, generated by the *lexical analyzer*. This chapter describes how the
lexical analyzer breaks a file into tokens.
Python uses the 7-bit ASCII character set for program text.
.. versionadded:: 2.3
An encoding declaration can be used to indicate that string literals and
comments use an encoding different from ASCII.
For compatibility with older versions, Python only warns if it finds 8-bit
characters; those warnings should be corrected by either declaring an explicit
encoding, or using escape sequences if those bytes are binary data, instead of
characters.
The run-time character set depends on the I/O devices connected to the program
but is generally a superset of ASCII.
**Future compatibility note:** It may be tempting to assume that the character
set for 8-bit characters is ISO Latin-1 (an ASCII superset that covers most
western languages that use the Latin alphabet), but it is possible that in the
future Unicode text editors will become common. These generally use the UTF-8
encoding, which is also an ASCII superset, but with very different use for the
characters with ordinals 128-255. While there is no consensus on this subject
yet, it is unwise to assume either Latin-1 or UTF-8, even though the current
implementation appears to favor Latin-1. This applies both to the source
character set and the run-time character set.
.. _line-structure:
Line structure
==============
.. index:: single: line structure
A Python program is divided into a number of *logical lines*.
.. _logical:
Logical lines
-------------
.. index::
single: logical line
single: physical line
single: line joining
single: NEWLINE token
The end of a logical line is represented by the token NEWLINE. Statements
cannot cross logical line boundaries except where NEWLINE is allowed by the
syntax (e.g., between statements in compound statements). A logical line is
constructed from one or more *physical lines* by following the explicit or
implicit *line joining* rules.
.. _physical:
Physical lines
--------------
A physical line is a sequence of characters terminated by an end-of-line
sequence. In source files and strings, any of the standard platform line
termination sequences can be used - the Unix form using ASCII LF (linefeed),
the Windows form using the ASCII sequence CR LF (return followed by linefeed),
or the old Macintosh form using the ASCII CR (return) character. All of these
forms can be used equally, regardless of platform. The end of input also serves
as an implicit terminator for the final physical line.
When embedding Python, source code strings should be passed to Python APIs using
the standard C conventions for newline characters (the ``\n`` character,
representing ASCII LF, is the line terminator).
.. _comments:
Comments
--------
.. index::
single: comment
single: hash character
A comment starts with a hash character (``#``) that is not part of a string
literal, and ends at the end of the physical line. A comment signifies the end
of the logical line unless the implicit line joining rules are invoked. Comments
are ignored by the syntax; they are not tokens.
.. _encodings:
Encoding declarations
---------------------
.. index:: source character set, encoding declarations (source file)
If a comment in the first or second line of the Python script matches the
regular expression ``coding[=:]\s*([-\w.]+)``, this comment is processed as an
encoding declaration; the first group of this expression names the encoding of
the source code file. The encoding declaration must appear on a line of its
own. If it is the second line, the first line must also be a comment-only line.
The recommended forms of an encoding expression are ::
# -*- coding: <encoding-name> -*-
which is recognized also by GNU Emacs, and ::
# vim:fileencoding=<encoding-name>
which is recognized by Bram Moolenaar's VIM. In addition, if the first bytes of
the file are the UTF-8 byte-order mark (``'\xef\xbb\xbf'``), the declared file
encoding is UTF-8 (this is supported, among others, by Microsoft's
:program:`notepad`).
If an encoding is declared, the encoding name must be recognized by Python. The
encoding is used for all lexical analysis, in particular to find the end of a
string, and to interpret the contents of Unicode literals. String literals are
converted to Unicode for syntactical analysis, then converted back to their
original encoding before interpretation starts.
.. XXX there should be a list of supported encodings.
.. _explicit-joining:
Explicit line joining
---------------------
.. index::
single: physical line
single: line joining
single: line continuation
single: backslash character
Two or more physical lines may be joined into logical lines using backslash
characters (``\``), as follows: when a physical line ends in a backslash that is
not part of a string literal or comment, it is joined with the following forming
a single logical line, deleting the backslash and the following end-of-line
character. For example::
if 1900 < year < 2100 and 1 <= month <= 12 \
and 1 <= day <= 31 and 0 <= hour < 24 \
and 0 <= minute < 60 and 0 <= second < 60: # Looks like a valid date
return 1
A line ending in a backslash cannot carry a comment. A backslash does not
continue a comment. A backslash does not continue a token except for string
literals (i.e., tokens other than string literals cannot be split across
physical lines using a backslash). A backslash is illegal elsewhere on a line
outside a string literal.
.. _implicit-joining:
Implicit line joining
---------------------
Expressions in parentheses, square brackets or curly braces can be split over
more than one physical line without using backslashes. For example::
month_names = ['Januari', 'Februari', 'Maart', # These are the
'April', 'Mei', 'Juni', # Dutch names
'Juli', 'Augustus', 'September', # for the months
'Oktober', 'November', 'December'] # of the year
Implicitly continued lines can carry comments. The indentation of the
continuation lines is not important. Blank continuation lines are allowed.
There is no NEWLINE token between implicit continuation lines. Implicitly
continued lines can also occur within triple-quoted strings (see below); in that
case they cannot carry comments.
.. _blank-lines:
Blank lines
-----------
.. index:: single: blank line
A logical line that contains only spaces, tabs, formfeeds and possibly a
comment, is ignored (i.e., no NEWLINE token is generated). During interactive
input of statements, handling of a blank line may differ depending on the
implementation of the read-eval-print loop. In the standard implementation, an
entirely blank logical line (i.e. one containing not even whitespace or a
comment) terminates a multi-line statement.
.. _indentation:
Indentation
-----------
.. index::
single: indentation
single: whitespace
single: leading whitespace
single: space
single: tab
single: grouping
single: statement grouping
Leading whitespace (spaces and tabs) at the beginning of a logical line is used
to compute the indentation level of the line, which in turn is used to determine
the grouping of statements.
First, tabs are replaced (from left to right) by one to eight spaces such that
the total number of characters up to and including the replacement is a multiple
of eight (this is intended to be the same rule as used by Unix). The total
number of spaces preceding the first non-blank character then determines the
line's indentation. Indentation cannot be split over multiple physical lines
using backslashes; the whitespace up to the first backslash determines the
indentation.
**Cross-platform compatibility note:** because of the nature of text editors on
non-UNIX platforms, it is unwise to use a mixture of spaces and tabs for the
indentation in a single source file. It should also be noted that different
platforms may explicitly limit the maximum indentation level.
A formfeed character may be present at the start of the line; it will be ignored
for the indentation calculations above. Formfeed characters occurring elsewhere
in the leading whitespace have an undefined effect (for instance, they may reset
the space count to zero).
.. index::
single: INDENT token
single: DEDENT token
The indentation levels of consecutive lines are used to generate INDENT and
DEDENT tokens, using a stack, as follows.
Before the first line of the file is read, a single zero is pushed on the stack;
this will never be popped off again. The numbers pushed on the stack will
always be strictly increasing from bottom to top. At the beginning of each
logical line, the line's indentation level is compared to the top of the stack.
If it is equal, nothing happens. If it is larger, it is pushed on the stack, and
one INDENT token is generated. If it is smaller, it *must* be one of the
numbers occurring on the stack; all numbers on the stack that are larger are
popped off, and for each number popped off a DEDENT token is generated. At the
end of the file, a DEDENT token is generated for each number remaining on the
stack that is larger than zero.
Here is an example of a correctly (though confusingly) indented piece of Python
code::
def perm(l):
# Compute the list of all permutations of l
if len(l) <= 1:
return [l]
r = []
for i in range(len(l)):
s = l[:i] + l[i+1:]
p = perm(s)
for x in p:
r.append(l[i:i+1] + x)
return r
The following example shows various indentation errors::
def perm(l): # error: first line indented
for i in range(len(l)): # error: not indented
s = l[:i] + l[i+1:]
p = perm(l[:i] + l[i+1:]) # error: unexpected indent
for x in p:
r.append(l[i:i+1] + x)
return r # error: inconsistent dedent
(Actually, the first three errors are detected by the parser; only the last
error is found by the lexical analyzer --- the indentation of ``return r`` does
not match a level popped off the stack.)
.. _whitespace:
Whitespace between tokens
-------------------------
Except at the beginning of a logical line or in string literals, the whitespace
characters space, tab and formfeed can be used interchangeably to separate
tokens. Whitespace is needed between two tokens only if their concatenation
could otherwise be interpreted as a different token (e.g., ab is one token, but
a b is two tokens).
.. _other-tokens:
Other tokens
============
Besides NEWLINE, INDENT and DEDENT, the following categories of tokens exist:
*identifiers*, *keywords*, *literals*, *operators*, and *delimiters*. Whitespace
characters (other than line terminators, discussed earlier) are not tokens, but
serve to delimit tokens. Where ambiguity exists, a token comprises the longest
possible string that forms a legal token, when read from left to right.
.. _identifiers:
Identifiers and keywords
========================
.. index::
single: identifier
single: name
Identifiers (also referred to as *names*) are described by the following lexical
definitions:
.. productionlist::
identifier: (`letter`|"_") (`letter` | `digit` | "_")*
letter: `lowercase` | `uppercase`
lowercase: "a"..."z"
uppercase: "A"..."Z"
digit: "0"..."9"
Identifiers are unlimited in length. Case is significant.
.. _keywords:
Keywords
--------
.. index::
single: keyword
single: reserved word
The following identifiers are used as reserved words, or *keywords* of the
language, and cannot be used as ordinary identifiers. They must be spelled
exactly as written here:
.. sourcecode:: text
and del from not while
as elif global or with
assert else if pass yield
break except import print
class exec in raise
continue finally is return
def for lambda try
.. versionchanged:: 2.4
:const:`None` became a constant and is now recognized by the compiler as a name
for the built-in object :const:`None`. Although it is not a keyword, you cannot
assign a different object to it.
.. versionchanged:: 2.5
Using :keyword:`as` and :keyword:`with` as identifiers triggers a warning. To
use them as keywords, enable the ``with_statement`` future feature .
.. versionchanged:: 2.6
:keyword:`as` and :keyword:`with` are full keywords.
.. _id-classes:
Reserved classes of identifiers
-------------------------------
Certain classes of identifiers (besides keywords) have special meanings. These
classes are identified by the patterns of leading and trailing underscore
characters:
``_*``
Not imported by ``from module import *``. The special identifier ``_`` is used
in the interactive interpreter to store the result of the last evaluation; it is
stored in the :mod:`__builtin__` module. When not in interactive mode, ``_``
has no special meaning and is not defined. See section :ref:`import`.
.. note::
The name ``_`` is often used in conjunction with internationalization;
refer to the documentation for the :mod:`gettext` module for more
information on this convention.
``__*__``
System-defined names. These names are defined by the interpreter and its
implementation (including the standard library). Current system names are
discussed in the :ref:`specialnames` section and elsewhere. More will likely
be defined in future versions of Python. *Any* use of ``__*__`` names, in
any context, that does not follow explicitly documented use, is subject to
breakage without warning.
``__*``
Class-private names. Names in this category, when used within the context of a
class definition, are re-written to use a mangled form to help avoid name
clashes between "private" attributes of base and derived classes. See section
:ref:`atom-identifiers`.
.. _literals:
Literals
========
.. index::
single: literal
single: constant
Literals are notations for constant values of some built-in types.
.. _strings:
String literals
---------------
.. index:: single: string literal
String literals are described by the following lexical definitions:
.. index:: single: ASCII@ASCII
.. productionlist::
stringliteral: [`stringprefix`](`shortstring` | `longstring`)
stringprefix: "r" | "u" | "ur" | "R" | "U" | "UR" | "Ur" | "uR"
: | "b" | "B" | "br" | "Br" | "bR" | "BR"
shortstring: "'" `shortstringitem`* "'" | '"' `shortstringitem`* '"'
longstring: "'''" `longstringitem`* "'''"
: | '"""' `longstringitem`* '"""'
shortstringitem: `shortstringchar` | `escapeseq`
longstringitem: `longstringchar` | `escapeseq`
shortstringchar: <any source character except "\" or newline or the quote>
longstringchar: <any source character except "\">
escapeseq: "\" <any ASCII character>
One syntactic restriction not indicated by these productions is that whitespace
is not allowed between the :token:`stringprefix` and the rest of the string
literal. The source character set is defined by the encoding declaration; it is
ASCII if no encoding declaration is given in the source file; see section
:ref:`encodings`.
.. index::
single: triple-quoted string
single: Unicode Consortium
single: string; Unicode
single: raw string
In plain English: String literals can be enclosed in matching single quotes
(``'``) or double quotes (``"``). They can also be enclosed in matching groups
of three single or double quotes (these are generally referred to as
*triple-quoted strings*). The backslash (``\``) character is used to escape
characters that otherwise have a special meaning, such as newline, backslash
itself, or the quote character. String literals may optionally be prefixed with
a letter ``'r'`` or ``'R'``; such strings are called :dfn:`raw strings` and use
different rules for interpreting backslash escape sequences. A prefix of
``'u'`` or ``'U'`` makes the string a Unicode string. Unicode strings use the
Unicode character set as defined by the Unicode Consortium and ISO 10646. Some
additional escape sequences, described below, are available in Unicode strings.
A prefix of ``'b'`` or ``'B'`` is ignored in Python 2; it indicates that the
literal should become a bytes literal in Python 3 (e.g. when code is
automatically converted with 2to3). A ``'u'`` or ``'b'`` prefix may be followed
by an ``'r'`` prefix.
In triple-quoted strings, unescaped newlines and quotes are allowed (and are
retained), except that three unescaped quotes in a row terminate the string. (A
"quote" is the character used to open the string, i.e. either ``'`` or ``"``.)
.. index::
single: physical line
single: escape sequence
single: Standard C
single: C
Unless an ``'r'`` or ``'R'`` prefix is present, escape sequences in strings are
interpreted according to rules similar to those used by Standard C. The
recognized escape sequences are:
+-----------------+---------------------------------+-------+
| Escape Sequence | Meaning | Notes |
+=================+=================================+=======+
| ``\newline`` | Ignored | |
+-----------------+---------------------------------+-------+
| ``\\`` | Backslash (``\``) | |
+-----------------+---------------------------------+-------+
| ``\'`` | Single quote (``'``) | |
+-----------------+---------------------------------+-------+
| ``\"`` | Double quote (``"``) | |
+-----------------+---------------------------------+-------+
| ``\a`` | ASCII Bell (BEL) | |
+-----------------+---------------------------------+-------+
| ``\b`` | ASCII Backspace (BS) | |
+-----------------+---------------------------------+-------+
| ``\f`` | ASCII Formfeed (FF) | |
+-----------------+---------------------------------+-------+
| ``\n`` | ASCII Linefeed (LF) | |
+-----------------+---------------------------------+-------+
| ``\N{name}`` | Character named *name* in the | |
| | Unicode database (Unicode only) | |
+-----------------+---------------------------------+-------+
| ``\r`` | ASCII Carriage Return (CR) | |
+-----------------+---------------------------------+-------+
| ``\t`` | ASCII Horizontal Tab (TAB) | |
+-----------------+---------------------------------+-------+
| ``\uxxxx`` | Character with 16-bit hex value | \(1) |
| | *xxxx* (Unicode only) | |
+-----------------+---------------------------------+-------+
| ``\Uxxxxxxxx`` | Character with 32-bit hex value | \(2) |
| | *xxxxxxxx* (Unicode only) | |
+-----------------+---------------------------------+-------+
| ``\v`` | ASCII Vertical Tab (VT) | |
+-----------------+---------------------------------+-------+
| ``\ooo`` | Character with octal value | (3,5) |
| | *ooo* | |
+-----------------+---------------------------------+-------+
| ``\xhh`` | Character with hex value *hh* | (4,5) |
+-----------------+---------------------------------+-------+
.. index:: single: ASCII@ASCII
Notes:
(1)
Individual code units which form parts of a surrogate pair can be encoded using
this escape sequence.
(2)
Any Unicode character can be encoded this way, but characters outside the Basic
Multilingual Plane (BMP) will be encoded using a surrogate pair if Python is
compiled to use 16-bit code units (the default).
(3)
As in Standard C, up to three octal digits are accepted.
(4)
Unlike in Standard C, exactly two hex digits are required.
(5)
In a string literal, hexadecimal and octal escapes denote the byte with the
given value; it is not necessary that the byte encodes a character in the source
character set. In a Unicode literal, these escapes denote a Unicode character
with the given value.
.. index:: single: unrecognized escape sequence
Unlike Standard C, all unrecognized escape sequences are left in the string
unchanged, i.e., *the backslash is left in the string*. (This behavior is
useful when debugging: if an escape sequence is mistyped, the resulting output
is more easily recognized as broken.) It is also important to note that the
escape sequences marked as "(Unicode only)" in the table above fall into the
category of unrecognized escapes for non-Unicode string literals.
When an ``'r'`` or ``'R'`` prefix is present, a character following a backslash
is included in the string without change, and *all backslashes are left in the
string*. For example, the string literal ``r"\n"`` consists of two characters:
a backslash and a lowercase ``'n'``. String quotes can be escaped with a
backslash, but the backslash remains in the string; for example, ``r"\""`` is a
valid string literal consisting of two characters: a backslash and a double
quote; ``r"\"`` is not a valid string literal (even a raw string cannot end in
an odd number of backslashes). Specifically, *a raw string cannot end in a
single backslash* (since the backslash would escape the following quote
character). Note also that a single backslash followed by a newline is
interpreted as those two characters as part of the string, *not* as a line
continuation.
When an ``'r'`` or ``'R'`` prefix is used in conjunction with a ``'u'`` or
``'U'`` prefix, then the ``\uXXXX`` and ``\UXXXXXXXX`` escape sequences are
processed while *all other backslashes are left in the string*. For example,
the string literal ``ur"\u0062\n"`` consists of three Unicode characters: 'LATIN
SMALL LETTER B', 'REVERSE SOLIDUS', and 'LATIN SMALL LETTER N'. Backslashes can
be escaped with a preceding backslash; however, both remain in the string. As a
result, ``\uXXXX`` escape sequences are only recognized when there are an odd
number of backslashes.
.. _string-catenation:
String literal concatenation
----------------------------
Multiple adjacent string literals (delimited by whitespace), possibly using
different quoting conventions, are allowed, and their meaning is the same as
their concatenation. Thus, ``"hello" 'world'`` is equivalent to
``"helloworld"``. This feature can be used to reduce the number of backslashes
needed, to split long strings conveniently across long lines, or even to add
comments to parts of strings, for example::
re.compile("[A-Za-z_]" # letter or underscore
"[A-Za-z0-9_]*" # letter, digit or underscore
)
Note that this feature is defined at the syntactical level, but implemented at
compile time. The '+' operator must be used to concatenate string expressions
at run time. Also note that literal concatenation can use different quoting
styles for each component (even mixing raw strings and triple quoted strings).
.. _numbers:
Numeric literals
----------------
.. index::
single: number
single: numeric literal
single: integer literal
single: plain integer literal
single: long integer literal
single: floating point literal
single: hexadecimal literal
single: binary literal
single: octal literal
single: decimal literal
single: imaginary literal
single: complex; literal
There are four types of numeric literals: plain integers, long integers,
floating point numbers, and imaginary numbers. There are no complex literals
(complex numbers can be formed by adding a real number and an imaginary number).
Note that numeric literals do not include a sign; a phrase like ``-1`` is
actually an expression composed of the unary operator '``-``' and the literal
``1``.
.. _integers:
Integer and long integer literals
---------------------------------
Integer and long integer literals are described by the following lexical
definitions:
.. productionlist::
longinteger: `integer` ("l" | "L")
integer: `decimalinteger` | `octinteger` | `hexinteger` | `bininteger`
decimalinteger: `nonzerodigit` `digit`* | "0"
octinteger: "0" ("o" | "O") `octdigit`+ | "0" `octdigit`+
hexinteger: "0" ("x" | "X") `hexdigit`+
bininteger: "0" ("b" | "B") `bindigit`+
nonzerodigit: "1"..."9"
octdigit: "0"..."7"
bindigit: "0" | "1"
hexdigit: `digit` | "a"..."f" | "A"..."F"
Although both lower case ``'l'`` and upper case ``'L'`` are allowed as suffix
for long integers, it is strongly recommended to always use ``'L'``, since the
letter ``'l'`` looks too much like the digit ``'1'``.
Plain integer literals that are above the largest representable plain integer
(e.g., 2147483647 when using 32-bit arithmetic) are accepted as if they were
long integers instead. [#]_ There is no limit for long integer literals apart
from what can be stored in available memory.
Some examples of plain integer literals (first row) and long integer literals
(second and third rows)::
7 2147483647 0177
3L 79228162514264337593543950336L 0377L 0x100000000L
79228162514264337593543950336 0xdeadbeef
.. _floating:
Floating point literals
-----------------------
Floating point literals are described by the following lexical definitions:
.. productionlist::
floatnumber: `pointfloat` | `exponentfloat`
pointfloat: [`intpart`] `fraction` | `intpart` "."
exponentfloat: (`intpart` | `pointfloat`) `exponent`
intpart: `digit`+
fraction: "." `digit`+
exponent: ("e" | "E") ["+" | "-"] `digit`+
Note that the integer and exponent parts of floating point numbers can look like
octal integers, but are interpreted using radix 10. For example, ``077e010`` is
legal, and denotes the same number as ``77e10``. The allowed range of floating
point literals is implementation-dependent. Some examples of floating point
literals::
3.14 10. .001 1e100 3.14e-10 0e0
Note that numeric literals do not include a sign; a phrase like ``-1`` is
actually an expression composed of the unary operator ``-`` and the literal
``1``.
.. _imaginary:
Imaginary literals
------------------
Imaginary literals are described by the following lexical definitions:
.. productionlist::
imagnumber: (`floatnumber` | `intpart`) ("j" | "J")
An imaginary literal yields a complex number with a real part of 0.0. Complex
numbers are represented as a pair of floating point numbers and have the same
restrictions on their range. To create a complex number with a nonzero real
part, add a floating point number to it, e.g., ``(3+4j)``. Some examples of
imaginary literals::
3.14j 10.j 10j .001j 1e100j 3.14e-10j
.. _operators:
Operators
=========
.. index:: single: operators
The following tokens are operators:
.. code-block:: none
+ - * ** / // %
<< >> & | ^ ~
< > <= >= == != <>
The comparison operators ``<>`` and ``!=`` are alternate spellings of the same
operator. ``!=`` is the preferred spelling; ``<>`` is obsolescent.
.. _delimiters:
Delimiters
==========
.. index:: single: delimiters
The following tokens serve as delimiters in the grammar:
.. code-block:: none
( ) [ ] { } @
, : . ` = ;
+= -= *= /= //= %=
&= |= ^= >>= <<= **=
The period can also occur in floating-point and imaginary literals. A sequence
of three periods has a special meaning as an ellipsis in slices. The second half
of the list, the augmented assignment operators, serve lexically as delimiters,
but also perform an operation.
The following printing ASCII characters have special meaning as part of other
tokens or are otherwise significant to the lexical analyzer:
.. code-block:: none
' " # \
.. index:: single: ASCII@ASCII
The following printing ASCII characters are not used in Python. Their
occurrence outside string literals and comments is an unconditional error:
.. code-block:: none
$ ?
.. rubric:: Footnotes
.. [#] In versions of Python prior to 2.4, octal and hexadecimal literals in the range
just above the largest representable plain integer but below the largest
unsigned 32-bit number (on a machine using 32-bit arithmetic), 4294967296, were
taken as the negative plain integer obtained by subtracting 4294967296 from
their unsigned value.
PK
%�\| l5� 5� , html/_sources/reference/simple_stmts.rst.txtnu �[���
.. _simple:
*****************
Simple statements
*****************
.. index:: pair: simple; statement
Simple statements are comprised within a single logical line. Several simple
statements may occur on a single line separated by semicolons. The syntax for
simple statements is:
.. productionlist::
simple_stmt: `expression_stmt`
: | `assert_stmt`
: | `assignment_stmt`
: | `augmented_assignment_stmt`
: | `pass_stmt`
: | `del_stmt`
: | `print_stmt`
: | `return_stmt`
: | `yield_stmt`
: | `raise_stmt`
: | `break_stmt`
: | `continue_stmt`
: | `import_stmt`
: | `future_stmt`
: | `global_stmt`
: | `exec_stmt`
.. _exprstmts:
Expression statements
=====================
.. index::
pair: expression; statement
pair: expression; list
Expression statements are used (mostly interactively) to compute and write a
value, or (usually) to call a procedure (a function that returns no meaningful
result; in Python, procedures return the value ``None``). Other uses of
expression statements are allowed and occasionally useful. The syntax for an
expression statement is:
.. productionlist::
expression_stmt: `expression_list`
An expression statement evaluates the expression list (which may be a single
expression).
.. index::
builtin: repr
object: None
pair: string; conversion
single: output
pair: standard; output
pair: writing; values
pair: procedure; call
In interactive mode, if the value is not ``None``, it is converted to a string
using the built-in :func:`repr` function and the resulting string is written to
standard output (see section :ref:`print`) on a line by itself. (Expression
statements yielding ``None`` are not written, so that procedure calls do not
cause any output.)
.. _assignment:
Assignment statements
=====================
.. index::
single: =; assignment statement
pair: assignment; statement
pair: binding; name
pair: rebinding; name
object: mutable
pair: attribute; assignment
Assignment statements are used to (re)bind names to values and to modify
attributes or items of mutable objects:
.. productionlist::
assignment_stmt: (`target_list` "=")+ (`expression_list` | `yield_expression`)
target_list: `target` ("," `target`)* [","]
target: `identifier`
: | "(" `target_list` ")"
: | "[" [`target_list`] "]"
: | `attributeref`
: | `subscription`
: | `slicing`
(See section :ref:`primaries` for the syntax definitions for the last three
symbols.)
.. index:: pair: expression; list
An assignment statement evaluates the expression list (remember that this can be
a single expression or a comma-separated list, the latter yielding a tuple) and
assigns the single resulting object to each of the target lists, from left to
right.
.. index::
single: target
pair: target; list
Assignment is defined recursively depending on the form of the target (list).
When a target is part of a mutable object (an attribute reference, subscription
or slicing), the mutable object must ultimately perform the assignment and
decide about its validity, and may raise an exception if the assignment is
unacceptable. The rules observed by various types and the exceptions raised are
given with the definition of the object types (see section :ref:`types`).
.. index:: triple: target; list; assignment
Assignment of an object to a target list is recursively defined as follows.
* If the target list is a single target: The object is assigned to that target.
* If the target list is a comma-separated list of targets: The object must be an
iterable with the same number of items as there are targets in the target list,
and the items are assigned, from left to right, to the corresponding targets.
Assignment of an object to a single target is recursively defined as follows.
* If the target is an identifier (name):
.. index:: statement: global
* If the name does not occur in a :keyword:`global` statement in the current
code block: the name is bound to the object in the current local namespace.
* Otherwise: the name is bound to the object in the current global namespace.
.. index:: single: destructor
The name is rebound if it was already bound. This may cause the reference count
for the object previously bound to the name to reach zero, causing the object to
be deallocated and its destructor (if it has one) to be called.
* If the target is a target list enclosed in parentheses or in square brackets:
The object must be an iterable with the same number of items as there are
targets in the target list, and its items are assigned, from left to right,
to the corresponding targets.
.. index:: pair: attribute; assignment
* If the target is an attribute reference: The primary expression in the
reference is evaluated. It should yield an object with assignable attributes;
if this is not the case, :exc:`TypeError` is raised. That object is then
asked to assign the assigned object to the given attribute; if it cannot
perform the assignment, it raises an exception (usually but not necessarily
:exc:`AttributeError`).
.. _attr-target-note:
Note: If the object is a class instance and the attribute reference occurs on
both sides of the assignment operator, the RHS expression, ``a.x`` can access
either an instance attribute or (if no instance attribute exists) a class
attribute. The LHS target ``a.x`` is always set as an instance attribute,
creating it if necessary. Thus, the two occurrences of ``a.x`` do not
necessarily refer to the same attribute: if the RHS expression refers to a
class attribute, the LHS creates a new instance attribute as the target of the
assignment::
class Cls:
x = 3 # class variable
inst = Cls()
inst.x = inst.x + 1 # writes inst.x as 4 leaving Cls.x as 3
This description does not necessarily apply to descriptor attributes, such as
properties created with :func:`property`.
.. index::
pair: subscription; assignment
object: mutable
* If the target is a subscription: The primary expression in the reference is
evaluated. It should yield either a mutable sequence object (such as a list) or
a mapping object (such as a dictionary). Next, the subscript expression is
evaluated.
.. index::
object: sequence
object: list
If the primary is a mutable sequence object (such as a list), the subscript must
yield a plain integer. If it is negative, the sequence's length is added to it.
The resulting value must be a nonnegative integer less than the sequence's
length, and the sequence is asked to assign the assigned object to its item with
that index. If the index is out of range, :exc:`IndexError` is raised
(assignment to a subscripted sequence cannot add new items to a list).
.. index::
object: mapping
object: dictionary
If the primary is a mapping object (such as a dictionary), the subscript must
have a type compatible with the mapping's key type, and the mapping is then
asked to create a key/datum pair which maps the subscript to the assigned
object. This can either replace an existing key/value pair with the same key
value, or insert a new key/value pair (if no key with the same value existed).
.. index:: pair: slicing; assignment
* If the target is a slicing: The primary expression in the reference is
evaluated. It should yield a mutable sequence object (such as a list). The
assigned object should be a sequence object of the same type. Next, the lower
and upper bound expressions are evaluated, insofar they are present; defaults
are zero and the sequence's length. The bounds should evaluate to (small)
integers. If either bound is negative, the sequence's length is added to it.
The resulting bounds are clipped to lie between zero and the sequence's length,
inclusive. Finally, the sequence object is asked to replace the slice with the
items of the assigned sequence. The length of the slice may be different from
the length of the assigned sequence, thus changing the length of the target
sequence, if the object allows it.
.. impl-detail::
In the current implementation, the syntax for targets is taken to be the same
as for expressions, and invalid syntax is rejected during the code generation
phase, causing less detailed error messages.
WARNING: Although the definition of assignment implies that overlaps between the
left-hand side and the right-hand side are 'safe' (for example ``a, b = b, a``
swaps two variables), overlaps *within* the collection of assigned-to variables
are not safe! For instance, the following program prints ``[0, 2]``::
x = [0, 1]
i = 0
i, x[i] = 1, 2
print x
.. _augassign:
Augmented assignment statements
-------------------------------
.. index::
pair: augmented; assignment
single: statement; assignment, augmented
single: +=; augmented assignment
single: -=; augmented assignment
single: *=; augmented assignment
single: /=; augmented assignment
single: %=; augmented assignment
single: &=; augmented assignment
single: ^=; augmented assignment
single: |=; augmented assignment
single: **=; augmented assignment
single: //=; augmented assignment
single: >>=; augmented assignment
single: <<=; augmented assignment
Augmented assignment is the combination, in a single statement, of a binary
operation and an assignment statement:
.. productionlist::
augmented_assignment_stmt: `augtarget` `augop` (`expression_list` | `yield_expression`)
augtarget: `identifier` | `attributeref` | `subscription` | `slicing`
augop: "+=" | "-=" | "*=" | "/=" | "//=" | "%=" | "**="
: | ">>=" | "<<=" | "&=" | "^=" | "|="
(See section :ref:`primaries` for the syntax definitions for the last three
symbols.)
An augmented assignment evaluates the target (which, unlike normal assignment
statements, cannot be an unpacking) and the expression list, performs the binary
operation specific to the type of assignment on the two operands, and assigns
the result to the original target. The target is only evaluated once.
An augmented assignment expression like ``x += 1`` can be rewritten as ``x = x +
1`` to achieve a similar, but not exactly equal effect. In the augmented
version, ``x`` is only evaluated once. Also, when possible, the actual operation
is performed *in-place*, meaning that rather than creating a new object and
assigning that to the target, the old object is modified instead.
With the exception of assigning to tuples and multiple targets in a single
statement, the assignment done by augmented assignment statements is handled the
same way as normal assignments. Similarly, with the exception of the possible
*in-place* behavior, the binary operation performed by augmented assignment is
the same as the normal binary operations.
For targets which are attribute references, the same :ref:`caveat about class
and instance attributes <attr-target-note>` applies as for regular assignments.
.. _assert:
The :keyword:`assert` statement
===============================
.. index::
statement: assert
pair: debugging; assertions
Assert statements are a convenient way to insert debugging assertions into a
program:
.. productionlist::
assert_stmt: "assert" `expression` ["," `expression`]
The simple form, ``assert expression``, is equivalent to ::
if __debug__:
if not expression: raise AssertionError
The extended form, ``assert expression1, expression2``, is equivalent to ::
if __debug__:
if not expression1: raise AssertionError(expression2)
.. index::
single: __debug__
exception: AssertionError
These equivalences assume that :const:`__debug__` and :exc:`AssertionError` refer to
the built-in variables with those names. In the current implementation, the
built-in variable :const:`__debug__` is ``True`` under normal circumstances,
``False`` when optimization is requested (command line option -O). The current
code generator emits no code for an assert statement when optimization is
requested at compile time. Note that it is unnecessary to include the source
code for the expression that failed in the error message; it will be displayed
as part of the stack trace.
Assignments to :const:`__debug__` are illegal. The value for the built-in variable
is determined when the interpreter starts.
.. _pass:
The :keyword:`pass` statement
=============================
.. index::
statement: pass
pair: null; operation
.. productionlist::
pass_stmt: "pass"
:keyword:`pass` is a null operation --- when it is executed, nothing happens.
It is useful as a placeholder when a statement is required syntactically, but no
code needs to be executed, for example::
def f(arg): pass # a function that does nothing (yet)
class C: pass # a class with no methods (yet)
.. _del:
The :keyword:`del` statement
============================
.. index::
statement: del
pair: deletion; target
triple: deletion; target; list
.. productionlist::
del_stmt: "del" `target_list`
Deletion is recursively defined very similar to the way assignment is defined.
Rather than spelling it out in full details, here are some hints.
Deletion of a target list recursively deletes each target, from left to right.
.. index::
statement: global
pair: unbinding; name
Deletion of a name removes the binding of that name from the local or global
namespace, depending on whether the name occurs in a :keyword:`global` statement
in the same code block. If the name is unbound, a :exc:`NameError` exception
will be raised.
.. index:: pair: free; variable
It is illegal to delete a name from the local namespace if it occurs as a free
variable in a nested block.
.. index:: pair: attribute; deletion
Deletion of attribute references, subscriptions and slicings is passed to the
primary object involved; deletion of a slicing is in general equivalent to
assignment of an empty slice of the right type (but even this is determined by
the sliced object).
.. _print:
The :keyword:`print` statement
==============================
.. index:: statement: print
.. productionlist::
print_stmt: "print" ([`expression` ("," `expression`)* [","]]
: | ">>" `expression` [("," `expression`)+ [","]])
:keyword:`print` evaluates each expression in turn and writes the resulting
object to standard output (see below). If an object is not a string, it is
first converted to a string using the rules for string conversions. The
(resulting or original) string is then written. A space is written before each
object is (converted and) written, unless the output system believes it is
positioned at the beginning of a line. This is the case (1) when no characters
have yet been written to standard output, (2) when the last character written to
standard output is a whitespace character except ``' '``, or (3) when the last
write operation on standard output was not a :keyword:`print` statement.
(In some cases it may be functional to write an empty string to standard output
for this reason.)
.. note::
Objects which act like file objects but which are not the built-in file objects
often do not properly emulate this aspect of the file object's behavior, so it
is best not to rely on this.
.. index::
single: output
pair: writing; values
pair: trailing; comma
pair: newline; suppression
A ``'\n'`` character is written at the end, unless the :keyword:`print`
statement ends with a comma. This is the only action if the statement contains
just the keyword :keyword:`print`.
.. index::
pair: standard; output
module: sys
single: stdout (in module sys)
exception: RuntimeError
Standard output is defined as the file object named ``stdout`` in the built-in
module :mod:`sys`. If no such object exists, or if it does not have a
:meth:`write` method, a :exc:`RuntimeError` exception is raised.
.. index:: single: extended print statement
:keyword:`print` also has an extended form, defined by the second portion of the
syntax described above. This form is sometimes referred to as ":keyword:`print`
chevron." In this form, the first expression after the ``>>`` must evaluate to a
"file-like" object, specifically an object that has a :meth:`write` method as
described above. With this extended form, the subsequent expressions are
printed to this file object. If the first expression evaluates to ``None``,
then ``sys.stdout`` is used as the file for output.
.. _return:
The :keyword:`return` statement
===============================
.. index::
statement: return
pair: function; definition
pair: class; definition
.. productionlist::
return_stmt: "return" [`expression_list`]
:keyword:`return` may only occur syntactically nested in a function definition,
not within a nested class definition.
If an expression list is present, it is evaluated, else ``None`` is substituted.
:keyword:`return` leaves the current function call with the expression list (or
``None``) as return value.
.. index:: keyword: finally
When :keyword:`return` passes control out of a :keyword:`try` statement with a
:keyword:`finally` clause, that :keyword:`finally` clause is executed before
really leaving the function.
In a generator function, the :keyword:`return` statement is not allowed to
include an :token:`expression_list`. In that context, a bare :keyword:`return`
indicates that the generator is done and will cause :exc:`StopIteration` to be
raised.
.. _yield:
The :keyword:`yield` statement
==============================
.. index::
statement: yield
single: generator; function
single: generator; iterator
single: function; generator
exception: StopIteration
.. productionlist::
yield_stmt: `yield_expression`
The :keyword:`yield` statement is only used when defining a generator function,
and is only used in the body of the generator function. Using a :keyword:`yield`
statement in a function definition is sufficient to cause that definition to
create a generator function instead of a normal function.
When a generator function is called, it returns an iterator known as a generator
iterator, or more commonly, a generator. The body of the generator function is
executed by calling the generator's :meth:`~generator.next` method repeatedly
until it raises an exception.
When a :keyword:`yield` statement is executed, the state of the generator is
frozen and the value of :token:`expression_list` is returned to
:meth:`~generator.next`'s caller. By "frozen" we mean that all local state is
retained, including the current bindings of local variables, the instruction
pointer, and the internal evaluation stack: enough information is saved so that
the next time :meth:`~generator.next` is invoked, the function can proceed
exactly as if the :keyword:`yield` statement were just another external call.
As of Python version 2.5, the :keyword:`yield` statement is now allowed in the
:keyword:`try` clause of a :keyword:`try` ... :keyword:`finally` construct. If
the generator is not resumed before it is finalized (by reaching a zero
reference count or by being garbage collected), the generator-iterator's
:meth:`close` method will be called, allowing any pending :keyword:`finally`
clauses to execute.
For full details of :keyword:`yield` semantics, refer to the :ref:`yieldexpr`
section.
.. note::
In Python 2.2, the :keyword:`yield` statement was only allowed when the
``generators`` feature has been enabled. This ``__future__``
import statement was used to enable the feature::
from __future__ import generators
.. seealso::
:pep:`255` - Simple Generators
The proposal for adding generators and the :keyword:`yield` statement to Python.
:pep:`342` - Coroutines via Enhanced Generators
The proposal that, among other generator enhancements, proposed allowing
:keyword:`yield` to appear inside a :keyword:`try` ... :keyword:`finally` block.
.. _raise:
The :keyword:`raise` statement
==============================
.. index::
statement: raise
single: exception
pair: raising; exception
.. productionlist::
raise_stmt: "raise" [`expression` ["," `expression` ["," `expression`]]]
If no expressions are present, :keyword:`raise` re-raises the last exception
that was active in the current scope. If no exception is active in the current
scope, a :exc:`TypeError` exception is raised indicating that this is an error
(if running under IDLE, a :exc:`Queue.Empty` exception is raised instead).
Otherwise, :keyword:`raise` evaluates the expressions to get three objects,
using ``None`` as the value of omitted expressions. The first two objects are
used to determine the *type* and *value* of the exception.
If the first object is an instance, the type of the exception is the class of
the instance, the instance itself is the value, and the second object must be
``None``.
If the first object is a class, it becomes the type of the exception. The second
object is used to determine the exception value: If it is an instance of the
class, the instance becomes the exception value. If the second object is a
tuple, it is used as the argument list for the class constructor; if it is
``None``, an empty argument list is used, and any other object is treated as a
single argument to the constructor. The instance so created by calling the
constructor is used as the exception value.
.. index:: object: traceback
If a third object is present and not ``None``, it must be a traceback object
(see section :ref:`types`), and it is substituted instead of the current
location as the place where the exception occurred. If the third object is
present and not a traceback object or ``None``, a :exc:`TypeError` exception is
raised. The three-expression form of :keyword:`raise` is useful to re-raise an
exception transparently in an except clause, but :keyword:`raise` with no
expressions should be preferred if the exception to be re-raised was the most
recently active exception in the current scope.
Additional information on exceptions can be found in section :ref:`exceptions`,
and information about handling exceptions is in section :ref:`try`.
.. _break:
The :keyword:`break` statement
==============================
.. index::
statement: break
statement: for
statement: while
pair: loop; statement
.. productionlist::
break_stmt: "break"
:keyword:`break` may only occur syntactically nested in a :keyword:`for` or
:keyword:`while` loop, but not nested in a function or class definition within
that loop.
.. index:: keyword: else
It terminates the nearest enclosing loop, skipping the optional :keyword:`else`
clause if the loop has one.
.. index:: pair: loop control; target
If a :keyword:`for` loop is terminated by :keyword:`break`, the loop control
target keeps its current value.
.. index:: keyword: finally
When :keyword:`break` passes control out of a :keyword:`try` statement with a
:keyword:`finally` clause, that :keyword:`finally` clause is executed before
really leaving the loop.
.. _continue:
The :keyword:`continue` statement
=================================
.. index::
statement: continue
statement: for
statement: while
pair: loop; statement
keyword: finally
.. productionlist::
continue_stmt: "continue"
:keyword:`continue` may only occur syntactically nested in a :keyword:`for` or
:keyword:`while` loop, but not nested in a function or class definition or
:keyword:`finally` clause within that loop. It continues with the next
cycle of the nearest enclosing loop.
When :keyword:`continue` passes control out of a :keyword:`try` statement with a
:keyword:`finally` clause, that :keyword:`finally` clause is executed before
really starting the next loop cycle.
.. _import:
.. _from:
The :keyword:`import` statement
===============================
.. index::
statement: import
single: module; importing
pair: name; binding
keyword: from
single: as; import statement
.. productionlist::
import_stmt: "import" `module` ["as" `name`] ( "," `module` ["as" `name`] )*
: | "from" `relative_module` "import" `identifier` ["as" `name`]
: ( "," `identifier` ["as" `name`] )*
: | "from" `relative_module` "import" "(" `identifier` ["as" `name`]
: ( "," `identifier` ["as" `name`] )* [","] ")"
: | "from" `module` "import" "*"
module: (`identifier` ".")* `identifier`
relative_module: "."* `module` | "."+
name: `identifier`
Import statements are executed in two steps: (1) find a module, and initialize
it if necessary; (2) define a name or names in the local namespace (of the scope
where the :keyword:`import` statement occurs). The statement comes in two
forms differing on whether it uses the :keyword:`from` keyword. The first form
(without :keyword:`from`) repeats these steps for each identifier in the list.
The form with :keyword:`from` performs step (1) once, and then performs step
(2) repeatedly.
.. index::
single: package
To understand how step (1) occurs, one must first understand how Python handles
hierarchical naming of modules. To help organize modules and provide a
hierarchy in naming, Python has a concept of packages. A package can contain
other packages and modules while modules cannot contain other modules or
packages. From a file system perspective, packages are directories and modules
are files.
.. index::
single: sys.modules
Once the name of the module is known (unless otherwise specified, the term
"module" will refer to both packages and modules), searching
for the module or package can begin. The first place checked is
:data:`sys.modules`, the cache of all modules that have been imported
previously. If the module is found there then it is used in step (2) of import.
.. index::
single: sys.meta_path
single: finder
pair: finder; find_module
single: __path__
If the module is not found in the cache, then :data:`sys.meta_path` is searched
(the specification for :data:`sys.meta_path` can be found in :pep:`302`).
The object is a list of :term:`finder` objects which are queried in order as to
whether they know how to load the module by calling their :meth:`find_module`
method with the name of the module. If the module happens to be contained
within a package (as denoted by the existence of a dot in the name), then a
second argument to :meth:`find_module` is given as the value of the
:attr:`__path__` attribute from the parent package (everything up to the last
dot in the name of the module being imported). If a finder can find the module
it returns a :term:`loader` (discussed later) or returns ``None``.
.. index::
single: sys.path_hooks
single: sys.path_importer_cache
single: sys.path
If none of the finders on :data:`sys.meta_path` are able to find the module
then some implicitly defined finders are queried. Implementations of Python
vary in what implicit meta path finders are defined. The one they all do
define, though, is one that handles :data:`sys.path_hooks`,
:data:`sys.path_importer_cache`, and :data:`sys.path`.
The implicit finder searches for the requested module in the "paths" specified
in one of two places ("paths" do not have to be file system paths). If the
module being imported is supposed to be contained within a package then the
second argument passed to :meth:`find_module`, :attr:`__path__` on the parent
package, is used as the source of paths. If the module is not contained in a
package then :data:`sys.path` is used as the source of paths.
Once the source of paths is chosen it is iterated over to find a finder that
can handle that path. The dict at :data:`sys.path_importer_cache` caches
finders for paths and is checked for a finder. If the path does not have a
finder cached then :data:`sys.path_hooks` is searched by calling each object in
the list with a single argument of the path, returning a finder or raises
:exc:`ImportError`. If a finder is returned then it is cached in
:data:`sys.path_importer_cache` and then used for that path entry. If no finder
can be found but the path exists then a value of ``None`` is
stored in :data:`sys.path_importer_cache` to signify that an implicit,
file-based finder that handles modules stored as individual files should be
used for that path. If the path does not exist then a finder which always
returns ``None`` is placed in the cache for the path.
.. index::
single: loader
pair: loader; load_module
exception: ImportError
If no finder can find the module then :exc:`ImportError` is raised. Otherwise
some finder returned a loader whose :meth:`load_module` method is called with
the name of the module to load (see :pep:`302` for the original definition of
loaders). A loader has several responsibilities to perform on a module it
loads. First, if the module already exists in :data:`sys.modules` (a
possibility if the loader is called outside of the import machinery) then it
is to use that module for initialization and not a new module. But if the
module does not exist in :data:`sys.modules` then it is to be added to that
dict before initialization begins. If an error occurs during loading of the
module and it was added to :data:`sys.modules` it is to be removed from the
dict. If an error occurs but the module was already in :data:`sys.modules` it
is left in the dict.
.. index::
single: __name__
single: __file__
single: __path__
single: __package__
single: __loader__
The loader must set several attributes on the module. :data:`__name__` is to be
set to the name of the module. :data:`__file__` is to be the "path" to the file
unless the module is built-in (and thus listed in
:data:`sys.builtin_module_names`) in which case the attribute is not set.
If what is being imported is a package then :data:`__path__` is to be set to a
list of paths to be searched when looking for modules and packages contained
within the package being imported. :data:`__package__` is optional but should
be set to the name of package that contains the module or package (the empty
string is used for module not contained in a package). :data:`__loader__` is
also optional but should be set to the loader object that is loading the
module.
.. index::
exception: ImportError
If an error occurs during loading then the loader raises :exc:`ImportError` if
some other exception is not already being propagated. Otherwise the loader
returns the module that was loaded and initialized.
When step (1) finishes without raising an exception, step (2) can begin.
The first form of :keyword:`import` statement binds the module name in the local
namespace to the module object, and then goes on to import the next identifier,
if any. If the module name is followed by :keyword:`as`, the name following
:keyword:`as` is used as the local name for the module.
.. index::
pair: name; binding
exception: ImportError
The :keyword:`from` form does not bind the module name: it goes through the list
of identifiers, looks each one of them up in the module found in step (1), and
binds the name in the local namespace to the object thus found. As with the
first form of :keyword:`import`, an alternate local name can be supplied by
specifying ":keyword:`as` localname". If a name is not found,
:exc:`ImportError` is raised. If the list of identifiers is replaced by a star
(``'*'``), all public names defined in the module are bound in the local
namespace of the :keyword:`import` statement..
.. index:: single: __all__ (optional module attribute)
The *public names* defined by a module are determined by checking the module's
namespace for a variable named ``__all__``; if defined, it must be a sequence of
strings which are names defined or imported by that module. The names given in
``__all__`` are all considered public and are required to exist. If ``__all__``
is not defined, the set of public names includes all names found in the module's
namespace which do not begin with an underscore character (``'_'``).
``__all__`` should contain the entire public API. It is intended to avoid
accidentally exporting items that are not part of the API (such as library
modules which were imported and used within the module).
The :keyword:`from` form with ``*`` may only occur in a module scope. If the
wild card form of import --- ``import *`` --- is used in a function and the
function contains or is a nested block with free variables, the compiler will
raise a :exc:`SyntaxError`.
.. index::
single: relative; import
When specifying what module to import you do not have to specify the absolute
name of the module. When a module or package is contained within another
package it is possible to make a relative import within the same top package
without having to mention the package name. By using leading dots in the
specified module or package after :keyword:`from` you can specify how high to
traverse up the current package hierarchy without specifying exact names. One
leading dot means the current package where the module making the import
exists. Two dots means up one package level. Three dots is up two levels, etc.
So if you execute ``from . import mod`` from a module in the ``pkg`` package
then you will end up importing ``pkg.mod``. If you execute ``from ..subpkg2
import mod`` from within ``pkg.subpkg1`` you will import ``pkg.subpkg2.mod``.
The specification for relative imports is contained within :pep:`328`.
:func:`importlib.import_module` is provided to support applications that
determine which modules need to be loaded dynamically.
.. _future:
Future statements
-----------------
.. index:: pair: future; statement
A :dfn:`future statement` is a directive to the compiler that a particular
module should be compiled using syntax or semantics that will be available in a
specified future release of Python. The future statement is intended to ease
migration to future versions of Python that introduce incompatible changes to
the language. It allows use of the new features on a per-module basis before
the release in which the feature becomes standard.
.. productionlist:: *
future_statement: "from" "__future__" "import" feature ["as" name]
: ("," feature ["as" name])*
: | "from" "__future__" "import" "(" feature ["as" name]
: ("," feature ["as" name])* [","] ")"
feature: identifier
name: identifier
A future statement must appear near the top of the module. The only lines that
can appear before a future statement are:
* the module docstring (if any),
* comments,
* blank lines, and
* other future statements.
The features recognized by Python 2.6 are ``unicode_literals``,
``print_function``, ``absolute_import``, ``division``, ``generators``,
``nested_scopes`` and ``with_statement``. ``generators``, ``with_statement``,
``nested_scopes`` are redundant in Python version 2.6 and above because they are
always enabled.
A future statement is recognized and treated specially at compile time: Changes
to the semantics of core constructs are often implemented by generating
different code. It may even be the case that a new feature introduces new
incompatible syntax (such as a new reserved word), in which case the compiler
may need to parse the module differently. Such decisions cannot be pushed off
until runtime.
For any given release, the compiler knows which feature names have been defined,
and raises a compile-time error if a future statement contains a feature not
known to it.
The direct runtime semantics are the same as for any import statement: there is
a standard module :mod:`__future__`, described later, and it will be imported in
the usual way at the time the future statement is executed.
The interesting runtime semantics depend on the specific feature enabled by the
future statement.
Note that there is nothing special about the statement::
import __future__ [as name]
That is not a future statement; it's an ordinary import statement with no
special semantics or syntax restrictions.
Code compiled by an :keyword:`exec` statement or calls to the built-in functions
:func:`compile` and :func:`execfile` that occur in a module :mod:`M` containing
a future statement will, by default, use the new syntax or semantics associated
with the future statement. This can, starting with Python 2.2 be controlled by
optional arguments to :func:`compile` --- see the documentation of that function
for details.
A future statement typed at an interactive interpreter prompt will take effect
for the rest of the interpreter session. If an interpreter is started with the
:option:`-i` option, is passed a script name to execute, and the script includes
a future statement, it will be in effect in the interactive session started
after the script is executed.
.. seealso::
:pep:`236` - Back to the __future__
The original proposal for the __future__ mechanism.
.. _global:
The :keyword:`global` statement
===============================
.. index::
statement: global
triple: global; name; binding
.. productionlist::
global_stmt: "global" `identifier` ("," `identifier`)*
The :keyword:`global` statement is a declaration which holds for the entire
current code block. It means that the listed identifiers are to be interpreted
as globals. It would be impossible to assign to a global variable without
:keyword:`global`, although free variables may refer to globals without being
declared global.
Names listed in a :keyword:`global` statement must not be used in the same code
block textually preceding that :keyword:`global` statement.
Names listed in a :keyword:`global` statement must not be defined as formal
parameters or in a :keyword:`for` loop control target, :keyword:`class`
definition, function definition, or :keyword:`import` statement.
.. impl-detail::
The current implementation does not enforce the latter two restrictions, but
programs should not abuse this freedom, as future implementations may enforce
them or silently change the meaning of the program.
.. index::
statement: exec
builtin: eval
builtin: execfile
builtin: compile
**Programmer's note:** :keyword:`global` is a directive to the parser. It
applies only to code parsed at the same time as the :keyword:`global` statement.
In particular, a :keyword:`global` statement contained in an :keyword:`exec`
statement does not affect the code block *containing* the :keyword:`exec`
statement, and code contained in an :keyword:`exec` statement is unaffected by
:keyword:`global` statements in the code containing the :keyword:`exec`
statement. The same applies to the :func:`eval`, :func:`execfile` and
:func:`compile` functions.
.. _exec:
The :keyword:`exec` statement
=============================
.. index:: statement: exec
.. productionlist::
exec_stmt: "exec" `or_expr` ["in" `expression` ["," `expression`]]
This statement supports dynamic execution of Python code. The first expression
should evaluate to either a Unicode string, a *Latin-1* encoded string, an open
file object, a code object, or a tuple. If it is a string, the string is parsed
as a suite of Python statements which is then executed (unless a syntax error
occurs). [#]_ If it is an open file, the file is parsed until EOF and executed.
If it is a code object, it is simply executed. For the interpretation of a
tuple, see below. In all cases, the code that's executed is expected to be
valid as file input (see section :ref:`file-input`). Be aware that the
:keyword:`return` and :keyword:`yield` statements may not be used outside of
function definitions even within the context of code passed to the
:keyword:`exec` statement.
In all cases, if the optional parts are omitted, the code is executed in the
current scope. If only the first expression after ``in`` is specified,
it should be a dictionary, which will be used for both the global and the local
variables. If two expressions are given, they are used for the global and local
variables, respectively. If provided, *locals* can be any mapping object.
Remember that at module level, globals and locals are the same dictionary. If
two separate objects are given as *globals* and *locals*, the code will be
executed as if it were embedded in a class definition.
The first expression may also be a tuple of length 2 or 3. In this case, the
optional parts must be omitted. The form ``exec(expr, globals)`` is equivalent
to ``exec expr in globals``, while the form ``exec(expr, globals, locals)`` is
equivalent to ``exec expr in globals, locals``. The tuple form of ``exec``
provides compatibility with Python 3, where ``exec`` is a function rather than
a statement.
.. versionchanged:: 2.4
Formerly, *locals* was required to be a dictionary.
.. index::
single: __builtins__
module: __builtin__
As a side effect, an implementation may insert additional keys into the
dictionaries given besides those corresponding to variable names set by the
executed code. For example, the current implementation may add a reference to
the dictionary of the built-in module :mod:`__builtin__` under the key
``__builtins__`` (!).
.. index::
builtin: eval
builtin: globals
builtin: locals
**Programmer's hints:** dynamic evaluation of expressions is supported by the
built-in function :func:`eval`. The built-in functions :func:`globals` and
:func:`locals` return the current global and local dictionary, respectively,
which may be useful to pass around for use by :keyword:`exec`.
.. rubric:: Footnotes
.. [#] Note that the parser only accepts the Unix-style end of line convention.
If you are reading the code from a file, make sure to use
:term:`universal newlines` mode to convert Windows or Mac-style newlines.
PK
%�\0�pI�
�
3 html/_sources/reference/toplevel_components.rst.txtnu �[���
.. _top-level:
********************
Top-level components
********************
.. index:: single: interpreter
The Python interpreter can get its input from a number of sources: from a script
passed to it as standard input or as program argument, typed in interactively,
from a module source file, etc. This chapter gives the syntax used in these
cases.
.. _programs:
Complete Python programs
========================
.. index:: single: program
.. index::
module: sys
module: __main__
module: __builtin__
While a language specification need not prescribe how the language interpreter
is invoked, it is useful to have a notion of a complete Python program. A
complete Python program is executed in a minimally initialized environment: all
built-in and standard modules are available, but none have been initialized,
except for :mod:`sys` (various system services), :mod:`__builtin__` (built-in
functions, exceptions and ``None``) and :mod:`__main__`. The latter is used to
provide the local and global namespace for execution of the complete program.
The syntax for a complete Python program is that for file input, described in
the next section.
.. index::
single: interactive mode
module: __main__
The interpreter may also be invoked in interactive mode; in this case, it does
not read and execute a complete program but reads and executes one statement
(possibly compound) at a time. The initial environment is identical to that of
a complete program; each statement is executed in the namespace of
:mod:`__main__`.
.. index::
single: UNIX
single: command line
single: standard input
A complete program can be passed to the interpreter
in three forms: with the :option:`-c` *string* command line option, as a file
passed as the first command line argument, or as standard input. If the file
or standard input is a tty device, the interpreter enters interactive mode;
otherwise, it executes the file as a complete program.
.. _file-input:
File input
==========
All input read from non-interactive files has the same form:
.. productionlist::
file_input: (NEWLINE | `statement`)*
This syntax is used in the following situations:
* when parsing a complete Python program (from a file or from a string);
* when parsing a module;
* when parsing a string passed to the :keyword:`exec` statement;
.. _interactive:
Interactive input
=================
Input in interactive mode is parsed using the following grammar:
.. productionlist::
interactive_input: [`stmt_list`] NEWLINE | `compound_stmt` NEWLINE
Note that a (top-level) compound statement must be followed by a blank line in
interactive mode; this is needed to help the parser detect the end of the input.
.. _expression-input:
Expression input
================
.. index:: single: input
.. index:: builtin: eval
There are two forms of expression input. Both ignore leading whitespace. The
string argument to :func:`eval` must have the following form:
.. productionlist::
eval_input: `expression_list` NEWLINE*
.. index:: builtin: input
The input line read by :func:`input` must have the following form:
.. productionlist::
input_input: `expression_list` NEWLINE
.. index::
object: file
single: input; raw
single: raw input
builtin: raw_input
single: readline() (file method)
Note: to read 'raw' input line without interpretation, you can use the built-in
function :func:`raw_input` or the :meth:`readline` method of file objects.
PK
%�\�� � ' html/_sources/tutorial/appendix.rst.txtnu �[��� .. _tut-appendix:
********
Appendix
********
.. _tut-interac:
Interactive Mode
================
.. _tut-error:
Error Handling
--------------
When an error occurs, the interpreter prints an error message and a stack trace.
In interactive mode, it then returns to the primary prompt; when input came from
a file, it exits with a nonzero exit status after printing the stack trace.
(Exceptions handled by an :keyword:`except` clause in a :keyword:`try` statement
are not errors in this context.) Some errors are unconditionally fatal and
cause an exit with a nonzero exit; this applies to internal inconsistencies and
some cases of running out of memory. All error messages are written to the
standard error stream; normal output from executed commands is written to
standard output.
Typing the interrupt character (usually :kbd:`Control-C` or :kbd:`Delete`) to the primary or
secondary prompt cancels the input and returns to the primary prompt. [#]_
Typing an interrupt while a command is executing raises the
:exc:`KeyboardInterrupt` exception, which may be handled by a :keyword:`try`
statement.
.. _tut-scripts:
Executable Python Scripts
-------------------------
On BSD'ish Unix systems, Python scripts can be made directly executable, like
shell scripts, by putting the line ::
#!/usr/bin/env python
(assuming that the interpreter is on the user's :envvar:`PATH`) at the beginning
of the script and giving the file an executable mode. The ``#!`` must be the
first two characters of the file. On some platforms, this first line must end
with a Unix-style line ending (``'\n'``), not a Windows (``'\r\n'``) line
ending. Note that the hash, or pound, character, ``'#'``, is used to start a
comment in Python.
The script can be given an executable mode, or permission, using the
:program:`chmod` command.
.. code-block:: bash
$ chmod +x myscript.py
On Windows systems, there is no notion of an "executable mode". The Python
installer automatically associates ``.py`` files with ``python.exe`` so that
a double-click on a Python file will run it as a script. The extension can
also be ``.pyw``, in that case, the console window that normally appears is
suppressed.
.. _tut-startup:
The Interactive Startup File
----------------------------
When you use Python interactively, it is frequently handy to have some standard
commands executed every time the interpreter is started. You can do this by
setting an environment variable named :envvar:`PYTHONSTARTUP` to the name of a
file containing your start-up commands. This is similar to the :file:`.profile`
feature of the Unix shells.
This file is only read in interactive sessions, not when Python reads commands
from a script, and not when :file:`/dev/tty` is given as the explicit source of
commands (which otherwise behaves like an interactive session). It is executed
in the same namespace where interactive commands are executed, so that objects
that it defines or imports can be used without qualification in the interactive
session. You can also change the prompts ``sys.ps1`` and ``sys.ps2`` in this
file.
If you want to read an additional start-up file from the current directory, you
can program this in the global start-up file using code like ``if
os.path.isfile('.pythonrc.py'): exec(open('.pythonrc.py').read())``.
If you want to use the startup file in a script, you must do this explicitly
in the script::
import os
filename = os.environ.get('PYTHONSTARTUP')
if filename and os.path.isfile(filename):
with open(filename) as fobj:
startup_file = fobj.read()
exec(startup_file)
.. _tut-customize:
The Customization Modules
-------------------------
Python provides two hooks to let you customize it: :mod:`sitecustomize` and
:mod:`usercustomize`. To see how it works, you need first to find the location
of your user site-packages directory. Start Python and run this code::
>>> import site
>>> site.getusersitepackages()
'/home/user/.local/lib/python2.7/site-packages'
Now you can create a file named :file:`usercustomize.py` in that directory and
put anything you want in it. It will affect every invocation of Python, unless
it is started with the :option:`-s` option to disable the automatic import.
:mod:`sitecustomize` works in the same way, but is typically created by an
administrator of the computer in the global site-packages directory, and is
imported before :mod:`usercustomize`. See the documentation of the :mod:`site`
module for more details.
.. rubric:: Footnotes
.. [#] A problem with the GNU Readline package may prevent this.
PK
%�\�
��� � ' html/_sources/tutorial/appetite.rst.txtnu �[��� .. _tut-intro:
**********************
Whetting Your Appetite
**********************
If you do much work on computers, eventually you find that there's some task
you'd like to automate. For example, you may wish to perform a
search-and-replace over a large number of text files, or rename and rearrange a
bunch of photo files in a complicated way. Perhaps you'd like to write a small
custom database, or a specialized GUI application, or a simple game.
If you're a professional software developer, you may have to work with several
C/C++/Java libraries but find the usual write/compile/test/re-compile cycle is
too slow. Perhaps you're writing a test suite for such a library and find
writing the testing code a tedious task. Or maybe you've written a program that
could use an extension language, and you don't want to design and implement a
whole new language for your application.
Python is just the language for you.
You could write a Unix shell script or Windows batch files for some of these
tasks, but shell scripts are best at moving around files and changing text data,
not well-suited for GUI applications or games. You could write a C/C++/Java
program, but it can take a lot of development time to get even a first-draft
program. Python is simpler to use, available on Windows, Mac OS X, and Unix
operating systems, and will help you get the job done more quickly.
Python is simple to use, but it is a real programming language, offering much
more structure and support for large programs than shell scripts or batch files
can offer. On the other hand, Python also offers much more error checking than
C, and, being a *very-high-level language*, it has high-level data types built
in, such as flexible arrays and dictionaries. Because of its more general data
types Python is applicable to a much larger problem domain than Awk or even
Perl, yet many things are at least as easy in Python as in those languages.
Python allows you to split your program into modules that can be reused in other
Python programs. It comes with a large collection of standard modules that you
can use as the basis of your programs --- or as examples to start learning to
program in Python. Some of these modules provide things like file I/O, system
calls, sockets, and even interfaces to graphical user interface toolkits like
Tk.
Python is an interpreted language, which can save you considerable time during
program development because no compilation and linking is necessary. The
interpreter can be used interactively, which makes it easy to experiment with
features of the language, to write throw-away programs, or to test functions
during bottom-up program development. It is also a handy desk calculator.
Python enables programs to be written compactly and readably. Programs written
in Python are typically much shorter than equivalent C, C++, or Java programs,
for several reasons:
* the high-level data types allow you to express complex operations in a single
statement;
* statement grouping is done by indentation instead of beginning and ending
brackets;
* no variable or argument declarations are necessary.
Python is *extensible*: if you know how to program in C it is easy to add a new
built-in function or module to the interpreter, either to perform critical
operations at maximum speed, or to link Python programs to libraries that may
only be available in binary form (such as a vendor-specific graphics library).
Once you are really hooked, you can link the Python interpreter into an
application written in C and use it as an extension or command language for that
application.
By the way, the language is named after the BBC show "Monty Python's Flying
Circus" and has nothing to do with reptiles. Making references to Monty
Python skits in documentation is not only allowed, it is encouraged!
Now that you are all excited about Python, you'll want to examine it in some
more detail. Since the best way to learn a language is to use it, the tutorial
invites you to play with the Python interpreter as you read.
In the next chapter, the mechanics of using the interpreter are explained. This
is rather mundane information, but essential for trying out the examples shown
later.
The rest of the tutorial introduces various features of the Python language and
system through examples, beginning with simple expressions, statements and data
types, through functions and modules, and finally touching upon advanced
concepts like exceptions and user-defined classes.
PK
%�\ߞ�l� � & html/_sources/tutorial/classes.rst.txtnu �[��� .. _tut-classes:
*******
Classes
*******
Compared with other programming languages, Python's class mechanism adds classes
with a minimum of new syntax and semantics. It is a mixture of the class
mechanisms found in C++ and Modula-3. Python classes provide all the standard
features of Object Oriented Programming: the class inheritance mechanism allows
multiple base classes, a derived class can override any methods of its base
class or classes, and a method can call the method of a base class with the same
name. Objects can contain arbitrary amounts and kinds of data. As is true for
modules, classes partake of the dynamic nature of Python: they are created at
runtime, and can be modified further after creation.
In C++ terminology, normally class members (including the data members) are
*public* (except see below :ref:`tut-private`), and all member functions are
*virtual*. As in Modula-3, there are no shorthands for referencing the object's
members from its methods: the method function is declared with an explicit first
argument representing the object, which is provided implicitly by the call. As
in Smalltalk, classes themselves are objects. This provides semantics for
importing and renaming. Unlike C++ and Modula-3, built-in types can be used as
base classes for extension by the user. Also, like in C++, most built-in
operators with special syntax (arithmetic operators, subscripting etc.) can be
redefined for class instances.
(Lacking universally accepted terminology to talk about classes, I will make
occasional use of Smalltalk and C++ terms. I would use Modula-3 terms, since
its object-oriented semantics are closer to those of Python than C++, but I
expect that few readers have heard of it.)
.. _tut-object:
A Word About Names and Objects
==============================
Objects have individuality, and multiple names (in multiple scopes) can be bound
to the same object. This is known as aliasing in other languages. This is
usually not appreciated on a first glance at Python, and can be safely ignored
when dealing with immutable basic types (numbers, strings, tuples). However,
aliasing has a possibly surprising effect on the semantics of Python code
involving mutable objects such as lists, dictionaries, and most other types.
This is usually used to the benefit of the program, since aliases behave like
pointers in some respects. For example, passing an object is cheap since only a
pointer is passed by the implementation; and if a function modifies an object
passed as an argument, the caller will see the change --- this eliminates the
need for two different argument passing mechanisms as in Pascal.
.. _tut-scopes:
Python Scopes and Namespaces
============================
Before introducing classes, I first have to tell you something about Python's
scope rules. Class definitions play some neat tricks with namespaces, and you
need to know how scopes and namespaces work to fully understand what's going on.
Incidentally, knowledge about this subject is useful for any advanced Python
programmer.
Let's begin with some definitions.
A *namespace* is a mapping from names to objects. Most namespaces are currently
implemented as Python dictionaries, but that's normally not noticeable in any
way (except for performance), and it may change in the future. Examples of
namespaces are: the set of built-in names (containing functions such as :func:`abs`, and
built-in exception names); the global names in a module; and the local names in
a function invocation. In a sense the set of attributes of an object also form
a namespace. The important thing to know about namespaces is that there is
absolutely no relation between names in different namespaces; for instance, two
different modules may both define a function ``maximize`` without confusion ---
users of the modules must prefix it with the module name.
By the way, I use the word *attribute* for any name following a dot --- for
example, in the expression ``z.real``, ``real`` is an attribute of the object
``z``. Strictly speaking, references to names in modules are attribute
references: in the expression ``modname.funcname``, ``modname`` is a module
object and ``funcname`` is an attribute of it. In this case there happens to be
a straightforward mapping between the module's attributes and the global names
defined in the module: they share the same namespace! [#]_
Attributes may be read-only or writable. In the latter case, assignment to
attributes is possible. Module attributes are writable: you can write
``modname.the_answer = 42``. Writable attributes may also be deleted with the
:keyword:`del` statement. For example, ``del modname.the_answer`` will remove
the attribute :attr:`the_answer` from the object named by ``modname``.
Namespaces are created at different moments and have different lifetimes. The
namespace containing the built-in names is created when the Python interpreter
starts up, and is never deleted. The global namespace for a module is created
when the module definition is read in; normally, module namespaces also last
until the interpreter quits. The statements executed by the top-level
invocation of the interpreter, either read from a script file or interactively,
are considered part of a module called :mod:`__main__`, so they have their own
global namespace. (The built-in names actually also live in a module; this is
called :mod:`__builtin__`.)
The local namespace for a function is created when the function is called, and
deleted when the function returns or raises an exception that is not handled
within the function. (Actually, forgetting would be a better way to describe
what actually happens.) Of course, recursive invocations each have their own
local namespace.
A *scope* is a textual region of a Python program where a namespace is directly
accessible. "Directly accessible" here means that an unqualified reference to a
name attempts to find the name in the namespace.
Although scopes are determined statically, they are used dynamically. At any
time during execution, there are at least three nested scopes whose namespaces
are directly accessible:
* the innermost scope, which is searched first, contains the local names
* the scopes of any enclosing functions, which are searched starting with the
nearest enclosing scope, contains non-local, but also non-global names
* the next-to-last scope contains the current module's global names
* the outermost scope (searched last) is the namespace containing built-in names
If a name is declared global, then all references and assignments go directly to
the middle scope containing the module's global names. Otherwise, all variables
found outside of the innermost scope are read-only (an attempt to write to such
a variable will simply create a *new* local variable in the innermost scope,
leaving the identically named outer variable unchanged).
Usually, the local scope references the local names of the (textually) current
function. Outside functions, the local scope references the same namespace as
the global scope: the module's namespace. Class definitions place yet another
namespace in the local scope.
It is important to realize that scopes are determined textually: the global
scope of a function defined in a module is that module's namespace, no matter
from where or by what alias the function is called. On the other hand, the
actual search for names is done dynamically, at run time --- however, the
language definition is evolving towards static name resolution, at "compile"
time, so don't rely on dynamic name resolution! (In fact, local variables are
already determined statically.)
A special quirk of Python is that -- if no :keyword:`global` statement is in
effect -- assignments to names always go into the innermost scope. Assignments
do not copy data --- they just bind names to objects. The same is true for
deletions: the statement ``del x`` removes the binding of ``x`` from the
namespace referenced by the local scope. In fact, all operations that introduce
new names use the local scope: in particular, :keyword:`import` statements and
function definitions bind the module or function name in the local scope. (The
:keyword:`global` statement can be used to indicate that particular variables
live in the global scope.)
.. _tut-firstclasses:
A First Look at Classes
=======================
Classes introduce a little bit of new syntax, three new object types, and some
new semantics.
.. _tut-classdefinition:
Class Definition Syntax
-----------------------
The simplest form of class definition looks like this::
class ClassName:
<statement-1>
.
.
.
<statement-N>
Class definitions, like function definitions (:keyword:`def` statements) must be
executed before they have any effect. (You could conceivably place a class
definition in a branch of an :keyword:`if` statement, or inside a function.)
In practice, the statements inside a class definition will usually be function
definitions, but other statements are allowed, and sometimes useful --- we'll
come back to this later. The function definitions inside a class normally have
a peculiar form of argument list, dictated by the calling conventions for
methods --- again, this is explained later.
When a class definition is entered, a new namespace is created, and used as the
local scope --- thus, all assignments to local variables go into this new
namespace. In particular, function definitions bind the name of the new
function here.
When a class definition is left normally (via the end), a *class object* is
created. This is basically a wrapper around the contents of the namespace
created by the class definition; we'll learn more about class objects in the
next section. The original local scope (the one in effect just before the class
definition was entered) is reinstated, and the class object is bound here to the
class name given in the class definition header (:class:`ClassName` in the
example).
.. _tut-classobjects:
Class Objects
-------------
Class objects support two kinds of operations: attribute references and
instantiation.
*Attribute references* use the standard syntax used for all attribute references
in Python: ``obj.name``. Valid attribute names are all the names that were in
the class's namespace when the class object was created. So, if the class
definition looked like this::
class MyClass:
"""A simple example class"""
i = 12345
def f(self):
return 'hello world'
then ``MyClass.i`` and ``MyClass.f`` are valid attribute references, returning
an integer and a function object, respectively. Class attributes can also be
assigned to, so you can change the value of ``MyClass.i`` by assignment.
:attr:`__doc__` is also a valid attribute, returning the docstring belonging to
the class: ``"A simple example class"``.
Class *instantiation* uses function notation. Just pretend that the class
object is a parameterless function that returns a new instance of the class.
For example (assuming the above class)::
x = MyClass()
creates a new *instance* of the class and assigns this object to the local
variable ``x``.
The instantiation operation ("calling" a class object) creates an empty object.
Many classes like to create objects with instances customized to a specific
initial state. Therefore a class may define a special method named
:meth:`__init__`, like this::
def __init__(self):
self.data = []
When a class defines an :meth:`__init__` method, class instantiation
automatically invokes :meth:`__init__` for the newly-created class instance. So
in this example, a new, initialized instance can be obtained by::
x = MyClass()
Of course, the :meth:`__init__` method may have arguments for greater
flexibility. In that case, arguments given to the class instantiation operator
are passed on to :meth:`__init__`. For example, ::
>>> class Complex:
... def __init__(self, realpart, imagpart):
... self.r = realpart
... self.i = imagpart
...
>>> x = Complex(3.0, -4.5)
>>> x.r, x.i
(3.0, -4.5)
.. _tut-instanceobjects:
Instance Objects
----------------
Now what can we do with instance objects? The only operations understood by
instance objects are attribute references. There are two kinds of valid
attribute names, data attributes and methods.
*data attributes* correspond to "instance variables" in Smalltalk, and to "data
members" in C++. Data attributes need not be declared; like local variables,
they spring into existence when they are first assigned to. For example, if
``x`` is the instance of :class:`MyClass` created above, the following piece of
code will print the value ``16``, without leaving a trace::
x.counter = 1
while x.counter < 10:
x.counter = x.counter * 2
print x.counter
del x.counter
The other kind of instance attribute reference is a *method*. A method is a
function that "belongs to" an object. (In Python, the term method is not unique
to class instances: other object types can have methods as well. For example,
list objects have methods called append, insert, remove, sort, and so on.
However, in the following discussion, we'll use the term method exclusively to
mean methods of class instance objects, unless explicitly stated otherwise.)
.. index:: object: method
Valid method names of an instance object depend on its class. By definition,
all attributes of a class that are function objects define corresponding
methods of its instances. So in our example, ``x.f`` is a valid method
reference, since ``MyClass.f`` is a function, but ``x.i`` is not, since
``MyClass.i`` is not. But ``x.f`` is not the same thing as ``MyClass.f`` --- it
is a *method object*, not a function object.
.. _tut-methodobjects:
Method Objects
--------------
Usually, a method is called right after it is bound::
x.f()
In the :class:`MyClass` example, this will return the string ``'hello world'``.
However, it is not necessary to call a method right away: ``x.f`` is a method
object, and can be stored away and called at a later time. For example::
xf = x.f
while True:
print xf()
will continue to print ``hello world`` until the end of time.
What exactly happens when a method is called? You may have noticed that
``x.f()`` was called without an argument above, even though the function
definition for :meth:`f` specified an argument. What happened to the argument?
Surely Python raises an exception when a function that requires an argument is
called without any --- even if the argument isn't actually used...
Actually, you may have guessed the answer: the special thing about methods is
that the object is passed as the first argument of the function. In our
example, the call ``x.f()`` is exactly equivalent to ``MyClass.f(x)``. In
general, calling a method with a list of *n* arguments is equivalent to calling
the corresponding function with an argument list that is created by inserting
the method's object before the first argument.
If you still don't understand how methods work, a look at the implementation can
perhaps clarify matters. When a non-data attribute of an instance is
referenced, the instance's class is searched. If the name denotes a valid class
attribute that is a function object, a method object is created by packing
(pointers to) the instance object and the function object just found together in
an abstract object: this is the method object. When the method object is called
with an argument list, a new argument list is constructed from the instance
object and the argument list, and the function object is called with this new
argument list.
.. _tut-class-and-instance-variables:
Class and Instance Variables
----------------------------
Generally speaking, instance variables are for data unique to each instance
and class variables are for attributes and methods shared by all instances
of the class::
class Dog:
kind = 'canine' # class variable shared by all instances
def __init__(self, name):
self.name = name # instance variable unique to each instance
>>> d = Dog('Fido')
>>> e = Dog('Buddy')
>>> d.kind # shared by all dogs
'canine'
>>> e.kind # shared by all dogs
'canine'
>>> d.name # unique to d
'Fido'
>>> e.name # unique to e
'Buddy'
As discussed in :ref:`tut-object`, shared data can have possibly surprising
effects with involving :term:`mutable` objects such as lists and dictionaries.
For example, the *tricks* list in the following code should not be used as a
class variable because just a single list would be shared by all *Dog*
instances::
class Dog:
tricks = [] # mistaken use of a class variable
def __init__(self, name):
self.name = name
def add_trick(self, trick):
self.tricks.append(trick)
>>> d = Dog('Fido')
>>> e = Dog('Buddy')
>>> d.add_trick('roll over')
>>> e.add_trick('play dead')
>>> d.tricks # unexpectedly shared by all dogs
['roll over', 'play dead']
Correct design of the class should use an instance variable instead::
class Dog:
def __init__(self, name):
self.name = name
self.tricks = [] # creates a new empty list for each dog
def add_trick(self, trick):
self.tricks.append(trick)
>>> d = Dog('Fido')
>>> e = Dog('Buddy')
>>> d.add_trick('roll over')
>>> e.add_trick('play dead')
>>> d.tricks
['roll over']
>>> e.tricks
['play dead']
.. _tut-remarks:
Random Remarks
==============
.. These should perhaps be placed more carefully...
Data attributes override method attributes with the same name; to avoid
accidental name conflicts, which may cause hard-to-find bugs in large programs,
it is wise to use some kind of convention that minimizes the chance of
conflicts. Possible conventions include capitalizing method names, prefixing
data attribute names with a small unique string (perhaps just an underscore), or
using verbs for methods and nouns for data attributes.
Data attributes may be referenced by methods as well as by ordinary users
("clients") of an object. In other words, classes are not usable to implement
pure abstract data types. In fact, nothing in Python makes it possible to
enforce data hiding --- it is all based upon convention. (On the other hand,
the Python implementation, written in C, can completely hide implementation
details and control access to an object if necessary; this can be used by
extensions to Python written in C.)
Clients should use data attributes with care --- clients may mess up invariants
maintained by the methods by stamping on their data attributes. Note that
clients may add data attributes of their own to an instance object without
affecting the validity of the methods, as long as name conflicts are avoided ---
again, a naming convention can save a lot of headaches here.
There is no shorthand for referencing data attributes (or other methods!) from
within methods. I find that this actually increases the readability of methods:
there is no chance of confusing local variables and instance variables when
glancing through a method.
Often, the first argument of a method is called ``self``. This is nothing more
than a convention: the name ``self`` has absolutely no special meaning to
Python. Note, however, that by not following the convention your code may be
less readable to other Python programmers, and it is also conceivable that a
*class browser* program might be written that relies upon such a convention.
Any function object that is a class attribute defines a method for instances of
that class. It is not necessary that the function definition is textually
enclosed in the class definition: assigning a function object to a local
variable in the class is also ok. For example::
# Function defined outside the class
def f1(self, x, y):
return min(x, x+y)
class C:
f = f1
def g(self):
return 'hello world'
h = g
Now ``f``, ``g`` and ``h`` are all attributes of class :class:`C` that refer to
function objects, and consequently they are all methods of instances of
:class:`C` --- ``h`` being exactly equivalent to ``g``. Note that this practice
usually only serves to confuse the reader of a program.
Methods may call other methods by using method attributes of the ``self``
argument::
class Bag:
def __init__(self):
self.data = []
def add(self, x):
self.data.append(x)
def addtwice(self, x):
self.add(x)
self.add(x)
Methods may reference global names in the same way as ordinary functions. The
global scope associated with a method is the module containing its
definition. (A class is never used as a global scope.) While one
rarely encounters a good reason for using global data in a method, there are
many legitimate uses of the global scope: for one thing, functions and modules
imported into the global scope can be used by methods, as well as functions and
classes defined in it. Usually, the class containing the method is itself
defined in this global scope, and in the next section we'll find some good
reasons why a method would want to reference its own class.
Each value is an object, and therefore has a *class* (also called its *type*).
It is stored as ``object.__class__``.
.. _tut-inheritance:
Inheritance
===========
Of course, a language feature would not be worthy of the name "class" without
supporting inheritance. The syntax for a derived class definition looks like
this::
class DerivedClassName(BaseClassName):
<statement-1>
.
.
.
<statement-N>
The name :class:`BaseClassName` must be defined in a scope containing the
derived class definition. In place of a base class name, other arbitrary
expressions are also allowed. This can be useful, for example, when the base
class is defined in another module::
class DerivedClassName(modname.BaseClassName):
Execution of a derived class definition proceeds the same as for a base class.
When the class object is constructed, the base class is remembered. This is
used for resolving attribute references: if a requested attribute is not found
in the class, the search proceeds to look in the base class. This rule is
applied recursively if the base class itself is derived from some other class.
There's nothing special about instantiation of derived classes:
``DerivedClassName()`` creates a new instance of the class. Method references
are resolved as follows: the corresponding class attribute is searched,
descending down the chain of base classes if necessary, and the method reference
is valid if this yields a function object.
Derived classes may override methods of their base classes. Because methods
have no special privileges when calling other methods of the same object, a
method of a base class that calls another method defined in the same base class
may end up calling a method of a derived class that overrides it. (For C++
programmers: all methods in Python are effectively ``virtual``.)
An overriding method in a derived class may in fact want to extend rather than
simply replace the base class method of the same name. There is a simple way to
call the base class method directly: just call ``BaseClassName.methodname(self,
arguments)``. This is occasionally useful to clients as well. (Note that this
only works if the base class is accessible as ``BaseClassName`` in the global
scope.)
Python has two built-in functions that work with inheritance:
* Use :func:`isinstance` to check an instance's type: ``isinstance(obj, int)``
will be ``True`` only if ``obj.__class__`` is :class:`int` or some class
derived from :class:`int`.
* Use :func:`issubclass` to check class inheritance: ``issubclass(bool, int)``
is ``True`` since :class:`bool` is a subclass of :class:`int`. However,
``issubclass(unicode, str)`` is ``False`` since :class:`unicode` is not a
subclass of :class:`str` (they only share a common ancestor,
:class:`basestring`).
.. _tut-multiple:
Multiple Inheritance
--------------------
Python supports a limited form of multiple inheritance as well. A class
definition with multiple base classes looks like this::
class DerivedClassName(Base1, Base2, Base3):
<statement-1>
.
.
.
<statement-N>
For old-style classes, the only rule is depth-first, left-to-right. Thus, if an
attribute is not found in :class:`DerivedClassName`, it is searched in
:class:`Base1`, then (recursively) in the base classes of :class:`Base1`, and
only if it is not found there, it is searched in :class:`Base2`, and so on.
(To some people breadth first --- searching :class:`Base2` and :class:`Base3`
before the base classes of :class:`Base1` --- looks more natural. However, this
would require you to know whether a particular attribute of :class:`Base1` is
actually defined in :class:`Base1` or in one of its base classes before you can
figure out the consequences of a name conflict with an attribute of
:class:`Base2`. The depth-first rule makes no differences between direct and
inherited attributes of :class:`Base1`.)
For :term:`new-style class`\es, the method resolution order changes dynamically
to support cooperative calls to :func:`super`. This approach is known in some
other multiple-inheritance languages as call-next-method and is more powerful
than the super call found in single-inheritance languages.
With new-style classes, dynamic ordering is necessary because all cases of
multiple inheritance exhibit one or more diamond relationships (where at
least one of the parent classes can be accessed through multiple paths from the
bottommost class). For example, all new-style classes inherit from
:class:`object`, so any case of multiple inheritance provides more than one path
to reach :class:`object`. To keep the base classes from being accessed more
than once, the dynamic algorithm linearizes the search order in a way that
preserves the left-to-right ordering specified in each class, that calls each
parent only once, and that is monotonic (meaning that a class can be subclassed
without affecting the precedence order of its parents). Taken together, these
properties make it possible to design reliable and extensible classes with
multiple inheritance. For more detail, see
https://www.python.org/download/releases/2.3/mro/.
.. _tut-private:
Private Variables and Class-local References
============================================
"Private" instance variables that cannot be accessed except from inside an
object don't exist in Python. However, there is a convention that is followed
by most Python code: a name prefixed with an underscore (e.g. ``_spam``) should
be treated as a non-public part of the API (whether it is a function, a method
or a data member). It should be considered an implementation detail and subject
to change without notice.
.. index::
pair: name; mangling
Since there is a valid use-case for class-private members (namely to avoid name
clashes of names with names defined by subclasses), there is limited support for
such a mechanism, called :dfn:`name mangling`. Any identifier of the form
``__spam`` (at least two leading underscores, at most one trailing underscore)
is textually replaced with ``_classname__spam``, where ``classname`` is the
current class name with leading underscore(s) stripped. This mangling is done
without regard to the syntactic position of the identifier, as long as it
occurs within the definition of a class.
Name mangling is helpful for letting subclasses override methods without
breaking intraclass method calls. For example::
class Mapping:
def __init__(self, iterable):
self.items_list = []
self.__update(iterable)
def update(self, iterable):
for item in iterable:
self.items_list.append(item)
__update = update # private copy of original update() method
class MappingSubclass(Mapping):
def update(self, keys, values):
# provides new signature for update()
# but does not break __init__()
for item in zip(keys, values):
self.items_list.append(item)
The above example would work even if ``MappingSubclass`` were to introduce a
``__update`` identifier since it is replaced with ``_Mapping__update`` in the
``Mapping`` class and ``_MappingSubclass__update`` in the ``MappingSubclass``
class respectively.
Note that the mangling rules are designed mostly to avoid accidents; it still is
possible to access or modify a variable that is considered private. This can
even be useful in special circumstances, such as in the debugger.
Notice that code passed to ``exec``, ``eval()`` or ``execfile()`` does not
consider the classname of the invoking class to be the current class; this is
similar to the effect of the ``global`` statement, the effect of which is
likewise restricted to code that is byte-compiled together. The same
restriction applies to ``getattr()``, ``setattr()`` and ``delattr()``, as well
as when referencing ``__dict__`` directly.
.. _tut-odds:
Odds and Ends
=============
Sometimes it is useful to have a data type similar to the Pascal "record" or C
"struct", bundling together a few named data items. An empty class definition
will do nicely::
class Employee:
pass
john = Employee() # Create an empty employee record
# Fill the fields of the record
john.name = 'John Doe'
john.dept = 'computer lab'
john.salary = 1000
A piece of Python code that expects a particular abstract data type can often be
passed a class that emulates the methods of that data type instead. For
instance, if you have a function that formats some data from a file object, you
can define a class with methods :meth:`read` and :meth:`!readline` that get the
data from a string buffer instead, and pass it as an argument.
.. (Unfortunately, this technique has its limitations: a class can't define
operations that are accessed by special syntax such as sequence subscripting
or arithmetic operators, and assigning such a "pseudo-file" to sys.stdin will
not cause the interpreter to read further input from it.)
Instance method objects have attributes, too: ``m.im_self`` is the instance
object with the method :meth:`m`, and ``m.im_func`` is the function object
corresponding to the method.
.. _tut-exceptionclasses:
Exceptions Are Classes Too
==========================
User-defined exceptions are identified by classes as well. Using this mechanism
it is possible to create extensible hierarchies of exceptions.
There are two new valid (semantic) forms for the :keyword:`raise` statement::
raise Class, instance
raise instance
In the first form, ``instance`` must be an instance of :class:`Class` or of a
class derived from it. The second form is a shorthand for::
raise instance.__class__, instance
A class in an :keyword:`except` clause is compatible with an exception if it is
the same class or a base class thereof (but not the other way around --- an
except clause listing a derived class is not compatible with a base class). For
example, the following code will print B, C, D in that order::
class B:
pass
class C(B):
pass
class D(C):
pass
for c in [B, C, D]:
try:
raise c()
except D:
print "D"
except C:
print "C"
except B:
print "B"
Note that if the except clauses were reversed (with ``except B`` first), it
would have printed B, B, B --- the first matching except clause is triggered.
When an error message is printed for an unhandled exception, the exception's
class name is printed, then a colon and a space, and finally the instance
converted to a string using the built-in function :func:`str`.
.. _tut-iterators:
Iterators
=========
By now you have probably noticed that most container objects can be looped over
using a :keyword:`for` statement::
for element in [1, 2, 3]:
print element
for element in (1, 2, 3):
print element
for key in {'one':1, 'two':2}:
print key
for char in "123":
print char
for line in open("myfile.txt"):
print line,
This style of access is clear, concise, and convenient. The use of iterators
pervades and unifies Python. Behind the scenes, the :keyword:`for` statement
calls :func:`iter` on the container object. The function returns an iterator
object that defines the method :meth:`~iterator.next` which accesses elements
in the container one at a time. When there are no more elements,
:meth:`~iterator.next` raises a :exc:`StopIteration` exception which tells the
:keyword:`for` loop to terminate.
This example shows how it all works::
>>> s = 'abc'
>>> it = iter(s)
>>> it
<iterator object at 0x00A1DB50>
>>> it.next()
'a'
>>> it.next()
'b'
>>> it.next()
'c'
>>> it.next()
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
it.next()
StopIteration
Having seen the mechanics behind the iterator protocol, it is easy to add
iterator behavior to your classes. Define an :meth:`__iter__` method which
returns an object with a :meth:`~iterator.next` method. If the class
defines :meth:`~iterator.next`, then :meth:`__iter__` can just return ``self``::
class Reverse:
"""Iterator for looping over a sequence backwards."""
def __init__(self, data):
self.data = data
self.index = len(data)
def __iter__(self):
return self
def next(self):
if self.index == 0:
raise StopIteration
self.index = self.index - 1
return self.data[self.index]
::
>>> rev = Reverse('spam')
>>> iter(rev)
<__main__.Reverse object at 0x00A1DB50>
>>> for char in rev:
... print char
...
m
a
p
s
.. _tut-generators:
Generators
==========
:term:`Generator`\s are a simple and powerful tool for creating iterators. They
are written like regular functions but use the :keyword:`yield` statement
whenever they want to return data. Each time :func:`next` is called on it, the
generator resumes where it left off (it remembers all the data values and which
statement was last executed). An example shows that generators can be trivially
easy to create::
def reverse(data):
for index in range(len(data)-1, -1, -1):
yield data[index]
::
>>> for char in reverse('golf'):
... print char
...
f
l
o
g
Anything that can be done with generators can also be done with class-based
iterators as described in the previous section. What makes generators so
compact is that the :meth:`__iter__` and :meth:`~generator.next` methods
are created automatically.
Another key feature is that the local variables and execution state are
automatically saved between calls. This made the function easier to write and
much more clear than an approach using instance variables like ``self.index``
and ``self.data``.
In addition to automatic method creation and saving program state, when
generators terminate, they automatically raise :exc:`StopIteration`. In
combination, these features make it easy to create iterators with no more effort
than writing a regular function.
.. _tut-genexps:
Generator Expressions
=====================
Some simple generators can be coded succinctly as expressions using a syntax
similar to list comprehensions but with parentheses instead of square brackets.
These expressions are designed for situations where the generator is used right
away by an enclosing function. Generator expressions are more compact but less
versatile than full generator definitions and tend to be more memory friendly
than equivalent list comprehensions.
Examples::
>>> sum(i*i for i in range(10)) # sum of squares
285
>>> xvec = [10, 20, 30]
>>> yvec = [7, 5, 3]
>>> sum(x*y for x,y in zip(xvec, yvec)) # dot product
260
>>> from math import pi, sin
>>> sine_table = dict((x, sin(x*pi/180)) for x in range(0, 91))
>>> unique_words = set(word for line in page for word in line.split())
>>> valedictorian = max((student.gpa, student.name) for student in graduates)
>>> data = 'golf'
>>> list(data[i] for i in range(len(data)-1,-1,-1))
['f', 'l', 'o', 'g']
.. rubric:: Footnotes
.. [#] Except for one thing. Module objects have a secret read-only attribute called
:attr:`~object.__dict__` which returns the dictionary used to implement the module's
namespace; the name :attr:`~object.__dict__` is an attribute but not a global name.
Obviously, using this violates the abstraction of namespace implementation, and
should be restricted to things like post-mortem debuggers.
PK
%�\�9'm�\ �\ * html/_sources/tutorial/controlflow.rst.txtnu �[��� .. _tut-morecontrol:
***********************
More Control Flow Tools
***********************
Besides the :keyword:`while` statement just introduced, Python knows the usual
control flow statements known from other languages, with some twists.
.. _tut-if:
:keyword:`if` Statements
========================
Perhaps the most well-known statement type is the :keyword:`if` statement. For
example::
>>> x = int(raw_input("Please enter an integer: "))
Please enter an integer: 42
>>> if x < 0:
... x = 0
... print 'Negative changed to zero'
... elif x == 0:
... print 'Zero'
... elif x == 1:
... print 'Single'
... else:
... print 'More'
...
More
There can be zero or more :keyword:`elif` parts, and the :keyword:`else` part is
optional. The keyword ':keyword:`elif`' is short for 'else if', and is useful
to avoid excessive indentation. An :keyword:`if` ... :keyword:`elif` ...
:keyword:`elif` ... sequence is a substitute for the ``switch`` or
``case`` statements found in other languages.
.. _tut-for:
:keyword:`for` Statements
=========================
.. index::
statement: for
statement: for
The :keyword:`for` statement in Python differs a bit from what you may be used
to in C or Pascal. Rather than always iterating over an arithmetic progression
of numbers (like in Pascal), or giving the user the ability to define both the
iteration step and halting condition (as C), Python's :keyword:`for` statement
iterates over the items of any sequence (a list or a string), in the order that
they appear in the sequence. For example (no pun intended):
.. One suggestion was to give a real C example here, but that may only serve to
confuse non-C programmers.
::
>>> # Measure some strings:
... words = ['cat', 'window', 'defenestrate']
>>> for w in words:
... print w, len(w)
...
cat 3
window 6
defenestrate 12
If you need to modify the sequence you are iterating over while inside the loop
(for example to duplicate selected items), it is recommended that you first
make a copy. Iterating over a sequence does not implicitly make a copy. The
slice notation makes this especially convenient::
>>> for w in words[:]: # Loop over a slice copy of the entire list.
... if len(w) > 6:
... words.insert(0, w)
...
>>> words
['defenestrate', 'cat', 'window', 'defenestrate']
.. _tut-range:
The :func:`range` Function
==========================
If you do need to iterate over a sequence of numbers, the built-in function
:func:`range` comes in handy. It generates lists containing arithmetic
progressions::
>>> range(10)
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
The given end point is never part of the generated list; ``range(10)`` generates
a list of 10 values, the legal indices for items of a sequence of length 10. It
is possible to let the range start at another number, or to specify a different
increment (even negative; sometimes this is called the 'step')::
>>> range(5, 10)
[5, 6, 7, 8, 9]
>>> range(0, 10, 3)
[0, 3, 6, 9]
>>> range(-10, -100, -30)
[-10, -40, -70]
To iterate over the indices of a sequence, you can combine :func:`range` and
:func:`len` as follows::
>>> a = ['Mary', 'had', 'a', 'little', 'lamb']
>>> for i in range(len(a)):
... print i, a[i]
...
0 Mary
1 had
2 a
3 little
4 lamb
In most such cases, however, it is convenient to use the :func:`enumerate`
function, see :ref:`tut-loopidioms`.
.. _tut-break:
:keyword:`break` and :keyword:`continue` Statements, and :keyword:`else` Clauses on Loops
=========================================================================================
The :keyword:`break` statement, like in C, breaks out of the innermost enclosing
:keyword:`for` or :keyword:`while` loop.
Loop statements may have an ``else`` clause; it is executed when the loop
terminates through exhaustion of the list (with :keyword:`for`) or when the
condition becomes false (with :keyword:`while`), but not when the loop is
terminated by a :keyword:`break` statement. This is exemplified by the
following loop, which searches for prime numbers::
>>> for n in range(2, 10):
... for x in range(2, n):
... if n % x == 0:
... print n, 'equals', x, '*', n/x
... break
... else:
... # loop fell through without finding a factor
... print n, 'is a prime number'
...
2 is a prime number
3 is a prime number
4 equals 2 * 2
5 is a prime number
6 equals 2 * 3
7 is a prime number
8 equals 2 * 4
9 equals 3 * 3
(Yes, this is the correct code. Look closely: the ``else`` clause belongs to
the :keyword:`for` loop, **not** the :keyword:`if` statement.)
When used with a loop, the ``else`` clause has more in common with the
``else`` clause of a :keyword:`try` statement than it does that of
:keyword:`if` statements: a :keyword:`try` statement's ``else`` clause runs
when no exception occurs, and a loop's ``else`` clause runs when no ``break``
occurs. For more on the :keyword:`try` statement and exceptions, see
:ref:`tut-handling`.
The :keyword:`continue` statement, also borrowed from C, continues with the next
iteration of the loop::
>>> for num in range(2, 10):
... if num % 2 == 0:
... print "Found an even number", num
... continue
... print "Found a number", num
Found an even number 2
Found a number 3
Found an even number 4
Found a number 5
Found an even number 6
Found a number 7
Found an even number 8
Found a number 9
.. _tut-pass:
:keyword:`pass` Statements
==========================
The :keyword:`pass` statement does nothing. It can be used when a statement is
required syntactically but the program requires no action. For example::
>>> while True:
... pass # Busy-wait for keyboard interrupt (Ctrl+C)
...
This is commonly used for creating minimal classes::
>>> class MyEmptyClass:
... pass
...
Another place :keyword:`pass` can be used is as a place-holder for a function or
conditional body when you are working on new code, allowing you to keep thinking
at a more abstract level. The :keyword:`pass` is silently ignored::
>>> def initlog(*args):
... pass # Remember to implement this!
...
.. _tut-functions:
Defining Functions
==================
We can create a function that writes the Fibonacci series to an arbitrary
boundary::
>>> def fib(n): # write Fibonacci series up to n
... """Print a Fibonacci series up to n."""
... a, b = 0, 1
... while a < n:
... print a,
... a, b = b, a+b
...
>>> # Now call the function we just defined:
... fib(2000)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597
.. index::
single: documentation strings
single: docstrings
single: strings, documentation
The keyword :keyword:`def` introduces a function *definition*. It must be
followed by the function name and the parenthesized list of formal parameters.
The statements that form the body of the function start at the next line, and
must be indented.
The first statement of the function body can optionally be a string literal;
this string literal is the function's documentation string, or :dfn:`docstring`.
(More about docstrings can be found in the section :ref:`tut-docstrings`.)
There are tools which use docstrings to automatically produce online or printed
documentation, or to let the user interactively browse through code; it's good
practice to include docstrings in code that you write, so make a habit of it.
The *execution* of a function introduces a new symbol table used for the local
variables of the function. More precisely, all variable assignments in a
function store the value in the local symbol table; whereas variable references
first look in the local symbol table, then in the local symbol tables of
enclosing functions, then in the global symbol table, and finally in the table
of built-in names. Thus, global variables cannot be directly assigned a value
within a function (unless named in a :keyword:`global` statement), although they
may be referenced.
The actual parameters (arguments) to a function call are introduced in the local
symbol table of the called function when it is called; thus, arguments are
passed using *call by value* (where the *value* is always an object *reference*,
not the value of the object). [#]_ When a function calls another function, a new
local symbol table is created for that call.
A function definition introduces the function name in the current symbol table.
The value of the function name has a type that is recognized by the interpreter
as a user-defined function. This value can be assigned to another name which
can then also be used as a function. This serves as a general renaming
mechanism::
>>> fib
<function fib at 10042ed0>
>>> f = fib
>>> f(100)
0 1 1 2 3 5 8 13 21 34 55 89
Coming from other languages, you might object that ``fib`` is not a function but
a procedure since it doesn't return a value. In fact, even functions without a
:keyword:`return` statement do return a value, albeit a rather boring one. This
value is called ``None`` (it's a built-in name). Writing the value ``None`` is
normally suppressed by the interpreter if it would be the only value written.
You can see it if you really want to using :keyword:`print`::
>>> fib(0)
>>> print fib(0)
None
It is simple to write a function that returns a list of the numbers of the
Fibonacci series, instead of printing it::
>>> def fib2(n): # return Fibonacci series up to n
... """Return a list containing the Fibonacci series up to n."""
... result = []
... a, b = 0, 1
... while a < n:
... result.append(a) # see below
... a, b = b, a+b
... return result
...
>>> f100 = fib2(100) # call it
>>> f100 # write the result
[0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]
This example, as usual, demonstrates some new Python features:
* The :keyword:`return` statement returns with a value from a function.
:keyword:`return` without an expression argument returns ``None``. Falling off
the end of a function also returns ``None``.
* The statement ``result.append(a)`` calls a *method* of the list object
``result``. A method is a function that 'belongs' to an object and is named
``obj.methodname``, where ``obj`` is some object (this may be an expression),
and ``methodname`` is the name of a method that is defined by the object's type.
Different types define different methods. Methods of different types may have
the same name without causing ambiguity. (It is possible to define your own
object types and methods, using *classes*, see :ref:`tut-classes`)
The method :meth:`append` shown in the example is defined for list objects; it
adds a new element at the end of the list. In this example it is equivalent to
``result = result + [a]``, but more efficient.
.. _tut-defining:
More on Defining Functions
==========================
It is also possible to define functions with a variable number of arguments.
There are three forms, which can be combined.
.. _tut-defaultargs:
Default Argument Values
-----------------------
The most useful form is to specify a default value for one or more arguments.
This creates a function that can be called with fewer arguments than it is
defined to allow. For example::
def ask_ok(prompt, retries=4, complaint='Yes or no, please!'):
while True:
ok = raw_input(prompt)
if ok in ('y', 'ye', 'yes'):
return True
if ok in ('n', 'no', 'nop', 'nope'):
return False
retries = retries - 1
if retries < 0:
raise IOError('refusenik user')
print complaint
This function can be called in several ways:
* giving only the mandatory argument:
``ask_ok('Do you really want to quit?')``
* giving one of the optional arguments:
``ask_ok('OK to overwrite the file?', 2)``
* or even giving all arguments:
``ask_ok('OK to overwrite the file?', 2, 'Come on, only yes or no!')``
This example also introduces the :keyword:`in` keyword. This tests whether or
not a sequence contains a certain value.
The default values are evaluated at the point of function definition in the
*defining* scope, so that ::
i = 5
def f(arg=i):
print arg
i = 6
f()
will print ``5``.
**Important warning:** The default value is evaluated only once. This makes a
difference when the default is a mutable object such as a list, dictionary, or
instances of most classes. For example, the following function accumulates the
arguments passed to it on subsequent calls::
def f(a, L=[]):
L.append(a)
return L
print f(1)
print f(2)
print f(3)
This will print ::
[1]
[1, 2]
[1, 2, 3]
If you don't want the default to be shared between subsequent calls, you can
write the function like this instead::
def f(a, L=None):
if L is None:
L = []
L.append(a)
return L
.. _tut-keywordargs:
Keyword Arguments
-----------------
Functions can also be called using :term:`keyword arguments <keyword argument>`
of the form ``kwarg=value``. For instance, the following function::
def parrot(voltage, state='a stiff', action='voom', type='Norwegian Blue'):
print "-- This parrot wouldn't", action,
print "if you put", voltage, "volts through it."
print "-- Lovely plumage, the", type
print "-- It's", state, "!"
accepts one required argument (``voltage``) and three optional arguments
(``state``, ``action``, and ``type``). This function can be called in any
of the following ways::
parrot(1000) # 1 positional argument
parrot(voltage=1000) # 1 keyword argument
parrot(voltage=1000000, action='VOOOOOM') # 2 keyword arguments
parrot(action='VOOOOOM', voltage=1000000) # 2 keyword arguments
parrot('a million', 'bereft of life', 'jump') # 3 positional arguments
parrot('a thousand', state='pushing up the daisies') # 1 positional, 1 keyword
but all the following calls would be invalid::
parrot() # required argument missing
parrot(voltage=5.0, 'dead') # non-keyword argument after a keyword argument
parrot(110, voltage=220) # duplicate value for the same argument
parrot(actor='John Cleese') # unknown keyword argument
In a function call, keyword arguments must follow positional arguments.
All the keyword arguments passed must match one of the arguments
accepted by the function (e.g. ``actor`` is not a valid argument for the
``parrot`` function), and their order is not important. This also includes
non-optional arguments (e.g. ``parrot(voltage=1000)`` is valid too).
No argument may receive a value more than once.
Here's an example that fails due to this restriction::
>>> def function(a):
... pass
...
>>> function(0, a=0)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: function() got multiple values for keyword argument 'a'
When a final formal parameter of the form ``**name`` is present, it receives a
dictionary (see :ref:`typesmapping`) containing all keyword arguments except for
those corresponding to a formal parameter. This may be combined with a formal
parameter of the form ``*name`` (described in the next subsection) which
receives a tuple containing the positional arguments beyond the formal parameter
list. (``*name`` must occur before ``**name``.) For example, if we define a
function like this::
def cheeseshop(kind, *arguments, **keywords):
print "-- Do you have any", kind, "?"
print "-- I'm sorry, we're all out of", kind
for arg in arguments:
print arg
print "-" * 40
keys = sorted(keywords.keys())
for kw in keys:
print kw, ":", keywords[kw]
It could be called like this::
cheeseshop("Limburger", "It's very runny, sir.",
"It's really very, VERY runny, sir.",
shopkeeper='Michael Palin',
client="John Cleese",
sketch="Cheese Shop Sketch")
and of course it would print:
.. code-block:: none
-- Do you have any Limburger ?
-- I'm sorry, we're all out of Limburger
It's very runny, sir.
It's really very, VERY runny, sir.
----------------------------------------
client : John Cleese
shopkeeper : Michael Palin
sketch : Cheese Shop Sketch
Note that the list of keyword argument names is created by sorting the result
of the keywords dictionary's ``keys()`` method before printing its contents;
if this is not done, the order in which the arguments are printed is undefined.
.. _tut-arbitraryargs:
Arbitrary Argument Lists
------------------------
.. index::
statement: *
Finally, the least frequently used option is to specify that a function can be
called with an arbitrary number of arguments. These arguments will be wrapped
up in a tuple (see :ref:`tut-tuples`). Before the variable number of arguments,
zero or more normal arguments may occur. ::
def write_multiple_items(file, separator, *args):
file.write(separator.join(args))
.. _tut-unpacking-arguments:
Unpacking Argument Lists
------------------------
The reverse situation occurs when the arguments are already in a list or tuple
but need to be unpacked for a function call requiring separate positional
arguments. For instance, the built-in :func:`range` function expects separate
*start* and *stop* arguments. If they are not available separately, write the
function call with the ``*``\ -operator to unpack the arguments out of a list
or tuple::
>>> range(3, 6) # normal call with separate arguments
[3, 4, 5]
>>> args = [3, 6]
>>> range(*args) # call with arguments unpacked from a list
[3, 4, 5]
.. index::
statement: **
In the same fashion, dictionaries can deliver keyword arguments with the ``**``\
-operator::
>>> def parrot(voltage, state='a stiff', action='voom'):
... print "-- This parrot wouldn't", action,
... print "if you put", voltage, "volts through it.",
... print "E's", state, "!"
...
>>> d = {"voltage": "four million", "state": "bleedin' demised", "action": "VOOM"}
>>> parrot(**d)
-- This parrot wouldn't VOOM if you put four million volts through it. E's bleedin' demised !
.. _tut-lambda:
Lambda Expressions
------------------
Small anonymous functions can be created with the :keyword:`lambda` keyword.
This function returns the sum of its two arguments: ``lambda a, b: a+b``.
Lambda functions can be used wherever function objects are required. They are
syntactically restricted to a single expression. Semantically, they are just
syntactic sugar for a normal function definition. Like nested function
definitions, lambda functions can reference variables from the containing
scope::
>>> def make_incrementor(n):
... return lambda x: x + n
...
>>> f = make_incrementor(42)
>>> f(0)
42
>>> f(1)
43
The above example uses a lambda expression to return a function. Another use
is to pass a small function as an argument::
>>> pairs = [(1, 'one'), (2, 'two'), (3, 'three'), (4, 'four')]
>>> pairs.sort(key=lambda pair: pair[1])
>>> pairs
[(4, 'four'), (1, 'one'), (3, 'three'), (2, 'two')]
.. _tut-docstrings:
Documentation Strings
---------------------
.. index::
single: docstrings
single: documentation strings
single: strings, documentation
There are emerging conventions about the content and formatting of documentation
strings.
The first line should always be a short, concise summary of the object's
purpose. For brevity, it should not explicitly state the object's name or type,
since these are available by other means (except if the name happens to be a
verb describing a function's operation). This line should begin with a capital
letter and end with a period.
If there are more lines in the documentation string, the second line should be
blank, visually separating the summary from the rest of the description. The
following lines should be one or more paragraphs describing the object's calling
conventions, its side effects, etc.
The Python parser does not strip indentation from multi-line string literals in
Python, so tools that process documentation have to strip indentation if
desired. This is done using the following convention. The first non-blank line
*after* the first line of the string determines the amount of indentation for
the entire documentation string. (We can't use the first line since it is
generally adjacent to the string's opening quotes so its indentation is not
apparent in the string literal.) Whitespace "equivalent" to this indentation is
then stripped from the start of all lines of the string. Lines that are
indented less should not occur, but if they occur all their leading whitespace
should be stripped. Equivalence of whitespace should be tested after expansion
of tabs (to 8 spaces, normally).
Here is an example of a multi-line docstring::
>>> def my_function():
... """Do nothing, but document it.
...
... No, really, it doesn't do anything.
... """
... pass
...
>>> print my_function.__doc__
Do nothing, but document it.
No, really, it doesn't do anything.
.. _tut-codingstyle:
Intermezzo: Coding Style
========================
.. sectionauthor:: Georg Brandl <georg@python.org>
.. index:: pair: coding; style
Now that you are about to write longer, more complex pieces of Python, it is a
good time to talk about *coding style*. Most languages can be written (or more
concise, *formatted*) in different styles; some are more readable than others.
Making it easy for others to read your code is always a good idea, and adopting
a nice coding style helps tremendously for that.
For Python, :pep:`8` has emerged as the style guide that most projects adhere to;
it promotes a very readable and eye-pleasing coding style. Every Python
developer should read it at some point; here are the most important points
extracted for you:
* Use 4-space indentation, and no tabs.
4 spaces are a good compromise between small indentation (allows greater
nesting depth) and large indentation (easier to read). Tabs introduce
confusion, and are best left out.
* Wrap lines so that they don't exceed 79 characters.
This helps users with small displays and makes it possible to have several
code files side-by-side on larger displays.
* Use blank lines to separate functions and classes, and larger blocks of
code inside functions.
* When possible, put comments on a line of their own.
* Use docstrings.
* Use spaces around operators and after commas, but not directly inside
bracketing constructs: ``a = f(1, 2) + g(3, 4)``.
* Name your classes and functions consistently; the convention is to use
``CamelCase`` for classes and ``lower_case_with_underscores`` for functions
and methods. Always use ``self`` as the name for the first method argument
(see :ref:`tut-firstclasses` for more on classes and methods).
* Don't use fancy encodings if your code is meant to be used in international
environments. Plain ASCII works best in any case.
.. rubric:: Footnotes
.. [#] Actually, *call by object reference* would be a better description,
since if a mutable object is passed, the caller will see any changes the
callee makes to it (items inserted into a list).
PK
%�\��ڷ�c �c - html/_sources/tutorial/datastructures.rst.txtnu �[��� .. _tut-structures:
***************
Data Structures
***************
This chapter describes some things you've learned about already in more detail,
and adds some new things as well.
.. _tut-morelists:
More on Lists
=============
The list data type has some more methods. Here are all of the methods of list
objects:
.. method:: list.append(x)
:noindex:
Add an item to the end of the list; equivalent to ``a[len(a):] = [x]``.
.. method:: list.extend(L)
:noindex:
Extend the list by appending all the items in the given list; equivalent to
``a[len(a):] = L``.
.. method:: list.insert(i, x)
:noindex:
Insert an item at a given position. The first argument is the index of the
element before which to insert, so ``a.insert(0, x)`` inserts at the front of
the list, and ``a.insert(len(a), x)`` is equivalent to ``a.append(x)``.
.. method:: list.remove(x)
:noindex:
Remove the first item from the list whose value is *x*. It is an error if there
is no such item.
.. method:: list.pop([i])
:noindex:
Remove the item at the given position in the list, and return it. If no index
is specified, ``a.pop()`` removes and returns the last item in the list. (The
square brackets around the *i* in the method signature denote that the parameter
is optional, not that you should type square brackets at that position. You
will see this notation frequently in the Python Library Reference.)
.. method:: list.index(x)
:noindex:
Return the index in the list of the first item whose value is *x*. It is an
error if there is no such item.
.. method:: list.count(x)
:noindex:
Return the number of times *x* appears in the list.
.. method:: list.sort(cmp=None, key=None, reverse=False)
:noindex:
Sort the items of the list in place (the arguments can be used for sort
customization, see :func:`sorted` for their explanation).
.. method:: list.reverse()
:noindex:
Reverse the elements of the list, in place.
An example that uses most of the list methods::
>>> a = [66.25, 333, 333, 1, 1234.5]
>>> print a.count(333), a.count(66.25), a.count('x')
2 1 0
>>> a.insert(2, -1)
>>> a.append(333)
>>> a
[66.25, 333, -1, 333, 1, 1234.5, 333]
>>> a.index(333)
1
>>> a.remove(333)
>>> a
[66.25, -1, 333, 1, 1234.5, 333]
>>> a.reverse()
>>> a
[333, 1234.5, 1, 333, -1, 66.25]
>>> a.sort()
>>> a
[-1, 1, 66.25, 333, 333, 1234.5]
>>> a.pop()
1234.5
>>> a
[-1, 1, 66.25, 333, 333]
You might have noticed that methods like ``insert``, ``remove`` or ``sort`` that
only modify the list have no return value printed -- they return the default
``None``. This is a design principle for all mutable data structures in
Python.
.. _tut-lists-as-stacks:
Using Lists as Stacks
---------------------
.. sectionauthor:: Ka-Ping Yee <ping@lfw.org>
The list methods make it very easy to use a list as a stack, where the last
element added is the first element retrieved ("last-in, first-out"). To add an
item to the top of the stack, use :meth:`append`. To retrieve an item from the
top of the stack, use :meth:`pop` without an explicit index. For example::
>>> stack = [3, 4, 5]
>>> stack.append(6)
>>> stack.append(7)
>>> stack
[3, 4, 5, 6, 7]
>>> stack.pop()
7
>>> stack
[3, 4, 5, 6]
>>> stack.pop()
6
>>> stack.pop()
5
>>> stack
[3, 4]
.. _tut-lists-as-queues:
Using Lists as Queues
---------------------
.. sectionauthor:: Ka-Ping Yee <ping@lfw.org>
It is also possible to use a list as a queue, where the first element added is
the first element retrieved ("first-in, first-out"); however, lists are not
efficient for this purpose. While appends and pops from the end of list are
fast, doing inserts or pops from the beginning of a list is slow (because all
of the other elements have to be shifted by one).
To implement a queue, use :class:`collections.deque` which was designed to
have fast appends and pops from both ends. For example::
>>> from collections import deque
>>> queue = deque(["Eric", "John", "Michael"])
>>> queue.append("Terry") # Terry arrives
>>> queue.append("Graham") # Graham arrives
>>> queue.popleft() # The first to arrive now leaves
'Eric'
>>> queue.popleft() # The second to arrive now leaves
'John'
>>> queue # Remaining queue in order of arrival
deque(['Michael', 'Terry', 'Graham'])
.. _tut-functional:
Functional Programming Tools
----------------------------
There are three built-in functions that are very useful when used with lists:
:func:`filter`, :func:`map`, and :func:`reduce`.
``filter(function, sequence)`` returns a sequence consisting of those items from
the sequence for which ``function(item)`` is true. If *sequence* is a
:class:`str`, :class:`unicode` or :class:`tuple`, the result will be of the
same type; otherwise, it is always a :class:`list`. For example, to compute a
sequence of numbers divisible by 3 or 5::
>>> def f(x): return x % 3 == 0 or x % 5 == 0
...
>>> filter(f, range(2, 25))
[3, 5, 6, 9, 10, 12, 15, 18, 20, 21, 24]
``map(function, sequence)`` calls ``function(item)`` for each of the sequence's
items and returns a list of the return values. For example, to compute some
cubes::
>>> def cube(x): return x*x*x
...
>>> map(cube, range(1, 11))
[1, 8, 27, 64, 125, 216, 343, 512, 729, 1000]
More than one sequence may be passed; the function must then have as many
arguments as there are sequences and is called with the corresponding item from
each sequence (or ``None`` if some sequence is shorter than another). For
example::
>>> seq = range(8)
>>> def add(x, y): return x+y
...
>>> map(add, seq, seq)
[0, 2, 4, 6, 8, 10, 12, 14]
``reduce(function, sequence)`` returns a single value constructed by calling the
binary function *function* on the first two items of the sequence, then on the
result and the next item, and so on. For example, to compute the sum of the
numbers 1 through 10::
>>> def add(x,y): return x+y
...
>>> reduce(add, range(1, 11))
55
If there's only one item in the sequence, its value is returned; if the sequence
is empty, an exception is raised.
A third argument can be passed to indicate the starting value. In this case the
starting value is returned for an empty sequence, and the function is first
applied to the starting value and the first sequence item, then to the result
and the next item, and so on. For example, ::
>>> def sum(seq):
... def add(x,y): return x+y
... return reduce(add, seq, 0)
...
>>> sum(range(1, 11))
55
>>> sum([])
0
Don't use this example's definition of :func:`sum`: since summing numbers is
such a common need, a built-in function ``sum(sequence)`` is already provided,
and works exactly like this.
.. _tut-listcomps:
List Comprehensions
-------------------
List comprehensions provide a concise way to create lists.
Common applications are to make new lists where each element is the result of
some operations applied to each member of another sequence or iterable, or to
create a subsequence of those elements that satisfy a certain condition.
For example, assume we want to create a list of squares, like::
>>> squares = []
>>> for x in range(10):
... squares.append(x**2)
...
>>> squares
[0, 1, 4, 9, 16, 25, 36, 49, 64, 81]
We can obtain the same result with::
squares = [x**2 for x in range(10)]
This is also equivalent to ``squares = map(lambda x: x**2, range(10))``,
but it's more concise and readable.
A list comprehension consists of brackets containing an expression followed
by a :keyword:`for` clause, then zero or more :keyword:`for` or :keyword:`if`
clauses. The result will be a new list resulting from evaluating the expression
in the context of the :keyword:`for` and :keyword:`if` clauses which follow it.
For example, this listcomp combines the elements of two lists if they are not
equal::
>>> [(x, y) for x in [1,2,3] for y in [3,1,4] if x != y]
[(1, 3), (1, 4), (2, 3), (2, 1), (2, 4), (3, 1), (3, 4)]
and it's equivalent to:
>>> combs = []
>>> for x in [1,2,3]:
... for y in [3,1,4]:
... if x != y:
... combs.append((x, y))
...
>>> combs
[(1, 3), (1, 4), (2, 3), (2, 1), (2, 4), (3, 1), (3, 4)]
Note how the order of the :keyword:`for` and :keyword:`if` statements is the
same in both these snippets.
If the expression is a tuple (e.g. the ``(x, y)`` in the previous example),
it must be parenthesized. ::
>>> vec = [-4, -2, 0, 2, 4]
>>> # create a new list with the values doubled
>>> [x*2 for x in vec]
[-8, -4, 0, 4, 8]
>>> # filter the list to exclude negative numbers
>>> [x for x in vec if x >= 0]
[0, 2, 4]
>>> # apply a function to all the elements
>>> [abs(x) for x in vec]
[4, 2, 0, 2, 4]
>>> # call a method on each element
>>> freshfruit = [' banana', ' loganberry ', 'passion fruit ']
>>> [weapon.strip() for weapon in freshfruit]
['banana', 'loganberry', 'passion fruit']
>>> # create a list of 2-tuples like (number, square)
>>> [(x, x**2) for x in range(6)]
[(0, 0), (1, 1), (2, 4), (3, 9), (4, 16), (5, 25)]
>>> # the tuple must be parenthesized, otherwise an error is raised
>>> [x, x**2 for x in range(6)]
File "<stdin>", line 1, in <module>
[x, x**2 for x in range(6)]
^
SyntaxError: invalid syntax
>>> # flatten a list using a listcomp with two 'for'
>>> vec = [[1,2,3], [4,5,6], [7,8,9]]
>>> [num for elem in vec for num in elem]
[1, 2, 3, 4, 5, 6, 7, 8, 9]
List comprehensions can contain complex expressions and nested functions::
>>> from math import pi
>>> [str(round(pi, i)) for i in range(1, 6)]
['3.1', '3.14', '3.142', '3.1416', '3.14159']
Nested List Comprehensions
''''''''''''''''''''''''''
The initial expression in a list comprehension can be any arbitrary expression,
including another list comprehension.
Consider the following example of a 3x4 matrix implemented as a list of
3 lists of length 4::
>>> matrix = [
... [1, 2, 3, 4],
... [5, 6, 7, 8],
... [9, 10, 11, 12],
... ]
The following list comprehension will transpose rows and columns::
>>> [[row[i] for row in matrix] for i in range(4)]
[[1, 5, 9], [2, 6, 10], [3, 7, 11], [4, 8, 12]]
As we saw in the previous section, the nested listcomp is evaluated in
the context of the :keyword:`for` that follows it, so this example is
equivalent to::
>>> transposed = []
>>> for i in range(4):
... transposed.append([row[i] for row in matrix])
...
>>> transposed
[[1, 5, 9], [2, 6, 10], [3, 7, 11], [4, 8, 12]]
which, in turn, is the same as::
>>> transposed = []
>>> for i in range(4):
... # the following 3 lines implement the nested listcomp
... transposed_row = []
... for row in matrix:
... transposed_row.append(row[i])
... transposed.append(transposed_row)
...
>>> transposed
[[1, 5, 9], [2, 6, 10], [3, 7, 11], [4, 8, 12]]
In the real world, you should prefer built-in functions to complex flow statements.
The :func:`zip` function would do a great job for this use case::
>>> zip(*matrix)
[(1, 5, 9), (2, 6, 10), (3, 7, 11), (4, 8, 12)]
See :ref:`tut-unpacking-arguments` for details on the asterisk in this line.
.. _tut-del:
The :keyword:`del` statement
============================
There is a way to remove an item from a list given its index instead of its
value: the :keyword:`del` statement. This differs from the :meth:`pop` method
which returns a value. The :keyword:`del` statement can also be used to remove
slices from a list or clear the entire list (which we did earlier by assignment
of an empty list to the slice). For example::
>>> a = [-1, 1, 66.25, 333, 333, 1234.5]
>>> del a[0]
>>> a
[1, 66.25, 333, 333, 1234.5]
>>> del a[2:4]
>>> a
[1, 66.25, 1234.5]
>>> del a[:]
>>> a
[]
:keyword:`del` can also be used to delete entire variables::
>>> del a
Referencing the name ``a`` hereafter is an error (at least until another value
is assigned to it). We'll find other uses for :keyword:`del` later.
.. _tut-tuples:
Tuples and Sequences
====================
We saw that lists and strings have many common properties, such as indexing and
slicing operations. They are two examples of *sequence* data types (see
:ref:`typesseq`). Since Python is an evolving language, other sequence data
types may be added. There is also another standard sequence data type: the
*tuple*.
A tuple consists of a number of values separated by commas, for instance::
>>> t = 12345, 54321, 'hello!'
>>> t[0]
12345
>>> t
(12345, 54321, 'hello!')
>>> # Tuples may be nested:
... u = t, (1, 2, 3, 4, 5)
>>> u
((12345, 54321, 'hello!'), (1, 2, 3, 4, 5))
>>> # Tuples are immutable:
... t[0] = 88888
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: 'tuple' object does not support item assignment
>>> # but they can contain mutable objects:
... v = ([1, 2, 3], [3, 2, 1])
>>> v
([1, 2, 3], [3, 2, 1])
As you see, on output tuples are always enclosed in parentheses, so that nested
tuples are interpreted correctly; they may be input with or without surrounding
parentheses, although often parentheses are necessary anyway (if the tuple is
part of a larger expression). It is not possible to assign to the individual
items of a tuple, however it is possible to create tuples which contain mutable
objects, such as lists.
Though tuples may seem similar to lists, they are often used in different
situations and for different purposes.
Tuples are :term:`immutable`, and usually contain a heterogeneous sequence of
elements that are accessed via unpacking (see later in this section) or indexing
(or even by attribute in the case of :func:`namedtuples <collections.namedtuple>`).
Lists are :term:`mutable`, and their elements are usually homogeneous and are
accessed by iterating over the list.
A special problem is the construction of tuples containing 0 or 1 items: the
syntax has some extra quirks to accommodate these. Empty tuples are constructed
by an empty pair of parentheses; a tuple with one item is constructed by
following a value with a comma (it is not sufficient to enclose a single value
in parentheses). Ugly, but effective. For example::
>>> empty = ()
>>> singleton = 'hello', # <-- note trailing comma
>>> len(empty)
0
>>> len(singleton)
1
>>> singleton
('hello',)
The statement ``t = 12345, 54321, 'hello!'`` is an example of *tuple packing*:
the values ``12345``, ``54321`` and ``'hello!'`` are packed together in a tuple.
The reverse operation is also possible::
>>> x, y, z = t
This is called, appropriately enough, *sequence unpacking* and works for any
sequence on the right-hand side. Sequence unpacking requires the list of
variables on the left to have the same number of elements as the length of the
sequence. Note that multiple assignment is really just a combination of tuple
packing and sequence unpacking.
.. _tut-sets:
Sets
====
Python also includes a data type for *sets*. A set is an unordered collection
with no duplicate elements. Basic uses include membership testing and
eliminating duplicate entries. Set objects also support mathematical operations
like union, intersection, difference, and symmetric difference.
Curly braces or the :func:`set` function can be used to create sets. Note: to
create an empty set you have to use ``set()``, not ``{}``; the latter creates an
empty dictionary, a data structure that we discuss in the next section.
Here is a brief demonstration::
>>> basket = ['apple', 'orange', 'apple', 'pear', 'orange', 'banana']
>>> fruit = set(basket) # create a set without duplicates
>>> fruit
set(['orange', 'pear', 'apple', 'banana'])
>>> 'orange' in fruit # fast membership testing
True
>>> 'crabgrass' in fruit
False
>>> # Demonstrate set operations on unique letters from two words
...
>>> a = set('abracadabra')
>>> b = set('alacazam')
>>> a # unique letters in a
set(['a', 'r', 'b', 'c', 'd'])
>>> a - b # letters in a but not in b
set(['r', 'd', 'b'])
>>> a | b # letters in either a or b
set(['a', 'c', 'r', 'd', 'b', 'm', 'z', 'l'])
>>> a & b # letters in both a and b
set(['a', 'c'])
>>> a ^ b # letters in a or b but not both
set(['r', 'd', 'b', 'm', 'z', 'l'])
Similarly to :ref:`list comprehensions <tut-listcomps>`, set comprehensions
are also supported::
>>> a = {x for x in 'abracadabra' if x not in 'abc'}
>>> a
set(['r', 'd'])
.. _tut-dictionaries:
Dictionaries
============
Another useful data type built into Python is the *dictionary* (see
:ref:`typesmapping`). Dictionaries are sometimes found in other languages as
"associative memories" or "associative arrays". Unlike sequences, which are
indexed by a range of numbers, dictionaries are indexed by *keys*, which can be
any immutable type; strings and numbers can always be keys. Tuples can be used
as keys if they contain only strings, numbers, or tuples; if a tuple contains
any mutable object either directly or indirectly, it cannot be used as a key.
You can't use lists as keys, since lists can be modified in place using index
assignments, slice assignments, or methods like :meth:`append` and
:meth:`extend`.
It is best to think of a dictionary as an unordered set of *key: value* pairs,
with the requirement that the keys are unique (within one dictionary). A pair of
braces creates an empty dictionary: ``{}``. Placing a comma-separated list of
key:value pairs within the braces adds initial key:value pairs to the
dictionary; this is also the way dictionaries are written on output.
The main operations on a dictionary are storing a value with some key and
extracting the value given the key. It is also possible to delete a key:value
pair with ``del``. If you store using a key that is already in use, the old
value associated with that key is forgotten. It is an error to extract a value
using a non-existent key.
The :meth:`keys` method of a dictionary object returns a list of all the keys
used in the dictionary, in arbitrary order (if you want it sorted, just apply
the :func:`sorted` function to it). To check whether a single key is in the
dictionary, use the :keyword:`in` keyword.
Here is a small example using a dictionary::
>>> tel = {'jack': 4098, 'sape': 4139}
>>> tel['guido'] = 4127
>>> tel
{'sape': 4139, 'guido': 4127, 'jack': 4098}
>>> tel['jack']
4098
>>> del tel['sape']
>>> tel['irv'] = 4127
>>> tel
{'guido': 4127, 'irv': 4127, 'jack': 4098}
>>> tel.keys()
['guido', 'irv', 'jack']
>>> 'guido' in tel
True
The :func:`dict` constructor builds dictionaries directly from sequences of
key-value pairs::
>>> dict([('sape', 4139), ('guido', 4127), ('jack', 4098)])
{'sape': 4139, 'jack': 4098, 'guido': 4127}
In addition, dict comprehensions can be used to create dictionaries from
arbitrary key and value expressions::
>>> {x: x**2 for x in (2, 4, 6)}
{2: 4, 4: 16, 6: 36}
When the keys are simple strings, it is sometimes easier to specify pairs using
keyword arguments::
>>> dict(sape=4139, guido=4127, jack=4098)
{'sape': 4139, 'jack': 4098, 'guido': 4127}
.. _tut-loopidioms:
Looping Techniques
==================
When looping through a sequence, the position index and corresponding value can
be retrieved at the same time using the :func:`enumerate` function. ::
>>> for i, v in enumerate(['tic', 'tac', 'toe']):
... print i, v
...
0 tic
1 tac
2 toe
To loop over two or more sequences at the same time, the entries can be paired
with the :func:`zip` function. ::
>>> questions = ['name', 'quest', 'favorite color']
>>> answers = ['lancelot', 'the holy grail', 'blue']
>>> for q, a in zip(questions, answers):
... print 'What is your {0}? It is {1}.'.format(q, a)
...
What is your name? It is lancelot.
What is your quest? It is the holy grail.
What is your favorite color? It is blue.
To loop over a sequence in reverse, first specify the sequence in a forward
direction and then call the :func:`reversed` function. ::
>>> for i in reversed(xrange(1,10,2)):
... print i
...
9
7
5
3
1
To loop over a sequence in sorted order, use the :func:`sorted` function which
returns a new sorted list while leaving the source unaltered. ::
>>> basket = ['apple', 'orange', 'apple', 'pear', 'orange', 'banana']
>>> for f in sorted(set(basket)):
... print f
...
apple
banana
orange
pear
When looping through dictionaries, the key and corresponding value can be
retrieved at the same time using the :meth:`iteritems` method. ::
>>> knights = {'gallahad': 'the pure', 'robin': 'the brave'}
>>> for k, v in knights.iteritems():
... print k, v
...
gallahad the pure
robin the brave
It is sometimes tempting to change a list while you are looping over it;
however, it is often simpler and safer to create a new list instead. ::
>>> import math
>>> raw_data = [56.2, float('NaN'), 51.7, 55.3, 52.5, float('NaN'), 47.8]
>>> filtered_data = []
>>> for value in raw_data:
... if not math.isnan(value):
... filtered_data.append(value)
...
>>> filtered_data
[56.2, 51.7, 55.3, 52.5, 47.8]
.. _tut-conditions:
More on Conditions
==================
The conditions used in ``while`` and ``if`` statements can contain any
operators, not just comparisons.
The comparison operators ``in`` and ``not in`` check whether a value occurs
(does not occur) in a sequence. The operators ``is`` and ``is not`` compare
whether two objects are really the same object; this only matters for mutable
objects like lists. All comparison operators have the same priority, which is
lower than that of all numerical operators.
Comparisons can be chained. For example, ``a < b == c`` tests whether ``a`` is
less than ``b`` and moreover ``b`` equals ``c``.
Comparisons may be combined using the Boolean operators ``and`` and ``or``, and
the outcome of a comparison (or of any other Boolean expression) may be negated
with ``not``. These have lower priorities than comparison operators; between
them, ``not`` has the highest priority and ``or`` the lowest, so that ``A and
not B or C`` is equivalent to ``(A and (not B)) or C``. As always, parentheses
can be used to express the desired composition.
The Boolean operators ``and`` and ``or`` are so-called *short-circuit*
operators: their arguments are evaluated from left to right, and evaluation
stops as soon as the outcome is determined. For example, if ``A`` and ``C`` are
true but ``B`` is false, ``A and B and C`` does not evaluate the expression
``C``. When used as a general value and not as a Boolean, the return value of a
short-circuit operator is the last evaluated argument.
It is possible to assign the result of a comparison or other Boolean expression
to a variable. For example, ::
>>> string1, string2, string3 = '', 'Trondheim', 'Hammer Dance'
>>> non_null = string1 or string2 or string3
>>> non_null
'Trondheim'
Note that in Python, unlike C, assignment cannot occur inside expressions. C
programmers may grumble about this, but it avoids a common class of problems
encountered in C programs: typing ``=`` in an expression when ``==`` was
intended.
.. _tut-comparing:
Comparing Sequences and Other Types
===================================
Sequence objects may be compared to other objects with the same sequence type.
The comparison uses *lexicographical* ordering: first the first two items are
compared, and if they differ this determines the outcome of the comparison; if
they are equal, the next two items are compared, and so on, until either
sequence is exhausted. If two items to be compared are themselves sequences of
the same type, the lexicographical comparison is carried out recursively. If
all items of two sequences compare equal, the sequences are considered equal.
If one sequence is an initial sub-sequence of the other, the shorter sequence is
the smaller (lesser) one. Lexicographical ordering for strings uses the ASCII
ordering for individual characters. Some examples of comparisons between
sequences of the same type::
(1, 2, 3) < (1, 2, 4)
[1, 2, 3] < [1, 2, 4]
'ABC' < 'C' < 'Pascal' < 'Python'
(1, 2, 3, 4) < (1, 2, 4)
(1, 2) < (1, 2, -1)
(1, 2, 3) == (1.0, 2.0, 3.0)
(1, 2, ('aa', 'ab')) < (1, 2, ('abc', 'a'), 4)
Note that comparing objects of different types is legal. The outcome is
deterministic but arbitrary: the types are ordered by their name. Thus, a list
is always smaller than a string, a string is always smaller than a tuple, etc.
[#]_ Mixed numeric types are compared according to their numeric value, so 0
equals 0.0, etc.
.. rubric:: Footnotes
.. [#] The rules for comparing objects of different types should not be relied upon;
they may change in a future version of the language.
PK
%�\?po��; �; % html/_sources/tutorial/errors.rst.txtnu �[��� .. _tut-errors:
*********************
Errors and Exceptions
*********************
Until now error messages haven't been more than mentioned, but if you have tried
out the examples you have probably seen some. There are (at least) two
distinguishable kinds of errors: *syntax errors* and *exceptions*.
.. _tut-syntaxerrors:
Syntax Errors
=============
Syntax errors, also known as parsing errors, are perhaps the most common kind of
complaint you get while you are still learning Python::
>>> while True print 'Hello world'
File "<stdin>", line 1
while True print 'Hello world'
^
SyntaxError: invalid syntax
The parser repeats the offending line and displays a little 'arrow' pointing at
the earliest point in the line where the error was detected. The error is
caused by (or at least detected at) the token *preceding* the arrow: in the
example, the error is detected at the keyword :keyword:`print`, since a colon
(``':'``) is missing before it. File name and line number are printed so you
know where to look in case the input came from a script.
.. _tut-exceptions:
Exceptions
==========
Even if a statement or expression is syntactically correct, it may cause an
error when an attempt is made to execute it. Errors detected during execution
are called *exceptions* and are not unconditionally fatal: you will soon learn
how to handle them in Python programs. Most exceptions are not handled by
programs, however, and result in error messages as shown here::
>>> 10 * (1/0)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ZeroDivisionError: integer division or modulo by zero
>>> 4 + spam*3
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
NameError: name 'spam' is not defined
>>> '2' + 2
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: cannot concatenate 'str' and 'int' objects
The last line of the error message indicates what happened. Exceptions come in
different types, and the type is printed as part of the message: the types in
the example are :exc:`ZeroDivisionError`, :exc:`NameError` and :exc:`TypeError`.
The string printed as the exception type is the name of the built-in exception
that occurred. This is true for all built-in exceptions, but need not be true
for user-defined exceptions (although it is a useful convention). Standard
exception names are built-in identifiers (not reserved keywords).
The rest of the line provides detail based on the type of exception and what
caused it.
The preceding part of the error message shows the context where the exception
happened, in the form of a stack traceback. In general it contains a stack
traceback listing source lines; however, it will not display lines read from
standard input.
:ref:`bltin-exceptions` lists the built-in exceptions and their meanings.
.. _tut-handling:
Handling Exceptions
===================
It is possible to write programs that handle selected exceptions. Look at the
following example, which asks the user for input until a valid integer has been
entered, but allows the user to interrupt the program (using :kbd:`Control-C` or
whatever the operating system supports); note that a user-generated interruption
is signalled by raising the :exc:`KeyboardInterrupt` exception. ::
>>> while True:
... try:
... x = int(raw_input("Please enter a number: "))
... break
... except ValueError:
... print "Oops! That was no valid number. Try again..."
...
The :keyword:`try` statement works as follows.
* First, the *try clause* (the statement(s) between the :keyword:`try` and
:keyword:`except` keywords) is executed.
* If no exception occurs, the *except clause* is skipped and execution of the
:keyword:`try` statement is finished.
* If an exception occurs during execution of the try clause, the rest of the
clause is skipped. Then if its type matches the exception named after the
:keyword:`except` keyword, the except clause is executed, and then execution
continues after the :keyword:`try` statement.
* If an exception occurs which does not match the exception named in the except
clause, it is passed on to outer :keyword:`try` statements; if no handler is
found, it is an *unhandled exception* and execution stops with a message as
shown above.
A :keyword:`try` statement may have more than one except clause, to specify
handlers for different exceptions. At most one handler will be executed.
Handlers only handle exceptions that occur in the corresponding try clause, not
in other handlers of the same :keyword:`try` statement. An except clause may
name multiple exceptions as a parenthesized tuple, for example::
... except (RuntimeError, TypeError, NameError):
... pass
Note that the parentheses around this tuple are required, because
``except ValueError, e:`` was the syntax used for what is normally
written as ``except ValueError as e:`` in modern Python (described
below). The old syntax is still supported for backwards compatibility.
This means ``except RuntimeError, TypeError`` is not equivalent to
``except (RuntimeError, TypeError):`` but to ``except RuntimeError as
TypeError:`` which is not what you want.
The last except clause may omit the exception name(s), to serve as a wildcard.
Use this with extreme caution, since it is easy to mask a real programming error
in this way! It can also be used to print an error message and then re-raise
the exception (allowing a caller to handle the exception as well)::
import sys
try:
f = open('myfile.txt')
s = f.readline()
i = int(s.strip())
except IOError as e:
print "I/O error({0}): {1}".format(e.errno, e.strerror)
except ValueError:
print "Could not convert data to an integer."
except:
print "Unexpected error:", sys.exc_info()[0]
raise
The :keyword:`try` ... :keyword:`except` statement has an optional *else
clause*, which, when present, must follow all except clauses. It is useful for
code that must be executed if the try clause does not raise an exception. For
example::
for arg in sys.argv[1:]:
try:
f = open(arg, 'r')
except IOError:
print 'cannot open', arg
else:
print arg, 'has', len(f.readlines()), 'lines'
f.close()
The use of the :keyword:`else` clause is better than adding additional code to
the :keyword:`try` clause because it avoids accidentally catching an exception
that wasn't raised by the code being protected by the :keyword:`try` ...
:keyword:`except` statement.
When an exception occurs, it may have an associated value, also known as the
exception's *argument*. The presence and type of the argument depend on the
exception type.
The except clause may specify a variable after the exception name (or tuple).
The variable is bound to an exception instance with the arguments stored in
``instance.args``. For convenience, the exception instance defines
:meth:`__str__` so the arguments can be printed directly without having to
reference ``.args``.
One may also instantiate an exception first before raising it and add any
attributes to it as desired. ::
>>> try:
... raise Exception('spam', 'eggs')
... except Exception as inst:
... print type(inst) # the exception instance
... print inst.args # arguments stored in .args
... print inst # __str__ allows args to be printed directly
... x, y = inst.args
... print 'x =', x
... print 'y =', y
...
<type 'exceptions.Exception'>
('spam', 'eggs')
('spam', 'eggs')
x = spam
y = eggs
If an exception has an argument, it is printed as the last part ('detail') of
the message for unhandled exceptions.
Exception handlers don't just handle exceptions if they occur immediately in the
try clause, but also if they occur inside functions that are called (even
indirectly) in the try clause. For example::
>>> def this_fails():
... x = 1/0
...
>>> try:
... this_fails()
... except ZeroDivisionError as detail:
... print 'Handling run-time error:', detail
...
Handling run-time error: integer division or modulo by zero
.. _tut-raising:
Raising Exceptions
==================
The :keyword:`raise` statement allows the programmer to force a specified
exception to occur. For example::
>>> raise NameError('HiThere')
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
NameError: HiThere
The sole argument to :keyword:`raise` indicates the exception to be raised.
This must be either an exception instance or an exception class (a class that
derives from :class:`Exception`).
If you need to determine whether an exception was raised but don't intend to
handle it, a simpler form of the :keyword:`raise` statement allows you to
re-raise the exception::
>>> try:
... raise NameError('HiThere')
... except NameError:
... print 'An exception flew by!'
... raise
...
An exception flew by!
Traceback (most recent call last):
File "<stdin>", line 2, in <module>
NameError: HiThere
.. _tut-userexceptions:
User-defined Exceptions
=======================
Programs may name their own exceptions by creating a new exception class (see
:ref:`tut-classes` for more about Python classes). Exceptions should typically
be derived from the :exc:`Exception` class, either directly or indirectly. For
example::
>>> class MyError(Exception):
... def __init__(self, value):
... self.value = value
... def __str__(self):
... return repr(self.value)
...
>>> try:
... raise MyError(2*2)
... except MyError as e:
... print 'My exception occurred, value:', e.value
...
My exception occurred, value: 4
>>> raise MyError('oops!')
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
__main__.MyError: 'oops!'
In this example, the default :meth:`__init__` of :class:`Exception` has been
overridden. The new behavior simply creates the *value* attribute. This
replaces the default behavior of creating the *args* attribute.
Exception classes can be defined which do anything any other class can do, but
are usually kept simple, often only offering a number of attributes that allow
information about the error to be extracted by handlers for the exception. When
creating a module that can raise several distinct errors, a common practice is
to create a base class for exceptions defined by that module, and subclass that
to create specific exception classes for different error conditions::
class Error(Exception):
"""Base class for exceptions in this module."""
pass
class InputError(Error):
"""Exception raised for errors in the input.
Attributes:
expr -- input expression in which the error occurred
msg -- explanation of the error
"""
def __init__(self, expr, msg):
self.expr = expr
self.msg = msg
class TransitionError(Error):
"""Raised when an operation attempts a state transition that's not
allowed.
Attributes:
prev -- state at beginning of transition
next -- attempted new state
msg -- explanation of why the specific transition is not allowed
"""
def __init__(self, prev, next, msg):
self.prev = prev
self.next = next
self.msg = msg
Most exceptions are defined with names that end in "Error", similar to the
naming of the standard exceptions.
Many standard modules define their own exceptions to report errors that may
occur in functions they define. More information on classes is presented in
chapter :ref:`tut-classes`.
.. _tut-cleanup:
Defining Clean-up Actions
=========================
The :keyword:`try` statement has another optional clause which is intended to
define clean-up actions that must be executed under all circumstances. For
example::
>>> try:
... raise KeyboardInterrupt
... finally:
... print 'Goodbye, world!'
...
Goodbye, world!
Traceback (most recent call last):
File "<stdin>", line 2, in <module>
KeyboardInterrupt
A *finally clause* is always executed before leaving the :keyword:`try`
statement, whether an exception has occurred or not. When an exception has
occurred in the :keyword:`try` clause and has not been handled by an
:keyword:`except` clause (or it has occurred in an :keyword:`except` or
:keyword:`else` clause), it is re-raised after the :keyword:`finally` clause has
been executed. The :keyword:`finally` clause is also executed "on the way out"
when any other clause of the :keyword:`try` statement is left via a
:keyword:`break`, :keyword:`continue` or :keyword:`return` statement. A more
complicated example (having :keyword:`except` and :keyword:`finally` clauses in
the same :keyword:`try` statement works as of Python 2.5)::
>>> def divide(x, y):
... try:
... result = x / y
... except ZeroDivisionError:
... print "division by zero!"
... else:
... print "result is", result
... finally:
... print "executing finally clause"
...
>>> divide(2, 1)
result is 2
executing finally clause
>>> divide(2, 0)
division by zero!
executing finally clause
>>> divide("2", "1")
executing finally clause
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "<stdin>", line 3, in divide
TypeError: unsupported operand type(s) for /: 'str' and 'str'
As you can see, the :keyword:`finally` clause is executed in any event. The
:exc:`TypeError` raised by dividing two strings is not handled by the
:keyword:`except` clause and therefore re-raised after the :keyword:`finally`
clause has been executed.
In real world applications, the :keyword:`finally` clause is useful for
releasing external resources (such as files or network connections), regardless
of whether the use of the resource was successful.
.. _tut-cleanup-with:
Predefined Clean-up Actions
===========================
Some objects define standard clean-up actions to be undertaken when the object
is no longer needed, regardless of whether or not the operation using the object
succeeded or failed. Look at the following example, which tries to open a file
and print its contents to the screen. ::
for line in open("myfile.txt"):
print line,
The problem with this code is that it leaves the file open for an indeterminate
amount of time after the code has finished executing. This is not an issue in
simple scripts, but can be a problem for larger applications. The
:keyword:`with` statement allows objects like files to be used in a way that
ensures they are always cleaned up promptly and correctly. ::
with open("myfile.txt") as f:
for line in f:
print line,
After the statement is executed, the file *f* is always closed, even if a
problem was encountered while processing the lines. Other objects which provide
predefined clean-up actions will indicate this in their documentation.
PK
%�\�Egm! ! , html/_sources/tutorial/floatingpoint.rst.txtnu �[��� .. _tut-fp-issues:
**************************************************
Floating Point Arithmetic: Issues and Limitations
**************************************************
.. sectionauthor:: Tim Peters <tim_one@users.sourceforge.net>
Floating-point numbers are represented in computer hardware as base 2 (binary)
fractions. For example, the decimal fraction ::
0.125
has value 1/10 + 2/100 + 5/1000, and in the same way the binary fraction ::
0.001
has value 0/2 + 0/4 + 1/8. These two fractions have identical values, the only
real difference being that the first is written in base 10 fractional notation,
and the second in base 2.
Unfortunately, most decimal fractions cannot be represented exactly as binary
fractions. A consequence is that, in general, the decimal floating-point
numbers you enter are only approximated by the binary floating-point numbers
actually stored in the machine.
The problem is easier to understand at first in base 10. Consider the fraction
1/3. You can approximate that as a base 10 fraction::
0.3
or, better, ::
0.33
or, better, ::
0.333
and so on. No matter how many digits you're willing to write down, the result
will never be exactly 1/3, but will be an increasingly better approximation of
1/3.
In the same way, no matter how many base 2 digits you're willing to use, the
decimal value 0.1 cannot be represented exactly as a base 2 fraction. In base
2, 1/10 is the infinitely repeating fraction ::
0.0001100110011001100110011001100110011001100110011...
Stop at any finite number of bits, and you get an approximation.
On a typical machine running Python, there are 53 bits of precision available
for a Python float, so the value stored internally when you enter the decimal
number ``0.1`` is the binary fraction ::
0.00011001100110011001100110011001100110011001100110011010
which is close to, but not exactly equal to, 1/10.
It's easy to forget that the stored value is an approximation to the original
decimal fraction, because of the way that floats are displayed at the
interpreter prompt. Python only prints a decimal approximation to the true
decimal value of the binary approximation stored by the machine. If Python
were to print the true decimal value of the binary approximation stored for
0.1, it would have to display ::
>>> 0.1
0.1000000000000000055511151231257827021181583404541015625
That is more digits than most people find useful, so Python keeps the number
of digits manageable by displaying a rounded value instead ::
>>> 0.1
0.1
It's important to realize that this is, in a real sense, an illusion: the value
in the machine is not exactly 1/10, you're simply rounding the *display* of the
true machine value. This fact becomes apparent as soon as you try to do
arithmetic with these values ::
>>> 0.1 + 0.2
0.30000000000000004
Note that this is in the very nature of binary floating-point: this is not a
bug in Python, and it is not a bug in your code either. You'll see the same
kind of thing in all languages that support your hardware's floating-point
arithmetic (although some languages may not *display* the difference by
default, or in all output modes).
Other surprises follow from this one. For example, if you try to round the
value 2.675 to two decimal places, you get this ::
>>> round(2.675, 2)
2.67
The documentation for the built-in :func:`round` function says that it rounds
to the nearest value, rounding ties away from zero. Since the decimal fraction
2.675 is exactly halfway between 2.67 and 2.68, you might expect the result
here to be (a binary approximation to) 2.68. It's not, because when the
decimal string ``2.675`` is converted to a binary floating-point number, it's
again replaced with a binary approximation, whose exact value is ::
2.67499999999999982236431605997495353221893310546875
Since this approximation is slightly closer to 2.67 than to 2.68, it's rounded
down.
If you're in a situation where you care which way your decimal halfway-cases
are rounded, you should consider using the :mod:`decimal` module.
Incidentally, the :mod:`decimal` module also provides a nice way to "see" the
exact value that's stored in any particular Python float ::
>>> from decimal import Decimal
>>> Decimal(2.675)
Decimal('2.67499999999999982236431605997495353221893310546875')
Another consequence is that since 0.1 is not exactly 1/10, summing ten values
of 0.1 may not yield exactly 1.0, either::
>>> sum = 0.0
>>> for i in range(10):
... sum += 0.1
...
>>> sum
0.9999999999999999
Binary floating-point arithmetic holds many surprises like this. The problem
with "0.1" is explained in precise detail below, in the "Representation Error"
section. See `The Perils of Floating Point <http://www.lahey.com/float.htm>`_
for a more complete account of other common surprises.
As that says near the end, "there are no easy answers." Still, don't be unduly
wary of floating-point! The errors in Python float operations are inherited
from the floating-point hardware, and on most machines are on the order of no
more than 1 part in 2\*\*53 per operation. That's more than adequate for most
tasks, but you do need to keep in mind that it's not decimal arithmetic, and
that every float operation can suffer a new rounding error.
While pathological cases do exist, for most casual use of floating-point
arithmetic you'll see the result you expect in the end if you simply round the
display of your final results to the number of decimal digits you expect. For
fine control over how a float is displayed see the :meth:`str.format` method's
format specifiers in :ref:`formatstrings`.
.. _tut-fp-error:
Representation Error
====================
This section explains the "0.1" example in detail, and shows how you can
perform an exact analysis of cases like this yourself. Basic familiarity with
binary floating-point representation is assumed.
:dfn:`Representation error` refers to the fact that some (most, actually)
decimal fractions cannot be represented exactly as binary (base 2) fractions.
This is the chief reason why Python (or Perl, C, C++, Java, Fortran, and many
others) often won't display the exact decimal number you expect::
>>> 0.1 + 0.2
0.30000000000000004
Why is that? 1/10 and 2/10 are not exactly representable as a binary
fraction. Almost all machines today (July 2010) use IEEE-754 floating point
arithmetic, and almost all platforms map Python floats to IEEE-754 "double
precision". 754 doubles contain 53 bits of precision, so on input the computer
strives to convert 0.1 to the closest fraction it can of the form *J*/2**\ *N*
where *J* is an integer containing exactly 53 bits. Rewriting ::
1 / 10 ~= J / (2**N)
as ::
J ~= 2**N / 10
and recalling that *J* has exactly 53 bits (is ``>= 2**52`` but ``< 2**53``),
the best value for *N* is 56::
>>> 2**52
4503599627370496
>>> 2**53
9007199254740992
>>> 2**56/10
7205759403792793
That is, 56 is the only value for *N* that leaves *J* with exactly 53 bits.
The best possible value for *J* is then that quotient rounded::
>>> q, r = divmod(2**56, 10)
>>> r
6
Since the remainder is more than half of 10, the best approximation is obtained
by rounding up::
>>> q+1
7205759403792794
Therefore the best possible approximation to 1/10 in 754 double precision is
that over 2\*\*56, or ::
7205759403792794 / 72057594037927936
Note that since we rounded up, this is actually a little bit larger than 1/10;
if we had not rounded up, the quotient would have been a little bit smaller
than 1/10. But in no case can it be *exactly* 1/10!
So the computer never "sees" 1/10: what it sees is the exact fraction given
above, the best 754 double approximation it can get::
>>> .1 * 2**56
7205759403792794.0
If we multiply that fraction by 10\*\*30, we can see the (truncated) value of
its 30 most significant decimal digits::
>>> 7205759403792794 * 10**30 // 2**56
100000000000000005551115123125L
meaning that the exact number stored in the computer is approximately equal to
the decimal value 0.100000000000000005551115123125. In versions prior to
Python 2.7 and Python 3.1, Python rounded this value to 17 significant digits,
giving '0.10000000000000001'. In current versions, Python displays a value
based on the shortest decimal fraction that rounds correctly back to the true
binary value, resulting simply in '0.1'.
PK
%�\Kͧ�F F $ html/_sources/tutorial/index.rst.txtnu �[��� .. _tutorial-index:
######################
The Python Tutorial
######################
Python is an easy to learn, powerful programming language. It has efficient
high-level data structures and a simple but effective approach to
object-oriented programming. Python's elegant syntax and dynamic typing,
together with its interpreted nature, make it an ideal language for scripting
and rapid application development in many areas on most platforms.
The Python interpreter and the extensive standard library are freely available
in source or binary form for all major platforms from the Python Web site,
https://www.python.org/, and may be freely distributed. The same site also
contains distributions of and pointers to many free third party Python modules,
programs and tools, and additional documentation.
The Python interpreter is easily extended with new functions and data types
implemented in C or C++ (or other languages callable from C). Python is also
suitable as an extension language for customizable applications.
This tutorial introduces the reader informally to the basic concepts and
features of the Python language and system. It helps to have a Python
interpreter handy for hands-on experience, but all examples are self-contained,
so the tutorial can be read off-line as well.
For a description of standard objects and modules, see :ref:`library-index`.
:ref:`reference-index` gives a more formal definition of the language. To write
extensions in C or C++, read :ref:`extending-index` and
:ref:`c-api-index`. There are also several books covering Python in depth.
This tutorial does not attempt to be comprehensive and cover every single
feature, or even every commonly used feature. Instead, it introduces many of
Python's most noteworthy features, and will give you a good idea of the
language's flavor and style. After reading it, you will be able to read and
write Python modules and programs, and you will be ready to learn more about the
various Python library modules described in :ref:`library-index`.
The :ref:`glossary` is also worth going through.
.. toctree::
:numbered:
appetite.rst
interpreter.rst
introduction.rst
controlflow.rst
datastructures.rst
modules.rst
inputoutput.rst
errors.rst
classes.rst
stdlib.rst
stdlib2.rst
whatnow.rst
interactive.rst
floatingpoint.rst
appendix.rst
PK
%�\��> �> * html/_sources/tutorial/inputoutput.rst.txtnu �[��� .. _tut-io:
****************
Input and Output
****************
There are several ways to present the output of a program; data can be printed
in a human-readable form, or written to a file for future use. This chapter will
discuss some of the possibilities.
.. _tut-formatting:
Fancier Output Formatting
=========================
So far we've encountered two ways of writing values: *expression statements* and
the :keyword:`print` statement. (A third way is using the :meth:`write` method
of file objects; the standard output file can be referenced as ``sys.stdout``.
See the Library Reference for more information on this.)
Often you'll want more control over the formatting of your output than simply
printing space-separated values. There are two ways to format your output; the
first way is to do all the string handling yourself; using string slicing and
concatenation operations you can create any layout you can imagine. The
string types have some methods that perform useful operations for padding
strings to a given column width; these will be discussed shortly. The second
way is to use the :meth:`str.format` method.
The :mod:`string` module contains a :class:`~string.Template` class which offers
yet another way to substitute values into strings.
One question remains, of course: how do you convert values to strings? Luckily,
Python has ways to convert any value to a string: pass it to the :func:`repr`
or :func:`str` functions.
The :func:`str` function is meant to return representations of values which are
fairly human-readable, while :func:`repr` is meant to generate representations
which can be read by the interpreter (or will force a :exc:`SyntaxError` if
there is no equivalent syntax). For objects which don't have a particular
representation for human consumption, :func:`str` will return the same value as
:func:`repr`. Many values, such as numbers or structures like lists and
dictionaries, have the same representation using either function. Strings and
floating point numbers, in particular, have two distinct representations.
Some examples::
>>> s = 'Hello, world.'
>>> str(s)
'Hello, world.'
>>> repr(s)
"'Hello, world.'"
>>> str(1.0/7.0)
'0.142857142857'
>>> repr(1.0/7.0)
'0.14285714285714285'
>>> x = 10 * 3.25
>>> y = 200 * 200
>>> s = 'The value of x is ' + repr(x) + ', and y is ' + repr(y) + '...'
>>> print s
The value of x is 32.5, and y is 40000...
>>> # The repr() of a string adds string quotes and backslashes:
... hello = 'hello, world\n'
>>> hellos = repr(hello)
>>> print hellos
'hello, world\n'
>>> # The argument to repr() may be any Python object:
... repr((x, y, ('spam', 'eggs')))
"(32.5, 40000, ('spam', 'eggs'))"
Here are two ways to write a table of squares and cubes::
>>> for x in range(1, 11):
... print repr(x).rjust(2), repr(x*x).rjust(3),
... # Note trailing comma on previous line
... print repr(x*x*x).rjust(4)
...
1 1 1
2 4 8
3 9 27
4 16 64
5 25 125
6 36 216
7 49 343
8 64 512
9 81 729
10 100 1000
>>> for x in range(1,11):
... print '{0:2d} {1:3d} {2:4d}'.format(x, x*x, x*x*x)
...
1 1 1
2 4 8
3 9 27
4 16 64
5 25 125
6 36 216
7 49 343
8 64 512
9 81 729
10 100 1000
(Note that in the first example, one space between each column was added by the
way :keyword:`print` works: by default it adds spaces between its arguments.)
This example demonstrates the :meth:`str.rjust` method of string
objects, which right-justifies a string in a field of a given width by padding
it with spaces on the left. There are similar methods :meth:`str.ljust` and
:meth:`str.center`. These methods do not write anything, they just return a
new string. If the input string is too long, they don't truncate it, but
return it unchanged; this will mess up your column lay-out but that's usually
better than the alternative, which would be lying about a value. (If you
really want truncation you can always add a slice operation, as in
``x.ljust(n)[:n]``.)
There is another method, :meth:`str.zfill`, which pads a numeric string on the
left with zeros. It understands about plus and minus signs::
>>> '12'.zfill(5)
'00012'
>>> '-3.14'.zfill(7)
'-003.14'
>>> '3.14159265359'.zfill(5)
'3.14159265359'
Basic usage of the :meth:`str.format` method looks like this::
>>> print 'We are the {} who say "{}!"'.format('knights', 'Ni')
We are the knights who say "Ni!"
The brackets and characters within them (called format fields) are replaced with
the objects passed into the :meth:`str.format` method. A number in the
brackets refers to the position of the object passed into the
:meth:`str.format` method. ::
>>> print '{0} and {1}'.format('spam', 'eggs')
spam and eggs
>>> print '{1} and {0}'.format('spam', 'eggs')
eggs and spam
If keyword arguments are used in the :meth:`str.format` method, their values
are referred to by using the name of the argument. ::
>>> print 'This {food} is {adjective}.'.format(
... food='spam', adjective='absolutely horrible')
This spam is absolutely horrible.
Positional and keyword arguments can be arbitrarily combined::
>>> print 'The story of {0}, {1}, and {other}.'.format('Bill', 'Manfred',
... other='Georg')
The story of Bill, Manfred, and Georg.
``'!s'`` (apply :func:`str`) and ``'!r'`` (apply :func:`repr`) can be used to
convert the value before it is formatted. ::
>>> import math
>>> print 'The value of PI is approximately {}.'.format(math.pi)
The value of PI is approximately 3.14159265359.
>>> print 'The value of PI is approximately {!r}.'.format(math.pi)
The value of PI is approximately 3.141592653589793.
An optional ``':'`` and format specifier can follow the field name. This allows
greater control over how the value is formatted. The following example
rounds Pi to three places after the decimal.
>>> import math
>>> print 'The value of PI is approximately {0:.3f}.'.format(math.pi)
The value of PI is approximately 3.142.
Passing an integer after the ``':'`` will cause that field to be a minimum
number of characters wide. This is useful for making tables pretty. ::
>>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 7678}
>>> for name, phone in table.items():
... print '{0:10} ==> {1:10d}'.format(name, phone)
...
Jack ==> 4098
Dcab ==> 7678
Sjoerd ==> 4127
If you have a really long format string that you don't want to split up, it
would be nice if you could reference the variables to be formatted by name
instead of by position. This can be done by simply passing the dict and using
square brackets ``'[]'`` to access the keys ::
>>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
>>> print ('Jack: {0[Jack]:d}; Sjoerd: {0[Sjoerd]:d}; '
... 'Dcab: {0[Dcab]:d}'.format(table))
Jack: 4098; Sjoerd: 4127; Dcab: 8637678
This could also be done by passing the table as keyword arguments with the '**'
notation. ::
>>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
>>> print 'Jack: {Jack:d}; Sjoerd: {Sjoerd:d}; Dcab: {Dcab:d}'.format(**table)
Jack: 4098; Sjoerd: 4127; Dcab: 8637678
This is particularly useful in combination with the built-in function
:func:`vars`, which returns a dictionary containing all local variables.
For a complete overview of string formatting with :meth:`str.format`, see
:ref:`formatstrings`.
Old string formatting
---------------------
The ``%`` operator can also be used for string formatting. It interprets the
left argument much like a :c:func:`sprintf`\ -style format string to be applied
to the right argument, and returns the string resulting from this formatting
operation. For example::
>>> import math
>>> print 'The value of PI is approximately %5.3f.' % math.pi
The value of PI is approximately 3.142.
More information can be found in the :ref:`string-formatting` section.
.. _tut-files:
Reading and Writing Files
=========================
.. index::
builtin: open
object: file
:func:`open` returns a file object, and is most commonly used with two
arguments: ``open(filename, mode)``.
::
>>> f = open('workfile', 'w')
>>> print f
<open file 'workfile', mode 'w' at 80a0960>
The first argument is a string containing the filename. The second argument is
another string containing a few characters describing the way in which the file
will be used. *mode* can be ``'r'`` when the file will only be read, ``'w'``
for only writing (an existing file with the same name will be erased), and
``'a'`` opens the file for appending; any data written to the file is
automatically added to the end. ``'r+'`` opens the file for both reading and
writing. The *mode* argument is optional; ``'r'`` will be assumed if it's
omitted.
On Windows, ``'b'`` appended to the mode opens the file in binary mode, so there
are also modes like ``'rb'``, ``'wb'``, and ``'r+b'``. Python on Windows makes
a distinction between text and binary files; the end-of-line characters in text
files are automatically altered slightly when data is read or written. This
behind-the-scenes modification to file data is fine for ASCII text files, but
it'll corrupt binary data like that in :file:`JPEG` or :file:`EXE` files. Be
very careful to use binary mode when reading and writing such files. On Unix,
it doesn't hurt to append a ``'b'`` to the mode, so you can use it
platform-independently for all binary files.
.. _tut-filemethods:
Methods of File Objects
-----------------------
The rest of the examples in this section will assume that a file object called
``f`` has already been created.
To read a file's contents, call ``f.read(size)``, which reads some quantity of
data and returns it as a string. *size* is an optional numeric argument. When
*size* is omitted or negative, the entire contents of the file will be read and
returned; it's your problem if the file is twice as large as your machine's
memory. Otherwise, at most *size* bytes are read and returned. If the end of
the file has been reached, ``f.read()`` will return an empty string (``""``).
::
>>> f.read()
'This is the entire file.\n'
>>> f.read()
''
``f.readline()`` reads a single line from the file; a newline character (``\n``)
is left at the end of the string, and is only omitted on the last line of the
file if the file doesn't end in a newline. This makes the return value
unambiguous; if ``f.readline()`` returns an empty string, the end of the file
has been reached, while a blank line is represented by ``'\n'``, a string
containing only a single newline. ::
>>> f.readline()
'This is the first line of the file.\n'
>>> f.readline()
'Second line of the file\n'
>>> f.readline()
''
For reading lines from a file, you can loop over the file object. This is memory
efficient, fast, and leads to simple code::
>>> for line in f:
print line,
This is the first line of the file.
Second line of the file
If you want to read all the lines of a file in a list you can also use
``list(f)`` or ``f.readlines()``.
``f.write(string)`` writes the contents of *string* to the file, returning
``None``. ::
>>> f.write('This is a test\n')
To write something other than a string, it needs to be converted to a string
first::
>>> value = ('the answer', 42)
>>> s = str(value)
>>> f.write(s)
``f.tell()`` returns an integer giving the file object's current position in the
file, measured in bytes from the beginning of the file. To change the file
object's position, use ``f.seek(offset, from_what)``. The position is computed
from adding *offset* to a reference point; the reference point is selected by
the *from_what* argument. A *from_what* value of 0 measures from the beginning
of the file, 1 uses the current file position, and 2 uses the end of the file as
the reference point. *from_what* can be omitted and defaults to 0, using the
beginning of the file as the reference point. ::
>>> f = open('workfile', 'r+')
>>> f.write('0123456789abcdef')
>>> f.seek(5) # Go to the 6th byte in the file
>>> f.read(1)
'5'
>>> f.seek(-3, 2) # Go to the 3rd byte before the end
>>> f.read(1)
'd'
When you're done with a file, call ``f.close()`` to close it and free up any
system resources taken up by the open file. After calling ``f.close()``,
attempts to use the file object will automatically fail. ::
>>> f.close()
>>> f.read()
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ValueError: I/O operation on closed file
It is good practice to use the :keyword:`with` keyword when dealing with file
objects. This has the advantage that the file is properly closed after its
suite finishes, even if an exception is raised on the way. It is also much
shorter than writing equivalent :keyword:`try`\ -\ :keyword:`finally` blocks::
>>> with open('workfile', 'r') as f:
... read_data = f.read()
>>> f.closed
True
File objects have some additional methods, such as :meth:`~file.isatty` and
:meth:`~file.truncate` which are less frequently used; consult the Library
Reference for a complete guide to file objects.
.. _tut-json:
Saving structured data with :mod:`json`
---------------------------------------
.. index:: module: json
Strings can easily be written to and read from a file. Numbers take a bit more
effort, since the :meth:`read` method only returns strings, which will have to
be passed to a function like :func:`int`, which takes a string like ``'123'``
and returns its numeric value 123. When you want to save more complex data
types like nested lists and dictionaries, parsing and serializing by hand
becomes complicated.
Rather than having users constantly writing and debugging code to save
complicated data types to files, Python allows you to use the popular data
interchange format called `JSON (JavaScript Object Notation)
<http://json.org>`_. The standard module called :mod:`json` can take Python
data hierarchies, and convert them to string representations; this process is
called :dfn:`serializing`. Reconstructing the data from the string representation
is called :dfn:`deserializing`. Between serializing and deserializing, the
string representing the object may have been stored in a file or data, or
sent over a network connection to some distant machine.
.. note::
The JSON format is commonly used by modern applications to allow for data
exchange. Many programmers are already familiar with it, which makes
it a good choice for interoperability.
If you have an object ``x``, you can view its JSON string representation with a
simple line of code::
>>> import json
>>> json.dumps([1, 'simple', 'list'])
'[1, "simple", "list"]'
Another variant of the :func:`~json.dumps` function, called :func:`~json.dump`,
simply serializes the object to a file. So if ``f`` is a :term:`file object`
opened for writing, we can do this::
json.dump(x, f)
To decode the object again, if ``f`` is a :term:`file object` which has
been opened for reading::
x = json.load(f)
This simple serialization technique can handle lists and dictionaries, but
serializing arbitrary class instances in JSON requires a bit of extra effort.
The reference for the :mod:`json` module contains an explanation of this.
.. seealso::
:mod:`pickle` - the pickle module
Contrary to :ref:`JSON <tut-json>`, *pickle* is a protocol which allows
the serialization of arbitrarily complex Python objects. As such, it is
specific to Python and cannot be used to communicate with applications
written in other languages. It is also insecure by default:
deserializing pickle data coming from an untrusted source can execute
arbitrary code, if the data was crafted by a skilled attacker.
PK
%�\A��)_ _ * html/_sources/tutorial/interactive.rst.txtnu �[��� .. _tut-interacting:
**************************************************
Interactive Input Editing and History Substitution
**************************************************
Some versions of the Python interpreter support editing of the current input
line and history substitution, similar to facilities found in the Korn shell and
the GNU Bash shell. This is implemented using the `GNU Readline`_ library,
which supports Emacs-style and vi-style editing. This library has its own
documentation which I won't duplicate here; however, the basics are easily
explained. The interactive editing and history described here are optionally
available in the Unix and Cygwin versions of the interpreter.
This chapter does *not* document the editing facilities of Mark Hammond's
PythonWin package or the Tk-based environment, IDLE, distributed with Python.
The command line history recall which operates within DOS boxes on NT and some
other DOS and Windows flavors is yet another beast.
.. _tut-lineediting:
Line Editing
============
If supported, input line editing is active whenever the interpreter prints a
primary or secondary prompt. The current line can be edited using the
conventional Emacs control characters. The most important of these are:
:kbd:`C-A` (Control-A) moves the cursor to the beginning of the line, :kbd:`C-E`
to the end, :kbd:`C-B` moves it one position to the left, :kbd:`C-F` to the
right. Backspace erases the character to the left of the cursor, :kbd:`C-D` the
character to its right. :kbd:`C-K` kills (erases) the rest of the line to the
right of the cursor, :kbd:`C-Y` yanks back the last killed string.
:kbd:`C-underscore` undoes the last change you made; it can be repeated for
cumulative effect.
.. _tut-history:
History Substitution
====================
History substitution works as follows. All non-empty input lines issued are
saved in a history buffer, and when a new prompt is given you are positioned on
a new line at the bottom of this buffer. :kbd:`C-P` moves one line up (back) in
the history buffer, :kbd:`C-N` moves one down. Any line in the history buffer
can be edited; an asterisk appears in front of the prompt to mark a line as
modified. Pressing the :kbd:`Return` key passes the current line to the
interpreter. :kbd:`C-R` starts an incremental reverse search; :kbd:`C-S` starts
a forward search.
.. _tut-keybindings:
Key Bindings
============
The key bindings and some other parameters of the Readline library can be
customized by placing commands in an initialization file called
:file:`~/.inputrc`. Key bindings have the form ::
key-name: function-name
or ::
"string": function-name
and options can be set with ::
set option-name value
For example::
# I prefer vi-style editing:
set editing-mode vi
# Edit using a single line:
set horizontal-scroll-mode On
# Rebind some keys:
Meta-h: backward-kill-word
"\C-u": universal-argument
"\C-x\C-r": re-read-init-file
Note that the default binding for :kbd:`Tab` in Python is to insert a :kbd:`Tab`
character instead of Readline's default filename completion function. If you
insist, you can override this by putting ::
Tab: complete
in your :file:`~/.inputrc`. (Of course, this makes it harder to type indented
continuation lines if you're accustomed to using :kbd:`Tab` for that purpose.)
.. index::
module: rlcompleter
module: readline
Automatic completion of variable and module names is optionally available. To
enable it in the interpreter's interactive mode, add the following to your
startup file: [#]_ ::
import rlcompleter, readline
readline.parse_and_bind('tab: complete')
This binds the :kbd:`Tab` key to the completion function, so hitting the
:kbd:`Tab` key twice suggests completions; it looks at Python statement names,
the current local variables, and the available module names. For dotted
expressions such as ``string.a``, it will evaluate the expression up to the
final ``'.'`` and then suggest completions from the attributes of the resulting
object. Note that this may execute application-defined code if an object with a
:meth:`__getattr__` method is part of the expression.
A more capable startup file might look like this example. Note that this
deletes the names it creates once they are no longer needed; this is done since
the startup file is executed in the same namespace as the interactive commands,
and removing the names avoids creating side effects in the interactive
environment. You may find it convenient to keep some of the imported modules,
such as :mod:`os`, which turn out to be needed in most sessions with the
interpreter. ::
# Add auto-completion and a stored history file of commands to your Python
# interactive interpreter. Requires Python 2.0+, readline. Autocomplete is
# bound to the Esc key by default (you can change it - see readline docs).
#
# Store the file in ~/.pystartup, and set an environment variable to point
# to it: "export PYTHONSTARTUP=~/.pystartup" in bash.
import atexit
import os
import readline
import rlcompleter
historyPath = os.path.expanduser("~/.pyhistory")
def save_history(historyPath=historyPath):
import readline
readline.write_history_file(historyPath)
if os.path.exists(historyPath):
readline.read_history_file(historyPath)
atexit.register(save_history)
del os, atexit, readline, rlcompleter, save_history, historyPath
.. _tut-commentary:
Alternatives to the Interactive Interpreter
===========================================
This facility is an enormous step forward compared to earlier versions of the
interpreter; however, some wishes are left: It would be nice if the proper
indentation were suggested on continuation lines (the parser knows if an indent
token is required next). The completion mechanism might use the interpreter's
symbol table. A command to check (or even suggest) matching parentheses,
quotes, etc., would also be useful.
One alternative enhanced interactive interpreter that has been around for quite
some time is IPython_, which features tab completion, object exploration and
advanced history management. It can also be thoroughly customized and embedded
into other applications. Another similar enhanced interactive environment is
bpython_.
.. rubric:: Footnotes
.. [#] Python will execute the contents of a file identified by the
:envvar:`PYTHONSTARTUP` environment variable when you start an interactive
interpreter. To customize Python even for non-interactive mode, see
:ref:`tut-customize`.
.. _GNU Readline: https://tiswww.case.edu/php/chet/readline/rltop.html
.. _IPython: http://ipython.scipy.org/
.. _bpython: http://www.bpython-interpreter.org/
PK
%�\�~+� � * html/_sources/tutorial/interpreter.rst.txtnu �[��� .. _tut-using:
****************************
Using the Python Interpreter
****************************
.. _tut-invoking:
Invoking the Interpreter
========================
The Python interpreter is usually installed as :file:`/usr/local/bin/python` on
those machines where it is available; putting :file:`/usr/local/bin` in your
Unix shell's search path makes it possible to start it by typing the command ::
python
to the shell. Since the choice of the directory where the interpreter lives is
an installation option, other places are possible; check with your local Python
guru or system administrator. (E.g., :file:`/usr/local/python` is a popular
alternative location.)
On Windows machines, the Python installation is usually placed in
:file:`C:\\Python27`, though you can change this when you're running the
installer. To add this directory to your path, you can type the following
command into the command prompt in a DOS box::
set path=%path%;C:\python27
Typing an end-of-file character (:kbd:`Control-D` on Unix, :kbd:`Control-Z` on
Windows) at the primary prompt causes the interpreter to exit with a zero exit
status. If that doesn't work, you can exit the interpreter by typing the
following command: ``quit()``.
The interpreter's line-editing features usually aren't very sophisticated. On
Unix, whoever installed the interpreter may have enabled support for the GNU
readline library, which adds more elaborate interactive editing and history
features. Perhaps the quickest check to see whether command line editing is
supported is typing :kbd:`Control-P` to the first Python prompt you get. If it beeps,
you have command line editing; see Appendix :ref:`tut-interacting` for an
introduction to the keys. If nothing appears to happen, or if ``^P`` is echoed,
command line editing isn't available; you'll only be able to use backspace to
remove characters from the current line.
The interpreter operates somewhat like the Unix shell: when called with standard
input connected to a tty device, it reads and executes commands interactively;
when called with a file name argument or with a file as standard input, it reads
and executes a *script* from that file.
A second way of starting the interpreter is ``python -c command [arg] ...``,
which executes the statement(s) in *command*, analogous to the shell's
:option:`-c` option. Since Python statements often contain spaces or other
characters that are special to the shell, it is usually advised to quote
*command* in its entirety with single quotes.
Some Python modules are also useful as scripts. These can be invoked using
``python -m module [arg] ...``, which executes the source file for *module* as
if you had spelled out its full name on the command line.
When a script file is used, it is sometimes useful to be able to run the script
and enter interactive mode afterwards. This can be done by passing :option:`-i`
before the script.
All command-line options are described in :ref:`using-on-general`.
.. _tut-argpassing:
Argument Passing
----------------
When known to the interpreter, the script name and additional arguments
thereafter are turned into a list of strings and assigned to the ``argv``
variable in the ``sys`` module. You can access this list by executing ``import
sys``. The length of the list is at least one; when no script and no arguments
are given, ``sys.argv[0]`` is an empty string. When the script name is given as
``'-'`` (meaning standard input), ``sys.argv[0]`` is set to ``'-'``. When
:option:`-c` *command* is used, ``sys.argv[0]`` is set to ``'-c'``. When
:option:`-m` *module* is used, ``sys.argv[0]`` is set to the full name of the
located module. Options found after :option:`-c` *command* or :option:`-m`
*module* are not consumed by the Python interpreter's option processing but
left in ``sys.argv`` for the command or module to handle.
.. _tut-interactive:
Interactive Mode
----------------
When commands are read from a tty, the interpreter is said to be in *interactive
mode*. In this mode it prompts for the next command with the *primary prompt*,
usually three greater-than signs (``>>>``); for continuation lines it prompts
with the *secondary prompt*, by default three dots (``...``). The interpreter
prints a welcome message stating its version number and a copyright notice
before printing the first prompt:
.. code-block:: shell-session
python
Python 2.7 (#1, Feb 28 2010, 00:02:06)
Type "help", "copyright", "credits" or "license" for more information.
>>>
Continuation lines are needed when entering a multi-line construct. As an
example, take a look at this :keyword:`if` statement::
>>> the_world_is_flat = 1
>>> if the_world_is_flat:
... print "Be careful not to fall off!"
...
Be careful not to fall off!
For more on interactive mode, see :ref:`tut-interac`.
.. _tut-interp:
The Interpreter and Its Environment
===================================
.. _tut-source-encoding:
Source Code Encoding
--------------------
By default, Python source files are treated as encoded in ASCII.
To declare an encoding other than the default one, a special comment line
should be added as the *first* line of the file. The syntax is as follows::
# -*- coding: encoding -*-
where *encoding* is one of the valid :mod:`codecs` supported by Python.
For example, to declare that Windows-1252 encoding is to be used, the first
line of your source code file should be::
# -*- coding: cp1252 -*-
One exception to the *first line* rule is when the source code starts with a
:ref:`UNIX "shebang" line <tut-scripts>`. In this case, the encoding
declaration should be added as the second line of the file. For example::
#!/usr/bin/env python
# -*- coding: cp1252 -*-
PK
%�\g�J�OU OU + html/_sources/tutorial/introduction.rst.txtnu �[��� .. _tut-informal:
**********************************
An Informal Introduction to Python
**********************************
In the following examples, input and output are distinguished by the presence or
absence of prompts (:term:`>>>` and :term:`...`): to repeat the example, you must type
everything after the prompt, when the prompt appears; lines that do not begin
with a prompt are output from the interpreter. Note that a secondary prompt on a
line by itself in an example means you must type a blank line; this is used to
end a multi-line command.
Many of the examples in this manual, even those entered at the interactive
prompt, include comments. Comments in Python start with the hash character,
``#``, and extend to the end of the physical line. A comment may appear at the
start of a line or following whitespace or code, but not within a string
literal. A hash character within a string literal is just a hash character.
Since comments are to clarify code and are not interpreted by Python, they may
be omitted when typing in examples.
Some examples::
# this is the first comment
spam = 1 # and this is the second comment
# ... and now a third!
text = "# This is not a comment because it's inside quotes."
.. _tut-calculator:
Using Python as a Calculator
============================
Let's try some simple Python commands. Start the interpreter and wait for the
primary prompt, ``>>>``. (It shouldn't take long.)
.. _tut-numbers:
Numbers
-------
The interpreter acts as a simple calculator: you can type an expression at it
and it will write the value. Expression syntax is straightforward: the
operators ``+``, ``-``, ``*`` and ``/`` work just like in most other languages
(for example, Pascal or C); parentheses (``()``) can be used for grouping.
For example::
>>> 2 + 2
4
>>> 50 - 5*6
20
>>> (50 - 5.0*6) / 4
5.0
>>> 8 / 5.0
1.6
The integer numbers (e.g. ``2``, ``4``, ``20``) have type :class:`int`,
the ones with a fractional part (e.g. ``5.0``, ``1.6``) have type
:class:`float`. We will see more about numeric types later in the tutorial.
The return type of a division (``/``) operation depends on its operands. If
both operands are of type :class:`int`, :term:`floor division` is performed
and an :class:`int` is returned. If either operand is a :class:`float`,
classic division is performed and a :class:`float` is returned. The ``//``
operator is also provided for doing floor division no matter what the
operands are. The remainder can be calculated with the ``%`` operator::
>>> 17 / 3 # int / int -> int
5
>>> 17 / 3.0 # int / float -> float
5.666666666666667
>>> 17 // 3.0 # explicit floor division discards the fractional part
5.0
>>> 17 % 3 # the % operator returns the remainder of the division
2
>>> 5 * 3 + 2 # result * divisor + remainder
17
With Python, it is possible to use the ``**`` operator to calculate powers [#]_::
>>> 5 ** 2 # 5 squared
25
>>> 2 ** 7 # 2 to the power of 7
128
The equal sign (``=``) is used to assign a value to a variable. Afterwards, no
result is displayed before the next interactive prompt::
>>> width = 20
>>> height = 5 * 9
>>> width * height
900
If a variable is not "defined" (assigned a value), trying to use it will
give you an error::
>>> n # try to access an undefined variable
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
NameError: name 'n' is not defined
There is full support for floating point; operators with mixed type operands
convert the integer operand to floating point::
>>> 3 * 3.75 / 1.5
7.5
>>> 7.0 / 2
3.5
In interactive mode, the last printed expression is assigned to the variable
``_``. This means that when you are using Python as a desk calculator, it is
somewhat easier to continue calculations, for example::
>>> tax = 12.5 / 100
>>> price = 100.50
>>> price * tax
12.5625
>>> price + _
113.0625
>>> round(_, 2)
113.06
This variable should be treated as read-only by the user. Don't explicitly
assign a value to it --- you would create an independent local variable with the
same name masking the built-in variable with its magic behavior.
In addition to :class:`int` and :class:`float`, Python supports other types of
numbers, such as :class:`~decimal.Decimal` and :class:`~fractions.Fraction`.
Python also has built-in support for :ref:`complex numbers <typesnumeric>`,
and uses the ``j`` or ``J`` suffix to indicate the imaginary part
(e.g. ``3+5j``).
.. _tut-strings:
Strings
-------
Besides numbers, Python can also manipulate strings, which can be expressed
in several ways. They can be enclosed in single quotes (``'...'``) or
double quotes (``"..."``) with the same result [#]_. ``\`` can be used
to escape quotes::
>>> 'spam eggs' # single quotes
'spam eggs'
>>> 'doesn\'t' # use \' to escape the single quote...
"doesn't"
>>> "doesn't" # ...or use double quotes instead
"doesn't"
>>> '"Yes," they said.'
'"Yes," they said.'
>>> "\"Yes,\" they said."
'"Yes," they said.'
>>> '"Isn\'t," they said.'
'"Isn\'t," they said.'
In the interactive interpreter, the output string is enclosed in quotes and
special characters are escaped with backslashes. While this might sometimes
look different from the input (the enclosing quotes could change), the two
strings are equivalent. The string is enclosed in double quotes if
the string contains a single quote and no double quotes, otherwise it is
enclosed in single quotes. The :keyword:`print` statement produces a more
readable output, by omitting the enclosing quotes and by printing escaped
and special characters::
>>> '"Isn\'t," they said.'
'"Isn\'t," they said.'
>>> print '"Isn\'t," they said.'
"Isn't," they said.
>>> s = 'First line.\nSecond line.' # \n means newline
>>> s # without print, \n is included in the output
'First line.\nSecond line.'
>>> print s # with print, \n produces a new line
First line.
Second line.
If you don't want characters prefaced by ``\`` to be interpreted as
special characters, you can use *raw strings* by adding an ``r`` before
the first quote::
>>> print 'C:\some\name' # here \n means newline!
C:\some
ame
>>> print r'C:\some\name' # note the r before the quote
C:\some\name
String literals can span multiple lines. One way is using triple-quotes:
``"""..."""`` or ``'''...'''``. End of lines are automatically
included in the string, but it's possible to prevent this by adding a ``\`` at
the end of the line. The following example::
print """\
Usage: thingy [OPTIONS]
-h Display this usage message
-H hostname Hostname to connect to
"""
produces the following output (note that the initial newline is not included):
.. code-block:: text
Usage: thingy [OPTIONS]
-h Display this usage message
-H hostname Hostname to connect to
Strings can be concatenated (glued together) with the ``+`` operator, and
repeated with ``*``::
>>> # 3 times 'un', followed by 'ium'
>>> 3 * 'un' + 'ium'
'unununium'
Two or more *string literals* (i.e. the ones enclosed between quotes) next
to each other are automatically concatenated. ::
>>> 'Py' 'thon'
'Python'
This feature is particularly useful when you want to break long strings::
>>> text = ('Put several strings within parentheses '
... 'to have them joined together.')
>>> text
'Put several strings within parentheses to have them joined together.'
This only works with two literals though, not with variables or expressions::
>>> prefix = 'Py'
>>> prefix 'thon' # can't concatenate a variable and a string literal
...
SyntaxError: invalid syntax
>>> ('un' * 3) 'ium'
...
SyntaxError: invalid syntax
If you want to concatenate variables or a variable and a literal, use ``+``::
>>> prefix + 'thon'
'Python'
Strings can be *indexed* (subscripted), with the first character having index 0.
There is no separate character type; a character is simply a string of size
one::
>>> word = 'Python'
>>> word[0] # character in position 0
'P'
>>> word[5] # character in position 5
'n'
Indices may also be negative numbers, to start counting from the right::
>>> word[-1] # last character
'n'
>>> word[-2] # second-last character
'o'
>>> word[-6]
'P'
Note that since -0 is the same as 0, negative indices start from -1.
In addition to indexing, *slicing* is also supported. While indexing is used
to obtain individual characters, *slicing* allows you to obtain a substring::
>>> word[0:2] # characters from position 0 (included) to 2 (excluded)
'Py'
>>> word[2:5] # characters from position 2 (included) to 5 (excluded)
'tho'
Note how the start is always included, and the end always excluded. This
makes sure that ``s[:i] + s[i:]`` is always equal to ``s``::
>>> word[:2] + word[2:]
'Python'
>>> word[:4] + word[4:]
'Python'
Slice indices have useful defaults; an omitted first index defaults to zero, an
omitted second index defaults to the size of the string being sliced. ::
>>> word[:2] # character from the beginning to position 2 (excluded)
'Py'
>>> word[4:] # characters from position 4 (included) to the end
'on'
>>> word[-2:] # characters from the second-last (included) to the end
'on'
One way to remember how slices work is to think of the indices as pointing
*between* characters, with the left edge of the first character numbered 0.
Then the right edge of the last character of a string of *n* characters has
index *n*, for example::
+---+---+---+---+---+---+
| P | y | t | h | o | n |
+---+---+---+---+---+---+
0 1 2 3 4 5 6
-6 -5 -4 -3 -2 -1
The first row of numbers gives the position of the indices 0...6 in the string;
the second row gives the corresponding negative indices. The slice from *i* to
*j* consists of all characters between the edges labeled *i* and *j*,
respectively.
For non-negative indices, the length of a slice is the difference of the
indices, if both are within bounds. For example, the length of ``word[1:3]`` is
2.
Attempting to use an index that is too large will result in an error::
>>> word[42] # the word only has 6 characters
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
IndexError: string index out of range
However, out of range slice indexes are handled gracefully when used for
slicing::
>>> word[4:42]
'on'
>>> word[42:]
''
Python strings cannot be changed --- they are :term:`immutable`.
Therefore, assigning to an indexed position in the string results in an error::
>>> word[0] = 'J'
...
TypeError: 'str' object does not support item assignment
>>> word[2:] = 'py'
...
TypeError: 'str' object does not support item assignment
If you need a different string, you should create a new one::
>>> 'J' + word[1:]
'Jython'
>>> word[:2] + 'py'
'Pypy'
The built-in function :func:`len` returns the length of a string::
>>> s = 'supercalifragilisticexpialidocious'
>>> len(s)
34
.. seealso::
:ref:`typesseq`
Strings, and the Unicode strings described in the next section, are
examples of *sequence types*, and support the common operations supported
by such types.
:ref:`string-methods`
Both strings and Unicode strings support a large number of methods for
basic transformations and searching.
:ref:`formatstrings`
Information about string formatting with :meth:`str.format`.
:ref:`string-formatting`
The old formatting operations invoked when strings and Unicode strings are
the left operand of the ``%`` operator are described in more detail here.
.. _tut-unicodestrings:
Unicode Strings
---------------
.. sectionauthor:: Marc-Andre Lemburg <mal@lemburg.com>
Starting with Python 2.0 a new data type for storing text data is available to
the programmer: the Unicode object. It can be used to store and manipulate
Unicode data (see http://www.unicode.org/) and integrates well with the existing
string objects, providing auto-conversions where necessary.
Unicode has the advantage of providing one ordinal for every character in every
script used in modern and ancient texts. Previously, there were only 256
possible ordinals for script characters. Texts were typically bound to a code
page which mapped the ordinals to script characters. This lead to very much
confusion especially with respect to internationalization (usually written as
``i18n`` --- ``'i'`` + 18 characters + ``'n'``) of software. Unicode solves
these problems by defining one code page for all scripts.
Creating Unicode strings in Python is just as simple as creating normal
strings::
>>> u'Hello World !'
u'Hello World !'
The small ``'u'`` in front of the quote indicates that a Unicode string is
supposed to be created. If you want to include special characters in the string,
you can do so by using the Python *Unicode-Escape* encoding. The following
example shows how::
>>> u'Hello\u0020World !'
u'Hello World !'
The escape sequence ``\u0020`` indicates to insert the Unicode character with
the ordinal value 0x0020 (the space character) at the given position.
Other characters are interpreted by using their respective ordinal values
directly as Unicode ordinals. If you have literal strings in the standard
Latin-1 encoding that is used in many Western countries, you will find it
convenient that the lower 256 characters of Unicode are the same as the 256
characters of Latin-1.
For experts, there is also a raw mode just like the one for normal strings. You
have to prefix the opening quote with 'ur' to have Python use the
*Raw-Unicode-Escape* encoding. It will only apply the above ``\uXXXX``
conversion if there is an uneven number of backslashes in front of the small
'u'. ::
>>> ur'Hello\u0020World !'
u'Hello World !'
>>> ur'Hello\\u0020World !'
u'Hello\\\\u0020World !'
The raw mode is most useful when you have to enter lots of backslashes, as can
be necessary in regular expressions.
Apart from these standard encodings, Python provides a whole set of other ways
of creating Unicode strings on the basis of a known encoding.
.. index:: builtin: unicode
The built-in function :func:`unicode` provides access to all registered Unicode
codecs (COders and DECoders). Some of the more well known encodings which these
codecs can convert are *Latin-1*, *ASCII*, *UTF-8*, and *UTF-16*. The latter two
are variable-length encodings that store each Unicode character in one or more
bytes. The default encoding is normally set to ASCII, which passes through
characters in the range 0 to 127 and rejects any other characters with an error.
When a Unicode string is printed, written to a file, or converted with
:func:`str`, conversion takes place using this default encoding. ::
>>> u"abc"
u'abc'
>>> str(u"abc")
'abc'
>>> u"äöü"
u'\xe4\xf6\xfc'
>>> str(u"äöü")
Traceback (most recent call last):
File "<stdin>", line 1, in ?
UnicodeEncodeError: 'ascii' codec can't encode characters in position 0-2: ordinal not in range(128)
To convert a Unicode string into an 8-bit string using a specific encoding,
Unicode objects provide an :func:`encode` method that takes one argument, the
name of the encoding. Lowercase names for encodings are preferred. ::
>>> u"äöü".encode('utf-8')
'\xc3\xa4\xc3\xb6\xc3\xbc'
If you have data in a specific encoding and want to produce a corresponding
Unicode string from it, you can use the :func:`unicode` function with the
encoding name as the second argument. ::
>>> unicode('\xc3\xa4\xc3\xb6\xc3\xbc', 'utf-8')
u'\xe4\xf6\xfc'
.. _tut-lists:
Lists
-----
Python knows a number of *compound* data types, used to group together other
values. The most versatile is the *list*, which can be written as a list of
comma-separated values (items) between square brackets. Lists might contain
items of different types, but usually the items all have the same type. ::
>>> squares = [1, 4, 9, 16, 25]
>>> squares
[1, 4, 9, 16, 25]
Like strings (and all other built-in :term:`sequence` type), lists can be
indexed and sliced::
>>> squares[0] # indexing returns the item
1
>>> squares[-1]
25
>>> squares[-3:] # slicing returns a new list
[9, 16, 25]
All slice operations return a new list containing the requested elements. This
means that the following slice returns a new (shallow) copy of the list::
>>> squares[:]
[1, 4, 9, 16, 25]
Lists also supports operations like concatenation::
>>> squares + [36, 49, 64, 81, 100]
[1, 4, 9, 16, 25, 36, 49, 64, 81, 100]
Unlike strings, which are :term:`immutable`, lists are a :term:`mutable`
type, i.e. it is possible to change their content::
>>> cubes = [1, 8, 27, 65, 125] # something's wrong here
>>> 4 ** 3 # the cube of 4 is 64, not 65!
64
>>> cubes[3] = 64 # replace the wrong value
>>> cubes
[1, 8, 27, 64, 125]
You can also add new items at the end of the list, by using
the :meth:`~list.append` *method* (we will see more about methods later)::
>>> cubes.append(216) # add the cube of 6
>>> cubes.append(7 ** 3) # and the cube of 7
>>> cubes
[1, 8, 27, 64, 125, 216, 343]
Assignment to slices is also possible, and this can even change the size of the
list or clear it entirely::
>>> letters = ['a', 'b', 'c', 'd', 'e', 'f', 'g']
>>> letters
['a', 'b', 'c', 'd', 'e', 'f', 'g']
>>> # replace some values
>>> letters[2:5] = ['C', 'D', 'E']
>>> letters
['a', 'b', 'C', 'D', 'E', 'f', 'g']
>>> # now remove them
>>> letters[2:5] = []
>>> letters
['a', 'b', 'f', 'g']
>>> # clear the list by replacing all the elements with an empty list
>>> letters[:] = []
>>> letters
[]
The built-in function :func:`len` also applies to lists::
>>> letters = ['a', 'b', 'c', 'd']
>>> len(letters)
4
It is possible to nest lists (create lists containing other lists), for
example::
>>> a = ['a', 'b', 'c']
>>> n = [1, 2, 3]
>>> x = [a, n]
>>> x
[['a', 'b', 'c'], [1, 2, 3]]
>>> x[0]
['a', 'b', 'c']
>>> x[0][1]
'b'
.. _tut-firststeps:
First Steps Towards Programming
===============================
Of course, we can use Python for more complicated tasks than adding two and two
together. For instance, we can write an initial sub-sequence of the *Fibonacci*
series as follows::
>>> # Fibonacci series:
... # the sum of two elements defines the next
... a, b = 0, 1
>>> while b < 10:
... print b
... a, b = b, a+b
...
1
1
2
3
5
8
This example introduces several new features.
* The first line contains a *multiple assignment*: the variables ``a`` and ``b``
simultaneously get the new values 0 and 1. On the last line this is used again,
demonstrating that the expressions on the right-hand side are all evaluated
first before any of the assignments take place. The right-hand side expressions
are evaluated from the left to the right.
* The :keyword:`while` loop executes as long as the condition (here: ``b < 10``)
remains true. In Python, like in C, any non-zero integer value is true; zero is
false. The condition may also be a string or list value, in fact any sequence;
anything with a non-zero length is true, empty sequences are false. The test
used in the example is a simple comparison. The standard comparison operators
are written the same as in C: ``<`` (less than), ``>`` (greater than), ``==``
(equal to), ``<=`` (less than or equal to), ``>=`` (greater than or equal to)
and ``!=`` (not equal to).
* The *body* of the loop is *indented*: indentation is Python's way of grouping
statements. At the interactive prompt, you have to type a tab or space(s) for
each indented line. In practice you will prepare more complicated input
for Python with a text editor; all decent text editors have an auto-indent
facility. When a compound statement is entered interactively, it must be
followed by a blank line to indicate completion (since the parser cannot
guess when you have typed the last line). Note that each line within a basic
block must be indented by the same amount.
* The :keyword:`print` statement writes the value of the expression(s) it is
given. It differs from just writing the expression you want to write (as we did
earlier in the calculator examples) in the way it handles multiple expressions
and strings. Strings are printed without quotes, and a space is inserted
between items, so you can format things nicely, like this::
>>> i = 256*256
>>> print 'The value of i is', i
The value of i is 65536
A trailing comma avoids the newline after the output::
>>> a, b = 0, 1
>>> while b < 1000:
... print b,
... a, b = b, a+b
...
1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987
Note that the interpreter inserts a newline before it prints the next prompt if
the last line was not completed.
.. rubric:: Footnotes
.. [#] Since ``**`` has higher precedence than ``-``, ``-3**2`` will be
interpreted as ``-(3**2)`` and thus result in ``-9``. To avoid this
and get ``9``, you can use ``(-3)**2``.
.. [#] Unlike other languages, special characters such as ``\n`` have the
same meaning with both single (``'...'``) and double (``"..."``) quotes.
The only difference between the two is that within single quotes you don't
need to escape ``"`` (but you have to escape ``\'``) and vice versa.
PK
%�\���+W` W` & html/_sources/tutorial/modules.rst.txtnu �[��� .. _tut-modules:
*******
Modules
*******
If you quit from the Python interpreter and enter it again, the definitions you
have made (functions and variables) are lost. Therefore, if you want to write a
somewhat longer program, you are better off using a text editor to prepare the
input for the interpreter and running it with that file as input instead. This
is known as creating a *script*. As your program gets longer, you may want to
split it into several files for easier maintenance. You may also want to use a
handy function that you've written in several programs without copying its
definition into each program.
To support this, Python has a way to put definitions in a file and use them in a
script or in an interactive instance of the interpreter. Such a file is called a
*module*; definitions from a module can be *imported* into other modules or into
the *main* module (the collection of variables that you have access to in a
script executed at the top level and in calculator mode).
A module is a file containing Python definitions and statements. The file name
is the module name with the suffix :file:`.py` appended. Within a module, the
module's name (as a string) is available as the value of the global variable
``__name__``. For instance, use your favorite text editor to create a file
called :file:`fibo.py` in the current directory with the following contents::
# Fibonacci numbers module
def fib(n): # write Fibonacci series up to n
a, b = 0, 1
while b < n:
print b,
a, b = b, a+b
def fib2(n): # return Fibonacci series up to n
result = []
a, b = 0, 1
while b < n:
result.append(b)
a, b = b, a+b
return result
Now enter the Python interpreter and import this module with the following
command::
>>> import fibo
This does not enter the names of the functions defined in ``fibo`` directly in
the current symbol table; it only enters the module name ``fibo`` there. Using
the module name you can access the functions::
>>> fibo.fib(1000)
1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987
>>> fibo.fib2(100)
[1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]
>>> fibo.__name__
'fibo'
If you intend to use a function often you can assign it to a local name::
>>> fib = fibo.fib
>>> fib(500)
1 1 2 3 5 8 13 21 34 55 89 144 233 377
.. _tut-moremodules:
More on Modules
===============
A module can contain executable statements as well as function definitions.
These statements are intended to initialize the module. They are executed only
the *first* time the module name is encountered in an import statement. [#]_
(They are also run if the file is executed as a script.)
Each module has its own private symbol table, which is used as the global symbol
table by all functions defined in the module. Thus, the author of a module can
use global variables in the module without worrying about accidental clashes
with a user's global variables. On the other hand, if you know what you are
doing you can touch a module's global variables with the same notation used to
refer to its functions, ``modname.itemname``.
Modules can import other modules. It is customary but not required to place all
:keyword:`import` statements at the beginning of a module (or script, for that
matter). The imported module names are placed in the importing module's global
symbol table.
There is a variant of the :keyword:`import` statement that imports names from a
module directly into the importing module's symbol table. For example::
>>> from fibo import fib, fib2
>>> fib(500)
1 1 2 3 5 8 13 21 34 55 89 144 233 377
This does not introduce the module name from which the imports are taken in the
local symbol table (so in the example, ``fibo`` is not defined).
There is even a variant to import all names that a module defines::
>>> from fibo import *
>>> fib(500)
1 1 2 3 5 8 13 21 34 55 89 144 233 377
This imports all names except those beginning with an underscore (``_``).
Note that in general the practice of importing ``*`` from a module or package is
frowned upon, since it often causes poorly readable code. However, it is okay to
use it to save typing in interactive sessions.
If the module name is followed by :keyword:`as`, then the name
following :keyword:`as` is bound directly to the imported module.
::
>>> import fibo as fib
>>> fib.fib(500)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377
This is effectively importing the module in the same way that ``import fibo``
will do, with the only difference of it being available as ``fib``.
It can also be used when utilising :keyword:`from` with similar effects::
>>> from fibo import fib as fibonacci
>>> fibonacci(500)
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377
.. note::
For efficiency reasons, each module is only imported once per interpreter
session. Therefore, if you change your modules, you must restart the
interpreter -- or, if it's just one module you want to test interactively,
use :func:`reload`, e.g. ``reload(modulename)``.
.. _tut-modulesasscripts:
Executing modules as scripts
----------------------------
When you run a Python module with ::
python fibo.py <arguments>
the code in the module will be executed, just as if you imported it, but with
the ``__name__`` set to ``"__main__"``. That means that by adding this code at
the end of your module::
if __name__ == "__main__":
import sys
fib(int(sys.argv[1]))
you can make the file usable as a script as well as an importable module,
because the code that parses the command line only runs if the module is
executed as the "main" file:
.. code-block:: shell-session
$ python fibo.py 50
1 1 2 3 5 8 13 21 34
If the module is imported, the code is not run::
>>> import fibo
>>>
This is often used either to provide a convenient user interface to a module, or
for testing purposes (running the module as a script executes a test suite).
.. _tut-searchpath:
The Module Search Path
----------------------
.. index:: triple: module; search; path
When a module named :mod:`spam` is imported, the interpreter first searches for
a built-in module with that name. If not found, it then searches for a file
named :file:`spam.py` in a list of directories given by the variable
:data:`sys.path`. :data:`sys.path` is initialized from these locations:
* the directory containing the input script (or the current directory).
* :envvar:`PYTHONPATH` (a list of directory names, with the same syntax as the
shell variable :envvar:`PATH`).
* the installation-dependent default.
After initialization, Python programs can modify :data:`sys.path`. The
directory containing the script being run is placed at the beginning of the
search path, ahead of the standard library path. This means that scripts in that
directory will be loaded instead of modules of the same name in the library
directory. This is an error unless the replacement is intended. See section
:ref:`tut-standardmodules` for more information.
"Compiled" Python files
-----------------------
As an important speed-up of the start-up time for short programs that use a lot
of standard modules, if a file called :file:`spam.pyc` exists in the directory
where :file:`spam.py` is found, this is assumed to contain an
already-"byte-compiled" version of the module :mod:`spam`. The modification time
of the version of :file:`spam.py` used to create :file:`spam.pyc` is recorded in
:file:`spam.pyc`, and the :file:`.pyc` file is ignored if these don't match.
Normally, you don't need to do anything to create the :file:`spam.pyc` file.
Whenever :file:`spam.py` is successfully compiled, an attempt is made to write
the compiled version to :file:`spam.pyc`. It is not an error if this attempt
fails; if for any reason the file is not written completely, the resulting
:file:`spam.pyc` file will be recognized as invalid and thus ignored later. The
contents of the :file:`spam.pyc` file are platform independent, so a Python
module directory can be shared by machines of different architectures.
Some tips for experts:
* When the Python interpreter is invoked with the :option:`-O` flag, optimized
code is generated and stored in :file:`.pyo` files. The optimizer currently
doesn't help much; it only removes :keyword:`assert` statements. When
:option:`-O` is used, *all* :term:`bytecode` is optimized; ``.pyc`` files are
ignored and ``.py`` files are compiled to optimized bytecode.
* Passing two :option:`-O` flags to the Python interpreter (:option:`-OO`) will
cause the bytecode compiler to perform optimizations that could in some rare
cases result in malfunctioning programs. Currently only ``__doc__`` strings are
removed from the bytecode, resulting in more compact :file:`.pyo` files. Since
some programs may rely on having these available, you should only use this
option if you know what you're doing.
* A program doesn't run any faster when it is read from a :file:`.pyc` or
:file:`.pyo` file than when it is read from a :file:`.py` file; the only thing
that's faster about :file:`.pyc` or :file:`.pyo` files is the speed with which
they are loaded.
* When a script is run by giving its name on the command line, the bytecode for
the script is never written to a :file:`.pyc` or :file:`.pyo` file. Thus, the
startup time of a script may be reduced by moving most of its code to a module
and having a small bootstrap script that imports that module. It is also
possible to name a :file:`.pyc` or :file:`.pyo` file directly on the command
line.
* It is possible to have a file called :file:`spam.pyc` (or :file:`spam.pyo`
when :option:`-O` is used) without a file :file:`spam.py` for the same module.
This can be used to distribute a library of Python code in a form that is
moderately hard to reverse engineer.
.. index:: module: compileall
* The module :mod:`compileall` can create :file:`.pyc` files (or :file:`.pyo`
files when :option:`-O` is used) for all modules in a directory.
.. _tut-standardmodules:
Standard Modules
================
.. index:: module: sys
Python comes with a library of standard modules, described in a separate
document, the Python Library Reference ("Library Reference" hereafter). Some
modules are built into the interpreter; these provide access to operations that
are not part of the core of the language but are nevertheless built in, either
for efficiency or to provide access to operating system primitives such as
system calls. The set of such modules is a configuration option which also
depends on the underlying platform. For example, the :mod:`winreg` module is only
provided on Windows systems. One particular module deserves some attention:
:mod:`sys`, which is built into every Python interpreter. The variables
``sys.ps1`` and ``sys.ps2`` define the strings used as primary and secondary
prompts::
>>> import sys
>>> sys.ps1
'>>> '
>>> sys.ps2
'... '
>>> sys.ps1 = 'C> '
C> print 'Yuck!'
Yuck!
C>
These two variables are only defined if the interpreter is in interactive mode.
The variable ``sys.path`` is a list of strings that determines the interpreter's
search path for modules. It is initialized to a default path taken from the
environment variable :envvar:`PYTHONPATH`, or from a built-in default if
:envvar:`PYTHONPATH` is not set. You can modify it using standard list
operations::
>>> import sys
>>> sys.path.append('/ufs/guido/lib/python')
.. _tut-dir:
The :func:`dir` Function
========================
The built-in function :func:`dir` is used to find out which names a module
defines. It returns a sorted list of strings::
>>> import fibo, sys
>>> dir(fibo)
['__name__', 'fib', 'fib2']
>>> dir(sys) # doctest: +NORMALIZE_WHITESPACE
['__displayhook__', '__doc__', '__excepthook__', '__name__', '__package__',
'__stderr__', '__stdin__', '__stdout__', '_clear_type_cache',
'_current_frames', '_getframe', '_mercurial', 'api_version', 'argv',
'builtin_module_names', 'byteorder', 'call_tracing', 'callstats',
'copyright', 'displayhook', 'dont_write_bytecode', 'exc_clear', 'exc_info',
'exc_traceback', 'exc_type', 'exc_value', 'excepthook', 'exec_prefix',
'executable', 'exit', 'flags', 'float_info', 'float_repr_style',
'getcheckinterval', 'getdefaultencoding', 'getdlopenflags',
'getfilesystemencoding', 'getobjects', 'getprofile', 'getrecursionlimit',
'getrefcount', 'getsizeof', 'gettotalrefcount', 'gettrace', 'hexversion',
'long_info', 'maxint', 'maxsize', 'maxunicode', 'meta_path', 'modules',
'path', 'path_hooks', 'path_importer_cache', 'platform', 'prefix', 'ps1',
'py3kwarning', 'setcheckinterval', 'setdlopenflags', 'setprofile',
'setrecursionlimit', 'settrace', 'stderr', 'stdin', 'stdout', 'subversion',
'version', 'version_info', 'warnoptions']
Without arguments, :func:`dir` lists the names you have defined currently::
>>> a = [1, 2, 3, 4, 5]
>>> import fibo
>>> fib = fibo.fib
>>> dir()
['__builtins__', '__name__', '__package__', 'a', 'fib', 'fibo', 'sys']
Note that it lists all types of names: variables, modules, functions, etc.
.. index:: module: __builtin__
:func:`dir` does not list the names of built-in functions and variables. If you
want a list of those, they are defined in the standard module
:mod:`__builtin__`::
>>> import __builtin__
>>> dir(__builtin__) # doctest: +NORMALIZE_WHITESPACE
['ArithmeticError', 'AssertionError', 'AttributeError', 'BaseException',
'BufferError', 'BytesWarning', 'DeprecationWarning', 'EOFError',
'Ellipsis', 'EnvironmentError', 'Exception', 'False', 'FloatingPointError',
'FutureWarning', 'GeneratorExit', 'IOError', 'ImportError', 'ImportWarning',
'IndentationError', 'IndexError', 'KeyError', 'KeyboardInterrupt',
'LookupError', 'MemoryError', 'NameError', 'None', 'NotImplemented',
'NotImplementedError', 'OSError', 'OverflowError',
'PendingDeprecationWarning', 'ReferenceError', 'RuntimeError',
'RuntimeWarning', 'StandardError', 'StopIteration', 'SyntaxError',
'SyntaxWarning', 'SystemError', 'SystemExit', 'TabError', 'True',
'TypeError', 'UnboundLocalError', 'UnicodeDecodeError',
'UnicodeEncodeError', 'UnicodeError', 'UnicodeTranslateError',
'UnicodeWarning', 'UserWarning', 'ValueError', 'Warning',
'ZeroDivisionError', '_', '__debug__', '__doc__', '__import__',
'__name__', '__package__', 'abs', 'all', 'any', 'apply', 'basestring',
'bin', 'bool', 'buffer', 'bytearray', 'bytes', 'callable', 'chr',
'classmethod', 'cmp', 'coerce', 'compile', 'complex', 'copyright',
'credits', 'delattr', 'dict', 'dir', 'divmod', 'enumerate', 'eval',
'execfile', 'exit', 'file', 'filter', 'float', 'format', 'frozenset',
'getattr', 'globals', 'hasattr', 'hash', 'help', 'hex', 'id', 'input',
'int', 'intern', 'isinstance', 'issubclass', 'iter', 'len', 'license',
'list', 'locals', 'long', 'map', 'max', 'memoryview', 'min', 'next',
'object', 'oct', 'open', 'ord', 'pow', 'print', 'property', 'quit',
'range', 'raw_input', 'reduce', 'reload', 'repr', 'reversed', 'round',
'set', 'setattr', 'slice', 'sorted', 'staticmethod', 'str', 'sum', 'super',
'tuple', 'type', 'unichr', 'unicode', 'vars', 'xrange', 'zip']
.. _tut-packages:
Packages
========
Packages are a way of structuring Python's module namespace by using "dotted
module names". For example, the module name :mod:`A.B` designates a submodule
named ``B`` in a package named ``A``. Just like the use of modules saves the
authors of different modules from having to worry about each other's global
variable names, the use of dotted module names saves the authors of multi-module
packages like NumPy or Pillow from having to worry about
each other's module names.
Suppose you want to design a collection of modules (a "package") for the uniform
handling of sound files and sound data. There are many different sound file
formats (usually recognized by their extension, for example: :file:`.wav`,
:file:`.aiff`, :file:`.au`), so you may need to create and maintain a growing
collection of modules for the conversion between the various file formats.
There are also many different operations you might want to perform on sound data
(such as mixing, adding echo, applying an equalizer function, creating an
artificial stereo effect), so in addition you will be writing a never-ending
stream of modules to perform these operations. Here's a possible structure for
your package (expressed in terms of a hierarchical filesystem):
.. code-block:: text
sound/ Top-level package
__init__.py Initialize the sound package
formats/ Subpackage for file format conversions
__init__.py
wavread.py
wavwrite.py
aiffread.py
aiffwrite.py
auread.py
auwrite.py
...
effects/ Subpackage for sound effects
__init__.py
echo.py
surround.py
reverse.py
...
filters/ Subpackage for filters
__init__.py
equalizer.py
vocoder.py
karaoke.py
...
When importing the package, Python searches through the directories on
``sys.path`` looking for the package subdirectory.
The :file:`__init__.py` files are required to make Python treat the directories
as containing packages; this is done to prevent directories with a common name,
such as ``string``, from unintentionally hiding valid modules that occur later
on the module search path. In the simplest case, :file:`__init__.py` can just be
an empty file, but it can also execute initialization code for the package or
set the ``__all__`` variable, described later.
Users of the package can import individual modules from the package, for
example::
import sound.effects.echo
This loads the submodule :mod:`sound.effects.echo`. It must be referenced with
its full name. ::
sound.effects.echo.echofilter(input, output, delay=0.7, atten=4)
An alternative way of importing the submodule is::
from sound.effects import echo
This also loads the submodule :mod:`echo`, and makes it available without its
package prefix, so it can be used as follows::
echo.echofilter(input, output, delay=0.7, atten=4)
Yet another variation is to import the desired function or variable directly::
from sound.effects.echo import echofilter
Again, this loads the submodule :mod:`echo`, but this makes its function
:func:`echofilter` directly available::
echofilter(input, output, delay=0.7, atten=4)
Note that when using ``from package import item``, the item can be either a
submodule (or subpackage) of the package, or some other name defined in the
package, like a function, class or variable. The ``import`` statement first
tests whether the item is defined in the package; if not, it assumes it is a
module and attempts to load it. If it fails to find it, an :exc:`ImportError`
exception is raised.
Contrarily, when using syntax like ``import item.subitem.subsubitem``, each item
except for the last must be a package; the last item can be a module or a
package but can't be a class or function or variable defined in the previous
item.
.. _tut-pkg-import-star:
Importing \* From a Package
---------------------------
.. index:: single: __all__
Now what happens when the user writes ``from sound.effects import *``? Ideally,
one would hope that this somehow goes out to the filesystem, finds which
submodules are present in the package, and imports them all. This could take a
long time and importing sub-modules might have unwanted side-effects that should
only happen when the sub-module is explicitly imported.
The only solution is for the package author to provide an explicit index of the
package. The :keyword:`import` statement uses the following convention: if a package's
:file:`__init__.py` code defines a list named ``__all__``, it is taken to be the
list of module names that should be imported when ``from package import *`` is
encountered. It is up to the package author to keep this list up-to-date when a
new version of the package is released. Package authors may also decide not to
support it, if they don't see a use for importing \* from their package. For
example, the file :file:`sound/effects/__init__.py` could contain the following
code::
__all__ = ["echo", "surround", "reverse"]
This would mean that ``from sound.effects import *`` would import the three
named submodules of the :mod:`sound` package.
If ``__all__`` is not defined, the statement ``from sound.effects import *``
does *not* import all submodules from the package :mod:`sound.effects` into the
current namespace; it only ensures that the package :mod:`sound.effects` has
been imported (possibly running any initialization code in :file:`__init__.py`)
and then imports whatever names are defined in the package. This includes any
names defined (and submodules explicitly loaded) by :file:`__init__.py`. It
also includes any submodules of the package that were explicitly loaded by
previous :keyword:`import` statements. Consider this code::
import sound.effects.echo
import sound.effects.surround
from sound.effects import *
In this example, the :mod:`echo` and :mod:`surround` modules are imported in the
current namespace because they are defined in the :mod:`sound.effects` package
when the ``from...import`` statement is executed. (This also works when
``__all__`` is defined.)
Although certain modules are designed to export only names that follow certain
patterns when you use ``import *``, it is still considered bad practice in
production code.
Remember, there is nothing wrong with using ``from Package import
specific_submodule``! In fact, this is the recommended notation unless the
importing module needs to use submodules with the same name from different
packages.
Intra-package References
------------------------
The submodules often need to refer to each other. For example, the
:mod:`surround` module might use the :mod:`echo` module. In fact, such
references are so common that the :keyword:`import` statement first looks in the
containing package before looking in the standard module search path. Thus, the
:mod:`surround` module can simply use ``import echo`` or ``from echo import
echofilter``. If the imported module is not found in the current package (the
package of which the current module is a submodule), the :keyword:`import`
statement looks for a top-level module with the given name.
When packages are structured into subpackages (as with the :mod:`sound` package
in the example), you can use absolute imports to refer to submodules of siblings
packages. For example, if the module :mod:`sound.filters.vocoder` needs to use
the :mod:`echo` module in the :mod:`sound.effects` package, it can use ``from
sound.effects import echo``.
Starting with Python 2.5, in addition to the implicit relative imports described
above, you can write explicit relative imports with the ``from module import
name`` form of import statement. These explicit relative imports use leading
dots to indicate the current and parent packages involved in the relative
import. From the :mod:`surround` module for example, you might use::
from . import echo
from .. import formats
from ..filters import equalizer
Note that both explicit and implicit relative imports are based on the name of
the current module. Since the name of the main module is always ``"__main__"``,
modules intended for use as the main module of a Python application should
always use absolute imports.
Packages in Multiple Directories
--------------------------------
Packages support one more special attribute, :attr:`__path__`. This is
initialized to be a list containing the name of the directory holding the
package's :file:`__init__.py` before the code in that file is executed. This
variable can be modified; doing so affects future searches for modules and
subpackages contained in the package.
While this feature is not often needed, it can be used to extend the set of
modules found in a package.
.. rubric:: Footnotes
.. [#] In fact function definitions are also 'statements' that are 'executed'; the
execution of a module-level function definition enters the function name in
the module's global symbol table.
PK
%�\�@"Ά& �& % html/_sources/tutorial/stdlib.rst.txtnu �[��� .. _tut-brieftour:
**********************************
Brief Tour of the Standard Library
**********************************
.. _tut-os-interface:
Operating System Interface
==========================
The :mod:`os` module provides dozens of functions for interacting with the
operating system::
>>> import os
>>> os.getcwd() # Return the current working directory
'C:\\Python26'
>>> os.chdir('/server/accesslogs') # Change current working directory
>>> os.system('mkdir today') # Run the command mkdir in the system shell
0
Be sure to use the ``import os`` style instead of ``from os import *``. This
will keep :func:`os.open` from shadowing the built-in :func:`open` function which
operates much differently.
.. index:: builtin: help
The built-in :func:`dir` and :func:`help` functions are useful as interactive
aids for working with large modules like :mod:`os`::
>>> import os
>>> dir(os)
<returns a list of all module functions>
>>> help(os)
<returns an extensive manual page created from the module's docstrings>
For daily file and directory management tasks, the :mod:`shutil` module provides
a higher level interface that is easier to use::
>>> import shutil
>>> shutil.copyfile('data.db', 'archive.db')
>>> shutil.move('/build/executables', 'installdir')
.. _tut-file-wildcards:
File Wildcards
==============
The :mod:`glob` module provides a function for making file lists from directory
wildcard searches::
>>> import glob
>>> glob.glob('*.py')
['primes.py', 'random.py', 'quote.py']
.. _tut-command-line-arguments:
Command Line Arguments
======================
Common utility scripts often need to process command line arguments. These
arguments are stored in the :mod:`sys` module's *argv* attribute as a list. For
instance the following output results from running ``python demo.py one two
three`` at the command line::
>>> import sys
>>> print sys.argv
['demo.py', 'one', 'two', 'three']
The :mod:`getopt` module processes *sys.argv* using the conventions of the Unix
:func:`getopt` function. More powerful and flexible command line processing is
provided by the :mod:`argparse` module.
.. _tut-stderr:
Error Output Redirection and Program Termination
================================================
The :mod:`sys` module also has attributes for *stdin*, *stdout*, and *stderr*.
The latter is useful for emitting warnings and error messages to make them
visible even when *stdout* has been redirected::
>>> sys.stderr.write('Warning, log file not found starting a new one\n')
Warning, log file not found starting a new one
The most direct way to terminate a script is to use ``sys.exit()``.
.. _tut-string-pattern-matching:
String Pattern Matching
=======================
The :mod:`re` module provides regular expression tools for advanced string
processing. For complex matching and manipulation, regular expressions offer
succinct, optimized solutions::
>>> import re
>>> re.findall(r'\bf[a-z]*', 'which foot or hand fell fastest')
['foot', 'fell', 'fastest']
>>> re.sub(r'(\b[a-z]+) \1', r'\1', 'cat in the the hat')
'cat in the hat'
When only simple capabilities are needed, string methods are preferred because
they are easier to read and debug::
>>> 'tea for too'.replace('too', 'two')
'tea for two'
.. _tut-mathematics:
Mathematics
===========
The :mod:`math` module gives access to the underlying C library functions for
floating point math::
>>> import math
>>> math.cos(math.pi / 4.0)
0.70710678118654757
>>> math.log(1024, 2)
10.0
The :mod:`random` module provides tools for making random selections::
>>> import random
>>> random.choice(['apple', 'pear', 'banana'])
'apple'
>>> random.sample(xrange(100), 10) # sampling without replacement
[30, 83, 16, 4, 8, 81, 41, 50, 18, 33]
>>> random.random() # random float
0.17970987693706186
>>> random.randrange(6) # random integer chosen from range(6)
4
.. _tut-internet-access:
Internet Access
===============
There are a number of modules for accessing the internet and processing internet
protocols. Two of the simplest are :mod:`urllib2` for retrieving data from URLs
and :mod:`smtplib` for sending mail::
>>> import urllib2
>>> for line in urllib2.urlopen('http://tycho.usno.navy.mil/cgi-bin/timer.pl'):
... if 'EST' in line or 'EDT' in line: # look for Eastern Time
... print line
<BR>Nov. 25, 09:43:32 PM EST
>>> import smtplib
>>> server = smtplib.SMTP('localhost')
>>> server.sendmail('soothsayer@example.org', 'jcaesar@example.org',
... """To: jcaesar@example.org
... From: soothsayer@example.org
...
... Beware the Ides of March.
... """)
>>> server.quit()
(Note that the second example needs a mailserver running on localhost.)
.. _tut-dates-and-times:
Dates and Times
===============
The :mod:`datetime` module supplies classes for manipulating dates and times in
both simple and complex ways. While date and time arithmetic is supported, the
focus of the implementation is on efficient member extraction for output
formatting and manipulation. The module also supports objects that are timezone
aware. ::
>>> # dates are easily constructed and formatted
>>> from datetime import date
>>> now = date.today()
>>> now
datetime.date(2003, 12, 2)
>>> now.strftime("%m-%d-%y. %d %b %Y is a %A on the %d day of %B.")
'12-02-03. 02 Dec 2003 is a Tuesday on the 02 day of December.'
>>> # dates support calendar arithmetic
>>> birthday = date(1964, 7, 31)
>>> age = now - birthday
>>> age.days
14368
.. _tut-data-compression:
Data Compression
================
Common data archiving and compression formats are directly supported by modules
including: :mod:`zlib`, :mod:`gzip`, :mod:`bz2`, :mod:`zipfile` and
:mod:`tarfile`. ::
>>> import zlib
>>> s = 'witch which has which witches wrist watch'
>>> len(s)
41
>>> t = zlib.compress(s)
>>> len(t)
37
>>> zlib.decompress(t)
'witch which has which witches wrist watch'
>>> zlib.crc32(s)
226805979
.. _tut-performance-measurement:
Performance Measurement
=======================
Some Python users develop a deep interest in knowing the relative performance of
different approaches to the same problem. Python provides a measurement tool
that answers those questions immediately.
For example, it may be tempting to use the tuple packing and unpacking feature
instead of the traditional approach to swapping arguments. The :mod:`timeit`
module quickly demonstrates a modest performance advantage::
>>> from timeit import Timer
>>> Timer('t=a; a=b; b=t', 'a=1; b=2').timeit()
0.57535828626024577
>>> Timer('a,b = b,a', 'a=1; b=2').timeit()
0.54962537085770791
In contrast to :mod:`timeit`'s fine level of granularity, the :mod:`profile` and
:mod:`pstats` modules provide tools for identifying time critical sections in
larger blocks of code.
.. _tut-quality-control:
Quality Control
===============
One approach for developing high quality software is to write tests for each
function as it is developed and to run those tests frequently during the
development process.
The :mod:`doctest` module provides a tool for scanning a module and validating
tests embedded in a program's docstrings. Test construction is as simple as
cutting-and-pasting a typical call along with its results into the docstring.
This improves the documentation by providing the user with an example and it
allows the doctest module to make sure the code remains true to the
documentation::
def average(values):
"""Computes the arithmetic mean of a list of numbers.
>>> print average([20, 30, 70])
40.0
"""
return sum(values, 0.0) / len(values)
import doctest
doctest.testmod() # automatically validate the embedded tests
The :mod:`unittest` module is not as effortless as the :mod:`doctest` module,
but it allows a more comprehensive set of tests to be maintained in a separate
file::
import unittest
class TestStatisticalFunctions(unittest.TestCase):
def test_average(self):
self.assertEqual(average([20, 30, 70]), 40.0)
self.assertEqual(round(average([1, 5, 7]), 1), 4.3)
with self.assertRaises(ZeroDivisionError):
average([])
with self.assertRaises(TypeError):
average(20, 30, 70)
unittest.main() # Calling from the command line invokes all tests
.. _tut-batteries-included:
Batteries Included
==================
Python has a "batteries included" philosophy. This is best seen through the
sophisticated and robust capabilities of its larger packages. For example:
* The :mod:`xmlrpclib` and :mod:`SimpleXMLRPCServer` modules make implementing
remote procedure calls into an almost trivial task. Despite the modules
names, no direct knowledge or handling of XML is needed.
* The :mod:`email` package is a library for managing email messages, including
MIME and other RFC 2822-based message documents. Unlike :mod:`smtplib` and
:mod:`poplib` which actually send and receive messages, the email package has
a complete toolset for building or decoding complex message structures
(including attachments) and for implementing internet encoding and header
protocols.
* The :mod:`xml.dom` and :mod:`xml.sax` packages provide robust support for
parsing this popular data interchange format. Likewise, the :mod:`csv` module
supports direct reads and writes in a common database format. Together, these
modules and packages greatly simplify data interchange between Python
applications and other tools.
* Internationalization is supported by a number of modules including
:mod:`gettext`, :mod:`locale`, and the :mod:`codecs` package.
PK
%�\���_�; �; & html/_sources/tutorial/stdlib2.rst.txtnu �[��� .. _tut-brieftourtwo:
**********************************************
Brief Tour of the Standard Library --- Part II
**********************************************
This second tour covers more advanced modules that support professional
programming needs. These modules rarely occur in small scripts.
.. _tut-output-formatting:
Output Formatting
=================
The :mod:`repr` module provides a version of :func:`repr` customized for
abbreviated displays of large or deeply nested containers::
>>> import repr
>>> repr.repr(set('supercalifragilisticexpialidocious'))
"set(['a', 'c', 'd', 'e', 'f', 'g', ...])"
The :mod:`pprint` module offers more sophisticated control over printing both
built-in and user defined objects in a way that is readable by the interpreter.
When the result is longer than one line, the "pretty printer" adds line breaks
and indentation to more clearly reveal data structure::
>>> import pprint
>>> t = [[[['black', 'cyan'], 'white', ['green', 'red']], [['magenta',
... 'yellow'], 'blue']]]
...
>>> pprint.pprint(t, width=30)
[[[['black', 'cyan'],
'white',
['green', 'red']],
[['magenta', 'yellow'],
'blue']]]
The :mod:`textwrap` module formats paragraphs of text to fit a given screen
width::
>>> import textwrap
>>> doc = """The wrap() method is just like fill() except that it returns
... a list of strings instead of one big string with newlines to separate
... the wrapped lines."""
...
>>> print textwrap.fill(doc, width=40)
The wrap() method is just like fill()
except that it returns a list of strings
instead of one big string with newlines
to separate the wrapped lines.
The :mod:`locale` module accesses a database of culture specific data formats.
The grouping attribute of locale's format function provides a direct way of
formatting numbers with group separators::
>>> import locale
>>> locale.setlocale(locale.LC_ALL, 'English_United States.1252')
'English_United States.1252'
>>> conv = locale.localeconv() # get a mapping of conventions
>>> x = 1234567.8
>>> locale.format("%d", x, grouping=True)
'1,234,567'
>>> locale.format_string("%s%.*f", (conv['currency_symbol'],
... conv['frac_digits'], x), grouping=True)
'$1,234,567.80'
.. _tut-templating:
Templating
==========
The :mod:`string` module includes a versatile :class:`~string.Template` class
with a simplified syntax suitable for editing by end-users. This allows users
to customize their applications without having to alter the application.
The format uses placeholder names formed by ``$`` with valid Python identifiers
(alphanumeric characters and underscores). Surrounding the placeholder with
braces allows it to be followed by more alphanumeric letters with no intervening
spaces. Writing ``$$`` creates a single escaped ``$``::
>>> from string import Template
>>> t = Template('${village}folk send $$10 to $cause.')
>>> t.substitute(village='Nottingham', cause='the ditch fund')
'Nottinghamfolk send $10 to the ditch fund.'
The :meth:`~string.Template.substitute` method raises a :exc:`KeyError` when a
placeholder is not supplied in a dictionary or a keyword argument. For
mail-merge style applications, user supplied data may be incomplete and the
:meth:`~string.Template.safe_substitute` method may be more appropriate ---
it will leave placeholders unchanged if data is missing::
>>> t = Template('Return the $item to $owner.')
>>> d = dict(item='unladen swallow')
>>> t.substitute(d)
Traceback (most recent call last):
...
KeyError: 'owner'
>>> t.safe_substitute(d)
'Return the unladen swallow to $owner.'
Template subclasses can specify a custom delimiter. For example, a batch
renaming utility for a photo browser may elect to use percent signs for
placeholders such as the current date, image sequence number, or file format::
>>> import time, os.path
>>> photofiles = ['img_1074.jpg', 'img_1076.jpg', 'img_1077.jpg']
>>> class BatchRename(Template):
... delimiter = '%'
>>> fmt = raw_input('Enter rename style (%d-date %n-seqnum %f-format): ')
Enter rename style (%d-date %n-seqnum %f-format): Ashley_%n%f
>>> t = BatchRename(fmt)
>>> date = time.strftime('%d%b%y')
>>> for i, filename in enumerate(photofiles):
... base, ext = os.path.splitext(filename)
... newname = t.substitute(d=date, n=i, f=ext)
... print '{0} --> {1}'.format(filename, newname)
img_1074.jpg --> Ashley_0.jpg
img_1076.jpg --> Ashley_1.jpg
img_1077.jpg --> Ashley_2.jpg
Another application for templating is separating program logic from the details
of multiple output formats. This makes it possible to substitute custom
templates for XML files, plain text reports, and HTML web reports.
.. _tut-binary-formats:
Working with Binary Data Record Layouts
=======================================
The :mod:`struct` module provides :func:`~struct.pack` and
:func:`~struct.unpack` functions for working with variable length binary
record formats. The following example shows
how to loop through header information in a ZIP file without using the
:mod:`zipfile` module. Pack codes ``"H"`` and ``"I"`` represent two and four
byte unsigned numbers respectively. The ``"<"`` indicates that they are
standard size and in little-endian byte order::
import struct
data = open('myfile.zip', 'rb').read()
start = 0
for i in range(3): # show the first 3 file headers
start += 14
fields = struct.unpack('<IIIHH', data[start:start+16])
crc32, comp_size, uncomp_size, filenamesize, extra_size = fields
start += 16
filename = data[start:start+filenamesize]
start += filenamesize
extra = data[start:start+extra_size]
print filename, hex(crc32), comp_size, uncomp_size
start += extra_size + comp_size # skip to the next header
.. _tut-multi-threading:
Multi-threading
===============
Threading is a technique for decoupling tasks which are not sequentially
dependent. Threads can be used to improve the responsiveness of applications
that accept user input while other tasks run in the background. A related use
case is running I/O in parallel with computations in another thread.
The following code shows how the high level :mod:`threading` module can run
tasks in background while the main program continues to run::
import threading, zipfile
class AsyncZip(threading.Thread):
def __init__(self, infile, outfile):
threading.Thread.__init__(self)
self.infile = infile
self.outfile = outfile
def run(self):
f = zipfile.ZipFile(self.outfile, 'w', zipfile.ZIP_DEFLATED)
f.write(self.infile)
f.close()
print 'Finished background zip of: ', self.infile
background = AsyncZip('mydata.txt', 'myarchive.zip')
background.start()
print 'The main program continues to run in foreground.'
background.join() # Wait for the background task to finish
print 'Main program waited until background was done.'
The principal challenge of multi-threaded applications is coordinating threads
that share data or other resources. To that end, the threading module provides
a number of synchronization primitives including locks, events, condition
variables, and semaphores.
While those tools are powerful, minor design errors can result in problems that
are difficult to reproduce. So, the preferred approach to task coordination is
to concentrate all access to a resource in a single thread and then use the
:mod:`Queue` module to feed that thread with requests from other threads.
Applications using :class:`Queue.Queue` objects for inter-thread communication
and coordination are easier to design, more readable, and more reliable.
.. _tut-logging:
Logging
=======
The :mod:`logging` module offers a full featured and flexible logging system.
At its simplest, log messages are sent to a file or to ``sys.stderr``::
import logging
logging.debug('Debugging information')
logging.info('Informational message')
logging.warning('Warning:config file %s not found', 'server.conf')
logging.error('Error occurred')
logging.critical('Critical error -- shutting down')
This produces the following output:
.. code-block:: none
WARNING:root:Warning:config file server.conf not found
ERROR:root:Error occurred
CRITICAL:root:Critical error -- shutting down
By default, informational and debugging messages are suppressed and the output
is sent to standard error. Other output options include routing messages
through email, datagrams, sockets, or to an HTTP Server. New filters can select
different routing based on message priority: :const:`~logging.DEBUG`,
:const:`~logging.INFO`, :const:`~logging.WARNING`, :const:`~logging.ERROR`,
and :const:`~logging.CRITICAL`.
The logging system can be configured directly from Python or can be loaded from
a user editable configuration file for customized logging without altering the
application.
.. _tut-weak-references:
Weak References
===============
Python does automatic memory management (reference counting for most objects and
:term:`garbage collection` to eliminate cycles). The memory is freed shortly
after the last reference to it has been eliminated.
This approach works fine for most applications but occasionally there is a need
to track objects only as long as they are being used by something else.
Unfortunately, just tracking them creates a reference that makes them permanent.
The :mod:`weakref` module provides tools for tracking objects without creating a
reference. When the object is no longer needed, it is automatically removed
from a weakref table and a callback is triggered for weakref objects. Typical
applications include caching objects that are expensive to create::
>>> import weakref, gc
>>> class A:
... def __init__(self, value):
... self.value = value
... def __repr__(self):
... return str(self.value)
...
>>> a = A(10) # create a reference
>>> d = weakref.WeakValueDictionary()
>>> d['primary'] = a # does not create a reference
>>> d['primary'] # fetch the object if it is still alive
10
>>> del a # remove the one reference
>>> gc.collect() # run garbage collection right away
0
>>> d['primary'] # entry was automatically removed
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
d['primary'] # entry was automatically removed
File "C:/python26/lib/weakref.py", line 46, in __getitem__
o = self.data[key]()
KeyError: 'primary'
.. _tut-list-tools:
Tools for Working with Lists
============================
Many data structure needs can be met with the built-in list type. However,
sometimes there is a need for alternative implementations with different
performance trade-offs.
The :mod:`array` module provides an :class:`~array.array()` object that is like
a list that stores only homogeneous data and stores it more compactly. The
following example shows an array of numbers stored as two byte unsigned binary
numbers (typecode ``"H"``) rather than the usual 16 bytes per entry for regular
lists of Python int objects::
>>> from array import array
>>> a = array('H', [4000, 10, 700, 22222])
>>> sum(a)
26932
>>> a[1:3]
array('H', [10, 700])
The :mod:`collections` module provides a :class:`~collections.deque()` object
that is like a list with faster appends and pops from the left side but slower
lookups in the middle. These objects are well suited for implementing queues
and breadth first tree searches::
>>> from collections import deque
>>> d = deque(["task1", "task2", "task3"])
>>> d.append("task4")
>>> print "Handling", d.popleft()
Handling task1
::
unsearched = deque([starting_node])
def breadth_first_search(unsearched):
node = unsearched.popleft()
for m in gen_moves(node):
if is_goal(m):
return m
unsearched.append(m)
In addition to alternative list implementations, the library also offers other
tools such as the :mod:`bisect` module with functions for manipulating sorted
lists::
>>> import bisect
>>> scores = [(100, 'perl'), (200, 'tcl'), (400, 'lua'), (500, 'python')]
>>> bisect.insort(scores, (300, 'ruby'))
>>> scores
[(100, 'perl'), (200, 'tcl'), (300, 'ruby'), (400, 'lua'), (500, 'python')]
The :mod:`heapq` module provides functions for implementing heaps based on
regular lists. The lowest valued entry is always kept at position zero. This
is useful for applications which repeatedly access the smallest element but do
not want to run a full list sort::
>>> from heapq import heapify, heappop, heappush
>>> data = [1, 3, 5, 7, 9, 2, 4, 6, 8, 0]
>>> heapify(data) # rearrange the list into heap order
>>> heappush(data, -5) # add a new entry
>>> [heappop(data) for i in range(3)] # fetch the three smallest entries
[-5, 0, 1]
.. _tut-decimal-fp:
Decimal Floating Point Arithmetic
=================================
The :mod:`decimal` module offers a :class:`~decimal.Decimal` datatype for
decimal floating point arithmetic. Compared to the built-in :class:`float`
implementation of binary floating point, the class is especially helpful for
* financial applications and other uses which require exact decimal
representation,
* control over precision,
* control over rounding to meet legal or regulatory requirements,
* tracking of significant decimal places, or
* applications where the user expects the results to match calculations done by
hand.
For example, calculating a 5% tax on a 70 cent phone charge gives different
results in decimal floating point and binary floating point. The difference
becomes significant if the results are rounded to the nearest cent::
>>> from decimal import *
>>> x = Decimal('0.70') * Decimal('1.05')
>>> x
Decimal('0.7350')
>>> x.quantize(Decimal('0.01')) # round to nearest cent
Decimal('0.74')
>>> round(.70 * 1.05, 2) # same calculation with floats
0.73
The :class:`~decimal.Decimal` result keeps a trailing zero, automatically
inferring four place significance from multiplicands with two place
significance. Decimal reproduces mathematics as done by hand and avoids
issues that can arise when binary floating point cannot exactly represent
decimal quantities.
Exact representation enables the :class:`~decimal.Decimal` class to perform
modulo calculations and equality tests that are unsuitable for binary floating
point::
>>> Decimal('1.00') % Decimal('.10')
Decimal('0.00')
>>> 1.00 % 0.10
0.09999999999999995
>>> sum([Decimal('0.1')]*10) == Decimal('1.0')
True
>>> sum([0.1]*10) == 1.0
False
The :mod:`decimal` module provides arithmetic with as much precision as needed::
>>> getcontext().prec = 36
>>> Decimal(1) / Decimal(7)
Decimal('0.142857142857142857142857142857142857')
PK
%�\�ٗ� & html/_sources/tutorial/whatnow.rst.txtnu �[��� .. _tut-whatnow:
*********
What Now?
*********
Reading this tutorial has probably reinforced your interest in using Python ---
you should be eager to apply Python to solving your real-world problems. Where
should you go to learn more?
This tutorial is part of Python's documentation set. Some other documents in
the set are:
* :ref:`library-index`:
You should browse through this manual, which gives complete (though terse)
reference material about types, functions, and the modules in the standard
library. The standard Python distribution includes a *lot* of additional code.
There are modules to read Unix mailboxes, retrieve documents via HTTP, generate
random numbers, parse command-line options, write CGI programs, compress data,
and many other tasks. Skimming through the Library Reference will give you an
idea of what's available.
* :ref:`install-index` explains how to install external modules written by other
Python users.
* :ref:`reference-index`: A detailed explanation of Python's syntax and
semantics. It's heavy reading, but is useful as a complete guide to the
language itself.
More Python resources:
* https://www.python.org: The major Python Web site. It contains code,
documentation, and pointers to Python-related pages around the Web. This Web
site is mirrored in various places around the world, such as Europe, Japan, and
Australia; a mirror may be faster than the main site, depending on your
geographical location.
* https://docs.python.org: Fast access to Python's documentation.
* https://pypi.org: The Python Package Index, previously also nicknamed
the Cheese Shop, is an index of user-created Python modules that are available
for download. Once you begin releasing code, you can register it here so that
others can find it.
* https://code.activestate.com/recipes/langs/python/: The Python Cookbook is a
sizable collection of code examples, larger modules, and useful scripts.
Particularly notable contributions are collected in a book also titled Python
Cookbook (O'Reilly & Associates, ISBN 0-596-00797-3.)
For Python-related questions and problem reports, you can post to the newsgroup
:newsgroup:`comp.lang.python`, or send them to the mailing list at
python-list@python.org. The newsgroup and mailing list are gatewayed, so
messages posted to one will automatically be forwarded to the other. There are
around 120 postings a day (with peaks up to several hundred), asking (and
answering) questions, suggesting new features, and announcing new modules.
Before posting, be sure to check the list of :ref:`Frequently Asked Questions
<faq-index>` (also called the FAQ). Mailing list
archives are available at https://mail.python.org/pipermail/. The FAQ answers
many of the questions that come up again and again, and may already contain the
solution for your problem.
.. Postings figure based on average of last six months activity as
reported by www.egroups.com; Jan. 2000 - June 2000: 21272 msgs / 182
days = 116.9 msgs / day and steadily increasing. (XXX up to date figures?)
PK
%�\��ęW �W # html/_sources/using/cmdline.rst.txtnu �[��� .. highlightlang:: sh
.. ATTENTION: You probably should update Misc/python.man, too, if you modify
this file.
.. _using-on-general:
Command line and environment
============================
The CPython interpreter scans the command line and the environment for various
settings.
.. impl-detail::
Other implementations' command line schemes may differ. See
:ref:`implementations` for further resources.
.. _using-on-cmdline:
Command line
------------
When invoking Python, you may specify any of these options::
python [-bBdEiOQsRStuUvVWxX3?] [-c command | -m module-name | script | - ] [args]
The most common use case is, of course, a simple invocation of a script::
python myscript.py
.. _using-on-interface-options:
Interface options
~~~~~~~~~~~~~~~~~
The interpreter interface resembles that of the UNIX shell, but provides some
additional methods of invocation:
* When called with standard input connected to a tty device, it prompts for
commands and executes them until an EOF (an end-of-file character, you can
produce that with :kbd:`Ctrl-D` on UNIX or :kbd:`Ctrl-Z, Enter` on Windows) is read.
* When called with a file name argument or with a file as standard input, it
reads and executes a script from that file.
* When called with a directory name argument, it reads and executes an
appropriately named script from that directory.
* When called with ``-c command``, it executes the Python statement(s) given as
*command*. Here *command* may contain multiple statements separated by
newlines. Leading whitespace is significant in Python statements!
* When called with ``-m module-name``, the given module is located on the
Python module path and executed as a script.
In non-interactive mode, the entire input is parsed before it is executed.
An interface option terminates the list of options consumed by the interpreter,
all consecutive arguments will end up in :data:`sys.argv` -- note that the first
element, subscript zero (``sys.argv[0]``), is a string reflecting the program's
source.
.. cmdoption:: -c <command>
Execute the Python code in *command*. *command* can be one or more
statements separated by newlines, with significant leading whitespace as in
normal module code.
If this option is given, the first element of :data:`sys.argv` will be
``"-c"`` and the current directory will be added to the start of
:data:`sys.path` (allowing modules in that directory to be imported as top
level modules).
.. cmdoption:: -m <module-name>
Search :data:`sys.path` for the named module and execute its contents as
the :mod:`__main__` module.
Since the argument is a *module* name, you must not give a file extension
(``.py``). The ``module-name`` should be a valid Python module name, but
the implementation may not always enforce this (e.g. it may allow you to
use a name that includes a hyphen).
Package names are also permitted. When a package name is supplied instead
of a normal module, the interpreter will execute ``<pkg>.__main__`` as
the main module. This behaviour is deliberately similar to the handling
of directories and zipfiles that are passed to the interpreter as the
script argument.
.. note::
This option cannot be used with built-in modules and extension modules
written in C, since they do not have Python module files. However, it
can still be used for precompiled modules, even if the original source
file is not available.
If this option is given, the first element of :data:`sys.argv` will be the
full path to the module file. As with the :option:`-c` option, the current
directory will be added to the start of :data:`sys.path`.
Many standard library modules contain code that is invoked on their execution
as a script. An example is the :mod:`timeit` module::
python -mtimeit -s 'setup here' 'benchmarked code here'
python -mtimeit -h # for details
.. seealso::
:func:`runpy.run_module`
Equivalent functionality directly available to Python code
:pep:`338` -- Executing modules as scripts
.. versionadded:: 2.4
.. versionchanged:: 2.5
The named module can now be located inside a package.
.. versionchanged:: 2.7
Supply the package name to run a ``__main__`` submodule.
sys.argv[0] is now set to ``"-m"`` while searching for the module
(it was previously incorrectly set to ``"-c"``)
.. describe:: -
Read commands from standard input (:data:`sys.stdin`). If standard input is
a terminal, :option:`-i` is implied.
If this option is given, the first element of :data:`sys.argv` will be
``"-"`` and the current directory will be added to the start of
:data:`sys.path`.
.. seealso::
:func:`runpy.run_path`
Equivalent functionality directly available to Python code
.. describe:: <script>
Execute the Python code contained in *script*, which must be a filesystem
path (absolute or relative) referring to either a Python file, a directory
containing a ``__main__.py`` file, or a zipfile containing a
``__main__.py`` file.
If this option is given, the first element of :data:`sys.argv` will be the
script name as given on the command line.
If the script name refers directly to a Python file, the directory
containing that file is added to the start of :data:`sys.path`, and the
file is executed as the :mod:`__main__` module.
If the script name refers to a directory or zipfile, the script name is
added to the start of :data:`sys.path` and the ``__main__.py`` file in
that location is executed as the :mod:`__main__` module.
.. versionchanged:: 2.5
Directories and zipfiles containing a ``__main__.py`` file at the top
level are now considered valid Python scripts.
If no interface option is given, :option:`-i` is implied, ``sys.argv[0]`` is
an empty string (``""``) and the current directory will be added to the
start of :data:`sys.path`.
.. seealso:: :ref:`tut-invoking`
Generic options
~~~~~~~~~~~~~~~
.. cmdoption:: -?
-h
--help
Print a short description of all command line options.
.. versionchanged:: 2.5
The ``--help`` variant.
.. cmdoption:: -V
--version
Print the Python version number and exit. Example output could be::
Python 2.5.1
.. versionchanged:: 2.5
The ``--version`` variant.
Miscellaneous options
~~~~~~~~~~~~~~~~~~~~~
.. cmdoption:: -b
Issue a warning when comparing :class:`unicode` with :class:`bytearray`.
Issue an error when the option is given twice (:option:`!-bb`).
Note that, unlike the corresponding Python 3.x flag, this will **not** emit
warnings for comparisons between :class:`str` and :class:`unicode`.
Instead, the ``str`` instance will be implicitly decoded to ``unicode`` and
Unicode comparison used.
.. versionadded:: 2.6
.. cmdoption:: -B
If given, Python won't try to write ``.pyc`` or ``.pyo`` files on the
import of source modules. See also :envvar:`PYTHONDONTWRITEBYTECODE`.
.. versionadded:: 2.6
.. cmdoption:: -d
Turn on parser debugging output (for wizards only, depending on compilation
options). See also :envvar:`PYTHONDEBUG`.
.. cmdoption:: -E
Ignore all :envvar:`PYTHON*` environment variables, e.g.
:envvar:`PYTHONPATH` and :envvar:`PYTHONHOME`, that might be set.
.. versionadded:: 2.2
.. cmdoption:: -i
When a script is passed as first argument or the :option:`-c` option is used,
enter interactive mode after executing the script or the command, even when
:data:`sys.stdin` does not appear to be a terminal. The
:envvar:`PYTHONSTARTUP` file is not read.
This can be useful to inspect global variables or a stack trace when a script
raises an exception. See also :envvar:`PYTHONINSPECT`.
.. _using-on-optimizations:
.. cmdoption:: -O
Turn on basic optimizations. This changes the filename extension for
compiled (:term:`bytecode`) files from ``.pyc`` to ``.pyo``. See also
:envvar:`PYTHONOPTIMIZE`.
.. cmdoption:: -OO
Discard docstrings in addition to the :option:`-O` optimizations.
.. cmdoption:: -Q <arg>
Division control. The argument must be one of the following:
``old``
division of int/int and long/long return an int or long (*default*)
``new``
new division semantics, i.e. division of int/int and long/long returns a
float
``warn``
old division semantics with a warning for int/int and long/long
``warnall``
old division semantics with a warning for all uses of the division operator
.. seealso::
:file:`Tools/scripts/fixdiv.py`
for a use of ``warnall``
:pep:`238` -- Changing the division operator
.. cmdoption:: -R
Turn on hash randomization, so that the :meth:`__hash__` values of str,
bytes and datetime objects are "salted" with an unpredictable random value.
Although they remain constant within an individual Python process, they are
not predictable between repeated invocations of Python.
This is intended to provide protection against a denial-of-service caused by
carefully-chosen inputs that exploit the worst case performance of a dict
construction, O(n^2) complexity. See
http://www.ocert.org/advisories/ocert-2011-003.html for details.
Changing hash values affects the order in which keys are retrieved from a
dict. Although Python has never made guarantees about this ordering (and it
typically varies between 32-bit and 64-bit builds), enough real-world code
implicitly relies on this non-guaranteed behavior that the randomization is
disabled by default.
See also :envvar:`PYTHONHASHSEED`.
.. versionadded:: 2.6.8
.. cmdoption:: -s
Don't add the :data:`user site-packages directory <site.USER_SITE>` to
:data:`sys.path`.
.. versionadded:: 2.6
.. seealso::
:pep:`370` -- Per user site-packages directory
.. cmdoption:: -S
Disable the import of the module :mod:`site` and the site-dependent
manipulations of :data:`sys.path` that it entails.
.. cmdoption:: -t
Issue a warning when a source file mixes tabs and spaces for indentation in a
way that makes it depend on the worth of a tab expressed in spaces. Issue an
error when the option is given twice (:option:`!-tt`).
.. cmdoption:: -u
Force stdin, stdout and stderr to be totally unbuffered. On systems where it
matters, also put stdin, stdout and stderr in binary mode.
Note that there is internal buffering in :meth:`file.readlines` and
:ref:`bltin-file-objects` (``for line in sys.stdin``) which is not influenced
by this option. To work around this, you will want to use
:meth:`file.readline` inside a ``while 1:`` loop.
See also :envvar:`PYTHONUNBUFFERED`.
.. cmdoption:: -v
Print a message each time a module is initialized, showing the place
(filename or built-in module) from which it is loaded. When given twice
(:option:`!-vv`), print a message for each file that is checked for when
searching for a module. Also provides information on module cleanup at exit.
See also :envvar:`PYTHONVERBOSE`.
.. cmdoption:: -W arg
Warning control. Python's warning machinery by default prints warning
messages to :data:`sys.stderr`. A typical warning message has the following
form::
file:line: category: message
By default, each warning is printed once for each source line where it
occurs. This option controls how often warnings are printed.
Multiple :option:`-W` options may be given; when a warning matches more than
one option, the action for the last matching option is performed. Invalid
:option:`-W` options are ignored (though, a warning message is printed about
invalid options when the first warning is issued).
Starting from Python 2.7, :exc:`DeprecationWarning` and its descendants
are ignored by default. The :option:`!-Wd` option can be used to re-enable
them.
Warnings can also be controlled from within a Python program using the
:mod:`warnings` module.
The simplest form of argument is one of the following action strings (or a
unique abbreviation) by themselves:
``ignore``
Ignore all warnings.
``default``
Explicitly request the default behavior (printing each warning once per
source line).
``all``
Print a warning each time it occurs (this may generate many messages if a
warning is triggered repeatedly for the same source line, such as inside a
loop).
``module``
Print each warning only the first time it occurs in each module.
``once``
Print each warning only the first time it occurs in the program.
``error``
Raise an exception instead of printing a warning message.
The full form of argument is::
action:message:category:module:line
Here, *action* is as explained above but only applies to messages that match
the remaining fields. Empty fields match all values; trailing empty fields
may be omitted. The *message* field matches the start of the warning message
printed; this match is case-insensitive. The *category* field matches the
warning category. This must be a class name; the match tests whether the
actual warning category of the message is a subclass of the specified warning
category. The full class name must be given. The *module* field matches the
(fully-qualified) module name; this match is case-sensitive. The *line*
field matches the line number, where zero matches all line numbers and is
thus equivalent to an omitted line number.
.. seealso::
:mod:`warnings` -- the warnings module
:pep:`230` -- Warning framework
:envvar:`PYTHONWARNINGS`
.. cmdoption:: -x
Skip the first line of the source, allowing use of non-Unix forms of
``#!cmd``. This is intended for a DOS specific hack only.
.. cmdoption:: -3
Warn about Python 3.x possible incompatibilities by emitting a
:exc:`DeprecationWarning` for features that are removed or significantly
changed in Python 3 and can't be detected using static code analysis.
.. versionadded:: 2.6
See :doc:`/howto/pyporting` for more details.
Options you shouldn't use
~~~~~~~~~~~~~~~~~~~~~~~~~
.. cmdoption:: -J
Reserved for use by Jython_.
.. _Jython: http://www.jython.org/
.. cmdoption:: -U
Turns all string literals into unicodes globally. Do not be tempted to use
this option as it will probably break your world. It also produces
``.pyc`` files with a different magic number than normal. Instead, you can
enable unicode literals on a per-module basis by using::
from __future__ import unicode_literals
at the top of the file. See :mod:`__future__` for details.
.. cmdoption:: -X
Reserved for alternative implementations of Python to use for their own
purposes.
.. _using-on-envvars:
Environment variables
---------------------
These environment variables influence Python's behavior, they are processed
before the command-line switches other than -E. It is customary that
command-line switches override environmental variables where there is a
conflict.
.. envvar:: PYTHONHOME
Change the location of the standard Python libraries. By default, the
libraries are searched in :file:`{prefix}/lib/python{version}` and
:file:`{exec_prefix}/lib/python{version}`, where :file:`{prefix}` and
:file:`{exec_prefix}` are installation-dependent directories, both defaulting
to :file:`/usr/local`.
When :envvar:`PYTHONHOME` is set to a single directory, its value replaces
both :file:`{prefix}` and :file:`{exec_prefix}`. To specify different values
for these, set :envvar:`PYTHONHOME` to :file:`{prefix}:{exec_prefix}`.
.. envvar:: PYTHONPATH
Augment the default search path for module files. The format is the same as
the shell's :envvar:`PATH`: one or more directory pathnames separated by
:data:`os.pathsep` (e.g. colons on Unix or semicolons on Windows).
Non-existent directories are silently ignored.
In addition to normal directories, individual :envvar:`PYTHONPATH` entries
may refer to zipfiles containing pure Python modules (in either source or
compiled form). Extension modules cannot be imported from zipfiles.
The default search path is installation dependent, but generally begins with
:file:`{prefix}/lib/python{version}` (see :envvar:`PYTHONHOME` above). It
is *always* appended to :envvar:`PYTHONPATH`.
An additional directory will be inserted in the search path in front of
:envvar:`PYTHONPATH` as described above under
:ref:`using-on-interface-options`. The search path can be manipulated from
within a Python program as the variable :data:`sys.path`.
.. envvar:: PYTHONSTARTUP
If this is the name of a readable file, the Python commands in that file are
executed before the first prompt is displayed in interactive mode. The file
is executed in the same namespace where interactive commands are executed so
that objects defined or imported in it can be used without qualification in
the interactive session. You can also change the prompts :data:`sys.ps1` and
:data:`sys.ps2` in this file.
.. envvar:: PYTHONY2K
Set this to a non-empty string to cause the :mod:`time` module to require
dates specified as strings to include 4-digit years, otherwise 2-digit years
are converted based on rules described in the :mod:`time` module
documentation.
.. envvar:: PYTHONOPTIMIZE
If this is set to a non-empty string it is equivalent to specifying the
:option:`-O` option. If set to an integer, it is equivalent to specifying
:option:`-O` multiple times.
.. envvar:: PYTHONDEBUG
If this is set to a non-empty string it is equivalent to specifying the
:option:`-d` option. If set to an integer, it is equivalent to specifying
:option:`-d` multiple times.
.. envvar:: PYTHONINSPECT
If this is set to a non-empty string it is equivalent to specifying the
:option:`-i` option.
This variable can also be modified by Python code using :data:`os.environ`
to force inspect mode on program termination.
.. envvar:: PYTHONUNBUFFERED
If this is set to a non-empty string it is equivalent to specifying the
:option:`-u` option.
.. envvar:: PYTHONVERBOSE
If this is set to a non-empty string it is equivalent to specifying the
:option:`-v` option. If set to an integer, it is equivalent to specifying
:option:`-v` multiple times.
.. envvar:: PYTHONCASEOK
If this is set, Python ignores case in :keyword:`import` statements. This
only works on Windows, OS X, OS/2, and RiscOS.
.. envvar:: PYTHONDONTWRITEBYTECODE
If this is set, Python won't try to write ``.pyc`` or ``.pyo`` files on the
import of source modules. This is equivalent to specifying the :option:`-B`
option.
.. versionadded:: 2.6
.. envvar:: PYTHONHASHSEED
If this variable is set to ``random``, the effect is the same as specifying
the :option:`-R` option: a random value is used to seed the hashes of str,
bytes and datetime objects.
If :envvar:`PYTHONHASHSEED` is set to an integer value, it is used as a
fixed seed for generating the hash() of the types covered by the hash
randomization.
Its purpose is to allow repeatable hashing, such as for selftests for the
interpreter itself, or to allow a cluster of python processes to share hash
values.
The integer must be a decimal number in the range [0,4294967295].
Specifying the value 0 will lead to the same hash values as when hash
randomization is disabled.
.. versionadded:: 2.6.8
.. envvar:: PYTHONIOENCODING
Overrides the encoding used for stdin/stdout/stderr, in the syntax
``encodingname:errorhandler``. The ``:errorhandler`` part is optional and
has the same meaning as in :func:`str.encode`.
.. versionadded:: 2.6
.. envvar:: PYTHONNOUSERSITE
If this is set, Python won't add the :data:`user site-packages directory
<site.USER_SITE>` to :data:`sys.path`.
.. versionadded:: 2.6
.. seealso::
:pep:`370` -- Per user site-packages directory
.. envvar:: PYTHONUSERBASE
Defines the :data:`user base directory <site.USER_BASE>`, which is used to
compute the path of the :data:`user site-packages directory <site.USER_SITE>`
and :ref:`Distutils installation paths <inst-alt-install-user>` for ``python
setup.py install --user``.
.. versionadded:: 2.6
.. seealso::
:pep:`370` -- Per user site-packages directory
.. envvar:: PYTHONEXECUTABLE
If this environment variable is set, ``sys.argv[0]`` will be set to its
value instead of the value got through the C runtime. Only works on
Mac OS X.
.. envvar:: PYTHONWARNINGS
This is equivalent to the :option:`-W` option. If set to a comma
separated string, it is equivalent to specifying :option:`-W` multiple
times.
.. envvar:: PYTHONHTTPSVERIFY
If this environment variable is set specifically to ``0``, then it is
equivalent to implicitly calling :func:`ssl._https_verify_certificates` with
``enable=False`` when :mod:`ssl` is first imported.
Refer to the documentation of :func:`ssl._https_verify_certificates` for
details.
.. versionadded:: 2.7.12
Debug-mode variables
~~~~~~~~~~~~~~~~~~~~
Setting these variables only has an effect in a debug build of Python, that is,
if Python was configured with the ``--with-pydebug`` build option.
.. envvar:: PYTHONTHREADDEBUG
If set, Python will print threading debug info.
.. versionchanged:: 2.6
Previously, this variable was called ``THREADDEBUG``.
.. envvar:: PYTHONDUMPREFS
If set, Python will dump objects and reference counts still alive after
shutting down the interpreter.
.. envvar:: PYTHONMALLOCSTATS
If set, Python will print memory allocation statistics every time a new
object arena is created, and on shutdown.
.. envvar:: PYTHONSHOWALLOCCOUNT
If set and Python was compiled with ``COUNT_ALLOCS`` defined, Python will
dump allocations counts into stderr on shutdown.
.. versionadded:: 2.7.15
.. envvar:: PYTHONSHOWREFCOUNT
If set, Python will print the total reference count when the program
finishes or after each statement in the interactive interpreter.
.. versionadded:: 2.7.15
PK
%�\SϤ� � ! html/_sources/using/index.rst.txtnu �[��� .. _using-index:
##########################
Python Setup and Usage
##########################
This part of the documentation is devoted to general information on the setup
of the Python environment on different platforms, the invocation of the
interpreter and things that make working with Python easier.
.. toctree::
:numbered:
cmdline.rst
unix.rst
windows.rst
mac.rst
PK
%�\/r��a a html/_sources/using/mac.rst.txtnu �[���
.. _using-on-mac:
***************************
Using Python on a Macintosh
***************************
:Author: Bob Savage <bobsavage@mac.com>
Python on a Macintosh running Mac OS X is in principle very similar to Python on
any other Unix platform, but there are a number of additional features such as
the IDE and the Package Manager that are worth pointing out.
The Mac-specific modules are documented in :ref:`mac-specific-services`.
Python on Mac OS 9 or earlier can be quite different from Python on Unix or
Windows, but is beyond the scope of this manual, as that platform is no longer
supported, starting with Python 2.4. See http://www.cwi.nl/~jack/macpython for
installers for the latest 2.3 release for Mac OS 9 and related documentation.
.. _getting-osx:
Getting and Installing MacPython
================================
Mac OS X 10.8 comes with Python 2.7 pre-installed by Apple. If you wish, you
are invited to install the most recent version of Python from the Python website
(https://www.python.org). A current "universal binary" build of Python, which
runs natively on the Mac's new Intel and legacy PPC CPU's, is available there.
What you get after installing is a number of things:
* A :file:`MacPython 2.7` folder in your :file:`Applications` folder. In here
you find IDLE, the development environment that is a standard part of official
Python distributions; PythonLauncher, which handles double-clicking Python
scripts from the Finder; and the "Build Applet" tool, which allows you to
package Python scripts as standalone applications on your system.
* A framework :file:`/Library/Frameworks/Python.framework`, which includes the
Python executable and libraries. The installer adds this location to your shell
path. To uninstall MacPython, you can simply remove these three things. A
symlink to the Python executable is placed in /usr/local/bin/.
The Apple-provided build of Python is installed in
:file:`/System/Library/Frameworks/Python.framework` and :file:`/usr/bin/python`,
respectively. You should never modify or delete these, as they are
Apple-controlled and are used by Apple- or third-party software. Remember that
if you choose to install a newer Python version from python.org, you will have
two different but functional Python installations on your computer, so it will
be important that your paths and usages are consistent with what you want to do.
IDLE includes a help menu that allows you to access Python documentation. If you
are completely new to Python you should start reading the tutorial introduction
in that document.
If you are familiar with Python on other Unix platforms you should read the
section on running Python scripts from the Unix shell.
How to run a Python script
--------------------------
Your best way to get started with Python on Mac OS X is through the IDLE
integrated development environment, see section :ref:`ide` and use the Help menu
when the IDE is running.
If you want to run Python scripts from the Terminal window command line or from
the Finder you first need an editor to create your script. Mac OS X comes with a
number of standard Unix command line editors, :program:`vim` and
:program:`emacs` among them. If you want a more Mac-like editor,
:program:`BBEdit` or :program:`TextWrangler` from Bare Bones Software (see
http://www.barebones.com/products/bbedit/index.html) are good choices, as is
:program:`TextMate` (see https://macromates.com/). Other editors include
:program:`Gvim` (http://macvim.org) and :program:`Aquamacs`
(http://aquamacs.org/).
To run your script from the Terminal window you must make sure that
:file:`/usr/local/bin` is in your shell search path.
To run your script from the Finder you have two options:
* Drag it to :program:`PythonLauncher`
* Select :program:`PythonLauncher` as the default application to open your
script (or any .py script) through the finder Info window and double-click it.
:program:`PythonLauncher` has various preferences to control how your script is
launched. Option-dragging allows you to change these for one invocation, or use
its Preferences menu to change things globally.
.. _osx-gui-scripts:
Running scripts with a GUI
--------------------------
With older versions of Python, there is one Mac OS X quirk that you need to be
aware of: programs that talk to the Aqua window manager (in other words,
anything that has a GUI) need to be run in a special way. Use :program:`pythonw`
instead of :program:`python` to start such scripts.
With Python 2.7, you can use either :program:`python` or :program:`pythonw`.
Configuration
-------------
Python on OS X honors all standard Unix environment variables such as
:envvar:`PYTHONPATH`, but setting these variables for programs started from the
Finder is non-standard as the Finder does not read your :file:`.profile` or
:file:`.cshrc` at startup. You need to create a file
:file:`~/.MacOSX/environment.plist`. See Apple's Technical Document QA1067 for
details.
For more information on installation Python packages in MacPython, see section
:ref:`mac-package-manager`.
.. _ide:
The IDE
=======
MacPython ships with the standard IDLE development environment. A good
introduction to using IDLE can be found at
https://hkn.eecs.berkeley.edu/~dyoo/python/idle_intro/index.html.
.. _mac-package-manager:
Installing Additional Python Packages
=====================================
There are several methods to install additional Python packages:
* Packages can be installed via the standard Python distutils mode (``python
setup.py install``).
* Many packages can also be installed via the :program:`setuptools` extension
or :program:`pip` wrapper, see https://pip.pypa.io/.
GUI Programming on the Mac
==========================
There are several options for building GUI applications on the Mac with Python.
*PyObjC* is a Python binding to Apple's Objective-C/Cocoa framework, which is
the foundation of most modern Mac development. Information on PyObjC is
available from https://pythonhosted.org/pyobjc/.
The standard Python GUI toolkit is :mod:`Tkinter`, based on the cross-platform
Tk toolkit (https://www.tcl.tk). An Aqua-native version of Tk is bundled with OS
X by Apple, and the latest version can be downloaded and installed from
https://www.activestate.com; it can also be built from source.
*wxPython* is another popular cross-platform GUI toolkit that runs natively on
Mac OS X. Packages and documentation are available from http://www.wxpython.org.
*PyQt* is another popular cross-platform GUI toolkit that runs natively on Mac
OS X. More information can be found at
https://riverbankcomputing.com/software/pyqt/intro.
Distributing Python Applications on the Mac
===========================================
The "Build Applet" tool that is placed in the MacPython 2.7 folder is fine for
packaging small Python scripts on your own machine to run as a standard Mac
application. This tool, however, is not robust enough to distribute Python
applications to other users.
The standard tool for deploying standalone Python applications on the Mac is
:program:`py2app`. More information on installing and using py2app can be found
at http://undefined.org/python/#py2app.
Other Resources
===============
The MacPython mailing list is an excellent support resource for Python users and
developers on the Mac:
https://www.python.org/community/sigs/current/pythonmac-sig/
Another useful resource is the MacPython wiki:
https://wiki.python.org/moin/MacPython
PK
%�\� <� html/_sources/using/unix.rst.txtnu �[��� .. highlightlang:: sh
.. _using-on-unix:
********************************
Using Python on Unix platforms
********************************
.. sectionauthor:: Shriphani Palakodety
Getting and installing the latest version of Python
===================================================
On Linux
--------
Python comes preinstalled on most Linux distributions, and is available as a
package on all others. However there are certain features you might want to use
that are not available on your distro's package. You can easily compile the
latest version of Python from source.
In the event that Python doesn't come preinstalled and isn't in the repositories as
well, you can easily make packages for your own distro. Have a look at the
following links:
.. seealso::
https://www.debian.org/doc/manuals/maint-guide/first.en.html
for Debian users
https://en.opensuse.org/Portal:Packaging
for OpenSuse users
https://docs.fedoraproject.org/en-US/Fedora_Draft_Documentation/0.1/html/RPM_Guide/ch-creating-rpms.html
for Fedora users
http://www.slackbook.org/html/package-management-making-packages.html
for Slackware users
On FreeBSD and OpenBSD
----------------------
* FreeBSD users, to add the package use::
pkg install python3
* OpenBSD users, to add the package use::
pkg_add -r python
pkg_add ftp://ftp.openbsd.org/pub/OpenBSD/4.2/packages/<insert your architecture here>/python-<version>.tgz
For example i386 users get the 2.5.1 version of Python using::
pkg_add ftp://ftp.openbsd.org/pub/OpenBSD/4.2/packages/i386/python-2.5.1p2.tgz
On OpenSolaris
--------------
You can get Python from `OpenCSW <https://www.opencsw.org/>`_. Various versions
of Python are available and can be installed with e.g. ``pkgutil -i python27``.
.. _building-python-on-unix:
Building Python
===============
If you want to compile CPython yourself, first thing you should do is get the
`source <https://www.python.org/downloads/source/>`_. You can download either the
latest release's source or just grab a fresh `clone
<https://docs.python.org/devguide/setup.html#getting-the-source-code>`_. (If you want
to contribute patches, you will need a clone.)
The build process consists in the usual ::
./configure
make
make install
invocations. Configuration options and caveats for specific Unix platforms are
extensively documented in the :source:`README` file in the root of the Python
source tree.
.. warning::
``make install`` can overwrite or masquerade the :file:`python` binary.
``make altinstall`` is therefore recommended instead of ``make install``
since it only installs :file:`{exec_prefix}/bin/python{version}`.
Python-related paths and files
==============================
These are subject to difference depending on local installation conventions;
:envvar:`prefix` (``${prefix}``) and :envvar:`exec_prefix` (``${exec_prefix}``)
are installation-dependent and should be interpreted as for GNU software; they
may be the same.
For example, on most Linux systems, the default for both is :file:`/usr`.
+-----------------------------------------------+------------------------------------------+
| File/directory | Meaning |
+===============================================+==========================================+
| :file:`{exec_prefix}/bin/python` | Recommended location of the interpreter. |
+-----------------------------------------------+------------------------------------------+
| :file:`{prefix}/lib/python{version}`, | Recommended locations of the directories |
| :file:`{exec_prefix}/lib/python{version}` | containing the standard modules. |
+-----------------------------------------------+------------------------------------------+
| :file:`{prefix}/include/python{version}`, | Recommended locations of the directories |
| :file:`{exec_prefix}/include/python{version}` | containing the include files needed for |
| | developing Python extensions and |
| | embedding the interpreter. |
+-----------------------------------------------+------------------------------------------+
| :file:`~/.pythonrc.py` | User-specific initialization file loaded |
| | by the user module; not used by default |
| | or by most applications. |
+-----------------------------------------------+------------------------------------------+
Miscellaneous
=============
To easily use Python scripts on Unix, you need to make them executable,
e.g. with ::
$ chmod +x script
and put an appropriate Shebang line at the top of the script. A good choice is
usually ::
#!/usr/bin/env python
which searches for the Python interpreter in the whole :envvar:`PATH`. However,
some Unices may not have the :program:`env` command, so you may need to hardcode
``/usr/bin/python`` as the interpreter path.
To use shell commands in your Python scripts, look at the :mod:`subprocess` module.
Editors and IDEs
================
There are a number of IDEs that support Python programming language.
Many editors and IDEs provide syntax highlighting, debugging tools, and :pep:`8` checks.
Please go to `Python Editors <https://wiki.python.org/moin/PythonEditors>`_ and
`Integrated Development Environments <https://wiki.python.org/moin/IntegratedDevelopmentEnvironments>`_
for a comprehensive list.PK
%�\?���3 �3 # html/_sources/using/windows.rst.txtnu �[��� .. highlightlang:: none
.. _using-on-windows:
*************************
Using Python on Windows
*************************
.. sectionauthor:: Robert Lehmann <lehmannro@gmail.com>
This document aims to give an overview of Windows-specific behaviour you should
know about when using Python on Microsoft Windows.
Installing Python
=================
Unlike most Unix systems and services, Windows does not require Python natively
and thus does not pre-install a version of Python. However, the CPython team
has compiled Windows installers (MSI packages) with every `release
<https://www.python.org/download/releases/>`_ for many years.
With ongoing development of Python, some platforms that used to be supported
earlier are no longer supported (due to the lack of users or developers).
Check :pep:`11` for details on all unsupported platforms.
* DOS and Windows 3.x are deprecated since Python 2.0 and code specific to these
systems was removed in Python 2.1.
* Up to 2.5, Python was still compatible with Windows 95, 98 and ME (but already
raised a deprecation warning on installation). For Python 2.6 (and all
following releases), this support was dropped and new releases are just
expected to work on the Windows NT family.
* `Windows CE <http://pythonce.sourceforge.net/>`_ is still supported.
* The `Cygwin <https://cygwin.com/>`_ installer offers to install the Python
interpreter as well (cf. `Cygwin package source
<ftp://ftp.uni-erlangen.de/pub/pc/gnuwin32/cygwin/mirrors/cygnus/
release/python>`_, `Maintainer releases
<http://www.tishler.net/jason/software/python/>`_)
See `Python for Windows (and DOS) <https://www.python.org/download/windows/>`_
for detailed information about platforms with precompiled installers.
.. seealso::
`Python on XP <http://dooling.com/index.php/2006/03/14/python-on-xp-7-minutes-to-hello-world/>`_
"7 Minutes to "Hello World!""
by Richard Dooling, 2006
`Installing on Windows <http://www.diveintopython.net/installing_python/windows.html>`_
in "`Dive into Python: Python from novice to pro
<http://www.diveintopython.net/>`_"
by Mark Pilgrim, 2004,
ISBN 1-59059-356-1
`For Windows users <http://python.swaroopch.com/installation.html#installation-on-windows>`_
in "Installing Python"
in "`A Byte of Python <http://python.swaroopch.com/>`_"
by Swaroop C H, 2003
Alternative bundles
===================
Besides the standard CPython distribution, there are modified packages including
additional functionality. The following is a list of popular versions and their
key features:
`ActivePython <https://www.activestate.com/activepython/>`_
Installer with multi-platform compatibility, documentation, PyWin32
`Enthought Python Distribution <https://www.enthought.com/products/epd/>`_
Popular modules (such as PyWin32) with their respective documentation, tool
suite for building extensible Python applications
Notice that these packages are likely to install *older* versions of Python.
Configuring Python
==================
In order to run Python flawlessly, you might have to change certain environment
settings in Windows.
.. _setting-envvars:
Excursus: Setting environment variables
---------------------------------------
Windows has a built-in dialog for changing environment variables (following
guide applies to XP classical view): Right-click the icon for your machine
(usually located on your Desktop and called "My Computer") and choose
:menuselection:`Properties` there. Then, open the :guilabel:`Advanced` tab
and click the :guilabel:`Environment Variables` button.
In short, your path is:
:menuselection:`My Computer
--> Properties
--> Advanced
--> Environment Variables`
In this dialog, you can add or modify User and System variables. To change
System variables, you need non-restricted access to your machine
(i.e. Administrator rights).
Another way of adding variables to your environment is using the :command:`set`
command::
set PYTHONPATH=%PYTHONPATH%;C:\My_python_lib
To make this setting permanent, you could add the corresponding command line to
your :file:`autoexec.bat`. :program:`msconfig` is a graphical interface to this
file.
Viewing environment variables can also be done more straight-forward: The
command prompt will expand strings wrapped into percent signs automatically::
echo %PATH%
Consult :command:`set /?` for details on this behaviour.
.. seealso::
https://support.microsoft.com/kb/100843
Environment variables in Windows NT
https://support.microsoft.com/kb/310519
How To Manage Environment Variables in Windows XP
https://www.chem.gla.ac.uk/~louis/software/faq/q1.html
Setting Environment variables, Louis J. Farrugia
Finding the Python executable
-----------------------------
Besides using the automatically created start menu entry for the Python
interpreter, you might want to start Python in the DOS prompt. To make this
work, you need to set your :envvar:`%PATH%` environment variable to include the
directory of your Python distribution, delimited by a semicolon from other
entries. An example variable could look like this (assuming the first two
entries are Windows' default)::
C:\WINDOWS\system32;C:\WINDOWS;C:\Python25
Typing :command:`python` on your command prompt will now fire up the Python
interpreter. Thus, you can also execute your scripts with command line options,
see :ref:`using-on-cmdline` documentation.
Finding modules
---------------
Python usually stores its library (and thereby your site-packages folder) in the
installation directory. So, if you had installed Python to
:file:`C:\\Python\\`, the default library would reside in
:file:`C:\\Python\\Lib\\` and third-party modules should be stored in
:file:`C:\\Python\\Lib\\site-packages\\`.
This is how :data:`sys.path` is populated on Windows:
* An empty entry is added at the start, which corresponds to the current
directory.
* If the environment variable :envvar:`PYTHONPATH` exists, as described in
:ref:`using-on-envvars`, its entries are added next. Note that on Windows,
paths in this variable must be separated by semicolons, to distinguish them
from the colon used in drive identifiers (``C:\`` etc.).
* Additional "application paths" can be added in the registry as subkeys of
:samp:`\\SOFTWARE\\Python\\PythonCore\\{version}\\PythonPath` under both the
``HKEY_CURRENT_USER`` and ``HKEY_LOCAL_MACHINE`` hives. Subkeys which have
semicolon-delimited path strings as their default value will cause each path
to be added to :data:`sys.path`. (Note that all known installers only use
HKLM, so HKCU is typically empty.)
* If the environment variable :envvar:`PYTHONHOME` is set, it is assumed as
"Python Home". Otherwise, the path of the main Python executable is used to
locate a "landmark file" (``Lib\os.py``) to deduce the "Python Home". If a
Python home is found, the relevant sub-directories added to :data:`sys.path`
(``Lib``, ``plat-win``, etc) are based on that folder. Otherwise, the core
Python path is constructed from the PythonPath stored in the registry.
* If the Python Home cannot be located, no :envvar:`PYTHONPATH` is specified in
the environment, and no registry entries can be found, a default path with
relative entries is used (e.g. ``.\Lib;.\plat-win``, etc).
The end result of all this is:
* When running :file:`python.exe`, or any other .exe in the main Python
directory (either an installed version, or directly from the PCbuild
directory), the core path is deduced, and the core paths in the registry are
ignored. Other "application paths" in the registry are always read.
* When Python is hosted in another .exe (different directory, embedded via COM,
etc), the "Python Home" will not be deduced, so the core path from the
registry is used. Other "application paths" in the registry are always read.
* If Python can't find its home and there is no registry (eg, frozen .exe, some
very strange installation setup) you get a path with some default, but
relative, paths.
Executing scripts
-----------------
Python scripts (files with the extension ``.py``) will be executed by
:program:`python.exe` by default. This executable opens a terminal, which stays
open even if the program uses a GUI. If you do not want this to happen, use the
extension ``.pyw`` which will cause the script to be executed by
:program:`pythonw.exe` by default (both executables are located in the top-level
of your Python installation directory). This suppresses the terminal window on
startup.
You can also make all ``.py`` scripts execute with :program:`pythonw.exe`,
setting this through the usual facilities, for example (might require
administrative rights):
#. Launch a command prompt.
#. Associate the correct file group with ``.py`` scripts::
assoc .py=Python.File
#. Redirect all Python files to the new executable::
ftype Python.File=C:\Path\to\pythonw.exe "%1" %*
Additional modules
==================
Even though Python aims to be portable among all platforms, there are features
that are unique to Windows. A couple of modules, both in the standard library
and external, and snippets exist to use these features.
The Windows-specific standard modules are documented in
:ref:`mswin-specific-services`.
PyWin32
-------
The `PyWin32 <https://pypi.org/project/pywin32>`_ module by Mark Hammond
is a collection of modules for advanced Windows-specific support. This includes
utilities for:
* `Component Object Model <https://www.microsoft.com/com/>`_ (COM)
* Win32 API calls
* Registry
* Event log
* `Microsoft Foundation Classes <https://msdn.microsoft.com/en-us/library/fe1cf721%28VS.80%29.aspx>`_ (MFC)
user interfaces
`PythonWin <https://web.archive.org/web/20060524042422/
https://www.python.org/windows/pythonwin/>`_ is a sample MFC application
shipped with PyWin32. It is an embeddable IDE with a built-in debugger.
.. seealso::
`Win32 How Do I...? <http://timgolden.me.uk/python/win32_how_do_i.html>`_
by Tim Golden
`Python and COM <http://www.boddie.org.uk/python/COM.html>`_
by David and Paul Boddie
Py2exe
------
`Py2exe <http://www.py2exe.org/>`_ is a :mod:`distutils` extension (see
:ref:`extending-distutils`) which wraps Python scripts into executable Windows
programs (:file:`{*}.exe` files). When you have done this, you can distribute
your application without requiring your users to install Python.
WConio
------
Since Python's advanced terminal handling layer, :mod:`curses`, is restricted to
Unix-like systems, there is a library exclusive to Windows as well: Windows
Console I/O for Python.
`WConio <http://newcenturycomputers.net/projects/wconio.html>`_ is a wrapper for
Turbo-C's :file:`CONIO.H`, used to create text user interfaces.
Compiling Python on Windows
===========================
If you want to compile CPython yourself, first thing you should do is get the
`source <https://www.python.org/downloads/source/>`_. You can download either the
latest release's source or just grab a fresh `checkout
<https://docs.python.org/devguide/setup.html#getting-the-source-code>`_.
For Microsoft Visual C++, which is the compiler with which official Python
releases are built, the source tree contains solutions/project files. View the
:file:`readme.txt` in their respective directories:
+--------------------+--------------+-----------------------+
| Directory | MSVC version | Visual Studio version |
+====================+==============+=======================+
| :file:`PC/VC6/` | 6.0 | 97 |
+--------------------+--------------+-----------------------+
| :file:`PC/VS7.1/` | 7.1 | 2003 |
+--------------------+--------------+-----------------------+
| :file:`PC/VS8.0/` | 8.0 | 2005 |
+--------------------+--------------+-----------------------+
| :file:`PCbuild/` | 9.0 | 2008 |
+--------------------+--------------+-----------------------+
Note that not all of these build directories are fully supported. Read the
release notes to see which compiler version the official releases for your
version are built with.
Check :file:`PC/readme.txt` for general information on the build process.
For extension modules, consult :ref:`building-on-windows`.
.. seealso::
`Python + Windows + distutils + SWIG + gcc MinGW <http://sebsauvage.net/python/mingw.html>`_
or "Creating Python extensions in C/C++ with SWIG and compiling them with
MinGW gcc under Windows" or "Installing Python extension with distutils
and without Microsoft Visual C++" by Sébastien Sauvage, 2003
`MingW -- Python extensions <http://oldwiki.mingw.org/index.php/Python%20extensions>`_
by Trent Apted et al, 2007
Other resources
===============
.. seealso::
`Python Programming On Win32 <http://shop.oreilly.com/product/9781565926219.do>`_
"Help for Windows Programmers"
by Mark Hammond and Andy Robinson, O'Reilly Media, 2000,
ISBN 1-56592-621-8
`A Python for Windows Tutorial <http://www.imladris.com/Scripts/PythonForWindows.html>`_
by Amanda Birmingham, 2004
PK
%�\5nBfJ� J� " html/_sources/whatsnew/2.0.rst.txtnu �[��� ****************************
What's New in Python 2.0
****************************
:Author: A.M. Kuchling and Moshe Zadka
.. |release| replace:: 1.02
.. $Id: whatsnew20.tex 50964 2006-07-30 03:03:43Z fred.drake $
Introduction
============
A new release of Python, version 2.0, was released on October 16, 2000. This
article covers the exciting new features in 2.0, highlights some other useful
changes, and points out a few incompatible changes that may require rewriting
code.
Python's development never completely stops between releases, and a steady flow
of bug fixes and improvements are always being submitted. A host of minor fixes,
a few optimizations, additional docstrings, and better error messages went into
2.0; to list them all would be impossible, but they're certainly significant.
Consult the publicly-available CVS logs if you want to see the full list. This
progress is due to the five developers working for PythonLabs are now getting
paid to spend their days fixing bugs, and also due to the improved communication
resulting from moving to SourceForge.
.. ======================================================================
What About Python 1.6?
======================
Python 1.6 can be thought of as the Contractual Obligations Python release.
After the core development team left CNRI in May 2000, CNRI requested that a 1.6
release be created, containing all the work on Python that had been performed at
CNRI. Python 1.6 therefore represents the state of the CVS tree as of May 2000,
with the most significant new feature being Unicode support. Development
continued after May, of course, so the 1.6 tree received a few fixes to ensure
that it's forward-compatible with Python 2.0. 1.6 is therefore part of Python's
evolution, and not a side branch.
So, should you take much interest in Python 1.6? Probably not. The 1.6final
and 2.0beta1 releases were made on the same day (September 5, 2000), the plan
being to finalize Python 2.0 within a month or so. If you have applications to
maintain, there seems little point in breaking things by moving to 1.6, fixing
them, and then having another round of breakage within a month by moving to 2.0;
you're better off just going straight to 2.0. Most of the really interesting
features described in this document are only in 2.0, because a lot of work was
done between May and September.
.. ======================================================================
New Development Process
=======================
The most important change in Python 2.0 may not be to the code at all, but to
how Python is developed: in May 2000 the Python developers began using the tools
made available by SourceForge for storing source code, tracking bug reports,
and managing the queue of patch submissions. To report bugs or submit patches
for Python 2.0, use the bug tracking and patch manager tools available from
Python's project page, located at https://sourceforge.net/projects/python/.
The most important of the services now hosted at SourceForge is the Python CVS
tree, the version-controlled repository containing the source code for Python.
Previously, there were roughly 7 or so people who had write access to the CVS
tree, and all patches had to be inspected and checked in by one of the people on
this short list. Obviously, this wasn't very scalable. By moving the CVS tree
to SourceForge, it became possible to grant write access to more people; as of
September 2000 there were 27 people able to check in changes, a fourfold
increase. This makes possible large-scale changes that wouldn't be attempted if
they'd have to be filtered through the small group of core developers. For
example, one day Peter Schneider-Kamp took it into his head to drop K&R C
compatibility and convert the C source for Python to ANSI C. After getting
approval on the python-dev mailing list, he launched into a flurry of checkins
that lasted about a week, other developers joined in to help, and the job was
done. If there were only 5 people with write access, probably that task would
have been viewed as "nice, but not worth the time and effort needed" and it
would never have gotten done.
The shift to using SourceForge's services has resulted in a remarkable increase
in the speed of development. Patches now get submitted, commented on, revised
by people other than the original submitter, and bounced back and forth between
people until the patch is deemed worth checking in. Bugs are tracked in one
central location and can be assigned to a specific person for fixing, and we can
count the number of open bugs to measure progress. This didn't come without a
cost: developers now have more e-mail to deal with, more mailing lists to
follow, and special tools had to be written for the new environment. For
example, SourceForge sends default patch and bug notification e-mail messages
that are completely unhelpful, so Ka-Ping Yee wrote an HTML screen-scraper that
sends more useful messages.
The ease of adding code caused a few initial growing pains, such as code was
checked in before it was ready or without getting clear agreement from the
developer group. The approval process that has emerged is somewhat similar to
that used by the Apache group. Developers can vote +1, +0, -0, or -1 on a patch;
+1 and -1 denote acceptance or rejection, while +0 and -0 mean the developer is
mostly indifferent to the change, though with a slight positive or negative
slant. The most significant change from the Apache model is that the voting is
essentially advisory, letting Guido van Rossum, who has Benevolent Dictator For
Life status, know what the general opinion is. He can still ignore the result of
a vote, and approve or reject a change even if the community disagrees with him.
Producing an actual patch is the last step in adding a new feature, and is
usually easy compared to the earlier task of coming up with a good design.
Discussions of new features can often explode into lengthy mailing list threads,
making the discussion hard to follow, and no one can read every posting to
python-dev. Therefore, a relatively formal process has been set up to write
Python Enhancement Proposals (PEPs), modelled on the Internet RFC process. PEPs
are draft documents that describe a proposed new feature, and are continually
revised until the community reaches a consensus, either accepting or rejecting
the proposal. Quoting from the introduction to PEP 1, "PEP Purpose and
Guidelines":
.. epigraph::
PEP stands for Python Enhancement Proposal. A PEP is a design document
providing information to the Python community, or describing a new feature for
Python. The PEP should provide a concise technical specification of the feature
and a rationale for the feature.
We intend PEPs to be the primary mechanisms for proposing new features, for
collecting community input on an issue, and for documenting the design decisions
that have gone into Python. The PEP author is responsible for building
consensus within the community and documenting dissenting opinions.
Read the rest of PEP 1 for the details of the PEP editorial process, style, and
format. PEPs are kept in the Python CVS tree on SourceForge, though they're not
part of the Python 2.0 distribution, and are also available in HTML form from
https://www.python.org/dev/peps/. As of September 2000, there are 25 PEPS, ranging
from PEP 201, "Lockstep Iteration", to PEP 225, "Elementwise/Objectwise
Operators".
.. ======================================================================
Unicode
=======
The largest new feature in Python 2.0 is a new fundamental data type: Unicode
strings. Unicode uses 16-bit numbers to represent characters instead of the
8-bit number used by ASCII, meaning that 65,536 distinct characters can be
supported.
The final interface for Unicode support was arrived at through countless
often-stormy discussions on the python-dev mailing list, and mostly implemented by
Marc-André Lemburg, based on a Unicode string type implementation by Fredrik
Lundh. A detailed explanation of the interface was written up as :pep:`100`,
"Python Unicode Integration". This article will simply cover the most
significant points about the Unicode interfaces.
In Python source code, Unicode strings are written as ``u"string"``. Arbitrary
Unicode characters can be written using a new escape sequence, ``\uHHHH``, where
*HHHH* is a 4-digit hexadecimal number from 0000 to FFFF. The existing
``\xHHHH`` escape sequence can also be used, and octal escapes can be used for
characters up to U+01FF, which is represented by ``\777``.
Unicode strings, just like regular strings, are an immutable sequence type.
They can be indexed and sliced, but not modified in place. Unicode strings have
an ``encode( [encoding] )`` method that returns an 8-bit string in the desired
encoding. Encodings are named by strings, such as ``'ascii'``, ``'utf-8'``,
``'iso-8859-1'``, or whatever. A codec API is defined for implementing and
registering new encodings that are then available throughout a Python program.
If an encoding isn't specified, the default encoding is usually 7-bit ASCII,
though it can be changed for your Python installation by calling the
``sys.setdefaultencoding(encoding)`` function in a customised version of
:file:`site.py`.
Combining 8-bit and Unicode strings always coerces to Unicode, using the default
ASCII encoding; the result of ``'a' + u'bc'`` is ``u'abc'``.
New built-in functions have been added, and existing built-ins modified to
support Unicode:
* ``unichr(ch)`` returns a Unicode string 1 character long, containing the
character *ch*.
* ``ord(u)``, where *u* is a 1-character regular or Unicode string, returns the
number of the character as an integer.
* ``unicode(string [, encoding] [, errors] )`` creates a Unicode string
from an 8-bit string. ``encoding`` is a string naming the encoding to use. The
``errors`` parameter specifies the treatment of characters that are invalid for
the current encoding; passing ``'strict'`` as the value causes an exception to
be raised on any encoding error, while ``'ignore'`` causes errors to be silently
ignored and ``'replace'`` uses U+FFFD, the official replacement character, in
case of any problems.
* The :keyword:`exec` statement, and various built-ins such as ``eval()``,
``getattr()``, and ``setattr()`` will also accept Unicode strings as well as
regular strings. (It's possible that the process of fixing this missed some
built-ins; if you find a built-in function that accepts strings but doesn't
accept Unicode strings at all, please report it as a bug.)
A new module, :mod:`unicodedata`, provides an interface to Unicode character
properties. For example, ``unicodedata.category(u'A')`` returns the 2-character
string 'Lu', the 'L' denoting it's a letter, and 'u' meaning that it's
uppercase. ``unicodedata.bidirectional(u'\u0660')`` returns 'AN', meaning that
U+0660 is an Arabic number.
The :mod:`codecs` module contains functions to look up existing encodings and
register new ones. Unless you want to implement a new encoding, you'll most
often use the ``codecs.lookup(encoding)`` function, which returns a
4-element tuple: ``(encode_func, decode_func, stream_reader, stream_writer)``.
* *encode_func* is a function that takes a Unicode string, and returns a 2-tuple
``(string, length)``. *string* is an 8-bit string containing a portion (perhaps
all) of the Unicode string converted into the given encoding, and *length* tells
you how much of the Unicode string was converted.
* *decode_func* is the opposite of *encode_func*, taking an 8-bit string and
returning a 2-tuple ``(ustring, length)``, consisting of the resulting Unicode
string *ustring* and the integer *length* telling how much of the 8-bit string
was consumed.
* *stream_reader* is a class that supports decoding input from a stream.
*stream_reader(file_obj)* returns an object that supports the :meth:`read`,
:meth:`readline`, and :meth:`readlines` methods. These methods will all
translate from the given encoding and return Unicode strings.
* *stream_writer*, similarly, is a class that supports encoding output to a
stream. *stream_writer(file_obj)* returns an object that supports the
:meth:`write` and :meth:`writelines` methods. These methods expect Unicode
strings, translating them to the given encoding on output.
For example, the following code writes a Unicode string into a file, encoding
it as UTF-8::
import codecs
unistr = u'\u0660\u2000ab ...'
(UTF8_encode, UTF8_decode,
UTF8_streamreader, UTF8_streamwriter) = codecs.lookup('UTF-8')
output = UTF8_streamwriter( open( '/tmp/output', 'wb') )
output.write( unistr )
output.close()
The following code would then read UTF-8 input from the file::
input = UTF8_streamreader( open( '/tmp/output', 'rb') )
print repr(input.read())
input.close()
Unicode-aware regular expressions are available through the :mod:`re` module,
which has a new underlying implementation called SRE written by Fredrik Lundh of
Secret Labs AB.
A ``-U`` command line option was added which causes the Python compiler to
interpret all string literals as Unicode string literals. This is intended to be
used in testing and future-proofing your Python code, since some future version
of Python may drop support for 8-bit strings and provide only Unicode strings.
.. ======================================================================
List Comprehensions
===================
Lists are a workhorse data type in Python, and many programs manipulate a list
at some point. Two common operations on lists are to loop over them, and either
pick out the elements that meet a certain criterion, or apply some function to
each element. For example, given a list of strings, you might want to pull out
all the strings containing a given substring, or strip off trailing whitespace
from each line.
The existing :func:`map` and :func:`filter` functions can be used for this
purpose, but they require a function as one of their arguments. This is fine if
there's an existing built-in function that can be passed directly, but if there
isn't, you have to create a little function to do the required work, and
Python's scoping rules make the result ugly if the little function needs
additional information. Take the first example in the previous paragraph,
finding all the strings in the list containing a given substring. You could
write the following to do it::
# Given the list L, make a list of all strings
# containing the substring S.
sublist = filter( lambda s, substring=S:
string.find(s, substring) != -1,
L)
Because of Python's scoping rules, a default argument is used so that the
anonymous function created by the :keyword:`lambda` statement knows what
substring is being searched for. List comprehensions make this cleaner::
sublist = [ s for s in L if string.find(s, S) != -1 ]
List comprehensions have the form::
[ expression for expr in sequence1
for expr2 in sequence2 ...
for exprN in sequenceN
if condition ]
The :keyword:`for`...\ :keyword:`in` clauses contain the sequences to be
iterated over. The sequences do not have to be the same length, because they
are *not* iterated over in parallel, but from left to right; this is explained
more clearly in the following paragraphs. The elements of the generated list
will be the successive values of *expression*. The final :keyword:`if` clause
is optional; if present, *expression* is only evaluated and added to the result
if *condition* is true.
To make the semantics very clear, a list comprehension is equivalent to the
following Python code::
for expr1 in sequence1:
for expr2 in sequence2:
...
for exprN in sequenceN:
if (condition):
# Append the value of
# the expression to the
# resulting list.
This means that when there are multiple :keyword:`for`...\ :keyword:`in`
clauses, the resulting list will be equal to the product of the lengths of all
the sequences. If you have two lists of length 3, the output list is 9 elements
long::
seq1 = 'abc'
seq2 = (1,2,3)
>>> [ (x,y) for x in seq1 for y in seq2]
[('a', 1), ('a', 2), ('a', 3), ('b', 1), ('b', 2), ('b', 3), ('c', 1),
('c', 2), ('c', 3)]
To avoid introducing an ambiguity into Python's grammar, if *expression* is
creating a tuple, it must be surrounded with parentheses. The first list
comprehension below is a syntax error, while the second one is correct::
# Syntax error
[ x,y for x in seq1 for y in seq2]
# Correct
[ (x,y) for x in seq1 for y in seq2]
The idea of list comprehensions originally comes from the functional programming
language Haskell (https://www.haskell.org). Greg Ewing argued most effectively
for adding them to Python and wrote the initial list comprehension patch, which
was then discussed for a seemingly endless time on the python-dev mailing list
and kept up-to-date by Skip Montanaro.
.. ======================================================================
Augmented Assignment
====================
Augmented assignment operators, another long-requested feature, have been added
to Python 2.0. Augmented assignment operators include ``+=``, ``-=``, ``*=``,
and so forth. For example, the statement ``a += 2`` increments the value of the
variable ``a`` by 2, equivalent to the slightly lengthier ``a = a + 2``.
The full list of supported assignment operators is ``+=``, ``-=``, ``*=``,
``/=``, ``%=``, ``**=``, ``&=``, ``|=``, ``^=``, ``>>=``, and ``<<=``. Python
classes can override the augmented assignment operators by defining methods
named :meth:`__iadd__`, :meth:`__isub__`, etc. For example, the following
:class:`Number` class stores a number and supports using += to create a new
instance with an incremented value.
.. The empty groups below prevent conversion to guillemets.
::
class Number:
def __init__(self, value):
self.value = value
def __iadd__(self, increment):
return Number( self.value + increment)
n = Number(5)
n += 3
print n.value
The :meth:`__iadd__` special method is called with the value of the increment,
and should return a new instance with an appropriately modified value; this
return value is bound as the new value of the variable on the left-hand side.
Augmented assignment operators were first introduced in the C programming
language, and most C-derived languages, such as :program:`awk`, C++, Java, Perl,
and PHP also support them. The augmented assignment patch was implemented by
Thomas Wouters.
.. ======================================================================
String Methods
==============
Until now string-manipulation functionality was in the :mod:`string` module,
which was usually a front-end for the :mod:`strop` module written in C. The
addition of Unicode posed a difficulty for the :mod:`strop` module, because the
functions would all need to be rewritten in order to accept either 8-bit or
Unicode strings. For functions such as :func:`string.replace`, which takes 3
string arguments, that means eight possible permutations, and correspondingly
complicated code.
Instead, Python 2.0 pushes the problem onto the string type, making string
manipulation functionality available through methods on both 8-bit strings and
Unicode strings. ::
>>> 'andrew'.capitalize()
'Andrew'
>>> 'hostname'.replace('os', 'linux')
'hlinuxtname'
>>> 'moshe'.find('sh')
2
One thing that hasn't changed, a noteworthy April Fools' joke notwithstanding,
is that Python strings are immutable. Thus, the string methods return new
strings, and do not modify the string on which they operate.
The old :mod:`string` module is still around for backwards compatibility, but it
mostly acts as a front-end to the new string methods.
Two methods which have no parallel in pre-2.0 versions, although they did exist
in JPython for quite some time, are :meth:`startswith` and :meth:`endswith`.
``s.startswith(t)`` is equivalent to ``s[:len(t)] == t``, while
``s.endswith(t)`` is equivalent to ``s[-len(t):] == t``.
One other method which deserves special mention is :meth:`join`. The
:meth:`join` method of a string receives one parameter, a sequence of strings,
and is equivalent to the :func:`string.join` function from the old :mod:`string`
module, with the arguments reversed. In other words, ``s.join(seq)`` is
equivalent to the old ``string.join(seq, s)``.
.. ======================================================================
Garbage Collection of Cycles
============================
The C implementation of Python uses reference counting to implement garbage
collection. Every Python object maintains a count of the number of references
pointing to itself, and adjusts the count as references are created or
destroyed. Once the reference count reaches zero, the object is no longer
accessible, since you need to have a reference to an object to access it, and if
the count is zero, no references exist any longer.
Reference counting has some pleasant properties: it's easy to understand and
implement, and the resulting implementation is portable, fairly fast, and reacts
well with other libraries that implement their own memory handling schemes. The
major problem with reference counting is that it sometimes doesn't realise that
objects are no longer accessible, resulting in a memory leak. This happens when
there are cycles of references.
Consider the simplest possible cycle, a class instance which has a reference to
itself::
instance = SomeClass()
instance.myself = instance
After the above two lines of code have been executed, the reference count of
``instance`` is 2; one reference is from the variable named ``'instance'``, and
the other is from the ``myself`` attribute of the instance.
If the next line of code is ``del instance``, what happens? The reference count
of ``instance`` is decreased by 1, so it has a reference count of 1; the
reference in the ``myself`` attribute still exists. Yet the instance is no
longer accessible through Python code, and it could be deleted. Several objects
can participate in a cycle if they have references to each other, causing all of
the objects to be leaked.
Python 2.0 fixes this problem by periodically executing a cycle detection
algorithm which looks for inaccessible cycles and deletes the objects involved.
A new :mod:`gc` module provides functions to perform a garbage collection,
obtain debugging statistics, and tuning the collector's parameters.
Running the cycle detection algorithm takes some time, and therefore will result
in some additional overhead. It is hoped that after we've gotten experience
with the cycle collection from using 2.0, Python 2.1 will be able to minimize
the overhead with careful tuning. It's not yet obvious how much performance is
lost, because benchmarking this is tricky and depends crucially on how often the
program creates and destroys objects. The detection of cycles can be disabled
when Python is compiled, if you can't afford even a tiny speed penalty or
suspect that the cycle collection is buggy, by specifying the
:option:`!--without-cycle-gc` switch when running the :program:`configure`
script.
Several people tackled this problem and contributed to a solution. An early
implementation of the cycle detection approach was written by Toby Kelsey. The
current algorithm was suggested by Eric Tiedemann during a visit to CNRI, and
Guido van Rossum and Neil Schemenauer wrote two different implementations, which
were later integrated by Neil. Lots of other people offered suggestions along
the way; the March 2000 archives of the python-dev mailing list contain most of
the relevant discussion, especially in the threads titled "Reference cycle
collection for Python" and "Finalization again".
.. ======================================================================
Other Core Changes
==================
Various minor changes have been made to Python's syntax and built-in functions.
None of the changes are very far-reaching, but they're handy conveniences.
Minor Language Changes
----------------------
A new syntax makes it more convenient to call a given function with a tuple of
arguments and/or a dictionary of keyword arguments. In Python 1.5 and earlier,
you'd use the :func:`apply` built-in function: ``apply(f, args, kw)`` calls the
function :func:`f` with the argument tuple *args* and the keyword arguments in
the dictionary *kw*. :func:`apply` is the same in 2.0, but thanks to a patch
from Greg Ewing, ``f(*args, **kw)`` is a shorter and clearer way to achieve the
same effect. This syntax is symmetrical with the syntax for defining
functions::
def f(*args, **kw):
# args is a tuple of positional args,
# kw is a dictionary of keyword args
...
The :keyword:`print` statement can now have its output directed to a file-like
object by following the :keyword:`print` with ``>> file``, similar to the
redirection operator in Unix shells. Previously you'd either have to use the
:meth:`write` method of the file-like object, which lacks the convenience and
simplicity of :keyword:`print`, or you could assign a new value to
``sys.stdout`` and then restore the old value. For sending output to standard
error, it's much easier to write this::
print >> sys.stderr, "Warning: action field not supplied"
Modules can now be renamed on importing them, using the syntax ``import module
as name`` or ``from module import name as othername``. The patch was submitted
by Thomas Wouters.
A new format style is available when using the ``%`` operator; '%r' will insert
the :func:`repr` of its argument. This was also added from symmetry
considerations, this time for symmetry with the existing '%s' format style,
which inserts the :func:`str` of its argument. For example, ``'%r %s' % ('abc',
'abc')`` returns a string containing ``'abc' abc``.
Previously there was no way to implement a class that overrode Python's built-in
:keyword:`in` operator and implemented a custom version. ``obj in seq`` returns
true if *obj* is present in the sequence *seq*; Python computes this by simply
trying every index of the sequence until either *obj* is found or an
:exc:`IndexError` is encountered. Moshe Zadka contributed a patch which adds a
:meth:`__contains__` magic method for providing a custom implementation for
:keyword:`in`. Additionally, new built-in objects written in C can define what
:keyword:`in` means for them via a new slot in the sequence protocol.
Earlier versions of Python used a recursive algorithm for deleting objects.
Deeply nested data structures could cause the interpreter to fill up the C stack
and crash; Christian Tismer rewrote the deletion logic to fix this problem. On
a related note, comparing recursive objects recursed infinitely and crashed;
Jeremy Hylton rewrote the code to no longer crash, producing a useful result
instead. For example, after this code::
a = []
b = []
a.append(a)
b.append(b)
The comparison ``a==b`` returns true, because the two recursive data structures
are isomorphic. See the thread "trashcan and PR#7" in the April 2000 archives of
the python-dev mailing list for the discussion leading up to this
implementation, and some useful relevant links. Note that comparisons can now
also raise exceptions. In earlier versions of Python, a comparison operation
such as ``cmp(a,b)`` would always produce an answer, even if a user-defined
:meth:`__cmp__` method encountered an error, since the resulting exception would
simply be silently swallowed.
.. Starting URL:
.. https://www.python.org/pipermail/python-dev/2000-April/004834.html
Work has been done on porting Python to 64-bit Windows on the Itanium processor,
mostly by Trent Mick of ActiveState. (Confusingly, ``sys.platform`` is still
``'win32'`` on Win64 because it seems that for ease of porting, MS Visual C++
treats code as 32 bit on Itanium.) PythonWin also supports Windows CE; see the
Python CE page at http://pythonce.sourceforge.net/ for more information.
Another new platform is Darwin/MacOS X; initial support for it is in Python 2.0.
Dynamic loading works, if you specify "configure --with-dyld --with-suffix=.x".
Consult the README in the Python source distribution for more instructions.
An attempt has been made to alleviate one of Python's warts, the often-confusing
:exc:`NameError` exception when code refers to a local variable before the
variable has been assigned a value. For example, the following code raises an
exception on the :keyword:`print` statement in both 1.5.2 and 2.0; in 1.5.2 a
:exc:`NameError` exception is raised, while 2.0 raises a new
:exc:`UnboundLocalError` exception. :exc:`UnboundLocalError` is a subclass of
:exc:`NameError`, so any existing code that expects :exc:`NameError` to be
raised should still work. ::
def f():
print "i=",i
i = i + 1
f()
Two new exceptions, :exc:`TabError` and :exc:`IndentationError`, have been
introduced. They're both subclasses of :exc:`SyntaxError`, and are raised when
Python code is found to be improperly indented.
Changes to Built-in Functions
-----------------------------
A new built-in, ``zip(seq1, seq2, ...)``, has been added. :func:`zip`
returns a list of tuples where each tuple contains the i-th element from each of
the argument sequences. The difference between :func:`zip` and ``map(None,
seq1, seq2)`` is that :func:`map` pads the sequences with ``None`` if the
sequences aren't all of the same length, while :func:`zip` truncates the
returned list to the length of the shortest argument sequence.
The :func:`int` and :func:`long` functions now accept an optional "base"
parameter when the first argument is a string. ``int('123', 10)`` returns 123,
while ``int('123', 16)`` returns 291. ``int(123, 16)`` raises a
:exc:`TypeError` exception with the message "can't convert non-string with
explicit base".
A new variable holding more detailed version information has been added to the
:mod:`sys` module. ``sys.version_info`` is a tuple ``(major, minor, micro,
level, serial)`` For example, in a hypothetical 2.0.1beta1, ``sys.version_info``
would be ``(2, 0, 1, 'beta', 1)``. *level* is a string such as ``"alpha"``,
``"beta"``, or ``"final"`` for a final release.
Dictionaries have an odd new method, ``setdefault(key, default)``, which
behaves similarly to the existing :meth:`get` method. However, if the key is
missing, :meth:`setdefault` both returns the value of *default* as :meth:`get`
would do, and also inserts it into the dictionary as the value for *key*. Thus,
the following lines of code::
if dict.has_key( key ): return dict[key]
else:
dict[key] = []
return dict[key]
can be reduced to a single ``return dict.setdefault(key, [])`` statement.
The interpreter sets a maximum recursion depth in order to catch runaway
recursion before filling the C stack and causing a core dump or GPF..
Previously this limit was fixed when you compiled Python, but in 2.0 the maximum
recursion depth can be read and modified using :func:`sys.getrecursionlimit` and
:func:`sys.setrecursionlimit`. The default value is 1000, and a rough maximum
value for a given platform can be found by running a new script,
:file:`Misc/find_recursionlimit.py`.
.. ======================================================================
Porting to 2.0
==============
New Python releases try hard to be compatible with previous releases, and the
record has been pretty good. However, some changes are considered useful
enough, usually because they fix initial design decisions that turned out to be
actively mistaken, that breaking backward compatibility can't always be avoided.
This section lists the changes in Python 2.0 that may cause old Python code to
break.
The change which will probably break the most code is tightening up the
arguments accepted by some methods. Some methods would take multiple arguments
and treat them as a tuple, particularly various list methods such as
:meth:`append` and :meth:`insert`. In earlier versions of Python, if ``L`` is
a list, ``L.append( 1,2 )`` appends the tuple ``(1,2)`` to the list. In Python
2.0 this causes a :exc:`TypeError` exception to be raised, with the message:
'append requires exactly 1 argument; 2 given'. The fix is to simply add an
extra set of parentheses to pass both values as a tuple: ``L.append( (1,2) )``.
The earlier versions of these methods were more forgiving because they used an
old function in Python's C interface to parse their arguments; 2.0 modernizes
them to use :func:`PyArg_ParseTuple`, the current argument parsing function,
which provides more helpful error messages and treats multi-argument calls as
errors. If you absolutely must use 2.0 but can't fix your code, you can edit
:file:`Objects/listobject.c` and define the preprocessor symbol
``NO_STRICT_LIST_APPEND`` to preserve the old behaviour; this isn't recommended.
Some of the functions in the :mod:`socket` module are still forgiving in this
way. For example, :func:`socket.connect( ('hostname', 25) )` is the correct
form, passing a tuple representing an IP address, but :func:`socket.connect(
'hostname', 25 )` also works. :func:`socket.connect_ex` and :func:`socket.bind`
are similarly easy-going. 2.0alpha1 tightened these functions up, but because
the documentation actually used the erroneous multiple argument form, many
people wrote code which would break with the stricter checking. GvR backed out
the changes in the face of public reaction, so for the :mod:`socket` module, the
documentation was fixed and the multiple argument form is simply marked as
deprecated; it *will* be tightened up again in a future Python version.
The ``\x`` escape in string literals now takes exactly 2 hex digits. Previously
it would consume all the hex digits following the 'x' and take the lowest 8 bits
of the result, so ``\x123456`` was equivalent to ``\x56``.
The :exc:`AttributeError` and :exc:`NameError` exceptions have a more friendly
error message, whose text will be something like ``'Spam' instance has no
attribute 'eggs'`` or ``name 'eggs' is not defined``. Previously the error
message was just the missing attribute name ``eggs``, and code written to take
advantage of this fact will break in 2.0.
Some work has been done to make integers and long integers a bit more
interchangeable. In 1.5.2, large-file support was added for Solaris, to allow
reading files larger than 2 GiB; this made the :meth:`tell` method of file
objects return a long integer instead of a regular integer. Some code would
subtract two file offsets and attempt to use the result to multiply a sequence
or slice a string, but this raised a :exc:`TypeError`. In 2.0, long integers
can be used to multiply or slice a sequence, and it'll behave as you'd
intuitively expect it to; ``3L * 'abc'`` produces 'abcabcabc', and
``(0,1,2,3)[2L:4L]`` produces (2,3). Long integers can also be used in various
contexts where previously only integers were accepted, such as in the
:meth:`seek` method of file objects, and in the formats supported by the ``%``
operator (``%d``, ``%i``, ``%x``, etc.). For example, ``"%d" % 2L**64`` will
produce the string ``18446744073709551616``.
The subtlest long integer change of all is that the :func:`str` of a long
integer no longer has a trailing 'L' character, though :func:`repr` still
includes it. The 'L' annoyed many people who wanted to print long integers that
looked just like regular integers, since they had to go out of their way to chop
off the character. This is no longer a problem in 2.0, but code which does
``str(longval)[:-1]`` and assumes the 'L' is there, will now lose the final
digit.
Taking the :func:`repr` of a float now uses a different formatting precision
than :func:`str`. :func:`repr` uses ``%.17g`` format string for C's
:func:`sprintf`, while :func:`str` uses ``%.12g`` as before. The effect is that
:func:`repr` may occasionally show more decimal places than :func:`str`, for
certain numbers. For example, the number 8.1 can't be represented exactly in
binary, so ``repr(8.1)`` is ``'8.0999999999999996'``, while str(8.1) is
``'8.1'``.
The ``-X`` command-line option, which turned all standard exceptions into
strings instead of classes, has been removed; the standard exceptions will now
always be classes. The :mod:`exceptions` module containing the standard
exceptions was translated from Python to a built-in C module, written by Barry
Warsaw and Fredrik Lundh.
.. Commented out for now -- I don't think anyone will care.
The pattern and match objects provided by SRE are C types, not Python
class instances as in 1.5. This means you can no longer inherit from
\class{RegexObject} or \class{MatchObject}, but that shouldn't be much
of a problem since no one should have been doing that in the first
place.
.. ======================================================================
Extending/Embedding Changes
===========================
Some of the changes are under the covers, and will only be apparent to people
writing C extension modules or embedding a Python interpreter in a larger
application. If you aren't dealing with Python's C API, you can safely skip
this section.
The version number of the Python C API was incremented, so C extensions compiled
for 1.5.2 must be recompiled in order to work with 2.0. On Windows, it's not
possible for Python 2.0 to import a third party extension built for Python 1.5.x
due to how Windows DLLs work, so Python will raise an exception and the import
will fail.
Users of Jim Fulton's ExtensionClass module will be pleased to find out that
hooks have been added so that ExtensionClasses are now supported by
:func:`isinstance` and :func:`issubclass`. This means you no longer have to
remember to write code such as ``if type(obj) == myExtensionClass``, but can use
the more natural ``if isinstance(obj, myExtensionClass)``.
The :file:`Python/importdl.c` file, which was a mass of #ifdefs to support
dynamic loading on many different platforms, was cleaned up and reorganised by
Greg Stein. :file:`importdl.c` is now quite small, and platform-specific code
has been moved into a bunch of :file:`Python/dynload_\*.c` files. Another
cleanup: there were also a number of :file:`my\*.h` files in the Include/
directory that held various portability hacks; they've been merged into a single
file, :file:`Include/pyport.h`.
Vladimir Marangozov's long-awaited malloc restructuring was completed, to make
it easy to have the Python interpreter use a custom allocator instead of C's
standard :func:`malloc`. For documentation, read the comments in
:file:`Include/pymem.h` and :file:`Include/objimpl.h`. For the lengthy
discussions during which the interface was hammered out, see the Web archives of
the 'patches' and 'python-dev' lists at python.org.
Recent versions of the GUSI development environment for MacOS support POSIX
threads. Therefore, Python's POSIX threading support now works on the
Macintosh. Threading support using the user-space GNU ``pth`` library was also
contributed.
Threading support on Windows was enhanced, too. Windows supports thread locks
that use kernel objects only in case of contention; in the common case when
there's no contention, they use simpler functions which are an order of
magnitude faster. A threaded version of Python 1.5.2 on NT is twice as slow as
an unthreaded version; with the 2.0 changes, the difference is only 10%. These
improvements were contributed by Yakov Markovitch.
Python 2.0's source now uses only ANSI C prototypes, so compiling Python now
requires an ANSI C compiler, and can no longer be done using a compiler that
only supports K&R C.
Previously the Python virtual machine used 16-bit numbers in its bytecode,
limiting the size of source files. In particular, this affected the maximum
size of literal lists and dictionaries in Python source; occasionally people who
are generating Python code would run into this limit. A patch by Charles G.
Waldman raises the limit from ``2^16`` to ``2^{32}``.
Three new convenience functions intended for adding constants to a module's
dictionary at module initialization time were added: :func:`PyModule_AddObject`,
:func:`PyModule_AddIntConstant`, and :func:`PyModule_AddStringConstant`. Each
of these functions takes a module object, a null-terminated C string containing
the name to be added, and a third argument for the value to be assigned to the
name. This third argument is, respectively, a Python object, a C long, or a C
string.
A wrapper API was added for Unix-style signal handlers. :func:`PyOS_getsig` gets
a signal handler and :func:`PyOS_setsig` will set a new handler.
.. ======================================================================
Distutils: Making Modules Easy to Install
=========================================
Before Python 2.0, installing modules was a tedious affair -- there was no way
to figure out automatically where Python is installed, or what compiler options
to use for extension modules. Software authors had to go through an arduous
ritual of editing Makefiles and configuration files, which only really work on
Unix and leave Windows and MacOS unsupported. Python users faced wildly
differing installation instructions which varied between different extension
packages, which made administering a Python installation something of a chore.
The SIG for distribution utilities, shepherded by Greg Ward, has created the
Distutils, a system to make package installation much easier. They form the
:mod:`distutils` package, a new part of Python's standard library. In the best
case, installing a Python module from source will require the same steps: first
you simply mean unpack the tarball or zip archive, and the run "``python
setup.py install``". The platform will be automatically detected, the compiler
will be recognized, C extension modules will be compiled, and the distribution
installed into the proper directory. Optional command-line arguments provide
more control over the installation process, the distutils package offers many
places to override defaults -- separating the build from the install, building
or installing in non-default directories, and more.
In order to use the Distutils, you need to write a :file:`setup.py` script. For
the simple case, when the software contains only .py files, a minimal
:file:`setup.py` can be just a few lines long::
from distutils.core import setup
setup (name = "foo", version = "1.0",
py_modules = ["module1", "module2"])
The :file:`setup.py` file isn't much more complicated if the software consists
of a few packages::
from distutils.core import setup
setup (name = "foo", version = "1.0",
packages = ["package", "package.subpackage"])
A C extension can be the most complicated case; here's an example taken from
the PyXML package::
from distutils.core import setup, Extension
expat_extension = Extension('xml.parsers.pyexpat',
define_macros = [('XML_NS', None)],
include_dirs = [ 'extensions/expat/xmltok',
'extensions/expat/xmlparse' ],
sources = [ 'extensions/pyexpat.c',
'extensions/expat/xmltok/xmltok.c',
'extensions/expat/xmltok/xmlrole.c', ]
)
setup (name = "PyXML", version = "0.5.4",
ext_modules =[ expat_extension ] )
The Distutils can also take care of creating source and binary distributions.
The "sdist" command, run by "``python setup.py sdist``', builds a source
distribution such as :file:`foo-1.0.tar.gz`. Adding new commands isn't
difficult, "bdist_rpm" and "bdist_wininst" commands have already been
contributed to create an RPM distribution and a Windows installer for the
software, respectively. Commands to create other distribution formats such as
Debian packages and Solaris :file:`.pkg` files are in various stages of
development.
All this is documented in a new manual, *Distributing Python Modules*, that
joins the basic set of Python documentation.
.. ======================================================================
XML Modules
===========
Python 1.5.2 included a simple XML parser in the form of the :mod:`xmllib`
module, contributed by Sjoerd Mullender. Since 1.5.2's release, two different
interfaces for processing XML have become common: SAX2 (version 2 of the Simple
API for XML) provides an event-driven interface with some similarities to
:mod:`xmllib`, and the DOM (Document Object Model) provides a tree-based
interface, transforming an XML document into a tree of nodes that can be
traversed and modified. Python 2.0 includes a SAX2 interface and a stripped-down
DOM interface as part of the :mod:`xml` package. Here we will give a brief
overview of these new interfaces; consult the Python documentation or the source
code for complete details. The Python XML SIG is also working on improved
documentation.
SAX2 Support
------------
SAX defines an event-driven interface for parsing XML. To use SAX, you must
write a SAX handler class. Handler classes inherit from various classes
provided by SAX, and override various methods that will then be called by the
XML parser. For example, the :meth:`startElement` and :meth:`endElement`
methods are called for every starting and end tag encountered by the parser, the
:meth:`characters` method is called for every chunk of character data, and so
forth.
The advantage of the event-driven approach is that the whole document doesn't
have to be resident in memory at any one time, which matters if you are
processing really huge documents. However, writing the SAX handler class can
get very complicated if you're trying to modify the document structure in some
elaborate way.
For example, this little example program defines a handler that prints a message
for every starting and ending tag, and then parses the file :file:`hamlet.xml`
using it::
from xml import sax
class SimpleHandler(sax.ContentHandler):
def startElement(self, name, attrs):
print 'Start of element:', name, attrs.keys()
def endElement(self, name):
print 'End of element:', name
# Create a parser object
parser = sax.make_parser()
# Tell it what handler to use
handler = SimpleHandler()
parser.setContentHandler( handler )
# Parse a file!
parser.parse( 'hamlet.xml' )
For more information, consult the Python documentation, or the XML HOWTO at
http://pyxml.sourceforge.net/topics/howto/xml-howto.html.
DOM Support
-----------
The Document Object Model is a tree-based representation for an XML document. A
top-level :class:`Document` instance is the root of the tree, and has a single
child which is the top-level :class:`Element` instance. This :class:`Element`
has children nodes representing character data and any sub-elements, which may
have further children of their own, and so forth. Using the DOM you can
traverse the resulting tree any way you like, access element and attribute
values, insert and delete nodes, and convert the tree back into XML.
The DOM is useful for modifying XML documents, because you can create a DOM
tree, modify it by adding new nodes or rearranging subtrees, and then produce a
new XML document as output. You can also construct a DOM tree manually and
convert it to XML, which can be a more flexible way of producing XML output than
simply writing ``<tag1>``...\ ``</tag1>`` to a file.
The DOM implementation included with Python lives in the :mod:`xml.dom.minidom`
module. It's a lightweight implementation of the Level 1 DOM with support for
XML namespaces. The :func:`parse` and :func:`parseString` convenience
functions are provided for generating a DOM tree::
from xml.dom import minidom
doc = minidom.parse('hamlet.xml')
``doc`` is a :class:`Document` instance. :class:`Document`, like all the other
DOM classes such as :class:`Element` and :class:`Text`, is a subclass of the
:class:`Node` base class. All the nodes in a DOM tree therefore support certain
common methods, such as :meth:`toxml` which returns a string containing the XML
representation of the node and its children. Each class also has special
methods of its own; for example, :class:`Element` and :class:`Document`
instances have a method to find all child elements with a given tag name.
Continuing from the previous 2-line example::
perslist = doc.getElementsByTagName( 'PERSONA' )
print perslist[0].toxml()
print perslist[1].toxml()
For the *Hamlet* XML file, the above few lines output::
<PERSONA>CLAUDIUS, king of Denmark. </PERSONA>
<PERSONA>HAMLET, son to the late, and nephew to the present king.</PERSONA>
The root element of the document is available as ``doc.documentElement``, and
its children can be easily modified by deleting, adding, or removing nodes::
root = doc.documentElement
# Remove the first child
root.removeChild( root.childNodes[0] )
# Move the new first child to the end
root.appendChild( root.childNodes[0] )
# Insert the new first child (originally,
# the third child) before the 20th child.
root.insertBefore( root.childNodes[0], root.childNodes[20] )
Again, I will refer you to the Python documentation for a complete listing of
the different :class:`Node` classes and their various methods.
Relationship to PyXML
---------------------
The XML Special Interest Group has been working on XML-related Python code for a
while. Its code distribution, called PyXML, is available from the SIG's Web
pages at https://www.python.org/community/sigs/current/xml-sig. The PyXML distribution also used
the package name ``xml``. If you've written programs that used PyXML, you're
probably wondering about its compatibility with the 2.0 :mod:`xml` package.
The answer is that Python 2.0's :mod:`xml` package isn't compatible with PyXML,
but can be made compatible by installing a recent version PyXML. Many
applications can get by with the XML support that is included with Python 2.0,
but more complicated applications will require that the full PyXML package will
be installed. When installed, PyXML versions 0.6.0 or greater will replace the
:mod:`xml` package shipped with Python, and will be a strict superset of the
standard package, adding a bunch of additional features. Some of the additional
features in PyXML include:
* 4DOM, a full DOM implementation from FourThought, Inc.
* The xmlproc validating parser, written by Lars Marius Garshol.
* The :mod:`sgmlop` parser accelerator module, written by Fredrik Lundh.
.. ======================================================================
Module changes
==============
Lots of improvements and bugfixes were made to Python's extensive standard
library; some of the affected modules include :mod:`readline`,
:mod:`ConfigParser`, :mod:`cgi`, :mod:`calendar`, :mod:`posix`, :mod:`readline`,
:mod:`xmllib`, :mod:`aifc`, :mod:`chunk, wave`, :mod:`random`, :mod:`shelve`,
and :mod:`nntplib`. Consult the CVS logs for the exact patch-by-patch details.
Brian Gallew contributed OpenSSL support for the :mod:`socket` module. OpenSSL
is an implementation of the Secure Socket Layer, which encrypts the data being
sent over a socket. When compiling Python, you can edit :file:`Modules/Setup`
to include SSL support, which adds an additional function to the :mod:`socket`
module: ``socket.ssl(socket, keyfile, certfile)``, which takes a socket
object and returns an SSL socket. The :mod:`httplib` and :mod:`urllib` modules
were also changed to support ``https://`` URLs, though no one has implemented
FTP or SMTP over SSL.
The :mod:`httplib` module has been rewritten by Greg Stein to support HTTP/1.1.
Backward compatibility with the 1.5 version of :mod:`httplib` is provided,
though using HTTP/1.1 features such as pipelining will require rewriting code to
use a different set of interfaces.
The :mod:`Tkinter` module now supports Tcl/Tk version 8.1, 8.2, or 8.3, and
support for the older 7.x versions has been dropped. The Tkinter module now
supports displaying Unicode strings in Tk widgets. Also, Fredrik Lundh
contributed an optimization which makes operations like ``create_line`` and
``create_polygon`` much faster, especially when using lots of coordinates.
The :mod:`curses` module has been greatly extended, starting from Oliver
Andrich's enhanced version, to provide many additional functions from ncurses
and SYSV curses, such as colour, alternative character set support, pads, and
mouse support. This means the module is no longer compatible with operating
systems that only have BSD curses, but there don't seem to be any currently
maintained OSes that fall into this category.
As mentioned in the earlier discussion of 2.0's Unicode support, the underlying
implementation of the regular expressions provided by the :mod:`re` module has
been changed. SRE, a new regular expression engine written by Fredrik Lundh and
partially funded by Hewlett Packard, supports matching against both 8-bit
strings and Unicode strings.
.. ======================================================================
New modules
===========
A number of new modules were added. We'll simply list them with brief
descriptions; consult the 2.0 documentation for the details of a particular
module.
* :mod:`atexit`: For registering functions to be called before the Python
interpreter exits. Code that currently sets ``sys.exitfunc`` directly should be
changed to use the :mod:`atexit` module instead, importing :mod:`atexit` and
calling :func:`atexit.register` with the function to be called on exit.
(Contributed by Skip Montanaro.)
* :mod:`codecs`, :mod:`encodings`, :mod:`unicodedata`: Added as part of the new
Unicode support.
* :mod:`filecmp`: Supersedes the old :mod:`cmp`, :mod:`cmpcache` and
:mod:`dircmp` modules, which have now become deprecated. (Contributed by Gordon
MacMillan and Moshe Zadka.)
* :mod:`gettext`: This module provides internationalization (I18N) and
localization (L10N) support for Python programs by providing an interface to the
GNU gettext message catalog library. (Integrated by Barry Warsaw, from separate
contributions by Martin von Löwis, Peter Funk, and James Henstridge.)
* :mod:`linuxaudiodev`: Support for the :file:`/dev/audio` device on Linux, a
twin to the existing :mod:`sunaudiodev` module. (Contributed by Peter Bosch,
with fixes by Jeremy Hylton.)
* :mod:`mmap`: An interface to memory-mapped files on both Windows and Unix. A
file's contents can be mapped directly into memory, at which point it behaves
like a mutable string, so its contents can be read and modified. They can even
be passed to functions that expect ordinary strings, such as the :mod:`re`
module. (Contributed by Sam Rushing, with some extensions by A.M. Kuchling.)
* :mod:`pyexpat`: An interface to the Expat XML parser. (Contributed by Paul
Prescod.)
* :mod:`robotparser`: Parse a :file:`robots.txt` file, which is used for writing
Web spiders that politely avoid certain areas of a Web site. The parser accepts
the contents of a :file:`robots.txt` file, builds a set of rules from it, and
can then answer questions about the fetchability of a given URL. (Contributed
by Skip Montanaro.)
* :mod:`tabnanny`: A module/script to check Python source code for ambiguous
indentation. (Contributed by Tim Peters.)
* :mod:`UserString`: A base class useful for deriving objects that behave like
strings.
* :mod:`webbrowser`: A module that provides a platform independent way to launch
a web browser on a specific URL. For each platform, various browsers are tried
in a specific order. The user can alter which browser is launched by setting the
*BROWSER* environment variable. (Originally inspired by Eric S. Raymond's patch
to :mod:`urllib` which added similar functionality, but the final module comes
from code originally implemented by Fred Drake as
:file:`Tools/idle/BrowserControl.py`, and adapted for the standard library by
Fred.)
* :mod:`_winreg`: An interface to the Windows registry. :mod:`_winreg` is an
adaptation of functions that have been part of PythonWin since 1995, but has now
been added to the core distribution, and enhanced to support Unicode.
:mod:`_winreg` was written by Bill Tutt and Mark Hammond.
* :mod:`zipfile`: A module for reading and writing ZIP-format archives. These
are archives produced by :program:`PKZIP` on DOS/Windows or :program:`zip` on
Unix, not to be confused with :program:`gzip`\ -format files (which are
supported by the :mod:`gzip` module) (Contributed by James C. Ahlstrom.)
* :mod:`imputil`: A module that provides a simpler way for writing customised
import hooks, in comparison to the existing :mod:`ihooks` module. (Implemented
by Greg Stein, with much discussion on python-dev along the way.)
.. ======================================================================
IDLE Improvements
=================
IDLE is the official Python cross-platform IDE, written using Tkinter. Python
2.0 includes IDLE 0.6, which adds a number of new features and improvements. A
partial list:
* UI improvements and optimizations, especially in the area of syntax
highlighting and auto-indentation.
* The class browser now shows more information, such as the top level functions
in a module.
* Tab width is now a user settable option. When opening an existing Python file,
IDLE automatically detects the indentation conventions, and adapts.
* There is now support for calling browsers on various platforms, used to open
the Python documentation in a browser.
* IDLE now has a command line, which is largely similar to the vanilla Python
interpreter.
* Call tips were added in many places.
* IDLE can now be installed as a package.
* In the editor window, there is now a line/column bar at the bottom.
* Three new keystroke commands: Check module (:kbd:`Alt-F5`), Import module (:kbd:`F5`) and
Run script (:kbd:`Ctrl-F5`).
.. ======================================================================
Deleted and Deprecated Modules
==============================
A few modules have been dropped because they're obsolete, or because there are
now better ways to do the same thing. The :mod:`stdwin` module is gone; it was
for a platform-independent windowing toolkit that's no longer developed.
A number of modules have been moved to the :file:`lib-old` subdirectory:
:mod:`cmp`, :mod:`cmpcache`, :mod:`dircmp`, :mod:`dump`, :mod:`find`,
:mod:`grep`, :mod:`packmail`, :mod:`poly`, :mod:`util`, :mod:`whatsound`,
:mod:`zmod`. If you have code which relies on a module that's been moved to
:file:`lib-old`, you can simply add that directory to ``sys.path`` to get them
back, but you're encouraged to update any code that uses these modules.
Acknowledgements
================
The authors would like to thank the following people for offering suggestions on
various drafts of this article: David Bolen, Mark Hammond, Gregg Hauser, Jeremy
Hylton, Fredrik Lundh, Detlef Lannert, Aahz Maruch, Skip Montanaro, Vladimir
Marangozov, Tobias Polzin, Guido van Rossum, Neil Schemenauer, and Russ Schmidt.
PK
%�\��VR�� �� " html/_sources/whatsnew/2.1.rst.txtnu �[��� ****************************
What's New in Python 2.1
****************************
:Author: A.M. Kuchling
.. |release| replace:: 1.01
.. $Id: whatsnew21.tex 50964 2006-07-30 03:03:43Z fred.drake $
Introduction
============
This article explains the new features in Python 2.1. While there aren't as
many changes in 2.1 as there were in Python 2.0, there are still some pleasant
surprises in store. 2.1 is the first release to be steered through the use of
Python Enhancement Proposals, or PEPs, so most of the sizable changes have
accompanying PEPs that provide more complete documentation and a design
rationale for the change. This article doesn't attempt to document the new
features completely, but simply provides an overview of the new features for
Python programmers. Refer to the Python 2.1 documentation, or to the specific
PEP, for more details about any new feature that particularly interests you.
One recent goal of the Python development team has been to accelerate the pace
of new releases, with a new release coming every 6 to 9 months. 2.1 is the first
release to come out at this faster pace, with the first alpha appearing in
January, 3 months after the final version of 2.0 was released.
The final release of Python 2.1 was made on April 17, 2001.
.. ======================================================================
PEP 227: Nested Scopes
======================
The largest change in Python 2.1 is to Python's scoping rules. In Python 2.0,
at any given time there are at most three namespaces used to look up variable
names: local, module-level, and the built-in namespace. This often surprised
people because it didn't match their intuitive expectations. For example, a
nested recursive function definition doesn't work::
def f():
...
def g(value):
...
return g(value-1) + 1
...
The function :func:`g` will always raise a :exc:`NameError` exception, because
the binding of the name ``g`` isn't in either its local namespace or in the
module-level namespace. This isn't much of a problem in practice (how often do
you recursively define interior functions like this?), but this also made using
the :keyword:`lambda` statement clumsier, and this was a problem in practice.
In code which uses :keyword:`lambda` you can often find local variables being
copied by passing them as the default values of arguments. ::
def find(self, name):
"Return list of any entries equal to 'name'"
L = filter(lambda x, name=name: x == name,
self.list_attribute)
return L
The readability of Python code written in a strongly functional style suffers
greatly as a result.
The most significant change to Python 2.1 is that static scoping has been added
to the language to fix this problem. As a first effect, the ``name=name``
default argument is now unnecessary in the above example. Put simply, when a
given variable name is not assigned a value within a function (by an assignment,
or the :keyword:`def`, :keyword:`class`, or :keyword:`import` statements),
references to the variable will be looked up in the local namespace of the
enclosing scope. A more detailed explanation of the rules, and a dissection of
the implementation, can be found in the PEP.
This change may cause some compatibility problems for code where the same
variable name is used both at the module level and as a local variable within a
function that contains further function definitions. This seems rather unlikely
though, since such code would have been pretty confusing to read in the first
place.
One side effect of the change is that the ``from module import *`` and
:keyword:`exec` statements have been made illegal inside a function scope under
certain conditions. The Python reference manual has said all along that ``from
module import *`` is only legal at the top level of a module, but the CPython
interpreter has never enforced this before. As part of the implementation of
nested scopes, the compiler which turns Python source into bytecodes has to
generate different code to access variables in a containing scope. ``from
module import *`` and :keyword:`exec` make it impossible for the compiler to
figure this out, because they add names to the local namespace that are
unknowable at compile time. Therefore, if a function contains function
definitions or :keyword:`lambda` expressions with free variables, the compiler
will flag this by raising a :exc:`SyntaxError` exception.
To make the preceding explanation a bit clearer, here's an example::
x = 1
def f():
# The next line is a syntax error
exec 'x=2'
def g():
return x
Line 4 containing the :keyword:`exec` statement is a syntax error, since
:keyword:`exec` would define a new local variable named ``x`` whose value should
be accessed by :func:`g`.
This shouldn't be much of a limitation, since :keyword:`exec` is rarely used in
most Python code (and when it is used, it's often a sign of a poor design
anyway).
Compatibility concerns have led to nested scopes being introduced gradually; in
Python 2.1, they aren't enabled by default, but can be turned on within a module
by using a future statement as described in PEP 236. (See the following section
for further discussion of PEP 236.) In Python 2.2, nested scopes will become
the default and there will be no way to turn them off, but users will have had
all of 2.1's lifetime to fix any breakage resulting from their introduction.
.. seealso::
:pep:`227` - Statically Nested Scopes
Written and implemented by Jeremy Hylton.
.. ======================================================================
PEP 236: __future__ Directives
==============================
The reaction to nested scopes was widespread concern about the dangers of
breaking code with the 2.1 release, and it was strong enough to make the
Pythoneers take a more conservative approach. This approach consists of
introducing a convention for enabling optional functionality in release N that
will become compulsory in release N+1.
The syntax uses a ``from...import`` statement using the reserved module name
:mod:`__future__`. Nested scopes can be enabled by the following statement::
from __future__ import nested_scopes
While it looks like a normal :keyword:`import` statement, it's not; there are
strict rules on where such a future statement can be put. They can only be at
the top of a module, and must precede any Python code or regular
:keyword:`import` statements. This is because such statements can affect how
the Python bytecode compiler parses code and generates bytecode, so they must
precede any statement that will result in bytecodes being produced.
.. seealso::
:pep:`236` - Back to the :mod:`__future__`
Written by Tim Peters, and primarily implemented by Jeremy Hylton.
.. ======================================================================
PEP 207: Rich Comparisons
=========================
In earlier versions, Python's support for implementing comparisons on user-defined
classes and extension types was quite simple. Classes could implement a
:meth:`__cmp__` method that was given two instances of a class, and could only
return 0 if they were equal or +1 or -1 if they weren't; the method couldn't
raise an exception or return anything other than a Boolean value. Users of
Numeric Python often found this model too weak and restrictive, because in the
number-crunching programs that numeric Python is used for, it would be more
useful to be able to perform elementwise comparisons of two matrices, returning
a matrix containing the results of a given comparison for each element. If the
two matrices are of different sizes, then the compare has to be able to raise an
exception to signal the error.
In Python 2.1, rich comparisons were added in order to support this need.
Python classes can now individually overload each of the ``<``, ``<=``, ``>``,
``>=``, ``==``, and ``!=`` operations. The new magic method names are:
+-----------+----------------+
| Operation | Method name |
+===========+================+
| ``<`` | :meth:`__lt__` |
+-----------+----------------+
| ``<=`` | :meth:`__le__` |
+-----------+----------------+
| ``>`` | :meth:`__gt__` |
+-----------+----------------+
| ``>=`` | :meth:`__ge__` |
+-----------+----------------+
| ``==`` | :meth:`__eq__` |
+-----------+----------------+
| ``!=`` | :meth:`__ne__` |
+-----------+----------------+
(The magic methods are named after the corresponding Fortran operators ``.LT.``.
``.LE.``, &c. Numeric programmers are almost certainly quite familiar with
these names and will find them easy to remember.)
Each of these magic methods is of the form ``method(self, other)``, where
``self`` will be the object on the left-hand side of the operator, while
``other`` will be the object on the right-hand side. For example, the
expression ``A < B`` will cause ``A.__lt__(B)`` to be called.
Each of these magic methods can return anything at all: a Boolean, a matrix, a
list, or any other Python object. Alternatively they can raise an exception if
the comparison is impossible, inconsistent, or otherwise meaningless.
The built-in ``cmp(A,B)`` function can use the rich comparison machinery,
and now accepts an optional argument specifying which comparison operation to
use; this is given as one of the strings ``"<"``, ``"<="``, ``">"``, ``">="``,
``"=="``, or ``"!="``. If called without the optional third argument,
:func:`cmp` will only return -1, 0, or +1 as in previous versions of Python;
otherwise it will call the appropriate method and can return any Python object.
There are also corresponding changes of interest to C programmers; there's a new
slot ``tp_richcmp`` in type objects and an API for performing a given rich
comparison. I won't cover the C API here, but will refer you to PEP 207, or to
2.1's C API documentation, for the full list of related functions.
.. seealso::
:pep:`207` - Rich Comparisons
Written by Guido van Rossum, heavily based on earlier work by David Ascher, and
implemented by Guido van Rossum.
.. ======================================================================
PEP 230: Warning Framework
==========================
Over its 10 years of existence, Python has accumulated a certain number of
obsolete modules and features along the way. It's difficult to know when a
feature is safe to remove, since there's no way of knowing how much code uses it
--- perhaps no programs depend on the feature, or perhaps many do. To enable
removing old features in a more structured way, a warning framework was added.
When the Python developers want to get rid of a feature, it will first trigger a
warning in the next version of Python. The following Python version can then
drop the feature, and users will have had a full release cycle to remove uses of
the old feature.
Python 2.1 adds the warning framework to be used in this scheme. It adds a
:mod:`warnings` module that provide functions to issue warnings, and to filter
out warnings that you don't want to be displayed. Third-party modules can also
use this framework to deprecate old features that they no longer wish to
support.
For example, in Python 2.1 the :mod:`regex` module is deprecated, so importing
it causes a warning to be printed::
>>> import regex
__main__:1: DeprecationWarning: the regex module
is deprecated; please use the re module
>>>
Warnings can be issued by calling the :func:`warnings.warn` function::
warnings.warn("feature X no longer supported")
The first parameter is the warning message; an additional optional parameters
can be used to specify a particular warning category.
Filters can be added to disable certain warnings; a regular expression pattern
can be applied to the message or to the module name in order to suppress a
warning. For example, you may have a program that uses the :mod:`regex` module
and not want to spare the time to convert it to use the :mod:`re` module right
now. The warning can be suppressed by calling ::
import warnings
warnings.filterwarnings(action = 'ignore',
message='.*regex module is deprecated',
category=DeprecationWarning,
module = '__main__')
This adds a filter that will apply only to warnings of the class
:class:`DeprecationWarning` triggered in the :mod:`__main__` module, and applies
a regular expression to only match the message about the :mod:`regex` module
being deprecated, and will cause such warnings to be ignored. Warnings can also
be printed only once, printed every time the offending code is executed, or
turned into exceptions that will cause the program to stop (unless the
exceptions are caught in the usual way, of course).
Functions were also added to Python's C API for issuing warnings; refer to PEP
230 or to Python's API documentation for the details.
.. seealso::
:pep:`5` - Guidelines for Language Evolution
Written by Paul Prescod, to specify procedures to be followed when removing old
features from Python. The policy described in this PEP hasn't been officially
adopted, but the eventual policy probably won't be too different from Prescod's
proposal.
:pep:`230` - Warning Framework
Written and implemented by Guido van Rossum.
.. ======================================================================
PEP 229: New Build System
=========================
When compiling Python, the user had to go in and edit the :file:`Modules/Setup`
file in order to enable various additional modules; the default set is
relatively small and limited to modules that compile on most Unix platforms.
This means that on Unix platforms with many more features, most notably Linux,
Python installations often don't contain all useful modules they could.
Python 2.0 added the Distutils, a set of modules for distributing and installing
extensions. In Python 2.1, the Distutils are used to compile much of the
standard library of extension modules, autodetecting which ones are supported on
the current machine. It's hoped that this will make Python installations easier
and more featureful.
Instead of having to edit the :file:`Modules/Setup` file in order to enable
modules, a :file:`setup.py` script in the top directory of the Python source
distribution is run at build time, and attempts to discover which modules can be
enabled by examining the modules and header files on the system. If a module is
configured in :file:`Modules/Setup`, the :file:`setup.py` script won't attempt
to compile that module and will defer to the :file:`Modules/Setup` file's
contents. This provides a way to specific any strange command-line flags or
libraries that are required for a specific platform.
In another far-reaching change to the build mechanism, Neil Schemenauer
restructured things so Python now uses a single makefile that isn't recursive,
instead of makefiles in the top directory and in each of the :file:`Python/`,
:file:`Parser/`, :file:`Objects/`, and :file:`Modules/` subdirectories. This
makes building Python faster and also makes hacking the Makefiles clearer and
simpler.
.. seealso::
:pep:`229` - Using Distutils to Build Python
Written and implemented by A.M. Kuchling.
.. ======================================================================
PEP 205: Weak References
========================
Weak references, available through the :mod:`weakref` module, are a minor but
useful new data type in the Python programmer's toolbox.
Storing a reference to an object (say, in a dictionary or a list) has the side
effect of keeping that object alive forever. There are a few specific cases
where this behaviour is undesirable, object caches being the most common one,
and another being circular references in data structures such as trees.
For example, consider a memoizing function that caches the results of another
function ``f(x)`` by storing the function's argument and its result in a
dictionary::
_cache = {}
def memoize(x):
if _cache.has_key(x):
return _cache[x]
retval = f(x)
# Cache the returned object
_cache[x] = retval
return retval
This version works for simple things such as integers, but it has a side effect;
the ``_cache`` dictionary holds a reference to the return values, so they'll
never be deallocated until the Python process exits and cleans up This isn't
very noticeable for integers, but if :func:`f` returns an object, or a data
structure that takes up a lot of memory, this can be a problem.
Weak references provide a way to implement a cache that won't keep objects alive
beyond their time. If an object is only accessible through weak references, the
object will be deallocated and the weak references will now indicate that the
object it referred to no longer exists. A weak reference to an object *obj* is
created by calling ``wr = weakref.ref(obj)``. The object being referred to is
returned by calling the weak reference as if it were a function: ``wr()``. It
will return the referenced object, or ``None`` if the object no longer exists.
This makes it possible to write a :func:`memoize` function whose cache doesn't
keep objects alive, by storing weak references in the cache. ::
_cache = {}
def memoize(x):
if _cache.has_key(x):
obj = _cache[x]()
# If weak reference object still exists,
# return it
if obj is not None: return obj
retval = f(x)
# Cache a weak reference
_cache[x] = weakref.ref(retval)
return retval
The :mod:`weakref` module also allows creating proxy objects which behave like
weak references --- an object referenced only by proxy objects is deallocated --
but instead of requiring an explicit call to retrieve the object, the proxy
transparently forwards all operations to the object as long as the object still
exists. If the object is deallocated, attempting to use a proxy will cause a
:exc:`weakref.ReferenceError` exception to be raised. ::
proxy = weakref.proxy(obj)
proxy.attr # Equivalent to obj.attr
proxy.meth() # Equivalent to obj.meth()
del obj
proxy.attr # raises weakref.ReferenceError
.. seealso::
:pep:`205` - Weak References
Written and implemented by Fred L. Drake, Jr.
.. ======================================================================
PEP 232: Function Attributes
============================
In Python 2.1, functions can now have arbitrary information attached to them.
People were often using docstrings to hold information about functions and
methods, because the ``__doc__`` attribute was the only way of attaching any
information to a function. For example, in the Zope Web application server,
functions are marked as safe for public access by having a docstring, and in
John Aycock's SPARK parsing framework, docstrings hold parts of the BNF grammar
to be parsed. This overloading is unfortunate, since docstrings are really
intended to hold a function's documentation; for example, it means you can't
properly document functions intended for private use in Zope.
Arbitrary attributes can now be set and retrieved on functions using the regular
Python syntax::
def f(): pass
f.publish = 1
f.secure = 1
f.grammar = "A ::= B (C D)*"
The dictionary containing attributes can be accessed as the function's
:attr:`~object.__dict__`. Unlike the :attr:`~object.__dict__` attribute of class instances, in
functions you can actually assign a new dictionary to :attr:`~object.__dict__`, though
the new value is restricted to a regular Python dictionary; you *can't* be
tricky and set it to a :class:`~UserDict.UserDict` instance, or any other random object
that behaves like a mapping.
.. seealso::
:pep:`232` - Function Attributes
Written and implemented by Barry Warsaw.
.. ======================================================================
PEP 235: Importing Modules on Case-Insensitive Platforms
========================================================
Some operating systems have filesystems that are case-insensitive, MacOS and
Windows being the primary examples; on these systems, it's impossible to
distinguish the filenames ``FILE.PY`` and ``file.py``, even though they do store
the file's name in its original case (they're case-preserving, too).
In Python 2.1, the :keyword:`import` statement will work to simulate case-sensitivity
on case-insensitive platforms. Python will now search for the first
case-sensitive match by default, raising an :exc:`ImportError` if no such file
is found, so ``import file`` will not import a module named ``FILE.PY``.
Case-insensitive matching can be requested by setting the :envvar:`PYTHONCASEOK`
environment variable before starting the Python interpreter.
.. ======================================================================
PEP 217: Interactive Display Hook
=================================
When using the Python interpreter interactively, the output of commands is
displayed using the built-in :func:`repr` function. In Python 2.1, the variable
:func:`sys.displayhook` can be set to a callable object which will be called
instead of :func:`repr`. For example, you can set it to a special
pretty-printing function::
>>> # Create a recursive data structure
... L = [1,2,3]
>>> L.append(L)
>>> L # Show Python's default output
[1, 2, 3, [...]]
>>> # Use pprint.pprint() as the display function
... import sys, pprint
>>> sys.displayhook = pprint.pprint
>>> L
[1, 2, 3, <Recursion on list with id=135143996>]
>>>
.. seealso::
:pep:`217` - Display Hook for Interactive Use
Written and implemented by Moshe Zadka.
.. ======================================================================
PEP 208: New Coercion Model
===========================
How numeric coercion is done at the C level was significantly modified. This
will only affect the authors of C extensions to Python, allowing them more
flexibility in writing extension types that support numeric operations.
Extension types can now set the type flag ``Py_TPFLAGS_CHECKTYPES`` in their
``PyTypeObject`` structure to indicate that they support the new coercion model.
In such extension types, the numeric slot functions can no longer assume that
they'll be passed two arguments of the same type; instead they may be passed two
arguments of differing types, and can then perform their own internal coercion.
If the slot function is passed a type it can't handle, it can indicate the
failure by returning a reference to the ``Py_NotImplemented`` singleton value.
The numeric functions of the other type will then be tried, and perhaps they can
handle the operation; if the other type also returns ``Py_NotImplemented``, then
a :exc:`TypeError` will be raised. Numeric methods written in Python can also
return ``Py_NotImplemented``, causing the interpreter to act as if the method
did not exist (perhaps raising a :exc:`TypeError`, perhaps trying another
object's numeric methods).
.. seealso::
:pep:`208` - Reworking the Coercion Model
Written and implemented by Neil Schemenauer, heavily based upon earlier work by
Marc-André Lemburg. Read this to understand the fine points of how numeric
operations will now be processed at the C level.
.. ======================================================================
PEP 241: Metadata in Python Packages
====================================
A common complaint from Python users is that there's no single catalog of all
the Python modules in existence. T. Middleton's Vaults of Parnassus at
http://www.vex.net/parnassus/ are the largest catalog of Python modules, but
registering software at the Vaults is optional, and many people don't bother.
As a first small step toward fixing the problem, Python software packaged using
the Distutils :command:`sdist` command will include a file named
:file:`PKG-INFO` containing information about the package such as its name,
version, and author (metadata, in cataloguing terminology). PEP 241 contains
the full list of fields that can be present in the :file:`PKG-INFO` file. As
people began to package their software using Python 2.1, more and more packages
will include metadata, making it possible to build automated cataloguing systems
and experiment with them. With the result experience, perhaps it'll be possible
to design a really good catalog and then build support for it into Python 2.2.
For example, the Distutils :command:`sdist` and :command:`bdist_\*` commands
could support an ``upload`` option that would automatically upload your
package to a catalog server.
You can start creating packages containing :file:`PKG-INFO` even if you're not
using Python 2.1, since a new release of the Distutils will be made for users of
earlier Python versions. Version 1.0.2 of the Distutils includes the changes
described in PEP 241, as well as various bugfixes and enhancements. It will be
available from the Distutils SIG at https://www.python.org/community/sigs/current/distutils-sig/.
.. seealso::
:pep:`241` - Metadata for Python Software Packages
Written and implemented by A.M. Kuchling.
:pep:`243` - Module Repository Upload Mechanism
Written by Sean Reifschneider, this draft PEP describes a proposed mechanism for
uploading Python packages to a central server.
.. ======================================================================
New and Improved Modules
========================
* Ka-Ping Yee contributed two new modules: :mod:`inspect.py`, a module for
getting information about live Python code, and :mod:`pydoc.py`, a module for
interactively converting docstrings to HTML or text. As a bonus,
:file:`Tools/scripts/pydoc`, which is now automatically installed, uses
:mod:`pydoc.py` to display documentation given a Python module, package, or
class name. For example, ``pydoc xml.dom`` displays the following::
Python Library Documentation: package xml.dom in xml
NAME
xml.dom - W3C Document Object Model implementation for Python.
FILE
/usr/local/lib/python2.1/xml/dom/__init__.pyc
DESCRIPTION
The Python mapping of the Document Object Model is documented in the
Python Library Reference in the section on the xml.dom package.
This package contains the following modules:
...
:file:`pydoc` also includes a Tk-based interactive help browser. :file:`pydoc`
quickly becomes addictive; try it out!
* Two different modules for unit testing were added to the standard library.
The :mod:`doctest` module, contributed by Tim Peters, provides a testing
framework based on running embedded examples in docstrings and comparing the
results against the expected output. PyUnit, contributed by Steve Purcell, is a
unit testing framework inspired by JUnit, which was in turn an adaptation of
Kent Beck's Smalltalk testing framework. See http://pyunit.sourceforge.net/ for
more information about PyUnit.
* The :mod:`difflib` module contains a class, :class:`SequenceMatcher`, which
compares two sequences and computes the changes required to transform one
sequence into the other. For example, this module can be used to write a tool
similar to the Unix :program:`diff` program, and in fact the sample program
:file:`Tools/scripts/ndiff.py` demonstrates how to write such a script.
* :mod:`curses.panel`, a wrapper for the panel library, part of ncurses and of
SYSV curses, was contributed by Thomas Gellekum. The panel library provides
windows with the additional feature of depth. Windows can be moved higher or
lower in the depth ordering, and the panel library figures out where panels
overlap and which sections are visible.
* The PyXML package has gone through a few releases since Python 2.0, and Python
2.1 includes an updated version of the :mod:`xml` package. Some of the
noteworthy changes include support for Expat 1.2 and later versions, the ability
for Expat parsers to handle files in any encoding supported by Python, and
various bugfixes for SAX, DOM, and the :mod:`minidom` module.
* Ping also contributed another hook for handling uncaught exceptions.
:func:`sys.excepthook` can be set to a callable object. When an exception isn't
caught by any :keyword:`try`...\ :keyword:`except` blocks, the exception will be
passed to :func:`sys.excepthook`, which can then do whatever it likes. At the
Ninth Python Conference, Ping demonstrated an application for this hook:
printing an extended traceback that not only lists the stack frames, but also
lists the function arguments and the local variables for each frame.
* Various functions in the :mod:`time` module, such as :func:`asctime` and
:func:`localtime`, require a floating point argument containing the time in
seconds since the epoch. The most common use of these functions is to work with
the current time, so the floating point argument has been made optional; when a
value isn't provided, the current time will be used. For example, log file
entries usually need a string containing the current time; in Python 2.1,
``time.asctime()`` can be used, instead of the lengthier
``time.asctime(time.localtime(time.time()))`` that was previously required.
This change was proposed and implemented by Thomas Wouters.
* The :mod:`ftplib` module now defaults to retrieving files in passive mode,
because passive mode is more likely to work from behind a firewall. This
request came from the Debian bug tracking system, since other Debian packages
use :mod:`ftplib` to retrieve files and then don't work from behind a firewall.
It's deemed unlikely that this will cause problems for anyone, because Netscape
defaults to passive mode and few people complain, but if passive mode is
unsuitable for your application or network setup, call ``set_pasv(0)`` on
FTP objects to disable passive mode.
* Support for raw socket access has been added to the :mod:`socket` module,
contributed by Grant Edwards.
* The :mod:`pstats` module now contains a simple interactive statistics browser
for displaying timing profiles for Python programs, invoked when the module is
run as a script. Contributed by Eric S. Raymond.
* A new implementation-dependent function, ``sys._getframe([depth])``, has
been added to return a given frame object from the current call stack.
:func:`sys._getframe` returns the frame at the top of the call stack; if the
optional integer argument *depth* is supplied, the function returns the frame
that is *depth* calls below the top of the stack. For example,
``sys._getframe(1)`` returns the caller's frame object.
This function is only present in CPython, not in Jython or the .NET
implementation. Use it for debugging, and resist the temptation to put it into
production code.
.. ======================================================================
Other Changes and Fixes
=======================
There were relatively few smaller changes made in Python 2.1 due to the shorter
release cycle. A search through the CVS change logs turns up 117 patches
applied, and 136 bugs fixed; both figures are likely to be underestimates. Some
of the more notable changes are:
* A specialized object allocator is now optionally available, that should be
faster than the system :func:`malloc` and have less memory overhead. The
allocator uses C's :func:`malloc` function to get large pools of memory, and
then fulfills smaller memory requests from these pools. It can be enabled by
providing the :option:`!--with-pymalloc` option to the :program:`configure`
script; see :file:`Objects/obmalloc.c` for the implementation details.
Authors of C extension modules should test their code with the object allocator
enabled, because some incorrect code may break, causing core dumps at runtime.
There are a bunch of memory allocation functions in Python's C API that have
previously been just aliases for the C library's :func:`malloc` and
:func:`free`, meaning that if you accidentally called mismatched functions, the
error wouldn't be noticeable. When the object allocator is enabled, these
functions aren't aliases of :func:`malloc` and :func:`free` any more, and
calling the wrong function to free memory will get you a core dump. For
example, if memory was allocated using :func:`PyMem_New`, it has to be freed
using :func:`PyMem_Del`, not :func:`free`. A few modules included with Python
fell afoul of this and had to be fixed; doubtless there are more third-party
modules that will have the same problem.
The object allocator was contributed by Vladimir Marangozov.
* The speed of line-oriented file I/O has been improved because people often
complain about its lack of speed, and because it's often been used as a naïve
benchmark. The :meth:`readline` method of file objects has therefore been
rewritten to be much faster. The exact amount of the speedup will vary from
platform to platform depending on how slow the C library's :func:`getc` was, but
is around 66%, and potentially much faster on some particular operating systems.
Tim Peters did much of the benchmarking and coding for this change, motivated by
a discussion in comp.lang.python.
A new module and method for file objects was also added, contributed by Jeff
Epler. The new method, :meth:`xreadlines`, is similar to the existing
:func:`xrange` built-in. :func:`xreadlines` returns an opaque sequence object
that only supports being iterated over, reading a line on every iteration but
not reading the entire file into memory as the existing :meth:`readlines` method
does. You'd use it like this::
for line in sys.stdin.xreadlines():
# ... do something for each line ...
...
For a fuller discussion of the line I/O changes, see the python-dev summary for
January 1--15, 2001 at https://mail.python.org/pipermail/python-dev/2001-January/.
* A new method, :meth:`popitem`, was added to dictionaries to enable
destructively iterating through the contents of a dictionary; this can be faster
for large dictionaries because there's no need to construct a list containing
all the keys or values. ``D.popitem()`` removes a random ``(key, value)`` pair
from the dictionary ``D`` and returns it as a 2-tuple. This was implemented
mostly by Tim Peters and Guido van Rossum, after a suggestion and preliminary
patch by Moshe Zadka.
* Modules can now control which names are imported when ``from module import *``
is used, by defining an ``__all__`` attribute containing a list of names that
will be imported. One common complaint is that if the module imports other
modules such as :mod:`sys` or :mod:`string`, ``from module import *`` will add
them to the importing module's namespace. To fix this, simply list the public
names in ``__all__``::
# List public names
__all__ = ['Database', 'open']
A stricter version of this patch was first suggested and implemented by Ben
Wolfson, but after some python-dev discussion, a weaker final version was
checked in.
* Applying :func:`repr` to strings previously used octal escapes for
non-printable characters; for example, a newline was ``'\012'``. This was a
vestigial trace of Python's C ancestry, but today octal is of very little
practical use. Ka-Ping Yee suggested using hex escapes instead of octal ones,
and using the ``\n``, ``\t``, ``\r`` escapes for the appropriate characters,
and implemented this new formatting.
* Syntax errors detected at compile-time can now raise exceptions containing the
filename and line number of the error, a pleasant side effect of the compiler
reorganization done by Jeremy Hylton.
* C extensions which import other modules have been changed to use
:func:`PyImport_ImportModule`, which means that they will use any import hooks
that have been installed. This is also encouraged for third-party extensions
that need to import some other module from C code.
* The size of the Unicode character database was shrunk by another 340K thanks
to Fredrik Lundh.
* Some new ports were contributed: MacOS X (by Steven Majewski), Cygwin (by
Jason Tishler); RISCOS (by Dietmar Schwertberger); Unixware 7 (by Billy G.
Allie).
And there's the usual list of minor bugfixes, minor memory leaks, docstring
edits, and other tweaks, too lengthy to be worth itemizing; see the CVS logs for
the full details if you want them.
.. ======================================================================
Acknowledgements
================
The author would like to thank the following people for offering suggestions on
various drafts of this article: Graeme Cross, David Goodger, Jay Graves, Michael
Hudson, Marc-André Lemburg, Fredrik Lundh, Neil Schemenauer, Thomas Wouters.
PK
%�\�Ҫ:�� �� " html/_sources/whatsnew/2.2.rst.txtnu �[��� ****************************
What's New in Python 2.2
****************************
:Author: A.M. Kuchling
.. |release| replace:: 1.02
.. $Id: whatsnew22.tex 37315 2004-09-10 19:33:00Z akuchling $
Introduction
============
This article explains the new features in Python 2.2.2, released on October 14,
2002. Python 2.2.2 is a bugfix release of Python 2.2, originally released on
December 21, 2001.
Python 2.2 can be thought of as the "cleanup release". There are some features
such as generators and iterators that are completely new, but most of the
changes, significant and far-reaching though they may be, are aimed at cleaning
up irregularities and dark corners of the language design.
This article doesn't attempt to provide a complete specification of the new
features, but instead provides a convenient overview. For full details, you
should refer to the documentation for Python 2.2, such as the `Python Library
Reference <https://docs.python.org/2.2/lib/lib.html>`_ and the `Python
Reference Manual <https://docs.python.org/2.2/ref/ref.html>`_. If you want to
understand the complete implementation and design rationale for a change, refer
to the PEP for a particular new feature.
.. see also, now defunct
http://www.unixreview.com/documents/s=1356/urm0109h/0109h.htm
"What's So Special About Python 2.2?" is also about the new 2.2 features, and
was written by Cameron Laird and Kathryn Soraiz.
.. ======================================================================
PEPs 252 and 253: Type and Class Changes
========================================
The largest and most far-reaching changes in Python 2.2 are to Python's model of
objects and classes. The changes should be backward compatible, so it's likely
that your code will continue to run unchanged, but the changes provide some
amazing new capabilities. Before beginning this, the longest and most
complicated section of this article, I'll provide an overview of the changes and
offer some comments.
A long time ago I wrote a Web page listing flaws in Python's design. One of the
most significant flaws was that it's impossible to subclass Python types
implemented in C. In particular, it's not possible to subclass built-in types,
so you can't just subclass, say, lists in order to add a single useful method to
them. The :mod:`UserList` module provides a class that supports all of the
methods of lists and that can be subclassed further, but there's lots of C code
that expects a regular Python list and won't accept a :class:`~UserList.UserList`
instance.
Python 2.2 fixes this, and in the process adds some exciting new capabilities.
A brief summary:
* You can subclass built-in types such as lists and even integers, and your
subclasses should work in every place that requires the original type.
* It's now possible to define static and class methods, in addition to the
instance methods available in previous versions of Python.
* It's also possible to automatically call methods on accessing or setting an
instance attribute by using a new mechanism called :dfn:`properties`. Many uses
of :meth:`__getattr__` can be rewritten to use properties instead, making the
resulting code simpler and faster. As a small side benefit, attributes can now
have docstrings, too.
* The list of legal attributes for an instance can be limited to a particular
set using :dfn:`slots`, making it possible to safeguard against typos and
perhaps make more optimizations possible in future versions of Python.
Some users have voiced concern about all these changes. Sure, they say, the new
features are neat and lend themselves to all sorts of tricks that weren't
possible in previous versions of Python, but they also make the language more
complicated. Some people have said that they've always recommended Python for
its simplicity, and feel that its simplicity is being lost.
Personally, I think there's no need to worry. Many of the new features are
quite esoteric, and you can write a lot of Python code without ever needed to be
aware of them. Writing a simple class is no more difficult than it ever was, so
you don't need to bother learning or teaching them unless they're actually
needed. Some very complicated tasks that were previously only possible from C
will now be possible in pure Python, and to my mind that's all for the better.
I'm not going to attempt to cover every single corner case and small change that
were required to make the new features work. Instead this section will paint
only the broad strokes. See section :ref:`sect-rellinks`, "Related Links", for
further sources of information about Python 2.2's new object model.
Old and New Classes
-------------------
First, you should know that Python 2.2 really has two kinds of classes: classic
or old-style classes, and new-style classes. The old-style class model is
exactly the same as the class model in earlier versions of Python. All the new
features described in this section apply only to new-style classes. This
divergence isn't intended to last forever; eventually old-style classes will be
dropped, possibly in Python 3.0.
So how do you define a new-style class? You do it by subclassing an existing
new-style class. Most of Python's built-in types, such as integers, lists,
dictionaries, and even files, are new-style classes now. A new-style class
named :class:`object`, the base class for all built-in types, has also been
added so if no built-in type is suitable, you can just subclass
:class:`object`::
class C(object):
def __init__ (self):
...
...
This means that :keyword:`class` statements that don't have any base classes are
always classic classes in Python 2.2. (Actually you can also change this by
setting a module-level variable named :attr:`__metaclass__` --- see :pep:`253`
for the details --- but it's easier to just subclass :keyword:`object`.)
The type objects for the built-in types are available as built-ins, named using
a clever trick. Python has always had built-in functions named :func:`int`,
:func:`float`, and :func:`str`. In 2.2, they aren't functions any more, but
type objects that behave as factories when called. ::
>>> int
<type 'int'>
>>> int('123')
123
To make the set of types complete, new type objects such as :func:`dict` and
:func:`file` have been added. Here's a more interesting example, adding a
:meth:`lock` method to file objects::
class LockableFile(file):
def lock (self, operation, length=0, start=0, whence=0):
import fcntl
return fcntl.lockf(self.fileno(), operation,
length, start, whence)
The now-obsolete :mod:`posixfile` module contained a class that emulated all of
a file object's methods and also added a :meth:`lock` method, but this class
couldn't be passed to internal functions that expected a built-in file,
something which is possible with our new :class:`LockableFile`.
Descriptors
-----------
In previous versions of Python, there was no consistent way to discover what
attributes and methods were supported by an object. There were some informal
conventions, such as defining :attr:`__members__` and :attr:`__methods__`
attributes that were lists of names, but often the author of an extension type
or a class wouldn't bother to define them. You could fall back on inspecting
the :attr:`~object.__dict__` of an object, but when class inheritance or an arbitrary
:meth:`__getattr__` hook were in use this could still be inaccurate.
The one big idea underlying the new class model is that an API for describing
the attributes of an object using :dfn:`descriptors` has been formalized.
Descriptors specify the value of an attribute, stating whether it's a method or
a field. With the descriptor API, static methods and class methods become
possible, as well as more exotic constructs.
Attribute descriptors are objects that live inside class objects, and have a few
attributes of their own:
* :attr:`~definition.__name__` is the attribute's name.
* :attr:`__doc__` is the attribute's docstring.
* ``__get__(object)`` is a method that retrieves the attribute value from
*object*.
* ``__set__(object, value)`` sets the attribute on *object* to *value*.
* ``__delete__(object, value)`` deletes the *value* attribute of *object*.
For example, when you write ``obj.x``, the steps that Python actually performs
are::
descriptor = obj.__class__.x
descriptor.__get__(obj)
For methods, :meth:`descriptor.__get__` returns a temporary object that's
callable, and wraps up the instance and the method to be called on it. This is
also why static methods and class methods are now possible; they have
descriptors that wrap up just the method, or the method and the class. As a
brief explanation of these new kinds of methods, static methods aren't passed
the instance, and therefore resemble regular functions. Class methods are
passed the class of the object, but not the object itself. Static and class
methods are defined like this::
class C(object):
def f(arg1, arg2):
...
f = staticmethod(f)
def g(cls, arg1, arg2):
...
g = classmethod(g)
The :func:`staticmethod` function takes the function :func:`f`, and returns it
wrapped up in a descriptor so it can be stored in the class object. You might
expect there to be special syntax for creating such methods (``def static f``,
``defstatic f()``, or something like that) but no such syntax has been defined
yet; that's been left for future versions of Python.
More new features, such as slots and properties, are also implemented as new
kinds of descriptors, and it's not difficult to write a descriptor class that
does something novel. For example, it would be possible to write a descriptor
class that made it possible to write Eiffel-style preconditions and
postconditions for a method. A class that used this feature might be defined
like this::
from eiffel import eiffelmethod
class C(object):
def f(self, arg1, arg2):
# The actual function
...
def pre_f(self):
# Check preconditions
...
def post_f(self):
# Check postconditions
...
f = eiffelmethod(f, pre_f, post_f)
Note that a person using the new :func:`eiffelmethod` doesn't have to understand
anything about descriptors. This is why I think the new features don't increase
the basic complexity of the language. There will be a few wizards who need to
know about it in order to write :func:`eiffelmethod` or the ZODB or whatever,
but most users will just write code on top of the resulting libraries and ignore
the implementation details.
Multiple Inheritance: The Diamond Rule
--------------------------------------
Multiple inheritance has also been made more useful through changing the rules
under which names are resolved. Consider this set of classes (diagram taken
from :pep:`253` by Guido van Rossum)::
class A:
^ ^ def save(self): ...
/ \
/ \
/ \
/ \
class B class C:
^ ^ def save(self): ...
\ /
\ /
\ /
\ /
class D
The lookup rule for classic classes is simple but not very smart; the base
classes are searched depth-first, going from left to right. A reference to
:meth:`D.save` will search the classes :class:`D`, :class:`B`, and then
:class:`A`, where :meth:`save` would be found and returned. :meth:`C.save`
would never be found at all. This is bad, because if :class:`C`'s :meth:`save`
method is saving some internal state specific to :class:`C`, not calling it will
result in that state never getting saved.
New-style classes follow a different algorithm that's a bit more complicated to
explain, but does the right thing in this situation. (Note that Python 2.3
changes this algorithm to one that produces the same results in most cases, but
produces more useful results for really complicated inheritance graphs.)
#. List all the base classes, following the classic lookup rule and include a
class multiple times if it's visited repeatedly. In the above example, the list
of visited classes is [:class:`D`, :class:`B`, :class:`A`, :class:`C`,
:class:`A`].
#. Scan the list for duplicated classes. If any are found, remove all but one
occurrence, leaving the *last* one in the list. In the above example, the list
becomes [:class:`D`, :class:`B`, :class:`C`, :class:`A`] after dropping
duplicates.
Following this rule, referring to :meth:`D.save` will return :meth:`C.save`,
which is the behaviour we're after. This lookup rule is the same as the one
followed by Common Lisp. A new built-in function, :func:`super`, provides a way
to get at a class's superclasses without having to reimplement Python's
algorithm. The most commonly used form will be ``super(class, obj)``, which
returns a bound superclass object (not the actual class object). This form
will be used in methods to call a method in the superclass; for example,
:class:`D`'s :meth:`save` method would look like this::
class D (B,C):
def save (self):
# Call superclass .save()
super(D, self).save()
# Save D's private information here
...
:func:`super` can also return unbound superclass objects when called as
``super(class)`` or ``super(class1, class2)``, but this probably won't
often be useful.
Attribute Access
----------------
A fair number of sophisticated Python classes define hooks for attribute access
using :meth:`__getattr__`; most commonly this is done for convenience, to make
code more readable by automatically mapping an attribute access such as
``obj.parent`` into a method call such as ``obj.get_parent``. Python 2.2 adds
some new ways of controlling attribute access.
First, ``__getattr__(attr_name)`` is still supported by new-style classes,
and nothing about it has changed. As before, it will be called when an attempt
is made to access ``obj.foo`` and no attribute named ``foo`` is found in the
instance's dictionary.
New-style classes also support a new method,
``__getattribute__(attr_name)``. The difference between the two methods is
that :meth:`__getattribute__` is *always* called whenever any attribute is
accessed, while the old :meth:`__getattr__` is only called if ``foo`` isn't
found in the instance's dictionary.
However, Python 2.2's support for :dfn:`properties` will often be a simpler way
to trap attribute references. Writing a :meth:`__getattr__` method is
complicated because to avoid recursion you can't use regular attribute accesses
inside them, and instead have to mess around with the contents of
:attr:`~object.__dict__`. :meth:`__getattr__` methods also end up being called by Python
when it checks for other methods such as :meth:`__repr__` or :meth:`__coerce__`,
and so have to be written with this in mind. Finally, calling a function on
every attribute access results in a sizable performance loss.
:class:`property` is a new built-in type that packages up three functions that
get, set, or delete an attribute, and a docstring. For example, if you want to
define a :attr:`size` attribute that's computed, but also settable, you could
write::
class C(object):
def get_size (self):
result = ... computation ...
return result
def set_size (self, size):
... compute something based on the size
and set internal state appropriately ...
# Define a property. The 'delete this attribute'
# method is defined as None, so the attribute
# can't be deleted.
size = property(get_size, set_size,
None,
"Storage size of this instance")
That is certainly clearer and easier to write than a pair of
:meth:`__getattr__`/:meth:`__setattr__` methods that check for the :attr:`size`
attribute and handle it specially while retrieving all other attributes from the
instance's :attr:`~object.__dict__`. Accesses to :attr:`size` are also the only ones
which have to perform the work of calling a function, so references to other
attributes run at their usual speed.
Finally, it's possible to constrain the list of attributes that can be
referenced on an object using the new :attr:`~object.__slots__` class attribute. Python
objects are usually very dynamic; at any time it's possible to define a new
attribute on an instance by just doing ``obj.new_attr=1``. A new-style class
can define a class attribute named :attr:`~object.__slots__` to limit the legal
attributes to a particular set of names. An example will make this clear::
>>> class C(object):
... __slots__ = ('template', 'name')
...
>>> obj = C()
>>> print obj.template
None
>>> obj.template = 'Test'
>>> print obj.template
Test
>>> obj.newattr = None
Traceback (most recent call last):
File "<stdin>", line 1, in ?
AttributeError: 'C' object has no attribute 'newattr'
Note how you get an :exc:`AttributeError` on the attempt to assign to an
attribute not listed in :attr:`~object.__slots__`.
.. _sect-rellinks:
Related Links
-------------
This section has just been a quick overview of the new features, giving enough
of an explanation to start you programming, but many details have been
simplified or ignored. Where should you go to get a more complete picture?
https://docs.python.org/dev/howto/descriptor.html is a lengthy tutorial introduction to
the descriptor features, written by Guido van Rossum. If my description has
whetted your appetite, go read this tutorial next, because it goes into much
more detail about the new features while still remaining quite easy to read.
Next, there are two relevant PEPs, :pep:`252` and :pep:`253`. :pep:`252` is
titled "Making Types Look More Like Classes", and covers the descriptor API.
:pep:`253` is titled "Subtyping Built-in Types", and describes the changes to
type objects that make it possible to subtype built-in objects. :pep:`253` is
the more complicated PEP of the two, and at a few points the necessary
explanations of types and meta-types may cause your head to explode. Both PEPs
were written and implemented by Guido van Rossum, with substantial assistance
from the rest of the Zope Corp. team.
Finally, there's the ultimate authority: the source code. Most of the machinery
for the type handling is in :file:`Objects/typeobject.c`, but you should only
resort to it after all other avenues have been exhausted, including posting a
question to python-list or python-dev.
.. ======================================================================
PEP 234: Iterators
==================
Another significant addition to 2.2 is an iteration interface at both the C and
Python levels. Objects can define how they can be looped over by callers.
In Python versions up to 2.1, the usual way to make ``for item in obj`` work is
to define a :meth:`__getitem__` method that looks something like this::
def __getitem__(self, index):
return <next item>
:meth:`__getitem__` is more properly used to define an indexing operation on an
object so that you can write ``obj[5]`` to retrieve the sixth element. It's a
bit misleading when you're using this only to support :keyword:`for` loops.
Consider some file-like object that wants to be looped over; the *index*
parameter is essentially meaningless, as the class probably assumes that a
series of :meth:`__getitem__` calls will be made with *index* incrementing by
one each time. In other words, the presence of the :meth:`__getitem__` method
doesn't mean that using ``file[5]`` to randomly access the sixth element will
work, though it really should.
In Python 2.2, iteration can be implemented separately, and :meth:`__getitem__`
methods can be limited to classes that really do support random access. The
basic idea of iterators is simple. A new built-in function, ``iter(obj)``
or ``iter(C, sentinel)``, is used to get an iterator. ``iter(obj)`` returns
an iterator for the object *obj*, while ``iter(C, sentinel)`` returns an
iterator that will invoke the callable object *C* until it returns *sentinel* to
signal that the iterator is done.
Python classes can define an :meth:`__iter__` method, which should create and
return a new iterator for the object; if the object is its own iterator, this
method can just return ``self``. In particular, iterators will usually be their
own iterators. Extension types implemented in C can implement a :c:member:`~PyTypeObject.tp_iter`
function in order to return an iterator, and extension types that want to behave
as iterators can define a :c:member:`~PyTypeObject.tp_iternext` function.
So, after all this, what do iterators actually do? They have one required
method, :meth:`next`, which takes no arguments and returns the next value. When
there are no more values to be returned, calling :meth:`next` should raise the
:exc:`StopIteration` exception. ::
>>> L = [1,2,3]
>>> i = iter(L)
>>> print i
<iterator object at 0x8116870>
>>> i.next()
1
>>> i.next()
2
>>> i.next()
3
>>> i.next()
Traceback (most recent call last):
File "<stdin>", line 1, in ?
StopIteration
>>>
In 2.2, Python's :keyword:`for` statement no longer expects a sequence; it
expects something for which :func:`iter` will return an iterator. For backward
compatibility and convenience, an iterator is automatically constructed for
sequences that don't implement :meth:`__iter__` or a :c:member:`~PyTypeObject.tp_iter` slot, so
``for i in [1,2,3]`` will still work. Wherever the Python interpreter loops
over a sequence, it's been changed to use the iterator protocol. This means you
can do things like this::
>>> L = [1,2,3]
>>> i = iter(L)
>>> a,b,c = i
>>> a,b,c
(1, 2, 3)
Iterator support has been added to some of Python's basic types. Calling
:func:`iter` on a dictionary will return an iterator which loops over its keys::
>>> m = {'Jan': 1, 'Feb': 2, 'Mar': 3, 'Apr': 4, 'May': 5, 'Jun': 6,
... 'Jul': 7, 'Aug': 8, 'Sep': 9, 'Oct': 10, 'Nov': 11, 'Dec': 12}
>>> for key in m: print key, m[key]
...
Mar 3
Feb 2
Aug 8
Sep 9
May 5
Jun 6
Jul 7
Jan 1
Apr 4
Nov 11
Dec 12
Oct 10
That's just the default behaviour. If you want to iterate over keys, values, or
key/value pairs, you can explicitly call the :meth:`iterkeys`,
:meth:`itervalues`, or :meth:`iteritems` methods to get an appropriate iterator.
In a minor related change, the :keyword:`in` operator now works on dictionaries,
so ``key in dict`` is now equivalent to ``dict.has_key(key)``.
Files also provide an iterator, which calls the :meth:`readline` method until
there are no more lines in the file. This means you can now read each line of a
file using code like this::
for line in file:
# do something for each line
...
Note that you can only go forward in an iterator; there's no way to get the
previous element, reset the iterator, or make a copy of it. An iterator object
could provide such additional capabilities, but the iterator protocol only
requires a :meth:`next` method.
.. seealso::
:pep:`234` - Iterators
Written by Ka-Ping Yee and GvR; implemented by the Python Labs crew, mostly by
GvR and Tim Peters.
.. ======================================================================
PEP 255: Simple Generators
==========================
Generators are another new feature, one that interacts with the introduction of
iterators.
You're doubtless familiar with how function calls work in Python or C. When you
call a function, it gets a private namespace where its local variables are
created. When the function reaches a :keyword:`return` statement, the local
variables are destroyed and the resulting value is returned to the caller. A
later call to the same function will get a fresh new set of local variables.
But, what if the local variables weren't thrown away on exiting a function?
What if you could later resume the function where it left off? This is what
generators provide; they can be thought of as resumable functions.
Here's the simplest example of a generator function::
def generate_ints(N):
for i in range(N):
yield i
A new keyword, :keyword:`yield`, was introduced for generators. Any function
containing a :keyword:`yield` statement is a generator function; this is
detected by Python's bytecode compiler which compiles the function specially as
a result. Because a new keyword was introduced, generators must be explicitly
enabled in a module by including a ``from __future__ import generators``
statement near the top of the module's source code. In Python 2.3 this
statement will become unnecessary.
When you call a generator function, it doesn't return a single value; instead it
returns a generator object that supports the iterator protocol. On executing
the :keyword:`yield` statement, the generator outputs the value of ``i``,
similar to a :keyword:`return` statement. The big difference between
:keyword:`yield` and a :keyword:`return` statement is that on reaching a
:keyword:`yield` the generator's state of execution is suspended and local
variables are preserved. On the next call to the generator's ``next()`` method,
the function will resume executing immediately after the :keyword:`yield`
statement. (For complicated reasons, the :keyword:`yield` statement isn't
allowed inside the :keyword:`try` block of a :keyword:`try`...\
:keyword:`finally` statement; read :pep:`255` for a full explanation of the
interaction between :keyword:`yield` and exceptions.)
Here's a sample usage of the :func:`generate_ints` generator::
>>> gen = generate_ints(3)
>>> gen
<generator object at 0x8117f90>
>>> gen.next()
0
>>> gen.next()
1
>>> gen.next()
2
>>> gen.next()
Traceback (most recent call last):
File "<stdin>", line 1, in ?
File "<stdin>", line 2, in generate_ints
StopIteration
You could equally write ``for i in generate_ints(5)``, or ``a,b,c =
generate_ints(3)``.
Inside a generator function, the :keyword:`return` statement can only be used
without a value, and signals the end of the procession of values; afterwards the
generator cannot return any further values. :keyword:`return` with a value, such
as ``return 5``, is a syntax error inside a generator function. The end of the
generator's results can also be indicated by raising :exc:`StopIteration`
manually, or by just letting the flow of execution fall off the bottom of the
function.
You could achieve the effect of generators manually by writing your own class
and storing all the local variables of the generator as instance variables. For
example, returning a list of integers could be done by setting ``self.count`` to
0, and having the :meth:`next` method increment ``self.count`` and return it.
However, for a moderately complicated generator, writing a corresponding class
would be much messier. :file:`Lib/test/test_generators.py` contains a number of
more interesting examples. The simplest one implements an in-order traversal of
a tree using generators recursively. ::
# A recursive generator that generates Tree leaves in in-order.
def inorder(t):
if t:
for x in inorder(t.left):
yield x
yield t.label
for x in inorder(t.right):
yield x
Two other examples in :file:`Lib/test/test_generators.py` produce solutions for
the N-Queens problem (placing $N$ queens on an $NxN$ chess board so that no
queen threatens another) and the Knight's Tour (a route that takes a knight to
every square of an $NxN$ chessboard without visiting any square twice).
The idea of generators comes from other programming languages, especially Icon
(https://www.cs.arizona.edu/icon/), where the idea of generators is central. In
Icon, every expression and function call behaves like a generator. One example
from "An Overview of the Icon Programming Language" at
https://www.cs.arizona.edu/icon/docs/ipd266.htm gives an idea of what this looks
like::
sentence := "Store it in the neighboring harbor"
if (i := find("or", sentence)) > 5 then write(i)
In Icon the :func:`find` function returns the indexes at which the substring
"or" is found: 3, 23, 33. In the :keyword:`if` statement, ``i`` is first
assigned a value of 3, but 3 is less than 5, so the comparison fails, and Icon
retries it with the second value of 23. 23 is greater than 5, so the comparison
now succeeds, and the code prints the value 23 to the screen.
Python doesn't go nearly as far as Icon in adopting generators as a central
concept. Generators are considered a new part of the core Python language, but
learning or using them isn't compulsory; if they don't solve any problems that
you have, feel free to ignore them. One novel feature of Python's interface as
compared to Icon's is that a generator's state is represented as a concrete
object (the iterator) that can be passed around to other functions or stored in
a data structure.
.. seealso::
:pep:`255` - Simple Generators
Written by Neil Schemenauer, Tim Peters, Magnus Lie Hetland. Implemented mostly
by Neil Schemenauer and Tim Peters, with other fixes from the Python Labs crew.
.. ======================================================================
PEP 237: Unifying Long Integers and Integers
============================================
In recent versions, the distinction between regular integers, which are 32-bit
values on most machines, and long integers, which can be of arbitrary size, was
becoming an annoyance. For example, on platforms that support files larger than
``2**32`` bytes, the :meth:`tell` method of file objects has to return a long
integer. However, there were various bits of Python that expected plain integers
and would raise an error if a long integer was provided instead. For example,
in Python 1.5, only regular integers could be used as a slice index, and
``'abc'[1L:]`` would raise a :exc:`TypeError` exception with the message 'slice
index must be int'.
Python 2.2 will shift values from short to long integers as required. The 'L'
suffix is no longer needed to indicate a long integer literal, as now the
compiler will choose the appropriate type. (Using the 'L' suffix will be
discouraged in future 2.x versions of Python, triggering a warning in Python
2.4, and probably dropped in Python 3.0.) Many operations that used to raise an
:exc:`OverflowError` will now return a long integer as their result. For
example::
>>> 1234567890123
1234567890123L
>>> 2 ** 64
18446744073709551616L
In most cases, integers and long integers will now be treated identically. You
can still distinguish them with the :func:`type` built-in function, but that's
rarely needed.
.. seealso::
:pep:`237` - Unifying Long Integers and Integers
Written by Moshe Zadka and Guido van Rossum. Implemented mostly by Guido van
Rossum.
.. ======================================================================
PEP 238: Changing the Division Operator
=======================================
The most controversial change in Python 2.2 heralds the start of an effort to
fix an old design flaw that's been in Python from the beginning. Currently
Python's division operator, ``/``, behaves like C's division operator when
presented with two integer arguments: it returns an integer result that's
truncated down when there would be a fractional part. For example, ``3/2`` is
1, not 1.5, and ``(-1)/2`` is -1, not -0.5. This means that the results of
division can vary unexpectedly depending on the type of the two operands and
because Python is dynamically typed, it can be difficult to determine the
possible types of the operands.
(The controversy is over whether this is *really* a design flaw, and whether
it's worth breaking existing code to fix this. It's caused endless discussions
on python-dev, and in July 2001 erupted into a storm of acidly sarcastic
postings on :newsgroup:`comp.lang.python`. I won't argue for either side here
and will stick to describing what's implemented in 2.2. Read :pep:`238` for a
summary of arguments and counter-arguments.)
Because this change might break code, it's being introduced very gradually.
Python 2.2 begins the transition, but the switch won't be complete until Python
3.0.
First, I'll borrow some terminology from :pep:`238`. "True division" is the
division that most non-programmers are familiar with: 3/2 is 1.5, 1/4 is 0.25,
and so forth. "Floor division" is what Python's ``/`` operator currently does
when given integer operands; the result is the floor of the value returned by
true division. "Classic division" is the current mixed behaviour of ``/``; it
returns the result of floor division when the operands are integers, and returns
the result of true division when one of the operands is a floating-point number.
Here are the changes 2.2 introduces:
* A new operator, ``//``, is the floor division operator. (Yes, we know it looks
like C++'s comment symbol.) ``//`` *always* performs floor division no matter
what the types of its operands are, so ``1 // 2`` is 0 and ``1.0 // 2.0`` is
also 0.0.
``//`` is always available in Python 2.2; you don't need to enable it using a
``__future__`` statement.
* By including a ``from __future__ import division`` in a module, the ``/``
operator will be changed to return the result of true division, so ``1/2`` is
0.5. Without the ``__future__`` statement, ``/`` still means classic division.
The default meaning of ``/`` will not change until Python 3.0.
* Classes can define methods called :meth:`__truediv__` and :meth:`__floordiv__`
to overload the two division operators. At the C level, there are also slots in
the :c:type:`PyNumberMethods` structure so extension types can define the two
operators.
* Python 2.2 supports some command-line arguments for testing whether code will
work with the changed division semantics. Running python with :option:`-Q
warn <-Q>` will cause a warning to be issued whenever division is applied to two
integers. You can use this to find code that's affected by the change and fix
it. By default, Python 2.2 will simply perform classic division without a
warning; the warning will be turned on by default in Python 2.3.
.. seealso::
:pep:`238` - Changing the Division Operator
Written by Moshe Zadka and Guido van Rossum. Implemented by Guido van Rossum..
.. ======================================================================
Unicode Changes
===============
Python's Unicode support has been enhanced a bit in 2.2. Unicode strings are
usually stored as UCS-2, as 16-bit unsigned integers. Python 2.2 can also be
compiled to use UCS-4, 32-bit unsigned integers, as its internal encoding by
supplying :option:`!--enable-unicode=ucs4` to the configure script. (It's also
possible to specify :option:`!--disable-unicode` to completely disable Unicode
support.)
When built to use UCS-4 (a "wide Python"), the interpreter can natively handle
Unicode characters from U+000000 to U+110000, so the range of legal values for
the :func:`unichr` function is expanded accordingly. Using an interpreter
compiled to use UCS-2 (a "narrow Python"), values greater than 65535 will still
cause :func:`unichr` to raise a :exc:`ValueError` exception. This is all
described in :pep:`261`, "Support for 'wide' Unicode characters"; consult it for
further details.
Another change is simpler to explain. Since their introduction, Unicode strings
have supported an :meth:`encode` method to convert the string to a selected
encoding such as UTF-8 or Latin-1. A symmetric ``decode([*encoding*])``
method has been added to 8-bit strings (though not to Unicode strings) in 2.2.
:meth:`decode` assumes that the string is in the specified encoding and decodes
it, returning whatever is returned by the codec.
Using this new feature, codecs have been added for tasks not directly related to
Unicode. For example, codecs have been added for uu-encoding, MIME's base64
encoding, and compression with the :mod:`zlib` module::
>>> s = """Here is a lengthy piece of redundant, overly verbose,
... and repetitive text.
... """
>>> data = s.encode('zlib')
>>> data
'x\x9c\r\xc9\xc1\r\x80 \x10\x04\xc0?Ul...'
>>> data.decode('zlib')
'Here is a lengthy piece of redundant, overly verbose,\nand repetitive text.\n'
>>> print s.encode('uu')
begin 666 <data>
M2&5R92!I<R!A(&QE;F=T:'D@<&EE8V4@;V8@<F5D=6YD86YT+"!O=F5R;'D@
>=F5R8F]S92P*86YD(')E<&5T:71I=F4@=&5X="X*
end
>>> "sheesh".encode('rot-13')
'furrfu'
To convert a class instance to Unicode, a :meth:`__unicode__` method can be
defined by a class, analogous to :meth:`__str__`.
:meth:`encode`, :meth:`decode`, and :meth:`__unicode__` were implemented by
Marc-André Lemburg. The changes to support using UCS-4 internally were
implemented by Fredrik Lundh and Martin von Löwis.
.. seealso::
:pep:`261` - Support for 'wide' Unicode characters
Written by Paul Prescod.
.. ======================================================================
PEP 227: Nested Scopes
======================
In Python 2.1, statically nested scopes were added as an optional feature, to be
enabled by a ``from __future__ import nested_scopes`` directive. In 2.2 nested
scopes no longer need to be specially enabled, and are now always present. The
rest of this section is a copy of the description of nested scopes from my
"What's New in Python 2.1" document; if you read it when 2.1 came out, you can
skip the rest of this section.
The largest change introduced in Python 2.1, and made complete in 2.2, is to
Python's scoping rules. In Python 2.0, at any given time there are at most
three namespaces used to look up variable names: local, module-level, and the
built-in namespace. This often surprised people because it didn't match their
intuitive expectations. For example, a nested recursive function definition
doesn't work::
def f():
...
def g(value):
...
return g(value-1) + 1
...
The function :func:`g` will always raise a :exc:`NameError` exception, because
the binding of the name ``g`` isn't in either its local namespace or in the
module-level namespace. This isn't much of a problem in practice (how often do
you recursively define interior functions like this?), but this also made using
the :keyword:`lambda` statement clumsier, and this was a problem in practice.
In code which uses :keyword:`lambda` you can often find local variables being
copied by passing them as the default values of arguments. ::
def find(self, name):
"Return list of any entries equal to 'name'"
L = filter(lambda x, name=name: x == name,
self.list_attribute)
return L
The readability of Python code written in a strongly functional style suffers
greatly as a result.
The most significant change to Python 2.2 is that static scoping has been added
to the language to fix this problem. As a first effect, the ``name=name``
default argument is now unnecessary in the above example. Put simply, when a
given variable name is not assigned a value within a function (by an assignment,
or the :keyword:`def`, :keyword:`class`, or :keyword:`import` statements),
references to the variable will be looked up in the local namespace of the
enclosing scope. A more detailed explanation of the rules, and a dissection of
the implementation, can be found in the PEP.
This change may cause some compatibility problems for code where the same
variable name is used both at the module level and as a local variable within a
function that contains further function definitions. This seems rather unlikely
though, since such code would have been pretty confusing to read in the first
place.
One side effect of the change is that the ``from module import *`` and
:keyword:`exec` statements have been made illegal inside a function scope under
certain conditions. The Python reference manual has said all along that ``from
module import *`` is only legal at the top level of a module, but the CPython
interpreter has never enforced this before. As part of the implementation of
nested scopes, the compiler which turns Python source into bytecodes has to
generate different code to access variables in a containing scope. ``from
module import *`` and :keyword:`exec` make it impossible for the compiler to
figure this out, because they add names to the local namespace that are
unknowable at compile time. Therefore, if a function contains function
definitions or :keyword:`lambda` expressions with free variables, the compiler
will flag this by raising a :exc:`SyntaxError` exception.
To make the preceding explanation a bit clearer, here's an example::
x = 1
def f():
# The next line is a syntax error
exec 'x=2'
def g():
return x
Line 4 containing the :keyword:`exec` statement is a syntax error, since
:keyword:`exec` would define a new local variable named ``x`` whose value should
be accessed by :func:`g`.
This shouldn't be much of a limitation, since :keyword:`exec` is rarely used in
most Python code (and when it is used, it's often a sign of a poor design
anyway).
.. seealso::
:pep:`227` - Statically Nested Scopes
Written and implemented by Jeremy Hylton.
.. ======================================================================
New and Improved Modules
========================
* The :mod:`xmlrpclib` module was contributed to the standard library by Fredrik
Lundh, providing support for writing XML-RPC clients. XML-RPC is a simple
remote procedure call protocol built on top of HTTP and XML. For example, the
following snippet retrieves a list of RSS channels from the O'Reilly Network,
and then lists the recent headlines for one channel::
import xmlrpclib
s = xmlrpclib.Server(
'http://www.oreillynet.com/meerkat/xml-rpc/server.php')
channels = s.meerkat.getChannels()
# channels is a list of dictionaries, like this:
# [{'id': 4, 'title': 'Freshmeat Daily News'}
# {'id': 190, 'title': '32Bits Online'},
# {'id': 4549, 'title': '3DGamers'}, ... ]
# Get the items for one channel
items = s.meerkat.getItems( {'channel': 4} )
# 'items' is another list of dictionaries, like this:
# [{'link': 'http://freshmeat.net/releases/52719/',
# 'description': 'A utility which converts HTML to XSL FO.',
# 'title': 'html2fo 0.3 (Default)'}, ... ]
The :mod:`SimpleXMLRPCServer` module makes it easy to create straightforward
XML-RPC servers. See http://www.xmlrpc.com/ for more information about XML-RPC.
* The new :mod:`hmac` module implements the HMAC algorithm described by
:rfc:`2104`. (Contributed by Gerhard Häring.)
* Several functions that originally returned lengthy tuples now return
pseudo-sequences that still behave like tuples but also have mnemonic attributes such
as memberst_mtime or :attr:`tm_year`. The enhanced functions include
:func:`stat`, :func:`fstat`, :func:`statvfs`, and :func:`fstatvfs` in the
:mod:`os` module, and :func:`localtime`, :func:`gmtime`, and :func:`strptime` in
the :mod:`time` module.
For example, to obtain a file's size using the old tuples, you'd end up writing
something like ``file_size = os.stat(filename)[stat.ST_SIZE]``, but now this can
be written more clearly as ``file_size = os.stat(filename).st_size``.
The original patch for this feature was contributed by Nick Mathewson.
* The Python profiler has been extensively reworked and various errors in its
output have been corrected. (Contributed by Fred L. Drake, Jr. and Tim Peters.)
* The :mod:`socket` module can be compiled to support IPv6; specify the
:option:`!--enable-ipv6` option to Python's configure script. (Contributed by
Jun-ichiro "itojun" Hagino.)
* Two new format characters were added to the :mod:`struct` module for 64-bit
integers on platforms that support the C :c:type:`long long` type. ``q`` is for
a signed 64-bit integer, and ``Q`` is for an unsigned one. The value is
returned in Python's long integer type. (Contributed by Tim Peters.)
* In the interpreter's interactive mode, there's a new built-in function
:func:`help` that uses the :mod:`pydoc` module introduced in Python 2.1 to
provide interactive help. ``help(object)`` displays any available help text
about *object*. :func:`help` with no argument puts you in an online help
utility, where you can enter the names of functions, classes, or modules to read
their help text. (Contributed by Guido van Rossum, using Ka-Ping Yee's
:mod:`pydoc` module.)
* Various bugfixes and performance improvements have been made to the SRE engine
underlying the :mod:`re` module. For example, the :func:`re.sub` and
:func:`re.split` functions have been rewritten in C. Another contributed patch
speeds up certain Unicode character ranges by a factor of two, and a new
:meth:`finditer` method that returns an iterator over all the non-overlapping
matches in a given string. (SRE is maintained by Fredrik Lundh. The
BIGCHARSET patch was contributed by Martin von Löwis.)
* The :mod:`smtplib` module now supports :rfc:`2487`, "Secure SMTP over TLS", so
it's now possible to encrypt the SMTP traffic between a Python program and the
mail transport agent being handed a message. :mod:`smtplib` also supports SMTP
authentication. (Contributed by Gerhard Häring.)
* The :mod:`imaplib` module, maintained by Piers Lauder, has support for several
new extensions: the NAMESPACE extension defined in :rfc:`2342`, SORT, GETACL and
SETACL. (Contributed by Anthony Baxter and Michel Pelletier.)
* The :mod:`rfc822` module's parsing of email addresses is now compliant with
:rfc:`2822`, an update to :rfc:`822`. (The module's name is *not* going to be
changed to ``rfc2822``.) A new package, :mod:`email`, has also been added for
parsing and generating e-mail messages. (Contributed by Barry Warsaw, and
arising out of his work on Mailman.)
* The :mod:`difflib` module now contains a new :class:`Differ` class for
producing human-readable lists of changes (a "delta") between two sequences of
lines of text. There are also two generator functions, :func:`ndiff` and
:func:`restore`, which respectively return a delta from two sequences, or one of
the original sequences from a delta. (Grunt work contributed by David Goodger,
from ndiff.py code by Tim Peters who then did the generatorization.)
* New constants :const:`ascii_letters`, :const:`ascii_lowercase`, and
:const:`ascii_uppercase` were added to the :mod:`string` module. There were
several modules in the standard library that used :const:`string.letters` to
mean the ranges A-Za-z, but that assumption is incorrect when locales are in
use, because :const:`string.letters` varies depending on the set of legal
characters defined by the current locale. The buggy modules have all been fixed
to use :const:`ascii_letters` instead. (Reported by an unknown person; fixed by
Fred L. Drake, Jr.)
* The :mod:`mimetypes` module now makes it easier to use alternative MIME-type
databases by the addition of a :class:`MimeTypes` class, which takes a list of
filenames to be parsed. (Contributed by Fred L. Drake, Jr.)
* A :class:`Timer` class was added to the :mod:`threading` module that allows
scheduling an activity to happen at some future time. (Contributed by Itamar
Shtull-Trauring.)
.. ======================================================================
Interpreter Changes and Fixes
=============================
Some of the changes only affect people who deal with the Python interpreter at
the C level because they're writing Python extension modules, embedding the
interpreter, or just hacking on the interpreter itself. If you only write Python
code, none of the changes described here will affect you very much.
* Profiling and tracing functions can now be implemented in C, which can operate
at much higher speeds than Python-based functions and should reduce the overhead
of profiling and tracing. This will be of interest to authors of development
environments for Python. Two new C functions were added to Python's API,
:c:func:`PyEval_SetProfile` and :c:func:`PyEval_SetTrace`. The existing
:func:`sys.setprofile` and :func:`sys.settrace` functions still exist, and have
simply been changed to use the new C-level interface. (Contributed by Fred L.
Drake, Jr.)
* Another low-level API, primarily of interest to implementors of Python
debuggers and development tools, was added. :c:func:`PyInterpreterState_Head` and
:c:func:`PyInterpreterState_Next` let a caller walk through all the existing
interpreter objects; :c:func:`PyInterpreterState_ThreadHead` and
:c:func:`PyThreadState_Next` allow looping over all the thread states for a given
interpreter. (Contributed by David Beazley.)
* The C-level interface to the garbage collector has been changed to make it
easier to write extension types that support garbage collection and to debug
misuses of the functions. Various functions have slightly different semantics,
so a bunch of functions had to be renamed. Extensions that use the old API will
still compile but will *not* participate in garbage collection, so updating them
for 2.2 should be considered fairly high priority.
To upgrade an extension module to the new API, perform the following steps:
* Rename :c:func:`Py_TPFLAGS_GC` to :c:func:`PyTPFLAGS_HAVE_GC`.
* Use :c:func:`PyObject_GC_New` or :c:func:`PyObject_GC_NewVar` to allocate
objects, and :c:func:`PyObject_GC_Del` to deallocate them.
* Rename :c:func:`PyObject_GC_Init` to :c:func:`PyObject_GC_Track` and
:c:func:`PyObject_GC_Fini` to :c:func:`PyObject_GC_UnTrack`.
* Remove :c:func:`PyGC_HEAD_SIZE` from object size calculations.
* Remove calls to :c:func:`PyObject_AS_GC` and :c:func:`PyObject_FROM_GC`.
* A new ``et`` format sequence was added to :c:func:`PyArg_ParseTuple`; ``et``
takes both a parameter and an encoding name, and converts the parameter to the
given encoding if the parameter turns out to be a Unicode string, or leaves it
alone if it's an 8-bit string, assuming it to already be in the desired
encoding. This differs from the ``es`` format character, which assumes that
8-bit strings are in Python's default ASCII encoding and converts them to the
specified new encoding. (Contributed by M.-A. Lemburg, and used for the MBCS
support on Windows described in the following section.)
* A different argument parsing function, :c:func:`PyArg_UnpackTuple`, has been
added that's simpler and presumably faster. Instead of specifying a format
string, the caller simply gives the minimum and maximum number of arguments
expected, and a set of pointers to :c:type:`PyObject\*` variables that will be
filled in with argument values.
* Two new flags :const:`METH_NOARGS` and :const:`METH_O` are available in method
definition tables to simplify implementation of methods with no arguments or a
single untyped argument. Calling such methods is more efficient than calling a
corresponding method that uses :const:`METH_VARARGS`. Also, the old
:const:`METH_OLDARGS` style of writing C methods is now officially deprecated.
* Two new wrapper functions, :c:func:`PyOS_snprintf` and :c:func:`PyOS_vsnprintf`
were added to provide cross-platform implementations for the relatively new
:c:func:`snprintf` and :c:func:`vsnprintf` C lib APIs. In contrast to the standard
:c:func:`sprintf` and :c:func:`vsprintf` functions, the Python versions check the
bounds of the buffer used to protect against buffer overruns. (Contributed by
M.-A. Lemburg.)
* The :c:func:`_PyTuple_Resize` function has lost an unused parameter, so now it
takes 2 parameters instead of 3. The third argument was never used, and can
simply be discarded when porting code from earlier versions to Python 2.2.
.. ======================================================================
Other Changes and Fixes
=======================
As usual there were a bunch of other improvements and bugfixes scattered
throughout the source tree. A search through the CVS change logs finds there
were 527 patches applied and 683 bugs fixed between Python 2.1 and 2.2; 2.2.1
applied 139 patches and fixed 143 bugs; 2.2.2 applied 106 patches and fixed 82
bugs. These figures are likely to be underestimates.
Some of the more notable changes are:
* The code for the MacOS port for Python, maintained by Jack Jansen, is now kept
in the main Python CVS tree, and many changes have been made to support MacOS X.
The most significant change is the ability to build Python as a framework,
enabled by supplying the :option:`!--enable-framework` option to the configure
script when compiling Python. According to Jack Jansen, "This installs a
self-contained Python installation plus the OS X framework "glue" into
:file:`/Library/Frameworks/Python.framework` (or another location of choice).
For now there is little immediate added benefit to this (actually, there is the
disadvantage that you have to change your PATH to be able to find Python), but
it is the basis for creating a full-blown Python application, porting the
MacPython IDE, possibly using Python as a standard OSA scripting language and
much more."
Most of the MacPython toolbox modules, which interface to MacOS APIs such as
windowing, QuickTime, scripting, etc. have been ported to OS X, but they've been
left commented out in :file:`setup.py`. People who want to experiment with
these modules can uncomment them manually.
.. Jack's original comments:
The main change is the possibility to build Python as a
framework. This installs a self-contained Python installation plus the
OSX framework "glue" into /Library/Frameworks/Python.framework (or
another location of choice). For now there is little immediate added
benefit to this (actually, there is the disadvantage that you have to
change your PATH to be able to find Python), but it is the basis for
creating a fullblown Python application, porting the MacPython IDE,
possibly using Python as a standard OSA scripting language and much
more. You enable this with "configure --enable-framework".
The other change is that most MacPython toolbox modules, which
interface to all the MacOS APIs such as windowing, quicktime,
scripting, etc. have been ported. Again, most of these are not of
immediate use, as they need a full application to be really useful, so
they have been commented out in setup.py. People wanting to experiment
can uncomment them. Gestalt and Internet Config modules are enabled by
default.
* Keyword arguments passed to built-in functions that don't take them now cause a
:exc:`TypeError` exception to be raised, with the message "*function* takes no
keyword arguments".
* Weak references, added in Python 2.1 as an extension module, are now part of
the core because they're used in the implementation of new-style classes. The
:exc:`ReferenceError` exception has therefore moved from the :mod:`weakref`
module to become a built-in exception.
* A new script, :file:`Tools/scripts/cleanfuture.py` by Tim Peters,
automatically removes obsolete ``__future__`` statements from Python source
code.
* An additional *flags* argument has been added to the built-in function
:func:`compile`, so the behaviour of ``__future__`` statements can now be
correctly observed in simulated shells, such as those presented by IDLE and
other development environments. This is described in :pep:`264`. (Contributed
by Michael Hudson.)
* The new license introduced with Python 1.6 wasn't GPL-compatible. This is
fixed by some minor textual changes to the 2.2 license, so it's now legal to
embed Python inside a GPLed program again. Note that Python itself is not
GPLed, but instead is under a license that's essentially equivalent to the BSD
license, same as it always was. The license changes were also applied to the
Python 2.0.1 and 2.1.1 releases.
* When presented with a Unicode filename on Windows, Python will now convert it
to an MBCS encoded string, as used by the Microsoft file APIs. As MBCS is
explicitly used by the file APIs, Python's choice of ASCII as the default
encoding turns out to be an annoyance. On Unix, the locale's character set is
used if ``locale.nl_langinfo(CODESET)`` is available. (Windows support was
contributed by Mark Hammond with assistance from Marc-André Lemburg. Unix
support was added by Martin von Löwis.)
* Large file support is now enabled on Windows. (Contributed by Tim Peters.)
* The :file:`Tools/scripts/ftpmirror.py` script now parses a :file:`.netrc`
file, if you have one. (Contributed by Mike Romberg.)
* Some features of the object returned by the :func:`xrange` function are now
deprecated, and trigger warnings when they're accessed; they'll disappear in
Python 2.3. :class:`xrange` objects tried to pretend they were full sequence
types by supporting slicing, sequence multiplication, and the :keyword:`in`
operator, but these features were rarely used and therefore buggy. The
:meth:`tolist` method and the :attr:`start`, :attr:`stop`, and :attr:`step`
attributes are also being deprecated. At the C level, the fourth argument to
the :c:func:`PyRange_New` function, ``repeat``, has also been deprecated.
* There were a bunch of patches to the dictionary implementation, mostly to fix
potential core dumps if a dictionary contains objects that sneakily changed
their hash value, or mutated the dictionary they were contained in. For a while
python-dev fell into a gentle rhythm of Michael Hudson finding a case that
dumped core, Tim Peters fixing the bug, Michael finding another case, and round
and round it went.
* On Windows, Python can now be compiled with Borland C thanks to a number of
patches contributed by Stephen Hansen, though the result isn't fully functional
yet. (But this *is* progress...)
* Another Windows enhancement: Wise Solutions generously offered PythonLabs use
of their InstallerMaster 8.1 system. Earlier PythonLabs Windows installers used
Wise 5.0a, which was beginning to show its age. (Packaged up by Tim Peters.)
* Files ending in ``.pyw`` can now be imported on Windows. ``.pyw`` is a
Windows-only thing, used to indicate that a script needs to be run using
PYTHONW.EXE instead of PYTHON.EXE in order to prevent a DOS console from popping
up to display the output. This patch makes it possible to import such scripts,
in case they're also usable as modules. (Implemented by David Bolen.)
* On platforms where Python uses the C :c:func:`dlopen` function to load
extension modules, it's now possible to set the flags used by :c:func:`dlopen`
using the :func:`sys.getdlopenflags` and :func:`sys.setdlopenflags` functions.
(Contributed by Bram Stolk.)
* The :func:`pow` built-in function no longer supports 3 arguments when
floating-point numbers are supplied. ``pow(x, y, z)`` returns ``(x**y) % z``,
but this is never useful for floating point numbers, and the final result varies
unpredictably depending on the platform. A call such as ``pow(2.0, 8.0, 7.0)``
will now raise a :exc:`TypeError` exception.
.. ======================================================================
Acknowledgements
================
The author would like to thank the following people for offering suggestions,
corrections and assistance with various drafts of this article: Fred Bremmer,
Keith Briggs, Andrew Dalke, Fred L. Drake, Jr., Carel Fellinger, David Goodger,
Mark Hammond, Stephen Hansen, Michael Hudson, Jack Jansen, Marc-André Lemburg,
Martin von Löwis, Fredrik Lundh, Michael McLay, Nick Mathewson, Paul Moore,
Gustavo Niemeyer, Don O'Donnell, Joonas Paalasma, Tim Peters, Jens Quade, Tom
Reinhardt, Neil Schemenauer, Guido van Rossum, Greg Ward, Edward Welbourne.
PK
%�\���?^ ?^ " html/_sources/whatsnew/2.3.rst.txtnu �[��� ****************************
What's New in Python 2.3
****************************
:Author: A.M. Kuchling
.. |release| replace:: 1.01
.. $Id: whatsnew23.tex 54631 2007-03-31 11:58:36Z georg.brandl $
This article explains the new features in Python 2.3. Python 2.3 was released
on July 29, 2003.
The main themes for Python 2.3 are polishing some of the features added in 2.2,
adding various small but useful enhancements to the core language, and expanding
the standard library. The new object model introduced in the previous version
has benefited from 18 months of bugfixes and from optimization efforts that have
improved the performance of new-style classes. A few new built-in functions
have been added such as :func:`sum` and :func:`enumerate`. The :keyword:`in`
operator can now be used for substring searches (e.g. ``"ab" in "abc"`` returns
:const:`True`).
Some of the many new library features include Boolean, set, heap, and date/time
data types, the ability to import modules from ZIP-format archives, metadata
support for the long-awaited Python catalog, an updated version of IDLE, and
modules for logging messages, wrapping text, parsing CSV files, processing
command-line options, using BerkeleyDB databases... the list of new and
enhanced modules is lengthy.
This article doesn't attempt to provide a complete specification of the new
features, but instead provides a convenient overview. For full details, you
should refer to the documentation for Python 2.3, such as the Python Library
Reference and the Python Reference Manual. If you want to understand the
complete implementation and design rationale, refer to the PEP for a particular
new feature.
.. ======================================================================
PEP 218: A Standard Set Datatype
================================
The new :mod:`sets` module contains an implementation of a set datatype. The
:class:`Set` class is for mutable sets, sets that can have members added and
removed. The :class:`ImmutableSet` class is for sets that can't be modified,
and instances of :class:`ImmutableSet` can therefore be used as dictionary keys.
Sets are built on top of dictionaries, so the elements within a set must be
hashable.
Here's a simple example::
>>> import sets
>>> S = sets.Set([1,2,3])
>>> S
Set([1, 2, 3])
>>> 1 in S
True
>>> 0 in S
False
>>> S.add(5)
>>> S.remove(3)
>>> S
Set([1, 2, 5])
>>>
The union and intersection of sets can be computed with the :meth:`union` and
:meth:`intersection` methods; an alternative notation uses the bitwise operators
``&`` and ``|``. Mutable sets also have in-place versions of these methods,
:meth:`union_update` and :meth:`intersection_update`. ::
>>> S1 = sets.Set([1,2,3])
>>> S2 = sets.Set([4,5,6])
>>> S1.union(S2)
Set([1, 2, 3, 4, 5, 6])
>>> S1 | S2 # Alternative notation
Set([1, 2, 3, 4, 5, 6])
>>> S1.intersection(S2)
Set([])
>>> S1 & S2 # Alternative notation
Set([])
>>> S1.union_update(S2)
>>> S1
Set([1, 2, 3, 4, 5, 6])
>>>
It's also possible to take the symmetric difference of two sets. This is the
set of all elements in the union that aren't in the intersection. Another way
of putting it is that the symmetric difference contains all elements that are in
exactly one set. Again, there's an alternative notation (``^``), and an
in-place version with the ungainly name :meth:`symmetric_difference_update`. ::
>>> S1 = sets.Set([1,2,3,4])
>>> S2 = sets.Set([3,4,5,6])
>>> S1.symmetric_difference(S2)
Set([1, 2, 5, 6])
>>> S1 ^ S2
Set([1, 2, 5, 6])
>>>
There are also :meth:`issubset` and :meth:`issuperset` methods for checking
whether one set is a subset or superset of another::
>>> S1 = sets.Set([1,2,3])
>>> S2 = sets.Set([2,3])
>>> S2.issubset(S1)
True
>>> S1.issubset(S2)
False
>>> S1.issuperset(S2)
True
>>>
.. seealso::
:pep:`218` - Adding a Built-In Set Object Type
PEP written by Greg V. Wilson. Implemented by Greg V. Wilson, Alex Martelli, and
GvR.
.. ======================================================================
.. _section-generators:
PEP 255: Simple Generators
==========================
In Python 2.2, generators were added as an optional feature, to be enabled by a
``from __future__ import generators`` directive. In 2.3 generators no longer
need to be specially enabled, and are now always present; this means that
:keyword:`yield` is now always a keyword. The rest of this section is a copy of
the description of generators from the "What's New in Python 2.2" document; if
you read it back when Python 2.2 came out, you can skip the rest of this
section.
You're doubtless familiar with how function calls work in Python or C. When you
call a function, it gets a private namespace where its local variables are
created. When the function reaches a :keyword:`return` statement, the local
variables are destroyed and the resulting value is returned to the caller. A
later call to the same function will get a fresh new set of local variables.
But, what if the local variables weren't thrown away on exiting a function?
What if you could later resume the function where it left off? This is what
generators provide; they can be thought of as resumable functions.
Here's the simplest example of a generator function::
def generate_ints(N):
for i in range(N):
yield i
A new keyword, :keyword:`yield`, was introduced for generators. Any function
containing a :keyword:`yield` statement is a generator function; this is
detected by Python's bytecode compiler which compiles the function specially as
a result.
When you call a generator function, it doesn't return a single value; instead it
returns a generator object that supports the iterator protocol. On executing
the :keyword:`yield` statement, the generator outputs the value of ``i``,
similar to a :keyword:`return` statement. The big difference between
:keyword:`yield` and a :keyword:`return` statement is that on reaching a
:keyword:`yield` the generator's state of execution is suspended and local
variables are preserved. On the next call to the generator's ``.next()``
method, the function will resume executing immediately after the
:keyword:`yield` statement. (For complicated reasons, the :keyword:`yield`
statement isn't allowed inside the :keyword:`try` block of a :keyword:`try`...\
:keyword:`finally` statement; read :pep:`255` for a full explanation of the
interaction between :keyword:`yield` and exceptions.)
Here's a sample usage of the :func:`generate_ints` generator::
>>> gen = generate_ints(3)
>>> gen
<generator object at 0x8117f90>
>>> gen.next()
0
>>> gen.next()
1
>>> gen.next()
2
>>> gen.next()
Traceback (most recent call last):
File "stdin", line 1, in ?
File "stdin", line 2, in generate_ints
StopIteration
You could equally write ``for i in generate_ints(5)``, or ``a,b,c =
generate_ints(3)``.
Inside a generator function, the :keyword:`return` statement can only be used
without a value, and signals the end of the procession of values; afterwards the
generator cannot return any further values. :keyword:`return` with a value, such
as ``return 5``, is a syntax error inside a generator function. The end of the
generator's results can also be indicated by raising :exc:`StopIteration`
manually, or by just letting the flow of execution fall off the bottom of the
function.
You could achieve the effect of generators manually by writing your own class
and storing all the local variables of the generator as instance variables. For
example, returning a list of integers could be done by setting ``self.count`` to
0, and having the :meth:`next` method increment ``self.count`` and return it.
However, for a moderately complicated generator, writing a corresponding class
would be much messier. :file:`Lib/test/test_generators.py` contains a number of
more interesting examples. The simplest one implements an in-order traversal of
a tree using generators recursively. ::
# A recursive generator that generates Tree leaves in in-order.
def inorder(t):
if t:
for x in inorder(t.left):
yield x
yield t.label
for x in inorder(t.right):
yield x
Two other examples in :file:`Lib/test/test_generators.py` produce solutions for
the N-Queens problem (placing $N$ queens on an $NxN$ chess board so that no
queen threatens another) and the Knight's Tour (a route that takes a knight to
every square of an $NxN$ chessboard without visiting any square twice).
The idea of generators comes from other programming languages, especially Icon
(https://www.cs.arizona.edu/icon/), where the idea of generators is central. In
Icon, every expression and function call behaves like a generator. One example
from "An Overview of the Icon Programming Language" at
https://www.cs.arizona.edu/icon/docs/ipd266.htm gives an idea of what this looks
like::
sentence := "Store it in the neighboring harbor"
if (i := find("or", sentence)) > 5 then write(i)
In Icon the :func:`find` function returns the indexes at which the substring
"or" is found: 3, 23, 33. In the :keyword:`if` statement, ``i`` is first
assigned a value of 3, but 3 is less than 5, so the comparison fails, and Icon
retries it with the second value of 23. 23 is greater than 5, so the comparison
now succeeds, and the code prints the value 23 to the screen.
Python doesn't go nearly as far as Icon in adopting generators as a central
concept. Generators are considered part of the core Python language, but
learning or using them isn't compulsory; if they don't solve any problems that
you have, feel free to ignore them. One novel feature of Python's interface as
compared to Icon's is that a generator's state is represented as a concrete
object (the iterator) that can be passed around to other functions or stored in
a data structure.
.. seealso::
:pep:`255` - Simple Generators
Written by Neil Schemenauer, Tim Peters, Magnus Lie Hetland. Implemented mostly
by Neil Schemenauer and Tim Peters, with other fixes from the Python Labs crew.
.. ======================================================================
.. _section-encodings:
PEP 263: Source Code Encodings
==============================
Python source files can now be declared as being in different character set
encodings. Encodings are declared by including a specially formatted comment in
the first or second line of the source file. For example, a UTF-8 file can be
declared with::
#!/usr/bin/env python
# -*- coding: UTF-8 -*-
Without such an encoding declaration, the default encoding used is 7-bit ASCII.
Executing or importing modules that contain string literals with 8-bit
characters and have no encoding declaration will result in a
:exc:`DeprecationWarning` being signalled by Python 2.3; in 2.4 this will be a
syntax error.
The encoding declaration only affects Unicode string literals, which will be
converted to Unicode using the specified encoding. Note that Python identifiers
are still restricted to ASCII characters, so you can't have variable names that
use characters outside of the usual alphanumerics.
.. seealso::
:pep:`263` - Defining Python Source Code Encodings
Written by Marc-André Lemburg and Martin von Löwis; implemented by Suzuki Hisao
and Martin von Löwis.
.. ======================================================================
PEP 273: Importing Modules from ZIP Archives
============================================
The new :mod:`zipimport` module adds support for importing modules from a
ZIP-format archive. You don't need to import the module explicitly; it will be
automatically imported if a ZIP archive's filename is added to ``sys.path``.
For example:
.. code-block:: shell-session
amk@nyman:~/src/python$ unzip -l /tmp/example.zip
Archive: /tmp/example.zip
Length Date Time Name
-------- ---- ---- ----
8467 11-26-02 22:30 jwzthreading.py
-------- -------
8467 1 file
amk@nyman:~/src/python$ ./python
Python 2.3 (#1, Aug 1 2003, 19:54:32)
>>> import sys
>>> sys.path.insert(0, '/tmp/example.zip') # Add .zip file to front of path
>>> import jwzthreading
>>> jwzthreading.__file__
'/tmp/example.zip/jwzthreading.py'
>>>
An entry in ``sys.path`` can now be the filename of a ZIP archive. The ZIP
archive can contain any kind of files, but only files named :file:`\*.py`,
:file:`\*.pyc`, or :file:`\*.pyo` can be imported. If an archive only contains
:file:`\*.py` files, Python will not attempt to modify the archive by adding the
corresponding :file:`\*.pyc` file, meaning that if a ZIP archive doesn't contain
:file:`\*.pyc` files, importing may be rather slow.
A path within the archive can also be specified to only import from a
subdirectory; for example, the path :file:`/tmp/example.zip/lib/` would only
import from the :file:`lib/` subdirectory within the archive.
.. seealso::
:pep:`273` - Import Modules from Zip Archives
Written by James C. Ahlstrom, who also provided an implementation. Python 2.3
follows the specification in :pep:`273`, but uses an implementation written by
Just van Rossum that uses the import hooks described in :pep:`302`. See section
:ref:`section-pep302` for a description of the new import hooks.
.. ======================================================================
PEP 277: Unicode file name support for Windows NT
=================================================
On Windows NT, 2000, and XP, the system stores file names as Unicode strings.
Traditionally, Python has represented file names as byte strings, which is
inadequate because it renders some file names inaccessible.
Python now allows using arbitrary Unicode strings (within the limitations of the
file system) for all functions that expect file names, most notably the
:func:`open` built-in function. If a Unicode string is passed to
:func:`os.listdir`, Python now returns a list of Unicode strings. A new
function, :func:`os.getcwdu`, returns the current directory as a Unicode string.
Byte strings still work as file names, and on Windows Python will transparently
convert them to Unicode using the ``mbcs`` encoding.
Other systems also allow Unicode strings as file names but convert them to byte
strings before passing them to the system, which can cause a :exc:`UnicodeError`
to be raised. Applications can test whether arbitrary Unicode strings are
supported as file names by checking :attr:`os.path.supports_unicode_filenames`,
a Boolean value.
Under MacOS, :func:`os.listdir` may now return Unicode filenames.
.. seealso::
:pep:`277` - Unicode file name support for Windows NT
Written by Neil Hodgson; implemented by Neil Hodgson, Martin von Löwis, and Mark
Hammond.
.. ======================================================================
.. index::
single: universal newlines; What's new
PEP 278: Universal Newline Support
==================================
The three major operating systems used today are Microsoft Windows, Apple's
Macintosh OS, and the various Unix derivatives. A minor irritation of
cross-platform work is that these three platforms all use different characters to
mark the ends of lines in text files. Unix uses the linefeed (ASCII character
10), MacOS uses the carriage return (ASCII character 13), and Windows uses a
two-character sequence of a carriage return plus a newline.
Python's file objects can now support end of line conventions other than the
one followed by the platform on which Python is running. Opening a file with
the mode ``'U'`` or ``'rU'`` will open a file for reading in :term:`universal
newlines` mode. All three line ending conventions will be translated to a
``'\n'`` in the strings returned by the various file methods such as
:meth:`read` and :meth:`readline`.
Universal newline support is also used when importing modules and when executing
a file with the :func:`execfile` function. This means that Python modules can
be shared between all three operating systems without needing to convert the
line-endings.
This feature can be disabled when compiling Python by specifying the
:option:`!--without-universal-newlines` switch when running Python's
:program:`configure` script.
.. seealso::
:pep:`278` - Universal Newline Support
Written and implemented by Jack Jansen.
.. ======================================================================
.. _section-enumerate:
PEP 279: enumerate()
====================
A new built-in function, :func:`enumerate`, will make certain loops a bit
clearer. ``enumerate(thing)``, where *thing* is either an iterator or a
sequence, returns an iterator that will return ``(0, thing[0])``, ``(1,
thing[1])``, ``(2, thing[2])``, and so forth.
A common idiom to change every element of a list looks like this::
for i in range(len(L)):
item = L[i]
# ... compute some result based on item ...
L[i] = result
This can be rewritten using :func:`enumerate` as::
for i, item in enumerate(L):
# ... compute some result based on item ...
L[i] = result
.. seealso::
:pep:`279` - The enumerate() built-in function
Written and implemented by Raymond D. Hettinger.
.. ======================================================================
PEP 282: The logging Package
============================
A standard package for writing logs, :mod:`logging`, has been added to Python
2.3. It provides a powerful and flexible mechanism for generating logging
output which can then be filtered and processed in various ways. A
configuration file written in a standard format can be used to control the
logging behavior of a program. Python includes handlers that will write log
records to standard error or to a file or socket, send them to the system log,
or even e-mail them to a particular address; of course, it's also possible to
write your own handler classes.
The :class:`Logger` class is the primary class. Most application code will deal
with one or more :class:`Logger` objects, each one used by a particular
subsystem of the application. Each :class:`Logger` is identified by a name, and
names are organized into a hierarchy using ``.`` as the component separator.
For example, you might have :class:`Logger` instances named ``server``,
``server.auth`` and ``server.network``. The latter two instances are below
``server`` in the hierarchy. This means that if you turn up the verbosity for
``server`` or direct ``server`` messages to a different handler, the changes
will also apply to records logged to ``server.auth`` and ``server.network``.
There's also a root :class:`Logger` that's the parent of all other loggers.
For simple uses, the :mod:`logging` package contains some convenience functions
that always use the root log::
import logging
logging.debug('Debugging information')
logging.info('Informational message')
logging.warning('Warning:config file %s not found', 'server.conf')
logging.error('Error occurred')
logging.critical('Critical error -- shutting down')
This produces the following output::
WARNING:root:Warning:config file server.conf not found
ERROR:root:Error occurred
CRITICAL:root:Critical error -- shutting down
In the default configuration, informational and debugging messages are
suppressed and the output is sent to standard error. You can enable the display
of informational and debugging messages by calling the :meth:`setLevel` method
on the root logger.
Notice the :func:`warning` call's use of string formatting operators; all of the
functions for logging messages take the arguments ``(msg, arg1, arg2, ...)`` and
log the string resulting from ``msg % (arg1, arg2, ...)``.
There's also an :func:`exception` function that records the most recent
traceback. Any of the other functions will also record the traceback if you
specify a true value for the keyword argument *exc_info*. ::
def f():
try: 1/0
except: logging.exception('Problem recorded')
f()
This produces the following output::
ERROR:root:Problem recorded
Traceback (most recent call last):
File "t.py", line 6, in f
1/0
ZeroDivisionError: integer division or modulo by zero
Slightly more advanced programs will use a logger other than the root logger.
The ``getLogger(name)`` function is used to get a particular log, creating
it if it doesn't exist yet. ``getLogger(None)`` returns the root logger. ::
log = logging.getLogger('server')
...
log.info('Listening on port %i', port)
...
log.critical('Disk full')
...
Log records are usually propagated up the hierarchy, so a message logged to
``server.auth`` is also seen by ``server`` and ``root``, but a :class:`Logger`
can prevent this by setting its :attr:`propagate` attribute to :const:`False`.
There are more classes provided by the :mod:`logging` package that can be
customized. When a :class:`Logger` instance is told to log a message, it
creates a :class:`LogRecord` instance that is sent to any number of different
:class:`Handler` instances. Loggers and handlers can also have an attached list
of filters, and each filter can cause the :class:`LogRecord` to be ignored or
can modify the record before passing it along. When they're finally output,
:class:`LogRecord` instances are converted to text by a :class:`Formatter`
class. All of these classes can be replaced by your own specially-written
classes.
With all of these features the :mod:`logging` package should provide enough
flexibility for even the most complicated applications. This is only an
incomplete overview of its features, so please see the package's reference
documentation for all of the details. Reading :pep:`282` will also be helpful.
.. seealso::
:pep:`282` - A Logging System
Written by Vinay Sajip and Trent Mick; implemented by Vinay Sajip.
.. ======================================================================
.. _section-bool:
PEP 285: A Boolean Type
=======================
A Boolean type was added to Python 2.3. Two new constants were added to the
:mod:`__builtin__` module, :const:`True` and :const:`False`. (:const:`True` and
:const:`False` constants were added to the built-ins in Python 2.2.1, but the
2.2.1 versions are simply set to integer values of 1 and 0 and aren't a
different type.)
The type object for this new type is named :class:`bool`; the constructor for it
takes any Python value and converts it to :const:`True` or :const:`False`. ::
>>> bool(1)
True
>>> bool(0)
False
>>> bool([])
False
>>> bool( (1,) )
True
Most of the standard library modules and built-in functions have been changed to
return Booleans. ::
>>> obj = []
>>> hasattr(obj, 'append')
True
>>> isinstance(obj, list)
True
>>> isinstance(obj, tuple)
False
Python's Booleans were added with the primary goal of making code clearer. For
example, if you're reading a function and encounter the statement ``return 1``,
you might wonder whether the ``1`` represents a Boolean truth value, an index,
or a coefficient that multiplies some other quantity. If the statement is
``return True``, however, the meaning of the return value is quite clear.
Python's Booleans were *not* added for the sake of strict type-checking. A very
strict language such as Pascal would also prevent you performing arithmetic with
Booleans, and would require that the expression in an :keyword:`if` statement
always evaluate to a Boolean result. Python is not this strict and never will
be, as :pep:`285` explicitly says. This means you can still use any expression
in an :keyword:`if` statement, even ones that evaluate to a list or tuple or
some random object. The Boolean type is a subclass of the :class:`int` class so
that arithmetic using a Boolean still works. ::
>>> True + 1
2
>>> False + 1
1
>>> False * 75
0
>>> True * 75
75
To sum up :const:`True` and :const:`False` in a sentence: they're alternative
ways to spell the integer values 1 and 0, with the single difference that
:func:`str` and :func:`repr` return the strings ``'True'`` and ``'False'``
instead of ``'1'`` and ``'0'``.
.. seealso::
:pep:`285` - Adding a bool type
Written and implemented by GvR.
.. ======================================================================
PEP 293: Codec Error Handling Callbacks
=======================================
When encoding a Unicode string into a byte string, unencodable characters may be
encountered. So far, Python has allowed specifying the error processing as
either "strict" (raising :exc:`UnicodeError`), "ignore" (skipping the
character), or "replace" (using a question mark in the output string), with
"strict" being the default behavior. It may be desirable to specify alternative
processing of such errors, such as inserting an XML character reference or HTML
entity reference into the converted string.
Python now has a flexible framework to add different processing strategies. New
error handlers can be added with :func:`codecs.register_error`, and codecs then
can access the error handler with :func:`codecs.lookup_error`. An equivalent C
API has been added for codecs written in C. The error handler gets the necessary
state information such as the string being converted, the position in the string
where the error was detected, and the target encoding. The handler can then
either raise an exception or return a replacement string.
Two additional error handlers have been implemented using this framework:
"backslashreplace" uses Python backslash quoting to represent unencodable
characters and "xmlcharrefreplace" emits XML character references.
.. seealso::
:pep:`293` - Codec Error Handling Callbacks
Written and implemented by Walter Dörwald.
.. ======================================================================
.. _section-pep301:
PEP 301: Package Index and Metadata for Distutils
=================================================
Support for the long-requested Python catalog makes its first appearance in 2.3.
The heart of the catalog is the new Distutils :command:`register` command.
Running ``python setup.py register`` will collect the metadata describing a
package, such as its name, version, maintainer, description, &c., and send it to
a central catalog server. The resulting catalog is available from
https://pypi.org.
To make the catalog a bit more useful, a new optional *classifiers* keyword
argument has been added to the Distutils :func:`setup` function. A list of
`Trove <http://catb.org/~esr/trove/>`_-style strings can be supplied to help
classify the software.
Here's an example :file:`setup.py` with classifiers, written to be compatible
with older versions of the Distutils::
from distutils import core
kw = {'name': "Quixote",
'version': "0.5.1",
'description': "A highly Pythonic Web application framework",
# ...
}
if (hasattr(core, 'setup_keywords') and
'classifiers' in core.setup_keywords):
kw['classifiers'] = \
['Topic :: Internet :: WWW/HTTP :: Dynamic Content',
'Environment :: No Input/Output (Daemon)',
'Intended Audience :: Developers'],
core.setup(**kw)
The full list of classifiers can be obtained by running ``python setup.py
register --list-classifiers``.
.. seealso::
:pep:`301` - Package Index and Metadata for Distutils
Written and implemented by Richard Jones.
.. ======================================================================
.. _section-pep302:
PEP 302: New Import Hooks
=========================
While it's been possible to write custom import hooks ever since the
:mod:`ihooks` module was introduced in Python 1.3, no one has ever been really
happy with it because writing new import hooks is difficult and messy. There
have been various proposed alternatives such as the :mod:`imputil` and :mod:`iu`
modules, but none of them has ever gained much acceptance, and none of them were
easily usable from C code.
:pep:`302` borrows ideas from its predecessors, especially from Gordon
McMillan's :mod:`iu` module. Three new items are added to the :mod:`sys`
module:
* ``sys.path_hooks`` is a list of callable objects; most often they'll be
classes. Each callable takes a string containing a path and either returns an
importer object that will handle imports from this path or raises an
:exc:`ImportError` exception if it can't handle this path.
* ``sys.path_importer_cache`` caches importer objects for each path, so
``sys.path_hooks`` will only need to be traversed once for each path.
* ``sys.meta_path`` is a list of importer objects that will be traversed before
``sys.path`` is checked. This list is initially empty, but user code can add
objects to it. Additional built-in and frozen modules can be imported by an
object added to this list.
Importer objects must have a single method, ``find_module(fullname,
path=None)``. *fullname* will be a module or package name, e.g. ``string`` or
``distutils.core``. :meth:`find_module` must return a loader object that has a
single method, ``load_module(fullname)``, that creates and returns the
corresponding module object.
Pseudo-code for Python's new import logic, therefore, looks something like this
(simplified a bit; see :pep:`302` for the full details)::
for mp in sys.meta_path:
loader = mp(fullname)
if loader is not None:
<module> = loader.load_module(fullname)
for path in sys.path:
for hook in sys.path_hooks:
try:
importer = hook(path)
except ImportError:
# ImportError, so try the other path hooks
pass
else:
loader = importer.find_module(fullname)
<module> = loader.load_module(fullname)
# Not found!
raise ImportError
.. seealso::
:pep:`302` - New Import Hooks
Written by Just van Rossum and Paul Moore. Implemented by Just van Rossum.
.. ======================================================================
.. _section-pep305:
PEP 305: Comma-separated Files
==============================
Comma-separated files are a format frequently used for exporting data from
databases and spreadsheets. Python 2.3 adds a parser for comma-separated files.
Comma-separated format is deceptively simple at first glance::
Costs,150,200,3.95
Read a line and call ``line.split(',')``: what could be simpler? But toss in
string data that can contain commas, and things get more complicated::
"Costs",150,200,3.95,"Includes taxes, shipping, and sundry items"
A big ugly regular expression can parse this, but using the new :mod:`csv`
package is much simpler::
import csv
input = open('datafile', 'rb')
reader = csv.reader(input)
for line in reader:
print line
The :func:`reader` function takes a number of different options. The field
separator isn't limited to the comma and can be changed to any character, and so
can the quoting and line-ending characters.
Different dialects of comma-separated files can be defined and registered;
currently there are two dialects, both used by Microsoft Excel. A separate
:class:`csv.writer` class will generate comma-separated files from a succession
of tuples or lists, quoting strings that contain the delimiter.
.. seealso::
:pep:`305` - CSV File API
Written and implemented by Kevin Altis, Dave Cole, Andrew McNamara, Skip
Montanaro, Cliff Wells.
.. ======================================================================
.. _section-pep307:
PEP 307: Pickle Enhancements
============================
The :mod:`pickle` and :mod:`cPickle` modules received some attention during the
2.3 development cycle. In 2.2, new-style classes could be pickled without
difficulty, but they weren't pickled very compactly; :pep:`307` quotes a trivial
example where a new-style class results in a pickled string three times longer
than that for a classic class.
The solution was to invent a new pickle protocol. The :func:`pickle.dumps`
function has supported a text-or-binary flag for a long time. In 2.3, this
flag is redefined from a Boolean to an integer: 0 is the old text-mode pickle
format, 1 is the old binary format, and now 2 is a new 2.3-specific format. A
new constant, :const:`pickle.HIGHEST_PROTOCOL`, can be used to select the
fanciest protocol available.
Unpickling is no longer considered a safe operation. 2.2's :mod:`pickle`
provided hooks for trying to prevent unsafe classes from being unpickled
(specifically, a :attr:`__safe_for_unpickling__` attribute), but none of this
code was ever audited and therefore it's all been ripped out in 2.3. You should
not unpickle untrusted data in any version of Python.
To reduce the pickling overhead for new-style classes, a new interface for
customizing pickling was added using three special methods:
:meth:`__getstate__`, :meth:`__setstate__`, and :meth:`__getnewargs__`. Consult
:pep:`307` for the full semantics of these methods.
As a way to compress pickles yet further, it's now possible to use integer codes
instead of long strings to identify pickled classes. The Python Software
Foundation will maintain a list of standardized codes; there's also a range of
codes for private use. Currently no codes have been specified.
.. seealso::
:pep:`307` - Extensions to the pickle protocol
Written and implemented by Guido van Rossum and Tim Peters.
.. ======================================================================
.. _section-slices:
Extended Slices
===============
Ever since Python 1.4, the slicing syntax has supported an optional third "step"
or "stride" argument. For example, these are all legal Python syntax:
``L[1:10:2]``, ``L[:-1:1]``, ``L[::-1]``. This was added to Python at the
request of the developers of Numerical Python, which uses the third argument
extensively. However, Python's built-in list, tuple, and string sequence types
have never supported this feature, raising a :exc:`TypeError` if you tried it.
Michael Hudson contributed a patch to fix this shortcoming.
For example, you can now easily extract the elements of a list that have even
indexes::
>>> L = range(10)
>>> L[::2]
[0, 2, 4, 6, 8]
Negative values also work to make a copy of the same list in reverse order::
>>> L[::-1]
[9, 8, 7, 6, 5, 4, 3, 2, 1, 0]
This also works for tuples, arrays, and strings::
>>> s='abcd'
>>> s[::2]
'ac'
>>> s[::-1]
'dcba'
If you have a mutable sequence such as a list or an array you can assign to or
delete an extended slice, but there are some differences between assignment to
extended and regular slices. Assignment to a regular slice can be used to
change the length of the sequence::
>>> a = range(3)
>>> a
[0, 1, 2]
>>> a[1:3] = [4, 5, 6]
>>> a
[0, 4, 5, 6]
Extended slices aren't this flexible. When assigning to an extended slice, the
list on the right hand side of the statement must contain the same number of
items as the slice it is replacing::
>>> a = range(4)
>>> a
[0, 1, 2, 3]
>>> a[::2]
[0, 2]
>>> a[::2] = [0, -1]
>>> a
[0, 1, -1, 3]
>>> a[::2] = [0,1,2]
Traceback (most recent call last):
File "<stdin>", line 1, in ?
ValueError: attempt to assign sequence of size 3 to extended slice of size 2
Deletion is more straightforward::
>>> a = range(4)
>>> a
[0, 1, 2, 3]
>>> a[::2]
[0, 2]
>>> del a[::2]
>>> a
[1, 3]
One can also now pass slice objects to the :meth:`__getitem__` methods of the
built-in sequences::
>>> range(10).__getitem__(slice(0, 5, 2))
[0, 2, 4]
Or use slice objects directly in subscripts::
>>> range(10)[slice(0, 5, 2)]
[0, 2, 4]
To simplify implementing sequences that support extended slicing, slice objects
now have a method ``indices(length)`` which, given the length of a sequence,
returns a ``(start, stop, step)`` tuple that can be passed directly to
:func:`range`. :meth:`indices` handles omitted and out-of-bounds indices in a
manner consistent with regular slices (and this innocuous phrase hides a welter
of confusing details!). The method is intended to be used like this::
class FakeSeq:
...
def calc_item(self, i):
...
def __getitem__(self, item):
if isinstance(item, slice):
indices = item.indices(len(self))
return FakeSeq([self.calc_item(i) for i in range(*indices)])
else:
return self.calc_item(i)
From this example you can also see that the built-in :class:`slice` object is
now the type object for the slice type, and is no longer a function. This is
consistent with Python 2.2, where :class:`int`, :class:`str`, etc., underwent
the same change.
.. ======================================================================
Other Language Changes
======================
Here are all of the changes that Python 2.3 makes to the core Python language.
* The :keyword:`yield` statement is now always a keyword, as described in
section :ref:`section-generators` of this document.
* A new built-in function :func:`enumerate` was added, as described in section
:ref:`section-enumerate` of this document.
* Two new constants, :const:`True` and :const:`False` were added along with the
built-in :class:`bool` type, as described in section :ref:`section-bool` of this
document.
* The :func:`int` type constructor will now return a long integer instead of
raising an :exc:`OverflowError` when a string or floating-point number is too
large to fit into an integer. This can lead to the paradoxical result that
``isinstance(int(expression), int)`` is false, but that seems unlikely to cause
problems in practice.
* Built-in types now support the extended slicing syntax, as described in
section :ref:`section-slices` of this document.
* A new built-in function, ``sum(iterable, start=0)``, adds up the numeric
items in the iterable object and returns their sum. :func:`sum` only accepts
numbers, meaning that you can't use it to concatenate a bunch of strings.
(Contributed by Alex Martelli.)
* ``list.insert(pos, value)`` used to insert *value* at the front of the list
when *pos* was negative. The behaviour has now been changed to be consistent
with slice indexing, so when *pos* is -1 the value will be inserted before the
last element, and so forth.
* ``list.index(value)``, which searches for *value* within the list and returns
its index, now takes optional *start* and *stop* arguments to limit the search
to only part of the list.
* Dictionaries have a new method, ``pop(key[, *default*])``, that returns
the value corresponding to *key* and removes that key/value pair from the
dictionary. If the requested key isn't present in the dictionary, *default* is
returned if it's specified and :exc:`KeyError` raised if it isn't. ::
>>> d = {1:2}
>>> d
{1: 2}
>>> d.pop(4)
Traceback (most recent call last):
File "stdin", line 1, in ?
KeyError: 4
>>> d.pop(1)
2
>>> d.pop(1)
Traceback (most recent call last):
File "stdin", line 1, in ?
KeyError: 'pop(): dictionary is empty'
>>> d
{}
>>>
There's also a new class method, ``dict.fromkeys(iterable, value)``, that
creates a dictionary with keys taken from the supplied iterator *iterable* and
all values set to *value*, defaulting to ``None``.
(Patches contributed by Raymond Hettinger.)
Also, the :func:`dict` constructor now accepts keyword arguments to simplify
creating small dictionaries::
>>> dict(red=1, blue=2, green=3, black=4)
{'blue': 2, 'black': 4, 'green': 3, 'red': 1}
(Contributed by Just van Rossum.)
* The :keyword:`assert` statement no longer checks the ``__debug__`` flag, so
you can no longer disable assertions by assigning to ``__debug__``. Running
Python with the :option:`-O` switch will still generate code that doesn't
execute any assertions.
* Most type objects are now callable, so you can use them to create new objects
such as functions, classes, and modules. (This means that the :mod:`new` module
can be deprecated in a future Python version, because you can now use the type
objects available in the :mod:`types` module.) For example, you can create a new
module object with the following code:
::
>>> import types
>>> m = types.ModuleType('abc','docstring')
>>> m
<module 'abc' (built-in)>
>>> m.__doc__
'docstring'
* A new warning, :exc:`PendingDeprecationWarning` was added to indicate features
which are in the process of being deprecated. The warning will *not* be printed
by default. To check for use of features that will be deprecated in the future,
supply :option:`-Walways::PendingDeprecationWarning:: <-W>` on the command line or
use :func:`warnings.filterwarnings`.
* The process of deprecating string-based exceptions, as in ``raise "Error
occurred"``, has begun. Raising a string will now trigger
:exc:`PendingDeprecationWarning`.
* Using ``None`` as a variable name will now result in a :exc:`SyntaxWarning`
warning. In a future version of Python, ``None`` may finally become a keyword.
* The :meth:`xreadlines` method of file objects, introduced in Python 2.1, is no
longer necessary because files now behave as their own iterator.
:meth:`xreadlines` was originally introduced as a faster way to loop over all
the lines in a file, but now you can simply write ``for line in file_obj``.
File objects also have a new read-only :attr:`encoding` attribute that gives the
encoding used by the file; Unicode strings written to the file will be
automatically converted to bytes using the given encoding.
* The method resolution order used by new-style classes has changed, though
you'll only notice the difference if you have a really complicated inheritance
hierarchy. Classic classes are unaffected by this change. Python 2.2
originally used a topological sort of a class's ancestors, but 2.3 now uses the
C3 algorithm as described in the paper `"A Monotonic Superclass Linearization
for Dylan" <http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.19.3910>`_. To
understand the motivation for this change, read Michele Simionato's article
`"Python 2.3 Method Resolution Order" <http://www.phyast.pitt.edu/~micheles/mro.html>`_, or
read the thread on python-dev starting with the message at
https://mail.python.org/pipermail/python-dev/2002-October/029035.html. Samuele
Pedroni first pointed out the problem and also implemented the fix by coding the
C3 algorithm.
* Python runs multithreaded programs by switching between threads after
executing N bytecodes. The default value for N has been increased from 10 to
100 bytecodes, speeding up single-threaded applications by reducing the
switching overhead. Some multithreaded applications may suffer slower response
time, but that's easily fixed by setting the limit back to a lower number using
``sys.setcheckinterval(N)``. The limit can be retrieved with the new
:func:`sys.getcheckinterval` function.
* One minor but far-reaching change is that the names of extension types defined
by the modules included with Python now contain the module and a ``'.'`` in
front of the type name. For example, in Python 2.2, if you created a socket and
printed its :attr:`__class__`, you'd get this output::
>>> s = socket.socket()
>>> s.__class__
<type 'socket'>
In 2.3, you get this::
>>> s.__class__
<type '_socket.socket'>
* One of the noted incompatibilities between old- and new-style classes has been
removed: you can now assign to the :attr:`~definition.__name__` and :attr:`~class.__bases__`
attributes of new-style classes. There are some restrictions on what can be
assigned to :attr:`~class.__bases__` along the lines of those relating to assigning to
an instance's :attr:`~instance.__class__` attribute.
.. ======================================================================
String Changes
--------------
* The :keyword:`in` operator now works differently for strings. Previously, when
evaluating ``X in Y`` where *X* and *Y* are strings, *X* could only be a single
character. That's now changed; *X* can be a string of any length, and ``X in Y``
will return :const:`True` if *X* is a substring of *Y*. If *X* is the empty
string, the result is always :const:`True`. ::
>>> 'ab' in 'abcd'
True
>>> 'ad' in 'abcd'
False
>>> '' in 'abcd'
True
Note that this doesn't tell you where the substring starts; if you need that
information, use the :meth:`find` string method.
* The :meth:`strip`, :meth:`lstrip`, and :meth:`rstrip` string methods now have
an optional argument for specifying the characters to strip. The default is
still to remove all whitespace characters::
>>> ' abc '.strip()
'abc'
>>> '><><abc<><><>'.strip('<>')
'abc'
>>> '><><abc<><><>\n'.strip('<>')
'abc<><><>\n'
>>> u'\u4000\u4001abc\u4000'.strip(u'\u4000')
u'\u4001abc'
>>>
(Suggested by Simon Brunning and implemented by Walter Dörwald.)
* The :meth:`startswith` and :meth:`endswith` string methods now accept negative
numbers for the *start* and *end* parameters.
* Another new string method is :meth:`zfill`, originally a function in the
:mod:`string` module. :meth:`zfill` pads a numeric string with zeros on the
left until it's the specified width. Note that the ``%`` operator is still more
flexible and powerful than :meth:`zfill`. ::
>>> '45'.zfill(4)
'0045'
>>> '12345'.zfill(4)
'12345'
>>> 'goofy'.zfill(6)
'0goofy'
(Contributed by Walter Dörwald.)
* A new type object, :class:`basestring`, has been added. Both 8-bit strings and
Unicode strings inherit from this type, so ``isinstance(obj, basestring)`` will
return :const:`True` for either kind of string. It's a completely abstract
type, so you can't create :class:`basestring` instances.
* Interned strings are no longer immortal and will now be garbage-collected in
the usual way when the only reference to them is from the internal dictionary of
interned strings. (Implemented by Oren Tirosh.)
.. ======================================================================
Optimizations
-------------
* The creation of new-style class instances has been made much faster; they're
now faster than classic classes!
* The :meth:`sort` method of list objects has been extensively rewritten by Tim
Peters, and the implementation is significantly faster.
* Multiplication of large long integers is now much faster thanks to an
implementation of Karatsuba multiplication, an algorithm that scales better than
the O(n\*n) required for the grade-school multiplication algorithm. (Original
patch by Christopher A. Craig, and significantly reworked by Tim Peters.)
* The ``SET_LINENO`` opcode is now gone. This may provide a small speed
increase, depending on your compiler's idiosyncrasies. See section
:ref:`section-other` for a longer explanation. (Removed by Michael Hudson.)
* :func:`xrange` objects now have their own iterator, making ``for i in
xrange(n)`` slightly faster than ``for i in range(n)``. (Patch by Raymond
Hettinger.)
* A number of small rearrangements have been made in various hotspots to improve
performance, such as inlining a function or removing some code. (Implemented
mostly by GvR, but lots of people have contributed single changes.)
The net result of the 2.3 optimizations is that Python 2.3 runs the pystone
benchmark around 25% faster than Python 2.2.
.. ======================================================================
New, Improved, and Deprecated Modules
=====================================
As usual, Python's standard library received a number of enhancements and bug
fixes. Here's a partial list of the most notable changes, sorted alphabetically
by module name. Consult the :file:`Misc/NEWS` file in the source tree for a more
complete list of changes, or look through the CVS logs for all the details.
* The :mod:`array` module now supports arrays of Unicode characters using the
``'u'`` format character. Arrays also now support using the ``+=`` assignment
operator to add another array's contents, and the ``*=`` assignment operator to
repeat an array. (Contributed by Jason Orendorff.)
* The :mod:`bsddb` module has been replaced by version 4.1.6 of the `PyBSDDB
<http://pybsddb.sourceforge.net>`_ package, providing a more complete interface
to the transactional features of the BerkeleyDB library.
The old version of the module has been renamed to :mod:`bsddb185` and is no
longer built automatically; you'll have to edit :file:`Modules/Setup` to enable
it. Note that the new :mod:`bsddb` package is intended to be compatible with
the old module, so be sure to file bugs if you discover any incompatibilities.
When upgrading to Python 2.3, if the new interpreter is compiled with a new
version of the underlying BerkeleyDB library, you will almost certainly have to
convert your database files to the new version. You can do this fairly easily
with the new scripts :file:`db2pickle.py` and :file:`pickle2db.py` which you
will find in the distribution's :file:`Tools/scripts` directory. If you've
already been using the PyBSDDB package and importing it as :mod:`bsddb3`, you
will have to change your ``import`` statements to import it as :mod:`bsddb`.
* The new :mod:`bz2` module is an interface to the bz2 data compression library.
bz2-compressed data is usually smaller than corresponding :mod:`zlib`\
-compressed data. (Contributed by Gustavo Niemeyer.)
* A set of standard date/time types has been added in the new :mod:`datetime`
module. See the following section for more details.
* The Distutils :class:`Extension` class now supports an extra constructor
argument named *depends* for listing additional source files that an extension
depends on. This lets Distutils recompile the module if any of the dependency
files are modified. For example, if :file:`sampmodule.c` includes the header
file :file:`sample.h`, you would create the :class:`Extension` object like
this::
ext = Extension("samp",
sources=["sampmodule.c"],
depends=["sample.h"])
Modifying :file:`sample.h` would then cause the module to be recompiled.
(Contributed by Jeremy Hylton.)
* Other minor changes to Distutils: it now checks for the :envvar:`CC`,
:envvar:`CFLAGS`, :envvar:`CPP`, :envvar:`LDFLAGS`, and :envvar:`CPPFLAGS`
environment variables, using them to override the settings in Python's
configuration (contributed by Robert Weber).
* Previously the :mod:`doctest` module would only search the docstrings of
public methods and functions for test cases, but it now also examines private
ones as well. The :func:`DocTestSuite` function creates a
:class:`unittest.TestSuite` object from a set of :mod:`doctest` tests.
* The new ``gc.get_referents(object)`` function returns a list of all the
objects referenced by *object*.
* The :mod:`getopt` module gained a new function, :func:`gnu_getopt`, that
supports the same arguments as the existing :func:`getopt` function but uses
GNU-style scanning mode. The existing :func:`getopt` stops processing options as
soon as a non-option argument is encountered, but in GNU-style mode processing
continues, meaning that options and arguments can be mixed. For example::
>>> getopt.getopt(['-f', 'filename', 'output', '-v'], 'f:v')
([('-f', 'filename')], ['output', '-v'])
>>> getopt.gnu_getopt(['-f', 'filename', 'output', '-v'], 'f:v')
([('-f', 'filename'), ('-v', '')], ['output'])
(Contributed by Peter Åstrand.)
* The :mod:`grp`, :mod:`pwd`, and :mod:`resource` modules now return enhanced
tuples::
>>> import grp
>>> g = grp.getgrnam('amk')
>>> g.gr_name, g.gr_gid
('amk', 500)
* The :mod:`gzip` module can now handle files exceeding 2 GiB.
* The new :mod:`heapq` module contains an implementation of a heap queue
algorithm. A heap is an array-like data structure that keeps items in a
partially sorted order such that, for every index *k*, ``heap[k] <=
heap[2*k+1]`` and ``heap[k] <= heap[2*k+2]``. This makes it quick to remove the
smallest item, and inserting a new item while maintaining the heap property is
O(lg n). (See https://xlinux.nist.gov/dads//HTML/priorityque.html for more
information about the priority queue data structure.)
The :mod:`heapq` module provides :func:`heappush` and :func:`heappop` functions
for adding and removing items while maintaining the heap property on top of some
other mutable Python sequence type. Here's an example that uses a Python list::
>>> import heapq
>>> heap = []
>>> for item in [3, 7, 5, 11, 1]:
... heapq.heappush(heap, item)
...
>>> heap
[1, 3, 5, 11, 7]
>>> heapq.heappop(heap)
1
>>> heapq.heappop(heap)
3
>>> heap
[5, 7, 11]
(Contributed by Kevin O'Connor.)
* The IDLE integrated development environment has been updated using the code
from the IDLEfork project (http://idlefork.sourceforge.net). The most notable feature is
that the code being developed is now executed in a subprocess, meaning that
there's no longer any need for manual ``reload()`` operations. IDLE's core code
has been incorporated into the standard library as the :mod:`idlelib` package.
* The :mod:`imaplib` module now supports IMAP over SSL. (Contributed by Piers
Lauder and Tino Lange.)
* The :mod:`itertools` contains a number of useful functions for use with
iterators, inspired by various functions provided by the ML and Haskell
languages. For example, ``itertools.ifilter(predicate, iterator)`` returns all
elements in the iterator for which the function :func:`predicate` returns
:const:`True`, and ``itertools.repeat(obj, N)`` returns ``obj`` *N* times.
There are a number of other functions in the module; see the package's reference
documentation for details.
(Contributed by Raymond Hettinger.)
* Two new functions in the :mod:`math` module, ``degrees(rads)`` and
``radians(degs)``, convert between radians and degrees. Other functions in
the :mod:`math` module such as :func:`math.sin` and :func:`math.cos` have always
required input values measured in radians. Also, an optional *base* argument
was added to :func:`math.log` to make it easier to compute logarithms for bases
other than ``e`` and ``10``. (Contributed by Raymond Hettinger.)
* Several new POSIX functions (:func:`getpgid`, :func:`killpg`, :func:`lchown`,
:func:`loadavg`, :func:`major`, :func:`makedev`, :func:`minor`, and
:func:`mknod`) were added to the :mod:`posix` module that underlies the
:mod:`os` module. (Contributed by Gustavo Niemeyer, Geert Jansen, and Denis S.
Otkidach.)
* In the :mod:`os` module, the :func:`\*stat` family of functions can now report
fractions of a second in a timestamp. Such time stamps are represented as
floats, similar to the value returned by :func:`time.time`.
During testing, it was found that some applications will break if time stamps
are floats. For compatibility, when using the tuple interface of the
:class:`stat_result` time stamps will be represented as integers. When using
named fields (a feature first introduced in Python 2.2), time stamps are still
represented as integers, unless :func:`os.stat_float_times` is invoked to enable
float return values::
>>> os.stat("/tmp").st_mtime
1034791200
>>> os.stat_float_times(True)
>>> os.stat("/tmp").st_mtime
1034791200.6335014
In Python 2.4, the default will change to always returning floats.
Application developers should enable this feature only if all their libraries
work properly when confronted with floating point time stamps, or if they use
the tuple API. If used, the feature should be activated on an application level
instead of trying to enable it on a per-use basis.
* The :mod:`optparse` module contains a new parser for command-line arguments
that can convert option values to a particular Python type and will
automatically generate a usage message. See the following section for more
details.
* The old and never-documented :mod:`linuxaudiodev` module has been deprecated,
and a new version named :mod:`ossaudiodev` has been added. The module was
renamed because the OSS sound drivers can be used on platforms other than Linux,
and the interface has also been tidied and brought up to date in various ways.
(Contributed by Greg Ward and Nicholas FitzRoy-Dale.)
* The new :mod:`platform` module contains a number of functions that try to
determine various properties of the platform you're running on. There are
functions for getting the architecture, CPU type, the Windows OS version, and
even the Linux distribution version. (Contributed by Marc-André Lemburg.)
* The parser objects provided by the :mod:`pyexpat` module can now optionally
buffer character data, resulting in fewer calls to your character data handler
and therefore faster performance. Setting the parser object's
:attr:`buffer_text` attribute to :const:`True` will enable buffering.
* The ``sample(population, k)`` function was added to the :mod:`random`
module. *population* is a sequence or :class:`xrange` object containing the
elements of a population, and :func:`sample` chooses *k* elements from the
population without replacing chosen elements. *k* can be any value up to
``len(population)``. For example::
>>> days = ['Mo', 'Tu', 'We', 'Th', 'Fr', 'St', 'Sn']
>>> random.sample(days, 3) # Choose 3 elements
['St', 'Sn', 'Th']
>>> random.sample(days, 7) # Choose 7 elements
['Tu', 'Th', 'Mo', 'We', 'St', 'Fr', 'Sn']
>>> random.sample(days, 7) # Choose 7 again
['We', 'Mo', 'Sn', 'Fr', 'Tu', 'St', 'Th']
>>> random.sample(days, 8) # Can't choose eight
Traceback (most recent call last):
File "<stdin>", line 1, in ?
File "random.py", line 414, in sample
raise ValueError, "sample larger than population"
ValueError: sample larger than population
>>> random.sample(xrange(1,10000,2), 10) # Choose ten odd nos. under 10000
[3407, 3805, 1505, 7023, 2401, 2267, 9733, 3151, 8083, 9195]
The :mod:`random` module now uses a new algorithm, the Mersenne Twister,
implemented in C. It's faster and more extensively studied than the previous
algorithm.
(All changes contributed by Raymond Hettinger.)
* The :mod:`readline` module also gained a number of new functions:
:func:`get_history_item`, :func:`get_current_history_length`, and
:func:`redisplay`.
* The :mod:`rexec` and :mod:`Bastion` modules have been declared dead, and
attempts to import them will fail with a :exc:`RuntimeError`. New-style classes
provide new ways to break out of the restricted execution environment provided
by :mod:`rexec`, and no one has interest in fixing them or time to do so. If
you have applications using :mod:`rexec`, rewrite them to use something else.
(Sticking with Python 2.2 or 2.1 will not make your applications any safer
because there are known bugs in the :mod:`rexec` module in those versions. To
repeat: if you're using :mod:`rexec`, stop using it immediately.)
* The :mod:`rotor` module has been deprecated because the algorithm it uses for
encryption is not believed to be secure. If you need encryption, use one of the
several AES Python modules that are available separately.
* The :mod:`shutil` module gained a ``move(src, dest)`` function that
recursively moves a file or directory to a new location.
* Support for more advanced POSIX signal handling was added to the :mod:`signal`
but then removed again as it proved impossible to make it work reliably across
platforms.
* The :mod:`socket` module now supports timeouts. You can call the
``settimeout(t)`` method on a socket object to set a timeout of *t* seconds.
Subsequent socket operations that take longer than *t* seconds to complete will
abort and raise a :exc:`socket.timeout` exception.
The original timeout implementation was by Tim O'Malley. Michael Gilfix
integrated it into the Python :mod:`socket` module and shepherded it through a
lengthy review. After the code was checked in, Guido van Rossum rewrote parts
of it. (This is a good example of a collaborative development process in
action.)
* On Windows, the :mod:`socket` module now ships with Secure Sockets Layer
(SSL) support.
* The value of the C :const:`PYTHON_API_VERSION` macro is now exposed at the
Python level as ``sys.api_version``. The current exception can be cleared by
calling the new :func:`sys.exc_clear` function.
* The new :mod:`tarfile` module allows reading from and writing to
:program:`tar`\ -format archive files. (Contributed by Lars Gustäbel.)
* The new :mod:`textwrap` module contains functions for wrapping strings
containing paragraphs of text. The ``wrap(text, width)`` function takes a
string and returns a list containing the text split into lines of no more than
the chosen width. The ``fill(text, width)`` function returns a single
string, reformatted to fit into lines no longer than the chosen width. (As you
can guess, :func:`fill` is built on top of :func:`wrap`. For example::
>>> import textwrap
>>> paragraph = "Not a whit, we defy augury: ... more text ..."
>>> textwrap.wrap(paragraph, 60)
["Not a whit, we defy augury: there's a special providence in",
"the fall of a sparrow. If it be now, 'tis not to come; if it",
...]
>>> print textwrap.fill(paragraph, 35)
Not a whit, we defy augury: there's
a special providence in the fall of
a sparrow. If it be now, 'tis not
to come; if it be not to come, it
will be now; if it be not now, yet
it will come: the readiness is all.
>>>
The module also contains a :class:`TextWrapper` class that actually implements
the text wrapping strategy. Both the :class:`TextWrapper` class and the
:func:`wrap` and :func:`fill` functions support a number of additional keyword
arguments for fine-tuning the formatting; consult the module's documentation
for details. (Contributed by Greg Ward.)
* The :mod:`thread` and :mod:`threading` modules now have companion modules,
:mod:`dummy_thread` and :mod:`dummy_threading`, that provide a do-nothing
implementation of the :mod:`thread` module's interface for platforms where
threads are not supported. The intention is to simplify thread-aware modules
(ones that *don't* rely on threads to run) by putting the following code at the
top::
try:
import threading as _threading
except ImportError:
import dummy_threading as _threading
In this example, :mod:`_threading` is used as the module name to make it clear
that the module being used is not necessarily the actual :mod:`threading`
module. Code can call functions and use classes in :mod:`_threading` whether or
not threads are supported, avoiding an :keyword:`if` statement and making the
code slightly clearer. This module will not magically make multithreaded code
run without threads; code that waits for another thread to return or to do
something will simply hang forever.
* The :mod:`time` module's :func:`strptime` function has long been an annoyance
because it uses the platform C library's :func:`strptime` implementation, and
different platforms sometimes have odd bugs. Brett Cannon contributed a
portable implementation that's written in pure Python and should behave
identically on all platforms.
* The new :mod:`timeit` module helps measure how long snippets of Python code
take to execute. The :file:`timeit.py` file can be run directly from the
command line, or the module's :class:`Timer` class can be imported and used
directly. Here's a short example that figures out whether it's faster to
convert an 8-bit string to Unicode by appending an empty Unicode string to it or
by using the :func:`unicode` function::
import timeit
timer1 = timeit.Timer('unicode("abc")')
timer2 = timeit.Timer('"abc" + u""')
# Run three trials
print timer1.repeat(repeat=3, number=100000)
print timer2.repeat(repeat=3, number=100000)
# On my laptop this outputs:
# [0.36831796169281006, 0.37441694736480713, 0.35304892063140869]
# [0.17574405670166016, 0.18193507194519043, 0.17565798759460449]
* The :mod:`Tix` module has received various bug fixes and updates for the
current version of the Tix package.
* The :mod:`Tkinter` module now works with a thread-enabled version of Tcl.
Tcl's threading model requires that widgets only be accessed from the thread in
which they're created; accesses from another thread can cause Tcl to panic. For
certain Tcl interfaces, :mod:`Tkinter` will now automatically avoid this when a
widget is accessed from a different thread by marshalling a command, passing it
to the correct thread, and waiting for the results. Other interfaces can't be
handled automatically but :mod:`Tkinter` will now raise an exception on such an
access so that you can at least find out about the problem. See
https://mail.python.org/pipermail/python-dev/2002-December/031107.html for a more
detailed explanation of this change. (Implemented by Martin von Löwis.)
* Calling Tcl methods through :mod:`_tkinter` no longer returns only strings.
Instead, if Tcl returns other objects those objects are converted to their
Python equivalent, if one exists, or wrapped with a :class:`_tkinter.Tcl_Obj`
object if no Python equivalent exists. This behavior can be controlled through
the :meth:`wantobjects` method of :class:`tkapp` objects.
When using :mod:`_tkinter` through the :mod:`Tkinter` module (as most Tkinter
applications will), this feature is always activated. It should not cause
compatibility problems, since Tkinter would always convert string results to
Python types where possible.
If any incompatibilities are found, the old behavior can be restored by setting
the :attr:`wantobjects` variable in the :mod:`Tkinter` module to false before
creating the first :class:`tkapp` object. ::
import Tkinter
Tkinter.wantobjects = 0
Any breakage caused by this change should be reported as a bug.
* The :mod:`UserDict` module has a new :class:`DictMixin` class which defines
all dictionary methods for classes that already have a minimum mapping
interface. This greatly simplifies writing classes that need to be
substitutable for dictionaries, such as the classes in the :mod:`shelve`
module.
Adding the mix-in as a superclass provides the full dictionary interface
whenever the class defines :meth:`__getitem__`, :meth:`__setitem__`,
:meth:`__delitem__`, and :meth:`keys`. For example::
>>> import UserDict
>>> class SeqDict(UserDict.DictMixin):
... """Dictionary lookalike implemented with lists."""
... def __init__(self):
... self.keylist = []
... self.valuelist = []
... def __getitem__(self, key):
... try:
... i = self.keylist.index(key)
... except ValueError:
... raise KeyError
... return self.valuelist[i]
... def __setitem__(self, key, value):
... try:
... i = self.keylist.index(key)
... self.valuelist[i] = value
... except ValueError:
... self.keylist.append(key)
... self.valuelist.append(value)
... def __delitem__(self, key):
... try:
... i = self.keylist.index(key)
... except ValueError:
... raise KeyError
... self.keylist.pop(i)
... self.valuelist.pop(i)
... def keys(self):
... return list(self.keylist)
...
>>> s = SeqDict()
>>> dir(s) # See that other dictionary methods are implemented
['__cmp__', '__contains__', '__delitem__', '__doc__', '__getitem__',
'__init__', '__iter__', '__len__', '__module__', '__repr__',
'__setitem__', 'clear', 'get', 'has_key', 'items', 'iteritems',
'iterkeys', 'itervalues', 'keylist', 'keys', 'pop', 'popitem',
'setdefault', 'update', 'valuelist', 'values']
(Contributed by Raymond Hettinger.)
* The DOM implementation in :mod:`xml.dom.minidom` can now generate XML output
in a particular encoding by providing an optional encoding argument to the
:meth:`toxml` and :meth:`toprettyxml` methods of DOM nodes.
* The :mod:`xmlrpclib` module now supports an XML-RPC extension for handling nil
data values such as Python's ``None``. Nil values are always supported on
unmarshalling an XML-RPC response. To generate requests containing ``None``,
you must supply a true value for the *allow_none* parameter when creating a
:class:`Marshaller` instance.
* The new :mod:`DocXMLRPCServer` module allows writing self-documenting XML-RPC
servers. Run it in demo mode (as a program) to see it in action. Pointing the
Web browser to the RPC server produces pydoc-style documentation; pointing
xmlrpclib to the server allows invoking the actual methods. (Contributed by
Brian Quinlan.)
* Support for internationalized domain names (RFCs 3454, 3490, 3491, and 3492)
has been added. The "idna" encoding can be used to convert between a Unicode
domain name and the ASCII-compatible encoding (ACE) of that name. ::
>{}>{}> u"www.Alliancefrançaise.nu".encode("idna")
'www.xn--alliancefranaise-npb.nu'
The :mod:`socket` module has also been extended to transparently convert
Unicode hostnames to the ACE version before passing them to the C library.
Modules that deal with hostnames such as :mod:`httplib` and :mod:`ftplib`)
also support Unicode host names; :mod:`httplib` also sends HTTP ``Host``
headers using the ACE version of the domain name. :mod:`urllib` supports
Unicode URLs with non-ASCII host names as long as the ``path`` part of the URL
is ASCII only.
To implement this change, the :mod:`stringprep` module, the ``mkstringprep``
tool and the ``punycode`` encoding have been added.
.. ======================================================================
Date/Time Type
--------------
Date and time types suitable for expressing timestamps were added as the
:mod:`datetime` module. The types don't support different calendars or many
fancy features, and just stick to the basics of representing time.
The three primary types are: :class:`date`, representing a day, month, and year;
:class:`~datetime.time`, consisting of hour, minute, and second; and :class:`~datetime.datetime`,
which contains all the attributes of both :class:`date` and :class:`~datetime.time`.
There's also a :class:`timedelta` class representing differences between two
points in time, and time zone logic is implemented by classes inheriting from
the abstract :class:`tzinfo` class.
You can create instances of :class:`date` and :class:`~datetime.time` by either supplying
keyword arguments to the appropriate constructor, e.g.
``datetime.date(year=1972, month=10, day=15)``, or by using one of a number of
class methods. For example, the :meth:`date.today` class method returns the
current local date.
Once created, instances of the date/time classes are all immutable. There are a
number of methods for producing formatted strings from objects::
>>> import datetime
>>> now = datetime.datetime.now()
>>> now.isoformat()
'2002-12-30T21:27:03.994956'
>>> now.ctime() # Only available on date, datetime
'Mon Dec 30 21:27:03 2002'
>>> now.strftime('%Y %d %b')
'2002 30 Dec'
The :meth:`replace` method allows modifying one or more fields of a
:class:`date` or :class:`~datetime.datetime` instance, returning a new instance::
>>> d = datetime.datetime.now()
>>> d
datetime.datetime(2002, 12, 30, 22, 15, 38, 827738)
>>> d.replace(year=2001, hour = 12)
datetime.datetime(2001, 12, 30, 12, 15, 38, 827738)
>>>
Instances can be compared, hashed, and converted to strings (the result is the
same as that of :meth:`isoformat`). :class:`date` and :class:`~datetime.datetime`
instances can be subtracted from each other, and added to :class:`timedelta`
instances. The largest missing feature is that there's no standard library
support for parsing strings and getting back a :class:`date` or
:class:`~datetime.datetime`.
For more information, refer to the module's reference documentation.
(Contributed by Tim Peters.)
.. ======================================================================
The optparse Module
-------------------
The :mod:`getopt` module provides simple parsing of command-line arguments. The
new :mod:`optparse` module (originally named Optik) provides more elaborate
command-line parsing that follows the Unix conventions, automatically creates
the output for :option:`!--help`, and can perform different actions for different
options.
You start by creating an instance of :class:`OptionParser` and telling it what
your program's options are. ::
import sys
from optparse import OptionParser
op = OptionParser()
op.add_option('-i', '--input',
action='store', type='string', dest='input',
help='set input filename')
op.add_option('-l', '--length',
action='store', type='int', dest='length',
help='set maximum length of output')
Parsing a command line is then done by calling the :meth:`parse_args` method. ::
options, args = op.parse_args(sys.argv[1:])
print options
print args
This returns an object containing all of the option values, and a list of
strings containing the remaining arguments.
Invoking the script with the various arguments now works as you'd expect it to.
Note that the length argument is automatically converted to an integer.
.. code-block:: shell-session
$ ./python opt.py -i data arg1
<Values at 0x400cad4c: {'input': 'data', 'length': None}>
['arg1']
$ ./python opt.py --input=data --length=4
<Values at 0x400cad2c: {'input': 'data', 'length': 4}>
[]
$
The help message is automatically generated for you:
.. code-block:: shell-session
$ ./python opt.py --help
usage: opt.py [options]
options:
-h, --help show this help message and exit
-iINPUT, --input=INPUT
set input filename
-lLENGTH, --length=LENGTH
set maximum length of output
$
See the module's documentation for more details.
Optik was written by Greg Ward, with suggestions from the readers of the Getopt
SIG.
.. ======================================================================
.. _section-pymalloc:
Pymalloc: A Specialized Object Allocator
========================================
Pymalloc, a specialized object allocator written by Vladimir Marangozov, was a
feature added to Python 2.1. Pymalloc is intended to be faster than the system
:c:func:`malloc` and to have less memory overhead for allocation patterns typical
of Python programs. The allocator uses C's :c:func:`malloc` function to get large
pools of memory and then fulfills smaller memory requests from these pools.
In 2.1 and 2.2, pymalloc was an experimental feature and wasn't enabled by
default; you had to explicitly enable it when compiling Python by providing the
:option:`!--with-pymalloc` option to the :program:`configure` script. In 2.3,
pymalloc has had further enhancements and is now enabled by default; you'll have
to supply :option:`!--without-pymalloc` to disable it.
This change is transparent to code written in Python; however, pymalloc may
expose bugs in C extensions. Authors of C extension modules should test their
code with pymalloc enabled, because some incorrect code may cause core dumps at
runtime.
There's one particularly common error that causes problems. There are a number
of memory allocation functions in Python's C API that have previously just been
aliases for the C library's :c:func:`malloc` and :c:func:`free`, meaning that if
you accidentally called mismatched functions the error wouldn't be noticeable.
When the object allocator is enabled, these functions aren't aliases of
:c:func:`malloc` and :c:func:`free` any more, and calling the wrong function to
free memory may get you a core dump. For example, if memory was allocated using
:c:func:`PyObject_Malloc`, it has to be freed using :c:func:`PyObject_Free`, not
:c:func:`free`. A few modules included with Python fell afoul of this and had to
be fixed; doubtless there are more third-party modules that will have the same
problem.
As part of this change, the confusing multiple interfaces for allocating memory
have been consolidated down into two API families. Memory allocated with one
family must not be manipulated with functions from the other family. There is
one family for allocating chunks of memory and another family of functions
specifically for allocating Python objects.
* To allocate and free an undistinguished chunk of memory use the "raw memory"
family: :c:func:`PyMem_Malloc`, :c:func:`PyMem_Realloc`, and :c:func:`PyMem_Free`.
* The "object memory" family is the interface to the pymalloc facility described
above and is biased towards a large number of "small" allocations:
:c:func:`PyObject_Malloc`, :c:func:`PyObject_Realloc`, and :c:func:`PyObject_Free`.
* To allocate and free Python objects, use the "object" family
:c:func:`PyObject_New`, :c:func:`PyObject_NewVar`, and :c:func:`PyObject_Del`.
Thanks to lots of work by Tim Peters, pymalloc in 2.3 also provides debugging
features to catch memory overwrites and doubled frees in both extension modules
and in the interpreter itself. To enable this support, compile a debugging
version of the Python interpreter by running :program:`configure` with
:option:`!--with-pydebug`.
To aid extension writers, a header file :file:`Misc/pymemcompat.h` is
distributed with the source to Python 2.3 that allows Python extensions to use
the 2.3 interfaces to memory allocation while compiling against any version of
Python since 1.5.2. You would copy the file from Python's source distribution
and bundle it with the source of your extension.
.. seealso::
https://hg.python.org/cpython/file/default/Objects/obmalloc.c
For the full details of the pymalloc implementation, see the comments at
the top of the file :file:`Objects/obmalloc.c` in the Python source code.
The above link points to the file within the python.org SVN browser.
.. ======================================================================
Build and C API Changes
=======================
Changes to Python's build process and to the C API include:
* The cycle detection implementation used by the garbage collection has proven
to be stable, so it's now been made mandatory. You can no longer compile Python
without it, and the :option:`!--with-cycle-gc` switch to :program:`configure` has
been removed.
* Python can now optionally be built as a shared library
(:file:`libpython2.3.so`) by supplying :option:`!--enable-shared` when running
Python's :program:`configure` script. (Contributed by Ondrej Palkovsky.)
* The :c:macro:`DL_EXPORT` and :c:macro:`DL_IMPORT` macros are now deprecated.
Initialization functions for Python extension modules should now be declared
using the new macro :c:macro:`PyMODINIT_FUNC`, while the Python core will
generally use the :c:macro:`PyAPI_FUNC` and :c:macro:`PyAPI_DATA` macros.
* The interpreter can be compiled without any docstrings for the built-in
functions and modules by supplying :option:`!--without-doc-strings` to the
:program:`configure` script. This makes the Python executable about 10% smaller,
but will also mean that you can't get help for Python's built-ins. (Contributed
by Gustavo Niemeyer.)
* The :c:func:`PyArg_NoArgs` macro is now deprecated, and code that uses it
should be changed. For Python 2.2 and later, the method definition table can
specify the :const:`METH_NOARGS` flag, signalling that there are no arguments,
and the argument checking can then be removed. If compatibility with pre-2.2
versions of Python is important, the code could use ``PyArg_ParseTuple(args,
"")`` instead, but this will be slower than using :const:`METH_NOARGS`.
* :c:func:`PyArg_ParseTuple` accepts new format characters for various sizes of
unsigned integers: ``B`` for :c:type:`unsigned char`, ``H`` for :c:type:`unsigned
short int`, ``I`` for :c:type:`unsigned int`, and ``K`` for :c:type:`unsigned
long long`.
* A new function, ``PyObject_DelItemString(mapping, char *key)`` was added
as shorthand for ``PyObject_DelItem(mapping, PyString_New(key))``.
* File objects now manage their internal string buffer differently, increasing
it exponentially when needed. This results in the benchmark tests in
:file:`Lib/test/test_bufio.py` speeding up considerably (from 57 seconds to 1.7
seconds, according to one measurement).
* It's now possible to define class and static methods for a C extension type by
setting either the :const:`METH_CLASS` or :const:`METH_STATIC` flags in a
method's :c:type:`PyMethodDef` structure.
* Python now includes a copy of the Expat XML parser's source code, removing any
dependence on a system version or local installation of Expat.
* If you dynamically allocate type objects in your extension, you should be
aware of a change in the rules relating to the :attr:`__module__` and
:attr:`~definition.__name__` attributes. In summary, you will want to ensure the type's
dictionary contains a ``'__module__'`` key; making the module name the part of
the type name leading up to the final period will no longer have the desired
effect. For more detail, read the API reference documentation or the source.
.. ======================================================================
Port-Specific Changes
---------------------
Support for a port to IBM's OS/2 using the EMX runtime environment was merged
into the main Python source tree. EMX is a POSIX emulation layer over the OS/2
system APIs. The Python port for EMX tries to support all the POSIX-like
capability exposed by the EMX runtime, and mostly succeeds; :func:`fork` and
:func:`fcntl` are restricted by the limitations of the underlying emulation
layer. The standard OS/2 port, which uses IBM's Visual Age compiler, also
gained support for case-sensitive import semantics as part of the integration of
the EMX port into CVS. (Contributed by Andrew MacIntyre.)
On MacOS, most toolbox modules have been weaklinked to improve backward
compatibility. This means that modules will no longer fail to load if a single
routine is missing on the current OS version. Instead calling the missing
routine will raise an exception. (Contributed by Jack Jansen.)
The RPM spec files, found in the :file:`Misc/RPM/` directory in the Python
source distribution, were updated for 2.3. (Contributed by Sean Reifschneider.)
Other new platforms now supported by Python include AtheOS
(http://atheos.cx/), GNU/Hurd, and OpenVMS.
.. ======================================================================
.. _section-other:
Other Changes and Fixes
=======================
As usual, there were a bunch of other improvements and bugfixes scattered
throughout the source tree. A search through the CVS change logs finds there
were 523 patches applied and 514 bugs fixed between Python 2.2 and 2.3. Both
figures are likely to be underestimates.
Some of the more notable changes are:
* If the :envvar:`PYTHONINSPECT` environment variable is set, the Python
interpreter will enter the interactive prompt after running a Python program, as
if Python had been invoked with the :option:`-i` option. The environment
variable can be set before running the Python interpreter, or it can be set by
the Python program as part of its execution.
* The :file:`regrtest.py` script now provides a way to allow "all resources
except *foo*." A resource name passed to the :option:`!-u` option can now be
prefixed with a hyphen (``'-'``) to mean "remove this resource." For example,
the option '``-uall,-bsddb``' could be used to enable the use of all resources
except ``bsddb``.
* The tools used to build the documentation now work under Cygwin as well as
Unix.
* The ``SET_LINENO`` opcode has been removed. Back in the mists of time, this
opcode was needed to produce line numbers in tracebacks and support trace
functions (for, e.g., :mod:`pdb`). Since Python 1.5, the line numbers in
tracebacks have been computed using a different mechanism that works with
"python -O". For Python 2.3 Michael Hudson implemented a similar scheme to
determine when to call the trace function, removing the need for ``SET_LINENO``
entirely.
It would be difficult to detect any resulting difference from Python code, apart
from a slight speed up when Python is run without :option:`-O`.
C extensions that access the :attr:`f_lineno` field of frame objects should
instead call ``PyCode_Addr2Line(f->f_code, f->f_lasti)``. This will have the
added effect of making the code work as desired under "python -O" in earlier
versions of Python.
A nifty new feature is that trace functions can now assign to the
:attr:`f_lineno` attribute of frame objects, changing the line that will be
executed next. A ``jump`` command has been added to the :mod:`pdb` debugger
taking advantage of this new feature. (Implemented by Richie Hindle.)
.. ======================================================================
Porting to Python 2.3
=====================
This section lists previously described changes that may require changes to your
code:
* :keyword:`yield` is now always a keyword; if it's used as a variable name in
your code, a different name must be chosen.
* For strings *X* and *Y*, ``X in Y`` now works if *X* is more than one
character long.
* The :func:`int` type constructor will now return a long integer instead of
raising an :exc:`OverflowError` when a string or floating-point number is too
large to fit into an integer.
* If you have Unicode strings that contain 8-bit characters, you must declare
the file's encoding (UTF-8, Latin-1, or whatever) by adding a comment to the top
of the file. See section :ref:`section-encodings` for more information.
* Calling Tcl methods through :mod:`_tkinter` no longer returns only strings.
Instead, if Tcl returns other objects those objects are converted to their
Python equivalent, if one exists, or wrapped with a :class:`_tkinter.Tcl_Obj`
object if no Python equivalent exists.
* Large octal and hex literals such as ``0xffffffff`` now trigger a
:exc:`FutureWarning`. Currently they're stored as 32-bit numbers and result in a
negative value, but in Python 2.4 they'll become positive long integers.
There are a few ways to fix this warning. If you really need a positive number,
just add an ``L`` to the end of the literal. If you're trying to get a 32-bit
integer with low bits set and have previously used an expression such as ``~(1
<< 31)``, it's probably clearest to start with all bits set and clear the
desired upper bits. For example, to clear just the top bit (bit 31), you could
write ``0xffffffffL &~(1L<<31)``.
* You can no longer disable assertions by assigning to ``__debug__``.
* The Distutils :func:`setup` function has gained various new keyword arguments
such as *depends*. Old versions of the Distutils will abort if passed unknown
keywords. A solution is to check for the presence of the new
:func:`get_distutil_options` function in your :file:`setup.py` and only uses the
new keywords with a version of the Distutils that supports them::
from distutils import core
kw = {'sources': 'foo.c', ...}
if hasattr(core, 'get_distutil_options'):
kw['depends'] = ['foo.h']
ext = Extension(**kw)
* Using ``None`` as a variable name will now result in a :exc:`SyntaxWarning`
warning.
* Names of extension types defined by the modules included with Python now
contain the module and a ``'.'`` in front of the type name.
.. ======================================================================
.. _23acks:
Acknowledgements
================
The author would like to thank the following people for offering suggestions,
corrections and assistance with various drafts of this article: Jeff Bauer,
Simon Brunning, Brett Cannon, Michael Chermside, Andrew Dalke, Scott David
Daniels, Fred L. Drake, Jr., David Fraser, Kelly Gerber, Raymond Hettinger,
Michael Hudson, Chris Lambert, Detlef Lannert, Martin von Löwis, Andrew
MacIntyre, Lalo Martins, Chad Netzer, Gustavo Niemeyer, Neal Norwitz, Hans
Nowak, Chris Reedy, Francesco Ricciardi, Vinay Sajip, Neil Schemenauer, Roman
Suzi, Jason Tishler, Just van Rossum.
PK
%�\;�] � � " html/_sources/whatsnew/2.4.rst.txtnu �[��� ****************************
What's New in Python 2.4
****************************
:Author: A.M. Kuchling
.. |release| replace:: 1.02
.. $Id: whatsnew24.tex 54632 2007-03-31 11:59:54Z georg.brandl $
.. Don't write extensive text for new sections; I'll do that.
.. Feel free to add commented-out reminders of things that need
.. to be covered. --amk
This article explains the new features in Python 2.4.1, released on March 30,
2005.
Python 2.4 is a medium-sized release. It doesn't introduce as many changes as
the radical Python 2.2, but introduces more features than the conservative 2.3
release. The most significant new language features are function decorators and
generator expressions; most other changes are to the standard library.
According to the CVS change logs, there were 481 patches applied and 502 bugs
fixed between Python 2.3 and 2.4. Both figures are likely to be underestimates.
This article doesn't attempt to provide a complete specification of every single
new feature, but instead provides a brief introduction to each feature. For
full details, you should refer to the documentation for Python 2.4, such as the
Python Library Reference and the Python Reference Manual. Often you will be
referred to the PEP for a particular new feature for explanations of the
implementation and design rationale.
.. ======================================================================
PEP 218: Built-In Set Objects
=============================
Python 2.3 introduced the :mod:`sets` module. C implementations of set data
types have now been added to the Python core as two new built-in types,
``set(iterable)`` and ``frozenset(iterable)``. They provide high speed
operations for membership testing, for eliminating duplicates from sequences,
and for mathematical operations like unions, intersections, differences, and
symmetric differences. ::
>>> a = set('abracadabra') # form a set from a string
>>> 'z' in a # fast membership testing
False
>>> a # unique letters in a
set(['a', 'r', 'b', 'c', 'd'])
>>> ''.join(a) # convert back into a string
'arbcd'
>>> b = set('alacazam') # form a second set
>>> a - b # letters in a but not in b
set(['r', 'd', 'b'])
>>> a | b # letters in either a or b
set(['a', 'c', 'r', 'd', 'b', 'm', 'z', 'l'])
>>> a & b # letters in both a and b
set(['a', 'c'])
>>> a ^ b # letters in a or b but not both
set(['r', 'd', 'b', 'm', 'z', 'l'])
>>> a.add('z') # add a new element
>>> a.update('wxy') # add multiple new elements
>>> a
set(['a', 'c', 'b', 'd', 'r', 'w', 'y', 'x', 'z'])
>>> a.remove('x') # take one element out
>>> a
set(['a', 'c', 'b', 'd', 'r', 'w', 'y', 'z'])
The :func:`frozenset` type is an immutable version of :func:`set`. Since it is
immutable and hashable, it may be used as a dictionary key or as a member of
another set.
The :mod:`sets` module remains in the standard library, and may be useful if you
wish to subclass the :class:`Set` or :class:`ImmutableSet` classes. There are
currently no plans to deprecate the module.
.. seealso::
:pep:`218` - Adding a Built-In Set Object Type
Originally proposed by Greg Wilson and ultimately implemented by Raymond
Hettinger.
.. ======================================================================
PEP 237: Unifying Long Integers and Integers
============================================
The lengthy transition process for this PEP, begun in Python 2.2, takes another
step forward in Python 2.4. In 2.3, certain integer operations that would
behave differently after int/long unification triggered :exc:`FutureWarning`
warnings and returned values limited to 32 or 64 bits (depending on your
platform). In 2.4, these expressions no longer produce a warning and instead
produce a different result that's usually a long integer.
The problematic expressions are primarily left shifts and lengthy hexadecimal
and octal constants. For example, ``2 << 32`` results in a warning in 2.3,
evaluating to 0 on 32-bit platforms. In Python 2.4, this expression now returns
the correct answer, 8589934592.
.. seealso::
:pep:`237` - Unifying Long Integers and Integers
Original PEP written by Moshe Zadka and GvR. The changes for 2.4 were
implemented by Kalle Svensson.
.. ======================================================================
PEP 289: Generator Expressions
==============================
The iterator feature introduced in Python 2.2 and the :mod:`itertools` module
make it easier to write programs that loop through large data sets without
having the entire data set in memory at one time. List comprehensions don't fit
into this picture very well because they produce a Python list object containing
all of the items. This unavoidably pulls all of the objects into memory, which
can be a problem if your data set is very large. When trying to write a
functionally-styled program, it would be natural to write something like::
links = [link for link in get_all_links() if not link.followed]
for link in links:
...
instead of ::
for link in get_all_links():
if link.followed:
continue
...
The first form is more concise and perhaps more readable, but if you're dealing
with a large number of link objects you'd have to write the second form to avoid
having all link objects in memory at the same time.
Generator expressions work similarly to list comprehensions but don't
materialize the entire list; instead they create a generator that will return
elements one by one. The above example could be written as::
links = (link for link in get_all_links() if not link.followed)
for link in links:
...
Generator expressions always have to be written inside parentheses, as in the
above example. The parentheses signalling a function call also count, so if you
want to create an iterator that will be immediately passed to a function you
could write::
print sum(obj.count for obj in list_all_objects())
Generator expressions differ from list comprehensions in various small ways.
Most notably, the loop variable (*obj* in the above example) is not accessible
outside of the generator expression. List comprehensions leave the variable
assigned to its last value; future versions of Python will change this, making
list comprehensions match generator expressions in this respect.
.. seealso::
:pep:`289` - Generator Expressions
Proposed by Raymond Hettinger and implemented by Jiwon Seo with early efforts
steered by Hye-Shik Chang.
.. ======================================================================
PEP 292: Simpler String Substitutions
=====================================
Some new classes in the standard library provide an alternative mechanism for
substituting variables into strings; this style of substitution may be better
for applications where untrained users need to edit templates.
The usual way of substituting variables by name is the ``%`` operator::
>>> '%(page)i: %(title)s' % {'page':2, 'title': 'The Best of Times'}
'2: The Best of Times'
When writing the template string, it can be easy to forget the ``i`` or ``s``
after the closing parenthesis. This isn't a big problem if the template is in a
Python module, because you run the code, get an "Unsupported format character"
:exc:`ValueError`, and fix the problem. However, consider an application such
as Mailman where template strings or translations are being edited by users who
aren't aware of the Python language. The format string's syntax is complicated
to explain to such users, and if they make a mistake, it's difficult to provide
helpful feedback to them.
PEP 292 adds a :class:`Template` class to the :mod:`string` module that uses
``$`` to indicate a substitution::
>>> import string
>>> t = string.Template('$page: $title')
>>> t.substitute({'page':2, 'title': 'The Best of Times'})
'2: The Best of Times'
If a key is missing from the dictionary, the :meth:`substitute` method will
raise a :exc:`KeyError`. There's also a :meth:`safe_substitute` method that
ignores missing keys::
>>> t = string.Template('$page: $title')
>>> t.safe_substitute({'page':3})
'3: $title'
.. seealso::
:pep:`292` - Simpler String Substitutions
Written and implemented by Barry Warsaw.
.. ======================================================================
PEP 318: Decorators for Functions and Methods
=============================================
Python 2.2 extended Python's object model by adding static methods and class
methods, but it didn't extend Python's syntax to provide any new way of defining
static or class methods. Instead, you had to write a :keyword:`def` statement
in the usual way, and pass the resulting method to a :func:`staticmethod` or
:func:`classmethod` function that would wrap up the function as a method of the
new type. Your code would look like this::
class C:
def meth (cls):
...
meth = classmethod(meth) # Rebind name to wrapped-up class method
If the method was very long, it would be easy to miss or forget the
:func:`classmethod` invocation after the function body.
The intention was always to add some syntax to make such definitions more
readable, but at the time of 2.2's release a good syntax was not obvious. Today
a good syntax *still* isn't obvious but users are asking for easier access to
the feature; a new syntactic feature has been added to meet this need.
The new feature is called "function decorators". The name comes from the idea
that :func:`classmethod`, :func:`staticmethod`, and friends are storing
additional information on a function object; they're *decorating* functions with
more details.
The notation borrows from Java and uses the ``'@'`` character as an indicator.
Using the new syntax, the example above would be written::
class C:
@classmethod
def meth (cls):
...
The ``@classmethod`` is shorthand for the ``meth=classmethod(meth)`` assignment.
More generally, if you have the following::
@A
@B
@C
def f ():
...
It's equivalent to the following pre-decorator code::
def f(): ...
f = A(B(C(f)))
Decorators must come on the line before a function definition, one decorator per
line, and can't be on the same line as the def statement, meaning that ``@A def
f(): ...`` is illegal. You can only decorate function definitions, either at
the module level or inside a class; you can't decorate class definitions.
A decorator is just a function that takes the function to be decorated as an
argument and returns either the same function or some new object. The return
value of the decorator need not be callable (though it typically is), unless
further decorators will be applied to the result. It's easy to write your own
decorators. The following simple example just sets an attribute on the function
object::
>>> def deco(func):
... func.attr = 'decorated'
... return func
...
>>> @deco
... def f(): pass
...
>>> f
<function f at 0x402ef0d4>
>>> f.attr
'decorated'
>>>
As a slightly more realistic example, the following decorator checks that the
supplied argument is an integer::
def require_int (func):
def wrapper (arg):
assert isinstance(arg, int)
return func(arg)
return wrapper
@require_int
def p1 (arg):
print arg
@require_int
def p2(arg):
print arg*2
An example in :pep:`318` contains a fancier version of this idea that lets you
both specify the required type and check the returned type.
Decorator functions can take arguments. If arguments are supplied, your
decorator function is called with only those arguments and must return a new
decorator function; this function must take a single function and return a
function, as previously described. In other words, ``@A @B @C(args)`` becomes::
def f(): ...
_deco = C(args)
f = A(B(_deco(f)))
Getting this right can be slightly brain-bending, but it's not too difficult.
A small related change makes the :attr:`func_name` attribute of functions
writable. This attribute is used to display function names in tracebacks, so
decorators should change the name of any new function that's constructed and
returned.
.. seealso::
:pep:`318` - Decorators for Functions, Methods and Classes
Written by Kevin D. Smith, Jim Jewett, and Skip Montanaro. Several people
wrote patches implementing function decorators, but the one that was actually
checked in was patch #979728, written by Mark Russell.
https://wiki.python.org/moin/PythonDecoratorLibrary
This Wiki page contains several examples of decorators.
.. ======================================================================
PEP 322: Reverse Iteration
==========================
A new built-in function, ``reversed(seq)``, takes a sequence and returns an
iterator that loops over the elements of the sequence in reverse order. ::
>>> for i in reversed(xrange(1,4)):
... print i
...
3
2
1
Compared to extended slicing, such as ``range(1,4)[::-1]``, :func:`reversed` is
easier to read, runs faster, and uses substantially less memory.
Note that :func:`reversed` only accepts sequences, not arbitrary iterators. If
you want to reverse an iterator, first convert it to a list with :func:`list`.
::
>>> input = open('/etc/passwd', 'r')
>>> for line in reversed(list(input)):
... print line
...
root:*:0:0:System Administrator:/var/root:/bin/tcsh
...
.. seealso::
:pep:`322` - Reverse Iteration
Written and implemented by Raymond Hettinger.
.. ======================================================================
PEP 324: New subprocess Module
==============================
The standard library provides a number of ways to execute a subprocess, offering
different features and different levels of complexity.
``os.system(command)`` is easy to use, but slow (it runs a shell process
which executes the command) and dangerous (you have to be careful about escaping
the shell's metacharacters). The :mod:`popen2` module offers classes that can
capture standard output and standard error from the subprocess, but the naming
is confusing. The :mod:`subprocess` module cleans this up, providing a unified
interface that offers all the features you might need.
Instead of :mod:`popen2`'s collection of classes, :mod:`subprocess` contains a
single class called :class:`Popen` whose constructor supports a number of
different keyword arguments. ::
class Popen(args, bufsize=0, executable=None,
stdin=None, stdout=None, stderr=None,
preexec_fn=None, close_fds=False, shell=False,
cwd=None, env=None, universal_newlines=False,
startupinfo=None, creationflags=0):
*args* is commonly a sequence of strings that will be the arguments to the
program executed as the subprocess. (If the *shell* argument is true, *args*
can be a string which will then be passed on to the shell for interpretation,
just as :func:`os.system` does.)
*stdin*, *stdout*, and *stderr* specify what the subprocess's input, output, and
error streams will be. You can provide a file object or a file descriptor, or
you can use the constant ``subprocess.PIPE`` to create a pipe between the
subprocess and the parent.
.. index::
single: universal newlines; What's new
The constructor has a number of handy options:
* *close_fds* requests that all file descriptors be closed before running the
subprocess.
* *cwd* specifies the working directory in which the subprocess will be executed
(defaulting to whatever the parent's working directory is).
* *env* is a dictionary specifying environment variables.
* *preexec_fn* is a function that gets called before the child is started.
* *universal_newlines* opens the child's input and output using Python's
:term:`universal newlines` feature.
Once you've created the :class:`Popen` instance, you can call its :meth:`wait`
method to pause until the subprocess has exited, :meth:`poll` to check if it's
exited without pausing, or ``communicate(data)`` to send the string *data*
to the subprocess's standard input. ``communicate(data)`` then reads any
data that the subprocess has sent to its standard output or standard error,
returning a tuple ``(stdout_data, stderr_data)``.
:func:`call` is a shortcut that passes its arguments along to the :class:`Popen`
constructor, waits for the command to complete, and returns the status code of
the subprocess. It can serve as a safer analog to :func:`os.system`::
sts = subprocess.call(['dpkg', '-i', '/tmp/new-package.deb'])
if sts == 0:
# Success
...
else:
# dpkg returned an error
...
The command is invoked without use of the shell. If you really do want to use
the shell, you can add ``shell=True`` as a keyword argument and provide a string
instead of a sequence::
sts = subprocess.call('dpkg -i /tmp/new-package.deb', shell=True)
The PEP takes various examples of shell and Python code and shows how they'd be
translated into Python code that uses :mod:`subprocess`. Reading this section
of the PEP is highly recommended.
.. seealso::
:pep:`324` - subprocess - New process module
Written and implemented by Peter Åstrand, with assistance from Fredrik Lundh and
others.
.. ======================================================================
PEP 327: Decimal Data Type
==========================
Python has always supported floating-point (FP) numbers, based on the underlying
C :c:type:`double` type, as a data type. However, while most programming
languages provide a floating-point type, many people (even programmers) are
unaware that floating-point numbers don't represent certain decimal fractions
accurately. The new :class:`Decimal` type can represent these fractions
accurately, up to a user-specified precision limit.
Why is Decimal needed?
----------------------
The limitations arise from the representation used for floating-point numbers.
FP numbers are made up of three components:
* The sign, which is positive or negative.
* The mantissa, which is a single-digit binary number followed by a fractional
part. For example, ``1.01`` in base-2 notation is ``1 + 0/2 + 1/4``, or 1.25 in
decimal notation.
* The exponent, which tells where the decimal point is located in the number
represented.
For example, the number 1.25 has positive sign, a mantissa value of 1.01 (in
binary), and an exponent of 0 (the decimal point doesn't need to be shifted).
The number 5 has the same sign and mantissa, but the exponent is 2 because the
mantissa is multiplied by 4 (2 to the power of the exponent 2); 1.25 \* 4 equals
5.
Modern systems usually provide floating-point support that conforms to a
standard called IEEE 754. C's :c:type:`double` type is usually implemented as a
64-bit IEEE 754 number, which uses 52 bits of space for the mantissa. This
means that numbers can only be specified to 52 bits of precision. If you're
trying to represent numbers whose expansion repeats endlessly, the expansion is
cut off after 52 bits. Unfortunately, most software needs to produce output in
base 10, and common fractions in base 10 are often repeating decimals in binary.
For example, 1.1 decimal is binary ``1.0001100110011 ...``; .1 = 1/16 + 1/32 +
1/256 plus an infinite number of additional terms. IEEE 754 has to chop off
that infinitely repeated decimal after 52 digits, so the representation is
slightly inaccurate.
Sometimes you can see this inaccuracy when the number is printed::
>>> 1.1
1.1000000000000001
The inaccuracy isn't always visible when you print the number because the
FP-to-decimal-string conversion is provided by the C library, and most C libraries try
to produce sensible output. Even if it's not displayed, however, the inaccuracy
is still there and subsequent operations can magnify the error.
For many applications this doesn't matter. If I'm plotting points and
displaying them on my monitor, the difference between 1.1 and 1.1000000000000001
is too small to be visible. Reports often limit output to a certain number of
decimal places, and if you round the number to two or three or even eight
decimal places, the error is never apparent. However, for applications where it
does matter, it's a lot of work to implement your own custom arithmetic
routines.
Hence, the :class:`Decimal` type was created.
The :class:`Decimal` type
-------------------------
A new module, :mod:`decimal`, was added to Python's standard library. It
contains two classes, :class:`Decimal` and :class:`Context`. :class:`Decimal`
instances represent numbers, and :class:`Context` instances are used to wrap up
various settings such as the precision and default rounding mode.
:class:`Decimal` instances are immutable, like regular Python integers and FP
numbers; once it's been created, you can't change the value an instance
represents. :class:`Decimal` instances can be created from integers or
strings::
>>> import decimal
>>> decimal.Decimal(1972)
Decimal("1972")
>>> decimal.Decimal("1.1")
Decimal("1.1")
You can also provide tuples containing the sign, the mantissa represented as a
tuple of decimal digits, and the exponent::
>>> decimal.Decimal((1, (1, 4, 7, 5), -2))
Decimal("-14.75")
Cautionary note: the sign bit is a Boolean value, so 0 is positive and 1 is
negative.
Converting from floating-point numbers poses a bit of a problem: should the FP
number representing 1.1 turn into the decimal number for exactly 1.1, or for 1.1
plus whatever inaccuracies are introduced? The decision was to dodge the issue
and leave such a conversion out of the API. Instead, you should convert the
floating-point number into a string using the desired precision and pass the
string to the :class:`Decimal` constructor::
>>> f = 1.1
>>> decimal.Decimal(str(f))
Decimal("1.1")
>>> decimal.Decimal('%.12f' % f)
Decimal("1.100000000000")
Once you have :class:`Decimal` instances, you can perform the usual mathematical
operations on them. One limitation: exponentiation requires an integer
exponent::
>>> a = decimal.Decimal('35.72')
>>> b = decimal.Decimal('1.73')
>>> a+b
Decimal("37.45")
>>> a-b
Decimal("33.99")
>>> a*b
Decimal("61.7956")
>>> a/b
Decimal("20.64739884393063583815028902")
>>> a ** 2
Decimal("1275.9184")
>>> a**b
Traceback (most recent call last):
...
decimal.InvalidOperation: x ** (non-integer)
You can combine :class:`Decimal` instances with integers, but not with
floating-point numbers::
>>> a + 4
Decimal("39.72")
>>> a + 4.5
Traceback (most recent call last):
...
TypeError: You can interact Decimal only with int, long or Decimal data types.
>>>
:class:`Decimal` numbers can be used with the :mod:`math` and :mod:`cmath`
modules, but note that they'll be immediately converted to floating-point
numbers before the operation is performed, resulting in a possible loss of
precision and accuracy. You'll also get back a regular floating-point number
and not a :class:`Decimal`. ::
>>> import math, cmath
>>> d = decimal.Decimal('123456789012.345')
>>> math.sqrt(d)
351364.18288201344
>>> cmath.sqrt(-d)
351364.18288201344j
:class:`Decimal` instances have a :meth:`sqrt` method that returns a
:class:`Decimal`, but if you need other things such as trigonometric functions
you'll have to implement them. ::
>>> d.sqrt()
Decimal("351364.1828820134592177245001")
The :class:`Context` type
-------------------------
Instances of the :class:`Context` class encapsulate several settings for
decimal operations:
* :attr:`prec` is the precision, the number of decimal places.
* :attr:`rounding` specifies the rounding mode. The :mod:`decimal` module has
constants for the various possibilities: :const:`ROUND_DOWN`,
:const:`ROUND_CEILING`, :const:`ROUND_HALF_EVEN`, and various others.
* :attr:`traps` is a dictionary specifying what happens on encountering certain
error conditions: either an exception is raised or a value is returned. Some
examples of error conditions are division by zero, loss of precision, and
overflow.
There's a thread-local default context available by calling :func:`getcontext`;
you can change the properties of this context to alter the default precision,
rounding, or trap handling. The following example shows the effect of changing
the precision of the default context::
>>> decimal.getcontext().prec
28
>>> decimal.Decimal(1) / decimal.Decimal(7)
Decimal("0.1428571428571428571428571429")
>>> decimal.getcontext().prec = 9
>>> decimal.Decimal(1) / decimal.Decimal(7)
Decimal("0.142857143")
The default action for error conditions is selectable; the module can either
return a special value such as infinity or not-a-number, or exceptions can be
raised::
>>> decimal.Decimal(1) / decimal.Decimal(0)
Traceback (most recent call last):
...
decimal.DivisionByZero: x / 0
>>> decimal.getcontext().traps[decimal.DivisionByZero] = False
>>> decimal.Decimal(1) / decimal.Decimal(0)
Decimal("Infinity")
>>>
The :class:`Context` instance also has various methods for formatting numbers
such as :meth:`to_eng_string` and :meth:`to_sci_string`.
For more information, see the documentation for the :mod:`decimal` module, which
includes a quick-start tutorial and a reference.
.. seealso::
:pep:`327` - Decimal Data Type
Written by Facundo Batista and implemented by Facundo Batista, Eric Price,
Raymond Hettinger, Aahz, and Tim Peters.
http://www.lahey.com/float.htm
The article uses Fortran code to illustrate many of the problems that
floating-point inaccuracy can cause.
http://speleotrove.com/decimal/
A description of a decimal-based representation. This representation is being
proposed as a standard, and underlies the new Python decimal type. Much of this
material was written by Mike Cowlishaw, designer of the Rexx language.
.. ======================================================================
PEP 328: Multi-line Imports
===========================
One language change is a small syntactic tweak aimed at making it easier to
import many names from a module. In a ``from module import names`` statement,
*names* is a sequence of names separated by commas. If the sequence is very
long, you can either write multiple imports from the same module, or you can use
backslashes to escape the line endings like this::
from SimpleXMLRPCServer import SimpleXMLRPCServer,\
SimpleXMLRPCRequestHandler,\
CGIXMLRPCRequestHandler,\
resolve_dotted_attribute
The syntactic change in Python 2.4 simply allows putting the names within
parentheses. Python ignores newlines within a parenthesized expression, so the
backslashes are no longer needed::
from SimpleXMLRPCServer import (SimpleXMLRPCServer,
SimpleXMLRPCRequestHandler,
CGIXMLRPCRequestHandler,
resolve_dotted_attribute)
The PEP also proposes that all :keyword:`import` statements be absolute imports,
with a leading ``.`` character to indicate a relative import. This part of the
PEP was not implemented for Python 2.4, but was completed for Python 2.5.
.. seealso::
:pep:`328` - Imports: Multi-Line and Absolute/Relative
Written by Aahz. Multi-line imports were implemented by Dima Dorfman.
.. ======================================================================
PEP 331: Locale-Independent Float/String Conversions
====================================================
The :mod:`locale` modules lets Python software select various conversions and
display conventions that are localized to a particular country or language.
However, the module was careful to not change the numeric locale because various
functions in Python's implementation required that the numeric locale remain set
to the ``'C'`` locale. Often this was because the code was using the C
library's :c:func:`atof` function.
Not setting the numeric locale caused trouble for extensions that used third-party
C libraries, however, because they wouldn't have the correct locale set.
The motivating example was GTK+, whose user interface widgets weren't displaying
numbers in the current locale.
The solution described in the PEP is to add three new functions to the Python
API that perform ASCII-only conversions, ignoring the locale setting:
* ``PyOS_ascii_strtod(str, ptr)`` and ``PyOS_ascii_atof(str, ptr)``
both convert a string to a C :c:type:`double`.
* ``PyOS_ascii_formatd(buffer, buf_len, format, d)`` converts a
:c:type:`double` to an ASCII string.
The code for these functions came from the GLib library
(https://developer.gnome.org/glib/stable/), whose developers kindly
relicensed the relevant functions and donated them to the Python Software
Foundation. The :mod:`locale` module can now change the numeric locale,
letting extensions such as GTK+ produce the correct results.
.. seealso::
:pep:`331` - Locale-Independent Float/String Conversions
Written by Christian R. Reis, and implemented by Gustavo Carneiro.
.. ======================================================================
Other Language Changes
======================
Here are all of the changes that Python 2.4 makes to the core Python language.
* Decorators for functions and methods were added (:pep:`318`).
* Built-in :func:`set` and :func:`frozenset` types were added (:pep:`218`).
Other new built-ins include the ``reversed(seq)`` function (:pep:`322`).
* Generator expressions were added (:pep:`289`).
* Certain numeric expressions no longer return values restricted to 32 or 64
bits (:pep:`237`).
* You can now put parentheses around the list of names in a ``from module import
names`` statement (:pep:`328`).
* The :meth:`dict.update` method now accepts the same argument forms as the
:class:`dict` constructor. This includes any mapping, any iterable of key/value
pairs, and keyword arguments. (Contributed by Raymond Hettinger.)
* The string methods :meth:`ljust`, :meth:`rjust`, and :meth:`center` now take
an optional argument for specifying a fill character other than a space.
(Contributed by Raymond Hettinger.)
* Strings also gained an :meth:`rsplit` method that works like the :meth:`split`
method but splits from the end of the string. (Contributed by Sean
Reifschneider.) ::
>>> 'www.python.org'.split('.', 1)
['www', 'python.org']
'www.python.org'.rsplit('.', 1)
['www.python', 'org']
* Three keyword parameters, *cmp*, *key*, and *reverse*, were added to the
:meth:`sort` method of lists. These parameters make some common usages of
:meth:`sort` simpler. All of these parameters are optional.
For the *cmp* parameter, the value should be a comparison function that takes
two parameters and returns -1, 0, or +1 depending on how the parameters compare.
This function will then be used to sort the list. Previously this was the only
parameter that could be provided to :meth:`sort`.
*key* should be a single-parameter function that takes a list element and
returns a comparison key for the element. The list is then sorted using the
comparison keys. The following example sorts a list case-insensitively::
>>> L = ['A', 'b', 'c', 'D']
>>> L.sort() # Case-sensitive sort
>>> L
['A', 'D', 'b', 'c']
>>> # Using 'key' parameter to sort list
>>> L.sort(key=lambda x: x.lower())
>>> L
['A', 'b', 'c', 'D']
>>> # Old-fashioned way
>>> L.sort(cmp=lambda x,y: cmp(x.lower(), y.lower()))
>>> L
['A', 'b', 'c', 'D']
The last example, which uses the *cmp* parameter, is the old way to perform a
case-insensitive sort. It works but is slower than using a *key* parameter.
Using *key* calls :meth:`lower` method once for each element in the list while
using *cmp* will call it twice for each comparison, so using *key* saves on
invocations of the :meth:`lower` method.
For simple key functions and comparison functions, it is often possible to avoid
a :keyword:`lambda` expression by using an unbound method instead. For example,
the above case-insensitive sort is best written as::
>>> L.sort(key=str.lower)
>>> L
['A', 'b', 'c', 'D']
Finally, the *reverse* parameter takes a Boolean value. If the value is true,
the list will be sorted into reverse order. Instead of ``L.sort();
L.reverse()``, you can now write ``L.sort(reverse=True)``.
The results of sorting are now guaranteed to be stable. This means that two
entries with equal keys will be returned in the same order as they were input.
For example, you can sort a list of people by name, and then sort the list by
age, resulting in a list sorted by age where people with the same age are in
name-sorted order.
(All changes to :meth:`sort` contributed by Raymond Hettinger.)
* There is a new built-in function ``sorted(iterable)`` that works like the
in-place :meth:`list.sort` method but can be used in expressions. The
differences are:
* the input may be any iterable;
* a newly formed copy is sorted, leaving the original intact; and
* the expression returns the new sorted copy
::
>>> L = [9,7,8,3,2,4,1,6,5]
>>> [10+i for i in sorted(L)] # usable in a list comprehension
[11, 12, 13, 14, 15, 16, 17, 18, 19]
>>> L # original is left unchanged
[9,7,8,3,2,4,1,6,5]
>>> sorted('Monty Python') # any iterable may be an input
[' ', 'M', 'P', 'h', 'n', 'n', 'o', 'o', 't', 't', 'y', 'y']
>>> # List the contents of a dict sorted by key values
>>> colormap = dict(red=1, blue=2, green=3, black=4, yellow=5)
>>> for k, v in sorted(colormap.iteritems()):
... print k, v
...
black 4
blue 2
green 3
red 1
yellow 5
(Contributed by Raymond Hettinger.)
* Integer operations will no longer trigger an :exc:`OverflowWarning`. The
:exc:`OverflowWarning` warning will disappear in Python 2.5.
* The interpreter gained a new switch, :option:`-m`, that takes a name, searches
for the corresponding module on ``sys.path``, and runs the module as a script.
For example, you can now run the Python profiler with ``python -m profile``.
(Contributed by Nick Coghlan.)
* The ``eval(expr, globals, locals)`` and ``execfile(filename, globals,
locals)`` functions and the :keyword:`exec` statement now accept any mapping type
for the *locals* parameter. Previously this had to be a regular Python
dictionary. (Contributed by Raymond Hettinger.)
* The :func:`zip` built-in function and :func:`itertools.izip` now return an
empty list if called with no arguments. Previously they raised a
:exc:`TypeError` exception. This makes them more suitable for use with variable
length argument lists::
>>> def transpose(array):
... return zip(*array)
...
>>> transpose([(1,2,3), (4,5,6)])
[(1, 4), (2, 5), (3, 6)]
>>> transpose([])
[]
(Contributed by Raymond Hettinger.)
* Encountering a failure while importing a module no longer leaves a partially-initialized
module object in ``sys.modules``. The incomplete module object left
behind would fool further imports of the same module into succeeding, leading to
confusing errors. (Fixed by Tim Peters.)
* :const:`None` is now a constant; code that binds a new value to the name
``None`` is now a syntax error. (Contributed by Raymond Hettinger.)
.. ======================================================================
Optimizations
-------------
* The inner loops for list and tuple slicing were optimized and now run about
one-third faster. The inner loops for dictionaries were also optimized,
resulting in performance boosts for :meth:`keys`, :meth:`values`, :meth:`items`,
:meth:`iterkeys`, :meth:`itervalues`, and :meth:`iteritems`. (Contributed by
Raymond Hettinger.)
* The machinery for growing and shrinking lists was optimized for speed and for
space efficiency. Appending and popping from lists now runs faster due to more
efficient code paths and less frequent use of the underlying system
:c:func:`realloc`. List comprehensions also benefit. :meth:`list.extend` was
also optimized and no longer converts its argument into a temporary list before
extending the base list. (Contributed by Raymond Hettinger.)
* :func:`list`, :func:`tuple`, :func:`map`, :func:`filter`, and :func:`zip` now
run several times faster with non-sequence arguments that supply a
:meth:`__len__` method. (Contributed by Raymond Hettinger.)
* The methods :meth:`list.__getitem__`, :meth:`dict.__getitem__`, and
:meth:`dict.__contains__` are now implemented as :class:`method_descriptor`
objects rather than :class:`wrapper_descriptor` objects. This form of access
doubles their performance and makes them more suitable for use as arguments to
functionals: ``map(mydict.__getitem__, keylist)``. (Contributed by Raymond
Hettinger.)
* Added a new opcode, ``LIST_APPEND``, that simplifies the generated bytecode
for list comprehensions and speeds them up by about a third. (Contributed by
Raymond Hettinger.)
* The peephole bytecode optimizer has been improved to produce shorter, faster
bytecode; remarkably, the resulting bytecode is more readable. (Enhanced by
Raymond Hettinger.)
* String concatenations in statements of the form ``s = s + "abc"`` and ``s +=
"abc"`` are now performed more efficiently in certain circumstances. This
optimization won't be present in other Python implementations such as Jython, so
you shouldn't rely on it; using the :meth:`join` method of strings is still
recommended when you want to efficiently glue a large number of strings
together. (Contributed by Armin Rigo.)
The net result of the 2.4 optimizations is that Python 2.4 runs the pystone
benchmark around 5% faster than Python 2.3 and 35% faster than Python 2.2.
(pystone is not a particularly good benchmark, but it's the most commonly used
measurement of Python's performance. Your own applications may show greater or
smaller benefits from Python 2.4.)
.. pystone is almost useless for comparing different versions of Python;
instead, it excels at predicting relative Python performance on different
machines. So, this section would be more informative if it used other tools
such as pybench and parrotbench. For a more application oriented benchmark,
try comparing the timings of test_decimal.py under 2.3 and 2.4.
.. ======================================================================
New, Improved, and Deprecated Modules
=====================================
As usual, Python's standard library received a number of enhancements and bug
fixes. Here's a partial list of the most notable changes, sorted alphabetically
by module name. Consult the :file:`Misc/NEWS` file in the source tree for a more
complete list of changes, or look through the CVS logs for all the details.
* The :mod:`asyncore` module's :func:`loop` function now has a *count* parameter
that lets you perform a limited number of passes through the polling loop. The
default is still to loop forever.
* The :mod:`base64` module now has more complete RFC 3548 support for Base64,
Base32, and Base16 encoding and decoding, including optional case folding and
optional alternative alphabets. (Contributed by Barry Warsaw.)
* The :mod:`bisect` module now has an underlying C implementation for improved
performance. (Contributed by Dmitry Vasiliev.)
* The CJKCodecs collections of East Asian codecs, maintained by Hye-Shik Chang,
was integrated into 2.4. The new encodings are:
* Chinese (PRC): gb2312, gbk, gb18030, big5hkscs, hz
* Chinese (ROC): big5, cp950
* Japanese: cp932, euc-jis-2004, euc-jp, euc-jisx0213, iso-2022-jp,
iso-2022-jp-1, iso-2022-jp-2, iso-2022-jp-3, iso-2022-jp-ext, iso-2022-jp-2004,
shift-jis, shift-jisx0213, shift-jis-2004
* Korean: cp949, euc-kr, johab, iso-2022-kr
* Some other new encodings were added: HP Roman8, ISO_8859-11, ISO_8859-16,
PCTP-154, and TIS-620.
* The UTF-8 and UTF-16 codecs now cope better with receiving partial input.
Previously the :class:`StreamReader` class would try to read more data, making
it impossible to resume decoding from the stream. The :meth:`read` method will
now return as much data as it can and future calls will resume decoding where
previous ones left off. (Implemented by Walter Dörwald.)
* There is a new :mod:`collections` module for various specialized collection
datatypes. Currently it contains just one type, :class:`deque`, a double-ended
queue that supports efficiently adding and removing elements from either
end::
>>> from collections import deque
>>> d = deque('ghi') # make a new deque with three items
>>> d.append('j') # add a new entry to the right side
>>> d.appendleft('f') # add a new entry to the left side
>>> d # show the representation of the deque
deque(['f', 'g', 'h', 'i', 'j'])
>>> d.pop() # return and remove the rightmost item
'j'
>>> d.popleft() # return and remove the leftmost item
'f'
>>> list(d) # list the contents of the deque
['g', 'h', 'i']
>>> 'h' in d # search the deque
True
Several modules, such as the :mod:`Queue` and :mod:`threading` modules, now take
advantage of :class:`collections.deque` for improved performance. (Contributed
by Raymond Hettinger.)
* The :mod:`ConfigParser` classes have been enhanced slightly. The :meth:`read`
method now returns a list of the files that were successfully parsed, and the
:meth:`set` method raises :exc:`TypeError` if passed a *value* argument that
isn't a string. (Contributed by John Belmonte and David Goodger.)
* The :mod:`curses` module now supports the ncurses extension
:func:`use_default_colors`. On platforms where the terminal supports
transparency, this makes it possible to use a transparent background.
(Contributed by Jörg Lehmann.)
* The :mod:`difflib` module now includes an :class:`HtmlDiff` class that creates
an HTML table showing a side by side comparison of two versions of a text.
(Contributed by Dan Gass.)
* The :mod:`email` package was updated to version 3.0, which dropped various
deprecated APIs and removes support for Python versions earlier than 2.3. The
3.0 version of the package uses a new incremental parser for MIME messages,
available in the :mod:`email.FeedParser` module. The new parser doesn't require
reading the entire message into memory, and doesn't raise exceptions if a
message is malformed; instead it records any problems in the :attr:`defect`
attribute of the message. (Developed by Anthony Baxter, Barry Warsaw, Thomas
Wouters, and others.)
* The :mod:`heapq` module has been converted to C. The resulting tenfold
improvement in speed makes the module suitable for handling high volumes of
data. In addition, the module has two new functions :func:`nlargest` and
:func:`nsmallest` that use heaps to find the N largest or smallest values in a
dataset without the expense of a full sort. (Contributed by Raymond Hettinger.)
* The :mod:`httplib` module now contains constants for HTTP status codes defined
in various HTTP-related RFC documents. Constants have names such as
:const:`OK`, :const:`CREATED`, :const:`CONTINUE`, and
:const:`MOVED_PERMANENTLY`; use pydoc to get a full list. (Contributed by
Andrew Eland.)
* The :mod:`imaplib` module now supports IMAP's THREAD command (contributed by
Yves Dionne) and new :meth:`deleteacl` and :meth:`myrights` methods (contributed
by Arnaud Mazin).
* The :mod:`itertools` module gained a ``groupby(iterable[, *func*])``
function. *iterable* is something that can be iterated over to return a stream
of elements, and the optional *func* parameter is a function that takes an
element and returns a key value; if omitted, the key is simply the element
itself. :func:`groupby` then groups the elements into subsequences which have
matching values of the key, and returns a series of 2-tuples containing the key
value and an iterator over the subsequence.
Here's an example to make this clearer. The *key* function simply returns
whether a number is even or odd, so the result of :func:`groupby` is to return
consecutive runs of odd or even numbers. ::
>>> import itertools
>>> L = [2, 4, 6, 7, 8, 9, 11, 12, 14]
>>> for key_val, it in itertools.groupby(L, lambda x: x % 2):
... print key_val, list(it)
...
0 [2, 4, 6]
1 [7]
0 [8]
1 [9, 11]
0 [12, 14]
>>>
:func:`groupby` is typically used with sorted input. The logic for
:func:`groupby` is similar to the Unix ``uniq`` filter which makes it handy for
eliminating, counting, or identifying duplicate elements::
>>> word = 'abracadabra'
>>> letters = sorted(word) # Turn string into a sorted list of letters
>>> letters
['a', 'a', 'a', 'a', 'a', 'b', 'b', 'c', 'd', 'r', 'r']
>>> for k, g in itertools.groupby(letters):
... print k, list(g)
...
a ['a', 'a', 'a', 'a', 'a']
b ['b', 'b']
c ['c']
d ['d']
r ['r', 'r']
>>> # List unique letters
>>> [k for k, g in groupby(letters)]
['a', 'b', 'c', 'd', 'r']
>>> # Count letter occurrences
>>> [(k, len(list(g))) for k, g in groupby(letters)]
[('a', 5), ('b', 2), ('c', 1), ('d', 1), ('r', 2)]
(Contributed by Hye-Shik Chang.)
* :mod:`itertools` also gained a function named ``tee(iterator, N)`` that
returns *N* independent iterators that replicate *iterator*. If *N* is omitted,
the default is 2. ::
>>> L = [1,2,3]
>>> i1, i2 = itertools.tee(L)
>>> i1,i2
(<itertools.tee object at 0x402c2080>, <itertools.tee object at 0x402c2090>)
>>> list(i1) # Run the first iterator to exhaustion
[1, 2, 3]
>>> list(i2) # Run the second iterator to exhaustion
[1, 2, 3]
Note that :func:`tee` has to keep copies of the values returned by the
iterator; in the worst case, it may need to keep all of them. This should
therefore be used carefully if the leading iterator can run far ahead of the
trailing iterator in a long stream of inputs. If the separation is large, then
you might as well use :func:`list` instead. When the iterators track closely
with one another, :func:`tee` is ideal. Possible applications include
bookmarking, windowing, or lookahead iterators. (Contributed by Raymond
Hettinger.)
* A number of functions were added to the :mod:`locale` module, such as
:func:`bind_textdomain_codeset` to specify a particular encoding and a family of
:func:`l\*gettext` functions that return messages in the chosen encoding.
(Contributed by Gustavo Niemeyer.)
* Some keyword arguments were added to the :mod:`logging` package's
:func:`basicConfig` function to simplify log configuration. The default
behavior is to log messages to standard error, but various keyword arguments can
be specified to log to a particular file, change the logging format, or set the
logging level. For example::
import logging
logging.basicConfig(filename='/var/log/application.log',
level=0, # Log all messages
format='%(levelname):%(process):%(thread):%(message)')
Other additions to the :mod:`logging` package include a ``log(level, msg)``
convenience method, as well as a :class:`TimedRotatingFileHandler` class that
rotates its log files at a timed interval. The module already had
:class:`RotatingFileHandler`, which rotated logs once the file exceeded a
certain size. Both classes derive from a new :class:`BaseRotatingHandler` class
that can be used to implement other rotating handlers.
(Changes implemented by Vinay Sajip.)
* The :mod:`marshal` module now shares interned strings on unpacking a data
structure. This may shrink the size of certain pickle strings, but the primary
effect is to make :file:`.pyc` files significantly smaller. (Contributed by
Martin von Löwis.)
* The :mod:`nntplib` module's :class:`NNTP` class gained :meth:`description` and
:meth:`descriptions` methods to retrieve newsgroup descriptions for a single
group or for a range of groups. (Contributed by Jürgen A. Erhard.)
* Two new functions were added to the :mod:`operator` module,
``attrgetter(attr)`` and ``itemgetter(index)``. Both functions return
callables that take a single argument and return the corresponding attribute or
item; these callables make excellent data extractors when used with :func:`map`
or :func:`sorted`. For example::
>>> L = [('c', 2), ('d', 1), ('a', 4), ('b', 3)]
>>> map(operator.itemgetter(0), L)
['c', 'd', 'a', 'b']
>>> map(operator.itemgetter(1), L)
[2, 1, 4, 3]
>>> sorted(L, key=operator.itemgetter(1)) # Sort list by second tuple item
[('d', 1), ('c', 2), ('b', 3), ('a', 4)]
(Contributed by Raymond Hettinger.)
* The :mod:`optparse` module was updated in various ways. The module now passes
its messages through :func:`gettext.gettext`, making it possible to
internationalize Optik's help and error messages. Help messages for options can
now include the string ``'%default'``, which will be replaced by the option's
default value. (Contributed by Greg Ward.)
* The long-term plan is to deprecate the :mod:`rfc822` module in some future
Python release in favor of the :mod:`email` package. To this end, the
:func:`email.Utils.formatdate` function has been changed to make it usable as a
replacement for :func:`rfc822.formatdate`. You may want to write new e-mail
processing code with this in mind. (Change implemented by Anthony Baxter.)
* A new ``urandom(n)`` function was added to the :mod:`os` module, returning
a string containing *n* bytes of random data. This function provides access to
platform-specific sources of randomness such as :file:`/dev/urandom` on Linux or
the Windows CryptoAPI. (Contributed by Trevor Perrin.)
* Another new function: ``os.path.lexists(path)`` returns true if the file
specified by *path* exists, whether or not it's a symbolic link. This differs
from the existing ``os.path.exists(path)`` function, which returns false if
*path* is a symlink that points to a destination that doesn't exist.
(Contributed by Beni Cherniavsky.)
* A new :func:`getsid` function was added to the :mod:`posix` module that
underlies the :mod:`os` module. (Contributed by J. Raynor.)
* The :mod:`poplib` module now supports POP over SSL. (Contributed by Hector
Urtubia.)
* The :mod:`profile` module can now profile C extension functions. (Contributed
by Nick Bastin.)
* The :mod:`random` module has a new method called ``getrandbits(N)`` that
returns a long integer *N* bits in length. The existing :meth:`randrange`
method now uses :meth:`getrandbits` where appropriate, making generation of
arbitrarily large random numbers more efficient. (Contributed by Raymond
Hettinger.)
* The regular expression language accepted by the :mod:`re` module was extended
with simple conditional expressions, written as ``(?(group)A|B)``. *group* is
either a numeric group ID or a group name defined with ``(?P<group>...)``
earlier in the expression. If the specified group matched, the regular
expression pattern *A* will be tested against the string; if the group didn't
match, the pattern *B* will be used instead. (Contributed by Gustavo Niemeyer.)
* The :mod:`re` module is also no longer recursive, thanks to a massive amount
of work by Gustavo Niemeyer. In a recursive regular expression engine, certain
patterns result in a large amount of C stack space being consumed, and it was
possible to overflow the stack. For example, if you matched a 30000-byte string
of ``a`` characters against the expression ``(a|b)+``, one stack frame was
consumed per character. Python 2.3 tried to check for stack overflow and raise
a :exc:`RuntimeError` exception, but certain patterns could sidestep the
checking and if you were unlucky Python could segfault. Python 2.4's regular
expression engine can match this pattern without problems.
* The :mod:`signal` module now performs tighter error-checking on the parameters
to the :func:`signal.signal` function. For example, you can't set a handler on
the :const:`SIGKILL` signal; previous versions of Python would quietly accept
this, but 2.4 will raise a :exc:`RuntimeError` exception.
* Two new functions were added to the :mod:`socket` module. :func:`socketpair`
returns a pair of connected sockets and ``getservbyport(port)`` looks up the
service name for a given port number. (Contributed by Dave Cole and Barry
Warsaw.)
* The :func:`sys.exitfunc` function has been deprecated. Code should be using
the existing :mod:`atexit` module, which correctly handles calling multiple exit
functions. Eventually :func:`sys.exitfunc` will become a purely internal
interface, accessed only by :mod:`atexit`.
* The :mod:`tarfile` module now generates GNU-format tar files by default.
(Contributed by Lars Gustaebel.)
* The :mod:`threading` module now has an elegantly simple way to support
thread-local data. The module contains a :class:`local` class whose attribute
values are local to different threads. ::
import threading
data = threading.local()
data.number = 42
data.url = ('www.python.org', 80)
Other threads can assign and retrieve their own values for the :attr:`number`
and :attr:`url` attributes. You can subclass :class:`local` to initialize
attributes or to add methods. (Contributed by Jim Fulton.)
* The :mod:`timeit` module now automatically disables periodic garbage
collection during the timing loop. This change makes consecutive timings more
comparable. (Contributed by Raymond Hettinger.)
* The :mod:`weakref` module now supports a wider variety of objects including
Python functions, class instances, sets, frozensets, deques, arrays, files,
sockets, and regular expression pattern objects. (Contributed by Raymond
Hettinger.)
* The :mod:`xmlrpclib` module now supports a multi-call extension for
transmitting multiple XML-RPC calls in a single HTTP operation. (Contributed by
Brian Quinlan.)
* The :mod:`mpz`, :mod:`rotor`, and :mod:`xreadlines` modules have been
removed.
.. ======================================================================
.. whole new modules get described in subsections here
.. =====================
cookielib
---------
The :mod:`cookielib` library supports client-side handling for HTTP cookies,
mirroring the :mod:`Cookie` module's server-side cookie support. Cookies are
stored in cookie jars; the library transparently stores cookies offered by the
web server in the cookie jar, and fetches the cookie from the jar when
connecting to the server. As in web browsers, policy objects control whether
cookies are accepted or not.
In order to store cookies across sessions, two implementations of cookie jars
are provided: one that stores cookies in the Netscape format so applications can
use the Mozilla or Lynx cookie files, and one that stores cookies in the same
format as the Perl libwww library.
:mod:`urllib2` has been changed to interact with :mod:`cookielib`:
:class:`HTTPCookieProcessor` manages a cookie jar that is used when accessing
URLs.
This module was contributed by John J. Lee.
.. ==================
doctest
-------
The :mod:`doctest` module underwent considerable refactoring thanks to Edward
Loper and Tim Peters. Testing can still be as simple as running
:func:`doctest.testmod`, but the refactorings allow customizing the module's
operation in various ways
The new :class:`DocTestFinder` class extracts the tests from a given object's
docstrings::
def f (x, y):
""">>> f(2,2)
4
>>> f(3,2)
6
"""
return x*y
finder = doctest.DocTestFinder()
# Get list of DocTest instances
tests = finder.find(f)
The new :class:`DocTestRunner` class then runs individual tests and can produce
a summary of the results::
runner = doctest.DocTestRunner()
for t in tests:
tried, failed = runner.run(t)
runner.summarize(verbose=1)
The above example produces the following output::
1 items passed all tests:
2 tests in f
2 tests in 1 items.
2 passed and 0 failed.
Test passed.
:class:`DocTestRunner` uses an instance of the :class:`OutputChecker` class to
compare the expected output with the actual output. This class takes a number
of different flags that customize its behaviour; ambitious users can also write
a completely new subclass of :class:`OutputChecker`.
The default output checker provides a number of handy features. For example,
with the :const:`doctest.ELLIPSIS` option flag, an ellipsis (``...``) in the
expected output matches any substring, making it easier to accommodate outputs
that vary in minor ways::
def o (n):
""">>> o(1)
<__main__.C instance at 0x...>
>>>
"""
Another special string, ``<BLANKLINE>``, matches a blank line::
def p (n):
""">>> p(1)
<BLANKLINE>
>>>
"""
Another new capability is producing a diff-style display of the output by
specifying the :const:`doctest.REPORT_UDIFF` (unified diffs),
:const:`doctest.REPORT_CDIFF` (context diffs), or :const:`doctest.REPORT_NDIFF`
(delta-style) option flags. For example::
def g (n):
""">>> g(4)
here
is
a
lengthy
>>>"""
L = 'here is a rather lengthy list of words'.split()
for word in L[:n]:
print word
Running the above function's tests with :const:`doctest.REPORT_UDIFF` specified,
you get the following output:
.. code-block:: none
**********************************************************************
File "t.py", line 15, in g
Failed example:
g(4)
Differences (unified diff with -expected +actual):
@@ -2,3 +2,3 @@
is
a
-lengthy
+rather
**********************************************************************
.. ======================================================================
Build and C API Changes
=======================
Some of the changes to Python's build process and to the C API are:
* Three new convenience macros were added for common return values from
extension functions: :c:macro:`Py_RETURN_NONE`, :c:macro:`Py_RETURN_TRUE`, and
:c:macro:`Py_RETURN_FALSE`. (Contributed by Brett Cannon.)
* Another new macro, :c:macro:`Py_CLEAR(obj)`, decreases the reference count of
*obj* and sets *obj* to the null pointer. (Contributed by Jim Fulton.)
* A new function, ``PyTuple_Pack(N, obj1, obj2, ..., objN)``, constructs
tuples from a variable length argument list of Python objects. (Contributed by
Raymond Hettinger.)
* A new function, ``PyDict_Contains(d, k)``, implements fast dictionary
lookups without masking exceptions raised during the look-up process.
(Contributed by Raymond Hettinger.)
* The :c:macro:`Py_IS_NAN(X)` macro returns 1 if its float or double argument
*X* is a NaN. (Contributed by Tim Peters.)
* C code can avoid unnecessary locking by using the new
:c:func:`PyEval_ThreadsInitialized` function to tell if any thread operations
have been performed. If this function returns false, no lock operations are
needed. (Contributed by Nick Coghlan.)
* A new function, :c:func:`PyArg_VaParseTupleAndKeywords`, is the same as
:c:func:`PyArg_ParseTupleAndKeywords` but takes a :c:type:`va_list` instead of a
number of arguments. (Contributed by Greg Chapman.)
* A new method flag, :const:`METH_COEXISTS`, allows a function defined in slots
to co-exist with a :c:type:`PyCFunction` having the same name. This can halve
the access time for a method such as :meth:`set.__contains__`. (Contributed by
Raymond Hettinger.)
* Python can now be built with additional profiling for the interpreter itself,
intended as an aid to people developing the Python core. Providing
:option:`!--enable-profiling` to the :program:`configure` script will let you
profile the interpreter with :program:`gprof`, and providing the
:option:`!--with-tsc` switch enables profiling using the Pentium's
Time-Stamp-Counter register. Note that the :option:`!--with-tsc` switch is slightly
misnamed, because the profiling feature also works on the PowerPC platform,
though that processor architecture doesn't call that register "the TSC
register". (Contributed by Jeremy Hylton.)
* The :c:type:`tracebackobject` type has been renamed to
:c:type:`PyTracebackObject`.
.. ======================================================================
Port-Specific Changes
---------------------
* The Windows port now builds under MSVC++ 7.1 as well as version 6.
(Contributed by Martin von Löwis.)
.. ======================================================================
Porting to Python 2.4
=====================
This section lists previously described changes that may require changes to your
code:
* Left shifts and hexadecimal/octal constants that are too large no longer
trigger a :exc:`FutureWarning` and return a value limited to 32 or 64 bits;
instead they return a long integer.
* Integer operations will no longer trigger an :exc:`OverflowWarning`. The
:exc:`OverflowWarning` warning will disappear in Python 2.5.
* The :func:`zip` built-in function and :func:`itertools.izip` now return an
empty list instead of raising a :exc:`TypeError` exception if called with no
arguments.
* You can no longer compare the :class:`date` and :class:`~datetime.datetime` instances
provided by the :mod:`datetime` module. Two instances of different classes
will now always be unequal, and relative comparisons (``<``, ``>``) will raise
a :exc:`TypeError`.
* :func:`dircache.listdir` now passes exceptions to the caller instead of
returning empty lists.
* :func:`LexicalHandler.startDTD` used to receive the public and system IDs in
the wrong order. This has been corrected; applications relying on the wrong
order need to be fixed.
* :func:`fcntl.ioctl` now warns if the *mutate* argument is omitted and
relevant.
* The :mod:`tarfile` module now generates GNU-format tar files by default.
* Encountering a failure while importing a module no longer leaves a
partially-initialized module object in ``sys.modules``.
* :const:`None` is now a constant; code that binds a new value to the name
``None`` is now a syntax error.
* The :func:`signals.signal` function now raises a :exc:`RuntimeError` exception
for certain illegal values; previously these errors would pass silently. For
example, you can no longer set a handler on the :const:`SIGKILL` signal.
.. ======================================================================
.. _24acks:
Acknowledgements
================
The author would like to thank the following people for offering suggestions,
corrections and assistance with various drafts of this article: Koray Can,
Hye-Shik Chang, Michael Dyck, Raymond Hettinger, Brian Hurt, Hamish Lawson,
Fredrik Lundh, Sean Reifschneider, Sadruddin Rejeb.
PK
%�\(QK�,� ,� " html/_sources/whatsnew/2.5.rst.txtnu �[��� ****************************
What's New in Python 2.5
****************************
:Author: A.M. Kuchling
.. |release| replace:: 1.01
.. $Id: whatsnew25.tex 56611 2007-07-29 08:26:10Z georg.brandl $
.. Fix XXX comments
This article explains the new features in Python 2.5. The final release of
Python 2.5 is scheduled for August 2006; :pep:`356` describes the planned
release schedule.
The changes in Python 2.5 are an interesting mix of language and library
improvements. The library enhancements will be more important to Python's user
community, I think, because several widely-useful packages were added. New
modules include ElementTree for XML processing (:mod:`xml.etree`),
the SQLite database module (:mod:`sqlite`), and the :mod:`ctypes`
module for calling C functions.
The language changes are of middling significance. Some pleasant new features
were added, but most of them aren't features that you'll use every day.
Conditional expressions were finally added to the language using a novel syntax;
see section :ref:`pep-308`. The new ':keyword:`with`' statement will make
writing cleanup code easier (section :ref:`pep-343`). Values can now be passed
into generators (section :ref:`pep-342`). Imports are now visible as either
absolute or relative (section :ref:`pep-328`). Some corner cases of exception
handling are handled better (section :ref:`pep-341`). All these improvements
are worthwhile, but they're improvements to one specific language feature or
another; none of them are broad modifications to Python's semantics.
As well as the language and library additions, other improvements and bugfixes
were made throughout the source tree. A search through the SVN change logs
finds there were 353 patches applied and 458 bugs fixed between Python 2.4 and
2.5. (Both figures are likely to be underestimates.)
This article doesn't try to be a complete specification of the new features;
instead changes are briefly introduced using helpful examples. For full
details, you should always refer to the documentation for Python 2.5 at
https://docs.python.org. If you want to understand the complete implementation
and design rationale, refer to the PEP for a particular new feature.
Comments, suggestions, and error reports for this document are welcome; please
e-mail them to the author or open a bug in the Python bug tracker.
.. ======================================================================
.. _pep-308:
PEP 308: Conditional Expressions
================================
For a long time, people have been requesting a way to write conditional
expressions, which are expressions that return value A or value B depending on
whether a Boolean value is true or false. A conditional expression lets you
write a single assignment statement that has the same effect as the following::
if condition:
x = true_value
else:
x = false_value
There have been endless tedious discussions of syntax on both python-dev and
comp.lang.python. A vote was even held that found the majority of voters wanted
conditional expressions in some form, but there was no syntax that was preferred
by a clear majority. Candidates included C's ``cond ? true_v : false_v``, ``if
cond then true_v else false_v``, and 16 other variations.
Guido van Rossum eventually chose a surprising syntax::
x = true_value if condition else false_value
Evaluation is still lazy as in existing Boolean expressions, so the order of
evaluation jumps around a bit. The *condition* expression in the middle is
evaluated first, and the *true_value* expression is evaluated only if the
condition was true. Similarly, the *false_value* expression is only evaluated
when the condition is false.
This syntax may seem strange and backwards; why does the condition go in the
*middle* of the expression, and not in the front as in C's ``c ? x : y``? The
decision was checked by applying the new syntax to the modules in the standard
library and seeing how the resulting code read. In many cases where a
conditional expression is used, one value seems to be the 'common case' and one
value is an 'exceptional case', used only on rarer occasions when the condition
isn't met. The conditional syntax makes this pattern a bit more obvious::
contents = ((doc + '\n') if doc else '')
I read the above statement as meaning "here *contents* is usually assigned a
value of ``doc+'\n'``; sometimes *doc* is empty, in which special case an empty
string is returned." I doubt I will use conditional expressions very often
where there isn't a clear common and uncommon case.
There was some discussion of whether the language should require surrounding
conditional expressions with parentheses. The decision was made to *not*
require parentheses in the Python language's grammar, but as a matter of style I
think you should always use them. Consider these two statements::
# First version -- no parens
level = 1 if logging else 0
# Second version -- with parens
level = (1 if logging else 0)
In the first version, I think a reader's eye might group the statement into
'level = 1', 'if logging', 'else 0', and think that the condition decides
whether the assignment to *level* is performed. The second version reads
better, in my opinion, because it makes it clear that the assignment is always
performed and the choice is being made between two values.
Another reason for including the brackets: a few odd combinations of list
comprehensions and lambdas could look like incorrect conditional expressions.
See :pep:`308` for some examples. If you put parentheses around your
conditional expressions, you won't run into this case.
.. seealso::
:pep:`308` - Conditional Expressions
PEP written by Guido van Rossum and Raymond D. Hettinger; implemented by Thomas
Wouters.
.. ======================================================================
.. _pep-309:
PEP 309: Partial Function Application
=====================================
The :mod:`functools` module is intended to contain tools for functional-style
programming.
One useful tool in this module is the :func:`partial` function. For programs
written in a functional style, you'll sometimes want to construct variants of
existing functions that have some of the parameters filled in. Consider a
Python function ``f(a, b, c)``; you could create a new function ``g(b, c)`` that
was equivalent to ``f(1, b, c)``. This is called "partial function
application".
:func:`partial` takes the arguments ``(function, arg1, arg2, ... kwarg1=value1,
kwarg2=value2)``. The resulting object is callable, so you can just call it to
invoke *function* with the filled-in arguments.
Here's a small but realistic example::
import functools
def log (message, subsystem):
"Write the contents of 'message' to the specified subsystem."
print '%s: %s' % (subsystem, message)
...
server_log = functools.partial(log, subsystem='server')
server_log('Unable to open socket')
Here's another example, from a program that uses PyGTK. Here a context-sensitive
pop-up menu is being constructed dynamically. The callback provided
for the menu option is a partially applied version of the :meth:`open_item`
method, where the first argument has been provided. ::
...
class Application:
def open_item(self, path):
...
def init (self):
open_func = functools.partial(self.open_item, item_path)
popup_menu.append( ("Open", open_func, 1) )
Another function in the :mod:`functools` module is the
``update_wrapper(wrapper, wrapped)`` function that helps you write
well-behaved decorators. :func:`update_wrapper` copies the name, module, and
docstring attribute to a wrapper function so that tracebacks inside the wrapped
function are easier to understand. For example, you might write::
def my_decorator(f):
def wrapper(*args, **kwds):
print 'Calling decorated function'
return f(*args, **kwds)
functools.update_wrapper(wrapper, f)
return wrapper
:func:`wraps` is a decorator that can be used inside your own decorators to copy
the wrapped function's information. An alternate version of the previous
example would be::
def my_decorator(f):
@functools.wraps(f)
def wrapper(*args, **kwds):
print 'Calling decorated function'
return f(*args, **kwds)
return wrapper
.. seealso::
:pep:`309` - Partial Function Application
PEP proposed and written by Peter Harris; implemented by Hye-Shik Chang and Nick
Coghlan, with adaptations by Raymond Hettinger.
.. ======================================================================
.. _pep-314:
PEP 314: Metadata for Python Software Packages v1.1
===================================================
Some simple dependency support was added to Distutils. The :func:`setup`
function now has ``requires``, ``provides``, and ``obsoletes`` keyword
parameters. When you build a source distribution using the ``sdist`` command,
the dependency information will be recorded in the :file:`PKG-INFO` file.
Another new keyword parameter is ``download_url``, which should be set to a URL
for the package's source code. This means it's now possible to look up an entry
in the package index, determine the dependencies for a package, and download the
required packages. ::
VERSION = '1.0'
setup(name='PyPackage',
version=VERSION,
requires=['numarray', 'zlib (>=1.1.4)'],
obsoletes=['OldPackage']
download_url=('http://www.example.com/pypackage/dist/pkg-%s.tar.gz'
% VERSION),
)
Another new enhancement to the Python package index at
https://pypi.org is storing source and binary archives for a
package. The new :command:`upload` Distutils command will upload a package to
the repository.
Before a package can be uploaded, you must be able to build a distribution using
the :command:`sdist` Distutils command. Once that works, you can run ``python
setup.py upload`` to add your package to the PyPI archive. Optionally you can
GPG-sign the package by supplying the :option:`!--sign` and :option:`!--identity`
options.
Package uploading was implemented by Martin von Löwis and Richard Jones.
.. seealso::
:pep:`314` - Metadata for Python Software Packages v1.1
PEP proposed and written by A.M. Kuchling, Richard Jones, and Fred Drake;
implemented by Richard Jones and Fred Drake.
.. ======================================================================
.. _pep-328:
PEP 328: Absolute and Relative Imports
======================================
The simpler part of PEP 328 was implemented in Python 2.4: parentheses could now
be used to enclose the names imported from a module using the ``from ... import
...`` statement, making it easier to import many different names.
The more complicated part has been implemented in Python 2.5: importing a module
can be specified to use absolute or package-relative imports. The plan is to
move toward making absolute imports the default in future versions of Python.
Let's say you have a package directory like this::
pkg/
pkg/__init__.py
pkg/main.py
pkg/string.py
This defines a package named :mod:`pkg` containing the :mod:`pkg.main` and
:mod:`pkg.string` submodules.
Consider the code in the :file:`main.py` module. What happens if it executes
the statement ``import string``? In Python 2.4 and earlier, it will first look
in the package's directory to perform a relative import, finds
:file:`pkg/string.py`, imports the contents of that file as the
:mod:`pkg.string` module, and that module is bound to the name ``string`` in the
:mod:`pkg.main` module's namespace.
That's fine if :mod:`pkg.string` was what you wanted. But what if you wanted
Python's standard :mod:`string` module? There's no clean way to ignore
:mod:`pkg.string` and look for the standard module; generally you had to look at
the contents of ``sys.modules``, which is slightly unclean. Holger Krekel's
:mod:`py.std` package provides a tidier way to perform imports from the standard
library, ``import py; py.std.string.join()``, but that package isn't available
on all Python installations.
Reading code which relies on relative imports is also less clear, because a
reader may be confused about which module, :mod:`string` or :mod:`pkg.string`,
is intended to be used. Python users soon learned not to duplicate the names of
standard library modules in the names of their packages' submodules, but you
can't protect against having your submodule's name being used for a new module
added in a future version of Python.
In Python 2.5, you can switch :keyword:`import`'s behaviour to absolute imports
using a ``from __future__ import absolute_import`` directive. This absolute-import
behaviour will become the default in a future version (probably Python
2.7). Once absolute imports are the default, ``import string`` will always
find the standard library's version. It's suggested that users should begin
using absolute imports as much as possible, so it's preferable to begin writing
``from pkg import string`` in your code.
Relative imports are still possible by adding a leading period to the module
name when using the ``from ... import`` form::
# Import names from pkg.string
from .string import name1, name2
# Import pkg.string
from . import string
This imports the :mod:`string` module relative to the current package, so in
:mod:`pkg.main` this will import *name1* and *name2* from :mod:`pkg.string`.
Additional leading periods perform the relative import starting from the parent
of the current package. For example, code in the :mod:`A.B.C` module can do::
from . import D # Imports A.B.D
from .. import E # Imports A.E
from ..F import G # Imports A.F.G
Leading periods cannot be used with the ``import modname`` form of the import
statement, only the ``from ... import`` form.
.. seealso::
:pep:`328` - Imports: Multi-Line and Absolute/Relative
PEP written by Aahz; implemented by Thomas Wouters.
https://pylib.readthedocs.org/
The py library by Holger Krekel, which contains the :mod:`py.std` package.
.. ======================================================================
.. _pep-338:
PEP 338: Executing Modules as Scripts
=====================================
The :option:`-m` switch added in Python 2.4 to execute a module as a script
gained a few more abilities. Instead of being implemented in C code inside the
Python interpreter, the switch now uses an implementation in a new module,
:mod:`runpy`.
The :mod:`runpy` module implements a more sophisticated import mechanism so that
it's now possible to run modules in a package such as :mod:`pychecker.checker`.
The module also supports alternative import mechanisms such as the
:mod:`zipimport` module. This means you can add a .zip archive's path to
``sys.path`` and then use the :option:`-m` switch to execute code from the
archive.
.. seealso::
:pep:`338` - Executing modules as scripts
PEP written and implemented by Nick Coghlan.
.. ======================================================================
.. _pep-341:
PEP 341: Unified try/except/finally
===================================
Until Python 2.5, the :keyword:`try` statement came in two flavours. You could
use a :keyword:`finally` block to ensure that code is always executed, or one or
more :keyword:`except` blocks to catch specific exceptions. You couldn't
combine both :keyword:`except` blocks and a :keyword:`finally` block, because
generating the right bytecode for the combined version was complicated and it
wasn't clear what the semantics of the combined statement should be.
Guido van Rossum spent some time working with Java, which does support the
equivalent of combining :keyword:`except` blocks and a :keyword:`finally` block,
and this clarified what the statement should mean. In Python 2.5, you can now
write::
try:
block-1 ...
except Exception1:
handler-1 ...
except Exception2:
handler-2 ...
else:
else-block
finally:
final-block
The code in *block-1* is executed. If the code raises an exception, the various
:keyword:`except` blocks are tested: if the exception is of class
:class:`Exception1`, *handler-1* is executed; otherwise if it's of class
:class:`Exception2`, *handler-2* is executed, and so forth. If no exception is
raised, the *else-block* is executed.
No matter what happened previously, the *final-block* is executed once the code
block is complete and any raised exceptions handled. Even if there's an error in
an exception handler or the *else-block* and a new exception is raised, the code
in the *final-block* is still run.
.. seealso::
:pep:`341` - Unifying try-except and try-finally
PEP written by Georg Brandl; implementation by Thomas Lee.
.. ======================================================================
.. _pep-342:
PEP 342: New Generator Features
===============================
Python 2.5 adds a simple way to pass values *into* a generator. As introduced in
Python 2.3, generators only produce output; once a generator's code was invoked
to create an iterator, there was no way to pass any new information into the
function when its execution is resumed. Sometimes the ability to pass in some
information would be useful. Hackish solutions to this include making the
generator's code look at a global variable and then changing the global
variable's value, or passing in some mutable object that callers then modify.
To refresh your memory of basic generators, here's a simple example::
def counter (maximum):
i = 0
while i < maximum:
yield i
i += 1
When you call ``counter(10)``, the result is an iterator that returns the values
from 0 up to 9. On encountering the :keyword:`yield` statement, the iterator
returns the provided value and suspends the function's execution, preserving the
local variables. Execution resumes on the following call to the iterator's
:meth:`next` method, picking up after the :keyword:`yield` statement.
In Python 2.3, :keyword:`yield` was a statement; it didn't return any value. In
2.5, :keyword:`yield` is now an expression, returning a value that can be
assigned to a variable or otherwise operated on::
val = (yield i)
I recommend that you always put parentheses around a :keyword:`yield` expression
when you're doing something with the returned value, as in the above example.
The parentheses aren't always necessary, but it's easier to always add them
instead of having to remember when they're needed.
(:pep:`342` explains the exact rules, which are that a :keyword:`yield`\
-expression must always be parenthesized except when it occurs at the top-level
expression on the right-hand side of an assignment. This means you can write
``val = yield i`` but have to use parentheses when there's an operation, as in
``val = (yield i) + 12``.)
Values are sent into a generator by calling its ``send(value)`` method. The
generator's code is then resumed and the :keyword:`yield` expression returns the
specified *value*. If the regular :meth:`next` method is called, the
:keyword:`yield` returns :const:`None`.
Here's the previous example, modified to allow changing the value of the
internal counter. ::
def counter (maximum):
i = 0
while i < maximum:
val = (yield i)
# If value provided, change counter
if val is not None:
i = val
else:
i += 1
And here's an example of changing the counter::
>>> it = counter(10)
>>> print it.next()
0
>>> print it.next()
1
>>> print it.send(8)
8
>>> print it.next()
9
>>> print it.next()
Traceback (most recent call last):
File "t.py", line 15, in ?
print it.next()
StopIteration
:keyword:`yield` will usually return :const:`None`, so you should always check
for this case. Don't just use its value in expressions unless you're sure that
the :meth:`send` method will be the only method used to resume your generator
function.
In addition to :meth:`send`, there are two other new methods on generators:
* ``throw(type, value=None, traceback=None)`` is used to raise an exception
inside the generator; the exception is raised by the :keyword:`yield` expression
where the generator's execution is paused.
* :meth:`close` raises a new :exc:`GeneratorExit` exception inside the generator
to terminate the iteration. On receiving this exception, the generator's code
must either raise :exc:`GeneratorExit` or :exc:`StopIteration`. Catching the
:exc:`GeneratorExit` exception and returning a value is illegal and will trigger
a :exc:`RuntimeError`; if the function raises some other exception, that
exception is propagated to the caller. :meth:`close` will also be called by
Python's garbage collector when the generator is garbage-collected.
If you need to run cleanup code when a :exc:`GeneratorExit` occurs, I suggest
using a ``try: ... finally:`` suite instead of catching :exc:`GeneratorExit`.
The cumulative effect of these changes is to turn generators from one-way
producers of information into both producers and consumers.
Generators also become *coroutines*, a more generalized form of subroutines.
Subroutines are entered at one point and exited at another point (the top of the
function, and a :keyword:`return` statement), but coroutines can be entered,
exited, and resumed at many different points (the :keyword:`yield` statements).
We'll have to figure out patterns for using coroutines effectively in Python.
The addition of the :meth:`close` method has one side effect that isn't obvious.
:meth:`close` is called when a generator is garbage-collected, so this means the
generator's code gets one last chance to run before the generator is destroyed.
This last chance means that ``try...finally`` statements in generators can now
be guaranteed to work; the :keyword:`finally` clause will now always get a
chance to run. The syntactic restriction that you couldn't mix :keyword:`yield`
statements with a ``try...finally`` suite has therefore been removed. This
seems like a minor bit of language trivia, but using generators and
``try...finally`` is actually necessary in order to implement the
:keyword:`with` statement described by PEP 343. I'll look at this new statement
in the following section.
Another even more esoteric effect of this change: previously, the
:attr:`gi_frame` attribute of a generator was always a frame object. It's now
possible for :attr:`gi_frame` to be ``None`` once the generator has been
exhausted.
.. seealso::
:pep:`342` - Coroutines via Enhanced Generators
PEP written by Guido van Rossum and Phillip J. Eby; implemented by Phillip J.
Eby. Includes examples of some fancier uses of generators as coroutines.
Earlier versions of these features were proposed in :pep:`288` by Raymond
Hettinger and :pep:`325` by Samuele Pedroni.
https://en.wikipedia.org/wiki/Coroutine
The Wikipedia entry for coroutines.
http://www.sidhe.org/~dan/blog/archives/000178.html
An explanation of coroutines from a Perl point of view, written by Dan Sugalski.
.. ======================================================================
.. _pep-343:
PEP 343: The 'with' statement
=============================
The ':keyword:`with`' statement clarifies code that previously would use
``try...finally`` blocks to ensure that clean-up code is executed. In this
section, I'll discuss the statement as it will commonly be used. In the next
section, I'll examine the implementation details and show how to write objects
for use with this statement.
The ':keyword:`with`' statement is a new control-flow structure whose basic
structure is::
with expression [as variable]:
with-block
The expression is evaluated, and it should result in an object that supports the
context management protocol (that is, has :meth:`__enter__` and :meth:`__exit__`
methods.
The object's :meth:`__enter__` is called before *with-block* is executed and
therefore can run set-up code. It also may return a value that is bound to the
name *variable*, if given. (Note carefully that *variable* is *not* assigned
the result of *expression*.)
After execution of the *with-block* is finished, the object's :meth:`__exit__`
method is called, even if the block raised an exception, and can therefore run
clean-up code.
To enable the statement in Python 2.5, you need to add the following directive
to your module::
from __future__ import with_statement
The statement will always be enabled in Python 2.6.
Some standard Python objects now support the context management protocol and can
be used with the ':keyword:`with`' statement. File objects are one example::
with open('/etc/passwd', 'r') as f:
for line in f:
print line
... more processing code ...
After this statement has executed, the file object in *f* will have been
automatically closed, even if the :keyword:`for` loop raised an exception
part-way through the block.
.. note::
In this case, *f* is the same object created by :func:`open`, because
:meth:`file.__enter__` returns *self*.
The :mod:`threading` module's locks and condition variables also support the
':keyword:`with`' statement::
lock = threading.Lock()
with lock:
# Critical section of code
...
The lock is acquired before the block is executed and always released once the
block is complete.
The new :func:`localcontext` function in the :mod:`decimal` module makes it easy
to save and restore the current decimal context, which encapsulates the desired
precision and rounding characteristics for computations::
from decimal import Decimal, Context, localcontext
# Displays with default precision of 28 digits
v = Decimal('578')
print v.sqrt()
with localcontext(Context(prec=16)):
# All code in this block uses a precision of 16 digits.
# The original context is restored on exiting the block.
print v.sqrt()
.. _new-25-context-managers:
Writing Context Managers
------------------------
Under the hood, the ':keyword:`with`' statement is fairly complicated. Most
people will only use ':keyword:`with`' in company with existing objects and
don't need to know these details, so you can skip the rest of this section if
you like. Authors of new objects will need to understand the details of the
underlying implementation and should keep reading.
A high-level explanation of the context management protocol is:
* The expression is evaluated and should result in an object called a "context
manager". The context manager must have :meth:`__enter__` and :meth:`__exit__`
methods.
* The context manager's :meth:`__enter__` method is called. The value returned
is assigned to *VAR*. If no ``'as VAR'`` clause is present, the value is simply
discarded.
* The code in *BLOCK* is executed.
* If *BLOCK* raises an exception, the ``__exit__(type, value, traceback)``
is called with the exception details, the same values returned by
:func:`sys.exc_info`. The method's return value controls whether the exception
is re-raised: any false value re-raises the exception, and ``True`` will result
in suppressing it. You'll only rarely want to suppress the exception, because
if you do the author of the code containing the ':keyword:`with`' statement will
never realize anything went wrong.
* If *BLOCK* didn't raise an exception, the :meth:`__exit__` method is still
called, but *type*, *value*, and *traceback* are all ``None``.
Let's think through an example. I won't present detailed code but will only
sketch the methods necessary for a database that supports transactions.
(For people unfamiliar with database terminology: a set of changes to the
database are grouped into a transaction. Transactions can be either committed,
meaning that all the changes are written into the database, or rolled back,
meaning that the changes are all discarded and the database is unchanged. See
any database textbook for more information.)
Let's assume there's an object representing a database connection. Our goal will
be to let the user write code like this::
db_connection = DatabaseConnection()
with db_connection as cursor:
cursor.execute('insert into ...')
cursor.execute('delete from ...')
# ... more operations ...
The transaction should be committed if the code in the block runs flawlessly or
rolled back if there's an exception. Here's the basic interface for
:class:`DatabaseConnection` that I'll assume::
class DatabaseConnection:
# Database interface
def cursor (self):
"Returns a cursor object and starts a new transaction"
def commit (self):
"Commits current transaction"
def rollback (self):
"Rolls back current transaction"
The :meth:`__enter__` method is pretty easy, having only to start a new
transaction. For this application the resulting cursor object would be a useful
result, so the method will return it. The user can then add ``as cursor`` to
their ':keyword:`with`' statement to bind the cursor to a variable name. ::
class DatabaseConnection:
...
def __enter__ (self):
# Code to start a new transaction
cursor = self.cursor()
return cursor
The :meth:`__exit__` method is the most complicated because it's where most of
the work has to be done. The method has to check if an exception occurred. If
there was no exception, the transaction is committed. The transaction is rolled
back if there was an exception.
In the code below, execution will just fall off the end of the function,
returning the default value of ``None``. ``None`` is false, so the exception
will be re-raised automatically. If you wished, you could be more explicit and
add a :keyword:`return` statement at the marked location. ::
class DatabaseConnection:
...
def __exit__ (self, type, value, tb):
if tb is None:
# No exception, so commit
self.commit()
else:
# Exception occurred, so rollback.
self.rollback()
# return False
.. _contextlibmod:
The contextlib module
---------------------
The new :mod:`contextlib` module provides some functions and a decorator that
are useful for writing objects for use with the ':keyword:`with`' statement.
The decorator is called :func:`contextmanager`, and lets you write a single
generator function instead of defining a new class. The generator should yield
exactly one value. The code up to the :keyword:`yield` will be executed as the
:meth:`__enter__` method, and the value yielded will be the method's return
value that will get bound to the variable in the ':keyword:`with`' statement's
:keyword:`as` clause, if any. The code after the :keyword:`yield` will be
executed in the :meth:`__exit__` method. Any exception raised in the block will
be raised by the :keyword:`yield` statement.
Our database example from the previous section could be written using this
decorator as::
from contextlib import contextmanager
@contextmanager
def db_transaction (connection):
cursor = connection.cursor()
try:
yield cursor
except:
connection.rollback()
raise
else:
connection.commit()
db = DatabaseConnection()
with db_transaction(db) as cursor:
...
The :mod:`contextlib` module also has a ``nested(mgr1, mgr2, ...)`` function
that combines a number of context managers so you don't need to write nested
':keyword:`with`' statements. In this example, the single ':keyword:`with`'
statement both starts a database transaction and acquires a thread lock::
lock = threading.Lock()
with nested (db_transaction(db), lock) as (cursor, locked):
...
Finally, the ``closing(object)`` function returns *object* so that it can be
bound to a variable, and calls ``object.close`` at the end of the block. ::
import urllib, sys
from contextlib import closing
with closing(urllib.urlopen('http://www.yahoo.com')) as f:
for line in f:
sys.stdout.write(line)
.. seealso::
:pep:`343` - The "with" statement
PEP written by Guido van Rossum and Nick Coghlan; implemented by Mike Bland,
Guido van Rossum, and Neal Norwitz. The PEP shows the code generated for a
':keyword:`with`' statement, which can be helpful in learning how the statement
works.
The documentation for the :mod:`contextlib` module.
.. ======================================================================
.. _pep-352:
PEP 352: Exceptions as New-Style Classes
========================================
Exception classes can now be new-style classes, not just classic classes, and
the built-in :exc:`Exception` class and all the standard built-in exceptions
(:exc:`NameError`, :exc:`ValueError`, etc.) are now new-style classes.
The inheritance hierarchy for exceptions has been rearranged a bit. In 2.5, the
inheritance relationships are::
BaseException # New in Python 2.5
|- KeyboardInterrupt
|- SystemExit
|- Exception
|- (all other current built-in exceptions)
This rearrangement was done because people often want to catch all exceptions
that indicate program errors. :exc:`KeyboardInterrupt` and :exc:`SystemExit`
aren't errors, though, and usually represent an explicit action such as the user
hitting :kbd:`Control-C` or code calling :func:`sys.exit`. A bare ``except:`` will
catch all exceptions, so you commonly need to list :exc:`KeyboardInterrupt` and
:exc:`SystemExit` in order to re-raise them. The usual pattern is::
try:
...
except (KeyboardInterrupt, SystemExit):
raise
except:
# Log error...
# Continue running program...
In Python 2.5, you can now write ``except Exception`` to achieve the same
result, catching all the exceptions that usually indicate errors but leaving
:exc:`KeyboardInterrupt` and :exc:`SystemExit` alone. As in previous versions,
a bare ``except:`` still catches all exceptions.
The goal for Python 3.0 is to require any class raised as an exception to derive
from :exc:`BaseException` or some descendant of :exc:`BaseException`, and future
releases in the Python 2.x series may begin to enforce this constraint.
Therefore, I suggest you begin making all your exception classes derive from
:exc:`Exception` now. It's been suggested that the bare ``except:`` form should
be removed in Python 3.0, but Guido van Rossum hasn't decided whether to do this
or not.
Raising of strings as exceptions, as in the statement ``raise "Error
occurred"``, is deprecated in Python 2.5 and will trigger a warning. The aim is
to be able to remove the string-exception feature in a few releases.
.. seealso::
:pep:`352` - Required Superclass for Exceptions
PEP written by Brett Cannon and Guido van Rossum; implemented by Brett Cannon.
.. ======================================================================
.. _pep-353:
PEP 353: Using ssize_t as the index type
========================================
A wide-ranging change to Python's C API, using a new :c:type:`Py_ssize_t` type
definition instead of :c:type:`int`, will permit the interpreter to handle more
data on 64-bit platforms. This change doesn't affect Python's capacity on 32-bit
platforms.
Various pieces of the Python interpreter used C's :c:type:`int` type to store
sizes or counts; for example, the number of items in a list or tuple were stored
in an :c:type:`int`. The C compilers for most 64-bit platforms still define
:c:type:`int` as a 32-bit type, so that meant that lists could only hold up to
``2**31 - 1`` = 2147483647 items. (There are actually a few different
programming models that 64-bit C compilers can use -- see
http://www.unix.org/version2/whatsnew/lp64_wp.html for a discussion -- but the
most commonly available model leaves :c:type:`int` as 32 bits.)
A limit of 2147483647 items doesn't really matter on a 32-bit platform because
you'll run out of memory before hitting the length limit. Each list item
requires space for a pointer, which is 4 bytes, plus space for a
:c:type:`PyObject` representing the item. 2147483647\*4 is already more bytes
than a 32-bit address space can contain.
It's possible to address that much memory on a 64-bit platform, however. The
pointers for a list that size would only require 16 GiB of space, so it's not
unreasonable that Python programmers might construct lists that large.
Therefore, the Python interpreter had to be changed to use some type other than
:c:type:`int`, and this will be a 64-bit type on 64-bit platforms. The change
will cause incompatibilities on 64-bit machines, so it was deemed worth making
the transition now, while the number of 64-bit users is still relatively small.
(In 5 or 10 years, we may *all* be on 64-bit machines, and the transition would
be more painful then.)
This change most strongly affects authors of C extension modules. Python
strings and container types such as lists and tuples now use
:c:type:`Py_ssize_t` to store their size. Functions such as
:c:func:`PyList_Size` now return :c:type:`Py_ssize_t`. Code in extension modules
may therefore need to have some variables changed to :c:type:`Py_ssize_t`.
The :c:func:`PyArg_ParseTuple` and :c:func:`Py_BuildValue` functions have a new
conversion code, ``n``, for :c:type:`Py_ssize_t`. :c:func:`PyArg_ParseTuple`'s
``s#`` and ``t#`` still output :c:type:`int` by default, but you can define the
macro :c:macro:`PY_SSIZE_T_CLEAN` before including :file:`Python.h` to make
them return :c:type:`Py_ssize_t`.
:pep:`353` has a section on conversion guidelines that extension authors should
read to learn about supporting 64-bit platforms.
.. seealso::
:pep:`353` - Using ssize_t as the index type
PEP written and implemented by Martin von Löwis.
.. ======================================================================
.. _pep-357:
PEP 357: The '__index__' method
===============================
The NumPy developers had a problem that could only be solved by adding a new
special method, :meth:`__index__`. When using slice notation, as in
``[start:stop:step]``, the values of the *start*, *stop*, and *step* indexes
must all be either integers or long integers. NumPy defines a variety of
specialized integer types corresponding to unsigned and signed integers of 8,
16, 32, and 64 bits, but there was no way to signal that these types could be
used as slice indexes.
Slicing can't just use the existing :meth:`__int__` method because that method
is also used to implement coercion to integers. If slicing used
:meth:`__int__`, floating-point numbers would also become legal slice indexes
and that's clearly an undesirable behaviour.
Instead, a new special method called :meth:`__index__` was added. It takes no
arguments and returns an integer giving the slice index to use. For example::
class C:
def __index__ (self):
return self.value
The return value must be either a Python integer or long integer. The
interpreter will check that the type returned is correct, and raises a
:exc:`TypeError` if this requirement isn't met.
A corresponding :attr:`nb_index` slot was added to the C-level
:c:type:`PyNumberMethods` structure to let C extensions implement this protocol.
``PyNumber_Index(obj)`` can be used in extension code to call the
:meth:`__index__` function and retrieve its result.
.. seealso::
:pep:`357` - Allowing Any Object to be Used for Slicing
PEP written and implemented by Travis Oliphant.
.. ======================================================================
.. _other-lang:
Other Language Changes
======================
Here are all of the changes that Python 2.5 makes to the core Python language.
* The :class:`dict` type has a new hook for letting subclasses provide a default
value when a key isn't contained in the dictionary. When a key isn't found, the
dictionary's ``__missing__(key)`` method will be called. This hook is used
to implement the new :class:`defaultdict` class in the :mod:`collections`
module. The following example defines a dictionary that returns zero for any
missing key::
class zerodict (dict):
def __missing__ (self, key):
return 0
d = zerodict({1:1, 2:2})
print d[1], d[2] # Prints 1, 2
print d[3], d[4] # Prints 0, 0
* Both 8-bit and Unicode strings have new ``partition(sep)`` and
``rpartition(sep)`` methods that simplify a common use case.
The ``find(S)`` method is often used to get an index which is then used to
slice the string and obtain the pieces that are before and after the separator.
``partition(sep)`` condenses this pattern into a single method call that
returns a 3-tuple containing the substring before the separator, the separator
itself, and the substring after the separator. If the separator isn't found,
the first element of the tuple is the entire string and the other two elements
are empty. ``rpartition(sep)`` also returns a 3-tuple but starts searching
from the end of the string; the ``r`` stands for 'reverse'.
Some examples::
>>> ('http://www.python.org').partition('://')
('http', '://', 'www.python.org')
>>> ('file:/usr/share/doc/index.html').partition('://')
('file:/usr/share/doc/index.html', '', '')
>>> (u'Subject: a quick question').partition(':')
(u'Subject', u':', u' a quick question')
>>> 'www.python.org'.rpartition('.')
('www.python', '.', 'org')
>>> 'www.python.org'.rpartition(':')
('', '', 'www.python.org')
(Implemented by Fredrik Lundh following a suggestion by Raymond Hettinger.)
* The :meth:`startswith` and :meth:`endswith` methods of string types now accept
tuples of strings to check for. ::
def is_image_file (filename):
return filename.endswith(('.gif', '.jpg', '.tiff'))
(Implemented by Georg Brandl following a suggestion by Tom Lynn.)
.. RFE #1491485
* The :func:`min` and :func:`max` built-in functions gained a ``key`` keyword
parameter analogous to the ``key`` argument for :meth:`sort`. This parameter
supplies a function that takes a single argument and is called for every value
in the list; :func:`min`/:func:`max` will return the element with the
smallest/largest return value from this function. For example, to find the
longest string in a list, you can do::
L = ['medium', 'longest', 'short']
# Prints 'longest'
print max(L, key=len)
# Prints 'short', because lexicographically 'short' has the largest value
print max(L)
(Contributed by Steven Bethard and Raymond Hettinger.)
* Two new built-in functions, :func:`any` and :func:`all`, evaluate whether an
iterator contains any true or false values. :func:`any` returns :const:`True`
if any value returned by the iterator is true; otherwise it will return
:const:`False`. :func:`all` returns :const:`True` only if all of the values
returned by the iterator evaluate as true. (Suggested by Guido van Rossum, and
implemented by Raymond Hettinger.)
* The result of a class's :meth:`__hash__` method can now be either a long
integer or a regular integer. If a long integer is returned, the hash of that
value is taken. In earlier versions the hash value was required to be a
regular integer, but in 2.5 the :func:`id` built-in was changed to always
return non-negative numbers, and users often seem to use ``id(self)`` in
:meth:`__hash__` methods (though this is discouraged).
.. Bug #1536021
* ASCII is now the default encoding for modules. It's now a syntax error if a
module contains string literals with 8-bit characters but doesn't have an
encoding declaration. In Python 2.4 this triggered a warning, not a syntax
error. See :pep:`263` for how to declare a module's encoding; for example, you
might add a line like this near the top of the source file::
# -*- coding: latin1 -*-
* A new warning, :class:`UnicodeWarning`, is triggered when you attempt to
compare a Unicode string and an 8-bit string that can't be converted to Unicode
using the default ASCII encoding. The result of the comparison is false::
>>> chr(128) == unichr(128) # Can't convert chr(128) to Unicode
__main__:1: UnicodeWarning: Unicode equal comparison failed
to convert both arguments to Unicode - interpreting them
as being unequal
False
>>> chr(127) == unichr(127) # chr(127) can be converted
True
Previously this would raise a :class:`UnicodeDecodeError` exception, but in 2.5
this could result in puzzling problems when accessing a dictionary. If you
looked up ``unichr(128)`` and ``chr(128)`` was being used as a key, you'd get a
:class:`UnicodeDecodeError` exception. Other changes in 2.5 resulted in this
exception being raised instead of suppressed by the code in :file:`dictobject.c`
that implements dictionaries.
Raising an exception for such a comparison is strictly correct, but the change
might have broken code, so instead :class:`UnicodeWarning` was introduced.
(Implemented by Marc-André Lemburg.)
* One error that Python programmers sometimes make is forgetting to include an
:file:`__init__.py` module in a package directory. Debugging this mistake can be
confusing, and usually requires running Python with the :option:`-v` switch to
log all the paths searched. In Python 2.5, a new :exc:`ImportWarning` warning is
triggered when an import would have picked up a directory as a package but no
:file:`__init__.py` was found. This warning is silently ignored by default;
provide the :option:`-Wd <-W>` option when running the Python executable to display
the warning message. (Implemented by Thomas Wouters.)
* The list of base classes in a class definition can now be empty. As an
example, this is now legal::
class C():
pass
(Implemented by Brett Cannon.)
.. ======================================================================
.. _25interactive:
Interactive Interpreter Changes
-------------------------------
In the interactive interpreter, ``quit`` and ``exit`` have long been strings so
that new users get a somewhat helpful message when they try to quit::
>>> quit
'Use Ctrl-D (i.e. EOF) to exit.'
In Python 2.5, ``quit`` and ``exit`` are now objects that still produce string
representations of themselves, but are also callable. Newbies who try ``quit()``
or ``exit()`` will now exit the interpreter as they expect. (Implemented by
Georg Brandl.)
The Python executable now accepts the standard long options :option:`--help`
and :option:`--version`; on Windows, it also accepts the :option:`/? <-?>` option
for displaying a help message. (Implemented by Georg Brandl.)
.. ======================================================================
.. _opts:
Optimizations
-------------
Several of the optimizations were developed at the NeedForSpeed sprint, an event
held in Reykjavik, Iceland, from May 21--28 2006. The sprint focused on speed
enhancements to the CPython implementation and was funded by EWT LLC with local
support from CCP Games. Those optimizations added at this sprint are specially
marked in the following list.
* When they were introduced in Python 2.4, the built-in :class:`set` and
:class:`frozenset` types were built on top of Python's dictionary type. In 2.5
the internal data structure has been customized for implementing sets, and as a
result sets will use a third less memory and are somewhat faster. (Implemented
by Raymond Hettinger.)
* The speed of some Unicode operations, such as finding substrings, string
splitting, and character map encoding and decoding, has been improved.
(Substring search and splitting improvements were added by Fredrik Lundh and
Andrew Dalke at the NeedForSpeed sprint. Character maps were improved by Walter
Dörwald and Martin von Löwis.)
.. Patch 1313939, 1359618
* The ``long(str, base)`` function is now faster on long digit strings
because fewer intermediate results are calculated. The peak is for strings of
around 800--1000 digits where the function is 6 times faster. (Contributed by
Alan McIntyre and committed at the NeedForSpeed sprint.)
.. Patch 1442927
* It's now illegal to mix iterating over a file with ``for line in file`` and
calling the file object's :meth:`read`/:meth:`readline`/:meth:`readlines`
methods. Iteration uses an internal buffer and the :meth:`read\*` methods
don't use that buffer. Instead they would return the data following the
buffer, causing the data to appear out of order. Mixing iteration and these
methods will now trigger a :exc:`ValueError` from the :meth:`read\*` method.
(Implemented by Thomas Wouters.)
.. Patch 1397960
* The :mod:`struct` module now compiles structure format strings into an
internal representation and caches this representation, yielding a 20% speedup.
(Contributed by Bob Ippolito at the NeedForSpeed sprint.)
* The :mod:`re` module got a 1 or 2% speedup by switching to Python's allocator
functions instead of the system's :c:func:`malloc` and :c:func:`free`.
(Contributed by Jack Diederich at the NeedForSpeed sprint.)
* The code generator's peephole optimizer now performs simple constant folding
in expressions. If you write something like ``a = 2+3``, the code generator
will do the arithmetic and produce code corresponding to ``a = 5``. (Proposed
and implemented by Raymond Hettinger.)
* Function calls are now faster because code objects now keep the most recently
finished frame (a "zombie frame") in an internal field of the code object,
reusing it the next time the code object is invoked. (Original patch by Michael
Hudson, modified by Armin Rigo and Richard Jones; committed at the NeedForSpeed
sprint.) Frame objects are also slightly smaller, which may improve cache
locality and reduce memory usage a bit. (Contributed by Neal Norwitz.)
.. Patch 876206
.. Patch 1337051
* Python's built-in exceptions are now new-style classes, a change that speeds
up instantiation considerably. Exception handling in Python 2.5 is therefore
about 30% faster than in 2.4. (Contributed by Richard Jones, Georg Brandl and
Sean Reifschneider at the NeedForSpeed sprint.)
* Importing now caches the paths tried, recording whether they exist or not so
that the interpreter makes fewer :c:func:`open` and :c:func:`stat` calls on
startup. (Contributed by Martin von Löwis and Georg Brandl.)
.. Patch 921466
.. ======================================================================
.. _25modules:
New, Improved, and Removed Modules
==================================
The standard library received many enhancements and bug fixes in Python 2.5.
Here's a partial list of the most notable changes, sorted alphabetically by
module name. Consult the :file:`Misc/NEWS` file in the source tree for a more
complete list of changes, or look through the SVN logs for all the details.
* The :mod:`audioop` module now supports the a-LAW encoding, and the code for
u-LAW encoding has been improved. (Contributed by Lars Immisch.)
* The :mod:`codecs` module gained support for incremental codecs. The
:func:`codec.lookup` function now returns a :class:`CodecInfo` instance instead
of a tuple. :class:`CodecInfo` instances behave like a 4-tuple to preserve
backward compatibility but also have the attributes :attr:`encode`,
:attr:`decode`, :attr:`incrementalencoder`, :attr:`incrementaldecoder`,
:attr:`streamwriter`, and :attr:`streamreader`. Incremental codecs can receive
input and produce output in multiple chunks; the output is the same as if the
entire input was fed to the non-incremental codec. See the :mod:`codecs` module
documentation for details. (Designed and implemented by Walter Dörwald.)
.. Patch 1436130
* The :mod:`collections` module gained a new type, :class:`defaultdict`, that
subclasses the standard :class:`dict` type. The new type mostly behaves like a
dictionary but constructs a default value when a key isn't present,
automatically adding it to the dictionary for the requested key value.
The first argument to :class:`defaultdict`'s constructor is a factory function
that gets called whenever a key is requested but not found. This factory
function receives no arguments, so you can use built-in type constructors such
as :func:`list` or :func:`int`. For example, you can make an index of words
based on their initial letter like this::
words = """Nel mezzo del cammin di nostra vita
mi ritrovai per una selva oscura
che la diritta via era smarrita""".lower().split()
index = defaultdict(list)
for w in words:
init_letter = w[0]
index[init_letter].append(w)
Printing ``index`` results in the following output::
defaultdict(<type 'list'>, {'c': ['cammin', 'che'], 'e': ['era'],
'd': ['del', 'di', 'diritta'], 'm': ['mezzo', 'mi'],
'l': ['la'], 'o': ['oscura'], 'n': ['nel', 'nostra'],
'p': ['per'], 's': ['selva', 'smarrita'],
'r': ['ritrovai'], 'u': ['una'], 'v': ['vita', 'via']}
(Contributed by Guido van Rossum.)
* The :class:`deque` double-ended queue type supplied by the :mod:`collections`
module now has a ``remove(value)`` method that removes the first occurrence
of *value* in the queue, raising :exc:`ValueError` if the value isn't found.
(Contributed by Raymond Hettinger.)
* New module: The :mod:`contextlib` module contains helper functions for use
with the new ':keyword:`with`' statement. See section :ref:`contextlibmod`
for more about this module.
* New module: The :mod:`cProfile` module is a C implementation of the existing
:mod:`profile` module that has much lower overhead. The module's interface is
the same as :mod:`profile`: you run ``cProfile.run('main()')`` to profile a
function, can save profile data to a file, etc. It's not yet known if the
Hotshot profiler, which is also written in C but doesn't match the
:mod:`profile` module's interface, will continue to be maintained in future
versions of Python. (Contributed by Armin Rigo.)
Also, the :mod:`pstats` module for analyzing the data measured by the profiler
now supports directing the output to any file object by supplying a *stream*
argument to the :class:`Stats` constructor. (Contributed by Skip Montanaro.)
* The :mod:`csv` module, which parses files in comma-separated value format,
received several enhancements and a number of bugfixes. You can now set the
maximum size in bytes of a field by calling the
``csv.field_size_limit(new_limit)`` function; omitting the *new_limit*
argument will return the currently-set limit. The :class:`reader` class now has
a :attr:`line_num` attribute that counts the number of physical lines read from
the source; records can span multiple physical lines, so :attr:`line_num` is not
the same as the number of records read.
The CSV parser is now stricter about multi-line quoted fields. Previously, if a
line ended within a quoted field without a terminating newline character, a
newline would be inserted into the returned field. This behavior caused problems
when reading files that contained carriage return characters within fields, so
the code was changed to return the field without inserting newlines. As a
consequence, if newlines embedded within fields are important, the input should
be split into lines in a manner that preserves the newline characters.
(Contributed by Skip Montanaro and Andrew McNamara.)
* The :class:`~datetime.datetime` class in the :mod:`datetime` module now has a
``strptime(string, format)`` method for parsing date strings, contributed
by Josh Spoerri. It uses the same format characters as :func:`time.strptime` and
:func:`time.strftime`::
from datetime import datetime
ts = datetime.strptime('10:13:15 2006-03-07',
'%H:%M:%S %Y-%m-%d')
* The :meth:`SequenceMatcher.get_matching_blocks` method in the :mod:`difflib`
module now guarantees to return a minimal list of blocks describing matching
subsequences. Previously, the algorithm would occasionally break a block of
matching elements into two list entries. (Enhancement by Tim Peters.)
* The :mod:`doctest` module gained a ``SKIP`` option that keeps an example from
being executed at all. This is intended for code snippets that are usage
examples intended for the reader and aren't actually test cases.
An *encoding* parameter was added to the :func:`testfile` function and the
:class:`DocFileSuite` class to specify the file's encoding. This makes it
easier to use non-ASCII characters in tests contained within a docstring.
(Contributed by Bjorn Tillenius.)
.. Patch 1080727
* The :mod:`email` package has been updated to version 4.0. (Contributed by
Barry Warsaw.)
.. XXX need to provide some more detail here
.. index::
single: universal newlines; What's new
* The :mod:`fileinput` module was made more flexible. Unicode filenames are now
supported, and a *mode* parameter that defaults to ``"r"`` was added to the
:func:`input` function to allow opening files in binary or :term:`universal
newlines` mode. Another new parameter, *openhook*, lets you use a function
other than :func:`open` to open the input files. Once you're iterating over
the set of files, the :class:`FileInput` object's new :meth:`fileno` returns
the file descriptor for the currently opened file. (Contributed by Georg
Brandl.)
* In the :mod:`gc` module, the new :func:`get_count` function returns a 3-tuple
containing the current collection counts for the three GC generations. This is
accounting information for the garbage collector; when these counts reach a
specified threshold, a garbage collection sweep will be made. The existing
:func:`gc.collect` function now takes an optional *generation* argument of 0, 1,
or 2 to specify which generation to collect. (Contributed by Barry Warsaw.)
* The :func:`nsmallest` and :func:`nlargest` functions in the :mod:`heapq`
module now support a ``key`` keyword parameter similar to the one provided by
the :func:`min`/:func:`max` functions and the :meth:`sort` methods. For
example::
>>> import heapq
>>> L = ["short", 'medium', 'longest', 'longer still']
>>> heapq.nsmallest(2, L) # Return two lowest elements, lexicographically
['longer still', 'longest']
>>> heapq.nsmallest(2, L, key=len) # Return two shortest elements
['short', 'medium']
(Contributed by Raymond Hettinger.)
* The :func:`itertools.islice` function now accepts ``None`` for the start and
step arguments. This makes it more compatible with the attributes of slice
objects, so that you can now write the following::
s = slice(5) # Create slice object
itertools.islice(iterable, s.start, s.stop, s.step)
(Contributed by Raymond Hettinger.)
* The :func:`format` function in the :mod:`locale` module has been modified and
two new functions were added, :func:`format_string` and :func:`currency`.
The :func:`format` function's *val* parameter could previously be a string as
long as no more than one %char specifier appeared; now the parameter must be
exactly one %char specifier with no surrounding text. An optional *monetary*
parameter was also added which, if ``True``, will use the locale's rules for
formatting currency in placing a separator between groups of three digits.
To format strings with multiple %char specifiers, use the new
:func:`format_string` function that works like :func:`format` but also supports
mixing %char specifiers with arbitrary text.
A new :func:`currency` function was also added that formats a number according
to the current locale's settings.
(Contributed by Georg Brandl.)
.. Patch 1180296
* The :mod:`mailbox` module underwent a massive rewrite to add the capability to
modify mailboxes in addition to reading them. A new set of classes that include
:class:`mbox`, :class:`MH`, and :class:`Maildir` are used to read mailboxes, and
have an ``add(message)`` method to add messages, ``remove(key)`` to
remove messages, and :meth:`lock`/:meth:`unlock` to lock/unlock the mailbox.
The following example converts a maildir-format mailbox into an mbox-format
one::
import mailbox
# 'factory=None' uses email.Message.Message as the class representing
# individual messages.
src = mailbox.Maildir('maildir', factory=None)
dest = mailbox.mbox('/tmp/mbox')
for msg in src:
dest.add(msg)
(Contributed by Gregory K. Johnson. Funding was provided by Google's 2005
Summer of Code.)
* New module: the :mod:`msilib` module allows creating Microsoft Installer
:file:`.msi` files and CAB files. Some support for reading the :file:`.msi`
database is also included. (Contributed by Martin von Löwis.)
* The :mod:`nis` module now supports accessing domains other than the system
default domain by supplying a *domain* argument to the :func:`nis.match` and
:func:`nis.maps` functions. (Contributed by Ben Bell.)
* The :mod:`operator` module's :func:`itemgetter` and :func:`attrgetter`
functions now support multiple fields. A call such as
``operator.attrgetter('a', 'b')`` will return a function that retrieves the
:attr:`a` and :attr:`b` attributes. Combining this new feature with the
:meth:`sort` method's ``key`` parameter lets you easily sort lists using
multiple fields. (Contributed by Raymond Hettinger.)
* The :mod:`optparse` module was updated to version 1.5.1 of the Optik library.
The :class:`OptionParser` class gained an :attr:`epilog` attribute, a string
that will be printed after the help message, and a :meth:`destroy` method to
break reference cycles created by the object. (Contributed by Greg Ward.)
* The :mod:`os` module underwent several changes. The :attr:`stat_float_times`
variable now defaults to true, meaning that :func:`os.stat` will now return time
values as floats. (This doesn't necessarily mean that :func:`os.stat` will
return times that are precise to fractions of a second; not all systems support
such precision.)
Constants named :attr:`os.SEEK_SET`, :attr:`os.SEEK_CUR`, and
:attr:`os.SEEK_END` have been added; these are the parameters to the
:func:`os.lseek` function. Two new constants for locking are
:attr:`os.O_SHLOCK` and :attr:`os.O_EXLOCK`.
Two new functions, :func:`wait3` and :func:`wait4`, were added. They're similar
the :func:`waitpid` function which waits for a child process to exit and returns
a tuple of the process ID and its exit status, but :func:`wait3` and
:func:`wait4` return additional information. :func:`wait3` doesn't take a
process ID as input, so it waits for any child process to exit and returns a
3-tuple of *process-id*, *exit-status*, *resource-usage* as returned from the
:func:`resource.getrusage` function. ``wait4(pid)`` does take a process ID.
(Contributed by Chad J. Schroeder.)
On FreeBSD, the :func:`os.stat` function now returns times with nanosecond
resolution, and the returned object now has :attr:`st_gen` and
:attr:`st_birthtime`. The :attr:`st_flags` attribute is also available, if the
platform supports it. (Contributed by Antti Louko and Diego Pettenò.)
.. (Patch 1180695, 1212117)
* The Python debugger provided by the :mod:`pdb` module can now store lists of
commands to execute when a breakpoint is reached and execution stops. Once
breakpoint #1 has been created, enter ``commands 1`` and enter a series of
commands to be executed, finishing the list with ``end``. The command list can
include commands that resume execution, such as ``continue`` or ``next``.
(Contributed by Grégoire Dooms.)
.. Patch 790710
* The :mod:`pickle` and :mod:`cPickle` modules no longer accept a return value
of ``None`` from the :meth:`__reduce__` method; the method must return a tuple
of arguments instead. The ability to return ``None`` was deprecated in Python
2.4, so this completes the removal of the feature.
* The :mod:`pkgutil` module, containing various utility functions for finding
packages, was enhanced to support PEP 302's import hooks and now also works for
packages stored in ZIP-format archives. (Contributed by Phillip J. Eby.)
* The pybench benchmark suite by Marc-André Lemburg is now included in the
:file:`Tools/pybench` directory. The pybench suite is an improvement on the
commonly used :file:`pystone.py` program because pybench provides a more
detailed measurement of the interpreter's speed. It times particular operations
such as function calls, tuple slicing, method lookups, and numeric operations,
instead of performing many different operations and reducing the result to a
single number as :file:`pystone.py` does.
* The :mod:`pyexpat` module now uses version 2.0 of the Expat parser.
(Contributed by Trent Mick.)
* The :class:`~Queue.Queue` class provided by the :mod:`Queue` module gained two new
methods. :meth:`join` blocks until all items in the queue have been retrieved
and all processing work on the items have been completed. Worker threads call
the other new method, :meth:`task_done`, to signal that processing for an item
has been completed. (Contributed by Raymond Hettinger.)
* The old :mod:`regex` and :mod:`regsub` modules, which have been deprecated
ever since Python 2.0, have finally been deleted. Other deleted modules:
:mod:`statcache`, :mod:`tzparse`, :mod:`whrandom`.
* Also deleted: the :file:`lib-old` directory, which includes ancient modules
such as :mod:`dircmp` and :mod:`ni`, was removed. :file:`lib-old` wasn't on the
default ``sys.path``, so unless your programs explicitly added the directory to
``sys.path``, this removal shouldn't affect your code.
* The :mod:`rlcompleter` module is no longer dependent on importing the
:mod:`readline` module and therefore now works on non-Unix platforms. (Patch
from Robert Kiendl.)
.. Patch #1472854
* The :mod:`SimpleXMLRPCServer` and :mod:`DocXMLRPCServer` classes now have a
:attr:`rpc_paths` attribute that constrains XML-RPC operations to a limited set
of URL paths; the default is to allow only ``'/'`` and ``'/RPC2'``. Setting
:attr:`rpc_paths` to ``None`` or an empty tuple disables this path checking.
.. Bug #1473048
* The :mod:`socket` module now supports :const:`AF_NETLINK` sockets on Linux,
thanks to a patch from Philippe Biondi. Netlink sockets are a Linux-specific
mechanism for communications between a user-space process and kernel code; an
introductory article about them is at https://www.linuxjournal.com/article/7356.
In Python code, netlink addresses are represented as a tuple of 2 integers,
``(pid, group_mask)``.
Two new methods on socket objects, ``recv_into(buffer)`` and
``recvfrom_into(buffer)``, store the received data in an object that
supports the buffer protocol instead of returning the data as a string. This
means you can put the data directly into an array or a memory-mapped file.
Socket objects also gained :meth:`getfamily`, :meth:`gettype`, and
:meth:`getproto` accessor methods to retrieve the family, type, and protocol
values for the socket.
* New module: the :mod:`spwd` module provides functions for accessing the shadow
password database on systems that support shadow passwords.
* The :mod:`struct` is now faster because it compiles format strings into
:class:`Struct` objects with :meth:`pack` and :meth:`unpack` methods. This is
similar to how the :mod:`re` module lets you create compiled regular expression
objects. You can still use the module-level :func:`pack` and :func:`unpack`
functions; they'll create :class:`Struct` objects and cache them. Or you can
use :class:`Struct` instances directly::
s = struct.Struct('ih3s')
data = s.pack(1972, 187, 'abc')
year, number, name = s.unpack(data)
You can also pack and unpack data to and from buffer objects directly using the
``pack_into(buffer, offset, v1, v2, ...)`` and ``unpack_from(buffer,
offset)`` methods. This lets you store data directly into an array or a
memory-mapped file.
(:class:`Struct` objects were implemented by Bob Ippolito at the NeedForSpeed
sprint. Support for buffer objects was added by Martin Blais, also at the
NeedForSpeed sprint.)
* The Python developers switched from CVS to Subversion during the 2.5
development process. Information about the exact build version is available as
the ``sys.subversion`` variable, a 3-tuple of ``(interpreter-name, branch-name,
revision-range)``. For example, at the time of writing my copy of 2.5 was
reporting ``('CPython', 'trunk', '45313:45315')``.
This information is also available to C extensions via the
:c:func:`Py_GetBuildInfo` function that returns a string of build information
like this: ``"trunk:45355:45356M, Apr 13 2006, 07:42:19"``. (Contributed by
Barry Warsaw.)
* Another new function, :func:`sys._current_frames`, returns the current stack
frames for all running threads as a dictionary mapping thread identifiers to the
topmost stack frame currently active in that thread at the time the function is
called. (Contributed by Tim Peters.)
* The :class:`TarFile` class in the :mod:`tarfile` module now has an
:meth:`extractall` method that extracts all members from the archive into the
current working directory. It's also possible to set a different directory as
the extraction target, and to unpack only a subset of the archive's members.
The compression used for a tarfile opened in stream mode can now be autodetected
using the mode ``'r|*'``. (Contributed by Lars Gustäbel.)
.. patch 918101
* The :mod:`threading` module now lets you set the stack size used when new
threads are created. The ``stack_size([*size*])`` function returns the
currently configured stack size, and supplying the optional *size* parameter
sets a new value. Not all platforms support changing the stack size, but
Windows, POSIX threading, and OS/2 all do. (Contributed by Andrew MacIntyre.)
.. Patch 1454481
* The :mod:`unicodedata` module has been updated to use version 4.1.0 of the
Unicode character database. Version 3.2.0 is required by some specifications,
so it's still available as :attr:`unicodedata.ucd_3_2_0`.
* New module: the :mod:`uuid` module generates universally unique identifiers
(UUIDs) according to :rfc:`4122`. The RFC defines several different UUID
versions that are generated from a starting string, from system properties, or
purely randomly. This module contains a :class:`UUID` class and functions
named :func:`uuid1`, :func:`uuid3`, :func:`uuid4`, and :func:`uuid5` to
generate different versions of UUID. (Version 2 UUIDs are not specified in
:rfc:`4122` and are not supported by this module.) ::
>>> import uuid
>>> # make a UUID based on the host ID and current time
>>> uuid.uuid1()
UUID('a8098c1a-f86e-11da-bd1a-00112444be1e')
>>> # make a UUID using an MD5 hash of a namespace UUID and a name
>>> uuid.uuid3(uuid.NAMESPACE_DNS, 'python.org')
UUID('6fa459ea-ee8a-3ca4-894e-db77e160355e')
>>> # make a random UUID
>>> uuid.uuid4()
UUID('16fd2706-8baf-433b-82eb-8c7fada847da')
>>> # make a UUID using a SHA-1 hash of a namespace UUID and a name
>>> uuid.uuid5(uuid.NAMESPACE_DNS, 'python.org')
UUID('886313e1-3b8a-5372-9b90-0c9aee199e5d')
(Contributed by Ka-Ping Yee.)
* The :mod:`weakref` module's :class:`WeakKeyDictionary` and
:class:`WeakValueDictionary` types gained new methods for iterating over the
weak references contained in the dictionary. :meth:`iterkeyrefs` and
:meth:`keyrefs` methods were added to :class:`WeakKeyDictionary`, and
:meth:`itervaluerefs` and :meth:`valuerefs` were added to
:class:`WeakValueDictionary`. (Contributed by Fred L. Drake, Jr.)
* The :mod:`webbrowser` module received a number of enhancements. It's now
usable as a script with ``python -m webbrowser``, taking a URL as the argument;
there are a number of switches to control the behaviour (:option:`!-n` for a new
browser window, :option:`!-t` for a new tab). New module-level functions,
:func:`open_new` and :func:`open_new_tab`, were added to support this. The
module's :func:`open` function supports an additional feature, an *autoraise*
parameter that signals whether to raise the open window when possible. A number
of additional browsers were added to the supported list such as Firefox, Opera,
Konqueror, and elinks. (Contributed by Oleg Broytmann and Georg Brandl.)
.. Patch #754022
* The :mod:`xmlrpclib` module now supports returning :class:`~datetime.datetime` objects
for the XML-RPC date type. Supply ``use_datetime=True`` to the :func:`loads`
function or the :class:`Unmarshaller` class to enable this feature. (Contributed
by Skip Montanaro.)
.. Patch 1120353
* The :mod:`zipfile` module now supports the ZIP64 version of the format,
meaning that a .zip archive can now be larger than 4 GiB and can contain
individual files larger than 4 GiB. (Contributed by Ronald Oussoren.)
.. Patch 1446489
* The :mod:`zlib` module's :class:`Compress` and :class:`Decompress` objects now
support a :meth:`copy` method that makes a copy of the object's internal state
and returns a new :class:`Compress` or :class:`Decompress` object.
(Contributed by Chris AtLee.)
.. Patch 1435422
.. ======================================================================
.. _module-ctypes:
The ctypes package
------------------
The :mod:`ctypes` package, written by Thomas Heller, has been added to the
standard library. :mod:`ctypes` lets you call arbitrary functions in shared
libraries or DLLs. Long-time users may remember the :mod:`dl` module, which
provides functions for loading shared libraries and calling functions in them.
The :mod:`ctypes` package is much fancier.
To load a shared library or DLL, you must create an instance of the
:class:`CDLL` class and provide the name or path of the shared library or DLL.
Once that's done, you can call arbitrary functions by accessing them as
attributes of the :class:`CDLL` object. ::
import ctypes
libc = ctypes.CDLL('libc.so.6')
result = libc.printf("Line of output\n")
Type constructors for the various C types are provided: :func:`c_int`,
:func:`c_float`, :func:`c_double`, :func:`c_char_p` (equivalent to :c:type:`char
\*`), and so forth. Unlike Python's types, the C versions are all mutable; you
can assign to their :attr:`value` attribute to change the wrapped value. Python
integers and strings will be automatically converted to the corresponding C
types, but for other types you must call the correct type constructor. (And I
mean *must*; getting it wrong will often result in the interpreter crashing
with a segmentation fault.)
You shouldn't use :func:`c_char_p` with a Python string when the C function will
be modifying the memory area, because Python strings are supposed to be
immutable; breaking this rule will cause puzzling bugs. When you need a
modifiable memory area, use :func:`create_string_buffer`::
s = "this is a string"
buf = ctypes.create_string_buffer(s)
libc.strfry(buf)
C functions are assumed to return integers, but you can set the :attr:`restype`
attribute of the function object to change this::
>>> libc.atof('2.71828')
-1783957616
>>> libc.atof.restype = ctypes.c_double
>>> libc.atof('2.71828')
2.71828
:mod:`ctypes` also provides a wrapper for Python's C API as the
``ctypes.pythonapi`` object. This object does *not* release the global
interpreter lock before calling a function, because the lock must be held when
calling into the interpreter's code. There's a :class:`py_object()` type
constructor that will create a :c:type:`PyObject \*` pointer. A simple usage::
import ctypes
d = {}
ctypes.pythonapi.PyObject_SetItem(ctypes.py_object(d),
ctypes.py_object("abc"), ctypes.py_object(1))
# d is now {'abc', 1}.
Don't forget to use :class:`py_object()`; if it's omitted you end up with a
segmentation fault.
:mod:`ctypes` has been around for a while, but people still write and
distribution hand-coded extension modules because you can't rely on
:mod:`ctypes` being present. Perhaps developers will begin to write Python
wrappers atop a library accessed through :mod:`ctypes` instead of extension
modules, now that :mod:`ctypes` is included with core Python.
.. seealso::
http://starship.python.net/crew/theller/ctypes/
The ctypes web page, with a tutorial, reference, and FAQ.
The documentation for the :mod:`ctypes` module.
.. ======================================================================
.. _module-etree:
The ElementTree package
-----------------------
A subset of Fredrik Lundh's ElementTree library for processing XML has been
added to the standard library as :mod:`xml.etree`. The available modules are
:mod:`ElementTree`, :mod:`ElementPath`, and :mod:`ElementInclude` from
ElementTree 1.2.6. The :mod:`cElementTree` accelerator module is also
included.
The rest of this section will provide a brief overview of using ElementTree.
Full documentation for ElementTree is available at
http://effbot.org/zone/element-index.htm.
ElementTree represents an XML document as a tree of element nodes. The text
content of the document is stored as the :attr:`text` and :attr:`tail`
attributes of (This is one of the major differences between ElementTree and
the Document Object Model; in the DOM there are many different types of node,
including :class:`TextNode`.)
The most commonly used parsing function is :func:`parse`, that takes either a
string (assumed to contain a filename) or a file-like object and returns an
:class:`ElementTree` instance::
from xml.etree import ElementTree as ET
tree = ET.parse('ex-1.xml')
feed = urllib.urlopen(
'http://planet.python.org/rss10.xml')
tree = ET.parse(feed)
Once you have an :class:`ElementTree` instance, you can call its :meth:`getroot`
method to get the root :class:`Element` node.
There's also an :func:`XML` function that takes a string literal and returns an
:class:`Element` node (not an :class:`ElementTree`). This function provides a
tidy way to incorporate XML fragments, approaching the convenience of an XML
literal::
svg = ET.XML("""<svg width="10px" version="1.0">
</svg>""")
svg.set('height', '320px')
svg.append(elem1)
Each XML element supports some dictionary-like and some list-like access
methods. Dictionary-like operations are used to access attribute values, and
list-like operations are used to access child nodes.
+-------------------------------+--------------------------------------------+
| Operation | Result |
+===============================+============================================+
| ``elem[n]`` | Returns n'th child element. |
+-------------------------------+--------------------------------------------+
| ``elem[m:n]`` | Returns list of m'th through n'th child |
| | elements. |
+-------------------------------+--------------------------------------------+
| ``len(elem)`` | Returns number of child elements. |
+-------------------------------+--------------------------------------------+
| ``list(elem)`` | Returns list of child elements. |
+-------------------------------+--------------------------------------------+
| ``elem.append(elem2)`` | Adds *elem2* as a child. |
+-------------------------------+--------------------------------------------+
| ``elem.insert(index, elem2)`` | Inserts *elem2* at the specified location. |
+-------------------------------+--------------------------------------------+
| ``del elem[n]`` | Deletes n'th child element. |
+-------------------------------+--------------------------------------------+
| ``elem.keys()`` | Returns list of attribute names. |
+-------------------------------+--------------------------------------------+
| ``elem.get(name)`` | Returns value of attribute *name*. |
+-------------------------------+--------------------------------------------+
| ``elem.set(name, value)`` | Sets new value for attribute *name*. |
+-------------------------------+--------------------------------------------+
| ``elem.attrib`` | Retrieves the dictionary containing |
| | attributes. |
+-------------------------------+--------------------------------------------+
| ``del elem.attrib[name]`` | Deletes attribute *name*. |
+-------------------------------+--------------------------------------------+
Comments and processing instructions are also represented as :class:`Element`
nodes. To check if a node is a comment or processing instructions::
if elem.tag is ET.Comment:
...
elif elem.tag is ET.ProcessingInstruction:
...
To generate XML output, you should call the :meth:`ElementTree.write` method.
Like :func:`parse`, it can take either a string or a file-like object::
# Encoding is US-ASCII
tree.write('output.xml')
# Encoding is UTF-8
f = open('output.xml', 'w')
tree.write(f, encoding='utf-8')
(Caution: the default encoding used for output is ASCII. For general XML work,
where an element's name may contain arbitrary Unicode characters, ASCII isn't a
very useful encoding because it will raise an exception if an element's name
contains any characters with values greater than 127. Therefore, it's best to
specify a different encoding such as UTF-8 that can handle any Unicode
character.)
This section is only a partial description of the ElementTree interfaces. Please
read the package's official documentation for more details.
.. seealso::
http://effbot.org/zone/element-index.htm
Official documentation for ElementTree.
.. ======================================================================
.. _module-hashlib:
The hashlib package
-------------------
A new :mod:`hashlib` module, written by Gregory P. Smith, has been added to
replace the :mod:`md5` and :mod:`sha` modules. :mod:`hashlib` adds support for
additional secure hashes (SHA-224, SHA-256, SHA-384, and SHA-512). When
available, the module uses OpenSSL for fast platform optimized implementations
of algorithms.
The old :mod:`md5` and :mod:`sha` modules still exist as wrappers around hashlib
to preserve backwards compatibility. The new module's interface is very close
to that of the old modules, but not identical. The most significant difference
is that the constructor functions for creating new hashing objects are named
differently. ::
# Old versions
h = md5.md5()
h = md5.new()
# New version
h = hashlib.md5()
# Old versions
h = sha.sha()
h = sha.new()
# New version
h = hashlib.sha1()
# Hash that weren't previously available
h = hashlib.sha224()
h = hashlib.sha256()
h = hashlib.sha384()
h = hashlib.sha512()
# Alternative form
h = hashlib.new('md5') # Provide algorithm as a string
Once a hash object has been created, its methods are the same as before:
``update(string)`` hashes the specified string into the current digest
state, :meth:`digest` and :meth:`hexdigest` return the digest value as a binary
string or a string of hex digits, and :meth:`copy` returns a new hashing object
with the same digest state.
.. seealso::
The documentation for the :mod:`hashlib` module.
.. ======================================================================
.. _module-sqlite:
The sqlite3 package
-------------------
The pysqlite module (http://www.pysqlite.org), a wrapper for the SQLite embedded
database, has been added to the standard library under the package name
:mod:`sqlite3`.
SQLite is a C library that provides a lightweight disk-based database that
doesn't require a separate server process and allows accessing the database
using a nonstandard variant of the SQL query language. Some applications can use
SQLite for internal data storage. It's also possible to prototype an
application using SQLite and then port the code to a larger database such as
PostgreSQL or Oracle.
pysqlite was written by Gerhard Häring and provides a SQL interface compliant
with the DB-API 2.0 specification described by :pep:`249`.
If you're compiling the Python source yourself, note that the source tree
doesn't include the SQLite code, only the wrapper module. You'll need to have
the SQLite libraries and headers installed before compiling Python, and the
build process will compile the module when the necessary headers are available.
To use the module, you must first create a :class:`Connection` object that
represents the database. Here the data will be stored in the
:file:`/tmp/example` file::
conn = sqlite3.connect('/tmp/example')
You can also supply the special name ``:memory:`` to create a database in RAM.
Once you have a :class:`Connection`, you can create a :class:`Cursor` object
and call its :meth:`execute` method to perform SQL commands::
c = conn.cursor()
# Create table
c.execute('''create table stocks
(date text, trans text, symbol text,
qty real, price real)''')
# Insert a row of data
c.execute("""insert into stocks
values ('2006-01-05','BUY','RHAT',100,35.14)""")
Usually your SQL operations will need to use values from Python variables. You
shouldn't assemble your query using Python's string operations because doing so
is insecure; it makes your program vulnerable to an SQL injection attack.
Instead, use the DB-API's parameter substitution. Put ``?`` as a placeholder
wherever you want to use a value, and then provide a tuple of values as the
second argument to the cursor's :meth:`execute` method. (Other database modules
may use a different placeholder, such as ``%s`` or ``:1``.) For example::
# Never do this -- insecure!
symbol = 'IBM'
c.execute("... where symbol = '%s'" % symbol)
# Do this instead
t = (symbol,)
c.execute('select * from stocks where symbol=?', t)
# Larger example
for t in (('2006-03-28', 'BUY', 'IBM', 1000, 45.00),
('2006-04-05', 'BUY', 'MSOFT', 1000, 72.00),
('2006-04-06', 'SELL', 'IBM', 500, 53.00),
):
c.execute('insert into stocks values (?,?,?,?,?)', t)
To retrieve data after executing a SELECT statement, you can either treat the
cursor as an iterator, call the cursor's :meth:`fetchone` method to retrieve a
single matching row, or call :meth:`fetchall` to get a list of the matching
rows.
This example uses the iterator form::
>>> c = conn.cursor()
>>> c.execute('select * from stocks order by price')
>>> for row in c:
... print row
...
(u'2006-01-05', u'BUY', u'RHAT', 100, 35.140000000000001)
(u'2006-03-28', u'BUY', u'IBM', 1000, 45.0)
(u'2006-04-06', u'SELL', u'IBM', 500, 53.0)
(u'2006-04-05', u'BUY', u'MSOFT', 1000, 72.0)
>>>
For more information about the SQL dialect supported by SQLite, see
https://www.sqlite.org.
.. seealso::
http://www.pysqlite.org
The pysqlite web page.
https://www.sqlite.org
The SQLite web page; the documentation describes the syntax and the available
data types for the supported SQL dialect.
The documentation for the :mod:`sqlite3` module.
:pep:`249` - Database API Specification 2.0
PEP written by Marc-André Lemburg.
.. ======================================================================
.. _module-wsgiref:
The wsgiref package
-------------------
The Web Server Gateway Interface (WSGI) v1.0 defines a standard interface
between web servers and Python web applications and is described in :pep:`333`.
The :mod:`wsgiref` package is a reference implementation of the WSGI
specification.
.. XXX should this be in a PEP 333 section instead?
The package includes a basic HTTP server that will run a WSGI application; this
server is useful for debugging but isn't intended for production use. Setting
up a server takes only a few lines of code::
from wsgiref import simple_server
wsgi_app = ...
host = ''
port = 8000
httpd = simple_server.make_server(host, port, wsgi_app)
httpd.serve_forever()
.. XXX discuss structure of WSGI applications?
.. XXX provide an example using Django or some other framework?
.. seealso::
http://www.wsgi.org
A central web site for WSGI-related resources.
:pep:`333` - Python Web Server Gateway Interface v1.0
PEP written by Phillip J. Eby.
.. ======================================================================
.. _build-api:
Build and C API Changes
=======================
Changes to Python's build process and to the C API include:
* The Python source tree was converted from CVS to Subversion, in a complex
migration procedure that was supervised and flawlessly carried out by Martin von
Löwis. The procedure was developed as :pep:`347`.
* Coverity, a company that markets a source code analysis tool called Prevent,
provided the results of their examination of the Python source code. The
analysis found about 60 bugs that were quickly fixed. Many of the bugs were
refcounting problems, often occurring in error-handling code. See
https://scan.coverity.com for the statistics.
* The largest change to the C API came from :pep:`353`, which modifies the
interpreter to use a :c:type:`Py_ssize_t` type definition instead of
:c:type:`int`. See the earlier section :ref:`pep-353` for a discussion of this
change.
* The design of the bytecode compiler has changed a great deal, no longer
generating bytecode by traversing the parse tree. Instead the parse tree is
converted to an abstract syntax tree (or AST), and it is the abstract syntax
tree that's traversed to produce the bytecode.
It's possible for Python code to obtain AST objects by using the
:func:`compile` built-in and specifying ``_ast.PyCF_ONLY_AST`` as the value of
the *flags* parameter::
from _ast import PyCF_ONLY_AST
ast = compile("""a=0
for i in range(10):
a += i
""", "<string>", 'exec', PyCF_ONLY_AST)
assignment = ast.body[0]
for_loop = ast.body[1]
No official documentation has been written for the AST code yet, but :pep:`339`
discusses the design. To start learning about the code, read the definition of
the various AST nodes in :file:`Parser/Python.asdl`. A Python script reads this
file and generates a set of C structure definitions in
:file:`Include/Python-ast.h`. The :c:func:`PyParser_ASTFromString` and
:c:func:`PyParser_ASTFromFile`, defined in :file:`Include/pythonrun.h`, take
Python source as input and return the root of an AST representing the contents.
This AST can then be turned into a code object by :c:func:`PyAST_Compile`. For
more information, read the source code, and then ask questions on python-dev.
The AST code was developed under Jeremy Hylton's management, and implemented by
(in alphabetical order) Brett Cannon, Nick Coghlan, Grant Edwards, John
Ehresman, Kurt Kaiser, Neal Norwitz, Tim Peters, Armin Rigo, and Neil
Schemenauer, plus the participants in a number of AST sprints at conferences
such as PyCon.
.. List of names taken from Jeremy's python-dev post at
.. https://mail.python.org/pipermail/python-dev/2005-October/057500.html
* Evan Jones's patch to obmalloc, first described in a talk at PyCon DC 2005,
was applied. Python 2.4 allocated small objects in 256K-sized arenas, but never
freed arenas. With this patch, Python will free arenas when they're empty. The
net effect is that on some platforms, when you allocate many objects, Python's
memory usage may actually drop when you delete them and the memory may be
returned to the operating system. (Implemented by Evan Jones, and reworked by
Tim Peters.)
Note that this change means extension modules must be more careful when
allocating memory. Python's API has many different functions for allocating
memory that are grouped into families. For example, :c:func:`PyMem_Malloc`,
:c:func:`PyMem_Realloc`, and :c:func:`PyMem_Free` are one family that allocates
raw memory, while :c:func:`PyObject_Malloc`, :c:func:`PyObject_Realloc`, and
:c:func:`PyObject_Free` are another family that's supposed to be used for
creating Python objects.
Previously these different families all reduced to the platform's
:c:func:`malloc` and :c:func:`free` functions. This meant it didn't matter if
you got things wrong and allocated memory with the :c:func:`PyMem` function but
freed it with the :c:func:`PyObject` function. With 2.5's changes to obmalloc,
these families now do different things and mismatches will probably result in a
segfault. You should carefully test your C extension modules with Python 2.5.
* The built-in set types now have an official C API. Call :c:func:`PySet_New`
and :c:func:`PyFrozenSet_New` to create a new set, :c:func:`PySet_Add` and
:c:func:`PySet_Discard` to add and remove elements, and :c:func:`PySet_Contains`
and :c:func:`PySet_Size` to examine the set's state. (Contributed by Raymond
Hettinger.)
* C code can now obtain information about the exact revision of the Python
interpreter by calling the :c:func:`Py_GetBuildInfo` function that returns a
string of build information like this: ``"trunk:45355:45356M, Apr 13 2006,
07:42:19"``. (Contributed by Barry Warsaw.)
* Two new macros can be used to indicate C functions that are local to the
current file so that a faster calling convention can be used.
``Py_LOCAL(type)`` declares the function as returning a value of the
specified *type* and uses a fast-calling qualifier.
``Py_LOCAL_INLINE(type)`` does the same thing and also requests the
function be inlined. If :c:func:`PY_LOCAL_AGGRESSIVE` is defined before
:file:`python.h` is included, a set of more aggressive optimizations are enabled
for the module; you should benchmark the results to find out if these
optimizations actually make the code faster. (Contributed by Fredrik Lundh at
the NeedForSpeed sprint.)
* ``PyErr_NewException(name, base, dict)`` can now accept a tuple of base
classes as its *base* argument. (Contributed by Georg Brandl.)
* The :c:func:`PyErr_Warn` function for issuing warnings is now deprecated in
favour of ``PyErr_WarnEx(category, message, stacklevel)`` which lets you
specify the number of stack frames separating this function and the caller. A
*stacklevel* of 1 is the function calling :c:func:`PyErr_WarnEx`, 2 is the
function above that, and so forth. (Added by Neal Norwitz.)
* The CPython interpreter is still written in C, but the code can now be
compiled with a C++ compiler without errors. (Implemented by Anthony Baxter,
Martin von Löwis, Skip Montanaro.)
* The :c:func:`PyRange_New` function was removed. It was never documented, never
used in the core code, and had dangerously lax error checking. In the unlikely
case that your extensions were using it, you can replace it by something like
the following::
range = PyObject_CallFunction((PyObject*) &PyRange_Type, "lll",
start, stop, step);
.. ======================================================================
.. _ports:
Port-Specific Changes
---------------------
* MacOS X (10.3 and higher): dynamic loading of modules now uses the
:c:func:`dlopen` function instead of MacOS-specific functions.
* MacOS X: an :option:`!--enable-universalsdk` switch was added to the
:program:`configure` script that compiles the interpreter as a universal binary
able to run on both PowerPC and Intel processors. (Contributed by Ronald
Oussoren; :issue:`2573`.)
* Windows: :file:`.dll` is no longer supported as a filename extension for
extension modules. :file:`.pyd` is now the only filename extension that will be
searched for.
.. ======================================================================
.. _porting:
Porting to Python 2.5
=====================
This section lists previously described changes that may require changes to your
code:
* ASCII is now the default encoding for modules. It's now a syntax error if a
module contains string literals with 8-bit characters but doesn't have an
encoding declaration. In Python 2.4 this triggered a warning, not a syntax
error.
* Previously, the :attr:`gi_frame` attribute of a generator was always a frame
object. Because of the :pep:`342` changes described in section :ref:`pep-342`,
it's now possible for :attr:`gi_frame` to be ``None``.
* A new warning, :class:`UnicodeWarning`, is triggered when you attempt to
compare a Unicode string and an 8-bit string that can't be converted to Unicode
using the default ASCII encoding. Previously such comparisons would raise a
:class:`UnicodeDecodeError` exception.
* Library: the :mod:`csv` module is now stricter about multi-line quoted fields.
If your files contain newlines embedded within fields, the input should be split
into lines in a manner which preserves the newline characters.
* Library: the :mod:`locale` module's :func:`format` function's would
previously accept any string as long as no more than one %char specifier
appeared. In Python 2.5, the argument must be exactly one %char specifier with
no surrounding text.
* Library: The :mod:`pickle` and :mod:`cPickle` modules no longer accept a
return value of ``None`` from the :meth:`__reduce__` method; the method must
return a tuple of arguments instead. The modules also no longer accept the
deprecated *bin* keyword parameter.
* Library: The :mod:`SimpleXMLRPCServer` and :mod:`DocXMLRPCServer` classes now
have a :attr:`rpc_paths` attribute that constrains XML-RPC operations to a
limited set of URL paths; the default is to allow only ``'/'`` and ``'/RPC2'``.
Setting :attr:`rpc_paths` to ``None`` or an empty tuple disables this path
checking.
* C API: Many functions now use :c:type:`Py_ssize_t` instead of :c:type:`int` to
allow processing more data on 64-bit machines. Extension code may need to make
the same change to avoid warnings and to support 64-bit machines. See the
earlier section :ref:`pep-353` for a discussion of this change.
* C API: The obmalloc changes mean that you must be careful to not mix usage
of the :c:func:`PyMem_\*` and :c:func:`PyObject_\*` families of functions. Memory
allocated with one family's :c:func:`\*_Malloc` must be freed with the
corresponding family's :c:func:`\*_Free` function.
.. ======================================================================
Acknowledgements
================
The author would like to thank the following people for offering suggestions,
corrections and assistance with various drafts of this article: Georg Brandl,
Nick Coghlan, Phillip J. Eby, Lars Gustäbel, Raymond Hettinger, Ralf W.
Grosse-Kunstleve, Kent Johnson, Iain Lowe, Martin von Löwis, Fredrik Lundh, Andrew
McNamara, Skip Montanaro, Gustavo Niemeyer, Paul Prescod, James Pryor, Mike
Rovner, Scott Weikart, Barry Warsaw, Thomas Wouters.
PK
%�\@��y� � " html/_sources/whatsnew/2.6.rst.txtnu �[��� ****************************
What's New in Python 2.6
****************************
.. XXX add trademark info for Apple, Microsoft, SourceForge.
:Author: A.M. Kuchling (amk at amk.ca)
.. $Id$
Rules for maintenance:
* Anyone can add text to this document. Do not spend very much time
on the wording of your changes, because your text will probably
get rewritten to some degree.
* The maintainer will go through Misc/NEWS periodically and add
changes; it's therefore more important to add your changes to
Misc/NEWS than to this file.
* This is not a complete list of every single change; completeness
is the purpose of Misc/NEWS. Some changes I consider too small
or esoteric to include. If such a change is added to the text,
I'll just remove it. (This is another reason you shouldn't spend
too much time on writing your addition.)
* If you want to draw your new text to the attention of the
maintainer, add 'XXX' to the beginning of the paragraph or
section.
* It's OK to just add a fragmentary note about a change. For
example: "XXX Describe the transmogrify() function added to the
socket module." The maintainer will research the change and
write the necessary text.
* You can comment out your additions if you like, but it's not
necessary (especially when a final release is some months away).
* Credit the author of a patch or bugfix. Just the name is
sufficient; the e-mail address isn't necessary.
* It's helpful to add the bug/patch number in a parenthetical comment.
XXX Describe the transmogrify() function added to the socket
module.
(Contributed by P.Y. Developer; :issue:`12345`.)
This saves the maintainer some effort going through the SVN logs
when researching a change.
This article explains the new features in Python 2.6, released on October 1
2008. The release schedule is described in :pep:`361`.
The major theme of Python 2.6 is preparing the migration path to
Python 3.0, a major redesign of the language. Whenever possible,
Python 2.6 incorporates new features and syntax from 3.0 while
remaining compatible with existing code by not removing older features
or syntax. When it's not possible to do that, Python 2.6 tries to do
what it can, adding compatibility functions in a
:mod:`future_builtins` module and a :option:`-3` switch to warn about
usages that will become unsupported in 3.0.
Some significant new packages have been added to the standard library,
such as the :mod:`multiprocessing` and :mod:`json` modules, but
there aren't many new features that aren't related to Python 3.0 in
some way.
Python 2.6 also sees a number of improvements and bugfixes throughout
the source. A search through the change logs finds there were 259
patches applied and 612 bugs fixed between Python 2.5 and 2.6. Both
figures are likely to be underestimates.
This article doesn't attempt to provide a complete specification of
the new features, but instead provides a convenient overview. For
full details, you should refer to the documentation for Python 2.6. If
you want to understand the rationale for the design and
implementation, refer to the PEP for a particular new feature.
Whenever possible, "What's New in Python" links to the bug/patch item
for each change.
.. Compare with previous release in 2 - 3 sentences here.
add hyperlink when the documentation becomes available online.
.. ========================================================================
.. Large, PEP-level features and changes should be described here.
.. ========================================================================
Python 3.0
================
The development cycle for Python versions 2.6 and 3.0 was
synchronized, with the alpha and beta releases for both versions being
made on the same days. The development of 3.0 has influenced many
features in 2.6.
Python 3.0 is a far-ranging redesign of Python that breaks
compatibility with the 2.x series. This means that existing Python
code will need some conversion in order to run on
Python 3.0. However, not all the changes in 3.0 necessarily break
compatibility. In cases where new features won't cause existing code
to break, they've been backported to 2.6 and are described in this
document in the appropriate place. Some of the 3.0-derived features
are:
* A :meth:`__complex__` method for converting objects to a complex number.
* Alternate syntax for catching exceptions: ``except TypeError as exc``.
* The addition of :func:`functools.reduce` as a synonym for the built-in
:func:`reduce` function.
Python 3.0 adds several new built-in functions and changes the
semantics of some existing builtins. Functions that are new in 3.0
such as :func:`bin` have simply been added to Python 2.6, but existing
builtins haven't been changed; instead, the :mod:`future_builtins`
module has versions with the new 3.0 semantics. Code written to be
compatible with 3.0 can do ``from future_builtins import hex, map`` as
necessary.
A new command-line switch, :option:`-3`, enables warnings
about features that will be removed in Python 3.0. You can run code
with this switch to see how much work will be necessary to port
code to 3.0. The value of this switch is available
to Python code as the boolean variable :data:`sys.py3kwarning`,
and to C extension code as :c:data:`Py_Py3kWarningFlag`.
.. seealso::
The 3xxx series of PEPs, which contains proposals for Python 3.0.
:pep:`3000` describes the development process for Python 3.0.
Start with :pep:`3100` that describes the general goals for Python
3.0, and then explore the higher-numbered PEPS that propose
specific features.
Changes to the Development Process
==================================================
While 2.6 was being developed, the Python development process
underwent two significant changes: we switched from SourceForge's
issue tracker to a customized Roundup installation, and the
documentation was converted from LaTeX to reStructuredText.
New Issue Tracker: Roundup
--------------------------------------------------
For a long time, the Python developers had been growing increasingly
annoyed by SourceForge's bug tracker. SourceForge's hosted solution
doesn't permit much customization; for example, it wasn't possible to
customize the life cycle of issues.
The infrastructure committee of the Python Software Foundation
therefore posted a call for issue trackers, asking volunteers to set
up different products and import some of the bugs and patches from
SourceForge. Four different trackers were examined: `Jira
<https://www.atlassian.com/software/jira/>`__,
`Launchpad <https://launchpad.net/>`__,
`Roundup <http://roundup.sourceforge.net/>`__, and
`Trac <https://trac.edgewall.org/>`__.
The committee eventually settled on Jira
and Roundup as the two candidates. Jira is a commercial product that
offers no-cost hosted instances to free-software projects; Roundup
is an open-source project that requires volunteers
to administer it and a server to host it.
After posting a call for volunteers, a new Roundup installation was
set up at https://bugs.python.org. One installation of Roundup can
host multiple trackers, and this server now also hosts issue trackers
for Jython and for the Python web site. It will surely find
other uses in the future. Where possible,
this edition of "What's New in Python" links to the bug/patch
item for each change.
Hosting of the Python bug tracker is kindly provided by
`Upfront Systems <http://www.upfrontsystems.co.za/>`__
of Stellenbosch, South Africa. Martin von Loewis put a
lot of effort into importing existing bugs and patches from
SourceForge; his scripts for this import operation are at
http://svn.python.org/view/tracker/importer/ and may be useful to
other projects wishing to move from SourceForge to Roundup.
.. seealso::
https://bugs.python.org
The Python bug tracker.
http://bugs.jython.org:
The Jython bug tracker.
http://roundup.sourceforge.net/
Roundup downloads and documentation.
http://svn.python.org/view/tracker/importer/
Martin von Loewis's conversion scripts.
New Documentation Format: reStructuredText Using Sphinx
-----------------------------------------------------------
The Python documentation was written using LaTeX since the project
started around 1989. In the 1980s and early 1990s, most documentation
was printed out for later study, not viewed online. LaTeX was widely
used because it provided attractive printed output while remaining
straightforward to write once the basic rules of the markup were
learned.
Today LaTeX is still used for writing publications destined for
printing, but the landscape for programming tools has shifted. We no
longer print out reams of documentation; instead, we browse through it
online and HTML has become the most important format to support.
Unfortunately, converting LaTeX to HTML is fairly complicated and Fred
L. Drake Jr., the long-time Python documentation editor, spent a lot
of time maintaining the conversion process. Occasionally people would
suggest converting the documentation into SGML and later XML, but
performing a good conversion is a major task and no one ever committed
the time required to finish the job.
During the 2.6 development cycle, Georg Brandl put a lot of effort
into building a new toolchain for processing the documentation. The
resulting package is called Sphinx, and is available from
http://sphinx-doc.org/.
Sphinx concentrates on HTML output, producing attractively styled and
modern HTML; printed output is still supported through conversion to
LaTeX. The input format is reStructuredText, a markup syntax
supporting custom extensions and directives that is commonly used in
the Python community.
Sphinx is a standalone package that can be used for writing, and
almost two dozen other projects
(`listed on the Sphinx web site <http://sphinx-doc.org/examples.html>`__)
have adopted Sphinx as their documentation tool.
.. seealso::
`Documenting Python <https://docs.python.org/devguide/documenting.html>`__
Describes how to write for Python's documentation.
`Sphinx <http://sphinx-doc.org/>`__
Documentation and code for the Sphinx toolchain.
`Docutils <http://docutils.sourceforge.net>`__
The underlying reStructuredText parser and toolset.
PEP 343: The 'with' statement
=============================
The previous version, Python 2.5, added the ':keyword:`with`'
statement as an optional feature, to be enabled by a ``from __future__
import with_statement`` directive. In 2.6 the statement no longer needs to
be specially enabled; this means that :keyword:`with` is now always a
keyword. The rest of this section is a copy of the corresponding
section from the "What's New in Python 2.5" document; if you're
familiar with the ':keyword:`with`' statement
from Python 2.5, you can skip this section.
The ':keyword:`with`' statement clarifies code that previously would use
``try...finally`` blocks to ensure that clean-up code is executed. In this
section, I'll discuss the statement as it will commonly be used. In the next
section, I'll examine the implementation details and show how to write objects
for use with this statement.
The ':keyword:`with`' statement is a control-flow structure whose basic
structure is::
with expression [as variable]:
with-block
The expression is evaluated, and it should result in an object that supports the
context management protocol (that is, has :meth:`__enter__` and :meth:`__exit__`
methods).
The object's :meth:`__enter__` is called before *with-block* is executed and
therefore can run set-up code. It also may return a value that is bound to the
name *variable*, if given. (Note carefully that *variable* is *not* assigned
the result of *expression*.)
After execution of the *with-block* is finished, the object's :meth:`__exit__`
method is called, even if the block raised an exception, and can therefore run
clean-up code.
Some standard Python objects now support the context management protocol and can
be used with the ':keyword:`with`' statement. File objects are one example::
with open('/etc/passwd', 'r') as f:
for line in f:
print line
... more processing code ...
After this statement has executed, the file object in *f* will have been
automatically closed, even if the :keyword:`for` loop raised an exception
part-way through the block.
.. note::
In this case, *f* is the same object created by :func:`open`, because
:meth:`file.__enter__` returns *self*.
The :mod:`threading` module's locks and condition variables also support the
':keyword:`with`' statement::
lock = threading.Lock()
with lock:
# Critical section of code
...
The lock is acquired before the block is executed and always released once the
block is complete.
The :func:`localcontext` function in the :mod:`decimal` module makes it easy
to save and restore the current decimal context, which encapsulates the desired
precision and rounding characteristics for computations::
from decimal import Decimal, Context, localcontext
# Displays with default precision of 28 digits
v = Decimal('578')
print v.sqrt()
with localcontext(Context(prec=16)):
# All code in this block uses a precision of 16 digits.
# The original context is restored on exiting the block.
print v.sqrt()
.. _new-26-context-managers:
Writing Context Managers
------------------------
Under the hood, the ':keyword:`with`' statement is fairly complicated. Most
people will only use ':keyword:`with`' in company with existing objects and
don't need to know these details, so you can skip the rest of this section if
you like. Authors of new objects will need to understand the details of the
underlying implementation and should keep reading.
A high-level explanation of the context management protocol is:
* The expression is evaluated and should result in an object called a "context
manager". The context manager must have :meth:`__enter__` and :meth:`__exit__`
methods.
* The context manager's :meth:`__enter__` method is called. The value returned
is assigned to *VAR*. If no ``as VAR`` clause is present, the value is simply
discarded.
* The code in *BLOCK* is executed.
* If *BLOCK* raises an exception, the context manager's :meth:`__exit__` method
is called with three arguments, the exception details (``type, value, traceback``,
the same values returned by :func:`sys.exc_info`, which can also be ``None``
if no exception occurred). The method's return value controls whether an exception
is re-raised: any false value re-raises the exception, and ``True`` will result
in suppressing it. You'll only rarely want to suppress the exception, because
if you do the author of the code containing the ':keyword:`with`' statement will
never realize anything went wrong.
* If *BLOCK* didn't raise an exception, the :meth:`__exit__` method is still
called, but *type*, *value*, and *traceback* are all ``None``.
Let's think through an example. I won't present detailed code but will only
sketch the methods necessary for a database that supports transactions.
(For people unfamiliar with database terminology: a set of changes to the
database are grouped into a transaction. Transactions can be either committed,
meaning that all the changes are written into the database, or rolled back,
meaning that the changes are all discarded and the database is unchanged. See
any database textbook for more information.)
Let's assume there's an object representing a database connection. Our goal will
be to let the user write code like this::
db_connection = DatabaseConnection()
with db_connection as cursor:
cursor.execute('insert into ...')
cursor.execute('delete from ...')
# ... more operations ...
The transaction should be committed if the code in the block runs flawlessly or
rolled back if there's an exception. Here's the basic interface for
:class:`DatabaseConnection` that I'll assume::
class DatabaseConnection:
# Database interface
def cursor(self):
"Returns a cursor object and starts a new transaction"
def commit(self):
"Commits current transaction"
def rollback(self):
"Rolls back current transaction"
The :meth:`__enter__` method is pretty easy, having only to start a new
transaction. For this application the resulting cursor object would be a useful
result, so the method will return it. The user can then add ``as cursor`` to
their ':keyword:`with`' statement to bind the cursor to a variable name. ::
class DatabaseConnection:
...
def __enter__(self):
# Code to start a new transaction
cursor = self.cursor()
return cursor
The :meth:`__exit__` method is the most complicated because it's where most of
the work has to be done. The method has to check if an exception occurred. If
there was no exception, the transaction is committed. The transaction is rolled
back if there was an exception.
In the code below, execution will just fall off the end of the function,
returning the default value of ``None``. ``None`` is false, so the exception
will be re-raised automatically. If you wished, you could be more explicit and
add a :keyword:`return` statement at the marked location. ::
class DatabaseConnection:
...
def __exit__(self, type, value, tb):
if tb is None:
# No exception, so commit
self.commit()
else:
# Exception occurred, so rollback.
self.rollback()
# return False
.. _module-contextlib:
The contextlib module
---------------------
The :mod:`contextlib` module provides some functions and a decorator that
are useful when writing objects for use with the ':keyword:`with`' statement.
The decorator is called :func:`contextmanager`, and lets you write a single
generator function instead of defining a new class. The generator should yield
exactly one value. The code up to the :keyword:`yield` will be executed as the
:meth:`__enter__` method, and the value yielded will be the method's return
value that will get bound to the variable in the ':keyword:`with`' statement's
:keyword:`as` clause, if any. The code after the :keyword:`yield` will be
executed in the :meth:`__exit__` method. Any exception raised in the block will
be raised by the :keyword:`yield` statement.
Using this decorator, our database example from the previous section
could be written as::
from contextlib import contextmanager
@contextmanager
def db_transaction(connection):
cursor = connection.cursor()
try:
yield cursor
except:
connection.rollback()
raise
else:
connection.commit()
db = DatabaseConnection()
with db_transaction(db) as cursor:
...
The :mod:`contextlib` module also has a ``nested(mgr1, mgr2, ...)`` function
that combines a number of context managers so you don't need to write nested
':keyword:`with`' statements. In this example, the single ':keyword:`with`'
statement both starts a database transaction and acquires a thread lock::
lock = threading.Lock()
with nested (db_transaction(db), lock) as (cursor, locked):
...
Finally, the :func:`closing` function returns its argument so that it can be
bound to a variable, and calls the argument's ``.close()`` method at the end
of the block. ::
import urllib, sys
from contextlib import closing
with closing(urllib.urlopen('http://www.yahoo.com')) as f:
for line in f:
sys.stdout.write(line)
.. seealso::
:pep:`343` - The "with" statement
PEP written by Guido van Rossum and Nick Coghlan; implemented by Mike Bland,
Guido van Rossum, and Neal Norwitz. The PEP shows the code generated for a
':keyword:`with`' statement, which can be helpful in learning how the statement
works.
The documentation for the :mod:`contextlib` module.
.. ======================================================================
.. _pep-0366:
PEP 366: Explicit Relative Imports From a Main Module
============================================================
Python's :option:`-m` switch allows running a module as a script.
When you ran a module that was located inside a package, relative
imports didn't work correctly.
The fix for Python 2.6 adds a :attr:`__package__` attribute to
modules. When this attribute is present, relative imports will be
relative to the value of this attribute instead of the
:attr:`__name__` attribute.
PEP 302-style importers can then set :attr:`__package__` as necessary.
The :mod:`runpy` module that implements the :option:`-m` switch now
does this, so relative imports will now work correctly in scripts
running from inside a package.
.. ======================================================================
.. _pep-0370:
PEP 370: Per-user ``site-packages`` Directory
=====================================================
When you run Python, the module search path ``sys.path`` usually
includes a directory whose path ends in ``"site-packages"``. This
directory is intended to hold locally-installed packages available to
all users using a machine or a particular site installation.
Python 2.6 introduces a convention for user-specific site directories.
The directory varies depending on the platform:
* Unix and Mac OS X: :file:`~/.local/`
* Windows: :file:`%APPDATA%/Python`
Within this directory, there will be version-specific subdirectories,
such as :file:`lib/python2.6/site-packages` on Unix/Mac OS and
:file:`Python26/site-packages` on Windows.
If you don't like the default directory, it can be overridden by an
environment variable. :envvar:`PYTHONUSERBASE` sets the root
directory used for all Python versions supporting this feature. On
Windows, the directory for application-specific data can be changed by
setting the :envvar:`APPDATA` environment variable. You can also
modify the :file:`site.py` file for your Python installation.
The feature can be disabled entirely by running Python with the
:option:`-s` option or setting the :envvar:`PYTHONNOUSERSITE`
environment variable.
.. seealso::
:pep:`370` - Per-user ``site-packages`` Directory
PEP written and implemented by Christian Heimes.
.. ======================================================================
.. _pep-0371:
PEP 371: The ``multiprocessing`` Package
=====================================================
The new :mod:`multiprocessing` package lets Python programs create new
processes that will perform a computation and return a result to the
parent. The parent and child processes can communicate using queues
and pipes, synchronize their operations using locks and semaphores,
and can share simple arrays of data.
The :mod:`multiprocessing` module started out as an exact emulation of
the :mod:`threading` module using processes instead of threads. That
goal was discarded along the path to Python 2.6, but the general
approach of the module is still similar. The fundamental class
is the :class:`Process`, which is passed a callable object and
a collection of arguments. The :meth:`start` method
sets the callable running in a subprocess, after which you can call
the :meth:`is_alive` method to check whether the subprocess is still running
and the :meth:`join` method to wait for the process to exit.
Here's a simple example where the subprocess will calculate a
factorial. The function doing the calculation is written strangely so
that it takes significantly longer when the input argument is a
multiple of 4.
::
import time
from multiprocessing import Process, Queue
def factorial(queue, N):
"Compute a factorial."
# If N is a multiple of 4, this function will take much longer.
if (N % 4) == 0:
time.sleep(.05 * N/4)
# Calculate the result
fact = 1L
for i in range(1, N+1):
fact = fact * i
# Put the result on the queue
queue.put(fact)
if __name__ == '__main__':
queue = Queue()
N = 5
p = Process(target=factorial, args=(queue, N))
p.start()
p.join()
result = queue.get()
print 'Factorial', N, '=', result
A :class:`~Queue.Queue` is used to communicate the result of the factorial.
The :class:`~Queue.Queue` object is stored in a global variable.
The child process will use the value of the variable when the child
was created; because it's a :class:`~Queue.Queue`, parent and child can use
the object to communicate. (If the parent were to change the value of
the global variable, the child's value would be unaffected, and vice
versa.)
Two other classes, :class:`Pool` and :class:`Manager`, provide
higher-level interfaces. :class:`Pool` will create a fixed number of
worker processes, and requests can then be distributed to the workers
by calling :meth:`apply` or :meth:`apply_async` to add a single request,
and :meth:`map` or :meth:`map_async` to add a number of
requests. The following code uses a :class:`Pool` to spread requests
across 5 worker processes and retrieve a list of results::
from multiprocessing import Pool
def factorial(N, dictionary):
"Compute a factorial."
...
p = Pool(5)
result = p.map(factorial, range(1, 1000, 10))
for v in result:
print v
This produces the following output::
1
39916800
51090942171709440000
8222838654177922817725562880000000
33452526613163807108170062053440751665152000000000
...
The other high-level interface, the :class:`Manager` class, creates a
separate server process that can hold master copies of Python data
structures. Other processes can then access and modify these data
structures using proxy objects. The following example creates a
shared dictionary by calling the :meth:`dict` method; the worker
processes then insert values into the dictionary. (Locking is not
done for you automatically, which doesn't matter in this example.
:class:`Manager`'s methods also include :meth:`Lock`, :meth:`RLock`,
and :meth:`Semaphore` to create shared locks.)
::
import time
from multiprocessing import Pool, Manager
def factorial(N, dictionary):
"Compute a factorial."
# Calculate the result
fact = 1L
for i in range(1, N+1):
fact = fact * i
# Store result in dictionary
dictionary[N] = fact
if __name__ == '__main__':
p = Pool(5)
mgr = Manager()
d = mgr.dict() # Create shared dictionary
# Run tasks using the pool
for N in range(1, 1000, 10):
p.apply_async(factorial, (N, d))
# Mark pool as closed -- no more tasks can be added.
p.close()
# Wait for tasks to exit
p.join()
# Output results
for k, v in sorted(d.items()):
print k, v
This will produce the output::
1 1
11 39916800
21 51090942171709440000
31 8222838654177922817725562880000000
41 33452526613163807108170062053440751665152000000000
51 15511187532873822802242430164693032110632597200169861120000...
.. seealso::
The documentation for the :mod:`multiprocessing` module.
:pep:`371` - Addition of the multiprocessing package
PEP written by Jesse Noller and Richard Oudkerk;
implemented by Richard Oudkerk and Jesse Noller.
.. ======================================================================
.. _pep-3101:
PEP 3101: Advanced String Formatting
=====================================================
In Python 3.0, the `%` operator is supplemented by a more powerful string
formatting method, :meth:`format`. Support for the :meth:`str.format` method
has been backported to Python 2.6.
In 2.6, both 8-bit and Unicode strings have a `.format()` method that
treats the string as a template and takes the arguments to be formatted.
The formatting template uses curly brackets (`{`, `}`) as special characters::
>>> # Substitute positional argument 0 into the string.
>>> "User ID: {0}".format("root")
'User ID: root'
>>> # Use the named keyword arguments
>>> "User ID: {uid} Last seen: {last_login}".format(
... uid="root",
... last_login = "5 Mar 2008 07:20")
'User ID: root Last seen: 5 Mar 2008 07:20'
Curly brackets can be escaped by doubling them::
>>> "Empty dict: {{}}".format()
"Empty dict: {}"
Field names can be integers indicating positional arguments, such as
``{0}``, ``{1}``, etc. or names of keyword arguments. You can also
supply compound field names that read attributes or access dictionary keys::
>>> import sys
>>> print 'Platform: {0.platform}\nPython version: {0.version}'.format(sys)
Platform: darwin
Python version: 2.6a1+ (trunk:61261M, Mar 5 2008, 20:29:41)
[GCC 4.0.1 (Apple Computer, Inc. build 5367)]'
>>> import mimetypes
>>> 'Content-type: {0[.mp4]}'.format(mimetypes.types_map)
'Content-type: video/mp4'
Note that when using dictionary-style notation such as ``[.mp4]``, you
don't need to put any quotation marks around the string; it will look
up the value using ``.mp4`` as the key. Strings beginning with a
number will be converted to an integer. You can't write more
complicated expressions inside a format string.
So far we've shown how to specify which field to substitute into the
resulting string. The precise formatting used is also controllable by
adding a colon followed by a format specifier. For example::
>>> # Field 0: left justify, pad to 15 characters
>>> # Field 1: right justify, pad to 6 characters
>>> fmt = '{0:15} ${1:>6}'
>>> fmt.format('Registration', 35)
'Registration $ 35'
>>> fmt.format('Tutorial', 50)
'Tutorial $ 50'
>>> fmt.format('Banquet', 125)
'Banquet $ 125'
Format specifiers can reference other fields through nesting::
>>> fmt = '{0:{1}}'
>>> width = 15
>>> fmt.format('Invoice #1234', width)
'Invoice #1234 '
>>> width = 35
>>> fmt.format('Invoice #1234', width)
'Invoice #1234 '
The alignment of a field within the desired width can be specified:
================ ============================================
Character Effect
================ ============================================
< (default) Left-align
> Right-align
^ Center
= (For numeric types only) Pad after the sign.
================ ============================================
Format specifiers can also include a presentation type, which
controls how the value is formatted. For example, floating-point numbers
can be formatted as a general number or in exponential notation::
>>> '{0:g}'.format(3.75)
'3.75'
>>> '{0:e}'.format(3.75)
'3.750000e+00'
A variety of presentation types are available. Consult the 2.6
documentation for a :ref:`complete list <formatstrings>`; here's a sample:
===== ========================================================================
``b`` Binary. Outputs the number in base 2.
``c`` Character. Converts the integer to the corresponding Unicode character
before printing.
``d`` Decimal Integer. Outputs the number in base 10.
``o`` Octal format. Outputs the number in base 8.
``x`` Hex format. Outputs the number in base 16, using lower-case letters for
the digits above 9.
``e`` Exponent notation. Prints the number in scientific notation using the
letter 'e' to indicate the exponent.
``g`` General format. This prints the number as a fixed-point number, unless
the number is too large, in which case it switches to 'e' exponent
notation.
``n`` Number. This is the same as 'g' (for floats) or 'd' (for integers),
except that it uses the current locale setting to insert the appropriate
number separator characters.
``%`` Percentage. Multiplies the number by 100 and displays in fixed ('f')
format, followed by a percent sign.
===== ========================================================================
Classes and types can define a :meth:`__format__` method to control how they're
formatted. It receives a single argument, the format specifier::
def __format__(self, format_spec):
if isinstance(format_spec, unicode):
return unicode(str(self))
else:
return str(self)
There's also a :func:`format` builtin that will format a single
value. It calls the type's :meth:`__format__` method with the
provided specifier::
>>> format(75.6564, '.2f')
'75.66'
.. seealso::
:ref:`formatstrings`
The reference documentation for format fields.
:pep:`3101` - Advanced String Formatting
PEP written by Talin. Implemented by Eric Smith.
.. ======================================================================
.. _pep-3105:
PEP 3105: ``print`` As a Function
=====================================================
The ``print`` statement becomes the :func:`print` function in Python 3.0.
Making :func:`print` a function makes it possible to replace the function
by doing ``def print(...)`` or importing a new function from somewhere else.
Python 2.6 has a ``__future__`` import that removes ``print`` as language
syntax, letting you use the functional form instead. For example::
>>> from __future__ import print_function
>>> print('# of entries', len(dictionary), file=sys.stderr)
The signature of the new function is::
def print(*args, sep=' ', end='\n', file=None)
The parameters are:
* *args*: positional arguments whose values will be printed out.
* *sep*: the separator, which will be printed between arguments.
* *end*: the ending text, which will be printed after all of the
arguments have been output.
* *file*: the file object to which the output will be sent.
.. seealso::
:pep:`3105` - Make print a function
PEP written by Georg Brandl.
.. ======================================================================
.. _pep-3110:
PEP 3110: Exception-Handling Changes
=====================================================
One error that Python programmers occasionally make
is writing the following code::
try:
...
except TypeError, ValueError: # Wrong!
...
The author is probably trying to catch both :exc:`TypeError` and
:exc:`ValueError` exceptions, but this code actually does something
different: it will catch :exc:`TypeError` and bind the resulting
exception object to the local name ``"ValueError"``. The
:exc:`ValueError` exception will not be caught at all. The correct
code specifies a tuple of exceptions::
try:
...
except (TypeError, ValueError):
...
This error happens because the use of the comma here is ambiguous:
does it indicate two different nodes in the parse tree, or a single
node that's a tuple?
Python 3.0 makes this unambiguous by replacing the comma with the word
"as". To catch an exception and store the exception object in the
variable ``exc``, you must write::
try:
...
except TypeError as exc:
...
Python 3.0 will only support the use of "as", and therefore interprets
the first example as catching two different exceptions. Python 2.6
supports both the comma and "as", so existing code will continue to
work. We therefore suggest using "as" when writing new Python code
that will only be executed with 2.6.
.. seealso::
:pep:`3110` - Catching Exceptions in Python 3000
PEP written and implemented by Collin Winter.
.. ======================================================================
.. _pep-3112:
PEP 3112: Byte Literals
=====================================================
Python 3.0 adopts Unicode as the language's fundamental string type and
denotes 8-bit literals differently, either as ``b'string'``
or using a :class:`bytes` constructor. For future compatibility,
Python 2.6 adds :class:`bytes` as a synonym for the :class:`str` type,
and it also supports the ``b''`` notation.
The 2.6 :class:`str` differs from 3.0's :class:`bytes` type in various
ways; most notably, the constructor is completely different. In 3.0,
``bytes([65, 66, 67])`` is 3 elements long, containing the bytes
representing ``ABC``; in 2.6, ``bytes([65, 66, 67])`` returns the
12-byte string representing the :func:`str` of the list.
The primary use of :class:`bytes` in 2.6 will be to write tests of
object type such as ``isinstance(x, bytes)``. This will help the 2to3
converter, which can't tell whether 2.x code intends strings to
contain either characters or 8-bit bytes; you can now
use either :class:`bytes` or :class:`str` to represent your intention
exactly, and the resulting code will also be correct in Python 3.0.
There's also a ``__future__`` import that causes all string literals
to become Unicode strings. This means that ``\u`` escape sequences
can be used to include Unicode characters::
from __future__ import unicode_literals
s = ('\u751f\u3080\u304e\u3000\u751f\u3054'
'\u3081\u3000\u751f\u305f\u307e\u3054')
print len(s) # 12 Unicode characters
At the C level, Python 3.0 will rename the existing 8-bit
string type, called :c:type:`PyStringObject` in Python 2.x,
to :c:type:`PyBytesObject`. Python 2.6 uses ``#define``
to support using the names :c:func:`PyBytesObject`,
:c:func:`PyBytes_Check`, :c:func:`PyBytes_FromStringAndSize`,
and all the other functions and macros used with strings.
Instances of the :class:`bytes` type are immutable just
as strings are. A new :class:`bytearray` type stores a mutable
sequence of bytes::
>>> bytearray([65, 66, 67])
bytearray(b'ABC')
>>> b = bytearray(u'\u21ef\u3244', 'utf-8')
>>> b
bytearray(b'\xe2\x87\xaf\xe3\x89\x84')
>>> b[0] = '\xe3'
>>> b
bytearray(b'\xe3\x87\xaf\xe3\x89\x84')
>>> unicode(str(b), 'utf-8')
u'\u31ef \u3244'
Byte arrays support most of the methods of string types, such as
:meth:`startswith`/:meth:`endswith`, :meth:`find`/:meth:`rfind`,
and some of the methods of lists, such as :meth:`append`,
:meth:`pop`, and :meth:`reverse`.
::
>>> b = bytearray('ABC')
>>> b.append('d')
>>> b.append(ord('e'))
>>> b
bytearray(b'ABCde')
There's also a corresponding C API, with
:c:func:`PyByteArray_FromObject`,
:c:func:`PyByteArray_FromStringAndSize`,
and various other functions.
.. seealso::
:pep:`3112` - Bytes literals in Python 3000
PEP written by Jason Orendorff; backported to 2.6 by Christian Heimes.
.. ======================================================================
.. _pep-3116:
PEP 3116: New I/O Library
=====================================================
Python's built-in file objects support a number of methods, but
file-like objects don't necessarily support all of them. Objects that
imitate files usually support :meth:`read` and :meth:`write`, but they
may not support :meth:`readline`, for example. Python 3.0 introduces
a layered I/O library in the :mod:`io` module that separates buffering
and text-handling features from the fundamental read and write
operations.
There are three levels of abstract base classes provided by
the :mod:`io` module:
* :class:`RawIOBase` defines raw I/O operations: :meth:`read`,
:meth:`readinto`,
:meth:`write`, :meth:`seek`, :meth:`tell`, :meth:`truncate`,
and :meth:`close`.
Most of the methods of this class will often map to a single system call.
There are also :meth:`readable`, :meth:`writable`, and :meth:`seekable`
methods for determining what operations a given object will allow.
Python 3.0 has concrete implementations of this class for files and
sockets, but Python 2.6 hasn't restructured its file and socket objects
in this way.
.. XXX should 2.6 register them in io.py?
* :class:`BufferedIOBase` is an abstract base class that
buffers data in memory to reduce the number of
system calls used, making I/O processing more efficient.
It supports all of the methods of :class:`RawIOBase`,
and adds a :attr:`raw` attribute holding the underlying raw object.
There are five concrete classes implementing this ABC.
:class:`BufferedWriter` and :class:`BufferedReader` are for objects
that support write-only or read-only usage that have a :meth:`seek`
method for random access. :class:`BufferedRandom` objects support
read and write access upon the same underlying stream, and
:class:`BufferedRWPair` is for objects such as TTYs that have both
read and write operations acting upon unconnected streams of data.
The :class:`BytesIO` class supports reading, writing, and seeking
over an in-memory buffer.
.. index::
single: universal newlines; What's new
* :class:`TextIOBase`: Provides functions for reading and writing
strings (remember, strings will be Unicode in Python 3.0),
and supporting :term:`universal newlines`. :class:`TextIOBase` defines
the :meth:`readline` method and supports iteration upon
objects.
There are two concrete implementations. :class:`TextIOWrapper`
wraps a buffered I/O object, supporting all of the methods for
text I/O and adding a :attr:`buffer` attribute for access
to the underlying object. :class:`~StringIO.StringIO` simply buffers
everything in memory without ever writing anything to disk.
(In Python 2.6, :class:`io.StringIO` is implemented in
pure Python, so it's pretty slow. You should therefore stick with the
existing :mod:`StringIO` module or :mod:`cStringIO` for now. At some
point Python 3.0's :mod:`io` module will be rewritten into C for speed,
and perhaps the C implementation will be backported to the 2.x releases.)
In Python 2.6, the underlying implementations haven't been
restructured to build on top of the :mod:`io` module's classes. The
module is being provided to make it easier to write code that's
forward-compatible with 3.0, and to save developers the effort of writing
their own implementations of buffering and text I/O.
.. seealso::
:pep:`3116` - New I/O
PEP written by Daniel Stutzbach, Mike Verdone, and Guido van Rossum.
Code by Guido van Rossum, Georg Brandl, Walter Doerwald,
Jeremy Hylton, Martin von Loewis, Tony Lownds, and others.
.. ======================================================================
.. _pep-3118:
PEP 3118: Revised Buffer Protocol
=====================================================
The buffer protocol is a C-level API that lets Python types
exchange pointers into their internal representations. A
memory-mapped file can be viewed as a buffer of characters, for
example, and this lets another module such as :mod:`re`
treat memory-mapped files as a string of characters to be searched.
The primary users of the buffer protocol are numeric-processing
packages such as NumPy, which expose the internal representation
of arrays so that callers can write data directly into an array instead
of going through a slower API. This PEP updates the buffer protocol in light of experience
from NumPy development, adding a number of new features
such as indicating the shape of an array or locking a memory region.
The most important new C API function is
``PyObject_GetBuffer(PyObject *obj, Py_buffer *view, int flags)``, which
takes an object and a set of flags, and fills in the
``Py_buffer`` structure with information
about the object's memory representation. Objects
can use this operation to lock memory in place
while an external caller could be modifying the contents,
so there's a corresponding ``PyBuffer_Release(Py_buffer *view)`` to
indicate that the external caller is done.
.. XXX PyObject_GetBuffer not documented in c-api
The *flags* argument to :c:func:`PyObject_GetBuffer` specifies
constraints upon the memory returned. Some examples are:
* :const:`PyBUF_WRITABLE` indicates that the memory must be writable.
* :const:`PyBUF_LOCK` requests a read-only or exclusive lock on the memory.
* :const:`PyBUF_C_CONTIGUOUS` and :const:`PyBUF_F_CONTIGUOUS`
requests a C-contiguous (last dimension varies the fastest) or
Fortran-contiguous (first dimension varies the fastest) array layout.
Two new argument codes for :c:func:`PyArg_ParseTuple`,
``s*`` and ``z*``, return locked buffer objects for a parameter.
.. seealso::
:pep:`3118` - Revising the buffer protocol
PEP written by Travis Oliphant and Carl Banks; implemented by
Travis Oliphant.
.. ======================================================================
.. _pep-3119:
PEP 3119: Abstract Base Classes
=====================================================
Some object-oriented languages such as Java support interfaces,
declaring that a class has a given set of methods or supports a given
access protocol. Abstract Base Classes (or ABCs) are an equivalent
feature for Python. The ABC support consists of an :mod:`abc` module
containing a metaclass called :class:`ABCMeta`, special handling of
this metaclass by the :func:`isinstance` and :func:`issubclass`
builtins, and a collection of basic ABCs that the Python developers
think will be widely useful. Future versions of Python will probably
add more ABCs.
Let's say you have a particular class and wish to know whether it supports
dictionary-style access. The phrase "dictionary-style" is vague, however.
It probably means that accessing items with ``obj[1]`` works.
Does it imply that setting items with ``obj[2] = value`` works?
Or that the object will have :meth:`keys`, :meth:`values`, and :meth:`items`
methods? What about the iterative variants such as :meth:`iterkeys`? :meth:`copy`
and :meth:`update`? Iterating over the object with :func:`iter`?
The Python 2.6 :mod:`collections` module includes a number of
different ABCs that represent these distinctions. :class:`Iterable`
indicates that a class defines :meth:`__iter__`, and
:class:`Container` means the class defines a :meth:`__contains__`
method and therefore supports ``x in y`` expressions. The basic
dictionary interface of getting items, setting items, and
:meth:`keys`, :meth:`values`, and :meth:`items`, is defined by the
:class:`MutableMapping` ABC.
You can derive your own classes from a particular ABC
to indicate they support that ABC's interface::
import collections
class Storage(collections.MutableMapping):
...
Alternatively, you could write the class without deriving from
the desired ABC and instead register the class by
calling the ABC's :meth:`register` method::
import collections
class Storage:
...
collections.MutableMapping.register(Storage)
For classes that you write, deriving from the ABC is probably clearer.
The :meth:`register` method is useful when you've written a new
ABC that can describe an existing type or class, or if you want
to declare that some third-party class implements an ABC.
For example, if you defined a :class:`PrintableType` ABC,
it's legal to do::
# Register Python's types
PrintableType.register(int)
PrintableType.register(float)
PrintableType.register(str)
Classes should obey the semantics specified by an ABC, but
Python can't check this; it's up to the class author to
understand the ABC's requirements and to implement the code accordingly.
To check whether an object supports a particular interface, you can
now write::
def func(d):
if not isinstance(d, collections.MutableMapping):
raise ValueError("Mapping object expected, not %r" % d)
Don't feel that you must now begin writing lots of checks as in the
above example. Python has a strong tradition of duck-typing, where
explicit type-checking is never done and code simply calls methods on
an object, trusting that those methods will be there and raising an
exception if they aren't. Be judicious in checking for ABCs and only
do it where it's absolutely necessary.
You can write your own ABCs by using ``abc.ABCMeta`` as the
metaclass in a class definition::
from abc import ABCMeta, abstractmethod
class Drawable():
__metaclass__ = ABCMeta
@abstractmethod
def draw(self, x, y, scale=1.0):
pass
def draw_doubled(self, x, y):
self.draw(x, y, scale=2.0)
class Square(Drawable):
def draw(self, x, y, scale):
...
In the :class:`Drawable` ABC above, the :meth:`draw_doubled` method
renders the object at twice its size and can be implemented in terms
of other methods described in :class:`Drawable`. Classes implementing
this ABC therefore don't need to provide their own implementation
of :meth:`draw_doubled`, though they can do so. An implementation
of :meth:`draw` is necessary, though; the ABC can't provide
a useful generic implementation.
You can apply the ``@abstractmethod`` decorator to methods such as
:meth:`draw` that must be implemented; Python will then raise an
exception for classes that don't define the method.
Note that the exception is only raised when you actually
try to create an instance of a subclass lacking the method::
>>> class Circle(Drawable):
... pass
...
>>> c = Circle()
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: Can't instantiate abstract class Circle with abstract methods draw
>>>
Abstract data attributes can be declared using the
``@abstractproperty`` decorator::
from abc import abstractproperty
...
@abstractproperty
def readonly(self):
return self._x
Subclasses must then define a :meth:`readonly` property.
.. seealso::
:pep:`3119` - Introducing Abstract Base Classes
PEP written by Guido van Rossum and Talin.
Implemented by Guido van Rossum.
Backported to 2.6 by Benjamin Aranguren, with Alex Martelli.
.. ======================================================================
.. _pep-3127:
PEP 3127: Integer Literal Support and Syntax
=====================================================
Python 3.0 changes the syntax for octal (base-8) integer literals,
prefixing them with "0o" or "0O" instead of a leading zero, and adds
support for binary (base-2) integer literals, signalled by a "0b" or
"0B" prefix.
Python 2.6 doesn't drop support for a leading 0 signalling
an octal number, but it does add support for "0o" and "0b"::
>>> 0o21, 2*8 + 1
(17, 17)
>>> 0b101111
47
The :func:`oct` builtin still returns numbers
prefixed with a leading zero, and a new :func:`bin`
builtin returns the binary representation for a number::
>>> oct(42)
'052'
>>> future_builtins.oct(42)
'0o52'
>>> bin(173)
'0b10101101'
The :func:`int` and :func:`long` builtins will now accept the "0o"
and "0b" prefixes when base-8 or base-2 are requested, or when the
*base* argument is zero (signalling that the base used should be
determined from the string)::
>>> int ('0o52', 0)
42
>>> int('1101', 2)
13
>>> int('0b1101', 2)
13
>>> int('0b1101', 0)
13
.. seealso::
:pep:`3127` - Integer Literal Support and Syntax
PEP written by Patrick Maupin; backported to 2.6 by
Eric Smith.
.. ======================================================================
.. _pep-3129:
PEP 3129: Class Decorators
=====================================================
Decorators have been extended from functions to classes. It's now legal to
write::
@foo
@bar
class A:
pass
This is equivalent to::
class A:
pass
A = foo(bar(A))
.. seealso::
:pep:`3129` - Class Decorators
PEP written by Collin Winter.
.. ======================================================================
.. _pep-3141:
PEP 3141: A Type Hierarchy for Numbers
=====================================================
Python 3.0 adds several abstract base classes for numeric types
inspired by Scheme's numeric tower. These classes were backported to
2.6 as the :mod:`numbers` module.
The most general ABC is :class:`Number`. It defines no operations at
all, and only exists to allow checking if an object is a number by
doing ``isinstance(obj, Number)``.
:class:`Complex` is a subclass of :class:`Number`. Complex numbers
can undergo the basic operations of addition, subtraction,
multiplication, division, and exponentiation, and you can retrieve the
real and imaginary parts and obtain a number's conjugate. Python's built-in
complex type is an implementation of :class:`Complex`.
:class:`Real` further derives from :class:`Complex`, and adds
operations that only work on real numbers: :func:`floor`, :func:`trunc`,
rounding, taking the remainder mod N, floor division,
and comparisons.
:class:`Rational` numbers derive from :class:`Real`, have
:attr:`numerator` and :attr:`denominator` properties, and can be
converted to floats. Python 2.6 adds a simple rational-number class,
:class:`Fraction`, in the :mod:`fractions` module. (It's called
:class:`Fraction` instead of :class:`Rational` to avoid
a name clash with :class:`numbers.Rational`.)
:class:`Integral` numbers derive from :class:`Rational`, and
can be shifted left and right with ``<<`` and ``>>``,
combined using bitwise operations such as ``&`` and ``|``,
and can be used as array indexes and slice boundaries.
In Python 3.0, the PEP slightly redefines the existing builtins
:func:`round`, :func:`math.floor`, :func:`math.ceil`, and adds a new
one, :func:`math.trunc`, that's been backported to Python 2.6.
:func:`math.trunc` rounds toward zero, returning the closest
:class:`Integral` that's between the function's argument and zero.
.. seealso::
:pep:`3141` - A Type Hierarchy for Numbers
PEP written by Jeffrey Yasskin.
`Scheme's numerical tower <https://www.gnu.org/software/guile/manual/html_node/Numerical-Tower.html#Numerical-Tower>`__, from the Guile manual.
`Scheme's number datatypes <http://schemers.org/Documents/Standards/R5RS/HTML/r5rs-Z-H-9.html#%_sec_6.2>`__ from the R5RS Scheme specification.
The :mod:`fractions` Module
--------------------------------------------------
To fill out the hierarchy of numeric types, the :mod:`fractions`
module provides a rational-number class. Rational numbers store their
values as a numerator and denominator forming a fraction, and can
exactly represent numbers such as ``2/3`` that floating-point numbers
can only approximate.
The :class:`Fraction` constructor takes two :class:`Integral` values
that will be the numerator and denominator of the resulting fraction. ::
>>> from fractions import Fraction
>>> a = Fraction(2, 3)
>>> b = Fraction(2, 5)
>>> float(a), float(b)
(0.66666666666666663, 0.40000000000000002)
>>> a+b
Fraction(16, 15)
>>> a/b
Fraction(5, 3)
For converting floating-point numbers to rationals,
the float type now has an :meth:`as_integer_ratio()` method that returns
the numerator and denominator for a fraction that evaluates to the same
floating-point value::
>>> (2.5) .as_integer_ratio()
(5, 2)
>>> (3.1415) .as_integer_ratio()
(7074029114692207L, 2251799813685248L)
>>> (1./3) .as_integer_ratio()
(6004799503160661L, 18014398509481984L)
Note that values that can only be approximated by floating-point
numbers, such as 1./3, are not simplified to the number being
approximated; the fraction attempts to match the floating-point value
**exactly**.
The :mod:`fractions` module is based upon an implementation by Sjoerd
Mullender that was in Python's :file:`Demo/classes/` directory for a
long time. This implementation was significantly updated by Jeffrey
Yasskin.
Other Language Changes
======================
Some smaller changes made to the core Python language are:
* Directories and zip archives containing a :file:`__main__.py` file
can now be executed directly by passing their name to the
interpreter. The directory or zip archive is automatically inserted
as the first entry in sys.path. (Suggestion and initial patch by
Andy Chu, subsequently revised by Phillip J. Eby and Nick Coghlan;
:issue:`1739468`.)
* The :func:`hasattr` function was catching and ignoring all errors,
under the assumption that they meant a :meth:`__getattr__` method
was failing somehow and the return value of :func:`hasattr` would
therefore be ``False``. This logic shouldn't be applied to
:exc:`KeyboardInterrupt` and :exc:`SystemExit`, however; Python 2.6
will no longer discard such exceptions when :func:`hasattr`
encounters them. (Fixed by Benjamin Peterson; :issue:`2196`.)
* When calling a function using the ``**`` syntax to provide keyword
arguments, you are no longer required to use a Python dictionary;
any mapping will now work::
>>> def f(**kw):
... print sorted(kw)
...
>>> ud=UserDict.UserDict()
>>> ud['a'] = 1
>>> ud['b'] = 'string'
>>> f(**ud)
['a', 'b']
(Contributed by Alexander Belopolsky; :issue:`1686487`.)
It's also become legal to provide keyword arguments after a ``*args`` argument
to a function call. ::
>>> def f(*args, **kw):
... print args, kw
...
>>> f(1,2,3, *(4,5,6), keyword=13)
(1, 2, 3, 4, 5, 6) {'keyword': 13}
Previously this would have been a syntax error.
(Contributed by Amaury Forgeot d'Arc; :issue:`3473`.)
* A new builtin, ``next(iterator, [default])`` returns the next item
from the specified iterator. If the *default* argument is supplied,
it will be returned if *iterator* has been exhausted; otherwise,
the :exc:`StopIteration` exception will be raised. (Backported
in :issue:`2719`.)
* Tuples now have :meth:`index` and :meth:`count` methods matching the
list type's :meth:`index` and :meth:`count` methods::
>>> t = (0,1,2,3,4,0,1,2)
>>> t.index(3)
3
>>> t.count(0)
2
(Contributed by Raymond Hettinger)
* The built-in types now have improved support for extended slicing syntax,
accepting various combinations of ``(start, stop, step)``.
Previously, the support was partial and certain corner cases wouldn't work.
(Implemented by Thomas Wouters.)
.. Revision 57619
* Properties now have three attributes, :attr:`getter`, :attr:`setter`
and :attr:`deleter`, that are decorators providing useful shortcuts
for adding a getter, setter or deleter function to an existing
property. You would use them like this::
class C(object):
@property
def x(self):
return self._x
@x.setter
def x(self, value):
self._x = value
@x.deleter
def x(self):
del self._x
class D(C):
@C.x.getter
def x(self):
return self._x * 2
@x.setter
def x(self, value):
self._x = value / 2
* Several methods of the built-in set types now accept multiple iterables:
:meth:`intersection`,
:meth:`intersection_update`,
:meth:`union`, :meth:`update`,
:meth:`difference` and :meth:`difference_update`.
::
>>> s=set('1234567890')
>>> s.intersection('abc123', 'cdf246') # Intersection between all inputs
set(['2'])
>>> s.difference('246', '789')
set(['1', '0', '3', '5'])
(Contributed by Raymond Hettinger.)
* Many floating-point features were added. The :func:`float` function
will now turn the string ``nan`` into an
IEEE 754 Not A Number value, and ``+inf`` and ``-inf`` into
positive or negative infinity. This works on any platform with
IEEE 754 semantics. (Contributed by Christian Heimes; :issue:`1635`.)
Other functions in the :mod:`math` module, :func:`isinf` and
:func:`isnan`, return true if their floating-point argument is
infinite or Not A Number. (:issue:`1640`)
Conversion functions were added to convert floating-point numbers
into hexadecimal strings (:issue:`3008`). These functions
convert floats to and from a string representation without
introducing rounding errors from the conversion between decimal and
binary. Floats have a :meth:`hex` method that returns a string
representation, and the ``float.fromhex()`` method converts a string
back into a number::
>>> a = 3.75
>>> a.hex()
'0x1.e000000000000p+1'
>>> float.fromhex('0x1.e000000000000p+1')
3.75
>>> b=1./3
>>> b.hex()
'0x1.5555555555555p-2'
* A numerical nicety: when creating a complex number from two floats
on systems that support signed zeros (-0 and +0), the
:func:`complex` constructor will now preserve the sign
of the zero. (Fixed by Mark T. Dickinson; :issue:`1507`.)
* Classes that inherit a :meth:`__hash__` method from a parent class
can set ``__hash__ = None`` to indicate that the class isn't
hashable. This will make ``hash(obj)`` raise a :exc:`TypeError`
and the class will not be indicated as implementing the
:class:`Hashable` ABC.
You should do this when you've defined a :meth:`__cmp__` or
:meth:`__eq__` method that compares objects by their value rather
than by identity. All objects have a default hash method that uses
``id(obj)`` as the hash value. There's no tidy way to remove the
:meth:`__hash__` method inherited from a parent class, so
assigning ``None`` was implemented as an override. At the
C level, extensions can set ``tp_hash`` to
:c:func:`PyObject_HashNotImplemented`.
(Fixed by Nick Coghlan and Amaury Forgeot d'Arc; :issue:`2235`.)
* The :exc:`GeneratorExit` exception now subclasses
:exc:`BaseException` instead of :exc:`Exception`. This means
that an exception handler that does ``except Exception:``
will not inadvertently catch :exc:`GeneratorExit`.
(Contributed by Chad Austin; :issue:`1537`.)
* Generator objects now have a :attr:`gi_code` attribute that refers to
the original code object backing the generator.
(Contributed by Collin Winter; :issue:`1473257`.)
* The :func:`compile` built-in function now accepts keyword arguments
as well as positional parameters. (Contributed by Thomas Wouters;
:issue:`1444529`.)
* The :func:`complex` constructor now accepts strings containing
parenthesized complex numbers, meaning that ``complex(repr(cplx))``
will now round-trip values. For example, ``complex('(3+4j)')``
now returns the value (3+4j). (:issue:`1491866`)
* The string :meth:`translate` method now accepts ``None`` as the
translation table parameter, which is treated as the identity
transformation. This makes it easier to carry out operations
that only delete characters. (Contributed by Bengt Richter and
implemented by Raymond Hettinger; :issue:`1193128`.)
* The built-in :func:`dir` function now checks for a :meth:`__dir__`
method on the objects it receives. This method must return a list
of strings containing the names of valid attributes for the object,
and lets the object control the value that :func:`dir` produces.
Objects that have :meth:`__getattr__` or :meth:`__getattribute__`
methods can use this to advertise pseudo-attributes they will honor.
(:issue:`1591665`)
* Instance method objects have new attributes for the object and function
comprising the method; the new synonym for :attr:`im_self` is
:attr:`__self__`, and :attr:`im_func` is also available as :attr:`__func__`.
The old names are still supported in Python 2.6, but are gone in 3.0.
* An obscure change: when you use the :func:`locals` function inside a
:keyword:`class` statement, the resulting dictionary no longer returns free
variables. (Free variables, in this case, are variables referenced in the
:keyword:`class` statement that aren't attributes of the class.)
.. ======================================================================
Optimizations
-------------
* The :mod:`warnings` module has been rewritten in C. This makes
it possible to invoke warnings from the parser, and may also
make the interpreter's startup faster.
(Contributed by Neal Norwitz and Brett Cannon; :issue:`1631171`.)
* Type objects now have a cache of methods that can reduce
the work required to find the correct method implementation
for a particular class; once cached, the interpreter doesn't need to
traverse base classes to figure out the right method to call.
The cache is cleared if a base class or the class itself is modified,
so the cache should remain correct even in the face of Python's dynamic
nature.
(Original optimization implemented by Armin Rigo, updated for
Python 2.6 by Kevin Jacobs; :issue:`1700288`.)
By default, this change is only applied to types that are included with
the Python core. Extension modules may not necessarily be compatible with
this cache,
so they must explicitly add :c:macro:`Py_TPFLAGS_HAVE_VERSION_TAG`
to the module's ``tp_flags`` field to enable the method cache.
(To be compatible with the method cache, the extension module's code
must not directly access and modify the ``tp_dict`` member of
any of the types it implements. Most modules don't do this,
but it's impossible for the Python interpreter to determine that.
See :issue:`1878` for some discussion.)
* Function calls that use keyword arguments are significantly faster
by doing a quick pointer comparison, usually saving the time of a
full string comparison. (Contributed by Raymond Hettinger, after an
initial implementation by Antoine Pitrou; :issue:`1819`.)
* All of the functions in the :mod:`struct` module have been rewritten in
C, thanks to work at the Need For Speed sprint.
(Contributed by Raymond Hettinger.)
* Some of the standard built-in types now set a bit in their type
objects. This speeds up checking whether an object is a subclass of
one of these types. (Contributed by Neal Norwitz.)
* Unicode strings now use faster code for detecting
whitespace and line breaks; this speeds up the :meth:`split` method
by about 25% and :meth:`splitlines` by 35%.
(Contributed by Antoine Pitrou.) Memory usage is reduced
by using pymalloc for the Unicode string's data.
* The ``with`` statement now stores the :meth:`__exit__` method on the stack,
producing a small speedup. (Implemented by Jeffrey Yasskin.)
* To reduce memory usage, the garbage collector will now clear internal
free lists when garbage-collecting the highest generation of objects.
This may return memory to the operating system sooner.
.. ======================================================================
.. _new-26-interpreter:
Interpreter Changes
-------------------------------
Two command-line options have been reserved for use by other Python
implementations. The :option:`-J` switch has been reserved for use by
Jython for Jython-specific options, such as switches that are passed to
the underlying JVM. :option:`-X` has been reserved for options
specific to a particular implementation of Python such as CPython,
Jython, or IronPython. If either option is used with Python 2.6, the
interpreter will report that the option isn't currently used.
Python can now be prevented from writing :file:`.pyc` or :file:`.pyo`
files by supplying the :option:`-B` switch to the Python interpreter,
or by setting the :envvar:`PYTHONDONTWRITEBYTECODE` environment
variable before running the interpreter. This setting is available to
Python programs as the ``sys.dont_write_bytecode`` variable, and
Python code can change the value to modify the interpreter's
behaviour. (Contributed by Neal Norwitz and Georg Brandl.)
The encoding used for standard input, output, and standard error can
be specified by setting the :envvar:`PYTHONIOENCODING` environment
variable before running the interpreter. The value should be a string
in the form ``<encoding>`` or ``<encoding>:<errorhandler>``.
The *encoding* part specifies the encoding's name, e.g. ``utf-8`` or
``latin-1``; the optional *errorhandler* part specifies
what to do with characters that can't be handled by the encoding,
and should be one of "error", "ignore", or "replace". (Contributed
by Martin von Loewis.)
.. ======================================================================
New and Improved Modules
========================
As in every release, Python's standard library received a number of
enhancements and bug fixes. Here's a partial list of the most notable
changes, sorted alphabetically by module name. Consult the
:file:`Misc/NEWS` file in the source tree for a more complete list of
changes, or look through the Subversion logs for all the details.
* The :mod:`asyncore` and :mod:`asynchat` modules are
being actively maintained again, and a number of patches and bugfixes
were applied. (Maintained by Josiah Carlson; see :issue:`1736190` for
one patch.)
* The :mod:`bsddb` module also has a new maintainer, Jesús Cea Avion, and the package
is now available as a standalone package. The web page for the package is
`www.jcea.es/programacion/pybsddb.htm
<https://www.jcea.es/programacion/pybsddb.htm>`__.
The plan is to remove the package from the standard library
in Python 3.0, because its pace of releases is much more frequent than
Python's.
The :mod:`bsddb.dbshelve` module now uses the highest pickling protocol
available, instead of restricting itself to protocol 1.
(Contributed by W. Barnes.)
* The :mod:`cgi` module will now read variables from the query string
of an HTTP POST request. This makes it possible to use form actions
with URLs that include query strings such as
"/cgi-bin/add.py?category=1". (Contributed by Alexandre Fiori and
Nubis; :issue:`1817`.)
The :func:`parse_qs` and :func:`parse_qsl` functions have been
relocated from the :mod:`cgi` module to the :mod:`urlparse` module.
The versions still available in the :mod:`cgi` module will
trigger :exc:`PendingDeprecationWarning` messages in 2.6
(:issue:`600362`).
* The :mod:`cmath` module underwent extensive revision,
contributed by Mark Dickinson and Christian Heimes.
Five new functions were added:
* :func:`polar` converts a complex number to polar form, returning
the modulus and argument of the complex number.
* :func:`rect` does the opposite, turning a modulus, argument pair
back into the corresponding complex number.
* :func:`phase` returns the argument (also called the angle) of a complex
number.
* :func:`isnan` returns True if either
the real or imaginary part of its argument is a NaN.
* :func:`isinf` returns True if either the real or imaginary part of
its argument is infinite.
The revisions also improved the numerical soundness of the
:mod:`cmath` module. For all functions, the real and imaginary
parts of the results are accurate to within a few units of least
precision (ulps) whenever possible. See :issue:`1381` for the
details. The branch cuts for :func:`asinh`, :func:`atanh`: and
:func:`atan` have also been corrected.
The tests for the module have been greatly expanded; nearly 2000 new
test cases exercise the algebraic functions.
On IEEE 754 platforms, the :mod:`cmath` module now handles IEEE 754
special values and floating-point exceptions in a manner consistent
with Annex 'G' of the C99 standard.
* A new data type in the :mod:`collections` module: :class:`namedtuple(typename,
fieldnames)` is a factory function that creates subclasses of the standard tuple
whose fields are accessible by name as well as index. For example::
>>> var_type = collections.namedtuple('variable',
... 'id name type size')
>>> # Names are separated by spaces or commas.
>>> # 'id, name, type, size' would also work.
>>> var_type._fields
('id', 'name', 'type', 'size')
>>> var = var_type(1, 'frequency', 'int', 4)
>>> print var[0], var.id # Equivalent
1 1
>>> print var[2], var.type # Equivalent
int int
>>> var._asdict()
{'size': 4, 'type': 'int', 'id': 1, 'name': 'frequency'}
>>> v2 = var._replace(name='amplitude')
>>> v2
variable(id=1, name='amplitude', type='int', size=4)
Several places in the standard library that returned tuples have
been modified to return :class:`namedtuple` instances. For example,
the :meth:`Decimal.as_tuple` method now returns a named tuple with
:attr:`sign`, :attr:`digits`, and :attr:`exponent` fields.
(Contributed by Raymond Hettinger.)
* Another change to the :mod:`collections` module is that the
:class:`deque` type now supports an optional *maxlen* parameter;
if supplied, the deque's size will be restricted to no more
than *maxlen* items. Adding more items to a full deque causes
old items to be discarded.
::
>>> from collections import deque
>>> dq=deque(maxlen=3)
>>> dq
deque([], maxlen=3)
>>> dq.append(1); dq.append(2); dq.append(3)
>>> dq
deque([1, 2, 3], maxlen=3)
>>> dq.append(4)
>>> dq
deque([2, 3, 4], maxlen=3)
(Contributed by Raymond Hettinger.)
* The :mod:`Cookie` module's :class:`Morsel` objects now support an
:attr:`httponly` attribute. In some browsers. cookies with this attribute
set cannot be accessed or manipulated by JavaScript code.
(Contributed by Arvin Schnell; :issue:`1638033`.)
* A new window method in the :mod:`curses` module,
:meth:`chgat`, changes the display attributes for a certain number of
characters on a single line. (Contributed by Fabian Kreutz.)
::
# Boldface text starting at y=0,x=21
# and affecting the rest of the line.
stdscr.chgat(0, 21, curses.A_BOLD)
The :class:`Textbox` class in the :mod:`curses.textpad` module
now supports editing in insert mode as well as overwrite mode.
Insert mode is enabled by supplying a true value for the *insert_mode*
parameter when creating the :class:`Textbox` instance.
* The :mod:`datetime` module's :meth:`strftime` methods now support a
``%f`` format code that expands to the number of microseconds in the
object, zero-padded on
the left to six places. (Contributed by Skip Montanaro; :issue:`1158`.)
* The :mod:`decimal` module was updated to version 1.66 of
`the General Decimal Specification <http://speleotrove.com/decimal/decarith.html>`__. New features
include some methods for some basic mathematical functions such as
:meth:`exp` and :meth:`log10`::
>>> Decimal(1).exp()
Decimal("2.718281828459045235360287471")
>>> Decimal("2.7182818").ln()
Decimal("0.9999999895305022877376682436")
>>> Decimal(1000).log10()
Decimal("3")
The :meth:`as_tuple` method of :class:`Decimal` objects now returns a
named tuple with :attr:`sign`, :attr:`digits`, and :attr:`exponent` fields.
(Implemented by Facundo Batista and Mark Dickinson. Named tuple
support added by Raymond Hettinger.)
* The :mod:`difflib` module's :class:`SequenceMatcher` class
now returns named tuples representing matches,
with :attr:`a`, :attr:`b`, and :attr:`size` attributes.
(Contributed by Raymond Hettinger.)
* An optional ``timeout`` parameter, specifying a timeout measured in
seconds, was added to the :class:`ftplib.FTP` class constructor as
well as the :meth:`connect` method. (Added by Facundo Batista.)
Also, the :class:`FTP` class's :meth:`storbinary` and
:meth:`storlines` now take an optional *callback* parameter that
will be called with each block of data after the data has been sent.
(Contributed by Phil Schwartz; :issue:`1221598`.)
* The :func:`reduce` built-in function is also available in the
:mod:`functools` module. In Python 3.0, the builtin has been
dropped and :func:`reduce` is only available from :mod:`functools`;
currently there are no plans to drop the builtin in the 2.x series.
(Patched by Christian Heimes; :issue:`1739906`.)
* When possible, the :mod:`getpass` module will now use
:file:`/dev/tty` to print a prompt message and read the password,
falling back to standard error and standard input. If the
password may be echoed to the terminal, a warning is printed before
the prompt is displayed. (Contributed by Gregory P. Smith.)
* The :func:`glob.glob` function can now return Unicode filenames if
a Unicode path was used and Unicode filenames are matched within the
directory. (:issue:`1001604`)
* A new function in the :mod:`heapq` module, ``merge(iter1, iter2, ...)``,
takes any number of iterables returning data in sorted
order, and returns a new generator that returns the contents of all
the iterators, also in sorted order. For example::
>>> list(heapq.merge([1, 3, 5, 9], [2, 8, 16]))
[1, 2, 3, 5, 8, 9, 16]
Another new function, ``heappushpop(heap, item)``,
pushes *item* onto *heap*, then pops off and returns the smallest item.
This is more efficient than making a call to :func:`heappush` and then
:func:`heappop`.
:mod:`heapq` is now implemented to only use less-than comparison,
instead of the less-than-or-equal comparison it previously used.
This makes :mod:`heapq`'s usage of a type match the
:meth:`list.sort` method.
(Contributed by Raymond Hettinger.)
* An optional ``timeout`` parameter, specifying a timeout measured in
seconds, was added to the :class:`httplib.HTTPConnection` and
:class:`HTTPSConnection` class constructors. (Added by Facundo
Batista.)
* Most of the :mod:`inspect` module's functions, such as
:func:`getmoduleinfo` and :func:`getargs`, now return named tuples.
In addition to behaving like tuples, the elements of the return value
can also be accessed as attributes.
(Contributed by Raymond Hettinger.)
Some new functions in the module include
:func:`isgenerator`, :func:`isgeneratorfunction`,
and :func:`isabstract`.
* The :mod:`itertools` module gained several new functions.
``izip_longest(iter1, iter2, ...[, fillvalue])`` makes tuples from
each of the elements; if some of the iterables are shorter than
others, the missing values are set to *fillvalue*. For example::
>>> tuple(itertools.izip_longest([1,2,3], [1,2,3,4,5]))
((1, 1), (2, 2), (3, 3), (None, 4), (None, 5))
``product(iter1, iter2, ..., [repeat=N])`` returns the Cartesian product
of the supplied iterables, a set of tuples containing
every possible combination of the elements returned from each iterable. ::
>>> list(itertools.product([1,2,3], [4,5,6]))
[(1, 4), (1, 5), (1, 6),
(2, 4), (2, 5), (2, 6),
(3, 4), (3, 5), (3, 6)]
The optional *repeat* keyword argument is used for taking the
product of an iterable or a set of iterables with themselves,
repeated *N* times. With a single iterable argument, *N*-tuples
are returned::
>>> list(itertools.product([1,2], repeat=3))
[(1, 1, 1), (1, 1, 2), (1, 2, 1), (1, 2, 2),
(2, 1, 1), (2, 1, 2), (2, 2, 1), (2, 2, 2)]
With two iterables, *2N*-tuples are returned. ::
>>> list(itertools.product([1,2], [3,4], repeat=2))
[(1, 3, 1, 3), (1, 3, 1, 4), (1, 3, 2, 3), (1, 3, 2, 4),
(1, 4, 1, 3), (1, 4, 1, 4), (1, 4, 2, 3), (1, 4, 2, 4),
(2, 3, 1, 3), (2, 3, 1, 4), (2, 3, 2, 3), (2, 3, 2, 4),
(2, 4, 1, 3), (2, 4, 1, 4), (2, 4, 2, 3), (2, 4, 2, 4)]
``combinations(iterable, r)`` returns sub-sequences of length *r* from
the elements of *iterable*. ::
>>> list(itertools.combinations('123', 2))
[('1', '2'), ('1', '3'), ('2', '3')]
>>> list(itertools.combinations('123', 3))
[('1', '2', '3')]
>>> list(itertools.combinations('1234', 3))
[('1', '2', '3'), ('1', '2', '4'),
('1', '3', '4'), ('2', '3', '4')]
``permutations(iter[, r])`` returns all the permutations of length *r* of
the iterable's elements. If *r* is not specified, it will default to the
number of elements produced by the iterable. ::
>>> list(itertools.permutations([1,2,3,4], 2))
[(1, 2), (1, 3), (1, 4),
(2, 1), (2, 3), (2, 4),
(3, 1), (3, 2), (3, 4),
(4, 1), (4, 2), (4, 3)]
``itertools.chain(*iterables)`` is an existing function in
:mod:`itertools` that gained a new constructor in Python 2.6.
``itertools.chain.from_iterable(iterable)`` takes a single
iterable that should return other iterables. :func:`chain` will
then return all the elements of the first iterable, then
all the elements of the second, and so on. ::
>>> list(itertools.chain.from_iterable([[1,2,3], [4,5,6]]))
[1, 2, 3, 4, 5, 6]
(All contributed by Raymond Hettinger.)
* The :mod:`logging` module's :class:`FileHandler` class
and its subclasses :class:`WatchedFileHandler`, :class:`RotatingFileHandler`,
and :class:`TimedRotatingFileHandler` now
have an optional *delay* parameter to their constructors. If *delay*
is true, opening of the log file is deferred until the first
:meth:`emit` call is made. (Contributed by Vinay Sajip.)
:class:`TimedRotatingFileHandler` also has a *utc* constructor
parameter. If the argument is true, UTC time will be used
in determining when midnight occurs and in generating filenames;
otherwise local time will be used.
* Several new functions were added to the :mod:`math` module:
* :func:`~math.isinf` and :func:`~math.isnan` determine whether a given float
is a (positive or negative) infinity or a NaN (Not a Number), respectively.
* :func:`~math.copysign` copies the sign bit of an IEEE 754 number,
returning the absolute value of *x* combined with the sign bit of
*y*. For example, ``math.copysign(1, -0.0)`` returns -1.0.
(Contributed by Christian Heimes.)
* :func:`~math.factorial` computes the factorial of a number.
(Contributed by Raymond Hettinger; :issue:`2138`.)
* :func:`~math.fsum` adds up the stream of numbers from an iterable,
and is careful to avoid loss of precision through using partial sums.
(Contributed by Jean Brouwers, Raymond Hettinger, and Mark Dickinson;
:issue:`2819`.)
* :func:`~math.acosh`, :func:`~math.asinh`
and :func:`~math.atanh` compute the inverse hyperbolic functions.
* :func:`~math.log1p` returns the natural logarithm of *1+x*
(base *e*).
* :func:`trunc` rounds a number toward zero, returning the closest
:class:`Integral` that's between the function's argument and zero.
Added as part of the backport of
`PEP 3141's type hierarchy for numbers <#pep-3141>`__.
* The :mod:`math` module has been improved to give more consistent
behaviour across platforms, especially with respect to handling of
floating-point exceptions and IEEE 754 special values.
Whenever possible, the module follows the recommendations of the C99
standard about 754's special values. For example, ``sqrt(-1.)``
should now give a :exc:`ValueError` across almost all platforms,
while ``sqrt(float('NaN'))`` should return a NaN on all IEEE 754
platforms. Where Annex 'F' of the C99 standard recommends signaling
'divide-by-zero' or 'invalid', Python will raise :exc:`ValueError`.
Where Annex 'F' of the C99 standard recommends signaling 'overflow',
Python will raise :exc:`OverflowError`. (See :issue:`711019` and
:issue:`1640`.)
(Contributed by Christian Heimes and Mark Dickinson.)
* :class:`~mmap.mmap` objects now have a :meth:`rfind` method that searches for a
substring beginning at the end of the string and searching
backwards. The :meth:`find` method also gained an *end* parameter
giving an index at which to stop searching.
(Contributed by John Lenton.)
* The :mod:`operator` module gained a
:func:`methodcaller` function that takes a name and an optional
set of arguments, returning a callable that will call
the named function on any arguments passed to it. For example::
>>> # Equivalent to lambda s: s.replace('old', 'new')
>>> replacer = operator.methodcaller('replace', 'old', 'new')
>>> replacer('old wine in old bottles')
'new wine in new bottles'
(Contributed by Georg Brandl, after a suggestion by Gregory Petrosyan.)
The :func:`attrgetter` function now accepts dotted names and performs
the corresponding attribute lookups::
>>> inst_name = operator.attrgetter(
... '__class__.__name__')
>>> inst_name('')
'str'
>>> inst_name(help)
'_Helper'
(Contributed by Georg Brandl, after a suggestion by Barry Warsaw.)
* The :mod:`os` module now wraps several new system calls.
``fchmod(fd, mode)`` and ``fchown(fd, uid, gid)`` change the mode
and ownership of an opened file, and ``lchmod(path, mode)`` changes
the mode of a symlink. (Contributed by Georg Brandl and Christian
Heimes.)
:func:`chflags` and :func:`lchflags` are wrappers for the
corresponding system calls (where they're available), changing the
flags set on a file. Constants for the flag values are defined in
the :mod:`stat` module; some possible values include
:const:`UF_IMMUTABLE` to signal the file may not be changed and
:const:`UF_APPEND` to indicate that data can only be appended to the
file. (Contributed by M. Levinson.)
``os.closerange(low, high)`` efficiently closes all file descriptors
from *low* to *high*, ignoring any errors and not including *high* itself.
This function is now used by the :mod:`subprocess` module to make starting
processes faster. (Contributed by Georg Brandl; :issue:`1663329`.)
* The ``os.environ`` object's :meth:`clear` method will now unset the
environment variables using :func:`os.unsetenv` in addition to clearing
the object's keys. (Contributed by Martin Horcicka; :issue:`1181`.)
* The :func:`os.walk` function now has a ``followlinks`` parameter. If
set to True, it will follow symlinks pointing to directories and
visit the directory's contents. For backward compatibility, the
parameter's default value is false. Note that the function can fall
into an infinite recursion if there's a symlink that points to a
parent directory. (:issue:`1273829`)
* In the :mod:`os.path` module, the :func:`splitext` function
has been changed to not split on leading period characters.
This produces better results when operating on Unix's dot-files.
For example, ``os.path.splitext('.ipython')``
now returns ``('.ipython', '')`` instead of ``('', '.ipython')``.
(:issue:`1115886`)
A new function, ``os.path.relpath(path, start='.')``, returns a relative path
from the ``start`` path, if it's supplied, or from the current
working directory to the destination ``path``. (Contributed by
Richard Barran; :issue:`1339796`.)
On Windows, :func:`os.path.expandvars` will now expand environment variables
given in the form "%var%", and "~user" will be expanded into the
user's home directory path. (Contributed by Josiah Carlson;
:issue:`957650`.)
* The Python debugger provided by the :mod:`pdb` module
gained a new command: "run" restarts the Python program being debugged
and can optionally take new command-line arguments for the program.
(Contributed by Rocky Bernstein; :issue:`1393667`.)
* The :func:`pdb.post_mortem` function, used to begin debugging a
traceback, will now use the traceback returned by :func:`sys.exc_info`
if no traceback is supplied. (Contributed by Facundo Batista;
:issue:`1106316`.)
* The :mod:`pickletools` module now has an :func:`optimize` function
that takes a string containing a pickle and removes some unused
opcodes, returning a shorter pickle that contains the same data structure.
(Contributed by Raymond Hettinger.)
* A :func:`get_data` function was added to the :mod:`pkgutil`
module that returns the contents of resource files included
with an installed Python package. For example::
>>> import pkgutil
>>> print pkgutil.get_data('test', 'exception_hierarchy.txt')
BaseException
+-- SystemExit
+-- KeyboardInterrupt
+-- GeneratorExit
+-- Exception
+-- StopIteration
+-- StandardError
...
(Contributed by Paul Moore; :issue:`2439`.)
* The :mod:`pyexpat` module's :class:`Parser` objects now allow setting
their :attr:`buffer_size` attribute to change the size of the buffer
used to hold character data.
(Contributed by Achim Gaedke; :issue:`1137`.)
* The :mod:`Queue` module now provides queue variants that retrieve entries
in different orders. The :class:`PriorityQueue` class stores
queued items in a heap and retrieves them in priority order,
and :class:`LifoQueue` retrieves the most recently added entries first,
meaning that it behaves like a stack.
(Contributed by Raymond Hettinger.)
* The :mod:`random` module's :class:`Random` objects can
now be pickled on a 32-bit system and unpickled on a 64-bit
system, and vice versa. Unfortunately, this change also means
that Python 2.6's :class:`Random` objects can't be unpickled correctly
on earlier versions of Python.
(Contributed by Shawn Ligocki; :issue:`1727780`.)
The new ``triangular(low, high, mode)`` function returns random
numbers following a triangular distribution. The returned values
are between *low* and *high*, not including *high* itself, and
with *mode* as the most frequently occurring value
in the distribution. (Contributed by Wladmir van der Laan and
Raymond Hettinger; :issue:`1681432`.)
* Long regular expression searches carried out by the :mod:`re`
module will check for signals being delivered, so
time-consuming searches can now be interrupted.
(Contributed by Josh Hoyt and Ralf Schmitt; :issue:`846388`.)
The regular expression module is implemented by compiling bytecodes
for a tiny regex-specific virtual machine. Untrusted code
could create malicious strings of bytecode directly and cause crashes,
so Python 2.6 includes a verifier for the regex bytecode.
(Contributed by Guido van Rossum from work for Google App Engine;
:issue:`3487`.)
* The :mod:`rlcompleter` module's :meth:`Completer.complete()` method
will now ignore exceptions triggered while evaluating a name.
(Fixed by Lorenz Quack; :issue:`2250`.)
* The :mod:`sched` module's :class:`scheduler` instances now
have a read-only :attr:`queue` attribute that returns the
contents of the scheduler's queue, represented as a list of
named tuples with the fields ``(time, priority, action, argument)``.
(Contributed by Raymond Hettinger; :issue:`1861`.)
* The :mod:`select` module now has wrapper functions
for the Linux :c:func:`epoll` and BSD :c:func:`kqueue` system calls.
:meth:`modify` method was added to the existing :class:`poll`
objects; ``pollobj.modify(fd, eventmask)`` takes a file descriptor
or file object and an event mask, modifying the recorded event mask
for that file.
(Contributed by Christian Heimes; :issue:`1657`.)
* The :func:`shutil.copytree` function now has an optional *ignore* argument
that takes a callable object. This callable will receive each directory path
and a list of the directory's contents, and returns a list of names that
will be ignored, not copied.
The :mod:`shutil` module also provides an :func:`ignore_patterns`
function for use with this new parameter. :func:`ignore_patterns`
takes an arbitrary number of glob-style patterns and returns a
callable that will ignore any files and directories that match any
of these patterns. The following example copies a directory tree,
but skips both :file:`.svn` directories and Emacs backup files,
which have names ending with '~'::
shutil.copytree('Doc/library', '/tmp/library',
ignore=shutil.ignore_patterns('*~', '.svn'))
(Contributed by Tarek Ziadé; :issue:`2663`.)
* Integrating signal handling with GUI handling event loops
like those used by Tkinter or GTk+ has long been a problem; most
software ends up polling, waking up every fraction of a second to check
if any GUI events have occurred.
The :mod:`signal` module can now make this more efficient.
Calling ``signal.set_wakeup_fd(fd)`` sets a file descriptor
to be used; when a signal is received, a byte is written to that
file descriptor. There's also a C-level function,
:c:func:`PySignal_SetWakeupFd`, for setting the descriptor.
Event loops will use this by opening a pipe to create two descriptors,
one for reading and one for writing. The writable descriptor
will be passed to :func:`set_wakeup_fd`, and the readable descriptor
will be added to the list of descriptors monitored by the event loop via
:c:func:`select` or :c:func:`poll`.
On receiving a signal, a byte will be written and the main event loop
will be woken up, avoiding the need to poll.
(Contributed by Adam Olsen; :issue:`1583`.)
The :func:`siginterrupt` function is now available from Python code,
and allows changing whether signals can interrupt system calls or not.
(Contributed by Ralf Schmitt.)
The :func:`setitimer` and :func:`getitimer` functions have also been
added (where they're available). :func:`setitimer`
allows setting interval timers that will cause a signal to be
delivered to the process after a specified time, measured in
wall-clock time, consumed process time, or combined process+system
time. (Contributed by Guilherme Polo; :issue:`2240`.)
* The :mod:`smtplib` module now supports SMTP over SSL thanks to the
addition of the :class:`SMTP_SSL` class. This class supports an
interface identical to the existing :class:`SMTP` class.
(Contributed by Monty Taylor.) Both class constructors also have an
optional ``timeout`` parameter that specifies a timeout for the
initial connection attempt, measured in seconds. (Contributed by
Facundo Batista.)
An implementation of the LMTP protocol (:rfc:`2033`) was also added
to the module. LMTP is used in place of SMTP when transferring
e-mail between agents that don't manage a mail queue. (LMTP
implemented by Leif Hedstrom; :issue:`957003`.)
:meth:`SMTP.starttls` now complies with :rfc:`3207` and forgets any
knowledge obtained from the server not obtained from the TLS
negotiation itself. (Patch contributed by Bill Fenner;
:issue:`829951`.)
* The :mod:`socket` module now supports TIPC (http://tipc.sourceforge.net/),
a high-performance non-IP-based protocol designed for use in clustered
environments. TIPC addresses are 4- or 5-tuples.
(Contributed by Alberto Bertogli; :issue:`1646`.)
A new function, :func:`create_connection`, takes an address and
connects to it using an optional timeout value, returning the
connected socket object. This function also looks up the address's
type and connects to it using IPv4 or IPv6 as appropriate. Changing
your code to use :func:`create_connection` instead of
``socket(socket.AF_INET, ...)`` may be all that's required to make
your code work with IPv6.
* The base classes in the :mod:`SocketServer` module now support
calling a :meth:`handle_timeout` method after a span of inactivity
specified by the server's :attr:`timeout` attribute. (Contributed
by Michael Pomraning.) The :meth:`serve_forever` method
now takes an optional poll interval measured in seconds,
controlling how often the server will check for a shutdown request.
(Contributed by Pedro Werneck and Jeffrey Yasskin;
:issue:`742598`, :issue:`1193577`.)
* The :mod:`sqlite3` module, maintained by Gerhard Haering,
has been updated from version 2.3.2 in Python 2.5 to
version 2.4.1.
* The :mod:`struct` module now supports the C99 :c:type:`_Bool` type,
using the format character ``'?'``.
(Contributed by David Remahl.)
* The :class:`Popen` objects provided by the :mod:`subprocess` module
now have :meth:`terminate`, :meth:`kill`, and :meth:`send_signal` methods.
On Windows, :meth:`send_signal` only supports the :const:`SIGTERM`
signal, and all these methods are aliases for the Win32 API function
:c:func:`TerminateProcess`.
(Contributed by Christian Heimes.)
* A new variable in the :mod:`sys` module, :attr:`float_info`, is an
object containing information derived from the :file:`float.h` file
about the platform's floating-point support. Attributes of this
object include :attr:`mant_dig` (number of digits in the mantissa),
:attr:`epsilon` (smallest difference between 1.0 and the next
largest value representable), and several others. (Contributed by
Christian Heimes; :issue:`1534`.)
Another new variable, :attr:`dont_write_bytecode`, controls whether Python
writes any :file:`.pyc` or :file:`.pyo` files on importing a module.
If this variable is true, the compiled files are not written. The
variable is initially set on start-up by supplying the :option:`-B`
switch to the Python interpreter, or by setting the
:envvar:`PYTHONDONTWRITEBYTECODE` environment variable before
running the interpreter. Python code can subsequently
change the value of this variable to control whether bytecode files
are written or not.
(Contributed by Neal Norwitz and Georg Brandl.)
Information about the command-line arguments supplied to the Python
interpreter is available by reading attributes of a named
tuple available as ``sys.flags``. For example, the :attr:`verbose`
attribute is true if Python
was executed in verbose mode, :attr:`debug` is true in debugging mode, etc.
These attributes are all read-only.
(Contributed by Christian Heimes.)
A new function, :func:`getsizeof`, takes a Python object and returns
the amount of memory used by the object, measured in bytes. Built-in
objects return correct results; third-party extensions may not,
but can define a :meth:`__sizeof__` method to return the
object's size.
(Contributed by Robert Schuppenies; :issue:`2898`.)
It's now possible to determine the current profiler and tracer functions
by calling :func:`sys.getprofile` and :func:`sys.gettrace`.
(Contributed by Georg Brandl; :issue:`1648`.)
* The :mod:`tarfile` module now supports POSIX.1-2001 (pax) tarfiles in
addition to the POSIX.1-1988 (ustar) and GNU tar formats that were
already supported. The default format is GNU tar; specify the
``format`` parameter to open a file using a different format::
tar = tarfile.open("output.tar", "w",
format=tarfile.PAX_FORMAT)
The new ``encoding`` and ``errors`` parameters specify an encoding and
an error handling scheme for character conversions. ``'strict'``,
``'ignore'``, and ``'replace'`` are the three standard ways Python can
handle errors,;
``'utf-8'`` is a special value that replaces bad characters with
their UTF-8 representation. (Character conversions occur because the
PAX format supports Unicode filenames, defaulting to UTF-8 encoding.)
The :meth:`TarFile.add` method now accepts an ``exclude`` argument that's
a function that can be used to exclude certain filenames from
an archive.
The function must take a filename and return true if the file
should be excluded or false if it should be archived.
The function is applied to both the name initially passed to :meth:`add`
and to the names of files in recursively-added directories.
(All changes contributed by Lars Gustäbel).
* An optional ``timeout`` parameter was added to the
:class:`telnetlib.Telnet` class constructor, specifying a timeout
measured in seconds. (Added by Facundo Batista.)
* The :class:`tempfile.NamedTemporaryFile` class usually deletes
the temporary file it created when the file is closed. This
behaviour can now be changed by passing ``delete=False`` to the
constructor. (Contributed by Damien Miller; :issue:`1537850`.)
A new class, :class:`SpooledTemporaryFile`, behaves like
a temporary file but stores its data in memory until a maximum size is
exceeded. On reaching that limit, the contents will be written to
an on-disk temporary file. (Contributed by Dustin J. Mitchell.)
The :class:`NamedTemporaryFile` and :class:`SpooledTemporaryFile` classes
both work as context managers, so you can write
``with tempfile.NamedTemporaryFile() as tmp: ...``.
(Contributed by Alexander Belopolsky; :issue:`2021`.)
* The :mod:`test.test_support` module gained a number
of context managers useful for writing tests.
:func:`EnvironmentVarGuard` is a
context manager that temporarily changes environment variables and
automatically restores them to their old values.
Another context manager, :class:`TransientResource`, can surround calls
to resources that may or may not be available; it will catch and
ignore a specified list of exceptions. For example,
a network test may ignore certain failures when connecting to an
external web site::
with test_support.TransientResource(IOError,
errno=errno.ETIMEDOUT):
f = urllib.urlopen('https://sf.net')
...
Finally, :func:`check_warnings` resets the :mod:`warning` module's
warning filters and returns an object that will record all warning
messages triggered (:issue:`3781`)::
with test_support.check_warnings() as wrec:
warnings.simplefilter("always")
# ... code that triggers a warning ...
assert str(wrec.message) == "function is outdated"
assert len(wrec.warnings) == 1, "Multiple warnings raised"
(Contributed by Brett Cannon.)
* The :mod:`textwrap` module can now preserve existing whitespace
at the beginnings and ends of the newly-created lines
by specifying ``drop_whitespace=False``
as an argument::
>>> S = """This sentence has a bunch of
... extra whitespace."""
>>> print textwrap.fill(S, width=15)
This sentence
has a bunch
of extra
whitespace.
>>> print textwrap.fill(S, drop_whitespace=False, width=15)
This sentence
has a bunch
of extra
whitespace.
>>>
(Contributed by Dwayne Bailey; :issue:`1581073`.)
* The :mod:`threading` module API is being changed to use properties
such as :attr:`daemon` instead of :meth:`setDaemon` and
:meth:`isDaemon` methods, and some methods have been renamed to use
underscores instead of camel-case; for example, the
:meth:`activeCount` method is renamed to :meth:`active_count`. Both
the 2.6 and 3.0 versions of the module support the same properties
and renamed methods, but don't remove the old methods. No date has been set
for the deprecation of the old APIs in Python 3.x; the old APIs won't
be removed in any 2.x version.
(Carried out by several people, most notably Benjamin Peterson.)
The :mod:`threading` module's :class:`Thread` objects
gained an :attr:`ident` property that returns the thread's
identifier, a nonzero integer. (Contributed by Gregory P. Smith;
:issue:`2871`.)
* The :mod:`timeit` module now accepts callables as well as strings
for the statement being timed and for the setup code.
Two convenience functions were added for creating
:class:`Timer` instances:
``repeat(stmt, setup, time, repeat, number)`` and
``timeit(stmt, setup, time, number)`` create an instance and call
the corresponding method. (Contributed by Erik Demaine;
:issue:`1533909`.)
* The :mod:`Tkinter` module now accepts lists and tuples for options,
separating the elements by spaces before passing the resulting value to
Tcl/Tk.
(Contributed by Guilherme Polo; :issue:`2906`.)
* The :mod:`turtle` module for turtle graphics was greatly enhanced by
Gregor Lingl. New features in the module include:
* Better animation of turtle movement and rotation.
* Control over turtle movement using the new :meth:`delay`,
:meth:`tracer`, and :meth:`speed` methods.
* The ability to set new shapes for the turtle, and to
define a new coordinate system.
* Turtles now have an :meth:`undo()` method that can roll back actions.
* Simple support for reacting to input events such as mouse and keyboard
activity, making it possible to write simple games.
* A :file:`turtle.cfg` file can be used to customize the starting appearance
of the turtle's screen.
* The module's docstrings can be replaced by new docstrings that have been
translated into another language.
(:issue:`1513695`)
* An optional ``timeout`` parameter was added to the
:func:`urllib.urlopen` function and the
:class:`urllib.ftpwrapper` class constructor, as well as the
:func:`urllib2.urlopen` function. The parameter specifies a timeout
measured in seconds. For example::
>>> u = urllib2.urlopen("http://slow.example.com",
timeout=3)
Traceback (most recent call last):
...
urllib2.URLError: <urlopen error timed out>
>>>
(Added by Facundo Batista.)
* The Unicode database provided by the :mod:`unicodedata` module
has been updated to version 5.1.0. (Updated by
Martin von Loewis; :issue:`3811`.)
* The :mod:`warnings` module's :func:`formatwarning` and :func:`showwarning`
gained an optional *line* argument that can be used to supply the
line of source code. (Added as part of :issue:`1631171`, which re-implemented
part of the :mod:`warnings` module in C code.)
A new function, :func:`catch_warnings`, is a context manager
intended for testing purposes that lets you temporarily modify the
warning filters and then restore their original values (:issue:`3781`).
* The XML-RPC :class:`~SimpleXMLRPCServer.SimpleXMLRPCServer` and :class:`~DocXMLRPCServer.DocXMLRPCServer`
classes can now be prevented from immediately opening and binding to
their socket by passing ``False`` as the *bind_and_activate*
constructor parameter. This can be used to modify the instance's
:attr:`allow_reuse_address` attribute before calling the
:meth:`server_bind` and :meth:`server_activate` methods to
open the socket and begin listening for connections.
(Contributed by Peter Parente; :issue:`1599845`.)
:class:`~SimpleXMLRPCServer.SimpleXMLRPCServer` also has a :attr:`_send_traceback_header`
attribute; if true, the exception and formatted traceback are returned
as HTTP headers "X-Exception" and "X-Traceback". This feature is
for debugging purposes only and should not be used on production servers
because the tracebacks might reveal passwords or other sensitive
information. (Contributed by Alan McIntyre as part of his
project for Google's Summer of Code 2007.)
* The :mod:`xmlrpclib` module no longer automatically converts
:class:`datetime.date` and :class:`datetime.time` to the
:class:`xmlrpclib.DateTime` type; the conversion semantics were
not necessarily correct for all applications. Code using
:mod:`xmlrpclib` should convert :class:`date` and :class:`~datetime.time`
instances. (:issue:`1330538`) The code can also handle
dates before 1900 (contributed by Ralf Schmitt; :issue:`2014`)
and 64-bit integers represented by using ``<i8>`` in XML-RPC responses
(contributed by Riku Lindblad; :issue:`2985`).
* The :mod:`zipfile` module's :class:`ZipFile` class now has
:meth:`extract` and :meth:`extractall` methods that will unpack
a single file or all the files in the archive to the current directory, or
to a specified directory::
z = zipfile.ZipFile('python-251.zip')
# Unpack a single file, writing it relative
# to the /tmp directory.
z.extract('Python/sysmodule.c', '/tmp')
# Unpack all the files in the archive.
z.extractall()
(Contributed by Alan McIntyre; :issue:`467924`.)
The :meth:`open`, :meth:`read` and :meth:`extract` methods can now
take either a filename or a :class:`ZipInfo` object. This is useful when an
archive accidentally contains a duplicated filename.
(Contributed by Graham Horler; :issue:`1775025`.)
Finally, :mod:`zipfile` now supports using Unicode filenames
for archived files. (Contributed by Alexey Borzenkov; :issue:`1734346`.)
.. ======================================================================
.. whole new modules get described in subsections here
The :mod:`ast` module
----------------------
The :mod:`ast` module provides an Abstract Syntax Tree
representation of Python code, and Armin Ronacher
contributed a set of helper functions that perform a variety of
common tasks. These will be useful for HTML templating
packages, code analyzers, and similar tools that process
Python code.
The :func:`parse` function takes an expression and returns an AST.
The :func:`dump` function outputs a representation of a tree, suitable
for debugging::
import ast
t = ast.parse("""
d = {}
for i in 'abcdefghijklm':
d[i + i] = ord(i) - ord('a') + 1
print d
""")
print ast.dump(t)
This outputs a deeply nested tree::
Module(body=[
Assign(targets=[
Name(id='d', ctx=Store())
], value=Dict(keys=[], values=[]))
For(target=Name(id='i', ctx=Store()),
iter=Str(s='abcdefghijklm'), body=[
Assign(targets=[
Subscript(value=
Name(id='d', ctx=Load()),
slice=
Index(value=
BinOp(left=Name(id='i', ctx=Load()), op=Add(),
right=Name(id='i', ctx=Load()))), ctx=Store())
], value=
BinOp(left=
BinOp(left=
Call(func=
Name(id='ord', ctx=Load()), args=[
Name(id='i', ctx=Load())
], keywords=[], starargs=None, kwargs=None),
op=Sub(), right=Call(func=
Name(id='ord', ctx=Load()), args=[
Str(s='a')
], keywords=[], starargs=None, kwargs=None)),
op=Add(), right=Num(n=1)))
], orelse=[])
Print(dest=None, values=[
Name(id='d', ctx=Load())
], nl=True)
])
The :func:`literal_eval` method takes a string or an AST
representing a literal expression, parses and evaluates it, and
returns the resulting value. A literal expression is a Python
expression containing only strings, numbers, dictionaries,
etc. but no statements or function calls. If you need to
evaluate an expression but cannot accept the security risk of using an
:func:`eval` call, :func:`literal_eval` will handle it safely::
>>> literal = '("a", "b", {2:4, 3:8, 1:2})'
>>> print ast.literal_eval(literal)
('a', 'b', {1: 2, 2: 4, 3: 8})
>>> print ast.literal_eval('"a" + "b"')
Traceback (most recent call last):
...
ValueError: malformed string
The module also includes :class:`NodeVisitor` and
:class:`NodeTransformer` classes for traversing and modifying an AST,
and functions for common transformations such as changing line
numbers.
.. ======================================================================
The :mod:`future_builtins` module
--------------------------------------
Python 3.0 makes many changes to the repertoire of built-in
functions, and most of the changes can't be introduced in the Python
2.x series because they would break compatibility.
The :mod:`future_builtins` module provides versions
of these built-in functions that can be imported when writing
3.0-compatible code.
The functions in this module currently include:
* ``ascii(obj)``: equivalent to :func:`repr`. In Python 3.0,
:func:`repr` will return a Unicode string, while :func:`ascii` will
return a pure ASCII bytestring.
* ``filter(predicate, iterable)``,
``map(func, iterable1, ...)``: the 3.0 versions
return iterators, unlike the 2.x builtins which return lists.
* ``hex(value)``, ``oct(value)``: instead of calling the
:meth:`__hex__` or :meth:`__oct__` methods, these versions will
call the :meth:`__index__` method and convert the result to hexadecimal
or octal. :func:`oct` will use the new ``0o`` notation for its
result.
.. ======================================================================
The :mod:`json` module: JavaScript Object Notation
--------------------------------------------------------------------
The new :mod:`json` module supports the encoding and decoding of Python types in
JSON (Javascript Object Notation). JSON is a lightweight interchange format
often used in web applications. For more information about JSON, see
http://www.json.org.
:mod:`json` comes with support for decoding and encoding most built-in Python
types. The following example encodes and decodes a dictionary::
>>> import json
>>> data = {"spam": "foo", "parrot": 42}
>>> in_json = json.dumps(data) # Encode the data
>>> in_json
'{"parrot": 42, "spam": "foo"}'
>>> json.loads(in_json) # Decode into a Python object
{"spam": "foo", "parrot": 42}
It's also possible to write your own decoders and encoders to support
more types. Pretty-printing of the JSON strings is also supported.
:mod:`json` (originally called simplejson) was written by Bob
Ippolito.
.. ======================================================================
The :mod:`plistlib` module: A Property-List Parser
--------------------------------------------------
The ``.plist`` format is commonly used on Mac OS X to
store basic data types (numbers, strings, lists,
and dictionaries) by serializing them into an XML-based format.
It resembles the XML-RPC serialization of data types.
Despite being primarily used on Mac OS X, the format
has nothing Mac-specific about it and the Python implementation works
on any platform that Python supports, so the :mod:`plistlib` module
has been promoted to the standard library.
Using the module is simple::
import sys
import plistlib
import datetime
# Create data structure
data_struct = dict(lastAccessed=datetime.datetime.now(),
version=1,
categories=('Personal','Shared','Private'))
# Create string containing XML.
plist_str = plistlib.writePlistToString(data_struct)
new_struct = plistlib.readPlistFromString(plist_str)
print data_struct
print new_struct
# Write data structure to a file and read it back.
plistlib.writePlist(data_struct, '/tmp/customizations.plist')
new_struct = plistlib.readPlist('/tmp/customizations.plist')
# read/writePlist accepts file-like objects as well as paths.
plistlib.writePlist(data_struct, sys.stdout)
.. ======================================================================
ctypes Enhancements
--------------------------------------------------
Thomas Heller continued to maintain and enhance the
:mod:`ctypes` module.
:mod:`ctypes` now supports a :class:`c_bool` datatype
that represents the C99 ``bool`` type. (Contributed by David Remahl;
:issue:`1649190`.)
The :mod:`ctypes` string, buffer and array types have improved
support for extended slicing syntax,
where various combinations of ``(start, stop, step)`` are supplied.
(Implemented by Thomas Wouters.)
.. Revision 57769
All :mod:`ctypes` data types now support
:meth:`from_buffer` and :meth:`from_buffer_copy`
methods that create a ctypes instance based on a
provided buffer object. :meth:`from_buffer_copy` copies
the contents of the object,
while :meth:`from_buffer` will share the same memory area.
A new calling convention tells :mod:`ctypes` to clear the ``errno`` or
Win32 LastError variables at the outset of each wrapped call.
(Implemented by Thomas Heller; :issue:`1798`.)
You can now retrieve the Unix ``errno`` variable after a function
call. When creating a wrapped function, you can supply
``use_errno=True`` as a keyword parameter to the :func:`DLL` function
and then call the module-level methods :meth:`set_errno` and
:meth:`get_errno` to set and retrieve the error value.
The Win32 LastError variable is similarly supported by
the :func:`DLL`, :func:`OleDLL`, and :func:`WinDLL` functions.
You supply ``use_last_error=True`` as a keyword parameter
and then call the module-level methods :meth:`set_last_error`
and :meth:`get_last_error`.
The :func:`byref` function, used to retrieve a pointer to a ctypes
instance, now has an optional *offset* parameter that is a byte
count that will be added to the returned pointer.
.. ======================================================================
Improved SSL Support
--------------------------------------------------
Bill Janssen made extensive improvements to Python 2.6's support for
the Secure Sockets Layer by adding a new module, :mod:`ssl`, that's
built atop the `OpenSSL <https://www.openssl.org/>`__ library.
This new module provides more control over the protocol negotiated,
the X.509 certificates used, and has better support for writing SSL
servers (as opposed to clients) in Python. The existing SSL support
in the :mod:`socket` module hasn't been removed and continues to work,
though it will be removed in Python 3.0.
To use the new module, you must first create a TCP connection in the
usual way and then pass it to the :func:`ssl.wrap_socket` function.
It's possible to specify whether a certificate is required, and to
obtain certificate info by calling the :meth:`getpeercert` method.
.. seealso::
The documentation for the :mod:`ssl` module.
.. ======================================================================
Deprecations and Removals
=========================
* String exceptions have been removed. Attempting to use them raises a
:exc:`TypeError`.
* Changes to the :class:`Exception` interface
as dictated by :pep:`352` continue to be made. For 2.6,
the :attr:`message` attribute is being deprecated in favor of the
:attr:`args` attribute.
* (3.0-warning mode) Python 3.0 will feature a reorganized standard
library that will drop many outdated modules and rename others.
Python 2.6 running in 3.0-warning mode will warn about these modules
when they are imported.
The list of deprecated modules is:
:mod:`audiodev`,
:mod:`bgenlocations`,
:mod:`buildtools`,
:mod:`bundlebuilder`,
:mod:`Canvas`,
:mod:`compiler`,
:mod:`dircache`,
:mod:`dl`,
:mod:`fpformat`,
:mod:`gensuitemodule`,
:mod:`ihooks`,
:mod:`imageop`,
:mod:`imgfile`,
:mod:`linuxaudiodev`,
:mod:`mhlib`,
:mod:`mimetools`,
:mod:`multifile`,
:mod:`new`,
:mod:`pure`,
:mod:`statvfs`,
:mod:`sunaudiodev`,
:mod:`test.testall`, and
:mod:`toaiff`.
* The :mod:`gopherlib` module has been removed.
* The :mod:`MimeWriter` module and :mod:`mimify` module
have been deprecated; use the :mod:`email`
package instead.
* The :mod:`md5` module has been deprecated; use the :mod:`hashlib` module
instead.
* The :mod:`posixfile` module has been deprecated; :func:`fcntl.lockf`
provides better locking.
* The :mod:`popen2` module has been deprecated; use the :mod:`subprocess`
module.
* The :mod:`rgbimg` module has been removed.
* The :mod:`sets` module has been deprecated; it's better to
use the built-in :class:`set` and :class:`frozenset` types.
* The :mod:`sha` module has been deprecated; use the :mod:`hashlib` module
instead.
.. ======================================================================
Build and C API Changes
=======================
Changes to Python's build process and to the C API include:
* Python now must be compiled with C89 compilers (after 19
years!). This means that the Python source tree has dropped its
own implementations of :c:func:`memmove` and :c:func:`strerror`, which
are in the C89 standard library.
* Python 2.6 can be built with Microsoft Visual Studio 2008 (version
9.0), and this is the new default compiler. See the
:file:`PCbuild` directory for the build files. (Implemented by
Christian Heimes.)
* On Mac OS X, Python 2.6 can be compiled as a 4-way universal build.
The :program:`configure` script
can take a :option:`!--with-universal-archs=[32-bit|64-bit|all]`
switch, controlling whether the binaries are built for 32-bit
architectures (x86, PowerPC), 64-bit (x86-64 and PPC-64), or both.
(Contributed by Ronald Oussoren.)
* The BerkeleyDB module now has a C API object, available as
``bsddb.db.api``. This object can be used by other C extensions
that wish to use the :mod:`bsddb` module for their own purposes.
(Contributed by Duncan Grisby.)
* The new buffer interface, previously described in
`the PEP 3118 section <#pep-3118-revised-buffer-protocol>`__,
adds :c:func:`PyObject_GetBuffer` and :c:func:`PyBuffer_Release`,
as well as a few other functions.
* Python's use of the C stdio library is now thread-safe, or at least
as thread-safe as the underlying library is. A long-standing potential
bug occurred if one thread closed a file object while another thread
was reading from or writing to the object. In 2.6 file objects
have a reference count, manipulated by the
:c:func:`PyFile_IncUseCount` and :c:func:`PyFile_DecUseCount`
functions. File objects can't be closed unless the reference count
is zero. :c:func:`PyFile_IncUseCount` should be called while the GIL
is still held, before carrying out an I/O operation using the
``FILE *`` pointer, and :c:func:`PyFile_DecUseCount` should be called
immediately after the GIL is re-acquired.
(Contributed by Antoine Pitrou and Gregory P. Smith.)
* Importing modules simultaneously in two different threads no longer
deadlocks; it will now raise an :exc:`ImportError`. A new API
function, :c:func:`PyImport_ImportModuleNoBlock`, will look for a
module in ``sys.modules`` first, then try to import it after
acquiring an import lock. If the import lock is held by another
thread, an :exc:`ImportError` is raised.
(Contributed by Christian Heimes.)
* Several functions return information about the platform's
floating-point support. :c:func:`PyFloat_GetMax` returns
the maximum representable floating point value,
and :c:func:`PyFloat_GetMin` returns the minimum
positive value. :c:func:`PyFloat_GetInfo` returns an object
containing more information from the :file:`float.h` file, such as
``"mant_dig"`` (number of digits in the mantissa), ``"epsilon"``
(smallest difference between 1.0 and the next largest value
representable), and several others.
(Contributed by Christian Heimes; :issue:`1534`.)
* C functions and methods that use
:c:func:`PyComplex_AsCComplex` will now accept arguments that
have a :meth:`__complex__` method. In particular, the functions in the
:mod:`cmath` module will now accept objects with this method.
This is a backport of a Python 3.0 change.
(Contributed by Mark Dickinson; :issue:`1675423`.)
* Python's C API now includes two functions for case-insensitive string
comparisons, ``PyOS_stricmp(char*, char*)``
and ``PyOS_strnicmp(char*, char*, Py_ssize_t)``.
(Contributed by Christian Heimes; :issue:`1635`.)
* Many C extensions define their own little macro for adding
integers and strings to the module's dictionary in the
``init*`` function. Python 2.6 finally defines standard macros
for adding values to a module, :c:macro:`PyModule_AddStringMacro`
and :c:macro:`PyModule_AddIntMacro()`. (Contributed by
Christian Heimes.)
* Some macros were renamed in both 3.0 and 2.6 to make it clearer that
they are macros,
not functions. :c:macro:`Py_Size()` became :c:macro:`Py_SIZE()`,
:c:macro:`Py_Type()` became :c:macro:`Py_TYPE()`, and
:c:macro:`Py_Refcnt()` became :c:macro:`Py_REFCNT()`.
The mixed-case macros are still available
in Python 2.6 for backward compatibility.
(:issue:`1629`)
* Distutils now places C extensions it builds in a
different directory when running on a debug version of Python.
(Contributed by Collin Winter; :issue:`1530959`.)
* Several basic data types, such as integers and strings, maintain
internal free lists of objects that can be re-used. The data
structures for these free lists now follow a naming convention: the
variable is always named ``free_list``, the counter is always named
``numfree``, and a macro ``Py<typename>_MAXFREELIST`` is
always defined.
* A new Makefile target, "make patchcheck", prepares the Python source tree
for making a patch: it fixes trailing whitespace in all modified
``.py`` files, checks whether the documentation has been changed,
and reports whether the :file:`Misc/ACKS` and :file:`Misc/NEWS` files
have been updated.
(Contributed by Brett Cannon.)
Another new target, "make profile-opt", compiles a Python binary
using GCC's profile-guided optimization. It compiles Python with
profiling enabled, runs the test suite to obtain a set of profiling
results, and then compiles using these results for optimization.
(Contributed by Gregory P. Smith.)
.. ======================================================================
Port-Specific Changes: Windows
-----------------------------------
* The support for Windows 95, 98, ME and NT4 has been dropped.
Python 2.6 requires at least Windows 2000 SP4.
* The new default compiler on Windows is Visual Studio 2008 (version
9.0). The build directories for Visual Studio 2003 (version 7.1) and
2005 (version 8.0) were moved into the PC/ directory. The new
:file:`PCbuild` directory supports cross compilation for X64, debug
builds and Profile Guided Optimization (PGO). PGO builds are roughly
10% faster than normal builds. (Contributed by Christian Heimes
with help from Amaury Forgeot d'Arc and Martin von Loewis.)
* The :mod:`msvcrt` module now supports
both the normal and wide char variants of the console I/O
API. The :func:`getwch` function reads a keypress and returns a Unicode
value, as does the :func:`getwche` function. The :func:`putwch` function
takes a Unicode character and writes it to the console.
(Contributed by Christian Heimes.)
* :func:`os.path.expandvars` will now expand environment variables in
the form "%var%", and "~user" will be expanded into the user's home
directory path. (Contributed by Josiah Carlson; :issue:`957650`.)
* The :mod:`socket` module's socket objects now have an
:meth:`ioctl` method that provides a limited interface to the
:c:func:`WSAIoctl` system interface.
* The :mod:`_winreg` module now has a function,
:func:`ExpandEnvironmentStrings`,
that expands environment variable references such as ``%NAME%``
in an input string. The handle objects provided by this
module now support the context protocol, so they can be used
in :keyword:`with` statements. (Contributed by Christian Heimes.)
:mod:`_winreg` also has better support for x64 systems,
exposing the :func:`DisableReflectionKey`, :func:`EnableReflectionKey`,
and :func:`QueryReflectionKey` functions, which enable and disable
registry reflection for 32-bit processes running on 64-bit systems.
(:issue:`1753245`)
* The :mod:`msilib` module's :class:`Record` object
gained :meth:`GetInteger` and :meth:`GetString` methods that
return field values as an integer or a string.
(Contributed by Floris Bruynooghe; :issue:`2125`.)
.. ======================================================================
Port-Specific Changes: Mac OS X
-----------------------------------
* When compiling a framework build of Python, you can now specify the
framework name to be used by providing the
:option:`!--with-framework-name=` option to the
:program:`configure` script.
* The :mod:`macfs` module has been removed. This in turn required the
:func:`macostools.touched` function to be removed because it depended on the
:mod:`macfs` module. (:issue:`1490190`)
* Many other Mac OS modules have been deprecated and will be removed in
Python 3.0:
:mod:`_builtinSuites`,
:mod:`aepack`,
:mod:`aetools`,
:mod:`aetypes`,
:mod:`applesingle`,
:mod:`appletrawmain`,
:mod:`appletrunner`,
:mod:`argvemulator`,
:mod:`Audio_mac`,
:mod:`autoGIL`,
:mod:`Carbon`,
:mod:`cfmfile`,
:mod:`CodeWarrior`,
:mod:`ColorPicker`,
:mod:`EasyDialogs`,
:mod:`Explorer`,
:mod:`Finder`,
:mod:`FrameWork`,
:mod:`findertools`,
:mod:`ic`,
:mod:`icglue`,
:mod:`icopen`,
:mod:`macerrors`,
:mod:`MacOS`,
:mod:`macfs`,
:mod:`macostools`,
:mod:`macresource`,
:mod:`MiniAEFrame`,
:mod:`Nav`,
:mod:`Netscape`,
:mod:`OSATerminology`,
:mod:`pimp`,
:mod:`PixMapWrapper`,
:mod:`StdSuites`,
:mod:`SystemEvents`,
:mod:`Terminal`, and
:mod:`terminalcommand`.
.. ======================================================================
Port-Specific Changes: IRIX
-----------------------------------
A number of old IRIX-specific modules were deprecated and will
be removed in Python 3.0:
:mod:`al` and :mod:`AL`,
:mod:`cd`,
:mod:`cddb`,
:mod:`cdplayer`,
:mod:`CL` and :mod:`cl`,
:mod:`DEVICE`,
:mod:`ERRNO`,
:mod:`FILE`,
:mod:`FL` and :mod:`fl`,
:mod:`flp`,
:mod:`fm`,
:mod:`GET`,
:mod:`GLWS`,
:mod:`GL` and :mod:`gl`,
:mod:`IN`,
:mod:`IOCTL`,
:mod:`jpeg`,
:mod:`panelparser`,
:mod:`readcd`,
:mod:`SV` and :mod:`sv`,
:mod:`torgb`,
:mod:`videoreader`, and
:mod:`WAIT`.
.. ======================================================================
Porting to Python 2.6
=====================
This section lists previously described changes and other bugfixes
that may require changes to your code:
* Classes that aren't supposed to be hashable should
set ``__hash__ = None`` in their definitions to indicate
the fact.
* String exceptions have been removed. Attempting to use them raises a
:exc:`TypeError`.
* The :meth:`__init__` method of :class:`collections.deque`
now clears any existing contents of the deque
before adding elements from the iterable. This change makes the
behavior match ``list.__init__()``.
* :meth:`object.__init__` previously accepted arbitrary arguments and
keyword arguments, ignoring them. In Python 2.6, this is no longer
allowed and will result in a :exc:`TypeError`. This will affect
:meth:`__init__` methods that end up calling the corresponding
method on :class:`object` (perhaps through using :func:`super`).
See :issue:`1683368` for discussion.
* The :class:`Decimal` constructor now accepts leading and trailing
whitespace when passed a string. Previously it would raise an
:exc:`InvalidOperation` exception. On the other hand, the
:meth:`create_decimal` method of :class:`Context` objects now
explicitly disallows extra whitespace, raising a
:exc:`ConversionSyntax` exception.
* Due to an implementation accident, if you passed a file path to
the built-in :func:`__import__` function, it would actually import
the specified file. This was never intended to work, however, and
the implementation now explicitly checks for this case and raises
an :exc:`ImportError`.
* C API: the :c:func:`PyImport_Import` and :c:func:`PyImport_ImportModule`
functions now default to absolute imports, not relative imports.
This will affect C extensions that import other modules.
* C API: extension data types that shouldn't be hashable
should define their ``tp_hash`` slot to
:c:func:`PyObject_HashNotImplemented`.
* The :mod:`socket` module exception :exc:`socket.error` now inherits
from :exc:`IOError`. Previously it wasn't a subclass of
:exc:`StandardError` but now it is, through :exc:`IOError`.
(Implemented by Gregory P. Smith; :issue:`1706815`.)
* The :mod:`xmlrpclib` module no longer automatically converts
:class:`datetime.date` and :class:`datetime.time` to the
:class:`xmlrpclib.DateTime` type; the conversion semantics were
not necessarily correct for all applications. Code using
:mod:`xmlrpclib` should convert :class:`date` and :class:`~datetime.time`
instances. (:issue:`1330538`)
* (3.0-warning mode) The :class:`Exception` class now warns
when accessed using slicing or index access; having
:class:`Exception` behave like a tuple is being phased out.
* (3.0-warning mode) inequality comparisons between two dictionaries
or two objects that don't implement comparison methods are reported
as warnings. ``dict1 == dict2`` still works, but ``dict1 < dict2``
is being phased out.
Comparisons between cells, which are an implementation detail of Python's
scoping rules, also cause warnings because such comparisons are forbidden
entirely in 3.0.
.. ======================================================================
.. _26acks:
Acknowledgements
================
The author would like to thank the following people for offering
suggestions, corrections and assistance with various drafts of this
article: Georg Brandl, Steve Brown, Nick Coghlan, Ralph Corderoy,
Jim Jewett, Kent Johnson, Chris Lambacher, Martin Michlmayr,
Antoine Pitrou, Brian Warner.
PK
%�\l >��� �� " html/_sources/whatsnew/2.7.rst.txtnu �[��� ****************************
What's New in Python 2.7
****************************
:Author: A.M. Kuchling (amk at amk.ca)
.. hyperlink all the methods & functions.
.. T_STRING_INPLACE not described in main docs
.. $Id$
Rules for maintenance:
* Anyone can add text to this document. Do not spend very much time
on the wording of your changes, because your text will probably
get rewritten to some degree.
* The maintainer will go through Misc/NEWS periodically and add
changes; it's therefore more important to add your changes to
Misc/NEWS than to this file.
* This is not a complete list of every single change; completeness
is the purpose of Misc/NEWS. Some changes I consider too small
or esoteric to include. If such a change is added to the text,
I'll just remove it. (This is another reason you shouldn't spend
too much time on writing your addition.)
* If you want to draw your new text to the attention of the
maintainer, add 'XXX' to the beginning of the paragraph or
section.
* It's OK to just add a fragmentary note about a change. For
example: "XXX Describe the transmogrify() function added to the
socket module." The maintainer will research the change and
write the necessary text.
* You can comment out your additions if you like, but it's not
necessary (especially when a final release is some months away).
* Credit the author of a patch or bugfix. Just the name is
sufficient; the e-mail address isn't necessary.
* It's helpful to add the bug/patch number in a parenthetical comment.
XXX Describe the transmogrify() function added to the socket
module.
(Contributed by P.Y. Developer; :issue:`12345`.)
This saves the maintainer some effort going through the SVN logs
when researching a change.
This article explains the new features in Python 2.7. Python 2.7 was released
on July 3, 2010.
Numeric handling has been improved in many ways, for both
floating-point numbers and for the :class:`~decimal.Decimal` class.
There are some useful additions to the standard library, such as a
greatly enhanced :mod:`unittest` module, the :mod:`argparse` module
for parsing command-line options, convenient :class:`~collections.OrderedDict`
and :class:`~collections.Counter` classes in the :mod:`collections` module,
and many other improvements.
Python 2.7 is planned to be the last of the 2.x releases, so we worked
on making it a good release for the long term. To help with porting
to Python 3, several new features from the Python 3.x series have been
included in 2.7.
This article doesn't attempt to provide a complete specification of
the new features, but instead provides a convenient overview. For
full details, you should refer to the documentation for Python 2.7 at
https://docs.python.org. If you want to understand the rationale for
the design and implementation, refer to the PEP for a particular new
feature or the issue on https://bugs.python.org in which a change was
discussed. Whenever possible, "What's New in Python" links to the
bug/patch item for each change.
.. _whatsnew27-python31:
The Future for Python 2.x
=========================
Python 2.7 is the last major release in the 2.x series, as the Python
maintainers have shifted the focus of their new feature development efforts
to the Python 3.x series. This means that while Python 2 continues to
receive bug fixes, and to be updated to build correctly on new hardware and
versions of supported operated systems, there will be no new full feature
releases for the language or standard library.
However, while there is a large common subset between Python 2.7 and Python
3, and many of the changes involved in migrating to that common subset, or
directly to Python 3, can be safely automated, some other changes (notably
those associated with Unicode handling) may require careful consideration,
and preferably robust automated regression test suites, to migrate
effectively.
This means that Python 2.7 will remain in place for a long time, providing a
stable and supported base platform for production systems that have not yet
been ported to Python 3. The full expected lifecycle of the Python 2.7
series is detailed in :pep:`373`.
Some key consequences of the long-term significance of 2.7 are:
* As noted above, the 2.7 release has a much longer period of maintenance
when compared to earlier 2.x versions. Python 2.7 is currently expected to
remain supported by the core development team (receiving security updates
and other bug fixes) until at least 2020 (10 years after its initial
release, compared to the more typical support period of 18--24 months).
* As the Python 2.7 standard library ages, making effective use of the
Python Package Index (either directly or via a redistributor) becomes
more important for Python 2 users. In addition to a wide variety of third
party packages for various tasks, the available packages include backports
of new modules and features from the Python 3 standard library that are
compatible with Python 2, as well as various tools and libraries that can
make it easier to migrate to Python 3. The `Python Packaging User Guide
<https://packaging.python.org>`__ provides guidance on downloading and
installing software from the Python Package Index.
* While the preferred approach to enhancing Python 2 is now the publication
of new packages on the Python Package Index, this approach doesn't
necessarily work in all cases, especially those related to network
security. In exceptional cases that cannot be handled adequately by
publishing new or updated packages on PyPI, the Python Enhancement
Proposal process may be used to make the case for adding new features
directly to the Python 2 standard library. Any such additions, and the
maintenance releases where they were added, will be noted in the
:ref:`py27-maintenance-enhancements` section below.
For projects wishing to migrate from Python 2 to Python 3, or for library
and framework developers wishing to support users on both Python 2 and
Python 3, there are a variety of tools and guides available to help decide
on a suitable approach and manage some of the technical details involved.
The recommended starting point is the :ref:`pyporting-howto` HOWTO guide.
Changes to the Handling of Deprecation Warnings
===============================================
For Python 2.7, a policy decision was made to silence warnings only of
interest to developers by default. :exc:`DeprecationWarning` and its
descendants are now ignored unless otherwise requested, preventing
users from seeing warnings triggered by an application. This change
was also made in the branch that became Python 3.2. (Discussed
on stdlib-sig and carried out in :issue:`7319`.)
In previous releases, :exc:`DeprecationWarning` messages were
enabled by default, providing Python developers with a clear
indication of where their code may break in a future major version
of Python.
However, there are increasingly many users of Python-based
applications who are not directly involved in the development of
those applications. :exc:`DeprecationWarning` messages are
irrelevant to such users, making them worry about an application
that's actually working correctly and burdening application developers
with responding to these concerns.
You can re-enable display of :exc:`DeprecationWarning` messages by
running Python with the :option:`-Wdefault <-W>` (short form:
:option:`-Wd <-W>`) switch, or by setting the :envvar:`PYTHONWARNINGS`
environment variable to ``"default"`` (or ``"d"``) before running
Python. Python code can also re-enable them
by calling ``warnings.simplefilter('default')``.
The ``unittest`` module also automatically reenables deprecation warnings
when running tests.
Python 3.1 Features
=======================
Much as Python 2.6 incorporated features from Python 3.0,
version 2.7 incorporates some of the new features
in Python 3.1. The 2.x series continues to provide tools
for migrating to the 3.x series.
A partial list of 3.1 features that were backported to 2.7:
* The syntax for set literals (``{1,2,3}`` is a mutable set).
* Dictionary and set comprehensions (``{i: i*2 for i in range(3)}``).
* Multiple context managers in a single :keyword:`with` statement.
* A new version of the :mod:`io` library, rewritten in C for performance.
* The ordered-dictionary type described in :ref:`pep-0372`.
* The new ``","`` format specifier described in :ref:`pep-0378`.
* The :class:`memoryview` object.
* A small subset of the :mod:`importlib` module,
`described below <#importlib-section>`__.
* The :func:`repr` of a float ``x`` is shorter in many cases: it's now
based on the shortest decimal string that's guaranteed to round back
to ``x``. As in previous versions of Python, it's guaranteed that
``float(repr(x))`` recovers ``x``.
* Float-to-string and string-to-float conversions are correctly rounded.
The :func:`round` function is also now correctly rounded.
* The :c:type:`PyCapsule` type, used to provide a C API for extension modules.
* The :c:func:`PyLong_AsLongAndOverflow` C API function.
Other new Python3-mode warnings include:
* :func:`operator.isCallable` and :func:`operator.sequenceIncludes`,
which are not supported in 3.x, now trigger warnings.
* The :option:`-3` switch now automatically
enables the :option:`-Qwarn <-Q>` switch that causes warnings
about using classic division with integers and long integers.
.. ========================================================================
.. Large, PEP-level features and changes should be described here.
.. ========================================================================
.. _pep-0372:
PEP 372: Adding an Ordered Dictionary to collections
====================================================
Regular Python dictionaries iterate over key/value pairs in arbitrary order.
Over the years, a number of authors have written alternative implementations
that remember the order that the keys were originally inserted. Based on
the experiences from those implementations, 2.7 introduces a new
:class:`~collections.OrderedDict` class in the :mod:`collections` module.
The :class:`~collections.OrderedDict` API provides the same interface as regular
dictionaries but iterates over keys and values in a guaranteed order
depending on when a key was first inserted::
>>> from collections import OrderedDict
>>> d = OrderedDict([('first', 1),
... ('second', 2),
... ('third', 3)])
>>> d.items()
[('first', 1), ('second', 2), ('third', 3)]
If a new entry overwrites an existing entry, the original insertion
position is left unchanged::
>>> d['second'] = 4
>>> d.items()
[('first', 1), ('second', 4), ('third', 3)]
Deleting an entry and reinserting it will move it to the end::
>>> del d['second']
>>> d['second'] = 5
>>> d.items()
[('first', 1), ('third', 3), ('second', 5)]
The :meth:`~collections.OrderedDict.popitem` method has an optional *last*
argument that defaults to ``True``. If *last* is true, the most recently
added key is returned and removed; if it's false, the
oldest key is selected::
>>> od = OrderedDict([(x,0) for x in range(20)])
>>> od.popitem()
(19, 0)
>>> od.popitem()
(18, 0)
>>> od.popitem(last=False)
(0, 0)
>>> od.popitem(last=False)
(1, 0)
Comparing two ordered dictionaries checks both the keys and values,
and requires that the insertion order was the same::
>>> od1 = OrderedDict([('first', 1),
... ('second', 2),
... ('third', 3)])
>>> od2 = OrderedDict([('third', 3),
... ('first', 1),
... ('second', 2)])
>>> od1 == od2
False
>>> # Move 'third' key to the end
>>> del od2['third']; od2['third'] = 3
>>> od1 == od2
True
Comparing an :class:`~collections.OrderedDict` with a regular dictionary
ignores the insertion order and just compares the keys and values.
How does the :class:`~collections.OrderedDict` work? It maintains a
doubly-linked list of keys, appending new keys to the list as they're inserted.
A secondary dictionary maps keys to their corresponding list node, so
deletion doesn't have to traverse the entire linked list and therefore
remains O(1).
The standard library now supports use of ordered dictionaries in several
modules.
* The :mod:`ConfigParser` module uses them by default, meaning that
configuration files can now be read, modified, and then written back
in their original order.
* The :meth:`~collections.somenamedtuple._asdict()` method for
:func:`collections.namedtuple` now returns an ordered dictionary with the
values appearing in the same order as the underlying tuple indices.
* The :mod:`json` module's :class:`~json.JSONDecoder` class
constructor was extended with an *object_pairs_hook* parameter to
allow :class:`OrderedDict` instances to be built by the decoder.
Support was also added for third-party tools like
`PyYAML <http://pyyaml.org/>`_.
.. seealso::
:pep:`372` - Adding an ordered dictionary to collections
PEP written by Armin Ronacher and Raymond Hettinger;
implemented by Raymond Hettinger.
.. _pep-0378:
PEP 378: Format Specifier for Thousands Separator
=================================================
To make program output more readable, it can be useful to add
separators to large numbers, rendering them as
18,446,744,073,709,551,616 instead of 18446744073709551616.
The fully general solution for doing this is the :mod:`locale` module,
which can use different separators ("," in North America, "." in
Europe) and different grouping sizes, but :mod:`locale` is complicated
to use and unsuitable for multi-threaded applications where different
threads are producing output for different locales.
Therefore, a simple comma-grouping mechanism has been added to the
mini-language used by the :meth:`str.format` method. When
formatting a floating-point number, simply include a comma between the
width and the precision::
>>> '{:20,.2f}'.format(18446744073709551616.0)
'18,446,744,073,709,551,616.00'
When formatting an integer, include the comma after the width:
>>> '{:20,d}'.format(18446744073709551616)
'18,446,744,073,709,551,616'
This mechanism is not adaptable at all; commas are always used as the
separator and the grouping is always into three-digit groups. The
comma-formatting mechanism isn't as general as the :mod:`locale`
module, but it's easier to use.
.. seealso::
:pep:`378` - Format Specifier for Thousands Separator
PEP written by Raymond Hettinger; implemented by Eric Smith.
PEP 389: The argparse Module for Parsing Command Lines
======================================================
The :mod:`argparse` module for parsing command-line arguments was
added as a more powerful replacement for the
:mod:`optparse` module.
This means Python now supports three different modules for parsing
command-line arguments: :mod:`getopt`, :mod:`optparse`, and
:mod:`argparse`. The :mod:`getopt` module closely resembles the C
library's :c:func:`getopt` function, so it remains useful if you're writing a
Python prototype that will eventually be rewritten in C.
:mod:`optparse` becomes redundant, but there are no plans to remove it
because there are many scripts still using it, and there's no
automated way to update these scripts. (Making the :mod:`argparse`
API consistent with :mod:`optparse`'s interface was discussed but
rejected as too messy and difficult.)
In short, if you're writing a new script and don't need to worry
about compatibility with earlier versions of Python, use
:mod:`argparse` instead of :mod:`optparse`.
Here's an example::
import argparse
parser = argparse.ArgumentParser(description='Command-line example.')
# Add optional switches
parser.add_argument('-v', action='store_true', dest='is_verbose',
help='produce verbose output')
parser.add_argument('-o', action='store', dest='output',
metavar='FILE',
help='direct output to FILE instead of stdout')
parser.add_argument('-C', action='store', type=int, dest='context',
metavar='NUM', default=0,
help='display NUM lines of added context')
# Allow any number of additional arguments.
parser.add_argument(nargs='*', action='store', dest='inputs',
help='input filenames (default is stdin)')
args = parser.parse_args()
print args.__dict__
Unless you override it, :option:`!-h` and :option:`!--help` switches
are automatically added, and produce neatly formatted output::
-> ./python.exe argparse-example.py --help
usage: argparse-example.py [-h] [-v] [-o FILE] [-C NUM] [inputs [inputs ...]]
Command-line example.
positional arguments:
inputs input filenames (default is stdin)
optional arguments:
-h, --help show this help message and exit
-v produce verbose output
-o FILE direct output to FILE instead of stdout
-C NUM display NUM lines of added context
As with :mod:`optparse`, the command-line switches and arguments
are returned as an object with attributes named by the *dest* parameters::
-> ./python.exe argparse-example.py -v
{'output': None,
'is_verbose': True,
'context': 0,
'inputs': []}
-> ./python.exe argparse-example.py -v -o /tmp/output -C 4 file1 file2
{'output': '/tmp/output',
'is_verbose': True,
'context': 4,
'inputs': ['file1', 'file2']}
:mod:`argparse` has much fancier validation than :mod:`optparse`; you
can specify an exact number of arguments as an integer, 0 or more
arguments by passing ``'*'``, 1 or more by passing ``'+'``, or an
optional argument with ``'?'``. A top-level parser can contain
sub-parsers to define subcommands that have different sets of
switches, as in ``svn commit``, ``svn checkout``, etc. You can
specify an argument's type as :class:`~argparse.FileType`, which will
automatically open files for you and understands that ``'-'`` means
standard input or output.
.. seealso::
:mod:`argparse` documentation
The documentation page of the argparse module.
:ref:`argparse-from-optparse`
Part of the Python documentation, describing how to convert
code that uses :mod:`optparse`.
:pep:`389` - argparse - New Command Line Parsing Module
PEP written and implemented by Steven Bethard.
PEP 391: Dictionary-Based Configuration For Logging
====================================================
The :mod:`logging` module is very flexible; applications can define
a tree of logging subsystems, and each logger in this tree can filter
out certain messages, format them differently, and direct messages to
a varying number of handlers.
All this flexibility can require a lot of configuration. You can
write Python statements to create objects and set their properties,
but a complex set-up requires verbose but boring code.
:mod:`logging` also supports a :func:`~logging.fileConfig`
function that parses a file, but the file format doesn't support
configuring filters, and it's messier to generate programmatically.
Python 2.7 adds a :func:`~logging.dictConfig` function that
uses a dictionary to configure logging. There are many ways to
produce a dictionary from different sources: construct one with code;
parse a file containing JSON; or use a YAML parsing library if one is
installed. For more information see :ref:`logging-config-api`.
The following example configures two loggers, the root logger and a
logger named "network". Messages sent to the root logger will be
sent to the system log using the syslog protocol, and messages
to the "network" logger will be written to a :file:`network.log` file
that will be rotated once the log reaches 1MB.
::
import logging
import logging.config
configdict = {
'version': 1, # Configuration schema in use; must be 1 for now
'formatters': {
'standard': {
'format': ('%(asctime)s %(name)-15s '
'%(levelname)-8s %(message)s')}},
'handlers': {'netlog': {'backupCount': 10,
'class': 'logging.handlers.RotatingFileHandler',
'filename': '/logs/network.log',
'formatter': 'standard',
'level': 'INFO',
'maxBytes': 1000000},
'syslog': {'class': 'logging.handlers.SysLogHandler',
'formatter': 'standard',
'level': 'ERROR'}},
# Specify all the subordinate loggers
'loggers': {
'network': {
'handlers': ['netlog']
}
},
# Specify properties of the root logger
'root': {
'handlers': ['syslog']
},
}
# Set up configuration
logging.config.dictConfig(configdict)
# As an example, log two error messages
logger = logging.getLogger('/')
logger.error('Database not found')
netlogger = logging.getLogger('network')
netlogger.error('Connection failed')
Three smaller enhancements to the :mod:`logging` module, all
implemented by Vinay Sajip, are:
.. rev79293
* The :class:`~logging.handlers.SysLogHandler` class now supports
syslogging over TCP. The constructor has a *socktype* parameter
giving the type of socket to use, either :const:`socket.SOCK_DGRAM`
for UDP or :const:`socket.SOCK_STREAM` for TCP. The default
protocol remains UDP.
* :class:`~logging.Logger` instances gained a :meth:`~logging.Logger.getChild`
method that retrieves a descendant logger using a relative path.
For example, once you retrieve a logger by doing ``log = getLogger('app')``,
calling ``log.getChild('network.listen')`` is equivalent to
``getLogger('app.network.listen')``.
* The :class:`~logging.LoggerAdapter` class gained an
:meth:`~logging.LoggerAdapter.isEnabledFor` method that takes a
*level* and returns whether the underlying logger would
process a message of that level of importance.
.. XXX: Logger objects don't have a class declaration so the link don't work
.. seealso::
:pep:`391` - Dictionary-Based Configuration For Logging
PEP written and implemented by Vinay Sajip.
PEP 3106: Dictionary Views
====================================================
The dictionary methods :meth:`~dict.keys`, :meth:`~dict.values`, and
:meth:`~dict.items` are different in Python 3.x. They return an object
called a :dfn:`view` instead of a fully materialized list.
It's not possible to change the return values of :meth:`~dict.keys`,
:meth:`~dict.values`, and :meth:`~dict.items` in Python 2.7 because
too much code would break. Instead the 3.x versions were added
under the new names :meth:`~dict.viewkeys`, :meth:`~dict.viewvalues`,
and :meth:`~dict.viewitems`.
::
>>> d = dict((i*10, chr(65+i)) for i in range(26))
>>> d
{0: 'A', 130: 'N', 10: 'B', 140: 'O', 20: ..., 250: 'Z'}
>>> d.viewkeys()
dict_keys([0, 130, 10, 140, 20, 150, 30, ..., 250])
Views can be iterated over, but the key and item views also behave
like sets. The ``&`` operator performs intersection, and ``|``
performs a union::
>>> d1 = dict((i*10, chr(65+i)) for i in range(26))
>>> d2 = dict((i**.5, i) for i in range(1000))
>>> d1.viewkeys() & d2.viewkeys()
set([0.0, 10.0, 20.0, 30.0])
>>> d1.viewkeys() | range(0, 30)
set([0, 1, 130, 3, 4, 5, 6, ..., 120, 250])
The view keeps track of the dictionary and its contents change as the
dictionary is modified::
>>> vk = d.viewkeys()
>>> vk
dict_keys([0, 130, 10, ..., 250])
>>> d[260] = '&'
>>> vk
dict_keys([0, 130, 260, 10, ..., 250])
However, note that you can't add or remove keys while you're iterating
over the view::
>>> for k in vk:
... d[k*2] = k
...
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
RuntimeError: dictionary changed size during iteration
You can use the view methods in Python 2.x code, and the 2to3
converter will change them to the standard :meth:`~dict.keys`,
:meth:`~dict.values`, and :meth:`~dict.items` methods.
.. seealso::
:pep:`3106` - Revamping dict.keys(), .values() and .items()
PEP written by Guido van Rossum.
Backported to 2.7 by Alexandre Vassalotti; :issue:`1967`.
PEP 3137: The memoryview Object
====================================================
The :class:`memoryview` object provides a view of another object's
memory content that matches the :class:`bytes` type's interface.
>>> import string
>>> m = memoryview(string.letters)
>>> m
<memory at 0x37f850>
>>> len(m) # Returns length of underlying object
52
>>> m[0], m[25], m[26] # Indexing returns one byte
('a', 'z', 'A')
>>> m2 = m[0:26] # Slicing returns another memoryview
>>> m2
<memory at 0x37f080>
The content of the view can be converted to a string of bytes or
a list of integers:
>>> m2.tobytes()
'abcdefghijklmnopqrstuvwxyz'
>>> m2.tolist()
[97, 98, 99, 100, 101, 102, 103, ... 121, 122]
>>>
:class:`memoryview` objects allow modifying the underlying object if
it's a mutable object.
>>> m2[0] = 75
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: cannot modify read-only memory
>>> b = bytearray(string.letters) # Creating a mutable object
>>> b
bytearray(b'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ')
>>> mb = memoryview(b)
>>> mb[0] = '*' # Assign to view, changing the bytearray.
>>> b[0:5] # The bytearray has been changed.
bytearray(b'*bcde')
>>>
.. seealso::
:pep:`3137` - Immutable Bytes and Mutable Buffer
PEP written by Guido van Rossum.
Implemented by Travis Oliphant, Antoine Pitrou and others.
Backported to 2.7 by Antoine Pitrou; :issue:`2396`.
Other Language Changes
======================
Some smaller changes made to the core Python language are:
* The syntax for set literals has been backported from Python 3.x.
Curly brackets are used to surround the contents of the resulting
mutable set; set literals are
distinguished from dictionaries by not containing colons and values.
``{}`` continues to represent an empty dictionary; use
``set()`` for an empty set.
>>> {1, 2, 3, 4, 5}
set([1, 2, 3, 4, 5])
>>> set() # empty set
set([])
>>> {} # empty dict
{}
Backported by Alexandre Vassalotti; :issue:`2335`.
* Dictionary and set comprehensions are another feature backported from
3.x, generalizing list/generator comprehensions to use
the literal syntax for sets and dictionaries.
>>> {x: x*x for x in range(6)}
{0: 0, 1: 1, 2: 4, 3: 9, 4: 16, 5: 25}
>>> {('a'*x) for x in range(6)}
set(['', 'a', 'aa', 'aaa', 'aaaa', 'aaaaa'])
Backported by Alexandre Vassalotti; :issue:`2333`.
* The :keyword:`with` statement can now use multiple context managers
in one statement. Context managers are processed from left to right
and each one is treated as beginning a new :keyword:`with` statement.
This means that::
with A() as a, B() as b:
... suite of statements ...
is equivalent to::
with A() as a:
with B() as b:
... suite of statements ...
The :func:`contextlib.nested` function provides a very similar
function, so it's no longer necessary and has been deprecated.
(Proposed in https://codereview.appspot.com/53094; implemented by
Georg Brandl.)
* Conversions between floating-point numbers and strings are
now correctly rounded on most platforms. These conversions occur
in many different places: :func:`str` on
floats and complex numbers; the :class:`float` and :class:`complex`
constructors;
numeric formatting; serializing and
deserializing floats and complex numbers using the
:mod:`marshal`, :mod:`pickle`
and :mod:`json` modules;
parsing of float and imaginary literals in Python code;
and :class:`~decimal.Decimal`-to-float conversion.
Related to this, the :func:`repr` of a floating-point number *x*
now returns a result based on the shortest decimal string that's
guaranteed to round back to *x* under correct rounding (with
round-half-to-even rounding mode). Previously it gave a string
based on rounding x to 17 decimal digits.
.. maybe add an example?
The rounding library responsible for this improvement works on
Windows and on Unix platforms using the gcc, icc, or suncc
compilers. There may be a small number of platforms where correct
operation of this code cannot be guaranteed, so the code is not
used on such systems. You can find out which code is being used
by checking :data:`sys.float_repr_style`, which will be ``short``
if the new code is in use and ``legacy`` if it isn't.
Implemented by Eric Smith and Mark Dickinson, using David Gay's
:file:`dtoa.c` library; :issue:`7117`.
* Conversions from long integers and regular integers to floating
point now round differently, returning the floating-point number
closest to the number. This doesn't matter for small integers that
can be converted exactly, but for large numbers that will
unavoidably lose precision, Python 2.7 now approximates more
closely. For example, Python 2.6 computed the following::
>>> n = 295147905179352891391
>>> float(n)
2.9514790517935283e+20
>>> n - long(float(n))
65535L
Python 2.7's floating-point result is larger, but much closer to the
true value::
>>> n = 295147905179352891391
>>> float(n)
2.9514790517935289e+20
>>> n - long(float(n))
-1L
(Implemented by Mark Dickinson; :issue:`3166`.)
Integer division is also more accurate in its rounding behaviours. (Also
implemented by Mark Dickinson; :issue:`1811`.)
* Implicit coercion for complex numbers has been removed; the interpreter
will no longer ever attempt to call a :meth:`__coerce__` method on complex
objects. (Removed by Meador Inge and Mark Dickinson; :issue:`5211`.)
* The :meth:`str.format` method now supports automatic numbering of the replacement
fields. This makes using :meth:`str.format` more closely resemble using
``%s`` formatting::
>>> '{}:{}:{}'.format(2009, 04, 'Sunday')
'2009:4:Sunday'
>>> '{}:{}:{day}'.format(2009, 4, day='Sunday')
'2009:4:Sunday'
The auto-numbering takes the fields from left to right, so the first ``{...}``
specifier will use the first argument to :meth:`str.format`, the next
specifier will use the next argument, and so on. You can't mix auto-numbering
and explicit numbering -- either number all of your specifier fields or none
of them -- but you can mix auto-numbering and named fields, as in the second
example above. (Contributed by Eric Smith; :issue:`5237`.)
Complex numbers now correctly support usage with :func:`format`,
and default to being right-aligned.
Specifying a precision or comma-separation applies to both the real
and imaginary parts of the number, but a specified field width and
alignment is applied to the whole of the resulting ``1.5+3j``
output. (Contributed by Eric Smith; :issue:`1588` and :issue:`7988`.)
The 'F' format code now always formats its output using uppercase characters,
so it will now produce 'INF' and 'NAN'.
(Contributed by Eric Smith; :issue:`3382`.)
A low-level change: the :meth:`object.__format__` method now triggers
a :exc:`PendingDeprecationWarning` if it's passed a format string,
because the :meth:`__format__` method for :class:`object` converts
the object to a string representation and formats that. Previously
the method silently applied the format string to the string
representation, but that could hide mistakes in Python code. If
you're supplying formatting information such as an alignment or
precision, presumably you're expecting the formatting to be applied
in some object-specific way. (Fixed by Eric Smith; :issue:`7994`.)
* The :func:`int` and :func:`long` types gained a ``bit_length``
method that returns the number of bits necessary to represent
its argument in binary::
>>> n = 37
>>> bin(n)
'0b100101'
>>> n.bit_length()
6
>>> n = 2**123-1
>>> n.bit_length()
123
>>> (n+1).bit_length()
124
(Contributed by Fredrik Johansson and Victor Stinner; :issue:`3439`.)
* The :keyword:`import` statement will no longer try an absolute import
if a relative import (e.g. ``from .os import sep``) fails. This
fixes a bug, but could possibly break certain :keyword:`import`
statements that were only working by accident. (Fixed by Meador Inge;
:issue:`7902`.)
* It's now possible for a subclass of the built-in :class:`unicode` type
to override the :meth:`__unicode__` method. (Implemented by
Victor Stinner; :issue:`1583863`.)
* The :class:`bytearray` type's :meth:`~bytearray.translate` method now accepts
``None`` as its first argument. (Fixed by Georg Brandl;
:issue:`4759`.)
.. XXX bytearray doesn't seem to be documented
* When using ``@classmethod`` and ``@staticmethod`` to wrap
methods as class or static methods, the wrapper object now
exposes the wrapped function as their :attr:`__func__` attribute.
(Contributed by Amaury Forgeot d'Arc, after a suggestion by
George Sakkis; :issue:`5982`.)
* When a restricted set of attributes were set using ``__slots__``,
deleting an unset attribute would not raise :exc:`AttributeError`
as you would expect. Fixed by Benjamin Peterson; :issue:`7604`.)
* Two new encodings are now supported: "cp720", used primarily for
Arabic text; and "cp858", a variant of CP 850 that adds the euro
symbol. (CP720 contributed by Alexander Belchenko and Amaury
Forgeot d'Arc in :issue:`1616979`; CP858 contributed by Tim Hatch in
:issue:`8016`.)
* The :class:`file` object will now set the :attr:`filename` attribute
on the :exc:`IOError` exception when trying to open a directory
on POSIX platforms (noted by Jan Kaliszewski; :issue:`4764`), and
now explicitly checks for and forbids writing to read-only file objects
instead of trusting the C library to catch and report the error
(fixed by Stefan Krah; :issue:`5677`).
* The Python tokenizer now translates line endings itself, so the
:func:`compile` built-in function now accepts code using any
line-ending convention. Additionally, it no longer requires that the
code end in a newline.
* Extra parentheses in function definitions are illegal in Python 3.x,
meaning that you get a syntax error from ``def f((x)): pass``. In
Python3-warning mode, Python 2.7 will now warn about this odd usage.
(Noted by James Lingard; :issue:`7362`.)
* It's now possible to create weak references to old-style class
objects. New-style classes were always weak-referenceable. (Fixed
by Antoine Pitrou; :issue:`8268`.)
* When a module object is garbage-collected, the module's dictionary is
now only cleared if no one else is holding a reference to the
dictionary (:issue:`7140`).
.. ======================================================================
.. _new-27-interpreter:
Interpreter Changes
-------------------------------
A new environment variable, :envvar:`PYTHONWARNINGS`,
allows controlling warnings. It should be set to a string
containing warning settings, equivalent to those
used with the :option:`-W` switch, separated by commas.
(Contributed by Brian Curtin; :issue:`7301`.)
For example, the following setting will print warnings every time
they occur, but turn warnings from the :mod:`Cookie` module into an
error. (The exact syntax for setting an environment variable varies
across operating systems and shells.)
::
export PYTHONWARNINGS=all,error:::Cookie:0
.. ======================================================================
Optimizations
-------------
Several performance enhancements have been added:
* A new opcode was added to perform the initial setup for
:keyword:`with` statements, looking up the :meth:`__enter__` and
:meth:`__exit__` methods. (Contributed by Benjamin Peterson.)
* The garbage collector now performs better for one common usage
pattern: when many objects are being allocated without deallocating
any of them. This would previously take quadratic
time for garbage collection, but now the number of full garbage collections
is reduced as the number of objects on the heap grows.
The new logic only performs a full garbage collection pass when
the middle generation has been collected 10 times and when the
number of survivor objects from the middle generation exceeds 10% of
the number of objects in the oldest generation. (Suggested by Martin
von Löwis and implemented by Antoine Pitrou; :issue:`4074`.)
* The garbage collector tries to avoid tracking simple containers
which can't be part of a cycle. In Python 2.7, this is now true for
tuples and dicts containing atomic types (such as ints, strings,
etc.). Transitively, a dict containing tuples of atomic types won't
be tracked either. This helps reduce the cost of each
garbage collection by decreasing the number of objects to be
considered and traversed by the collector.
(Contributed by Antoine Pitrou; :issue:`4688`.)
* Long integers are now stored internally either in base 2**15 or in base
2**30, the base being determined at build time. Previously, they
were always stored in base 2**15. Using base 2**30 gives
significant performance improvements on 64-bit machines, but
benchmark results on 32-bit machines have been mixed. Therefore,
the default is to use base 2**30 on 64-bit machines and base 2**15
on 32-bit machines; on Unix, there's a new configure option
:option:`!--enable-big-digits` that can be used to override this default.
Apart from the performance improvements this change should be
invisible to end users, with one exception: for testing and
debugging purposes there's a new structseq :data:`sys.long_info` that
provides information about the internal format, giving the number of
bits per digit and the size in bytes of the C type used to store
each digit::
>>> import sys
>>> sys.long_info
sys.long_info(bits_per_digit=30, sizeof_digit=4)
(Contributed by Mark Dickinson; :issue:`4258`.)
Another set of changes made long objects a few bytes smaller: 2 bytes
smaller on 32-bit systems and 6 bytes on 64-bit.
(Contributed by Mark Dickinson; :issue:`5260`.)
* The division algorithm for long integers has been made faster
by tightening the inner loop, doing shifts instead of multiplications,
and fixing an unnecessary extra iteration.
Various benchmarks show speedups of between 50% and 150% for long
integer divisions and modulo operations.
(Contributed by Mark Dickinson; :issue:`5512`.)
Bitwise operations are also significantly faster (initial patch by
Gregory Smith; :issue:`1087418`).
* The implementation of ``%`` checks for the left-side operand being
a Python string and special-cases it; this results in a 1--3%
performance increase for applications that frequently use ``%``
with strings, such as templating libraries.
(Implemented by Collin Winter; :issue:`5176`.)
* List comprehensions with an ``if`` condition are compiled into
faster bytecode. (Patch by Antoine Pitrou, back-ported to 2.7
by Jeffrey Yasskin; :issue:`4715`.)
* Converting an integer or long integer to a decimal string was made
faster by special-casing base 10 instead of using a generalized
conversion function that supports arbitrary bases.
(Patch by Gawain Bolton; :issue:`6713`.)
* The :meth:`split`, :meth:`replace`, :meth:`rindex`,
:meth:`rpartition`, and :meth:`rsplit` methods of string-like types
(strings, Unicode strings, and :class:`bytearray` objects) now use a
fast reverse-search algorithm instead of a character-by-character
scan. This is sometimes faster by a factor of 10. (Added by
Florent Xicluna; :issue:`7462` and :issue:`7622`.)
* The :mod:`pickle` and :mod:`cPickle` modules now automatically
intern the strings used for attribute names, reducing memory usage
of the objects resulting from unpickling. (Contributed by Jake
McGuire; :issue:`5084`.)
* The :mod:`cPickle` module now special-cases dictionaries,
nearly halving the time required to pickle them.
(Contributed by Collin Winter; :issue:`5670`.)
.. ======================================================================
New and Improved Modules
========================
As in every release, Python's standard library received a number of
enhancements and bug fixes. Here's a partial list of the most notable
changes, sorted alphabetically by module name. Consult the
:file:`Misc/NEWS` file in the source tree for a more complete list of
changes, or look through the Subversion logs for all the details.
* The :mod:`bdb` module's base debugging class :class:`~bdb.Bdb`
gained a feature for skipping modules. The constructor
now takes an iterable containing glob-style patterns such as
``django.*``; the debugger will not step into stack frames
from a module that matches one of these patterns.
(Contributed by Maru Newby after a suggestion by
Senthil Kumaran; :issue:`5142`.)
* The :mod:`binascii` module now supports the buffer API, so it can be
used with :class:`memoryview` instances and other similar buffer objects.
(Backported from 3.x by Florent Xicluna; :issue:`7703`.)
* Updated module: the :mod:`bsddb` module has been updated from 4.7.2devel9
to version 4.8.4 of
`the pybsddb package <https://www.jcea.es/programacion/pybsddb.htm>`__.
The new version features better Python 3.x compatibility, various bug fixes,
and adds several new BerkeleyDB flags and methods.
(Updated by Jesús Cea Avión; :issue:`8156`. The pybsddb
changelog can be read at http://hg.jcea.es/pybsddb/file/tip/ChangeLog.)
* The :mod:`bz2` module's :class:`~bz2.BZ2File` now supports the context
management protocol, so you can write ``with bz2.BZ2File(...) as f:``.
(Contributed by Hagen Fürstenau; :issue:`3860`.)
* New class: the :class:`~collections.Counter` class in the :mod:`collections`
module is useful for tallying data. :class:`~collections.Counter` instances
behave mostly like dictionaries but return zero for missing keys instead of
raising a :exc:`KeyError`:
.. doctest::
:options: +NORMALIZE_WHITESPACE
>>> from collections import Counter
>>> c = Counter()
>>> for letter in 'here is a sample of english text':
... c[letter] += 1
...
>>> c
Counter({' ': 6, 'e': 5, 's': 3, 'a': 2, 'i': 2, 'h': 2,
'l': 2, 't': 2, 'g': 1, 'f': 1, 'm': 1, 'o': 1, 'n': 1,
'p': 1, 'r': 1, 'x': 1})
>>> c['e']
5
>>> c['z']
0
There are three additional :class:`~collections.Counter` methods.
:meth:`~collections.Counter.most_common` returns the N most common
elements and their counts. :meth:`~collections.Counter.elements`
returns an iterator over the contained elements, repeating each
element as many times as its count.
:meth:`~collections.Counter.subtract` takes an iterable and
subtracts one for each element instead of adding; if the argument is
a dictionary or another :class:`Counter`, the counts are
subtracted. ::
>>> c.most_common(5)
[(' ', 6), ('e', 5), ('s', 3), ('a', 2), ('i', 2)]
>>> c.elements() ->
'a', 'a', ' ', ' ', ' ', ' ', ' ', ' ',
'e', 'e', 'e', 'e', 'e', 'g', 'f', 'i', 'i',
'h', 'h', 'm', 'l', 'l', 'o', 'n', 'p', 's',
's', 's', 'r', 't', 't', 'x'
>>> c['e']
5
>>> c.subtract('very heavy on the letter e')
>>> c['e'] # Count is now lower
-1
Contributed by Raymond Hettinger; :issue:`1696199`.
.. revision 79660
New class: :class:`~collections.OrderedDict` is described in the earlier
section :ref:`pep-0372`.
New method: The :class:`~collections.deque` data type now has a
:meth:`~collections.deque.count` method that returns the number of
contained elements equal to the supplied argument *x*, and a
:meth:`~collections.deque.reverse` method that reverses the elements
of the deque in-place. :class:`~collections.deque` also exposes its maximum
length as the read-only :attr:`~collections.deque.maxlen` attribute.
(Both features added by Raymond Hettinger.)
The :class:`~collections.namedtuple` class now has an optional *rename* parameter.
If *rename* is true, field names that are invalid because they've
been repeated or aren't legal Python identifiers will be
renamed to legal names that are derived from the field's
position within the list of fields:
>>> from collections import namedtuple
>>> T = namedtuple('T', ['field1', '$illegal', 'for', 'field2'], rename=True)
>>> T._fields
('field1', '_1', '_2', 'field2')
(Added by Raymond Hettinger; :issue:`1818`.)
Finally, the :class:`~collections.Mapping` abstract base class now
returns :const:`NotImplemented` if a mapping is compared to
another type that isn't a :class:`Mapping`.
(Fixed by Daniel Stutzbach; :issue:`8729`.)
* Constructors for the parsing classes in the :mod:`ConfigParser` module now
take an *allow_no_value* parameter, defaulting to false; if true,
options without values will be allowed. For example::
>>> import ConfigParser, StringIO
>>> sample_config = """
... [mysqld]
... user = mysql
... pid-file = /var/run/mysqld/mysqld.pid
... skip-bdb
... """
>>> config = ConfigParser.RawConfigParser(allow_no_value=True)
>>> config.readfp(StringIO.StringIO(sample_config))
>>> config.get('mysqld', 'user')
'mysql'
>>> print config.get('mysqld', 'skip-bdb')
None
>>> print config.get('mysqld', 'unknown')
Traceback (most recent call last):
...
NoOptionError: No option 'unknown' in section: 'mysqld'
(Contributed by Mats Kindahl; :issue:`7005`.)
* Deprecated function: :func:`contextlib.nested`, which allows
handling more than one context manager with a single :keyword:`with`
statement, has been deprecated, because the :keyword:`with` statement
now supports multiple context managers.
* The :mod:`cookielib` module now ignores cookies that have an invalid
version field, one that doesn't contain an integer value. (Fixed by
John J. Lee; :issue:`3924`.)
* The :mod:`copy` module's :func:`~copy.deepcopy` function will now
correctly copy bound instance methods. (Implemented by
Robert Collins; :issue:`1515`.)
* The :mod:`ctypes` module now always converts ``None`` to a C NULL
pointer for arguments declared as pointers. (Changed by Thomas
Heller; :issue:`4606`.) The underlying `libffi library
<https://sourceware.org/libffi/>`__ has been updated to version
3.0.9, containing various fixes for different platforms. (Updated
by Matthias Klose; :issue:`8142`.)
* New method: the :mod:`datetime` module's :class:`~datetime.timedelta` class
gained a :meth:`~datetime.timedelta.total_seconds` method that returns the
number of seconds in the duration. (Contributed by Brian Quinlan; :issue:`5788`.)
* New method: the :class:`~decimal.Decimal` class gained a
:meth:`~decimal.Decimal.from_float` class method that performs an exact
conversion of a floating-point number to a :class:`~decimal.Decimal`.
This exact conversion strives for the
closest decimal approximation to the floating-point representation's value;
the resulting decimal value will therefore still include the inaccuracy,
if any.
For example, ``Decimal.from_float(0.1)`` returns
``Decimal('0.1000000000000000055511151231257827021181583404541015625')``.
(Implemented by Raymond Hettinger; :issue:`4796`.)
Comparing instances of :class:`~decimal.Decimal` with floating-point
numbers now produces sensible results based on the numeric values
of the operands. Previously such comparisons would fall back to
Python's default rules for comparing objects, which produced arbitrary
results based on their type. Note that you still cannot combine
:class:`Decimal` and floating-point in other operations such as addition,
since you should be explicitly choosing how to convert between float and
:class:`~decimal.Decimal`. (Fixed by Mark Dickinson; :issue:`2531`.)
The constructor for :class:`~decimal.Decimal` now accepts
floating-point numbers (added by Raymond Hettinger; :issue:`8257`)
and non-European Unicode characters such as Arabic-Indic digits
(contributed by Mark Dickinson; :issue:`6595`).
Most of the methods of the :class:`~decimal.Context` class now accept integers
as well as :class:`~decimal.Decimal` instances; the only exceptions are the
:meth:`~decimal.Context.canonical` and :meth:`~decimal.Context.is_canonical`
methods. (Patch by Juan José Conti; :issue:`7633`.)
When using :class:`~decimal.Decimal` instances with a string's
:meth:`~str.format` method, the default alignment was previously
left-alignment. This has been changed to right-alignment, which is
more sensible for numeric types. (Changed by Mark Dickinson; :issue:`6857`.)
Comparisons involving a signaling NaN value (or ``sNAN``) now signal
:const:`InvalidOperation` instead of silently returning a true or
false value depending on the comparison operator. Quiet NaN values
(or ``NaN``) are now hashable. (Fixed by Mark Dickinson;
:issue:`7279`.)
* The :mod:`difflib` module now produces output that is more
compatible with modern :command:`diff`/:command:`patch` tools
through one small change, using a tab character instead of spaces as
a separator in the header giving the filename. (Fixed by Anatoly
Techtonik; :issue:`7585`.)
* The Distutils ``sdist`` command now always regenerates the
:file:`MANIFEST` file, since even if the :file:`MANIFEST.in` or
:file:`setup.py` files haven't been modified, the user might have
created some new files that should be included.
(Fixed by Tarek Ziadé; :issue:`8688`.)
* The :mod:`doctest` module's :const:`IGNORE_EXCEPTION_DETAIL` flag
will now ignore the name of the module containing the exception
being tested. (Patch by Lennart Regebro; :issue:`7490`.)
* The :mod:`email` module's :class:`~email.message.Message` class will
now accept a Unicode-valued payload, automatically converting the
payload to the encoding specified by :attr:`output_charset`.
(Added by R. David Murray; :issue:`1368247`.)
* The :class:`~fractions.Fraction` class now accepts a single float or
:class:`~decimal.Decimal` instance, or two rational numbers, as
arguments to its constructor. (Implemented by Mark Dickinson;
rationals added in :issue:`5812`, and float/decimal in
:issue:`8294`.)
Ordering comparisons (``<``, ``<=``, ``>``, ``>=``) between
fractions and complex numbers now raise a :exc:`TypeError`.
This fixes an oversight, making the :class:`~fractions.Fraction`
match the other numeric types.
.. revision 79455
* New class: :class:`~ftplib.FTP_TLS` in
the :mod:`ftplib` module provides secure FTP
connections using TLS encapsulation of authentication as well as
subsequent control and data transfers.
(Contributed by Giampaolo Rodola; :issue:`2054`.)
The :meth:`~ftplib.FTP.storbinary` method for binary uploads can now restart
uploads thanks to an added *rest* parameter (patch by Pablo Mouzo;
:issue:`6845`.)
* New class decorator: :func:`~functools.total_ordering` in the :mod:`functools`
module takes a class that defines an :meth:`__eq__` method and one of
:meth:`__lt__`, :meth:`__le__`, :meth:`__gt__`, or :meth:`__ge__`,
and generates the missing comparison methods. Since the
:meth:`__cmp__` method is being deprecated in Python 3.x,
this decorator makes it easier to define ordered classes.
(Added by Raymond Hettinger; :issue:`5479`.)
New function: :func:`~functools.cmp_to_key` will take an old-style comparison
function that expects two arguments and return a new callable that
can be used as the *key* parameter to functions such as
:func:`sorted`, :func:`min` and :func:`max`, etc. The primary
intended use is to help with making code compatible with Python 3.x.
(Added by Raymond Hettinger.)
* New function: the :mod:`gc` module's :func:`~gc.is_tracked` returns
true if a given instance is tracked by the garbage collector, false
otherwise. (Contributed by Antoine Pitrou; :issue:`4688`.)
* The :mod:`gzip` module's :class:`~gzip.GzipFile` now supports the context
management protocol, so you can write ``with gzip.GzipFile(...) as f:``
(contributed by Hagen Fürstenau; :issue:`3860`), and it now implements
the :class:`io.BufferedIOBase` ABC, so you can wrap it with
:class:`io.BufferedReader` for faster processing
(contributed by Nir Aides; :issue:`7471`).
It's also now possible to override the modification time
recorded in a gzipped file by providing an optional timestamp to
the constructor. (Contributed by Jacques Frechet; :issue:`4272`.)
Files in gzip format can be padded with trailing zero bytes; the
:mod:`gzip` module will now consume these trailing bytes. (Fixed by
Tadek Pietraszek and Brian Curtin; :issue:`2846`.)
* New attribute: the :mod:`hashlib` module now has an :attr:`~hashlib.hashlib.algorithms`
attribute containing a tuple naming the supported algorithms.
In Python 2.7, ``hashlib.algorithms`` contains
``('md5', 'sha1', 'sha224', 'sha256', 'sha384', 'sha512')``.
(Contributed by Carl Chenet; :issue:`7418`.)
* The default :class:`~httplib.HTTPResponse` class used by the :mod:`httplib` module now
supports buffering, resulting in much faster reading of HTTP responses.
(Contributed by Kristján Valur Jónsson; :issue:`4879`.)
The :class:`~httplib.HTTPConnection` and :class:`~httplib.HTTPSConnection` classes
now support a *source_address* parameter, a ``(host, port)`` 2-tuple
giving the source address that will be used for the connection.
(Contributed by Eldon Ziegler; :issue:`3972`.)
* The :mod:`ihooks` module now supports relative imports. Note that
:mod:`ihooks` is an older module for customizing imports,
superseded by the :mod:`imputil` module added in Python 2.0.
(Relative import support added by Neil Schemenauer.)
.. revision 75423
* The :mod:`imaplib` module now supports IPv6 addresses.
(Contributed by Derek Morr; :issue:`1655`.)
* New function: the :mod:`inspect` module's :func:`~inspect.getcallargs`
takes a callable and its positional and keyword arguments,
and figures out which of the callable's parameters will receive each argument,
returning a dictionary mapping argument names to their values. For example::
>>> from inspect import getcallargs
>>> def f(a, b=1, *pos, **named):
... pass
>>> getcallargs(f, 1, 2, 3)
{'a': 1, 'b': 2, 'pos': (3,), 'named': {}}
>>> getcallargs(f, a=2, x=4)
{'a': 2, 'b': 1, 'pos': (), 'named': {'x': 4}}
>>> getcallargs(f)
Traceback (most recent call last):
...
TypeError: f() takes at least 1 argument (0 given)
Contributed by George Sakkis; :issue:`3135`.
* Updated module: The :mod:`io` library has been upgraded to the version shipped with
Python 3.1. For 3.1, the I/O library was entirely rewritten in C
and is 2 to 20 times faster depending on the task being performed. The
original Python version was renamed to the :mod:`_pyio` module.
One minor resulting change: the :class:`io.TextIOBase` class now
has an :attr:`errors` attribute giving the error setting
used for encoding and decoding errors (one of ``'strict'``, ``'replace'``,
``'ignore'``).
The :class:`io.FileIO` class now raises an :exc:`OSError` when passed
an invalid file descriptor. (Implemented by Benjamin Peterson;
:issue:`4991`.) The :meth:`~io.IOBase.truncate` method now preserves the
file position; previously it would change the file position to the
end of the new file. (Fixed by Pascal Chambon; :issue:`6939`.)
* New function: ``itertools.compress(data, selectors)`` takes two
iterators. Elements of *data* are returned if the corresponding
value in *selectors* is true::
itertools.compress('ABCDEF', [1,0,1,0,1,1]) =>
A, C, E, F
.. maybe here is better to use >>> list(itertools.compress(...)) instead
New function: ``itertools.combinations_with_replacement(iter, r)``
returns all the possible *r*-length combinations of elements from the
iterable *iter*. Unlike :func:`~itertools.combinations`, individual elements
can be repeated in the generated combinations::
itertools.combinations_with_replacement('abc', 2) =>
('a', 'a'), ('a', 'b'), ('a', 'c'),
('b', 'b'), ('b', 'c'), ('c', 'c')
Note that elements are treated as unique depending on their position
in the input, not their actual values.
The :func:`itertools.count` function now has a *step* argument that
allows incrementing by values other than 1. :func:`~itertools.count` also
now allows keyword arguments, and using non-integer values such as
floats or :class:`~decimal.Decimal` instances. (Implemented by Raymond
Hettinger; :issue:`5032`.)
:func:`itertools.combinations` and :func:`itertools.product`
previously raised :exc:`ValueError` for values of *r* larger than
the input iterable. This was deemed a specification error, so they
now return an empty iterator. (Fixed by Raymond Hettinger; :issue:`4816`.)
* Updated module: The :mod:`json` module was upgraded to version 2.0.9 of the
simplejson package, which includes a C extension that makes
encoding and decoding faster.
(Contributed by Bob Ippolito; :issue:`4136`.)
To support the new :class:`collections.OrderedDict` type, :func:`json.load`
now has an optional *object_pairs_hook* parameter that will be called
with any object literal that decodes to a list of pairs.
(Contributed by Raymond Hettinger; :issue:`5381`.)
* The :mod:`mailbox` module's :class:`~mailbox.Maildir` class now records the
timestamp on the directories it reads, and only re-reads them if the
modification time has subsequently changed. This improves
performance by avoiding unneeded directory scans. (Fixed by
A.M. Kuchling and Antoine Pitrou; :issue:`1607951`, :issue:`6896`.)
* New functions: the :mod:`math` module gained
:func:`~math.erf` and :func:`~math.erfc` for the error function and the complementary error function,
:func:`~math.expm1` which computes ``e**x - 1`` with more precision than
using :func:`~math.exp` and subtracting 1,
:func:`~math.gamma` for the Gamma function, and
:func:`~math.lgamma` for the natural log of the Gamma function.
(Contributed by Mark Dickinson and nirinA raseliarison; :issue:`3366`.)
* The :mod:`multiprocessing` module's :class:`Manager*` classes
can now be passed a callable that will be called whenever
a subprocess is started, along with a set of arguments that will be
passed to the callable.
(Contributed by lekma; :issue:`5585`.)
The :class:`~multiprocessing.Pool` class, which controls a pool of worker processes,
now has an optional *maxtasksperchild* parameter. Worker processes
will perform the specified number of tasks and then exit, causing the
:class:`~multiprocessing.Pool` to start a new worker. This is useful if tasks may leak
memory or other resources, or if some tasks will cause the worker to
become very large.
(Contributed by Charles Cazabon; :issue:`6963`.)
* The :mod:`nntplib` module now supports IPv6 addresses.
(Contributed by Derek Morr; :issue:`1664`.)
* New functions: the :mod:`os` module wraps the following POSIX system
calls: :func:`~os.getresgid` and :func:`~os.getresuid`, which return the
real, effective, and saved GIDs and UIDs;
:func:`~os.setresgid` and :func:`~os.setresuid`, which set
real, effective, and saved GIDs and UIDs to new values;
:func:`~os.initgroups`, which initialize the group access list
for the current process. (GID/UID functions
contributed by Travis H.; :issue:`6508`. Support for initgroups added
by Jean-Paul Calderone; :issue:`7333`.)
The :func:`os.fork` function now re-initializes the import lock in
the child process; this fixes problems on Solaris when :func:`~os.fork`
is called from a thread. (Fixed by Zsolt Cserna; :issue:`7242`.)
* In the :mod:`os.path` module, the :func:`~os.path.normpath` and
:func:`~os.path.abspath` functions now preserve Unicode; if their input path
is a Unicode string, the return value is also a Unicode string.
(:meth:`~os.path.normpath` fixed by Matt Giuca in :issue:`5827`;
:meth:`~os.path.abspath` fixed by Ezio Melotti in :issue:`3426`.)
* The :mod:`pydoc` module now has help for the various symbols that Python
uses. You can now do ``help('<<')`` or ``help('@')``, for example.
(Contributed by David Laban; :issue:`4739`.)
* The :mod:`re` module's :func:`~re.split`, :func:`~re.sub`, and :func:`~re.subn`
now accept an optional *flags* argument, for consistency with the
other functions in the module. (Added by Gregory P. Smith.)
* New function: :func:`~runpy.run_path` in the :mod:`runpy` module
will execute the code at a provided *path* argument. *path* can be
the path of a Python source file (:file:`example.py`), a compiled
bytecode file (:file:`example.pyc`), a directory
(:file:`./package/`), or a zip archive (:file:`example.zip`). If a
directory or zip path is provided, it will be added to the front of
``sys.path`` and the module :mod:`__main__` will be imported. It's
expected that the directory or zip contains a :file:`__main__.py`;
if it doesn't, some other :file:`__main__.py` might be imported from
a location later in ``sys.path``. This makes more of the machinery
of :mod:`runpy` available to scripts that want to mimic the way
Python's command line processes an explicit path name.
(Added by Nick Coghlan; :issue:`6816`.)
* New function: in the :mod:`shutil` module, :func:`~shutil.make_archive`
takes a filename, archive type (zip or tar-format), and a directory
path, and creates an archive containing the directory's contents.
(Added by Tarek Ziadé.)
:mod:`shutil`'s :func:`~shutil.copyfile` and :func:`~shutil.copytree`
functions now raise a :exc:`~shutil.SpecialFileError` exception when
asked to copy a named pipe. Previously the code would treat
named pipes like a regular file by opening them for reading, and
this would block indefinitely. (Fixed by Antoine Pitrou; :issue:`3002`.)
* The :mod:`signal` module no longer re-installs the signal handler
unless this is truly necessary, which fixes a bug that could make it
impossible to catch the EINTR signal robustly. (Fixed by
Charles-Francois Natali; :issue:`8354`.)
* New functions: in the :mod:`site` module, three new functions
return various site- and user-specific paths.
:func:`~site.getsitepackages` returns a list containing all
global site-packages directories,
:func:`~site.getusersitepackages` returns the path of the user's
site-packages directory, and
:func:`~site.getuserbase` returns the value of the :envvar:`USER_BASE`
environment variable, giving the path to a directory that can be used
to store data.
(Contributed by Tarek Ziadé; :issue:`6693`.)
The :mod:`site` module now reports exceptions occurring
when the :mod:`sitecustomize` module is imported, and will no longer
catch and swallow the :exc:`KeyboardInterrupt` exception. (Fixed by
Victor Stinner; :issue:`3137`.)
* The :func:`~socket.create_connection` function
gained a *source_address* parameter, a ``(host, port)`` 2-tuple
giving the source address that will be used for the connection.
(Contributed by Eldon Ziegler; :issue:`3972`.)
The :meth:`~socket.socket.recv_into` and :meth:`~socket.socket.recvfrom_into`
methods will now write into objects that support the buffer API, most usefully
the :class:`bytearray` and :class:`memoryview` objects. (Implemented by
Antoine Pitrou; :issue:`8104`.)
* The :mod:`SocketServer` module's :class:`~SocketServer.TCPServer` class now
supports socket timeouts and disabling the Nagle algorithm.
The :attr:`~SocketServer.TCPServer.disable_nagle_algorithm` class attribute
defaults to ``False``; if overridden to be true,
new request connections will have the TCP_NODELAY option set to
prevent buffering many small sends into a single TCP packet.
The :attr:`~SocketServer.BaseServer.timeout` class attribute can hold
a timeout in seconds that will be applied to the request socket; if
no request is received within that time, :meth:`~SocketServer.BaseServer.handle_timeout`
will be called and :meth:`~SocketServer.BaseServer.handle_request` will return.
(Contributed by Kristján Valur Jónsson; :issue:`6192` and :issue:`6267`.)
* Updated module: the :mod:`sqlite3` module has been updated to
version 2.6.0 of the `pysqlite package <https://github.com/ghaering/pysqlite>`__. Version 2.6.0 includes a number of bugfixes, and adds
the ability to load SQLite extensions from shared libraries.
Call the ``enable_load_extension(True)`` method to enable extensions,
and then call :meth:`~sqlite3.Connection.load_extension` to load a particular shared library.
(Updated by Gerhard Häring.)
* The :mod:`ssl` module's :class:`~ssl.SSLSocket` objects now support the
buffer API, which fixed a test suite failure (fix by Antoine Pitrou;
:issue:`7133`) and automatically set
OpenSSL's :c:macro:`SSL_MODE_AUTO_RETRY`, which will prevent an error
code being returned from :meth:`recv` operations that trigger an SSL
renegotiation (fix by Antoine Pitrou; :issue:`8222`).
The :func:`ssl.wrap_socket` constructor function now takes a
*ciphers* argument that's a string listing the encryption algorithms
to be allowed; the format of the string is described
`in the OpenSSL documentation
<https://www.openssl.org/docs/manmaster/man1/ciphers.html#CIPHER-LIST-FORMAT>`__.
(Added by Antoine Pitrou; :issue:`8322`.)
Another change makes the extension load all of OpenSSL's ciphers and
digest algorithms so that they're all available. Some SSL
certificates couldn't be verified, reporting an "unknown algorithm"
error. (Reported by Beda Kosata, and fixed by Antoine Pitrou;
:issue:`8484`.)
The version of OpenSSL being used is now available as the module
attributes :data:`ssl.OPENSSL_VERSION` (a string),
:data:`ssl.OPENSSL_VERSION_INFO` (a 5-tuple), and
:data:`ssl.OPENSSL_VERSION_NUMBER` (an integer). (Added by Antoine
Pitrou; :issue:`8321`.)
* The :mod:`struct` module will no longer silently ignore overflow
errors when a value is too large for a particular integer format
code (one of ``bBhHiIlLqQ``); it now always raises a
:exc:`struct.error` exception. (Changed by Mark Dickinson;
:issue:`1523`.) The :func:`~struct.pack` function will also
attempt to use :meth:`__index__` to convert and pack non-integers
before trying the :meth:`__int__` method or reporting an error.
(Changed by Mark Dickinson; :issue:`8300`.)
* New function: the :mod:`subprocess` module's
:func:`~subprocess.check_output` runs a command with a specified set of arguments
and returns the command's output as a string when the command runs without
error, or raises a :exc:`~subprocess.CalledProcessError` exception otherwise.
::
>>> subprocess.check_output(['df', '-h', '.'])
'Filesystem Size Used Avail Capacity Mounted on\n
/dev/disk0s2 52G 49G 3.0G 94% /\n'
>>> subprocess.check_output(['df', '-h', '/bogus'])
...
subprocess.CalledProcessError: Command '['df', '-h', '/bogus']' returned non-zero exit status 1
(Contributed by Gregory P. Smith.)
The :mod:`subprocess` module will now retry its internal system calls
on receiving an :const:`EINTR` signal. (Reported by several people; final
patch by Gregory P. Smith in :issue:`1068268`.)
* New function: :func:`~symtable.Symbol.is_declared_global` in the :mod:`symtable` module
returns true for variables that are explicitly declared to be global,
false for ones that are implicitly global.
(Contributed by Jeremy Hylton.)
* The :mod:`syslog` module will now use the value of ``sys.argv[0]`` as the
identifier instead of the previous default value of ``'python'``.
(Changed by Sean Reifschneider; :issue:`8451`.)
* The ``sys.version_info`` value is now a named tuple, with attributes
named :attr:`major`, :attr:`minor`, :attr:`micro`,
:attr:`releaselevel`, and :attr:`serial`. (Contributed by Ross
Light; :issue:`4285`.)
:func:`sys.getwindowsversion` also returns a named tuple,
with attributes named :attr:`major`, :attr:`minor`, :attr:`build`,
:attr:`platform`, :attr:`service_pack`, :attr:`service_pack_major`,
:attr:`service_pack_minor`, :attr:`suite_mask`, and
:attr:`product_type`. (Contributed by Brian Curtin; :issue:`7766`.)
* The :mod:`tarfile` module's default error handling has changed, to
no longer suppress fatal errors. The default error level was previously 0,
which meant that errors would only result in a message being written to the
debug log, but because the debug log is not activated by default,
these errors go unnoticed. The default error level is now 1,
which raises an exception if there's an error.
(Changed by Lars Gustäbel; :issue:`7357`.)
:mod:`tarfile` now supports filtering the :class:`~tarfile.TarInfo`
objects being added to a tar file. When you call :meth:`~tarfile.TarFile.add`,
you may supply an optional *filter* argument
that's a callable. The *filter* callable will be passed the
:class:`~tarfile.TarInfo` for every file being added, and can modify and return it.
If the callable returns ``None``, the file will be excluded from the
resulting archive. This is more powerful than the existing
*exclude* argument, which has therefore been deprecated.
(Added by Lars Gustäbel; :issue:`6856`.)
The :class:`~tarfile.TarFile` class also now supports the context management protocol.
(Added by Lars Gustäbel; :issue:`7232`.)
* The :meth:`~threading.Event.wait` method of the :class:`threading.Event` class
now returns the internal flag on exit. This means the method will usually
return true because :meth:`~threading.Event.wait` is supposed to block until the
internal flag becomes true. The return value will only be false if
a timeout was provided and the operation timed out.
(Contributed by Tim Lesher; :issue:`1674032`.)
* The Unicode database provided by the :mod:`unicodedata` module is
now used internally to determine which characters are numeric,
whitespace, or represent line breaks. The database also
includes information from the :file:`Unihan.txt` data file (patch
by Anders Chrigström and Amaury Forgeot d'Arc; :issue:`1571184`)
and has been updated to version 5.2.0 (updated by
Florent Xicluna; :issue:`8024`).
* The :mod:`urlparse` module's :func:`~urlparse.urlsplit` now handles
unknown URL schemes in a fashion compliant with :rfc:`3986`: if the
URL is of the form ``"<something>://..."``, the text before the
``://`` is treated as the scheme, even if it's a made-up scheme that
the module doesn't know about. This change may break code that
worked around the old behaviour. For example, Python 2.6.4 or 2.5
will return the following:
>>> import urlparse
>>> urlparse.urlsplit('invented://host/filename?query')
('invented', '', '//host/filename?query', '', '')
Python 2.7 (and Python 2.6.5) will return:
>>> import urlparse
>>> urlparse.urlsplit('invented://host/filename?query')
('invented', 'host', '/filename?query', '', '')
(Python 2.7 actually produces slightly different output, since it
returns a named tuple instead of a standard tuple.)
The :mod:`urlparse` module also supports IPv6 literal addresses as defined by
:rfc:`2732` (contributed by Senthil Kumaran; :issue:`2987`). ::
>>> urlparse.urlparse('http://[1080::8:800:200C:417A]/foo')
ParseResult(scheme='http', netloc='[1080::8:800:200C:417A]',
path='/foo', params='', query='', fragment='')
* New class: the :class:`~weakref.WeakSet` class in the :mod:`weakref`
module is a set that only holds weak references to its elements; elements
will be removed once there are no references pointing to them.
(Originally implemented in Python 3.x by Raymond Hettinger, and backported
to 2.7 by Michael Foord.)
* The ElementTree library, :mod:`xml.etree`, no longer escapes
ampersands and angle brackets when outputting an XML processing
instruction (which looks like ``<?xml-stylesheet href="#style1"?>``)
or comment (which looks like ``<!-- comment -->``).
(Patch by Neil Muller; :issue:`2746`.)
* The XML-RPC client and server, provided by the :mod:`xmlrpclib` and
:mod:`SimpleXMLRPCServer` modules, have improved performance by
supporting HTTP/1.1 keep-alive and by optionally using gzip encoding
to compress the XML being exchanged. The gzip compression is
controlled by the :attr:`encode_threshold` attribute of
:class:`SimpleXMLRPCRequestHandler`, which contains a size in bytes;
responses larger than this will be compressed.
(Contributed by Kristján Valur Jónsson; :issue:`6267`.)
* The :mod:`zipfile` module's :class:`~zipfile.ZipFile` now supports the context
management protocol, so you can write ``with zipfile.ZipFile(...) as f:``.
(Contributed by Brian Curtin; :issue:`5511`.)
:mod:`zipfile` now also supports archiving empty directories and
extracts them correctly. (Fixed by Kuba Wieczorek; :issue:`4710`.)
Reading files out of an archive is faster, and interleaving
:meth:`~zipfile.ZipFile.read` and :meth:`~zipfile.ZipFile.readline` now works correctly.
(Contributed by Nir Aides; :issue:`7610`.)
The :func:`~zipfile.is_zipfile` function now
accepts a file object, in addition to the path names accepted in earlier
versions. (Contributed by Gabriel Genellina; :issue:`4756`.)
The :meth:`~zipfile.ZipFile.writestr` method now has an optional *compress_type* parameter
that lets you override the default compression method specified in the
:class:`~zipfile.ZipFile` constructor. (Contributed by Ronald Oussoren;
:issue:`6003`.)
.. ======================================================================
.. whole new modules get described in subsections here
.. _importlib-section:
New module: importlib
------------------------------
Python 3.1 includes the :mod:`importlib` package, a re-implementation
of the logic underlying Python's :keyword:`import` statement.
:mod:`importlib` is useful for implementors of Python interpreters and
to users who wish to write new importers that can participate in the
import process. Python 2.7 doesn't contain the complete
:mod:`importlib` package, but instead has a tiny subset that contains
a single function, :func:`~importlib.import_module`.
``import_module(name, package=None)`` imports a module. *name* is
a string containing the module or package's name. It's possible to do
relative imports by providing a string that begins with a ``.``
character, such as ``..utils.errors``. For relative imports, the
*package* argument must be provided and is the name of the package that
will be used as the anchor for
the relative import. :func:`~importlib.import_module` both inserts the imported
module into ``sys.modules`` and returns the module object.
Here are some examples::
>>> from importlib import import_module
>>> anydbm = import_module('anydbm') # Standard absolute import
>>> anydbm
<module 'anydbm' from '/p/python/Lib/anydbm.py'>
>>> # Relative import
>>> file_util = import_module('..file_util', 'distutils.command')
>>> file_util
<module 'distutils.file_util' from '/python/Lib/distutils/file_util.pyc'>
:mod:`importlib` was implemented by Brett Cannon and introduced in
Python 3.1.
New module: sysconfig
---------------------------------
The :mod:`sysconfig` module has been pulled out of the Distutils
package, becoming a new top-level module in its own right.
:mod:`sysconfig` provides functions for getting information about
Python's build process: compiler switches, installation paths, the
platform name, and whether Python is running from its source
directory.
Some of the functions in the module are:
* :func:`~sysconfig.get_config_var` returns variables from Python's
Makefile and the :file:`pyconfig.h` file.
* :func:`~sysconfig.get_config_vars` returns a dictionary containing
all of the configuration variables.
* :func:`~sysconfig.get_path` returns the configured path for
a particular type of module: the standard library,
site-specific modules, platform-specific modules, etc.
* :func:`~sysconfig.is_python_build` returns true if you're running a
binary from a Python source tree, and false otherwise.
Consult the :mod:`sysconfig` documentation for more details and for
a complete list of functions.
The Distutils package and :mod:`sysconfig` are now maintained by Tarek
Ziadé, who has also started a Distutils2 package (source repository at
https://hg.python.org/distutils2/) for developing a next-generation
version of Distutils.
ttk: Themed Widgets for Tk
--------------------------
Tcl/Tk 8.5 includes a set of themed widgets that re-implement basic Tk
widgets but have a more customizable appearance and can therefore more
closely resemble the native platform's widgets. This widget
set was originally called Tile, but was renamed to Ttk (for "themed Tk")
on being added to Tcl/Tck release 8.5.
To learn more, read the :mod:`ttk` module documentation. You may also
wish to read the Tcl/Tk manual page describing the
Ttk theme engine, available at
https://www.tcl.tk/man/tcl8.5/TkCmd/ttk_intro.htm. Some
screenshots of the Python/Ttk code in use are at
https://code.google.com/archive/p/python-ttk/wikis/Screenshots.wiki.
The :mod:`ttk` module was written by Guilherme Polo and added in
:issue:`2983`. An alternate version called ``Tile.py``, written by
Martin Franklin and maintained by Kevin Walzer, was proposed for
inclusion in :issue:`2618`, but the authors argued that Guilherme
Polo's work was more comprehensive.
.. _unittest-section:
Updated module: unittest
---------------------------------
The :mod:`unittest` module was greatly enhanced; many
new features were added. Most of these features were implemented
by Michael Foord, unless otherwise noted. The enhanced version of
the module is downloadable separately for use with Python versions 2.4 to 2.6,
packaged as the :mod:`unittest2` package, from
https://pypi.org/project/unittest2.
When used from the command line, the module can automatically discover
tests. It's not as fancy as `py.test <http://pytest.org>`__ or
`nose <https://nose.readthedocs.io/>`__, but provides a
simple way to run tests kept within a set of package directories. For example,
the following command will search the :file:`test/` subdirectory for
any importable test files named ``test*.py``::
python -m unittest discover -s test
Consult the :mod:`unittest` module documentation for more details.
(Developed in :issue:`6001`.)
The :func:`~unittest.main` function supports some other new options:
* :option:`-b <unittest -b>` or :option:`!--buffer` will buffer the standard output
and standard error streams during each test. If the test passes,
any resulting output will be discarded; on failure, the buffered
output will be displayed.
* :option:`-c <unittest -c>` or :option:`!--catch` will cause the control-C interrupt
to be handled more gracefully. Instead of interrupting the test
process immediately, the currently running test will be completed
and then the partial results up to the interruption will be reported.
If you're impatient, a second press of control-C will cause an immediate
interruption.
This control-C handler tries to avoid causing problems when the code
being tested or the tests being run have defined a signal handler of
their own, by noticing that a signal handler was already set and
calling it. If this doesn't work for you, there's a
:func:`~unittest.removeHandler` decorator that can be used to mark tests that
should have the control-C handling disabled.
* :option:`-f <unittest -f>` or :option:`!--failfast` makes
test execution stop immediately when a test fails instead of
continuing to execute further tests. (Suggested by Cliff Dyer and
implemented by Michael Foord; :issue:`8074`.)
The progress messages now show 'x' for expected failures
and 'u' for unexpected successes when run in verbose mode.
(Contributed by Benjamin Peterson.)
Test cases can raise the :exc:`~unittest.SkipTest` exception to skip a
test (:issue:`1034053`).
The error messages for :meth:`~unittest.TestCase.assertEqual`,
:meth:`~unittest.TestCase.assertTrue`, and :meth:`~unittest.TestCase.assertFalse`
failures now provide more information. If you set the
:attr:`~unittest.TestCase.longMessage` attribute of your :class:`~unittest.TestCase` classes to
true, both the standard error message and any additional message you
provide will be printed for failures. (Added by Michael Foord; :issue:`5663`.)
The :meth:`~unittest.TestCase.assertRaises` method now
returns a context handler when called without providing a callable
object to run. For example, you can write this::
with self.assertRaises(KeyError):
{}['foo']
(Implemented by Antoine Pitrou; :issue:`4444`.)
.. rev 78774
Module- and class-level setup and teardown fixtures are now supported.
Modules can contain :func:`~unittest.setUpModule` and :func:`~unittest.tearDownModule`
functions. Classes can have :meth:`~unittest.TestCase.setUpClass` and
:meth:`~unittest.TestCase.tearDownClass` methods that must be defined as class methods
(using ``@classmethod`` or equivalent). These functions and
methods are invoked when the test runner switches to a test case in a
different module or class.
The methods :meth:`~unittest.TestCase.addCleanup` and
:meth:`~unittest.TestCase.doCleanups` were added.
:meth:`~unittest.TestCase.addCleanup` lets you add cleanup functions that
will be called unconditionally (after :meth:`~unittest.TestCase.setUp` if
:meth:`~unittest.TestCase.setUp` fails, otherwise after :meth:`~unittest.TestCase.tearDown`). This allows
for much simpler resource allocation and deallocation during tests
(:issue:`5679`).
A number of new methods were added that provide more specialized
tests. Many of these methods were written by Google engineers
for use in their test suites; Gregory P. Smith, Michael Foord, and
GvR worked on merging them into Python's version of :mod:`unittest`.
* :meth:`~unittest.TestCase.assertIsNone` and :meth:`~unittest.TestCase.assertIsNotNone` take one
expression and verify that the result is or is not ``None``.
* :meth:`~unittest.TestCase.assertIs` and :meth:`~unittest.TestCase.assertIsNot`
take two values and check whether the two values evaluate to the same object or not.
(Added by Michael Foord; :issue:`2578`.)
* :meth:`~unittest.TestCase.assertIsInstance` and
:meth:`~unittest.TestCase.assertNotIsInstance` check whether
the resulting object is an instance of a particular class, or of
one of a tuple of classes. (Added by Georg Brandl; :issue:`7031`.)
* :meth:`~unittest.TestCase.assertGreater`, :meth:`~unittest.TestCase.assertGreaterEqual`,
:meth:`~unittest.TestCase.assertLess`, and :meth:`~unittest.TestCase.assertLessEqual` compare
two quantities.
* :meth:`~unittest.TestCase.assertMultiLineEqual` compares two strings, and if they're
not equal, displays a helpful comparison that highlights the
differences in the two strings. This comparison is now used by
default when Unicode strings are compared with :meth:`~unittest.TestCase.assertEqual`.
* :meth:`~unittest.TestCase.assertRegexpMatches` and
:meth:`~unittest.TestCase.assertNotRegexpMatches` checks whether the
first argument is a string matching or not matching the regular
expression provided as the second argument (:issue:`8038`).
* :meth:`~unittest.TestCase.assertRaisesRegexp` checks whether a particular exception
is raised, and then also checks that the string representation of
the exception matches the provided regular expression.
* :meth:`~unittest.TestCase.assertIn` and :meth:`~unittest.TestCase.assertNotIn`
tests whether *first* is or is not in *second*.
* :meth:`~unittest.TestCase.assertItemsEqual` tests whether two provided sequences
contain the same elements.
* :meth:`~unittest.TestCase.assertSetEqual` compares whether two sets are equal, and
only reports the differences between the sets in case of error.
* Similarly, :meth:`~unittest.TestCase.assertListEqual` and :meth:`~unittest.TestCase.assertTupleEqual`
compare the specified types and explain any differences without necessarily
printing their full values; these methods are now used by default
when comparing lists and tuples using :meth:`~unittest.TestCase.assertEqual`.
More generally, :meth:`~unittest.TestCase.assertSequenceEqual` compares two sequences
and can optionally check whether both sequences are of a
particular type.
* :meth:`~unittest.TestCase.assertDictEqual` compares two dictionaries and reports the
differences; it's now used by default when you compare two dictionaries
using :meth:`~unittest.TestCase.assertEqual`. :meth:`~unittest.TestCase.assertDictContainsSubset` checks whether
all of the key/value pairs in *first* are found in *second*.
* :meth:`~unittest.TestCase.assertAlmostEqual` and :meth:`~unittest.TestCase.assertNotAlmostEqual` test
whether *first* and *second* are approximately equal. This method
can either round their difference to an optionally-specified number
of *places* (the default is 7) and compare it to zero, or require
the difference to be smaller than a supplied *delta* value.
* :meth:`~unittest.TestLoader.loadTestsFromName` properly honors the
:attr:`~unittest.TestLoader.suiteClass` attribute of
the :class:`~unittest.TestLoader`. (Fixed by Mark Roddy; :issue:`6866`.)
* A new hook lets you extend the :meth:`~unittest.TestCase.assertEqual` method to handle
new data types. The :meth:`~unittest.TestCase.addTypeEqualityFunc` method takes a type
object and a function. The function will be used when both of the
objects being compared are of the specified type. This function
should compare the two objects and raise an exception if they don't
match; it's a good idea for the function to provide additional
information about why the two objects aren't matching, much as the new
sequence comparison methods do.
:func:`unittest.main` now takes an optional ``exit`` argument. If
false, :func:`~unittest.main` doesn't call :func:`sys.exit`, allowing
:func:`~unittest.main` to be used from the interactive interpreter.
(Contributed by J. Pablo Fernández; :issue:`3379`.)
:class:`~unittest.TestResult` has new :meth:`~unittest.TestResult.startTestRun` and
:meth:`~unittest.TestResult.stopTestRun` methods that are called immediately before
and after a test run. (Contributed by Robert Collins; :issue:`5728`.)
With all these changes, the :file:`unittest.py` was becoming awkwardly
large, so the module was turned into a package and the code split into
several files (by Benjamin Peterson). This doesn't affect how the
module is imported or used.
.. seealso::
http://www.voidspace.org.uk/python/articles/unittest2.shtml
Describes the new features, how to use them, and the
rationale for various design decisions. (By Michael Foord.)
.. _elementtree-section:
Updated module: ElementTree 1.3
---------------------------------
The version of the ElementTree library included with Python was updated to
version 1.3. Some of the new features are:
* The various parsing functions now take a *parser* keyword argument
giving an :class:`~xml.etree.ElementTree.XMLParser` instance that will
be used. This makes it possible to override the file's internal encoding::
p = ET.XMLParser(encoding='utf-8')
t = ET.XML("""<root/>""", parser=p)
Errors in parsing XML now raise a :exc:`ParseError` exception, whose
instances have a :attr:`position` attribute
containing a (*line*, *column*) tuple giving the location of the problem.
* ElementTree's code for converting trees to a string has been
significantly reworked, making it roughly twice as fast in many
cases. The :meth:`ElementTree.write() <xml.etree.ElementTree.ElementTree.write>`
and :meth:`Element.write` methods now have a *method* parameter that can be
"xml" (the default), "html", or "text". HTML mode will output empty
elements as ``<empty></empty>`` instead of ``<empty/>``, and text
mode will skip over elements and only output the text chunks. If
you set the :attr:`tag` attribute of an element to ``None`` but
leave its children in place, the element will be omitted when the
tree is written out, so you don't need to do more extensive rearrangement
to remove a single element.
Namespace handling has also been improved. All ``xmlns:<whatever>``
declarations are now output on the root element, not scattered throughout
the resulting XML. You can set the default namespace for a tree
by setting the :attr:`default_namespace` attribute and can
register new prefixes with :meth:`~xml.etree.ElementTree.register_namespace`. In XML mode,
you can use the true/false *xml_declaration* parameter to suppress the
XML declaration.
* New :class:`~xml.etree.ElementTree.Element` method:
:meth:`~xml.etree.ElementTree.Element.extend` appends the items from a
sequence to the element's children. Elements themselves behave like
sequences, so it's easy to move children from one element to
another::
from xml.etree import ElementTree as ET
t = ET.XML("""<list>
<item>1</item> <item>2</item> <item>3</item>
</list>""")
new = ET.XML('<root/>')
new.extend(t)
# Outputs <root><item>1</item>...</root>
print ET.tostring(new)
* New :class:`Element` method:
:meth:`~xml.etree.ElementTree.Element.iter` yields the children of the
element as a generator. It's also possible to write ``for child in
elem:`` to loop over an element's children. The existing method
:meth:`getiterator` is now deprecated, as is :meth:`getchildren`
which constructs and returns a list of children.
* New :class:`Element` method:
:meth:`~xml.etree.ElementTree.Element.itertext` yields all chunks of
text that are descendants of the element. For example::
t = ET.XML("""<list>
<item>1</item> <item>2</item> <item>3</item>
</list>""")
# Outputs ['\n ', '1', ' ', '2', ' ', '3', '\n']
print list(t.itertext())
* Deprecated: using an element as a Boolean (i.e., ``if elem:``) would
return true if the element had any children, or false if there were
no children. This behaviour is confusing -- ``None`` is false, but
so is a childless element? -- so it will now trigger a
:exc:`FutureWarning`. In your code, you should be explicit: write
``len(elem) != 0`` if you're interested in the number of children,
or ``elem is not None``.
Fredrik Lundh develops ElementTree and produced the 1.3 version;
you can read his article describing 1.3 at
http://effbot.org/zone/elementtree-13-intro.htm.
Florent Xicluna updated the version included with
Python, after discussions on python-dev and in :issue:`6472`.)
.. ======================================================================
Build and C API Changes
=======================
Changes to Python's build process and to the C API include:
* The latest release of the GNU Debugger, GDB 7, can be `scripted
using Python
<https://sourceware.org/gdb/current/onlinedocs/gdb/Python.html>`__.
When you begin debugging an executable program P, GDB will look for
a file named ``P-gdb.py`` and automatically read it. Dave Malcolm
contributed a :file:`python-gdb.py` that adds a number of
commands useful when debugging Python itself. For example,
``py-up`` and ``py-down`` go up or down one Python stack frame,
which usually corresponds to several C stack frames. ``py-print``
prints the value of a Python variable, and ``py-bt`` prints the
Python stack trace. (Added as a result of :issue:`8032`.)
* If you use the :file:`.gdbinit` file provided with Python,
the "pyo" macro in the 2.7 version now works correctly when the thread being
debugged doesn't hold the GIL; the macro now acquires it before printing.
(Contributed by Victor Stinner; :issue:`3632`.)
* :c:func:`Py_AddPendingCall` is now thread-safe, letting any
worker thread submit notifications to the main Python thread. This
is particularly useful for asynchronous IO operations.
(Contributed by Kristján Valur Jónsson; :issue:`4293`.)
* New function: :c:func:`PyCode_NewEmpty` creates an empty code object;
only the filename, function name, and first line number are required.
This is useful for extension modules that are attempting to
construct a more useful traceback stack. Previously such
extensions needed to call :c:func:`PyCode_New`, which had many
more arguments. (Added by Jeffrey Yasskin.)
* New function: :c:func:`PyErr_NewExceptionWithDoc` creates a new
exception class, just as the existing :c:func:`PyErr_NewException` does,
but takes an extra ``char *`` argument containing the docstring for the
new exception class. (Added by 'lekma' on the Python bug tracker;
:issue:`7033`.)
* New function: :c:func:`PyFrame_GetLineNumber` takes a frame object
and returns the line number that the frame is currently executing.
Previously code would need to get the index of the bytecode
instruction currently executing, and then look up the line number
corresponding to that address. (Added by Jeffrey Yasskin.)
* New functions: :c:func:`PyLong_AsLongAndOverflow` and
:c:func:`PyLong_AsLongLongAndOverflow` approximates a Python long
integer as a C :c:type:`long` or :c:type:`long long`.
If the number is too large to fit into
the output type, an *overflow* flag is set and returned to the caller.
(Contributed by Case Van Horsen; :issue:`7528` and :issue:`7767`.)
* New function: stemming from the rewrite of string-to-float conversion,
a new :c:func:`PyOS_string_to_double` function was added. The old
:c:func:`PyOS_ascii_strtod` and :c:func:`PyOS_ascii_atof` functions
are now deprecated.
* New function: :c:func:`PySys_SetArgvEx` sets the value of
``sys.argv`` and can optionally update ``sys.path`` to include the
directory containing the script named by ``sys.argv[0]`` depending
on the value of an *updatepath* parameter.
This function was added to close a security hole for applications
that embed Python. The old function, :c:func:`PySys_SetArgv`, would
always update ``sys.path``, and sometimes it would add the current
directory. This meant that, if you ran an application embedding
Python in a directory controlled by someone else, attackers could
put a Trojan-horse module in the directory (say, a file named
:file:`os.py`) that your application would then import and run.
If you maintain a C/C++ application that embeds Python, check
whether you're calling :c:func:`PySys_SetArgv` and carefully consider
whether the application should be using :c:func:`PySys_SetArgvEx`
with *updatepath* set to false.
Security issue reported as `CVE-2008-5983
<https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2008-5983>`_;
discussed in :issue:`5753`, and fixed by Antoine Pitrou.
* New macros: the Python header files now define the following macros:
:c:macro:`Py_ISALNUM`,
:c:macro:`Py_ISALPHA`,
:c:macro:`Py_ISDIGIT`,
:c:macro:`Py_ISLOWER`,
:c:macro:`Py_ISSPACE`,
:c:macro:`Py_ISUPPER`,
:c:macro:`Py_ISXDIGIT`,
:c:macro:`Py_TOLOWER`, and :c:macro:`Py_TOUPPER`.
All of these functions are analogous to the C
standard macros for classifying characters, but ignore the current
locale setting, because in
several places Python needs to analyze characters in a
locale-independent way. (Added by Eric Smith;
:issue:`5793`.)
.. XXX these macros don't seem to be described in the c-api docs.
* Removed function: :c:macro:`PyEval_CallObject` is now only available
as a macro. A function version was being kept around to preserve
ABI linking compatibility, but that was in 1997; it can certainly be
deleted by now. (Removed by Antoine Pitrou; :issue:`8276`.)
* New format codes: the :c:func:`PyFormat_FromString`,
:c:func:`PyFormat_FromStringV`, and :c:func:`PyErr_Format` functions now
accept ``%lld`` and ``%llu`` format codes for displaying
C's :c:type:`long long` types.
(Contributed by Mark Dickinson; :issue:`7228`.)
* The complicated interaction between threads and process forking has
been changed. Previously, the child process created by
:func:`os.fork` might fail because the child is created with only a
single thread running, the thread performing the :func:`os.fork`.
If other threads were holding a lock, such as Python's import lock,
when the fork was performed, the lock would still be marked as
"held" in the new process. But in the child process nothing would
ever release the lock, since the other threads weren't replicated,
and the child process would no longer be able to perform imports.
Python 2.7 acquires the import lock before performing an
:func:`os.fork`, and will also clean up any locks created using the
:mod:`threading` module. C extension modules that have internal
locks, or that call :c:func:`fork()` themselves, will not benefit
from this clean-up.
(Fixed by Thomas Wouters; :issue:`1590864`.)
* The :c:func:`Py_Finalize` function now calls the internal
:func:`threading._shutdown` function; this prevents some exceptions from
being raised when an interpreter shuts down.
(Patch by Adam Olsen; :issue:`1722344`.)
* When using the :c:type:`PyMemberDef` structure to define attributes
of a type, Python will no longer let you try to delete or set a
:const:`T_STRING_INPLACE` attribute.
.. rev 79644
* Global symbols defined by the :mod:`ctypes` module are now prefixed
with ``Py``, or with ``_ctypes``. (Implemented by Thomas
Heller; :issue:`3102`.)
* New configure option: the :option:`!--with-system-expat` switch allows
building the :mod:`pyexpat` module to use the system Expat library.
(Contributed by Arfrever Frehtes Taifersar Arahesis; :issue:`7609`.)
* New configure option: the
:option:`!--with-valgrind` option will now disable the pymalloc
allocator, which is difficult for the Valgrind memory-error detector
to analyze correctly.
Valgrind will therefore be better at detecting memory leaks and
overruns. (Contributed by James Henstridge; :issue:`2422`.)
* New configure option: you can now supply an empty string to
:option:`!--with-dbmliborder=` in order to disable all of the various
DBM modules. (Added by Arfrever Frehtes Taifersar Arahesis;
:issue:`6491`.)
* The :program:`configure` script now checks for floating-point rounding bugs
on certain 32-bit Intel chips and defines a :c:macro:`X87_DOUBLE_ROUNDING`
preprocessor definition. No code currently uses this definition,
but it's available if anyone wishes to use it.
(Added by Mark Dickinson; :issue:`2937`.)
:program:`configure` also now sets a :envvar:`LDCXXSHARED` Makefile
variable for supporting C++ linking. (Contributed by Arfrever
Frehtes Taifersar Arahesis; :issue:`1222585`.)
* The build process now creates the necessary files for pkg-config
support. (Contributed by Clinton Roy; :issue:`3585`.)
* The build process now supports Subversion 1.7. (Contributed by
Arfrever Frehtes Taifersar Arahesis; :issue:`6094`.)
.. _whatsnew27-capsules:
Capsules
-------------------
Python 3.1 adds a new C datatype, :c:type:`PyCapsule`, for providing a
C API to an extension module. A capsule is essentially the holder of
a C ``void *`` pointer, and is made available as a module attribute; for
example, the :mod:`socket` module's API is exposed as ``socket.CAPI``,
and :mod:`unicodedata` exposes ``ucnhash_CAPI``. Other extensions
can import the module, access its dictionary to get the capsule
object, and then get the ``void *`` pointer, which will usually point
to an array of pointers to the module's various API functions.
There is an existing data type already used for this,
:c:type:`PyCObject`, but it doesn't provide type safety. Evil code
written in pure Python could cause a segmentation fault by taking a
:c:type:`PyCObject` from module A and somehow substituting it for the
:c:type:`PyCObject` in module B. Capsules know their own name,
and getting the pointer requires providing the name:
.. code-block:: c
void *vtable;
if (!PyCapsule_IsValid(capsule, "mymodule.CAPI") {
PyErr_SetString(PyExc_ValueError, "argument type invalid");
return NULL;
}
vtable = PyCapsule_GetPointer(capsule, "mymodule.CAPI");
You are assured that ``vtable`` points to whatever you're expecting.
If a different capsule was passed in, :c:func:`PyCapsule_IsValid` would
detect the mismatched name and return false. Refer to
:ref:`using-capsules` for more information on using these objects.
Python 2.7 now uses capsules internally to provide various
extension-module APIs, but the :c:func:`PyCObject_AsVoidPtr` was
modified to handle capsules, preserving compile-time compatibility
with the :c:type:`CObject` interface. Use of
:c:func:`PyCObject_AsVoidPtr` will signal a
:exc:`PendingDeprecationWarning`, which is silent by default.
Implemented in Python 3.1 and backported to 2.7 by Larry Hastings;
discussed in :issue:`5630`.
.. ======================================================================
Port-Specific Changes: Windows
-----------------------------------
* The :mod:`msvcrt` module now contains some constants from
the :file:`crtassem.h` header file:
:data:`CRT_ASSEMBLY_VERSION`,
:data:`VC_ASSEMBLY_PUBLICKEYTOKEN`,
and :data:`LIBRARIES_ASSEMBLY_NAME_PREFIX`.
(Contributed by David Cournapeau; :issue:`4365`.)
* The :mod:`_winreg` module for accessing the registry now implements
the :func:`~_winreg.CreateKeyEx` and :func:`~_winreg.DeleteKeyEx`
functions, extended versions of previously-supported functions that
take several extra arguments. The :func:`~_winreg.DisableReflectionKey`,
:func:`~_winreg.EnableReflectionKey`, and :func:`~_winreg.QueryReflectionKey`
were also tested and documented.
(Implemented by Brian Curtin: :issue:`7347`.)
* The new :c:func:`_beginthreadex` API is used to start threads, and
the native thread-local storage functions are now used.
(Contributed by Kristján Valur Jónsson; :issue:`3582`.)
* The :func:`os.kill` function now works on Windows. The signal value
can be the constants :const:`CTRL_C_EVENT`,
:const:`CTRL_BREAK_EVENT`, or any integer. The first two constants
will send :kbd:`Control-C` and :kbd:`Control-Break` keystroke events to
subprocesses; any other value will use the :c:func:`TerminateProcess`
API. (Contributed by Miki Tebeka; :issue:`1220212`.)
* The :func:`os.listdir` function now correctly fails
for an empty path. (Fixed by Hirokazu Yamamoto; :issue:`5913`.)
* The :mod:`mimelib` module will now read the MIME database from
the Windows registry when initializing.
(Patch by Gabriel Genellina; :issue:`4969`.)
.. ======================================================================
Port-Specific Changes: Mac OS X
-----------------------------------
* The path ``/Library/Python/2.7/site-packages`` is now appended to
``sys.path``, in order to share added packages between the system
installation and a user-installed copy of the same version.
(Changed by Ronald Oussoren; :issue:`4865`.)
.. versionchanged:: 2.7.13
As of 2.7.13, this change was removed.
``/Library/Python/2.7/site-packages``, the site-packages directory
used by the Apple-supplied system Python 2.7 is no longer appended to
``sys.path`` for user-installed Pythons such as from the python.org
installers. As of macOS 10.12, Apple changed how the system
site-packages directory is configured, which could cause installation
of pip components, like setuptools, to fail. Packages installed for
the system Python will no longer be shared with user-installed
Pythons. (:issue:`28440`)
Port-Specific Changes: FreeBSD
-----------------------------------
* FreeBSD 7.1's :const:`SO_SETFIB` constant, used with
:func:`~socket.getsockopt`/:func:`~socket.setsockopt` to select an
alternate routing table, is now available in the :mod:`socket`
module. (Added by Kyle VanderBeek; :issue:`8235`.)
Other Changes and Fixes
=======================
* Two benchmark scripts, :file:`iobench` and :file:`ccbench`, were
added to the :file:`Tools` directory. :file:`iobench` measures the
speed of the built-in file I/O objects returned by :func:`open`
while performing various operations, and :file:`ccbench` is a
concurrency benchmark that tries to measure computing throughput,
thread switching latency, and IO processing bandwidth when
performing several tasks using a varying number of threads.
* The :file:`Tools/i18n/msgfmt.py` script now understands plural
forms in :file:`.po` files. (Fixed by Martin von Löwis;
:issue:`5464`.)
* When importing a module from a :file:`.pyc` or :file:`.pyo` file
with an existing :file:`.py` counterpart, the :attr:`co_filename`
attributes of the resulting code objects are overwritten when the
original filename is obsolete. This can happen if the file has been
renamed, moved, or is accessed through different paths. (Patch by
Ziga Seilnacht and Jean-Paul Calderone; :issue:`1180193`.)
* The :file:`regrtest.py` script now takes a :option:`!--randseed=`
switch that takes an integer that will be used as the random seed
for the :option:`!-r` option that executes tests in random order.
The :option:`!-r` option also reports the seed that was used
(Added by Collin Winter.)
* Another :file:`regrtest.py` switch is :option:`!-j`, which
takes an integer specifying how many tests run in parallel. This
allows reducing the total runtime on multi-core machines.
This option is compatible with several other options, including the
:option:`!-R` switch which is known to produce long runtimes.
(Added by Antoine Pitrou, :issue:`6152`.) This can also be used
with a new :option:`!-F` switch that runs selected tests in a loop
until they fail. (Added by Antoine Pitrou; :issue:`7312`.)
* When executed as a script, the :file:`py_compile.py` module now
accepts ``'-'`` as an argument, which will read standard input for
the list of filenames to be compiled. (Contributed by Piotr
Ożarowski; :issue:`8233`.)
.. ======================================================================
Porting to Python 2.7
=====================
This section lists previously described changes and other bugfixes
that may require changes to your code:
* The :func:`range` function processes its arguments more
consistently; it will now call :meth:`__int__` on non-float,
non-integer arguments that are supplied to it. (Fixed by Alexander
Belopolsky; :issue:`1533`.)
* The string :meth:`format` method changed the default precision used
for floating-point and complex numbers from 6 decimal
places to 12, which matches the precision used by :func:`str`.
(Changed by Eric Smith; :issue:`5920`.)
* Because of an optimization for the :keyword:`with` statement, the special
methods :meth:`__enter__` and :meth:`__exit__` must belong to the object's
type, and cannot be directly attached to the object's instance. This
affects new-style classes (derived from :class:`object`) and C extension
types. (:issue:`6101`.)
* Due to a bug in Python 2.6, the *exc_value* parameter to
:meth:`__exit__` methods was often the string representation of the
exception, not an instance. This was fixed in 2.7, so *exc_value*
will be an instance as expected. (Fixed by Florent Xicluna;
:issue:`7853`.)
* When a restricted set of attributes were set using ``__slots__``,
deleting an unset attribute would not raise :exc:`AttributeError`
as you would expect. Fixed by Benjamin Peterson; :issue:`7604`.)
In the standard library:
* Operations with :class:`~datetime.datetime` instances that resulted in a year
falling outside the supported range didn't always raise
:exc:`OverflowError`. Such errors are now checked more carefully
and will now raise the exception. (Reported by Mark Leander, patch
by Anand B. Pillai and Alexander Belopolsky; :issue:`7150`.)
* When using :class:`~decimal.Decimal` instances with a string's
:meth:`format` method, the default alignment was previously
left-alignment. This has been changed to right-alignment, which might
change the output of your programs.
(Changed by Mark Dickinson; :issue:`6857`.)
Comparisons involving a signaling NaN value (or ``sNAN``) now signal
:const:`~decimal.InvalidOperation` instead of silently returning a true or
false value depending on the comparison operator. Quiet NaN values
(or ``NaN``) are now hashable. (Fixed by Mark Dickinson;
:issue:`7279`.)
* The ElementTree library, :mod:`xml.etree`, no longer escapes
ampersands and angle brackets when outputting an XML processing
instruction (which looks like `<?xml-stylesheet href="#style1"?>`)
or comment (which looks like `<!-- comment -->`).
(Patch by Neil Muller; :issue:`2746`.)
* The :meth:`~StringIO.StringIO.readline` method of :class:`~StringIO.StringIO` objects now does
nothing when a negative length is requested, as other file-like
objects do. (:issue:`7348`).
* The :mod:`syslog` module will now use the value of ``sys.argv[0]`` as the
identifier instead of the previous default value of ``'python'``.
(Changed by Sean Reifschneider; :issue:`8451`.)
* The :mod:`tarfile` module's default error handling has changed, to
no longer suppress fatal errors. The default error level was previously 0,
which meant that errors would only result in a message being written to the
debug log, but because the debug log is not activated by default,
these errors go unnoticed. The default error level is now 1,
which raises an exception if there's an error.
(Changed by Lars Gustäbel; :issue:`7357`.)
* The :mod:`urlparse` module's :func:`~urlparse.urlsplit` now handles
unknown URL schemes in a fashion compliant with :rfc:`3986`: if the
URL is of the form ``"<something>://..."``, the text before the
``://`` is treated as the scheme, even if it's a made-up scheme that
the module doesn't know about. This change may break code that
worked around the old behaviour. For example, Python 2.6.4 or 2.5
will return the following:
>>> import urlparse
>>> urlparse.urlsplit('invented://host/filename?query')
('invented', '', '//host/filename?query', '', '')
Python 2.7 (and Python 2.6.5) will return:
>>> import urlparse
>>> urlparse.urlsplit('invented://host/filename?query')
('invented', 'host', '/filename?query', '', '')
(Python 2.7 actually produces slightly different output, since it
returns a named tuple instead of a standard tuple.)
For C extensions:
* C extensions that use integer format codes with the ``PyArg_Parse*``
family of functions will now raise a :exc:`TypeError` exception
instead of triggering a :exc:`DeprecationWarning` (:issue:`5080`).
* Use the new :c:func:`PyOS_string_to_double` function instead of the old
:c:func:`PyOS_ascii_strtod` and :c:func:`PyOS_ascii_atof` functions,
which are now deprecated.
For applications that embed Python:
* The :c:func:`PySys_SetArgvEx` function was added, letting
applications close a security hole when the existing
:c:func:`PySys_SetArgv` function was used. Check whether you're
calling :c:func:`PySys_SetArgv` and carefully consider whether the
application should be using :c:func:`PySys_SetArgvEx` with
*updatepath* set to false.
.. ======================================================================
.. _py27-maintenance-enhancements:
New Features Added to Python 2.7 Maintenance Releases
=====================================================
New features may be added to Python 2.7 maintenance releases when the
situation genuinely calls for it. Any such additions must go through
the Python Enhancement Proposal process, and make a compelling case for why
they can't be adequately addressed by either adding the new feature solely to
Python 3, or else by publishing it on the Python Package Index.
In addition to the specific proposals listed below, there is a general
exemption allowing new ``-3`` warnings to be added in any Python 2.7
maintenance release.
Two new environment variables for debug mode
--------------------------------------------
In debug mode, the ``[xxx refs]`` statistic is not written by default, the
:envvar:`PYTHONSHOWREFCOUNT` environment variable now must also be set.
(Contributed by Victor Stinner; :issue:`31733`.)
When Python is compiled with ``COUNT_ALLOC`` defined, allocation counts are no
longer dumped by default anymore: the :envvar:`PYTHONSHOWALLOCCOUNT` environment
variable must now also be set. Moreover, allocation counts are now dumped into
stderr, rather than stdout. (Contributed by Victor Stinner; :issue:`31692`.)
.. versionadded:: 2.7.15
PEP 434: IDLE Enhancement Exception for All Branches
----------------------------------------------------
:pep:`434` describes a general exemption for changes made to the IDLE
development environment shipped along with Python. This exemption makes it
possible for the IDLE developers to provide a more consistent user
experience across all supported versions of Python 2 and 3.
For details of any IDLE changes, refer to the NEWS file for the specific
release.
PEP 466: Network Security Enhancements for Python 2.7
-----------------------------------------------------
:pep:`466` describes a number of network security enhancement proposals
that have been approved for inclusion in Python 2.7 maintenance releases,
with the first of those changes appearing in the Python 2.7.7 release.
:pep:`466` related features added in Python 2.7.7:
* :func:`hmac.compare_digest` was backported from Python 3 to make a timing
attack resistant comparison operation available to Python 2 applications.
(Contributed by Alex Gaynor; :issue:`21306`.)
* OpenSSL 1.0.1g was upgraded in the official Windows installers published on
python.org. (Contributed by Zachary Ware; :issue:`21462`.)
:pep:`466` related features added in Python 2.7.8:
* :func:`hashlib.pbkdf2_hmac` was backported from Python 3 to make a hashing
algorithm suitable for secure password storage broadly available to Python
2 applications. (Contributed by Alex Gaynor; :issue:`21304`.)
* OpenSSL 1.0.1h was upgraded for the official Windows installers published on
python.org. (contributed by Zachary Ware in :issue:`21671` for CVE-2014-0224)
:pep:`466` related features added in Python 2.7.9:
* Most of Python 3.4's :mod:`ssl` module was backported. This means :mod:`ssl`
now supports Server Name Indication, TLS1.x settings, access to the platform
certificate store, the :class:`~ssl.SSLContext` class, and other
features. (Contributed by Alex Gaynor and David Reid; :issue:`21308`.)
Refer to the "Version added: 2.7.9" notes in the module documentation for
specific details.
* :func:`os.urandom` was changed to cache a file descriptor to ``/dev/urandom``
instead of reopening ``/dev/urandom`` on every call. (Contributed by Alex
Gaynor; :issue:`21305`.)
* :data:`hashlib.algorithms_guaranteed` and
:data:`hashlib.algorithms_available` were backported from Python 3 to make
it easier for Python 2 applications to select the strongest available hash
algorithm. (Contributed by Alex Gaynor in :issue:`21307`)
PEP 477: Backport ensurepip (PEP 453) to Python 2.7
---------------------------------------------------
:pep:`477` approves the inclusion of the :pep:`453` ensurepip module and the
improved documentation that was enabled by it in the Python 2.7 maintenance
releases, appearing first in the Python 2.7.9 release.
Bootstrapping pip By Default
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The new :mod:`ensurepip` module (defined in :pep:`453`) provides a standard
cross-platform mechanism to bootstrap the pip installer into Python
installations. The version of ``pip`` included with Python 2.7.9 is ``pip``
1.5.6, and future 2.7.x maintenance releases will update the bundled version to
the latest version of ``pip`` that is available at the time of creating the
release candidate.
By default, the commands ``pip``, ``pipX`` and ``pipX.Y`` will be installed on
all platforms (where X.Y stands for the version of the Python installation),
along with the ``pip`` Python package and its dependencies.
For CPython :ref:`source builds on POSIX systems <building-python-on-unix>`,
the ``make install`` and ``make altinstall`` commands do not bootstrap ``pip``
by default. This behaviour can be controlled through configure options, and
overridden through Makefile options.
On Windows and Mac OS X, the CPython installers now default to installing
``pip`` along with CPython itself (users may opt out of installing it
during the installation process). Window users will need to opt in to the
automatic ``PATH`` modifications to have ``pip`` available from the command
line by default, otherwise it can still be accessed through the Python
launcher for Windows as ``py -m pip``.
As `discussed in the PEP`__, platform packagers may choose not to install
these commands by default, as long as, when invoked, they provide clear and
simple directions on how to install them on that platform (usually using
the system package manager).
__ https://www.python.org/dev/peps/pep-0477/#disabling-ensurepip-by-downstream-distributors
Documentation Changes
~~~~~~~~~~~~~~~~~~~~~
As part of this change, the :ref:`installing-index` and
:ref:`distributing-index` sections of the documentation have been
completely redesigned as short getting started and FAQ documents. Most
packaging documentation has now been moved out to the Python Packaging
Authority maintained `Python Packaging User Guide
<http://packaging.python.org>`__ and the documentation of the individual
projects.
However, as this migration is currently still incomplete, the legacy
versions of those guides remaining available as :ref:`install-index`
and :ref:`distutils-index`.
.. seealso::
:pep:`453` -- Explicit bootstrapping of pip in Python installations
PEP written by Donald Stufft and Nick Coghlan, implemented by
Donald Stufft, Nick Coghlan, Martin von Löwis and Ned Deily.
PEP 476: Enabling certificate verification by default for stdlib http clients
-----------------------------------------------------------------------------
:pep:`476` updated :mod:`httplib` and modules which use it, such as
:mod:`urllib2` and :mod:`xmlrpclib`, to now verify that the server
presents a certificate which is signed by a Certificate Authority in the
platform trust store and whose hostname matches the hostname being requested
by default, significantly improving security for many applications. This
change was made in the Python 2.7.9 release.
For applications which require the old previous behavior, they can pass an
alternate context::
import urllib2
import ssl
# This disables all verification
context = ssl._create_unverified_context()
# This allows using a specific certificate for the host, which doesn't need
# to be in the trust store
context = ssl.create_default_context(cafile="/path/to/file.crt")
urllib2.urlopen("https://invalid-cert", context=context)
PEP 493: HTTPS verification migration tools for Python 2.7
----------------------------------------------------------
:pep:`493` provides additional migration tools to support a more incremental
infrastructure upgrade process for environments containing applications and
services relying on the historically permissive processing of server
certificates when establishing client HTTPS connections. These additions were
made in the Python 2.7.12 release.
These tools are intended for use in cases where affected applications and
services can't be modified to explicitly pass a more permissive SSL context
when establishing the connection.
For applications and services which can't be modified at all, the new
``PYTHONHTTPSVERIFY`` environment variable may be set to ``0`` to revert an
entire Python process back to the default permissive behaviour of Python 2.7.8
and earlier.
For cases where the connection establishment code can't be modified, but the
overall application can be, the new :func:`ssl._https_verify_certificates`
function can be used to adjust the default behaviour at runtime.
New ``make regen-all`` build target
-----------------------------------
To simplify cross-compilation, and to ensure that CPython can reliably be
compiled without requiring an existing version of Python to already be
available, the autotools-based build system no longer attempts to implicitly
recompile generated files based on file modification times.
Instead, a new ``make regen-all`` command has been added to force regeneration
of these files when desired (e.g. after an initial version of Python has
already been built based on the pregenerated versions).
More selective regeneration targets are also defined - see
:source:`Makefile.pre.in` for details.
(Contributed by Victor Stinner in :issue:`23404`.)
.. versionadded:: 2.7.14
Removal of ``make touch`` build target
--------------------------------------
The ``make touch`` build target previously used to request implicit regeneration
of generated files by updating their modification times has been removed.
It has been replaced by the new ``make regen-all`` target.
(Contributed by Victor Stinner in :issue:`23404`.)
.. versionchanged:: 2.7.14
.. ======================================================================
.. _acks27:
Acknowledgements
================
The author would like to thank the following people for offering
suggestions, corrections and assistance with various drafts of this
article: Nick Coghlan, Philip Jenvey, Ryan Lovett, R. David Murray,
Hugh Secker-Walker.
PK
%�\U��� � $ html/_sources/whatsnew/index.rst.txtnu �[��� .. _whatsnew-index:
######################
What's New in Python
######################
The "What's New in Python" series of essays takes tours through the most
important changes between major Python versions. They are a "must read" for
anyone wishing to stay up-to-date after a new release.
.. toctree::
:maxdepth: 2
2.7.rst
2.6.rst
2.5.rst
2.4.rst
2.3.rst
2.2.rst
2.1.rst
2.0.rst
PK
%�\~7��� � html/_sources/about.rst.txtnu �[��� =====================
About these documents
=====================
These documents are generated from `reStructuredText`_ sources by `Sphinx`_, a
document processor specifically written for the Python documentation.
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
.. _Sphinx: http://sphinx-doc.org/
.. In the online version of these documents, you can submit comments and suggest
changes directly on the documentation pages.
Development of the documentation and its toolchain is an entirely volunteer
effort, just like Python itself. If you want to contribute, please take a
look at the :ref:`reporting-bugs` page for information on how to do so. New
volunteers are always welcome!
Many thanks go to:
* Fred L. Drake, Jr., the creator of the original Python documentation toolset
and writer of much of the content;
* the `Docutils <http://docutils.sourceforge.net/>`_ project for creating
reStructuredText and the Docutils suite;
* Fredrik Lundh for his `Alternative Python Reference
<http://effbot.org/zone/pyref.htm>`_ project from which Sphinx got many good
ideas.
Contributors to the Python Documentation
----------------------------------------
Many people have contributed to the Python language, the Python standard
library, and the Python documentation. See :source:`Misc/ACKS` in the Python
source distribution for a partial list of contributors.
It is only with the input and contributions of the Python community
that Python has such wonderful documentation -- Thank You!
PK
%�\ �@� html/_sources/bugs.rst.txtnu �[��� .. _reporting-bugs:
**************
Reporting Bugs
**************
Python is a mature programming language which has established a reputation for
stability. In order to maintain this reputation, the developers would like to
know of any deficiencies you find in Python.
Documentation bugs
==================
If you find a bug in this documentation or would like to propose an improvement,
please submit a bug report on the :ref:`tracker <using-the-tracker>`. If you
have a suggestion on how to fix it, include that as well.
If you're short on time, you can also email documentation bug reports to
docs@python.org (behavioral bugs can be sent to python-list@python.org).
'docs@' is a mailing list run by volunteers; your request will be noticed,
though it may take a while to be processed.
.. seealso::
`Documentation bugs`_ on the Python issue tracker
.. _using-the-tracker:
Using the Python issue tracker
==============================
Bug reports for Python itself should be submitted via the Python Bug Tracker
(https://bugs.python.org/). The bug tracker offers a Web form which allows
pertinent information to be entered and submitted to the developers.
The first step in filing a report is to determine whether the problem has
already been reported. The advantage in doing so, aside from saving the
developers time, is that you learn what has been done to fix it; it may be that
the problem has already been fixed for the next release, or additional
information is needed (in which case you are welcome to provide it if you can!).
To do this, search the bug database using the search box on the top of the page.
If the problem you're reporting is not already in the bug tracker, go back to
the Python Bug Tracker and log in. If you don't already have a tracker account,
select the "Register" link or, if you use OpenID, one of the OpenID provider
logos in the sidebar. It is not possible to submit a bug report anonymously.
Being now logged in, you can submit a bug. Select the "Create New" link in the
sidebar to open the bug reporting form.
The submission form has a number of fields. For the "Title" field, enter a
*very* short description of the problem; less than ten words is good. In the
"Type" field, select the type of your problem; also select the "Component" and
"Versions" to which the bug relates.
In the "Comment" field, describe the problem in detail, including what you
expected to happen and what did happen. Be sure to include whether any
extension modules were involved, and what hardware and software platform you
were using (including version information as appropriate).
Each bug report will be assigned to a developer who will determine what needs to
be done to correct the problem. You will receive an update each time action is
taken on the bug.
.. seealso::
`How to Report Bugs Effectively <http://www.chiark.greenend.org.uk/~sgtatham/bugs.html>`_
Article which goes into some detail about how to create a useful bug report.
This describes what kind of information is useful and why it is useful.
`Bug Writing Guidelines <https://developer.mozilla.org/en-US/docs/Mozilla/QA/Bug_writing_guidelines>`_
Information about writing a good bug report. Some of this is specific to the
Mozilla project, but describes general good practices.
Getting started contributing to Python yourself
===============================================
Beyond just reporting bugs that you find, you are also welcome to submit
patches to fix them. You can find more information on how to get started
patching Python in the `Python Developer's Guide`_. If you have questions,
the `core-mentorship mailing list`_ is a friendly place to get answers to
any and all questions pertaining to the process of fixing issues in Python.
.. _Documentation bugs: https://bugs.python.org/issue?@filter=status&@filter=components&components=4&status=1&@columns=id,activity,title,status&@sort=-activity
.. _Python Developer's Guide: https://devguide.python.org/
.. _core-mentorship mailing list: https://mail.python.org/mailman3/lists/core-mentorship.python.org/
PK
%�\�oL html/_sources/contents.rst.txtnu �[��� %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Python Documentation contents
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
.. toctree::
whatsnew/index.rst
tutorial/index.rst
using/index.rst
reference/index.rst
library/index.rst
extending/index.rst
c-api/index.rst
distributing/index.rst
installing/index.rst
howto/index.rst
faq/index.rst
glossary.rst
about.rst
bugs.rst
copyright.rst
license.rst
.. to include legacy packaging docs in build
.. toctree::
:hidden:
distutils/index.rst
install/index.rst
PK
%�\˗�� � html/_sources/copyright.rst.txtnu �[��� *********
Copyright
*********
Python and this documentation is:
Copyright © 2001-2019 Python Software Foundation. All rights reserved.
Copyright © 2000 BeOpen.com. All rights reserved.
Copyright © 1995-2000 Corporation for National Research Initiatives. All rights
reserved.
Copyright © 1991-1995 Stichting Mathematisch Centrum. All rights reserved.
-------
See :ref:`history-and-license` for complete license and permissions information.
PK
%�\�WV�� � html/_sources/glossary.rst.txtnu �[��� .. _glossary:
********
Glossary
********
.. if you add new entries, keep the alphabetical sorting!
.. glossary::
``>>>``
The default Python prompt of the interactive shell. Often seen for code
examples which can be executed interactively in the interpreter.
``...``
The default Python prompt of the interactive shell when entering code for
an indented code block, when within a pair of matching left and right
delimiters (parentheses, square brackets, curly braces or triple quotes),
or after specifying a decorator.
2to3
A tool that tries to convert Python 2.x code to Python 3.x code by
handling most of the incompatibilities which can be detected by parsing the
source and traversing the parse tree.
2to3 is available in the standard library as :mod:`lib2to3`; a standalone
entry point is provided as :file:`Tools/scripts/2to3`. See
:ref:`2to3-reference`.
abstract base class
Abstract base classes complement :term:`duck-typing` by
providing a way to define interfaces when other techniques like
:func:`hasattr` would be clumsy or subtly wrong (for example with
:ref:`magic methods <new-style-special-lookup>`). ABCs introduce virtual
subclasses, which are classes that don't inherit from a class but are
still recognized by :func:`isinstance` and :func:`issubclass`; see the
:mod:`abc` module documentation. Python comes with many built-in ABCs for
data structures (in the :mod:`collections` module), numbers (in the
:mod:`numbers` module), and streams (in the :mod:`io` module). You can
create your own ABCs with the :mod:`abc` module.
argument
A value passed to a :term:`function` (or :term:`method`) when calling the
function. There are two types of arguments:
* :dfn:`keyword argument`: an argument preceded by an identifier (e.g.
``name=``) in a function call or passed as a value in a dictionary
preceded by ``**``. For example, ``3`` and ``5`` are both keyword
arguments in the following calls to :func:`complex`::
complex(real=3, imag=5)
complex(**{'real': 3, 'imag': 5})
* :dfn:`positional argument`: an argument that is not a keyword argument.
Positional arguments can appear at the beginning of an argument list
and/or be passed as elements of an :term:`iterable` preceded by ``*``.
For example, ``3`` and ``5`` are both positional arguments in the
following calls::
complex(3, 5)
complex(*(3, 5))
Arguments are assigned to the named local variables in a function body.
See the :ref:`calls` section for the rules governing this assignment.
Syntactically, any expression can be used to represent an argument; the
evaluated value is assigned to the local variable.
See also the :term:`parameter` glossary entry and the FAQ question on
:ref:`the difference between arguments and parameters
<faq-argument-vs-parameter>`.
attribute
A value associated with an object which is referenced by name using
dotted expressions. For example, if an object *o* has an attribute
*a* it would be referenced as *o.a*.
BDFL
Benevolent Dictator For Life, a.k.a. `Guido van Rossum
<https://www.python.org/~guido/>`_, Python's creator.
bytes-like object
An object that supports the :ref:`buffer protocol <bufferobjects>`,
like :class:`str`, :class:`bytearray` or :class:`memoryview`.
Bytes-like objects can be used for various operations that expect
binary data, such as compression, saving to a binary file or sending
over a socket. Some operations need the binary data to be mutable,
in which case not all bytes-like objects can apply.
bytecode
Python source code is compiled into bytecode, the internal representation
of a Python program in the CPython interpreter. The bytecode is also
cached in ``.pyc`` and ``.pyo`` files so that executing the same file is
faster the second time (recompilation from source to bytecode can be
avoided). This "intermediate language" is said to run on a
:term:`virtual machine` that executes the machine code corresponding to
each bytecode. Do note that bytecodes are not expected to work between
different Python virtual machines, nor to be stable between Python
releases.
A list of bytecode instructions can be found in the documentation for
:ref:`the dis module <bytecodes>`.
class
A template for creating user-defined objects. Class definitions
normally contain method definitions which operate on instances of the
class.
classic class
Any class which does not inherit from :class:`object`. See
:term:`new-style class`. Classic classes have been removed in Python 3.
coercion
The implicit conversion of an instance of one type to another during an
operation which involves two arguments of the same type. For example,
``int(3.15)`` converts the floating point number to the integer ``3``, but
in ``3+4.5``, each argument is of a different type (one int, one float),
and both must be converted to the same type before they can be added or it
will raise a ``TypeError``. Coercion between two operands can be
performed with the ``coerce`` built-in function; thus, ``3+4.5`` is
equivalent to calling ``operator.add(*coerce(3, 4.5))`` and results in
``operator.add(3.0, 4.5)``. Without coercion, all arguments of even
compatible types would have to be normalized to the same value by the
programmer, e.g., ``float(3)+4.5`` rather than just ``3+4.5``.
complex number
An extension of the familiar real number system in which all numbers are
expressed as a sum of a real part and an imaginary part. Imaginary
numbers are real multiples of the imaginary unit (the square root of
``-1``), often written ``i`` in mathematics or ``j`` in
engineering. Python has built-in support for complex numbers, which are
written with this latter notation; the imaginary part is written with a
``j`` suffix, e.g., ``3+1j``. To get access to complex equivalents of the
:mod:`math` module, use :mod:`cmath`. Use of complex numbers is a fairly
advanced mathematical feature. If you're not aware of a need for them,
it's almost certain you can safely ignore them.
context manager
An object which controls the environment seen in a :keyword:`with`
statement by defining :meth:`__enter__` and :meth:`__exit__` methods.
See :pep:`343`.
CPython
The canonical implementation of the Python programming language, as
distributed on `python.org <https://www.python.org>`_. The term "CPython"
is used when necessary to distinguish this implementation from others
such as Jython or IronPython.
decorator
A function returning another function, usually applied as a function
transformation using the ``@wrapper`` syntax. Common examples for
decorators are :func:`classmethod` and :func:`staticmethod`.
The decorator syntax is merely syntactic sugar, the following two
function definitions are semantically equivalent::
def f(...):
...
f = staticmethod(f)
@staticmethod
def f(...):
...
The same concept exists for classes, but is less commonly used there. See
the documentation for :ref:`function definitions <function>` and
:ref:`class definitions <class>` for more about decorators.
descriptor
Any *new-style* object which defines the methods :meth:`__get__`,
:meth:`__set__`, or :meth:`__delete__`. When a class attribute is a
descriptor, its special binding behavior is triggered upon attribute
lookup. Normally, using *a.b* to get, set or delete an attribute looks up
the object named *b* in the class dictionary for *a*, but if *b* is a
descriptor, the respective descriptor method gets called. Understanding
descriptors is a key to a deep understanding of Python because they are
the basis for many features including functions, methods, properties,
class methods, static methods, and reference to super classes.
For more information about descriptors' methods, see :ref:`descriptors`.
dictionary
An associative array, where arbitrary keys are mapped to values. The
keys can be any object with :meth:`__hash__` and :meth:`__eq__` methods.
Called a hash in Perl.
dictionary view
The objects returned from :meth:`dict.viewkeys`, :meth:`dict.viewvalues`,
and :meth:`dict.viewitems` are called dictionary views. They provide a dynamic
view on the dictionary’s entries, which means that when the dictionary
changes, the view reflects these changes. To force the
dictionary view to become a full list use ``list(dictview)``. See
:ref:`dict-views`.
docstring
A string literal which appears as the first expression in a class,
function or module. While ignored when the suite is executed, it is
recognized by the compiler and put into the :attr:`__doc__` attribute
of the enclosing class, function or module. Since it is available via
introspection, it is the canonical place for documentation of the
object.
duck-typing
A programming style which does not look at an object's type to determine
if it has the right interface; instead, the method or attribute is simply
called or used ("If it looks like a duck and quacks like a duck, it
must be a duck.") By emphasizing interfaces rather than specific types,
well-designed code improves its flexibility by allowing polymorphic
substitution. Duck-typing avoids tests using :func:`type` or
:func:`isinstance`. (Note, however, that duck-typing can be complemented
with :term:`abstract base classes <abstract base class>`.) Instead, it
typically employs :func:`hasattr` tests or :term:`EAFP` programming.
EAFP
Easier to ask for forgiveness than permission. This common Python coding
style assumes the existence of valid keys or attributes and catches
exceptions if the assumption proves false. This clean and fast style is
characterized by the presence of many :keyword:`try` and :keyword:`except`
statements. The technique contrasts with the :term:`LBYL` style
common to many other languages such as C.
expression
A piece of syntax which can be evaluated to some value. In other words,
an expression is an accumulation of expression elements like literals,
names, attribute access, operators or function calls which all return a
value. In contrast to many other languages, not all language constructs
are expressions. There are also :term:`statement`\s which cannot be used
as expressions, such as :keyword:`print` or :keyword:`if`. Assignments
are also statements, not expressions.
extension module
A module written in C or C++, using Python's C API to interact with the
core and with user code.
file object
An object exposing a file-oriented API (with methods such as
:meth:`read()` or :meth:`write()`) to an underlying resource. Depending
on the way it was created, a file object can mediate access to a real
on-disk file or to another type of storage or communication device
(for example standard input/output, in-memory buffers, sockets, pipes,
etc.). File objects are also called :dfn:`file-like objects` or
:dfn:`streams`.
There are actually three categories of file objects: raw binary files,
buffered binary files and text files. Their interfaces are defined in the
:mod:`io` module. The canonical way to create a file object is by using
the :func:`open` function.
file-like object
A synonym for :term:`file object`.
finder
An object that tries to find the :term:`loader` for a module. It must
implement a method named :meth:`find_module`. See :pep:`302` for
details.
floor division
Mathematical division that rounds down to nearest integer. The floor
division operator is ``//``. For example, the expression ``11 // 4``
evaluates to ``2`` in contrast to the ``2.75`` returned by float true
division. Note that ``(-11) // 4`` is ``-3`` because that is ``-2.75``
rounded *downward*. See :pep:`238`.
function
A series of statements which returns some value to a caller. It can also
be passed zero or more :term:`arguments <argument>` which may be used in
the execution of the body. See also :term:`parameter`, :term:`method`,
and the :ref:`function` section.
__future__
A pseudo-module which programmers can use to enable new language features
which are not compatible with the current interpreter. For example, the
expression ``11/4`` currently evaluates to ``2``. If the module in which
it is executed had enabled *true division* by executing::
from __future__ import division
the expression ``11/4`` would evaluate to ``2.75``. By importing the
:mod:`__future__` module and evaluating its variables, you can see when a
new feature was first added to the language and when it will become the
default::
>>> import __future__
>>> __future__.division
_Feature((2, 2, 0, 'alpha', 2), (3, 0, 0, 'alpha', 0), 8192)
garbage collection
The process of freeing memory when it is not used anymore. Python
performs garbage collection via reference counting and a cyclic garbage
collector that is able to detect and break reference cycles.
.. index:: single: generator
generator
A function which returns an iterator. It looks like a normal function
except that it contains :keyword:`yield` statements for producing a series
of values usable in a for-loop or that can be retrieved one at a time with
the :func:`next` function. Each :keyword:`yield` temporarily suspends
processing, remembering the location execution state (including local
variables and pending try-statements). When the generator resumes, it
picks up where it left off (in contrast to functions which start fresh on
every invocation).
.. index:: single: generator expression
generator expression
An expression that returns an iterator. It looks like a normal expression
followed by a :keyword:`for` expression defining a loop variable, range,
and an optional :keyword:`if` expression. The combined expression
generates values for an enclosing function::
>>> sum(i*i for i in range(10)) # sum of squares 0, 1, 4, ... 81
285
GIL
See :term:`global interpreter lock`.
global interpreter lock
The mechanism used by the :term:`CPython` interpreter to assure that
only one thread executes Python :term:`bytecode` at a time.
This simplifies the CPython implementation by making the object model
(including critical built-in types such as :class:`dict`) implicitly
safe against concurrent access. Locking the entire interpreter
makes it easier for the interpreter to be multi-threaded, at the
expense of much of the parallelism afforded by multi-processor
machines.
However, some extension modules, either standard or third-party,
are designed so as to release the GIL when doing computationally-intensive
tasks such as compression or hashing. Also, the GIL is always released
when doing I/O.
Past efforts to create a "free-threaded" interpreter (one which locks
shared data at a much finer granularity) have not been successful
because performance suffered in the common single-processor case. It
is believed that overcoming this performance issue would make the
implementation much more complicated and therefore costlier to maintain.
hashable
An object is *hashable* if it has a hash value which never changes during
its lifetime (it needs a :meth:`__hash__` method), and can be compared to
other objects (it needs an :meth:`__eq__` or :meth:`__cmp__` method).
Hashable objects which compare equal must have the same hash value.
Hashability makes an object usable as a dictionary key and a set member,
because these data structures use the hash value internally.
All of Python's immutable built-in objects are hashable, while no mutable
containers (such as lists or dictionaries) are. Objects which are
instances of user-defined classes are hashable by default; they all
compare unequal (except with themselves), and their hash value is derived
from their :func:`id`.
IDLE
An Integrated Development Environment for Python. IDLE is a basic editor
and interpreter environment which ships with the standard distribution of
Python.
immutable
An object with a fixed value. Immutable objects include numbers, strings and
tuples. Such an object cannot be altered. A new object has to
be created if a different value has to be stored. They play an important
role in places where a constant hash value is needed, for example as a key
in a dictionary.
integer division
Mathematical division discarding any remainder. For example, the
expression ``11/4`` currently evaluates to ``2`` in contrast to the
``2.75`` returned by float division. Also called *floor division*.
When dividing two integers the outcome will always be another integer
(having the floor function applied to it). However, if one of the operands
is another numeric type (such as a :class:`float`), the result will be
coerced (see :term:`coercion`) to a common type. For example, an integer
divided by a float will result in a float value, possibly with a decimal
fraction. Integer division can be forced by using the ``//`` operator
instead of the ``/`` operator. See also :term:`__future__`.
importing
The process by which Python code in one module is made available to
Python code in another module.
importer
An object that both finds and loads a module; both a
:term:`finder` and :term:`loader` object.
interactive
Python has an interactive interpreter which means you can enter
statements and expressions at the interpreter prompt, immediately
execute them and see their results. Just launch ``python`` with no
arguments (possibly by selecting it from your computer's main
menu). It is a very powerful way to test out new ideas or inspect
modules and packages (remember ``help(x)``).
interpreted
Python is an interpreted language, as opposed to a compiled one,
though the distinction can be blurry because of the presence of the
bytecode compiler. This means that source files can be run directly
without explicitly creating an executable which is then run.
Interpreted languages typically have a shorter development/debug cycle
than compiled ones, though their programs generally also run more
slowly. See also :term:`interactive`.
iterable
An object capable of returning its members one at a time. Examples of
iterables include all sequence types (such as :class:`list`, :class:`str`,
and :class:`tuple`) and some non-sequence types like :class:`dict`
and :class:`file` and objects of any classes you define
with an :meth:`__iter__` or :meth:`__getitem__` method. Iterables can be
used in a :keyword:`for` loop and in many other places where a sequence is
needed (:func:`zip`, :func:`map`, ...). When an iterable object is passed
as an argument to the built-in function :func:`iter`, it returns an
iterator for the object. This iterator is good for one pass over the set
of values. When using iterables, it is usually not necessary to call
:func:`iter` or deal with iterator objects yourself. The ``for``
statement does that automatically for you, creating a temporary unnamed
variable to hold the iterator for the duration of the loop. See also
:term:`iterator`, :term:`sequence`, and :term:`generator`.
iterator
An object representing a stream of data. Repeated calls to the iterator's
:meth:`~generator.next` method return successive items in the stream. When no more
data are available a :exc:`StopIteration` exception is raised instead. At
this point, the iterator object is exhausted and any further calls to its
:meth:`~generator.next` method just raise :exc:`StopIteration` again. Iterators are
required to have an :meth:`__iter__` method that returns the iterator
object itself so every iterator is also iterable and may be used in most
places where other iterables are accepted. One notable exception is code
which attempts multiple iteration passes. A container object (such as a
:class:`list`) produces a fresh new iterator each time you pass it to the
:func:`iter` function or use it in a :keyword:`for` loop. Attempting this
with an iterator will just return the same exhausted iterator object used
in the previous iteration pass, making it appear like an empty container.
More information can be found in :ref:`typeiter`.
key function
A key function or collation function is a callable that returns a value
used for sorting or ordering. For example, :func:`locale.strxfrm` is
used to produce a sort key that is aware of locale specific sort
conventions.
A number of tools in Python accept key functions to control how elements
are ordered or grouped. They include :func:`min`, :func:`max`,
:func:`sorted`, :meth:`list.sort`, :func:`heapq.nsmallest`,
:func:`heapq.nlargest`, and :func:`itertools.groupby`.
There are several ways to create a key function. For example. the
:meth:`str.lower` method can serve as a key function for case insensitive
sorts. Alternatively, an ad-hoc key function can be built from a
:keyword:`lambda` expression such as ``lambda r: (r[0], r[2])``. Also,
the :mod:`operator` module provides three key function constructors:
:func:`~operator.attrgetter`, :func:`~operator.itemgetter`, and
:func:`~operator.methodcaller`. See the :ref:`Sorting HOW TO
<sortinghowto>` for examples of how to create and use key functions.
keyword argument
See :term:`argument`.
lambda
An anonymous inline function consisting of a single :term:`expression`
which is evaluated when the function is called. The syntax to create
a lambda function is ``lambda [parameters]: expression``
LBYL
Look before you leap. This coding style explicitly tests for
pre-conditions before making calls or lookups. This style contrasts with
the :term:`EAFP` approach and is characterized by the presence of many
:keyword:`if` statements.
In a multi-threaded environment, the LBYL approach can risk introducing a
race condition between "the looking" and "the leaping". For example, the
code, ``if key in mapping: return mapping[key]`` can fail if another
thread removes *key* from *mapping* after the test, but before the lookup.
This issue can be solved with locks or by using the EAFP approach.
list
A built-in Python :term:`sequence`. Despite its name it is more akin
to an array in other languages than to a linked list since access to
elements is O(1).
list comprehension
A compact way to process all or part of the elements in a sequence and
return a list with the results. ``result = ["0x%02x" % x for x in
range(256) if x % 2 == 0]`` generates a list of strings containing
even hex numbers (0x..) in the range from 0 to 255. The :keyword:`if`
clause is optional. If omitted, all elements in ``range(256)`` are
processed.
loader
An object that loads a module. It must define a method named
:meth:`load_module`. A loader is typically returned by a
:term:`finder`. See :pep:`302` for details.
mapping
A container object that supports arbitrary key lookups and implements the
methods specified in the :class:`~collections.Mapping` or
:class:`~collections.MutableMapping`
:ref:`abstract base classes <collections-abstract-base-classes>`. Examples
include :class:`dict`, :class:`collections.defaultdict`,
:class:`collections.OrderedDict` and :class:`collections.Counter`.
metaclass
The class of a class. Class definitions create a class name, a class
dictionary, and a list of base classes. The metaclass is responsible for
taking those three arguments and creating the class. Most object oriented
programming languages provide a default implementation. What makes Python
special is that it is possible to create custom metaclasses. Most users
never need this tool, but when the need arises, metaclasses can provide
powerful, elegant solutions. They have been used for logging attribute
access, adding thread-safety, tracking object creation, implementing
singletons, and many other tasks.
More information can be found in :ref:`metaclasses`.
method
A function which is defined inside a class body. If called as an attribute
of an instance of that class, the method will get the instance object as
its first :term:`argument` (which is usually called ``self``).
See :term:`function` and :term:`nested scope`.
method resolution order
Method Resolution Order is the order in which base classes are searched
for a member during lookup. See `The Python 2.3 Method Resolution Order
<https://www.python.org/download/releases/2.3/mro/>`_ for details of the
algorithm used by the Python interpreter since the 2.3 release.
module
An object that serves as an organizational unit of Python code. Modules
have a namespace containing arbitrary Python objects. Modules are loaded
into Python by the process of :term:`importing`.
See also :term:`package`.
MRO
See :term:`method resolution order`.
mutable
Mutable objects can change their value but keep their :func:`id`. See
also :term:`immutable`.
named tuple
Any tuple-like class whose indexable elements are also accessible using
named attributes (for example, :func:`time.localtime` returns a
tuple-like object where the *year* is accessible either with an
index such as ``t[0]`` or with a named attribute like ``t.tm_year``).
A named tuple can be a built-in type such as :class:`time.struct_time`,
or it can be created with a regular class definition. A full featured
named tuple can also be created with the factory function
:func:`collections.namedtuple`. The latter approach automatically
provides extra features such as a self-documenting representation like
``Employee(name='jones', title='programmer')``.
namespace
The place where a variable is stored. Namespaces are implemented as
dictionaries. There are the local, global and built-in namespaces as well
as nested namespaces in objects (in methods). Namespaces support
modularity by preventing naming conflicts. For instance, the functions
:func:`__builtin__.open` and :func:`os.open` are distinguished by their
namespaces. Namespaces also aid readability and maintainability by making
it clear which module implements a function. For instance, writing
:func:`random.seed` or :func:`itertools.izip` makes it clear that those
functions are implemented by the :mod:`random` and :mod:`itertools`
modules, respectively.
nested scope
The ability to refer to a variable in an enclosing definition. For
instance, a function defined inside another function can refer to
variables in the outer function. Note that nested scopes work only for
reference and not for assignment which will always write to the innermost
scope. In contrast, local variables both read and write in the innermost
scope. Likewise, global variables read and write to the global namespace.
new-style class
Any class which inherits from :class:`object`. This includes all built-in
types like :class:`list` and :class:`dict`. Only new-style classes can
use Python's newer, versatile features like :attr:`~object.__slots__`,
descriptors, properties, and :meth:`__getattribute__`.
More information can be found in :ref:`newstyle`.
object
Any data with state (attributes or value) and defined behavior
(methods). Also the ultimate base class of any :term:`new-style
class`.
package
A Python :term:`module` which can contain submodules or recursively,
subpackages. Technically, a package is a Python module with an
``__path__`` attribute.
parameter
A named entity in a :term:`function` (or method) definition that
specifies an :term:`argument` (or in some cases, arguments) that the
function can accept. There are four types of parameters:
* :dfn:`positional-or-keyword`: specifies an argument that can be passed
either :term:`positionally <argument>` or as a :term:`keyword argument
<argument>`. This is the default kind of parameter, for example *foo*
and *bar* in the following::
def func(foo, bar=None): ...
* :dfn:`positional-only`: specifies an argument that can be supplied only
by position. Python has no syntax for defining positional-only
parameters. However, some built-in functions have positional-only
parameters (e.g. :func:`abs`).
* :dfn:`var-positional`: specifies that an arbitrary sequence of
positional arguments can be provided (in addition to any positional
arguments already accepted by other parameters). Such a parameter can
be defined by prepending the parameter name with ``*``, for example
*args* in the following::
def func(*args, **kwargs): ...
* :dfn:`var-keyword`: specifies that arbitrarily many keyword arguments
can be provided (in addition to any keyword arguments already accepted
by other parameters). Such a parameter can be defined by prepending
the parameter name with ``**``, for example *kwargs* in the example
above.
Parameters can specify both optional and required arguments, as well as
default values for some optional arguments.
See also the :term:`argument` glossary entry, the FAQ question on
:ref:`the difference between arguments and parameters
<faq-argument-vs-parameter>`, and the :ref:`function` section.
PEP
Python Enhancement Proposal. A PEP is a design document
providing information to the Python community, or describing a new
feature for Python or its processes or environment. PEPs should
provide a concise technical specification and a rationale for proposed
features.
PEPs are intended to be the primary mechanisms for proposing major new
features, for collecting community input on an issue, and for documenting
the design decisions that have gone into Python. The PEP author is
responsible for building consensus within the community and documenting
dissenting opinions.
See :pep:`1`.
positional argument
See :term:`argument`.
Python 3000
Nickname for the Python 3.x release line (coined long ago when the release
of version 3 was something in the distant future.) This is also
abbreviated "Py3k".
Pythonic
An idea or piece of code which closely follows the most common idioms
of the Python language, rather than implementing code using concepts
common to other languages. For example, a common idiom in Python is
to loop over all elements of an iterable using a :keyword:`for`
statement. Many other languages don't have this type of construct, so
people unfamiliar with Python sometimes use a numerical counter instead::
for i in range(len(food)):
print food[i]
As opposed to the cleaner, Pythonic method::
for piece in food:
print piece
reference count
The number of references to an object. When the reference count of an
object drops to zero, it is deallocated. Reference counting is
generally not visible to Python code, but it is a key element of the
:term:`CPython` implementation. The :mod:`sys` module defines a
:func:`~sys.getrefcount` function that programmers can call to return the
reference count for a particular object.
__slots__
A declaration inside a :term:`new-style class` that saves memory by
pre-declaring space for instance attributes and eliminating instance
dictionaries. Though popular, the technique is somewhat tricky to get
right and is best reserved for rare cases where there are large numbers of
instances in a memory-critical application.
sequence
An :term:`iterable` which supports efficient element access using integer
indices via the :meth:`__getitem__` special method and defines a
:meth:`len` method that returns the length of the sequence.
Some built-in sequence types are :class:`list`, :class:`str`,
:class:`tuple`, and :class:`unicode`. Note that :class:`dict` also
supports :meth:`__getitem__` and :meth:`__len__`, but is considered a
mapping rather than a sequence because the lookups use arbitrary
:term:`immutable` keys rather than integers.
slice
An object usually containing a portion of a :term:`sequence`. A slice is
created using the subscript notation, ``[]`` with colons between numbers
when several are given, such as in ``variable_name[1:3:5]``. The bracket
(subscript) notation uses :class:`slice` objects internally (or in older
versions, :meth:`__getslice__` and :meth:`__setslice__`).
special method
A method that is called implicitly by Python to execute a certain
operation on a type, such as addition. Such methods have names starting
and ending with double underscores. Special methods are documented in
:ref:`specialnames`.
statement
A statement is part of a suite (a "block" of code). A statement is either
an :term:`expression` or one of several constructs with a keyword, such
as :keyword:`if`, :keyword:`while` or :keyword:`for`.
struct sequence
A tuple with named elements. Struct sequences expose an interface similiar
to :term:`named tuple` in that elements can be accessed either by
index or as an attribute. However, they do not have any of the named tuple
methods like :meth:`~collections.somenamedtuple._make` or
:meth:`~collections.somenamedtuple._asdict`. Examples of struct sequences
include :data:`sys.float_info` and the return value of :func:`os.stat`.
triple-quoted string
A string which is bound by three instances of either a quotation mark
(") or an apostrophe ('). While they don't provide any functionality
not available with single-quoted strings, they are useful for a number
of reasons. They allow you to include unescaped single and double
quotes within a string and they can span multiple lines without the
use of the continuation character, making them especially useful when
writing docstrings.
type
The type of a Python object determines what kind of object it is; every
object has a type. An object's type is accessible as its
:attr:`~instance.__class__` attribute or can be retrieved with
``type(obj)``.
universal newlines
A manner of interpreting text streams in which all of the following are
recognized as ending a line: the Unix end-of-line convention ``'\n'``,
the Windows convention ``'\r\n'``, and the old Macintosh convention
``'\r'``. See :pep:`278` and :pep:`3116`, as well as
:func:`str.splitlines` for an additional use.
virtual environment
A cooperatively isolated runtime environment that allows Python users
and applications to install and upgrade Python distribution packages
without interfering with the behaviour of other Python applications
running on the same system.
virtual machine
A computer defined entirely in software. Python's virtual machine
executes the :term:`bytecode` emitted by the bytecode compiler.
Zen of Python
Listing of Python design principles and philosophies that are helpful in
understanding and using the language. The listing can be found by typing
"``import this``" at the interactive prompt.
PK
%�\>� (L� L� html/_sources/license.rst.txtnu �[��� .. highlightlang:: none
.. _history-and-license:
*******************
History and License
*******************
History of the software
=======================
Python was created in the early 1990s by Guido van Rossum at Stichting
Mathematisch Centrum (CWI, see https://www.cwi.nl/) in the Netherlands as a
successor of a language called ABC. Guido remains Python's principal author,
although it includes many contributions from others.
In 1995, Guido continued his work on Python at the Corporation for National
Research Initiatives (CNRI, see https://www.cnri.reston.va.us/) in Reston,
Virginia where he released several versions of the software.
In May 2000, Guido and the Python core development team moved to BeOpen.com to
form the BeOpen PythonLabs team. In October of the same year, the PythonLabs
team moved to Digital Creations (now Zope Corporation; see
http://www.zope.com/). In 2001, the Python Software Foundation (PSF, see
https://www.python.org/psf/) was formed, a non-profit organization created
specifically to own Python-related Intellectual Property. Zope Corporation is a
sponsoring member of the PSF.
All Python releases are Open Source (see https://opensource.org/ for the Open
Source Definition). Historically, most, but not all, Python releases have also
been GPL-compatible; the table below summarizes the various releases.
+----------------+--------------+-----------+------------+-----------------+
| Release | Derived from | Year | Owner | GPL compatible? |
+================+==============+===========+============+=================+
| 0.9.0 thru 1.2 | n/a | 1991-1995 | CWI | yes |
+----------------+--------------+-----------+------------+-----------------+
| 1.3 thru 1.5.2 | 1.2 | 1995-1999 | CNRI | yes |
+----------------+--------------+-----------+------------+-----------------+
| 1.6 | 1.5.2 | 2000 | CNRI | no |
+----------------+--------------+-----------+------------+-----------------+
| 2.0 | 1.6 | 2000 | BeOpen.com | no |
+----------------+--------------+-----------+------------+-----------------+
| 1.6.1 | 1.6 | 2001 | CNRI | no |
+----------------+--------------+-----------+------------+-----------------+
| 2.1 | 2.0+1.6.1 | 2001 | PSF | no |
+----------------+--------------+-----------+------------+-----------------+
| 2.0.1 | 2.0+1.6.1 | 2001 | PSF | yes |
+----------------+--------------+-----------+------------+-----------------+
| 2.1.1 | 2.1+2.0.1 | 2001 | PSF | yes |
+----------------+--------------+-----------+------------+-----------------+
| 2.1.2 | 2.1.1 | 2002 | PSF | yes |
+----------------+--------------+-----------+------------+-----------------+
| 2.1.3 | 2.1.2 | 2002 | PSF | yes |
+----------------+--------------+-----------+------------+-----------------+
| 2.2 and above | 2.1.1 | 2001-now | PSF | yes |
+----------------+--------------+-----------+------------+-----------------+
.. note::
GPL-compatible doesn't mean that we're distributing Python under the GPL. All
Python licenses, unlike the GPL, let you distribute a modified version without
making your changes open source. The GPL-compatible licenses make it possible to
combine Python with other software that is released under the GPL; the others
don't.
Thanks to the many outside volunteers who have worked under Guido's direction to
make these releases possible.
Terms and conditions for accessing or otherwise using Python
============================================================
PSF LICENSE AGREEMENT FOR PYTHON |release|
------------------------------------------
.. parsed-literal::
1. This LICENSE AGREEMENT is between the Python Software Foundation ("PSF"), and
the Individual or Organization ("Licensee") accessing and otherwise using Python
|release| software in source or binary form and its associated documentation.
2. Subject to the terms and conditions of this License Agreement, PSF hereby
grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce,
analyze, test, perform and/or display publicly, prepare derivative works,
distribute, and otherwise use Python |release| alone or in any derivative
version, provided, however, that PSF's License Agreement and PSF's notice of
copyright, i.e., "Copyright © 2001-2019 Python Software Foundation; All Rights
Reserved" are retained in Python |release| alone or in any derivative version
prepared by Licensee.
3. In the event Licensee prepares a derivative work that is based on or
incorporates Python |release| or any part thereof, and wants to make the
derivative work available to others as provided herein, then Licensee hereby
agrees to include in any such work a brief summary of the changes made to Python
|release|.
4. PSF is making Python |release| available to Licensee on an "AS IS" basis.
PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF
EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND DISCLAIMS ANY REPRESENTATION OR
WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE
USE OF PYTHON |release| WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.
5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON |release|
FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF
MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON |release|, OR ANY DERIVATIVE
THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.
6. This License Agreement will automatically terminate upon a material breach of
its terms and conditions.
7. Nothing in this License Agreement shall be deemed to create any relationship
of agency, partnership, or joint venture between PSF and Licensee. This License
Agreement does not grant permission to use PSF trademarks or trade name in a
trademark sense to endorse or promote products or services of Licensee, or any
third party.
8. By copying, installing or otherwise using Python |release|, Licensee agrees
to be bound by the terms and conditions of this License Agreement.
BEOPEN.COM LICENSE AGREEMENT FOR PYTHON 2.0
-------------------------------------------
BEOPEN PYTHON OPEN SOURCE LICENSE AGREEMENT VERSION 1
.. parsed-literal::
1. This LICENSE AGREEMENT is between BeOpen.com ("BeOpen"), having an office at
160 Saratoga Avenue, Santa Clara, CA 95051, and the Individual or Organization
("Licensee") accessing and otherwise using this software in source or binary
form and its associated documentation ("the Software").
2. Subject to the terms and conditions of this BeOpen Python License Agreement,
BeOpen hereby grants Licensee a non-exclusive, royalty-free, world-wide license
to reproduce, analyze, test, perform and/or display publicly, prepare derivative
works, distribute, and otherwise use the Software alone or in any derivative
version, provided, however, that the BeOpen Python License is retained in the
Software, alone or in any derivative version prepared by Licensee.
3. BeOpen is making the Software available to Licensee on an "AS IS" basis.
BEOPEN MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF
EXAMPLE, BUT NOT LIMITATION, BEOPEN MAKES NO AND DISCLAIMS ANY REPRESENTATION OR
WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE
USE OF THE SOFTWARE WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.
4. BEOPEN SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF THE SOFTWARE FOR
ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF USING,
MODIFYING OR DISTRIBUTING THE SOFTWARE, OR ANY DERIVATIVE THEREOF, EVEN IF
ADVISED OF THE POSSIBILITY THEREOF.
5. This License Agreement will automatically terminate upon a material breach of
its terms and conditions.
6. This License Agreement shall be governed by and interpreted in all respects
by the law of the State of California, excluding conflict of law provisions.
Nothing in this License Agreement shall be deemed to create any relationship of
agency, partnership, or joint venture between BeOpen and Licensee. This License
Agreement does not grant permission to use BeOpen trademarks or trade names in a
trademark sense to endorse or promote products or services of Licensee, or any
third party. As an exception, the "BeOpen Python" logos available at
http://www.pythonlabs.com/logos.html may be used according to the permissions
granted on that web page.
7. By copying, installing or otherwise using the software, Licensee agrees to be
bound by the terms and conditions of this License Agreement.
CNRI LICENSE AGREEMENT FOR PYTHON 1.6.1
---------------------------------------
.. parsed-literal::
1. This LICENSE AGREEMENT is between the Corporation for National Research
Initiatives, having an office at 1895 Preston White Drive, Reston, VA 20191
("CNRI"), and the Individual or Organization ("Licensee") accessing and
otherwise using Python 1.6.1 software in source or binary form and its
associated documentation.
2. Subject to the terms and conditions of this License Agreement, CNRI hereby
grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce,
analyze, test, perform and/or display publicly, prepare derivative works,
distribute, and otherwise use Python 1.6.1 alone or in any derivative version,
provided, however, that CNRI's License Agreement and CNRI's notice of copyright,
i.e., "Copyright © 1995-2001 Corporation for National Research Initiatives; All
Rights Reserved" are retained in Python 1.6.1 alone or in any derivative version
prepared by Licensee. Alternately, in lieu of CNRI's License Agreement,
Licensee may substitute the following text (omitting the quotes): "Python 1.6.1
is made available subject to the terms and conditions in CNRI's License
Agreement. This Agreement together with Python 1.6.1 may be located on the
Internet using the following unique, persistent identifier (known as a handle):
1895.22/1013. This Agreement may also be obtained from a proxy server on the
Internet using the following URL: http://hdl.handle.net/1895.22/1013."
3. In the event Licensee prepares a derivative work that is based on or
incorporates Python 1.6.1 or any part thereof, and wants to make the derivative
work available to others as provided herein, then Licensee hereby agrees to
include in any such work a brief summary of the changes made to Python 1.6.1.
4. CNRI is making Python 1.6.1 available to Licensee on an "AS IS" basis. CNRI
MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE,
BUT NOT LIMITATION, CNRI MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY
OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF
PYTHON 1.6.1 WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.
5. CNRI SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON 1.6.1 FOR
ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF
MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 1.6.1, OR ANY DERIVATIVE
THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.
6. This License Agreement will automatically terminate upon a material breach of
its terms and conditions.
7. This License Agreement shall be governed by the federal intellectual property
law of the United States, including without limitation the federal copyright
law, and, to the extent such U.S. federal law does not apply, by the law of the
Commonwealth of Virginia, excluding Virginia's conflict of law provisions.
Notwithstanding the foregoing, with regard to derivative works based on Python
1.6.1 that incorporate non-separable material that was previously distributed
under the GNU General Public License (GPL), the law of the Commonwealth of
Virginia shall govern this License Agreement only as to issues arising under or
with respect to Paragraphs 4, 5, and 7 of this License Agreement. Nothing in
this License Agreement shall be deemed to create any relationship of agency,
partnership, or joint venture between CNRI and Licensee. This License Agreement
does not grant permission to use CNRI trademarks or trade name in a trademark
sense to endorse or promote products or services of Licensee, or any third
party.
8. By clicking on the "ACCEPT" button where indicated, or by copying, installing
or otherwise using Python 1.6.1, Licensee agrees to be bound by the terms and
conditions of this License Agreement.
CWI LICENSE AGREEMENT FOR PYTHON 0.9.0 THROUGH 1.2
--------------------------------------------------
.. parsed-literal::
Copyright © 1991 - 1995, Stichting Mathematisch Centrum Amsterdam, The
Netherlands. All rights reserved.
Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted, provided that
the above copyright notice appear in all copies and that both that copyright
notice and this permission notice appear in supporting documentation, and that
the name of Stichting Mathematisch Centrum or CWI not be used in advertising or
publicity pertaining to distribution of the software without specific, written
prior permission.
STICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS
SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
EVENT SHALL STICHTING MATHEMATISCH CENTRUM BE LIABLE FOR ANY SPECIAL, INDIRECT
OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
SOFTWARE.
Licenses and Acknowledgements for Incorporated Software
=======================================================
This section is an incomplete, but growing list of licenses and acknowledgements
for third-party software incorporated in the Python distribution.
Mersenne Twister
----------------
The :mod:`_random` module includes code based on a download from
http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/MT2002/emt19937ar.html. The following are
the verbatim comments from the original code::
A C-program for MT19937, with initialization improved 2002/1/26.
Coded by Takuji Nishimura and Makoto Matsumoto.
Before using, initialize the state by using init_genrand(seed)
or init_by_array(init_key, key_length).
Copyright (C) 1997 - 2002, Makoto Matsumoto and Takuji Nishimura,
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
3. The names of its contributors may not be used to endorse or promote
products derived from this software without specific prior written
permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Any feedback is very welcome.
http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html
email: m-mat @ math.sci.hiroshima-u.ac.jp (remove space)
Sockets
-------
The :mod:`socket` module uses the functions, :func:`getaddrinfo`, and
:func:`getnameinfo`, which are coded in separate source files from the WIDE
Project, http://www.wide.ad.jp/. ::
Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project.
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
3. Neither the name of the project nor the names of its contributors
may be used to endorse or promote products derived from this software
without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
Floating point exception control
--------------------------------
The source for the :mod:`fpectl` module includes the following notice::
---------------------------------------------------------------------
/ Copyright (c) 1996. \
| The Regents of the University of California. |
| All rights reserved. |
| |
| Permission to use, copy, modify, and distribute this software for |
| any purpose without fee is hereby granted, provided that this en- |
| tire notice is included in all copies of any software which is or |
| includes a copy or modification of this software and in all |
| copies of the supporting documentation for such software. |
| |
| This work was produced at the University of California, Lawrence |
| Livermore National Laboratory under contract no. W-7405-ENG-48 |
| between the U.S. Department of Energy and The Regents of the |
| University of California for the operation of UC LLNL. |
| |
| DISCLAIMER |
| |
| This software was prepared as an account of work sponsored by an |
| agency of the United States Government. Neither the United States |
| Government nor the University of California nor any of their em- |
| ployees, makes any warranty, express or implied, or assumes any |
| liability or responsibility for the accuracy, completeness, or |
| usefulness of any information, apparatus, product, or process |
| disclosed, or represents that its use would not infringe |
| privately-owned rights. Reference herein to any specific commer- |
| cial products, process, or service by trade name, trademark, |
| manufacturer, or otherwise, does not necessarily constitute or |
| imply its endorsement, recommendation, or favoring by the United |
| States Government or the University of California. The views and |
| opinions of authors expressed herein do not necessarily state or |
| reflect those of the United States Government or the University |
| of California, and shall not be used for advertising or product |
\ endorsement purposes. /
---------------------------------------------------------------------
MD5 message digest algorithm
----------------------------
The source code for the :mod:`md5` module contains the following notice::
Copyright (C) 1999, 2002 Aladdin Enterprises. All rights reserved.
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
arising from the use of this software.
Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:
1. The origin of this software must not be misrepresented; you must not
claim that you wrote the original software. If you use this software
in a product, an acknowledgment in the product documentation would be
appreciated but is not required.
2. Altered source versions must be plainly marked as such, and must not be
misrepresented as being the original software.
3. This notice may not be removed or altered from any source distribution.
L. Peter Deutsch
ghost@aladdin.com
Independent implementation of MD5 (RFC 1321).
This code implements the MD5 Algorithm defined in RFC 1321, whose
text is available at
http://www.ietf.org/rfc/rfc1321.txt
The code is derived from the text of the RFC, including the test suite
(section A.5) but excluding the rest of Appendix A. It does not include
any code or documentation that is identified in the RFC as being
copyrighted.
The original and principal author of md5.h is L. Peter Deutsch
<ghost@aladdin.com>. Other authors are noted in the change history
that follows (in reverse chronological order):
2002-04-13 lpd Removed support for non-ANSI compilers; removed
references to Ghostscript; clarified derivation from RFC 1321;
now handles byte order either statically or dynamically.
1999-11-04 lpd Edited comments slightly for automatic TOC extraction.
1999-10-18 lpd Fixed typo in header comment (ansi2knr rather than md5);
added conditionalization for C++ compilation from Martin
Purschke <purschke@bnl.gov>.
1999-05-03 lpd Original version.
Asynchronous socket services
----------------------------
The :mod:`asynchat` and :mod:`asyncore` modules contain the following notice::
Copyright 1996 by Sam Rushing
All Rights Reserved
Permission to use, copy, modify, and distribute this software and
its documentation for any purpose and without fee is hereby
granted, provided that the above copyright notice appear in all
copies and that both that copyright notice and this permission
notice appear in supporting documentation, and that the name of Sam
Rushing not be used in advertising or publicity pertaining to
distribution of the software without specific, written prior
permission.
SAM RUSHING DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN
NO EVENT SHALL SAM RUSHING BE LIABLE FOR ANY SPECIAL, INDIRECT OR
CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
Cookie management
-----------------
The :mod:`Cookie` module contains the following notice::
Copyright 2000 by Timothy O'Malley <timo@alum.mit.edu>
All Rights Reserved
Permission to use, copy, modify, and distribute this software
and its documentation for any purpose and without fee is hereby
granted, provided that the above copyright notice appear in all
copies and that both that copyright notice and this permission
notice appear in supporting documentation, and that the name of
Timothy O'Malley not be used in advertising or publicity
pertaining to distribution of the software without specific, written
prior permission.
Timothy O'Malley DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS
SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
AND FITNESS, IN NO EVENT SHALL Timothy O'Malley BE LIABLE FOR
ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
PERFORMANCE OF THIS SOFTWARE.
Execution tracing
-----------------
The :mod:`trace` module contains the following notice::
portions copyright 2001, Autonomous Zones Industries, Inc., all rights...
err... reserved and offered to the public under the terms of the
Python 2.2 license.
Author: Zooko O'Whielacronx
http://zooko.com/
mailto:zooko@zooko.com
Copyright 2000, Mojam Media, Inc., all rights reserved.
Author: Skip Montanaro
Copyright 1999, Bioreason, Inc., all rights reserved.
Author: Andrew Dalke
Copyright 1995-1997, Automatrix, Inc., all rights reserved.
Author: Skip Montanaro
Copyright 1991-1995, Stichting Mathematisch Centrum, all rights reserved.
Permission to use, copy, modify, and distribute this Python software and
its associated documentation for any purpose without fee is hereby
granted, provided that the above copyright notice appears in all copies,
and that both that copyright notice and this permission notice appear in
supporting documentation, and that the name of neither Automatrix,
Bioreason or Mojam Media be used in advertising or publicity pertaining to
distribution of the software without specific, written prior permission.
UUencode and UUdecode functions
-------------------------------
The :mod:`uu` module contains the following notice::
Copyright 1994 by Lance Ellinghouse
Cathedral City, California Republic, United States of America.
All Rights Reserved
Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted,
provided that the above copyright notice appear in all copies and that
both that copyright notice and this permission notice appear in
supporting documentation, and that the name of Lance Ellinghouse
not be used in advertising or publicity pertaining to distribution
of the software without specific, written prior permission.
LANCE ELLINGHOUSE DISCLAIMS ALL WARRANTIES WITH REGARD TO
THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS, IN NO EVENT SHALL LANCE ELLINGHOUSE CENTRUM BE LIABLE
FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
Modified by Jack Jansen, CWI, July 1995:
- Use binascii module to do the actual line-by-line conversion
between ascii and binary. This results in a 1000-fold speedup. The C
version is still 5 times faster, though.
- Arguments more compliant with Python standard
XML Remote Procedure Calls
--------------------------
The :mod:`xmlrpclib` module contains the following notice::
The XML-RPC client interface is
Copyright (c) 1999-2002 by Secret Labs AB
Copyright (c) 1999-2002 by Fredrik Lundh
By obtaining, using, and/or copying this software and/or its
associated documentation, you agree that you have read, understood,
and will comply with the following terms and conditions:
Permission to use, copy, modify, and distribute this software and
its associated documentation for any purpose and without fee is
hereby granted, provided that the above copyright notice appears in
all copies, and that both that copyright notice and this permission
notice appear in supporting documentation, and that the name of
Secret Labs AB or the author not be used in advertising or publicity
pertaining to distribution of the software without specific, written
prior permission.
SECRET LABS AB AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD
TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANT-
ABILITY AND FITNESS. IN NO EVENT SHALL SECRET LABS AB OR THE AUTHOR
BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY
DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
OF THIS SOFTWARE.
test_epoll
----------
The :mod:`test_epoll` contains the following notice::
Copyright (c) 2001-2006 Twisted Matrix Laboratories.
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Select kqueue
-------------
The :mod:`select` and contains the following notice for the kqueue interface::
Copyright (c) 2000 Doug White, 2006 James Knight, 2007 Christian Heimes
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
strtod and dtoa
---------------
The file :file:`Python/dtoa.c`, which supplies C functions dtoa and
strtod for conversion of C doubles to and from strings, is derived
from the file of the same name by David M. Gay, currently available
from http://www.netlib.org/fp/. The original file, as retrieved on
March 16, 2009, contains the following copyright and licensing
notice::
/****************************************************************
*
* The author of this software is David M. Gay.
*
* Copyright (c) 1991, 2000, 2001 by Lucent Technologies.
*
* Permission to use, copy, modify, and distribute this software for any
* purpose without fee is hereby granted, provided that this entire notice
* is included in all copies of any software which is or includes a copy
* or modification of this software and in all copies of the supporting
* documentation for such software.
*
* THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED
* WARRANTY. IN PARTICULAR, NEITHER THE AUTHOR NOR LUCENT MAKES ANY
* REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY
* OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE.
*
***************************************************************/
OpenSSL
-------
The modules :mod:`hashlib`, :mod:`posix`, :mod:`ssl`, :mod:`crypt` use
the OpenSSL library for added performance if made available by the
operating system. Additionally, the Windows and Mac OS X installers for
Python may include a copy of the OpenSSL libraries, so we include a copy
of the OpenSSL license here::
LICENSE ISSUES
==============
The OpenSSL toolkit stays under a dual license, i.e. both the conditions of
the OpenSSL License and the original SSLeay license apply to the toolkit.
See below for the actual license texts. Actually both licenses are BSD-style
Open Source licenses. In case of any license issues related to OpenSSL
please contact openssl-core@openssl.org.
OpenSSL License
---------------
/* ====================================================================
* Copyright (c) 1998-2008 The OpenSSL Project. All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. All advertising materials mentioning features or use of this
* software must display the following acknowledgment:
* "This product includes software developed by the OpenSSL Project
* for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
*
* 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
* endorse or promote products derived from this software without
* prior written permission. For written permission, please contact
* openssl-core@openssl.org.
*
* 5. Products derived from this software may not be called "OpenSSL"
* nor may "OpenSSL" appear in their names without prior written
* permission of the OpenSSL Project.
*
* 6. Redistributions of any form whatsoever must retain the following
* acknowledgment:
* "This product includes software developed by the OpenSSL Project
* for use in the OpenSSL Toolkit (http://www.openssl.org/)"
*
* THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
* EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
* PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
* NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
* LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
* STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
* OF THE POSSIBILITY OF SUCH DAMAGE.
* ====================================================================
*
* This product includes cryptographic software written by Eric Young
* (eay@cryptsoft.com). This product includes software written by Tim
* Hudson (tjh@cryptsoft.com).
*
*/
Original SSLeay License
-----------------------
/* Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com)
* All rights reserved.
*
* This package is an SSL implementation written
* by Eric Young (eay@cryptsoft.com).
* The implementation was written so as to conform with Netscapes SSL.
*
* This library is free for commercial and non-commercial use as long as
* the following conditions are aheared to. The following conditions
* apply to all code found in this distribution, be it the RC4, RSA,
* lhash, DES, etc., code; not just the SSL code. The SSL documentation
* included with this distribution is covered by the same copyright terms
* except that the holder is Tim Hudson (tjh@cryptsoft.com).
*
* Copyright remains Eric Young's, and as such any Copyright notices in
* the code are not to be removed.
* If this package is used in a product, Eric Young should be given attribution
* as the author of the parts of the library used.
* This can be in the form of a textual message at program startup or
* in documentation (online or textual) provided with the package.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
* 1. Redistributions of source code must retain the copyright
* notice, this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* 3. All advertising materials mentioning features or use of this software
* must display the following acknowledgement:
* "This product includes cryptographic software written by
* Eric Young (eay@cryptsoft.com)"
* The word 'cryptographic' can be left out if the rouines from the library
* being used are not cryptographic related :-).
* 4. If you include any Windows specific code (or a derivative thereof) from
* the apps directory (application code) you must include an acknowledgement:
* "This product includes software written by Tim Hudson (tjh@cryptsoft.com)"
*
* THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND
* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
* OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
*
* The licence and distribution terms for any publically available version or
* derivative of this code cannot be changed. i.e. this code cannot simply be
* copied and put under another distribution licence
* [including the GNU Public Licence.]
*/
expat
-----
The :mod:`pyexpat` extension is built using an included copy of the expat
sources unless the build is configured ``--with-system-expat``::
Copyright (c) 1998, 1999, 2000 Thai Open Source Software Center Ltd
and Clark Cooper
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
libffi
------
The :mod:`_ctypes` extension is built using an included copy of the libffi
sources unless the build is configured ``--with-system-libffi``::
Copyright (c) 1996-2008 Red Hat, Inc and others.
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
``Software''), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
zlib
----
The :mod:`zlib` extension is built using an included copy of the zlib
sources if the zlib version found on the system is too old to be
used for the build::
Copyright (C) 1995-2010 Jean-loup Gailly and Mark Adler
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
arising from the use of this software.
Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:
1. The origin of this software must not be misrepresented; you must not
claim that you wrote the original software. If you use this software
in a product, an acknowledgment in the product documentation would be
appreciated but is not required.
2. Altered source versions must be plainly marked as such, and must not be
misrepresented as being the original software.
3. This notice may not be removed or altered from any source distribution.
Jean-loup Gailly Mark Adler
jloup@gzip.org madler@alumni.caltech.edu
PK
%�\<>� � html/_static/ajax-loader.gifnu �[��� GIF89a � ���U|���N��U|l��������!�Created with ajaxload.info !�
!� NETSCAPE2.0 , 3��0�Ikc:�N�f E�1º���.`��q�-[9ݦ9 Jk�H !�
, 4��N�! � ���DqBQT`1 `LE[�| �u��a� ��C�%$* !�
, 6�2#+�AȐ̔V/�c �N�IBa��p �
̳� ƨ+Y����2�d�� !�
, 3�b%+�2���V_��� �! 1D�a �F��� bR]�= 08,�Ȥr9L !�
, 2�r'+J�d��L� &v�`\bT���� hYB)��@ �< �&,�ȤR� !�
, 3� 9�t�ڞ0� �!.B���W��1 sa��5���0� ���m)J !�
, 2��� ٜU]���qp�`��a��4��AF�0�`��
�@�1���Α !�
, 2��0�I�eBԜ)� � ��q10�ʰ�P�aVڥ ub��[� ; PK
%�\�o�Ŭ � html/_static/basic.cssnu �[��� /**
* Sphinx stylesheet -- basic theme
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*/
/* -- main layout ----------------------------------------------------------- */
div.clearer {
clear: both;
}
/* -- relbar ---------------------------------------------------------------- */
div.related {
width: 100%;
font-size: 90%;
}
div.related h3 {
display: none;
}
div.related ul {
margin: 0;
padding: 0 0 0 10px;
list-style: none;
}
div.related li {
display: inline;
}
div.related li.right {
float: right;
margin-right: 5px;
}
/* -- sidebar --------------------------------------------------------------- */
div.sphinxsidebarwrapper {
position: relative;
top: 0;
padding: 10px 5px 0 10px;
word-wrap: break-word;
}
div.sphinxsidebar {
float: left;
width: 230px;
margin-left: -100%;
font-size: 90%;
}
div.sphinxsidebar ul {
list-style: none;
}
div.sphinxsidebar ul ul,
div.sphinxsidebar ul.want-points {
margin-left: 20px;
list-style: square;
}
div.sphinxsidebar ul ul {
margin-top: 0;
margin-bottom: 0;
}
div.sphinxsidebar form {
margin-top: 10px;
}
div.sphinxsidebar input {
border: 1px solid #98dbcc;
font-family: sans-serif;
font-size: 1em;
}
img {
border: 0;
}
/* -- search page ----------------------------------------------------------- */
ul.search {
margin: 10px 0 0 20px;
padding: 0;
}
ul.search li {
padding: 5px 0 5px 20px;
background-image: url(file.png);
background-repeat: no-repeat;
background-position: 0 7px;
}
ul.search li a {
font-weight: bold;
}
ul.search li div.context {
color: #888;
margin: 2px 0 0 30px;
text-align: left;
}
ul.keywordmatches li.goodmatch a {
font-weight: bold;
}
/* -- index page ------------------------------------------------------------ */
table.contentstable {
width: 90%;
}
table.contentstable p.biglink {
line-height: 150%;
}
a.biglink {
font-size: 1.3em;
}
span.linkdescr {
font-style: italic;
padding-top: 5px;
font-size: 90%;
}
/* -- general index --------------------------------------------------------- */
table.indextable td {
text-align: left;
vertical-align: top;
}
table.indextable dl, table.indextable dd {
margin-top: 0;
margin-bottom: 0;
}
table.indextable tr.pcap {
height: 10px;
}
table.indextable tr.cap {
margin-top: 10px;
background-color: #f2f2f2;
}
img.toggler {
margin-right: 3px;
margin-top: 3px;
cursor: pointer;
}
/* -- general body styles --------------------------------------------------- */
a.headerlink {
visibility: hidden;
}
h1:hover > a.headerlink,
h2:hover > a.headerlink,
h3:hover > a.headerlink,
h4:hover > a.headerlink,
h5:hover > a.headerlink,
h6:hover > a.headerlink,
dt:hover > a.headerlink {
visibility: visible;
}
div.body p.caption {
text-align: inherit;
}
div.body td {
text-align: left;
}
.field-list ul {
padding-left: 1em;
}
.first {
margin-top: 0 !important;
}
p.rubric {
margin-top: 30px;
font-weight: bold;
}
/* -- sidebars -------------------------------------------------------------- */
div.sidebar {
margin: 0 0 0.5em 1em;
border: 1px solid #ddb;
padding: 7px 7px 0 7px;
background-color: #ffe;
width: 40%;
float: right;
}
p.sidebar-title {
font-weight: bold;
}
/* -- topics ---------------------------------------------------------------- */
div.topic {
border: 1px solid #ccc;
padding: 7px 7px 0 7px;
margin: 10px 0 10px 0;
}
p.topic-title {
font-size: 1.1em;
font-weight: bold;
margin-top: 10px;
}
/* -- admonitions ----------------------------------------------------------- */
div.admonition {
margin-top: 10px;
margin-bottom: 10px;
padding: 7px;
}
div.admonition dt {
font-weight: bold;
}
div.admonition dl {
margin-bottom: 0;
}
p.admonition-title {
margin: 0px 10px 5px 0px;
font-weight: bold;
}
div.body p.centered {
text-align: center;
margin-top: 25px;
}
/* -- tables ---------------------------------------------------------------- */
table.docutils {
border: 0 solid #dce;
border-collapse: collapse;
}
table.docutils td, table.docutils th {
padding: 2px 5px 2px 5px;
border-left: 0;
background-color: #eef;
}
table.docutils td p.last, table.docutils th p.last {
margin-bottom: 0;
}
table.field-list td, table.field-list th {
border: 0 !important;
}
table.footnote td, table.footnote th {
border: 0 !important;
}
table.docutils th {
border-top: 1px solid #cac;
background-color: #ede;
}
th {
text-align: left;
padding-right: 5px;
}
th.head {
text-align: center;
}
/* -- other body styles ----------------------------------------------------- */
dl {
margin-bottom: 15px;
}
dd p {
margin-top: 0px;
}
dd ul, dd table {
margin-bottom: 10px;
}
dd {
margin-top: 3px;
margin-bottom: 10px;
margin-left: 30px;
}
dt:target, .highlighted {
background-color: #fbe54e;
}
dl.glossary dt {
font-weight: bold;
font-size: 1.1em;
}
.field-list ul {
margin: 0;
padding-left: 1em;
}
.field-list p {
margin: 0;
}
.refcount {
color: #060;
}
.optional {
font-size: 1.3em;
}
.versionmodified {
font-style: italic;
}
.deprecated {
background-color: #ffe4e4;
border: 1px solid #f66;
padding: 7px;
}
div.deprecated p {
margin-bottom: 0;
}
.system-message {
background-color: #fda;
padding: 5px;
border: 3px solid red;
}
.footnote:target {
background-color: #ffa;
}
.impl-detail {
margin-top: 10px;
margin-bottom: 10px;
padding: 7px;
border: 1px solid #ccc;
}
.impl-detail .compound-first {
margin-top: 0;
}
.impl-detail .compound-last {
margin-bottom: 0;
}
/* -- code displays --------------------------------------------------------- */
pre {
overflow: auto;
overflow-y: hidden;
}
td.linenos pre {
padding: 5px 0px;
border: 0;
background-color: transparent;
color: #aaa;
}
table.highlighttable {
margin-left: 0.5em;
}
table.highlighttable td {
padding: 0 0.5em 0 0.5em;
}
code.descname {
background-color: transparent;
font-weight: bold;
font-size: 1.2em;
}
code.descclassname {
background-color: transparent;
}
code.xref, a code {
background-color: transparent;
font-weight: bold;
}
h1 code, h2 code, h3 code, h4 code, h5 code, h6 code {
background-color: transparent;
}
.highlight {
background: none !important;
}
/* -- math display ---------------------------------------------------------- */
img.math {
vertical-align: middle;
}
div.body div.math p {
text-align: center;
}
span.eqno {
float: right;
}
/* -- printout stylesheet --------------------------------------------------- */
@media print {
div.document,
div.documentwrapper,
div.bodywrapper {
margin: 0 !important;
width: 100%;
}
div.sphinxsidebar,
div.related,
div.footer,
#top-link {
display: none;
}
}
PK
%�\`A�?� � html/_static/classic.cssnu �[��� /*
* classic.css_t
* ~~~~~~~~~~~~~
*
* Sphinx stylesheet -- classic theme.
*
* :copyright: Copyright 2007-2018 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/
@import url("basic.css");
/* -- page layout ----------------------------------------------------------- */
body {
font-family: sans-serif;
font-size: 100%;
background-color: #11303d;
color: #000;
margin: 0;
padding: 0;
}
div.document {
background-color: #1c4e63;
}
div.documentwrapper {
float: left;
width: 100%;
}
div.bodywrapper {
margin: 0 0 0 230px;
}
div.body {
background-color: #ffffff;
color: #000000;
padding: 0 20px 30px 20px;
}
div.footer {
color: #ffffff;
width: 100%;
padding: 9px 0 9px 0;
text-align: center;
font-size: 75%;
}
div.footer a {
color: #ffffff;
text-decoration: underline;
}
div.related {
background-color: #133f52;
line-height: 30px;
color: #ffffff;
}
div.related a {
color: #ffffff;
}
div.sphinxsidebar {
}
div.sphinxsidebar h3 {
font-family: 'Trebuchet MS', sans-serif;
color: #ffffff;
font-size: 1.4em;
font-weight: normal;
margin: 0;
padding: 0;
}
div.sphinxsidebar h3 a {
color: #ffffff;
}
div.sphinxsidebar h4 {
font-family: 'Trebuchet MS', sans-serif;
color: #ffffff;
font-size: 1.3em;
font-weight: normal;
margin: 5px 0 0 0;
padding: 0;
}
div.sphinxsidebar p {
color: #ffffff;
}
div.sphinxsidebar p.topless {
margin: 5px 10px 10px 10px;
}
div.sphinxsidebar ul {
margin: 10px;
padding: 0;
color: #ffffff;
}
div.sphinxsidebar a {
color: #98dbcc;
}
div.sphinxsidebar input {
border: 1px solid #98dbcc;
font-family: sans-serif;
font-size: 1em;
}
/* for collapsible sidebar */
div#sidebarbutton {
background-color: #3c6e83;
}
/* -- hyperlink styles ------------------------------------------------------ */
a {
color: #355f7c;
text-decoration: none;
}
a:visited {
color: #355f7c;
text-decoration: none;
}
a:hover {
text-decoration: underline;
}
/* -- body styles ----------------------------------------------------------- */
div.body h1,
div.body h2,
div.body h3,
div.body h4,
div.body h5,
div.body h6 {
font-family: 'Trebuchet MS', sans-serif;
background-color: #f2f2f2;
font-weight: normal;
color: #20435c;
border-bottom: 1px solid #ccc;
margin: 20px -20px 10px -20px;
padding: 3px 0 3px 10px;
}
div.body h1 { margin-top: 0; font-size: 200%; }
div.body h2 { font-size: 160%; }
div.body h3 { font-size: 140%; }
div.body h4 { font-size: 120%; }
div.body h5 { font-size: 110%; }
div.body h6 { font-size: 100%; }
a.headerlink {
color: #c60f0f;
font-size: 0.8em;
padding: 0 4px 0 4px;
text-decoration: none;
}
a.headerlink:hover {
background-color: #c60f0f;
color: white;
}
div.body p, div.body dd, div.body li, div.body blockquote {
text-align: justify;
line-height: 130%;
}
div.admonition p.admonition-title + p {
display: inline;
}
div.admonition p {
margin-bottom: 5px;
}
div.admonition pre {
margin-bottom: 5px;
}
div.admonition ul, div.admonition ol {
margin-bottom: 5px;
}
div.note {
background-color: #eee;
border: 1px solid #ccc;
}
div.seealso {
background-color: #ffc;
border: 1px solid #ff6;
}
div.topic {
background-color: #eee;
}
div.warning {
background-color: #ffe4e4;
border: 1px solid #f66;
}
p.admonition-title {
display: inline;
}
p.admonition-title:after {
content: ":";
}
pre {
padding: 5px;
background-color: #eeffcc;
color: #333333;
line-height: 120%;
border: 1px solid #ac9;
border-left: none;
border-right: none;
}
code {
background-color: #ecf0f3;
padding: 0 1px 0 1px;
font-size: 0.95em;
}
th {
background-color: #ede;
}
.warning code {
background: #efc2c2;
}
.note code {
background: #d6d6d6;
}
.viewcode-back {
font-family: sans-serif;
}
div.viewcode-block:target {
background-color: #f4debf;
border-top: 1px solid #ac9;
border-bottom: 1px solid #ac9;
}
div.code-block-caption {
color: #efefef;
background-color: #1c4e63;
}PK
%�\x,�� � html/_static/comment-bright.pngnu �[��� �PNG
IHDR �a �IDATx����<�ߙ��m۶m۶q�m۶m۶m� �M�=����D��8���tٍ�\{������56��j���>Qn�~3����s�D�{��o��S+ٻ�=���n���n���W�?��Xum���A��H�I�%p<Vr��{�̮7.�%���u�'�v�+�t�#?��%ߵ�e��/|��\8��Z�[�xgQ��o Dq��X�
ȄF���ޟgU�j+���t�%�7�;*"�Ii�b��[���� e[�[��n�r�7����6_w�9�֭�5S�҄4�,�,�C�"cp�]w\s5����ta(��ch��:��{[/��pŭ���� ��:34��H�E �� ?n�<�EZ�(b�F���Z�xb$E��lK� <O���i�~����0EQ��q" ��ޝ����/]�nź�
�W V����ܸ�$Ϸ�Ώ/�ȭ 3�Ϝ4�ԍ�x_Ϸ�6m
-\�&0@��s��A+���Xl_����ņ �T�����?ڴ6��۲���C ��v�����B���s�� ���>Hs�c���Yo�o���_{���Z)48s�ڳ��ۗ���8 Y�üYs��j3��4� s^�#ǒ��tˋq�kZ�ܜw�ݿ�ߵ>��!���8��pVn�{�շ�=�n$��p\�^;= ��;��wP IEND�B`�PK
%�\5��= = html/_static/comment-close.pngnu �[��� �PNG
IHDR �a IDATxm���8��$�k�m۶m۶m۶m۶�A�M�fp���:�O�'e�$Q�q�
� ��a��O[��B�3�U�9�O��g+ł-�81d��w=7����q�����1�����C�K�a� ~
�ʏ���<��e͛� �g�'�y�{�r�Gn���_���.|�5�խ̄Y�<m�x��%�U� �����
Z
���P��U �*�#�v�S���~ 'at5c���~�8 "3[��% �2W�0 A��|m'x�u�yV���~ � ^8�G� Y�X
Ђ���
��L��K����,%�ۏ.�I[��%,�, V���O��Z�c�� ?p�1��q��m*X��
���/`ـ��J �%�}�5�?��=
{�j��` �2�݂t�յW/�J;DV�m3� �-��$Ƿ���@Z���x�' �|��7s�=�`{]K<�q���я�� IRJ���Ip�Jm�I�ʲ�ս�(>� �l�ϕ��� ]�����������O�4���l�!A�@@�w� ��n����y��^���xa*��;1�u�S��W�ݦO<�*�7�g>b�~�yޞ�� mN� ��\�(�t��:+�tU&>9Z}��O�k=��� wԈ=��e��hjo
�O���Sd̳m#�(�2�ڮ�����&�!Q&��<���i�_~�� Y� �� =����K�eߨO��� � �)�\�/&��f������d� ����U���@�w� �yq�#�9� IEND�B`�PK
%�\4�� � � html/_static/comment.pngnu �[��� �PNG
IHDR �a HIDATx��� _���VT�Vܰ�Qǵ�FT7�m�]��<��M���=�>$�|��~\>&nM����K�<+W ��7�����zɫ ����?�w��!���8_�O�
��ާ4�&�
�M�S�'���/қ��=rּ`��V�0!��?t'$�#�'��P `��iawP��������?Dãqف�.`Ž �lZ%9A �{EҺ !;e� `f�T]�P]ZC D���X�2e)ן��r�y�OZs߂Ј
{�1<���*�Bx�����
�`���� �(�B4��2|��k@�� �=�P�A���Țe;�
Hͭ�U���`�B������@(��I��ϚR�
��F�"� a�(.� |R*w���ZB/bZ� f��M� Q+��d!���!06���5. ���9Eq+@ 3�ى�� VSË��d8�� �;��&KpHh0 �f; � ��h�Y�,]|�Lcne!��f�KcJ�Fiy����S��O�h�מ%ws
���va��J{�� �ڣ;/S3�� ?q��c�C��\�q�H ���x���sem���k2n<O�
9z��9�ѣ�l�t*�3� IEND�B`�PK
%�\��`x
x
html/_static/copybutton.jsnu �[��� $(document).ready(function() {
/* Add a [>>>] button on the top-right corner of code samples to hide
* the >>> and ... prompts and the output and thus make the code
* copyable. */
var div = $('.highlight-python .highlight,' +
'.highlight-python3 .highlight')
var pre = div.find('pre');
// get the styles from the current theme
pre.parent().parent().css('position', 'relative');
var hide_text = 'Hide the prompts and output';
var show_text = 'Show the prompts and output';
var border_width = pre.css('border-top-width');
var border_style = pre.css('border-top-style');
var border_color = pre.css('border-top-color');
var button_styles = {
'cursor':'pointer', 'position': 'absolute', 'top': '0', 'right': '0',
'border-color': border_color, 'border-style': border_style,
'border-width': border_width, 'color': border_color, 'text-size': '75%',
'font-family': 'monospace', 'padding-left': '0.2em', 'padding-right': '0.2em'
}
// create and add the button to all the code blocks that contain >>>
div.each(function(index) {
var jthis = $(this);
if (jthis.find('.gp').length > 0) {
var button = $('<span class="copybutton">>>></span>');
button.css(button_styles)
button.attr('title', hide_text);
button.data('hidden', 'false');
jthis.prepend(button);
}
// tracebacks (.gt) contain bare text elements that need to be
// wrapped in a span to work with .nextUntil() (see later)
jthis.find('pre:has(.gt)').contents().filter(function() {
return ((this.nodeType == 3) && (this.data.trim().length > 0));
}).wrap('<span>');
});
// define the behavior of the button when it's clicked
$('.copybutton').click(function(e){
e.preventDefault();
var button = $(this);
if (button.data('hidden') === 'false') {
// hide the code output
button.parent().find('.go, .gp, .gt').hide();
button.next('pre').find('.gt').nextUntil('.gp, .go').css('visibility', 'hidden');
button.css('text-decoration', 'line-through');
button.attr('title', show_text);
button.data('hidden', 'true');
} else {
// show the code output
button.parent().find('.go, .gp, .gt').show();
button.next('pre').find('.gt').nextUntil('.gp, .go').css('visibility', 'visible');
button.css('text-decoration', 'none');
button.attr('title', hide_text);
button.data('hidden', 'false');
}
});
});
PK
%�\_�� html/_static/default.cssnu �[��� @import url("classic.css");
PK
%�\JO�S$ $ html/_static/doctools.jsnu �[��� /*
* doctools.js
* ~~~~~~~~~~~
*
* Sphinx JavaScript utilities for all documentation.
*
* :copyright: Copyright 2007-2018 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/
/**
* select a different prefix for underscore
*/
$u = _.noConflict();
/**
* make the code below compatible with browsers without
* an installed firebug like debugger
if (!window.console || !console.firebug) {
var names = ["log", "debug", "info", "warn", "error", "assert", "dir",
"dirxml", "group", "groupEnd", "time", "timeEnd", "count", "trace",
"profile", "profileEnd"];
window.console = {};
for (var i = 0; i < names.length; ++i)
window.console[names[i]] = function() {};
}
*/
/**
* small helper function to urldecode strings
*/
jQuery.urldecode = function(x) {
return decodeURIComponent(x).replace(/\+/g, ' ');
};
/**
* small helper function to urlencode strings
*/
jQuery.urlencode = encodeURIComponent;
/**
* This function returns the parsed url parameters of the
* current request. Multiple values per key are supported,
* it will always return arrays of strings for the value parts.
*/
jQuery.getQueryParameters = function(s) {
if (typeof s === 'undefined')
s = document.location.search;
var parts = s.substr(s.indexOf('?') + 1).split('&');
var result = {};
for (var i = 0; i < parts.length; i++) {
var tmp = parts[i].split('=', 2);
var key = jQuery.urldecode(tmp[0]);
var value = jQuery.urldecode(tmp[1]);
if (key in result)
result[key].push(value);
else
result[key] = [value];
}
return result;
};
/**
* highlight a given string on a jquery object by wrapping it in
* span elements with the given class name.
*/
jQuery.fn.highlightText = function(text, className) {
function highlight(node, addItems) {
if (node.nodeType === 3) {
var val = node.nodeValue;
var pos = val.toLowerCase().indexOf(text);
if (pos >= 0 &&
!jQuery(node.parentNode).hasClass(className) &&
!jQuery(node.parentNode).hasClass("nohighlight")) {
var span;
var isInSVG = jQuery(node).closest("body, svg, foreignObject").is("svg");
if (isInSVG) {
span = document.createElementNS("http://www.w3.org/2000/svg", "tspan");
} else {
span = document.createElement("span");
span.className = className;
}
span.appendChild(document.createTextNode(val.substr(pos, text.length)));
node.parentNode.insertBefore(span, node.parentNode.insertBefore(
document.createTextNode(val.substr(pos + text.length)),
node.nextSibling));
node.nodeValue = val.substr(0, pos);
if (isInSVG) {
var bbox = span.getBBox();
var rect = document.createElementNS("http://www.w3.org/2000/svg", "rect");
rect.x.baseVal.value = bbox.x;
rect.y.baseVal.value = bbox.y;
rect.width.baseVal.value = bbox.width;
rect.height.baseVal.value = bbox.height;
rect.setAttribute('class', className);
var parentOfText = node.parentNode.parentNode;
addItems.push({
"parent": node.parentNode,
"target": rect});
}
}
}
else if (!jQuery(node).is("button, select, textarea")) {
jQuery.each(node.childNodes, function() {
highlight(this, addItems);
});
}
}
var addItems = [];
var result = this.each(function() {
highlight(this, addItems);
});
for (var i = 0; i < addItems.length; ++i) {
jQuery(addItems[i].parent).before(addItems[i].target);
}
return result;
};
/*
* backward compatibility for jQuery.browser
* This will be supported until firefox bug is fixed.
*/
if (!jQuery.browser) {
jQuery.uaMatch = function(ua) {
ua = ua.toLowerCase();
var match = /(chrome)[ \/]([\w.]+)/.exec(ua) ||
/(webkit)[ \/]([\w.]+)/.exec(ua) ||
/(opera)(?:.*version|)[ \/]([\w.]+)/.exec(ua) ||
/(msie) ([\w.]+)/.exec(ua) ||
ua.indexOf("compatible") < 0 && /(mozilla)(?:.*? rv:([\w.]+)|)/.exec(ua) ||
[];
return {
browser: match[ 1 ] || "",
version: match[ 2 ] || "0"
};
};
jQuery.browser = {};
jQuery.browser[jQuery.uaMatch(navigator.userAgent).browser] = true;
}
/**
* Small JavaScript module for the documentation.
*/
var Documentation = {
init : function() {
this.fixFirefoxAnchorBug();
this.highlightSearchWords();
this.initIndexTable();
},
/**
* i18n support
*/
TRANSLATIONS : {},
PLURAL_EXPR : function(n) { return n === 1 ? 0 : 1; },
LOCALE : 'unknown',
// gettext and ngettext don't access this so that the functions
// can safely bound to a different name (_ = Documentation.gettext)
gettext : function(string) {
var translated = Documentation.TRANSLATIONS[string];
if (typeof translated === 'undefined')
return string;
return (typeof translated === 'string') ? translated : translated[0];
},
ngettext : function(singular, plural, n) {
var translated = Documentation.TRANSLATIONS[singular];
if (typeof translated === 'undefined')
return (n == 1) ? singular : plural;
return translated[Documentation.PLURALEXPR(n)];
},
addTranslations : function(catalog) {
for (var key in catalog.messages)
this.TRANSLATIONS[key] = catalog.messages[key];
this.PLURAL_EXPR = new Function('n', 'return +(' + catalog.plural_expr + ')');
this.LOCALE = catalog.locale;
},
/**
* add context elements like header anchor links
*/
addContextElements : function() {
$('div[id] > :header:first').each(function() {
$('<a class="headerlink">\u00B6</a>').
attr('href', '#' + this.id).
attr('title', _('Permalink to this headline')).
appendTo(this);
});
$('dt[id]').each(function() {
$('<a class="headerlink">\u00B6</a>').
attr('href', '#' + this.id).
attr('title', _('Permalink to this definition')).
appendTo(this);
});
},
/**
* workaround a firefox stupidity
* see: https://bugzilla.mozilla.org/show_bug.cgi?id=645075
*/
fixFirefoxAnchorBug : function() {
if (document.location.hash && $.browser.mozilla)
window.setTimeout(function() {
document.location.href += '';
}, 10);
},
/**
* highlight the search words provided in the url in the text
*/
highlightSearchWords : function() {
var params = $.getQueryParameters();
var terms = (params.highlight) ? params.highlight[0].split(/\s+/) : [];
if (terms.length) {
var body = $('div.body');
if (!body.length) {
body = $('body');
}
window.setTimeout(function() {
$.each(terms, function() {
body.highlightText(this.toLowerCase(), 'highlighted');
});
}, 10);
$('<p class="highlight-link"><a href="javascript:Documentation.' +
'hideSearchWords()">' + _('Hide Search Matches') + '</a></p>')
.appendTo($('#searchbox'));
}
},
/**
* init the domain index toggle buttons
*/
initIndexTable : function() {
var togglers = $('img.toggler').click(function() {
var src = $(this).attr('src');
var idnum = $(this).attr('id').substr(7);
$('tr.cg-' + idnum).toggle();
if (src.substr(-9) === 'minus.png')
$(this).attr('src', src.substr(0, src.length-9) + 'plus.png');
else
$(this).attr('src', src.substr(0, src.length-8) + 'minus.png');
}).css('display', '');
if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) {
togglers.click();
}
},
/**
* helper function to hide the search marks again
*/
hideSearchWords : function() {
$('#searchbox .highlight-link').fadeOut(300);
$('span.highlighted').removeClass('highlighted');
},
/**
* make the url absolute
*/
makeURL : function(relativeURL) {
return DOCUMENTATION_OPTIONS.URL_ROOT + '/' + relativeURL;
},
/**
* get the current relative url
*/
getCurrentURL : function() {
var path = document.location.pathname;
var parts = path.split(/\//);
$.each(DOCUMENTATION_OPTIONS.URL_ROOT.split(/\//), function() {
if (this === '..')
parts.pop();
});
var url = parts.join('/');
return path.substring(url.lastIndexOf('/') + 1, path.length - 1);
},
initOnKeyListeners: function() {
$(document).keyup(function(event) {
var activeElementType = document.activeElement.tagName;
// don't navigate when in search box or textarea
if (activeElementType !== 'TEXTAREA' && activeElementType !== 'INPUT' && activeElementType !== 'SELECT') {
switch (event.keyCode) {
case 37: // left
var prevHref = $('link[rel="prev"]').prop('href');
if (prevHref) {
window.location.href = prevHref;
return false;
}
case 39: // right
var nextHref = $('link[rel="next"]').prop('href');
if (nextHref) {
window.location.href = nextHref;
return false;
}
}
}
});
}
};
// quick alias for translations
_ = Documentation.gettext;
$(document).ready(function() {
Documentation.init();
});PK
%�\N�9� % html/_static/documentation_options.jsnu �[��� var DOCUMENTATION_OPTIONS = {
URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'),
VERSION: '2.7.16',
LANGUAGE: 'None',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};PK
%�\�'�� � html/_static/down-pressed.pngnu �[��� �PNG
IHDR �a �IDATxc� ��@ �J@lK�f[�^g%_� ����
H��K �Ŀ�� �D ���A��b3���C�G�hr.��x�� ��/`X�� W��ʱ
�2 � �e�F�+,.xEJ � ���lAR�
$�W��T?�0i��)1� m� ���aU� IEND�B`�PK
%�\9.��� � html/_static/down.pngnu �[��� �PNG
IHDR ��7� �IDATx�����P@��
�@I�ߗ`&�"z6xK@kbϢx�s]��M �:���/�+�g�Pd�2G�eÐ~�߸J�_�c S_��
S%exdU��]�(UH���>�&����;4�i��$�n�3�> � y�c��d�� IEND�B`�PK
%�\S[�S html/_static/file.pngnu �[��� �PNG
IHDR �a �IDATx���R��){�l� ۶� f�=@�� �:���3�~箄������rX$A�X-�D ~�
����lj(�P%���8<<9::
��P��O&�$� ��l~�X����&���EW�^4�wQ}����^���ͣ�
��i���0/H/�@F)�Dzq+��j��[�SU5����h��/�oY� G&Lfs|�����{����3%�U+S��`AF� IEND�B`�PK
%�\���� html/_static/jquery-3.2.1.jsnu �[��� /*!
* jQuery JavaScript Library v3.2.1
* https://jquery.com/
*
* Includes Sizzle.js
* https://sizzlejs.com/
*
* Copyright JS Foundation and other contributors
* Released under the MIT license
* https://jquery.org/license
*
* Date: 2017-03-20T18:59Z
*/
( function( global, factory ) {
"use strict";
if ( typeof module === "object" && typeof module.exports === "object" ) {
// For CommonJS and CommonJS-like environments where a proper `window`
// is present, execute the factory and get jQuery.
// For environments that do not have a `window` with a `document`
// (such as Node.js), expose a factory as module.exports.
// This accentuates the need for the creation of a real `window`.
// e.g. var jQuery = require("jquery")(window);
// See ticket #14549 for more info.
module.exports = global.document ?
factory( global, true ) :
function( w ) {
if ( !w.document ) {
throw new Error( "jQuery requires a window with a document" );
}
return factory( w );
};
} else {
factory( global );
}
// Pass this if window is not defined yet
} )( typeof window !== "undefined" ? window : this, function( window, noGlobal ) {
// Edge <= 12 - 13+, Firefox <=18 - 45+, IE 10 - 11, Safari 5.1 - 9+, iOS 6 - 9.1
// throw exceptions when non-strict code (e.g., ASP.NET 4.5) accesses strict mode
// arguments.callee.caller (trac-13335). But as of jQuery 3.0 (2016), strict mode should be common
// enough that all such attempts are guarded in a try block.
"use strict";
var arr = [];
var document = window.document;
var getProto = Object.getPrototypeOf;
var slice = arr.slice;
var concat = arr.concat;
var push = arr.push;
var indexOf = arr.indexOf;
var class2type = {};
var toString = class2type.toString;
var hasOwn = class2type.hasOwnProperty;
var fnToString = hasOwn.toString;
var ObjectFunctionString = fnToString.call( Object );
var support = {};
function DOMEval( code, doc ) {
doc = doc || document;
var script = doc.createElement( "script" );
script.text = code;
doc.head.appendChild( script ).parentNode.removeChild( script );
}
/* global Symbol */
// Defining this global in .eslintrc.json would create a danger of using the global
// unguarded in another place, it seems safer to define global only for this module
var
version = "3.2.1",
// Define a local copy of jQuery
jQuery = function( selector, context ) {
// The jQuery object is actually just the init constructor 'enhanced'
// Need init if jQuery is called (just allow error to be thrown if not included)
return new jQuery.fn.init( selector, context );
},
// Support: Android <=4.0 only
// Make sure we trim BOM and NBSP
rtrim = /^[\s\uFEFF\xA0]+|[\s\uFEFF\xA0]+$/g,
// Matches dashed string for camelizing
rmsPrefix = /^-ms-/,
rdashAlpha = /-([a-z])/g,
// Used by jQuery.camelCase as callback to replace()
fcamelCase = function( all, letter ) {
return letter.toUpperCase();
};
jQuery.fn = jQuery.prototype = {
// The current version of jQuery being used
jquery: version,
constructor: jQuery,
// The default length of a jQuery object is 0
length: 0,
toArray: function() {
return slice.call( this );
},
// Get the Nth element in the matched element set OR
// Get the whole matched element set as a clean array
get: function( num ) {
// Return all the elements in a clean array
if ( num == null ) {
return slice.call( this );
}
// Return just the one element from the set
return num < 0 ? this[ num + this.length ] : this[ num ];
},
// Take an array of elements and push it onto the stack
// (returning the new matched element set)
pushStack: function( elems ) {
// Build a new jQuery matched element set
var ret = jQuery.merge( this.constructor(), elems );
// Add the old object onto the stack (as a reference)
ret.prevObject = this;
// Return the newly-formed element set
return ret;
},
// Execute a callback for every element in the matched set.
each: function( callback ) {
return jQuery.each( this, callback );
},
map: function( callback ) {
return this.pushStack( jQuery.map( this, function( elem, i ) {
return callback.call( elem, i, elem );
} ) );
},
slice: function() {
return this.pushStack( slice.apply( this, arguments ) );
},
first: function() {
return this.eq( 0 );
},
last: function() {
return this.eq( -1 );
},
eq: function( i ) {
var len = this.length,
j = +i + ( i < 0 ? len : 0 );
return this.pushStack( j >= 0 && j < len ? [ this[ j ] ] : [] );
},
end: function() {
return this.prevObject || this.constructor();
},
// For internal use only.
// Behaves like an Array's method, not like a jQuery method.
push: push,
sort: arr.sort,
splice: arr.splice
};
jQuery.extend = jQuery.fn.extend = function() {
var options, name, src, copy, copyIsArray, clone,
target = arguments[ 0 ] || {},
i = 1,
length = arguments.length,
deep = false;
// Handle a deep copy situation
if ( typeof target === "boolean" ) {
deep = target;
// Skip the boolean and the target
target = arguments[ i ] || {};
i++;
}
// Handle case when target is a string or something (possible in deep copy)
if ( typeof target !== "object" && !jQuery.isFunction( target ) ) {
target = {};
}
// Extend jQuery itself if only one argument is passed
if ( i === length ) {
target = this;
i--;
}
for ( ; i < length; i++ ) {
// Only deal with non-null/undefined values
if ( ( options = arguments[ i ] ) != null ) {
// Extend the base object
for ( name in options ) {
src = target[ name ];
copy = options[ name ];
// Prevent never-ending loop
if ( target === copy ) {
continue;
}
// Recurse if we're merging plain objects or arrays
if ( deep && copy && ( jQuery.isPlainObject( copy ) ||
( copyIsArray = Array.isArray( copy ) ) ) ) {
if ( copyIsArray ) {
copyIsArray = false;
clone = src && Array.isArray( src ) ? src : [];
} else {
clone = src && jQuery.isPlainObject( src ) ? src : {};
}
// Never move original objects, clone them
target[ name ] = jQuery.extend( deep, clone, copy );
// Don't bring in undefined values
} else if ( copy !== undefined ) {
target[ name ] = copy;
}
}
}
}
// Return the modified object
return target;
};
jQuery.extend( {
// Unique for each copy of jQuery on the page
expando: "jQuery" + ( version + Math.random() ).replace( /\D/g, "" ),
// Assume jQuery is ready without the ready module
isReady: true,
error: function( msg ) {
throw new Error( msg );
},
noop: function() {},
isFunction: function( obj ) {
return jQuery.type( obj ) === "function";
},
isWindow: function( obj ) {
return obj != null && obj === obj.window;
},
isNumeric: function( obj ) {
// As of jQuery 3.0, isNumeric is limited to
// strings and numbers (primitives or objects)
// that can be coerced to finite numbers (gh-2662)
var type = jQuery.type( obj );
return ( type === "number" || type === "string" ) &&
// parseFloat NaNs numeric-cast false positives ("")
// ...but misinterprets leading-number strings, particularly hex literals ("0x...")
// subtraction forces infinities to NaN
!isNaN( obj - parseFloat( obj ) );
},
isPlainObject: function( obj ) {
var proto, Ctor;
// Detect obvious negatives
// Use toString instead of jQuery.type to catch host objects
if ( !obj || toString.call( obj ) !== "[object Object]" ) {
return false;
}
proto = getProto( obj );
// Objects with no prototype (e.g., `Object.create( null )`) are plain
if ( !proto ) {
return true;
}
// Objects with prototype are plain iff they were constructed by a global Object function
Ctor = hasOwn.call( proto, "constructor" ) && proto.constructor;
return typeof Ctor === "function" && fnToString.call( Ctor ) === ObjectFunctionString;
},
isEmptyObject: function( obj ) {
/* eslint-disable no-unused-vars */
// See https://github.com/eslint/eslint/issues/6125
var name;
for ( name in obj ) {
return false;
}
return true;
},
type: function( obj ) {
if ( obj == null ) {
return obj + "";
}
// Support: Android <=2.3 only (functionish RegExp)
return typeof obj === "object" || typeof obj === "function" ?
class2type[ toString.call( obj ) ] || "object" :
typeof obj;
},
// Evaluates a script in a global context
globalEval: function( code ) {
DOMEval( code );
},
// Convert dashed to camelCase; used by the css and data modules
// Support: IE <=9 - 11, Edge 12 - 13
// Microsoft forgot to hump their vendor prefix (#9572)
camelCase: function( string ) {
return string.replace( rmsPrefix, "ms-" ).replace( rdashAlpha, fcamelCase );
},
each: function( obj, callback ) {
var length, i = 0;
if ( isArrayLike( obj ) ) {
length = obj.length;
for ( ; i < length; i++ ) {
if ( callback.call( obj[ i ], i, obj[ i ] ) === false ) {
break;
}
}
} else {
for ( i in obj ) {
if ( callback.call( obj[ i ], i, obj[ i ] ) === false ) {
break;
}
}
}
return obj;
},
// Support: Android <=4.0 only
trim: function( text ) {
return text == null ?
"" :
( text + "" ).replace( rtrim, "" );
},
// results is for internal usage only
makeArray: function( arr, results ) {
var ret = results || [];
if ( arr != null ) {
if ( isArrayLike( Object( arr ) ) ) {
jQuery.merge( ret,
typeof arr === "string" ?
[ arr ] : arr
);
} else {
push.call( ret, arr );
}
}
return ret;
},
inArray: function( elem, arr, i ) {
return arr == null ? -1 : indexOf.call( arr, elem, i );
},
// Support: Android <=4.0 only, PhantomJS 1 only
// push.apply(_, arraylike) throws on ancient WebKit
merge: function( first, second ) {
var len = +second.length,
j = 0,
i = first.length;
for ( ; j < len; j++ ) {
first[ i++ ] = second[ j ];
}
first.length = i;
return first;
},
grep: function( elems, callback, invert ) {
var callbackInverse,
matches = [],
i = 0,
length = elems.length,
callbackExpect = !invert;
// Go through the array, only saving the items
// that pass the validator function
for ( ; i < length; i++ ) {
callbackInverse = !callback( elems[ i ], i );
if ( callbackInverse !== callbackExpect ) {
matches.push( elems[ i ] );
}
}
return matches;
},
// arg is for internal usage only
map: function( elems, callback, arg ) {
var length, value,
i = 0,
ret = [];
// Go through the array, translating each of the items to their new values
if ( isArrayLike( elems ) ) {
length = elems.length;
for ( ; i < length; i++ ) {
value = callback( elems[ i ], i, arg );
if ( value != null ) {
ret.push( value );
}
}
// Go through every key on the object,
} else {
for ( i in elems ) {
value = callback( elems[ i ], i, arg );
if ( value != null ) {
ret.push( value );
}
}
}
// Flatten any nested arrays
return concat.apply( [], ret );
},
// A global GUID counter for objects
guid: 1,
// Bind a function to a context, optionally partially applying any
// arguments.
proxy: function( fn, context ) {
var tmp, args, proxy;
if ( typeof context === "string" ) {
tmp = fn[ context ];
context = fn;
fn = tmp;
}
// Quick check to determine if target is callable, in the spec
// this throws a TypeError, but we will just return undefined.
if ( !jQuery.isFunction( fn ) ) {
return undefined;
}
// Simulated bind
args = slice.call( arguments, 2 );
proxy = function() {
return fn.apply( context || this, args.concat( slice.call( arguments ) ) );
};
// Set the guid of unique handler to the same of original handler, so it can be removed
proxy.guid = fn.guid = fn.guid || jQuery.guid++;
return proxy;
},
now: Date.now,
// jQuery.support is not used in Core but other projects attach their
// properties to it so it needs to exist.
support: support
} );
if ( typeof Symbol === "function" ) {
jQuery.fn[ Symbol.iterator ] = arr[ Symbol.iterator ];
}
// Populate the class2type map
jQuery.each( "Boolean Number String Function Array Date RegExp Object Error Symbol".split( " " ),
function( i, name ) {
class2type[ "[object " + name + "]" ] = name.toLowerCase();
} );
function isArrayLike( obj ) {
// Support: real iOS 8.2 only (not reproducible in simulator)
// `in` check used to prevent JIT error (gh-2145)
// hasOwn isn't used here due to false negatives
// regarding Nodelist length in IE
var length = !!obj && "length" in obj && obj.length,
type = jQuery.type( obj );
if ( type === "function" || jQuery.isWindow( obj ) ) {
return false;
}
return type === "array" || length === 0 ||
typeof length === "number" && length > 0 && ( length - 1 ) in obj;
}
var Sizzle =
/*!
* Sizzle CSS Selector Engine v2.3.3
* https://sizzlejs.com/
*
* Copyright jQuery Foundation and other contributors
* Released under the MIT license
* http://jquery.org/license
*
* Date: 2016-08-08
*/
(function( window ) {
var i,
support,
Expr,
getText,
isXML,
tokenize,
compile,
select,
outermostContext,
sortInput,
hasDuplicate,
// Local document vars
setDocument,
document,
docElem,
documentIsHTML,
rbuggyQSA,
rbuggyMatches,
matches,
contains,
// Instance-specific data
expando = "sizzle" + 1 * new Date(),
preferredDoc = window.document,
dirruns = 0,
done = 0,
classCache = createCache(),
tokenCache = createCache(),
compilerCache = createCache(),
sortOrder = function( a, b ) {
if ( a === b ) {
hasDuplicate = true;
}
return 0;
},
// Instance methods
hasOwn = ({}).hasOwnProperty,
arr = [],
pop = arr.pop,
push_native = arr.push,
push = arr.push,
slice = arr.slice,
// Use a stripped-down indexOf as it's faster than native
// https://jsperf.com/thor-indexof-vs-for/5
indexOf = function( list, elem ) {
var i = 0,
len = list.length;
for ( ; i < len; i++ ) {
if ( list[i] === elem ) {
return i;
}
}
return -1;
},
booleans = "checked|selected|async|autofocus|autoplay|controls|defer|disabled|hidden|ismap|loop|multiple|open|readonly|required|scoped",
// Regular expressions
// http://www.w3.org/TR/css3-selectors/#whitespace
whitespace = "[\\x20\\t\\r\\n\\f]",
// http://www.w3.org/TR/CSS21/syndata.html#value-def-identifier
identifier = "(?:\\\\.|[\\w-]|[^\0-\\xa0])+",
// Attribute selectors: http://www.w3.org/TR/selectors/#attribute-selectors
attributes = "\\[" + whitespace + "*(" + identifier + ")(?:" + whitespace +
// Operator (capture 2)
"*([*^$|!~]?=)" + whitespace +
// "Attribute values must be CSS identifiers [capture 5] or strings [capture 3 or capture 4]"
"*(?:'((?:\\\\.|[^\\\\'])*)'|\"((?:\\\\.|[^\\\\\"])*)\"|(" + identifier + "))|)" + whitespace +
"*\\]",
pseudos = ":(" + identifier + ")(?:\\((" +
// To reduce the number of selectors needing tokenize in the preFilter, prefer arguments:
// 1. quoted (capture 3; capture 4 or capture 5)
"('((?:\\\\.|[^\\\\'])*)'|\"((?:\\\\.|[^\\\\\"])*)\")|" +
// 2. simple (capture 6)
"((?:\\\\.|[^\\\\()[\\]]|" + attributes + ")*)|" +
// 3. anything else (capture 2)
".*" +
")\\)|)",
// Leading and non-escaped trailing whitespace, capturing some non-whitespace characters preceding the latter
rwhitespace = new RegExp( whitespace + "+", "g" ),
rtrim = new RegExp( "^" + whitespace + "+|((?:^|[^\\\\])(?:\\\\.)*)" + whitespace + "+$", "g" ),
rcomma = new RegExp( "^" + whitespace + "*," + whitespace + "*" ),
rcombinators = new RegExp( "^" + whitespace + "*([>+~]|" + whitespace + ")" + whitespace + "*" ),
rattributeQuotes = new RegExp( "=" + whitespace + "*([^\\]'\"]*?)" + whitespace + "*\\]", "g" ),
rpseudo = new RegExp( pseudos ),
ridentifier = new RegExp( "^" + identifier + "$" ),
matchExpr = {
"ID": new RegExp( "^#(" + identifier + ")" ),
"CLASS": new RegExp( "^\\.(" + identifier + ")" ),
"TAG": new RegExp( "^(" + identifier + "|[*])" ),
"ATTR": new RegExp( "^" + attributes ),
"PSEUDO": new RegExp( "^" + pseudos ),
"CHILD": new RegExp( "^:(only|first|last|nth|nth-last)-(child|of-type)(?:\\(" + whitespace +
"*(even|odd|(([+-]|)(\\d*)n|)" + whitespace + "*(?:([+-]|)" + whitespace +
"*(\\d+)|))" + whitespace + "*\\)|)", "i" ),
"bool": new RegExp( "^(?:" + booleans + ")$", "i" ),
// For use in libraries implementing .is()
// We use this for POS matching in `select`
"needsContext": new RegExp( "^" + whitespace + "*[>+~]|:(even|odd|eq|gt|lt|nth|first|last)(?:\\(" +
whitespace + "*((?:-\\d)?\\d*)" + whitespace + "*\\)|)(?=[^-]|$)", "i" )
},
rinputs = /^(?:input|select|textarea|button)$/i,
rheader = /^h\d$/i,
rnative = /^[^{]+\{\s*\[native \w/,
// Easily-parseable/retrievable ID or TAG or CLASS selectors
rquickExpr = /^(?:#([\w-]+)|(\w+)|\.([\w-]+))$/,
rsibling = /[+~]/,
// CSS escapes
// http://www.w3.org/TR/CSS21/syndata.html#escaped-characters
runescape = new RegExp( "\\\\([\\da-f]{1,6}" + whitespace + "?|(" + whitespace + ")|.)", "ig" ),
funescape = function( _, escaped, escapedWhitespace ) {
var high = "0x" + escaped - 0x10000;
// NaN means non-codepoint
// Support: Firefox<24
// Workaround erroneous numeric interpretation of +"0x"
return high !== high || escapedWhitespace ?
escaped :
high < 0 ?
// BMP codepoint
String.fromCharCode( high + 0x10000 ) :
// Supplemental Plane codepoint (surrogate pair)
String.fromCharCode( high >> 10 | 0xD800, high & 0x3FF | 0xDC00 );
},
// CSS string/identifier serialization
// https://drafts.csswg.org/cssom/#common-serializing-idioms
rcssescape = /([\0-\x1f\x7f]|^-?\d)|^-$|[^\0-\x1f\x7f-\uFFFF\w-]/g,
fcssescape = function( ch, asCodePoint ) {
if ( asCodePoint ) {
// U+0000 NULL becomes U+FFFD REPLACEMENT CHARACTER
if ( ch === "\0" ) {
return "\uFFFD";
}
// Control characters and (dependent upon position) numbers get escaped as code points
return ch.slice( 0, -1 ) + "\\" + ch.charCodeAt( ch.length - 1 ).toString( 16 ) + " ";
}
// Other potentially-special ASCII characters get backslash-escaped
return "\\" + ch;
},
// Used for iframes
// See setDocument()
// Removing the function wrapper causes a "Permission Denied"
// error in IE
unloadHandler = function() {
setDocument();
},
disabledAncestor = addCombinator(
function( elem ) {
return elem.disabled === true && ("form" in elem || "label" in elem);
},
{ dir: "parentNode", next: "legend" }
);
// Optimize for push.apply( _, NodeList )
try {
push.apply(
(arr = slice.call( preferredDoc.childNodes )),
preferredDoc.childNodes
);
// Support: Android<4.0
// Detect silently failing push.apply
arr[ preferredDoc.childNodes.length ].nodeType;
} catch ( e ) {
push = { apply: arr.length ?
// Leverage slice if possible
function( target, els ) {
push_native.apply( target, slice.call(els) );
} :
// Support: IE<9
// Otherwise append directly
function( target, els ) {
var j = target.length,
i = 0;
// Can't trust NodeList.length
while ( (target[j++] = els[i++]) ) {}
target.length = j - 1;
}
};
}
function Sizzle( selector, context, results, seed ) {
var m, i, elem, nid, match, groups, newSelector,
newContext = context && context.ownerDocument,
// nodeType defaults to 9, since context defaults to document
nodeType = context ? context.nodeType : 9;
results = results || [];
// Return early from calls with invalid selector or context
if ( typeof selector !== "string" || !selector ||
nodeType !== 1 && nodeType !== 9 && nodeType !== 11 ) {
return results;
}
// Try to shortcut find operations (as opposed to filters) in HTML documents
if ( !seed ) {
if ( ( context ? context.ownerDocument || context : preferredDoc ) !== document ) {
setDocument( context );
}
context = context || document;
if ( documentIsHTML ) {
// If the selector is sufficiently simple, try using a "get*By*" DOM method
// (excepting DocumentFragment context, where the methods don't exist)
if ( nodeType !== 11 && (match = rquickExpr.exec( selector )) ) {
// ID selector
if ( (m = match[1]) ) {
// Document context
if ( nodeType === 9 ) {
if ( (elem = context.getElementById( m )) ) {
// Support: IE, Opera, Webkit
// TODO: identify versions
// getElementById can match elements by name instead of ID
if ( elem.id === m ) {
results.push( elem );
return results;
}
} else {
return results;
}
// Element context
} else {
// Support: IE, Opera, Webkit
// TODO: identify versions
// getElementById can match elements by name instead of ID
if ( newContext && (elem = newContext.getElementById( m )) &&
contains( context, elem ) &&
elem.id === m ) {
results.push( elem );
return results;
}
}
// Type selector
} else if ( match[2] ) {
push.apply( results, context.getElementsByTagName( selector ) );
return results;
// Class selector
} else if ( (m = match[3]) && support.getElementsByClassName &&
context.getElementsByClassName ) {
push.apply( results, context.getElementsByClassName( m ) );
return results;
}
}
// Take advantage of querySelectorAll
if ( support.qsa &&
!compilerCache[ selector + " " ] &&
(!rbuggyQSA || !rbuggyQSA.test( selector )) ) {
if ( nodeType !== 1 ) {
newContext = context;
newSelector = selector;
// qSA looks outside Element context, which is not what we want
// Thanks to Andrew Dupont for this workaround technique
// Support: IE <=8
// Exclude object elements
} else if ( context.nodeName.toLowerCase() !== "object" ) {
// Capture the context ID, setting it first if necessary
if ( (nid = context.getAttribute( "id" )) ) {
nid = nid.replace( rcssescape, fcssescape );
} else {
context.setAttribute( "id", (nid = expando) );
}
// Prefix every selector in the list
groups = tokenize( selector );
i = groups.length;
while ( i-- ) {
groups[i] = "#" + nid + " " + toSelector( groups[i] );
}
newSelector = groups.join( "," );
// Expand context for sibling selectors
newContext = rsibling.test( selector ) && testContext( context.parentNode ) ||
context;
}
if ( newSelector ) {
try {
push.apply( results,
newContext.querySelectorAll( newSelector )
);
return results;
} catch ( qsaError ) {
} finally {
if ( nid === expando ) {
context.removeAttribute( "id" );
}
}
}
}
}
}
// All others
return select( selector.replace( rtrim, "$1" ), context, results, seed );
}
/**
* Create key-value caches of limited size
* @returns {function(string, object)} Returns the Object data after storing it on itself with
* property name the (space-suffixed) string and (if the cache is larger than Expr.cacheLength)
* deleting the oldest entry
*/
function createCache() {
var keys = [];
function cache( key, value ) {
// Use (key + " ") to avoid collision with native prototype properties (see Issue #157)
if ( keys.push( key + " " ) > Expr.cacheLength ) {
// Only keep the most recent entries
delete cache[ keys.shift() ];
}
return (cache[ key + " " ] = value);
}
return cache;
}
/**
* Mark a function for special use by Sizzle
* @param {Function} fn The function to mark
*/
function markFunction( fn ) {
fn[ expando ] = true;
return fn;
}
/**
* Support testing using an element
* @param {Function} fn Passed the created element and returns a boolean result
*/
function assert( fn ) {
var el = document.createElement("fieldset");
try {
return !!fn( el );
} catch (e) {
return false;
} finally {
// Remove from its parent by default
if ( el.parentNode ) {
el.parentNode.removeChild( el );
}
// release memory in IE
el = null;
}
}
/**
* Adds the same handler for all of the specified attrs
* @param {String} attrs Pipe-separated list of attributes
* @param {Function} handler The method that will be applied
*/
function addHandle( attrs, handler ) {
var arr = attrs.split("|"),
i = arr.length;
while ( i-- ) {
Expr.attrHandle[ arr[i] ] = handler;
}
}
/**
* Checks document order of two siblings
* @param {Element} a
* @param {Element} b
* @returns {Number} Returns less than 0 if a precedes b, greater than 0 if a follows b
*/
function siblingCheck( a, b ) {
var cur = b && a,
diff = cur && a.nodeType === 1 && b.nodeType === 1 &&
a.sourceIndex - b.sourceIndex;
// Use IE sourceIndex if available on both nodes
if ( diff ) {
return diff;
}
// Check if b follows a
if ( cur ) {
while ( (cur = cur.nextSibling) ) {
if ( cur === b ) {
return -1;
}
}
}
return a ? 1 : -1;
}
/**
* Returns a function to use in pseudos for input types
* @param {String} type
*/
function createInputPseudo( type ) {
return function( elem ) {
var name = elem.nodeName.toLowerCase();
return name === "input" && elem.type === type;
};
}
/**
* Returns a function to use in pseudos for buttons
* @param {String} type
*/
function createButtonPseudo( type ) {
return function( elem ) {
var name = elem.nodeName.toLowerCase();
return (name === "input" || name === "button") && elem.type === type;
};
}
/**
* Returns a function to use in pseudos for :enabled/:disabled
* @param {Boolean} disabled true for :disabled; false for :enabled
*/
function createDisabledPseudo( disabled ) {
// Known :disabled false positives: fieldset[disabled] > legend:nth-of-type(n+2) :can-disable
return function( elem ) {
// Only certain elements can match :enabled or :disabled
// https://html.spec.whatwg.org/multipage/scripting.html#selector-enabled
// https://html.spec.whatwg.org/multipage/scripting.html#selector-disabled
if ( "form" in elem ) {
// Check for inherited disabledness on relevant non-disabled elements:
// * listed form-associated elements in a disabled fieldset
// https://html.spec.whatwg.org/multipage/forms.html#category-listed
// https://html.spec.whatwg.org/multipage/forms.html#concept-fe-disabled
// * option elements in a disabled optgroup
// https://html.spec.whatwg.org/multipage/forms.html#concept-option-disabled
// All such elements have a "form" property.
if ( elem.parentNode && elem.disabled === false ) {
// Option elements defer to a parent optgroup if present
if ( "label" in elem ) {
if ( "label" in elem.parentNode ) {
return elem.parentNode.disabled === disabled;
} else {
return elem.disabled === disabled;
}
}
// Support: IE 6 - 11
// Use the isDisabled shortcut property to check for disabled fieldset ancestors
return elem.isDisabled === disabled ||
// Where there is no isDisabled, check manually
/* jshint -W018 */
elem.isDisabled !== !disabled &&
disabledAncestor( elem ) === disabled;
}
return elem.disabled === disabled;
// Try to winnow out elements that can't be disabled before trusting the disabled property.
// Some victims get caught in our net (label, legend, menu, track), but it shouldn't
// even exist on them, let alone have a boolean value.
} else if ( "label" in elem ) {
return elem.disabled === disabled;
}
// Remaining elements are neither :enabled nor :disabled
return false;
};
}
/**
* Returns a function to use in pseudos for positionals
* @param {Function} fn
*/
function createPositionalPseudo( fn ) {
return markFunction(function( argument ) {
argument = +argument;
return markFunction(function( seed, matches ) {
var j,
matchIndexes = fn( [], seed.length, argument ),
i = matchIndexes.length;
// Match elements found at the specified indexes
while ( i-- ) {
if ( seed[ (j = matchIndexes[i]) ] ) {
seed[j] = !(matches[j] = seed[j]);
}
}
});
});
}
/**
* Checks a node for validity as a Sizzle context
* @param {Element|Object=} context
* @returns {Element|Object|Boolean} The input node if acceptable, otherwise a falsy value
*/
function testContext( context ) {
return context && typeof context.getElementsByTagName !== "undefined" && context;
}
// Expose support vars for convenience
support = Sizzle.support = {};
/**
* Detects XML nodes
* @param {Element|Object} elem An element or a document
* @returns {Boolean} True iff elem is a non-HTML XML node
*/
isXML = Sizzle.isXML = function( elem ) {
// documentElement is verified for cases where it doesn't yet exist
// (such as loading iframes in IE - #4833)
var documentElement = elem && (elem.ownerDocument || elem).documentElement;
return documentElement ? documentElement.nodeName !== "HTML" : false;
};
/**
* Sets document-related variables once based on the current document
* @param {Element|Object} [doc] An element or document object to use to set the document
* @returns {Object} Returns the current document
*/
setDocument = Sizzle.setDocument = function( node ) {
var hasCompare, subWindow,
doc = node ? node.ownerDocument || node : preferredDoc;
// Return early if doc is invalid or already selected
if ( doc === document || doc.nodeType !== 9 || !doc.documentElement ) {
return document;
}
// Update global variables
document = doc;
docElem = document.documentElement;
documentIsHTML = !isXML( document );
// Support: IE 9-11, Edge
// Accessing iframe documents after unload throws "permission denied" errors (jQuery #13936)
if ( preferredDoc !== document &&
(subWindow = document.defaultView) && subWindow.top !== subWindow ) {
// Support: IE 11, Edge
if ( subWindow.addEventListener ) {
subWindow.addEventListener( "unload", unloadHandler, false );
// Support: IE 9 - 10 only
} else if ( subWindow.attachEvent ) {
subWindow.attachEvent( "onunload", unloadHandler );
}
}
/* Attributes
---------------------------------------------------------------------- */
// Support: IE<8
// Verify that getAttribute really returns attributes and not properties
// (excepting IE8 booleans)
support.attributes = assert(function( el ) {
el.className = "i";
return !el.getAttribute("className");
});
/* getElement(s)By*
---------------------------------------------------------------------- */
// Check if getElementsByTagName("*") returns only elements
support.getElementsByTagName = assert(function( el ) {
el.appendChild( document.createComment("") );
return !el.getElementsByTagName("*").length;
});
// Support: IE<9
support.getElementsByClassName = rnative.test( document.getElementsByClassName );
// Support: IE<10
// Check if getElementById returns elements by name
// The broken getElementById methods don't pick up programmatically-set names,
// so use a roundabout getElementsByName test
support.getById = assert(function( el ) {
docElem.appendChild( el ).id = expando;
return !document.getElementsByName || !document.getElementsByName( expando ).length;
});
// ID filter and find
if ( support.getById ) {
Expr.filter["ID"] = function( id ) {
var attrId = id.replace( runescape, funescape );
return function( elem ) {
return elem.getAttribute("id") === attrId;
};
};
Expr.find["ID"] = function( id, context ) {
if ( typeof context.getElementById !== "undefined" && documentIsHTML ) {
var elem = context.getElementById( id );
return elem ? [ elem ] : [];
}
};
} else {
Expr.filter["ID"] = function( id ) {
var attrId = id.replace( runescape, funescape );
return function( elem ) {
var node = typeof elem.getAttributeNode !== "undefined" &&
elem.getAttributeNode("id");
return node && node.value === attrId;
};
};
// Support: IE 6 - 7 only
// getElementById is not reliable as a find shortcut
Expr.find["ID"] = function( id, context ) {
if ( typeof context.getElementById !== "undefined" && documentIsHTML ) {
var node, i, elems,
elem = context.getElementById( id );
if ( elem ) {
// Verify the id attribute
node = elem.getAttributeNode("id");
if ( node && node.value === id ) {
return [ elem ];
}
// Fall back on getElementsByName
elems = context.getElementsByName( id );
i = 0;
while ( (elem = elems[i++]) ) {
node = elem.getAttributeNode("id");
if ( node && node.value === id ) {
return [ elem ];
}
}
}
return [];
}
};
}
// Tag
Expr.find["TAG"] = support.getElementsByTagName ?
function( tag, context ) {
if ( typeof context.getElementsByTagName !== "undefined" ) {
return context.getElementsByTagName( tag );
// DocumentFragment nodes don't have gEBTN
} else if ( support.qsa ) {
return context.querySelectorAll( tag );
}
} :
function( tag, context ) {
var elem,
tmp = [],
i = 0,
// By happy coincidence, a (broken) gEBTN appears on DocumentFragment nodes too
results = context.getElementsByTagName( tag );
// Filter out possible comments
if ( tag === "*" ) {
while ( (elem = results[i++]) ) {
if ( elem.nodeType === 1 ) {
tmp.push( elem );
}
}
return tmp;
}
return results;
};
// Class
Expr.find["CLASS"] = support.getElementsByClassName && function( className, context ) {
if ( typeof context.getElementsByClassName !== "undefined" && documentIsHTML ) {
return context.getElementsByClassName( className );
}
};
/* QSA/matchesSelector
---------------------------------------------------------------------- */
// QSA and matchesSelector support
// matchesSelector(:active) reports false when true (IE9/Opera 11.5)
rbuggyMatches = [];
// qSa(:focus) reports false when true (Chrome 21)
// We allow this because of a bug in IE8/9 that throws an error
// whenever `document.activeElement` is accessed on an iframe
// So, we allow :focus to pass through QSA all the time to avoid the IE error
// See https://bugs.jquery.com/ticket/13378
rbuggyQSA = [];
if ( (support.qsa = rnative.test( document.querySelectorAll )) ) {
// Build QSA regex
// Regex strategy adopted from Diego Perini
assert(function( el ) {
// Select is set to empty string on purpose
// This is to test IE's treatment of not explicitly
// setting a boolean content attribute,
// since its presence should be enough
// https://bugs.jquery.com/ticket/12359
docElem.appendChild( el ).innerHTML = "<a id='" + expando + "'></a>" +
"<select id='" + expando + "-\r\\' msallowcapture=''>" +
"<option selected=''></option></select>";
// Support: IE8, Opera 11-12.16
// Nothing should be selected when empty strings follow ^= or $= or *=
// The test attribute must be unknown in Opera but "safe" for WinRT
// https://msdn.microsoft.com/en-us/library/ie/hh465388.aspx#attribute_section
if ( el.querySelectorAll("[msallowcapture^='']").length ) {
rbuggyQSA.push( "[*^$]=" + whitespace + "*(?:''|\"\")" );
}
// Support: IE8
// Boolean attributes and "value" are not treated correctly
if ( !el.querySelectorAll("[selected]").length ) {
rbuggyQSA.push( "\\[" + whitespace + "*(?:value|" + booleans + ")" );
}
// Support: Chrome<29, Android<4.4, Safari<7.0+, iOS<7.0+, PhantomJS<1.9.8+
if ( !el.querySelectorAll( "[id~=" + expando + "-]" ).length ) {
rbuggyQSA.push("~=");
}
// Webkit/Opera - :checked should return selected option elements
// http://www.w3.org/TR/2011/REC-css3-selectors-20110929/#checked
// IE8 throws error here and will not see later tests
if ( !el.querySelectorAll(":checked").length ) {
rbuggyQSA.push(":checked");
}
// Support: Safari 8+, iOS 8+
// https://bugs.webkit.org/show_bug.cgi?id=136851
// In-page `selector#id sibling-combinator selector` fails
if ( !el.querySelectorAll( "a#" + expando + "+*" ).length ) {
rbuggyQSA.push(".#.+[+~]");
}
});
assert(function( el ) {
el.innerHTML = "<a href='' disabled='disabled'></a>" +
"<select disabled='disabled'><option/></select>";
// Support: Windows 8 Native Apps
// The type and name attributes are restricted during .innerHTML assignment
var input = document.createElement("input");
input.setAttribute( "type", "hidden" );
el.appendChild( input ).setAttribute( "name", "D" );
// Support: IE8
// Enforce case-sensitivity of name attribute
if ( el.querySelectorAll("[name=d]").length ) {
rbuggyQSA.push( "name" + whitespace + "*[*^$|!~]?=" );
}
// FF 3.5 - :enabled/:disabled and hidden elements (hidden elements are still enabled)
// IE8 throws error here and will not see later tests
if ( el.querySelectorAll(":enabled").length !== 2 ) {
rbuggyQSA.push( ":enabled", ":disabled" );
}
// Support: IE9-11+
// IE's :disabled selector does not pick up the children of disabled fieldsets
docElem.appendChild( el ).disabled = true;
if ( el.querySelectorAll(":disabled").length !== 2 ) {
rbuggyQSA.push( ":enabled", ":disabled" );
}
// Opera 10-11 does not throw on post-comma invalid pseudos
el.querySelectorAll("*,:x");
rbuggyQSA.push(",.*:");
});
}
if ( (support.matchesSelector = rnative.test( (matches = docElem.matches ||
docElem.webkitMatchesSelector ||
docElem.mozMatchesSelector ||
docElem.oMatchesSelector ||
docElem.msMatchesSelector) )) ) {
assert(function( el ) {
// Check to see if it's possible to do matchesSelector
// on a disconnected node (IE 9)
support.disconnectedMatch = matches.call( el, "*" );
// This should fail with an exception
// Gecko does not error, returns false instead
matches.call( el, "[s!='']:x" );
rbuggyMatches.push( "!=", pseudos );
});
}
rbuggyQSA = rbuggyQSA.length && new RegExp( rbuggyQSA.join("|") );
rbuggyMatches = rbuggyMatches.length && new RegExp( rbuggyMatches.join("|") );
/* Contains
---------------------------------------------------------------------- */
hasCompare = rnative.test( docElem.compareDocumentPosition );
// Element contains another
// Purposefully self-exclusive
// As in, an element does not contain itself
contains = hasCompare || rnative.test( docElem.contains ) ?
function( a, b ) {
var adown = a.nodeType === 9 ? a.documentElement : a,
bup = b && b.parentNode;
return a === bup || !!( bup && bup.nodeType === 1 && (
adown.contains ?
adown.contains( bup ) :
a.compareDocumentPosition && a.compareDocumentPosition( bup ) & 16
));
} :
function( a, b ) {
if ( b ) {
while ( (b = b.parentNode) ) {
if ( b === a ) {
return true;
}
}
}
return false;
};
/* Sorting
---------------------------------------------------------------------- */
// Document order sorting
sortOrder = hasCompare ?
function( a, b ) {
// Flag for duplicate removal
if ( a === b ) {
hasDuplicate = true;
return 0;
}
// Sort on method existence if only one input has compareDocumentPosition
var compare = !a.compareDocumentPosition - !b.compareDocumentPosition;
if ( compare ) {
return compare;
}
// Calculate position if both inputs belong to the same document
compare = ( a.ownerDocument || a ) === ( b.ownerDocument || b ) ?
a.compareDocumentPosition( b ) :
// Otherwise we know they are disconnected
1;
// Disconnected nodes
if ( compare & 1 ||
(!support.sortDetached && b.compareDocumentPosition( a ) === compare) ) {
// Choose the first element that is related to our preferred document
if ( a === document || a.ownerDocument === preferredDoc && contains(preferredDoc, a) ) {
return -1;
}
if ( b === document || b.ownerDocument === preferredDoc && contains(preferredDoc, b) ) {
return 1;
}
// Maintain original order
return sortInput ?
( indexOf( sortInput, a ) - indexOf( sortInput, b ) ) :
0;
}
return compare & 4 ? -1 : 1;
} :
function( a, b ) {
// Exit early if the nodes are identical
if ( a === b ) {
hasDuplicate = true;
return 0;
}
var cur,
i = 0,
aup = a.parentNode,
bup = b.parentNode,
ap = [ a ],
bp = [ b ];
// Parentless nodes are either documents or disconnected
if ( !aup || !bup ) {
return a === document ? -1 :
b === document ? 1 :
aup ? -1 :
bup ? 1 :
sortInput ?
( indexOf( sortInput, a ) - indexOf( sortInput, b ) ) :
0;
// If the nodes are siblings, we can do a quick check
} else if ( aup === bup ) {
return siblingCheck( a, b );
}
// Otherwise we need full lists of their ancestors for comparison
cur = a;
while ( (cur = cur.parentNode) ) {
ap.unshift( cur );
}
cur = b;
while ( (cur = cur.parentNode) ) {
bp.unshift( cur );
}
// Walk down the tree looking for a discrepancy
while ( ap[i] === bp[i] ) {
i++;
}
return i ?
// Do a sibling check if the nodes have a common ancestor
siblingCheck( ap[i], bp[i] ) :
// Otherwise nodes in our document sort first
ap[i] === preferredDoc ? -1 :
bp[i] === preferredDoc ? 1 :
0;
};
return document;
};
Sizzle.matches = function( expr, elements ) {
return Sizzle( expr, null, null, elements );
};
Sizzle.matchesSelector = function( elem, expr ) {
// Set document vars if needed
if ( ( elem.ownerDocument || elem ) !== document ) {
setDocument( elem );
}
// Make sure that attribute selectors are quoted
expr = expr.replace( rattributeQuotes, "='$1']" );
if ( support.matchesSelector && documentIsHTML &&
!compilerCache[ expr + " " ] &&
( !rbuggyMatches || !rbuggyMatches.test( expr ) ) &&
( !rbuggyQSA || !rbuggyQSA.test( expr ) ) ) {
try {
var ret = matches.call( elem, expr );
// IE 9's matchesSelector returns false on disconnected nodes
if ( ret || support.disconnectedMatch ||
// As well, disconnected nodes are said to be in a document
// fragment in IE 9
elem.document && elem.document.nodeType !== 11 ) {
return ret;
}
} catch (e) {}
}
return Sizzle( expr, document, null, [ elem ] ).length > 0;
};
Sizzle.contains = function( context, elem ) {
// Set document vars if needed
if ( ( context.ownerDocument || context ) !== document ) {
setDocument( context );
}
return contains( context, elem );
};
Sizzle.attr = function( elem, name ) {
// Set document vars if needed
if ( ( elem.ownerDocument || elem ) !== document ) {
setDocument( elem );
}
var fn = Expr.attrHandle[ name.toLowerCase() ],
// Don't get fooled by Object.prototype properties (jQuery #13807)
val = fn && hasOwn.call( Expr.attrHandle, name.toLowerCase() ) ?
fn( elem, name, !documentIsHTML ) :
undefined;
return val !== undefined ?
val :
support.attributes || !documentIsHTML ?
elem.getAttribute( name ) :
(val = elem.getAttributeNode(name)) && val.specified ?
val.value :
null;
};
Sizzle.escape = function( sel ) {
return (sel + "").replace( rcssescape, fcssescape );
};
Sizzle.error = function( msg ) {
throw new Error( "Syntax error, unrecognized expression: " + msg );
};
/**
* Document sorting and removing duplicates
* @param {ArrayLike} results
*/
Sizzle.uniqueSort = function( results ) {
var elem,
duplicates = [],
j = 0,
i = 0;
// Unless we *know* we can detect duplicates, assume their presence
hasDuplicate = !support.detectDuplicates;
sortInput = !support.sortStable && results.slice( 0 );
results.sort( sortOrder );
if ( hasDuplicate ) {
while ( (elem = results[i++]) ) {
if ( elem === results[ i ] ) {
j = duplicates.push( i );
}
}
while ( j-- ) {
results.splice( duplicates[ j ], 1 );
}
}
// Clear input after sorting to release objects
// See https://github.com/jquery/sizzle/pull/225
sortInput = null;
return results;
};
/**
* Utility function for retrieving the text value of an array of DOM nodes
* @param {Array|Element} elem
*/
getText = Sizzle.getText = function( elem ) {
var node,
ret = "",
i = 0,
nodeType = elem.nodeType;
if ( !nodeType ) {
// If no nodeType, this is expected to be an array
while ( (node = elem[i++]) ) {
// Do not traverse comment nodes
ret += getText( node );
}
} else if ( nodeType === 1 || nodeType === 9 || nodeType === 11 ) {
// Use textContent for elements
// innerText usage removed for consistency of new lines (jQuery #11153)
if ( typeof elem.textContent === "string" ) {
return elem.textContent;
} else {
// Traverse its children
for ( elem = elem.firstChild; elem; elem = elem.nextSibling ) {
ret += getText( elem );
}
}
} else if ( nodeType === 3 || nodeType === 4 ) {
return elem.nodeValue;
}
// Do not include comment or processing instruction nodes
return ret;
};
Expr = Sizzle.selectors = {
// Can be adjusted by the user
cacheLength: 50,
createPseudo: markFunction,
match: matchExpr,
attrHandle: {},
find: {},
relative: {
">": { dir: "parentNode", first: true },
" ": { dir: "parentNode" },
"+": { dir: "previousSibling", first: true },
"~": { dir: "previousSibling" }
},
preFilter: {
"ATTR": function( match ) {
match[1] = match[1].replace( runescape, funescape );
// Move the given value to match[3] whether quoted or unquoted
match[3] = ( match[3] || match[4] || match[5] || "" ).replace( runescape, funescape );
if ( match[2] === "~=" ) {
match[3] = " " + match[3] + " ";
}
return match.slice( 0, 4 );
},
"CHILD": function( match ) {
/* matches from matchExpr["CHILD"]
1 type (only|nth|...)
2 what (child|of-type)
3 argument (even|odd|\d*|\d*n([+-]\d+)?|...)
4 xn-component of xn+y argument ([+-]?\d*n|)
5 sign of xn-component
6 x of xn-component
7 sign of y-component
8 y of y-component
*/
match[1] = match[1].toLowerCase();
if ( match[1].slice( 0, 3 ) === "nth" ) {
// nth-* requires argument
if ( !match[3] ) {
Sizzle.error( match[0] );
}
// numeric x and y parameters for Expr.filter.CHILD
// remember that false/true cast respectively to 0/1
match[4] = +( match[4] ? match[5] + (match[6] || 1) : 2 * ( match[3] === "even" || match[3] === "odd" ) );
match[5] = +( ( match[7] + match[8] ) || match[3] === "odd" );
// other types prohibit arguments
} else if ( match[3] ) {
Sizzle.error( match[0] );
}
return match;
},
"PSEUDO": function( match ) {
var excess,
unquoted = !match[6] && match[2];
if ( matchExpr["CHILD"].test( match[0] ) ) {
return null;
}
// Accept quoted arguments as-is
if ( match[3] ) {
match[2] = match[4] || match[5] || "";
// Strip excess characters from unquoted arguments
} else if ( unquoted && rpseudo.test( unquoted ) &&
// Get excess from tokenize (recursively)
(excess = tokenize( unquoted, true )) &&
// advance to the next closing parenthesis
(excess = unquoted.indexOf( ")", unquoted.length - excess ) - unquoted.length) ) {
// excess is a negative index
match[0] = match[0].slice( 0, excess );
match[2] = unquoted.slice( 0, excess );
}
// Return only captures needed by the pseudo filter method (type and argument)
return match.slice( 0, 3 );
}
},
filter: {
"TAG": function( nodeNameSelector ) {
var nodeName = nodeNameSelector.replace( runescape, funescape ).toLowerCase();
return nodeNameSelector === "*" ?
function() { return true; } :
function( elem ) {
return elem.nodeName && elem.nodeName.toLowerCase() === nodeName;
};
},
"CLASS": function( className ) {
var pattern = classCache[ className + " " ];
return pattern ||
(pattern = new RegExp( "(^|" + whitespace + ")" + className + "(" + whitespace + "|$)" )) &&
classCache( className, function( elem ) {
return pattern.test( typeof elem.className === "string" && elem.className || typeof elem.getAttribute !== "undefined" && elem.getAttribute("class") || "" );
});
},
"ATTR": function( name, operator, check ) {
return function( elem ) {
var result = Sizzle.attr( elem, name );
if ( result == null ) {
return operator === "!=";
}
if ( !operator ) {
return true;
}
result += "";
return operator === "=" ? result === check :
operator === "!=" ? result !== check :
operator === "^=" ? check && result.indexOf( check ) === 0 :
operator === "*=" ? check && result.indexOf( check ) > -1 :
operator === "$=" ? check && result.slice( -check.length ) === check :
operator === "~=" ? ( " " + result.replace( rwhitespace, " " ) + " " ).indexOf( check ) > -1 :
operator === "|=" ? result === check || result.slice( 0, check.length + 1 ) === check + "-" :
false;
};
},
"CHILD": function( type, what, argument, first, last ) {
var simple = type.slice( 0, 3 ) !== "nth",
forward = type.slice( -4 ) !== "last",
ofType = what === "of-type";
return first === 1 && last === 0 ?
// Shortcut for :nth-*(n)
function( elem ) {
return !!elem.parentNode;
} :
function( elem, context, xml ) {
var cache, uniqueCache, outerCache, node, nodeIndex, start,
dir = simple !== forward ? "nextSibling" : "previousSibling",
parent = elem.parentNode,
name = ofType && elem.nodeName.toLowerCase(),
useCache = !xml && !ofType,
diff = false;
if ( parent ) {
// :(first|last|only)-(child|of-type)
if ( simple ) {
while ( dir ) {
node = elem;
while ( (node = node[ dir ]) ) {
if ( ofType ?
node.nodeName.toLowerCase() === name :
node.nodeType === 1 ) {
return false;
}
}
// Reverse direction for :only-* (if we haven't yet done so)
start = dir = type === "only" && !start && "nextSibling";
}
return true;
}
start = [ forward ? parent.firstChild : parent.lastChild ];
// non-xml :nth-child(...) stores cache data on `parent`
if ( forward && useCache ) {
// Seek `elem` from a previously-cached index
// ...in a gzip-friendly way
node = parent;
outerCache = node[ expando ] || (node[ expando ] = {});
// Support: IE <9 only
// Defend against cloned attroperties (jQuery gh-1709)
uniqueCache = outerCache[ node.uniqueID ] ||
(outerCache[ node.uniqueID ] = {});
cache = uniqueCache[ type ] || [];
nodeIndex = cache[ 0 ] === dirruns && cache[ 1 ];
diff = nodeIndex && cache[ 2 ];
node = nodeIndex && parent.childNodes[ nodeIndex ];
while ( (node = ++nodeIndex && node && node[ dir ] ||
// Fallback to seeking `elem` from the start
(diff = nodeIndex = 0) || start.pop()) ) {
// When found, cache indexes on `parent` and break
if ( node.nodeType === 1 && ++diff && node === elem ) {
uniqueCache[ type ] = [ dirruns, nodeIndex, diff ];
break;
}
}
} else {
// Use previously-cached element index if available
if ( useCache ) {
// ...in a gzip-friendly way
node = elem;
outerCache = node[ expando ] || (node[ expando ] = {});
// Support: IE <9 only
// Defend against cloned attroperties (jQuery gh-1709)
uniqueCache = outerCache[ node.uniqueID ] ||
(outerCache[ node.uniqueID ] = {});
cache = uniqueCache[ type ] || [];
nodeIndex = cache[ 0 ] === dirruns && cache[ 1 ];
diff = nodeIndex;
}
// xml :nth-child(...)
// or :nth-last-child(...) or :nth(-last)?-of-type(...)
if ( diff === false ) {
// Use the same loop as above to seek `elem` from the start
while ( (node = ++nodeIndex && node && node[ dir ] ||
(diff = nodeIndex = 0) || start.pop()) ) {
if ( ( ofType ?
node.nodeName.toLowerCase() === name :
node.nodeType === 1 ) &&
++diff ) {
// Cache the index of each encountered element
if ( useCache ) {
outerCache = node[ expando ] || (node[ expando ] = {});
// Support: IE <9 only
// Defend against cloned attroperties (jQuery gh-1709)
uniqueCache = outerCache[ node.uniqueID ] ||
(outerCache[ node.uniqueID ] = {});
uniqueCache[ type ] = [ dirruns, diff ];
}
if ( node === elem ) {
break;
}
}
}
}
}
// Incorporate the offset, then check against cycle size
diff -= last;
return diff === first || ( diff % first === 0 && diff / first >= 0 );
}
};
},
"PSEUDO": function( pseudo, argument ) {
// pseudo-class names are case-insensitive
// http://www.w3.org/TR/selectors/#pseudo-classes
// Prioritize by case sensitivity in case custom pseudos are added with uppercase letters
// Remember that setFilters inherits from pseudos
var args,
fn = Expr.pseudos[ pseudo ] || Expr.setFilters[ pseudo.toLowerCase() ] ||
Sizzle.error( "unsupported pseudo: " + pseudo );
// The user may use createPseudo to indicate that
// arguments are needed to create the filter function
// just as Sizzle does
if ( fn[ expando ] ) {
return fn( argument );
}
// But maintain support for old signatures
if ( fn.length > 1 ) {
args = [ pseudo, pseudo, "", argument ];
return Expr.setFilters.hasOwnProperty( pseudo.toLowerCase() ) ?
markFunction(function( seed, matches ) {
var idx,
matched = fn( seed, argument ),
i = matched.length;
while ( i-- ) {
idx = indexOf( seed, matched[i] );
seed[ idx ] = !( matches[ idx ] = matched[i] );
}
}) :
function( elem ) {
return fn( elem, 0, args );
};
}
return fn;
}
},
pseudos: {
// Potentially complex pseudos
"not": markFunction(function( selector ) {
// Trim the selector passed to compile
// to avoid treating leading and trailing
// spaces as combinators
var input = [],
results = [],
matcher = compile( selector.replace( rtrim, "$1" ) );
return matcher[ expando ] ?
markFunction(function( seed, matches, context, xml ) {
var elem,
unmatched = matcher( seed, null, xml, [] ),
i = seed.length;
// Match elements unmatched by `matcher`
while ( i-- ) {
if ( (elem = unmatched[i]) ) {
seed[i] = !(matches[i] = elem);
}
}
}) :
function( elem, context, xml ) {
input[0] = elem;
matcher( input, null, xml, results );
// Don't keep the element (issue #299)
input[0] = null;
return !results.pop();
};
}),
"has": markFunction(function( selector ) {
return function( elem ) {
return Sizzle( selector, elem ).length > 0;
};
}),
"contains": markFunction(function( text ) {
text = text.replace( runescape, funescape );
return function( elem ) {
return ( elem.textContent || elem.innerText || getText( elem ) ).indexOf( text ) > -1;
};
}),
// "Whether an element is represented by a :lang() selector
// is based solely on the element's language value
// being equal to the identifier C,
// or beginning with the identifier C immediately followed by "-".
// The matching of C against the element's language value is performed case-insensitively.
// The identifier C does not have to be a valid language name."
// http://www.w3.org/TR/selectors/#lang-pseudo
"lang": markFunction( function( lang ) {
// lang value must be a valid identifier
if ( !ridentifier.test(lang || "") ) {
Sizzle.error( "unsupported lang: " + lang );
}
lang = lang.replace( runescape, funescape ).toLowerCase();
return function( elem ) {
var elemLang;
do {
if ( (elemLang = documentIsHTML ?
elem.lang :
elem.getAttribute("xml:lang") || elem.getAttribute("lang")) ) {
elemLang = elemLang.toLowerCase();
return elemLang === lang || elemLang.indexOf( lang + "-" ) === 0;
}
} while ( (elem = elem.parentNode) && elem.nodeType === 1 );
return false;
};
}),
// Miscellaneous
"target": function( elem ) {
var hash = window.location && window.location.hash;
return hash && hash.slice( 1 ) === elem.id;
},
"root": function( elem ) {
return elem === docElem;
},
"focus": function( elem ) {
return elem === document.activeElement && (!document.hasFocus || document.hasFocus()) && !!(elem.type || elem.href || ~elem.tabIndex);
},
// Boolean properties
"enabled": createDisabledPseudo( false ),
"disabled": createDisabledPseudo( true ),
"checked": function( elem ) {
// In CSS3, :checked should return both checked and selected elements
// http://www.w3.org/TR/2011/REC-css3-selectors-20110929/#checked
var nodeName = elem.nodeName.toLowerCase();
return (nodeName === "input" && !!elem.checked) || (nodeName === "option" && !!elem.selected);
},
"selected": function( elem ) {
// Accessing this property makes selected-by-default
// options in Safari work properly
if ( elem.parentNode ) {
elem.parentNode.selectedIndex;
}
return elem.selected === true;
},
// Contents
"empty": function( elem ) {
// http://www.w3.org/TR/selectors/#empty-pseudo
// :empty is negated by element (1) or content nodes (text: 3; cdata: 4; entity ref: 5),
// but not by others (comment: 8; processing instruction: 7; etc.)
// nodeType < 6 works because attributes (2) do not appear as children
for ( elem = elem.firstChild; elem; elem = elem.nextSibling ) {
if ( elem.nodeType < 6 ) {
return false;
}
}
return true;
},
"parent": function( elem ) {
return !Expr.pseudos["empty"]( elem );
},
// Element/input types
"header": function( elem ) {
return rheader.test( elem.nodeName );
},
"input": function( elem ) {
return rinputs.test( elem.nodeName );
},
"button": function( elem ) {
var name = elem.nodeName.toLowerCase();
return name === "input" && elem.type === "button" || name === "button";
},
"text": function( elem ) {
var attr;
return elem.nodeName.toLowerCase() === "input" &&
elem.type === "text" &&
// Support: IE<8
// New HTML5 attribute values (e.g., "search") appear with elem.type === "text"
( (attr = elem.getAttribute("type")) == null || attr.toLowerCase() === "text" );
},
// Position-in-collection
"first": createPositionalPseudo(function() {
return [ 0 ];
}),
"last": createPositionalPseudo(function( matchIndexes, length ) {
return [ length - 1 ];
}),
"eq": createPositionalPseudo(function( matchIndexes, length, argument ) {
return [ argument < 0 ? argument + length : argument ];
}),
"even": createPositionalPseudo(function( matchIndexes, length ) {
var i = 0;
for ( ; i < length; i += 2 ) {
matchIndexes.push( i );
}
return matchIndexes;
}),
"odd": createPositionalPseudo(function( matchIndexes, length ) {
var i = 1;
for ( ; i < length; i += 2 ) {
matchIndexes.push( i );
}
return matchIndexes;
}),
"lt": createPositionalPseudo(function( matchIndexes, length, argument ) {
var i = argument < 0 ? argument + length : argument;
for ( ; --i >= 0; ) {
matchIndexes.push( i );
}
return matchIndexes;
}),
"gt": createPositionalPseudo(function( matchIndexes, length, argument ) {
var i = argument < 0 ? argument + length : argument;
for ( ; ++i < length; ) {
matchIndexes.push( i );
}
return matchIndexes;
})
}
};
Expr.pseudos["nth"] = Expr.pseudos["eq"];
// Add button/input type pseudos
for ( i in { radio: true, checkbox: true, file: true, password: true, image: true } ) {
Expr.pseudos[ i ] = createInputPseudo( i );
}
for ( i in { submit: true, reset: true } ) {
Expr.pseudos[ i ] = createButtonPseudo( i );
}
// Easy API for creating new setFilters
function setFilters() {}
setFilters.prototype = Expr.filters = Expr.pseudos;
Expr.setFilters = new setFilters();
tokenize = Sizzle.tokenize = function( selector, parseOnly ) {
var matched, match, tokens, type,
soFar, groups, preFilters,
cached = tokenCache[ selector + " " ];
if ( cached ) {
return parseOnly ? 0 : cached.slice( 0 );
}
soFar = selector;
groups = [];
preFilters = Expr.preFilter;
while ( soFar ) {
// Comma and first run
if ( !matched || (match = rcomma.exec( soFar )) ) {
if ( match ) {
// Don't consume trailing commas as valid
soFar = soFar.slice( match[0].length ) || soFar;
}
groups.push( (tokens = []) );
}
matched = false;
// Combinators
if ( (match = rcombinators.exec( soFar )) ) {
matched = match.shift();
tokens.push({
value: matched,
// Cast descendant combinators to space
type: match[0].replace( rtrim, " " )
});
soFar = soFar.slice( matched.length );
}
// Filters
for ( type in Expr.filter ) {
if ( (match = matchExpr[ type ].exec( soFar )) && (!preFilters[ type ] ||
(match = preFilters[ type ]( match ))) ) {
matched = match.shift();
tokens.push({
value: matched,
type: type,
matches: match
});
soFar = soFar.slice( matched.length );
}
}
if ( !matched ) {
break;
}
}
// Return the length of the invalid excess
// if we're just parsing
// Otherwise, throw an error or return tokens
return parseOnly ?
soFar.length :
soFar ?
Sizzle.error( selector ) :
// Cache the tokens
tokenCache( selector, groups ).slice( 0 );
};
function toSelector( tokens ) {
var i = 0,
len = tokens.length,
selector = "";
for ( ; i < len; i++ ) {
selector += tokens[i].value;
}
return selector;
}
function addCombinator( matcher, combinator, base ) {
var dir = combinator.dir,
skip = combinator.next,
key = skip || dir,
checkNonElements = base && key === "parentNode",
doneName = done++;
return combinator.first ?
// Check against closest ancestor/preceding element
function( elem, context, xml ) {
while ( (elem = elem[ dir ]) ) {
if ( elem.nodeType === 1 || checkNonElements ) {
return matcher( elem, context, xml );
}
}
return false;
} :
// Check against all ancestor/preceding elements
function( elem, context, xml ) {
var oldCache, uniqueCache, outerCache,
newCache = [ dirruns, doneName ];
// We can't set arbitrary data on XML nodes, so they don't benefit from combinator caching
if ( xml ) {
while ( (elem = elem[ dir ]) ) {
if ( elem.nodeType === 1 || checkNonElements ) {
if ( matcher( elem, context, xml ) ) {
return true;
}
}
}
} else {
while ( (elem = elem[ dir ]) ) {
if ( elem.nodeType === 1 || checkNonElements ) {
outerCache = elem[ expando ] || (elem[ expando ] = {});
// Support: IE <9 only
// Defend against cloned attroperties (jQuery gh-1709)
uniqueCache = outerCache[ elem.uniqueID ] || (outerCache[ elem.uniqueID ] = {});
if ( skip && skip === elem.nodeName.toLowerCase() ) {
elem = elem[ dir ] || elem;
} else if ( (oldCache = uniqueCache[ key ]) &&
oldCache[ 0 ] === dirruns && oldCache[ 1 ] === doneName ) {
// Assign to newCache so results back-propagate to previous elements
return (newCache[ 2 ] = oldCache[ 2 ]);
} else {
// Reuse newcache so results back-propagate to previous elements
uniqueCache[ key ] = newCache;
// A match means we're done; a fail means we have to keep checking
if ( (newCache[ 2 ] = matcher( elem, context, xml )) ) {
return true;
}
}
}
}
}
return false;
};
}
function elementMatcher( matchers ) {
return matchers.length > 1 ?
function( elem, context, xml ) {
var i = matchers.length;
while ( i-- ) {
if ( !matchers[i]( elem, context, xml ) ) {
return false;
}
}
return true;
} :
matchers[0];
}
function multipleContexts( selector, contexts, results ) {
var i = 0,
len = contexts.length;
for ( ; i < len; i++ ) {
Sizzle( selector, contexts[i], results );
}
return results;
}
function condense( unmatched, map, filter, context, xml ) {
var elem,
newUnmatched = [],
i = 0,
len = unmatched.length,
mapped = map != null;
for ( ; i < len; i++ ) {
if ( (elem = unmatched[i]) ) {
if ( !filter || filter( elem, context, xml ) ) {
newUnmatched.push( elem );
if ( mapped ) {
map.push( i );
}
}
}
}
return newUnmatched;
}
function setMatcher( preFilter, selector, matcher, postFilter, postFinder, postSelector ) {
if ( postFilter && !postFilter[ expando ] ) {
postFilter = setMatcher( postFilter );
}
if ( postFinder && !postFinder[ expando ] ) {
postFinder = setMatcher( postFinder, postSelector );
}
return markFunction(function( seed, results, context, xml ) {
var temp, i, elem,
preMap = [],
postMap = [],
preexisting = results.length,
// Get initial elements from seed or context
elems = seed || multipleContexts( selector || "*", context.nodeType ? [ context ] : context, [] ),
// Prefilter to get matcher input, preserving a map for seed-results synchronization
matcherIn = preFilter && ( seed || !selector ) ?
condense( elems, preMap, preFilter, context, xml ) :
elems,
matcherOut = matcher ?
// If we have a postFinder, or filtered seed, or non-seed postFilter or preexisting results,
postFinder || ( seed ? preFilter : preexisting || postFilter ) ?
// ...intermediate processing is necessary
[] :
// ...otherwise use results directly
results :
matcherIn;
// Find primary matches
if ( matcher ) {
matcher( matcherIn, matcherOut, context, xml );
}
// Apply postFilter
if ( postFilter ) {
temp = condense( matcherOut, postMap );
postFilter( temp, [], context, xml );
// Un-match failing elements by moving them back to matcherIn
i = temp.length;
while ( i-- ) {
if ( (elem = temp[i]) ) {
matcherOut[ postMap[i] ] = !(matcherIn[ postMap[i] ] = elem);
}
}
}
if ( seed ) {
if ( postFinder || preFilter ) {
if ( postFinder ) {
// Get the final matcherOut by condensing this intermediate into postFinder contexts
temp = [];
i = matcherOut.length;
while ( i-- ) {
if ( (elem = matcherOut[i]) ) {
// Restore matcherIn since elem is not yet a final match
temp.push( (matcherIn[i] = elem) );
}
}
postFinder( null, (matcherOut = []), temp, xml );
}
// Move matched elements from seed to results to keep them synchronized
i = matcherOut.length;
while ( i-- ) {
if ( (elem = matcherOut[i]) &&
(temp = postFinder ? indexOf( seed, elem ) : preMap[i]) > -1 ) {
seed[temp] = !(results[temp] = elem);
}
}
}
// Add elements to results, through postFinder if defined
} else {
matcherOut = condense(
matcherOut === results ?
matcherOut.splice( preexisting, matcherOut.length ) :
matcherOut
);
if ( postFinder ) {
postFinder( null, results, matcherOut, xml );
} else {
push.apply( results, matcherOut );
}
}
});
}
function matcherFromTokens( tokens ) {
var checkContext, matcher, j,
len = tokens.length,
leadingRelative = Expr.relative[ tokens[0].type ],
implicitRelative = leadingRelative || Expr.relative[" "],
i = leadingRelative ? 1 : 0,
// The foundational matcher ensures that elements are reachable from top-level context(s)
matchContext = addCombinator( function( elem ) {
return elem === checkContext;
}, implicitRelative, true ),
matchAnyContext = addCombinator( function( elem ) {
return indexOf( checkContext, elem ) > -1;
}, implicitRelative, true ),
matchers = [ function( elem, context, xml ) {
var ret = ( !leadingRelative && ( xml || context !== outermostContext ) ) || (
(checkContext = context).nodeType ?
matchContext( elem, context, xml ) :
matchAnyContext( elem, context, xml ) );
// Avoid hanging onto element (issue #299)
checkContext = null;
return ret;
} ];
for ( ; i < len; i++ ) {
if ( (matcher = Expr.relative[ tokens[i].type ]) ) {
matchers = [ addCombinator(elementMatcher( matchers ), matcher) ];
} else {
matcher = Expr.filter[ tokens[i].type ].apply( null, tokens[i].matches );
// Return special upon seeing a positional matcher
if ( matcher[ expando ] ) {
// Find the next relative operator (if any) for proper handling
j = ++i;
for ( ; j < len; j++ ) {
if ( Expr.relative[ tokens[j].type ] ) {
break;
}
}
return setMatcher(
i > 1 && elementMatcher( matchers ),
i > 1 && toSelector(
// If the preceding token was a descendant combinator, insert an implicit any-element `*`
tokens.slice( 0, i - 1 ).concat({ value: tokens[ i - 2 ].type === " " ? "*" : "" })
).replace( rtrim, "$1" ),
matcher,
i < j && matcherFromTokens( tokens.slice( i, j ) ),
j < len && matcherFromTokens( (tokens = tokens.slice( j )) ),
j < len && toSelector( tokens )
);
}
matchers.push( matcher );
}
}
return elementMatcher( matchers );
}
function matcherFromGroupMatchers( elementMatchers, setMatchers ) {
var bySet = setMatchers.length > 0,
byElement = elementMatchers.length > 0,
superMatcher = function( seed, context, xml, results, outermost ) {
var elem, j, matcher,
matchedCount = 0,
i = "0",
unmatched = seed && [],
setMatched = [],
contextBackup = outermostContext,
// We must always have either seed elements or outermost context
elems = seed || byElement && Expr.find["TAG"]( "*", outermost ),
// Use integer dirruns iff this is the outermost matcher
dirrunsUnique = (dirruns += contextBackup == null ? 1 : Math.random() || 0.1),
len = elems.length;
if ( outermost ) {
outermostContext = context === document || context || outermost;
}
// Add elements passing elementMatchers directly to results
// Support: IE<9, Safari
// Tolerate NodeList properties (IE: "length"; Safari: <number>) matching elements by id
for ( ; i !== len && (elem = elems[i]) != null; i++ ) {
if ( byElement && elem ) {
j = 0;
if ( !context && elem.ownerDocument !== document ) {
setDocument( elem );
xml = !documentIsHTML;
}
while ( (matcher = elementMatchers[j++]) ) {
if ( matcher( elem, context || document, xml) ) {
results.push( elem );
break;
}
}
if ( outermost ) {
dirruns = dirrunsUnique;
}
}
// Track unmatched elements for set filters
if ( bySet ) {
// They will have gone through all possible matchers
if ( (elem = !matcher && elem) ) {
matchedCount--;
}
// Lengthen the array for every element, matched or not
if ( seed ) {
unmatched.push( elem );
}
}
}
// `i` is now the count of elements visited above, and adding it to `matchedCount`
// makes the latter nonnegative.
matchedCount += i;
// Apply set filters to unmatched elements
// NOTE: This can be skipped if there are no unmatched elements (i.e., `matchedCount`
// equals `i`), unless we didn't visit _any_ elements in the above loop because we have
// no element matchers and no seed.
// Incrementing an initially-string "0" `i` allows `i` to remain a string only in that
// case, which will result in a "00" `matchedCount` that differs from `i` but is also
// numerically zero.
if ( bySet && i !== matchedCount ) {
j = 0;
while ( (matcher = setMatchers[j++]) ) {
matcher( unmatched, setMatched, context, xml );
}
if ( seed ) {
// Reintegrate element matches to eliminate the need for sorting
if ( matchedCount > 0 ) {
while ( i-- ) {
if ( !(unmatched[i] || setMatched[i]) ) {
setMatched[i] = pop.call( results );
}
}
}
// Discard index placeholder values to get only actual matches
setMatched = condense( setMatched );
}
// Add matches to results
push.apply( results, setMatched );
// Seedless set matches succeeding multiple successful matchers stipulate sorting
if ( outermost && !seed && setMatched.length > 0 &&
( matchedCount + setMatchers.length ) > 1 ) {
Sizzle.uniqueSort( results );
}
}
// Override manipulation of globals by nested matchers
if ( outermost ) {
dirruns = dirrunsUnique;
outermostContext = contextBackup;
}
return unmatched;
};
return bySet ?
markFunction( superMatcher ) :
superMatcher;
}
compile = Sizzle.compile = function( selector, match /* Internal Use Only */ ) {
var i,
setMatchers = [],
elementMatchers = [],
cached = compilerCache[ selector + " " ];
if ( !cached ) {
// Generate a function of recursive functions that can be used to check each element
if ( !match ) {
match = tokenize( selector );
}
i = match.length;
while ( i-- ) {
cached = matcherFromTokens( match[i] );
if ( cached[ expando ] ) {
setMatchers.push( cached );
} else {
elementMatchers.push( cached );
}
}
// Cache the compiled function
cached = compilerCache( selector, matcherFromGroupMatchers( elementMatchers, setMatchers ) );
// Save selector and tokenization
cached.selector = selector;
}
return cached;
};
/**
* A low-level selection function that works with Sizzle's compiled
* selector functions
* @param {String|Function} selector A selector or a pre-compiled
* selector function built with Sizzle.compile
* @param {Element} context
* @param {Array} [results]
* @param {Array} [seed] A set of elements to match against
*/
select = Sizzle.select = function( selector, context, results, seed ) {
var i, tokens, token, type, find,
compiled = typeof selector === "function" && selector,
match = !seed && tokenize( (selector = compiled.selector || selector) );
results = results || [];
// Try to minimize operations if there is only one selector in the list and no seed
// (the latter of which guarantees us context)
if ( match.length === 1 ) {
// Reduce context if the leading compound selector is an ID
tokens = match[0] = match[0].slice( 0 );
if ( tokens.length > 2 && (token = tokens[0]).type === "ID" &&
context.nodeType === 9 && documentIsHTML && Expr.relative[ tokens[1].type ] ) {
context = ( Expr.find["ID"]( token.matches[0].replace(runescape, funescape), context ) || [] )[0];
if ( !context ) {
return results;
// Precompiled matchers will still verify ancestry, so step up a level
} else if ( compiled ) {
context = context.parentNode;
}
selector = selector.slice( tokens.shift().value.length );
}
// Fetch a seed set for right-to-left matching
i = matchExpr["needsContext"].test( selector ) ? 0 : tokens.length;
while ( i-- ) {
token = tokens[i];
// Abort if we hit a combinator
if ( Expr.relative[ (type = token.type) ] ) {
break;
}
if ( (find = Expr.find[ type ]) ) {
// Search, expanding context for leading sibling combinators
if ( (seed = find(
token.matches[0].replace( runescape, funescape ),
rsibling.test( tokens[0].type ) && testContext( context.parentNode ) || context
)) ) {
// If seed is empty or no tokens remain, we can return early
tokens.splice( i, 1 );
selector = seed.length && toSelector( tokens );
if ( !selector ) {
push.apply( results, seed );
return results;
}
break;
}
}
}
}
// Compile and execute a filtering function if one is not provided
// Provide `match` to avoid retokenization if we modified the selector above
( compiled || compile( selector, match ) )(
seed,
context,
!documentIsHTML,
results,
!context || rsibling.test( selector ) && testContext( context.parentNode ) || context
);
return results;
};
// One-time assignments
// Sort stability
support.sortStable = expando.split("").sort( sortOrder ).join("") === expando;
// Support: Chrome 14-35+
// Always assume duplicates if they aren't passed to the comparison function
support.detectDuplicates = !!hasDuplicate;
// Initialize against the default document
setDocument();
// Support: Webkit<537.32 - Safari 6.0.3/Chrome 25 (fixed in Chrome 27)
// Detached nodes confoundingly follow *each other*
support.sortDetached = assert(function( el ) {
// Should return 1, but returns 4 (following)
return el.compareDocumentPosition( document.createElement("fieldset") ) & 1;
});
// Support: IE<8
// Prevent attribute/property "interpolation"
// https://msdn.microsoft.com/en-us/library/ms536429%28VS.85%29.aspx
if ( !assert(function( el ) {
el.innerHTML = "<a href='#'></a>";
return el.firstChild.getAttribute("href") === "#" ;
}) ) {
addHandle( "type|href|height|width", function( elem, name, isXML ) {
if ( !isXML ) {
return elem.getAttribute( name, name.toLowerCase() === "type" ? 1 : 2 );
}
});
}
// Support: IE<9
// Use defaultValue in place of getAttribute("value")
if ( !support.attributes || !assert(function( el ) {
el.innerHTML = "<input/>";
el.firstChild.setAttribute( "value", "" );
return el.firstChild.getAttribute( "value" ) === "";
}) ) {
addHandle( "value", function( elem, name, isXML ) {
if ( !isXML && elem.nodeName.toLowerCase() === "input" ) {
return elem.defaultValue;
}
});
}
// Support: IE<9
// Use getAttributeNode to fetch booleans when getAttribute lies
if ( !assert(function( el ) {
return el.getAttribute("disabled") == null;
}) ) {
addHandle( booleans, function( elem, name, isXML ) {
var val;
if ( !isXML ) {
return elem[ name ] === true ? name.toLowerCase() :
(val = elem.getAttributeNode( name )) && val.specified ?
val.value :
null;
}
});
}
return Sizzle;
})( window );
jQuery.find = Sizzle;
jQuery.expr = Sizzle.selectors;
// Deprecated
jQuery.expr[ ":" ] = jQuery.expr.pseudos;
jQuery.uniqueSort = jQuery.unique = Sizzle.uniqueSort;
jQuery.text = Sizzle.getText;
jQuery.isXMLDoc = Sizzle.isXML;
jQuery.contains = Sizzle.contains;
jQuery.escapeSelector = Sizzle.escape;
var dir = function( elem, dir, until ) {
var matched = [],
truncate = until !== undefined;
while ( ( elem = elem[ dir ] ) && elem.nodeType !== 9 ) {
if ( elem.nodeType === 1 ) {
if ( truncate && jQuery( elem ).is( until ) ) {
break;
}
matched.push( elem );
}
}
return matched;
};
var siblings = function( n, elem ) {
var matched = [];
for ( ; n; n = n.nextSibling ) {
if ( n.nodeType === 1 && n !== elem ) {
matched.push( n );
}
}
return matched;
};
var rneedsContext = jQuery.expr.match.needsContext;
function nodeName( elem, name ) {
return elem.nodeName && elem.nodeName.toLowerCase() === name.toLowerCase();
};
var rsingleTag = ( /^<([a-z][^\/\0>:\x20\t\r\n\f]*)[\x20\t\r\n\f]*\/?>(?:<\/\1>|)$/i );
var risSimple = /^.[^:#\[\.,]*$/;
// Implement the identical functionality for filter and not
function winnow( elements, qualifier, not ) {
if ( jQuery.isFunction( qualifier ) ) {
return jQuery.grep( elements, function( elem, i ) {
return !!qualifier.call( elem, i, elem ) !== not;
} );
}
// Single element
if ( qualifier.nodeType ) {
return jQuery.grep( elements, function( elem ) {
return ( elem === qualifier ) !== not;
} );
}
// Arraylike of elements (jQuery, arguments, Array)
if ( typeof qualifier !== "string" ) {
return jQuery.grep( elements, function( elem ) {
return ( indexOf.call( qualifier, elem ) > -1 ) !== not;
} );
}
// Simple selector that can be filtered directly, removing non-Elements
if ( risSimple.test( qualifier ) ) {
return jQuery.filter( qualifier, elements, not );
}
// Complex selector, compare the two sets, removing non-Elements
qualifier = jQuery.filter( qualifier, elements );
return jQuery.grep( elements, function( elem ) {
return ( indexOf.call( qualifier, elem ) > -1 ) !== not && elem.nodeType === 1;
} );
}
jQuery.filter = function( expr, elems, not ) {
var elem = elems[ 0 ];
if ( not ) {
expr = ":not(" + expr + ")";
}
if ( elems.length === 1 && elem.nodeType === 1 ) {
return jQuery.find.matchesSelector( elem, expr ) ? [ elem ] : [];
}
return jQuery.find.matches( expr, jQuery.grep( elems, function( elem ) {
return elem.nodeType === 1;
} ) );
};
jQuery.fn.extend( {
find: function( selector ) {
var i, ret,
len = this.length,
self = this;
if ( typeof selector !== "string" ) {
return this.pushStack( jQuery( selector ).filter( function() {
for ( i = 0; i < len; i++ ) {
if ( jQuery.contains( self[ i ], this ) ) {
return true;
}
}
} ) );
}
ret = this.pushStack( [] );
for ( i = 0; i < len; i++ ) {
jQuery.find( selector, self[ i ], ret );
}
return len > 1 ? jQuery.uniqueSort( ret ) : ret;
},
filter: function( selector ) {
return this.pushStack( winnow( this, selector || [], false ) );
},
not: function( selector ) {
return this.pushStack( winnow( this, selector || [], true ) );
},
is: function( selector ) {
return !!winnow(
this,
// If this is a positional/relative selector, check membership in the returned set
// so $("p:first").is("p:last") won't return true for a doc with two "p".
typeof selector === "string" && rneedsContext.test( selector ) ?
jQuery( selector ) :
selector || [],
false
).length;
}
} );
// Initialize a jQuery object
// A central reference to the root jQuery(document)
var rootjQuery,
// A simple way to check for HTML strings
// Prioritize #id over <tag> to avoid XSS via location.hash (#9521)
// Strict HTML recognition (#11290: must start with <)
// Shortcut simple #id case for speed
rquickExpr = /^(?:\s*(<[\w\W]+>)[^>]*|#([\w-]+))$/,
init = jQuery.fn.init = function( selector, context, root ) {
var match, elem;
// HANDLE: $(""), $(null), $(undefined), $(false)
if ( !selector ) {
return this;
}
// Method init() accepts an alternate rootjQuery
// so migrate can support jQuery.sub (gh-2101)
root = root || rootjQuery;
// Handle HTML strings
if ( typeof selector === "string" ) {
if ( selector[ 0 ] === "<" &&
selector[ selector.length - 1 ] === ">" &&
selector.length >= 3 ) {
// Assume that strings that start and end with <> are HTML and skip the regex check
match = [ null, selector, null ];
} else {
match = rquickExpr.exec( selector );
}
// Match html or make sure no context is specified for #id
if ( match && ( match[ 1 ] || !context ) ) {
// HANDLE: $(html) -> $(array)
if ( match[ 1 ] ) {
context = context instanceof jQuery ? context[ 0 ] : context;
// Option to run scripts is true for back-compat
// Intentionally let the error be thrown if parseHTML is not present
jQuery.merge( this, jQuery.parseHTML(
match[ 1 ],
context && context.nodeType ? context.ownerDocument || context : document,
true
) );
// HANDLE: $(html, props)
if ( rsingleTag.test( match[ 1 ] ) && jQuery.isPlainObject( context ) ) {
for ( match in context ) {
// Properties of context are called as methods if possible
if ( jQuery.isFunction( this[ match ] ) ) {
this[ match ]( context[ match ] );
// ...and otherwise set as attributes
} else {
this.attr( match, context[ match ] );
}
}
}
return this;
// HANDLE: $(#id)
} else {
elem = document.getElementById( match[ 2 ] );
if ( elem ) {
// Inject the element directly into the jQuery object
this[ 0 ] = elem;
this.length = 1;
}
return this;
}
// HANDLE: $(expr, $(...))
} else if ( !context || context.jquery ) {
return ( context || root ).find( selector );
// HANDLE: $(expr, context)
// (which is just equivalent to: $(context).find(expr)
} else {
return this.constructor( context ).find( selector );
}
// HANDLE: $(DOMElement)
} else if ( selector.nodeType ) {
this[ 0 ] = selector;
this.length = 1;
return this;
// HANDLE: $(function)
// Shortcut for document ready
} else if ( jQuery.isFunction( selector ) ) {
return root.ready !== undefined ?
root.ready( selector ) :
// Execute immediately if ready is not present
selector( jQuery );
}
return jQuery.makeArray( selector, this );
};
// Give the init function the jQuery prototype for later instantiation
init.prototype = jQuery.fn;
// Initialize central reference
rootjQuery = jQuery( document );
var rparentsprev = /^(?:parents|prev(?:Until|All))/,
// Methods guaranteed to produce a unique set when starting from a unique set
guaranteedUnique = {
children: true,
contents: true,
next: true,
prev: true
};
jQuery.fn.extend( {
has: function( target ) {
var targets = jQuery( target, this ),
l = targets.length;
return this.filter( function() {
var i = 0;
for ( ; i < l; i++ ) {
if ( jQuery.contains( this, targets[ i ] ) ) {
return true;
}
}
} );
},
closest: function( selectors, context ) {
var cur,
i = 0,
l = this.length,
matched = [],
targets = typeof selectors !== "string" && jQuery( selectors );
// Positional selectors never match, since there's no _selection_ context
if ( !rneedsContext.test( selectors ) ) {
for ( ; i < l; i++ ) {
for ( cur = this[ i ]; cur && cur !== context; cur = cur.parentNode ) {
// Always skip document fragments
if ( cur.nodeType < 11 && ( targets ?
targets.index( cur ) > -1 :
// Don't pass non-elements to Sizzle
cur.nodeType === 1 &&
jQuery.find.matchesSelector( cur, selectors ) ) ) {
matched.push( cur );
break;
}
}
}
}
return this.pushStack( matched.length > 1 ? jQuery.uniqueSort( matched ) : matched );
},
// Determine the position of an element within the set
index: function( elem ) {
// No argument, return index in parent
if ( !elem ) {
return ( this[ 0 ] && this[ 0 ].parentNode ) ? this.first().prevAll().length : -1;
}
// Index in selector
if ( typeof elem === "string" ) {
return indexOf.call( jQuery( elem ), this[ 0 ] );
}
// Locate the position of the desired element
return indexOf.call( this,
// If it receives a jQuery object, the first element is used
elem.jquery ? elem[ 0 ] : elem
);
},
add: function( selector, context ) {
return this.pushStack(
jQuery.uniqueSort(
jQuery.merge( this.get(), jQuery( selector, context ) )
)
);
},
addBack: function( selector ) {
return this.add( selector == null ?
this.prevObject : this.prevObject.filter( selector )
);
}
} );
function sibling( cur, dir ) {
while ( ( cur = cur[ dir ] ) && cur.nodeType !== 1 ) {}
return cur;
}
jQuery.each( {
parent: function( elem ) {
var parent = elem.parentNode;
return parent && parent.nodeType !== 11 ? parent : null;
},
parents: function( elem ) {
return dir( elem, "parentNode" );
},
parentsUntil: function( elem, i, until ) {
return dir( elem, "parentNode", until );
},
next: function( elem ) {
return sibling( elem, "nextSibling" );
},
prev: function( elem ) {
return sibling( elem, "previousSibling" );
},
nextAll: function( elem ) {
return dir( elem, "nextSibling" );
},
prevAll: function( elem ) {
return dir( elem, "previousSibling" );
},
nextUntil: function( elem, i, until ) {
return dir( elem, "nextSibling", until );
},
prevUntil: function( elem, i, until ) {
return dir( elem, "previousSibling", until );
},
siblings: function( elem ) {
return siblings( ( elem.parentNode || {} ).firstChild, elem );
},
children: function( elem ) {
return siblings( elem.firstChild );
},
contents: function( elem ) {
if ( nodeName( elem, "iframe" ) ) {
return elem.contentDocument;
}
// Support: IE 9 - 11 only, iOS 7 only, Android Browser <=4.3 only
// Treat the template element as a regular one in browsers that
// don't support it.
if ( nodeName( elem, "template" ) ) {
elem = elem.content || elem;
}
return jQuery.merge( [], elem.childNodes );
}
}, function( name, fn ) {
jQuery.fn[ name ] = function( until, selector ) {
var matched = jQuery.map( this, fn, until );
if ( name.slice( -5 ) !== "Until" ) {
selector = until;
}
if ( selector && typeof selector === "string" ) {
matched = jQuery.filter( selector, matched );
}
if ( this.length > 1 ) {
// Remove duplicates
if ( !guaranteedUnique[ name ] ) {
jQuery.uniqueSort( matched );
}
// Reverse order for parents* and prev-derivatives
if ( rparentsprev.test( name ) ) {
matched.reverse();
}
}
return this.pushStack( matched );
};
} );
var rnothtmlwhite = ( /[^\x20\t\r\n\f]+/g );
// Convert String-formatted options into Object-formatted ones
function createOptions( options ) {
var object = {};
jQuery.each( options.match( rnothtmlwhite ) || [], function( _, flag ) {
object[ flag ] = true;
} );
return object;
}
/*
* Create a callback list using the following parameters:
*
* options: an optional list of space-separated options that will change how
* the callback list behaves or a more traditional option object
*
* By default a callback list will act like an event callback list and can be
* "fired" multiple times.
*
* Possible options:
*
* once: will ensure the callback list can only be fired once (like a Deferred)
*
* memory: will keep track of previous values and will call any callback added
* after the list has been fired right away with the latest "memorized"
* values (like a Deferred)
*
* unique: will ensure a callback can only be added once (no duplicate in the list)
*
* stopOnFalse: interrupt callings when a callback returns false
*
*/
jQuery.Callbacks = function( options ) {
// Convert options from String-formatted to Object-formatted if needed
// (we check in cache first)
options = typeof options === "string" ?
createOptions( options ) :
jQuery.extend( {}, options );
var // Flag to know if list is currently firing
firing,
// Last fire value for non-forgettable lists
memory,
// Flag to know if list was already fired
fired,
// Flag to prevent firing
locked,
// Actual callback list
list = [],
// Queue of execution data for repeatable lists
queue = [],
// Index of currently firing callback (modified by add/remove as needed)
firingIndex = -1,
// Fire callbacks
fire = function() {
// Enforce single-firing
locked = locked || options.once;
// Execute callbacks for all pending executions,
// respecting firingIndex overrides and runtime changes
fired = firing = true;
for ( ; queue.length; firingIndex = -1 ) {
memory = queue.shift();
while ( ++firingIndex < list.length ) {
// Run callback and check for early termination
if ( list[ firingIndex ].apply( memory[ 0 ], memory[ 1 ] ) === false &&
options.stopOnFalse ) {
// Jump to end and forget the data so .add doesn't re-fire
firingIndex = list.length;
memory = false;
}
}
}
// Forget the data if we're done with it
if ( !options.memory ) {
memory = false;
}
firing = false;
// Clean up if we're done firing for good
if ( locked ) {
// Keep an empty list if we have data for future add calls
if ( memory ) {
list = [];
// Otherwise, this object is spent
} else {
list = "";
}
}
},
// Actual Callbacks object
self = {
// Add a callback or a collection of callbacks to the list
add: function() {
if ( list ) {
// If we have memory from a past run, we should fire after adding
if ( memory && !firing ) {
firingIndex = list.length - 1;
queue.push( memory );
}
( function add( args ) {
jQuery.each( args, function( _, arg ) {
if ( jQuery.isFunction( arg ) ) {
if ( !options.unique || !self.has( arg ) ) {
list.push( arg );
}
} else if ( arg && arg.length && jQuery.type( arg ) !== "string" ) {
// Inspect recursively
add( arg );
}
} );
} )( arguments );
if ( memory && !firing ) {
fire();
}
}
return this;
},
// Remove a callback from the list
remove: function() {
jQuery.each( arguments, function( _, arg ) {
var index;
while ( ( index = jQuery.inArray( arg, list, index ) ) > -1 ) {
list.splice( index, 1 );
// Handle firing indexes
if ( index <= firingIndex ) {
firingIndex--;
}
}
} );
return this;
},
// Check if a given callback is in the list.
// If no argument is given, return whether or not list has callbacks attached.
has: function( fn ) {
return fn ?
jQuery.inArray( fn, list ) > -1 :
list.length > 0;
},
// Remove all callbacks from the list
empty: function() {
if ( list ) {
list = [];
}
return this;
},
// Disable .fire and .add
// Abort any current/pending executions
// Clear all callbacks and values
disable: function() {
locked = queue = [];
list = memory = "";
return this;
},
disabled: function() {
return !list;
},
// Disable .fire
// Also disable .add unless we have memory (since it would have no effect)
// Abort any pending executions
lock: function() {
locked = queue = [];
if ( !memory && !firing ) {
list = memory = "";
}
return this;
},
locked: function() {
return !!locked;
},
// Call all callbacks with the given context and arguments
fireWith: function( context, args ) {
if ( !locked ) {
args = args || [];
args = [ context, args.slice ? args.slice() : args ];
queue.push( args );
if ( !firing ) {
fire();
}
}
return this;
},
// Call all the callbacks with the given arguments
fire: function() {
self.fireWith( this, arguments );
return this;
},
// To know if the callbacks have already been called at least once
fired: function() {
return !!fired;
}
};
return self;
};
function Identity( v ) {
return v;
}
function Thrower( ex ) {
throw ex;
}
function adoptValue( value, resolve, reject, noValue ) {
var method;
try {
// Check for promise aspect first to privilege synchronous behavior
if ( value && jQuery.isFunction( ( method = value.promise ) ) ) {
method.call( value ).done( resolve ).fail( reject );
// Other thenables
} else if ( value && jQuery.isFunction( ( method = value.then ) ) ) {
method.call( value, resolve, reject );
// Other non-thenables
} else {
// Control `resolve` arguments by letting Array#slice cast boolean `noValue` to integer:
// * false: [ value ].slice( 0 ) => resolve( value )
// * true: [ value ].slice( 1 ) => resolve()
resolve.apply( undefined, [ value ].slice( noValue ) );
}
// For Promises/A+, convert exceptions into rejections
// Since jQuery.when doesn't unwrap thenables, we can skip the extra checks appearing in
// Deferred#then to conditionally suppress rejection.
} catch ( value ) {
// Support: Android 4.0 only
// Strict mode functions invoked without .call/.apply get global-object context
reject.apply( undefined, [ value ] );
}
}
jQuery.extend( {
Deferred: function( func ) {
var tuples = [
// action, add listener, callbacks,
// ... .then handlers, argument index, [final state]
[ "notify", "progress", jQuery.Callbacks( "memory" ),
jQuery.Callbacks( "memory" ), 2 ],
[ "resolve", "done", jQuery.Callbacks( "once memory" ),
jQuery.Callbacks( "once memory" ), 0, "resolved" ],
[ "reject", "fail", jQuery.Callbacks( "once memory" ),
jQuery.Callbacks( "once memory" ), 1, "rejected" ]
],
state = "pending",
promise = {
state: function() {
return state;
},
always: function() {
deferred.done( arguments ).fail( arguments );
return this;
},
"catch": function( fn ) {
return promise.then( null, fn );
},
// Keep pipe for back-compat
pipe: function( /* fnDone, fnFail, fnProgress */ ) {
var fns = arguments;
return jQuery.Deferred( function( newDefer ) {
jQuery.each( tuples, function( i, tuple ) {
// Map tuples (progress, done, fail) to arguments (done, fail, progress)
var fn = jQuery.isFunction( fns[ tuple[ 4 ] ] ) && fns[ tuple[ 4 ] ];
// deferred.progress(function() { bind to newDefer or newDefer.notify })
// deferred.done(function() { bind to newDefer or newDefer.resolve })
// deferred.fail(function() { bind to newDefer or newDefer.reject })
deferred[ tuple[ 1 ] ]( function() {
var returned = fn && fn.apply( this, arguments );
if ( returned && jQuery.isFunction( returned.promise ) ) {
returned.promise()
.progress( newDefer.notify )
.done( newDefer.resolve )
.fail( newDefer.reject );
} else {
newDefer[ tuple[ 0 ] + "With" ](
this,
fn ? [ returned ] : arguments
);
}
} );
} );
fns = null;
} ).promise();
},
then: function( onFulfilled, onRejected, onProgress ) {
var maxDepth = 0;
function resolve( depth, deferred, handler, special ) {
return function() {
var that = this,
args = arguments,
mightThrow = function() {
var returned, then;
// Support: Promises/A+ section 2.3.3.3.3
// https://promisesaplus.com/#point-59
// Ignore double-resolution attempts
if ( depth < maxDepth ) {
return;
}
returned = handler.apply( that, args );
// Support: Promises/A+ section 2.3.1
// https://promisesaplus.com/#point-48
if ( returned === deferred.promise() ) {
throw new TypeError( "Thenable self-resolution" );
}
// Support: Promises/A+ sections 2.3.3.1, 3.5
// https://promisesaplus.com/#point-54
// https://promisesaplus.com/#point-75
// Retrieve `then` only once
then = returned &&
// Support: Promises/A+ section 2.3.4
// https://promisesaplus.com/#point-64
// Only check objects and functions for thenability
( typeof returned === "object" ||
typeof returned === "function" ) &&
returned.then;
// Handle a returned thenable
if ( jQuery.isFunction( then ) ) {
// Special processors (notify) just wait for resolution
if ( special ) {
then.call(
returned,
resolve( maxDepth, deferred, Identity, special ),
resolve( maxDepth, deferred, Thrower, special )
);
// Normal processors (resolve) also hook into progress
} else {
// ...and disregard older resolution values
maxDepth++;
then.call(
returned,
resolve( maxDepth, deferred, Identity, special ),
resolve( maxDepth, deferred, Thrower, special ),
resolve( maxDepth, deferred, Identity,
deferred.notifyWith )
);
}
// Handle all other returned values
} else {
// Only substitute handlers pass on context
// and multiple values (non-spec behavior)
if ( handler !== Identity ) {
that = undefined;
args = [ returned ];
}
// Process the value(s)
// Default process is resolve
( special || deferred.resolveWith )( that, args );
}
},
// Only normal processors (resolve) catch and reject exceptions
process = special ?
mightThrow :
function() {
try {
mightThrow();
} catch ( e ) {
if ( jQuery.Deferred.exceptionHook ) {
jQuery.Deferred.exceptionHook( e,
process.stackTrace );
}
// Support: Promises/A+ section 2.3.3.3.4.1
// https://promisesaplus.com/#point-61
// Ignore post-resolution exceptions
if ( depth + 1 >= maxDepth ) {
// Only substitute handlers pass on context
// and multiple values (non-spec behavior)
if ( handler !== Thrower ) {
that = undefined;
args = [ e ];
}
deferred.rejectWith( that, args );
}
}
};
// Support: Promises/A+ section 2.3.3.3.1
// https://promisesaplus.com/#point-57
// Re-resolve promises immediately to dodge false rejection from
// subsequent errors
if ( depth ) {
process();
} else {
// Call an optional hook to record the stack, in case of exception
// since it's otherwise lost when execution goes async
if ( jQuery.Deferred.getStackHook ) {
process.stackTrace = jQuery.Deferred.getStackHook();
}
window.setTimeout( process );
}
};
}
return jQuery.Deferred( function( newDefer ) {
// progress_handlers.add( ... )
tuples[ 0 ][ 3 ].add(
resolve(
0,
newDefer,
jQuery.isFunction( onProgress ) ?
onProgress :
Identity,
newDefer.notifyWith
)
);
// fulfilled_handlers.add( ... )
tuples[ 1 ][ 3 ].add(
resolve(
0,
newDefer,
jQuery.isFunction( onFulfilled ) ?
onFulfilled :
Identity
)
);
// rejected_handlers.add( ... )
tuples[ 2 ][ 3 ].add(
resolve(
0,
newDefer,
jQuery.isFunction( onRejected ) ?
onRejected :
Thrower
)
);
} ).promise();
},
// Get a promise for this deferred
// If obj is provided, the promise aspect is added to the object
promise: function( obj ) {
return obj != null ? jQuery.extend( obj, promise ) : promise;
}
},
deferred = {};
// Add list-specific methods
jQuery.each( tuples, function( i, tuple ) {
var list = tuple[ 2 ],
stateString = tuple[ 5 ];
// promise.progress = list.add
// promise.done = list.add
// promise.fail = list.add
promise[ tuple[ 1 ] ] = list.add;
// Handle state
if ( stateString ) {
list.add(
function() {
// state = "resolved" (i.e., fulfilled)
// state = "rejected"
state = stateString;
},
// rejected_callbacks.disable
// fulfilled_callbacks.disable
tuples[ 3 - i ][ 2 ].disable,
// progress_callbacks.lock
tuples[ 0 ][ 2 ].lock
);
}
// progress_handlers.fire
// fulfilled_handlers.fire
// rejected_handlers.fire
list.add( tuple[ 3 ].fire );
// deferred.notify = function() { deferred.notifyWith(...) }
// deferred.resolve = function() { deferred.resolveWith(...) }
// deferred.reject = function() { deferred.rejectWith(...) }
deferred[ tuple[ 0 ] ] = function() {
deferred[ tuple[ 0 ] + "With" ]( this === deferred ? undefined : this, arguments );
return this;
};
// deferred.notifyWith = list.fireWith
// deferred.resolveWith = list.fireWith
// deferred.rejectWith = list.fireWith
deferred[ tuple[ 0 ] + "With" ] = list.fireWith;
} );
// Make the deferred a promise
promise.promise( deferred );
// Call given func if any
if ( func ) {
func.call( deferred, deferred );
}
// All done!
return deferred;
},
// Deferred helper
when: function( singleValue ) {
var
// count of uncompleted subordinates
remaining = arguments.length,
// count of unprocessed arguments
i = remaining,
// subordinate fulfillment data
resolveContexts = Array( i ),
resolveValues = slice.call( arguments ),
// the master Deferred
master = jQuery.Deferred(),
// subordinate callback factory
updateFunc = function( i ) {
return function( value ) {
resolveContexts[ i ] = this;
resolveValues[ i ] = arguments.length > 1 ? slice.call( arguments ) : value;
if ( !( --remaining ) ) {
master.resolveWith( resolveContexts, resolveValues );
}
};
};
// Single- and empty arguments are adopted like Promise.resolve
if ( remaining <= 1 ) {
adoptValue( singleValue, master.done( updateFunc( i ) ).resolve, master.reject,
!remaining );
// Use .then() to unwrap secondary thenables (cf. gh-3000)
if ( master.state() === "pending" ||
jQuery.isFunction( resolveValues[ i ] && resolveValues[ i ].then ) ) {
return master.then();
}
}
// Multiple arguments are aggregated like Promise.all array elements
while ( i-- ) {
adoptValue( resolveValues[ i ], updateFunc( i ), master.reject );
}
return master.promise();
}
} );
// These usually indicate a programmer mistake during development,
// warn about them ASAP rather than swallowing them by default.
var rerrorNames = /^(Eval|Internal|Range|Reference|Syntax|Type|URI)Error$/;
jQuery.Deferred.exceptionHook = function( error, stack ) {
// Support: IE 8 - 9 only
// Console exists when dev tools are open, which can happen at any time
if ( window.console && window.console.warn && error && rerrorNames.test( error.name ) ) {
window.console.warn( "jQuery.Deferred exception: " + error.message, error.stack, stack );
}
};
jQuery.readyException = function( error ) {
window.setTimeout( function() {
throw error;
} );
};
// The deferred used on DOM ready
var readyList = jQuery.Deferred();
jQuery.fn.ready = function( fn ) {
readyList
.then( fn )
// Wrap jQuery.readyException in a function so that the lookup
// happens at the time of error handling instead of callback
// registration.
.catch( function( error ) {
jQuery.readyException( error );
} );
return this;
};
jQuery.extend( {
// Is the DOM ready to be used? Set to true once it occurs.
isReady: false,
// A counter to track how many items to wait for before
// the ready event fires. See #6781
readyWait: 1,
// Handle when the DOM is ready
ready: function( wait ) {
// Abort if there are pending holds or we're already ready
if ( wait === true ? --jQuery.readyWait : jQuery.isReady ) {
return;
}
// Remember that the DOM is ready
jQuery.isReady = true;
// If a normal DOM Ready event fired, decrement, and wait if need be
if ( wait !== true && --jQuery.readyWait > 0 ) {
return;
}
// If there are functions bound, to execute
readyList.resolveWith( document, [ jQuery ] );
}
} );
jQuery.ready.then = readyList.then;
// The ready event handler and self cleanup method
function completed() {
document.removeEventListener( "DOMContentLoaded", completed );
window.removeEventListener( "load", completed );
jQuery.ready();
}
// Catch cases where $(document).ready() is called
// after the browser event has already occurred.
// Support: IE <=9 - 10 only
// Older IE sometimes signals "interactive" too soon
if ( document.readyState === "complete" ||
( document.readyState !== "loading" && !document.documentElement.doScroll ) ) {
// Handle it asynchronously to allow scripts the opportunity to delay ready
window.setTimeout( jQuery.ready );
} else {
// Use the handy event callback
document.addEventListener( "DOMContentLoaded", completed );
// A fallback to window.onload, that will always work
window.addEventListener( "load", completed );
}
// Multifunctional method to get and set values of a collection
// The value/s can optionally be executed if it's a function
var access = function( elems, fn, key, value, chainable, emptyGet, raw ) {
var i = 0,
len = elems.length,
bulk = key == null;
// Sets many values
if ( jQuery.type( key ) === "object" ) {
chainable = true;
for ( i in key ) {
access( elems, fn, i, key[ i ], true, emptyGet, raw );
}
// Sets one value
} else if ( value !== undefined ) {
chainable = true;
if ( !jQuery.isFunction( value ) ) {
raw = true;
}
if ( bulk ) {
// Bulk operations run against the entire set
if ( raw ) {
fn.call( elems, value );
fn = null;
// ...except when executing function values
} else {
bulk = fn;
fn = function( elem, key, value ) {
return bulk.call( jQuery( elem ), value );
};
}
}
if ( fn ) {
for ( ; i < len; i++ ) {
fn(
elems[ i ], key, raw ?
value :
value.call( elems[ i ], i, fn( elems[ i ], key ) )
);
}
}
}
if ( chainable ) {
return elems;
}
// Gets
if ( bulk ) {
return fn.call( elems );
}
return len ? fn( elems[ 0 ], key ) : emptyGet;
};
var acceptData = function( owner ) {
// Accepts only:
// - Node
// - Node.ELEMENT_NODE
// - Node.DOCUMENT_NODE
// - Object
// - Any
return owner.nodeType === 1 || owner.nodeType === 9 || !( +owner.nodeType );
};
function Data() {
this.expando = jQuery.expando + Data.uid++;
}
Data.uid = 1;
Data.prototype = {
cache: function( owner ) {
// Check if the owner object already has a cache
var value = owner[ this.expando ];
// If not, create one
if ( !value ) {
value = {};
// We can accept data for non-element nodes in modern browsers,
// but we should not, see #8335.
// Always return an empty object.
if ( acceptData( owner ) ) {
// If it is a node unlikely to be stringify-ed or looped over
// use plain assignment
if ( owner.nodeType ) {
owner[ this.expando ] = value;
// Otherwise secure it in a non-enumerable property
// configurable must be true to allow the property to be
// deleted when data is removed
} else {
Object.defineProperty( owner, this.expando, {
value: value,
configurable: true
} );
}
}
}
return value;
},
set: function( owner, data, value ) {
var prop,
cache = this.cache( owner );
// Handle: [ owner, key, value ] args
// Always use camelCase key (gh-2257)
if ( typeof data === "string" ) {
cache[ jQuery.camelCase( data ) ] = value;
// Handle: [ owner, { properties } ] args
} else {
// Copy the properties one-by-one to the cache object
for ( prop in data ) {
cache[ jQuery.camelCase( prop ) ] = data[ prop ];
}
}
return cache;
},
get: function( owner, key ) {
return key === undefined ?
this.cache( owner ) :
// Always use camelCase key (gh-2257)
owner[ this.expando ] && owner[ this.expando ][ jQuery.camelCase( key ) ];
},
access: function( owner, key, value ) {
// In cases where either:
//
// 1. No key was specified
// 2. A string key was specified, but no value provided
//
// Take the "read" path and allow the get method to determine
// which value to return, respectively either:
//
// 1. The entire cache object
// 2. The data stored at the key
//
if ( key === undefined ||
( ( key && typeof key === "string" ) && value === undefined ) ) {
return this.get( owner, key );
}
// When the key is not a string, or both a key and value
// are specified, set or extend (existing objects) with either:
//
// 1. An object of properties
// 2. A key and value
//
this.set( owner, key, value );
// Since the "set" path can have two possible entry points
// return the expected data based on which path was taken[*]
return value !== undefined ? value : key;
},
remove: function( owner, key ) {
var i,
cache = owner[ this.expando ];
if ( cache === undefined ) {
return;
}
if ( key !== undefined ) {
// Support array or space separated string of keys
if ( Array.isArray( key ) ) {
// If key is an array of keys...
// We always set camelCase keys, so remove that.
key = key.map( jQuery.camelCase );
} else {
key = jQuery.camelCase( key );
// If a key with the spaces exists, use it.
// Otherwise, create an array by matching non-whitespace
key = key in cache ?
[ key ] :
( key.match( rnothtmlwhite ) || [] );
}
i = key.length;
while ( i-- ) {
delete cache[ key[ i ] ];
}
}
// Remove the expando if there's no more data
if ( key === undefined || jQuery.isEmptyObject( cache ) ) {
// Support: Chrome <=35 - 45
// Webkit & Blink performance suffers when deleting properties
// from DOM nodes, so set to undefined instead
// https://bugs.chromium.org/p/chromium/issues/detail?id=378607 (bug restricted)
if ( owner.nodeType ) {
owner[ this.expando ] = undefined;
} else {
delete owner[ this.expando ];
}
}
},
hasData: function( owner ) {
var cache = owner[ this.expando ];
return cache !== undefined && !jQuery.isEmptyObject( cache );
}
};
var dataPriv = new Data();
var dataUser = new Data();
// Implementation Summary
//
// 1. Enforce API surface and semantic compatibility with 1.9.x branch
// 2. Improve the module's maintainability by reducing the storage
// paths to a single mechanism.
// 3. Use the same single mechanism to support "private" and "user" data.
// 4. _Never_ expose "private" data to user code (TODO: Drop _data, _removeData)
// 5. Avoid exposing implementation details on user objects (eg. expando properties)
// 6. Provide a clear path for implementation upgrade to WeakMap in 2014
var rbrace = /^(?:\{[\w\W]*\}|\[[\w\W]*\])$/,
rmultiDash = /[A-Z]/g;
function getData( data ) {
if ( data === "true" ) {
return true;
}
if ( data === "false" ) {
return false;
}
if ( data === "null" ) {
return null;
}
// Only convert to a number if it doesn't change the string
if ( data === +data + "" ) {
return +data;
}
if ( rbrace.test( data ) ) {
return JSON.parse( data );
}
return data;
}
function dataAttr( elem, key, data ) {
var name;
// If nothing was found internally, try to fetch any
// data from the HTML5 data-* attribute
if ( data === undefined && elem.nodeType === 1 ) {
name = "data-" + key.replace( rmultiDash, "-$&" ).toLowerCase();
data = elem.getAttribute( name );
if ( typeof data === "string" ) {
try {
data = getData( data );
} catch ( e ) {}
// Make sure we set the data so it isn't changed later
dataUser.set( elem, key, data );
} else {
data = undefined;
}
}
return data;
}
jQuery.extend( {
hasData: function( elem ) {
return dataUser.hasData( elem ) || dataPriv.hasData( elem );
},
data: function( elem, name, data ) {
return dataUser.access( elem, name, data );
},
removeData: function( elem, name ) {
dataUser.remove( elem, name );
},
// TODO: Now that all calls to _data and _removeData have been replaced
// with direct calls to dataPriv methods, these can be deprecated.
_data: function( elem, name, data ) {
return dataPriv.access( elem, name, data );
},
_removeData: function( elem, name ) {
dataPriv.remove( elem, name );
}
} );
jQuery.fn.extend( {
data: function( key, value ) {
var i, name, data,
elem = this[ 0 ],
attrs = elem && elem.attributes;
// Gets all values
if ( key === undefined ) {
if ( this.length ) {
data = dataUser.get( elem );
if ( elem.nodeType === 1 && !dataPriv.get( elem, "hasDataAttrs" ) ) {
i = attrs.length;
while ( i-- ) {
// Support: IE 11 only
// The attrs elements can be null (#14894)
if ( attrs[ i ] ) {
name = attrs[ i ].name;
if ( name.indexOf( "data-" ) === 0 ) {
name = jQuery.camelCase( name.slice( 5 ) );
dataAttr( elem, name, data[ name ] );
}
}
}
dataPriv.set( elem, "hasDataAttrs", true );
}
}
return data;
}
// Sets multiple values
if ( typeof key === "object" ) {
return this.each( function() {
dataUser.set( this, key );
} );
}
return access( this, function( value ) {
var data;
// The calling jQuery object (element matches) is not empty
// (and therefore has an element appears at this[ 0 ]) and the
// `value` parameter was not undefined. An empty jQuery object
// will result in `undefined` for elem = this[ 0 ] which will
// throw an exception if an attempt to read a data cache is made.
if ( elem && value === undefined ) {
// Attempt to get data from the cache
// The key will always be camelCased in Data
data = dataUser.get( elem, key );
if ( data !== undefined ) {
return data;
}
// Attempt to "discover" the data in
// HTML5 custom data-* attrs
data = dataAttr( elem, key );
if ( data !== undefined ) {
return data;
}
// We tried really hard, but the data doesn't exist.
return;
}
// Set the data...
this.each( function() {
// We always store the camelCased key
dataUser.set( this, key, value );
} );
}, null, value, arguments.length > 1, null, true );
},
removeData: function( key ) {
return this.each( function() {
dataUser.remove( this, key );
} );
}
} );
jQuery.extend( {
queue: function( elem, type, data ) {
var queue;
if ( elem ) {
type = ( type || "fx" ) + "queue";
queue = dataPriv.get( elem, type );
// Speed up dequeue by getting out quickly if this is just a lookup
if ( data ) {
if ( !queue || Array.isArray( data ) ) {
queue = dataPriv.access( elem, type, jQuery.makeArray( data ) );
} else {
queue.push( data );
}
}
return queue || [];
}
},
dequeue: function( elem, type ) {
type = type || "fx";
var queue = jQuery.queue( elem, type ),
startLength = queue.length,
fn = queue.shift(),
hooks = jQuery._queueHooks( elem, type ),
next = function() {
jQuery.dequeue( elem, type );
};
// If the fx queue is dequeued, always remove the progress sentinel
if ( fn === "inprogress" ) {
fn = queue.shift();
startLength--;
}
if ( fn ) {
// Add a progress sentinel to prevent the fx queue from being
// automatically dequeued
if ( type === "fx" ) {
queue.unshift( "inprogress" );
}
// Clear up the last queue stop function
delete hooks.stop;
fn.call( elem, next, hooks );
}
if ( !startLength && hooks ) {
hooks.empty.fire();
}
},
// Not public - generate a queueHooks object, or return the current one
_queueHooks: function( elem, type ) {
var key = type + "queueHooks";
return dataPriv.get( elem, key ) || dataPriv.access( elem, key, {
empty: jQuery.Callbacks( "once memory" ).add( function() {
dataPriv.remove( elem, [ type + "queue", key ] );
} )
} );
}
} );
jQuery.fn.extend( {
queue: function( type, data ) {
var setter = 2;
if ( typeof type !== "string" ) {
data = type;
type = "fx";
setter--;
}
if ( arguments.length < setter ) {
return jQuery.queue( this[ 0 ], type );
}
return data === undefined ?
this :
this.each( function() {
var queue = jQuery.queue( this, type, data );
// Ensure a hooks for this queue
jQuery._queueHooks( this, type );
if ( type === "fx" && queue[ 0 ] !== "inprogress" ) {
jQuery.dequeue( this, type );
}
} );
},
dequeue: function( type ) {
return this.each( function() {
jQuery.dequeue( this, type );
} );
},
clearQueue: function( type ) {
return this.queue( type || "fx", [] );
},
// Get a promise resolved when queues of a certain type
// are emptied (fx is the type by default)
promise: function( type, obj ) {
var tmp,
count = 1,
defer = jQuery.Deferred(),
elements = this,
i = this.length,
resolve = function() {
if ( !( --count ) ) {
defer.resolveWith( elements, [ elements ] );
}
};
if ( typeof type !== "string" ) {
obj = type;
type = undefined;
}
type = type || "fx";
while ( i-- ) {
tmp = dataPriv.get( elements[ i ], type + "queueHooks" );
if ( tmp && tmp.empty ) {
count++;
tmp.empty.add( resolve );
}
}
resolve();
return defer.promise( obj );
}
} );
var pnum = ( /[+-]?(?:\d*\.|)\d+(?:[eE][+-]?\d+|)/ ).source;
var rcssNum = new RegExp( "^(?:([+-])=|)(" + pnum + ")([a-z%]*)$", "i" );
var cssExpand = [ "Top", "Right", "Bottom", "Left" ];
var isHiddenWithinTree = function( elem, el ) {
// isHiddenWithinTree might be called from jQuery#filter function;
// in that case, element will be second argument
elem = el || elem;
// Inline style trumps all
return elem.style.display === "none" ||
elem.style.display === "" &&
// Otherwise, check computed style
// Support: Firefox <=43 - 45
// Disconnected elements can have computed display: none, so first confirm that elem is
// in the document.
jQuery.contains( elem.ownerDocument, elem ) &&
jQuery.css( elem, "display" ) === "none";
};
var swap = function( elem, options, callback, args ) {
var ret, name,
old = {};
// Remember the old values, and insert the new ones
for ( name in options ) {
old[ name ] = elem.style[ name ];
elem.style[ name ] = options[ name ];
}
ret = callback.apply( elem, args || [] );
// Revert the old values
for ( name in options ) {
elem.style[ name ] = old[ name ];
}
return ret;
};
function adjustCSS( elem, prop, valueParts, tween ) {
var adjusted,
scale = 1,
maxIterations = 20,
currentValue = tween ?
function() {
return tween.cur();
} :
function() {
return jQuery.css( elem, prop, "" );
},
initial = currentValue(),
unit = valueParts && valueParts[ 3 ] || ( jQuery.cssNumber[ prop ] ? "" : "px" ),
// Starting value computation is required for potential unit mismatches
initialInUnit = ( jQuery.cssNumber[ prop ] || unit !== "px" && +initial ) &&
rcssNum.exec( jQuery.css( elem, prop ) );
if ( initialInUnit && initialInUnit[ 3 ] !== unit ) {
// Trust units reported by jQuery.css
unit = unit || initialInUnit[ 3 ];
// Make sure we update the tween properties later on
valueParts = valueParts || [];
// Iteratively approximate from a nonzero starting point
initialInUnit = +initial || 1;
do {
// If previous iteration zeroed out, double until we get *something*.
// Use string for doubling so we don't accidentally see scale as unchanged below
scale = scale || ".5";
// Adjust and apply
initialInUnit = initialInUnit / scale;
jQuery.style( elem, prop, initialInUnit + unit );
// Update scale, tolerating zero or NaN from tween.cur()
// Break the loop if scale is unchanged or perfect, or if we've just had enough.
} while (
scale !== ( scale = currentValue() / initial ) && scale !== 1 && --maxIterations
);
}
if ( valueParts ) {
initialInUnit = +initialInUnit || +initial || 0;
// Apply relative offset (+=/-=) if specified
adjusted = valueParts[ 1 ] ?
initialInUnit + ( valueParts[ 1 ] + 1 ) * valueParts[ 2 ] :
+valueParts[ 2 ];
if ( tween ) {
tween.unit = unit;
tween.start = initialInUnit;
tween.end = adjusted;
}
}
return adjusted;
}
var defaultDisplayMap = {};
function getDefaultDisplay( elem ) {
var temp,
doc = elem.ownerDocument,
nodeName = elem.nodeName,
display = defaultDisplayMap[ nodeName ];
if ( display ) {
return display;
}
temp = doc.body.appendChild( doc.createElement( nodeName ) );
display = jQuery.css( temp, "display" );
temp.parentNode.removeChild( temp );
if ( display === "none" ) {
display = "block";
}
defaultDisplayMap[ nodeName ] = display;
return display;
}
function showHide( elements, show ) {
var display, elem,
values = [],
index = 0,
length = elements.length;
// Determine new display value for elements that need to change
for ( ; index < length; index++ ) {
elem = elements[ index ];
if ( !elem.style ) {
continue;
}
display = elem.style.display;
if ( show ) {
// Since we force visibility upon cascade-hidden elements, an immediate (and slow)
// check is required in this first loop unless we have a nonempty display value (either
// inline or about-to-be-restored)
if ( display === "none" ) {
values[ index ] = dataPriv.get( elem, "display" ) || null;
if ( !values[ index ] ) {
elem.style.display = "";
}
}
if ( elem.style.display === "" && isHiddenWithinTree( elem ) ) {
values[ index ] = getDefaultDisplay( elem );
}
} else {
if ( display !== "none" ) {
values[ index ] = "none";
// Remember what we're overwriting
dataPriv.set( elem, "display", display );
}
}
}
// Set the display of the elements in a second loop to avoid constant reflow
for ( index = 0; index < length; index++ ) {
if ( values[ index ] != null ) {
elements[ index ].style.display = values[ index ];
}
}
return elements;
}
jQuery.fn.extend( {
show: function() {
return showHide( this, true );
},
hide: function() {
return showHide( this );
},
toggle: function( state ) {
if ( typeof state === "boolean" ) {
return state ? this.show() : this.hide();
}
return this.each( function() {
if ( isHiddenWithinTree( this ) ) {
jQuery( this ).show();
} else {
jQuery( this ).hide();
}
} );
}
} );
var rcheckableType = ( /^(?:checkbox|radio)$/i );
var rtagName = ( /<([a-z][^\/\0>\x20\t\r\n\f]+)/i );
var rscriptType = ( /^$|\/(?:java|ecma)script/i );
// We have to close these tags to support XHTML (#13200)
var wrapMap = {
// Support: IE <=9 only
option: [ 1, "<select multiple='multiple'>", "</select>" ],
// XHTML parsers do not magically insert elements in the
// same way that tag soup parsers do. So we cannot shorten
// this by omitting <tbody> or other required elements.
thead: [ 1, "<table>", "</table>" ],
col: [ 2, "<table><colgroup>", "</colgroup></table>" ],
tr: [ 2, "<table><tbody>", "</tbody></table>" ],
td: [ 3, "<table><tbody><tr>", "</tr></tbody></table>" ],
_default: [ 0, "", "" ]
};
// Support: IE <=9 only
wrapMap.optgroup = wrapMap.option;
wrapMap.tbody = wrapMap.tfoot = wrapMap.colgroup = wrapMap.caption = wrapMap.thead;
wrapMap.th = wrapMap.td;
function getAll( context, tag ) {
// Support: IE <=9 - 11 only
// Use typeof to avoid zero-argument method invocation on host objects (#15151)
var ret;
if ( typeof context.getElementsByTagName !== "undefined" ) {
ret = context.getElementsByTagName( tag || "*" );
} else if ( typeof context.querySelectorAll !== "undefined" ) {
ret = context.querySelectorAll( tag || "*" );
} else {
ret = [];
}
if ( tag === undefined || tag && nodeName( context, tag ) ) {
return jQuery.merge( [ context ], ret );
}
return ret;
}
// Mark scripts as having already been evaluated
function setGlobalEval( elems, refElements ) {
var i = 0,
l = elems.length;
for ( ; i < l; i++ ) {
dataPriv.set(
elems[ i ],
"globalEval",
!refElements || dataPriv.get( refElements[ i ], "globalEval" )
);
}
}
var rhtml = /<|&#?\w+;/;
function buildFragment( elems, context, scripts, selection, ignored ) {
var elem, tmp, tag, wrap, contains, j,
fragment = context.createDocumentFragment(),
nodes = [],
i = 0,
l = elems.length;
for ( ; i < l; i++ ) {
elem = elems[ i ];
if ( elem || elem === 0 ) {
// Add nodes directly
if ( jQuery.type( elem ) === "object" ) {
// Support: Android <=4.0 only, PhantomJS 1 only
// push.apply(_, arraylike) throws on ancient WebKit
jQuery.merge( nodes, elem.nodeType ? [ elem ] : elem );
// Convert non-html into a text node
} else if ( !rhtml.test( elem ) ) {
nodes.push( context.createTextNode( elem ) );
// Convert html into DOM nodes
} else {
tmp = tmp || fragment.appendChild( context.createElement( "div" ) );
// Deserialize a standard representation
tag = ( rtagName.exec( elem ) || [ "", "" ] )[ 1 ].toLowerCase();
wrap = wrapMap[ tag ] || wrapMap._default;
tmp.innerHTML = wrap[ 1 ] + jQuery.htmlPrefilter( elem ) + wrap[ 2 ];
// Descend through wrappers to the right content
j = wrap[ 0 ];
while ( j-- ) {
tmp = tmp.lastChild;
}
// Support: Android <=4.0 only, PhantomJS 1 only
// push.apply(_, arraylike) throws on ancient WebKit
jQuery.merge( nodes, tmp.childNodes );
// Remember the top-level container
tmp = fragment.firstChild;
// Ensure the created nodes are orphaned (#12392)
tmp.textContent = "";
}
}
}
// Remove wrapper from fragment
fragment.textContent = "";
i = 0;
while ( ( elem = nodes[ i++ ] ) ) {
// Skip elements already in the context collection (trac-4087)
if ( selection && jQuery.inArray( elem, selection ) > -1 ) {
if ( ignored ) {
ignored.push( elem );
}
continue;
}
contains = jQuery.contains( elem.ownerDocument, elem );
// Append to fragment
tmp = getAll( fragment.appendChild( elem ), "script" );
// Preserve script evaluation history
if ( contains ) {
setGlobalEval( tmp );
}
// Capture executables
if ( scripts ) {
j = 0;
while ( ( elem = tmp[ j++ ] ) ) {
if ( rscriptType.test( elem.type || "" ) ) {
scripts.push( elem );
}
}
}
}
return fragment;
}
( function() {
var fragment = document.createDocumentFragment(),
div = fragment.appendChild( document.createElement( "div" ) ),
input = document.createElement( "input" );
// Support: Android 4.0 - 4.3 only
// Check state lost if the name is set (#11217)
// Support: Windows Web Apps (WWA)
// `name` and `type` must use .setAttribute for WWA (#14901)
input.setAttribute( "type", "radio" );
input.setAttribute( "checked", "checked" );
input.setAttribute( "name", "t" );
div.appendChild( input );
// Support: Android <=4.1 only
// Older WebKit doesn't clone checked state correctly in fragments
support.checkClone = div.cloneNode( true ).cloneNode( true ).lastChild.checked;
// Support: IE <=11 only
// Make sure textarea (and checkbox) defaultValue is properly cloned
div.innerHTML = "<textarea>x</textarea>";
support.noCloneChecked = !!div.cloneNode( true ).lastChild.defaultValue;
} )();
var documentElement = document.documentElement;
var
rkeyEvent = /^key/,
rmouseEvent = /^(?:mouse|pointer|contextmenu|drag|drop)|click/,
rtypenamespace = /^([^.]*)(?:\.(.+)|)/;
function returnTrue() {
return true;
}
function returnFalse() {
return false;
}
// Support: IE <=9 only
// See #13393 for more info
function safeActiveElement() {
try {
return document.activeElement;
} catch ( err ) { }
}
function on( elem, types, selector, data, fn, one ) {
var origFn, type;
// Types can be a map of types/handlers
if ( typeof types === "object" ) {
// ( types-Object, selector, data )
if ( typeof selector !== "string" ) {
// ( types-Object, data )
data = data || selector;
selector = undefined;
}
for ( type in types ) {
on( elem, type, selector, data, types[ type ], one );
}
return elem;
}
if ( data == null && fn == null ) {
// ( types, fn )
fn = selector;
data = selector = undefined;
} else if ( fn == null ) {
if ( typeof selector === "string" ) {
// ( types, selector, fn )
fn = data;
data = undefined;
} else {
// ( types, data, fn )
fn = data;
data = selector;
selector = undefined;
}
}
if ( fn === false ) {
fn = returnFalse;
} else if ( !fn ) {
return elem;
}
if ( one === 1 ) {
origFn = fn;
fn = function( event ) {
// Can use an empty set, since event contains the info
jQuery().off( event );
return origFn.apply( this, arguments );
};
// Use same guid so caller can remove using origFn
fn.guid = origFn.guid || ( origFn.guid = jQuery.guid++ );
}
return elem.each( function() {
jQuery.event.add( this, types, fn, data, selector );
} );
}
/*
* Helper functions for managing events -- not part of the public interface.
* Props to Dean Edwards' addEvent library for many of the ideas.
*/
jQuery.event = {
global: {},
add: function( elem, types, handler, data, selector ) {
var handleObjIn, eventHandle, tmp,
events, t, handleObj,
special, handlers, type, namespaces, origType,
elemData = dataPriv.get( elem );
// Don't attach events to noData or text/comment nodes (but allow plain objects)
if ( !elemData ) {
return;
}
// Caller can pass in an object of custom data in lieu of the handler
if ( handler.handler ) {
handleObjIn = handler;
handler = handleObjIn.handler;
selector = handleObjIn.selector;
}
// Ensure that invalid selectors throw exceptions at attach time
// Evaluate against documentElement in case elem is a non-element node (e.g., document)
if ( selector ) {
jQuery.find.matchesSelector( documentElement, selector );
}
// Make sure that the handler has a unique ID, used to find/remove it later
if ( !handler.guid ) {
handler.guid = jQuery.guid++;
}
// Init the element's event structure and main handler, if this is the first
if ( !( events = elemData.events ) ) {
events = elemData.events = {};
}
if ( !( eventHandle = elemData.handle ) ) {
eventHandle = elemData.handle = function( e ) {
// Discard the second event of a jQuery.event.trigger() and
// when an event is called after a page has unloaded
return typeof jQuery !== "undefined" && jQuery.event.triggered !== e.type ?
jQuery.event.dispatch.apply( elem, arguments ) : undefined;
};
}
// Handle multiple events separated by a space
types = ( types || "" ).match( rnothtmlwhite ) || [ "" ];
t = types.length;
while ( t-- ) {
tmp = rtypenamespace.exec( types[ t ] ) || [];
type = origType = tmp[ 1 ];
namespaces = ( tmp[ 2 ] || "" ).split( "." ).sort();
// There *must* be a type, no attaching namespace-only handlers
if ( !type ) {
continue;
}
// If event changes its type, use the special event handlers for the changed type
special = jQuery.event.special[ type ] || {};
// If selector defined, determine special event api type, otherwise given type
type = ( selector ? special.delegateType : special.bindType ) || type;
// Update special based on newly reset type
special = jQuery.event.special[ type ] || {};
// handleObj is passed to all event handlers
handleObj = jQuery.extend( {
type: type,
origType: origType,
data: data,
handler: handler,
guid: handler.guid,
selector: selector,
needsContext: selector && jQuery.expr.match.needsContext.test( selector ),
namespace: namespaces.join( "." )
}, handleObjIn );
// Init the event handler queue if we're the first
if ( !( handlers = events[ type ] ) ) {
handlers = events[ type ] = [];
handlers.delegateCount = 0;
// Only use addEventListener if the special events handler returns false
if ( !special.setup ||
special.setup.call( elem, data, namespaces, eventHandle ) === false ) {
if ( elem.addEventListener ) {
elem.addEventListener( type, eventHandle );
}
}
}
if ( special.add ) {
special.add.call( elem, handleObj );
if ( !handleObj.handler.guid ) {
handleObj.handler.guid = handler.guid;
}
}
// Add to the element's handler list, delegates in front
if ( selector ) {
handlers.splice( handlers.delegateCount++, 0, handleObj );
} else {
handlers.push( handleObj );
}
// Keep track of which events have ever been used, for event optimization
jQuery.event.global[ type ] = true;
}
},
// Detach an event or set of events from an element
remove: function( elem, types, handler, selector, mappedTypes ) {
var j, origCount, tmp,
events, t, handleObj,
special, handlers, type, namespaces, origType,
elemData = dataPriv.hasData( elem ) && dataPriv.get( elem );
if ( !elemData || !( events = elemData.events ) ) {
return;
}
// Once for each type.namespace in types; type may be omitted
types = ( types || "" ).match( rnothtmlwhite ) || [ "" ];
t = types.length;
while ( t-- ) {
tmp = rtypenamespace.exec( types[ t ] ) || [];
type = origType = tmp[ 1 ];
namespaces = ( tmp[ 2 ] || "" ).split( "." ).sort();
// Unbind all events (on this namespace, if provided) for the element
if ( !type ) {
for ( type in events ) {
jQuery.event.remove( elem, type + types[ t ], handler, selector, true );
}
continue;
}
special = jQuery.event.special[ type ] || {};
type = ( selector ? special.delegateType : special.bindType ) || type;
handlers = events[ type ] || [];
tmp = tmp[ 2 ] &&
new RegExp( "(^|\\.)" + namespaces.join( "\\.(?:.*\\.|)" ) + "(\\.|$)" );
// Remove matching events
origCount = j = handlers.length;
while ( j-- ) {
handleObj = handlers[ j ];
if ( ( mappedTypes || origType === handleObj.origType ) &&
( !handler || handler.guid === handleObj.guid ) &&
( !tmp || tmp.test( handleObj.namespace ) ) &&
( !selector || selector === handleObj.selector ||
selector === "**" && handleObj.selector ) ) {
handlers.splice( j, 1 );
if ( handleObj.selector ) {
handlers.delegateCount--;
}
if ( special.remove ) {
special.remove.call( elem, handleObj );
}
}
}
// Remove generic event handler if we removed something and no more handlers exist
// (avoids potential for endless recursion during removal of special event handlers)
if ( origCount && !handlers.length ) {
if ( !special.teardown ||
special.teardown.call( elem, namespaces, elemData.handle ) === false ) {
jQuery.removeEvent( elem, type, elemData.handle );
}
delete events[ type ];
}
}
// Remove data and the expando if it's no longer used
if ( jQuery.isEmptyObject( events ) ) {
dataPriv.remove( elem, "handle events" );
}
},
dispatch: function( nativeEvent ) {
// Make a writable jQuery.Event from the native event object
var event = jQuery.event.fix( nativeEvent );
var i, j, ret, matched, handleObj, handlerQueue,
args = new Array( arguments.length ),
handlers = ( dataPriv.get( this, "events" ) || {} )[ event.type ] || [],
special = jQuery.event.special[ event.type ] || {};
// Use the fix-ed jQuery.Event rather than the (read-only) native event
args[ 0 ] = event;
for ( i = 1; i < arguments.length; i++ ) {
args[ i ] = arguments[ i ];
}
event.delegateTarget = this;
// Call the preDispatch hook for the mapped type, and let it bail if desired
if ( special.preDispatch && special.preDispatch.call( this, event ) === false ) {
return;
}
// Determine handlers
handlerQueue = jQuery.event.handlers.call( this, event, handlers );
// Run delegates first; they may want to stop propagation beneath us
i = 0;
while ( ( matched = handlerQueue[ i++ ] ) && !event.isPropagationStopped() ) {
event.currentTarget = matched.elem;
j = 0;
while ( ( handleObj = matched.handlers[ j++ ] ) &&
!event.isImmediatePropagationStopped() ) {
// Triggered event must either 1) have no namespace, or 2) have namespace(s)
// a subset or equal to those in the bound event (both can have no namespace).
if ( !event.rnamespace || event.rnamespace.test( handleObj.namespace ) ) {
event.handleObj = handleObj;
event.data = handleObj.data;
ret = ( ( jQuery.event.special[ handleObj.origType ] || {} ).handle ||
handleObj.handler ).apply( matched.elem, args );
if ( ret !== undefined ) {
if ( ( event.result = ret ) === false ) {
event.preventDefault();
event.stopPropagation();
}
}
}
}
}
// Call the postDispatch hook for the mapped type
if ( special.postDispatch ) {
special.postDispatch.call( this, event );
}
return event.result;
},
handlers: function( event, handlers ) {
var i, handleObj, sel, matchedHandlers, matchedSelectors,
handlerQueue = [],
delegateCount = handlers.delegateCount,
cur = event.target;
// Find delegate handlers
if ( delegateCount &&
// Support: IE <=9
// Black-hole SVG <use> instance trees (trac-13180)
cur.nodeType &&
// Support: Firefox <=42
// Suppress spec-violating clicks indicating a non-primary pointer button (trac-3861)
// https://www.w3.org/TR/DOM-Level-3-Events/#event-type-click
// Support: IE 11 only
// ...but not arrow key "clicks" of radio inputs, which can have `button` -1 (gh-2343)
!( event.type === "click" && event.button >= 1 ) ) {
for ( ; cur !== this; cur = cur.parentNode || this ) {
// Don't check non-elements (#13208)
// Don't process clicks on disabled elements (#6911, #8165, #11382, #11764)
if ( cur.nodeType === 1 && !( event.type === "click" && cur.disabled === true ) ) {
matchedHandlers = [];
matchedSelectors = {};
for ( i = 0; i < delegateCount; i++ ) {
handleObj = handlers[ i ];
// Don't conflict with Object.prototype properties (#13203)
sel = handleObj.selector + " ";
if ( matchedSelectors[ sel ] === undefined ) {
matchedSelectors[ sel ] = handleObj.needsContext ?
jQuery( sel, this ).index( cur ) > -1 :
jQuery.find( sel, this, null, [ cur ] ).length;
}
if ( matchedSelectors[ sel ] ) {
matchedHandlers.push( handleObj );
}
}
if ( matchedHandlers.length ) {
handlerQueue.push( { elem: cur, handlers: matchedHandlers } );
}
}
}
}
// Add the remaining (directly-bound) handlers
cur = this;
if ( delegateCount < handlers.length ) {
handlerQueue.push( { elem: cur, handlers: handlers.slice( delegateCount ) } );
}
return handlerQueue;
},
addProp: function( name, hook ) {
Object.defineProperty( jQuery.Event.prototype, name, {
enumerable: true,
configurable: true,
get: jQuery.isFunction( hook ) ?
function() {
if ( this.originalEvent ) {
return hook( this.originalEvent );
}
} :
function() {
if ( this.originalEvent ) {
return this.originalEvent[ name ];
}
},
set: function( value ) {
Object.defineProperty( this, name, {
enumerable: true,
configurable: true,
writable: true,
value: value
} );
}
} );
},
fix: function( originalEvent ) {
return originalEvent[ jQuery.expando ] ?
originalEvent :
new jQuery.Event( originalEvent );
},
special: {
load: {
// Prevent triggered image.load events from bubbling to window.load
noBubble: true
},
focus: {
// Fire native event if possible so blur/focus sequence is correct
trigger: function() {
if ( this !== safeActiveElement() && this.focus ) {
this.focus();
return false;
}
},
delegateType: "focusin"
},
blur: {
trigger: function() {
if ( this === safeActiveElement() && this.blur ) {
this.blur();
return false;
}
},
delegateType: "focusout"
},
click: {
// For checkbox, fire native event so checked state will be right
trigger: function() {
if ( this.type === "checkbox" && this.click && nodeName( this, "input" ) ) {
this.click();
return false;
}
},
// For cross-browser consistency, don't fire native .click() on links
_default: function( event ) {
return nodeName( event.target, "a" );
}
},
beforeunload: {
postDispatch: function( event ) {
// Support: Firefox 20+
// Firefox doesn't alert if the returnValue field is not set.
if ( event.result !== undefined && event.originalEvent ) {
event.originalEvent.returnValue = event.result;
}
}
}
}
};
jQuery.removeEvent = function( elem, type, handle ) {
// This "if" is needed for plain objects
if ( elem.removeEventListener ) {
elem.removeEventListener( type, handle );
}
};
jQuery.Event = function( src, props ) {
// Allow instantiation without the 'new' keyword
if ( !( this instanceof jQuery.Event ) ) {
return new jQuery.Event( src, props );
}
// Event object
if ( src && src.type ) {
this.originalEvent = src;
this.type = src.type;
// Events bubbling up the document may have been marked as prevented
// by a handler lower down the tree; reflect the correct value.
this.isDefaultPrevented = src.defaultPrevented ||
src.defaultPrevented === undefined &&
// Support: Android <=2.3 only
src.returnValue === false ?
returnTrue :
returnFalse;
// Create target properties
// Support: Safari <=6 - 7 only
// Target should not be a text node (#504, #13143)
this.target = ( src.target && src.target.nodeType === 3 ) ?
src.target.parentNode :
src.target;
this.currentTarget = src.currentTarget;
this.relatedTarget = src.relatedTarget;
// Event type
} else {
this.type = src;
}
// Put explicitly provided properties onto the event object
if ( props ) {
jQuery.extend( this, props );
}
// Create a timestamp if incoming event doesn't have one
this.timeStamp = src && src.timeStamp || jQuery.now();
// Mark it as fixed
this[ jQuery.expando ] = true;
};
// jQuery.Event is based on DOM3 Events as specified by the ECMAScript Language Binding
// https://www.w3.org/TR/2003/WD-DOM-Level-3-Events-20030331/ecma-script-binding.html
jQuery.Event.prototype = {
constructor: jQuery.Event,
isDefaultPrevented: returnFalse,
isPropagationStopped: returnFalse,
isImmediatePropagationStopped: returnFalse,
isSimulated: false,
preventDefault: function() {
var e = this.originalEvent;
this.isDefaultPrevented = returnTrue;
if ( e && !this.isSimulated ) {
e.preventDefault();
}
},
stopPropagation: function() {
var e = this.originalEvent;
this.isPropagationStopped = returnTrue;
if ( e && !this.isSimulated ) {
e.stopPropagation();
}
},
stopImmediatePropagation: function() {
var e = this.originalEvent;
this.isImmediatePropagationStopped = returnTrue;
if ( e && !this.isSimulated ) {
e.stopImmediatePropagation();
}
this.stopPropagation();
}
};
// Includes all common event props including KeyEvent and MouseEvent specific props
jQuery.each( {
altKey: true,
bubbles: true,
cancelable: true,
changedTouches: true,
ctrlKey: true,
detail: true,
eventPhase: true,
metaKey: true,
pageX: true,
pageY: true,
shiftKey: true,
view: true,
"char": true,
charCode: true,
key: true,
keyCode: true,
button: true,
buttons: true,
clientX: true,
clientY: true,
offsetX: true,
offsetY: true,
pointerId: true,
pointerType: true,
screenX: true,
screenY: true,
targetTouches: true,
toElement: true,
touches: true,
which: function( event ) {
var button = event.button;
// Add which for key events
if ( event.which == null && rkeyEvent.test( event.type ) ) {
return event.charCode != null ? event.charCode : event.keyCode;
}
// Add which for click: 1 === left; 2 === middle; 3 === right
if ( !event.which && button !== undefined && rmouseEvent.test( event.type ) ) {
if ( button & 1 ) {
return 1;
}
if ( button & 2 ) {
return 3;
}
if ( button & 4 ) {
return 2;
}
return 0;
}
return event.which;
}
}, jQuery.event.addProp );
// Create mouseenter/leave events using mouseover/out and event-time checks
// so that event delegation works in jQuery.
// Do the same for pointerenter/pointerleave and pointerover/pointerout
//
// Support: Safari 7 only
// Safari sends mouseenter too often; see:
// https://bugs.chromium.org/p/chromium/issues/detail?id=470258
// for the description of the bug (it existed in older Chrome versions as well).
jQuery.each( {
mouseenter: "mouseover",
mouseleave: "mouseout",
pointerenter: "pointerover",
pointerleave: "pointerout"
}, function( orig, fix ) {
jQuery.event.special[ orig ] = {
delegateType: fix,
bindType: fix,
handle: function( event ) {
var ret,
target = this,
related = event.relatedTarget,
handleObj = event.handleObj;
// For mouseenter/leave call the handler if related is outside the target.
// NB: No relatedTarget if the mouse left/entered the browser window
if ( !related || ( related !== target && !jQuery.contains( target, related ) ) ) {
event.type = handleObj.origType;
ret = handleObj.handler.apply( this, arguments );
event.type = fix;
}
return ret;
}
};
} );
jQuery.fn.extend( {
on: function( types, selector, data, fn ) {
return on( this, types, selector, data, fn );
},
one: function( types, selector, data, fn ) {
return on( this, types, selector, data, fn, 1 );
},
off: function( types, selector, fn ) {
var handleObj, type;
if ( types && types.preventDefault && types.handleObj ) {
// ( event ) dispatched jQuery.Event
handleObj = types.handleObj;
jQuery( types.delegateTarget ).off(
handleObj.namespace ?
handleObj.origType + "." + handleObj.namespace :
handleObj.origType,
handleObj.selector,
handleObj.handler
);
return this;
}
if ( typeof types === "object" ) {
// ( types-object [, selector] )
for ( type in types ) {
this.off( type, selector, types[ type ] );
}
return this;
}
if ( selector === false || typeof selector === "function" ) {
// ( types [, fn] )
fn = selector;
selector = undefined;
}
if ( fn === false ) {
fn = returnFalse;
}
return this.each( function() {
jQuery.event.remove( this, types, fn, selector );
} );
}
} );
var
/* eslint-disable max-len */
// See https://github.com/eslint/eslint/issues/3229
rxhtmlTag = /<(?!area|br|col|embed|hr|img|input|link|meta|param)(([a-z][^\/\0>\x20\t\r\n\f]*)[^>]*)\/>/gi,
/* eslint-enable */
// Support: IE <=10 - 11, Edge 12 - 13
// In IE/Edge using regex groups here causes severe slowdowns.
// See https://connect.microsoft.com/IE/feedback/details/1736512/
rnoInnerhtml = /<script|<style|<link/i,
// checked="checked" or checked
rchecked = /checked\s*(?:[^=]|=\s*.checked.)/i,
rscriptTypeMasked = /^true\/(.*)/,
rcleanScript = /^\s*<!(?:\[CDATA\[|--)|(?:\]\]|--)>\s*$/g;
// Prefer a tbody over its parent table for containing new rows
function manipulationTarget( elem, content ) {
if ( nodeName( elem, "table" ) &&
nodeName( content.nodeType !== 11 ? content : content.firstChild, "tr" ) ) {
return jQuery( ">tbody", elem )[ 0 ] || elem;
}
return elem;
}
// Replace/restore the type attribute of script elements for safe DOM manipulation
function disableScript( elem ) {
elem.type = ( elem.getAttribute( "type" ) !== null ) + "/" + elem.type;
return elem;
}
function restoreScript( elem ) {
var match = rscriptTypeMasked.exec( elem.type );
if ( match ) {
elem.type = match[ 1 ];
} else {
elem.removeAttribute( "type" );
}
return elem;
}
function cloneCopyEvent( src, dest ) {
var i, l, type, pdataOld, pdataCur, udataOld, udataCur, events;
if ( dest.nodeType !== 1 ) {
return;
}
// 1. Copy private data: events, handlers, etc.
if ( dataPriv.hasData( src ) ) {
pdataOld = dataPriv.access( src );
pdataCur = dataPriv.set( dest, pdataOld );
events = pdataOld.events;
if ( events ) {
delete pdataCur.handle;
pdataCur.events = {};
for ( type in events ) {
for ( i = 0, l = events[ type ].length; i < l; i++ ) {
jQuery.event.add( dest, type, events[ type ][ i ] );
}
}
}
}
// 2. Copy user data
if ( dataUser.hasData( src ) ) {
udataOld = dataUser.access( src );
udataCur = jQuery.extend( {}, udataOld );
dataUser.set( dest, udataCur );
}
}
// Fix IE bugs, see support tests
function fixInput( src, dest ) {
var nodeName = dest.nodeName.toLowerCase();
// Fails to persist the checked state of a cloned checkbox or radio button.
if ( nodeName === "input" && rcheckableType.test( src.type ) ) {
dest.checked = src.checked;
// Fails to return the selected option to the default selected state when cloning options
} else if ( nodeName === "input" || nodeName === "textarea" ) {
dest.defaultValue = src.defaultValue;
}
}
function domManip( collection, args, callback, ignored ) {
// Flatten any nested arrays
args = concat.apply( [], args );
var fragment, first, scripts, hasScripts, node, doc,
i = 0,
l = collection.length,
iNoClone = l - 1,
value = args[ 0 ],
isFunction = jQuery.isFunction( value );
// We can't cloneNode fragments that contain checked, in WebKit
if ( isFunction ||
( l > 1 && typeof value === "string" &&
!support.checkClone && rchecked.test( value ) ) ) {
return collection.each( function( index ) {
var self = collection.eq( index );
if ( isFunction ) {
args[ 0 ] = value.call( this, index, self.html() );
}
domManip( self, args, callback, ignored );
} );
}
if ( l ) {
fragment = buildFragment( args, collection[ 0 ].ownerDocument, false, collection, ignored );
first = fragment.firstChild;
if ( fragment.childNodes.length === 1 ) {
fragment = first;
}
// Require either new content or an interest in ignored elements to invoke the callback
if ( first || ignored ) {
scripts = jQuery.map( getAll( fragment, "script" ), disableScript );
hasScripts = scripts.length;
// Use the original fragment for the last item
// instead of the first because it can end up
// being emptied incorrectly in certain situations (#8070).
for ( ; i < l; i++ ) {
node = fragment;
if ( i !== iNoClone ) {
node = jQuery.clone( node, true, true );
// Keep references to cloned scripts for later restoration
if ( hasScripts ) {
// Support: Android <=4.0 only, PhantomJS 1 only
// push.apply(_, arraylike) throws on ancient WebKit
jQuery.merge( scripts, getAll( node, "script" ) );
}
}
callback.call( collection[ i ], node, i );
}
if ( hasScripts ) {
doc = scripts[ scripts.length - 1 ].ownerDocument;
// Reenable scripts
jQuery.map( scripts, restoreScript );
// Evaluate executable scripts on first document insertion
for ( i = 0; i < hasScripts; i++ ) {
node = scripts[ i ];
if ( rscriptType.test( node.type || "" ) &&
!dataPriv.access( node, "globalEval" ) &&
jQuery.contains( doc, node ) ) {
if ( node.src ) {
// Optional AJAX dependency, but won't run scripts if not present
if ( jQuery._evalUrl ) {
jQuery._evalUrl( node.src );
}
} else {
DOMEval( node.textContent.replace( rcleanScript, "" ), doc );
}
}
}
}
}
}
return collection;
}
function remove( elem, selector, keepData ) {
var node,
nodes = selector ? jQuery.filter( selector, elem ) : elem,
i = 0;
for ( ; ( node = nodes[ i ] ) != null; i++ ) {
if ( !keepData && node.nodeType === 1 ) {
jQuery.cleanData( getAll( node ) );
}
if ( node.parentNode ) {
if ( keepData && jQuery.contains( node.ownerDocument, node ) ) {
setGlobalEval( getAll( node, "script" ) );
}
node.parentNode.removeChild( node );
}
}
return elem;
}
jQuery.extend( {
htmlPrefilter: function( html ) {
return html.replace( rxhtmlTag, "<$1></$2>" );
},
clone: function( elem, dataAndEvents, deepDataAndEvents ) {
var i, l, srcElements, destElements,
clone = elem.cloneNode( true ),
inPage = jQuery.contains( elem.ownerDocument, elem );
// Fix IE cloning issues
if ( !support.noCloneChecked && ( elem.nodeType === 1 || elem.nodeType === 11 ) &&
!jQuery.isXMLDoc( elem ) ) {
// We eschew Sizzle here for performance reasons: https://jsperf.com/getall-vs-sizzle/2
destElements = getAll( clone );
srcElements = getAll( elem );
for ( i = 0, l = srcElements.length; i < l; i++ ) {
fixInput( srcElements[ i ], destElements[ i ] );
}
}
// Copy the events from the original to the clone
if ( dataAndEvents ) {
if ( deepDataAndEvents ) {
srcElements = srcElements || getAll( elem );
destElements = destElements || getAll( clone );
for ( i = 0, l = srcElements.length; i < l; i++ ) {
cloneCopyEvent( srcElements[ i ], destElements[ i ] );
}
} else {
cloneCopyEvent( elem, clone );
}
}
// Preserve script evaluation history
destElements = getAll( clone, "script" );
if ( destElements.length > 0 ) {
setGlobalEval( destElements, !inPage && getAll( elem, "script" ) );
}
// Return the cloned set
return clone;
},
cleanData: function( elems ) {
var data, elem, type,
special = jQuery.event.special,
i = 0;
for ( ; ( elem = elems[ i ] ) !== undefined; i++ ) {
if ( acceptData( elem ) ) {
if ( ( data = elem[ dataPriv.expando ] ) ) {
if ( data.events ) {
for ( type in data.events ) {
if ( special[ type ] ) {
jQuery.event.remove( elem, type );
// This is a shortcut to avoid jQuery.event.remove's overhead
} else {
jQuery.removeEvent( elem, type, data.handle );
}
}
}
// Support: Chrome <=35 - 45+
// Assign undefined instead of using delete, see Data#remove
elem[ dataPriv.expando ] = undefined;
}
if ( elem[ dataUser.expando ] ) {
// Support: Chrome <=35 - 45+
// Assign undefined instead of using delete, see Data#remove
elem[ dataUser.expando ] = undefined;
}
}
}
}
} );
jQuery.fn.extend( {
detach: function( selector ) {
return remove( this, selector, true );
},
remove: function( selector ) {
return remove( this, selector );
},
text: function( value ) {
return access( this, function( value ) {
return value === undefined ?
jQuery.text( this ) :
this.empty().each( function() {
if ( this.nodeType === 1 || this.nodeType === 11 || this.nodeType === 9 ) {
this.textContent = value;
}
} );
}, null, value, arguments.length );
},
append: function() {
return domManip( this, arguments, function( elem ) {
if ( this.nodeType === 1 || this.nodeType === 11 || this.nodeType === 9 ) {
var target = manipulationTarget( this, elem );
target.appendChild( elem );
}
} );
},
prepend: function() {
return domManip( this, arguments, function( elem ) {
if ( this.nodeType === 1 || this.nodeType === 11 || this.nodeType === 9 ) {
var target = manipulationTarget( this, elem );
target.insertBefore( elem, target.firstChild );
}
} );
},
before: function() {
return domManip( this, arguments, function( elem ) {
if ( this.parentNode ) {
this.parentNode.insertBefore( elem, this );
}
} );
},
after: function() {
return domManip( this, arguments, function( elem ) {
if ( this.parentNode ) {
this.parentNode.insertBefore( elem, this.nextSibling );
}
} );
},
empty: function() {
var elem,
i = 0;
for ( ; ( elem = this[ i ] ) != null; i++ ) {
if ( elem.nodeType === 1 ) {
// Prevent memory leaks
jQuery.cleanData( getAll( elem, false ) );
// Remove any remaining nodes
elem.textContent = "";
}
}
return this;
},
clone: function( dataAndEvents, deepDataAndEvents ) {
dataAndEvents = dataAndEvents == null ? false : dataAndEvents;
deepDataAndEvents = deepDataAndEvents == null ? dataAndEvents : deepDataAndEvents;
return this.map( function() {
return jQuery.clone( this, dataAndEvents, deepDataAndEvents );
} );
},
html: function( value ) {
return access( this, function( value ) {
var elem = this[ 0 ] || {},
i = 0,
l = this.length;
if ( value === undefined && elem.nodeType === 1 ) {
return elem.innerHTML;
}
// See if we can take a shortcut and just use innerHTML
if ( typeof value === "string" && !rnoInnerhtml.test( value ) &&
!wrapMap[ ( rtagName.exec( value ) || [ "", "" ] )[ 1 ].toLowerCase() ] ) {
value = jQuery.htmlPrefilter( value );
try {
for ( ; i < l; i++ ) {
elem = this[ i ] || {};
// Remove element nodes and prevent memory leaks
if ( elem.nodeType === 1 ) {
jQuery.cleanData( getAll( elem, false ) );
elem.innerHTML = value;
}
}
elem = 0;
// If using innerHTML throws an exception, use the fallback method
} catch ( e ) {}
}
if ( elem ) {
this.empty().append( value );
}
}, null, value, arguments.length );
},
replaceWith: function() {
var ignored = [];
// Make the changes, replacing each non-ignored context element with the new content
return domManip( this, arguments, function( elem ) {
var parent = this.parentNode;
if ( jQuery.inArray( this, ignored ) < 0 ) {
jQuery.cleanData( getAll( this ) );
if ( parent ) {
parent.replaceChild( elem, this );
}
}
// Force callback invocation
}, ignored );
}
} );
jQuery.each( {
appendTo: "append",
prependTo: "prepend",
insertBefore: "before",
insertAfter: "after",
replaceAll: "replaceWith"
}, function( name, original ) {
jQuery.fn[ name ] = function( selector ) {
var elems,
ret = [],
insert = jQuery( selector ),
last = insert.length - 1,
i = 0;
for ( ; i <= last; i++ ) {
elems = i === last ? this : this.clone( true );
jQuery( insert[ i ] )[ original ]( elems );
// Support: Android <=4.0 only, PhantomJS 1 only
// .get() because push.apply(_, arraylike) throws on ancient WebKit
push.apply( ret, elems.get() );
}
return this.pushStack( ret );
};
} );
var rmargin = ( /^margin/ );
var rnumnonpx = new RegExp( "^(" + pnum + ")(?!px)[a-z%]+$", "i" );
var getStyles = function( elem ) {
// Support: IE <=11 only, Firefox <=30 (#15098, #14150)
// IE throws on elements created in popups
// FF meanwhile throws on frame elements through "defaultView.getComputedStyle"
var view = elem.ownerDocument.defaultView;
if ( !view || !view.opener ) {
view = window;
}
return view.getComputedStyle( elem );
};
( function() {
// Executing both pixelPosition & boxSizingReliable tests require only one layout
// so they're executed at the same time to save the second computation.
function computeStyleTests() {
// This is a singleton, we need to execute it only once
if ( !div ) {
return;
}
div.style.cssText =
"box-sizing:border-box;" +
"position:relative;display:block;" +
"margin:auto;border:1px;padding:1px;" +
"top:1%;width:50%";
div.innerHTML = "";
documentElement.appendChild( container );
var divStyle = window.getComputedStyle( div );
pixelPositionVal = divStyle.top !== "1%";
// Support: Android 4.0 - 4.3 only, Firefox <=3 - 44
reliableMarginLeftVal = divStyle.marginLeft === "2px";
boxSizingReliableVal = divStyle.width === "4px";
// Support: Android 4.0 - 4.3 only
// Some styles come back with percentage values, even though they shouldn't
div.style.marginRight = "50%";
pixelMarginRightVal = divStyle.marginRight === "4px";
documentElement.removeChild( container );
// Nullify the div so it wouldn't be stored in the memory and
// it will also be a sign that checks already performed
div = null;
}
var pixelPositionVal, boxSizingReliableVal, pixelMarginRightVal, reliableMarginLeftVal,
container = document.createElement( "div" ),
div = document.createElement( "div" );
// Finish early in limited (non-browser) environments
if ( !div.style ) {
return;
}
// Support: IE <=9 - 11 only
// Style of cloned element affects source element cloned (#8908)
div.style.backgroundClip = "content-box";
div.cloneNode( true ).style.backgroundClip = "";
support.clearCloneStyle = div.style.backgroundClip === "content-box";
container.style.cssText = "border:0;width:8px;height:0;top:0;left:-9999px;" +
"padding:0;margin-top:1px;position:absolute";
container.appendChild( div );
jQuery.extend( support, {
pixelPosition: function() {
computeStyleTests();
return pixelPositionVal;
},
boxSizingReliable: function() {
computeStyleTests();
return boxSizingReliableVal;
},
pixelMarginRight: function() {
computeStyleTests();
return pixelMarginRightVal;
},
reliableMarginLeft: function() {
computeStyleTests();
return reliableMarginLeftVal;
}
} );
} )();
function curCSS( elem, name, computed ) {
var width, minWidth, maxWidth, ret,
// Support: Firefox 51+
// Retrieving style before computed somehow
// fixes an issue with getting wrong values
// on detached elements
style = elem.style;
computed = computed || getStyles( elem );
// getPropertyValue is needed for:
// .css('filter') (IE 9 only, #12537)
// .css('--customProperty) (#3144)
if ( computed ) {
ret = computed.getPropertyValue( name ) || computed[ name ];
if ( ret === "" && !jQuery.contains( elem.ownerDocument, elem ) ) {
ret = jQuery.style( elem, name );
}
// A tribute to the "awesome hack by Dean Edwards"
// Android Browser returns percentage for some values,
// but width seems to be reliably pixels.
// This is against the CSSOM draft spec:
// https://drafts.csswg.org/cssom/#resolved-values
if ( !support.pixelMarginRight() && rnumnonpx.test( ret ) && rmargin.test( name ) ) {
// Remember the original values
width = style.width;
minWidth = style.minWidth;
maxWidth = style.maxWidth;
// Put in the new values to get a computed value out
style.minWidth = style.maxWidth = style.width = ret;
ret = computed.width;
// Revert the changed values
style.width = width;
style.minWidth = minWidth;
style.maxWidth = maxWidth;
}
}
return ret !== undefined ?
// Support: IE <=9 - 11 only
// IE returns zIndex value as an integer.
ret + "" :
ret;
}
function addGetHookIf( conditionFn, hookFn ) {
// Define the hook, we'll check on the first run if it's really needed.
return {
get: function() {
if ( conditionFn() ) {
// Hook not needed (or it's not possible to use it due
// to missing dependency), remove it.
delete this.get;
return;
}
// Hook needed; redefine it so that the support test is not executed again.
return ( this.get = hookFn ).apply( this, arguments );
}
};
}
var
// Swappable if display is none or starts with table
// except "table", "table-cell", or "table-caption"
// See here for display values: https://developer.mozilla.org/en-US/docs/CSS/display
rdisplayswap = /^(none|table(?!-c[ea]).+)/,
rcustomProp = /^--/,
cssShow = { position: "absolute", visibility: "hidden", display: "block" },
cssNormalTransform = {
letterSpacing: "0",
fontWeight: "400"
},
cssPrefixes = [ "Webkit", "Moz", "ms" ],
emptyStyle = document.createElement( "div" ).style;
// Return a css property mapped to a potentially vendor prefixed property
function vendorPropName( name ) {
// Shortcut for names that are not vendor prefixed
if ( name in emptyStyle ) {
return name;
}
// Check for vendor prefixed names
var capName = name[ 0 ].toUpperCase() + name.slice( 1 ),
i = cssPrefixes.length;
while ( i-- ) {
name = cssPrefixes[ i ] + capName;
if ( name in emptyStyle ) {
return name;
}
}
}
// Return a property mapped along what jQuery.cssProps suggests or to
// a vendor prefixed property.
function finalPropName( name ) {
var ret = jQuery.cssProps[ name ];
if ( !ret ) {
ret = jQuery.cssProps[ name ] = vendorPropName( name ) || name;
}
return ret;
}
function setPositiveNumber( elem, value, subtract ) {
// Any relative (+/-) values have already been
// normalized at this point
var matches = rcssNum.exec( value );
return matches ?
// Guard against undefined "subtract", e.g., when used as in cssHooks
Math.max( 0, matches[ 2 ] - ( subtract || 0 ) ) + ( matches[ 3 ] || "px" ) :
value;
}
function augmentWidthOrHeight( elem, name, extra, isBorderBox, styles ) {
var i,
val = 0;
// If we already have the right measurement, avoid augmentation
if ( extra === ( isBorderBox ? "border" : "content" ) ) {
i = 4;
// Otherwise initialize for horizontal or vertical properties
} else {
i = name === "width" ? 1 : 0;
}
for ( ; i < 4; i += 2 ) {
// Both box models exclude margin, so add it if we want it
if ( extra === "margin" ) {
val += jQuery.css( elem, extra + cssExpand[ i ], true, styles );
}
if ( isBorderBox ) {
// border-box includes padding, so remove it if we want content
if ( extra === "content" ) {
val -= jQuery.css( elem, "padding" + cssExpand[ i ], true, styles );
}
// At this point, extra isn't border nor margin, so remove border
if ( extra !== "margin" ) {
val -= jQuery.css( elem, "border" + cssExpand[ i ] + "Width", true, styles );
}
} else {
// At this point, extra isn't content, so add padding
val += jQuery.css( elem, "padding" + cssExpand[ i ], true, styles );
// At this point, extra isn't content nor padding, so add border
if ( extra !== "padding" ) {
val += jQuery.css( elem, "border" + cssExpand[ i ] + "Width", true, styles );
}
}
}
return val;
}
function getWidthOrHeight( elem, name, extra ) {
// Start with computed style
var valueIsBorderBox,
styles = getStyles( elem ),
val = curCSS( elem, name, styles ),
isBorderBox = jQuery.css( elem, "boxSizing", false, styles ) === "border-box";
// Computed unit is not pixels. Stop here and return.
if ( rnumnonpx.test( val ) ) {
return val;
}
// Check for style in case a browser which returns unreliable values
// for getComputedStyle silently falls back to the reliable elem.style
valueIsBorderBox = isBorderBox &&
( support.boxSizingReliable() || val === elem.style[ name ] );
// Fall back to offsetWidth/Height when value is "auto"
// This happens for inline elements with no explicit setting (gh-3571)
if ( val === "auto" ) {
val = elem[ "offset" + name[ 0 ].toUpperCase() + name.slice( 1 ) ];
}
// Normalize "", auto, and prepare for extra
val = parseFloat( val ) || 0;
// Use the active box-sizing model to add/subtract irrelevant styles
return ( val +
augmentWidthOrHeight(
elem,
name,
extra || ( isBorderBox ? "border" : "content" ),
valueIsBorderBox,
styles
)
) + "px";
}
jQuery.extend( {
// Add in style property hooks for overriding the default
// behavior of getting and setting a style property
cssHooks: {
opacity: {
get: function( elem, computed ) {
if ( computed ) {
// We should always get a number back from opacity
var ret = curCSS( elem, "opacity" );
return ret === "" ? "1" : ret;
}
}
}
},
// Don't automatically add "px" to these possibly-unitless properties
cssNumber: {
"animationIterationCount": true,
"columnCount": true,
"fillOpacity": true,
"flexGrow": true,
"flexShrink": true,
"fontWeight": true,
"lineHeight": true,
"opacity": true,
"order": true,
"orphans": true,
"widows": true,
"zIndex": true,
"zoom": true
},
// Add in properties whose names you wish to fix before
// setting or getting the value
cssProps: {
"float": "cssFloat"
},
// Get and set the style property on a DOM Node
style: function( elem, name, value, extra ) {
// Don't set styles on text and comment nodes
if ( !elem || elem.nodeType === 3 || elem.nodeType === 8 || !elem.style ) {
return;
}
// Make sure that we're working with the right name
var ret, type, hooks,
origName = jQuery.camelCase( name ),
isCustomProp = rcustomProp.test( name ),
style = elem.style;
// Make sure that we're working with the right name. We don't
// want to query the value if it is a CSS custom property
// since they are user-defined.
if ( !isCustomProp ) {
name = finalPropName( origName );
}
// Gets hook for the prefixed version, then unprefixed version
hooks = jQuery.cssHooks[ name ] || jQuery.cssHooks[ origName ];
// Check if we're setting a value
if ( value !== undefined ) {
type = typeof value;
// Convert "+=" or "-=" to relative numbers (#7345)
if ( type === "string" && ( ret = rcssNum.exec( value ) ) && ret[ 1 ] ) {
value = adjustCSS( elem, name, ret );
// Fixes bug #9237
type = "number";
}
// Make sure that null and NaN values aren't set (#7116)
if ( value == null || value !== value ) {
return;
}
// If a number was passed in, add the unit (except for certain CSS properties)
if ( type === "number" ) {
value += ret && ret[ 3 ] || ( jQuery.cssNumber[ origName ] ? "" : "px" );
}
// background-* props affect original clone's values
if ( !support.clearCloneStyle && value === "" && name.indexOf( "background" ) === 0 ) {
style[ name ] = "inherit";
}
// If a hook was provided, use that value, otherwise just set the specified value
if ( !hooks || !( "set" in hooks ) ||
( value = hooks.set( elem, value, extra ) ) !== undefined ) {
if ( isCustomProp ) {
style.setProperty( name, value );
} else {
style[ name ] = value;
}
}
} else {
// If a hook was provided get the non-computed value from there
if ( hooks && "get" in hooks &&
( ret = hooks.get( elem, false, extra ) ) !== undefined ) {
return ret;
}
// Otherwise just get the value from the style object
return style[ name ];
}
},
css: function( elem, name, extra, styles ) {
var val, num, hooks,
origName = jQuery.camelCase( name ),
isCustomProp = rcustomProp.test( name );
// Make sure that we're working with the right name. We don't
// want to modify the value if it is a CSS custom property
// since they are user-defined.
if ( !isCustomProp ) {
name = finalPropName( origName );
}
// Try prefixed name followed by the unprefixed name
hooks = jQuery.cssHooks[ name ] || jQuery.cssHooks[ origName ];
// If a hook was provided get the computed value from there
if ( hooks && "get" in hooks ) {
val = hooks.get( elem, true, extra );
}
// Otherwise, if a way to get the computed value exists, use that
if ( val === undefined ) {
val = curCSS( elem, name, styles );
}
// Convert "normal" to computed value
if ( val === "normal" && name in cssNormalTransform ) {
val = cssNormalTransform[ name ];
}
// Make numeric if forced or a qualifier was provided and val looks numeric
if ( extra === "" || extra ) {
num = parseFloat( val );
return extra === true || isFinite( num ) ? num || 0 : val;
}
return val;
}
} );
jQuery.each( [ "height", "width" ], function( i, name ) {
jQuery.cssHooks[ name ] = {
get: function( elem, computed, extra ) {
if ( computed ) {
// Certain elements can have dimension info if we invisibly show them
// but it must have a current display style that would benefit
return rdisplayswap.test( jQuery.css( elem, "display" ) ) &&
// Support: Safari 8+
// Table columns in Safari have non-zero offsetWidth & zero
// getBoundingClientRect().width unless display is changed.
// Support: IE <=11 only
// Running getBoundingClientRect on a disconnected node
// in IE throws an error.
( !elem.getClientRects().length || !elem.getBoundingClientRect().width ) ?
swap( elem, cssShow, function() {
return getWidthOrHeight( elem, name, extra );
} ) :
getWidthOrHeight( elem, name, extra );
}
},
set: function( elem, value, extra ) {
var matches,
styles = extra && getStyles( elem ),
subtract = extra && augmentWidthOrHeight(
elem,
name,
extra,
jQuery.css( elem, "boxSizing", false, styles ) === "border-box",
styles
);
// Convert to pixels if value adjustment is needed
if ( subtract && ( matches = rcssNum.exec( value ) ) &&
( matches[ 3 ] || "px" ) !== "px" ) {
elem.style[ name ] = value;
value = jQuery.css( elem, name );
}
return setPositiveNumber( elem, value, subtract );
}
};
} );
jQuery.cssHooks.marginLeft = addGetHookIf( support.reliableMarginLeft,
function( elem, computed ) {
if ( computed ) {
return ( parseFloat( curCSS( elem, "marginLeft" ) ) ||
elem.getBoundingClientRect().left -
swap( elem, { marginLeft: 0 }, function() {
return elem.getBoundingClientRect().left;
} )
) + "px";
}
}
);
// These hooks are used by animate to expand properties
jQuery.each( {
margin: "",
padding: "",
border: "Width"
}, function( prefix, suffix ) {
jQuery.cssHooks[ prefix + suffix ] = {
expand: function( value ) {
var i = 0,
expanded = {},
// Assumes a single number if not a string
parts = typeof value === "string" ? value.split( " " ) : [ value ];
for ( ; i < 4; i++ ) {
expanded[ prefix + cssExpand[ i ] + suffix ] =
parts[ i ] || parts[ i - 2 ] || parts[ 0 ];
}
return expanded;
}
};
if ( !rmargin.test( prefix ) ) {
jQuery.cssHooks[ prefix + suffix ].set = setPositiveNumber;
}
} );
jQuery.fn.extend( {
css: function( name, value ) {
return access( this, function( elem, name, value ) {
var styles, len,
map = {},
i = 0;
if ( Array.isArray( name ) ) {
styles = getStyles( elem );
len = name.length;
for ( ; i < len; i++ ) {
map[ name[ i ] ] = jQuery.css( elem, name[ i ], false, styles );
}
return map;
}
return value !== undefined ?
jQuery.style( elem, name, value ) :
jQuery.css( elem, name );
}, name, value, arguments.length > 1 );
}
} );
function Tween( elem, options, prop, end, easing ) {
return new Tween.prototype.init( elem, options, prop, end, easing );
}
jQuery.Tween = Tween;
Tween.prototype = {
constructor: Tween,
init: function( elem, options, prop, end, easing, unit ) {
this.elem = elem;
this.prop = prop;
this.easing = easing || jQuery.easing._default;
this.options = options;
this.start = this.now = this.cur();
this.end = end;
this.unit = unit || ( jQuery.cssNumber[ prop ] ? "" : "px" );
},
cur: function() {
var hooks = Tween.propHooks[ this.prop ];
return hooks && hooks.get ?
hooks.get( this ) :
Tween.propHooks._default.get( this );
},
run: function( percent ) {
var eased,
hooks = Tween.propHooks[ this.prop ];
if ( this.options.duration ) {
this.pos = eased = jQuery.easing[ this.easing ](
percent, this.options.duration * percent, 0, 1, this.options.duration
);
} else {
this.pos = eased = percent;
}
this.now = ( this.end - this.start ) * eased + this.start;
if ( this.options.step ) {
this.options.step.call( this.elem, this.now, this );
}
if ( hooks && hooks.set ) {
hooks.set( this );
} else {
Tween.propHooks._default.set( this );
}
return this;
}
};
Tween.prototype.init.prototype = Tween.prototype;
Tween.propHooks = {
_default: {
get: function( tween ) {
var result;
// Use a property on the element directly when it is not a DOM element,
// or when there is no matching style property that exists.
if ( tween.elem.nodeType !== 1 ||
tween.elem[ tween.prop ] != null && tween.elem.style[ tween.prop ] == null ) {
return tween.elem[ tween.prop ];
}
// Passing an empty string as a 3rd parameter to .css will automatically
// attempt a parseFloat and fallback to a string if the parse fails.
// Simple values such as "10px" are parsed to Float;
// complex values such as "rotate(1rad)" are returned as-is.
result = jQuery.css( tween.elem, tween.prop, "" );
// Empty strings, null, undefined and "auto" are converted to 0.
return !result || result === "auto" ? 0 : result;
},
set: function( tween ) {
// Use step hook for back compat.
// Use cssHook if its there.
// Use .style if available and use plain properties where available.
if ( jQuery.fx.step[ tween.prop ] ) {
jQuery.fx.step[ tween.prop ]( tween );
} else if ( tween.elem.nodeType === 1 &&
( tween.elem.style[ jQuery.cssProps[ tween.prop ] ] != null ||
jQuery.cssHooks[ tween.prop ] ) ) {
jQuery.style( tween.elem, tween.prop, tween.now + tween.unit );
} else {
tween.elem[ tween.prop ] = tween.now;
}
}
}
};
// Support: IE <=9 only
// Panic based approach to setting things on disconnected nodes
Tween.propHooks.scrollTop = Tween.propHooks.scrollLeft = {
set: function( tween ) {
if ( tween.elem.nodeType && tween.elem.parentNode ) {
tween.elem[ tween.prop ] = tween.now;
}
}
};
jQuery.easing = {
linear: function( p ) {
return p;
},
swing: function( p ) {
return 0.5 - Math.cos( p * Math.PI ) / 2;
},
_default: "swing"
};
jQuery.fx = Tween.prototype.init;
// Back compat <1.8 extension point
jQuery.fx.step = {};
var
fxNow, inProgress,
rfxtypes = /^(?:toggle|show|hide)$/,
rrun = /queueHooks$/;
function schedule() {
if ( inProgress ) {
if ( document.hidden === false && window.requestAnimationFrame ) {
window.requestAnimationFrame( schedule );
} else {
window.setTimeout( schedule, jQuery.fx.interval );
}
jQuery.fx.tick();
}
}
// Animations created synchronously will run synchronously
function createFxNow() {
window.setTimeout( function() {
fxNow = undefined;
} );
return ( fxNow = jQuery.now() );
}
// Generate parameters to create a standard animation
function genFx( type, includeWidth ) {
var which,
i = 0,
attrs = { height: type };
// If we include width, step value is 1 to do all cssExpand values,
// otherwise step value is 2 to skip over Left and Right
includeWidth = includeWidth ? 1 : 0;
for ( ; i < 4; i += 2 - includeWidth ) {
which = cssExpand[ i ];
attrs[ "margin" + which ] = attrs[ "padding" + which ] = type;
}
if ( includeWidth ) {
attrs.opacity = attrs.width = type;
}
return attrs;
}
function createTween( value, prop, animation ) {
var tween,
collection = ( Animation.tweeners[ prop ] || [] ).concat( Animation.tweeners[ "*" ] ),
index = 0,
length = collection.length;
for ( ; index < length; index++ ) {
if ( ( tween = collection[ index ].call( animation, prop, value ) ) ) {
// We're done with this property
return tween;
}
}
}
function defaultPrefilter( elem, props, opts ) {
var prop, value, toggle, hooks, oldfire, propTween, restoreDisplay, display,
isBox = "width" in props || "height" in props,
anim = this,
orig = {},
style = elem.style,
hidden = elem.nodeType && isHiddenWithinTree( elem ),
dataShow = dataPriv.get( elem, "fxshow" );
// Queue-skipping animations hijack the fx hooks
if ( !opts.queue ) {
hooks = jQuery._queueHooks( elem, "fx" );
if ( hooks.unqueued == null ) {
hooks.unqueued = 0;
oldfire = hooks.empty.fire;
hooks.empty.fire = function() {
if ( !hooks.unqueued ) {
oldfire();
}
};
}
hooks.unqueued++;
anim.always( function() {
// Ensure the complete handler is called before this completes
anim.always( function() {
hooks.unqueued--;
if ( !jQuery.queue( elem, "fx" ).length ) {
hooks.empty.fire();
}
} );
} );
}
// Detect show/hide animations
for ( prop in props ) {
value = props[ prop ];
if ( rfxtypes.test( value ) ) {
delete props[ prop ];
toggle = toggle || value === "toggle";
if ( value === ( hidden ? "hide" : "show" ) ) {
// Pretend to be hidden if this is a "show" and
// there is still data from a stopped show/hide
if ( value === "show" && dataShow && dataShow[ prop ] !== undefined ) {
hidden = true;
// Ignore all other no-op show/hide data
} else {
continue;
}
}
orig[ prop ] = dataShow && dataShow[ prop ] || jQuery.style( elem, prop );
}
}
// Bail out if this is a no-op like .hide().hide()
propTween = !jQuery.isEmptyObject( props );
if ( !propTween && jQuery.isEmptyObject( orig ) ) {
return;
}
// Restrict "overflow" and "display" styles during box animations
if ( isBox && elem.nodeType === 1 ) {
// Support: IE <=9 - 11, Edge 12 - 13
// Record all 3 overflow attributes because IE does not infer the shorthand
// from identically-valued overflowX and overflowY
opts.overflow = [ style.overflow, style.overflowX, style.overflowY ];
// Identify a display type, preferring old show/hide data over the CSS cascade
restoreDisplay = dataShow && dataShow.display;
if ( restoreDisplay == null ) {
restoreDisplay = dataPriv.get( elem, "display" );
}
display = jQuery.css( elem, "display" );
if ( display === "none" ) {
if ( restoreDisplay ) {
display = restoreDisplay;
} else {
// Get nonempty value(s) by temporarily forcing visibility
showHide( [ elem ], true );
restoreDisplay = elem.style.display || restoreDisplay;
display = jQuery.css( elem, "display" );
showHide( [ elem ] );
}
}
// Animate inline elements as inline-block
if ( display === "inline" || display === "inline-block" && restoreDisplay != null ) {
if ( jQuery.css( elem, "float" ) === "none" ) {
// Restore the original display value at the end of pure show/hide animations
if ( !propTween ) {
anim.done( function() {
style.display = restoreDisplay;
} );
if ( restoreDisplay == null ) {
display = style.display;
restoreDisplay = display === "none" ? "" : display;
}
}
style.display = "inline-block";
}
}
}
if ( opts.overflow ) {
style.overflow = "hidden";
anim.always( function() {
style.overflow = opts.overflow[ 0 ];
style.overflowX = opts.overflow[ 1 ];
style.overflowY = opts.overflow[ 2 ];
} );
}
// Implement show/hide animations
propTween = false;
for ( prop in orig ) {
// General show/hide setup for this element animation
if ( !propTween ) {
if ( dataShow ) {
if ( "hidden" in dataShow ) {
hidden = dataShow.hidden;
}
} else {
dataShow = dataPriv.access( elem, "fxshow", { display: restoreDisplay } );
}
// Store hidden/visible for toggle so `.stop().toggle()` "reverses"
if ( toggle ) {
dataShow.hidden = !hidden;
}
// Show elements before animating them
if ( hidden ) {
showHide( [ elem ], true );
}
/* eslint-disable no-loop-func */
anim.done( function() {
/* eslint-enable no-loop-func */
// The final step of a "hide" animation is actually hiding the element
if ( !hidden ) {
showHide( [ elem ] );
}
dataPriv.remove( elem, "fxshow" );
for ( prop in orig ) {
jQuery.style( elem, prop, orig[ prop ] );
}
} );
}
// Per-property setup
propTween = createTween( hidden ? dataShow[ prop ] : 0, prop, anim );
if ( !( prop in dataShow ) ) {
dataShow[ prop ] = propTween.start;
if ( hidden ) {
propTween.end = propTween.start;
propTween.start = 0;
}
}
}
}
function propFilter( props, specialEasing ) {
var index, name, easing, value, hooks;
// camelCase, specialEasing and expand cssHook pass
for ( index in props ) {
name = jQuery.camelCase( index );
easing = specialEasing[ name ];
value = props[ index ];
if ( Array.isArray( value ) ) {
easing = value[ 1 ];
value = props[ index ] = value[ 0 ];
}
if ( index !== name ) {
props[ name ] = value;
delete props[ index ];
}
hooks = jQuery.cssHooks[ name ];
if ( hooks && "expand" in hooks ) {
value = hooks.expand( value );
delete props[ name ];
// Not quite $.extend, this won't overwrite existing keys.
// Reusing 'index' because we have the correct "name"
for ( index in value ) {
if ( !( index in props ) ) {
props[ index ] = value[ index ];
specialEasing[ index ] = easing;
}
}
} else {
specialEasing[ name ] = easing;
}
}
}
function Animation( elem, properties, options ) {
var result,
stopped,
index = 0,
length = Animation.prefilters.length,
deferred = jQuery.Deferred().always( function() {
// Don't match elem in the :animated selector
delete tick.elem;
} ),
tick = function() {
if ( stopped ) {
return false;
}
var currentTime = fxNow || createFxNow(),
remaining = Math.max( 0, animation.startTime + animation.duration - currentTime ),
// Support: Android 2.3 only
// Archaic crash bug won't allow us to use `1 - ( 0.5 || 0 )` (#12497)
temp = remaining / animation.duration || 0,
percent = 1 - temp,
index = 0,
length = animation.tweens.length;
for ( ; index < length; index++ ) {
animation.tweens[ index ].run( percent );
}
deferred.notifyWith( elem, [ animation, percent, remaining ] );
// If there's more to do, yield
if ( percent < 1 && length ) {
return remaining;
}
// If this was an empty animation, synthesize a final progress notification
if ( !length ) {
deferred.notifyWith( elem, [ animation, 1, 0 ] );
}
// Resolve the animation and report its conclusion
deferred.resolveWith( elem, [ animation ] );
return false;
},
animation = deferred.promise( {
elem: elem,
props: jQuery.extend( {}, properties ),
opts: jQuery.extend( true, {
specialEasing: {},
easing: jQuery.easing._default
}, options ),
originalProperties: properties,
originalOptions: options,
startTime: fxNow || createFxNow(),
duration: options.duration,
tweens: [],
createTween: function( prop, end ) {
var tween = jQuery.Tween( elem, animation.opts, prop, end,
animation.opts.specialEasing[ prop ] || animation.opts.easing );
animation.tweens.push( tween );
return tween;
},
stop: function( gotoEnd ) {
var index = 0,
// If we are going to the end, we want to run all the tweens
// otherwise we skip this part
length = gotoEnd ? animation.tweens.length : 0;
if ( stopped ) {
return this;
}
stopped = true;
for ( ; index < length; index++ ) {
animation.tweens[ index ].run( 1 );
}
// Resolve when we played the last frame; otherwise, reject
if ( gotoEnd ) {
deferred.notifyWith( elem, [ animation, 1, 0 ] );
deferred.resolveWith( elem, [ animation, gotoEnd ] );
} else {
deferred.rejectWith( elem, [ animation, gotoEnd ] );
}
return this;
}
} ),
props = animation.props;
propFilter( props, animation.opts.specialEasing );
for ( ; index < length; index++ ) {
result = Animation.prefilters[ index ].call( animation, elem, props, animation.opts );
if ( result ) {
if ( jQuery.isFunction( result.stop ) ) {
jQuery._queueHooks( animation.elem, animation.opts.queue ).stop =
jQuery.proxy( result.stop, result );
}
return result;
}
}
jQuery.map( props, createTween, animation );
if ( jQuery.isFunction( animation.opts.start ) ) {
animation.opts.start.call( elem, animation );
}
// Attach callbacks from options
animation
.progress( animation.opts.progress )
.done( animation.opts.done, animation.opts.complete )
.fail( animation.opts.fail )
.always( animation.opts.always );
jQuery.fx.timer(
jQuery.extend( tick, {
elem: elem,
anim: animation,
queue: animation.opts.queue
} )
);
return animation;
}
jQuery.Animation = jQuery.extend( Animation, {
tweeners: {
"*": [ function( prop, value ) {
var tween = this.createTween( prop, value );
adjustCSS( tween.elem, prop, rcssNum.exec( value ), tween );
return tween;
} ]
},
tweener: function( props, callback ) {
if ( jQuery.isFunction( props ) ) {
callback = props;
props = [ "*" ];
} else {
props = props.match( rnothtmlwhite );
}
var prop,
index = 0,
length = props.length;
for ( ; index < length; index++ ) {
prop = props[ index ];
Animation.tweeners[ prop ] = Animation.tweeners[ prop ] || [];
Animation.tweeners[ prop ].unshift( callback );
}
},
prefilters: [ defaultPrefilter ],
prefilter: function( callback, prepend ) {
if ( prepend ) {
Animation.prefilters.unshift( callback );
} else {
Animation.prefilters.push( callback );
}
}
} );
jQuery.speed = function( speed, easing, fn ) {
var opt = speed && typeof speed === "object" ? jQuery.extend( {}, speed ) : {
complete: fn || !fn && easing ||
jQuery.isFunction( speed ) && speed,
duration: speed,
easing: fn && easing || easing && !jQuery.isFunction( easing ) && easing
};
// Go to the end state if fx are off
if ( jQuery.fx.off ) {
opt.duration = 0;
} else {
if ( typeof opt.duration !== "number" ) {
if ( opt.duration in jQuery.fx.speeds ) {
opt.duration = jQuery.fx.speeds[ opt.duration ];
} else {
opt.duration = jQuery.fx.speeds._default;
}
}
}
// Normalize opt.queue - true/undefined/null -> "fx"
if ( opt.queue == null || opt.queue === true ) {
opt.queue = "fx";
}
// Queueing
opt.old = opt.complete;
opt.complete = function() {
if ( jQuery.isFunction( opt.old ) ) {
opt.old.call( this );
}
if ( opt.queue ) {
jQuery.dequeue( this, opt.queue );
}
};
return opt;
};
jQuery.fn.extend( {
fadeTo: function( speed, to, easing, callback ) {
// Show any hidden elements after setting opacity to 0
return this.filter( isHiddenWithinTree ).css( "opacity", 0 ).show()
// Animate to the value specified
.end().animate( { opacity: to }, speed, easing, callback );
},
animate: function( prop, speed, easing, callback ) {
var empty = jQuery.isEmptyObject( prop ),
optall = jQuery.speed( speed, easing, callback ),
doAnimation = function() {
// Operate on a copy of prop so per-property easing won't be lost
var anim = Animation( this, jQuery.extend( {}, prop ), optall );
// Empty animations, or finishing resolves immediately
if ( empty || dataPriv.get( this, "finish" ) ) {
anim.stop( true );
}
};
doAnimation.finish = doAnimation;
return empty || optall.queue === false ?
this.each( doAnimation ) :
this.queue( optall.queue, doAnimation );
},
stop: function( type, clearQueue, gotoEnd ) {
var stopQueue = function( hooks ) {
var stop = hooks.stop;
delete hooks.stop;
stop( gotoEnd );
};
if ( typeof type !== "string" ) {
gotoEnd = clearQueue;
clearQueue = type;
type = undefined;
}
if ( clearQueue && type !== false ) {
this.queue( type || "fx", [] );
}
return this.each( function() {
var dequeue = true,
index = type != null && type + "queueHooks",
timers = jQuery.timers,
data = dataPriv.get( this );
if ( index ) {
if ( data[ index ] && data[ index ].stop ) {
stopQueue( data[ index ] );
}
} else {
for ( index in data ) {
if ( data[ index ] && data[ index ].stop && rrun.test( index ) ) {
stopQueue( data[ index ] );
}
}
}
for ( index = timers.length; index--; ) {
if ( timers[ index ].elem === this &&
( type == null || timers[ index ].queue === type ) ) {
timers[ index ].anim.stop( gotoEnd );
dequeue = false;
timers.splice( index, 1 );
}
}
// Start the next in the queue if the last step wasn't forced.
// Timers currently will call their complete callbacks, which
// will dequeue but only if they were gotoEnd.
if ( dequeue || !gotoEnd ) {
jQuery.dequeue( this, type );
}
} );
},
finish: function( type ) {
if ( type !== false ) {
type = type || "fx";
}
return this.each( function() {
var index,
data = dataPriv.get( this ),
queue = data[ type + "queue" ],
hooks = data[ type + "queueHooks" ],
timers = jQuery.timers,
length = queue ? queue.length : 0;
// Enable finishing flag on private data
data.finish = true;
// Empty the queue first
jQuery.queue( this, type, [] );
if ( hooks && hooks.stop ) {
hooks.stop.call( this, true );
}
// Look for any active animations, and finish them
for ( index = timers.length; index--; ) {
if ( timers[ index ].elem === this && timers[ index ].queue === type ) {
timers[ index ].anim.stop( true );
timers.splice( index, 1 );
}
}
// Look for any animations in the old queue and finish them
for ( index = 0; index < length; index++ ) {
if ( queue[ index ] && queue[ index ].finish ) {
queue[ index ].finish.call( this );
}
}
// Turn off finishing flag
delete data.finish;
} );
}
} );
jQuery.each( [ "toggle", "show", "hide" ], function( i, name ) {
var cssFn = jQuery.fn[ name ];
jQuery.fn[ name ] = function( speed, easing, callback ) {
return speed == null || typeof speed === "boolean" ?
cssFn.apply( this, arguments ) :
this.animate( genFx( name, true ), speed, easing, callback );
};
} );
// Generate shortcuts for custom animations
jQuery.each( {
slideDown: genFx( "show" ),
slideUp: genFx( "hide" ),
slideToggle: genFx( "toggle" ),
fadeIn: { opacity: "show" },
fadeOut: { opacity: "hide" },
fadeToggle: { opacity: "toggle" }
}, function( name, props ) {
jQuery.fn[ name ] = function( speed, easing, callback ) {
return this.animate( props, speed, easing, callback );
};
} );
jQuery.timers = [];
jQuery.fx.tick = function() {
var timer,
i = 0,
timers = jQuery.timers;
fxNow = jQuery.now();
for ( ; i < timers.length; i++ ) {
timer = timers[ i ];
// Run the timer and safely remove it when done (allowing for external removal)
if ( !timer() && timers[ i ] === timer ) {
timers.splice( i--, 1 );
}
}
if ( !timers.length ) {
jQuery.fx.stop();
}
fxNow = undefined;
};
jQuery.fx.timer = function( timer ) {
jQuery.timers.push( timer );
jQuery.fx.start();
};
jQuery.fx.interval = 13;
jQuery.fx.start = function() {
if ( inProgress ) {
return;
}
inProgress = true;
schedule();
};
jQuery.fx.stop = function() {
inProgress = null;
};
jQuery.fx.speeds = {
slow: 600,
fast: 200,
// Default speed
_default: 400
};
// Based off of the plugin by Clint Helfers, with permission.
// https://web.archive.org/web/20100324014747/http://blindsignals.com/index.php/2009/07/jquery-delay/
jQuery.fn.delay = function( time, type ) {
time = jQuery.fx ? jQuery.fx.speeds[ time ] || time : time;
type = type || "fx";
return this.queue( type, function( next, hooks ) {
var timeout = window.setTimeout( next, time );
hooks.stop = function() {
window.clearTimeout( timeout );
};
} );
};
( function() {
var input = document.createElement( "input" ),
select = document.createElement( "select" ),
opt = select.appendChild( document.createElement( "option" ) );
input.type = "checkbox";
// Support: Android <=4.3 only
// Default value for a checkbox should be "on"
support.checkOn = input.value !== "";
// Support: IE <=11 only
// Must access selectedIndex to make default options select
support.optSelected = opt.selected;
// Support: IE <=11 only
// An input loses its value after becoming a radio
input = document.createElement( "input" );
input.value = "t";
input.type = "radio";
support.radioValue = input.value === "t";
} )();
var boolHook,
attrHandle = jQuery.expr.attrHandle;
jQuery.fn.extend( {
attr: function( name, value ) {
return access( this, jQuery.attr, name, value, arguments.length > 1 );
},
removeAttr: function( name ) {
return this.each( function() {
jQuery.removeAttr( this, name );
} );
}
} );
jQuery.extend( {
attr: function( elem, name, value ) {
var ret, hooks,
nType = elem.nodeType;
// Don't get/set attributes on text, comment and attribute nodes
if ( nType === 3 || nType === 8 || nType === 2 ) {
return;
}
// Fallback to prop when attributes are not supported
if ( typeof elem.getAttribute === "undefined" ) {
return jQuery.prop( elem, name, value );
}
// Attribute hooks are determined by the lowercase version
// Grab necessary hook if one is defined
if ( nType !== 1 || !jQuery.isXMLDoc( elem ) ) {
hooks = jQuery.attrHooks[ name.toLowerCase() ] ||
( jQuery.expr.match.bool.test( name ) ? boolHook : undefined );
}
if ( value !== undefined ) {
if ( value === null ) {
jQuery.removeAttr( elem, name );
return;
}
if ( hooks && "set" in hooks &&
( ret = hooks.set( elem, value, name ) ) !== undefined ) {
return ret;
}
elem.setAttribute( name, value + "" );
return value;
}
if ( hooks && "get" in hooks && ( ret = hooks.get( elem, name ) ) !== null ) {
return ret;
}
ret = jQuery.find.attr( elem, name );
// Non-existent attributes return null, we normalize to undefined
return ret == null ? undefined : ret;
},
attrHooks: {
type: {
set: function( elem, value ) {
if ( !support.radioValue && value === "radio" &&
nodeName( elem, "input" ) ) {
var val = elem.value;
elem.setAttribute( "type", value );
if ( val ) {
elem.value = val;
}
return value;
}
}
}
},
removeAttr: function( elem, value ) {
var name,
i = 0,
// Attribute names can contain non-HTML whitespace characters
// https://html.spec.whatwg.org/multipage/syntax.html#attributes-2
attrNames = value && value.match( rnothtmlwhite );
if ( attrNames && elem.nodeType === 1 ) {
while ( ( name = attrNames[ i++ ] ) ) {
elem.removeAttribute( name );
}
}
}
} );
// Hooks for boolean attributes
boolHook = {
set: function( elem, value, name ) {
if ( value === false ) {
// Remove boolean attributes when set to false
jQuery.removeAttr( elem, name );
} else {
elem.setAttribute( name, name );
}
return name;
}
};
jQuery.each( jQuery.expr.match.bool.source.match( /\w+/g ), function( i, name ) {
var getter = attrHandle[ name ] || jQuery.find.attr;
attrHandle[ name ] = function( elem, name, isXML ) {
var ret, handle,
lowercaseName = name.toLowerCase();
if ( !isXML ) {
// Avoid an infinite loop by temporarily removing this function from the getter
handle = attrHandle[ lowercaseName ];
attrHandle[ lowercaseName ] = ret;
ret = getter( elem, name, isXML ) != null ?
lowercaseName :
null;
attrHandle[ lowercaseName ] = handle;
}
return ret;
};
} );
var rfocusable = /^(?:input|select|textarea|button)$/i,
rclickable = /^(?:a|area)$/i;
jQuery.fn.extend( {
prop: function( name, value ) {
return access( this, jQuery.prop, name, value, arguments.length > 1 );
},
removeProp: function( name ) {
return this.each( function() {
delete this[ jQuery.propFix[ name ] || name ];
} );
}
} );
jQuery.extend( {
prop: function( elem, name, value ) {
var ret, hooks,
nType = elem.nodeType;
// Don't get/set properties on text, comment and attribute nodes
if ( nType === 3 || nType === 8 || nType === 2 ) {
return;
}
if ( nType !== 1 || !jQuery.isXMLDoc( elem ) ) {
// Fix name and attach hooks
name = jQuery.propFix[ name ] || name;
hooks = jQuery.propHooks[ name ];
}
if ( value !== undefined ) {
if ( hooks && "set" in hooks &&
( ret = hooks.set( elem, value, name ) ) !== undefined ) {
return ret;
}
return ( elem[ name ] = value );
}
if ( hooks && "get" in hooks && ( ret = hooks.get( elem, name ) ) !== null ) {
return ret;
}
return elem[ name ];
},
propHooks: {
tabIndex: {
get: function( elem ) {
// Support: IE <=9 - 11 only
// elem.tabIndex doesn't always return the
// correct value when it hasn't been explicitly set
// https://web.archive.org/web/20141116233347/http://fluidproject.org/blog/2008/01/09/getting-setting-and-removing-tabindex-values-with-javascript/
// Use proper attribute retrieval(#12072)
var tabindex = jQuery.find.attr( elem, "tabindex" );
if ( tabindex ) {
return parseInt( tabindex, 10 );
}
if (
rfocusable.test( elem.nodeName ) ||
rclickable.test( elem.nodeName ) &&
elem.href
) {
return 0;
}
return -1;
}
}
},
propFix: {
"for": "htmlFor",
"class": "className"
}
} );
// Support: IE <=11 only
// Accessing the selectedIndex property
// forces the browser to respect setting selected
// on the option
// The getter ensures a default option is selected
// when in an optgroup
// eslint rule "no-unused-expressions" is disabled for this code
// since it considers such accessions noop
if ( !support.optSelected ) {
jQuery.propHooks.selected = {
get: function( elem ) {
/* eslint no-unused-expressions: "off" */
var parent = elem.parentNode;
if ( parent && parent.parentNode ) {
parent.parentNode.selectedIndex;
}
return null;
},
set: function( elem ) {
/* eslint no-unused-expressions: "off" */
var parent = elem.parentNode;
if ( parent ) {
parent.selectedIndex;
if ( parent.parentNode ) {
parent.parentNode.selectedIndex;
}
}
}
};
}
jQuery.each( [
"tabIndex",
"readOnly",
"maxLength",
"cellSpacing",
"cellPadding",
"rowSpan",
"colSpan",
"useMap",
"frameBorder",
"contentEditable"
], function() {
jQuery.propFix[ this.toLowerCase() ] = this;
} );
// Strip and collapse whitespace according to HTML spec
// https://html.spec.whatwg.org/multipage/infrastructure.html#strip-and-collapse-whitespace
function stripAndCollapse( value ) {
var tokens = value.match( rnothtmlwhite ) || [];
return tokens.join( " " );
}
function getClass( elem ) {
return elem.getAttribute && elem.getAttribute( "class" ) || "";
}
jQuery.fn.extend( {
addClass: function( value ) {
var classes, elem, cur, curValue, clazz, j, finalValue,
i = 0;
if ( jQuery.isFunction( value ) ) {
return this.each( function( j ) {
jQuery( this ).addClass( value.call( this, j, getClass( this ) ) );
} );
}
if ( typeof value === "string" && value ) {
classes = value.match( rnothtmlwhite ) || [];
while ( ( elem = this[ i++ ] ) ) {
curValue = getClass( elem );
cur = elem.nodeType === 1 && ( " " + stripAndCollapse( curValue ) + " " );
if ( cur ) {
j = 0;
while ( ( clazz = classes[ j++ ] ) ) {
if ( cur.indexOf( " " + clazz + " " ) < 0 ) {
cur += clazz + " ";
}
}
// Only assign if different to avoid unneeded rendering.
finalValue = stripAndCollapse( cur );
if ( curValue !== finalValue ) {
elem.setAttribute( "class", finalValue );
}
}
}
}
return this;
},
removeClass: function( value ) {
var classes, elem, cur, curValue, clazz, j, finalValue,
i = 0;
if ( jQuery.isFunction( value ) ) {
return this.each( function( j ) {
jQuery( this ).removeClass( value.call( this, j, getClass( this ) ) );
} );
}
if ( !arguments.length ) {
return this.attr( "class", "" );
}
if ( typeof value === "string" && value ) {
classes = value.match( rnothtmlwhite ) || [];
while ( ( elem = this[ i++ ] ) ) {
curValue = getClass( elem );
// This expression is here for better compressibility (see addClass)
cur = elem.nodeType === 1 && ( " " + stripAndCollapse( curValue ) + " " );
if ( cur ) {
j = 0;
while ( ( clazz = classes[ j++ ] ) ) {
// Remove *all* instances
while ( cur.indexOf( " " + clazz + " " ) > -1 ) {
cur = cur.replace( " " + clazz + " ", " " );
}
}
// Only assign if different to avoid unneeded rendering.
finalValue = stripAndCollapse( cur );
if ( curValue !== finalValue ) {
elem.setAttribute( "class", finalValue );
}
}
}
}
return this;
},
toggleClass: function( value, stateVal ) {
var type = typeof value;
if ( typeof stateVal === "boolean" && type === "string" ) {
return stateVal ? this.addClass( value ) : this.removeClass( value );
}
if ( jQuery.isFunction( value ) ) {
return this.each( function( i ) {
jQuery( this ).toggleClass(
value.call( this, i, getClass( this ), stateVal ),
stateVal
);
} );
}
return this.each( function() {
var className, i, self, classNames;
if ( type === "string" ) {
// Toggle individual class names
i = 0;
self = jQuery( this );
classNames = value.match( rnothtmlwhite ) || [];
while ( ( className = classNames[ i++ ] ) ) {
// Check each className given, space separated list
if ( self.hasClass( className ) ) {
self.removeClass( className );
} else {
self.addClass( className );
}
}
// Toggle whole class name
} else if ( value === undefined || type === "boolean" ) {
className = getClass( this );
if ( className ) {
// Store className if set
dataPriv.set( this, "__className__", className );
}
// If the element has a class name or if we're passed `false`,
// then remove the whole classname (if there was one, the above saved it).
// Otherwise bring back whatever was previously saved (if anything),
// falling back to the empty string if nothing was stored.
if ( this.setAttribute ) {
this.setAttribute( "class",
className || value === false ?
"" :
dataPriv.get( this, "__className__" ) || ""
);
}
}
} );
},
hasClass: function( selector ) {
var className, elem,
i = 0;
className = " " + selector + " ";
while ( ( elem = this[ i++ ] ) ) {
if ( elem.nodeType === 1 &&
( " " + stripAndCollapse( getClass( elem ) ) + " " ).indexOf( className ) > -1 ) {
return true;
}
}
return false;
}
} );
var rreturn = /\r/g;
jQuery.fn.extend( {
val: function( value ) {
var hooks, ret, isFunction,
elem = this[ 0 ];
if ( !arguments.length ) {
if ( elem ) {
hooks = jQuery.valHooks[ elem.type ] ||
jQuery.valHooks[ elem.nodeName.toLowerCase() ];
if ( hooks &&
"get" in hooks &&
( ret = hooks.get( elem, "value" ) ) !== undefined
) {
return ret;
}
ret = elem.value;
// Handle most common string cases
if ( typeof ret === "string" ) {
return ret.replace( rreturn, "" );
}
// Handle cases where value is null/undef or number
return ret == null ? "" : ret;
}
return;
}
isFunction = jQuery.isFunction( value );
return this.each( function( i ) {
var val;
if ( this.nodeType !== 1 ) {
return;
}
if ( isFunction ) {
val = value.call( this, i, jQuery( this ).val() );
} else {
val = value;
}
// Treat null/undefined as ""; convert numbers to string
if ( val == null ) {
val = "";
} else if ( typeof val === "number" ) {
val += "";
} else if ( Array.isArray( val ) ) {
val = jQuery.map( val, function( value ) {
return value == null ? "" : value + "";
} );
}
hooks = jQuery.valHooks[ this.type ] || jQuery.valHooks[ this.nodeName.toLowerCase() ];
// If set returns undefined, fall back to normal setting
if ( !hooks || !( "set" in hooks ) || hooks.set( this, val, "value" ) === undefined ) {
this.value = val;
}
} );
}
} );
jQuery.extend( {
valHooks: {
option: {
get: function( elem ) {
var val = jQuery.find.attr( elem, "value" );
return val != null ?
val :
// Support: IE <=10 - 11 only
// option.text throws exceptions (#14686, #14858)
// Strip and collapse whitespace
// https://html.spec.whatwg.org/#strip-and-collapse-whitespace
stripAndCollapse( jQuery.text( elem ) );
}
},
select: {
get: function( elem ) {
var value, option, i,
options = elem.options,
index = elem.selectedIndex,
one = elem.type === "select-one",
values = one ? null : [],
max = one ? index + 1 : options.length;
if ( index < 0 ) {
i = max;
} else {
i = one ? index : 0;
}
// Loop through all the selected options
for ( ; i < max; i++ ) {
option = options[ i ];
// Support: IE <=9 only
// IE8-9 doesn't update selected after form reset (#2551)
if ( ( option.selected || i === index ) &&
// Don't return options that are disabled or in a disabled optgroup
!option.disabled &&
( !option.parentNode.disabled ||
!nodeName( option.parentNode, "optgroup" ) ) ) {
// Get the specific value for the option
value = jQuery( option ).val();
// We don't need an array for one selects
if ( one ) {
return value;
}
// Multi-Selects return an array
values.push( value );
}
}
return values;
},
set: function( elem, value ) {
var optionSet, option,
options = elem.options,
values = jQuery.makeArray( value ),
i = options.length;
while ( i-- ) {
option = options[ i ];
/* eslint-disable no-cond-assign */
if ( option.selected =
jQuery.inArray( jQuery.valHooks.option.get( option ), values ) > -1
) {
optionSet = true;
}
/* eslint-enable no-cond-assign */
}
// Force browsers to behave consistently when non-matching value is set
if ( !optionSet ) {
elem.selectedIndex = -1;
}
return values;
}
}
}
} );
// Radios and checkboxes getter/setter
jQuery.each( [ "radio", "checkbox" ], function() {
jQuery.valHooks[ this ] = {
set: function( elem, value ) {
if ( Array.isArray( value ) ) {
return ( elem.checked = jQuery.inArray( jQuery( elem ).val(), value ) > -1 );
}
}
};
if ( !support.checkOn ) {
jQuery.valHooks[ this ].get = function( elem ) {
return elem.getAttribute( "value" ) === null ? "on" : elem.value;
};
}
} );
// Return jQuery for attributes-only inclusion
var rfocusMorph = /^(?:focusinfocus|focusoutblur)$/;
jQuery.extend( jQuery.event, {
trigger: function( event, data, elem, onlyHandlers ) {
var i, cur, tmp, bubbleType, ontype, handle, special,
eventPath = [ elem || document ],
type = hasOwn.call( event, "type" ) ? event.type : event,
namespaces = hasOwn.call( event, "namespace" ) ? event.namespace.split( "." ) : [];
cur = tmp = elem = elem || document;
// Don't do events on text and comment nodes
if ( elem.nodeType === 3 || elem.nodeType === 8 ) {
return;
}
// focus/blur morphs to focusin/out; ensure we're not firing them right now
if ( rfocusMorph.test( type + jQuery.event.triggered ) ) {
return;
}
if ( type.indexOf( "." ) > -1 ) {
// Namespaced trigger; create a regexp to match event type in handle()
namespaces = type.split( "." );
type = namespaces.shift();
namespaces.sort();
}
ontype = type.indexOf( ":" ) < 0 && "on" + type;
// Caller can pass in a jQuery.Event object, Object, or just an event type string
event = event[ jQuery.expando ] ?
event :
new jQuery.Event( type, typeof event === "object" && event );
// Trigger bitmask: & 1 for native handlers; & 2 for jQuery (always true)
event.isTrigger = onlyHandlers ? 2 : 3;
event.namespace = namespaces.join( "." );
event.rnamespace = event.namespace ?
new RegExp( "(^|\\.)" + namespaces.join( "\\.(?:.*\\.|)" ) + "(\\.|$)" ) :
null;
// Clean up the event in case it is being reused
event.result = undefined;
if ( !event.target ) {
event.target = elem;
}
// Clone any incoming data and prepend the event, creating the handler arg list
data = data == null ?
[ event ] :
jQuery.makeArray( data, [ event ] );
// Allow special events to draw outside the lines
special = jQuery.event.special[ type ] || {};
if ( !onlyHandlers && special.trigger && special.trigger.apply( elem, data ) === false ) {
return;
}
// Determine event propagation path in advance, per W3C events spec (#9951)
// Bubble up to document, then to window; watch for a global ownerDocument var (#9724)
if ( !onlyHandlers && !special.noBubble && !jQuery.isWindow( elem ) ) {
bubbleType = special.delegateType || type;
if ( !rfocusMorph.test( bubbleType + type ) ) {
cur = cur.parentNode;
}
for ( ; cur; cur = cur.parentNode ) {
eventPath.push( cur );
tmp = cur;
}
// Only add window if we got to document (e.g., not plain obj or detached DOM)
if ( tmp === ( elem.ownerDocument || document ) ) {
eventPath.push( tmp.defaultView || tmp.parentWindow || window );
}
}
// Fire handlers on the event path
i = 0;
while ( ( cur = eventPath[ i++ ] ) && !event.isPropagationStopped() ) {
event.type = i > 1 ?
bubbleType :
special.bindType || type;
// jQuery handler
handle = ( dataPriv.get( cur, "events" ) || {} )[ event.type ] &&
dataPriv.get( cur, "handle" );
if ( handle ) {
handle.apply( cur, data );
}
// Native handler
handle = ontype && cur[ ontype ];
if ( handle && handle.apply && acceptData( cur ) ) {
event.result = handle.apply( cur, data );
if ( event.result === false ) {
event.preventDefault();
}
}
}
event.type = type;
// If nobody prevented the default action, do it now
if ( !onlyHandlers && !event.isDefaultPrevented() ) {
if ( ( !special._default ||
special._default.apply( eventPath.pop(), data ) === false ) &&
acceptData( elem ) ) {
// Call a native DOM method on the target with the same name as the event.
// Don't do default actions on window, that's where global variables be (#6170)
if ( ontype && jQuery.isFunction( elem[ type ] ) && !jQuery.isWindow( elem ) ) {
// Don't re-trigger an onFOO event when we call its FOO() method
tmp = elem[ ontype ];
if ( tmp ) {
elem[ ontype ] = null;
}
// Prevent re-triggering of the same event, since we already bubbled it above
jQuery.event.triggered = type;
elem[ type ]();
jQuery.event.triggered = undefined;
if ( tmp ) {
elem[ ontype ] = tmp;
}
}
}
}
return event.result;
},
// Piggyback on a donor event to simulate a different one
// Used only for `focus(in | out)` events
simulate: function( type, elem, event ) {
var e = jQuery.extend(
new jQuery.Event(),
event,
{
type: type,
isSimulated: true
}
);
jQuery.event.trigger( e, null, elem );
}
} );
jQuery.fn.extend( {
trigger: function( type, data ) {
return this.each( function() {
jQuery.event.trigger( type, data, this );
} );
},
triggerHandler: function( type, data ) {
var elem = this[ 0 ];
if ( elem ) {
return jQuery.event.trigger( type, data, elem, true );
}
}
} );
jQuery.each( ( "blur focus focusin focusout resize scroll click dblclick " +
"mousedown mouseup mousemove mouseover mouseout mouseenter mouseleave " +
"change select submit keydown keypress keyup contextmenu" ).split( " " ),
function( i, name ) {
// Handle event binding
jQuery.fn[ name ] = function( data, fn ) {
return arguments.length > 0 ?
this.on( name, null, data, fn ) :
this.trigger( name );
};
} );
jQuery.fn.extend( {
hover: function( fnOver, fnOut ) {
return this.mouseenter( fnOver ).mouseleave( fnOut || fnOver );
}
} );
support.focusin = "onfocusin" in window;
// Support: Firefox <=44
// Firefox doesn't have focus(in | out) events
// Related ticket - https://bugzilla.mozilla.org/show_bug.cgi?id=687787
//
// Support: Chrome <=48 - 49, Safari <=9.0 - 9.1
// focus(in | out) events fire after focus & blur events,
// which is spec violation - http://www.w3.org/TR/DOM-Level-3-Events/#events-focusevent-event-order
// Related ticket - https://bugs.chromium.org/p/chromium/issues/detail?id=449857
if ( !support.focusin ) {
jQuery.each( { focus: "focusin", blur: "focusout" }, function( orig, fix ) {
// Attach a single capturing handler on the document while someone wants focusin/focusout
var handler = function( event ) {
jQuery.event.simulate( fix, event.target, jQuery.event.fix( event ) );
};
jQuery.event.special[ fix ] = {
setup: function() {
var doc = this.ownerDocument || this,
attaches = dataPriv.access( doc, fix );
if ( !attaches ) {
doc.addEventListener( orig, handler, true );
}
dataPriv.access( doc, fix, ( attaches || 0 ) + 1 );
},
teardown: function() {
var doc = this.ownerDocument || this,
attaches = dataPriv.access( doc, fix ) - 1;
if ( !attaches ) {
doc.removeEventListener( orig, handler, true );
dataPriv.remove( doc, fix );
} else {
dataPriv.access( doc, fix, attaches );
}
}
};
} );
}
var location = window.location;
var nonce = jQuery.now();
var rquery = ( /\?/ );
// Cross-browser xml parsing
jQuery.parseXML = function( data ) {
var xml;
if ( !data || typeof data !== "string" ) {
return null;
}
// Support: IE 9 - 11 only
// IE throws on parseFromString with invalid input.
try {
xml = ( new window.DOMParser() ).parseFromString( data, "text/xml" );
} catch ( e ) {
xml = undefined;
}
if ( !xml || xml.getElementsByTagName( "parsererror" ).length ) {
jQuery.error( "Invalid XML: " + data );
}
return xml;
};
var
rbracket = /\[\]$/,
rCRLF = /\r?\n/g,
rsubmitterTypes = /^(?:submit|button|image|reset|file)$/i,
rsubmittable = /^(?:input|select|textarea|keygen)/i;
function buildParams( prefix, obj, traditional, add ) {
var name;
if ( Array.isArray( obj ) ) {
// Serialize array item.
jQuery.each( obj, function( i, v ) {
if ( traditional || rbracket.test( prefix ) ) {
// Treat each array item as a scalar.
add( prefix, v );
} else {
// Item is non-scalar (array or object), encode its numeric index.
buildParams(
prefix + "[" + ( typeof v === "object" && v != null ? i : "" ) + "]",
v,
traditional,
add
);
}
} );
} else if ( !traditional && jQuery.type( obj ) === "object" ) {
// Serialize object item.
for ( name in obj ) {
buildParams( prefix + "[" + name + "]", obj[ name ], traditional, add );
}
} else {
// Serialize scalar item.
add( prefix, obj );
}
}
// Serialize an array of form elements or a set of
// key/values into a query string
jQuery.param = function( a, traditional ) {
var prefix,
s = [],
add = function( key, valueOrFunction ) {
// If value is a function, invoke it and use its return value
var value = jQuery.isFunction( valueOrFunction ) ?
valueOrFunction() :
valueOrFunction;
s[ s.length ] = encodeURIComponent( key ) + "=" +
encodeURIComponent( value == null ? "" : value );
};
// If an array was passed in, assume that it is an array of form elements.
if ( Array.isArray( a ) || ( a.jquery && !jQuery.isPlainObject( a ) ) ) {
// Serialize the form elements
jQuery.each( a, function() {
add( this.name, this.value );
} );
} else {
// If traditional, encode the "old" way (the way 1.3.2 or older
// did it), otherwise encode params recursively.
for ( prefix in a ) {
buildParams( prefix, a[ prefix ], traditional, add );
}
}
// Return the resulting serialization
return s.join( "&" );
};
jQuery.fn.extend( {
serialize: function() {
return jQuery.param( this.serializeArray() );
},
serializeArray: function() {
return this.map( function() {
// Can add propHook for "elements" to filter or add form elements
var elements = jQuery.prop( this, "elements" );
return elements ? jQuery.makeArray( elements ) : this;
} )
.filter( function() {
var type = this.type;
// Use .is( ":disabled" ) so that fieldset[disabled] works
return this.name && !jQuery( this ).is( ":disabled" ) &&
rsubmittable.test( this.nodeName ) && !rsubmitterTypes.test( type ) &&
( this.checked || !rcheckableType.test( type ) );
} )
.map( function( i, elem ) {
var val = jQuery( this ).val();
if ( val == null ) {
return null;
}
if ( Array.isArray( val ) ) {
return jQuery.map( val, function( val ) {
return { name: elem.name, value: val.replace( rCRLF, "\r\n" ) };
} );
}
return { name: elem.name, value: val.replace( rCRLF, "\r\n" ) };
} ).get();
}
} );
var
r20 = /%20/g,
rhash = /#.*$/,
rantiCache = /([?&])_=[^&]*/,
rheaders = /^(.*?):[ \t]*([^\r\n]*)$/mg,
// #7653, #8125, #8152: local protocol detection
rlocalProtocol = /^(?:about|app|app-storage|.+-extension|file|res|widget):$/,
rnoContent = /^(?:GET|HEAD)$/,
rprotocol = /^\/\//,
/* Prefilters
* 1) They are useful to introduce custom dataTypes (see ajax/jsonp.js for an example)
* 2) These are called:
* - BEFORE asking for a transport
* - AFTER param serialization (s.data is a string if s.processData is true)
* 3) key is the dataType
* 4) the catchall symbol "*" can be used
* 5) execution will start with transport dataType and THEN continue down to "*" if needed
*/
prefilters = {},
/* Transports bindings
* 1) key is the dataType
* 2) the catchall symbol "*" can be used
* 3) selection will start with transport dataType and THEN go to "*" if needed
*/
transports = {},
// Avoid comment-prolog char sequence (#10098); must appease lint and evade compression
allTypes = "*/".concat( "*" ),
// Anchor tag for parsing the document origin
originAnchor = document.createElement( "a" );
originAnchor.href = location.href;
// Base "constructor" for jQuery.ajaxPrefilter and jQuery.ajaxTransport
function addToPrefiltersOrTransports( structure ) {
// dataTypeExpression is optional and defaults to "*"
return function( dataTypeExpression, func ) {
if ( typeof dataTypeExpression !== "string" ) {
func = dataTypeExpression;
dataTypeExpression = "*";
}
var dataType,
i = 0,
dataTypes = dataTypeExpression.toLowerCase().match( rnothtmlwhite ) || [];
if ( jQuery.isFunction( func ) ) {
// For each dataType in the dataTypeExpression
while ( ( dataType = dataTypes[ i++ ] ) ) {
// Prepend if requested
if ( dataType[ 0 ] === "+" ) {
dataType = dataType.slice( 1 ) || "*";
( structure[ dataType ] = structure[ dataType ] || [] ).unshift( func );
// Otherwise append
} else {
( structure[ dataType ] = structure[ dataType ] || [] ).push( func );
}
}
}
};
}
// Base inspection function for prefilters and transports
function inspectPrefiltersOrTransports( structure, options, originalOptions, jqXHR ) {
var inspected = {},
seekingTransport = ( structure === transports );
function inspect( dataType ) {
var selected;
inspected[ dataType ] = true;
jQuery.each( structure[ dataType ] || [], function( _, prefilterOrFactory ) {
var dataTypeOrTransport = prefilterOrFactory( options, originalOptions, jqXHR );
if ( typeof dataTypeOrTransport === "string" &&
!seekingTransport && !inspected[ dataTypeOrTransport ] ) {
options.dataTypes.unshift( dataTypeOrTransport );
inspect( dataTypeOrTransport );
return false;
} else if ( seekingTransport ) {
return !( selected = dataTypeOrTransport );
}
} );
return selected;
}
return inspect( options.dataTypes[ 0 ] ) || !inspected[ "*" ] && inspect( "*" );
}
// A special extend for ajax options
// that takes "flat" options (not to be deep extended)
// Fixes #9887
function ajaxExtend( target, src ) {
var key, deep,
flatOptions = jQuery.ajaxSettings.flatOptions || {};
for ( key in src ) {
if ( src[ key ] !== undefined ) {
( flatOptions[ key ] ? target : ( deep || ( deep = {} ) ) )[ key ] = src[ key ];
}
}
if ( deep ) {
jQuery.extend( true, target, deep );
}
return target;
}
/* Handles responses to an ajax request:
* - finds the right dataType (mediates between content-type and expected dataType)
* - returns the corresponding response
*/
function ajaxHandleResponses( s, jqXHR, responses ) {
var ct, type, finalDataType, firstDataType,
contents = s.contents,
dataTypes = s.dataTypes;
// Remove auto dataType and get content-type in the process
while ( dataTypes[ 0 ] === "*" ) {
dataTypes.shift();
if ( ct === undefined ) {
ct = s.mimeType || jqXHR.getResponseHeader( "Content-Type" );
}
}
// Check if we're dealing with a known content-type
if ( ct ) {
for ( type in contents ) {
if ( contents[ type ] && contents[ type ].test( ct ) ) {
dataTypes.unshift( type );
break;
}
}
}
// Check to see if we have a response for the expected dataType
if ( dataTypes[ 0 ] in responses ) {
finalDataType = dataTypes[ 0 ];
} else {
// Try convertible dataTypes
for ( type in responses ) {
if ( !dataTypes[ 0 ] || s.converters[ type + " " + dataTypes[ 0 ] ] ) {
finalDataType = type;
break;
}
if ( !firstDataType ) {
firstDataType = type;
}
}
// Or just use first one
finalDataType = finalDataType || firstDataType;
}
// If we found a dataType
// We add the dataType to the list if needed
// and return the corresponding response
if ( finalDataType ) {
if ( finalDataType !== dataTypes[ 0 ] ) {
dataTypes.unshift( finalDataType );
}
return responses[ finalDataType ];
}
}
/* Chain conversions given the request and the original response
* Also sets the responseXXX fields on the jqXHR instance
*/
function ajaxConvert( s, response, jqXHR, isSuccess ) {
var conv2, current, conv, tmp, prev,
converters = {},
// Work with a copy of dataTypes in case we need to modify it for conversion
dataTypes = s.dataTypes.slice();
// Create converters map with lowercased keys
if ( dataTypes[ 1 ] ) {
for ( conv in s.converters ) {
converters[ conv.toLowerCase() ] = s.converters[ conv ];
}
}
current = dataTypes.shift();
// Convert to each sequential dataType
while ( current ) {
if ( s.responseFields[ current ] ) {
jqXHR[ s.responseFields[ current ] ] = response;
}
// Apply the dataFilter if provided
if ( !prev && isSuccess && s.dataFilter ) {
response = s.dataFilter( response, s.dataType );
}
prev = current;
current = dataTypes.shift();
if ( current ) {
// There's only work to do if current dataType is non-auto
if ( current === "*" ) {
current = prev;
// Convert response if prev dataType is non-auto and differs from current
} else if ( prev !== "*" && prev !== current ) {
// Seek a direct converter
conv = converters[ prev + " " + current ] || converters[ "* " + current ];
// If none found, seek a pair
if ( !conv ) {
for ( conv2 in converters ) {
// If conv2 outputs current
tmp = conv2.split( " " );
if ( tmp[ 1 ] === current ) {
// If prev can be converted to accepted input
conv = converters[ prev + " " + tmp[ 0 ] ] ||
converters[ "* " + tmp[ 0 ] ];
if ( conv ) {
// Condense equivalence converters
if ( conv === true ) {
conv = converters[ conv2 ];
// Otherwise, insert the intermediate dataType
} else if ( converters[ conv2 ] !== true ) {
current = tmp[ 0 ];
dataTypes.unshift( tmp[ 1 ] );
}
break;
}
}
}
}
// Apply converter (if not an equivalence)
if ( conv !== true ) {
// Unless errors are allowed to bubble, catch and return them
if ( conv && s.throws ) {
response = conv( response );
} else {
try {
response = conv( response );
} catch ( e ) {
return {
state: "parsererror",
error: conv ? e : "No conversion from " + prev + " to " + current
};
}
}
}
}
}
}
return { state: "success", data: response };
}
jQuery.extend( {
// Counter for holding the number of active queries
active: 0,
// Last-Modified header cache for next request
lastModified: {},
etag: {},
ajaxSettings: {
url: location.href,
type: "GET",
isLocal: rlocalProtocol.test( location.protocol ),
global: true,
processData: true,
async: true,
contentType: "application/x-www-form-urlencoded; charset=UTF-8",
/*
timeout: 0,
data: null,
dataType: null,
username: null,
password: null,
cache: null,
throws: false,
traditional: false,
headers: {},
*/
accepts: {
"*": allTypes,
text: "text/plain",
html: "text/html",
xml: "application/xml, text/xml",
json: "application/json, text/javascript"
},
contents: {
xml: /\bxml\b/,
html: /\bhtml/,
json: /\bjson\b/
},
responseFields: {
xml: "responseXML",
text: "responseText",
json: "responseJSON"
},
// Data converters
// Keys separate source (or catchall "*") and destination types with a single space
converters: {
// Convert anything to text
"* text": String,
// Text to html (true = no transformation)
"text html": true,
// Evaluate text as a json expression
"text json": JSON.parse,
// Parse text as xml
"text xml": jQuery.parseXML
},
// For options that shouldn't be deep extended:
// you can add your own custom options here if
// and when you create one that shouldn't be
// deep extended (see ajaxExtend)
flatOptions: {
url: true,
context: true
}
},
// Creates a full fledged settings object into target
// with both ajaxSettings and settings fields.
// If target is omitted, writes into ajaxSettings.
ajaxSetup: function( target, settings ) {
return settings ?
// Building a settings object
ajaxExtend( ajaxExtend( target, jQuery.ajaxSettings ), settings ) :
// Extending ajaxSettings
ajaxExtend( jQuery.ajaxSettings, target );
},
ajaxPrefilter: addToPrefiltersOrTransports( prefilters ),
ajaxTransport: addToPrefiltersOrTransports( transports ),
// Main method
ajax: function( url, options ) {
// If url is an object, simulate pre-1.5 signature
if ( typeof url === "object" ) {
options = url;
url = undefined;
}
// Force options to be an object
options = options || {};
var transport,
// URL without anti-cache param
cacheURL,
// Response headers
responseHeadersString,
responseHeaders,
// timeout handle
timeoutTimer,
// Url cleanup var
urlAnchor,
// Request state (becomes false upon send and true upon completion)
completed,
// To know if global events are to be dispatched
fireGlobals,
// Loop variable
i,
// uncached part of the url
uncached,
// Create the final options object
s = jQuery.ajaxSetup( {}, options ),
// Callbacks context
callbackContext = s.context || s,
// Context for global events is callbackContext if it is a DOM node or jQuery collection
globalEventContext = s.context &&
( callbackContext.nodeType || callbackContext.jquery ) ?
jQuery( callbackContext ) :
jQuery.event,
// Deferreds
deferred = jQuery.Deferred(),
completeDeferred = jQuery.Callbacks( "once memory" ),
// Status-dependent callbacks
statusCode = s.statusCode || {},
// Headers (they are sent all at once)
requestHeaders = {},
requestHeadersNames = {},
// Default abort message
strAbort = "canceled",
// Fake xhr
jqXHR = {
readyState: 0,
// Builds headers hashtable if needed
getResponseHeader: function( key ) {
var match;
if ( completed ) {
if ( !responseHeaders ) {
responseHeaders = {};
while ( ( match = rheaders.exec( responseHeadersString ) ) ) {
responseHeaders[ match[ 1 ].toLowerCase() ] = match[ 2 ];
}
}
match = responseHeaders[ key.toLowerCase() ];
}
return match == null ? null : match;
},
// Raw string
getAllResponseHeaders: function() {
return completed ? responseHeadersString : null;
},
// Caches the header
setRequestHeader: function( name, value ) {
if ( completed == null ) {
name = requestHeadersNames[ name.toLowerCase() ] =
requestHeadersNames[ name.toLowerCase() ] || name;
requestHeaders[ name ] = value;
}
return this;
},
// Overrides response content-type header
overrideMimeType: function( type ) {
if ( completed == null ) {
s.mimeType = type;
}
return this;
},
// Status-dependent callbacks
statusCode: function( map ) {
var code;
if ( map ) {
if ( completed ) {
// Execute the appropriate callbacks
jqXHR.always( map[ jqXHR.status ] );
} else {
// Lazy-add the new callbacks in a way that preserves old ones
for ( code in map ) {
statusCode[ code ] = [ statusCode[ code ], map[ code ] ];
}
}
}
return this;
},
// Cancel the request
abort: function( statusText ) {
var finalText = statusText || strAbort;
if ( transport ) {
transport.abort( finalText );
}
done( 0, finalText );
return this;
}
};
// Attach deferreds
deferred.promise( jqXHR );
// Add protocol if not provided (prefilters might expect it)
// Handle falsy url in the settings object (#10093: consistency with old signature)
// We also use the url parameter if available
s.url = ( ( url || s.url || location.href ) + "" )
.replace( rprotocol, location.protocol + "//" );
// Alias method option to type as per ticket #12004
s.type = options.method || options.type || s.method || s.type;
// Extract dataTypes list
s.dataTypes = ( s.dataType || "*" ).toLowerCase().match( rnothtmlwhite ) || [ "" ];
// A cross-domain request is in order when the origin doesn't match the current origin.
if ( s.crossDomain == null ) {
urlAnchor = document.createElement( "a" );
// Support: IE <=8 - 11, Edge 12 - 13
// IE throws exception on accessing the href property if url is malformed,
// e.g. http://example.com:80x/
try {
urlAnchor.href = s.url;
// Support: IE <=8 - 11 only
// Anchor's host property isn't correctly set when s.url is relative
urlAnchor.href = urlAnchor.href;
s.crossDomain = originAnchor.protocol + "//" + originAnchor.host !==
urlAnchor.protocol + "//" + urlAnchor.host;
} catch ( e ) {
// If there is an error parsing the URL, assume it is crossDomain,
// it can be rejected by the transport if it is invalid
s.crossDomain = true;
}
}
// Convert data if not already a string
if ( s.data && s.processData && typeof s.data !== "string" ) {
s.data = jQuery.param( s.data, s.traditional );
}
// Apply prefilters
inspectPrefiltersOrTransports( prefilters, s, options, jqXHR );
// If request was aborted inside a prefilter, stop there
if ( completed ) {
return jqXHR;
}
// We can fire global events as of now if asked to
// Don't fire events if jQuery.event is undefined in an AMD-usage scenario (#15118)
fireGlobals = jQuery.event && s.global;
// Watch for a new set of requests
if ( fireGlobals && jQuery.active++ === 0 ) {
jQuery.event.trigger( "ajaxStart" );
}
// Uppercase the type
s.type = s.type.toUpperCase();
// Determine if request has content
s.hasContent = !rnoContent.test( s.type );
// Save the URL in case we're toying with the If-Modified-Since
// and/or If-None-Match header later on
// Remove hash to simplify url manipulation
cacheURL = s.url.replace( rhash, "" );
// More options handling for requests with no content
if ( !s.hasContent ) {
// Remember the hash so we can put it back
uncached = s.url.slice( cacheURL.length );
// If data is available, append data to url
if ( s.data ) {
cacheURL += ( rquery.test( cacheURL ) ? "&" : "?" ) + s.data;
// #9682: remove data so that it's not used in an eventual retry
delete s.data;
}
// Add or update anti-cache param if needed
if ( s.cache === false ) {
cacheURL = cacheURL.replace( rantiCache, "$1" );
uncached = ( rquery.test( cacheURL ) ? "&" : "?" ) + "_=" + ( nonce++ ) + uncached;
}
// Put hash and anti-cache on the URL that will be requested (gh-1732)
s.url = cacheURL + uncached;
// Change '%20' to '+' if this is encoded form body content (gh-2658)
} else if ( s.data && s.processData &&
( s.contentType || "" ).indexOf( "application/x-www-form-urlencoded" ) === 0 ) {
s.data = s.data.replace( r20, "+" );
}
// Set the If-Modified-Since and/or If-None-Match header, if in ifModified mode.
if ( s.ifModified ) {
if ( jQuery.lastModified[ cacheURL ] ) {
jqXHR.setRequestHeader( "If-Modified-Since", jQuery.lastModified[ cacheURL ] );
}
if ( jQuery.etag[ cacheURL ] ) {
jqXHR.setRequestHeader( "If-None-Match", jQuery.etag[ cacheURL ] );
}
}
// Set the correct header, if data is being sent
if ( s.data && s.hasContent && s.contentType !== false || options.contentType ) {
jqXHR.setRequestHeader( "Content-Type", s.contentType );
}
// Set the Accepts header for the server, depending on the dataType
jqXHR.setRequestHeader(
"Accept",
s.dataTypes[ 0 ] && s.accepts[ s.dataTypes[ 0 ] ] ?
s.accepts[ s.dataTypes[ 0 ] ] +
( s.dataTypes[ 0 ] !== "*" ? ", " + allTypes + "; q=0.01" : "" ) :
s.accepts[ "*" ]
);
// Check for headers option
for ( i in s.headers ) {
jqXHR.setRequestHeader( i, s.headers[ i ] );
}
// Allow custom headers/mimetypes and early abort
if ( s.beforeSend &&
( s.beforeSend.call( callbackContext, jqXHR, s ) === false || completed ) ) {
// Abort if not done already and return
return jqXHR.abort();
}
// Aborting is no longer a cancellation
strAbort = "abort";
// Install callbacks on deferreds
completeDeferred.add( s.complete );
jqXHR.done( s.success );
jqXHR.fail( s.error );
// Get transport
transport = inspectPrefiltersOrTransports( transports, s, options, jqXHR );
// If no transport, we auto-abort
if ( !transport ) {
done( -1, "No Transport" );
} else {
jqXHR.readyState = 1;
// Send global event
if ( fireGlobals ) {
globalEventContext.trigger( "ajaxSend", [ jqXHR, s ] );
}
// If request was aborted inside ajaxSend, stop there
if ( completed ) {
return jqXHR;
}
// Timeout
if ( s.async && s.timeout > 0 ) {
timeoutTimer = window.setTimeout( function() {
jqXHR.abort( "timeout" );
}, s.timeout );
}
try {
completed = false;
transport.send( requestHeaders, done );
} catch ( e ) {
// Rethrow post-completion exceptions
if ( completed ) {
throw e;
}
// Propagate others as results
done( -1, e );
}
}
// Callback for when everything is done
function done( status, nativeStatusText, responses, headers ) {
var isSuccess, success, error, response, modified,
statusText = nativeStatusText;
// Ignore repeat invocations
if ( completed ) {
return;
}
completed = true;
// Clear timeout if it exists
if ( timeoutTimer ) {
window.clearTimeout( timeoutTimer );
}
// Dereference transport for early garbage collection
// (no matter how long the jqXHR object will be used)
transport = undefined;
// Cache response headers
responseHeadersString = headers || "";
// Set readyState
jqXHR.readyState = status > 0 ? 4 : 0;
// Determine if successful
isSuccess = status >= 200 && status < 300 || status === 304;
// Get response data
if ( responses ) {
response = ajaxHandleResponses( s, jqXHR, responses );
}
// Convert no matter what (that way responseXXX fields are always set)
response = ajaxConvert( s, response, jqXHR, isSuccess );
// If successful, handle type chaining
if ( isSuccess ) {
// Set the If-Modified-Since and/or If-None-Match header, if in ifModified mode.
if ( s.ifModified ) {
modified = jqXHR.getResponseHeader( "Last-Modified" );
if ( modified ) {
jQuery.lastModified[ cacheURL ] = modified;
}
modified = jqXHR.getResponseHeader( "etag" );
if ( modified ) {
jQuery.etag[ cacheURL ] = modified;
}
}
// if no content
if ( status === 204 || s.type === "HEAD" ) {
statusText = "nocontent";
// if not modified
} else if ( status === 304 ) {
statusText = "notmodified";
// If we have data, let's convert it
} else {
statusText = response.state;
success = response.data;
error = response.error;
isSuccess = !error;
}
} else {
// Extract error from statusText and normalize for non-aborts
error = statusText;
if ( status || !statusText ) {
statusText = "error";
if ( status < 0 ) {
status = 0;
}
}
}
// Set data for the fake xhr object
jqXHR.status = status;
jqXHR.statusText = ( nativeStatusText || statusText ) + "";
// Success/Error
if ( isSuccess ) {
deferred.resolveWith( callbackContext, [ success, statusText, jqXHR ] );
} else {
deferred.rejectWith( callbackContext, [ jqXHR, statusText, error ] );
}
// Status-dependent callbacks
jqXHR.statusCode( statusCode );
statusCode = undefined;
if ( fireGlobals ) {
globalEventContext.trigger( isSuccess ? "ajaxSuccess" : "ajaxError",
[ jqXHR, s, isSuccess ? success : error ] );
}
// Complete
completeDeferred.fireWith( callbackContext, [ jqXHR, statusText ] );
if ( fireGlobals ) {
globalEventContext.trigger( "ajaxComplete", [ jqXHR, s ] );
// Handle the global AJAX counter
if ( !( --jQuery.active ) ) {
jQuery.event.trigger( "ajaxStop" );
}
}
}
return jqXHR;
},
getJSON: function( url, data, callback ) {
return jQuery.get( url, data, callback, "json" );
},
getScript: function( url, callback ) {
return jQuery.get( url, undefined, callback, "script" );
}
} );
jQuery.each( [ "get", "post" ], function( i, method ) {
jQuery[ method ] = function( url, data, callback, type ) {
// Shift arguments if data argument was omitted
if ( jQuery.isFunction( data ) ) {
type = type || callback;
callback = data;
data = undefined;
}
// The url can be an options object (which then must have .url)
return jQuery.ajax( jQuery.extend( {
url: url,
type: method,
dataType: type,
data: data,
success: callback
}, jQuery.isPlainObject( url ) && url ) );
};
} );
jQuery._evalUrl = function( url ) {
return jQuery.ajax( {
url: url,
// Make this explicit, since user can override this through ajaxSetup (#11264)
type: "GET",
dataType: "script",
cache: true,
async: false,
global: false,
"throws": true
} );
};
jQuery.fn.extend( {
wrapAll: function( html ) {
var wrap;
if ( this[ 0 ] ) {
if ( jQuery.isFunction( html ) ) {
html = html.call( this[ 0 ] );
}
// The elements to wrap the target around
wrap = jQuery( html, this[ 0 ].ownerDocument ).eq( 0 ).clone( true );
if ( this[ 0 ].parentNode ) {
wrap.insertBefore( this[ 0 ] );
}
wrap.map( function() {
var elem = this;
while ( elem.firstElementChild ) {
elem = elem.firstElementChild;
}
return elem;
} ).append( this );
}
return this;
},
wrapInner: function( html ) {
if ( jQuery.isFunction( html ) ) {
return this.each( function( i ) {
jQuery( this ).wrapInner( html.call( this, i ) );
} );
}
return this.each( function() {
var self = jQuery( this ),
contents = self.contents();
if ( contents.length ) {
contents.wrapAll( html );
} else {
self.append( html );
}
} );
},
wrap: function( html ) {
var isFunction = jQuery.isFunction( html );
return this.each( function( i ) {
jQuery( this ).wrapAll( isFunction ? html.call( this, i ) : html );
} );
},
unwrap: function( selector ) {
this.parent( selector ).not( "body" ).each( function() {
jQuery( this ).replaceWith( this.childNodes );
} );
return this;
}
} );
jQuery.expr.pseudos.hidden = function( elem ) {
return !jQuery.expr.pseudos.visible( elem );
};
jQuery.expr.pseudos.visible = function( elem ) {
return !!( elem.offsetWidth || elem.offsetHeight || elem.getClientRects().length );
};
jQuery.ajaxSettings.xhr = function() {
try {
return new window.XMLHttpRequest();
} catch ( e ) {}
};
var xhrSuccessStatus = {
// File protocol always yields status code 0, assume 200
0: 200,
// Support: IE <=9 only
// #1450: sometimes IE returns 1223 when it should be 204
1223: 204
},
xhrSupported = jQuery.ajaxSettings.xhr();
support.cors = !!xhrSupported && ( "withCredentials" in xhrSupported );
support.ajax = xhrSupported = !!xhrSupported;
jQuery.ajaxTransport( function( options ) {
var callback, errorCallback;
// Cross domain only allowed if supported through XMLHttpRequest
if ( support.cors || xhrSupported && !options.crossDomain ) {
return {
send: function( headers, complete ) {
var i,
xhr = options.xhr();
xhr.open(
options.type,
options.url,
options.async,
options.username,
options.password
);
// Apply custom fields if provided
if ( options.xhrFields ) {
for ( i in options.xhrFields ) {
xhr[ i ] = options.xhrFields[ i ];
}
}
// Override mime type if needed
if ( options.mimeType && xhr.overrideMimeType ) {
xhr.overrideMimeType( options.mimeType );
}
// X-Requested-With header
// For cross-domain requests, seeing as conditions for a preflight are
// akin to a jigsaw puzzle, we simply never set it to be sure.
// (it can always be set on a per-request basis or even using ajaxSetup)
// For same-domain requests, won't change header if already provided.
if ( !options.crossDomain && !headers[ "X-Requested-With" ] ) {
headers[ "X-Requested-With" ] = "XMLHttpRequest";
}
// Set headers
for ( i in headers ) {
xhr.setRequestHeader( i, headers[ i ] );
}
// Callback
callback = function( type ) {
return function() {
if ( callback ) {
callback = errorCallback = xhr.onload =
xhr.onerror = xhr.onabort = xhr.onreadystatechange = null;
if ( type === "abort" ) {
xhr.abort();
} else if ( type === "error" ) {
// Support: IE <=9 only
// On a manual native abort, IE9 throws
// errors on any property access that is not readyState
if ( typeof xhr.status !== "number" ) {
complete( 0, "error" );
} else {
complete(
// File: protocol always yields status 0; see #8605, #14207
xhr.status,
xhr.statusText
);
}
} else {
complete(
xhrSuccessStatus[ xhr.status ] || xhr.status,
xhr.statusText,
// Support: IE <=9 only
// IE9 has no XHR2 but throws on binary (trac-11426)
// For XHR2 non-text, let the caller handle it (gh-2498)
( xhr.responseType || "text" ) !== "text" ||
typeof xhr.responseText !== "string" ?
{ binary: xhr.response } :
{ text: xhr.responseText },
xhr.getAllResponseHeaders()
);
}
}
};
};
// Listen to events
xhr.onload = callback();
errorCallback = xhr.onerror = callback( "error" );
// Support: IE 9 only
// Use onreadystatechange to replace onabort
// to handle uncaught aborts
if ( xhr.onabort !== undefined ) {
xhr.onabort = errorCallback;
} else {
xhr.onreadystatechange = function() {
// Check readyState before timeout as it changes
if ( xhr.readyState === 4 ) {
// Allow onerror to be called first,
// but that will not handle a native abort
// Also, save errorCallback to a variable
// as xhr.onerror cannot be accessed
window.setTimeout( function() {
if ( callback ) {
errorCallback();
}
} );
}
};
}
// Create the abort callback
callback = callback( "abort" );
try {
// Do send the request (this may raise an exception)
xhr.send( options.hasContent && options.data || null );
} catch ( e ) {
// #14683: Only rethrow if this hasn't been notified as an error yet
if ( callback ) {
throw e;
}
}
},
abort: function() {
if ( callback ) {
callback();
}
}
};
}
} );
// Prevent auto-execution of scripts when no explicit dataType was provided (See gh-2432)
jQuery.ajaxPrefilter( function( s ) {
if ( s.crossDomain ) {
s.contents.script = false;
}
} );
// Install script dataType
jQuery.ajaxSetup( {
accepts: {
script: "text/javascript, application/javascript, " +
"application/ecmascript, application/x-ecmascript"
},
contents: {
script: /\b(?:java|ecma)script\b/
},
converters: {
"text script": function( text ) {
jQuery.globalEval( text );
return text;
}
}
} );
// Handle cache's special case and crossDomain
jQuery.ajaxPrefilter( "script", function( s ) {
if ( s.cache === undefined ) {
s.cache = false;
}
if ( s.crossDomain ) {
s.type = "GET";
}
} );
// Bind script tag hack transport
jQuery.ajaxTransport( "script", function( s ) {
// This transport only deals with cross domain requests
if ( s.crossDomain ) {
var script, callback;
return {
send: function( _, complete ) {
script = jQuery( "<script>" ).prop( {
charset: s.scriptCharset,
src: s.url
} ).on(
"load error",
callback = function( evt ) {
script.remove();
callback = null;
if ( evt ) {
complete( evt.type === "error" ? 404 : 200, evt.type );
}
}
);
// Use native DOM manipulation to avoid our domManip AJAX trickery
document.head.appendChild( script[ 0 ] );
},
abort: function() {
if ( callback ) {
callback();
}
}
};
}
} );
var oldCallbacks = [],
rjsonp = /(=)\?(?=&|$)|\?\?/;
// Default jsonp settings
jQuery.ajaxSetup( {
jsonp: "callback",
jsonpCallback: function() {
var callback = oldCallbacks.pop() || ( jQuery.expando + "_" + ( nonce++ ) );
this[ callback ] = true;
return callback;
}
} );
// Detect, normalize options and install callbacks for jsonp requests
jQuery.ajaxPrefilter( "json jsonp", function( s, originalSettings, jqXHR ) {
var callbackName, overwritten, responseContainer,
jsonProp = s.jsonp !== false && ( rjsonp.test( s.url ) ?
"url" :
typeof s.data === "string" &&
( s.contentType || "" )
.indexOf( "application/x-www-form-urlencoded" ) === 0 &&
rjsonp.test( s.data ) && "data"
);
// Handle iff the expected data type is "jsonp" or we have a parameter to set
if ( jsonProp || s.dataTypes[ 0 ] === "jsonp" ) {
// Get callback name, remembering preexisting value associated with it
callbackName = s.jsonpCallback = jQuery.isFunction( s.jsonpCallback ) ?
s.jsonpCallback() :
s.jsonpCallback;
// Insert callback into url or form data
if ( jsonProp ) {
s[ jsonProp ] = s[ jsonProp ].replace( rjsonp, "$1" + callbackName );
} else if ( s.jsonp !== false ) {
s.url += ( rquery.test( s.url ) ? "&" : "?" ) + s.jsonp + "=" + callbackName;
}
// Use data converter to retrieve json after script execution
s.converters[ "script json" ] = function() {
if ( !responseContainer ) {
jQuery.error( callbackName + " was not called" );
}
return responseContainer[ 0 ];
};
// Force json dataType
s.dataTypes[ 0 ] = "json";
// Install callback
overwritten = window[ callbackName ];
window[ callbackName ] = function() {
responseContainer = arguments;
};
// Clean-up function (fires after converters)
jqXHR.always( function() {
// If previous value didn't exist - remove it
if ( overwritten === undefined ) {
jQuery( window ).removeProp( callbackName );
// Otherwise restore preexisting value
} else {
window[ callbackName ] = overwritten;
}
// Save back as free
if ( s[ callbackName ] ) {
// Make sure that re-using the options doesn't screw things around
s.jsonpCallback = originalSettings.jsonpCallback;
// Save the callback name for future use
oldCallbacks.push( callbackName );
}
// Call if it was a function and we have a response
if ( responseContainer && jQuery.isFunction( overwritten ) ) {
overwritten( responseContainer[ 0 ] );
}
responseContainer = overwritten = undefined;
} );
// Delegate to script
return "script";
}
} );
// Support: Safari 8 only
// In Safari 8 documents created via document.implementation.createHTMLDocument
// collapse sibling forms: the second one becomes a child of the first one.
// Because of that, this security measure has to be disabled in Safari 8.
// https://bugs.webkit.org/show_bug.cgi?id=137337
support.createHTMLDocument = ( function() {
var body = document.implementation.createHTMLDocument( "" ).body;
body.innerHTML = "<form></form><form></form>";
return body.childNodes.length === 2;
} )();
// Argument "data" should be string of html
// context (optional): If specified, the fragment will be created in this context,
// defaults to document
// keepScripts (optional): If true, will include scripts passed in the html string
jQuery.parseHTML = function( data, context, keepScripts ) {
if ( typeof data !== "string" ) {
return [];
}
if ( typeof context === "boolean" ) {
keepScripts = context;
context = false;
}
var base, parsed, scripts;
if ( !context ) {
// Stop scripts or inline event handlers from being executed immediately
// by using document.implementation
if ( support.createHTMLDocument ) {
context = document.implementation.createHTMLDocument( "" );
// Set the base href for the created document
// so any parsed elements with URLs
// are based on the document's URL (gh-2965)
base = context.createElement( "base" );
base.href = document.location.href;
context.head.appendChild( base );
} else {
context = document;
}
}
parsed = rsingleTag.exec( data );
scripts = !keepScripts && [];
// Single tag
if ( parsed ) {
return [ context.createElement( parsed[ 1 ] ) ];
}
parsed = buildFragment( [ data ], context, scripts );
if ( scripts && scripts.length ) {
jQuery( scripts ).remove();
}
return jQuery.merge( [], parsed.childNodes );
};
/**
* Load a url into a page
*/
jQuery.fn.load = function( url, params, callback ) {
var selector, type, response,
self = this,
off = url.indexOf( " " );
if ( off > -1 ) {
selector = stripAndCollapse( url.slice( off ) );
url = url.slice( 0, off );
}
// If it's a function
if ( jQuery.isFunction( params ) ) {
// We assume that it's the callback
callback = params;
params = undefined;
// Otherwise, build a param string
} else if ( params && typeof params === "object" ) {
type = "POST";
}
// If we have elements to modify, make the request
if ( self.length > 0 ) {
jQuery.ajax( {
url: url,
// If "type" variable is undefined, then "GET" method will be used.
// Make value of this field explicit since
// user can override it through ajaxSetup method
type: type || "GET",
dataType: "html",
data: params
} ).done( function( responseText ) {
// Save response for use in complete callback
response = arguments;
self.html( selector ?
// If a selector was specified, locate the right elements in a dummy div
// Exclude scripts to avoid IE 'Permission Denied' errors
jQuery( "<div>" ).append( jQuery.parseHTML( responseText ) ).find( selector ) :
// Otherwise use the full result
responseText );
// If the request succeeds, this function gets "data", "status", "jqXHR"
// but they are ignored because response was set above.
// If it fails, this function gets "jqXHR", "status", "error"
} ).always( callback && function( jqXHR, status ) {
self.each( function() {
callback.apply( this, response || [ jqXHR.responseText, status, jqXHR ] );
} );
} );
}
return this;
};
// Attach a bunch of functions for handling common AJAX events
jQuery.each( [
"ajaxStart",
"ajaxStop",
"ajaxComplete",
"ajaxError",
"ajaxSuccess",
"ajaxSend"
], function( i, type ) {
jQuery.fn[ type ] = function( fn ) {
return this.on( type, fn );
};
} );
jQuery.expr.pseudos.animated = function( elem ) {
return jQuery.grep( jQuery.timers, function( fn ) {
return elem === fn.elem;
} ).length;
};
jQuery.offset = {
setOffset: function( elem, options, i ) {
var curPosition, curLeft, curCSSTop, curTop, curOffset, curCSSLeft, calculatePosition,
position = jQuery.css( elem, "position" ),
curElem = jQuery( elem ),
props = {};
// Set position first, in-case top/left are set even on static elem
if ( position === "static" ) {
elem.style.position = "relative";
}
curOffset = curElem.offset();
curCSSTop = jQuery.css( elem, "top" );
curCSSLeft = jQuery.css( elem, "left" );
calculatePosition = ( position === "absolute" || position === "fixed" ) &&
( curCSSTop + curCSSLeft ).indexOf( "auto" ) > -1;
// Need to be able to calculate position if either
// top or left is auto and position is either absolute or fixed
if ( calculatePosition ) {
curPosition = curElem.position();
curTop = curPosition.top;
curLeft = curPosition.left;
} else {
curTop = parseFloat( curCSSTop ) || 0;
curLeft = parseFloat( curCSSLeft ) || 0;
}
if ( jQuery.isFunction( options ) ) {
// Use jQuery.extend here to allow modification of coordinates argument (gh-1848)
options = options.call( elem, i, jQuery.extend( {}, curOffset ) );
}
if ( options.top != null ) {
props.top = ( options.top - curOffset.top ) + curTop;
}
if ( options.left != null ) {
props.left = ( options.left - curOffset.left ) + curLeft;
}
if ( "using" in options ) {
options.using.call( elem, props );
} else {
curElem.css( props );
}
}
};
jQuery.fn.extend( {
offset: function( options ) {
// Preserve chaining for setter
if ( arguments.length ) {
return options === undefined ?
this :
this.each( function( i ) {
jQuery.offset.setOffset( this, options, i );
} );
}
var doc, docElem, rect, win,
elem = this[ 0 ];
if ( !elem ) {
return;
}
// Return zeros for disconnected and hidden (display: none) elements (gh-2310)
// Support: IE <=11 only
// Running getBoundingClientRect on a
// disconnected node in IE throws an error
if ( !elem.getClientRects().length ) {
return { top: 0, left: 0 };
}
rect = elem.getBoundingClientRect();
doc = elem.ownerDocument;
docElem = doc.documentElement;
win = doc.defaultView;
return {
top: rect.top + win.pageYOffset - docElem.clientTop,
left: rect.left + win.pageXOffset - docElem.clientLeft
};
},
position: function() {
if ( !this[ 0 ] ) {
return;
}
var offsetParent, offset,
elem = this[ 0 ],
parentOffset = { top: 0, left: 0 };
// Fixed elements are offset from window (parentOffset = {top:0, left: 0},
// because it is its only offset parent
if ( jQuery.css( elem, "position" ) === "fixed" ) {
// Assume getBoundingClientRect is there when computed position is fixed
offset = elem.getBoundingClientRect();
} else {
// Get *real* offsetParent
offsetParent = this.offsetParent();
// Get correct offsets
offset = this.offset();
if ( !nodeName( offsetParent[ 0 ], "html" ) ) {
parentOffset = offsetParent.offset();
}
// Add offsetParent borders
parentOffset = {
top: parentOffset.top + jQuery.css( offsetParent[ 0 ], "borderTopWidth", true ),
left: parentOffset.left + jQuery.css( offsetParent[ 0 ], "borderLeftWidth", true )
};
}
// Subtract parent offsets and element margins
return {
top: offset.top - parentOffset.top - jQuery.css( elem, "marginTop", true ),
left: offset.left - parentOffset.left - jQuery.css( elem, "marginLeft", true )
};
},
// This method will return documentElement in the following cases:
// 1) For the element inside the iframe without offsetParent, this method will return
// documentElement of the parent window
// 2) For the hidden or detached element
// 3) For body or html element, i.e. in case of the html node - it will return itself
//
// but those exceptions were never presented as a real life use-cases
// and might be considered as more preferable results.
//
// This logic, however, is not guaranteed and can change at any point in the future
offsetParent: function() {
return this.map( function() {
var offsetParent = this.offsetParent;
while ( offsetParent && jQuery.css( offsetParent, "position" ) === "static" ) {
offsetParent = offsetParent.offsetParent;
}
return offsetParent || documentElement;
} );
}
} );
// Create scrollLeft and scrollTop methods
jQuery.each( { scrollLeft: "pageXOffset", scrollTop: "pageYOffset" }, function( method, prop ) {
var top = "pageYOffset" === prop;
jQuery.fn[ method ] = function( val ) {
return access( this, function( elem, method, val ) {
// Coalesce documents and windows
var win;
if ( jQuery.isWindow( elem ) ) {
win = elem;
} else if ( elem.nodeType === 9 ) {
win = elem.defaultView;
}
if ( val === undefined ) {
return win ? win[ prop ] : elem[ method ];
}
if ( win ) {
win.scrollTo(
!top ? val : win.pageXOffset,
top ? val : win.pageYOffset
);
} else {
elem[ method ] = val;
}
}, method, val, arguments.length );
};
} );
// Support: Safari <=7 - 9.1, Chrome <=37 - 49
// Add the top/left cssHooks using jQuery.fn.position
// Webkit bug: https://bugs.webkit.org/show_bug.cgi?id=29084
// Blink bug: https://bugs.chromium.org/p/chromium/issues/detail?id=589347
// getComputedStyle returns percent when specified for top/left/bottom/right;
// rather than make the css module depend on the offset module, just check for it here
jQuery.each( [ "top", "left" ], function( i, prop ) {
jQuery.cssHooks[ prop ] = addGetHookIf( support.pixelPosition,
function( elem, computed ) {
if ( computed ) {
computed = curCSS( elem, prop );
// If curCSS returns percentage, fallback to offset
return rnumnonpx.test( computed ) ?
jQuery( elem ).position()[ prop ] + "px" :
computed;
}
}
);
} );
// Create innerHeight, innerWidth, height, width, outerHeight and outerWidth methods
jQuery.each( { Height: "height", Width: "width" }, function( name, type ) {
jQuery.each( { padding: "inner" + name, content: type, "": "outer" + name },
function( defaultExtra, funcName ) {
// Margin is only for outerHeight, outerWidth
jQuery.fn[ funcName ] = function( margin, value ) {
var chainable = arguments.length && ( defaultExtra || typeof margin !== "boolean" ),
extra = defaultExtra || ( margin === true || value === true ? "margin" : "border" );
return access( this, function( elem, type, value ) {
var doc;
if ( jQuery.isWindow( elem ) ) {
// $( window ).outerWidth/Height return w/h including scrollbars (gh-1729)
return funcName.indexOf( "outer" ) === 0 ?
elem[ "inner" + name ] :
elem.document.documentElement[ "client" + name ];
}
// Get document width or height
if ( elem.nodeType === 9 ) {
doc = elem.documentElement;
// Either scroll[Width/Height] or offset[Width/Height] or client[Width/Height],
// whichever is greatest
return Math.max(
elem.body[ "scroll" + name ], doc[ "scroll" + name ],
elem.body[ "offset" + name ], doc[ "offset" + name ],
doc[ "client" + name ]
);
}
return value === undefined ?
// Get width or height on the element, requesting but not forcing parseFloat
jQuery.css( elem, type, extra ) :
// Set width or height on the element
jQuery.style( elem, type, value, extra );
}, type, chainable ? margin : undefined, chainable );
};
} );
} );
jQuery.fn.extend( {
bind: function( types, data, fn ) {
return this.on( types, null, data, fn );
},
unbind: function( types, fn ) {
return this.off( types, null, fn );
},
delegate: function( selector, types, data, fn ) {
return this.on( types, selector, data, fn );
},
undelegate: function( selector, types, fn ) {
// ( namespace ) or ( selector, types [, fn] )
return arguments.length === 1 ?
this.off( selector, "**" ) :
this.off( types, selector || "**", fn );
}
} );
jQuery.holdReady = function( hold ) {
if ( hold ) {
jQuery.readyWait++;
} else {
jQuery.ready( true );
}
};
jQuery.isArray = Array.isArray;
jQuery.parseJSON = JSON.parse;
jQuery.nodeName = nodeName;
// Register as a named AMD module, since jQuery can be concatenated with other
// files that may use define, but not via a proper concatenation script that
// understands anonymous AMD modules. A named AMD is safest and most robust
// way to register. Lowercase jquery is used because AMD module names are
// derived from file names, and jQuery is normally delivered in a lowercase
// file name. Do this after creating the global so that if an AMD module wants
// to call noConflict to hide this version of jQuery, it will work.
// Note that for maximum portability, libraries that are not jQuery should
// declare themselves as anonymous modules, and avoid setting a global if an
// AMD loader is present. jQuery is a special case. For more information, see
// https://github.com/jrburke/requirejs/wiki/Updating-existing-libraries#wiki-anon
if ( typeof define === "function" && define.amd ) {
define( "jquery", [], function() {
return jQuery;
} );
}
var
// Map over jQuery in case of overwrite
_jQuery = window.jQuery,
// Map over the $ in case of overwrite
_$ = window.$;
jQuery.noConflict = function( deep ) {
if ( window.$ === jQuery ) {
window.$ = _$;
}
if ( deep && window.jQuery === jQuery ) {
window.jQuery = _jQuery;
}
return jQuery;
};
// Expose jQuery and $ identifiers, even in AMD
// (#7102#comment:10, https://github.com/jquery/jquery/pull/557)
// and CommonJS for browser emulators (#13566)
if ( !noGlobal ) {
window.jQuery = window.$ = jQuery;
}
return jQuery;
} );
PK
%�\)��R �R html/_static/jquery.jsnu �[��� /*! jQuery v3.2.1 | (c) JS Foundation and other contributors | jquery.org/license */
!function(a,b){"use strict";"object"==typeof module&&"object"==typeof module.exports?module.exports=a.document?b(a,!0):function(a){if(!a.document)throw new Error("jQuery requires a window with a document");return b(a)}:b(a)}("undefined"!=typeof window?window:this,function(a,b){"use strict";var c=[],d=a.document,e=Object.getPrototypeOf,f=c.slice,g=c.concat,h=c.push,i=c.indexOf,j={},k=j.toString,l=j.hasOwnProperty,m=l.toString,n=m.call(Object),o={};function p(a,b){b=b||d;var c=b.createElement("script");c.text=a,b.head.appendChild(c).parentNode.removeChild(c)}var q="3.2.1",r=function(a,b){return new r.fn.init(a,b)},s=/^[\s\uFEFF\xA0]+|[\s\uFEFF\xA0]+$/g,t=/^-ms-/,u=/-([a-z])/g,v=function(a,b){return b.toUpperCase()};r.fn=r.prototype={jquery:q,constructor:r,length:0,toArray:function(){return f.call(this)},get:function(a){return null==a?f.call(this):a<0?this[a+this.length]:this[a]},pushStack:function(a){var b=r.merge(this.constructor(),a);return b.prevObject=this,b},each:function(a){return r.each(this,a)},map:function(a){return this.pushStack(r.map(this,function(b,c){return a.call(b,c,b)}))},slice:function(){return this.pushStack(f.apply(this,arguments))},first:function(){return this.eq(0)},last:function(){return this.eq(-1)},eq:function(a){var b=this.length,c=+a+(a<0?b:0);return this.pushStack(c>=0&&c<b?[this[c]]:[])},end:function(){return this.prevObject||this.constructor()},push:h,sort:c.sort,splice:c.splice},r.extend=r.fn.extend=function(){var a,b,c,d,e,f,g=arguments[0]||{},h=1,i=arguments.length,j=!1;for("boolean"==typeof g&&(j=g,g=arguments[h]||{},h++),"object"==typeof g||r.isFunction(g)||(g={}),h===i&&(g=this,h--);h<i;h++)if(null!=(a=arguments[h]))for(b in a)c=g[b],d=a[b],g!==d&&(j&&d&&(r.isPlainObject(d)||(e=Array.isArray(d)))?(e?(e=!1,f=c&&Array.isArray(c)?c:[]):f=c&&r.isPlainObject(c)?c:{},g[b]=r.extend(j,f,d)):void 0!==d&&(g[b]=d));return g},r.extend({expando:"jQuery"+(q+Math.random()).replace(/\D/g,""),isReady:!0,error:function(a){throw new Error(a)},noop:function(){},isFunction:function(a){return"function"===r.type(a)},isWindow:function(a){return null!=a&&a===a.window},isNumeric:function(a){var b=r.type(a);return("number"===b||"string"===b)&&!isNaN(a-parseFloat(a))},isPlainObject:function(a){var b,c;return!(!a||"[object Object]"!==k.call(a))&&(!(b=e(a))||(c=l.call(b,"constructor")&&b.constructor,"function"==typeof c&&m.call(c)===n))},isEmptyObject:function(a){var b;for(b in a)return!1;return!0},type:function(a){return null==a?a+"":"object"==typeof a||"function"==typeof a?j[k.call(a)]||"object":typeof a},globalEval:function(a){p(a)},camelCase:function(a){return a.replace(t,"ms-").replace(u,v)},each:function(a,b){var c,d=0;if(w(a)){for(c=a.length;d<c;d++)if(b.call(a[d],d,a[d])===!1)break}else for(d in a)if(b.call(a[d],d,a[d])===!1)break;return a},trim:function(a){return null==a?"":(a+"").replace(s,"")},makeArray:function(a,b){var c=b||[];return null!=a&&(w(Object(a))?r.merge(c,"string"==typeof a?[a]:a):h.call(c,a)),c},inArray:function(a,b,c){return null==b?-1:i.call(b,a,c)},merge:function(a,b){for(var c=+b.length,d=0,e=a.length;d<c;d++)a[e++]=b[d];return a.length=e,a},grep:function(a,b,c){for(var d,e=[],f=0,g=a.length,h=!c;f<g;f++)d=!b(a[f],f),d!==h&&e.push(a[f]);return e},map:function(a,b,c){var d,e,f=0,h=[];if(w(a))for(d=a.length;f<d;f++)e=b(a[f],f,c),null!=e&&h.push(e);else for(f in a)e=b(a[f],f,c),null!=e&&h.push(e);return g.apply([],h)},guid:1,proxy:function(a,b){var c,d,e;if("string"==typeof b&&(c=a[b],b=a,a=c),r.isFunction(a))return d=f.call(arguments,2),e=function(){return a.apply(b||this,d.concat(f.call(arguments)))},e.guid=a.guid=a.guid||r.guid++,e},now:Date.now,support:o}),"function"==typeof Symbol&&(r.fn[Symbol.iterator]=c[Symbol.iterator]),r.each("Boolean Number String Function Array Date RegExp Object Error Symbol".split(" "),function(a,b){j["[object "+b+"]"]=b.toLowerCase()});function w(a){var b=!!a&&"length"in a&&a.length,c=r.type(a);return"function"!==c&&!r.isWindow(a)&&("array"===c||0===b||"number"==typeof b&&b>0&&b-1 in a)}var x=function(a){var b,c,d,e,f,g,h,i,j,k,l,m,n,o,p,q,r,s,t,u="sizzle"+1*new Date,v=a.document,w=0,x=0,y=ha(),z=ha(),A=ha(),B=function(a,b){return a===b&&(l=!0),0},C={}.hasOwnProperty,D=[],E=D.pop,F=D.push,G=D.push,H=D.slice,I=function(a,b){for(var c=0,d=a.length;c<d;c++)if(a[c]===b)return c;return-1},J="checked|selected|async|autofocus|autoplay|controls|defer|disabled|hidden|ismap|loop|multiple|open|readonly|required|scoped",K="[\\x20\\t\\r\\n\\f]",L="(?:\\\\.|[\\w-]|[^\0-\\xa0])+",M="\\["+K+"*("+L+")(?:"+K+"*([*^$|!~]?=)"+K+"*(?:'((?:\\\\.|[^\\\\'])*)'|\"((?:\\\\.|[^\\\\\"])*)\"|("+L+"))|)"+K+"*\\]",N=":("+L+")(?:\\((('((?:\\\\.|[^\\\\'])*)'|\"((?:\\\\.|[^\\\\\"])*)\")|((?:\\\\.|[^\\\\()[\\]]|"+M+")*)|.*)\\)|)",O=new RegExp(K+"+","g"),P=new RegExp("^"+K+"+|((?:^|[^\\\\])(?:\\\\.)*)"+K+"+$","g"),Q=new RegExp("^"+K+"*,"+K+"*"),R=new RegExp("^"+K+"*([>+~]|"+K+")"+K+"*"),S=new RegExp("="+K+"*([^\\]'\"]*?)"+K+"*\\]","g"),T=new RegExp(N),U=new RegExp("^"+L+"$"),V={ID:new RegExp("^#("+L+")"),CLASS:new RegExp("^\\.("+L+")"),TAG:new RegExp("^("+L+"|[*])"),ATTR:new RegExp("^"+M),PSEUDO:new RegExp("^"+N),CHILD:new RegExp("^:(only|first|last|nth|nth-last)-(child|of-type)(?:\\("+K+"*(even|odd|(([+-]|)(\\d*)n|)"+K+"*(?:([+-]|)"+K+"*(\\d+)|))"+K+"*\\)|)","i"),bool:new RegExp("^(?:"+J+")$","i"),needsContext:new RegExp("^"+K+"*[>+~]|:(even|odd|eq|gt|lt|nth|first|last)(?:\\("+K+"*((?:-\\d)?\\d*)"+K+"*\\)|)(?=[^-]|$)","i")},W=/^(?:input|select|textarea|button)$/i,X=/^h\d$/i,Y=/^[^{]+\{\s*\[native \w/,Z=/^(?:#([\w-]+)|(\w+)|\.([\w-]+))$/,$=/[+~]/,_=new RegExp("\\\\([\\da-f]{1,6}"+K+"?|("+K+")|.)","ig"),aa=function(a,b,c){var d="0x"+b-65536;return d!==d||c?b:d<0?String.fromCharCode(d+65536):String.fromCharCode(d>>10|55296,1023&d|56320)},ba=/([\0-\x1f\x7f]|^-?\d)|^-$|[^\0-\x1f\x7f-\uFFFF\w-]/g,ca=function(a,b){return b?"\0"===a?"\ufffd":a.slice(0,-1)+"\\"+a.charCodeAt(a.length-1).toString(16)+" ":"\\"+a},da=function(){m()},ea=ta(function(a){return a.disabled===!0&&("form"in a||"label"in a)},{dir:"parentNode",next:"legend"});try{G.apply(D=H.call(v.childNodes),v.childNodes),D[v.childNodes.length].nodeType}catch(fa){G={apply:D.length?function(a,b){F.apply(a,H.call(b))}:function(a,b){var c=a.length,d=0;while(a[c++]=b[d++]);a.length=c-1}}}function ga(a,b,d,e){var f,h,j,k,l,o,r,s=b&&b.ownerDocument,w=b?b.nodeType:9;if(d=d||[],"string"!=typeof a||!a||1!==w&&9!==w&&11!==w)return d;if(!e&&((b?b.ownerDocument||b:v)!==n&&m(b),b=b||n,p)){if(11!==w&&(l=Z.exec(a)))if(f=l[1]){if(9===w){if(!(j=b.getElementById(f)))return d;if(j.id===f)return d.push(j),d}else if(s&&(j=s.getElementById(f))&&t(b,j)&&j.id===f)return d.push(j),d}else{if(l[2])return G.apply(d,b.getElementsByTagName(a)),d;if((f=l[3])&&c.getElementsByClassName&&b.getElementsByClassName)return G.apply(d,b.getElementsByClassName(f)),d}if(c.qsa&&!A[a+" "]&&(!q||!q.test(a))){if(1!==w)s=b,r=a;else if("object"!==b.nodeName.toLowerCase()){(k=b.getAttribute("id"))?k=k.replace(ba,ca):b.setAttribute("id",k=u),o=g(a),h=o.length;while(h--)o[h]="#"+k+" "+sa(o[h]);r=o.join(","),s=$.test(a)&&qa(b.parentNode)||b}if(r)try{return G.apply(d,s.querySelectorAll(r)),d}catch(x){}finally{k===u&&b.removeAttribute("id")}}}return i(a.replace(P,"$1"),b,d,e)}function ha(){var a=[];function b(c,e){return a.push(c+" ")>d.cacheLength&&delete b[a.shift()],b[c+" "]=e}return b}function ia(a){return a[u]=!0,a}function ja(a){var b=n.createElement("fieldset");try{return!!a(b)}catch(c){return!1}finally{b.parentNode&&b.parentNode.removeChild(b),b=null}}function ka(a,b){var c=a.split("|"),e=c.length;while(e--)d.attrHandle[c[e]]=b}function la(a,b){var c=b&&a,d=c&&1===a.nodeType&&1===b.nodeType&&a.sourceIndex-b.sourceIndex;if(d)return d;if(c)while(c=c.nextSibling)if(c===b)return-1;return a?1:-1}function ma(a){return function(b){var c=b.nodeName.toLowerCase();return"input"===c&&b.type===a}}function na(a){return function(b){var c=b.nodeName.toLowerCase();return("input"===c||"button"===c)&&b.type===a}}function oa(a){return function(b){return"form"in b?b.parentNode&&b.disabled===!1?"label"in b?"label"in b.parentNode?b.parentNode.disabled===a:b.disabled===a:b.isDisabled===a||b.isDisabled!==!a&&ea(b)===a:b.disabled===a:"label"in b&&b.disabled===a}}function pa(a){return ia(function(b){return b=+b,ia(function(c,d){var e,f=a([],c.length,b),g=f.length;while(g--)c[e=f[g]]&&(c[e]=!(d[e]=c[e]))})})}function qa(a){return a&&"undefined"!=typeof a.getElementsByTagName&&a}c=ga.support={},f=ga.isXML=function(a){var b=a&&(a.ownerDocument||a).documentElement;return!!b&&"HTML"!==b.nodeName},m=ga.setDocument=function(a){var b,e,g=a?a.ownerDocument||a:v;return g!==n&&9===g.nodeType&&g.documentElement?(n=g,o=n.documentElement,p=!f(n),v!==n&&(e=n.defaultView)&&e.top!==e&&(e.addEventListener?e.addEventListener("unload",da,!1):e.attachEvent&&e.attachEvent("onunload",da)),c.attributes=ja(function(a){return a.className="i",!a.getAttribute("className")}),c.getElementsByTagName=ja(function(a){return a.appendChild(n.createComment("")),!a.getElementsByTagName("*").length}),c.getElementsByClassName=Y.test(n.getElementsByClassName),c.getById=ja(function(a){return o.appendChild(a).id=u,!n.getElementsByName||!n.getElementsByName(u).length}),c.getById?(d.filter.ID=function(a){var b=a.replace(_,aa);return function(a){return a.getAttribute("id")===b}},d.find.ID=function(a,b){if("undefined"!=typeof b.getElementById&&p){var c=b.getElementById(a);return c?[c]:[]}}):(d.filter.ID=function(a){var b=a.replace(_,aa);return function(a){var c="undefined"!=typeof a.getAttributeNode&&a.getAttributeNode("id");return c&&c.value===b}},d.find.ID=function(a,b){if("undefined"!=typeof b.getElementById&&p){var c,d,e,f=b.getElementById(a);if(f){if(c=f.getAttributeNode("id"),c&&c.value===a)return[f];e=b.getElementsByName(a),d=0;while(f=e[d++])if(c=f.getAttributeNode("id"),c&&c.value===a)return[f]}return[]}}),d.find.TAG=c.getElementsByTagName?function(a,b){return"undefined"!=typeof b.getElementsByTagName?b.getElementsByTagName(a):c.qsa?b.querySelectorAll(a):void 0}:function(a,b){var c,d=[],e=0,f=b.getElementsByTagName(a);if("*"===a){while(c=f[e++])1===c.nodeType&&d.push(c);return d}return f},d.find.CLASS=c.getElementsByClassName&&function(a,b){if("undefined"!=typeof b.getElementsByClassName&&p)return b.getElementsByClassName(a)},r=[],q=[],(c.qsa=Y.test(n.querySelectorAll))&&(ja(function(a){o.appendChild(a).innerHTML="<a id='"+u+"'></a><select id='"+u+"-\r\\' msallowcapture=''><option selected=''></option></select>",a.querySelectorAll("[msallowcapture^='']").length&&q.push("[*^$]="+K+"*(?:''|\"\")"),a.querySelectorAll("[selected]").length||q.push("\\["+K+"*(?:value|"+J+")"),a.querySelectorAll("[id~="+u+"-]").length||q.push("~="),a.querySelectorAll(":checked").length||q.push(":checked"),a.querySelectorAll("a#"+u+"+*").length||q.push(".#.+[+~]")}),ja(function(a){a.innerHTML="<a href='' disabled='disabled'></a><select disabled='disabled'><option/></select>";var b=n.createElement("input");b.setAttribute("type","hidden"),a.appendChild(b).setAttribute("name","D"),a.querySelectorAll("[name=d]").length&&q.push("name"+K+"*[*^$|!~]?="),2!==a.querySelectorAll(":enabled").length&&q.push(":enabled",":disabled"),o.appendChild(a).disabled=!0,2!==a.querySelectorAll(":disabled").length&&q.push(":enabled",":disabled"),a.querySelectorAll("*,:x"),q.push(",.*:")})),(c.matchesSelector=Y.test(s=o.matches||o.webkitMatchesSelector||o.mozMatchesSelector||o.oMatchesSelector||o.msMatchesSelector))&&ja(function(a){c.disconnectedMatch=s.call(a,"*"),s.call(a,"[s!='']:x"),r.push("!=",N)}),q=q.length&&new RegExp(q.join("|")),r=r.length&&new RegExp(r.join("|")),b=Y.test(o.compareDocumentPosition),t=b||Y.test(o.contains)?function(a,b){var c=9===a.nodeType?a.documentElement:a,d=b&&b.parentNode;return a===d||!(!d||1!==d.nodeType||!(c.contains?c.contains(d):a.compareDocumentPosition&&16&a.compareDocumentPosition(d)))}:function(a,b){if(b)while(b=b.parentNode)if(b===a)return!0;return!1},B=b?function(a,b){if(a===b)return l=!0,0;var d=!a.compareDocumentPosition-!b.compareDocumentPosition;return d?d:(d=(a.ownerDocument||a)===(b.ownerDocument||b)?a.compareDocumentPosition(b):1,1&d||!c.sortDetached&&b.compareDocumentPosition(a)===d?a===n||a.ownerDocument===v&&t(v,a)?-1:b===n||b.ownerDocument===v&&t(v,b)?1:k?I(k,a)-I(k,b):0:4&d?-1:1)}:function(a,b){if(a===b)return l=!0,0;var c,d=0,e=a.parentNode,f=b.parentNode,g=[a],h=[b];if(!e||!f)return a===n?-1:b===n?1:e?-1:f?1:k?I(k,a)-I(k,b):0;if(e===f)return la(a,b);c=a;while(c=c.parentNode)g.unshift(c);c=b;while(c=c.parentNode)h.unshift(c);while(g[d]===h[d])d++;return d?la(g[d],h[d]):g[d]===v?-1:h[d]===v?1:0},n):n},ga.matches=function(a,b){return ga(a,null,null,b)},ga.matchesSelector=function(a,b){if((a.ownerDocument||a)!==n&&m(a),b=b.replace(S,"='$1']"),c.matchesSelector&&p&&!A[b+" "]&&(!r||!r.test(b))&&(!q||!q.test(b)))try{var d=s.call(a,b);if(d||c.disconnectedMatch||a.document&&11!==a.document.nodeType)return d}catch(e){}return ga(b,n,null,[a]).length>0},ga.contains=function(a,b){return(a.ownerDocument||a)!==n&&m(a),t(a,b)},ga.attr=function(a,b){(a.ownerDocument||a)!==n&&m(a);var e=d.attrHandle[b.toLowerCase()],f=e&&C.call(d.attrHandle,b.toLowerCase())?e(a,b,!p):void 0;return void 0!==f?f:c.attributes||!p?a.getAttribute(b):(f=a.getAttributeNode(b))&&f.specified?f.value:null},ga.escape=function(a){return(a+"").replace(ba,ca)},ga.error=function(a){throw new Error("Syntax error, unrecognized expression: "+a)},ga.uniqueSort=function(a){var b,d=[],e=0,f=0;if(l=!c.detectDuplicates,k=!c.sortStable&&a.slice(0),a.sort(B),l){while(b=a[f++])b===a[f]&&(e=d.push(f));while(e--)a.splice(d[e],1)}return k=null,a},e=ga.getText=function(a){var b,c="",d=0,f=a.nodeType;if(f){if(1===f||9===f||11===f){if("string"==typeof a.textContent)return a.textContent;for(a=a.firstChild;a;a=a.nextSibling)c+=e(a)}else if(3===f||4===f)return a.nodeValue}else while(b=a[d++])c+=e(b);return c},d=ga.selectors={cacheLength:50,createPseudo:ia,match:V,attrHandle:{},find:{},relative:{">":{dir:"parentNode",first:!0}," ":{dir:"parentNode"},"+":{dir:"previousSibling",first:!0},"~":{dir:"previousSibling"}},preFilter:{ATTR:function(a){return a[1]=a[1].replace(_,aa),a[3]=(a[3]||a[4]||a[5]||"").replace(_,aa),"~="===a[2]&&(a[3]=" "+a[3]+" "),a.slice(0,4)},CHILD:function(a){return a[1]=a[1].toLowerCase(),"nth"===a[1].slice(0,3)?(a[3]||ga.error(a[0]),a[4]=+(a[4]?a[5]+(a[6]||1):2*("even"===a[3]||"odd"===a[3])),a[5]=+(a[7]+a[8]||"odd"===a[3])):a[3]&&ga.error(a[0]),a},PSEUDO:function(a){var b,c=!a[6]&&a[2];return V.CHILD.test(a[0])?null:(a[3]?a[2]=a[4]||a[5]||"":c&&T.test(c)&&(b=g(c,!0))&&(b=c.indexOf(")",c.length-b)-c.length)&&(a[0]=a[0].slice(0,b),a[2]=c.slice(0,b)),a.slice(0,3))}},filter:{TAG:function(a){var b=a.replace(_,aa).toLowerCase();return"*"===a?function(){return!0}:function(a){return a.nodeName&&a.nodeName.toLowerCase()===b}},CLASS:function(a){var b=y[a+" "];return b||(b=new RegExp("(^|"+K+")"+a+"("+K+"|$)"))&&y(a,function(a){return b.test("string"==typeof a.className&&a.className||"undefined"!=typeof a.getAttribute&&a.getAttribute("class")||"")})},ATTR:function(a,b,c){return function(d){var e=ga.attr(d,a);return null==e?"!="===b:!b||(e+="","="===b?e===c:"!="===b?e!==c:"^="===b?c&&0===e.indexOf(c):"*="===b?c&&e.indexOf(c)>-1:"$="===b?c&&e.slice(-c.length)===c:"~="===b?(" "+e.replace(O," ")+" ").indexOf(c)>-1:"|="===b&&(e===c||e.slice(0,c.length+1)===c+"-"))}},CHILD:function(a,b,c,d,e){var f="nth"!==a.slice(0,3),g="last"!==a.slice(-4),h="of-type"===b;return 1===d&&0===e?function(a){return!!a.parentNode}:function(b,c,i){var j,k,l,m,n,o,p=f!==g?"nextSibling":"previousSibling",q=b.parentNode,r=h&&b.nodeName.toLowerCase(),s=!i&&!h,t=!1;if(q){if(f){while(p){m=b;while(m=m[p])if(h?m.nodeName.toLowerCase()===r:1===m.nodeType)return!1;o=p="only"===a&&!o&&"nextSibling"}return!0}if(o=[g?q.firstChild:q.lastChild],g&&s){m=q,l=m[u]||(m[u]={}),k=l[m.uniqueID]||(l[m.uniqueID]={}),j=k[a]||[],n=j[0]===w&&j[1],t=n&&j[2],m=n&&q.childNodes[n];while(m=++n&&m&&m[p]||(t=n=0)||o.pop())if(1===m.nodeType&&++t&&m===b){k[a]=[w,n,t];break}}else if(s&&(m=b,l=m[u]||(m[u]={}),k=l[m.uniqueID]||(l[m.uniqueID]={}),j=k[a]||[],n=j[0]===w&&j[1],t=n),t===!1)while(m=++n&&m&&m[p]||(t=n=0)||o.pop())if((h?m.nodeName.toLowerCase()===r:1===m.nodeType)&&++t&&(s&&(l=m[u]||(m[u]={}),k=l[m.uniqueID]||(l[m.uniqueID]={}),k[a]=[w,t]),m===b))break;return t-=e,t===d||t%d===0&&t/d>=0}}},PSEUDO:function(a,b){var c,e=d.pseudos[a]||d.setFilters[a.toLowerCase()]||ga.error("unsupported pseudo: "+a);return e[u]?e(b):e.length>1?(c=[a,a,"",b],d.setFilters.hasOwnProperty(a.toLowerCase())?ia(function(a,c){var d,f=e(a,b),g=f.length;while(g--)d=I(a,f[g]),a[d]=!(c[d]=f[g])}):function(a){return e(a,0,c)}):e}},pseudos:{not:ia(function(a){var b=[],c=[],d=h(a.replace(P,"$1"));return d[u]?ia(function(a,b,c,e){var f,g=d(a,null,e,[]),h=a.length;while(h--)(f=g[h])&&(a[h]=!(b[h]=f))}):function(a,e,f){return b[0]=a,d(b,null,f,c),b[0]=null,!c.pop()}}),has:ia(function(a){return function(b){return ga(a,b).length>0}}),contains:ia(function(a){return a=a.replace(_,aa),function(b){return(b.textContent||b.innerText||e(b)).indexOf(a)>-1}}),lang:ia(function(a){return U.test(a||"")||ga.error("unsupported lang: "+a),a=a.replace(_,aa).toLowerCase(),function(b){var c;do if(c=p?b.lang:b.getAttribute("xml:lang")||b.getAttribute("lang"))return c=c.toLowerCase(),c===a||0===c.indexOf(a+"-");while((b=b.parentNode)&&1===b.nodeType);return!1}}),target:function(b){var c=a.location&&a.location.hash;return c&&c.slice(1)===b.id},root:function(a){return a===o},focus:function(a){return a===n.activeElement&&(!n.hasFocus||n.hasFocus())&&!!(a.type||a.href||~a.tabIndex)},enabled:oa(!1),disabled:oa(!0),checked:function(a){var b=a.nodeName.toLowerCase();return"input"===b&&!!a.checked||"option"===b&&!!a.selected},selected:function(a){return a.parentNode&&a.parentNode.selectedIndex,a.selected===!0},empty:function(a){for(a=a.firstChild;a;a=a.nextSibling)if(a.nodeType<6)return!1;return!0},parent:function(a){return!d.pseudos.empty(a)},header:function(a){return X.test(a.nodeName)},input:function(a){return W.test(a.nodeName)},button:function(a){var b=a.nodeName.toLowerCase();return"input"===b&&"button"===a.type||"button"===b},text:function(a){var b;return"input"===a.nodeName.toLowerCase()&&"text"===a.type&&(null==(b=a.getAttribute("type"))||"text"===b.toLowerCase())},first:pa(function(){return[0]}),last:pa(function(a,b){return[b-1]}),eq:pa(function(a,b,c){return[c<0?c+b:c]}),even:pa(function(a,b){for(var c=0;c<b;c+=2)a.push(c);return a}),odd:pa(function(a,b){for(var c=1;c<b;c+=2)a.push(c);return a}),lt:pa(function(a,b,c){for(var d=c<0?c+b:c;--d>=0;)a.push(d);return a}),gt:pa(function(a,b,c){for(var d=c<0?c+b:c;++d<b;)a.push(d);return a})}},d.pseudos.nth=d.pseudos.eq;for(b in{radio:!0,checkbox:!0,file:!0,password:!0,image:!0})d.pseudos[b]=ma(b);for(b in{submit:!0,reset:!0})d.pseudos[b]=na(b);function ra(){}ra.prototype=d.filters=d.pseudos,d.setFilters=new ra,g=ga.tokenize=function(a,b){var c,e,f,g,h,i,j,k=z[a+" "];if(k)return b?0:k.slice(0);h=a,i=[],j=d.preFilter;while(h){c&&!(e=Q.exec(h))||(e&&(h=h.slice(e[0].length)||h),i.push(f=[])),c=!1,(e=R.exec(h))&&(c=e.shift(),f.push({value:c,type:e[0].replace(P," ")}),h=h.slice(c.length));for(g in d.filter)!(e=V[g].exec(h))||j[g]&&!(e=j[g](e))||(c=e.shift(),f.push({value:c,type:g,matches:e}),h=h.slice(c.length));if(!c)break}return b?h.length:h?ga.error(a):z(a,i).slice(0)};function sa(a){for(var b=0,c=a.length,d="";b<c;b++)d+=a[b].value;return d}function ta(a,b,c){var d=b.dir,e=b.next,f=e||d,g=c&&"parentNode"===f,h=x++;return b.first?function(b,c,e){while(b=b[d])if(1===b.nodeType||g)return a(b,c,e);return!1}:function(b,c,i){var j,k,l,m=[w,h];if(i){while(b=b[d])if((1===b.nodeType||g)&&a(b,c,i))return!0}else while(b=b[d])if(1===b.nodeType||g)if(l=b[u]||(b[u]={}),k=l[b.uniqueID]||(l[b.uniqueID]={}),e&&e===b.nodeName.toLowerCase())b=b[d]||b;else{if((j=k[f])&&j[0]===w&&j[1]===h)return m[2]=j[2];if(k[f]=m,m[2]=a(b,c,i))return!0}return!1}}function ua(a){return a.length>1?function(b,c,d){var e=a.length;while(e--)if(!a[e](b,c,d))return!1;return!0}:a[0]}function va(a,b,c){for(var d=0,e=b.length;d<e;d++)ga(a,b[d],c);return c}function wa(a,b,c,d,e){for(var f,g=[],h=0,i=a.length,j=null!=b;h<i;h++)(f=a[h])&&(c&&!c(f,d,e)||(g.push(f),j&&b.push(h)));return g}function xa(a,b,c,d,e,f){return d&&!d[u]&&(d=xa(d)),e&&!e[u]&&(e=xa(e,f)),ia(function(f,g,h,i){var j,k,l,m=[],n=[],o=g.length,p=f||va(b||"*",h.nodeType?[h]:h,[]),q=!a||!f&&b?p:wa(p,m,a,h,i),r=c?e||(f?a:o||d)?[]:g:q;if(c&&c(q,r,h,i),d){j=wa(r,n),d(j,[],h,i),k=j.length;while(k--)(l=j[k])&&(r[n[k]]=!(q[n[k]]=l))}if(f){if(e||a){if(e){j=[],k=r.length;while(k--)(l=r[k])&&j.push(q[k]=l);e(null,r=[],j,i)}k=r.length;while(k--)(l=r[k])&&(j=e?I(f,l):m[k])>-1&&(f[j]=!(g[j]=l))}}else r=wa(r===g?r.splice(o,r.length):r),e?e(null,g,r,i):G.apply(g,r)})}function ya(a){for(var b,c,e,f=a.length,g=d.relative[a[0].type],h=g||d.relative[" "],i=g?1:0,k=ta(function(a){return a===b},h,!0),l=ta(function(a){return I(b,a)>-1},h,!0),m=[function(a,c,d){var e=!g&&(d||c!==j)||((b=c).nodeType?k(a,c,d):l(a,c,d));return b=null,e}];i<f;i++)if(c=d.relative[a[i].type])m=[ta(ua(m),c)];else{if(c=d.filter[a[i].type].apply(null,a[i].matches),c[u]){for(e=++i;e<f;e++)if(d.relative[a[e].type])break;return xa(i>1&&ua(m),i>1&&sa(a.slice(0,i-1).concat({value:" "===a[i-2].type?"*":""})).replace(P,"$1"),c,i<e&&ya(a.slice(i,e)),e<f&&ya(a=a.slice(e)),e<f&&sa(a))}m.push(c)}return ua(m)}function za(a,b){var c=b.length>0,e=a.length>0,f=function(f,g,h,i,k){var l,o,q,r=0,s="0",t=f&&[],u=[],v=j,x=f||e&&d.find.TAG("*",k),y=w+=null==v?1:Math.random()||.1,z=x.length;for(k&&(j=g===n||g||k);s!==z&&null!=(l=x[s]);s++){if(e&&l){o=0,g||l.ownerDocument===n||(m(l),h=!p);while(q=a[o++])if(q(l,g||n,h)){i.push(l);break}k&&(w=y)}c&&((l=!q&&l)&&r--,f&&t.push(l))}if(r+=s,c&&s!==r){o=0;while(q=b[o++])q(t,u,g,h);if(f){if(r>0)while(s--)t[s]||u[s]||(u[s]=E.call(i));u=wa(u)}G.apply(i,u),k&&!f&&u.length>0&&r+b.length>1&&ga.uniqueSort(i)}return k&&(w=y,j=v),t};return c?ia(f):f}return h=ga.compile=function(a,b){var c,d=[],e=[],f=A[a+" "];if(!f){b||(b=g(a)),c=b.length;while(c--)f=ya(b[c]),f[u]?d.push(f):e.push(f);f=A(a,za(e,d)),f.selector=a}return f},i=ga.select=function(a,b,c,e){var f,i,j,k,l,m="function"==typeof a&&a,n=!e&&g(a=m.selector||a);if(c=c||[],1===n.length){if(i=n[0]=n[0].slice(0),i.length>2&&"ID"===(j=i[0]).type&&9===b.nodeType&&p&&d.relative[i[1].type]){if(b=(d.find.ID(j.matches[0].replace(_,aa),b)||[])[0],!b)return c;m&&(b=b.parentNode),a=a.slice(i.shift().value.length)}f=V.needsContext.test(a)?0:i.length;while(f--){if(j=i[f],d.relative[k=j.type])break;if((l=d.find[k])&&(e=l(j.matches[0].replace(_,aa),$.test(i[0].type)&&qa(b.parentNode)||b))){if(i.splice(f,1),a=e.length&&sa(i),!a)return G.apply(c,e),c;break}}}return(m||h(a,n))(e,b,!p,c,!b||$.test(a)&&qa(b.parentNode)||b),c},c.sortStable=u.split("").sort(B).join("")===u,c.detectDuplicates=!!l,m(),c.sortDetached=ja(function(a){return 1&a.compareDocumentPosition(n.createElement("fieldset"))}),ja(function(a){return a.innerHTML="<a href='#'></a>","#"===a.firstChild.getAttribute("href")})||ka("type|href|height|width",function(a,b,c){if(!c)return a.getAttribute(b,"type"===b.toLowerCase()?1:2)}),c.attributes&&ja(function(a){return a.innerHTML="<input/>",a.firstChild.setAttribute("value",""),""===a.firstChild.getAttribute("value")})||ka("value",function(a,b,c){if(!c&&"input"===a.nodeName.toLowerCase())return a.defaultValue}),ja(function(a){return null==a.getAttribute("disabled")})||ka(J,function(a,b,c){var d;if(!c)return a[b]===!0?b.toLowerCase():(d=a.getAttributeNode(b))&&d.specified?d.value:null}),ga}(a);r.find=x,r.expr=x.selectors,r.expr[":"]=r.expr.pseudos,r.uniqueSort=r.unique=x.uniqueSort,r.text=x.getText,r.isXMLDoc=x.isXML,r.contains=x.contains,r.escapeSelector=x.escape;var y=function(a,b,c){var d=[],e=void 0!==c;while((a=a[b])&&9!==a.nodeType)if(1===a.nodeType){if(e&&r(a).is(c))break;d.push(a)}return d},z=function(a,b){for(var c=[];a;a=a.nextSibling)1===a.nodeType&&a!==b&&c.push(a);return c},A=r.expr.match.needsContext;function B(a,b){return a.nodeName&&a.nodeName.toLowerCase()===b.toLowerCase()}var C=/^<([a-z][^\/\0>:\x20\t\r\n\f]*)[\x20\t\r\n\f]*\/?>(?:<\/\1>|)$/i,D=/^.[^:#\[\.,]*$/;function E(a,b,c){return r.isFunction(b)?r.grep(a,function(a,d){return!!b.call(a,d,a)!==c}):b.nodeType?r.grep(a,function(a){return a===b!==c}):"string"!=typeof b?r.grep(a,function(a){return i.call(b,a)>-1!==c}):D.test(b)?r.filter(b,a,c):(b=r.filter(b,a),r.grep(a,function(a){return i.call(b,a)>-1!==c&&1===a.nodeType}))}r.filter=function(a,b,c){var d=b[0];return c&&(a=":not("+a+")"),1===b.length&&1===d.nodeType?r.find.matchesSelector(d,a)?[d]:[]:r.find.matches(a,r.grep(b,function(a){return 1===a.nodeType}))},r.fn.extend({find:function(a){var b,c,d=this.length,e=this;if("string"!=typeof a)return this.pushStack(r(a).filter(function(){for(b=0;b<d;b++)if(r.contains(e[b],this))return!0}));for(c=this.pushStack([]),b=0;b<d;b++)r.find(a,e[b],c);return d>1?r.uniqueSort(c):c},filter:function(a){return this.pushStack(E(this,a||[],!1))},not:function(a){return this.pushStack(E(this,a||[],!0))},is:function(a){return!!E(this,"string"==typeof a&&A.test(a)?r(a):a||[],!1).length}});var F,G=/^(?:\s*(<[\w\W]+>)[^>]*|#([\w-]+))$/,H=r.fn.init=function(a,b,c){var e,f;if(!a)return this;if(c=c||F,"string"==typeof a){if(e="<"===a[0]&&">"===a[a.length-1]&&a.length>=3?[null,a,null]:G.exec(a),!e||!e[1]&&b)return!b||b.jquery?(b||c).find(a):this.constructor(b).find(a);if(e[1]){if(b=b instanceof r?b[0]:b,r.merge(this,r.parseHTML(e[1],b&&b.nodeType?b.ownerDocument||b:d,!0)),C.test(e[1])&&r.isPlainObject(b))for(e in b)r.isFunction(this[e])?this[e](b[e]):this.attr(e,b[e]);return this}return f=d.getElementById(e[2]),f&&(this[0]=f,this.length=1),this}return a.nodeType?(this[0]=a,this.length=1,this):r.isFunction(a)?void 0!==c.ready?c.ready(a):a(r):r.makeArray(a,this)};H.prototype=r.fn,F=r(d);var I=/^(?:parents|prev(?:Until|All))/,J={children:!0,contents:!0,next:!0,prev:!0};r.fn.extend({has:function(a){var b=r(a,this),c=b.length;return this.filter(function(){for(var a=0;a<c;a++)if(r.contains(this,b[a]))return!0})},closest:function(a,b){var c,d=0,e=this.length,f=[],g="string"!=typeof a&&r(a);if(!A.test(a))for(;d<e;d++)for(c=this[d];c&&c!==b;c=c.parentNode)if(c.nodeType<11&&(g?g.index(c)>-1:1===c.nodeType&&r.find.matchesSelector(c,a))){f.push(c);break}return this.pushStack(f.length>1?r.uniqueSort(f):f)},index:function(a){return a?"string"==typeof a?i.call(r(a),this[0]):i.call(this,a.jquery?a[0]:a):this[0]&&this[0].parentNode?this.first().prevAll().length:-1},add:function(a,b){return this.pushStack(r.uniqueSort(r.merge(this.get(),r(a,b))))},addBack:function(a){return this.add(null==a?this.prevObject:this.prevObject.filter(a))}});function K(a,b){while((a=a[b])&&1!==a.nodeType);return a}r.each({parent:function(a){var b=a.parentNode;return b&&11!==b.nodeType?b:null},parents:function(a){return y(a,"parentNode")},parentsUntil:function(a,b,c){return y(a,"parentNode",c)},next:function(a){return K(a,"nextSibling")},prev:function(a){return K(a,"previousSibling")},nextAll:function(a){return y(a,"nextSibling")},prevAll:function(a){return y(a,"previousSibling")},nextUntil:function(a,b,c){return y(a,"nextSibling",c)},prevUntil:function(a,b,c){return y(a,"previousSibling",c)},siblings:function(a){return z((a.parentNode||{}).firstChild,a)},children:function(a){return z(a.firstChild)},contents:function(a){return B(a,"iframe")?a.contentDocument:(B(a,"template")&&(a=a.content||a),r.merge([],a.childNodes))}},function(a,b){r.fn[a]=function(c,d){var e=r.map(this,b,c);return"Until"!==a.slice(-5)&&(d=c),d&&"string"==typeof d&&(e=r.filter(d,e)),this.length>1&&(J[a]||r.uniqueSort(e),I.test(a)&&e.reverse()),this.pushStack(e)}});var L=/[^\x20\t\r\n\f]+/g;function M(a){var b={};return r.each(a.match(L)||[],function(a,c){b[c]=!0}),b}r.Callbacks=function(a){a="string"==typeof a?M(a):r.extend({},a);var b,c,d,e,f=[],g=[],h=-1,i=function(){for(e=e||a.once,d=b=!0;g.length;h=-1){c=g.shift();while(++h<f.length)f[h].apply(c[0],c[1])===!1&&a.stopOnFalse&&(h=f.length,c=!1)}a.memory||(c=!1),b=!1,e&&(f=c?[]:"")},j={add:function(){return f&&(c&&!b&&(h=f.length-1,g.push(c)),function d(b){r.each(b,function(b,c){r.isFunction(c)?a.unique&&j.has(c)||f.push(c):c&&c.length&&"string"!==r.type(c)&&d(c)})}(arguments),c&&!b&&i()),this},remove:function(){return r.each(arguments,function(a,b){var c;while((c=r.inArray(b,f,c))>-1)f.splice(c,1),c<=h&&h--}),this},has:function(a){return a?r.inArray(a,f)>-1:f.length>0},empty:function(){return f&&(f=[]),this},disable:function(){return e=g=[],f=c="",this},disabled:function(){return!f},lock:function(){return e=g=[],c||b||(f=c=""),this},locked:function(){return!!e},fireWith:function(a,c){return e||(c=c||[],c=[a,c.slice?c.slice():c],g.push(c),b||i()),this},fire:function(){return j.fireWith(this,arguments),this},fired:function(){return!!d}};return j};function N(a){return a}function O(a){throw a}function P(a,b,c,d){var e;try{a&&r.isFunction(e=a.promise)?e.call(a).done(b).fail(c):a&&r.isFunction(e=a.then)?e.call(a,b,c):b.apply(void 0,[a].slice(d))}catch(a){c.apply(void 0,[a])}}r.extend({Deferred:function(b){var c=[["notify","progress",r.Callbacks("memory"),r.Callbacks("memory"),2],["resolve","done",r.Callbacks("once memory"),r.Callbacks("once memory"),0,"resolved"],["reject","fail",r.Callbacks("once memory"),r.Callbacks("once memory"),1,"rejected"]],d="pending",e={state:function(){return d},always:function(){return f.done(arguments).fail(arguments),this},"catch":function(a){return e.then(null,a)},pipe:function(){var a=arguments;return r.Deferred(function(b){r.each(c,function(c,d){var e=r.isFunction(a[d[4]])&&a[d[4]];f[d[1]](function(){var a=e&&e.apply(this,arguments);a&&r.isFunction(a.promise)?a.promise().progress(b.notify).done(b.resolve).fail(b.reject):b[d[0]+"With"](this,e?[a]:arguments)})}),a=null}).promise()},then:function(b,d,e){var f=0;function g(b,c,d,e){return function(){var h=this,i=arguments,j=function(){var a,j;if(!(b<f)){if(a=d.apply(h,i),a===c.promise())throw new TypeError("Thenable self-resolution");j=a&&("object"==typeof a||"function"==typeof a)&&a.then,r.isFunction(j)?e?j.call(a,g(f,c,N,e),g(f,c,O,e)):(f++,j.call(a,g(f,c,N,e),g(f,c,O,e),g(f,c,N,c.notifyWith))):(d!==N&&(h=void 0,i=[a]),(e||c.resolveWith)(h,i))}},k=e?j:function(){try{j()}catch(a){r.Deferred.exceptionHook&&r.Deferred.exceptionHook(a,k.stackTrace),b+1>=f&&(d!==O&&(h=void 0,i=[a]),c.rejectWith(h,i))}};b?k():(r.Deferred.getStackHook&&(k.stackTrace=r.Deferred.getStackHook()),a.setTimeout(k))}}return r.Deferred(function(a){c[0][3].add(g(0,a,r.isFunction(e)?e:N,a.notifyWith)),c[1][3].add(g(0,a,r.isFunction(b)?b:N)),c[2][3].add(g(0,a,r.isFunction(d)?d:O))}).promise()},promise:function(a){return null!=a?r.extend(a,e):e}},f={};return r.each(c,function(a,b){var g=b[2],h=b[5];e[b[1]]=g.add,h&&g.add(function(){d=h},c[3-a][2].disable,c[0][2].lock),g.add(b[3].fire),f[b[0]]=function(){return f[b[0]+"With"](this===f?void 0:this,arguments),this},f[b[0]+"With"]=g.fireWith}),e.promise(f),b&&b.call(f,f),f},when:function(a){var b=arguments.length,c=b,d=Array(c),e=f.call(arguments),g=r.Deferred(),h=function(a){return function(c){d[a]=this,e[a]=arguments.length>1?f.call(arguments):c,--b||g.resolveWith(d,e)}};if(b<=1&&(P(a,g.done(h(c)).resolve,g.reject,!b),"pending"===g.state()||r.isFunction(e[c]&&e[c].then)))return g.then();while(c--)P(e[c],h(c),g.reject);return g.promise()}});var Q=/^(Eval|Internal|Range|Reference|Syntax|Type|URI)Error$/;r.Deferred.exceptionHook=function(b,c){a.console&&a.console.warn&&b&&Q.test(b.name)&&a.console.warn("jQuery.Deferred exception: "+b.message,b.stack,c)},r.readyException=function(b){a.setTimeout(function(){throw b})};var R=r.Deferred();r.fn.ready=function(a){return R.then(a)["catch"](function(a){r.readyException(a)}),this},r.extend({isReady:!1,readyWait:1,ready:function(a){(a===!0?--r.readyWait:r.isReady)||(r.isReady=!0,a!==!0&&--r.readyWait>0||R.resolveWith(d,[r]))}}),r.ready.then=R.then;function S(){d.removeEventListener("DOMContentLoaded",S),
a.removeEventListener("load",S),r.ready()}"complete"===d.readyState||"loading"!==d.readyState&&!d.documentElement.doScroll?a.setTimeout(r.ready):(d.addEventListener("DOMContentLoaded",S),a.addEventListener("load",S));var T=function(a,b,c,d,e,f,g){var h=0,i=a.length,j=null==c;if("object"===r.type(c)){e=!0;for(h in c)T(a,b,h,c[h],!0,f,g)}else if(void 0!==d&&(e=!0,r.isFunction(d)||(g=!0),j&&(g?(b.call(a,d),b=null):(j=b,b=function(a,b,c){return j.call(r(a),c)})),b))for(;h<i;h++)b(a[h],c,g?d:d.call(a[h],h,b(a[h],c)));return e?a:j?b.call(a):i?b(a[0],c):f},U=function(a){return 1===a.nodeType||9===a.nodeType||!+a.nodeType};function V(){this.expando=r.expando+V.uid++}V.uid=1,V.prototype={cache:function(a){var b=a[this.expando];return b||(b={},U(a)&&(a.nodeType?a[this.expando]=b:Object.defineProperty(a,this.expando,{value:b,configurable:!0}))),b},set:function(a,b,c){var d,e=this.cache(a);if("string"==typeof b)e[r.camelCase(b)]=c;else for(d in b)e[r.camelCase(d)]=b[d];return e},get:function(a,b){return void 0===b?this.cache(a):a[this.expando]&&a[this.expando][r.camelCase(b)]},access:function(a,b,c){return void 0===b||b&&"string"==typeof b&&void 0===c?this.get(a,b):(this.set(a,b,c),void 0!==c?c:b)},remove:function(a,b){var c,d=a[this.expando];if(void 0!==d){if(void 0!==b){Array.isArray(b)?b=b.map(r.camelCase):(b=r.camelCase(b),b=b in d?[b]:b.match(L)||[]),c=b.length;while(c--)delete d[b[c]]}(void 0===b||r.isEmptyObject(d))&&(a.nodeType?a[this.expando]=void 0:delete a[this.expando])}},hasData:function(a){var b=a[this.expando];return void 0!==b&&!r.isEmptyObject(b)}};var W=new V,X=new V,Y=/^(?:\{[\w\W]*\}|\[[\w\W]*\])$/,Z=/[A-Z]/g;function $(a){return"true"===a||"false"!==a&&("null"===a?null:a===+a+""?+a:Y.test(a)?JSON.parse(a):a)}function _(a,b,c){var d;if(void 0===c&&1===a.nodeType)if(d="data-"+b.replace(Z,"-$&").toLowerCase(),c=a.getAttribute(d),"string"==typeof c){try{c=$(c)}catch(e){}X.set(a,b,c)}else c=void 0;return c}r.extend({hasData:function(a){return X.hasData(a)||W.hasData(a)},data:function(a,b,c){return X.access(a,b,c)},removeData:function(a,b){X.remove(a,b)},_data:function(a,b,c){return W.access(a,b,c)},_removeData:function(a,b){W.remove(a,b)}}),r.fn.extend({data:function(a,b){var c,d,e,f=this[0],g=f&&f.attributes;if(void 0===a){if(this.length&&(e=X.get(f),1===f.nodeType&&!W.get(f,"hasDataAttrs"))){c=g.length;while(c--)g[c]&&(d=g[c].name,0===d.indexOf("data-")&&(d=r.camelCase(d.slice(5)),_(f,d,e[d])));W.set(f,"hasDataAttrs",!0)}return e}return"object"==typeof a?this.each(function(){X.set(this,a)}):T(this,function(b){var c;if(f&&void 0===b){if(c=X.get(f,a),void 0!==c)return c;if(c=_(f,a),void 0!==c)return c}else this.each(function(){X.set(this,a,b)})},null,b,arguments.length>1,null,!0)},removeData:function(a){return this.each(function(){X.remove(this,a)})}}),r.extend({queue:function(a,b,c){var d;if(a)return b=(b||"fx")+"queue",d=W.get(a,b),c&&(!d||Array.isArray(c)?d=W.access(a,b,r.makeArray(c)):d.push(c)),d||[]},dequeue:function(a,b){b=b||"fx";var c=r.queue(a,b),d=c.length,e=c.shift(),f=r._queueHooks(a,b),g=function(){r.dequeue(a,b)};"inprogress"===e&&(e=c.shift(),d--),e&&("fx"===b&&c.unshift("inprogress"),delete f.stop,e.call(a,g,f)),!d&&f&&f.empty.fire()},_queueHooks:function(a,b){var c=b+"queueHooks";return W.get(a,c)||W.access(a,c,{empty:r.Callbacks("once memory").add(function(){W.remove(a,[b+"queue",c])})})}}),r.fn.extend({queue:function(a,b){var c=2;return"string"!=typeof a&&(b=a,a="fx",c--),arguments.length<c?r.queue(this[0],a):void 0===b?this:this.each(function(){var c=r.queue(this,a,b);r._queueHooks(this,a),"fx"===a&&"inprogress"!==c[0]&&r.dequeue(this,a)})},dequeue:function(a){return this.each(function(){r.dequeue(this,a)})},clearQueue:function(a){return this.queue(a||"fx",[])},promise:function(a,b){var c,d=1,e=r.Deferred(),f=this,g=this.length,h=function(){--d||e.resolveWith(f,[f])};"string"!=typeof a&&(b=a,a=void 0),a=a||"fx";while(g--)c=W.get(f[g],a+"queueHooks"),c&&c.empty&&(d++,c.empty.add(h));return h(),e.promise(b)}});var aa=/[+-]?(?:\d*\.|)\d+(?:[eE][+-]?\d+|)/.source,ba=new RegExp("^(?:([+-])=|)("+aa+")([a-z%]*)$","i"),ca=["Top","Right","Bottom","Left"],da=function(a,b){return a=b||a,"none"===a.style.display||""===a.style.display&&r.contains(a.ownerDocument,a)&&"none"===r.css(a,"display")},ea=function(a,b,c,d){var e,f,g={};for(f in b)g[f]=a.style[f],a.style[f]=b[f];e=c.apply(a,d||[]);for(f in b)a.style[f]=g[f];return e};function fa(a,b,c,d){var e,f=1,g=20,h=d?function(){return d.cur()}:function(){return r.css(a,b,"")},i=h(),j=c&&c[3]||(r.cssNumber[b]?"":"px"),k=(r.cssNumber[b]||"px"!==j&&+i)&&ba.exec(r.css(a,b));if(k&&k[3]!==j){j=j||k[3],c=c||[],k=+i||1;do f=f||".5",k/=f,r.style(a,b,k+j);while(f!==(f=h()/i)&&1!==f&&--g)}return c&&(k=+k||+i||0,e=c[1]?k+(c[1]+1)*c[2]:+c[2],d&&(d.unit=j,d.start=k,d.end=e)),e}var ga={};function ha(a){var b,c=a.ownerDocument,d=a.nodeName,e=ga[d];return e?e:(b=c.body.appendChild(c.createElement(d)),e=r.css(b,"display"),b.parentNode.removeChild(b),"none"===e&&(e="block"),ga[d]=e,e)}function ia(a,b){for(var c,d,e=[],f=0,g=a.length;f<g;f++)d=a[f],d.style&&(c=d.style.display,b?("none"===c&&(e[f]=W.get(d,"display")||null,e[f]||(d.style.display="")),""===d.style.display&&da(d)&&(e[f]=ha(d))):"none"!==c&&(e[f]="none",W.set(d,"display",c)));for(f=0;f<g;f++)null!=e[f]&&(a[f].style.display=e[f]);return a}r.fn.extend({show:function(){return ia(this,!0)},hide:function(){return ia(this)},toggle:function(a){return"boolean"==typeof a?a?this.show():this.hide():this.each(function(){da(this)?r(this).show():r(this).hide()})}});var ja=/^(?:checkbox|radio)$/i,ka=/<([a-z][^\/\0>\x20\t\r\n\f]+)/i,la=/^$|\/(?:java|ecma)script/i,ma={option:[1,"<select multiple='multiple'>","</select>"],thead:[1,"<table>","</table>"],col:[2,"<table><colgroup>","</colgroup></table>"],tr:[2,"<table><tbody>","</tbody></table>"],td:[3,"<table><tbody><tr>","</tr></tbody></table>"],_default:[0,"",""]};ma.optgroup=ma.option,ma.tbody=ma.tfoot=ma.colgroup=ma.caption=ma.thead,ma.th=ma.td;function na(a,b){var c;return c="undefined"!=typeof a.getElementsByTagName?a.getElementsByTagName(b||"*"):"undefined"!=typeof a.querySelectorAll?a.querySelectorAll(b||"*"):[],void 0===b||b&&B(a,b)?r.merge([a],c):c}function oa(a,b){for(var c=0,d=a.length;c<d;c++)W.set(a[c],"globalEval",!b||W.get(b[c],"globalEval"))}var pa=/<|&#?\w+;/;function qa(a,b,c,d,e){for(var f,g,h,i,j,k,l=b.createDocumentFragment(),m=[],n=0,o=a.length;n<o;n++)if(f=a[n],f||0===f)if("object"===r.type(f))r.merge(m,f.nodeType?[f]:f);else if(pa.test(f)){g=g||l.appendChild(b.createElement("div")),h=(ka.exec(f)||["",""])[1].toLowerCase(),i=ma[h]||ma._default,g.innerHTML=i[1]+r.htmlPrefilter(f)+i[2],k=i[0];while(k--)g=g.lastChild;r.merge(m,g.childNodes),g=l.firstChild,g.textContent=""}else m.push(b.createTextNode(f));l.textContent="",n=0;while(f=m[n++])if(d&&r.inArray(f,d)>-1)e&&e.push(f);else if(j=r.contains(f.ownerDocument,f),g=na(l.appendChild(f),"script"),j&&oa(g),c){k=0;while(f=g[k++])la.test(f.type||"")&&c.push(f)}return l}!function(){var a=d.createDocumentFragment(),b=a.appendChild(d.createElement("div")),c=d.createElement("input");c.setAttribute("type","radio"),c.setAttribute("checked","checked"),c.setAttribute("name","t"),b.appendChild(c),o.checkClone=b.cloneNode(!0).cloneNode(!0).lastChild.checked,b.innerHTML="<textarea>x</textarea>",o.noCloneChecked=!!b.cloneNode(!0).lastChild.defaultValue}();var ra=d.documentElement,sa=/^key/,ta=/^(?:mouse|pointer|contextmenu|drag|drop)|click/,ua=/^([^.]*)(?:\.(.+)|)/;function va(){return!0}function wa(){return!1}function xa(){try{return d.activeElement}catch(a){}}function ya(a,b,c,d,e,f){var g,h;if("object"==typeof b){"string"!=typeof c&&(d=d||c,c=void 0);for(h in b)ya(a,h,c,d,b[h],f);return a}if(null==d&&null==e?(e=c,d=c=void 0):null==e&&("string"==typeof c?(e=d,d=void 0):(e=d,d=c,c=void 0)),e===!1)e=wa;else if(!e)return a;return 1===f&&(g=e,e=function(a){return r().off(a),g.apply(this,arguments)},e.guid=g.guid||(g.guid=r.guid++)),a.each(function(){r.event.add(this,b,e,d,c)})}r.event={global:{},add:function(a,b,c,d,e){var f,g,h,i,j,k,l,m,n,o,p,q=W.get(a);if(q){c.handler&&(f=c,c=f.handler,e=f.selector),e&&r.find.matchesSelector(ra,e),c.guid||(c.guid=r.guid++),(i=q.events)||(i=q.events={}),(g=q.handle)||(g=q.handle=function(b){return"undefined"!=typeof r&&r.event.triggered!==b.type?r.event.dispatch.apply(a,arguments):void 0}),b=(b||"").match(L)||[""],j=b.length;while(j--)h=ua.exec(b[j])||[],n=p=h[1],o=(h[2]||"").split(".").sort(),n&&(l=r.event.special[n]||{},n=(e?l.delegateType:l.bindType)||n,l=r.event.special[n]||{},k=r.extend({type:n,origType:p,data:d,handler:c,guid:c.guid,selector:e,needsContext:e&&r.expr.match.needsContext.test(e),namespace:o.join(".")},f),(m=i[n])||(m=i[n]=[],m.delegateCount=0,l.setup&&l.setup.call(a,d,o,g)!==!1||a.addEventListener&&a.addEventListener(n,g)),l.add&&(l.add.call(a,k),k.handler.guid||(k.handler.guid=c.guid)),e?m.splice(m.delegateCount++,0,k):m.push(k),r.event.global[n]=!0)}},remove:function(a,b,c,d,e){var f,g,h,i,j,k,l,m,n,o,p,q=W.hasData(a)&&W.get(a);if(q&&(i=q.events)){b=(b||"").match(L)||[""],j=b.length;while(j--)if(h=ua.exec(b[j])||[],n=p=h[1],o=(h[2]||"").split(".").sort(),n){l=r.event.special[n]||{},n=(d?l.delegateType:l.bindType)||n,m=i[n]||[],h=h[2]&&new RegExp("(^|\\.)"+o.join("\\.(?:.*\\.|)")+"(\\.|$)"),g=f=m.length;while(f--)k=m[f],!e&&p!==k.origType||c&&c.guid!==k.guid||h&&!h.test(k.namespace)||d&&d!==k.selector&&("**"!==d||!k.selector)||(m.splice(f,1),k.selector&&m.delegateCount--,l.remove&&l.remove.call(a,k));g&&!m.length&&(l.teardown&&l.teardown.call(a,o,q.handle)!==!1||r.removeEvent(a,n,q.handle),delete i[n])}else for(n in i)r.event.remove(a,n+b[j],c,d,!0);r.isEmptyObject(i)&&W.remove(a,"handle events")}},dispatch:function(a){var b=r.event.fix(a),c,d,e,f,g,h,i=new Array(arguments.length),j=(W.get(this,"events")||{})[b.type]||[],k=r.event.special[b.type]||{};for(i[0]=b,c=1;c<arguments.length;c++)i[c]=arguments[c];if(b.delegateTarget=this,!k.preDispatch||k.preDispatch.call(this,b)!==!1){h=r.event.handlers.call(this,b,j),c=0;while((f=h[c++])&&!b.isPropagationStopped()){b.currentTarget=f.elem,d=0;while((g=f.handlers[d++])&&!b.isImmediatePropagationStopped())b.rnamespace&&!b.rnamespace.test(g.namespace)||(b.handleObj=g,b.data=g.data,e=((r.event.special[g.origType]||{}).handle||g.handler).apply(f.elem,i),void 0!==e&&(b.result=e)===!1&&(b.preventDefault(),b.stopPropagation()))}return k.postDispatch&&k.postDispatch.call(this,b),b.result}},handlers:function(a,b){var c,d,e,f,g,h=[],i=b.delegateCount,j=a.target;if(i&&j.nodeType&&!("click"===a.type&&a.button>=1))for(;j!==this;j=j.parentNode||this)if(1===j.nodeType&&("click"!==a.type||j.disabled!==!0)){for(f=[],g={},c=0;c<i;c++)d=b[c],e=d.selector+" ",void 0===g[e]&&(g[e]=d.needsContext?r(e,this).index(j)>-1:r.find(e,this,null,[j]).length),g[e]&&f.push(d);f.length&&h.push({elem:j,handlers:f})}return j=this,i<b.length&&h.push({elem:j,handlers:b.slice(i)}),h},addProp:function(a,b){Object.defineProperty(r.Event.prototype,a,{enumerable:!0,configurable:!0,get:r.isFunction(b)?function(){if(this.originalEvent)return b(this.originalEvent)}:function(){if(this.originalEvent)return this.originalEvent[a]},set:function(b){Object.defineProperty(this,a,{enumerable:!0,configurable:!0,writable:!0,value:b})}})},fix:function(a){return a[r.expando]?a:new r.Event(a)},special:{load:{noBubble:!0},focus:{trigger:function(){if(this!==xa()&&this.focus)return this.focus(),!1},delegateType:"focusin"},blur:{trigger:function(){if(this===xa()&&this.blur)return this.blur(),!1},delegateType:"focusout"},click:{trigger:function(){if("checkbox"===this.type&&this.click&&B(this,"input"))return this.click(),!1},_default:function(a){return B(a.target,"a")}},beforeunload:{postDispatch:function(a){void 0!==a.result&&a.originalEvent&&(a.originalEvent.returnValue=a.result)}}}},r.removeEvent=function(a,b,c){a.removeEventListener&&a.removeEventListener(b,c)},r.Event=function(a,b){return this instanceof r.Event?(a&&a.type?(this.originalEvent=a,this.type=a.type,this.isDefaultPrevented=a.defaultPrevented||void 0===a.defaultPrevented&&a.returnValue===!1?va:wa,this.target=a.target&&3===a.target.nodeType?a.target.parentNode:a.target,this.currentTarget=a.currentTarget,this.relatedTarget=a.relatedTarget):this.type=a,b&&r.extend(this,b),this.timeStamp=a&&a.timeStamp||r.now(),void(this[r.expando]=!0)):new r.Event(a,b)},r.Event.prototype={constructor:r.Event,isDefaultPrevented:wa,isPropagationStopped:wa,isImmediatePropagationStopped:wa,isSimulated:!1,preventDefault:function(){var a=this.originalEvent;this.isDefaultPrevented=va,a&&!this.isSimulated&&a.preventDefault()},stopPropagation:function(){var a=this.originalEvent;this.isPropagationStopped=va,a&&!this.isSimulated&&a.stopPropagation()},stopImmediatePropagation:function(){var a=this.originalEvent;this.isImmediatePropagationStopped=va,a&&!this.isSimulated&&a.stopImmediatePropagation(),this.stopPropagation()}},r.each({altKey:!0,bubbles:!0,cancelable:!0,changedTouches:!0,ctrlKey:!0,detail:!0,eventPhase:!0,metaKey:!0,pageX:!0,pageY:!0,shiftKey:!0,view:!0,"char":!0,charCode:!0,key:!0,keyCode:!0,button:!0,buttons:!0,clientX:!0,clientY:!0,offsetX:!0,offsetY:!0,pointerId:!0,pointerType:!0,screenX:!0,screenY:!0,targetTouches:!0,toElement:!0,touches:!0,which:function(a){var b=a.button;return null==a.which&&sa.test(a.type)?null!=a.charCode?a.charCode:a.keyCode:!a.which&&void 0!==b&&ta.test(a.type)?1&b?1:2&b?3:4&b?2:0:a.which}},r.event.addProp),r.each({mouseenter:"mouseover",mouseleave:"mouseout",pointerenter:"pointerover",pointerleave:"pointerout"},function(a,b){r.event.special[a]={delegateType:b,bindType:b,handle:function(a){var c,d=this,e=a.relatedTarget,f=a.handleObj;return e&&(e===d||r.contains(d,e))||(a.type=f.origType,c=f.handler.apply(this,arguments),a.type=b),c}}}),r.fn.extend({on:function(a,b,c,d){return ya(this,a,b,c,d)},one:function(a,b,c,d){return ya(this,a,b,c,d,1)},off:function(a,b,c){var d,e;if(a&&a.preventDefault&&a.handleObj)return d=a.handleObj,r(a.delegateTarget).off(d.namespace?d.origType+"."+d.namespace:d.origType,d.selector,d.handler),this;if("object"==typeof a){for(e in a)this.off(e,b,a[e]);return this}return b!==!1&&"function"!=typeof b||(c=b,b=void 0),c===!1&&(c=wa),this.each(function(){r.event.remove(this,a,c,b)})}});var za=/<(?!area|br|col|embed|hr|img|input|link|meta|param)(([a-z][^\/\0>\x20\t\r\n\f]*)[^>]*)\/>/gi,Aa=/<script|<style|<link/i,Ba=/checked\s*(?:[^=]|=\s*.checked.)/i,Ca=/^true\/(.*)/,Da=/^\s*<!(?:\[CDATA\[|--)|(?:\]\]|--)>\s*$/g;function Ea(a,b){return B(a,"table")&&B(11!==b.nodeType?b:b.firstChild,"tr")?r(">tbody",a)[0]||a:a}function Fa(a){return a.type=(null!==a.getAttribute("type"))+"/"+a.type,a}function Ga(a){var b=Ca.exec(a.type);return b?a.type=b[1]:a.removeAttribute("type"),a}function Ha(a,b){var c,d,e,f,g,h,i,j;if(1===b.nodeType){if(W.hasData(a)&&(f=W.access(a),g=W.set(b,f),j=f.events)){delete g.handle,g.events={};for(e in j)for(c=0,d=j[e].length;c<d;c++)r.event.add(b,e,j[e][c])}X.hasData(a)&&(h=X.access(a),i=r.extend({},h),X.set(b,i))}}function Ia(a,b){var c=b.nodeName.toLowerCase();"input"===c&&ja.test(a.type)?b.checked=a.checked:"input"!==c&&"textarea"!==c||(b.defaultValue=a.defaultValue)}function Ja(a,b,c,d){b=g.apply([],b);var e,f,h,i,j,k,l=0,m=a.length,n=m-1,q=b[0],s=r.isFunction(q);if(s||m>1&&"string"==typeof q&&!o.checkClone&&Ba.test(q))return a.each(function(e){var f=a.eq(e);s&&(b[0]=q.call(this,e,f.html())),Ja(f,b,c,d)});if(m&&(e=qa(b,a[0].ownerDocument,!1,a,d),f=e.firstChild,1===e.childNodes.length&&(e=f),f||d)){for(h=r.map(na(e,"script"),Fa),i=h.length;l<m;l++)j=e,l!==n&&(j=r.clone(j,!0,!0),i&&r.merge(h,na(j,"script"))),c.call(a[l],j,l);if(i)for(k=h[h.length-1].ownerDocument,r.map(h,Ga),l=0;l<i;l++)j=h[l],la.test(j.type||"")&&!W.access(j,"globalEval")&&r.contains(k,j)&&(j.src?r._evalUrl&&r._evalUrl(j.src):p(j.textContent.replace(Da,""),k))}return a}function Ka(a,b,c){for(var d,e=b?r.filter(b,a):a,f=0;null!=(d=e[f]);f++)c||1!==d.nodeType||r.cleanData(na(d)),d.parentNode&&(c&&r.contains(d.ownerDocument,d)&&oa(na(d,"script")),d.parentNode.removeChild(d));return a}r.extend({htmlPrefilter:function(a){return a.replace(za,"<$1></$2>")},clone:function(a,b,c){var d,e,f,g,h=a.cloneNode(!0),i=r.contains(a.ownerDocument,a);if(!(o.noCloneChecked||1!==a.nodeType&&11!==a.nodeType||r.isXMLDoc(a)))for(g=na(h),f=na(a),d=0,e=f.length;d<e;d++)Ia(f[d],g[d]);if(b)if(c)for(f=f||na(a),g=g||na(h),d=0,e=f.length;d<e;d++)Ha(f[d],g[d]);else Ha(a,h);return g=na(h,"script"),g.length>0&&oa(g,!i&&na(a,"script")),h},cleanData:function(a){for(var b,c,d,e=r.event.special,f=0;void 0!==(c=a[f]);f++)if(U(c)){if(b=c[W.expando]){if(b.events)for(d in b.events)e[d]?r.event.remove(c,d):r.removeEvent(c,d,b.handle);c[W.expando]=void 0}c[X.expando]&&(c[X.expando]=void 0)}}}),r.fn.extend({detach:function(a){return Ka(this,a,!0)},remove:function(a){return Ka(this,a)},text:function(a){return T(this,function(a){return void 0===a?r.text(this):this.empty().each(function(){1!==this.nodeType&&11!==this.nodeType&&9!==this.nodeType||(this.textContent=a)})},null,a,arguments.length)},append:function(){return Ja(this,arguments,function(a){if(1===this.nodeType||11===this.nodeType||9===this.nodeType){var b=Ea(this,a);b.appendChild(a)}})},prepend:function(){return Ja(this,arguments,function(a){if(1===this.nodeType||11===this.nodeType||9===this.nodeType){var b=Ea(this,a);b.insertBefore(a,b.firstChild)}})},before:function(){return Ja(this,arguments,function(a){this.parentNode&&this.parentNode.insertBefore(a,this)})},after:function(){return Ja(this,arguments,function(a){this.parentNode&&this.parentNode.insertBefore(a,this.nextSibling)})},empty:function(){for(var a,b=0;null!=(a=this[b]);b++)1===a.nodeType&&(r.cleanData(na(a,!1)),a.textContent="");return this},clone:function(a,b){return a=null!=a&&a,b=null==b?a:b,this.map(function(){return r.clone(this,a,b)})},html:function(a){return T(this,function(a){var b=this[0]||{},c=0,d=this.length;if(void 0===a&&1===b.nodeType)return b.innerHTML;if("string"==typeof a&&!Aa.test(a)&&!ma[(ka.exec(a)||["",""])[1].toLowerCase()]){a=r.htmlPrefilter(a);try{for(;c<d;c++)b=this[c]||{},1===b.nodeType&&(r.cleanData(na(b,!1)),b.innerHTML=a);b=0}catch(e){}}b&&this.empty().append(a)},null,a,arguments.length)},replaceWith:function(){var a=[];return Ja(this,arguments,function(b){var c=this.parentNode;r.inArray(this,a)<0&&(r.cleanData(na(this)),c&&c.replaceChild(b,this))},a)}}),r.each({appendTo:"append",prependTo:"prepend",insertBefore:"before",insertAfter:"after",replaceAll:"replaceWith"},function(a,b){r.fn[a]=function(a){for(var c,d=[],e=r(a),f=e.length-1,g=0;g<=f;g++)c=g===f?this:this.clone(!0),r(e[g])[b](c),h.apply(d,c.get());return this.pushStack(d)}});var La=/^margin/,Ma=new RegExp("^("+aa+")(?!px)[a-z%]+$","i"),Na=function(b){var c=b.ownerDocument.defaultView;return c&&c.opener||(c=a),c.getComputedStyle(b)};!function(){function b(){if(i){i.style.cssText="box-sizing:border-box;position:relative;display:block;margin:auto;border:1px;padding:1px;top:1%;width:50%",i.innerHTML="",ra.appendChild(h);var b=a.getComputedStyle(i);c="1%"!==b.top,g="2px"===b.marginLeft,e="4px"===b.width,i.style.marginRight="50%",f="4px"===b.marginRight,ra.removeChild(h),i=null}}var c,e,f,g,h=d.createElement("div"),i=d.createElement("div");i.style&&(i.style.backgroundClip="content-box",i.cloneNode(!0).style.backgroundClip="",o.clearCloneStyle="content-box"===i.style.backgroundClip,h.style.cssText="border:0;width:8px;height:0;top:0;left:-9999px;padding:0;margin-top:1px;position:absolute",h.appendChild(i),r.extend(o,{pixelPosition:function(){return b(),c},boxSizingReliable:function(){return b(),e},pixelMarginRight:function(){return b(),f},reliableMarginLeft:function(){return b(),g}}))}();function Oa(a,b,c){var d,e,f,g,h=a.style;return c=c||Na(a),c&&(g=c.getPropertyValue(b)||c[b],""!==g||r.contains(a.ownerDocument,a)||(g=r.style(a,b)),!o.pixelMarginRight()&&Ma.test(g)&&La.test(b)&&(d=h.width,e=h.minWidth,f=h.maxWidth,h.minWidth=h.maxWidth=h.width=g,g=c.width,h.width=d,h.minWidth=e,h.maxWidth=f)),void 0!==g?g+"":g}function Pa(a,b){return{get:function(){return a()?void delete this.get:(this.get=b).apply(this,arguments)}}}var Qa=/^(none|table(?!-c[ea]).+)/,Ra=/^--/,Sa={position:"absolute",visibility:"hidden",display:"block"},Ta={letterSpacing:"0",fontWeight:"400"},Ua=["Webkit","Moz","ms"],Va=d.createElement("div").style;function Wa(a){if(a in Va)return a;var b=a[0].toUpperCase()+a.slice(1),c=Ua.length;while(c--)if(a=Ua[c]+b,a in Va)return a}function Xa(a){var b=r.cssProps[a];return b||(b=r.cssProps[a]=Wa(a)||a),b}function Ya(a,b,c){var d=ba.exec(b);return d?Math.max(0,d[2]-(c||0))+(d[3]||"px"):b}function Za(a,b,c,d,e){var f,g=0;for(f=c===(d?"border":"content")?4:"width"===b?1:0;f<4;f+=2)"margin"===c&&(g+=r.css(a,c+ca[f],!0,e)),d?("content"===c&&(g-=r.css(a,"padding"+ca[f],!0,e)),"margin"!==c&&(g-=r.css(a,"border"+ca[f]+"Width",!0,e))):(g+=r.css(a,"padding"+ca[f],!0,e),"padding"!==c&&(g+=r.css(a,"border"+ca[f]+"Width",!0,e)));return g}function $a(a,b,c){var d,e=Na(a),f=Oa(a,b,e),g="border-box"===r.css(a,"boxSizing",!1,e);return Ma.test(f)?f:(d=g&&(o.boxSizingReliable()||f===a.style[b]),"auto"===f&&(f=a["offset"+b[0].toUpperCase()+b.slice(1)]),f=parseFloat(f)||0,f+Za(a,b,c||(g?"border":"content"),d,e)+"px")}r.extend({cssHooks:{opacity:{get:function(a,b){if(b){var c=Oa(a,"opacity");return""===c?"1":c}}}},cssNumber:{animationIterationCount:!0,columnCount:!0,fillOpacity:!0,flexGrow:!0,flexShrink:!0,fontWeight:!0,lineHeight:!0,opacity:!0,order:!0,orphans:!0,widows:!0,zIndex:!0,zoom:!0},cssProps:{"float":"cssFloat"},style:function(a,b,c,d){if(a&&3!==a.nodeType&&8!==a.nodeType&&a.style){var e,f,g,h=r.camelCase(b),i=Ra.test(b),j=a.style;return i||(b=Xa(h)),g=r.cssHooks[b]||r.cssHooks[h],void 0===c?g&&"get"in g&&void 0!==(e=g.get(a,!1,d))?e:j[b]:(f=typeof c,"string"===f&&(e=ba.exec(c))&&e[1]&&(c=fa(a,b,e),f="number"),null!=c&&c===c&&("number"===f&&(c+=e&&e[3]||(r.cssNumber[h]?"":"px")),o.clearCloneStyle||""!==c||0!==b.indexOf("background")||(j[b]="inherit"),g&&"set"in g&&void 0===(c=g.set(a,c,d))||(i?j.setProperty(b,c):j[b]=c)),void 0)}},css:function(a,b,c,d){var e,f,g,h=r.camelCase(b),i=Ra.test(b);return i||(b=Xa(h)),g=r.cssHooks[b]||r.cssHooks[h],g&&"get"in g&&(e=g.get(a,!0,c)),void 0===e&&(e=Oa(a,b,d)),"normal"===e&&b in Ta&&(e=Ta[b]),""===c||c?(f=parseFloat(e),c===!0||isFinite(f)?f||0:e):e}}),r.each(["height","width"],function(a,b){r.cssHooks[b]={get:function(a,c,d){if(c)return!Qa.test(r.css(a,"display"))||a.getClientRects().length&&a.getBoundingClientRect().width?$a(a,b,d):ea(a,Sa,function(){return $a(a,b,d)})},set:function(a,c,d){var e,f=d&&Na(a),g=d&&Za(a,b,d,"border-box"===r.css(a,"boxSizing",!1,f),f);return g&&(e=ba.exec(c))&&"px"!==(e[3]||"px")&&(a.style[b]=c,c=r.css(a,b)),Ya(a,c,g)}}}),r.cssHooks.marginLeft=Pa(o.reliableMarginLeft,function(a,b){if(b)return(parseFloat(Oa(a,"marginLeft"))||a.getBoundingClientRect().left-ea(a,{marginLeft:0},function(){return a.getBoundingClientRect().left}))+"px"}),r.each({margin:"",padding:"",border:"Width"},function(a,b){r.cssHooks[a+b]={expand:function(c){for(var d=0,e={},f="string"==typeof c?c.split(" "):[c];d<4;d++)e[a+ca[d]+b]=f[d]||f[d-2]||f[0];return e}},La.test(a)||(r.cssHooks[a+b].set=Ya)}),r.fn.extend({css:function(a,b){return T(this,function(a,b,c){var d,e,f={},g=0;if(Array.isArray(b)){for(d=Na(a),e=b.length;g<e;g++)f[b[g]]=r.css(a,b[g],!1,d);return f}return void 0!==c?r.style(a,b,c):r.css(a,b)},a,b,arguments.length>1)}});function _a(a,b,c,d,e){return new _a.prototype.init(a,b,c,d,e)}r.Tween=_a,_a.prototype={constructor:_a,init:function(a,b,c,d,e,f){this.elem=a,this.prop=c,this.easing=e||r.easing._default,this.options=b,this.start=this.now=this.cur(),this.end=d,this.unit=f||(r.cssNumber[c]?"":"px")},cur:function(){var a=_a.propHooks[this.prop];return a&&a.get?a.get(this):_a.propHooks._default.get(this)},run:function(a){var b,c=_a.propHooks[this.prop];return this.options.duration?this.pos=b=r.easing[this.easing](a,this.options.duration*a,0,1,this.options.duration):this.pos=b=a,this.now=(this.end-this.start)*b+this.start,this.options.step&&this.options.step.call(this.elem,this.now,this),c&&c.set?c.set(this):_a.propHooks._default.set(this),this}},_a.prototype.init.prototype=_a.prototype,_a.propHooks={_default:{get:function(a){var b;return 1!==a.elem.nodeType||null!=a.elem[a.prop]&&null==a.elem.style[a.prop]?a.elem[a.prop]:(b=r.css(a.elem,a.prop,""),b&&"auto"!==b?b:0)},set:function(a){r.fx.step[a.prop]?r.fx.step[a.prop](a):1!==a.elem.nodeType||null==a.elem.style[r.cssProps[a.prop]]&&!r.cssHooks[a.prop]?a.elem[a.prop]=a.now:r.style(a.elem,a.prop,a.now+a.unit)}}},_a.propHooks.scrollTop=_a.propHooks.scrollLeft={set:function(a){a.elem.nodeType&&a.elem.parentNode&&(a.elem[a.prop]=a.now)}},r.easing={linear:function(a){return a},swing:function(a){return.5-Math.cos(a*Math.PI)/2},_default:"swing"},r.fx=_a.prototype.init,r.fx.step={};var ab,bb,cb=/^(?:toggle|show|hide)$/,db=/queueHooks$/;function eb(){bb&&(d.hidden===!1&&a.requestAnimationFrame?a.requestAnimationFrame(eb):a.setTimeout(eb,r.fx.interval),r.fx.tick())}function fb(){return a.setTimeout(function(){ab=void 0}),ab=r.now()}function gb(a,b){var c,d=0,e={height:a};for(b=b?1:0;d<4;d+=2-b)c=ca[d],e["margin"+c]=e["padding"+c]=a;return b&&(e.opacity=e.width=a),e}function hb(a,b,c){for(var d,e=(kb.tweeners[b]||[]).concat(kb.tweeners["*"]),f=0,g=e.length;f<g;f++)if(d=e[f].call(c,b,a))return d}function ib(a,b,c){var d,e,f,g,h,i,j,k,l="width"in b||"height"in b,m=this,n={},o=a.style,p=a.nodeType&&da(a),q=W.get(a,"fxshow");c.queue||(g=r._queueHooks(a,"fx"),null==g.unqueued&&(g.unqueued=0,h=g.empty.fire,g.empty.fire=function(){g.unqueued||h()}),g.unqueued++,m.always(function(){m.always(function(){g.unqueued--,r.queue(a,"fx").length||g.empty.fire()})}));for(d in b)if(e=b[d],cb.test(e)){if(delete b[d],f=f||"toggle"===e,e===(p?"hide":"show")){if("show"!==e||!q||void 0===q[d])continue;p=!0}n[d]=q&&q[d]||r.style(a,d)}if(i=!r.isEmptyObject(b),i||!r.isEmptyObject(n)){l&&1===a.nodeType&&(c.overflow=[o.overflow,o.overflowX,o.overflowY],j=q&&q.display,null==j&&(j=W.get(a,"display")),k=r.css(a,"display"),"none"===k&&(j?k=j:(ia([a],!0),j=a.style.display||j,k=r.css(a,"display"),ia([a]))),("inline"===k||"inline-block"===k&&null!=j)&&"none"===r.css(a,"float")&&(i||(m.done(function(){o.display=j}),null==j&&(k=o.display,j="none"===k?"":k)),o.display="inline-block")),c.overflow&&(o.overflow="hidden",m.always(function(){o.overflow=c.overflow[0],o.overflowX=c.overflow[1],o.overflowY=c.overflow[2]})),i=!1;for(d in n)i||(q?"hidden"in q&&(p=q.hidden):q=W.access(a,"fxshow",{display:j}),f&&(q.hidden=!p),p&&ia([a],!0),m.done(function(){p||ia([a]),W.remove(a,"fxshow");for(d in n)r.style(a,d,n[d])})),i=hb(p?q[d]:0,d,m),d in q||(q[d]=i.start,p&&(i.end=i.start,i.start=0))}}function jb(a,b){var c,d,e,f,g;for(c in a)if(d=r.camelCase(c),e=b[d],f=a[c],Array.isArray(f)&&(e=f[1],f=a[c]=f[0]),c!==d&&(a[d]=f,delete a[c]),g=r.cssHooks[d],g&&"expand"in g){f=g.expand(f),delete a[d];for(c in f)c in a||(a[c]=f[c],b[c]=e)}else b[d]=e}function kb(a,b,c){var d,e,f=0,g=kb.prefilters.length,h=r.Deferred().always(function(){delete i.elem}),i=function(){if(e)return!1;for(var b=ab||fb(),c=Math.max(0,j.startTime+j.duration-b),d=c/j.duration||0,f=1-d,g=0,i=j.tweens.length;g<i;g++)j.tweens[g].run(f);return h.notifyWith(a,[j,f,c]),f<1&&i?c:(i||h.notifyWith(a,[j,1,0]),h.resolveWith(a,[j]),!1)},j=h.promise({elem:a,props:r.extend({},b),opts:r.extend(!0,{specialEasing:{},easing:r.easing._default},c),originalProperties:b,originalOptions:c,startTime:ab||fb(),duration:c.duration,tweens:[],createTween:function(b,c){var d=r.Tween(a,j.opts,b,c,j.opts.specialEasing[b]||j.opts.easing);return j.tweens.push(d),d},stop:function(b){var c=0,d=b?j.tweens.length:0;if(e)return this;for(e=!0;c<d;c++)j.tweens[c].run(1);return b?(h.notifyWith(a,[j,1,0]),h.resolveWith(a,[j,b])):h.rejectWith(a,[j,b]),this}}),k=j.props;for(jb(k,j.opts.specialEasing);f<g;f++)if(d=kb.prefilters[f].call(j,a,k,j.opts))return r.isFunction(d.stop)&&(r._queueHooks(j.elem,j.opts.queue).stop=r.proxy(d.stop,d)),d;return r.map(k,hb,j),r.isFunction(j.opts.start)&&j.opts.start.call(a,j),j.progress(j.opts.progress).done(j.opts.done,j.opts.complete).fail(j.opts.fail).always(j.opts.always),r.fx.timer(r.extend(i,{elem:a,anim:j,queue:j.opts.queue})),j}r.Animation=r.extend(kb,{tweeners:{"*":[function(a,b){var c=this.createTween(a,b);return fa(c.elem,a,ba.exec(b),c),c}]},tweener:function(a,b){r.isFunction(a)?(b=a,a=["*"]):a=a.match(L);for(var c,d=0,e=a.length;d<e;d++)c=a[d],kb.tweeners[c]=kb.tweeners[c]||[],kb.tweeners[c].unshift(b)},prefilters:[ib],prefilter:function(a,b){b?kb.prefilters.unshift(a):kb.prefilters.push(a)}}),r.speed=function(a,b,c){var d=a&&"object"==typeof a?r.extend({},a):{complete:c||!c&&b||r.isFunction(a)&&a,duration:a,easing:c&&b||b&&!r.isFunction(b)&&b};return r.fx.off?d.duration=0:"number"!=typeof d.duration&&(d.duration in r.fx.speeds?d.duration=r.fx.speeds[d.duration]:d.duration=r.fx.speeds._default),null!=d.queue&&d.queue!==!0||(d.queue="fx"),d.old=d.complete,d.complete=function(){r.isFunction(d.old)&&d.old.call(this),d.queue&&r.dequeue(this,d.queue)},d},r.fn.extend({fadeTo:function(a,b,c,d){return this.filter(da).css("opacity",0).show().end().animate({opacity:b},a,c,d)},animate:function(a,b,c,d){var e=r.isEmptyObject(a),f=r.speed(b,c,d),g=function(){var b=kb(this,r.extend({},a),f);(e||W.get(this,"finish"))&&b.stop(!0)};return g.finish=g,e||f.queue===!1?this.each(g):this.queue(f.queue,g)},stop:function(a,b,c){var d=function(a){var b=a.stop;delete a.stop,b(c)};return"string"!=typeof a&&(c=b,b=a,a=void 0),b&&a!==!1&&this.queue(a||"fx",[]),this.each(function(){var b=!0,e=null!=a&&a+"queueHooks",f=r.timers,g=W.get(this);if(e)g[e]&&g[e].stop&&d(g[e]);else for(e in g)g[e]&&g[e].stop&&db.test(e)&&d(g[e]);for(e=f.length;e--;)f[e].elem!==this||null!=a&&f[e].queue!==a||(f[e].anim.stop(c),b=!1,f.splice(e,1));!b&&c||r.dequeue(this,a)})},finish:function(a){return a!==!1&&(a=a||"fx"),this.each(function(){var b,c=W.get(this),d=c[a+"queue"],e=c[a+"queueHooks"],f=r.timers,g=d?d.length:0;for(c.finish=!0,r.queue(this,a,[]),e&&e.stop&&e.stop.call(this,!0),b=f.length;b--;)f[b].elem===this&&f[b].queue===a&&(f[b].anim.stop(!0),f.splice(b,1));for(b=0;b<g;b++)d[b]&&d[b].finish&&d[b].finish.call(this);delete c.finish})}}),r.each(["toggle","show","hide"],function(a,b){var c=r.fn[b];r.fn[b]=function(a,d,e){return null==a||"boolean"==typeof a?c.apply(this,arguments):this.animate(gb(b,!0),a,d,e)}}),r.each({slideDown:gb("show"),slideUp:gb("hide"),slideToggle:gb("toggle"),fadeIn:{opacity:"show"},fadeOut:{opacity:"hide"},fadeToggle:{opacity:"toggle"}},function(a,b){r.fn[a]=function(a,c,d){return this.animate(b,a,c,d)}}),r.timers=[],r.fx.tick=function(){var a,b=0,c=r.timers;for(ab=r.now();b<c.length;b++)a=c[b],a()||c[b]!==a||c.splice(b--,1);c.length||r.fx.stop(),ab=void 0},r.fx.timer=function(a){r.timers.push(a),r.fx.start()},r.fx.interval=13,r.fx.start=function(){bb||(bb=!0,eb())},r.fx.stop=function(){bb=null},r.fx.speeds={slow:600,fast:200,_default:400},r.fn.delay=function(b,c){return b=r.fx?r.fx.speeds[b]||b:b,c=c||"fx",this.queue(c,function(c,d){var e=a.setTimeout(c,b);d.stop=function(){a.clearTimeout(e)}})},function(){var a=d.createElement("input"),b=d.createElement("select"),c=b.appendChild(d.createElement("option"));a.type="checkbox",o.checkOn=""!==a.value,o.optSelected=c.selected,a=d.createElement("input"),a.value="t",a.type="radio",o.radioValue="t"===a.value}();var lb,mb=r.expr.attrHandle;r.fn.extend({attr:function(a,b){return T(this,r.attr,a,b,arguments.length>1)},removeAttr:function(a){return this.each(function(){r.removeAttr(this,a)})}}),r.extend({attr:function(a,b,c){var d,e,f=a.nodeType;if(3!==f&&8!==f&&2!==f)return"undefined"==typeof a.getAttribute?r.prop(a,b,c):(1===f&&r.isXMLDoc(a)||(e=r.attrHooks[b.toLowerCase()]||(r.expr.match.bool.test(b)?lb:void 0)),void 0!==c?null===c?void r.removeAttr(a,b):e&&"set"in e&&void 0!==(d=e.set(a,c,b))?d:(a.setAttribute(b,c+""),c):e&&"get"in e&&null!==(d=e.get(a,b))?d:(d=r.find.attr(a,b),
null==d?void 0:d))},attrHooks:{type:{set:function(a,b){if(!o.radioValue&&"radio"===b&&B(a,"input")){var c=a.value;return a.setAttribute("type",b),c&&(a.value=c),b}}}},removeAttr:function(a,b){var c,d=0,e=b&&b.match(L);if(e&&1===a.nodeType)while(c=e[d++])a.removeAttribute(c)}}),lb={set:function(a,b,c){return b===!1?r.removeAttr(a,c):a.setAttribute(c,c),c}},r.each(r.expr.match.bool.source.match(/\w+/g),function(a,b){var c=mb[b]||r.find.attr;mb[b]=function(a,b,d){var e,f,g=b.toLowerCase();return d||(f=mb[g],mb[g]=e,e=null!=c(a,b,d)?g:null,mb[g]=f),e}});var nb=/^(?:input|select|textarea|button)$/i,ob=/^(?:a|area)$/i;r.fn.extend({prop:function(a,b){return T(this,r.prop,a,b,arguments.length>1)},removeProp:function(a){return this.each(function(){delete this[r.propFix[a]||a]})}}),r.extend({prop:function(a,b,c){var d,e,f=a.nodeType;if(3!==f&&8!==f&&2!==f)return 1===f&&r.isXMLDoc(a)||(b=r.propFix[b]||b,e=r.propHooks[b]),void 0!==c?e&&"set"in e&&void 0!==(d=e.set(a,c,b))?d:a[b]=c:e&&"get"in e&&null!==(d=e.get(a,b))?d:a[b]},propHooks:{tabIndex:{get:function(a){var b=r.find.attr(a,"tabindex");return b?parseInt(b,10):nb.test(a.nodeName)||ob.test(a.nodeName)&&a.href?0:-1}}},propFix:{"for":"htmlFor","class":"className"}}),o.optSelected||(r.propHooks.selected={get:function(a){var b=a.parentNode;return b&&b.parentNode&&b.parentNode.selectedIndex,null},set:function(a){var b=a.parentNode;b&&(b.selectedIndex,b.parentNode&&b.parentNode.selectedIndex)}}),r.each(["tabIndex","readOnly","maxLength","cellSpacing","cellPadding","rowSpan","colSpan","useMap","frameBorder","contentEditable"],function(){r.propFix[this.toLowerCase()]=this});function pb(a){var b=a.match(L)||[];return b.join(" ")}function qb(a){return a.getAttribute&&a.getAttribute("class")||""}r.fn.extend({addClass:function(a){var b,c,d,e,f,g,h,i=0;if(r.isFunction(a))return this.each(function(b){r(this).addClass(a.call(this,b,qb(this)))});if("string"==typeof a&&a){b=a.match(L)||[];while(c=this[i++])if(e=qb(c),d=1===c.nodeType&&" "+pb(e)+" "){g=0;while(f=b[g++])d.indexOf(" "+f+" ")<0&&(d+=f+" ");h=pb(d),e!==h&&c.setAttribute("class",h)}}return this},removeClass:function(a){var b,c,d,e,f,g,h,i=0;if(r.isFunction(a))return this.each(function(b){r(this).removeClass(a.call(this,b,qb(this)))});if(!arguments.length)return this.attr("class","");if("string"==typeof a&&a){b=a.match(L)||[];while(c=this[i++])if(e=qb(c),d=1===c.nodeType&&" "+pb(e)+" "){g=0;while(f=b[g++])while(d.indexOf(" "+f+" ")>-1)d=d.replace(" "+f+" "," ");h=pb(d),e!==h&&c.setAttribute("class",h)}}return this},toggleClass:function(a,b){var c=typeof a;return"boolean"==typeof b&&"string"===c?b?this.addClass(a):this.removeClass(a):r.isFunction(a)?this.each(function(c){r(this).toggleClass(a.call(this,c,qb(this),b),b)}):this.each(function(){var b,d,e,f;if("string"===c){d=0,e=r(this),f=a.match(L)||[];while(b=f[d++])e.hasClass(b)?e.removeClass(b):e.addClass(b)}else void 0!==a&&"boolean"!==c||(b=qb(this),b&&W.set(this,"__className__",b),this.setAttribute&&this.setAttribute("class",b||a===!1?"":W.get(this,"__className__")||""))})},hasClass:function(a){var b,c,d=0;b=" "+a+" ";while(c=this[d++])if(1===c.nodeType&&(" "+pb(qb(c))+" ").indexOf(b)>-1)return!0;return!1}});var rb=/\r/g;r.fn.extend({val:function(a){var b,c,d,e=this[0];{if(arguments.length)return d=r.isFunction(a),this.each(function(c){var e;1===this.nodeType&&(e=d?a.call(this,c,r(this).val()):a,null==e?e="":"number"==typeof e?e+="":Array.isArray(e)&&(e=r.map(e,function(a){return null==a?"":a+""})),b=r.valHooks[this.type]||r.valHooks[this.nodeName.toLowerCase()],b&&"set"in b&&void 0!==b.set(this,e,"value")||(this.value=e))});if(e)return b=r.valHooks[e.type]||r.valHooks[e.nodeName.toLowerCase()],b&&"get"in b&&void 0!==(c=b.get(e,"value"))?c:(c=e.value,"string"==typeof c?c.replace(rb,""):null==c?"":c)}}}),r.extend({valHooks:{option:{get:function(a){var b=r.find.attr(a,"value");return null!=b?b:pb(r.text(a))}},select:{get:function(a){var b,c,d,e=a.options,f=a.selectedIndex,g="select-one"===a.type,h=g?null:[],i=g?f+1:e.length;for(d=f<0?i:g?f:0;d<i;d++)if(c=e[d],(c.selected||d===f)&&!c.disabled&&(!c.parentNode.disabled||!B(c.parentNode,"optgroup"))){if(b=r(c).val(),g)return b;h.push(b)}return h},set:function(a,b){var c,d,e=a.options,f=r.makeArray(b),g=e.length;while(g--)d=e[g],(d.selected=r.inArray(r.valHooks.option.get(d),f)>-1)&&(c=!0);return c||(a.selectedIndex=-1),f}}}}),r.each(["radio","checkbox"],function(){r.valHooks[this]={set:function(a,b){if(Array.isArray(b))return a.checked=r.inArray(r(a).val(),b)>-1}},o.checkOn||(r.valHooks[this].get=function(a){return null===a.getAttribute("value")?"on":a.value})});var sb=/^(?:focusinfocus|focusoutblur)$/;r.extend(r.event,{trigger:function(b,c,e,f){var g,h,i,j,k,m,n,o=[e||d],p=l.call(b,"type")?b.type:b,q=l.call(b,"namespace")?b.namespace.split("."):[];if(h=i=e=e||d,3!==e.nodeType&&8!==e.nodeType&&!sb.test(p+r.event.triggered)&&(p.indexOf(".")>-1&&(q=p.split("."),p=q.shift(),q.sort()),k=p.indexOf(":")<0&&"on"+p,b=b[r.expando]?b:new r.Event(p,"object"==typeof b&&b),b.isTrigger=f?2:3,b.namespace=q.join("."),b.rnamespace=b.namespace?new RegExp("(^|\\.)"+q.join("\\.(?:.*\\.|)")+"(\\.|$)"):null,b.result=void 0,b.target||(b.target=e),c=null==c?[b]:r.makeArray(c,[b]),n=r.event.special[p]||{},f||!n.trigger||n.trigger.apply(e,c)!==!1)){if(!f&&!n.noBubble&&!r.isWindow(e)){for(j=n.delegateType||p,sb.test(j+p)||(h=h.parentNode);h;h=h.parentNode)o.push(h),i=h;i===(e.ownerDocument||d)&&o.push(i.defaultView||i.parentWindow||a)}g=0;while((h=o[g++])&&!b.isPropagationStopped())b.type=g>1?j:n.bindType||p,m=(W.get(h,"events")||{})[b.type]&&W.get(h,"handle"),m&&m.apply(h,c),m=k&&h[k],m&&m.apply&&U(h)&&(b.result=m.apply(h,c),b.result===!1&&b.preventDefault());return b.type=p,f||b.isDefaultPrevented()||n._default&&n._default.apply(o.pop(),c)!==!1||!U(e)||k&&r.isFunction(e[p])&&!r.isWindow(e)&&(i=e[k],i&&(e[k]=null),r.event.triggered=p,e[p](),r.event.triggered=void 0,i&&(e[k]=i)),b.result}},simulate:function(a,b,c){var d=r.extend(new r.Event,c,{type:a,isSimulated:!0});r.event.trigger(d,null,b)}}),r.fn.extend({trigger:function(a,b){return this.each(function(){r.event.trigger(a,b,this)})},triggerHandler:function(a,b){var c=this[0];if(c)return r.event.trigger(a,b,c,!0)}}),r.each("blur focus focusin focusout resize scroll click dblclick mousedown mouseup mousemove mouseover mouseout mouseenter mouseleave change select submit keydown keypress keyup contextmenu".split(" "),function(a,b){r.fn[b]=function(a,c){return arguments.length>0?this.on(b,null,a,c):this.trigger(b)}}),r.fn.extend({hover:function(a,b){return this.mouseenter(a).mouseleave(b||a)}}),o.focusin="onfocusin"in a,o.focusin||r.each({focus:"focusin",blur:"focusout"},function(a,b){var c=function(a){r.event.simulate(b,a.target,r.event.fix(a))};r.event.special[b]={setup:function(){var d=this.ownerDocument||this,e=W.access(d,b);e||d.addEventListener(a,c,!0),W.access(d,b,(e||0)+1)},teardown:function(){var d=this.ownerDocument||this,e=W.access(d,b)-1;e?W.access(d,b,e):(d.removeEventListener(a,c,!0),W.remove(d,b))}}});var tb=a.location,ub=r.now(),vb=/\?/;r.parseXML=function(b){var c;if(!b||"string"!=typeof b)return null;try{c=(new a.DOMParser).parseFromString(b,"text/xml")}catch(d){c=void 0}return c&&!c.getElementsByTagName("parsererror").length||r.error("Invalid XML: "+b),c};var wb=/\[\]$/,xb=/\r?\n/g,yb=/^(?:submit|button|image|reset|file)$/i,zb=/^(?:input|select|textarea|keygen)/i;function Ab(a,b,c,d){var e;if(Array.isArray(b))r.each(b,function(b,e){c||wb.test(a)?d(a,e):Ab(a+"["+("object"==typeof e&&null!=e?b:"")+"]",e,c,d)});else if(c||"object"!==r.type(b))d(a,b);else for(e in b)Ab(a+"["+e+"]",b[e],c,d)}r.param=function(a,b){var c,d=[],e=function(a,b){var c=r.isFunction(b)?b():b;d[d.length]=encodeURIComponent(a)+"="+encodeURIComponent(null==c?"":c)};if(Array.isArray(a)||a.jquery&&!r.isPlainObject(a))r.each(a,function(){e(this.name,this.value)});else for(c in a)Ab(c,a[c],b,e);return d.join("&")},r.fn.extend({serialize:function(){return r.param(this.serializeArray())},serializeArray:function(){return this.map(function(){var a=r.prop(this,"elements");return a?r.makeArray(a):this}).filter(function(){var a=this.type;return this.name&&!r(this).is(":disabled")&&zb.test(this.nodeName)&&!yb.test(a)&&(this.checked||!ja.test(a))}).map(function(a,b){var c=r(this).val();return null==c?null:Array.isArray(c)?r.map(c,function(a){return{name:b.name,value:a.replace(xb,"\r\n")}}):{name:b.name,value:c.replace(xb,"\r\n")}}).get()}});var Bb=/%20/g,Cb=/#.*$/,Db=/([?&])_=[^&]*/,Eb=/^(.*?):[ \t]*([^\r\n]*)$/gm,Fb=/^(?:about|app|app-storage|.+-extension|file|res|widget):$/,Gb=/^(?:GET|HEAD)$/,Hb=/^\/\//,Ib={},Jb={},Kb="*/".concat("*"),Lb=d.createElement("a");Lb.href=tb.href;function Mb(a){return function(b,c){"string"!=typeof b&&(c=b,b="*");var d,e=0,f=b.toLowerCase().match(L)||[];if(r.isFunction(c))while(d=f[e++])"+"===d[0]?(d=d.slice(1)||"*",(a[d]=a[d]||[]).unshift(c)):(a[d]=a[d]||[]).push(c)}}function Nb(a,b,c,d){var e={},f=a===Jb;function g(h){var i;return e[h]=!0,r.each(a[h]||[],function(a,h){var j=h(b,c,d);return"string"!=typeof j||f||e[j]?f?!(i=j):void 0:(b.dataTypes.unshift(j),g(j),!1)}),i}return g(b.dataTypes[0])||!e["*"]&&g("*")}function Ob(a,b){var c,d,e=r.ajaxSettings.flatOptions||{};for(c in b)void 0!==b[c]&&((e[c]?a:d||(d={}))[c]=b[c]);return d&&r.extend(!0,a,d),a}function Pb(a,b,c){var d,e,f,g,h=a.contents,i=a.dataTypes;while("*"===i[0])i.shift(),void 0===d&&(d=a.mimeType||b.getResponseHeader("Content-Type"));if(d)for(e in h)if(h[e]&&h[e].test(d)){i.unshift(e);break}if(i[0]in c)f=i[0];else{for(e in c){if(!i[0]||a.converters[e+" "+i[0]]){f=e;break}g||(g=e)}f=f||g}if(f)return f!==i[0]&&i.unshift(f),c[f]}function Qb(a,b,c,d){var e,f,g,h,i,j={},k=a.dataTypes.slice();if(k[1])for(g in a.converters)j[g.toLowerCase()]=a.converters[g];f=k.shift();while(f)if(a.responseFields[f]&&(c[a.responseFields[f]]=b),!i&&d&&a.dataFilter&&(b=a.dataFilter(b,a.dataType)),i=f,f=k.shift())if("*"===f)f=i;else if("*"!==i&&i!==f){if(g=j[i+" "+f]||j["* "+f],!g)for(e in j)if(h=e.split(" "),h[1]===f&&(g=j[i+" "+h[0]]||j["* "+h[0]])){g===!0?g=j[e]:j[e]!==!0&&(f=h[0],k.unshift(h[1]));break}if(g!==!0)if(g&&a["throws"])b=g(b);else try{b=g(b)}catch(l){return{state:"parsererror",error:g?l:"No conversion from "+i+" to "+f}}}return{state:"success",data:b}}r.extend({active:0,lastModified:{},etag:{},ajaxSettings:{url:tb.href,type:"GET",isLocal:Fb.test(tb.protocol),global:!0,processData:!0,async:!0,contentType:"application/x-www-form-urlencoded; charset=UTF-8",accepts:{"*":Kb,text:"text/plain",html:"text/html",xml:"application/xml, text/xml",json:"application/json, text/javascript"},contents:{xml:/\bxml\b/,html:/\bhtml/,json:/\bjson\b/},responseFields:{xml:"responseXML",text:"responseText",json:"responseJSON"},converters:{"* text":String,"text html":!0,"text json":JSON.parse,"text xml":r.parseXML},flatOptions:{url:!0,context:!0}},ajaxSetup:function(a,b){return b?Ob(Ob(a,r.ajaxSettings),b):Ob(r.ajaxSettings,a)},ajaxPrefilter:Mb(Ib),ajaxTransport:Mb(Jb),ajax:function(b,c){"object"==typeof b&&(c=b,b=void 0),c=c||{};var e,f,g,h,i,j,k,l,m,n,o=r.ajaxSetup({},c),p=o.context||o,q=o.context&&(p.nodeType||p.jquery)?r(p):r.event,s=r.Deferred(),t=r.Callbacks("once memory"),u=o.statusCode||{},v={},w={},x="canceled",y={readyState:0,getResponseHeader:function(a){var b;if(k){if(!h){h={};while(b=Eb.exec(g))h[b[1].toLowerCase()]=b[2]}b=h[a.toLowerCase()]}return null==b?null:b},getAllResponseHeaders:function(){return k?g:null},setRequestHeader:function(a,b){return null==k&&(a=w[a.toLowerCase()]=w[a.toLowerCase()]||a,v[a]=b),this},overrideMimeType:function(a){return null==k&&(o.mimeType=a),this},statusCode:function(a){var b;if(a)if(k)y.always(a[y.status]);else for(b in a)u[b]=[u[b],a[b]];return this},abort:function(a){var b=a||x;return e&&e.abort(b),A(0,b),this}};if(s.promise(y),o.url=((b||o.url||tb.href)+"").replace(Hb,tb.protocol+"//"),o.type=c.method||c.type||o.method||o.type,o.dataTypes=(o.dataType||"*").toLowerCase().match(L)||[""],null==o.crossDomain){j=d.createElement("a");try{j.href=o.url,j.href=j.href,o.crossDomain=Lb.protocol+"//"+Lb.host!=j.protocol+"//"+j.host}catch(z){o.crossDomain=!0}}if(o.data&&o.processData&&"string"!=typeof o.data&&(o.data=r.param(o.data,o.traditional)),Nb(Ib,o,c,y),k)return y;l=r.event&&o.global,l&&0===r.active++&&r.event.trigger("ajaxStart"),o.type=o.type.toUpperCase(),o.hasContent=!Gb.test(o.type),f=o.url.replace(Cb,""),o.hasContent?o.data&&o.processData&&0===(o.contentType||"").indexOf("application/x-www-form-urlencoded")&&(o.data=o.data.replace(Bb,"+")):(n=o.url.slice(f.length),o.data&&(f+=(vb.test(f)?"&":"?")+o.data,delete o.data),o.cache===!1&&(f=f.replace(Db,"$1"),n=(vb.test(f)?"&":"?")+"_="+ub++ +n),o.url=f+n),o.ifModified&&(r.lastModified[f]&&y.setRequestHeader("If-Modified-Since",r.lastModified[f]),r.etag[f]&&y.setRequestHeader("If-None-Match",r.etag[f])),(o.data&&o.hasContent&&o.contentType!==!1||c.contentType)&&y.setRequestHeader("Content-Type",o.contentType),y.setRequestHeader("Accept",o.dataTypes[0]&&o.accepts[o.dataTypes[0]]?o.accepts[o.dataTypes[0]]+("*"!==o.dataTypes[0]?", "+Kb+"; q=0.01":""):o.accepts["*"]);for(m in o.headers)y.setRequestHeader(m,o.headers[m]);if(o.beforeSend&&(o.beforeSend.call(p,y,o)===!1||k))return y.abort();if(x="abort",t.add(o.complete),y.done(o.success),y.fail(o.error),e=Nb(Jb,o,c,y)){if(y.readyState=1,l&&q.trigger("ajaxSend",[y,o]),k)return y;o.async&&o.timeout>0&&(i=a.setTimeout(function(){y.abort("timeout")},o.timeout));try{k=!1,e.send(v,A)}catch(z){if(k)throw z;A(-1,z)}}else A(-1,"No Transport");function A(b,c,d,h){var j,m,n,v,w,x=c;k||(k=!0,i&&a.clearTimeout(i),e=void 0,g=h||"",y.readyState=b>0?4:0,j=b>=200&&b<300||304===b,d&&(v=Pb(o,y,d)),v=Qb(o,v,y,j),j?(o.ifModified&&(w=y.getResponseHeader("Last-Modified"),w&&(r.lastModified[f]=w),w=y.getResponseHeader("etag"),w&&(r.etag[f]=w)),204===b||"HEAD"===o.type?x="nocontent":304===b?x="notmodified":(x=v.state,m=v.data,n=v.error,j=!n)):(n=x,!b&&x||(x="error",b<0&&(b=0))),y.status=b,y.statusText=(c||x)+"",j?s.resolveWith(p,[m,x,y]):s.rejectWith(p,[y,x,n]),y.statusCode(u),u=void 0,l&&q.trigger(j?"ajaxSuccess":"ajaxError",[y,o,j?m:n]),t.fireWith(p,[y,x]),l&&(q.trigger("ajaxComplete",[y,o]),--r.active||r.event.trigger("ajaxStop")))}return y},getJSON:function(a,b,c){return r.get(a,b,c,"json")},getScript:function(a,b){return r.get(a,void 0,b,"script")}}),r.each(["get","post"],function(a,b){r[b]=function(a,c,d,e){return r.isFunction(c)&&(e=e||d,d=c,c=void 0),r.ajax(r.extend({url:a,type:b,dataType:e,data:c,success:d},r.isPlainObject(a)&&a))}}),r._evalUrl=function(a){return r.ajax({url:a,type:"GET",dataType:"script",cache:!0,async:!1,global:!1,"throws":!0})},r.fn.extend({wrapAll:function(a){var b;return this[0]&&(r.isFunction(a)&&(a=a.call(this[0])),b=r(a,this[0].ownerDocument).eq(0).clone(!0),this[0].parentNode&&b.insertBefore(this[0]),b.map(function(){var a=this;while(a.firstElementChild)a=a.firstElementChild;return a}).append(this)),this},wrapInner:function(a){return r.isFunction(a)?this.each(function(b){r(this).wrapInner(a.call(this,b))}):this.each(function(){var b=r(this),c=b.contents();c.length?c.wrapAll(a):b.append(a)})},wrap:function(a){var b=r.isFunction(a);return this.each(function(c){r(this).wrapAll(b?a.call(this,c):a)})},unwrap:function(a){return this.parent(a).not("body").each(function(){r(this).replaceWith(this.childNodes)}),this}}),r.expr.pseudos.hidden=function(a){return!r.expr.pseudos.visible(a)},r.expr.pseudos.visible=function(a){return!!(a.offsetWidth||a.offsetHeight||a.getClientRects().length)},r.ajaxSettings.xhr=function(){try{return new a.XMLHttpRequest}catch(b){}};var Rb={0:200,1223:204},Sb=r.ajaxSettings.xhr();o.cors=!!Sb&&"withCredentials"in Sb,o.ajax=Sb=!!Sb,r.ajaxTransport(function(b){var c,d;if(o.cors||Sb&&!b.crossDomain)return{send:function(e,f){var g,h=b.xhr();if(h.open(b.type,b.url,b.async,b.username,b.password),b.xhrFields)for(g in b.xhrFields)h[g]=b.xhrFields[g];b.mimeType&&h.overrideMimeType&&h.overrideMimeType(b.mimeType),b.crossDomain||e["X-Requested-With"]||(e["X-Requested-With"]="XMLHttpRequest");for(g in e)h.setRequestHeader(g,e[g]);c=function(a){return function(){c&&(c=d=h.onload=h.onerror=h.onabort=h.onreadystatechange=null,"abort"===a?h.abort():"error"===a?"number"!=typeof h.status?f(0,"error"):f(h.status,h.statusText):f(Rb[h.status]||h.status,h.statusText,"text"!==(h.responseType||"text")||"string"!=typeof h.responseText?{binary:h.response}:{text:h.responseText},h.getAllResponseHeaders()))}},h.onload=c(),d=h.onerror=c("error"),void 0!==h.onabort?h.onabort=d:h.onreadystatechange=function(){4===h.readyState&&a.setTimeout(function(){c&&d()})},c=c("abort");try{h.send(b.hasContent&&b.data||null)}catch(i){if(c)throw i}},abort:function(){c&&c()}}}),r.ajaxPrefilter(function(a){a.crossDomain&&(a.contents.script=!1)}),r.ajaxSetup({accepts:{script:"text/javascript, application/javascript, application/ecmascript, application/x-ecmascript"},contents:{script:/\b(?:java|ecma)script\b/},converters:{"text script":function(a){return r.globalEval(a),a}}}),r.ajaxPrefilter("script",function(a){void 0===a.cache&&(a.cache=!1),a.crossDomain&&(a.type="GET")}),r.ajaxTransport("script",function(a){if(a.crossDomain){var b,c;return{send:function(e,f){b=r("<script>").prop({charset:a.scriptCharset,src:a.url}).on("load error",c=function(a){b.remove(),c=null,a&&f("error"===a.type?404:200,a.type)}),d.head.appendChild(b[0])},abort:function(){c&&c()}}}});var Tb=[],Ub=/(=)\?(?=&|$)|\?\?/;r.ajaxSetup({jsonp:"callback",jsonpCallback:function(){var a=Tb.pop()||r.expando+"_"+ub++;return this[a]=!0,a}}),r.ajaxPrefilter("json jsonp",function(b,c,d){var e,f,g,h=b.jsonp!==!1&&(Ub.test(b.url)?"url":"string"==typeof b.data&&0===(b.contentType||"").indexOf("application/x-www-form-urlencoded")&&Ub.test(b.data)&&"data");if(h||"jsonp"===b.dataTypes[0])return e=b.jsonpCallback=r.isFunction(b.jsonpCallback)?b.jsonpCallback():b.jsonpCallback,h?b[h]=b[h].replace(Ub,"$1"+e):b.jsonp!==!1&&(b.url+=(vb.test(b.url)?"&":"?")+b.jsonp+"="+e),b.converters["script json"]=function(){return g||r.error(e+" was not called"),g[0]},b.dataTypes[0]="json",f=a[e],a[e]=function(){g=arguments},d.always(function(){void 0===f?r(a).removeProp(e):a[e]=f,b[e]&&(b.jsonpCallback=c.jsonpCallback,Tb.push(e)),g&&r.isFunction(f)&&f(g[0]),g=f=void 0}),"script"}),o.createHTMLDocument=function(){var a=d.implementation.createHTMLDocument("").body;return a.innerHTML="<form></form><form></form>",2===a.childNodes.length}(),r.parseHTML=function(a,b,c){if("string"!=typeof a)return[];"boolean"==typeof b&&(c=b,b=!1);var e,f,g;return b||(o.createHTMLDocument?(b=d.implementation.createHTMLDocument(""),e=b.createElement("base"),e.href=d.location.href,b.head.appendChild(e)):b=d),f=C.exec(a),g=!c&&[],f?[b.createElement(f[1])]:(f=qa([a],b,g),g&&g.length&&r(g).remove(),r.merge([],f.childNodes))},r.fn.load=function(a,b,c){var d,e,f,g=this,h=a.indexOf(" ");return h>-1&&(d=pb(a.slice(h)),a=a.slice(0,h)),r.isFunction(b)?(c=b,b=void 0):b&&"object"==typeof b&&(e="POST"),g.length>0&&r.ajax({url:a,type:e||"GET",dataType:"html",data:b}).done(function(a){f=arguments,g.html(d?r("<div>").append(r.parseHTML(a)).find(d):a)}).always(c&&function(a,b){g.each(function(){c.apply(this,f||[a.responseText,b,a])})}),this},r.each(["ajaxStart","ajaxStop","ajaxComplete","ajaxError","ajaxSuccess","ajaxSend"],function(a,b){r.fn[b]=function(a){return this.on(b,a)}}),r.expr.pseudos.animated=function(a){return r.grep(r.timers,function(b){return a===b.elem}).length},r.offset={setOffset:function(a,b,c){var d,e,f,g,h,i,j,k=r.css(a,"position"),l=r(a),m={};"static"===k&&(a.style.position="relative"),h=l.offset(),f=r.css(a,"top"),i=r.css(a,"left"),j=("absolute"===k||"fixed"===k)&&(f+i).indexOf("auto")>-1,j?(d=l.position(),g=d.top,e=d.left):(g=parseFloat(f)||0,e=parseFloat(i)||0),r.isFunction(b)&&(b=b.call(a,c,r.extend({},h))),null!=b.top&&(m.top=b.top-h.top+g),null!=b.left&&(m.left=b.left-h.left+e),"using"in b?b.using.call(a,m):l.css(m)}},r.fn.extend({offset:function(a){if(arguments.length)return void 0===a?this:this.each(function(b){r.offset.setOffset(this,a,b)});var b,c,d,e,f=this[0];if(f)return f.getClientRects().length?(d=f.getBoundingClientRect(),b=f.ownerDocument,c=b.documentElement,e=b.defaultView,{top:d.top+e.pageYOffset-c.clientTop,left:d.left+e.pageXOffset-c.clientLeft}):{top:0,left:0}},position:function(){if(this[0]){var a,b,c=this[0],d={top:0,left:0};return"fixed"===r.css(c,"position")?b=c.getBoundingClientRect():(a=this.offsetParent(),b=this.offset(),B(a[0],"html")||(d=a.offset()),d={top:d.top+r.css(a[0],"borderTopWidth",!0),left:d.left+r.css(a[0],"borderLeftWidth",!0)}),{top:b.top-d.top-r.css(c,"marginTop",!0),left:b.left-d.left-r.css(c,"marginLeft",!0)}}},offsetParent:function(){return this.map(function(){var a=this.offsetParent;while(a&&"static"===r.css(a,"position"))a=a.offsetParent;return a||ra})}}),r.each({scrollLeft:"pageXOffset",scrollTop:"pageYOffset"},function(a,b){var c="pageYOffset"===b;r.fn[a]=function(d){return T(this,function(a,d,e){var f;return r.isWindow(a)?f=a:9===a.nodeType&&(f=a.defaultView),void 0===e?f?f[b]:a[d]:void(f?f.scrollTo(c?f.pageXOffset:e,c?e:f.pageYOffset):a[d]=e)},a,d,arguments.length)}}),r.each(["top","left"],function(a,b){r.cssHooks[b]=Pa(o.pixelPosition,function(a,c){if(c)return c=Oa(a,b),Ma.test(c)?r(a).position()[b]+"px":c})}),r.each({Height:"height",Width:"width"},function(a,b){r.each({padding:"inner"+a,content:b,"":"outer"+a},function(c,d){r.fn[d]=function(e,f){var g=arguments.length&&(c||"boolean"!=typeof e),h=c||(e===!0||f===!0?"margin":"border");return T(this,function(b,c,e){var f;return r.isWindow(b)?0===d.indexOf("outer")?b["inner"+a]:b.document.documentElement["client"+a]:9===b.nodeType?(f=b.documentElement,Math.max(b.body["scroll"+a],f["scroll"+a],b.body["offset"+a],f["offset"+a],f["client"+a])):void 0===e?r.css(b,c,h):r.style(b,c,e,h)},b,g?e:void 0,g)}})}),r.fn.extend({bind:function(a,b,c){return this.on(a,null,b,c)},unbind:function(a,b){return this.off(a,null,b)},delegate:function(a,b,c,d){return this.on(b,a,c,d)},undelegate:function(a,b,c){return 1===arguments.length?this.off(a,"**"):this.off(b,a||"**",c)}}),r.holdReady=function(a){a?r.readyWait++:r.ready(!0)},r.isArray=Array.isArray,r.parseJSON=JSON.parse,r.nodeName=B,"function"==typeof define&&define.amd&&define("jquery",[],function(){return r});var Vb=a.jQuery,Wb=a.$;return r.noConflict=function(b){return a.$===r&&(a.$=Wb),b&&a.jQuery===r&&(a.jQuery=Vb),r},b||(a.jQuery=a.$=r),r});
PK
%�\���Z Z html/_static/minus.pngnu �[��� �PNG
IHDR ��(� !IDATxc8� g>@�;(� !�&�� �� ]�f2n�N IEND�B`�PK
%�\�]l�= = html/_static/opensearch.xmlnu �[��� <?xml version="1.0" encoding="UTF-8"?>
<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">
<ShortName>Python</ShortName>
<Description>Search Python 2.7.16 documentation</Description>
<InputEncoding>utf-8</InputEncoding>
<Url type="text/html" method="get"
template="https://docs.python.org//search.html?q={searchTerms}&check_keywords=yes&area=default"/>
<LongName>Python 2.7.16 documentation</LongName>
<Image height="16" width="16" type="image/x-icon">https://www.python.org/images/favicon16x16.ico</Image>
</OpenSearchDescription>PK
%�\��%ZZ Z html/_static/plus.pngnu �[��� �PNG
IHDR ��(� !IDATxc8� g>@�;([�[�U�
@l -!a���@ IEND�B`�PK
%�\��
ͷ � html/_static/py.pngnu �[��� �PNG
IHDR �a sRGB �� � bKGD � � ����� pHYs �� tIME�8!3'^ 7IDAT8�e�OHUA��{߳w{"���&hS�6�Z� mB*xP�MQ��A� "�)mZH� FEF������2���y3g�����;�7̜�]���3i�sޙv�M����U����}�\·� x'G�j�N,�Z�X�wQ���1 *�{
8k9g'v;�͏;�j�/t?|�[{\�
�N�j�E�%g �J=M}�W�Ҏ� }x��v�^�{�Tn�J�N���\}��X�nܯ�zw/��umY5;mg����Q�" �SQ}�,�/�|��i���'}�S��@B�ځ�����������Wk� )`��j'�J/N�K@��e1M��FN,j}yhb�wp��+�щK�S�Xb���@:����ɗ��_�=mU5�EqR'�4I�N&t:�c��祝�j�.l
��`zF� 6��gu G�f�pm"�����J��(p
�o���ٞ�q�G0�"���n��:"�,�%8��4 ��+!್`��DoY-��4�ً, ߳5�3 ������gob�;��3c��]�I��i�ވ�C��
h�\nf]���� ����� � IEND�B`�PK
%�\�PlS+ + html/_static/pygments.cssnu �[��� .highlight .hll { background-color: #ffffcc }
.highlight { background: #eeffcc; }
.highlight .c { color: #408090; font-style: italic } /* Comment */
.highlight .err { border: 1px solid #FF0000 } /* Error */
.highlight .k { color: #007020; font-weight: bold } /* Keyword */
.highlight .o { color: #666666 } /* Operator */
.highlight .ch { color: #408090; font-style: italic } /* Comment.Hashbang */
.highlight .cm { color: #408090; font-style: italic } /* Comment.Multiline */
.highlight .cp { color: #007020 } /* Comment.Preproc */
.highlight .cpf { color: #408090; font-style: italic } /* Comment.PreprocFile */
.highlight .c1 { color: #408090; font-style: italic } /* Comment.Single */
.highlight .cs { color: #408090; background-color: #fff0f0 } /* Comment.Special */
.highlight .gd { color: #A00000 } /* Generic.Deleted */
.highlight .ge { font-style: italic } /* Generic.Emph */
.highlight .gr { color: #FF0000 } /* Generic.Error */
.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */
.highlight .gi { color: #00A000 } /* Generic.Inserted */
.highlight .go { color: #333333 } /* Generic.Output */
.highlight .gp { color: #c65d09; font-weight: bold } /* Generic.Prompt */
.highlight .gs { font-weight: bold } /* Generic.Strong */
.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */
.highlight .gt { color: #0044DD } /* Generic.Traceback */
.highlight .kc { color: #007020; font-weight: bold } /* Keyword.Constant */
.highlight .kd { color: #007020; font-weight: bold } /* Keyword.Declaration */
.highlight .kn { color: #007020; font-weight: bold } /* Keyword.Namespace */
.highlight .kp { color: #007020 } /* Keyword.Pseudo */
.highlight .kr { color: #007020; font-weight: bold } /* Keyword.Reserved */
.highlight .kt { color: #902000 } /* Keyword.Type */
.highlight .m { color: #208050 } /* Literal.Number */
.highlight .s { color: #4070a0 } /* Literal.String */
.highlight .na { color: #4070a0 } /* Name.Attribute */
.highlight .nb { color: #007020 } /* Name.Builtin */
.highlight .nc { color: #0e84b5; font-weight: bold } /* Name.Class */
.highlight .no { color: #60add5 } /* Name.Constant */
.highlight .nd { color: #555555; font-weight: bold } /* Name.Decorator */
.highlight .ni { color: #d55537; font-weight: bold } /* Name.Entity */
.highlight .ne { color: #007020 } /* Name.Exception */
.highlight .nf { color: #06287e } /* Name.Function */
.highlight .nl { color: #002070; font-weight: bold } /* Name.Label */
.highlight .nn { color: #0e84b5; font-weight: bold } /* Name.Namespace */
.highlight .nt { color: #062873; font-weight: bold } /* Name.Tag */
.highlight .nv { color: #bb60d5 } /* Name.Variable */
.highlight .ow { color: #007020; font-weight: bold } /* Operator.Word */
.highlight .w { color: #bbbbbb } /* Text.Whitespace */
.highlight .mb { color: #208050 } /* Literal.Number.Bin */
.highlight .mf { color: #208050 } /* Literal.Number.Float */
.highlight .mh { color: #208050 } /* Literal.Number.Hex */
.highlight .mi { color: #208050 } /* Literal.Number.Integer */
.highlight .mo { color: #208050 } /* Literal.Number.Oct */
.highlight .sa { color: #4070a0 } /* Literal.String.Affix */
.highlight .sb { color: #4070a0 } /* Literal.String.Backtick */
.highlight .sc { color: #4070a0 } /* Literal.String.Char */
.highlight .dl { color: #4070a0 } /* Literal.String.Delimiter */
.highlight .sd { color: #4070a0; font-style: italic } /* Literal.String.Doc */
.highlight .s2 { color: #4070a0 } /* Literal.String.Double */
.highlight .se { color: #4070a0; font-weight: bold } /* Literal.String.Escape */
.highlight .sh { color: #4070a0 } /* Literal.String.Heredoc */
.highlight .si { color: #70a0d0; font-style: italic } /* Literal.String.Interpol */
.highlight .sx { color: #c65d09 } /* Literal.String.Other */
.highlight .sr { color: #235388 } /* Literal.String.Regex */
.highlight .s1 { color: #4070a0 } /* Literal.String.Single */
.highlight .ss { color: #517918 } /* Literal.String.Symbol */
.highlight .bp { color: #007020 } /* Name.Builtin.Pseudo */
.highlight .fm { color: #06287e } /* Name.Function.Magic */
.highlight .vc { color: #bb60d5 } /* Name.Variable.Class */
.highlight .vg { color: #bb60d5 } /* Name.Variable.Global */
.highlight .vi { color: #bb60d5 } /* Name.Variable.Instance */
.highlight .vm { color: #bb60d5 } /* Name.Variable.Magic */
.highlight .il { color: #208050 } /* Literal.Number.Integer.Long */PK
%�\����ic ic html/_static/searchtools.jsnu �[��� /*
* searchtools.js_t
* ~~~~~~~~~~~~~~~~
*
* Sphinx JavaScript utilities for the full-text search.
*
* :copyright: Copyright 2007-2018 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/
/* Non-minified version JS is _stemmer.js if file is provided */
/**
* Porter Stemmer
*/
var Stemmer = function() {
var step2list = {
ational: 'ate',
tional: 'tion',
enci: 'ence',
anci: 'ance',
izer: 'ize',
bli: 'ble',
alli: 'al',
entli: 'ent',
eli: 'e',
ousli: 'ous',
ization: 'ize',
ation: 'ate',
ator: 'ate',
alism: 'al',
iveness: 'ive',
fulness: 'ful',
ousness: 'ous',
aliti: 'al',
iviti: 'ive',
biliti: 'ble',
logi: 'log'
};
var step3list = {
icate: 'ic',
ative: '',
alize: 'al',
iciti: 'ic',
ical: 'ic',
ful: '',
ness: ''
};
var c = "[^aeiou]"; // consonant
var v = "[aeiouy]"; // vowel
var C = c + "[^aeiouy]*"; // consonant sequence
var V = v + "[aeiou]*"; // vowel sequence
var mgr0 = "^(" + C + ")?" + V + C; // [C]VC... is m>0
var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$"; // [C]VC[V] is m=1
var mgr1 = "^(" + C + ")?" + V + C + V + C; // [C]VCVC... is m>1
var s_v = "^(" + C + ")?" + v; // vowel in stem
this.stemWord = function (w) {
var stem;
var suffix;
var firstch;
var origword = w;
if (w.length < 3)
return w;
var re;
var re2;
var re3;
var re4;
firstch = w.substr(0,1);
if (firstch == "y")
w = firstch.toUpperCase() + w.substr(1);
// Step 1a
re = /^(.+?)(ss|i)es$/;
re2 = /^(.+?)([^s])s$/;
if (re.test(w))
w = w.replace(re,"$1$2");
else if (re2.test(w))
w = w.replace(re2,"$1$2");
// Step 1b
re = /^(.+?)eed$/;
re2 = /^(.+?)(ed|ing)$/;
if (re.test(w)) {
var fp = re.exec(w);
re = new RegExp(mgr0);
if (re.test(fp[1])) {
re = /.$/;
w = w.replace(re,"");
}
}
else if (re2.test(w)) {
var fp = re2.exec(w);
stem = fp[1];
re2 = new RegExp(s_v);
if (re2.test(stem)) {
w = stem;
re2 = /(at|bl|iz)$/;
re3 = new RegExp("([^aeiouylsz])\\1$");
re4 = new RegExp("^" + C + v + "[^aeiouwxy]$");
if (re2.test(w))
w = w + "e";
else if (re3.test(w)) {
re = /.$/;
w = w.replace(re,"");
}
else if (re4.test(w))
w = w + "e";
}
}
// Step 1c
re = /^(.+?)y$/;
if (re.test(w)) {
var fp = re.exec(w);
stem = fp[1];
re = new RegExp(s_v);
if (re.test(stem))
w = stem + "i";
}
// Step 2
re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/;
if (re.test(w)) {
var fp = re.exec(w);
stem = fp[1];
suffix = fp[2];
re = new RegExp(mgr0);
if (re.test(stem))
w = stem + step2list[suffix];
}
// Step 3
re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/;
if (re.test(w)) {
var fp = re.exec(w);
stem = fp[1];
suffix = fp[2];
re = new RegExp(mgr0);
if (re.test(stem))
w = stem + step3list[suffix];
}
// Step 4
re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/;
re2 = /^(.+?)(s|t)(ion)$/;
if (re.test(w)) {
var fp = re.exec(w);
stem = fp[1];
re = new RegExp(mgr1);
if (re.test(stem))
w = stem;
}
else if (re2.test(w)) {
var fp = re2.exec(w);
stem = fp[1] + fp[2];
re2 = new RegExp(mgr1);
if (re2.test(stem))
w = stem;
}
// Step 5
re = /^(.+?)e$/;
if (re.test(w)) {
var fp = re.exec(w);
stem = fp[1];
re = new RegExp(mgr1);
re2 = new RegExp(meq1);
re3 = new RegExp("^" + C + v + "[^aeiouwxy]$");
if (re.test(stem) || (re2.test(stem) && !(re3.test(stem))))
w = stem;
}
re = /ll$/;
re2 = new RegExp(mgr1);
if (re.test(w) && re2.test(w)) {
re = /.$/;
w = w.replace(re,"");
}
// and turn initial Y back to y
if (firstch == "y")
w = firstch.toLowerCase() + w.substr(1);
return w;
}
}
/**
* Simple result scoring code.
*/
var Scorer = {
// Implement the following function to further tweak the score for each result
// The function takes a result array [filename, title, anchor, descr, score]
// and returns the new score.
/*
score: function(result) {
return result[4];
},
*/
// query matches the full name of an object
objNameMatch: 11,
// or matches in the last dotted part of the object name
objPartialMatch: 6,
// Additive scores depending on the priority of the object
objPrio: {0: 15, // used to be importantResults
1: 5, // used to be objectResults
2: -5}, // used to be unimportantResults
// Used when the priority is not in the mapping.
objPrioDefault: 0,
// query found in title
title: 15,
// query found in terms
term: 5
};
var splitChars = (function() {
var result = {};
var singles = [96, 180, 187, 191, 215, 247, 749, 885, 903, 907, 909, 930, 1014, 1648,
1748, 1809, 2416, 2473, 2481, 2526, 2601, 2609, 2612, 2615, 2653, 2702,
2706, 2729, 2737, 2740, 2857, 2865, 2868, 2910, 2928, 2948, 2961, 2971,
2973, 3085, 3089, 3113, 3124, 3213, 3217, 3241, 3252, 3295, 3341, 3345,
3369, 3506, 3516, 3633, 3715, 3721, 3736, 3744, 3748, 3750, 3756, 3761,
3781, 3912, 4239, 4347, 4681, 4695, 4697, 4745, 4785, 4799, 4801, 4823,
4881, 5760, 5901, 5997, 6313, 7405, 8024, 8026, 8028, 8030, 8117, 8125,
8133, 8181, 8468, 8485, 8487, 8489, 8494, 8527, 11311, 11359, 11687, 11695,
11703, 11711, 11719, 11727, 11735, 12448, 12539, 43010, 43014, 43019, 43587,
43696, 43713, 64286, 64297, 64311, 64317, 64319, 64322, 64325, 65141];
var i, j, start, end;
for (i = 0; i < singles.length; i++) {
result[singles[i]] = true;
}
var ranges = [[0, 47], [58, 64], [91, 94], [123, 169], [171, 177], [182, 184], [706, 709],
[722, 735], [741, 747], [751, 879], [888, 889], [894, 901], [1154, 1161],
[1318, 1328], [1367, 1368], [1370, 1376], [1416, 1487], [1515, 1519], [1523, 1568],
[1611, 1631], [1642, 1645], [1750, 1764], [1767, 1773], [1789, 1790], [1792, 1807],
[1840, 1868], [1958, 1968], [1970, 1983], [2027, 2035], [2038, 2041], [2043, 2047],
[2070, 2073], [2075, 2083], [2085, 2087], [2089, 2307], [2362, 2364], [2366, 2383],
[2385, 2391], [2402, 2405], [2419, 2424], [2432, 2436], [2445, 2446], [2449, 2450],
[2483, 2485], [2490, 2492], [2494, 2509], [2511, 2523], [2530, 2533], [2546, 2547],
[2554, 2564], [2571, 2574], [2577, 2578], [2618, 2648], [2655, 2661], [2672, 2673],
[2677, 2692], [2746, 2748], [2750, 2767], [2769, 2783], [2786, 2789], [2800, 2820],
[2829, 2830], [2833, 2834], [2874, 2876], [2878, 2907], [2914, 2917], [2930, 2946],
[2955, 2957], [2966, 2968], [2976, 2978], [2981, 2983], [2987, 2989], [3002, 3023],
[3025, 3045], [3059, 3076], [3130, 3132], [3134, 3159], [3162, 3167], [3170, 3173],
[3184, 3191], [3199, 3204], [3258, 3260], [3262, 3293], [3298, 3301], [3312, 3332],
[3386, 3388], [3390, 3423], [3426, 3429], [3446, 3449], [3456, 3460], [3479, 3481],
[3518, 3519], [3527, 3584], [3636, 3647], [3655, 3663], [3674, 3712], [3717, 3718],
[3723, 3724], [3726, 3731], [3752, 3753], [3764, 3772], [3774, 3775], [3783, 3791],
[3802, 3803], [3806, 3839], [3841, 3871], [3892, 3903], [3949, 3975], [3980, 4095],
[4139, 4158], [4170, 4175], [4182, 4185], [4190, 4192], [4194, 4196], [4199, 4205],
[4209, 4212], [4226, 4237], [4250, 4255], [4294, 4303], [4349, 4351], [4686, 4687],
[4702, 4703], [4750, 4751], [4790, 4791], [4806, 4807], [4886, 4887], [4955, 4968],
[4989, 4991], [5008, 5023], [5109, 5120], [5741, 5742], [5787, 5791], [5867, 5869],
[5873, 5887], [5906, 5919], [5938, 5951], [5970, 5983], [6001, 6015], [6068, 6102],
[6104, 6107], [6109, 6111], [6122, 6127], [6138, 6159], [6170, 6175], [6264, 6271],
[6315, 6319], [6390, 6399], [6429, 6469], [6510, 6511], [6517, 6527], [6572, 6592],
[6600, 6607], [6619, 6655], [6679, 6687], [6741, 6783], [6794, 6799], [6810, 6822],
[6824, 6916], [6964, 6980], [6988, 6991], [7002, 7042], [7073, 7085], [7098, 7167],
[7204, 7231], [7242, 7244], [7294, 7400], [7410, 7423], [7616, 7679], [7958, 7959],
[7966, 7967], [8006, 8007], [8014, 8015], [8062, 8063], [8127, 8129], [8141, 8143],
[8148, 8149], [8156, 8159], [8173, 8177], [8189, 8303], [8306, 8307], [8314, 8318],
[8330, 8335], [8341, 8449], [8451, 8454], [8456, 8457], [8470, 8472], [8478, 8483],
[8506, 8507], [8512, 8516], [8522, 8525], [8586, 9311], [9372, 9449], [9472, 10101],
[10132, 11263], [11493, 11498], [11503, 11516], [11518, 11519], [11558, 11567],
[11622, 11630], [11632, 11647], [11671, 11679], [11743, 11822], [11824, 12292],
[12296, 12320], [12330, 12336], [12342, 12343], [12349, 12352], [12439, 12444],
[12544, 12548], [12590, 12592], [12687, 12689], [12694, 12703], [12728, 12783],
[12800, 12831], [12842, 12880], [12896, 12927], [12938, 12976], [12992, 13311],
[19894, 19967], [40908, 40959], [42125, 42191], [42238, 42239], [42509, 42511],
[42540, 42559], [42592, 42593], [42607, 42622], [42648, 42655], [42736, 42774],
[42784, 42785], [42889, 42890], [42893, 43002], [43043, 43055], [43062, 43071],
[43124, 43137], [43188, 43215], [43226, 43249], [43256, 43258], [43260, 43263],
[43302, 43311], [43335, 43359], [43389, 43395], [43443, 43470], [43482, 43519],
[43561, 43583], [43596, 43599], [43610, 43615], [43639, 43641], [43643, 43647],
[43698, 43700], [43703, 43704], [43710, 43711], [43715, 43738], [43742, 43967],
[44003, 44015], [44026, 44031], [55204, 55215], [55239, 55242], [55292, 55295],
[57344, 63743], [64046, 64047], [64110, 64111], [64218, 64255], [64263, 64274],
[64280, 64284], [64434, 64466], [64830, 64847], [64912, 64913], [64968, 65007],
[65020, 65135], [65277, 65295], [65306, 65312], [65339, 65344], [65371, 65381],
[65471, 65473], [65480, 65481], [65488, 65489], [65496, 65497]];
for (i = 0; i < ranges.length; i++) {
start = ranges[i][0];
end = ranges[i][1];
for (j = start; j <= end; j++) {
result[j] = true;
}
}
return result;
})();
function splitQuery(query) {
var result = [];
var start = -1;
for (var i = 0; i < query.length; i++) {
if (splitChars[query.charCodeAt(i)]) {
if (start !== -1) {
result.push(query.slice(start, i));
start = -1;
}
} else if (start === -1) {
start = i;
}
}
if (start !== -1) {
result.push(query.slice(start));
}
return result;
}
/**
* Search Module
*/
var Search = {
_index : null,
_queued_query : null,
_pulse_status : -1,
init : function() {
var params = $.getQueryParameters();
if (params.q) {
var query = params.q[0];
$('input[name="q"]')[0].value = query;
this.performSearch(query);
}
},
loadIndex : function(url) {
$.ajax({type: "GET", url: url, data: null,
dataType: "script", cache: true,
complete: function(jqxhr, textstatus) {
if (textstatus != "success") {
document.getElementById("searchindexloader").src = url;
}
}});
},
setIndex : function(index) {
var q;
this._index = index;
if ((q = this._queued_query) !== null) {
this._queued_query = null;
Search.query(q);
}
},
hasIndex : function() {
return this._index !== null;
},
deferQuery : function(query) {
this._queued_query = query;
},
stopPulse : function() {
this._pulse_status = 0;
},
startPulse : function() {
if (this._pulse_status >= 0)
return;
function pulse() {
var i;
Search._pulse_status = (Search._pulse_status + 1) % 4;
var dotString = '';
for (i = 0; i < Search._pulse_status; i++)
dotString += '.';
Search.dots.text(dotString);
if (Search._pulse_status > -1)
window.setTimeout(pulse, 500);
}
pulse();
},
/**
* perform a search for something (or wait until index is loaded)
*/
performSearch : function(query) {
// create the required interface elements
this.out = $('#search-results');
this.title = $('<h2>' + _('Searching') + '</h2>').appendTo(this.out);
this.dots = $('<span></span>').appendTo(this.title);
this.status = $('<p style="display: none"></p>').appendTo(this.out);
this.output = $('<ul class="search"/>').appendTo(this.out);
$('#search-progress').text(_('Preparing search...'));
this.startPulse();
// index already loaded, the browser was quick!
if (this.hasIndex())
this.query(query);
else
this.deferQuery(query);
},
/**
* execute search (requires search index to be loaded)
*/
query : function(query) {
var i;
var stopwords = ["a","and","are","as","at","be","but","by","for","if","in","into","is","it","near","no","not","of","on","or","such","that","the","their","then","there","these","they","this","to","was","will","with"];
// stem the searchterms and add them to the correct list
var stemmer = new Stemmer();
var searchterms = [];
var excluded = [];
var hlterms = [];
var tmp = splitQuery(query);
var objectterms = [];
for (i = 0; i < tmp.length; i++) {
if (tmp[i] !== "") {
objectterms.push(tmp[i].toLowerCase());
}
if ($u.indexOf(stopwords, tmp[i].toLowerCase()) != -1 || tmp[i].match(/^\d+$/) ||
tmp[i] === "") {
// skip this "word"
continue;
}
// stem the word
var word = stemmer.stemWord(tmp[i].toLowerCase());
// prevent stemmer from cutting word smaller than two chars
if(word.length < 3 && tmp[i].length >= 3) {
word = tmp[i];
}
var toAppend;
// select the correct list
if (word[0] == '-') {
toAppend = excluded;
word = word.substr(1);
}
else {
toAppend = searchterms;
hlterms.push(tmp[i].toLowerCase());
}
// only add if not already in the list
if (!$u.contains(toAppend, word))
toAppend.push(word);
}
var highlightstring = '?highlight=' + $.urlencode(hlterms.join(" "));
// console.debug('SEARCH: searching for:');
// console.info('required: ', searchterms);
// console.info('excluded: ', excluded);
// prepare search
var terms = this._index.terms;
var titleterms = this._index.titleterms;
// array of [filename, title, anchor, descr, score]
var results = [];
$('#search-progress').empty();
// lookup as object
for (i = 0; i < objectterms.length; i++) {
var others = [].concat(objectterms.slice(0, i),
objectterms.slice(i+1, objectterms.length));
results = results.concat(this.performObjectSearch(objectterms[i], others));
}
// lookup as search terms in fulltext
results = results.concat(this.performTermsSearch(searchterms, excluded, terms, titleterms));
// let the scorer override scores with a custom scoring function
if (Scorer.score) {
for (i = 0; i < results.length; i++)
results[i][4] = Scorer.score(results[i]);
}
// now sort the results by score (in opposite order of appearance, since the
// display function below uses pop() to retrieve items) and then
// alphabetically
results.sort(function(a, b) {
var left = a[4];
var right = b[4];
if (left > right) {
return 1;
} else if (left < right) {
return -1;
} else {
// same score: sort alphabetically
left = a[1].toLowerCase();
right = b[1].toLowerCase();
return (left > right) ? -1 : ((left < right) ? 1 : 0);
}
});
// for debugging
//Search.lastresults = results.slice(); // a copy
//console.info('search results:', Search.lastresults);
// print the results
var resultCount = results.length;
function displayNextItem() {
// results left, load the summary and display it
if (results.length) {
var item = results.pop();
var listItem = $('<li style="display:none"></li>');
if (DOCUMENTATION_OPTIONS.FILE_SUFFIX === '') {
// dirhtml builder
var dirname = item[0] + '/';
if (dirname.match(/\/index\/$/)) {
dirname = dirname.substring(0, dirname.length-6);
} else if (dirname == 'index/') {
dirname = '';
}
listItem.append($('<a/>').attr('href',
DOCUMENTATION_OPTIONS.URL_ROOT + dirname +
highlightstring + item[2]).html(item[1]));
} else {
// normal html builders
listItem.append($('<a/>').attr('href',
item[0] + DOCUMENTATION_OPTIONS.FILE_SUFFIX +
highlightstring + item[2]).html(item[1]));
}
if (item[3]) {
listItem.append($('<span> (' + item[3] + ')</span>'));
Search.output.append(listItem);
listItem.slideDown(5, function() {
displayNextItem();
});
} else if (DOCUMENTATION_OPTIONS.HAS_SOURCE) {
var suffix = DOCUMENTATION_OPTIONS.SOURCELINK_SUFFIX;
if (suffix === undefined) {
suffix = '.txt';
}
$.ajax({url: DOCUMENTATION_OPTIONS.URL_ROOT + '_sources/' + item[5] + (item[5].slice(-suffix.length) === suffix ? '' : suffix),
dataType: "text",
complete: function(jqxhr, textstatus) {
var data = jqxhr.responseText;
if (data !== '' && data !== undefined) {
listItem.append(Search.makeSearchSummary(data, searchterms, hlterms));
}
Search.output.append(listItem);
listItem.slideDown(5, function() {
displayNextItem();
});
}});
} else {
// no source available, just display title
Search.output.append(listItem);
listItem.slideDown(5, function() {
displayNextItem();
});
}
}
// search finished, update title and status message
else {
Search.stopPulse();
Search.title.text(_('Search Results'));
if (!resultCount)
Search.status.text(_('Your search did not match any documents. Please make sure that all words are spelled correctly and that you\'ve selected enough categories.'));
else
Search.status.text(_('Search finished, found %s page(s) matching the search query.').replace('%s', resultCount));
Search.status.fadeIn(500);
}
}
displayNextItem();
},
/**
* search for object names
*/
performObjectSearch : function(object, otherterms) {
var filenames = this._index.filenames;
var docnames = this._index.docnames;
var objects = this._index.objects;
var objnames = this._index.objnames;
var titles = this._index.titles;
var i;
var results = [];
for (var prefix in objects) {
for (var name in objects[prefix]) {
var fullname = (prefix ? prefix + '.' : '') + name;
if (fullname.toLowerCase().indexOf(object) > -1) {
var score = 0;
var parts = fullname.split('.');
// check for different match types: exact matches of full name or
// "last name" (i.e. last dotted part)
if (fullname == object || parts[parts.length - 1] == object) {
score += Scorer.objNameMatch;
// matches in last name
} else if (parts[parts.length - 1].indexOf(object) > -1) {
score += Scorer.objPartialMatch;
}
var match = objects[prefix][name];
var objname = objnames[match[1]][2];
var title = titles[match[0]];
// If more than one term searched for, we require other words to be
// found in the name/title/description
if (otherterms.length > 0) {
var haystack = (prefix + ' ' + name + ' ' +
objname + ' ' + title).toLowerCase();
var allfound = true;
for (i = 0; i < otherterms.length; i++) {
if (haystack.indexOf(otherterms[i]) == -1) {
allfound = false;
break;
}
}
if (!allfound) {
continue;
}
}
var descr = objname + _(', in ') + title;
var anchor = match[3];
if (anchor === '')
anchor = fullname;
else if (anchor == '-')
anchor = objnames[match[1]][1] + '-' + fullname;
// add custom score for some objects according to scorer
if (Scorer.objPrio.hasOwnProperty(match[2])) {
score += Scorer.objPrio[match[2]];
} else {
score += Scorer.objPrioDefault;
}
results.push([docnames[match[0]], fullname, '#'+anchor, descr, score, filenames[match[0]]]);
}
}
}
return results;
},
/**
* search for full-text terms in the index
*/
performTermsSearch : function(searchterms, excluded, terms, titleterms) {
var docnames = this._index.docnames;
var filenames = this._index.filenames;
var titles = this._index.titles;
var i, j, file;
var fileMap = {};
var scoreMap = {};
var results = [];
// perform the search on the required terms
for (i = 0; i < searchterms.length; i++) {
var word = searchterms[i];
var files = [];
var _o = [
{files: terms[word], score: Scorer.term},
{files: titleterms[word], score: Scorer.title}
];
// no match but word was a required one
if ($u.every(_o, function(o){return o.files === undefined;})) {
break;
}
// found search word in contents
$u.each(_o, function(o) {
var _files = o.files;
if (_files === undefined)
return
if (_files.length === undefined)
_files = [_files];
files = files.concat(_files);
// set score for the word in each file to Scorer.term
for (j = 0; j < _files.length; j++) {
file = _files[j];
if (!(file in scoreMap))
scoreMap[file] = {}
scoreMap[file][word] = o.score;
}
});
// create the mapping
for (j = 0; j < files.length; j++) {
file = files[j];
if (file in fileMap)
fileMap[file].push(word);
else
fileMap[file] = [word];
}
}
// now check if the files don't contain excluded terms
for (file in fileMap) {
var valid = true;
// check if all requirements are matched
if (fileMap[file].length != searchterms.length)
continue;
// ensure that none of the excluded terms is in the search result
for (i = 0; i < excluded.length; i++) {
if (terms[excluded[i]] == file ||
titleterms[excluded[i]] == file ||
$u.contains(terms[excluded[i]] || [], file) ||
$u.contains(titleterms[excluded[i]] || [], file)) {
valid = false;
break;
}
}
// if we have still a valid result we can add it to the result list
if (valid) {
// select one (max) score for the file.
// for better ranking, we should calculate ranking by using words statistics like basic tf-idf...
var score = $u.max($u.map(fileMap[file], function(w){return scoreMap[file][w]}));
results.push([docnames[file], titles[file], '', null, score, filenames[file]]);
}
}
return results;
},
/**
* helper function to return a node containing the
* search summary for a given text. keywords is a list
* of stemmed words, hlwords is the list of normal, unstemmed
* words. the first one is used to find the occurrence, the
* latter for highlighting it.
*/
makeSearchSummary : function(text, keywords, hlwords) {
var textLower = text.toLowerCase();
var start = 0;
$.each(keywords, function() {
var i = textLower.indexOf(this.toLowerCase());
if (i > -1)
start = i;
});
start = Math.max(start - 120, 0);
var excerpt = ((start > 0) ? '...' : '') +
$.trim(text.substr(start, 240)) +
((start + 240 - text.length) ? '...' : '');
var rv = $('<div class="context"></div>').text(excerpt);
$.each(hlwords, function() {
rv = rv.highlightText(this, 'highlighted');
});
return rv;
}
};
$(document).ready(function() {
Search.init();
});PK
%�\�y��p p html/_static/sidebar.jsnu �[��� /*
* sidebar.js
* ~~~~~~~~~~
*
* This script makes the Sphinx sidebar collapsible and implements
* intelligent scrolling.
*
* .sphinxsidebar contains .sphinxsidebarwrapper. This script adds
* in .sphixsidebar, after .sphinxsidebarwrapper, the #sidebarbutton
* used to collapse and expand the sidebar.
*
* When the sidebar is collapsed the .sphinxsidebarwrapper is hidden
* and the width of the sidebar and the margin-left of the document
* are decreased. When the sidebar is expanded the opposite happens.
* This script saves a per-browser/per-session cookie used to
* remember the position of the sidebar among the pages.
* Once the browser is closed the cookie is deleted and the position
* reset to the default (expanded).
*
* :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/
$(function() {
// global elements used by the functions.
// the 'sidebarbutton' element is defined as global after its
// creation, in the add_sidebar_button function
var jwindow = $(window);
var jdocument = $(document);
var bodywrapper = $('.bodywrapper');
var sidebar = $('.sphinxsidebar');
var sidebarwrapper = $('.sphinxsidebarwrapper');
// original margin-left of the bodywrapper and width of the sidebar
// with the sidebar expanded
var bw_margin_expanded = bodywrapper.css('margin-left');
var ssb_width_expanded = sidebar.width();
// margin-left of the bodywrapper and width of the sidebar
// with the sidebar collapsed
var bw_margin_collapsed = '.8em';
var ssb_width_collapsed = '.8em';
// colors used by the current theme
var dark_color = $('.related').css('background-color');
var light_color = $('.document').css('background-color');
function get_viewport_height() {
if (window.innerHeight)
return window.innerHeight;
else
return jwindow.height();
}
function sidebar_is_collapsed() {
return sidebarwrapper.is(':not(:visible)');
}
function toggle_sidebar() {
if (sidebar_is_collapsed())
expand_sidebar();
else
collapse_sidebar();
// adjust the scrolling of the sidebar
scroll_sidebar();
}
function collapse_sidebar() {
sidebarwrapper.hide();
sidebar.css('width', ssb_width_collapsed);
bodywrapper.css('margin-left', bw_margin_collapsed);
sidebarbutton.css({
'margin-left': '0',
'height': bodywrapper.height()
});
sidebarbutton.find('span').text('»');
sidebarbutton.attr('title', _('Expand sidebar'));
document.cookie = 'sidebar=collapsed';
}
function expand_sidebar() {
bodywrapper.css('margin-left', bw_margin_expanded);
sidebar.css('width', ssb_width_expanded);
sidebarwrapper.show();
sidebarbutton.css({
'margin-left': ssb_width_expanded-12,
'height': bodywrapper.height()
});
sidebarbutton.find('span').text('«');
sidebarbutton.attr('title', _('Collapse sidebar'));
document.cookie = 'sidebar=expanded';
}
function add_sidebar_button() {
sidebarwrapper.css({
'float': 'left',
'margin-right': '0',
'width': ssb_width_expanded - 28
});
// create the button
sidebar.append(
'<div id="sidebarbutton"><span>«</span></div>'
);
var sidebarbutton = $('#sidebarbutton');
light_color = sidebarbutton.css('background-color');
// find the height of the viewport to center the '<<' in the page
var viewport_height = get_viewport_height();
sidebarbutton.find('span').css({
'display': 'block',
'margin-top': (viewport_height - sidebar.position().top - 20) / 2
});
sidebarbutton.click(toggle_sidebar);
sidebarbutton.attr('title', _('Collapse sidebar'));
sidebarbutton.css({
'color': '#FFFFFF',
'border-left': '1px solid ' + dark_color,
'font-size': '1.2em',
'cursor': 'pointer',
'height': bodywrapper.height(),
'padding-top': '1px',
'margin-left': ssb_width_expanded - 12
});
sidebarbutton.hover(
function () {
$(this).css('background-color', dark_color);
},
function () {
$(this).css('background-color', light_color);
}
);
}
function set_position_from_cookie() {
if (!document.cookie)
return;
var items = document.cookie.split(';');
for(var k=0; k<items.length; k++) {
var key_val = items[k].split('=');
var key = key_val[0];
if (key == 'sidebar') {
var value = key_val[1];
if ((value == 'collapsed') && (!sidebar_is_collapsed()))
collapse_sidebar();
else if ((value == 'expanded') && (sidebar_is_collapsed()))
expand_sidebar();
}
}
}
add_sidebar_button();
var sidebarbutton = $('#sidebarbutton');
set_position_from_cookie();
/* intelligent scrolling */
function scroll_sidebar() {
var sidebar_height = sidebarwrapper.height();
var viewport_height = get_viewport_height();
var offset = sidebar.position()['top'];
var wintop = jwindow.scrollTop();
var winbot = wintop + viewport_height;
var curtop = sidebarwrapper.position()['top'];
var curbot = curtop + sidebar_height;
// does sidebar fit in window?
if (sidebar_height < viewport_height) {
// yes: easy case -- always keep at the top
sidebarwrapper.css('top', $u.min([$u.max([0, wintop - offset - 10]),
jdocument.height() - sidebar_height - 200]));
}
else {
// no: only scroll if top/bottom edge of sidebar is at
// top/bottom edge of window
if (curtop > wintop && curbot > winbot) {
sidebarwrapper.css('top', $u.max([wintop - offset - 10, 0]));
}
else if (curtop < wintop && curbot < winbot) {
sidebarwrapper.css('top', $u.min([winbot - sidebar_height - offset - 20,
jdocument.height() - sidebar_height - 200]));
}
}
}
jwindow.scroll(scroll_sidebar);
});
PK
%�\F@�ί � html/_static/switchers.jsnu �[��� (function() {
'use strict';
// Parses versions in URL segments like:
// "3", "dev", "release/2.7" or "3.6rc2"
var version_regexs = [
'(?:\\d)',
'(?:\\d\\.\\d[\\w\\d\\.]*)',
'(?:dev)',
'(?:release/\\d.\\d[\\x\\d\\.]*)'];
var all_versions = {
'3.8': 'dev (3.8)',
'3.7': '3.7',
'3.6': '3.6',
'3.5': '3.5',
'2.7': '2.7',
};
var all_languages = {
'en': 'English',
'fr': 'French',
'ja': 'Japanese',
};
function build_version_select(current_version, current_release) {
var buf = ['<select>'];
$.each(all_versions, function(version, title) {
buf.push('<option value="' + version + '"');
if (version == current_version)
buf.push(' selected="selected">' + current_release + '</option>');
else
buf.push('>' + title + '</option>');
});
buf.push('</select>');
return buf.join('');
}
function build_language_select(current_language) {
var buf = ['<select>'];
$.each(all_languages, function(language, title) {
if (language == current_language)
buf.push('<option value="' + language + '" selected="selected">' +
all_languages[current_language] + '</option>');
else
buf.push('<option value="' + language + '">' + title + '</option>');
});
if (!(current_language in all_languages)) {
// In case we're browsing a language that is not yet in all_languages.
buf.push('<option value="' + current_language + '" selected="selected">' +
current_language + '</option>');
all_languages[current_language] = current_language;
}
buf.push('</select>');
return buf.join('');
}
function navigate_to_first_existing(urls) {
// Navigate to the first existing URL in urls.
var url = urls.shift();
if (urls.length == 0) {
window.location.href = url;
return;
}
$.ajax({
url: url,
success: function() {
window.location.href = url;
},
error: function() {
navigate_to_first_existing(urls);
}
});
}
function on_version_switch() {
var selected_version = $(this).children('option:selected').attr('value') + '/';
var url = window.location.href;
var current_language = language_segment_from_url(url);
var current_version = version_segment_in_url(url);
var new_url = url.replace('.org/' + current_language + current_version,
'.org/' + current_language + selected_version);
if (new_url != url) {
navigate_to_first_existing([
new_url,
url.replace('.org/' + current_language + current_version,
'.org/' + selected_version),
'https://docs.python.org/' + current_language + selected_version,
'https://docs.python.org/' + selected_version,
'https://docs.python.org/'
]);
}
}
function on_language_switch() {
var selected_language = $(this).children('option:selected').attr('value') + '/';
var url = window.location.href;
var current_language = language_segment_from_url(url);
var current_version = version_segment_in_url(url);
if (selected_language == 'en/') // Special 'default' case for english.
selected_language = '';
var new_url = url.replace('.org/' + current_language + current_version,
'.org/' + selected_language + current_version);
if (new_url != url) {
navigate_to_first_existing([
new_url,
'https://docs.python.org/'
]);
}
}
// Returns the path segment of the language as a string, like 'fr/'
// or '' if not found.
function language_segment_from_url(url) {
var language_regexp = '\.org/([a-z]{2}(?:-[a-z]{2})?/)';
var match = url.match(language_regexp);
if (match !== null)
return match[1];
return '';
}
// Returns the path segment of the version as a string, like '3.6/'
// or '' if not found.
function version_segment_in_url(url) {
var language_segment = '(?:[a-z]{2}(?:-[a-z]{2})?/)';
var version_segment = '(?:(?:' + version_regexs.join('|') + ')/)';
var version_regexp = '\\.org/' + language_segment + '?(' + version_segment + ')';
var match = url.match(version_regexp);
if (match !== null)
return match[1];
return ''
}
$(document).ready(function() {
var release = DOCUMENTATION_OPTIONS.VERSION;
var language_segment = language_segment_from_url(window.location.href);
var current_language = language_segment.replace(/\/+$/g, '') || 'en';
var version = release.substr(0, 3);
var version_select = build_version_select(version, release);
$('.version_switcher_placeholder').html(version_select);
$('.version_switcher_placeholder select').bind('change', on_version_switch);
var language_select = build_language_select(current_language);
$('.language_switcher_placeholder').html(language_select);
$('.language_switcher_placeholder select').bind('change', on_language_switch);
});
})();
PK
%�\��`� `� html/_static/underscore-1.3.1.jsnu �[��� // Underscore.js 1.3.1
// (c) 2009-2012 Jeremy Ashkenas, DocumentCloud Inc.
// Underscore is freely distributable under the MIT license.
// Portions of Underscore are inspired or borrowed from Prototype,
// Oliver Steele's Functional, and John Resig's Micro-Templating.
// For all details and documentation:
// http://documentcloud.github.com/underscore
(function() {
// Baseline setup
// --------------
// Establish the root object, `window` in the browser, or `global` on the server.
var root = this;
// Save the previous value of the `_` variable.
var previousUnderscore = root._;
// Establish the object that gets returned to break out of a loop iteration.
var breaker = {};
// Save bytes in the minified (but not gzipped) version:
var ArrayProto = Array.prototype, ObjProto = Object.prototype, FuncProto = Function.prototype;
// Create quick reference variables for speed access to core prototypes.
var slice = ArrayProto.slice,
unshift = ArrayProto.unshift,
toString = ObjProto.toString,
hasOwnProperty = ObjProto.hasOwnProperty;
// All **ECMAScript 5** native function implementations that we hope to use
// are declared here.
var
nativeForEach = ArrayProto.forEach,
nativeMap = ArrayProto.map,
nativeReduce = ArrayProto.reduce,
nativeReduceRight = ArrayProto.reduceRight,
nativeFilter = ArrayProto.filter,
nativeEvery = ArrayProto.every,
nativeSome = ArrayProto.some,
nativeIndexOf = ArrayProto.indexOf,
nativeLastIndexOf = ArrayProto.lastIndexOf,
nativeIsArray = Array.isArray,
nativeKeys = Object.keys,
nativeBind = FuncProto.bind;
// Create a safe reference to the Underscore object for use below.
var _ = function(obj) { return new wrapper(obj); };
// Export the Underscore object for **Node.js**, with
// backwards-compatibility for the old `require()` API. If we're in
// the browser, add `_` as a global object via a string identifier,
// for Closure Compiler "advanced" mode.
if (typeof exports !== 'undefined') {
if (typeof module !== 'undefined' && module.exports) {
exports = module.exports = _;
}
exports._ = _;
} else {
root['_'] = _;
}
// Current version.
_.VERSION = '1.3.1';
// Collection Functions
// --------------------
// The cornerstone, an `each` implementation, aka `forEach`.
// Handles objects with the built-in `forEach`, arrays, and raw objects.
// Delegates to **ECMAScript 5**'s native `forEach` if available.
var each = _.each = _.forEach = function(obj, iterator, context) {
if (obj == null) return;
if (nativeForEach && obj.forEach === nativeForEach) {
obj.forEach(iterator, context);
} else if (obj.length === +obj.length) {
for (var i = 0, l = obj.length; i < l; i++) {
if (i in obj && iterator.call(context, obj[i], i, obj) === breaker) return;
}
} else {
for (var key in obj) {
if (_.has(obj, key)) {
if (iterator.call(context, obj[key], key, obj) === breaker) return;
}
}
}
};
// Return the results of applying the iterator to each element.
// Delegates to **ECMAScript 5**'s native `map` if available.
_.map = _.collect = function(obj, iterator, context) {
var results = [];
if (obj == null) return results;
if (nativeMap && obj.map === nativeMap) return obj.map(iterator, context);
each(obj, function(value, index, list) {
results[results.length] = iterator.call(context, value, index, list);
});
if (obj.length === +obj.length) results.length = obj.length;
return results;
};
// **Reduce** builds up a single result from a list of values, aka `inject`,
// or `foldl`. Delegates to **ECMAScript 5**'s native `reduce` if available.
_.reduce = _.foldl = _.inject = function(obj, iterator, memo, context) {
var initial = arguments.length > 2;
if (obj == null) obj = [];
if (nativeReduce && obj.reduce === nativeReduce) {
if (context) iterator = _.bind(iterator, context);
return initial ? obj.reduce(iterator, memo) : obj.reduce(iterator);
}
each(obj, function(value, index, list) {
if (!initial) {
memo = value;
initial = true;
} else {
memo = iterator.call(context, memo, value, index, list);
}
});
if (!initial) throw new TypeError('Reduce of empty array with no initial value');
return memo;
};
// The right-associative version of reduce, also known as `foldr`.
// Delegates to **ECMAScript 5**'s native `reduceRight` if available.
_.reduceRight = _.foldr = function(obj, iterator, memo, context) {
var initial = arguments.length > 2;
if (obj == null) obj = [];
if (nativeReduceRight && obj.reduceRight === nativeReduceRight) {
if (context) iterator = _.bind(iterator, context);
return initial ? obj.reduceRight(iterator, memo) : obj.reduceRight(iterator);
}
var reversed = _.toArray(obj).reverse();
if (context && !initial) iterator = _.bind(iterator, context);
return initial ? _.reduce(reversed, iterator, memo, context) : _.reduce(reversed, iterator);
};
// Return the first value which passes a truth test. Aliased as `detect`.
_.find = _.detect = function(obj, iterator, context) {
var result;
any(obj, function(value, index, list) {
if (iterator.call(context, value, index, list)) {
result = value;
return true;
}
});
return result;
};
// Return all the elements that pass a truth test.
// Delegates to **ECMAScript 5**'s native `filter` if available.
// Aliased as `select`.
_.filter = _.select = function(obj, iterator, context) {
var results = [];
if (obj == null) return results;
if (nativeFilter && obj.filter === nativeFilter) return obj.filter(iterator, context);
each(obj, function(value, index, list) {
if (iterator.call(context, value, index, list)) results[results.length] = value;
});
return results;
};
// Return all the elements for which a truth test fails.
_.reject = function(obj, iterator, context) {
var results = [];
if (obj == null) return results;
each(obj, function(value, index, list) {
if (!iterator.call(context, value, index, list)) results[results.length] = value;
});
return results;
};
// Determine whether all of the elements match a truth test.
// Delegates to **ECMAScript 5**'s native `every` if available.
// Aliased as `all`.
_.every = _.all = function(obj, iterator, context) {
var result = true;
if (obj == null) return result;
if (nativeEvery && obj.every === nativeEvery) return obj.every(iterator, context);
each(obj, function(value, index, list) {
if (!(result = result && iterator.call(context, value, index, list))) return breaker;
});
return result;
};
// Determine if at least one element in the object matches a truth test.
// Delegates to **ECMAScript 5**'s native `some` if available.
// Aliased as `any`.
var any = _.some = _.any = function(obj, iterator, context) {
iterator || (iterator = _.identity);
var result = false;
if (obj == null) return result;
if (nativeSome && obj.some === nativeSome) return obj.some(iterator, context);
each(obj, function(value, index, list) {
if (result || (result = iterator.call(context, value, index, list))) return breaker;
});
return !!result;
};
// Determine if a given value is included in the array or object using `===`.
// Aliased as `contains`.
_.include = _.contains = function(obj, target) {
var found = false;
if (obj == null) return found;
if (nativeIndexOf && obj.indexOf === nativeIndexOf) return obj.indexOf(target) != -1;
found = any(obj, function(value) {
return value === target;
});
return found;
};
// Invoke a method (with arguments) on every item in a collection.
_.invoke = function(obj, method) {
var args = slice.call(arguments, 2);
return _.map(obj, function(value) {
return (_.isFunction(method) ? method || value : value[method]).apply(value, args);
});
};
// Convenience version of a common use case of `map`: fetching a property.
_.pluck = function(obj, key) {
return _.map(obj, function(value){ return value[key]; });
};
// Return the maximum element or (element-based computation).
_.max = function(obj, iterator, context) {
if (!iterator && _.isArray(obj)) return Math.max.apply(Math, obj);
if (!iterator && _.isEmpty(obj)) return -Infinity;
var result = {computed : -Infinity};
each(obj, function(value, index, list) {
var computed = iterator ? iterator.call(context, value, index, list) : value;
computed >= result.computed && (result = {value : value, computed : computed});
});
return result.value;
};
// Return the minimum element (or element-based computation).
_.min = function(obj, iterator, context) {
if (!iterator && _.isArray(obj)) return Math.min.apply(Math, obj);
if (!iterator && _.isEmpty(obj)) return Infinity;
var result = {computed : Infinity};
each(obj, function(value, index, list) {
var computed = iterator ? iterator.call(context, value, index, list) : value;
computed < result.computed && (result = {value : value, computed : computed});
});
return result.value;
};
// Shuffle an array.
_.shuffle = function(obj) {
var shuffled = [], rand;
each(obj, function(value, index, list) {
if (index == 0) {
shuffled[0] = value;
} else {
rand = Math.floor(Math.random() * (index + 1));
shuffled[index] = shuffled[rand];
shuffled[rand] = value;
}
});
return shuffled;
};
// Sort the object's values by a criterion produced by an iterator.
_.sortBy = function(obj, iterator, context) {
return _.pluck(_.map(obj, function(value, index, list) {
return {
value : value,
criteria : iterator.call(context, value, index, list)
};
}).sort(function(left, right) {
var a = left.criteria, b = right.criteria;
return a < b ? -1 : a > b ? 1 : 0;
}), 'value');
};
// Groups the object's values by a criterion. Pass either a string attribute
// to group by, or a function that returns the criterion.
_.groupBy = function(obj, val) {
var result = {};
var iterator = _.isFunction(val) ? val : function(obj) { return obj[val]; };
each(obj, function(value, index) {
var key = iterator(value, index);
(result[key] || (result[key] = [])).push(value);
});
return result;
};
// Use a comparator function to figure out at what index an object should
// be inserted so as to maintain order. Uses binary search.
_.sortedIndex = function(array, obj, iterator) {
iterator || (iterator = _.identity);
var low = 0, high = array.length;
while (low < high) {
var mid = (low + high) >> 1;
iterator(array[mid]) < iterator(obj) ? low = mid + 1 : high = mid;
}
return low;
};
// Safely convert anything iterable into a real, live array.
_.toArray = function(iterable) {
if (!iterable) return [];
if (iterable.toArray) return iterable.toArray();
if (_.isArray(iterable)) return slice.call(iterable);
if (_.isArguments(iterable)) return slice.call(iterable);
return _.values(iterable);
};
// Return the number of elements in an object.
_.size = function(obj) {
return _.toArray(obj).length;
};
// Array Functions
// ---------------
// Get the first element of an array. Passing **n** will return the first N
// values in the array. Aliased as `head`. The **guard** check allows it to work
// with `_.map`.
_.first = _.head = function(array, n, guard) {
return (n != null) && !guard ? slice.call(array, 0, n) : array[0];
};
// Returns everything but the last entry of the array. Especcialy useful on
// the arguments object. Passing **n** will return all the values in
// the array, excluding the last N. The **guard** check allows it to work with
// `_.map`.
_.initial = function(array, n, guard) {
return slice.call(array, 0, array.length - ((n == null) || guard ? 1 : n));
};
// Get the last element of an array. Passing **n** will return the last N
// values in the array. The **guard** check allows it to work with `_.map`.
_.last = function(array, n, guard) {
if ((n != null) && !guard) {
return slice.call(array, Math.max(array.length - n, 0));
} else {
return array[array.length - 1];
}
};
// Returns everything but the first entry of the array. Aliased as `tail`.
// Especially useful on the arguments object. Passing an **index** will return
// the rest of the values in the array from that index onward. The **guard**
// check allows it to work with `_.map`.
_.rest = _.tail = function(array, index, guard) {
return slice.call(array, (index == null) || guard ? 1 : index);
};
// Trim out all falsy values from an array.
_.compact = function(array) {
return _.filter(array, function(value){ return !!value; });
};
// Return a completely flattened version of an array.
_.flatten = function(array, shallow) {
return _.reduce(array, function(memo, value) {
if (_.isArray(value)) return memo.concat(shallow ? value : _.flatten(value));
memo[memo.length] = value;
return memo;
}, []);
};
// Return a version of the array that does not contain the specified value(s).
_.without = function(array) {
return _.difference(array, slice.call(arguments, 1));
};
// Produce a duplicate-free version of the array. If the array has already
// been sorted, you have the option of using a faster algorithm.
// Aliased as `unique`.
_.uniq = _.unique = function(array, isSorted, iterator) {
var initial = iterator ? _.map(array, iterator) : array;
var result = [];
_.reduce(initial, function(memo, el, i) {
if (0 == i || (isSorted === true ? _.last(memo) != el : !_.include(memo, el))) {
memo[memo.length] = el;
result[result.length] = array[i];
}
return memo;
}, []);
return result;
};
// Produce an array that contains the union: each distinct element from all of
// the passed-in arrays.
_.union = function() {
return _.uniq(_.flatten(arguments, true));
};
// Produce an array that contains every item shared between all the
// passed-in arrays. (Aliased as "intersect" for back-compat.)
_.intersection = _.intersect = function(array) {
var rest = slice.call(arguments, 1);
return _.filter(_.uniq(array), function(item) {
return _.every(rest, function(other) {
return _.indexOf(other, item) >= 0;
});
});
};
// Take the difference between one array and a number of other arrays.
// Only the elements present in just the first array will remain.
_.difference = function(array) {
var rest = _.flatten(slice.call(arguments, 1));
return _.filter(array, function(value){ return !_.include(rest, value); });
};
// Zip together multiple lists into a single array -- elements that share
// an index go together.
_.zip = function() {
var args = slice.call(arguments);
var length = _.max(_.pluck(args, 'length'));
var results = new Array(length);
for (var i = 0; i < length; i++) results[i] = _.pluck(args, "" + i);
return results;
};
// If the browser doesn't supply us with indexOf (I'm looking at you, **MSIE**),
// we need this function. Return the position of the first occurrence of an
// item in an array, or -1 if the item is not included in the array.
// Delegates to **ECMAScript 5**'s native `indexOf` if available.
// If the array is large and already in sort order, pass `true`
// for **isSorted** to use binary search.
_.indexOf = function(array, item, isSorted) {
if (array == null) return -1;
var i, l;
if (isSorted) {
i = _.sortedIndex(array, item);
return array[i] === item ? i : -1;
}
if (nativeIndexOf && array.indexOf === nativeIndexOf) return array.indexOf(item);
for (i = 0, l = array.length; i < l; i++) if (i in array && array[i] === item) return i;
return -1;
};
// Delegates to **ECMAScript 5**'s native `lastIndexOf` if available.
_.lastIndexOf = function(array, item) {
if (array == null) return -1;
if (nativeLastIndexOf && array.lastIndexOf === nativeLastIndexOf) return array.lastIndexOf(item);
var i = array.length;
while (i--) if (i in array && array[i] === item) return i;
return -1;
};
// Generate an integer Array containing an arithmetic progression. A port of
// the native Python `range()` function. See
// [the Python documentation](http://docs.python.org/library/functions.html#range).
_.range = function(start, stop, step) {
if (arguments.length <= 1) {
stop = start || 0;
start = 0;
}
step = arguments[2] || 1;
var len = Math.max(Math.ceil((stop - start) / step), 0);
var idx = 0;
var range = new Array(len);
while(idx < len) {
range[idx++] = start;
start += step;
}
return range;
};
// Function (ahem) Functions
// ------------------
// Reusable constructor function for prototype setting.
var ctor = function(){};
// Create a function bound to a given object (assigning `this`, and arguments,
// optionally). Binding with arguments is also known as `curry`.
// Delegates to **ECMAScript 5**'s native `Function.bind` if available.
// We check for `func.bind` first, to fail fast when `func` is undefined.
_.bind = function bind(func, context) {
var bound, args;
if (func.bind === nativeBind && nativeBind) return nativeBind.apply(func, slice.call(arguments, 1));
if (!_.isFunction(func)) throw new TypeError;
args = slice.call(arguments, 2);
return bound = function() {
if (!(this instanceof bound)) return func.apply(context, args.concat(slice.call(arguments)));
ctor.prototype = func.prototype;
var self = new ctor;
var result = func.apply(self, args.concat(slice.call(arguments)));
if (Object(result) === result) return result;
return self;
};
};
// Bind all of an object's methods to that object. Useful for ensuring that
// all callbacks defined on an object belong to it.
_.bindAll = function(obj) {
var funcs = slice.call(arguments, 1);
if (funcs.length == 0) funcs = _.functions(obj);
each(funcs, function(f) { obj[f] = _.bind(obj[f], obj); });
return obj;
};
// Memoize an expensive function by storing its results.
_.memoize = function(func, hasher) {
var memo = {};
hasher || (hasher = _.identity);
return function() {
var key = hasher.apply(this, arguments);
return _.has(memo, key) ? memo[key] : (memo[key] = func.apply(this, arguments));
};
};
// Delays a function for the given number of milliseconds, and then calls
// it with the arguments supplied.
_.delay = function(func, wait) {
var args = slice.call(arguments, 2);
return setTimeout(function(){ return func.apply(func, args); }, wait);
};
// Defers a function, scheduling it to run after the current call stack has
// cleared.
_.defer = function(func) {
return _.delay.apply(_, [func, 1].concat(slice.call(arguments, 1)));
};
// Returns a function, that, when invoked, will only be triggered at most once
// during a given window of time.
_.throttle = function(func, wait) {
var context, args, timeout, throttling, more;
var whenDone = _.debounce(function(){ more = throttling = false; }, wait);
return function() {
context = this; args = arguments;
var later = function() {
timeout = null;
if (more) func.apply(context, args);
whenDone();
};
if (!timeout) timeout = setTimeout(later, wait);
if (throttling) {
more = true;
} else {
func.apply(context, args);
}
whenDone();
throttling = true;
};
};
// Returns a function, that, as long as it continues to be invoked, will not
// be triggered. The function will be called after it stops being called for
// N milliseconds.
_.debounce = function(func, wait) {
var timeout;
return function() {
var context = this, args = arguments;
var later = function() {
timeout = null;
func.apply(context, args);
};
clearTimeout(timeout);
timeout = setTimeout(later, wait);
};
};
// Returns a function that will be executed at most one time, no matter how
// often you call it. Useful for lazy initialization.
_.once = function(func) {
var ran = false, memo;
return function() {
if (ran) return memo;
ran = true;
return memo = func.apply(this, arguments);
};
};
// Returns the first function passed as an argument to the second,
// allowing you to adjust arguments, run code before and after, and
// conditionally execute the original function.
_.wrap = function(func, wrapper) {
return function() {
var args = [func].concat(slice.call(arguments, 0));
return wrapper.apply(this, args);
};
};
// Returns a function that is the composition of a list of functions, each
// consuming the return value of the function that follows.
_.compose = function() {
var funcs = arguments;
return function() {
var args = arguments;
for (var i = funcs.length - 1; i >= 0; i--) {
args = [funcs[i].apply(this, args)];
}
return args[0];
};
};
// Returns a function that will only be executed after being called N times.
_.after = function(times, func) {
if (times <= 0) return func();
return function() {
if (--times < 1) { return func.apply(this, arguments); }
};
};
// Object Functions
// ----------------
// Retrieve the names of an object's properties.
// Delegates to **ECMAScript 5**'s native `Object.keys`
_.keys = nativeKeys || function(obj) {
if (obj !== Object(obj)) throw new TypeError('Invalid object');
var keys = [];
for (var key in obj) if (_.has(obj, key)) keys[keys.length] = key;
return keys;
};
// Retrieve the values of an object's properties.
_.values = function(obj) {
return _.map(obj, _.identity);
};
// Return a sorted list of the function names available on the object.
// Aliased as `methods`
_.functions = _.methods = function(obj) {
var names = [];
for (var key in obj) {
if (_.isFunction(obj[key])) names.push(key);
}
return names.sort();
};
// Extend a given object with all the properties in passed-in object(s).
_.extend = function(obj) {
each(slice.call(arguments, 1), function(source) {
for (var prop in source) {
obj[prop] = source[prop];
}
});
return obj;
};
// Fill in a given object with default properties.
_.defaults = function(obj) {
each(slice.call(arguments, 1), function(source) {
for (var prop in source) {
if (obj[prop] == null) obj[prop] = source[prop];
}
});
return obj;
};
// Create a (shallow-cloned) duplicate of an object.
_.clone = function(obj) {
if (!_.isObject(obj)) return obj;
return _.isArray(obj) ? obj.slice() : _.extend({}, obj);
};
// Invokes interceptor with the obj, and then returns obj.
// The primary purpose of this method is to "tap into" a method chain, in
// order to perform operations on intermediate results within the chain.
_.tap = function(obj, interceptor) {
interceptor(obj);
return obj;
};
// Internal recursive comparison function.
function eq(a, b, stack) {
// Identical objects are equal. `0 === -0`, but they aren't identical.
// See the Harmony `egal` proposal: http://wiki.ecmascript.org/doku.php?id=harmony:egal.
if (a === b) return a !== 0 || 1 / a == 1 / b;
// A strict comparison is necessary because `null == undefined`.
if (a == null || b == null) return a === b;
// Unwrap any wrapped objects.
if (a._chain) a = a._wrapped;
if (b._chain) b = b._wrapped;
// Invoke a custom `isEqual` method if one is provided.
if (a.isEqual && _.isFunction(a.isEqual)) return a.isEqual(b);
if (b.isEqual && _.isFunction(b.isEqual)) return b.isEqual(a);
// Compare `[[Class]]` names.
var className = toString.call(a);
if (className != toString.call(b)) return false;
switch (className) {
// Strings, numbers, dates, and booleans are compared by value.
case '[object String]':
// Primitives and their corresponding object wrappers are equivalent; thus, `"5"` is
// equivalent to `new String("5")`.
return a == String(b);
case '[object Number]':
// `NaN`s are equivalent, but non-reflexive. An `egal` comparison is performed for
// other numeric values.
return a != +a ? b != +b : (a == 0 ? 1 / a == 1 / b : a == +b);
case '[object Date]':
case '[object Boolean]':
// Coerce dates and booleans to numeric primitive values. Dates are compared by their
// millisecond representations. Note that invalid dates with millisecond representations
// of `NaN` are not equivalent.
return +a == +b;
// RegExps are compared by their source patterns and flags.
case '[object RegExp]':
return a.source == b.source &&
a.global == b.global &&
a.multiline == b.multiline &&
a.ignoreCase == b.ignoreCase;
}
if (typeof a != 'object' || typeof b != 'object') return false;
// Assume equality for cyclic structures. The algorithm for detecting cyclic
// structures is adapted from ES 5.1 section 15.12.3, abstract operation `JO`.
var length = stack.length;
while (length--) {
// Linear search. Performance is inversely proportional to the number of
// unique nested structures.
if (stack[length] == a) return true;
}
// Add the first object to the stack of traversed objects.
stack.push(a);
var size = 0, result = true;
// Recursively compare objects and arrays.
if (className == '[object Array]') {
// Compare array lengths to determine if a deep comparison is necessary.
size = a.length;
result = size == b.length;
if (result) {
// Deep compare the contents, ignoring non-numeric properties.
while (size--) {
// Ensure commutative equality for sparse arrays.
if (!(result = size in a == size in b && eq(a[size], b[size], stack))) break;
}
}
} else {
// Objects with different constructors are not equivalent.
if ('constructor' in a != 'constructor' in b || a.constructor != b.constructor) return false;
// Deep compare objects.
for (var key in a) {
if (_.has(a, key)) {
// Count the expected number of properties.
size++;
// Deep compare each member.
if (!(result = _.has(b, key) && eq(a[key], b[key], stack))) break;
}
}
// Ensure that both objects contain the same number of properties.
if (result) {
for (key in b) {
if (_.has(b, key) && !(size--)) break;
}
result = !size;
}
}
// Remove the first object from the stack of traversed objects.
stack.pop();
return result;
}
// Perform a deep comparison to check if two objects are equal.
_.isEqual = function(a, b) {
return eq(a, b, []);
};
// Is a given array, string, or object empty?
// An "empty" object has no enumerable own-properties.
_.isEmpty = function(obj) {
if (_.isArray(obj) || _.isString(obj)) return obj.length === 0;
for (var key in obj) if (_.has(obj, key)) return false;
return true;
};
// Is a given value a DOM element?
_.isElement = function(obj) {
return !!(obj && obj.nodeType == 1);
};
// Is a given value an array?
// Delegates to ECMA5's native Array.isArray
_.isArray = nativeIsArray || function(obj) {
return toString.call(obj) == '[object Array]';
};
// Is a given variable an object?
_.isObject = function(obj) {
return obj === Object(obj);
};
// Is a given variable an arguments object?
_.isArguments = function(obj) {
return toString.call(obj) == '[object Arguments]';
};
if (!_.isArguments(arguments)) {
_.isArguments = function(obj) {
return !!(obj && _.has(obj, 'callee'));
};
}
// Is a given value a function?
_.isFunction = function(obj) {
return toString.call(obj) == '[object Function]';
};
// Is a given value a string?
_.isString = function(obj) {
return toString.call(obj) == '[object String]';
};
// Is a given value a number?
_.isNumber = function(obj) {
return toString.call(obj) == '[object Number]';
};
// Is the given value `NaN`?
_.isNaN = function(obj) {
// `NaN` is the only value for which `===` is not reflexive.
return obj !== obj;
};
// Is a given value a boolean?
_.isBoolean = function(obj) {
return obj === true || obj === false || toString.call(obj) == '[object Boolean]';
};
// Is a given value a date?
_.isDate = function(obj) {
return toString.call(obj) == '[object Date]';
};
// Is the given value a regular expression?
_.isRegExp = function(obj) {
return toString.call(obj) == '[object RegExp]';
};
// Is a given value equal to null?
_.isNull = function(obj) {
return obj === null;
};
// Is a given variable undefined?
_.isUndefined = function(obj) {
return obj === void 0;
};
// Has own property?
_.has = function(obj, key) {
return hasOwnProperty.call(obj, key);
};
// Utility Functions
// -----------------
// Run Underscore.js in *noConflict* mode, returning the `_` variable to its
// previous owner. Returns a reference to the Underscore object.
_.noConflict = function() {
root._ = previousUnderscore;
return this;
};
// Keep the identity function around for default iterators.
_.identity = function(value) {
return value;
};
// Run a function **n** times.
_.times = function (n, iterator, context) {
for (var i = 0; i < n; i++) iterator.call(context, i);
};
// Escape a string for HTML interpolation.
_.escape = function(string) {
return (''+string).replace(/&/g, '&').replace(/</g, '<').replace(/>/g, '>').replace(/"/g, '"').replace(/'/g, ''').replace(/\//g,'/');
};
// Add your own custom functions to the Underscore object, ensuring that
// they're correctly added to the OOP wrapper as well.
_.mixin = function(obj) {
each(_.functions(obj), function(name){
addToWrapper(name, _[name] = obj[name]);
});
};
// Generate a unique integer id (unique within the entire client session).
// Useful for temporary DOM ids.
var idCounter = 0;
_.uniqueId = function(prefix) {
var id = idCounter++;
return prefix ? prefix + id : id;
};
// By default, Underscore uses ERB-style template delimiters, change the
// following template settings to use alternative delimiters.
_.templateSettings = {
evaluate : /<%([\s\S]+?)%>/g,
interpolate : /<%=([\s\S]+?)%>/g,
escape : /<%-([\s\S]+?)%>/g
};
// When customizing `templateSettings`, if you don't want to define an
// interpolation, evaluation or escaping regex, we need one that is
// guaranteed not to match.
var noMatch = /.^/;
// Within an interpolation, evaluation, or escaping, remove HTML escaping
// that had been previously added.
var unescape = function(code) {
return code.replace(/\\\\/g, '\\').replace(/\\'/g, "'");
};
// JavaScript micro-templating, similar to John Resig's implementation.
// Underscore templating handles arbitrary delimiters, preserves whitespace,
// and correctly escapes quotes within interpolated code.
_.template = function(str, data) {
var c = _.templateSettings;
var tmpl = 'var __p=[],print=function(){__p.push.apply(__p,arguments);};' +
'with(obj||{}){__p.push(\'' +
str.replace(/\\/g, '\\\\')
.replace(/'/g, "\\'")
.replace(c.escape || noMatch, function(match, code) {
return "',_.escape(" + unescape(code) + "),'";
})
.replace(c.interpolate || noMatch, function(match, code) {
return "'," + unescape(code) + ",'";
})
.replace(c.evaluate || noMatch, function(match, code) {
return "');" + unescape(code).replace(/[\r\n\t]/g, ' ') + ";__p.push('";
})
.replace(/\r/g, '\\r')
.replace(/\n/g, '\\n')
.replace(/\t/g, '\\t')
+ "');}return __p.join('');";
var func = new Function('obj', '_', tmpl);
if (data) return func(data, _);
return function(data) {
return func.call(this, data, _);
};
};
// Add a "chain" function, which will delegate to the wrapper.
_.chain = function(obj) {
return _(obj).chain();
};
// The OOP Wrapper
// ---------------
// If Underscore is called as a function, it returns a wrapped object that
// can be used OO-style. This wrapper holds altered versions of all the
// underscore functions. Wrapped objects may be chained.
var wrapper = function(obj) { this._wrapped = obj; };
// Expose `wrapper.prototype` as `_.prototype`
_.prototype = wrapper.prototype;
// Helper function to continue chaining intermediate results.
var result = function(obj, chain) {
return chain ? _(obj).chain() : obj;
};
// A method to easily add functions to the OOP wrapper.
var addToWrapper = function(name, func) {
wrapper.prototype[name] = function() {
var args = slice.call(arguments);
unshift.call(args, this._wrapped);
return result(func.apply(_, args), this._chain);
};
};
// Add all of the Underscore functions to the wrapper object.
_.mixin(_);
// Add all mutator Array functions to the wrapper.
each(['pop', 'push', 'reverse', 'shift', 'sort', 'splice', 'unshift'], function(name) {
var method = ArrayProto[name];
wrapper.prototype[name] = function() {
var wrapped = this._wrapped;
method.apply(wrapped, arguments);
var length = wrapped.length;
if ((name == 'shift' || name == 'splice') && length === 0) delete wrapped[0];
return result(wrapped, this._chain);
};
});
// Add all accessor Array functions to the wrapper.
each(['concat', 'join', 'slice'], function(name) {
var method = ArrayProto[name];
wrapper.prototype[name] = function() {
return result(method.apply(this._wrapped, arguments), this._chain);
};
});
// Start chaining a wrapped Underscore object.
wrapper.prototype.chain = function() {
this._chain = true;
return this;
};
// Extracts the result from a wrapped and chained object.
wrapper.prototype.value = function() {
return this._wrapped;
};
}).call(this);
PK
%�\��;�l/ l/ html/_static/underscore.jsnu �[��� // Underscore.js 1.3.1
// (c) 2009-2012 Jeremy Ashkenas, DocumentCloud Inc.
// Underscore is freely distributable under the MIT license.
// Portions of Underscore are inspired or borrowed from Prototype,
// Oliver Steele's Functional, and John Resig's Micro-Templating.
// For all details and documentation:
// http://documentcloud.github.com/underscore
(function(){function q(a,c,d){if(a===c)return a!==0||1/a==1/c;if(a==null||c==null)return a===c;if(a._chain)a=a._wrapped;if(c._chain)c=c._wrapped;if(a.isEqual&&b.isFunction(a.isEqual))return a.isEqual(c);if(c.isEqual&&b.isFunction(c.isEqual))return c.isEqual(a);var e=l.call(a);if(e!=l.call(c))return false;switch(e){case "[object String]":return a==String(c);case "[object Number]":return a!=+a?c!=+c:a==0?1/a==1/c:a==+c;case "[object Date]":case "[object Boolean]":return+a==+c;case "[object RegExp]":return a.source==
c.source&&a.global==c.global&&a.multiline==c.multiline&&a.ignoreCase==c.ignoreCase}if(typeof a!="object"||typeof c!="object")return false;for(var f=d.length;f--;)if(d[f]==a)return true;d.push(a);var f=0,g=true;if(e=="[object Array]"){if(f=a.length,g=f==c.length)for(;f--;)if(!(g=f in a==f in c&&q(a[f],c[f],d)))break}else{if("constructor"in a!="constructor"in c||a.constructor!=c.constructor)return false;for(var h in a)if(b.has(a,h)&&(f++,!(g=b.has(c,h)&&q(a[h],c[h],d))))break;if(g){for(h in c)if(b.has(c,
h)&&!f--)break;g=!f}}d.pop();return g}var r=this,G=r._,n={},k=Array.prototype,o=Object.prototype,i=k.slice,H=k.unshift,l=o.toString,I=o.hasOwnProperty,w=k.forEach,x=k.map,y=k.reduce,z=k.reduceRight,A=k.filter,B=k.every,C=k.some,p=k.indexOf,D=k.lastIndexOf,o=Array.isArray,J=Object.keys,s=Function.prototype.bind,b=function(a){return new m(a)};if(typeof exports!=="undefined"){if(typeof module!=="undefined"&&module.exports)exports=module.exports=b;exports._=b}else r._=b;b.VERSION="1.3.1";var j=b.each=
b.forEach=function(a,c,d){if(a!=null)if(w&&a.forEach===w)a.forEach(c,d);else if(a.length===+a.length)for(var e=0,f=a.length;e<f;e++){if(e in a&&c.call(d,a[e],e,a)===n)break}else for(e in a)if(b.has(a,e)&&c.call(d,a[e],e,a)===n)break};b.map=b.collect=function(a,c,b){var e=[];if(a==null)return e;if(x&&a.map===x)return a.map(c,b);j(a,function(a,g,h){e[e.length]=c.call(b,a,g,h)});if(a.length===+a.length)e.length=a.length;return e};b.reduce=b.foldl=b.inject=function(a,c,d,e){var f=arguments.length>2;a==
null&&(a=[]);if(y&&a.reduce===y)return e&&(c=b.bind(c,e)),f?a.reduce(c,d):a.reduce(c);j(a,function(a,b,i){f?d=c.call(e,d,a,b,i):(d=a,f=true)});if(!f)throw new TypeError("Reduce of empty array with no initial value");return d};b.reduceRight=b.foldr=function(a,c,d,e){var f=arguments.length>2;a==null&&(a=[]);if(z&&a.reduceRight===z)return e&&(c=b.bind(c,e)),f?a.reduceRight(c,d):a.reduceRight(c);var g=b.toArray(a).reverse();e&&!f&&(c=b.bind(c,e));return f?b.reduce(g,c,d,e):b.reduce(g,c)};b.find=b.detect=
function(a,c,b){var e;E(a,function(a,g,h){if(c.call(b,a,g,h))return e=a,true});return e};b.filter=b.select=function(a,c,b){var e=[];if(a==null)return e;if(A&&a.filter===A)return a.filter(c,b);j(a,function(a,g,h){c.call(b,a,g,h)&&(e[e.length]=a)});return e};b.reject=function(a,c,b){var e=[];if(a==null)return e;j(a,function(a,g,h){c.call(b,a,g,h)||(e[e.length]=a)});return e};b.every=b.all=function(a,c,b){var e=true;if(a==null)return e;if(B&&a.every===B)return a.every(c,b);j(a,function(a,g,h){if(!(e=
e&&c.call(b,a,g,h)))return n});return e};var E=b.some=b.any=function(a,c,d){c||(c=b.identity);var e=false;if(a==null)return e;if(C&&a.some===C)return a.some(c,d);j(a,function(a,b,h){if(e||(e=c.call(d,a,b,h)))return n});return!!e};b.include=b.contains=function(a,c){var b=false;if(a==null)return b;return p&&a.indexOf===p?a.indexOf(c)!=-1:b=E(a,function(a){return a===c})};b.invoke=function(a,c){var d=i.call(arguments,2);return b.map(a,function(a){return(b.isFunction(c)?c||a:a[c]).apply(a,d)})};b.pluck=
function(a,c){return b.map(a,function(a){return a[c]})};b.max=function(a,c,d){if(!c&&b.isArray(a))return Math.max.apply(Math,a);if(!c&&b.isEmpty(a))return-Infinity;var e={computed:-Infinity};j(a,function(a,b,h){b=c?c.call(d,a,b,h):a;b>=e.computed&&(e={value:a,computed:b})});return e.value};b.min=function(a,c,d){if(!c&&b.isArray(a))return Math.min.apply(Math,a);if(!c&&b.isEmpty(a))return Infinity;var e={computed:Infinity};j(a,function(a,b,h){b=c?c.call(d,a,b,h):a;b<e.computed&&(e={value:a,computed:b})});
return e.value};b.shuffle=function(a){var b=[],d;j(a,function(a,f){f==0?b[0]=a:(d=Math.floor(Math.random()*(f+1)),b[f]=b[d],b[d]=a)});return b};b.sortBy=function(a,c,d){return b.pluck(b.map(a,function(a,b,g){return{value:a,criteria:c.call(d,a,b,g)}}).sort(function(a,b){var c=a.criteria,d=b.criteria;return c<d?-1:c>d?1:0}),"value")};b.groupBy=function(a,c){var d={},e=b.isFunction(c)?c:function(a){return a[c]};j(a,function(a,b){var c=e(a,b);(d[c]||(d[c]=[])).push(a)});return d};b.sortedIndex=function(a,
c,d){d||(d=b.identity);for(var e=0,f=a.length;e<f;){var g=e+f>>1;d(a[g])<d(c)?e=g+1:f=g}return e};b.toArray=function(a){return!a?[]:a.toArray?a.toArray():b.isArray(a)?i.call(a):b.isArguments(a)?i.call(a):b.values(a)};b.size=function(a){return b.toArray(a).length};b.first=b.head=function(a,b,d){return b!=null&&!d?i.call(a,0,b):a[0]};b.initial=function(a,b,d){return i.call(a,0,a.length-(b==null||d?1:b))};b.last=function(a,b,d){return b!=null&&!d?i.call(a,Math.max(a.length-b,0)):a[a.length-1]};b.rest=
b.tail=function(a,b,d){return i.call(a,b==null||d?1:b)};b.compact=function(a){return b.filter(a,function(a){return!!a})};b.flatten=function(a,c){return b.reduce(a,function(a,e){if(b.isArray(e))return a.concat(c?e:b.flatten(e));a[a.length]=e;return a},[])};b.without=function(a){return b.difference(a,i.call(arguments,1))};b.uniq=b.unique=function(a,c,d){var d=d?b.map(a,d):a,e=[];b.reduce(d,function(d,g,h){if(0==h||(c===true?b.last(d)!=g:!b.include(d,g)))d[d.length]=g,e[e.length]=a[h];return d},[]);
return e};b.union=function(){return b.uniq(b.flatten(arguments,true))};b.intersection=b.intersect=function(a){var c=i.call(arguments,1);return b.filter(b.uniq(a),function(a){return b.every(c,function(c){return b.indexOf(c,a)>=0})})};b.difference=function(a){var c=b.flatten(i.call(arguments,1));return b.filter(a,function(a){return!b.include(c,a)})};b.zip=function(){for(var a=i.call(arguments),c=b.max(b.pluck(a,"length")),d=Array(c),e=0;e<c;e++)d[e]=b.pluck(a,""+e);return d};b.indexOf=function(a,c,
d){if(a==null)return-1;var e;if(d)return d=b.sortedIndex(a,c),a[d]===c?d:-1;if(p&&a.indexOf===p)return a.indexOf(c);for(d=0,e=a.length;d<e;d++)if(d in a&&a[d]===c)return d;return-1};b.lastIndexOf=function(a,b){if(a==null)return-1;if(D&&a.lastIndexOf===D)return a.lastIndexOf(b);for(var d=a.length;d--;)if(d in a&&a[d]===b)return d;return-1};b.range=function(a,b,d){arguments.length<=1&&(b=a||0,a=0);for(var d=arguments[2]||1,e=Math.max(Math.ceil((b-a)/d),0),f=0,g=Array(e);f<e;)g[f++]=a,a+=d;return g};
var F=function(){};b.bind=function(a,c){var d,e;if(a.bind===s&&s)return s.apply(a,i.call(arguments,1));if(!b.isFunction(a))throw new TypeError;e=i.call(arguments,2);return d=function(){if(!(this instanceof d))return a.apply(c,e.concat(i.call(arguments)));F.prototype=a.prototype;var b=new F,g=a.apply(b,e.concat(i.call(arguments)));return Object(g)===g?g:b}};b.bindAll=function(a){var c=i.call(arguments,1);c.length==0&&(c=b.functions(a));j(c,function(c){a[c]=b.bind(a[c],a)});return a};b.memoize=function(a,
c){var d={};c||(c=b.identity);return function(){var e=c.apply(this,arguments);return b.has(d,e)?d[e]:d[e]=a.apply(this,arguments)}};b.delay=function(a,b){var d=i.call(arguments,2);return setTimeout(function(){return a.apply(a,d)},b)};b.defer=function(a){return b.delay.apply(b,[a,1].concat(i.call(arguments,1)))};b.throttle=function(a,c){var d,e,f,g,h,i=b.debounce(function(){h=g=false},c);return function(){d=this;e=arguments;var b;f||(f=setTimeout(function(){f=null;h&&a.apply(d,e);i()},c));g?h=true:
a.apply(d,e);i();g=true}};b.debounce=function(a,b){var d;return function(){var e=this,f=arguments;clearTimeout(d);d=setTimeout(function(){d=null;a.apply(e,f)},b)}};b.once=function(a){var b=false,d;return function(){if(b)return d;b=true;return d=a.apply(this,arguments)}};b.wrap=function(a,b){return function(){var d=[a].concat(i.call(arguments,0));return b.apply(this,d)}};b.compose=function(){var a=arguments;return function(){for(var b=arguments,d=a.length-1;d>=0;d--)b=[a[d].apply(this,b)];return b[0]}};
b.after=function(a,b){return a<=0?b():function(){if(--a<1)return b.apply(this,arguments)}};b.keys=J||function(a){if(a!==Object(a))throw new TypeError("Invalid object");var c=[],d;for(d in a)b.has(a,d)&&(c[c.length]=d);return c};b.values=function(a){return b.map(a,b.identity)};b.functions=b.methods=function(a){var c=[],d;for(d in a)b.isFunction(a[d])&&c.push(d);return c.sort()};b.extend=function(a){j(i.call(arguments,1),function(b){for(var d in b)a[d]=b[d]});return a};b.defaults=function(a){j(i.call(arguments,
1),function(b){for(var d in b)a[d]==null&&(a[d]=b[d])});return a};b.clone=function(a){return!b.isObject(a)?a:b.isArray(a)?a.slice():b.extend({},a)};b.tap=function(a,b){b(a);return a};b.isEqual=function(a,b){return q(a,b,[])};b.isEmpty=function(a){if(b.isArray(a)||b.isString(a))return a.length===0;for(var c in a)if(b.has(a,c))return false;return true};b.isElement=function(a){return!!(a&&a.nodeType==1)};b.isArray=o||function(a){return l.call(a)=="[object Array]"};b.isObject=function(a){return a===Object(a)};
b.isArguments=function(a){return l.call(a)=="[object Arguments]"};if(!b.isArguments(arguments))b.isArguments=function(a){return!(!a||!b.has(a,"callee"))};b.isFunction=function(a){return l.call(a)=="[object Function]"};b.isString=function(a){return l.call(a)=="[object String]"};b.isNumber=function(a){return l.call(a)=="[object Number]"};b.isNaN=function(a){return a!==a};b.isBoolean=function(a){return a===true||a===false||l.call(a)=="[object Boolean]"};b.isDate=function(a){return l.call(a)=="[object Date]"};
b.isRegExp=function(a){return l.call(a)=="[object RegExp]"};b.isNull=function(a){return a===null};b.isUndefined=function(a){return a===void 0};b.has=function(a,b){return I.call(a,b)};b.noConflict=function(){r._=G;return this};b.identity=function(a){return a};b.times=function(a,b,d){for(var e=0;e<a;e++)b.call(d,e)};b.escape=function(a){return(""+a).replace(/&/g,"&").replace(/</g,"<").replace(/>/g,">").replace(/"/g,""").replace(/'/g,"'").replace(/\//g,"/")};b.mixin=function(a){j(b.functions(a),
function(c){K(c,b[c]=a[c])})};var L=0;b.uniqueId=function(a){var b=L++;return a?a+b:b};b.templateSettings={evaluate:/<%([\s\S]+?)%>/g,interpolate:/<%=([\s\S]+?)%>/g,escape:/<%-([\s\S]+?)%>/g};var t=/.^/,u=function(a){return a.replace(/\\\\/g,"\\").replace(/\\'/g,"'")};b.template=function(a,c){var d=b.templateSettings,d="var __p=[],print=function(){__p.push.apply(__p,arguments);};with(obj||{}){__p.push('"+a.replace(/\\/g,"\\\\").replace(/'/g,"\\'").replace(d.escape||t,function(a,b){return"',_.escape("+
u(b)+"),'"}).replace(d.interpolate||t,function(a,b){return"',"+u(b)+",'"}).replace(d.evaluate||t,function(a,b){return"');"+u(b).replace(/[\r\n\t]/g," ")+";__p.push('"}).replace(/\r/g,"\\r").replace(/\n/g,"\\n").replace(/\t/g,"\\t")+"');}return __p.join('');",e=new Function("obj","_",d);return c?e(c,b):function(a){return e.call(this,a,b)}};b.chain=function(a){return b(a).chain()};var m=function(a){this._wrapped=a};b.prototype=m.prototype;var v=function(a,c){return c?b(a).chain():a},K=function(a,c){m.prototype[a]=
function(){var a=i.call(arguments);H.call(a,this._wrapped);return v(c.apply(b,a),this._chain)}};b.mixin(b);j("pop,push,reverse,shift,sort,splice,unshift".split(","),function(a){var b=k[a];m.prototype[a]=function(){var d=this._wrapped;b.apply(d,arguments);var e=d.length;(a=="shift"||a=="splice")&&e===0&&delete d[0];return v(d,this._chain)}});j(["concat","join","slice"],function(a){var b=k[a];m.prototype[a]=function(){return v(b.apply(this._wrapped,arguments),this._chain)}});m.prototype.chain=function(){this._chain=
true;return this};m.prototype.value=function(){return this._wrapped}}).call(this);
PK
%�\���H� � html/_static/up-pressed.pngnu �[��� �PNG
IHDR �a �IDATxc� �o+ Sb�)Sb�G&W�
��+H�,��� Cق��
n;�"VsT�?��.#&ھ�jF�c�g��b�
.�.�NG`49l��*�
Ŀ�� 'q<�� *��]�J��c���y�j�����ؖ��f � b0S�ԙ�µ���| IEND�B`�PK
%�\>u�� � html/_static/up.pngnu �[��� �PNG
IHDR ��7� �IDATx�����@��e�z $���&� �8�:�& :Kpw�n}���O����� <��:!!��{�G@�Dz?�"̧��� �S��{g�<�ݢ� lMQw�y�|�?�
0 pq8q`� � �p�L-'��SBNA��wT���ń�|U V IEND�B`�PK
%�\Fo,� c c html/_static/websupport.jsnu �[��� /*
* websupport.js
* ~~~~~~~~~~~~~
*
* sphinx.websupport utilities for all documentation.
*
* :copyright: Copyright 2007-2018 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/
(function($) {
$.fn.autogrow = function() {
return this.each(function() {
var textarea = this;
$.fn.autogrow.resize(textarea);
$(textarea)
.focus(function() {
textarea.interval = setInterval(function() {
$.fn.autogrow.resize(textarea);
}, 500);
})
.blur(function() {
clearInterval(textarea.interval);
});
});
};
$.fn.autogrow.resize = function(textarea) {
var lineHeight = parseInt($(textarea).css('line-height'), 10);
var lines = textarea.value.split('\n');
var columns = textarea.cols;
var lineCount = 0;
$.each(lines, function() {
lineCount += Math.ceil(this.length / columns) || 1;
});
var height = lineHeight * (lineCount + 1);
$(textarea).css('height', height);
};
})(jQuery);
(function($) {
var comp, by;
function init() {
initEvents();
initComparator();
}
function initEvents() {
$(document).on("click", 'a.comment-close', function(event) {
event.preventDefault();
hide($(this).attr('id').substring(2));
});
$(document).on("click", 'a.vote', function(event) {
event.preventDefault();
handleVote($(this));
});
$(document).on("click", 'a.reply', function(event) {
event.preventDefault();
openReply($(this).attr('id').substring(2));
});
$(document).on("click", 'a.close-reply', function(event) {
event.preventDefault();
closeReply($(this).attr('id').substring(2));
});
$(document).on("click", 'a.sort-option', function(event) {
event.preventDefault();
handleReSort($(this));
});
$(document).on("click", 'a.show-proposal', function(event) {
event.preventDefault();
showProposal($(this).attr('id').substring(2));
});
$(document).on("click", 'a.hide-proposal', function(event) {
event.preventDefault();
hideProposal($(this).attr('id').substring(2));
});
$(document).on("click", 'a.show-propose-change', function(event) {
event.preventDefault();
showProposeChange($(this).attr('id').substring(2));
});
$(document).on("click", 'a.hide-propose-change', function(event) {
event.preventDefault();
hideProposeChange($(this).attr('id').substring(2));
});
$(document).on("click", 'a.accept-comment', function(event) {
event.preventDefault();
acceptComment($(this).attr('id').substring(2));
});
$(document).on("click", 'a.delete-comment', function(event) {
event.preventDefault();
deleteComment($(this).attr('id').substring(2));
});
$(document).on("click", 'a.comment-markup', function(event) {
event.preventDefault();
toggleCommentMarkupBox($(this).attr('id').substring(2));
});
}
/**
* Set comp, which is a comparator function used for sorting and
* inserting comments into the list.
*/
function setComparator() {
// If the first three letters are "asc", sort in ascending order
// and remove the prefix.
if (by.substring(0,3) == 'asc') {
var i = by.substring(3);
comp = function(a, b) { return a[i] - b[i]; };
} else {
// Otherwise sort in descending order.
comp = function(a, b) { return b[by] - a[by]; };
}
// Reset link styles and format the selected sort option.
$('a.sel').attr('href', '#').removeClass('sel');
$('a.by' + by).removeAttr('href').addClass('sel');
}
/**
* Create a comp function. If the user has preferences stored in
* the sortBy cookie, use those, otherwise use the default.
*/
function initComparator() {
by = 'rating'; // Default to sort by rating.
// If the sortBy cookie is set, use that instead.
if (document.cookie.length > 0) {
var start = document.cookie.indexOf('sortBy=');
if (start != -1) {
start = start + 7;
var end = document.cookie.indexOf(";", start);
if (end == -1) {
end = document.cookie.length;
by = unescape(document.cookie.substring(start, end));
}
}
}
setComparator();
}
/**
* Show a comment div.
*/
function show(id) {
$('#ao' + id).hide();
$('#ah' + id).show();
var context = $.extend({id: id}, opts);
var popup = $(renderTemplate(popupTemplate, context)).hide();
popup.find('textarea[name="proposal"]').hide();
popup.find('a.by' + by).addClass('sel');
var form = popup.find('#cf' + id);
form.submit(function(event) {
event.preventDefault();
addComment(form);
});
$('#s' + id).after(popup);
popup.slideDown('fast', function() {
getComments(id);
});
}
/**
* Hide a comment div.
*/
function hide(id) {
$('#ah' + id).hide();
$('#ao' + id).show();
var div = $('#sc' + id);
div.slideUp('fast', function() {
div.remove();
});
}
/**
* Perform an ajax request to get comments for a node
* and insert the comments into the comments tree.
*/
function getComments(id) {
$.ajax({
type: 'GET',
url: opts.getCommentsURL,
data: {node: id},
success: function(data, textStatus, request) {
var ul = $('#cl' + id);
var speed = 100;
$('#cf' + id)
.find('textarea[name="proposal"]')
.data('source', data.source);
if (data.comments.length === 0) {
ul.html('<li>No comments yet.</li>');
ul.data('empty', true);
} else {
// If there are comments, sort them and put them in the list.
var comments = sortComments(data.comments);
speed = data.comments.length * 100;
appendComments(comments, ul);
ul.data('empty', false);
}
$('#cn' + id).slideUp(speed + 200);
ul.slideDown(speed);
},
error: function(request, textStatus, error) {
showError('Oops, there was a problem retrieving the comments.');
},
dataType: 'json'
});
}
/**
* Add a comment via ajax and insert the comment into the comment tree.
*/
function addComment(form) {
var node_id = form.find('input[name="node"]').val();
var parent_id = form.find('input[name="parent"]').val();
var text = form.find('textarea[name="comment"]').val();
var proposal = form.find('textarea[name="proposal"]').val();
if (text == '') {
showError('Please enter a comment.');
return;
}
// Disable the form that is being submitted.
form.find('textarea,input').attr('disabled', 'disabled');
// Send the comment to the server.
$.ajax({
type: "POST",
url: opts.addCommentURL,
dataType: 'json',
data: {
node: node_id,
parent: parent_id,
text: text,
proposal: proposal
},
success: function(data, textStatus, error) {
// Reset the form.
if (node_id) {
hideProposeChange(node_id);
}
form.find('textarea')
.val('')
.add(form.find('input'))
.removeAttr('disabled');
var ul = $('#cl' + (node_id || parent_id));
if (ul.data('empty')) {
$(ul).empty();
ul.data('empty', false);
}
insertComment(data.comment);
var ao = $('#ao' + node_id);
ao.find('img').attr({'src': opts.commentBrightImage});
if (node_id) {
// if this was a "root" comment, remove the commenting box
// (the user can get it back by reopening the comment popup)
$('#ca' + node_id).slideUp();
}
},
error: function(request, textStatus, error) {
form.find('textarea,input').removeAttr('disabled');
showError('Oops, there was a problem adding the comment.');
}
});
}
/**
* Recursively append comments to the main comment list and children
* lists, creating the comment tree.
*/
function appendComments(comments, ul) {
$.each(comments, function() {
var div = createCommentDiv(this);
ul.append($(document.createElement('li')).html(div));
appendComments(this.children, div.find('ul.comment-children'));
// To avoid stagnating data, don't store the comments children in data.
this.children = null;
div.data('comment', this);
});
}
/**
* After adding a new comment, it must be inserted in the correct
* location in the comment tree.
*/
function insertComment(comment) {
var div = createCommentDiv(comment);
// To avoid stagnating data, don't store the comments children in data.
comment.children = null;
div.data('comment', comment);
var ul = $('#cl' + (comment.node || comment.parent));
var siblings = getChildren(ul);
var li = $(document.createElement('li'));
li.hide();
// Determine where in the parents children list to insert this comment.
for(var i=0; i < siblings.length; i++) {
if (comp(comment, siblings[i]) <= 0) {
$('#cd' + siblings[i].id)
.parent()
.before(li.html(div));
li.slideDown('fast');
return;
}
}
// If we get here, this comment rates lower than all the others,
// or it is the only comment in the list.
ul.append(li.html(div));
li.slideDown('fast');
}
function acceptComment(id) {
$.ajax({
type: 'POST',
url: opts.acceptCommentURL,
data: {id: id},
success: function(data, textStatus, request) {
$('#cm' + id).fadeOut('fast');
$('#cd' + id).removeClass('moderate');
},
error: function(request, textStatus, error) {
showError('Oops, there was a problem accepting the comment.');
}
});
}
function deleteComment(id) {
$.ajax({
type: 'POST',
url: opts.deleteCommentURL,
data: {id: id},
success: function(data, textStatus, request) {
var div = $('#cd' + id);
if (data == 'delete') {
// Moderator mode: remove the comment and all children immediately
div.slideUp('fast', function() {
div.remove();
});
return;
}
// User mode: only mark the comment as deleted
div
.find('span.user-id:first')
.text('[deleted]').end()
.find('div.comment-text:first')
.text('[deleted]').end()
.find('#cm' + id + ', #dc' + id + ', #ac' + id + ', #rc' + id +
', #sp' + id + ', #hp' + id + ', #cr' + id + ', #rl' + id)
.remove();
var comment = div.data('comment');
comment.username = '[deleted]';
comment.text = '[deleted]';
div.data('comment', comment);
},
error: function(request, textStatus, error) {
showError('Oops, there was a problem deleting the comment.');
}
});
}
function showProposal(id) {
$('#sp' + id).hide();
$('#hp' + id).show();
$('#pr' + id).slideDown('fast');
}
function hideProposal(id) {
$('#hp' + id).hide();
$('#sp' + id).show();
$('#pr' + id).slideUp('fast');
}
function showProposeChange(id) {
$('#pc' + id).hide();
$('#hc' + id).show();
var textarea = $('#pt' + id);
textarea.val(textarea.data('source'));
$.fn.autogrow.resize(textarea[0]);
textarea.slideDown('fast');
}
function hideProposeChange(id) {
$('#hc' + id).hide();
$('#pc' + id).show();
var textarea = $('#pt' + id);
textarea.val('').removeAttr('disabled');
textarea.slideUp('fast');
}
function toggleCommentMarkupBox(id) {
$('#mb' + id).toggle();
}
/** Handle when the user clicks on a sort by link. */
function handleReSort(link) {
var classes = link.attr('class').split(/\s+/);
for (var i=0; i<classes.length; i++) {
if (classes[i] != 'sort-option') {
by = classes[i].substring(2);
}
}
setComparator();
// Save/update the sortBy cookie.
var expiration = new Date();
expiration.setDate(expiration.getDate() + 365);
document.cookie= 'sortBy=' + escape(by) +
';expires=' + expiration.toUTCString();
$('ul.comment-ul').each(function(index, ul) {
var comments = getChildren($(ul), true);
comments = sortComments(comments);
appendComments(comments, $(ul).empty());
});
}
/**
* Function to process a vote when a user clicks an arrow.
*/
function handleVote(link) {
if (!opts.voting) {
showError("You'll need to login to vote.");
return;
}
var id = link.attr('id');
if (!id) {
// Didn't click on one of the voting arrows.
return;
}
// If it is an unvote, the new vote value is 0,
// Otherwise it's 1 for an upvote, or -1 for a downvote.
var value = 0;
if (id.charAt(1) != 'u') {
value = id.charAt(0) == 'u' ? 1 : -1;
}
// The data to be sent to the server.
var d = {
comment_id: id.substring(2),
value: value
};
// Swap the vote and unvote links.
link.hide();
$('#' + id.charAt(0) + (id.charAt(1) == 'u' ? 'v' : 'u') + d.comment_id)
.show();
// The div the comment is displayed in.
var div = $('div#cd' + d.comment_id);
var data = div.data('comment');
// If this is not an unvote, and the other vote arrow has
// already been pressed, unpress it.
if ((d.value !== 0) && (data.vote === d.value * -1)) {
$('#' + (d.value == 1 ? 'd' : 'u') + 'u' + d.comment_id).hide();
$('#' + (d.value == 1 ? 'd' : 'u') + 'v' + d.comment_id).show();
}
// Update the comments rating in the local data.
data.rating += (data.vote === 0) ? d.value : (d.value - data.vote);
data.vote = d.value;
div.data('comment', data);
// Change the rating text.
div.find('.rating:first')
.text(data.rating + ' point' + (data.rating == 1 ? '' : 's'));
// Send the vote information to the server.
$.ajax({
type: "POST",
url: opts.processVoteURL,
data: d,
error: function(request, textStatus, error) {
showError('Oops, there was a problem casting that vote.');
}
});
}
/**
* Open a reply form used to reply to an existing comment.
*/
function openReply(id) {
// Swap out the reply link for the hide link
$('#rl' + id).hide();
$('#cr' + id).show();
// Add the reply li to the children ul.
var div = $(renderTemplate(replyTemplate, {id: id})).hide();
$('#cl' + id)
.prepend(div)
// Setup the submit handler for the reply form.
.find('#rf' + id)
.submit(function(event) {
event.preventDefault();
addComment($('#rf' + id));
closeReply(id);
})
.find('input[type=button]')
.click(function() {
closeReply(id);
});
div.slideDown('fast', function() {
$('#rf' + id).find('textarea').focus();
});
}
/**
* Close the reply form opened with openReply.
*/
function closeReply(id) {
// Remove the reply div from the DOM.
$('#rd' + id).slideUp('fast', function() {
$(this).remove();
});
// Swap out the hide link for the reply link
$('#cr' + id).hide();
$('#rl' + id).show();
}
/**
* Recursively sort a tree of comments using the comp comparator.
*/
function sortComments(comments) {
comments.sort(comp);
$.each(comments, function() {
this.children = sortComments(this.children);
});
return comments;
}
/**
* Get the children comments from a ul. If recursive is true,
* recursively include childrens' children.
*/
function getChildren(ul, recursive) {
var children = [];
ul.children().children("[id^='cd']")
.each(function() {
var comment = $(this).data('comment');
if (recursive)
comment.children = getChildren($(this).find('#cl' + comment.id), true);
children.push(comment);
});
return children;
}
/** Create a div to display a comment in. */
function createCommentDiv(comment) {
if (!comment.displayed && !opts.moderator) {
return $('<div class="moderate">Thank you! Your comment will show up '
+ 'once it is has been approved by a moderator.</div>');
}
// Prettify the comment rating.
comment.pretty_rating = comment.rating + ' point' +
(comment.rating == 1 ? '' : 's');
// Make a class (for displaying not yet moderated comments differently)
comment.css_class = comment.displayed ? '' : ' moderate';
// Create a div for this comment.
var context = $.extend({}, opts, comment);
var div = $(renderTemplate(commentTemplate, context));
// If the user has voted on this comment, highlight the correct arrow.
if (comment.vote) {
var direction = (comment.vote == 1) ? 'u' : 'd';
div.find('#' + direction + 'v' + comment.id).hide();
div.find('#' + direction + 'u' + comment.id).show();
}
if (opts.moderator || comment.text != '[deleted]') {
div.find('a.reply').show();
if (comment.proposal_diff)
div.find('#sp' + comment.id).show();
if (opts.moderator && !comment.displayed)
div.find('#cm' + comment.id).show();
if (opts.moderator || (opts.username == comment.username))
div.find('#dc' + comment.id).show();
}
return div;
}
/**
* A simple template renderer. Placeholders such as <%id%> are replaced
* by context['id'] with items being escaped. Placeholders such as <#id#>
* are not escaped.
*/
function renderTemplate(template, context) {
var esc = $(document.createElement('div'));
function handle(ph, escape) {
var cur = context;
$.each(ph.split('.'), function() {
cur = cur[this];
});
return escape ? esc.text(cur || "").html() : cur;
}
return template.replace(/<([%#])([\w\.]*)\1>/g, function() {
return handle(arguments[2], arguments[1] == '%' ? true : false);
});
}
/** Flash an error message briefly. */
function showError(message) {
$(document.createElement('div')).attr({'class': 'popup-error'})
.append($(document.createElement('div'))
.attr({'class': 'error-message'}).text(message))
.appendTo('body')
.fadeIn("slow")
.delay(2000)
.fadeOut("slow");
}
/** Add a link the user uses to open the comments popup. */
$.fn.comment = function() {
return this.each(function() {
var id = $(this).attr('id').substring(1);
var count = COMMENT_METADATA[id];
var title = count + ' comment' + (count == 1 ? '' : 's');
var image = count > 0 ? opts.commentBrightImage : opts.commentImage;
var addcls = count == 0 ? ' nocomment' : '';
$(this)
.append(
$(document.createElement('a')).attr({
href: '#',
'class': 'sphinx-comment-open' + addcls,
id: 'ao' + id
})
.append($(document.createElement('img')).attr({
src: image,
alt: 'comment',
title: title
}))
.click(function(event) {
event.preventDefault();
show($(this).attr('id').substring(2));
})
)
.append(
$(document.createElement('a')).attr({
href: '#',
'class': 'sphinx-comment-close hidden',
id: 'ah' + id
})
.append($(document.createElement('img')).attr({
src: opts.closeCommentImage,
alt: 'close',
title: 'close'
}))
.click(function(event) {
event.preventDefault();
hide($(this).attr('id').substring(2));
})
);
});
};
var opts = {
processVoteURL: '/_process_vote',
addCommentURL: '/_add_comment',
getCommentsURL: '/_get_comments',
acceptCommentURL: '/_accept_comment',
deleteCommentURL: '/_delete_comment',
commentImage: '/static/_static/comment.png',
closeCommentImage: '/static/_static/comment-close.png',
loadingImage: '/static/_static/ajax-loader.gif',
commentBrightImage: '/static/_static/comment-bright.png',
upArrow: '/static/_static/up.png',
downArrow: '/static/_static/down.png',
upArrowPressed: '/static/_static/up-pressed.png',
downArrowPressed: '/static/_static/down-pressed.png',
voting: false,
moderator: false
};
if (typeof COMMENT_OPTIONS != "undefined") {
opts = jQuery.extend(opts, COMMENT_OPTIONS);
}
var popupTemplate = '\
<div class="sphinx-comments" id="sc<%id%>">\
<p class="sort-options">\
Sort by:\
<a href="#" class="sort-option byrating">best rated</a>\
<a href="#" class="sort-option byascage">newest</a>\
<a href="#" class="sort-option byage">oldest</a>\
</p>\
<div class="comment-header">Comments</div>\
<div class="comment-loading" id="cn<%id%>">\
loading comments... <img src="<%loadingImage%>" alt="" /></div>\
<ul id="cl<%id%>" class="comment-ul"></ul>\
<div id="ca<%id%>">\
<p class="add-a-comment">Add a comment\
(<a href="#" class="comment-markup" id="ab<%id%>">markup</a>):</p>\
<div class="comment-markup-box" id="mb<%id%>">\
reStructured text markup: <i>*emph*</i>, <b>**strong**</b>, \
<code>``code``</code>, \
code blocks: <code>::</code> and an indented block after blank line</div>\
<form method="post" id="cf<%id%>" class="comment-form" action="">\
<textarea name="comment" cols="80"></textarea>\
<p class="propose-button">\
<a href="#" id="pc<%id%>" class="show-propose-change">\
Propose a change ▹\
</a>\
<a href="#" id="hc<%id%>" class="hide-propose-change">\
Propose a change ▿\
</a>\
</p>\
<textarea name="proposal" id="pt<%id%>" cols="80"\
spellcheck="false"></textarea>\
<input type="submit" value="Add comment" />\
<input type="hidden" name="node" value="<%id%>" />\
<input type="hidden" name="parent" value="" />\
</form>\
</div>\
</div>';
var commentTemplate = '\
<div id="cd<%id%>" class="sphinx-comment<%css_class%>">\
<div class="vote">\
<div class="arrow">\
<a href="#" id="uv<%id%>" class="vote" title="vote up">\
<img src="<%upArrow%>" />\
</a>\
<a href="#" id="uu<%id%>" class="un vote" title="vote up">\
<img src="<%upArrowPressed%>" />\
</a>\
</div>\
<div class="arrow">\
<a href="#" id="dv<%id%>" class="vote" title="vote down">\
<img src="<%downArrow%>" id="da<%id%>" />\
</a>\
<a href="#" id="du<%id%>" class="un vote" title="vote down">\
<img src="<%downArrowPressed%>" />\
</a>\
</div>\
</div>\
<div class="comment-content">\
<p class="tagline comment">\
<span class="user-id"><%username%></span>\
<span class="rating"><%pretty_rating%></span>\
<span class="delta"><%time.delta%></span>\
</p>\
<div class="comment-text comment"><#text#></div>\
<p class="comment-opts comment">\
<a href="#" class="reply hidden" id="rl<%id%>">reply ▹</a>\
<a href="#" class="close-reply" id="cr<%id%>">reply ▿</a>\
<a href="#" id="sp<%id%>" class="show-proposal">proposal ▹</a>\
<a href="#" id="hp<%id%>" class="hide-proposal">proposal ▿</a>\
<a href="#" id="dc<%id%>" class="delete-comment hidden">delete</a>\
<span id="cm<%id%>" class="moderation hidden">\
<a href="#" id="ac<%id%>" class="accept-comment">accept</a>\
</span>\
</p>\
<pre class="proposal" id="pr<%id%>">\
<#proposal_diff#>\
</pre>\
<ul class="comment-children" id="cl<%id%>"></ul>\
</div>\
<div class="clearleft"></div>\
</div>\
</div>';
var replyTemplate = '\
<li>\
<div class="reply-div" id="rd<%id%>">\
<form id="rf<%id%>">\
<textarea name="comment" cols="80"></textarea>\
<input type="submit" value="Add reply" />\
<input type="button" value="Cancel" />\
<input type="hidden" name="parent" value="<%id%>" />\
<input type="hidden" name="node" value="" />\
</form>\
</div>\
</li>';
$(document).ready(function() {
init();
});
})(jQuery);
$(document).ready(function() {
// add comment anchors for all paragraphs that are commentable
$('.sphinx-has-comment').comment();
// highlight search words in search results
$("div.context").each(function() {
var params = $.getQueryParameters();
var terms = (params.q) ? params.q[0].split(/\s+/) : [];
var result = $(this);
$.each(terms, function() {
result.highlightText(this.toLowerCase(), 'highlighted');
});
});
// directly open comment window if requested
var anchor = document.location.hash;
if (anchor.substring(0, 9) == '#comment-') {
$('#ao' + anchor.substring(9)).click();
document.location.hash = '#s' + anchor.substring(9);
}
});
PK
%�\�NC�L! L! html/c-api/gen.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Generator Objects — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="DateTime Objects" href="datetime.html" />
<link rel="prev" title="Cell Objects" href="cell.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/gen.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="datetime.html" title="DateTime Objects"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="cell.html" title="Cell Objects"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" accesskey="U">Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="generator-objects">
<span id="gen-objects"></span><h1>Generator Objects<a class="headerlink" href="#generator-objects" title="Permalink to this headline">¶</a></h1>
<p>Generator objects are what Python uses to implement generator iterators. They
are normally created by iterating over a function that yields values, rather
than explicitly calling <a class="reference internal" href="#c.PyGen_New" title="PyGen_New"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyGen_New()</span></code></a>.</p>
<dl class="type">
<dt id="c.PyGenObject">
<code class="descname">PyGenObject</code><a class="headerlink" href="#c.PyGenObject" title="Permalink to this definition">¶</a></dt>
<dd><p>The C structure used for generator objects.</p>
</dd></dl>
<dl class="var">
<dt id="c.PyGen_Type">
<a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a> <code class="descname">PyGen_Type</code><a class="headerlink" href="#c.PyGen_Type" title="Permalink to this definition">¶</a></dt>
<dd><p>The type object corresponding to generator objects.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyGen_Check">
int <code class="descname">PyGen_Check</code><span class="sig-paren">(</span>ob<span class="sig-paren">)</span><a class="headerlink" href="#c.PyGen_Check" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if <em>ob</em> is a generator object; <em>ob</em> must not be <em>NULL</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyGen_CheckExact">
int <code class="descname">PyGen_CheckExact</code><span class="sig-paren">(</span>ob<span class="sig-paren">)</span><a class="headerlink" href="#c.PyGen_CheckExact" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if <em>ob</em>’s type is <em>PyGen_Type</em> is a generator object; <em>ob</em> must not
be <em>NULL</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyGen_New">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyGen_New</code><span class="sig-paren">(</span>PyFrameObject<em> *frame</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyGen_New" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Create and return a new generator object based on the <em>frame</em> object. A
reference to <em>frame</em> is stolen by this function. The parameter must not be
<em>NULL</em>.</p>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="cell.html"
title="previous chapter">Cell Objects</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="datetime.html"
title="next chapter">DateTime Objects</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/gen.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="datetime.html" title="DateTime Objects"
>next</a> |</li>
<li class="right" >
<a href="cell.html" title="Cell Objects"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" >Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\+��� �� html/c-api/import.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Importing Modules — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Data marshalling support" href="marshal.html" />
<link rel="prev" title="Operating System Utilities" href="sys.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/import.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="marshal.html" title="Data marshalling support"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="sys.html" title="Operating System Utilities"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="utilities.html" accesskey="U">Utilities</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="importing-modules">
<span id="importing"></span><h1>Importing Modules<a class="headerlink" href="#importing-modules" title="Permalink to this headline">¶</a></h1>
<dl class="function">
<dt id="c.PyImport_ImportModule">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyImport_ImportModule</code><span class="sig-paren">(</span>const char<em> *name</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyImport_ImportModule" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p id="index-0">This is a simplified interface to <a class="reference internal" href="#c.PyImport_ImportModuleEx" title="PyImport_ImportModuleEx"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyImport_ImportModuleEx()</span></code></a> below,
leaving the <em>globals</em> and <em>locals</em> arguments set to <em>NULL</em> and <em>level</em> set
to 0. When the <em>name</em>
argument contains a dot (when it specifies a submodule of a package), the
<em>fromlist</em> argument is set to the list <code class="docutils literal notranslate"><span class="pre">['*']</span></code> so that the return value is the
named module rather than the top-level package containing it as would otherwise
be the case. (Unfortunately, this has an additional side effect when <em>name</em> in
fact specifies a subpackage instead of a submodule: the submodules specified in
the package’s <code class="docutils literal notranslate"><span class="pre">__all__</span></code> variable are loaded.) Return a new reference to the
imported module, or <em>NULL</em> with an exception set on failure. Before Python 2.4,
the module may still be created in the failure case — examine <code class="docutils literal notranslate"><span class="pre">sys.modules</span></code>
to find out. Starting with Python 2.4, a failing import of a module no longer
leaves the module in <code class="docutils literal notranslate"><span class="pre">sys.modules</span></code>.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.4: </span>Failing imports remove incomplete module objects.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.6: </span>Always uses absolute imports.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyImport_ImportModuleNoBlock">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyImport_ImportModuleNoBlock</code><span class="sig-paren">(</span>const char<em> *name</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyImport_ImportModuleNoBlock" title="Permalink to this definition">¶</a></dt>
<dd><p>This version of <a class="reference internal" href="#c.PyImport_ImportModule" title="PyImport_ImportModule"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyImport_ImportModule()</span></code></a> does not block. It’s intended
to be used in C functions that import other modules to execute a function.
The import may block if another thread holds the import lock. The function
<a class="reference internal" href="#c.PyImport_ImportModuleNoBlock" title="PyImport_ImportModuleNoBlock"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyImport_ImportModuleNoBlock()</span></code></a> never blocks. It first tries to fetch
the module from sys.modules and falls back to <a class="reference internal" href="#c.PyImport_ImportModule" title="PyImport_ImportModule"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyImport_ImportModule()</span></code></a>
unless the lock is held, in which case the function will raise an
<a class="reference internal" href="../library/exceptions.html#exceptions.ImportError" title="exceptions.ImportError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ImportError</span></code></a>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyImport_ImportModuleEx">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyImport_ImportModuleEx</code><span class="sig-paren">(</span>char<em> *name</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *globals</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *locals</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *fromlist</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyImport_ImportModuleEx" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p id="index-1">Import a module. This is best described by referring to the built-in Python
function <a class="reference internal" href="../library/functions.html#__import__" title="__import__"><code class="xref py py-func docutils literal notranslate"><span class="pre">__import__()</span></code></a>, as the standard <a class="reference internal" href="../library/functions.html#__import__" title="__import__"><code class="xref py py-func docutils literal notranslate"><span class="pre">__import__()</span></code></a> function calls
this function directly.</p>
<p>The return value is a new reference to the imported module or top-level package,
or <em>NULL</em> with an exception set on failure (before Python 2.4, the module may
still be created in this case). Like for <a class="reference internal" href="../library/functions.html#__import__" title="__import__"><code class="xref py py-func docutils literal notranslate"><span class="pre">__import__()</span></code></a>, the return value
when a submodule of a package was requested is normally the top-level package,
unless a non-empty <em>fromlist</em> was given.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.4: </span>Failing imports remove incomplete module objects.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.6: </span>The function is an alias for <a class="reference internal" href="#c.PyImport_ImportModuleLevel" title="PyImport_ImportModuleLevel"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyImport_ImportModuleLevel()</span></code></a> with
<code class="docutils literal notranslate"><span class="pre">-1</span></code> as level, meaning relative import.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyImport_ImportModuleLevel">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyImport_ImportModuleLevel</code><span class="sig-paren">(</span>char<em> *name</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *globals</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *locals</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *fromlist</em>, int<em> level</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyImport_ImportModuleLevel" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Import a module. This is best described by referring to the built-in Python
function <a class="reference internal" href="../library/functions.html#__import__" title="__import__"><code class="xref py py-func docutils literal notranslate"><span class="pre">__import__()</span></code></a>, as the standard <a class="reference internal" href="../library/functions.html#__import__" title="__import__"><code class="xref py py-func docutils literal notranslate"><span class="pre">__import__()</span></code></a> function calls
this function directly.</p>
<p>The return value is a new reference to the imported module or top-level package,
or <em>NULL</em> with an exception set on failure. Like for <a class="reference internal" href="../library/functions.html#__import__" title="__import__"><code class="xref py py-func docutils literal notranslate"><span class="pre">__import__()</span></code></a>,
the return value when a submodule of a package was requested is normally the
top-level package, unless a non-empty <em>fromlist</em> was given.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.5.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyImport_Import">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyImport_Import</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *name</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyImport_Import" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p id="index-2">This is a higher-level interface that calls the current “import hook function”.
It invokes the <a class="reference internal" href="../library/functions.html#__import__" title="__import__"><code class="xref py py-func docutils literal notranslate"><span class="pre">__import__()</span></code></a> function from the <code class="docutils literal notranslate"><span class="pre">__builtins__</span></code> of the
current globals. This means that the import is done using whatever import hooks
are installed in the current environment, e.g. by <a class="reference internal" href="../library/rexec.html#module-rexec" title="rexec: Basic restricted execution framework. (deprecated)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">rexec</span></code></a> or <code class="xref py py-mod docutils literal notranslate"><span class="pre">ihooks</span></code>.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.6: </span>Always uses absolute imports.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyImport_ReloadModule">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyImport_ReloadModule</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *m</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyImport_ReloadModule" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p id="index-3">Reload a module. This is best described by referring to the built-in Python
function <a class="reference internal" href="../library/functions.html#reload" title="reload"><code class="xref py py-func docutils literal notranslate"><span class="pre">reload()</span></code></a>, as the standard <a class="reference internal" href="../library/functions.html#reload" title="reload"><code class="xref py py-func docutils literal notranslate"><span class="pre">reload()</span></code></a> function calls this
function directly. Return a new reference to the reloaded module, or <em>NULL</em>
with an exception set on failure (the module still exists in this case).</p>
</dd></dl>
<dl class="function">
<dt id="c.PyImport_AddModule">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyImport_AddModule</code><span class="sig-paren">(</span>const char<em> *name</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyImport_AddModule" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Borrowed reference.</em><p>Return the module object corresponding to a module name. The <em>name</em> argument
may be of the form <code class="docutils literal notranslate"><span class="pre">package.module</span></code>. First check the modules dictionary if
there’s one there, and if not, create a new one and insert it in the modules
dictionary. Return <em>NULL</em> with an exception set on failure.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This function does not load or import the module; if the module wasn’t already
loaded, you will get an empty module object. Use <a class="reference internal" href="#c.PyImport_ImportModule" title="PyImport_ImportModule"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyImport_ImportModule()</span></code></a>
or one of its variants to import a module. Package structures implied by a
dotted name for <em>name</em> are not created if not already present.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyImport_ExecCodeModule">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyImport_ExecCodeModule</code><span class="sig-paren">(</span>char<em> *name</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *co</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyImport_ExecCodeModule" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p id="index-4">Given a module name (possibly of the form <code class="docutils literal notranslate"><span class="pre">package.module</span></code>) and a code object
read from a Python bytecode file or obtained from the built-in function
<a class="reference internal" href="../library/functions.html#compile" title="compile"><code class="xref py py-func docutils literal notranslate"><span class="pre">compile()</span></code></a>, load the module. Return a new reference to the module object,
or <em>NULL</em> with an exception set if an error occurred. Before Python 2.4, the
module could still be created in error cases. Starting with Python 2.4, <em>name</em>
is removed from <a class="reference internal" href="../library/sys.html#sys.modules" title="sys.modules"><code class="xref py py-attr docutils literal notranslate"><span class="pre">sys.modules</span></code></a> in error cases, and even if <em>name</em> was already
in <a class="reference internal" href="../library/sys.html#sys.modules" title="sys.modules"><code class="xref py py-attr docutils literal notranslate"><span class="pre">sys.modules</span></code></a> on entry to <a class="reference internal" href="#c.PyImport_ExecCodeModule" title="PyImport_ExecCodeModule"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyImport_ExecCodeModule()</span></code></a>. Leaving
incompletely initialized modules in <a class="reference internal" href="../library/sys.html#sys.modules" title="sys.modules"><code class="xref py py-attr docutils literal notranslate"><span class="pre">sys.modules</span></code></a> is dangerous, as imports of
such modules have no way to know that the module object is an unknown (and
probably damaged with respect to the module author’s intents) state.</p>
<p>The module’s <code class="xref py py-attr docutils literal notranslate"><span class="pre">__file__</span></code> attribute will be set to the code object’s
<code class="xref c c-member docutils literal notranslate"><span class="pre">co_filename</span></code>.</p>
<p>This function will reload the module if it was already imported. See
<a class="reference internal" href="#c.PyImport_ReloadModule" title="PyImport_ReloadModule"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyImport_ReloadModule()</span></code></a> for the intended way to reload a module.</p>
<p>If <em>name</em> points to a dotted name of the form <code class="docutils literal notranslate"><span class="pre">package.module</span></code>, any package
structures not already created will still not be created.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.4: </span><em>name</em> is removed from <a class="reference internal" href="../library/sys.html#sys.modules" title="sys.modules"><code class="xref py py-attr docutils literal notranslate"><span class="pre">sys.modules</span></code></a> in error cases.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyImport_ExecCodeModuleEx">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyImport_ExecCodeModuleEx</code><span class="sig-paren">(</span>char<em> *name</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *co</em>, char<em> *pathname</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyImport_ExecCodeModuleEx" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Like <a class="reference internal" href="#c.PyImport_ExecCodeModule" title="PyImport_ExecCodeModule"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyImport_ExecCodeModule()</span></code></a>, but the <code class="xref py py-attr docutils literal notranslate"><span class="pre">__file__</span></code> attribute of
the module object is set to <em>pathname</em> if it is non-<code class="docutils literal notranslate"><span class="pre">NULL</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyImport_GetMagicNumber">
long <code class="descname">PyImport_GetMagicNumber</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyImport_GetMagicNumber" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the magic number for Python bytecode files (a.k.a. <code class="file docutils literal notranslate"><span class="pre">.pyc</span></code> and
<code class="file docutils literal notranslate"><span class="pre">.pyo</span></code> files). The magic number should be present in the first four bytes
of the bytecode file, in little-endian byte order.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyImport_GetModuleDict">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyImport_GetModuleDict</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyImport_GetModuleDict" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Borrowed reference.</em><p>Return the dictionary used for the module administration (a.k.a.
<code class="docutils literal notranslate"><span class="pre">sys.modules</span></code>). Note that this is a per-interpreter variable.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyImport_GetImporter">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyImport_GetImporter</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *path</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyImport_GetImporter" title="Permalink to this definition">¶</a></dt>
<dd><p>Return an importer object for a <a class="reference internal" href="../library/sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code></a>/<code class="xref py py-attr docutils literal notranslate"><span class="pre">pkg.__path__</span></code> item
<em>path</em>, possibly by fetching it from the <a class="reference internal" href="../library/sys.html#sys.path_importer_cache" title="sys.path_importer_cache"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path_importer_cache</span></code></a>
dict. If it wasn’t yet cached, traverse <a class="reference internal" href="../library/sys.html#sys.path_hooks" title="sys.path_hooks"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path_hooks</span></code></a> until a hook
is found that can handle the path item. Return <code class="docutils literal notranslate"><span class="pre">None</span></code> if no hook could;
this tells our caller it should fall back to the built-in import mechanism.
Cache the result in <a class="reference internal" href="../library/sys.html#sys.path_importer_cache" title="sys.path_importer_cache"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path_importer_cache</span></code></a>. Return a new reference
to the importer object.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c._PyImport_Init">
void <code class="descname">_PyImport_Init</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c._PyImport_Init" title="Permalink to this definition">¶</a></dt>
<dd><p>Initialize the import mechanism. For internal use only.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyImport_Cleanup">
void <code class="descname">PyImport_Cleanup</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyImport_Cleanup" title="Permalink to this definition">¶</a></dt>
<dd><p>Empty the module table. For internal use only.</p>
</dd></dl>
<dl class="function">
<dt id="c._PyImport_Fini">
void <code class="descname">_PyImport_Fini</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c._PyImport_Fini" title="Permalink to this definition">¶</a></dt>
<dd><p>Finalize the import mechanism. For internal use only.</p>
</dd></dl>
<dl class="function">
<dt id="c._PyImport_FindExtension">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">_PyImport_FindExtension</code><span class="sig-paren">(</span>char<em> *</em>, char<em> *</em><span class="sig-paren">)</span><a class="headerlink" href="#c._PyImport_FindExtension" title="Permalink to this definition">¶</a></dt>
<dd><p>For internal use only.</p>
</dd></dl>
<dl class="function">
<dt id="c._PyImport_FixupExtension">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">_PyImport_FixupExtension</code><span class="sig-paren">(</span>char<em> *</em>, char<em> *</em><span class="sig-paren">)</span><a class="headerlink" href="#c._PyImport_FixupExtension" title="Permalink to this definition">¶</a></dt>
<dd><p>For internal use only.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyImport_ImportFrozenModule">
int <code class="descname">PyImport_ImportFrozenModule</code><span class="sig-paren">(</span>char<em> *name</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyImport_ImportFrozenModule" title="Permalink to this definition">¶</a></dt>
<dd><p>Load a frozen module named <em>name</em>. Return <code class="docutils literal notranslate"><span class="pre">1</span></code> for success, <code class="docutils literal notranslate"><span class="pre">0</span></code> if the
module is not found, and <code class="docutils literal notranslate"><span class="pre">-1</span></code> with an exception set if the initialization
failed. To access the imported module on a successful load, use
<a class="reference internal" href="#c.PyImport_ImportModule" title="PyImport_ImportModule"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyImport_ImportModule()</span></code></a>. (Note the misnomer — this function would
reload the module if it was already imported.)</p>
</dd></dl>
<dl class="type">
<dt id="c._frozen">
struct <code class="descname">_frozen</code><a class="headerlink" href="#c._frozen" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-5">This is the structure type definition for frozen module descriptors, as
generated by the <strong class="program">freeze</strong> utility (see <code class="file docutils literal notranslate"><span class="pre">Tools/freeze/</span></code> in the
Python source distribution). Its definition, found in <code class="file docutils literal notranslate"><span class="pre">Include/import.h</span></code>,
is:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="n">_frozen</span> <span class="p">{</span>
<span class="kt">char</span> <span class="o">*</span><span class="n">name</span><span class="p">;</span>
<span class="kt">unsigned</span> <span class="kt">char</span> <span class="o">*</span><span class="n">code</span><span class="p">;</span>
<span class="kt">int</span> <span class="n">size</span><span class="p">;</span>
<span class="p">};</span>
</pre></div>
</div>
</dd></dl>
<dl class="var">
<dt id="c.PyImport_FrozenModules">
struct <a class="reference internal" href="#c._frozen" title="_frozen">_frozen</a>* <code class="descname">PyImport_FrozenModules</code><a class="headerlink" href="#c.PyImport_FrozenModules" title="Permalink to this definition">¶</a></dt>
<dd><p>This pointer is initialized to point to an array of <code class="xref c c-type docutils literal notranslate"><span class="pre">struct</span> <span class="pre">_frozen</span></code>
records, terminated by one whose members are all <em>NULL</em> or zero. When a frozen
module is imported, it is searched in this table. Third-party code could play
tricks with this to provide a dynamically created collection of frozen modules.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyImport_AppendInittab">
int <code class="descname">PyImport_AppendInittab</code><span class="sig-paren">(</span>const char<em> *name</em>, void (<em>*initfunc</em>)(void)<span class="sig-paren">)</span><a class="headerlink" href="#c.PyImport_AppendInittab" title="Permalink to this definition">¶</a></dt>
<dd><p>Add a single module to the existing table of built-in modules. This is a
convenience wrapper around <a class="reference internal" href="#c.PyImport_ExtendInittab" title="PyImport_ExtendInittab"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyImport_ExtendInittab()</span></code></a>, returning <code class="docutils literal notranslate"><span class="pre">-1</span></code> if
the table could not be extended. The new module can be imported by the name
<em>name</em>, and uses the function <em>initfunc</em> as the initialization function called
on the first attempted import. This should be called before
<a class="reference internal" href="init.html#c.Py_Initialize" title="Py_Initialize"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_Initialize()</span></code></a>.</p>
</dd></dl>
<dl class="type">
<dt id="c._inittab">
struct <code class="descname">_inittab</code><a class="headerlink" href="#c._inittab" title="Permalink to this definition">¶</a></dt>
<dd><p>Structure describing a single entry in the list of built-in modules. Each of
these structures gives the name and initialization function for a module built
into the interpreter. Programs which embed Python may use an array of these
structures in conjunction with <a class="reference internal" href="#c.PyImport_ExtendInittab" title="PyImport_ExtendInittab"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyImport_ExtendInittab()</span></code></a> to provide
additional built-in modules. The structure is defined in
<code class="file docutils literal notranslate"><span class="pre">Include/import.h</span></code> as:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="n">_inittab</span> <span class="p">{</span>
<span class="kt">char</span> <span class="o">*</span><span class="n">name</span><span class="p">;</span>
<span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">initfunc</span><span class="p">)(</span><span class="kt">void</span><span class="p">);</span>
<span class="p">};</span>
</pre></div>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyImport_ExtendInittab">
int <code class="descname">PyImport_ExtendInittab</code><span class="sig-paren">(</span>struct <a class="reference internal" href="#c._inittab" title="_inittab">_inittab</a><em> *newtab</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyImport_ExtendInittab" title="Permalink to this definition">¶</a></dt>
<dd><p>Add a collection of modules to the table of built-in modules. The <em>newtab</em>
array must end with a sentinel entry which contains <em>NULL</em> for the <code class="xref py py-attr docutils literal notranslate"><span class="pre">name</span></code>
field; failure to provide the sentinel value can result in a memory fault.
Returns <code class="docutils literal notranslate"><span class="pre">0</span></code> on success or <code class="docutils literal notranslate"><span class="pre">-1</span></code> if insufficient memory could be allocated to
extend the internal table. In the event of failure, no modules are added to the
internal table. This should be called before <a class="reference internal" href="init.html#c.Py_Initialize" title="Py_Initialize"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_Initialize()</span></code></a>.</p>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="sys.html"
title="previous chapter">Operating System Utilities</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="marshal.html"
title="next chapter">Data marshalling support</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/import.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="marshal.html" title="Data marshalling support"
>next</a> |</li>
<li class="right" >
<a href="sys.html" title="Operating System Utilities"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="utilities.html" >Utilities</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\G0P�4 �4 html/c-api/index.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Python/C API Reference Manual — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Introduction" href="intro.html" />
<link rel="prev" title="5. Embedding Python in Another Application" href="../extending/embedding.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/index.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="intro.html" title="Introduction"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="../extending/embedding.html" title="5. Embedding Python in Another Application"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="python-c-api-reference-manual">
<span id="c-api-index"></span><h1>Python/C API Reference Manual<a class="headerlink" href="#python-c-api-reference-manual" title="Permalink to this headline">¶</a></h1>
<p>This manual documents the API used by C and C++ programmers who want to write
extension modules or embed Python. It is a companion to <a class="reference internal" href="../extending/index.html#extending-index"><span class="std std-ref">Extending and Embedding the Python Interpreter</span></a>,
which describes the general principles of extension writing but does not
document the API functions in detail.</p>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="intro.html">Introduction</a><ul>
<li class="toctree-l2"><a class="reference internal" href="intro.html#include-files">Include Files</a></li>
<li class="toctree-l2"><a class="reference internal" href="intro.html#objects-types-and-reference-counts">Objects, Types and Reference Counts</a></li>
<li class="toctree-l2"><a class="reference internal" href="intro.html#exceptions">Exceptions</a></li>
<li class="toctree-l2"><a class="reference internal" href="intro.html#embedding-python">Embedding Python</a></li>
<li class="toctree-l2"><a class="reference internal" href="intro.html#debugging-builds">Debugging Builds</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="veryhigh.html">The Very High Level Layer</a></li>
<li class="toctree-l1"><a class="reference internal" href="refcounting.html">Reference Counting</a></li>
<li class="toctree-l1"><a class="reference internal" href="exceptions.html">Exception Handling</a><ul>
<li class="toctree-l2"><a class="reference internal" href="exceptions.html#unicode-exception-objects">Unicode Exception Objects</a></li>
<li class="toctree-l2"><a class="reference internal" href="exceptions.html#recursion-control">Recursion Control</a></li>
<li class="toctree-l2"><a class="reference internal" href="exceptions.html#standard-exceptions">Standard Exceptions</a></li>
<li class="toctree-l2"><a class="reference internal" href="exceptions.html#standard-warning-categories">Standard Warning Categories</a></li>
<li class="toctree-l2"><a class="reference internal" href="exceptions.html#string-exceptions">String Exceptions</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="utilities.html">Utilities</a><ul>
<li class="toctree-l2"><a class="reference internal" href="sys.html">Operating System Utilities</a></li>
<li class="toctree-l2"><a class="reference internal" href="sys.html#system-functions">System Functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="sys.html#process-control">Process Control</a></li>
<li class="toctree-l2"><a class="reference internal" href="import.html">Importing Modules</a></li>
<li class="toctree-l2"><a class="reference internal" href="marshal.html">Data marshalling support</a></li>
<li class="toctree-l2"><a class="reference internal" href="arg.html">Parsing arguments and building values</a></li>
<li class="toctree-l2"><a class="reference internal" href="conversion.html">String conversion and formatting</a></li>
<li class="toctree-l2"><a class="reference internal" href="reflection.html">Reflection</a></li>
<li class="toctree-l2"><a class="reference internal" href="codec.html">Codec registry and support functions</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="abstract.html">Abstract Objects Layer</a><ul>
<li class="toctree-l2"><a class="reference internal" href="object.html">Object Protocol</a></li>
<li class="toctree-l2"><a class="reference internal" href="number.html">Number Protocol</a></li>
<li class="toctree-l2"><a class="reference internal" href="sequence.html">Sequence Protocol</a></li>
<li class="toctree-l2"><a class="reference internal" href="mapping.html">Mapping Protocol</a></li>
<li class="toctree-l2"><a class="reference internal" href="iter.html">Iterator Protocol</a></li>
<li class="toctree-l2"><a class="reference internal" href="objbuffer.html">Old Buffer Protocol</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="concrete.html">Concrete Objects Layer</a><ul>
<li class="toctree-l2"><a class="reference internal" href="concrete.html#fundamental-objects">Fundamental Objects</a></li>
<li class="toctree-l2"><a class="reference internal" href="concrete.html#numeric-objects">Numeric Objects</a></li>
<li class="toctree-l2"><a class="reference internal" href="concrete.html#sequence-objects">Sequence Objects</a></li>
<li class="toctree-l2"><a class="reference internal" href="concrete.html#mapping-objects">Mapping Objects</a></li>
<li class="toctree-l2"><a class="reference internal" href="concrete.html#other-objects">Other Objects</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="init.html">Initialization, Finalization, and Threads</a><ul>
<li class="toctree-l2"><a class="reference internal" href="init.html#initializing-and-finalizing-the-interpreter">Initializing and finalizing the interpreter</a></li>
<li class="toctree-l2"><a class="reference internal" href="init.html#process-wide-parameters">Process-wide parameters</a></li>
<li class="toctree-l2"><a class="reference internal" href="init.html#thread-state-and-the-global-interpreter-lock">Thread State and the Global Interpreter Lock</a></li>
<li class="toctree-l2"><a class="reference internal" href="init.html#sub-interpreter-support">Sub-interpreter support</a></li>
<li class="toctree-l2"><a class="reference internal" href="init.html#asynchronous-notifications">Asynchronous Notifications</a></li>
<li class="toctree-l2"><a class="reference internal" href="init.html#profiling-and-tracing">Profiling and Tracing</a></li>
<li class="toctree-l2"><a class="reference internal" href="init.html#advanced-debugger-support">Advanced Debugger Support</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="memory.html">Memory Management</a><ul>
<li class="toctree-l2"><a class="reference internal" href="memory.html#overview">Overview</a></li>
<li class="toctree-l2"><a class="reference internal" href="memory.html#memory-interface">Memory Interface</a></li>
<li class="toctree-l2"><a class="reference internal" href="memory.html#object-allocators">Object allocators</a></li>
<li class="toctree-l2"><a class="reference internal" href="memory.html#the-pymalloc-allocator">The pymalloc allocator</a></li>
<li class="toctree-l2"><a class="reference internal" href="memory.html#examples">Examples</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="objimpl.html">Object Implementation Support</a><ul>
<li class="toctree-l2"><a class="reference internal" href="allocation.html">Allocating Objects on the Heap</a></li>
<li class="toctree-l2"><a class="reference internal" href="structures.html">Common Object Structures</a></li>
<li class="toctree-l2"><a class="reference internal" href="typeobj.html">Type Objects</a></li>
<li class="toctree-l2"><a class="reference internal" href="typeobj.html#number-object-structures">Number Object Structures</a></li>
<li class="toctree-l2"><a class="reference internal" href="typeobj.html#mapping-object-structures">Mapping Object Structures</a></li>
<li class="toctree-l2"><a class="reference internal" href="typeobj.html#sequence-object-structures">Sequence Object Structures</a></li>
<li class="toctree-l2"><a class="reference internal" href="typeobj.html#buffer-object-structures">Buffer Object Structures</a></li>
<li class="toctree-l2"><a class="reference internal" href="gcsupport.html">Supporting Cyclic Garbage Collection</a></li>
</ul>
</li>
</ul>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="../extending/embedding.html"
title="previous chapter">5. Embedding Python in Another Application</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="intro.html"
title="next chapter">Introduction</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/index.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="intro.html" title="Introduction"
>next</a> |</li>
<li class="right" >
<a href="../extending/embedding.html" title="5. Embedding Python in Another Application"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\��n -� -� html/c-api/init.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Initialization, Finalization, and Threads — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Memory Management" href="memory.html" />
<link rel="prev" title="Code Objects" href="code.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/init.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="memory.html" title="Memory Management"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="code.html" title="Code Objects"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Python/C API Reference Manual</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="initialization-finalization-and-threads">
<span id="initialization"></span><h1>Initialization, Finalization, and Threads<a class="headerlink" href="#initialization-finalization-and-threads" title="Permalink to this headline">¶</a></h1>
<div class="section" id="initializing-and-finalizing-the-interpreter">
<h2>Initializing and finalizing the interpreter<a class="headerlink" href="#initializing-and-finalizing-the-interpreter" title="Permalink to this headline">¶</a></h2>
<dl class="function">
<dt id="c.Py_Initialize">
void <code class="descname">Py_Initialize</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_Initialize" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-0">Initialize the Python interpreter. In an application embedding Python, this
should be called before using any other Python/C API functions; with the
exception of <a class="reference internal" href="#c.Py_SetProgramName" title="Py_SetProgramName"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_SetProgramName()</span></code></a>, <a class="reference internal" href="#c.Py_SetPythonHome" title="Py_SetPythonHome"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_SetPythonHome()</span></code></a>, <a class="reference internal" href="#c.PyEval_InitThreads" title="PyEval_InitThreads"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyEval_InitThreads()</span></code></a>,
<a class="reference internal" href="#c.PyEval_ReleaseLock" title="PyEval_ReleaseLock"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyEval_ReleaseLock()</span></code></a>, and <a class="reference internal" href="#c.PyEval_AcquireLock" title="PyEval_AcquireLock"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyEval_AcquireLock()</span></code></a>. This initializes
the table of loaded modules (<code class="docutils literal notranslate"><span class="pre">sys.modules</span></code>), and creates the fundamental
modules <a class="reference internal" href="../library/__builtin__.html#module-__builtin__" title="__builtin__: The module that provides the built-in namespace."><code class="xref py py-mod docutils literal notranslate"><span class="pre">__builtin__</span></code></a>, <a class="reference internal" href="../library/__main__.html#module-__main__" title="__main__: The environment where the top-level script is run."><code class="xref py py-mod docutils literal notranslate"><span class="pre">__main__</span></code></a> and <a class="reference internal" href="../library/sys.html#module-sys" title="sys: Access system-specific parameters and functions."><code class="xref py py-mod docutils literal notranslate"><span class="pre">sys</span></code></a>. It also initializes
the module search path (<code class="docutils literal notranslate"><span class="pre">sys.path</span></code>). It does not set <code class="docutils literal notranslate"><span class="pre">sys.argv</span></code>; use
<a class="reference internal" href="#c.PySys_SetArgvEx" title="PySys_SetArgvEx"><code class="xref c c-func docutils literal notranslate"><span class="pre">PySys_SetArgvEx()</span></code></a> for that. This is a no-op when called for a second time
(without calling <a class="reference internal" href="#c.Py_Finalize" title="Py_Finalize"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_Finalize()</span></code></a> first). There is no return value; it is a
fatal error if the initialization fails.</p>
</dd></dl>
<dl class="function">
<dt id="c.Py_InitializeEx">
void <code class="descname">Py_InitializeEx</code><span class="sig-paren">(</span>int<em> initsigs</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_InitializeEx" title="Permalink to this definition">¶</a></dt>
<dd><p>This function works like <a class="reference internal" href="#c.Py_Initialize" title="Py_Initialize"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_Initialize()</span></code></a> if <em>initsigs</em> is <code class="docutils literal notranslate"><span class="pre">1</span></code>. If
<em>initsigs</em> is <code class="docutils literal notranslate"><span class="pre">0</span></code>, it skips initialization registration of signal handlers, which
might be useful when Python is embedded.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.Py_IsInitialized">
int <code class="descname">Py_IsInitialized</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_IsInitialized" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true (nonzero) when the Python interpreter has been initialized, false
(zero) if not. After <a class="reference internal" href="#c.Py_Finalize" title="Py_Finalize"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_Finalize()</span></code></a> is called, this returns false until
<a class="reference internal" href="#c.Py_Initialize" title="Py_Initialize"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_Initialize()</span></code></a> is called again.</p>
</dd></dl>
<dl class="function">
<dt id="c.Py_Finalize">
void <code class="descname">Py_Finalize</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_Finalize" title="Permalink to this definition">¶</a></dt>
<dd><p>Undo all initializations made by <a class="reference internal" href="#c.Py_Initialize" title="Py_Initialize"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_Initialize()</span></code></a> and subsequent use of
Python/C API functions, and destroy all sub-interpreters (see
<a class="reference internal" href="#c.Py_NewInterpreter" title="Py_NewInterpreter"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_NewInterpreter()</span></code></a> below) that were created and not yet destroyed since
the last call to <a class="reference internal" href="#c.Py_Initialize" title="Py_Initialize"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_Initialize()</span></code></a>. Ideally, this frees all memory
allocated by the Python interpreter. This is a no-op when called for a second
time (without calling <a class="reference internal" href="#c.Py_Initialize" title="Py_Initialize"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_Initialize()</span></code></a> again first). There is no return
value; errors during finalization are ignored.</p>
<p>This function is provided for a number of reasons. An embedding application
might want to restart Python without having to restart the application itself.
An application that has loaded the Python interpreter from a dynamically
loadable library (or DLL) might want to free all memory allocated by Python
before unloading the DLL. During a hunt for memory leaks in an application a
developer might want to free all memory allocated by Python before exiting from
the application.</p>
<p><strong>Bugs and caveats:</strong> The destruction of modules and objects in modules is done
in random order; this may cause destructors (<a class="reference internal" href="../reference/datamodel.html#object.__del__" title="object.__del__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__del__()</span></code></a> methods) to fail
when they depend on other objects (even functions) or modules. Dynamically
loaded extension modules loaded by Python are not unloaded. Small amounts of
memory allocated by the Python interpreter may not be freed (if you find a leak,
please report it). Memory tied up in circular references between objects is not
freed. Some memory allocated by extension modules may not be freed. Some
extensions may not work properly if their initialization routine is called more
than once; this can happen if an application calls <a class="reference internal" href="#c.Py_Initialize" title="Py_Initialize"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_Initialize()</span></code></a> and
<a class="reference internal" href="#c.Py_Finalize" title="Py_Finalize"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_Finalize()</span></code></a> more than once.</p>
</dd></dl>
</div>
<div class="section" id="process-wide-parameters">
<h2>Process-wide parameters<a class="headerlink" href="#process-wide-parameters" title="Permalink to this headline">¶</a></h2>
<dl class="function">
<dt id="c.Py_SetProgramName">
void <code class="descname">Py_SetProgramName</code><span class="sig-paren">(</span>char<em> *name</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_SetProgramName" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-1">This function should be called before <a class="reference internal" href="#c.Py_Initialize" title="Py_Initialize"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_Initialize()</span></code></a> is called for
the first time, if it is called at all. It tells the interpreter the value
of the <code class="docutils literal notranslate"><span class="pre">argv[0]</span></code> argument to the <code class="xref c c-func docutils literal notranslate"><span class="pre">main()</span></code> function of the program.
This is used by <a class="reference internal" href="#c.Py_GetPath" title="Py_GetPath"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_GetPath()</span></code></a> and some other functions below to find
the Python run-time libraries relative to the interpreter executable. The
default value is <code class="docutils literal notranslate"><span class="pre">'python'</span></code>. The argument should point to a
zero-terminated character string in static storage whose contents will not
change for the duration of the program’s execution. No code in the Python
interpreter will change the contents of this storage.</p>
</dd></dl>
<dl class="function">
<dt id="c.Py_GetProgramName">
char* <code class="descname">Py_GetProgramName</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_GetProgramName" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-2">Return the program name set with <a class="reference internal" href="#c.Py_SetProgramName" title="Py_SetProgramName"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_SetProgramName()</span></code></a>, or the default.
The returned string points into static storage; the caller should not modify its
value.</p>
</dd></dl>
<dl class="function">
<dt id="c.Py_GetPrefix">
char* <code class="descname">Py_GetPrefix</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_GetPrefix" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the <em>prefix</em> for installed platform-independent files. This is derived
through a number of complicated rules from the program name set with
<a class="reference internal" href="#c.Py_SetProgramName" title="Py_SetProgramName"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_SetProgramName()</span></code></a> and some environment variables; for example, if the
program name is <code class="docutils literal notranslate"><span class="pre">'/usr/local/bin/python'</span></code>, the prefix is <code class="docutils literal notranslate"><span class="pre">'/usr/local'</span></code>. The
returned string points into static storage; the caller should not modify its
value. This corresponds to the <strong class="makevar">prefix</strong> variable in the top-level
<code class="file docutils literal notranslate"><span class="pre">Makefile</span></code> and the <code class="docutils literal notranslate"><span class="pre">--prefix</span></code> argument to the <strong class="program">configure</strong>
script at build time. The value is available to Python code as <code class="docutils literal notranslate"><span class="pre">sys.prefix</span></code>.
It is only useful on Unix. See also the next function.</p>
</dd></dl>
<dl class="function">
<dt id="c.Py_GetExecPrefix">
char* <code class="descname">Py_GetExecPrefix</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_GetExecPrefix" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the <em>exec-prefix</em> for installed platform-<em>dependent</em> files. This is
derived through a number of complicated rules from the program name set with
<a class="reference internal" href="#c.Py_SetProgramName" title="Py_SetProgramName"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_SetProgramName()</span></code></a> and some environment variables; for example, if the
program name is <code class="docutils literal notranslate"><span class="pre">'/usr/local/bin/python'</span></code>, the exec-prefix is
<code class="docutils literal notranslate"><span class="pre">'/usr/local'</span></code>. The returned string points into static storage; the caller
should not modify its value. This corresponds to the <strong class="makevar">exec_prefix</strong>
variable in the top-level <code class="file docutils literal notranslate"><span class="pre">Makefile</span></code> and the <code class="docutils literal notranslate"><span class="pre">--exec-prefix</span></code>
argument to the <strong class="program">configure</strong> script at build time. The value is
available to Python code as <code class="docutils literal notranslate"><span class="pre">sys.exec_prefix</span></code>. It is only useful on Unix.</p>
<p>Background: The exec-prefix differs from the prefix when platform dependent
files (such as executables and shared libraries) are installed in a different
directory tree. In a typical installation, platform dependent files may be
installed in the <code class="file docutils literal notranslate"><span class="pre">/usr/local/plat</span></code> subtree while platform independent may
be installed in <code class="file docutils literal notranslate"><span class="pre">/usr/local</span></code>.</p>
<p>Generally speaking, a platform is a combination of hardware and software
families, e.g. Sparc machines running the Solaris 2.x operating system are
considered the same platform, but Intel machines running Solaris 2.x are another
platform, and Intel machines running Linux are yet another platform. Different
major revisions of the same operating system generally also form different
platforms. Non-Unix operating systems are a different story; the installation
strategies on those systems are so different that the prefix and exec-prefix are
meaningless, and set to the empty string. Note that compiled Python bytecode
files are platform independent (but not independent from the Python version by
which they were compiled!).</p>
<p>System administrators will know how to configure the <strong class="program">mount</strong> or
<strong class="program">automount</strong> programs to share <code class="file docutils literal notranslate"><span class="pre">/usr/local</span></code> between platforms
while having <code class="file docutils literal notranslate"><span class="pre">/usr/local/plat</span></code> be a different filesystem for each
platform.</p>
</dd></dl>
<dl class="function">
<dt id="c.Py_GetProgramFullPath">
char* <code class="descname">Py_GetProgramFullPath</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_GetProgramFullPath" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-3">Return the full program name of the Python executable; this is computed as a
side-effect of deriving the default module search path from the program name
(set by <a class="reference internal" href="#c.Py_SetProgramName" title="Py_SetProgramName"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_SetProgramName()</span></code></a> above). The returned string points into
static storage; the caller should not modify its value. The value is available
to Python code as <code class="docutils literal notranslate"><span class="pre">sys.executable</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.Py_GetPath">
char* <code class="descname">Py_GetPath</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_GetPath" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-4">Return the default module search path; this is computed from the program name
(set by <a class="reference internal" href="#c.Py_SetProgramName" title="Py_SetProgramName"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_SetProgramName()</span></code></a> above) and some environment variables.
The returned string consists of a series of directory names separated by a
platform dependent delimiter character. The delimiter character is <code class="docutils literal notranslate"><span class="pre">':'</span></code>
on Unix and Mac OS X, <code class="docutils literal notranslate"><span class="pre">';'</span></code> on Windows. The returned string points into
static storage; the caller should not modify its value. The list
<a class="reference internal" href="../library/sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code></a> is initialized with this value on interpreter startup; it
can be (and usually is) modified later to change the search path for loading
modules.</p>
</dd></dl>
<dl class="function">
<dt id="c.Py_GetVersion">
const char* <code class="descname">Py_GetVersion</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_GetVersion" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the version of this Python interpreter. This is a string that looks
something like</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="s">"1.5 (#67, Dec 31 1997, 22:34:28) [GCC 2.7.2.2]"</span>
</pre></div>
</div>
<p id="index-5">The first word (up to the first space character) is the current Python version;
the first three characters are the major and minor version separated by a
period. The returned string points into static storage; the caller should not
modify its value. The value is available to Python code as <code class="docutils literal notranslate"><span class="pre">sys.version</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.Py_GetPlatform">
const char* <code class="descname">Py_GetPlatform</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_GetPlatform" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-6">Return the platform identifier for the current platform. On Unix, this is
formed from the “official” name of the operating system, converted to lower
case, followed by the major revision number; e.g., for Solaris 2.x, which is
also known as SunOS 5.x, the value is <code class="docutils literal notranslate"><span class="pre">'sunos5'</span></code>. On Mac OS X, it is
<code class="docutils literal notranslate"><span class="pre">'darwin'</span></code>. On Windows, it is <code class="docutils literal notranslate"><span class="pre">'win'</span></code>. The returned string points into
static storage; the caller should not modify its value. The value is available
to Python code as <code class="docutils literal notranslate"><span class="pre">sys.platform</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.Py_GetCopyright">
const char* <code class="descname">Py_GetCopyright</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_GetCopyright" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the official copyright string for the current Python version, for example</p>
<p><code class="docutils literal notranslate"><span class="pre">'Copyright</span> <span class="pre">1991-1995</span> <span class="pre">Stichting</span> <span class="pre">Mathematisch</span> <span class="pre">Centrum,</span> <span class="pre">Amsterdam'</span></code></p>
<p id="index-7">The returned string points into static storage; the caller should not modify its
value. The value is available to Python code as <code class="docutils literal notranslate"><span class="pre">sys.copyright</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.Py_GetCompiler">
const char* <code class="descname">Py_GetCompiler</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_GetCompiler" title="Permalink to this definition">¶</a></dt>
<dd><p>Return an indication of the compiler used to build the current Python version,
in square brackets, for example:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="s">"[GCC 2.7.2.2]"</span>
</pre></div>
</div>
<p id="index-8">The returned string points into static storage; the caller should not modify its
value. The value is available to Python code as part of the variable
<code class="docutils literal notranslate"><span class="pre">sys.version</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.Py_GetBuildInfo">
const char* <code class="descname">Py_GetBuildInfo</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_GetBuildInfo" title="Permalink to this definition">¶</a></dt>
<dd><p>Return information about the sequence number and build date and time of the
current Python interpreter instance, for example</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="s">"#67, Aug 1 1997, 22:34:28"</span>
</pre></div>
</div>
<p id="index-9">The returned string points into static storage; the caller should not modify its
value. The value is available to Python code as part of the variable
<code class="docutils literal notranslate"><span class="pre">sys.version</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PySys_SetArgvEx">
void <code class="descname">PySys_SetArgvEx</code><span class="sig-paren">(</span>int<em> argc</em>, char<em> **argv</em>, int<em> updatepath</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySys_SetArgvEx" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-10">Set <a class="reference internal" href="../library/sys.html#sys.argv" title="sys.argv"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.argv</span></code></a> based on <em>argc</em> and <em>argv</em>. These parameters are
similar to those passed to the program’s <code class="xref c c-func docutils literal notranslate"><span class="pre">main()</span></code> function with the
difference that the first entry should refer to the script file to be
executed rather than the executable hosting the Python interpreter. If there
isn’t a script that will be run, the first entry in <em>argv</em> can be an empty
string. If this function fails to initialize <a class="reference internal" href="../library/sys.html#sys.argv" title="sys.argv"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.argv</span></code></a>, a fatal
condition is signalled using <a class="reference internal" href="sys.html#c.Py_FatalError" title="Py_FatalError"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_FatalError()</span></code></a>.</p>
<p>If <em>updatepath</em> is zero, this is all the function does. If <em>updatepath</em>
is non-zero, the function also modifies <a class="reference internal" href="../library/sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code></a> according to the
following algorithm:</p>
<ul class="simple">
<li>If the name of an existing script is passed in <code class="docutils literal notranslate"><span class="pre">argv[0]</span></code>, the absolute
path of the directory where the script is located is prepended to
<a class="reference internal" href="../library/sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code></a>.</li>
<li>Otherwise (that is, if <em>argc</em> is 0 or <code class="docutils literal notranslate"><span class="pre">argv[0]</span></code> doesn’t point
to an existing file name), an empty string is prepended to
<a class="reference internal" href="../library/sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code></a>, which is the same as prepending the current working
directory (<code class="docutils literal notranslate"><span class="pre">"."</span></code>).</li>
</ul>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>It is recommended that applications embedding the Python interpreter
for purposes other than executing a single script pass <code class="docutils literal notranslate"><span class="pre">0</span></code> as <em>updatepath</em>,
and update <a class="reference internal" href="../library/sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code></a> themselves if desired.
See <a class="reference external" href="https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2008-5983">CVE-2008-5983</a>.</p>
<p>On versions before 2.6.6, you can achieve the same effect by manually
popping the first <a class="reference internal" href="../library/sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code></a> element after having called
<a class="reference internal" href="#c.PySys_SetArgv" title="PySys_SetArgv"><code class="xref c c-func docutils literal notranslate"><span class="pre">PySys_SetArgv()</span></code></a>, for example using:</p>
<div class="last highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">PyRun_SimpleString</span><span class="p">(</span><span class="s">"import sys; sys.path.pop(0)</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span>
</pre></div>
</div>
</div>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.6.6.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PySys_SetArgv">
void <code class="descname">PySys_SetArgv</code><span class="sig-paren">(</span>int<em> argc</em>, char<em> **argv</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySys_SetArgv" title="Permalink to this definition">¶</a></dt>
<dd><p>This function works like <a class="reference internal" href="#c.PySys_SetArgvEx" title="PySys_SetArgvEx"><code class="xref c c-func docutils literal notranslate"><span class="pre">PySys_SetArgvEx()</span></code></a> with <em>updatepath</em> set to <code class="docutils literal notranslate"><span class="pre">1</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.Py_SetPythonHome">
void <code class="descname">Py_SetPythonHome</code><span class="sig-paren">(</span>char<em> *home</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_SetPythonHome" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the default “home” directory, that is, the location of the standard
Python libraries. See <span class="target" id="index-11"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONHOME"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONHOME</span></code></a> for the meaning of the
argument string.</p>
<p>The argument should point to a zero-terminated character string in static
storage whose contents will not change for the duration of the program’s
execution. No code in the Python interpreter will change the contents of
this storage.</p>
</dd></dl>
<dl class="function">
<dt id="c.Py_GetPythonHome">
char* <code class="descname">Py_GetPythonHome</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_GetPythonHome" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the default “home”, that is, the value set by a previous call to
<a class="reference internal" href="#c.Py_SetPythonHome" title="Py_SetPythonHome"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_SetPythonHome()</span></code></a>, or the value of the <span class="target" id="index-12"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONHOME"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONHOME</span></code></a>
environment variable if it is set.</p>
</dd></dl>
</div>
<div class="section" id="thread-state-and-the-global-interpreter-lock">
<span id="threads"></span><h2>Thread State and the Global Interpreter Lock<a class="headerlink" href="#thread-state-and-the-global-interpreter-lock" title="Permalink to this headline">¶</a></h2>
<p id="index-13">The Python interpreter is not fully thread-safe. In order to support
multi-threaded Python programs, there’s a global lock, called the <a class="reference internal" href="../glossary.html#term-global-interpreter-lock"><span class="xref std std-term">global
interpreter lock</span></a> or <a class="reference internal" href="../glossary.html#term-gil"><span class="xref std std-term">GIL</span></a>, that must be held by the current thread before
it can safely access Python objects. Without the lock, even the simplest
operations could cause problems in a multi-threaded program: for example, when
two threads simultaneously increment the reference count of the same object, the
reference count could end up being incremented only once instead of twice.</p>
<p id="index-14">Therefore, the rule exists that only the thread that has acquired the
<a class="reference internal" href="../glossary.html#term-gil"><span class="xref std std-term">GIL</span></a> may operate on Python objects or call Python/C API functions.
In order to emulate concurrency of execution, the interpreter regularly
tries to switch threads (see <a class="reference internal" href="../library/sys.html#sys.setcheckinterval" title="sys.setcheckinterval"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.setcheckinterval()</span></code></a>). The lock is also
released around potentially blocking I/O operations like reading or writing
a file, so that other Python threads can run in the meantime.</p>
<p id="index-15">The Python interpreter keeps some thread-specific bookkeeping information
inside a data structure called <a class="reference internal" href="#c.PyThreadState" title="PyThreadState"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyThreadState</span></code></a>. There’s also one
global variable pointing to the current <a class="reference internal" href="#c.PyThreadState" title="PyThreadState"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyThreadState</span></code></a>: it can
be retrieved using <a class="reference internal" href="#c.PyThreadState_Get" title="PyThreadState_Get"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyThreadState_Get()</span></code></a>.</p>
<div class="section" id="releasing-the-gil-from-extension-code">
<h3>Releasing the GIL from extension code<a class="headerlink" href="#releasing-the-gil-from-extension-code" title="Permalink to this headline">¶</a></h3>
<p>Most extension code manipulating the <a class="reference internal" href="../glossary.html#term-gil"><span class="xref std std-term">GIL</span></a> has the following simple
structure:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">Save</span> <span class="n">the</span> <span class="kr">thread</span> <span class="n">state</span> <span class="n">in</span> <span class="n">a</span> <span class="n">local</span> <span class="n">variable</span><span class="p">.</span>
<span class="n">Release</span> <span class="n">the</span> <span class="n">global</span> <span class="n">interpreter</span> <span class="n">lock</span><span class="p">.</span>
<span class="p">...</span> <span class="n">Do</span> <span class="n">some</span> <span class="n">blocking</span> <span class="n">I</span><span class="o">/</span><span class="n">O</span> <span class="n">operation</span> <span class="p">...</span>
<span class="n">Reacquire</span> <span class="n">the</span> <span class="n">global</span> <span class="n">interpreter</span> <span class="n">lock</span><span class="p">.</span>
<span class="n">Restore</span> <span class="n">the</span> <span class="kr">thread</span> <span class="n">state</span> <span class="n">from</span> <span class="n">the</span> <span class="n">local</span> <span class="n">variable</span><span class="p">.</span>
</pre></div>
</div>
<p>This is so common that a pair of macros exists to simplify it:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">Py_BEGIN_ALLOW_THREADS</span>
<span class="p">...</span> <span class="n">Do</span> <span class="n">some</span> <span class="n">blocking</span> <span class="n">I</span><span class="o">/</span><span class="n">O</span> <span class="n">operation</span> <span class="p">...</span>
<span class="n">Py_END_ALLOW_THREADS</span>
</pre></div>
</div>
<p id="index-16">The <a class="reference internal" href="#c.Py_BEGIN_ALLOW_THREADS" title="Py_BEGIN_ALLOW_THREADS"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_BEGIN_ALLOW_THREADS</span></code></a> macro opens a new block and declares a
hidden local variable; the <a class="reference internal" href="#c.Py_END_ALLOW_THREADS" title="Py_END_ALLOW_THREADS"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_END_ALLOW_THREADS</span></code></a> macro closes the
block. These two macros are still available when Python is compiled without
thread support (they simply have an empty expansion).</p>
<p>When thread support is enabled, the block above expands to the following code:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">PyThreadState</span> <span class="o">*</span><span class="n">_save</span><span class="p">;</span>
<span class="n">_save</span> <span class="o">=</span> <span class="n">PyEval_SaveThread</span><span class="p">();</span>
<span class="p">...</span><span class="n">Do</span> <span class="n">some</span> <span class="n">blocking</span> <span class="n">I</span><span class="o">/</span><span class="n">O</span> <span class="n">operation</span><span class="p">...</span>
<span class="n">PyEval_RestoreThread</span><span class="p">(</span><span class="n">_save</span><span class="p">);</span>
</pre></div>
</div>
<p id="index-17">Here is how these functions work: the global interpreter lock is used to protect the pointer to the
current thread state. When releasing the lock and saving the thread state,
the current thread state pointer must be retrieved before the lock is released
(since another thread could immediately acquire the lock and store its own thread
state in the global variable). Conversely, when acquiring the lock and restoring
the thread state, the lock must be acquired before storing the thread state
pointer.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Calling system I/O functions is the most common use case for releasing
the GIL, but it can also be useful before calling long-running computations
which don’t need access to Python objects, such as compression or
cryptographic functions operating over memory buffers. For example, the
standard <a class="reference internal" href="../library/zlib.html#module-zlib" title="zlib: Low-level interface to compression and decompression routines compatible with gzip."><code class="xref py py-mod docutils literal notranslate"><span class="pre">zlib</span></code></a> and <a class="reference internal" href="../library/hashlib.html#module-hashlib" title="hashlib: Secure hash and message digest algorithms."><code class="xref py py-mod docutils literal notranslate"><span class="pre">hashlib</span></code></a> modules release the GIL when
compressing or hashing data.</p>
</div>
</div>
<div class="section" id="non-python-created-threads">
<span id="gilstate"></span><h3>Non-Python created threads<a class="headerlink" href="#non-python-created-threads" title="Permalink to this headline">¶</a></h3>
<p>When threads are created using the dedicated Python APIs (such as the
<a class="reference internal" href="../library/threading.html#module-threading" title="threading: Higher-level threading interface."><code class="xref py py-mod docutils literal notranslate"><span class="pre">threading</span></code></a> module), a thread state is automatically associated to them
and the code showed above is therefore correct. However, when threads are
created from C (for example by a third-party library with its own thread
management), they don’t hold the GIL, nor is there a thread state structure
for them.</p>
<p>If you need to call Python code from these threads (often this will be part
of a callback API provided by the aforementioned third-party library),
you must first register these threads with the interpreter by
creating a thread state data structure, then acquiring the GIL, and finally
storing their thread state pointer, before you can start using the Python/C
API. When you are done, you should reset the thread state pointer, release
the GIL, and finally free the thread state data structure.</p>
<p>The <a class="reference internal" href="#c.PyGILState_Ensure" title="PyGILState_Ensure"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyGILState_Ensure()</span></code></a> and <a class="reference internal" href="#c.PyGILState_Release" title="PyGILState_Release"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyGILState_Release()</span></code></a> functions do
all of the above automatically. The typical idiom for calling into Python
from a C thread is:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">PyGILState_STATE</span> <span class="n">gstate</span><span class="p">;</span>
<span class="n">gstate</span> <span class="o">=</span> <span class="n">PyGILState_Ensure</span><span class="p">();</span>
<span class="cm">/* Perform Python actions here. */</span>
<span class="n">result</span> <span class="o">=</span> <span class="n">CallSomeFunction</span><span class="p">();</span>
<span class="cm">/* evaluate result or handle exception */</span>
<span class="cm">/* Release the thread. No Python API allowed beyond this point. */</span>
<span class="n">PyGILState_Release</span><span class="p">(</span><span class="n">gstate</span><span class="p">);</span>
</pre></div>
</div>
<p>Note that the <code class="xref c c-func docutils literal notranslate"><span class="pre">PyGILState_*()</span></code> functions assume there is only one global
interpreter (created automatically by <a class="reference internal" href="#c.Py_Initialize" title="Py_Initialize"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_Initialize()</span></code></a>). Python
supports the creation of additional interpreters (using
<a class="reference internal" href="#c.Py_NewInterpreter" title="Py_NewInterpreter"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_NewInterpreter()</span></code></a>), but mixing multiple interpreters and the
<code class="xref c c-func docutils literal notranslate"><span class="pre">PyGILState_*()</span></code> API is unsupported.</p>
<p>Another important thing to note about threads is their behaviour in the face
of the C <code class="xref c c-func docutils literal notranslate"><span class="pre">fork()</span></code> call. On most systems with <code class="xref c c-func docutils literal notranslate"><span class="pre">fork()</span></code>, after a
process forks only the thread that issued the fork will exist. That also
means any locks held by other threads will never be released. Python solves
this for <a class="reference internal" href="../library/os.html#os.fork" title="os.fork"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.fork()</span></code></a> by acquiring the locks it uses internally before
the fork, and releasing them afterwards. In addition, it resets any
<a class="reference internal" href="../library/threading.html#lock-objects"><span class="std std-ref">Lock Objects</span></a> in the child. When extending or embedding Python, there
is no way to inform Python of additional (non-Python) locks that need to be
acquired before or reset after a fork. OS facilities such as
<code class="xref c c-func docutils literal notranslate"><span class="pre">pthread_atfork()</span></code> would need to be used to accomplish the same thing.
Additionally, when extending or embedding Python, calling <code class="xref c c-func docutils literal notranslate"><span class="pre">fork()</span></code>
directly rather than through <a class="reference internal" href="../library/os.html#os.fork" title="os.fork"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.fork()</span></code></a> (and returning to or calling
into Python) may result in a deadlock by one of Python’s internal locks
being held by a thread that is defunct after the fork.
<a class="reference internal" href="sys.html#c.PyOS_AfterFork" title="PyOS_AfterFork"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyOS_AfterFork()</span></code></a> tries to reset the necessary locks, but is not
always able to.</p>
</div>
<div class="section" id="high-level-api">
<h3>High-level API<a class="headerlink" href="#high-level-api" title="Permalink to this headline">¶</a></h3>
<p>These are the most commonly used types and functions when writing C extension
code, or when embedding the Python interpreter:</p>
<dl class="type">
<dt id="c.PyInterpreterState">
<code class="descname">PyInterpreterState</code><a class="headerlink" href="#c.PyInterpreterState" title="Permalink to this definition">¶</a></dt>
<dd><p>This data structure represents the state shared by a number of cooperating
threads. Threads belonging to the same interpreter share their module
administration and a few other internal items. There are no public members in
this structure.</p>
<p>Threads belonging to different interpreters initially share nothing, except
process state like available memory, open file descriptors and such. The global
interpreter lock is also shared by all threads, regardless of to which
interpreter they belong.</p>
</dd></dl>
<dl class="type">
<dt id="c.PyThreadState">
<code class="descname">PyThreadState</code><a class="headerlink" href="#c.PyThreadState" title="Permalink to this definition">¶</a></dt>
<dd><p>This data structure represents the state of a single thread. The only public
data member is <a class="reference internal" href="#c.PyInterpreterState" title="PyInterpreterState"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyInterpreterState</span> <span class="pre">*</span></code></a><code class="xref py py-attr docutils literal notranslate"><span class="pre">interp</span></code>, which points to
this thread’s interpreter state.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyEval_InitThreads">
void <code class="descname">PyEval_InitThreads</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyEval_InitThreads" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-18">Initialize and acquire the global interpreter lock. It should be called in the
main thread before creating a second thread or engaging in any other thread
operations such as <a class="reference internal" href="#c.PyEval_ReleaseLock" title="PyEval_ReleaseLock"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyEval_ReleaseLock()</span></code></a> or
<code class="docutils literal notranslate"><span class="pre">PyEval_ReleaseThread(tstate)</span></code>. It is not needed before calling
<a class="reference internal" href="#c.PyEval_SaveThread" title="PyEval_SaveThread"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyEval_SaveThread()</span></code></a> or <a class="reference internal" href="#c.PyEval_RestoreThread" title="PyEval_RestoreThread"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyEval_RestoreThread()</span></code></a>.</p>
<p id="index-19">This is a no-op when called for a second time. It is safe to call this function
before calling <a class="reference internal" href="#c.Py_Initialize" title="Py_Initialize"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_Initialize()</span></code></a>.</p>
<div class="admonition note" id="index-20">
<p class="first admonition-title">Note</p>
<p>When only the main thread exists, no GIL operations are needed. This is a
common situation (most Python programs do not use threads), and the lock
operations slow the interpreter down a bit. Therefore, the lock is not
created initially. This situation is equivalent to having acquired the lock:
when there is only a single thread, all object accesses are safe. Therefore,
when this function initializes the global interpreter lock, it also acquires
it. Before the Python <code class="xref py py-mod docutils literal notranslate"><span class="pre">_thread</span></code> module creates a new thread, knowing
that either it has the lock or the lock hasn’t been created yet, it calls
<a class="reference internal" href="#c.PyEval_InitThreads" title="PyEval_InitThreads"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyEval_InitThreads()</span></code></a>. When this call returns, it is guaranteed that
the lock has been created and that the calling thread has acquired it.</p>
<p>It is <strong>not</strong> safe to call this function when it is unknown which thread (if
any) currently has the global interpreter lock.</p>
<p class="last">This function is not available when thread support is disabled at compile time.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyEval_ThreadsInitialized">
int <code class="descname">PyEval_ThreadsInitialized</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyEval_ThreadsInitialized" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns a non-zero value if <a class="reference internal" href="#c.PyEval_InitThreads" title="PyEval_InitThreads"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyEval_InitThreads()</span></code></a> has been called. This
function can be called without holding the GIL, and therefore can be used to
avoid calls to the locking API when running single-threaded. This function is
not available when thread support is disabled at compile time.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyEval_SaveThread">
<a class="reference internal" href="#c.PyThreadState" title="PyThreadState">PyThreadState</a>* <code class="descname">PyEval_SaveThread</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyEval_SaveThread" title="Permalink to this definition">¶</a></dt>
<dd><p>Release the global interpreter lock (if it has been created and thread
support is enabled) and reset the thread state to <em>NULL</em>, returning the
previous thread state (which is not <em>NULL</em>). If the lock has been created,
the current thread must have acquired it. (This function is available even
when thread support is disabled at compile time.)</p>
</dd></dl>
<dl class="function">
<dt id="c.PyEval_RestoreThread">
void <code class="descname">PyEval_RestoreThread</code><span class="sig-paren">(</span><a class="reference internal" href="#c.PyThreadState" title="PyThreadState">PyThreadState</a><em> *tstate</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyEval_RestoreThread" title="Permalink to this definition">¶</a></dt>
<dd><p>Acquire the global interpreter lock (if it has been created and thread
support is enabled) and set the thread state to <em>tstate</em>, which must not be
<em>NULL</em>. If the lock has been created, the current thread must not have
acquired it, otherwise deadlock ensues. (This function is available even
when thread support is disabled at compile time.)</p>
</dd></dl>
<dl class="function">
<dt id="c.PyThreadState_Get">
<a class="reference internal" href="#c.PyThreadState" title="PyThreadState">PyThreadState</a>* <code class="descname">PyThreadState_Get</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyThreadState_Get" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the current thread state. The global interpreter lock must be held.
When the current thread state is <em>NULL</em>, this issues a fatal error (so that
the caller needn’t check for <em>NULL</em>).</p>
</dd></dl>
<dl class="function">
<dt id="c.PyThreadState_Swap">
<a class="reference internal" href="#c.PyThreadState" title="PyThreadState">PyThreadState</a>* <code class="descname">PyThreadState_Swap</code><span class="sig-paren">(</span><a class="reference internal" href="#c.PyThreadState" title="PyThreadState">PyThreadState</a><em> *tstate</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyThreadState_Swap" title="Permalink to this definition">¶</a></dt>
<dd><p>Swap the current thread state with the thread state given by the argument
<em>tstate</em>, which may be <em>NULL</em>. The global interpreter lock must be held
and is not released.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyEval_ReInitThreads">
void <code class="descname">PyEval_ReInitThreads</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyEval_ReInitThreads" title="Permalink to this definition">¶</a></dt>
<dd><p>This function is called from <a class="reference internal" href="sys.html#c.PyOS_AfterFork" title="PyOS_AfterFork"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyOS_AfterFork()</span></code></a> to ensure that newly
created child processes don’t hold locks referring to threads which
are not running in the child process.</p>
</dd></dl>
<p>The following functions use thread-local storage, and are not compatible
with sub-interpreters:</p>
<dl class="function">
<dt id="c.PyGILState_Ensure">
PyGILState_STATE <code class="descname">PyGILState_Ensure</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyGILState_Ensure" title="Permalink to this definition">¶</a></dt>
<dd><p>Ensure that the current thread is ready to call the Python C API regardless
of the current state of Python, or of the global interpreter lock. This may
be called as many times as desired by a thread as long as each call is
matched with a call to <a class="reference internal" href="#c.PyGILState_Release" title="PyGILState_Release"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyGILState_Release()</span></code></a>. In general, other
thread-related APIs may be used between <a class="reference internal" href="#c.PyGILState_Ensure" title="PyGILState_Ensure"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyGILState_Ensure()</span></code></a> and
<a class="reference internal" href="#c.PyGILState_Release" title="PyGILState_Release"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyGILState_Release()</span></code></a> calls as long as the thread state is restored to
its previous state before the Release(). For example, normal usage of the
<a class="reference internal" href="#c.Py_BEGIN_ALLOW_THREADS" title="Py_BEGIN_ALLOW_THREADS"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_BEGIN_ALLOW_THREADS</span></code></a> and <a class="reference internal" href="#c.Py_END_ALLOW_THREADS" title="Py_END_ALLOW_THREADS"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_END_ALLOW_THREADS</span></code></a> macros is
acceptable.</p>
<p>The return value is an opaque “handle” to the thread state when
<a class="reference internal" href="#c.PyGILState_Ensure" title="PyGILState_Ensure"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyGILState_Ensure()</span></code></a> was called, and must be passed to
<a class="reference internal" href="#c.PyGILState_Release" title="PyGILState_Release"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyGILState_Release()</span></code></a> to ensure Python is left in the same state. Even
though recursive calls are allowed, these handles <em>cannot</em> be shared - each
unique call to <a class="reference internal" href="#c.PyGILState_Ensure" title="PyGILState_Ensure"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyGILState_Ensure()</span></code></a> must save the handle for its call
to <a class="reference internal" href="#c.PyGILState_Release" title="PyGILState_Release"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyGILState_Release()</span></code></a>.</p>
<p>When the function returns, the current thread will hold the GIL and be able
to call arbitrary Python code. Failure is a fatal error.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.3.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyGILState_Release">
void <code class="descname">PyGILState_Release</code><span class="sig-paren">(</span>PyGILState_STATE<span class="sig-paren">)</span><a class="headerlink" href="#c.PyGILState_Release" title="Permalink to this definition">¶</a></dt>
<dd><p>Release any resources previously acquired. After this call, Python’s state will
be the same as it was prior to the corresponding <a class="reference internal" href="#c.PyGILState_Ensure" title="PyGILState_Ensure"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyGILState_Ensure()</span></code></a> call
(but generally this state will be unknown to the caller, hence the use of the
GILState API).</p>
<p>Every call to <a class="reference internal" href="#c.PyGILState_Ensure" title="PyGILState_Ensure"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyGILState_Ensure()</span></code></a> must be matched by a call to
<a class="reference internal" href="#c.PyGILState_Release" title="PyGILState_Release"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyGILState_Release()</span></code></a> on the same thread.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.3.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyGILState_GetThisThreadState">
<a class="reference internal" href="#c.PyThreadState" title="PyThreadState">PyThreadState</a>* <code class="descname">PyGILState_GetThisThreadState</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyGILState_GetThisThreadState" title="Permalink to this definition">¶</a></dt>
<dd><p>Get the current thread state for this thread. May return <code class="docutils literal notranslate"><span class="pre">NULL</span></code> if no
GILState API has been used on the current thread. Note that the main thread
always has such a thread-state, even if no auto-thread-state call has been
made on the main thread. This is mainly a helper/diagnostic function.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.3.</span></p>
</div>
</dd></dl>
<p>The following macros are normally used without a trailing semicolon; look for
example usage in the Python source distribution.</p>
<dl class="macro">
<dt id="c.Py_BEGIN_ALLOW_THREADS">
<code class="descname">Py_BEGIN_ALLOW_THREADS</code><a class="headerlink" href="#c.Py_BEGIN_ALLOW_THREADS" title="Permalink to this definition">¶</a></dt>
<dd><p>This macro expands to <code class="docutils literal notranslate"><span class="pre">{</span> <span class="pre">PyThreadState</span> <span class="pre">*_save;</span> <span class="pre">_save</span> <span class="pre">=</span> <span class="pre">PyEval_SaveThread();</span></code>.
Note that it contains an opening brace; it must be matched with a following
<a class="reference internal" href="#c.Py_END_ALLOW_THREADS" title="Py_END_ALLOW_THREADS"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_END_ALLOW_THREADS</span></code></a> macro. See above for further discussion of this
macro. It is a no-op when thread support is disabled at compile time.</p>
</dd></dl>
<dl class="macro">
<dt id="c.Py_END_ALLOW_THREADS">
<code class="descname">Py_END_ALLOW_THREADS</code><a class="headerlink" href="#c.Py_END_ALLOW_THREADS" title="Permalink to this definition">¶</a></dt>
<dd><p>This macro expands to <code class="docutils literal notranslate"><span class="pre">PyEval_RestoreThread(_save);</span> <span class="pre">}</span></code>. Note that it contains
a closing brace; it must be matched with an earlier
<a class="reference internal" href="#c.Py_BEGIN_ALLOW_THREADS" title="Py_BEGIN_ALLOW_THREADS"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_BEGIN_ALLOW_THREADS</span></code></a> macro. See above for further discussion of
this macro. It is a no-op when thread support is disabled at compile time.</p>
</dd></dl>
<dl class="macro">
<dt id="c.Py_BLOCK_THREADS">
<code class="descname">Py_BLOCK_THREADS</code><a class="headerlink" href="#c.Py_BLOCK_THREADS" title="Permalink to this definition">¶</a></dt>
<dd><p>This macro expands to <code class="docutils literal notranslate"><span class="pre">PyEval_RestoreThread(_save);</span></code>: it is equivalent to
<a class="reference internal" href="#c.Py_END_ALLOW_THREADS" title="Py_END_ALLOW_THREADS"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_END_ALLOW_THREADS</span></code></a> without the closing brace. It is a no-op when
thread support is disabled at compile time.</p>
</dd></dl>
<dl class="macro">
<dt id="c.Py_UNBLOCK_THREADS">
<code class="descname">Py_UNBLOCK_THREADS</code><a class="headerlink" href="#c.Py_UNBLOCK_THREADS" title="Permalink to this definition">¶</a></dt>
<dd><p>This macro expands to <code class="docutils literal notranslate"><span class="pre">_save</span> <span class="pre">=</span> <span class="pre">PyEval_SaveThread();</span></code>: it is equivalent to
<a class="reference internal" href="#c.Py_BEGIN_ALLOW_THREADS" title="Py_BEGIN_ALLOW_THREADS"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_BEGIN_ALLOW_THREADS</span></code></a> without the opening brace and variable
declaration. It is a no-op when thread support is disabled at compile time.</p>
</dd></dl>
</div>
<div class="section" id="low-level-api">
<h3>Low-level API<a class="headerlink" href="#low-level-api" title="Permalink to this headline">¶</a></h3>
<p>All of the following functions are only available when thread support is enabled
at compile time, and must be called only when the global interpreter lock has
been created.</p>
<dl class="function">
<dt id="c.PyInterpreterState_New">
<a class="reference internal" href="#c.PyInterpreterState" title="PyInterpreterState">PyInterpreterState</a>* <code class="descname">PyInterpreterState_New</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyInterpreterState_New" title="Permalink to this definition">¶</a></dt>
<dd><p>Create a new interpreter state object. The global interpreter lock need not
be held, but may be held if it is necessary to serialize calls to this
function.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyInterpreterState_Clear">
void <code class="descname">PyInterpreterState_Clear</code><span class="sig-paren">(</span><a class="reference internal" href="#c.PyInterpreterState" title="PyInterpreterState">PyInterpreterState</a><em> *interp</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyInterpreterState_Clear" title="Permalink to this definition">¶</a></dt>
<dd><p>Reset all information in an interpreter state object. The global interpreter
lock must be held.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyInterpreterState_Delete">
void <code class="descname">PyInterpreterState_Delete</code><span class="sig-paren">(</span><a class="reference internal" href="#c.PyInterpreterState" title="PyInterpreterState">PyInterpreterState</a><em> *interp</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyInterpreterState_Delete" title="Permalink to this definition">¶</a></dt>
<dd><p>Destroy an interpreter state object. The global interpreter lock need not be
held. The interpreter state must have been reset with a previous call to
<a class="reference internal" href="#c.PyInterpreterState_Clear" title="PyInterpreterState_Clear"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyInterpreterState_Clear()</span></code></a>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyThreadState_New">
<a class="reference internal" href="#c.PyThreadState" title="PyThreadState">PyThreadState</a>* <code class="descname">PyThreadState_New</code><span class="sig-paren">(</span><a class="reference internal" href="#c.PyInterpreterState" title="PyInterpreterState">PyInterpreterState</a><em> *interp</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyThreadState_New" title="Permalink to this definition">¶</a></dt>
<dd><p>Create a new thread state object belonging to the given interpreter object.
The global interpreter lock need not be held, but may be held if it is
necessary to serialize calls to this function.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyThreadState_Clear">
void <code class="descname">PyThreadState_Clear</code><span class="sig-paren">(</span><a class="reference internal" href="#c.PyThreadState" title="PyThreadState">PyThreadState</a><em> *tstate</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyThreadState_Clear" title="Permalink to this definition">¶</a></dt>
<dd><p>Reset all information in a thread state object. The global interpreter lock
must be held.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyThreadState_Delete">
void <code class="descname">PyThreadState_Delete</code><span class="sig-paren">(</span><a class="reference internal" href="#c.PyThreadState" title="PyThreadState">PyThreadState</a><em> *tstate</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyThreadState_Delete" title="Permalink to this definition">¶</a></dt>
<dd><p>Destroy a thread state object. The global interpreter lock need not be held.
The thread state must have been reset with a previous call to
<a class="reference internal" href="#c.PyThreadState_Clear" title="PyThreadState_Clear"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyThreadState_Clear()</span></code></a>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyThreadState_GetDict">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyThreadState_GetDict</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyThreadState_GetDict" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Borrowed reference.</em><p>Return a dictionary in which extensions can store thread-specific state
information. Each extension should use a unique key to use to store state in
the dictionary. It is okay to call this function when no current thread state
is available. If this function returns <em>NULL</em>, no exception has been raised and
the caller should assume no current thread state is available.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.3: </span>Previously this could only be called when a current thread is active, and <em>NULL</em>
meant that an exception was raised.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyThreadState_SetAsyncExc">
int <code class="descname">PyThreadState_SetAsyncExc</code><span class="sig-paren">(</span>long<em> id</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *exc</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyThreadState_SetAsyncExc" title="Permalink to this definition">¶</a></dt>
<dd><p>Asynchronously raise an exception in a thread. The <em>id</em> argument is the thread
id of the target thread; <em>exc</em> is the exception object to be raised. This
function does not steal any references to <em>exc</em>. To prevent naive misuse, you
must write your own C extension to call this. Must be called with the GIL held.
Returns the number of thread states modified; this is normally one, but will be
zero if the thread id isn’t found. If <em>exc</em> is <code class="xref py py-const docutils literal notranslate"><span class="pre">NULL</span></code>, the pending
exception (if any) for the thread is cleared. This raises no exceptions.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.3.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyEval_AcquireThread">
void <code class="descname">PyEval_AcquireThread</code><span class="sig-paren">(</span><a class="reference internal" href="#c.PyThreadState" title="PyThreadState">PyThreadState</a><em> *tstate</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyEval_AcquireThread" title="Permalink to this definition">¶</a></dt>
<dd><p>Acquire the global interpreter lock and set the current thread state to
<em>tstate</em>, which should not be <em>NULL</em>. The lock must have been created earlier.
If this thread already has the lock, deadlock ensues.</p>
<p><a class="reference internal" href="#c.PyEval_RestoreThread" title="PyEval_RestoreThread"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyEval_RestoreThread()</span></code></a> is a higher-level function which is always
available (even when thread support isn’t enabled or when threads have
not been initialized).</p>
</dd></dl>
<dl class="function">
<dt id="c.PyEval_ReleaseThread">
void <code class="descname">PyEval_ReleaseThread</code><span class="sig-paren">(</span><a class="reference internal" href="#c.PyThreadState" title="PyThreadState">PyThreadState</a><em> *tstate</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyEval_ReleaseThread" title="Permalink to this definition">¶</a></dt>
<dd><p>Reset the current thread state to <em>NULL</em> and release the global interpreter
lock. The lock must have been created earlier and must be held by the current
thread. The <em>tstate</em> argument, which must not be <em>NULL</em>, is only used to check
that it represents the current thread state — if it isn’t, a fatal error is
reported.</p>
<p><a class="reference internal" href="#c.PyEval_SaveThread" title="PyEval_SaveThread"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyEval_SaveThread()</span></code></a> is a higher-level function which is always
available (even when thread support isn’t enabled or when threads have
not been initialized).</p>
</dd></dl>
<dl class="function">
<dt id="c.PyEval_AcquireLock">
void <code class="descname">PyEval_AcquireLock</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyEval_AcquireLock" title="Permalink to this definition">¶</a></dt>
<dd><p>Acquire the global interpreter lock. The lock must have been created earlier.
If this thread already has the lock, a deadlock ensues.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">This function does not change the current thread state. Please use
<a class="reference internal" href="#c.PyEval_RestoreThread" title="PyEval_RestoreThread"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyEval_RestoreThread()</span></code></a> or <a class="reference internal" href="#c.PyEval_AcquireThread" title="PyEval_AcquireThread"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyEval_AcquireThread()</span></code></a>
instead.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyEval_ReleaseLock">
void <code class="descname">PyEval_ReleaseLock</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyEval_ReleaseLock" title="Permalink to this definition">¶</a></dt>
<dd><p>Release the global interpreter lock. The lock must have been created earlier.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">This function does not change the current thread state. Please use
<a class="reference internal" href="#c.PyEval_SaveThread" title="PyEval_SaveThread"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyEval_SaveThread()</span></code></a> or <a class="reference internal" href="#c.PyEval_ReleaseThread" title="PyEval_ReleaseThread"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyEval_ReleaseThread()</span></code></a>
instead.</p>
</div>
</dd></dl>
</div>
</div>
<div class="section" id="sub-interpreter-support">
<h2>Sub-interpreter support<a class="headerlink" href="#sub-interpreter-support" title="Permalink to this headline">¶</a></h2>
<p>While in most uses, you will only embed a single Python interpreter, there
are cases where you need to create several independent interpreters in the
same process and perhaps even in the same thread. Sub-interpreters allow
you to do that. You can switch between sub-interpreters using the
<a class="reference internal" href="#c.PyThreadState_Swap" title="PyThreadState_Swap"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyThreadState_Swap()</span></code></a> function. You can create and destroy them
using the following functions:</p>
<dl class="function">
<dt id="c.Py_NewInterpreter">
<a class="reference internal" href="#c.PyThreadState" title="PyThreadState">PyThreadState</a>* <code class="descname">Py_NewInterpreter</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_NewInterpreter" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-21">Create a new sub-interpreter. This is an (almost) totally separate environment
for the execution of Python code. In particular, the new interpreter has
separate, independent versions of all imported modules, including the
fundamental modules <code class="xref py py-mod docutils literal notranslate"><span class="pre">builtins</span></code>, <a class="reference internal" href="../library/__main__.html#module-__main__" title="__main__: The environment where the top-level script is run."><code class="xref py py-mod docutils literal notranslate"><span class="pre">__main__</span></code></a> and <a class="reference internal" href="../library/sys.html#module-sys" title="sys: Access system-specific parameters and functions."><code class="xref py py-mod docutils literal notranslate"><span class="pre">sys</span></code></a>. The
table of loaded modules (<code class="docutils literal notranslate"><span class="pre">sys.modules</span></code>) and the module search path
(<code class="docutils literal notranslate"><span class="pre">sys.path</span></code>) are also separate. The new environment has no <code class="docutils literal notranslate"><span class="pre">sys.argv</span></code>
variable. It has new standard I/O stream file objects <code class="docutils literal notranslate"><span class="pre">sys.stdin</span></code>,
<code class="docutils literal notranslate"><span class="pre">sys.stdout</span></code> and <code class="docutils literal notranslate"><span class="pre">sys.stderr</span></code> (however these refer to the same underlying
file descriptors).</p>
<p>The return value points to the first thread state created in the new
sub-interpreter. This thread state is made in the current thread state.
Note that no actual thread is created; see the discussion of thread states
below. If creation of the new interpreter is unsuccessful, <em>NULL</em> is
returned; no exception is set since the exception state is stored in the
current thread state and there may not be a current thread state. (Like all
other Python/C API functions, the global interpreter lock must be held before
calling this function and is still held when it returns; however, unlike most
other Python/C API functions, there needn’t be a current thread state on
entry.)</p>
<p id="index-22">Extension modules are shared between (sub-)interpreters as follows: the first
time a particular extension is imported, it is initialized normally, and a
(shallow) copy of its module’s dictionary is squirreled away. When the same
extension is imported by another (sub-)interpreter, a new module is initialized
and filled with the contents of this copy; the extension’s <code class="docutils literal notranslate"><span class="pre">init</span></code> function is
not called. Note that this is different from what happens when an extension is
imported after the interpreter has been completely re-initialized by calling
<a class="reference internal" href="#c.Py_Finalize" title="Py_Finalize"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_Finalize()</span></code></a> and <a class="reference internal" href="#c.Py_Initialize" title="Py_Initialize"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_Initialize()</span></code></a>; in that case, the extension’s
<code class="docutils literal notranslate"><span class="pre">initmodule</span></code> function <em>is</em> called again.</p>
<span class="target" id="index-23"></span></dd></dl>
<dl class="function">
<dt id="c.Py_EndInterpreter">
void <code class="descname">Py_EndInterpreter</code><span class="sig-paren">(</span><a class="reference internal" href="#c.PyThreadState" title="PyThreadState">PyThreadState</a><em> *tstate</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_EndInterpreter" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-24">Destroy the (sub-)interpreter represented by the given thread state. The given
thread state must be the current thread state. See the discussion of thread
states below. When the call returns, the current thread state is <em>NULL</em>. All
thread states associated with this interpreter are destroyed. (The global
interpreter lock must be held before calling this function and is still held
when it returns.) <a class="reference internal" href="#c.Py_Finalize" title="Py_Finalize"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_Finalize()</span></code></a> will destroy all sub-interpreters that
haven’t been explicitly destroyed at that point.</p>
</dd></dl>
<div class="section" id="bugs-and-caveats">
<h3>Bugs and caveats<a class="headerlink" href="#bugs-and-caveats" title="Permalink to this headline">¶</a></h3>
<p>Because sub-interpreters (and the main interpreter) are part of the same
process, the insulation between them isn’t perfect — for example, using
low-level file operations like <a class="reference internal" href="../library/os.html#os.close" title="os.close"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.close()</span></code></a> they can
(accidentally or maliciously) affect each other’s open files. Because of the
way extensions are shared between (sub-)interpreters, some extensions may not
work properly; this is especially likely when the extension makes use of
(static) global variables, or when the extension manipulates its module’s
dictionary after its initialization. It is possible to insert objects created
in one sub-interpreter into a namespace of another sub-interpreter; this should
be done with great care to avoid sharing user-defined functions, methods,
instances or classes between sub-interpreters, since import operations executed
by such objects may affect the wrong (sub-)interpreter’s dictionary of loaded
modules.</p>
<p>Also note that combining this functionality with <code class="xref c c-func docutils literal notranslate"><span class="pre">PyGILState_*()</span></code> APIs
is delicate, because these APIs assume a bijection between Python thread states
and OS-level threads, an assumption broken by the presence of sub-interpreters.
It is highly recommended that you don’t switch sub-interpreters between a pair
of matching <a class="reference internal" href="#c.PyGILState_Ensure" title="PyGILState_Ensure"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyGILState_Ensure()</span></code></a> and <a class="reference internal" href="#c.PyGILState_Release" title="PyGILState_Release"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyGILState_Release()</span></code></a> calls.
Furthermore, extensions (such as <a class="reference internal" href="../library/ctypes.html#module-ctypes" title="ctypes: A foreign function library for Python."><code class="xref py py-mod docutils literal notranslate"><span class="pre">ctypes</span></code></a>) using these APIs to allow calling
of Python code from non-Python created threads will probably be broken when using
sub-interpreters.</p>
</div>
</div>
<div class="section" id="asynchronous-notifications">
<h2>Asynchronous Notifications<a class="headerlink" href="#asynchronous-notifications" title="Permalink to this headline">¶</a></h2>
<p>A mechanism is provided to make asynchronous notifications to the main
interpreter thread. These notifications take the form of a function
pointer and a void pointer argument.</p>
<dl class="function">
<dt id="c.Py_AddPendingCall">
int <code class="descname">Py_AddPendingCall</code><span class="sig-paren">(</span>int (<em>*func</em>)(void *), void<em> *arg</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_AddPendingCall" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-25">Schedule a function to be called from the main interpreter thread. On
success, <code class="docutils literal notranslate"><span class="pre">0</span></code> is returned and <em>func</em> is queued for being called in the
main thread. On failure, <code class="docutils literal notranslate"><span class="pre">-1</span></code> is returned without setting any exception.</p>
<p>When successfully queued, <em>func</em> will be <em>eventually</em> called from the
main interpreter thread with the argument <em>arg</em>. It will be called
asynchronously with respect to normally running Python code, but with
both these conditions met:</p>
<ul class="simple">
<li>on a <a class="reference internal" href="../glossary.html#term-bytecode"><span class="xref std std-term">bytecode</span></a> boundary;</li>
<li>with the main thread holding the <a class="reference internal" href="../glossary.html#term-global-interpreter-lock"><span class="xref std std-term">global interpreter lock</span></a>
(<em>func</em> can therefore use the full C API).</li>
</ul>
<p><em>func</em> must return <code class="docutils literal notranslate"><span class="pre">0</span></code> on success, or <code class="docutils literal notranslate"><span class="pre">-1</span></code> on failure with an exception
set. <em>func</em> won’t be interrupted to perform another asynchronous
notification recursively, but it can still be interrupted to switch
threads if the global interpreter lock is released.</p>
<p>This function doesn’t need a current thread state to run, and it doesn’t
need the global interpreter lock.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">This is a low-level function, only useful for very special cases.
There is no guarantee that <em>func</em> will be called as quick as
possible. If the main thread is busy executing a system call,
<em>func</em> won’t be called before the system call returns. This
function is generally <strong>not</strong> suitable for calling Python code from
arbitrary C threads. Instead, use the <a class="reference internal" href="#gilstate"><span class="std std-ref">PyGILState API</span></a>.</p>
</div>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.7.</span></p>
</div>
</dd></dl>
</div>
<div class="section" id="profiling-and-tracing">
<span id="profiling"></span><h2>Profiling and Tracing<a class="headerlink" href="#profiling-and-tracing" title="Permalink to this headline">¶</a></h2>
<p>The Python interpreter provides some low-level support for attaching profiling
and execution tracing facilities. These are used for profiling, debugging, and
coverage analysis tools.</p>
<p>Starting with Python 2.2, the implementation of this facility was substantially
revised, and an interface from C was added. This C interface allows the
profiling or tracing code to avoid the overhead of calling through Python-level
callable objects, making a direct C function call instead. The essential
attributes of the facility have not changed; the interface allows trace
functions to be installed per-thread, and the basic events reported to the trace
function are the same as had been reported to the Python-level trace functions
in previous versions.</p>
<dl class="type">
<dt id="c.Py_tracefunc">
int <code class="descname">(*Py_tracefunc)</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *obj</em>, PyFrameObject<em> *frame</em>, int<em> what</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *arg</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_tracefunc" title="Permalink to this definition">¶</a></dt>
<dd><p>The type of the trace function registered using <a class="reference internal" href="#c.PyEval_SetProfile" title="PyEval_SetProfile"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyEval_SetProfile()</span></code></a> and
<a class="reference internal" href="#c.PyEval_SetTrace" title="PyEval_SetTrace"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyEval_SetTrace()</span></code></a>. The first parameter is the object passed to the
registration function as <em>obj</em>, <em>frame</em> is the frame object to which the event
pertains, <em>what</em> is one of the constants <code class="xref py py-const docutils literal notranslate"><span class="pre">PyTrace_CALL</span></code>,
<code class="xref py py-const docutils literal notranslate"><span class="pre">PyTrace_EXCEPTION</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">PyTrace_LINE</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">PyTrace_RETURN</span></code>,
<code class="xref py py-const docutils literal notranslate"><span class="pre">PyTrace_C_CALL</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">PyTrace_C_EXCEPTION</span></code>, or
<code class="xref py py-const docutils literal notranslate"><span class="pre">PyTrace_C_RETURN</span></code>, and <em>arg</em> depends on the value of <em>what</em>:</p>
<table border="1" class="docutils">
<colgroup>
<col width="44%" />
<col width="56%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Value of <em>what</em></th>
<th class="head">Meaning of <em>arg</em></th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="xref py py-const docutils literal notranslate"><span class="pre">PyTrace_CALL</span></code></td>
<td>Always <a class="reference internal" href="none.html#c.Py_None" title="Py_None"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_None</span></code></a>.</td>
</tr>
<tr class="row-odd"><td><code class="xref py py-const docutils literal notranslate"><span class="pre">PyTrace_EXCEPTION</span></code></td>
<td>Exception information as returned by
<a class="reference internal" href="../library/sys.html#sys.exc_info" title="sys.exc_info"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.exc_info()</span></code></a>.</td>
</tr>
<tr class="row-even"><td><code class="xref py py-const docutils literal notranslate"><span class="pre">PyTrace_LINE</span></code></td>
<td>Always <a class="reference internal" href="none.html#c.Py_None" title="Py_None"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_None</span></code></a>.</td>
</tr>
<tr class="row-odd"><td><code class="xref py py-const docutils literal notranslate"><span class="pre">PyTrace_RETURN</span></code></td>
<td>Value being returned to the caller,
or <em>NULL</em> if caused by an exception.</td>
</tr>
<tr class="row-even"><td><code class="xref py py-const docutils literal notranslate"><span class="pre">PyTrace_C_CALL</span></code></td>
<td>Function object being called.</td>
</tr>
<tr class="row-odd"><td><code class="xref py py-const docutils literal notranslate"><span class="pre">PyTrace_C_EXCEPTION</span></code></td>
<td>Function object being called.</td>
</tr>
<tr class="row-even"><td><code class="xref py py-const docutils literal notranslate"><span class="pre">PyTrace_C_RETURN</span></code></td>
<td>Function object being called.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="var">
<dt id="c.PyTrace_CALL">
int <code class="descname">PyTrace_CALL</code><a class="headerlink" href="#c.PyTrace_CALL" title="Permalink to this definition">¶</a></dt>
<dd><p>The value of the <em>what</em> parameter to a <a class="reference internal" href="#c.Py_tracefunc" title="Py_tracefunc"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_tracefunc</span></code></a> function when a new
call to a function or method is being reported, or a new entry into a generator.
Note that the creation of the iterator for a generator function is not reported
as there is no control transfer to the Python bytecode in the corresponding
frame.</p>
</dd></dl>
<dl class="var">
<dt id="c.PyTrace_EXCEPTION">
int <code class="descname">PyTrace_EXCEPTION</code><a class="headerlink" href="#c.PyTrace_EXCEPTION" title="Permalink to this definition">¶</a></dt>
<dd><p>The value of the <em>what</em> parameter to a <a class="reference internal" href="#c.Py_tracefunc" title="Py_tracefunc"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_tracefunc</span></code></a> function when an
exception has been raised. The callback function is called with this value for
<em>what</em> when after any bytecode is processed after which the exception becomes
set within the frame being executed. The effect of this is that as exception
propagation causes the Python stack to unwind, the callback is called upon
return to each frame as the exception propagates. Only trace functions receives
these events; they are not needed by the profiler.</p>
</dd></dl>
<dl class="var">
<dt id="c.PyTrace_LINE">
int <code class="descname">PyTrace_LINE</code><a class="headerlink" href="#c.PyTrace_LINE" title="Permalink to this definition">¶</a></dt>
<dd><p>The value passed as the <em>what</em> parameter to a trace function (but not a
profiling function) when a line-number event is being reported.</p>
</dd></dl>
<dl class="var">
<dt id="c.PyTrace_RETURN">
int <code class="descname">PyTrace_RETURN</code><a class="headerlink" href="#c.PyTrace_RETURN" title="Permalink to this definition">¶</a></dt>
<dd><p>The value for the <em>what</em> parameter to <a class="reference internal" href="#c.Py_tracefunc" title="Py_tracefunc"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_tracefunc</span></code></a> functions when a
call is about to return.</p>
</dd></dl>
<dl class="var">
<dt id="c.PyTrace_C_CALL">
int <code class="descname">PyTrace_C_CALL</code><a class="headerlink" href="#c.PyTrace_C_CALL" title="Permalink to this definition">¶</a></dt>
<dd><p>The value for the <em>what</em> parameter to <a class="reference internal" href="#c.Py_tracefunc" title="Py_tracefunc"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_tracefunc</span></code></a> functions when a C
function is about to be called.</p>
</dd></dl>
<dl class="var">
<dt id="c.PyTrace_C_EXCEPTION">
int <code class="descname">PyTrace_C_EXCEPTION</code><a class="headerlink" href="#c.PyTrace_C_EXCEPTION" title="Permalink to this definition">¶</a></dt>
<dd><p>The value for the <em>what</em> parameter to <a class="reference internal" href="#c.Py_tracefunc" title="Py_tracefunc"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_tracefunc</span></code></a> functions when a C
function has raised an exception.</p>
</dd></dl>
<dl class="var">
<dt id="c.PyTrace_C_RETURN">
int <code class="descname">PyTrace_C_RETURN</code><a class="headerlink" href="#c.PyTrace_C_RETURN" title="Permalink to this definition">¶</a></dt>
<dd><p>The value for the <em>what</em> parameter to <a class="reference internal" href="#c.Py_tracefunc" title="Py_tracefunc"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_tracefunc</span></code></a> functions when a C
function has returned.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyEval_SetProfile">
void <code class="descname">PyEval_SetProfile</code><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_tracefunc" title="Py_tracefunc">Py_tracefunc</a><em> func</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *obj</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyEval_SetProfile" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the profiler function to <em>func</em>. The <em>obj</em> parameter is passed to the
function as its first parameter, and may be any Python object, or <em>NULL</em>. If
the profile function needs to maintain state, using a different value for <em>obj</em>
for each thread provides a convenient and thread-safe place to store it. The
profile function is called for all monitored events except <code class="xref py py-const docutils literal notranslate"><span class="pre">PyTrace_LINE</span></code>
and <code class="xref py py-const docutils literal notranslate"><span class="pre">PyTrace_EXCEPTION</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyEval_SetTrace">
void <code class="descname">PyEval_SetTrace</code><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_tracefunc" title="Py_tracefunc">Py_tracefunc</a><em> func</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *obj</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyEval_SetTrace" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the tracing function to <em>func</em>. This is similar to
<a class="reference internal" href="#c.PyEval_SetProfile" title="PyEval_SetProfile"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyEval_SetProfile()</span></code></a>, except the tracing function does receive line-number
events and does not receive any event related to C function objects being called. Any
trace function registered using <a class="reference internal" href="#c.PyEval_SetTrace" title="PyEval_SetTrace"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyEval_SetTrace()</span></code></a> will not receive
<code class="xref py py-const docutils literal notranslate"><span class="pre">PyTrace_C_CALL</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">PyTrace_C_EXCEPTION</span></code> or <code class="xref py py-const docutils literal notranslate"><span class="pre">PyTrace_C_RETURN</span></code>
as a value for the <em>what</em> parameter.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyEval_GetCallStats">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyEval_GetCallStats</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *self</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyEval_GetCallStats" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a tuple of function call counts. There are constants defined for the
positions within the tuple:</p>
<table border="1" class="docutils">
<colgroup>
<col width="82%" />
<col width="18%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Name</th>
<th class="head">Value</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="xref py py-const docutils literal notranslate"><span class="pre">PCALL_ALL</span></code></td>
<td>0</td>
</tr>
<tr class="row-odd"><td><code class="xref py py-const docutils literal notranslate"><span class="pre">PCALL_FUNCTION</span></code></td>
<td>1</td>
</tr>
<tr class="row-even"><td><code class="xref py py-const docutils literal notranslate"><span class="pre">PCALL_FAST_FUNCTION</span></code></td>
<td>2</td>
</tr>
<tr class="row-odd"><td><code class="xref py py-const docutils literal notranslate"><span class="pre">PCALL_FASTER_FUNCTION</span></code></td>
<td>3</td>
</tr>
<tr class="row-even"><td><code class="xref py py-const docutils literal notranslate"><span class="pre">PCALL_METHOD</span></code></td>
<td>4</td>
</tr>
<tr class="row-odd"><td><code class="xref py py-const docutils literal notranslate"><span class="pre">PCALL_BOUND_METHOD</span></code></td>
<td>5</td>
</tr>
<tr class="row-even"><td><code class="xref py py-const docutils literal notranslate"><span class="pre">PCALL_CFUNCTION</span></code></td>
<td>6</td>
</tr>
<tr class="row-odd"><td><code class="xref py py-const docutils literal notranslate"><span class="pre">PCALL_TYPE</span></code></td>
<td>7</td>
</tr>
<tr class="row-even"><td><code class="xref py py-const docutils literal notranslate"><span class="pre">PCALL_GENERATOR</span></code></td>
<td>8</td>
</tr>
<tr class="row-odd"><td><code class="xref py py-const docutils literal notranslate"><span class="pre">PCALL_OTHER</span></code></td>
<td>9</td>
</tr>
<tr class="row-even"><td><code class="xref py py-const docutils literal notranslate"><span class="pre">PCALL_POP</span></code></td>
<td>10</td>
</tr>
</tbody>
</table>
<p><code class="xref py py-const docutils literal notranslate"><span class="pre">PCALL_FAST_FUNCTION</span></code> means no argument tuple needs to be created.
<code class="xref py py-const docutils literal notranslate"><span class="pre">PCALL_FASTER_FUNCTION</span></code> means that the fast-path frame setup code is used.</p>
<p>If there is a method call where the call can be optimized by changing
the argument tuple and calling the function directly, it gets recorded
twice.</p>
<p>This function is only present if Python is compiled with <code class="xref py py-const docutils literal notranslate"><span class="pre">CALL_PROFILE</span></code>
defined.</p>
</dd></dl>
</div>
<div class="section" id="advanced-debugger-support">
<span id="advanced-debugging"></span><h2>Advanced Debugger Support<a class="headerlink" href="#advanced-debugger-support" title="Permalink to this headline">¶</a></h2>
<p>These functions are only intended to be used by advanced debugging tools.</p>
<dl class="function">
<dt id="c.PyInterpreterState_Head">
<a class="reference internal" href="#c.PyInterpreterState" title="PyInterpreterState">PyInterpreterState</a>* <code class="descname">PyInterpreterState_Head</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyInterpreterState_Head" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the interpreter state object at the head of the list of all such objects.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyInterpreterState_Next">
<a class="reference internal" href="#c.PyInterpreterState" title="PyInterpreterState">PyInterpreterState</a>* <code class="descname">PyInterpreterState_Next</code><span class="sig-paren">(</span><a class="reference internal" href="#c.PyInterpreterState" title="PyInterpreterState">PyInterpreterState</a><em> *interp</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyInterpreterState_Next" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the next interpreter state object after <em>interp</em> from the list of all
such objects.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyInterpreterState_ThreadHead">
<a class="reference internal" href="#c.PyThreadState" title="PyThreadState">PyThreadState</a> * <code class="descname">PyInterpreterState_ThreadHead</code><span class="sig-paren">(</span><a class="reference internal" href="#c.PyInterpreterState" title="PyInterpreterState">PyInterpreterState</a><em> *interp</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyInterpreterState_ThreadHead" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the pointer to the first <a class="reference internal" href="#c.PyThreadState" title="PyThreadState"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyThreadState</span></code></a> object in the list of
threads associated with the interpreter <em>interp</em>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyThreadState_Next">
<a class="reference internal" href="#c.PyThreadState" title="PyThreadState">PyThreadState</a>* <code class="descname">PyThreadState_Next</code><span class="sig-paren">(</span><a class="reference internal" href="#c.PyThreadState" title="PyThreadState">PyThreadState</a><em> *tstate</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyThreadState_Next" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the next thread state object after <em>tstate</em> from the list of all such
objects belonging to the same <a class="reference internal" href="#c.PyInterpreterState" title="PyInterpreterState"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyInterpreterState</span></code></a> object.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Initialization, Finalization, and Threads</a><ul>
<li><a class="reference internal" href="#initializing-and-finalizing-the-interpreter">Initializing and finalizing the interpreter</a></li>
<li><a class="reference internal" href="#process-wide-parameters">Process-wide parameters</a></li>
<li><a class="reference internal" href="#thread-state-and-the-global-interpreter-lock">Thread State and the Global Interpreter Lock</a><ul>
<li><a class="reference internal" href="#releasing-the-gil-from-extension-code">Releasing the GIL from extension code</a></li>
<li><a class="reference internal" href="#non-python-created-threads">Non-Python created threads</a></li>
<li><a class="reference internal" href="#high-level-api">High-level API</a></li>
<li><a class="reference internal" href="#low-level-api">Low-level API</a></li>
</ul>
</li>
<li><a class="reference internal" href="#sub-interpreter-support">Sub-interpreter support</a><ul>
<li><a class="reference internal" href="#bugs-and-caveats">Bugs and caveats</a></li>
</ul>
</li>
<li><a class="reference internal" href="#asynchronous-notifications">Asynchronous Notifications</a></li>
<li><a class="reference internal" href="#profiling-and-tracing">Profiling and Tracing</a></li>
<li><a class="reference internal" href="#advanced-debugger-support">Advanced Debugger Support</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="code.html"
title="previous chapter">Code Objects</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="memory.html"
title="next chapter">Memory Management</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/init.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="memory.html" title="Memory Management"
>next</a> |</li>
<li class="right" >
<a href="code.html" title="Code Objects"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\#*9l0P 0P html/c-api/int.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Plain Integer Objects — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Boolean Objects" href="bool.html" />
<link rel="prev" title="The None Object" href="none.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/int.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="bool.html" title="Boolean Objects"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="none.html" title="The None Object"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" accesskey="U">Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="plain-integer-objects">
<span id="intobjects"></span><h1>Plain Integer Objects<a class="headerlink" href="#plain-integer-objects" title="Permalink to this headline">¶</a></h1>
<span class="target" id="index-0"></span><dl class="type">
<dt id="c.PyIntObject">
<code class="descname">PyIntObject</code><a class="headerlink" href="#c.PyIntObject" title="Permalink to this definition">¶</a></dt>
<dd><p>This subtype of <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject</span></code></a> represents a Python integer object.</p>
</dd></dl>
<dl class="var">
<dt id="c.PyInt_Type">
<a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a> <code class="descname">PyInt_Type</code><a class="headerlink" href="#c.PyInt_Type" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-1">This instance of <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyTypeObject</span></code></a> represents the Python plain integer type.
This is the same object as <code class="docutils literal notranslate"><span class="pre">int</span></code> and <code class="docutils literal notranslate"><span class="pre">types.IntType</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyInt_Check">
int <code class="descname">PyInt_Check</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyInt_Check" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if <em>o</em> is of type <a class="reference internal" href="#c.PyInt_Type" title="PyInt_Type"><code class="xref c c-data docutils literal notranslate"><span class="pre">PyInt_Type</span></code></a> or a subtype of
<a class="reference internal" href="#c.PyInt_Type" title="PyInt_Type"><code class="xref c c-data docutils literal notranslate"><span class="pre">PyInt_Type</span></code></a>.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.2: </span>Allowed subtypes to be accepted.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyInt_CheckExact">
int <code class="descname">PyInt_CheckExact</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyInt_CheckExact" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if <em>o</em> is of type <a class="reference internal" href="#c.PyInt_Type" title="PyInt_Type"><code class="xref c c-data docutils literal notranslate"><span class="pre">PyInt_Type</span></code></a>, but not a subtype of
<a class="reference internal" href="#c.PyInt_Type" title="PyInt_Type"><code class="xref c c-data docutils literal notranslate"><span class="pre">PyInt_Type</span></code></a>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyInt_FromString">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyInt_FromString</code><span class="sig-paren">(</span>char<em> *str</em>, char<em> **pend</em>, int<em> base</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyInt_FromString" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a new <a class="reference internal" href="#c.PyIntObject" title="PyIntObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyIntObject</span></code></a> or <a class="reference internal" href="long.html#c.PyLongObject" title="PyLongObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyLongObject</span></code></a> based on the string
value in <em>str</em>, which is interpreted according to the radix in <em>base</em>. If
<em>pend</em> is non-<em>NULL</em>, <code class="docutils literal notranslate"><span class="pre">*pend</span></code> will point to the first character in <em>str</em> which
follows the representation of the number. If <em>base</em> is <code class="docutils literal notranslate"><span class="pre">0</span></code>, the radix will be
determined based on the leading characters of <em>str</em>: if <em>str</em> starts with
<code class="docutils literal notranslate"><span class="pre">'0x'</span></code> or <code class="docutils literal notranslate"><span class="pre">'0X'</span></code>, radix 16 will be used; if <em>str</em> starts with <code class="docutils literal notranslate"><span class="pre">'0'</span></code>, radix
8 will be used; otherwise radix 10 will be used. If <em>base</em> is not <code class="docutils literal notranslate"><span class="pre">0</span></code>, it
must be between <code class="docutils literal notranslate"><span class="pre">2</span></code> and <code class="docutils literal notranslate"><span class="pre">36</span></code>, inclusive. Leading spaces are ignored. If
there are no digits, <a class="reference internal" href="../library/exceptions.html#exceptions.ValueError" title="exceptions.ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> will be raised. If the string represents
a number too large to be contained within the machine’s <code class="xref c c-type docutils literal notranslate"><span class="pre">long</span> <span class="pre">int</span></code> type
and overflow warnings are being suppressed, a <a class="reference internal" href="long.html#c.PyLongObject" title="PyLongObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyLongObject</span></code></a> will be
returned. If overflow warnings are not being suppressed, <em>NULL</em> will be
returned in this case.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyInt_FromLong">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyInt_FromLong</code><span class="sig-paren">(</span>long<em> ival</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyInt_FromLong" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Create a new integer object with a value of <em>ival</em>.</p>
<p>The current implementation keeps an array of integer objects for all integers
between <code class="docutils literal notranslate"><span class="pre">-5</span></code> and <code class="docutils literal notranslate"><span class="pre">256</span></code>, when you create an int in that range you actually
just get back a reference to the existing object. So it should be possible to
change the value of <code class="docutils literal notranslate"><span class="pre">1</span></code>. I suspect the behaviour of Python in this case is
undefined. :-)</p>
</dd></dl>
<dl class="function">
<dt id="c.PyInt_FromSsize_t">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyInt_FromSsize_t</code><span class="sig-paren">(</span>Py_ssize_t<em> ival</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyInt_FromSsize_t" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Create a new integer object with a value of <em>ival</em>. If the value is larger
than <code class="docutils literal notranslate"><span class="pre">LONG_MAX</span></code> or smaller than <code class="docutils literal notranslate"><span class="pre">LONG_MIN</span></code>, a long integer object is
returned.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.5.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyInt_FromSize_t">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyInt_FromSize_t</code><span class="sig-paren">(</span>size_t<em> ival</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyInt_FromSize_t" title="Permalink to this definition">¶</a></dt>
<dd><p>Create a new integer object with a value of <em>ival</em>. If the value exceeds
<code class="docutils literal notranslate"><span class="pre">LONG_MAX</span></code>, a long integer object is returned.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.5.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyInt_AsLong">
long <code class="descname">PyInt_AsLong</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *io</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyInt_AsLong" title="Permalink to this definition">¶</a></dt>
<dd><p>Will first attempt to cast the object to a <a class="reference internal" href="#c.PyIntObject" title="PyIntObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyIntObject</span></code></a>, if it is not
already one, and then return its value. If there is an error, <code class="docutils literal notranslate"><span class="pre">-1</span></code> is
returned, and the caller should check <code class="docutils literal notranslate"><span class="pre">PyErr_Occurred()</span></code> to find out whether
there was an error, or whether the value just happened to be <code class="docutils literal notranslate"><span class="pre">-1</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyInt_AS_LONG">
long <code class="descname">PyInt_AS_LONG</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *io</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyInt_AS_LONG" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the value of the object <em>io</em>. No error checking is performed.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyInt_AsUnsignedLongMask">
unsigned long <code class="descname">PyInt_AsUnsignedLongMask</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *io</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyInt_AsUnsignedLongMask" title="Permalink to this definition">¶</a></dt>
<dd><p>Will first attempt to cast the object to a <a class="reference internal" href="#c.PyIntObject" title="PyIntObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyIntObject</span></code></a> or
<a class="reference internal" href="long.html#c.PyLongObject" title="PyLongObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyLongObject</span></code></a>, if it is not already one, and then return its value as
unsigned long. This function does not check for overflow.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.3.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyInt_AsUnsignedLongLongMask">
unsigned PY_LONG_LONG <code class="descname">PyInt_AsUnsignedLongLongMask</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *io</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyInt_AsUnsignedLongLongMask" title="Permalink to this definition">¶</a></dt>
<dd><p>Will first attempt to cast the object to a <a class="reference internal" href="#c.PyIntObject" title="PyIntObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyIntObject</span></code></a> or
<a class="reference internal" href="long.html#c.PyLongObject" title="PyLongObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyLongObject</span></code></a>, if it is not already one, and then return its value as
unsigned long long, without checking for overflow.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.3.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyInt_AsSsize_t">
Py_ssize_t <code class="descname">PyInt_AsSsize_t</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *io</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyInt_AsSsize_t" title="Permalink to this definition">¶</a></dt>
<dd><p>Will first attempt to cast the object to a <a class="reference internal" href="#c.PyIntObject" title="PyIntObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyIntObject</span></code></a> or
<a class="reference internal" href="long.html#c.PyLongObject" title="PyLongObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyLongObject</span></code></a>, if it is not already one, and then return its value as
<code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.5.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyInt_GetMax">
long <code class="descname">PyInt_GetMax</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyInt_GetMax" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-2">Return the system’s idea of the largest integer it can handle
(<code class="xref py py-const docutils literal notranslate"><span class="pre">LONG_MAX</span></code>, as defined in the system header files).</p>
</dd></dl>
<dl class="function">
<dt id="c.PyInt_ClearFreeList">
int <code class="descname">PyInt_ClearFreeList</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyInt_ClearFreeList" title="Permalink to this definition">¶</a></dt>
<dd><p>Clear the integer free list. Return the number of items that could not
be freed.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="none.html"
title="previous chapter">The <code class="docutils literal notranslate"><span class="pre">None</span></code> Object</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="bool.html"
title="next chapter">Boolean Objects</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/int.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="bool.html" title="Boolean Objects"
>next</a> |</li>
<li class="right" >
<a href="none.html" title="The None Object"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" >Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\��A�� � html/c-api/intro.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Introduction — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="The Very High Level Layer" href="veryhigh.html" />
<link rel="prev" title="Python/C API Reference Manual" href="index.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/intro.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="veryhigh.html" title="The Very High Level Layer"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="index.html" title="Python/C API Reference Manual"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Python/C API Reference Manual</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="introduction">
<span id="api-intro"></span><h1>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h1>
<p>The Application Programmer’s Interface to Python gives C and C++ programmers
access to the Python interpreter at a variety of levels. The API is equally
usable from C++, but for brevity it is generally referred to as the Python/C
API. There are two fundamentally different reasons for using the Python/C API.
The first reason is to write <em>extension modules</em> for specific purposes; these
are C modules that extend the Python interpreter. This is probably the most
common use. The second reason is to use Python as a component in a larger
application; this technique is generally referred to as <em class="dfn">embedding</em> Python
in an application.</p>
<p>Writing an extension module is a relatively well-understood process, where a
“cookbook” approach works well. There are several tools that automate the
process to some extent. While people have embedded Python in other
applications since its early existence, the process of embedding Python is less
straightforward than writing an extension.</p>
<p>Many API functions are useful independent of whether you’re embedding or
extending Python; moreover, most applications that embed Python will need to
provide a custom extension as well, so it’s probably a good idea to become
familiar with writing an extension before attempting to embed Python in a real
application.</p>
<div class="section" id="include-files">
<span id="api-includes"></span><h2>Include Files<a class="headerlink" href="#include-files" title="Permalink to this headline">¶</a></h2>
<p>All function, type and macro definitions needed to use the Python/C API are
included in your code by the following line:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cp">#include</span> <span class="cpf">"Python.h"</span><span class="cp"></span>
</pre></div>
</div>
<p>This implies inclusion of the following standard headers: <code class="docutils literal notranslate"><span class="pre"><stdio.h></span></code>,
<code class="docutils literal notranslate"><span class="pre"><string.h></span></code>, <code class="docutils literal notranslate"><span class="pre"><errno.h></span></code>, <code class="docutils literal notranslate"><span class="pre"><limits.h></span></code>, <code class="docutils literal notranslate"><span class="pre"><assert.h></span></code> and <code class="docutils literal notranslate"><span class="pre"><stdlib.h></span></code>
(if available).</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Since Python may define some pre-processor definitions which affect the standard
headers on some systems, you <em>must</em> include <code class="file docutils literal notranslate"><span class="pre">Python.h</span></code> before any standard
headers are included.</p>
</div>
<p>All user visible names defined by Python.h (except those defined by the included
standard headers) have one of the prefixes <code class="docutils literal notranslate"><span class="pre">Py</span></code> or <code class="docutils literal notranslate"><span class="pre">_Py</span></code>. Names beginning
with <code class="docutils literal notranslate"><span class="pre">_Py</span></code> are for internal use by the Python implementation and should not be
used by extension writers. Structure member names do not have a reserved prefix.</p>
<p><strong>Important:</strong> user code should never define names that begin with <code class="docutils literal notranslate"><span class="pre">Py</span></code> or
<code class="docutils literal notranslate"><span class="pre">_Py</span></code>. This confuses the reader, and jeopardizes the portability of the user
code to future Python versions, which may define additional names beginning with
one of these prefixes.</p>
<p>The header files are typically installed with Python. On Unix, these are
located in the directories <code class="file docutils literal notranslate"><em><span class="pre">prefix</span></em><span class="pre">/include/pythonversion/</span></code> and
<code class="file docutils literal notranslate"><em><span class="pre">exec_prefix</span></em><span class="pre">/include/pythonversion/</span></code>, where <span class="target" id="index-0"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">prefix</span></code> and
<span class="target" id="index-1"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">exec_prefix</span></code> are defined by the corresponding parameters to Python’s
<strong class="program">configure</strong> script and <em>version</em> is <code class="docutils literal notranslate"><span class="pre">sys.version[:3]</span></code>. On Windows,
the headers are installed in <code class="file docutils literal notranslate"><em><span class="pre">prefix</span></em><span class="pre">/include</span></code>, where <span class="target" id="index-2"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">prefix</span></code> is
the installation directory specified to the installer.</p>
<p>To include the headers, place both directories (if different) on your compiler’s
search path for includes. Do <em>not</em> place the parent directories on the search
path and then use <code class="docutils literal notranslate"><span class="pre">#include</span> <span class="pre"><pythonX.Y/Python.h></span></code>; this will break on
multi-platform builds since the platform independent headers under
<span class="target" id="index-3"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">prefix</span></code> include the platform specific headers from
<span class="target" id="index-4"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">exec_prefix</span></code>.</p>
<p>C++ users should note that though the API is defined entirely using C, the
header files do properly declare the entry points to be <code class="docutils literal notranslate"><span class="pre">extern</span> <span class="pre">"C"</span></code>, so there
is no need to do anything special to use the API from C++.</p>
</div>
<div class="section" id="objects-types-and-reference-counts">
<span id="api-objects"></span><h2>Objects, Types and Reference Counts<a class="headerlink" href="#objects-types-and-reference-counts" title="Permalink to this headline">¶</a></h2>
<p id="index-5">Most Python/C API functions have one or more arguments as well as a return value
of type <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject*</span></code></a>. This type is a pointer to an opaque data type
representing an arbitrary Python object. Since all Python object types are
treated the same way by the Python language in most situations (e.g.,
assignments, scope rules, and argument passing), it is only fitting that they
should be represented by a single C type. Almost all Python objects live on the
heap: you never declare an automatic or static variable of type
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject</span></code></a>, only pointer variables of type <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject*</span></code></a> can be
declared. The sole exception are the type objects; since these must never be
deallocated, they are typically static <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyTypeObject</span></code></a> objects.</p>
<p>All Python objects (even Python integers) have a <em class="dfn">type</em> and a
<em class="dfn">reference count</em>. An object’s type determines what kind of object it is
(e.g., an integer, a list, or a user-defined function; there are many more as
explained in <a class="reference internal" href="../reference/datamodel.html#types"><span class="std std-ref">The standard type hierarchy</span></a>). For each of the well-known types there is a macro
to check whether an object is of that type; for instance, <code class="docutils literal notranslate"><span class="pre">PyList_Check(a)</span></code> is
true if (and only if) the object pointed to by <em>a</em> is a Python list.</p>
<div class="section" id="reference-counts">
<span id="api-refcounts"></span><h3>Reference Counts<a class="headerlink" href="#reference-counts" title="Permalink to this headline">¶</a></h3>
<p>The reference count is important because today’s computers have a finite (and
often severely limited) memory size; it counts how many different places there
are that have a reference to an object. Such a place could be another object,
or a global (or static) C variable, or a local variable in some C function.
When an object’s reference count becomes zero, the object is deallocated. If
it contains references to other objects, their reference count is decremented.
Those other objects may be deallocated in turn, if this decrement makes their
reference count become zero, and so on. (There’s an obvious problem with
objects that reference each other here; for now, the solution is “don’t do
that.”)</p>
<p id="index-6">Reference counts are always manipulated explicitly. The normal way is to use
the macro <a class="reference internal" href="refcounting.html#c.Py_INCREF" title="Py_INCREF"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_INCREF()</span></code></a> to increment an object’s reference count by one,
and <a class="reference internal" href="refcounting.html#c.Py_DECREF" title="Py_DECREF"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_DECREF()</span></code></a> to decrement it by one. The <a class="reference internal" href="refcounting.html#c.Py_DECREF" title="Py_DECREF"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_DECREF()</span></code></a> macro
is considerably more complex than the incref one, since it must check whether
the reference count becomes zero and then cause the object’s deallocator to be
called. The deallocator is a function pointer contained in the object’s type
structure. The type-specific deallocator takes care of decrementing the
reference counts for other objects contained in the object if this is a compound
object type, such as a list, as well as performing any additional finalization
that’s needed. There’s no chance that the reference count can overflow; at
least as many bits are used to hold the reference count as there are distinct
memory locations in virtual memory (assuming <code class="docutils literal notranslate"><span class="pre">sizeof(Py_ssize_t)</span> <span class="pre">>=</span> <span class="pre">sizeof(void*)</span></code>).
Thus, the reference count increment is a simple operation.</p>
<p>It is not necessary to increment an object’s reference count for every local
variable that contains a pointer to an object. In theory, the object’s
reference count goes up by one when the variable is made to point to it and it
goes down by one when the variable goes out of scope. However, these two
cancel each other out, so at the end the reference count hasn’t changed. The
only real reason to use the reference count is to prevent the object from being
deallocated as long as our variable is pointing to it. If we know that there
is at least one other reference to the object that lives at least as long as
our variable, there is no need to increment the reference count temporarily.
An important situation where this arises is in objects that are passed as
arguments to C functions in an extension module that are called from Python;
the call mechanism guarantees to hold a reference to every argument for the
duration of the call.</p>
<p>However, a common pitfall is to extract an object from a list and hold on to it
for a while without incrementing its reference count. Some other operation might
conceivably remove the object from the list, decrementing its reference count
and possible deallocating it. The real danger is that innocent-looking
operations may invoke arbitrary Python code which could do this; there is a code
path which allows control to flow back to the user from a <a class="reference internal" href="refcounting.html#c.Py_DECREF" title="Py_DECREF"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_DECREF()</span></code></a>, so
almost any operation is potentially dangerous.</p>
<p>A safe approach is to always use the generic operations (functions whose name
begins with <code class="docutils literal notranslate"><span class="pre">PyObject_</span></code>, <code class="docutils literal notranslate"><span class="pre">PyNumber_</span></code>, <code class="docutils literal notranslate"><span class="pre">PySequence_</span></code> or <code class="docutils literal notranslate"><span class="pre">PyMapping_</span></code>).
These operations always increment the reference count of the object they return.
This leaves the caller with the responsibility to call <a class="reference internal" href="refcounting.html#c.Py_DECREF" title="Py_DECREF"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_DECREF()</span></code></a> when
they are done with the result; this soon becomes second nature.</p>
<div class="section" id="reference-count-details">
<span id="api-refcountdetails"></span><h4>Reference Count Details<a class="headerlink" href="#reference-count-details" title="Permalink to this headline">¶</a></h4>
<p>The reference count behavior of functions in the Python/C API is best explained
in terms of <em>ownership of references</em>. Ownership pertains to references, never
to objects (objects are not owned: they are always shared). “Owning a
reference” means being responsible for calling Py_DECREF on it when the
reference is no longer needed. Ownership can also be transferred, meaning that
the code that receives ownership of the reference then becomes responsible for
eventually decref’ing it by calling <a class="reference internal" href="refcounting.html#c.Py_DECREF" title="Py_DECREF"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_DECREF()</span></code></a> or <a class="reference internal" href="refcounting.html#c.Py_XDECREF" title="Py_XDECREF"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_XDECREF()</span></code></a>
when it’s no longer needed—or passing on this responsibility (usually to its
caller). When a function passes ownership of a reference on to its caller, the
caller is said to receive a <em>new</em> reference. When no ownership is transferred,
the caller is said to <em>borrow</em> the reference. Nothing needs to be done for a
borrowed reference.</p>
<p>Conversely, when a calling function passes in a reference to an object, there
are two possibilities: the function <em>steals</em> a reference to the object, or it
does not. <em>Stealing a reference</em> means that when you pass a reference to a
function, that function assumes that it now owns that reference, and you are not
responsible for it any longer.</p>
<p id="index-7">Few functions steal references; the two notable exceptions are
<a class="reference internal" href="list.html#c.PyList_SetItem" title="PyList_SetItem"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyList_SetItem()</span></code></a> and <a class="reference internal" href="tuple.html#c.PyTuple_SetItem" title="PyTuple_SetItem"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyTuple_SetItem()</span></code></a>, which steal a reference
to the item (but not to the tuple or list into which the item is put!). These
functions were designed to steal a reference because of a common idiom for
populating a tuple or list with newly created objects; for example, the code to
create the tuple <code class="docutils literal notranslate"><span class="pre">(1,</span> <span class="pre">2,</span> <span class="pre">"three")</span></code> could look like this (forgetting about
error handling for the moment; a better way to code this is shown below):</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">PyObject</span> <span class="o">*</span><span class="n">t</span><span class="p">;</span>
<span class="n">t</span> <span class="o">=</span> <span class="n">PyTuple_New</span><span class="p">(</span><span class="mi">3</span><span class="p">);</span>
<span class="n">PyTuple_SetItem</span><span class="p">(</span><span class="n">t</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="n">PyInt_FromLong</span><span class="p">(</span><span class="mi">1L</span><span class="p">));</span>
<span class="n">PyTuple_SetItem</span><span class="p">(</span><span class="n">t</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">PyInt_FromLong</span><span class="p">(</span><span class="mi">2L</span><span class="p">));</span>
<span class="n">PyTuple_SetItem</span><span class="p">(</span><span class="n">t</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="n">PyString_FromString</span><span class="p">(</span><span class="s">"three"</span><span class="p">));</span>
</pre></div>
</div>
<p>Here, <a class="reference internal" href="int.html#c.PyInt_FromLong" title="PyInt_FromLong"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyInt_FromLong()</span></code></a> returns a new reference which is immediately
stolen by <a class="reference internal" href="tuple.html#c.PyTuple_SetItem" title="PyTuple_SetItem"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyTuple_SetItem()</span></code></a>. When you want to keep using an object
although the reference to it will be stolen, use <a class="reference internal" href="refcounting.html#c.Py_INCREF" title="Py_INCREF"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_INCREF()</span></code></a> to grab
another reference before calling the reference-stealing function.</p>
<p>Incidentally, <a class="reference internal" href="tuple.html#c.PyTuple_SetItem" title="PyTuple_SetItem"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyTuple_SetItem()</span></code></a> is the <em>only</em> way to set tuple items;
<a class="reference internal" href="sequence.html#c.PySequence_SetItem" title="PySequence_SetItem"><code class="xref c c-func docutils literal notranslate"><span class="pre">PySequence_SetItem()</span></code></a> and <a class="reference internal" href="object.html#c.PyObject_SetItem" title="PyObject_SetItem"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_SetItem()</span></code></a> refuse to do this
since tuples are an immutable data type. You should only use
<a class="reference internal" href="tuple.html#c.PyTuple_SetItem" title="PyTuple_SetItem"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyTuple_SetItem()</span></code></a> for tuples that you are creating yourself.</p>
<p>Equivalent code for populating a list can be written using <a class="reference internal" href="list.html#c.PyList_New" title="PyList_New"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyList_New()</span></code></a>
and <a class="reference internal" href="list.html#c.PyList_SetItem" title="PyList_SetItem"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyList_SetItem()</span></code></a>.</p>
<p>However, in practice, you will rarely use these ways of creating and populating
a tuple or list. There’s a generic function, <a class="reference internal" href="arg.html#c.Py_BuildValue" title="Py_BuildValue"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_BuildValue()</span></code></a>, that can
create most common objects from C values, directed by a <em class="dfn">format string</em>.
For example, the above two blocks of code could be replaced by the following
(which also takes care of the error checking):</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">PyObject</span> <span class="o">*</span><span class="n">tuple</span><span class="p">,</span> <span class="o">*</span><span class="n">list</span><span class="p">;</span>
<span class="n">tuple</span> <span class="o">=</span> <span class="n">Py_BuildValue</span><span class="p">(</span><span class="s">"(iis)"</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="s">"three"</span><span class="p">);</span>
<span class="n">list</span> <span class="o">=</span> <span class="n">Py_BuildValue</span><span class="p">(</span><span class="s">"[iis]"</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="s">"three"</span><span class="p">);</span>
</pre></div>
</div>
<p>It is much more common to use <a class="reference internal" href="object.html#c.PyObject_SetItem" title="PyObject_SetItem"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_SetItem()</span></code></a> and friends with items
whose references you are only borrowing, like arguments that were passed in to
the function you are writing. In that case, their behaviour regarding reference
counts is much saner, since you don’t have to increment a reference count so you
can give a reference away (“have it be stolen”). For example, this function
sets all items of a list (actually, any mutable sequence) to a given item:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span>
<span class="nf">set_all</span><span class="p">(</span><span class="n">PyObject</span> <span class="o">*</span><span class="n">target</span><span class="p">,</span> <span class="n">PyObject</span> <span class="o">*</span><span class="n">item</span><span class="p">)</span>
<span class="p">{</span>
<span class="kt">int</span> <span class="n">i</span><span class="p">,</span> <span class="n">n</span><span class="p">;</span>
<span class="n">n</span> <span class="o">=</span> <span class="n">PyObject_Length</span><span class="p">(</span><span class="n">target</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">n</span> <span class="o"><</span> <span class="mi">0</span><span class="p">)</span>
<span class="k">return</span> <span class="o">-</span><span class="mi">1</span><span class="p">;</span>
<span class="k">for</span> <span class="p">(</span><span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">n</span><span class="p">;</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span> <span class="p">{</span>
<span class="n">PyObject</span> <span class="o">*</span><span class="n">index</span> <span class="o">=</span> <span class="n">PyInt_FromLong</span><span class="p">(</span><span class="n">i</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">index</span><span class="p">)</span>
<span class="k">return</span> <span class="o">-</span><span class="mi">1</span><span class="p">;</span>
<span class="k">if</span> <span class="p">(</span><span class="n">PyObject_SetItem</span><span class="p">(</span><span class="n">target</span><span class="p">,</span> <span class="n">index</span><span class="p">,</span> <span class="n">item</span><span class="p">)</span> <span class="o"><</span> <span class="mi">0</span><span class="p">)</span> <span class="p">{</span>
<span class="n">Py_DECREF</span><span class="p">(</span><span class="n">index</span><span class="p">);</span>
<span class="k">return</span> <span class="o">-</span><span class="mi">1</span><span class="p">;</span>
<span class="p">}</span>
<span class="n">Py_DECREF</span><span class="p">(</span><span class="n">index</span><span class="p">);</span>
<span class="p">}</span>
<span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
<p id="index-8">The situation is slightly different for function return values. While passing
a reference to most functions does not change your ownership responsibilities
for that reference, many functions that return a reference to an object give
you ownership of the reference. The reason is simple: in many cases, the
returned object is created on the fly, and the reference you get is the only
reference to the object. Therefore, the generic functions that return object
references, like <a class="reference internal" href="object.html#c.PyObject_GetItem" title="PyObject_GetItem"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_GetItem()</span></code></a> and <a class="reference internal" href="sequence.html#c.PySequence_GetItem" title="PySequence_GetItem"><code class="xref c c-func docutils literal notranslate"><span class="pre">PySequence_GetItem()</span></code></a>,
always return a new reference (the caller becomes the owner of the reference).</p>
<p>It is important to realize that whether you own a reference returned by a
function depends on which function you call only — <em>the plumage</em> (the type of
the object passed as an argument to the function) <em>doesn’t enter into it!</em>
Thus, if you extract an item from a list using <a class="reference internal" href="list.html#c.PyList_GetItem" title="PyList_GetItem"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyList_GetItem()</span></code></a>, you
don’t own the reference — but if you obtain the same item from the same list
using <a class="reference internal" href="sequence.html#c.PySequence_GetItem" title="PySequence_GetItem"><code class="xref c c-func docutils literal notranslate"><span class="pre">PySequence_GetItem()</span></code></a> (which happens to take exactly the same
arguments), you do own a reference to the returned object.</p>
<p id="index-9">Here is an example of how you could write a function that computes the sum of
the items in a list of integers; once using <a class="reference internal" href="list.html#c.PyList_GetItem" title="PyList_GetItem"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyList_GetItem()</span></code></a>, and once
using <a class="reference internal" href="sequence.html#c.PySequence_GetItem" title="PySequence_GetItem"><code class="xref c c-func docutils literal notranslate"><span class="pre">PySequence_GetItem()</span></code></a>.</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">long</span>
<span class="nf">sum_list</span><span class="p">(</span><span class="n">PyObject</span> <span class="o">*</span><span class="n">list</span><span class="p">)</span>
<span class="p">{</span>
<span class="kt">int</span> <span class="n">i</span><span class="p">,</span> <span class="n">n</span><span class="p">;</span>
<span class="kt">long</span> <span class="n">total</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
<span class="n">PyObject</span> <span class="o">*</span><span class="n">item</span><span class="p">;</span>
<span class="n">n</span> <span class="o">=</span> <span class="n">PyList_Size</span><span class="p">(</span><span class="n">list</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">n</span> <span class="o"><</span> <span class="mi">0</span><span class="p">)</span>
<span class="k">return</span> <span class="o">-</span><span class="mi">1</span><span class="p">;</span> <span class="cm">/* Not a list */</span>
<span class="k">for</span> <span class="p">(</span><span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">n</span><span class="p">;</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span> <span class="p">{</span>
<span class="n">item</span> <span class="o">=</span> <span class="n">PyList_GetItem</span><span class="p">(</span><span class="n">list</span><span class="p">,</span> <span class="n">i</span><span class="p">);</span> <span class="cm">/* Can't fail */</span>
<span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">PyInt_Check</span><span class="p">(</span><span class="n">item</span><span class="p">))</span> <span class="k">continue</span><span class="p">;</span> <span class="cm">/* Skip non-integers */</span>
<span class="n">total</span> <span class="o">+=</span> <span class="n">PyInt_AsLong</span><span class="p">(</span><span class="n">item</span><span class="p">);</span>
<span class="p">}</span>
<span class="k">return</span> <span class="n">total</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
<div class="highlight-c notranslate" id="index-10"><div class="highlight"><pre><span></span><span class="kt">long</span>
<span class="nf">sum_sequence</span><span class="p">(</span><span class="n">PyObject</span> <span class="o">*</span><span class="n">sequence</span><span class="p">)</span>
<span class="p">{</span>
<span class="kt">int</span> <span class="n">i</span><span class="p">,</span> <span class="n">n</span><span class="p">;</span>
<span class="kt">long</span> <span class="n">total</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
<span class="n">PyObject</span> <span class="o">*</span><span class="n">item</span><span class="p">;</span>
<span class="n">n</span> <span class="o">=</span> <span class="n">PySequence_Length</span><span class="p">(</span><span class="n">sequence</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">n</span> <span class="o"><</span> <span class="mi">0</span><span class="p">)</span>
<span class="k">return</span> <span class="o">-</span><span class="mi">1</span><span class="p">;</span> <span class="cm">/* Has no length */</span>
<span class="k">for</span> <span class="p">(</span><span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">n</span><span class="p">;</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span> <span class="p">{</span>
<span class="n">item</span> <span class="o">=</span> <span class="n">PySequence_GetItem</span><span class="p">(</span><span class="n">sequence</span><span class="p">,</span> <span class="n">i</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">item</span> <span class="o">==</span> <span class="nb">NULL</span><span class="p">)</span>
<span class="k">return</span> <span class="o">-</span><span class="mi">1</span><span class="p">;</span> <span class="cm">/* Not a sequence, or other failure */</span>
<span class="k">if</span> <span class="p">(</span><span class="n">PyInt_Check</span><span class="p">(</span><span class="n">item</span><span class="p">))</span>
<span class="n">total</span> <span class="o">+=</span> <span class="n">PyInt_AsLong</span><span class="p">(</span><span class="n">item</span><span class="p">);</span>
<span class="n">Py_DECREF</span><span class="p">(</span><span class="n">item</span><span class="p">);</span> <span class="cm">/* Discard reference ownership */</span>
<span class="p">}</span>
<span class="k">return</span> <span class="n">total</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="types">
<span id="api-types"></span><span id="index-11"></span><h3>Types<a class="headerlink" href="#types" title="Permalink to this headline">¶</a></h3>
<p>There are few other data types that play a significant role in the Python/C
API; most are simple C types such as <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code>, <code class="xref c c-type docutils literal notranslate"><span class="pre">long</span></code>,
<code class="xref c c-type docutils literal notranslate"><span class="pre">double</span></code> and <code class="xref c c-type docutils literal notranslate"><span class="pre">char*</span></code>. A few structure types are used to
describe static tables used to list the functions exported by a module or the
data attributes of a new object type, and another is used to describe the value
of a complex number. These will be discussed together with the functions that
use them.</p>
</div>
</div>
<div class="section" id="exceptions">
<span id="api-exceptions"></span><h2>Exceptions<a class="headerlink" href="#exceptions" title="Permalink to this headline">¶</a></h2>
<p>The Python programmer only needs to deal with exceptions if specific error
handling is required; unhandled exceptions are automatically propagated to the
caller, then to the caller’s caller, and so on, until they reach the top-level
interpreter, where they are reported to the user accompanied by a stack
traceback.</p>
<p id="index-12">For C programmers, however, error checking always has to be explicit. All
functions in the Python/C API can raise exceptions, unless an explicit claim is
made otherwise in a function’s documentation. In general, when a function
encounters an error, it sets an exception, discards any object references that
it owns, and returns an error indicator. If not documented otherwise, this
indicator is either <em>NULL</em> or <code class="docutils literal notranslate"><span class="pre">-1</span></code>, depending on the function’s return type.
A few functions return a Boolean true/false result, with false indicating an
error. Very few functions return no explicit error indicator or have an
ambiguous return value, and require explicit testing for errors with
<a class="reference internal" href="exceptions.html#c.PyErr_Occurred" title="PyErr_Occurred"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyErr_Occurred()</span></code></a>. These exceptions are always explicitly documented.</p>
<p id="index-13">Exception state is maintained in per-thread storage (this is equivalent to
using global storage in an unthreaded application). A thread can be in one of
two states: an exception has occurred, or not. The function
<a class="reference internal" href="exceptions.html#c.PyErr_Occurred" title="PyErr_Occurred"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyErr_Occurred()</span></code></a> can be used to check for this: it returns a borrowed
reference to the exception type object when an exception has occurred, and
<em>NULL</em> otherwise. There are a number of functions to set the exception state:
<a class="reference internal" href="exceptions.html#c.PyErr_SetString" title="PyErr_SetString"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyErr_SetString()</span></code></a> is the most common (though not the most general)
function to set the exception state, and <a class="reference internal" href="exceptions.html#c.PyErr_Clear" title="PyErr_Clear"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyErr_Clear()</span></code></a> clears the
exception state.</p>
<p id="index-14">The full exception state consists of three objects (all of which can be
<em>NULL</em>): the exception type, the corresponding exception value, and the
traceback. These have the same meanings as the Python objects
<code class="docutils literal notranslate"><span class="pre">sys.exc_type</span></code>, <code class="docutils literal notranslate"><span class="pre">sys.exc_value</span></code>, and <code class="docutils literal notranslate"><span class="pre">sys.exc_traceback</span></code>; however, they
are not the same: the Python objects represent the last exception being handled
by a Python <a class="reference internal" href="../reference/compound_stmts.html#try"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">try</span></code></a> … <a class="reference internal" href="../reference/compound_stmts.html#except"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">except</span></code></a> statement, while the C level
exception state only exists while an exception is being passed on between C
functions until it reaches the Python bytecode interpreter’s main loop, which
takes care of transferring it to <code class="docutils literal notranslate"><span class="pre">sys.exc_type</span></code> and friends.</p>
<p id="index-15">Note that starting with Python 1.5, the preferred, thread-safe way to access the
exception state from Python code is to call the function <a class="reference internal" href="../library/sys.html#sys.exc_info" title="sys.exc_info"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.exc_info()</span></code></a>,
which returns the per-thread exception state for Python code. Also, the
semantics of both ways to access the exception state have changed so that a
function which catches an exception will save and restore its thread’s exception
state so as to preserve the exception state of its caller. This prevents common
bugs in exception handling code caused by an innocent-looking function
overwriting the exception being handled; it also reduces the often unwanted
lifetime extension for objects that are referenced by the stack frames in the
traceback.</p>
<p>As a general principle, a function that calls another function to perform some
task should check whether the called function raised an exception, and if so,
pass the exception state on to its caller. It should discard any object
references that it owns, and return an error indicator, but it should <em>not</em> set
another exception — that would overwrite the exception that was just raised,
and lose important information about the exact cause of the error.</p>
<p id="index-16">A simple example of detecting exceptions and passing them on is shown in the
<code class="xref c c-func docutils literal notranslate"><span class="pre">sum_sequence()</span></code> example above. It so happens that this example doesn’t
need to clean up any owned references when it detects an error. The following
example function shows some error cleanup. First, to remind you why you like
Python, we show the equivalent Python code:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">def</span> <span class="n">incr_item</span><span class="p">(</span><span class="n">dict</span><span class="p">,</span> <span class="n">key</span><span class="p">)</span><span class="o">:</span>
<span class="nl">try</span><span class="p">:</span>
<span class="n">item</span> <span class="o">=</span> <span class="n">dict</span><span class="p">[</span><span class="n">key</span><span class="p">]</span>
<span class="n">except</span> <span class="nl">KeyError</span><span class="p">:</span>
<span class="n">item</span> <span class="o">=</span> <span class="mi">0</span>
<span class="n">dict</span><span class="p">[</span><span class="n">key</span><span class="p">]</span> <span class="o">=</span> <span class="n">item</span> <span class="o">+</span> <span class="mi">1</span>
</pre></div>
</div>
<p id="index-17">Here is the corresponding C code, in all its glory:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span>
<span class="nf">incr_item</span><span class="p">(</span><span class="n">PyObject</span> <span class="o">*</span><span class="n">dict</span><span class="p">,</span> <span class="n">PyObject</span> <span class="o">*</span><span class="n">key</span><span class="p">)</span>
<span class="p">{</span>
<span class="cm">/* Objects all initialized to NULL for Py_XDECREF */</span>
<span class="n">PyObject</span> <span class="o">*</span><span class="n">item</span> <span class="o">=</span> <span class="nb">NULL</span><span class="p">,</span> <span class="o">*</span><span class="n">const_one</span> <span class="o">=</span> <span class="nb">NULL</span><span class="p">,</span> <span class="o">*</span><span class="n">incremented_item</span> <span class="o">=</span> <span class="nb">NULL</span><span class="p">;</span>
<span class="kt">int</span> <span class="n">rv</span> <span class="o">=</span> <span class="o">-</span><span class="mi">1</span><span class="p">;</span> <span class="cm">/* Return value initialized to -1 (failure) */</span>
<span class="n">item</span> <span class="o">=</span> <span class="n">PyObject_GetItem</span><span class="p">(</span><span class="n">dict</span><span class="p">,</span> <span class="n">key</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">item</span> <span class="o">==</span> <span class="nb">NULL</span><span class="p">)</span> <span class="p">{</span>
<span class="cm">/* Handle KeyError only: */</span>
<span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">PyErr_ExceptionMatches</span><span class="p">(</span><span class="n">PyExc_KeyError</span><span class="p">))</span>
<span class="k">goto</span> <span class="n">error</span><span class="p">;</span>
<span class="cm">/* Clear the error and use zero: */</span>
<span class="n">PyErr_Clear</span><span class="p">();</span>
<span class="n">item</span> <span class="o">=</span> <span class="n">PyInt_FromLong</span><span class="p">(</span><span class="mi">0L</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">item</span> <span class="o">==</span> <span class="nb">NULL</span><span class="p">)</span>
<span class="k">goto</span> <span class="n">error</span><span class="p">;</span>
<span class="p">}</span>
<span class="n">const_one</span> <span class="o">=</span> <span class="n">PyInt_FromLong</span><span class="p">(</span><span class="mi">1L</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">const_one</span> <span class="o">==</span> <span class="nb">NULL</span><span class="p">)</span>
<span class="k">goto</span> <span class="n">error</span><span class="p">;</span>
<span class="n">incremented_item</span> <span class="o">=</span> <span class="n">PyNumber_Add</span><span class="p">(</span><span class="n">item</span><span class="p">,</span> <span class="n">const_one</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">incremented_item</span> <span class="o">==</span> <span class="nb">NULL</span><span class="p">)</span>
<span class="k">goto</span> <span class="n">error</span><span class="p">;</span>
<span class="k">if</span> <span class="p">(</span><span class="n">PyObject_SetItem</span><span class="p">(</span><span class="n">dict</span><span class="p">,</span> <span class="n">key</span><span class="p">,</span> <span class="n">incremented_item</span><span class="p">)</span> <span class="o"><</span> <span class="mi">0</span><span class="p">)</span>
<span class="k">goto</span> <span class="n">error</span><span class="p">;</span>
<span class="n">rv</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="cm">/* Success */</span>
<span class="cm">/* Continue with cleanup code */</span>
<span class="nl">error</span><span class="p">:</span>
<span class="cm">/* Cleanup code, shared by success and failure path */</span>
<span class="cm">/* Use Py_XDECREF() to ignore NULL references */</span>
<span class="n">Py_XDECREF</span><span class="p">(</span><span class="n">item</span><span class="p">);</span>
<span class="n">Py_XDECREF</span><span class="p">(</span><span class="n">const_one</span><span class="p">);</span>
<span class="n">Py_XDECREF</span><span class="p">(</span><span class="n">incremented_item</span><span class="p">);</span>
<span class="k">return</span> <span class="n">rv</span><span class="p">;</span> <span class="cm">/* -1 for error, 0 for success */</span>
<span class="p">}</span>
</pre></div>
</div>
<span class="target" id="index-18"></span><p id="index-19">This example represents an endorsed use of the <code class="docutils literal notranslate"><span class="pre">goto</span></code> statement in C!
It illustrates the use of <a class="reference internal" href="exceptions.html#c.PyErr_ExceptionMatches" title="PyErr_ExceptionMatches"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyErr_ExceptionMatches()</span></code></a> and
<a class="reference internal" href="exceptions.html#c.PyErr_Clear" title="PyErr_Clear"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyErr_Clear()</span></code></a> to handle specific exceptions, and the use of
<a class="reference internal" href="refcounting.html#c.Py_XDECREF" title="Py_XDECREF"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_XDECREF()</span></code></a> to dispose of owned references that may be <em>NULL</em> (note the
<code class="docutils literal notranslate"><span class="pre">'X'</span></code> in the name; <a class="reference internal" href="refcounting.html#c.Py_DECREF" title="Py_DECREF"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_DECREF()</span></code></a> would crash when confronted with a
<em>NULL</em> reference). It is important that the variables used to hold owned
references are initialized to <em>NULL</em> for this to work; likewise, the proposed
return value is initialized to <code class="docutils literal notranslate"><span class="pre">-1</span></code> (failure) and only set to success after
the final call made is successful.</p>
</div>
<div class="section" id="embedding-python">
<span id="api-embedding"></span><h2>Embedding Python<a class="headerlink" href="#embedding-python" title="Permalink to this headline">¶</a></h2>
<p>The one important task that only embedders (as opposed to extension writers) of
the Python interpreter have to worry about is the initialization, and possibly
the finalization, of the Python interpreter. Most functionality of the
interpreter can only be used after the interpreter has been initialized.</p>
<p id="index-20">The basic initialization function is <a class="reference internal" href="init.html#c.Py_Initialize" title="Py_Initialize"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_Initialize()</span></code></a>. This initializes
the table of loaded modules, and creates the fundamental modules
<a class="reference internal" href="../library/__builtin__.html#module-__builtin__" title="__builtin__: The module that provides the built-in namespace."><code class="xref py py-mod docutils literal notranslate"><span class="pre">__builtin__</span></code></a>, <a class="reference internal" href="../library/__main__.html#module-__main__" title="__main__: The environment where the top-level script is run."><code class="xref py py-mod docutils literal notranslate"><span class="pre">__main__</span></code></a>, <a class="reference internal" href="../library/sys.html#module-sys" title="sys: Access system-specific parameters and functions."><code class="xref py py-mod docutils literal notranslate"><span class="pre">sys</span></code></a>, and <a class="reference internal" href="../library/exceptions.html#module-exceptions" title="exceptions: Standard exception classes."><code class="xref py py-mod docutils literal notranslate"><span class="pre">exceptions</span></code></a>. It also
initializes the module search path (<code class="docutils literal notranslate"><span class="pre">sys.path</span></code>).</p>
<p id="index-21"><a class="reference internal" href="init.html#c.Py_Initialize" title="Py_Initialize"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_Initialize()</span></code></a> does not set the “script argument list” (<code class="docutils literal notranslate"><span class="pre">sys.argv</span></code>).
If this variable is needed by Python code that will be executed later, it must
be set explicitly with a call to <code class="docutils literal notranslate"><span class="pre">PySys_SetArgvEx(argc,</span> <span class="pre">argv,</span> <span class="pre">updatepath)</span></code>
after the call to <a class="reference internal" href="init.html#c.Py_Initialize" title="Py_Initialize"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_Initialize()</span></code></a>.</p>
<p>On most systems (in particular, on Unix and Windows, although the details are
slightly different), <a class="reference internal" href="init.html#c.Py_Initialize" title="Py_Initialize"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_Initialize()</span></code></a> calculates the module search path
based upon its best guess for the location of the standard Python interpreter
executable, assuming that the Python library is found in a fixed location
relative to the Python interpreter executable. In particular, it looks for a
directory named <code class="file docutils literal notranslate"><span class="pre">lib/python</span><em><span class="pre">X.Y</span></em></code> relative to the parent directory
where the executable named <code class="file docutils literal notranslate"><span class="pre">python</span></code> is found on the shell command search
path (the environment variable <span class="target" id="index-22"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code>).</p>
<p>For instance, if the Python executable is found in
<code class="file docutils literal notranslate"><span class="pre">/usr/local/bin/python</span></code>, it will assume that the libraries are in
<code class="file docutils literal notranslate"><span class="pre">/usr/local/lib/python</span><em><span class="pre">X.Y</span></em></code>. (In fact, this particular path is also
the “fallback” location, used when no executable file named <code class="file docutils literal notranslate"><span class="pre">python</span></code> is
found along <span class="target" id="index-23"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code>.) The user can override this behavior by setting the
environment variable <span class="target" id="index-24"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONHOME"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONHOME</span></code></a>, or insert additional directories in
front of the standard path by setting <span class="target" id="index-25"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONPATH"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONPATH</span></code></a>.</p>
<p id="index-26">The embedding application can steer the search by calling
<code class="docutils literal notranslate"><span class="pre">Py_SetProgramName(file)</span></code> <em>before</em> calling <a class="reference internal" href="init.html#c.Py_Initialize" title="Py_Initialize"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_Initialize()</span></code></a>. Note that
<span class="target" id="index-27"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONHOME"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONHOME</span></code></a> still overrides this and <span class="target" id="index-28"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONPATH"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONPATH</span></code></a> is still
inserted in front of the standard path. An application that requires total
control has to provide its own implementation of <a class="reference internal" href="init.html#c.Py_GetPath" title="Py_GetPath"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_GetPath()</span></code></a>,
<a class="reference internal" href="init.html#c.Py_GetPrefix" title="Py_GetPrefix"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_GetPrefix()</span></code></a>, <a class="reference internal" href="init.html#c.Py_GetExecPrefix" title="Py_GetExecPrefix"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_GetExecPrefix()</span></code></a>, and
<a class="reference internal" href="init.html#c.Py_GetProgramFullPath" title="Py_GetProgramFullPath"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_GetProgramFullPath()</span></code></a> (all defined in <code class="file docutils literal notranslate"><span class="pre">Modules/getpath.c</span></code>).</p>
<p id="index-29">Sometimes, it is desirable to “uninitialize” Python. For instance, the
application may want to start over (make another call to
<a class="reference internal" href="init.html#c.Py_Initialize" title="Py_Initialize"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_Initialize()</span></code></a>) or the application is simply done with its use of
Python and wants to free memory allocated by Python. This can be accomplished
by calling <a class="reference internal" href="init.html#c.Py_Finalize" title="Py_Finalize"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_Finalize()</span></code></a>. The function <a class="reference internal" href="init.html#c.Py_IsInitialized" title="Py_IsInitialized"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_IsInitialized()</span></code></a> returns
true if Python is currently in the initialized state. More information about
these functions is given in a later chapter. Notice that <a class="reference internal" href="init.html#c.Py_Finalize" title="Py_Finalize"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_Finalize()</span></code></a>
does <em>not</em> free all memory allocated by the Python interpreter, e.g. memory
allocated by extension modules currently cannot be released.</p>
</div>
<div class="section" id="debugging-builds">
<span id="api-debugging"></span><h2>Debugging Builds<a class="headerlink" href="#debugging-builds" title="Permalink to this headline">¶</a></h2>
<p>Python can be built with several macros to enable extra checks of the
interpreter and extension modules. These checks tend to add a large amount of
overhead to the runtime so they are not enabled by default.</p>
<p>A full list of the various types of debugging builds is in the file
<code class="file docutils literal notranslate"><span class="pre">Misc/SpecialBuilds.txt</span></code> in the Python source distribution. Builds are
available that support tracing of reference counts, debugging the memory
allocator, or low-level profiling of the main interpreter loop. Only the most
frequently-used builds will be described in the remainder of this section.</p>
<p>Compiling the interpreter with the <code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_DEBUG</span></code> macro defined produces
what is generally meant by “a debug build” of Python. <code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_DEBUG</span></code> is
enabled in the Unix build by adding <code class="docutils literal notranslate"><span class="pre">--with-pydebug</span></code> to the
<code class="file docutils literal notranslate"><span class="pre">./configure</span></code> command. It is also implied by the presence of the
not-Python-specific <code class="xref c c-macro docutils literal notranslate"><span class="pre">_DEBUG</span></code> macro. When <code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_DEBUG</span></code> is enabled
in the Unix build, compiler optimization is disabled.</p>
<p>In addition to the reference count debugging described below, the following
extra checks are performed:</p>
<ul class="simple">
<li>Extra checks are added to the object allocator.</li>
<li>Extra checks are added to the parser and compiler.</li>
<li>Downcasts from wide types to narrow types are checked for loss of information.</li>
<li>A number of assertions are added to the dictionary and set implementations.
In addition, the set object acquires a <code class="xref py py-meth docutils literal notranslate"><span class="pre">test_c_api()</span></code> method.</li>
<li>Sanity checks of the input arguments are added to frame creation.</li>
<li>The storage for long ints is initialized with a known invalid pattern to catch
reference to uninitialized digits.</li>
<li>Low-level tracing and extra exception checking are added to the runtime
virtual machine.</li>
<li>Extra checks are added to the memory arena implementation.</li>
<li>Extra debugging is added to the thread module.</li>
</ul>
<p>There may be additional checks not mentioned here.</p>
<p>Defining <code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_TRACE_REFS</span></code> enables reference tracing. When defined, a
circular doubly linked list of active objects is maintained by adding two extra
fields to every <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject</span></code></a>. Total allocations are tracked as well. Upon
exit, all existing references are printed. (In interactive mode this happens
after every statement run by the interpreter.) Implied by <code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_DEBUG</span></code>.</p>
<p>Please refer to <code class="file docutils literal notranslate"><span class="pre">Misc/SpecialBuilds.txt</span></code> in the Python source distribution
for more detailed information.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Introduction</a><ul>
<li><a class="reference internal" href="#include-files">Include Files</a></li>
<li><a class="reference internal" href="#objects-types-and-reference-counts">Objects, Types and Reference Counts</a><ul>
<li><a class="reference internal" href="#reference-counts">Reference Counts</a><ul>
<li><a class="reference internal" href="#reference-count-details">Reference Count Details</a></li>
</ul>
</li>
<li><a class="reference internal" href="#types">Types</a></li>
</ul>
</li>
<li><a class="reference internal" href="#exceptions">Exceptions</a></li>
<li><a class="reference internal" href="#embedding-python">Embedding Python</a></li>
<li><a class="reference internal" href="#debugging-builds">Debugging Builds</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="index.html"
title="previous chapter">Python/C API Reference Manual</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="veryhigh.html"
title="next chapter">The Very High Level Layer</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/intro.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="veryhigh.html" title="The Very High Level Layer"
>next</a> |</li>
<li class="right" >
<a href="index.html" title="Python/C API Reference Manual"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\�g}��' �' html/c-api/iter.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Iterator Protocol — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Old Buffer Protocol" href="objbuffer.html" />
<link rel="prev" title="Mapping Protocol" href="mapping.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/iter.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="objbuffer.html" title="Old Buffer Protocol"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="mapping.html" title="Mapping Protocol"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="abstract.html" accesskey="U">Abstract Objects Layer</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="iterator-protocol">
<span id="iterator"></span><h1>Iterator Protocol<a class="headerlink" href="#iterator-protocol" title="Permalink to this headline">¶</a></h1>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
<p>There are two functions specifically for working with iterators.</p>
<dl class="function">
<dt id="c.PyIter_Check">
int <code class="descname">PyIter_Check</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyIter_Check" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if the object <em>o</em> supports the iterator protocol.</p>
<p>This function can return a false positive in the case of old-style
classes because those classes always define a <code class="xref c c-member docutils literal notranslate"><span class="pre">tp_iternext</span></code>
slot with logic that either invokes a <a class="reference internal" href="../library/functions.html#next" title="next"><code class="xref py py-meth docutils literal notranslate"><span class="pre">next()</span></code></a> method or raises
a <a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyIter_Next">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyIter_Next</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyIter_Next" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return the next value from the iteration <em>o</em>. The object must be an iterator
(it is up to the caller to check this). If there are no remaining values,
returns <em>NULL</em> with no exception set. If an error occurs while retrieving
the item, returns <em>NULL</em> and passes along the exception.</p>
</dd></dl>
<p>To write a loop which iterates over an iterator, the C code should look
something like this:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">PyObject</span> <span class="o">*</span><span class="n">iterator</span> <span class="o">=</span> <span class="n">PyObject_GetIter</span><span class="p">(</span><span class="n">obj</span><span class="p">);</span>
<span class="n">PyObject</span> <span class="o">*</span><span class="n">item</span><span class="p">;</span>
<span class="k">if</span> <span class="p">(</span><span class="n">iterator</span> <span class="o">==</span> <span class="nb">NULL</span><span class="p">)</span> <span class="p">{</span>
<span class="cm">/* propagate error */</span>
<span class="p">}</span>
<span class="k">while</span> <span class="p">(</span><span class="n">item</span> <span class="o">=</span> <span class="n">PyIter_Next</span><span class="p">(</span><span class="n">iterator</span><span class="p">))</span> <span class="p">{</span>
<span class="cm">/* do something with item */</span>
<span class="p">...</span>
<span class="cm">/* release reference when done */</span>
<span class="n">Py_DECREF</span><span class="p">(</span><span class="n">item</span><span class="p">);</span>
<span class="p">}</span>
<span class="n">Py_DECREF</span><span class="p">(</span><span class="n">iterator</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">PyErr_Occurred</span><span class="p">())</span> <span class="p">{</span>
<span class="cm">/* propagate error */</span>
<span class="p">}</span>
<span class="k">else</span> <span class="p">{</span>
<span class="cm">/* continue doing useful work */</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="mapping.html"
title="previous chapter">Mapping Protocol</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="objbuffer.html"
title="next chapter">Old Buffer Protocol</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/iter.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="objbuffer.html" title="Old Buffer Protocol"
>next</a> |</li>
<li class="right" >
<a href="mapping.html" title="Mapping Protocol"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="abstract.html" >Abstract Objects Layer</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\���6. 6. html/c-api/iterator.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Iterator Objects — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Descriptor Objects" href="descriptor.html" />
<link rel="prev" title="Module Objects" href="module.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/iterator.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="descriptor.html" title="Descriptor Objects"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="module.html" title="Module Objects"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" accesskey="U">Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="iterator-objects">
<span id="id1"></span><h1>Iterator Objects<a class="headerlink" href="#iterator-objects" title="Permalink to this headline">¶</a></h1>
<p>Python provides two general-purpose iterator objects. The first, a sequence
iterator, works with an arbitrary sequence supporting the <a class="reference internal" href="../reference/datamodel.html#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getitem__()</span></code></a>
method. The second works with a callable object and a sentinel value, calling
the callable for each item in the sequence, and ending the iteration when the
sentinel value is returned.</p>
<dl class="var">
<dt id="c.PySeqIter_Type">
<a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a> <code class="descname">PySeqIter_Type</code><a class="headerlink" href="#c.PySeqIter_Type" title="Permalink to this definition">¶</a></dt>
<dd><p>Type object for iterator objects returned by <a class="reference internal" href="#c.PySeqIter_New" title="PySeqIter_New"><code class="xref c c-func docutils literal notranslate"><span class="pre">PySeqIter_New()</span></code></a> and the
one-argument form of the <a class="reference internal" href="../library/functions.html#iter" title="iter"><code class="xref py py-func docutils literal notranslate"><span class="pre">iter()</span></code></a> built-in function for built-in sequence
types.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PySeqIter_Check">
int <code class="descname">PySeqIter_Check</code><span class="sig-paren">(</span>op<span class="sig-paren">)</span><a class="headerlink" href="#c.PySeqIter_Check" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if the type of <em>op</em> is <a class="reference internal" href="#c.PySeqIter_Type" title="PySeqIter_Type"><code class="xref c c-data docutils literal notranslate"><span class="pre">PySeqIter_Type</span></code></a>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PySeqIter_New">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PySeqIter_New</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *seq</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySeqIter_New" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return an iterator that works with a general sequence object, <em>seq</em>. The
iteration ends when the sequence raises <a class="reference internal" href="../library/exceptions.html#exceptions.IndexError" title="exceptions.IndexError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">IndexError</span></code></a> for the subscripting
operation.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="var">
<dt id="c.PyCallIter_Type">
<a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a> <code class="descname">PyCallIter_Type</code><a class="headerlink" href="#c.PyCallIter_Type" title="Permalink to this definition">¶</a></dt>
<dd><p>Type object for iterator objects returned by <a class="reference internal" href="#c.PyCallIter_New" title="PyCallIter_New"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyCallIter_New()</span></code></a> and the
two-argument form of the <a class="reference internal" href="../library/functions.html#iter" title="iter"><code class="xref py py-func docutils literal notranslate"><span class="pre">iter()</span></code></a> built-in function.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyCallIter_Check">
int <code class="descname">PyCallIter_Check</code><span class="sig-paren">(</span>op<span class="sig-paren">)</span><a class="headerlink" href="#c.PyCallIter_Check" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if the type of <em>op</em> is <a class="reference internal" href="#c.PyCallIter_Type" title="PyCallIter_Type"><code class="xref c c-data docutils literal notranslate"><span class="pre">PyCallIter_Type</span></code></a>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyCallIter_New">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyCallIter_New</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *callable</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *sentinel</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCallIter_New" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a new iterator. The first parameter, <em>callable</em>, can be any Python
callable object that can be called with no parameters; each call to it should
return the next item in the iteration. When <em>callable</em> returns a value equal to
<em>sentinel</em>, the iteration will be terminated.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="module.html"
title="previous chapter">Module Objects</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="descriptor.html"
title="next chapter">Descriptor Objects</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/iterator.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="descriptor.html" title="Descriptor Objects"
>next</a> |</li>
<li class="right" >
<a href="module.html" title="Module Objects"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" >Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\�L>�^` ^` html/c-api/list.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>List Objects — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Dictionary Objects" href="dict.html" />
<link rel="prev" title="Tuple Objects" href="tuple.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/list.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="dict.html" title="Dictionary Objects"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="tuple.html" title="Tuple Objects"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" accesskey="U">Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="list-objects">
<span id="listobjects"></span><h1>List Objects<a class="headerlink" href="#list-objects" title="Permalink to this headline">¶</a></h1>
<span class="target" id="index-0"></span><dl class="type">
<dt id="c.PyListObject">
<code class="descname">PyListObject</code><a class="headerlink" href="#c.PyListObject" title="Permalink to this definition">¶</a></dt>
<dd><p>This subtype of <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject</span></code></a> represents a Python list object.</p>
</dd></dl>
<dl class="var">
<dt id="c.PyList_Type">
<a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a> <code class="descname">PyList_Type</code><a class="headerlink" href="#c.PyList_Type" title="Permalink to this definition">¶</a></dt>
<dd><p>This instance of <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyTypeObject</span></code></a> represents the Python list type. This
is the same object as <code class="docutils literal notranslate"><span class="pre">list</span></code> in the Python layer.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyList_Check">
int <code class="descname">PyList_Check</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyList_Check" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if <em>p</em> is a list object or an instance of a subtype of the list
type.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.2: </span>Allowed subtypes to be accepted.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyList_CheckExact">
int <code class="descname">PyList_CheckExact</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyList_CheckExact" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if <em>p</em> is a list object, but not an instance of a subtype of
the list type.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyList_New">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyList_New</code><span class="sig-paren">(</span>Py_ssize_t<em> len</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyList_New" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a new list of length <em>len</em> on success, or <em>NULL</em> on failure.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If <em>len</em> is greater than zero, the returned list object’s items are
set to <code class="docutils literal notranslate"><span class="pre">NULL</span></code>. Thus you cannot use abstract API functions such as
<a class="reference internal" href="sequence.html#c.PySequence_SetItem" title="PySequence_SetItem"><code class="xref c c-func docutils literal notranslate"><span class="pre">PySequence_SetItem()</span></code></a> or expose the object to Python code before
setting all items to a real object with <a class="reference internal" href="#c.PyList_SetItem" title="PyList_SetItem"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyList_SetItem()</span></code></a>.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> for <em>size</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyList_Size">
Py_ssize_t <code class="descname">PyList_Size</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *list</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyList_Size" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-1">Return the length of the list object in <em>list</em>; this is equivalent to
<code class="docutils literal notranslate"><span class="pre">len(list)</span></code> on a list object.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function returned an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code>. This might require changes in
your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyList_GET_SIZE">
Py_ssize_t <code class="descname">PyList_GET_SIZE</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *list</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyList_GET_SIZE" title="Permalink to this definition">¶</a></dt>
<dd><p>Macro form of <a class="reference internal" href="#c.PyList_Size" title="PyList_Size"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyList_Size()</span></code></a> without error checking.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This macro returned an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code>. This might require changes in your
code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyList_GetItem">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyList_GetItem</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *list</em>, Py_ssize_t<em> index</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyList_GetItem" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Borrowed reference.</em><p>Return the object at position <em>index</em> in the list pointed to by <em>list</em>. The
position must be positive, indexing from the end of the list is not
supported. If <em>index</em> is out of bounds, return <em>NULL</em> and set an
<a class="reference internal" href="../library/exceptions.html#exceptions.IndexError" title="exceptions.IndexError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">IndexError</span></code></a> exception.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> for <em>index</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyList_GET_ITEM">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyList_GET_ITEM</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *list</em>, Py_ssize_t<em> i</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyList_GET_ITEM" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Borrowed reference.</em><p>Macro form of <a class="reference internal" href="#c.PyList_GetItem" title="PyList_GetItem"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyList_GetItem()</span></code></a> without error checking.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This macro used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> for <em>i</em>. This might require changes in
your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyList_SetItem">
int <code class="descname">PyList_SetItem</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *list</em>, Py_ssize_t<em> index</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *item</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyList_SetItem" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the item at index <em>index</em> in list to <em>item</em>. Return <code class="docutils literal notranslate"><span class="pre">0</span></code> on success
or <code class="docutils literal notranslate"><span class="pre">-1</span></code> on failure.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This function “steals” a reference to <em>item</em> and discards a reference to
an item already in the list at the affected position.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> for <em>index</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyList_SET_ITEM">
void <code class="descname">PyList_SET_ITEM</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *list</em>, Py_ssize_t<em> i</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyList_SET_ITEM" title="Permalink to this definition">¶</a></dt>
<dd><p>Macro form of <a class="reference internal" href="#c.PyList_SetItem" title="PyList_SetItem"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyList_SetItem()</span></code></a> without error checking. This is
normally only used to fill in new lists where there is no previous content.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This macro “steals” a reference to <em>item</em>, and, unlike
<a class="reference internal" href="#c.PyList_SetItem" title="PyList_SetItem"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyList_SetItem()</span></code></a>, does <em>not</em> discard a reference to any item that
it being replaced; any reference in <em>list</em> at position <em>i</em> will be
leaked.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This macro used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> for <em>i</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyList_Insert">
int <code class="descname">PyList_Insert</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *list</em>, Py_ssize_t<em> index</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *item</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyList_Insert" title="Permalink to this definition">¶</a></dt>
<dd><p>Insert the item <em>item</em> into list <em>list</em> in front of index <em>index</em>. Return
<code class="docutils literal notranslate"><span class="pre">0</span></code> if successful; return <code class="docutils literal notranslate"><span class="pre">-1</span></code> and set an exception if unsuccessful.
Analogous to <code class="docutils literal notranslate"><span class="pre">list.insert(index,</span> <span class="pre">item)</span></code>.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> for <em>index</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyList_Append">
int <code class="descname">PyList_Append</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *list</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *item</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyList_Append" title="Permalink to this definition">¶</a></dt>
<dd><p>Append the object <em>item</em> at the end of list <em>list</em>. Return <code class="docutils literal notranslate"><span class="pre">0</span></code> if
successful; return <code class="docutils literal notranslate"><span class="pre">-1</span></code> and set an exception if unsuccessful. Analogous
to <code class="docutils literal notranslate"><span class="pre">list.append(item)</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyList_GetSlice">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyList_GetSlice</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *list</em>, Py_ssize_t<em> low</em>, Py_ssize_t<em> high</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyList_GetSlice" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a list of the objects in <em>list</em> containing the objects <em>between</em> <em>low</em>
and <em>high</em>. Return <em>NULL</em> and set an exception if unsuccessful. Analogous
to <code class="docutils literal notranslate"><span class="pre">list[low:high]</span></code>. Negative indices, as when slicing from Python, are not
supported.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> for <em>low</em> and <em>high</em>. This might
require changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyList_SetSlice">
int <code class="descname">PyList_SetSlice</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *list</em>, Py_ssize_t<em> low</em>, Py_ssize_t<em> high</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *itemlist</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyList_SetSlice" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the slice of <em>list</em> between <em>low</em> and <em>high</em> to the contents of
<em>itemlist</em>. Analogous to <code class="docutils literal notranslate"><span class="pre">list[low:high]</span> <span class="pre">=</span> <span class="pre">itemlist</span></code>. The <em>itemlist</em> may
be <em>NULL</em>, indicating the assignment of an empty list (slice deletion).
Return <code class="docutils literal notranslate"><span class="pre">0</span></code> on success, <code class="docutils literal notranslate"><span class="pre">-1</span></code> on failure. Negative indices, as when
slicing from Python, are not supported.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> for <em>low</em> and <em>high</em>. This might
require changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyList_Sort">
int <code class="descname">PyList_Sort</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *list</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyList_Sort" title="Permalink to this definition">¶</a></dt>
<dd><p>Sort the items of <em>list</em> in place. Return <code class="docutils literal notranslate"><span class="pre">0</span></code> on success, <code class="docutils literal notranslate"><span class="pre">-1</span></code> on
failure. This is equivalent to <code class="docutils literal notranslate"><span class="pre">list.sort()</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyList_Reverse">
int <code class="descname">PyList_Reverse</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *list</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyList_Reverse" title="Permalink to this definition">¶</a></dt>
<dd><p>Reverse the items of <em>list</em> in place. Return <code class="docutils literal notranslate"><span class="pre">0</span></code> on success, <code class="docutils literal notranslate"><span class="pre">-1</span></code> on
failure. This is the equivalent of <code class="docutils literal notranslate"><span class="pre">list.reverse()</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyList_AsTuple">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyList_AsTuple</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *list</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyList_AsTuple" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p id="index-2">Return a new tuple object containing the contents of <em>list</em>; equivalent to
<code class="docutils literal notranslate"><span class="pre">tuple(list)</span></code>.</p>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="tuple.html"
title="previous chapter">Tuple Objects</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="dict.html"
title="next chapter">Dictionary Objects</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/list.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="dict.html" title="Dictionary Objects"
>next</a> |</li>
<li class="right" >
<a href="tuple.html" title="Tuple Objects"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" >Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\��7f�� �� html/c-api/long.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Long Integer Objects — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Floating Point Objects" href="float.html" />
<link rel="prev" title="Boolean Objects" href="bool.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/long.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="float.html" title="Floating Point Objects"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="bool.html" title="Boolean Objects"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" accesskey="U">Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="long-integer-objects">
<span id="longobjects"></span><h1>Long Integer Objects<a class="headerlink" href="#long-integer-objects" title="Permalink to this headline">¶</a></h1>
<span class="target" id="index-0"></span><dl class="type">
<dt id="c.PyLongObject">
<code class="descname">PyLongObject</code><a class="headerlink" href="#c.PyLongObject" title="Permalink to this definition">¶</a></dt>
<dd><p>This subtype of <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject</span></code></a> represents a Python long integer object.</p>
</dd></dl>
<dl class="var">
<dt id="c.PyLong_Type">
<a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a> <code class="descname">PyLong_Type</code><a class="headerlink" href="#c.PyLong_Type" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-1">This instance of <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyTypeObject</span></code></a> represents the Python long integer type.
This is the same object as <code class="docutils literal notranslate"><span class="pre">long</span></code> and <code class="docutils literal notranslate"><span class="pre">types.LongType</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyLong_Check">
int <code class="descname">PyLong_Check</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyLong_Check" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if its argument is a <a class="reference internal" href="#c.PyLongObject" title="PyLongObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyLongObject</span></code></a> or a subtype of
<a class="reference internal" href="#c.PyLongObject" title="PyLongObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyLongObject</span></code></a>.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.2: </span>Allowed subtypes to be accepted.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyLong_CheckExact">
int <code class="descname">PyLong_CheckExact</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyLong_CheckExact" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if its argument is a <a class="reference internal" href="#c.PyLongObject" title="PyLongObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyLongObject</span></code></a>, but not a subtype of
<a class="reference internal" href="#c.PyLongObject" title="PyLongObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyLongObject</span></code></a>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyLong_FromLong">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyLong_FromLong</code><span class="sig-paren">(</span>long<em> v</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyLong_FromLong" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a new <a class="reference internal" href="#c.PyLongObject" title="PyLongObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyLongObject</span></code></a> object from <em>v</em>, or <em>NULL</em> on failure.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyLong_FromUnsignedLong">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyLong_FromUnsignedLong</code><span class="sig-paren">(</span>unsigned long<em> v</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyLong_FromUnsignedLong" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a new <a class="reference internal" href="#c.PyLongObject" title="PyLongObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyLongObject</span></code></a> object from a C <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">long</span></code>, or
<em>NULL</em> on failure.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyLong_FromSsize_t">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyLong_FromSsize_t</code><span class="sig-paren">(</span>Py_ssize_t<em> v</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyLong_FromSsize_t" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a new <a class="reference internal" href="#c.PyLongObject" title="PyLongObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyLongObject</span></code></a> object from a C <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code>, or
<em>NULL</em> on failure.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyLong_FromSize_t">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyLong_FromSize_t</code><span class="sig-paren">(</span>size_t<em> v</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyLong_FromSize_t" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a new <a class="reference internal" href="#c.PyLongObject" title="PyLongObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyLongObject</span></code></a> object from a C <code class="xref c c-type docutils literal notranslate"><span class="pre">size_t</span></code>, or
<em>NULL</em> on failure.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyLong_FromLongLong">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyLong_FromLongLong</code><span class="sig-paren">(</span>PY_LONG_LONG<em> v</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyLong_FromLongLong" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a new <a class="reference internal" href="#c.PyLongObject" title="PyLongObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyLongObject</span></code></a> object from a C <code class="xref c c-type docutils literal notranslate"><span class="pre">long</span> <span class="pre">long</span></code>, or <em>NULL</em>
on failure.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyLong_FromUnsignedLongLong">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyLong_FromUnsignedLongLong</code><span class="sig-paren">(</span>unsigned PY_LONG_LONG<em> v</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyLong_FromUnsignedLongLong" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a new <a class="reference internal" href="#c.PyLongObject" title="PyLongObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyLongObject</span></code></a> object from a C <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">long</span> <span class="pre">long</span></code>,
or <em>NULL</em> on failure.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyLong_FromDouble">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyLong_FromDouble</code><span class="sig-paren">(</span>double<em> v</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyLong_FromDouble" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a new <a class="reference internal" href="#c.PyLongObject" title="PyLongObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyLongObject</span></code></a> object from the integer part of <em>v</em>, or
<em>NULL</em> on failure.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyLong_FromString">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyLong_FromString</code><span class="sig-paren">(</span>char<em> *str</em>, char<em> **pend</em>, int<em> base</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyLong_FromString" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a new <a class="reference internal" href="#c.PyLongObject" title="PyLongObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyLongObject</span></code></a> based on the string value in <em>str</em>, which is
interpreted according to the radix in <em>base</em>. If <em>pend</em> is non-<em>NULL</em>,
<em>*pend</em> will point to the first character in <em>str</em> which follows the
representation of the number. If <em>base</em> is <code class="docutils literal notranslate"><span class="pre">0</span></code>, the radix will be determined
based on the leading characters of <em>str</em>: if <em>str</em> starts with <code class="docutils literal notranslate"><span class="pre">'0x'</span></code> or
<code class="docutils literal notranslate"><span class="pre">'0X'</span></code>, radix 16 will be used; if <em>str</em> starts with <code class="docutils literal notranslate"><span class="pre">'0'</span></code>, radix 8 will be
used; otherwise radix 10 will be used. If <em>base</em> is not <code class="docutils literal notranslate"><span class="pre">0</span></code>, it must be
between <code class="docutils literal notranslate"><span class="pre">2</span></code> and <code class="docutils literal notranslate"><span class="pre">36</span></code>, inclusive. Leading spaces are ignored. If there are
no digits, <a class="reference internal" href="../library/exceptions.html#exceptions.ValueError" title="exceptions.ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> will be raised.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyLong_FromUnicode">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyLong_FromUnicode</code><span class="sig-paren">(</span><a class="reference internal" href="unicode.html#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a><em> *u</em>, Py_ssize_t<em> length</em>, int<em> base</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyLong_FromUnicode" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Convert a sequence of Unicode digits to a Python long integer value. The first
parameter, <em>u</em>, points to the first character of the Unicode string, <em>length</em>
gives the number of characters, and <em>base</em> is the radix for the conversion. The
radix must be in the range [2, 36]; if it is out of range, <a class="reference internal" href="../library/exceptions.html#exceptions.ValueError" title="exceptions.ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a>
will be raised.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.6.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> for <em>length</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyLong_FromVoidPtr">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyLong_FromVoidPtr</code><span class="sig-paren">(</span>void<em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyLong_FromVoidPtr" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Create a Python integer or long integer from the pointer <em>p</em>. The pointer value
can be retrieved from the resulting value using <a class="reference internal" href="#c.PyLong_AsVoidPtr" title="PyLong_AsVoidPtr"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyLong_AsVoidPtr()</span></code></a>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.5.2.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>If the integer is larger than LONG_MAX, a positive long integer is returned.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyLong_AsLong">
long <code class="descname">PyLong_AsLong</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *pylong</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyLong_AsLong" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-2">Return a C <code class="xref c c-type docutils literal notranslate"><span class="pre">long</span></code> representation of the contents of <em>pylong</em>. If
<em>pylong</em> is greater than <code class="xref py py-const docutils literal notranslate"><span class="pre">LONG_MAX</span></code>, an <a class="reference internal" href="../library/exceptions.html#exceptions.OverflowError" title="exceptions.OverflowError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OverflowError</span></code></a> is raised
and <code class="docutils literal notranslate"><span class="pre">-1</span></code> will be returned.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyLong_AsLongAndOverflow">
long <code class="descname">PyLong_AsLongAndOverflow</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *pylong</em>, int<em> *overflow</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyLong_AsLongAndOverflow" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a C <code class="xref c c-type docutils literal notranslate"><span class="pre">long</span></code> representation of the contents of
<em>pylong</em>. If <em>pylong</em> is greater than <code class="xref py py-const docutils literal notranslate"><span class="pre">LONG_MAX</span></code> or less
than <code class="xref py py-const docutils literal notranslate"><span class="pre">LONG_MIN</span></code>, set <em>*overflow</em> to <code class="docutils literal notranslate"><span class="pre">1</span></code> or <code class="docutils literal notranslate"><span class="pre">-1</span></code>,
respectively, and return <code class="docutils literal notranslate"><span class="pre">-1</span></code>; otherwise, set <em>*overflow</em> to
<code class="docutils literal notranslate"><span class="pre">0</span></code>. If any other exception occurs (for example a TypeError or
MemoryError), then <code class="docutils literal notranslate"><span class="pre">-1</span></code> will be returned and <em>*overflow</em> will
be <code class="docutils literal notranslate"><span class="pre">0</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.7.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyLong_AsLongLongAndOverflow">
PY_LONG_LONG <code class="descname">PyLong_AsLongLongAndOverflow</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *pylong</em>, int<em> *overflow</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyLong_AsLongLongAndOverflow" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a C <code class="xref c c-type docutils literal notranslate"><span class="pre">long</span> <span class="pre">long</span></code> representation of the contents of
<em>pylong</em>. If <em>pylong</em> is greater than <code class="xref py py-const docutils literal notranslate"><span class="pre">PY_LLONG_MAX</span></code> or less
than <code class="xref py py-const docutils literal notranslate"><span class="pre">PY_LLONG_MIN</span></code>, set <em>*overflow</em> to <code class="docutils literal notranslate"><span class="pre">1</span></code> or <code class="docutils literal notranslate"><span class="pre">-1</span></code>,
respectively, and return <code class="docutils literal notranslate"><span class="pre">-1</span></code>; otherwise, set <em>*overflow</em> to
<code class="docutils literal notranslate"><span class="pre">0</span></code>. If any other exception occurs (for example a TypeError or
MemoryError), then <code class="docutils literal notranslate"><span class="pre">-1</span></code> will be returned and <em>*overflow</em> will
be <code class="docutils literal notranslate"><span class="pre">0</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.7.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyLong_AsSsize_t">
Py_ssize_t <code class="descname">PyLong_AsSsize_t</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *pylong</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyLong_AsSsize_t" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-3">Return a C <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code> representation of the contents of <em>pylong</em>. If
<em>pylong</em> is greater than <code class="xref py py-const docutils literal notranslate"><span class="pre">PY_SSIZE_T_MAX</span></code>, an <a class="reference internal" href="../library/exceptions.html#exceptions.OverflowError" title="exceptions.OverflowError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OverflowError</span></code></a> is raised
and <code class="docutils literal notranslate"><span class="pre">-1</span></code> will be returned.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyLong_AsUnsignedLong">
unsigned long <code class="descname">PyLong_AsUnsignedLong</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *pylong</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyLong_AsUnsignedLong" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-4">Return a C <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">long</span></code> representation of the contents of <em>pylong</em>.
If <em>pylong</em> is greater than <code class="xref py py-const docutils literal notranslate"><span class="pre">ULONG_MAX</span></code>, an <a class="reference internal" href="../library/exceptions.html#exceptions.OverflowError" title="exceptions.OverflowError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OverflowError</span></code></a> is
raised.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyLong_AsLongLong">
PY_LONG_LONG <code class="descname">PyLong_AsLongLong</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *pylong</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyLong_AsLongLong" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-5">Return a C <code class="xref c c-type docutils literal notranslate"><span class="pre">long</span> <span class="pre">long</span></code> from a Python long integer. If
<em>pylong</em> cannot be represented as a <code class="xref c c-type docutils literal notranslate"><span class="pre">long</span> <span class="pre">long</span></code>, an
<a class="reference internal" href="../library/exceptions.html#exceptions.OverflowError" title="exceptions.OverflowError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OverflowError</span></code></a> is raised and <code class="docutils literal notranslate"><span class="pre">-1</span></code> is returned.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyLong_AsUnsignedLongLong">
unsigned PY_LONG_LONG <code class="descname">PyLong_AsUnsignedLongLong</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *pylong</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyLong_AsUnsignedLongLong" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-6">Return a C <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">long</span> <span class="pre">long</span></code> from a Python long integer. If
<em>pylong</em> cannot be represented as an <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">long</span> <span class="pre">long</span></code>, an
<a class="reference internal" href="../library/exceptions.html#exceptions.OverflowError" title="exceptions.OverflowError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OverflowError</span></code></a> is raised and <code class="docutils literal notranslate"><span class="pre">(unsigned</span> <span class="pre">long</span> <span class="pre">long)-1</span></code> is
returned.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.7: </span>A negative <em>pylong</em> now raises <a class="reference internal" href="../library/exceptions.html#exceptions.OverflowError" title="exceptions.OverflowError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OverflowError</span></code></a>, not
<a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a>.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyLong_AsUnsignedLongMask">
unsigned long <code class="descname">PyLong_AsUnsignedLongMask</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *io</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyLong_AsUnsignedLongMask" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a C <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">long</span></code> from a Python long integer, without checking
for overflow.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.3.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyLong_AsUnsignedLongLongMask">
unsigned PY_LONG_LONG <code class="descname">PyLong_AsUnsignedLongLongMask</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *io</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyLong_AsUnsignedLongLongMask" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a C <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">long</span> <span class="pre">long</span></code> from a Python long integer, without
checking for overflow.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.3.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyLong_AsDouble">
double <code class="descname">PyLong_AsDouble</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *pylong</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyLong_AsDouble" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a C <code class="xref c c-type docutils literal notranslate"><span class="pre">double</span></code> representation of the contents of <em>pylong</em>. If
<em>pylong</em> cannot be approximately represented as a <code class="xref c c-type docutils literal notranslate"><span class="pre">double</span></code>, an
<a class="reference internal" href="../library/exceptions.html#exceptions.OverflowError" title="exceptions.OverflowError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OverflowError</span></code></a> exception is raised and <code class="docutils literal notranslate"><span class="pre">-1.0</span></code> will be returned.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyLong_AsVoidPtr">
void* <code class="descname">PyLong_AsVoidPtr</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *pylong</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyLong_AsVoidPtr" title="Permalink to this definition">¶</a></dt>
<dd><p>Convert a Python integer or long integer <em>pylong</em> to a C <code class="xref c c-type docutils literal notranslate"><span class="pre">void</span></code> pointer.
If <em>pylong</em> cannot be converted, an <a class="reference internal" href="../library/exceptions.html#exceptions.OverflowError" title="exceptions.OverflowError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OverflowError</span></code></a> will be raised. This
is only assured to produce a usable <code class="xref c c-type docutils literal notranslate"><span class="pre">void</span></code> pointer for values created
with <a class="reference internal" href="#c.PyLong_FromVoidPtr" title="PyLong_FromVoidPtr"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyLong_FromVoidPtr()</span></code></a>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.5.2.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>For values outside 0..LONG_MAX, both signed and unsigned integers are accepted.</p>
</div>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="bool.html"
title="previous chapter">Boolean Objects</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="float.html"
title="next chapter">Floating Point Objects</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/long.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="float.html" title="Floating Point Objects"
>next</a> |</li>
<li class="right" >
<a href="bool.html" title="Boolean Objects"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" >Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\S�f�> �> html/c-api/mapping.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Mapping Protocol — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Iterator Protocol" href="iter.html" />
<link rel="prev" title="Sequence Protocol" href="sequence.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/mapping.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="iter.html" title="Iterator Protocol"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="sequence.html" title="Sequence Protocol"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="abstract.html" accesskey="U">Abstract Objects Layer</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="mapping-protocol">
<span id="mapping"></span><h1>Mapping Protocol<a class="headerlink" href="#mapping-protocol" title="Permalink to this headline">¶</a></h1>
<dl class="function">
<dt id="c.PyMapping_Check">
int <code class="descname">PyMapping_Check</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyMapping_Check" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">1</span></code> if the object provides mapping protocol, and <code class="docutils literal notranslate"><span class="pre">0</span></code> otherwise. This
function always succeeds.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyMapping_Size">
Py_ssize_t <code class="descname">PyMapping_Size</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyMapping_Size" title="Permalink to this definition">¶</a></dt>
<dt id="c.PyMapping_Length">
Py_ssize_t <code class="descname">PyMapping_Length</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyMapping_Length" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-0">Returns the number of keys in object <em>o</em> on success, and <code class="docutils literal notranslate"><span class="pre">-1</span></code> on failure. For
objects that do not provide mapping protocol, this is equivalent to the Python
expression <code class="docutils literal notranslate"><span class="pre">len(o)</span></code>.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>These functions returned an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyMapping_DelItemString">
int <code class="descname">PyMapping_DelItemString</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em>, char<em> *key</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyMapping_DelItemString" title="Permalink to this definition">¶</a></dt>
<dd><p>Remove the mapping for object <em>key</em> from the object <em>o</em>. Return <code class="docutils literal notranslate"><span class="pre">-1</span></code> on
failure. This is equivalent to the Python statement <code class="docutils literal notranslate"><span class="pre">del</span> <span class="pre">o[key]</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyMapping_DelItem">
int <code class="descname">PyMapping_DelItem</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *key</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyMapping_DelItem" title="Permalink to this definition">¶</a></dt>
<dd><p>Remove the mapping for object <em>key</em> from the object <em>o</em>. Return <code class="docutils literal notranslate"><span class="pre">-1</span></code> on
failure. This is equivalent to the Python statement <code class="docutils literal notranslate"><span class="pre">del</span> <span class="pre">o[key]</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyMapping_HasKeyString">
int <code class="descname">PyMapping_HasKeyString</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em>, char<em> *key</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyMapping_HasKeyString" title="Permalink to this definition">¶</a></dt>
<dd><p>On success, return <code class="docutils literal notranslate"><span class="pre">1</span></code> if the mapping object has the key <em>key</em> and <code class="docutils literal notranslate"><span class="pre">0</span></code>
otherwise. This is equivalent to <code class="docutils literal notranslate"><span class="pre">o[key]</span></code>, returning <code class="docutils literal notranslate"><span class="pre">True</span></code> on success
and <code class="docutils literal notranslate"><span class="pre">False</span></code> on an exception. This function always succeeds.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyMapping_HasKey">
int <code class="descname">PyMapping_HasKey</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *key</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyMapping_HasKey" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">1</span></code> if the mapping object has the key <em>key</em> and <code class="docutils literal notranslate"><span class="pre">0</span></code> otherwise.
This is equivalent to <code class="docutils literal notranslate"><span class="pre">o[key]</span></code>, returning <code class="docutils literal notranslate"><span class="pre">True</span></code> on success and <code class="docutils literal notranslate"><span class="pre">False</span></code>
on an exception. This function always succeeds.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyMapping_Keys">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyMapping_Keys</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyMapping_Keys" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>On success, return a list of the keys in object <em>o</em>. On failure, return <em>NULL</em>.
This is equivalent to the Python expression <code class="docutils literal notranslate"><span class="pre">o.keys()</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyMapping_Values">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyMapping_Values</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyMapping_Values" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>On success, return a list of the values in object <em>o</em>. On failure, return
<em>NULL</em>. This is equivalent to the Python expression <code class="docutils literal notranslate"><span class="pre">o.values()</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyMapping_Items">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyMapping_Items</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyMapping_Items" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>On success, return a list of the items in object <em>o</em>, where each item is a tuple
containing a key-value pair. On failure, return <em>NULL</em>. This is equivalent to
the Python expression <code class="docutils literal notranslate"><span class="pre">o.items()</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyMapping_GetItemString">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyMapping_GetItemString</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em>, char<em> *key</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyMapping_GetItemString" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return element of <em>o</em> corresponding to the object <em>key</em> or <em>NULL</em> on failure.
This is the equivalent of the Python expression <code class="docutils literal notranslate"><span class="pre">o[key]</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyMapping_SetItemString">
int <code class="descname">PyMapping_SetItemString</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em>, char<em> *key</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *v</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyMapping_SetItemString" title="Permalink to this definition">¶</a></dt>
<dd><p>Map the object <em>key</em> to the value <em>v</em> in object <em>o</em>. Returns <code class="docutils literal notranslate"><span class="pre">-1</span></code> on failure.
This is the equivalent of the Python statement <code class="docutils literal notranslate"><span class="pre">o[key]</span> <span class="pre">=</span> <span class="pre">v</span></code>.</p>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="sequence.html"
title="previous chapter">Sequence Protocol</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="iter.html"
title="next chapter">Iterator Protocol</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/mapping.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="iter.html" title="Iterator Protocol"
>next</a> |</li>
<li class="right" >
<a href="sequence.html" title="Sequence Protocol"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="abstract.html" >Abstract Objects Layer</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\ �c�? �? html/c-api/marshal.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Data marshalling support — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Parsing arguments and building values" href="arg.html" />
<link rel="prev" title="Importing Modules" href="import.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/marshal.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="arg.html" title="Parsing arguments and building values"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="import.html" title="Importing Modules"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="utilities.html" accesskey="U">Utilities</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="data-marshalling-support">
<span id="marshalling-utils"></span><h1>Data marshalling support<a class="headerlink" href="#data-marshalling-support" title="Permalink to this headline">¶</a></h1>
<p>These routines allow C code to work with serialized objects using the same
data format as the <a class="reference internal" href="../library/marshal.html#module-marshal" title="marshal: Convert Python objects to streams of bytes and back (with different constraints)."><code class="xref py py-mod docutils literal notranslate"><span class="pre">marshal</span></code></a> module. There are functions to write data
into the serialization format, and additional functions that can be used to
read the data back. Files used to store marshalled data must be opened in
binary mode.</p>
<p>Numeric values are stored with the least significant byte first.</p>
<p>The module supports two versions of the data format: version <code class="docutils literal notranslate"><span class="pre">0</span></code> is the
historical version, version <code class="docutils literal notranslate"><span class="pre">1</span></code> (new in Python 2.4) shares interned strings in
the file, and upon unmarshalling. Version 2 (new in Python 2.5) uses a binary
format for floating point numbers. <em>Py_MARSHAL_VERSION</em> indicates the current
file format (currently 2).</p>
<dl class="function">
<dt id="c.PyMarshal_WriteLongToFile">
void <code class="descname">PyMarshal_WriteLongToFile</code><span class="sig-paren">(</span>long<em> value</em>, FILE<em> *file</em>, int<em> version</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyMarshal_WriteLongToFile" title="Permalink to this definition">¶</a></dt>
<dd><p>Marshal a <code class="xref c c-type docutils literal notranslate"><span class="pre">long</span></code> integer, <em>value</em>, to <em>file</em>. This will only write
the least-significant 32 bits of <em>value</em>; regardless of the size of the
native <code class="xref c c-type docutils literal notranslate"><span class="pre">long</span></code> type.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.4: </span><em>version</em> indicates the file format.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyMarshal_WriteObjectToFile">
void <code class="descname">PyMarshal_WriteObjectToFile</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *value</em>, FILE<em> *file</em>, int<em> version</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyMarshal_WriteObjectToFile" title="Permalink to this definition">¶</a></dt>
<dd><p>Marshal a Python object, <em>value</em>, to <em>file</em>.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.4: </span><em>version</em> indicates the file format.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyMarshal_WriteObjectToString">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyMarshal_WriteObjectToString</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *value</em>, int<em> version</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyMarshal_WriteObjectToString" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a string object containing the marshalled representation of <em>value</em>.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.4: </span><em>version</em> indicates the file format.</p>
</div>
</dd></dl>
<p>The following functions allow marshalled values to be read back in.</p>
<p>XXX What about error detection? It appears that reading past the end of the
file will always result in a negative numeric value (where that’s relevant),
but it’s not clear that negative values won’t be handled properly when there’s
no error. What’s the right way to tell? Should only non-negative values be
written using these routines?</p>
<dl class="function">
<dt id="c.PyMarshal_ReadLongFromFile">
long <code class="descname">PyMarshal_ReadLongFromFile</code><span class="sig-paren">(</span>FILE<em> *file</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyMarshal_ReadLongFromFile" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a C <code class="xref c c-type docutils literal notranslate"><span class="pre">long</span></code> from the data stream in a <code class="xref c c-type docutils literal notranslate"><span class="pre">FILE*</span></code> opened
for reading. Only a 32-bit value can be read in using this function,
regardless of the native size of <code class="xref c c-type docutils literal notranslate"><span class="pre">long</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyMarshal_ReadShortFromFile">
int <code class="descname">PyMarshal_ReadShortFromFile</code><span class="sig-paren">(</span>FILE<em> *file</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyMarshal_ReadShortFromFile" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a C <code class="xref c c-type docutils literal notranslate"><span class="pre">short</span></code> from the data stream in a <code class="xref c c-type docutils literal notranslate"><span class="pre">FILE*</span></code> opened
for reading. Only a 16-bit value can be read in using this function,
regardless of the native size of <code class="xref c c-type docutils literal notranslate"><span class="pre">short</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyMarshal_ReadObjectFromFile">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyMarshal_ReadObjectFromFile</code><span class="sig-paren">(</span>FILE<em> *file</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyMarshal_ReadObjectFromFile" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a Python object from the data stream in a <code class="xref c c-type docutils literal notranslate"><span class="pre">FILE*</span></code> opened for
reading. On error, sets the appropriate exception (<a class="reference internal" href="../library/exceptions.html#exceptions.EOFError" title="exceptions.EOFError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">EOFError</span></code></a> or
<a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a>) and returns <em>NULL</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyMarshal_ReadLastObjectFromFile">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyMarshal_ReadLastObjectFromFile</code><span class="sig-paren">(</span>FILE<em> *file</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyMarshal_ReadLastObjectFromFile" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a Python object from the data stream in a <code class="xref c c-type docutils literal notranslate"><span class="pre">FILE*</span></code> opened for
reading. Unlike <a class="reference internal" href="#c.PyMarshal_ReadObjectFromFile" title="PyMarshal_ReadObjectFromFile"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyMarshal_ReadObjectFromFile()</span></code></a>, this function
assumes that no further objects will be read from the file, allowing it to
aggressively load file data into memory so that the de-serialization can
operate from data in memory rather than reading a byte at a time from the
file. Only use these variant if you are certain that you won’t be reading
anything else from the file. On error, sets the appropriate exception
(<a class="reference internal" href="../library/exceptions.html#exceptions.EOFError" title="exceptions.EOFError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">EOFError</span></code></a> or <a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a>) and returns <em>NULL</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyMarshal_ReadObjectFromString">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyMarshal_ReadObjectFromString</code><span class="sig-paren">(</span>char<em> *string</em>, Py_ssize_t<em> len</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyMarshal_ReadObjectFromString" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a Python object from the data stream in a character buffer
containing <em>len</em> bytes pointed to by <em>string</em>. On error, sets the
appropriate exception (<a class="reference internal" href="../library/exceptions.html#exceptions.EOFError" title="exceptions.EOFError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">EOFError</span></code></a> or <a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a>) and returns
<em>NULL</em>.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>len</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="import.html"
title="previous chapter">Importing Modules</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="arg.html"
title="next chapter">Parsing arguments and building values</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/marshal.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="arg.html" title="Parsing arguments and building values"
>next</a> |</li>
<li class="right" >
<a href="import.html" title="Importing Modules"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="utilities.html" >Utilities</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\UV� À À html/c-api/memory.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Memory Management — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Object Implementation Support" href="objimpl.html" />
<link rel="prev" title="Initialization, Finalization, and Threads" href="init.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/memory.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="objimpl.html" title="Object Implementation Support"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="init.html" title="Initialization, Finalization, and Threads"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Python/C API Reference Manual</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="memory-management">
<span id="memory"></span><h1>Memory Management<a class="headerlink" href="#memory-management" title="Permalink to this headline">¶</a></h1>
<div class="section" id="overview">
<span id="memoryoverview"></span><h2>Overview<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
<p>Memory management in Python involves a private heap containing all Python
objects and data structures. The management of this private heap is ensured
internally by the <em>Python memory manager</em>. The Python memory manager has
different components which deal with various dynamic storage management aspects,
like sharing, segmentation, preallocation or caching.</p>
<p>At the lowest level, a raw memory allocator ensures that there is enough room in
the private heap for storing all Python-related data by interacting with the
memory manager of the operating system. On top of the raw memory allocator,
several object-specific allocators operate on the same heap and implement
distinct memory management policies adapted to the peculiarities of every object
type. For example, integer objects are managed differently within the heap than
strings, tuples or dictionaries because integers imply different storage
requirements and speed/space tradeoffs. The Python memory manager thus delegates
some of the work to the object-specific allocators, but ensures that the latter
operate within the bounds of the private heap.</p>
<p>It is important to understand that the management of the Python heap is
performed by the interpreter itself and that the user has no control over it,
even if they regularly manipulate object pointers to memory blocks inside that
heap. The allocation of heap space for Python objects and other internal
buffers is performed on demand by the Python memory manager through the Python/C
API functions listed in this document.</p>
<p id="index-0">To avoid memory corruption, extension writers should never try to operate on
Python objects with the functions exported by the C library: <code class="xref c c-func docutils literal notranslate"><span class="pre">malloc()</span></code>,
<code class="xref c c-func docutils literal notranslate"><span class="pre">calloc()</span></code>, <code class="xref c c-func docutils literal notranslate"><span class="pre">realloc()</span></code> and <code class="xref c c-func docutils literal notranslate"><span class="pre">free()</span></code>. This will result in mixed
calls between the C allocator and the Python memory manager with fatal
consequences, because they implement different algorithms and operate on
different heaps. However, one may safely allocate and release memory blocks
with the C library allocator for individual purposes, as shown in the following
example:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">PyObject</span> <span class="o">*</span><span class="n">res</span><span class="p">;</span>
<span class="kt">char</span> <span class="o">*</span><span class="n">buf</span> <span class="o">=</span> <span class="p">(</span><span class="kt">char</span> <span class="o">*</span><span class="p">)</span> <span class="n">malloc</span><span class="p">(</span><span class="n">BUFSIZ</span><span class="p">);</span> <span class="cm">/* for I/O */</span>
<span class="k">if</span> <span class="p">(</span><span class="n">buf</span> <span class="o">==</span> <span class="nb">NULL</span><span class="p">)</span>
<span class="k">return</span> <span class="n">PyErr_NoMemory</span><span class="p">();</span>
<span class="p">...</span><span class="n">Do</span> <span class="n">some</span> <span class="n">I</span><span class="o">/</span><span class="n">O</span> <span class="n">operation</span> <span class="n">involving</span> <span class="n">buf</span><span class="p">...</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">PyString_FromString</span><span class="p">(</span><span class="n">buf</span><span class="p">);</span>
<span class="n">free</span><span class="p">(</span><span class="n">buf</span><span class="p">);</span> <span class="cm">/* malloc'ed */</span>
<span class="k">return</span> <span class="n">res</span><span class="p">;</span>
</pre></div>
</div>
<p>In this example, the memory request for the I/O buffer is handled by the C
library allocator. The Python memory manager is involved only in the allocation
of the string object returned as a result.</p>
<p>In most situations, however, it is recommended to allocate memory from the
Python heap specifically because the latter is under control of the Python
memory manager. For example, this is required when the interpreter is extended
with new object types written in C. Another reason for using the Python heap is
the desire to <em>inform</em> the Python memory manager about the memory needs of the
extension module. Even when the requested memory is used exclusively for
internal, highly-specific purposes, delegating all memory requests to the Python
memory manager causes the interpreter to have a more accurate image of its
memory footprint as a whole. Consequently, under certain circumstances, the
Python memory manager may or may not trigger appropriate actions, like garbage
collection, memory compaction or other preventive procedures. Note that by using
the C library allocator as shown in the previous example, the allocated memory
for the I/O buffer escapes completely the Python memory manager.</p>
</div>
<div class="section" id="memory-interface">
<span id="memoryinterface"></span><h2>Memory Interface<a class="headerlink" href="#memory-interface" title="Permalink to this headline">¶</a></h2>
<p>The following function sets, modeled after the ANSI C standard, but specifying
behavior when requesting zero bytes, are available for allocating and releasing
memory from the Python heap:</p>
<dl class="function">
<dt id="c.PyMem_Malloc">
void* <code class="descname">PyMem_Malloc</code><span class="sig-paren">(</span>size_t<em> n</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyMem_Malloc" title="Permalink to this definition">¶</a></dt>
<dd><p>Allocates <em>n</em> bytes and returns a pointer of type <code class="xref c c-type docutils literal notranslate"><span class="pre">void*</span></code> to the
allocated memory, or <em>NULL</em> if the request fails. Requesting zero bytes returns
a distinct non-<em>NULL</em> pointer if possible, as if <code class="docutils literal notranslate"><span class="pre">PyMem_Malloc(1)</span></code> had
been called instead. The memory will not have been initialized in any way.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyMem_Realloc">
void* <code class="descname">PyMem_Realloc</code><span class="sig-paren">(</span>void<em> *p</em>, size_t<em> n</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyMem_Realloc" title="Permalink to this definition">¶</a></dt>
<dd><p>Resizes the memory block pointed to by <em>p</em> to <em>n</em> bytes. The contents will be
unchanged to the minimum of the old and the new sizes. If <em>p</em> is <em>NULL</em>, the
call is equivalent to <code class="docutils literal notranslate"><span class="pre">PyMem_Malloc(n)</span></code>; else if <em>n</em> is equal to zero,
the memory block is resized but is not freed, and the returned pointer is
non-<em>NULL</em>. Unless <em>p</em> is <em>NULL</em>, it must have been returned by a previous call
to <a class="reference internal" href="#c.PyMem_Malloc" title="PyMem_Malloc"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyMem_Malloc()</span></code></a> or <a class="reference internal" href="#c.PyMem_Realloc" title="PyMem_Realloc"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyMem_Realloc()</span></code></a>. If the request fails,
<a class="reference internal" href="#c.PyMem_Realloc" title="PyMem_Realloc"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyMem_Realloc()</span></code></a> returns <em>NULL</em> and <em>p</em> remains a valid pointer to the
previous memory area.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyMem_Free">
void <code class="descname">PyMem_Free</code><span class="sig-paren">(</span>void<em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyMem_Free" title="Permalink to this definition">¶</a></dt>
<dd><p>Frees the memory block pointed to by <em>p</em>, which must have been returned by a
previous call to <a class="reference internal" href="#c.PyMem_Malloc" title="PyMem_Malloc"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyMem_Malloc()</span></code></a> or <a class="reference internal" href="#c.PyMem_Realloc" title="PyMem_Realloc"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyMem_Realloc()</span></code></a>. Otherwise, or
if <code class="docutils literal notranslate"><span class="pre">PyMem_Free(p)</span></code> has been called before, undefined behavior occurs. If
<em>p</em> is <em>NULL</em>, no operation is performed.</p>
</dd></dl>
<p>The following type-oriented macros are provided for convenience. Note that
<em>TYPE</em> refers to any C type.</p>
<dl class="function">
<dt id="c.PyMem_New">
TYPE* <code class="descname">PyMem_New</code><span class="sig-paren">(</span>TYPE, size_t<em> n</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyMem_New" title="Permalink to this definition">¶</a></dt>
<dd><p>Same as <a class="reference internal" href="#c.PyMem_Malloc" title="PyMem_Malloc"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyMem_Malloc()</span></code></a>, but allocates <code class="docutils literal notranslate"><span class="pre">(n</span> <span class="pre">*</span> <span class="pre">sizeof(TYPE))</span></code> bytes of
memory. Returns a pointer cast to <code class="xref c c-type docutils literal notranslate"><span class="pre">TYPE*</span></code>. The memory will not have
been initialized in any way.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyMem_Resize">
TYPE* <code class="descname">PyMem_Resize</code><span class="sig-paren">(</span>void<em> *p</em>, TYPE, size_t<em> n</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyMem_Resize" title="Permalink to this definition">¶</a></dt>
<dd><p>Same as <a class="reference internal" href="#c.PyMem_Realloc" title="PyMem_Realloc"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyMem_Realloc()</span></code></a>, but the memory block is resized to <code class="docutils literal notranslate"><span class="pre">(n</span> <span class="pre">*</span>
<span class="pre">sizeof(TYPE))</span></code> bytes. Returns a pointer cast to <code class="xref c c-type docutils literal notranslate"><span class="pre">TYPE*</span></code>. On return,
<em>p</em> will be a pointer to the new memory area, or <em>NULL</em> in the event of
failure. This is a C preprocessor macro; p is always reassigned. Save
the original value of p to avoid losing memory when handling errors.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyMem_Del">
void <code class="descname">PyMem_Del</code><span class="sig-paren">(</span>void<em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyMem_Del" title="Permalink to this definition">¶</a></dt>
<dd><p>Same as <a class="reference internal" href="#c.PyMem_Free" title="PyMem_Free"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyMem_Free()</span></code></a>.</p>
</dd></dl>
<p>In addition, the following macro sets are provided for calling the Python memory
allocator directly, without involving the C API functions listed above. However,
note that their use does not preserve binary compatibility across Python
versions and is therefore deprecated in extension modules.</p>
<p><code class="xref c c-func docutils literal notranslate"><span class="pre">PyMem_MALLOC()</span></code>, <code class="xref c c-func docutils literal notranslate"><span class="pre">PyMem_REALLOC()</span></code>, <code class="xref c c-func docutils literal notranslate"><span class="pre">PyMem_FREE()</span></code>.</p>
<p><code class="xref c c-func docutils literal notranslate"><span class="pre">PyMem_NEW()</span></code>, <code class="xref c c-func docutils literal notranslate"><span class="pre">PyMem_RESIZE()</span></code>, <code class="xref c c-func docutils literal notranslate"><span class="pre">PyMem_DEL()</span></code>.</p>
</div>
<div class="section" id="object-allocators">
<h2>Object allocators<a class="headerlink" href="#object-allocators" title="Permalink to this headline">¶</a></h2>
<p>The following function sets, modeled after the ANSI C standard, but specifying
behavior when requesting zero bytes, are available for allocating and releasing
memory from the Python heap.</p>
<p>By default, these functions use <a class="reference internal" href="#pymalloc"><span class="std std-ref">pymalloc memory allocator</span></a>.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">The <a class="reference internal" href="../glossary.html#term-global-interpreter-lock"><span class="xref std std-term">GIL</span></a> must be held when using these
functions.</p>
</div>
<dl class="function">
<dt id="c.PyObject_Malloc">
void* <code class="descname">PyObject_Malloc</code><span class="sig-paren">(</span>size_t<em> n</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_Malloc" title="Permalink to this definition">¶</a></dt>
<dd><p>Allocates <em>n</em> bytes and returns a pointer of type <code class="xref c c-type docutils literal notranslate"><span class="pre">void*</span></code> to the
allocated memory, or <em>NULL</em> if the request fails.</p>
<p>Requesting zero bytes returns a distinct non-<em>NULL</em> pointer if possible, as
if <code class="docutils literal notranslate"><span class="pre">PyObject_Malloc(1)</span></code> had been called instead. The memory will not have
been initialized in any way.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_Realloc">
void* <code class="descname">PyObject_Realloc</code><span class="sig-paren">(</span>void<em> *p</em>, size_t<em> n</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_Realloc" title="Permalink to this definition">¶</a></dt>
<dd><p>Resizes the memory block pointed to by <em>p</em> to <em>n</em> bytes. The contents will be
unchanged to the minimum of the old and the new sizes.</p>
<p>If <em>p</em> is <em>NULL</em>, the call is equivalent to <code class="docutils literal notranslate"><span class="pre">PyObject_Malloc(n)</span></code>; else if <em>n</em>
is equal to zero, the memory block is resized but is not freed, and the
returned pointer is non-<em>NULL</em>.</p>
<p>Unless <em>p</em> is <em>NULL</em>, it must have been returned by a previous call to
<a class="reference internal" href="#c.PyObject_Malloc" title="PyObject_Malloc"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_Malloc()</span></code></a>, <a class="reference internal" href="#c.PyObject_Realloc" title="PyObject_Realloc"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_Realloc()</span></code></a> or <code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_Calloc()</span></code>.</p>
<p>If the request fails, <a class="reference internal" href="#c.PyObject_Realloc" title="PyObject_Realloc"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_Realloc()</span></code></a> returns <em>NULL</em> and <em>p</em> remains
a valid pointer to the previous memory area.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_Free">
void <code class="descname">PyObject_Free</code><span class="sig-paren">(</span>void<em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_Free" title="Permalink to this definition">¶</a></dt>
<dd><p>Frees the memory block pointed to by <em>p</em>, which must have been returned by a
previous call to <a class="reference internal" href="#c.PyObject_Malloc" title="PyObject_Malloc"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_Malloc()</span></code></a>, <a class="reference internal" href="#c.PyObject_Realloc" title="PyObject_Realloc"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_Realloc()</span></code></a> or
<code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_Calloc()</span></code>. Otherwise, or if <code class="docutils literal notranslate"><span class="pre">PyObject_Free(p)</span></code> has been called
before, undefined behavior occurs.</p>
<p>If <em>p</em> is <em>NULL</em>, no operation is performed.</p>
</dd></dl>
<p>In addition, the following macro sets are provided:</p>
<ul class="simple">
<li><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_MALLOC()</span></code>: alias to <a class="reference internal" href="#c.PyObject_Malloc" title="PyObject_Malloc"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_Malloc()</span></code></a></li>
<li><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_REALLOC()</span></code>: alias to <a class="reference internal" href="#c.PyObject_Realloc" title="PyObject_Realloc"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_Realloc()</span></code></a></li>
<li><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_FREE()</span></code>: alias to <a class="reference internal" href="#c.PyObject_Free" title="PyObject_Free"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_Free()</span></code></a></li>
<li><a class="reference internal" href="allocation.html#c.PyObject_Del" title="PyObject_Del"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_Del()</span></code></a>: alias to <a class="reference internal" href="#c.PyObject_Free" title="PyObject_Free"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_Free()</span></code></a></li>
<li><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_DEL()</span></code>: alias to <code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_FREE()</span></code> (so finally an alias
to <a class="reference internal" href="#c.PyObject_Free" title="PyObject_Free"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_Free()</span></code></a>)</li>
</ul>
</div>
<div class="section" id="the-pymalloc-allocator">
<span id="pymalloc"></span><h2>The pymalloc allocator<a class="headerlink" href="#the-pymalloc-allocator" title="Permalink to this headline">¶</a></h2>
<p>Python has a <em>pymalloc</em> allocator optimized for small objects (smaller or equal
to 512 bytes) with a short lifetime. It uses memory mappings called “arenas”
with a fixed size of 256 KiB. It falls back to <code class="xref c c-func docutils literal notranslate"><span class="pre">malloc()</span></code> and
<code class="xref c c-func docutils literal notranslate"><span class="pre">realloc()</span></code> for allocations larger than 512 bytes.</p>
<p><em>pymalloc</em> is the default allocator of <a class="reference internal" href="#c.PyObject_Malloc" title="PyObject_Malloc"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_Malloc()</span></code></a>.</p>
<p>The arena allocator uses the following functions:</p>
<ul class="simple">
<li><code class="xref c c-func docutils literal notranslate"><span class="pre">mmap()</span></code> and <code class="xref c c-func docutils literal notranslate"><span class="pre">munmap()</span></code> if available,</li>
<li><code class="xref c c-func docutils literal notranslate"><span class="pre">malloc()</span></code> and <code class="xref c c-func docutils literal notranslate"><span class="pre">free()</span></code> otherwise.</li>
</ul>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.7.7: </span>The threshold changed from 256 to 512 bytes. The arena allocator now
uses <code class="xref c c-func docutils literal notranslate"><span class="pre">mmap()</span></code> if available.</p>
</div>
</div>
<div class="section" id="examples">
<span id="memoryexamples"></span><h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
<p>Here is the example from section <a class="reference internal" href="#memoryoverview"><span class="std std-ref">Overview</span></a>, rewritten so that the
I/O buffer is allocated from the Python heap by using the first function set:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">PyObject</span> <span class="o">*</span><span class="n">res</span><span class="p">;</span>
<span class="kt">char</span> <span class="o">*</span><span class="n">buf</span> <span class="o">=</span> <span class="p">(</span><span class="kt">char</span> <span class="o">*</span><span class="p">)</span> <span class="n">PyMem_Malloc</span><span class="p">(</span><span class="n">BUFSIZ</span><span class="p">);</span> <span class="cm">/* for I/O */</span>
<span class="k">if</span> <span class="p">(</span><span class="n">buf</span> <span class="o">==</span> <span class="nb">NULL</span><span class="p">)</span>
<span class="k">return</span> <span class="n">PyErr_NoMemory</span><span class="p">();</span>
<span class="cm">/* ...Do some I/O operation involving buf... */</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">PyString_FromString</span><span class="p">(</span><span class="n">buf</span><span class="p">);</span>
<span class="n">PyMem_Free</span><span class="p">(</span><span class="n">buf</span><span class="p">);</span> <span class="cm">/* allocated with PyMem_Malloc */</span>
<span class="k">return</span> <span class="n">res</span><span class="p">;</span>
</pre></div>
</div>
<p>The same code using the type-oriented function set:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">PyObject</span> <span class="o">*</span><span class="n">res</span><span class="p">;</span>
<span class="kt">char</span> <span class="o">*</span><span class="n">buf</span> <span class="o">=</span> <span class="n">PyMem_New</span><span class="p">(</span><span class="kt">char</span><span class="p">,</span> <span class="n">BUFSIZ</span><span class="p">);</span> <span class="cm">/* for I/O */</span>
<span class="k">if</span> <span class="p">(</span><span class="n">buf</span> <span class="o">==</span> <span class="nb">NULL</span><span class="p">)</span>
<span class="k">return</span> <span class="n">PyErr_NoMemory</span><span class="p">();</span>
<span class="cm">/* ...Do some I/O operation involving buf... */</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">PyString_FromString</span><span class="p">(</span><span class="n">buf</span><span class="p">);</span>
<span class="n">PyMem_Del</span><span class="p">(</span><span class="n">buf</span><span class="p">);</span> <span class="cm">/* allocated with PyMem_New */</span>
<span class="k">return</span> <span class="n">res</span><span class="p">;</span>
</pre></div>
</div>
<p>Note that in the two examples above, the buffer is always manipulated via
functions belonging to the same set. Indeed, it is required to use the same
memory API family for a given memory block, so that the risk of mixing different
allocators is reduced to a minimum. The following code sequence contains two
errors, one of which is labeled as <em>fatal</em> because it mixes two different
allocators operating on different heaps.</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">char</span> <span class="o">*</span><span class="n">buf1</span> <span class="o">=</span> <span class="n">PyMem_New</span><span class="p">(</span><span class="kt">char</span><span class="p">,</span> <span class="n">BUFSIZ</span><span class="p">);</span>
<span class="kt">char</span> <span class="o">*</span><span class="n">buf2</span> <span class="o">=</span> <span class="p">(</span><span class="kt">char</span> <span class="o">*</span><span class="p">)</span> <span class="n">malloc</span><span class="p">(</span><span class="n">BUFSIZ</span><span class="p">);</span>
<span class="kt">char</span> <span class="o">*</span><span class="n">buf3</span> <span class="o">=</span> <span class="p">(</span><span class="kt">char</span> <span class="o">*</span><span class="p">)</span> <span class="n">PyMem_Malloc</span><span class="p">(</span><span class="n">BUFSIZ</span><span class="p">);</span>
<span class="p">...</span>
<span class="n">PyMem_Del</span><span class="p">(</span><span class="n">buf3</span><span class="p">);</span> <span class="cm">/* Wrong -- should be PyMem_Free() */</span>
<span class="n">free</span><span class="p">(</span><span class="n">buf2</span><span class="p">);</span> <span class="cm">/* Right -- allocated via malloc() */</span>
<span class="n">free</span><span class="p">(</span><span class="n">buf1</span><span class="p">);</span> <span class="cm">/* Fatal -- should be PyMem_Del() */</span>
</pre></div>
</div>
<p>In addition to the functions aimed at handling raw memory blocks from the Python
heap, objects in Python are allocated and released with <a class="reference internal" href="allocation.html#c.PyObject_New" title="PyObject_New"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_New()</span></code></a>,
<a class="reference internal" href="allocation.html#c.PyObject_NewVar" title="PyObject_NewVar"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_NewVar()</span></code></a> and <a class="reference internal" href="allocation.html#c.PyObject_Del" title="PyObject_Del"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_Del()</span></code></a>.</p>
<p>These will be explained in the next chapter on defining and implementing new
object types in C.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Memory Management</a><ul>
<li><a class="reference internal" href="#overview">Overview</a></li>
<li><a class="reference internal" href="#memory-interface">Memory Interface</a></li>
<li><a class="reference internal" href="#object-allocators">Object allocators</a></li>
<li><a class="reference internal" href="#the-pymalloc-allocator">The pymalloc allocator</a></li>
<li><a class="reference internal" href="#examples">Examples</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="init.html"
title="previous chapter">Initialization, Finalization, and Threads</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="objimpl.html"
title="next chapter">Object Implementation Support</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/memory.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="objimpl.html" title="Object Implementation Support"
>next</a> |</li>
<li class="right" >
<a href="init.html" title="Initialization, Finalization, and Threads"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\ۏ�
&5 &5 html/c-api/method.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Method Objects — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="File Objects" href="file.html" />
<link rel="prev" title="Function Objects" href="function.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/method.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="file.html" title="File Objects"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="function.html" title="Function Objects"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" accesskey="U">Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="method-objects">
<span id="id1"></span><h1>Method Objects<a class="headerlink" href="#method-objects" title="Permalink to this headline">¶</a></h1>
<p id="index-0">There are some useful functions that are useful for working with method objects.</p>
<dl class="var">
<dt id="c.PyMethod_Type">
<a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a> <code class="descname">PyMethod_Type</code><a class="headerlink" href="#c.PyMethod_Type" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-1">This instance of <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyTypeObject</span></code></a> represents the Python method type. This
is exposed to Python programs as <code class="docutils literal notranslate"><span class="pre">types.MethodType</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyMethod_Check">
int <code class="descname">PyMethod_Check</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyMethod_Check" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if <em>o</em> is a method object (has type <a class="reference internal" href="#c.PyMethod_Type" title="PyMethod_Type"><code class="xref c c-data docutils literal notranslate"><span class="pre">PyMethod_Type</span></code></a>). The
parameter must not be <em>NULL</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyMethod_New">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyMethod_New</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *func</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *self</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *class</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyMethod_New" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a new method object, with <em>func</em> being any callable object; this is the
function that will be called when the method is called. If this method should
be bound to an instance, <em>self</em> should be the instance and <em>class</em> should be the
class of <em>self</em>, otherwise <em>self</em> should be <em>NULL</em> and <em>class</em> should be the
class which provides the unbound method..</p>
</dd></dl>
<dl class="function">
<dt id="c.PyMethod_Class">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyMethod_Class</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *meth</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyMethod_Class" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Borrowed reference.</em><p>Return the class object from which the method <em>meth</em> was created; if this was
created from an instance, it will be the class of the instance.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyMethod_GET_CLASS">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyMethod_GET_CLASS</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *meth</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyMethod_GET_CLASS" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Borrowed reference.</em><p>Macro version of <a class="reference internal" href="#c.PyMethod_Class" title="PyMethod_Class"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyMethod_Class()</span></code></a> which avoids error checking.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyMethod_Function">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyMethod_Function</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *meth</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyMethod_Function" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Borrowed reference.</em><p>Return the function object associated with the method <em>meth</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyMethod_GET_FUNCTION">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyMethod_GET_FUNCTION</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *meth</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyMethod_GET_FUNCTION" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Borrowed reference.</em><p>Macro version of <a class="reference internal" href="#c.PyMethod_Function" title="PyMethod_Function"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyMethod_Function()</span></code></a> which avoids error checking.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyMethod_Self">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyMethod_Self</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *meth</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyMethod_Self" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Borrowed reference.</em><p>Return the instance associated with the method <em>meth</em> if it is bound, otherwise
return <em>NULL</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyMethod_GET_SELF">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyMethod_GET_SELF</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *meth</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyMethod_GET_SELF" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Borrowed reference.</em><p>Macro version of <a class="reference internal" href="#c.PyMethod_Self" title="PyMethod_Self"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyMethod_Self()</span></code></a> which avoids error checking.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyMethod_ClearFreeList">
int <code class="descname">PyMethod_ClearFreeList</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyMethod_ClearFreeList" title="Permalink to this definition">¶</a></dt>
<dd><p>Clear the free list. Return the total number of freed items.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="function.html"
title="previous chapter">Function Objects</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="file.html"
title="next chapter">File Objects</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/method.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="file.html" title="File Objects"
>next</a> |</li>
<li class="right" >
<a href="function.html" title="Function Objects"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" >Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\� @��B �B html/c-api/module.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Module Objects — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Iterator Objects" href="iterator.html" />
<link rel="prev" title="File Objects" href="file.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/module.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="iterator.html" title="Iterator Objects"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="file.html" title="File Objects"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" accesskey="U">Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="module-objects">
<span id="moduleobjects"></span><h1>Module Objects<a class="headerlink" href="#module-objects" title="Permalink to this headline">¶</a></h1>
<p id="index-0">There are only a few functions special to module objects.</p>
<dl class="var">
<dt id="c.PyModule_Type">
<a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a> <code class="descname">PyModule_Type</code><a class="headerlink" href="#c.PyModule_Type" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-1">This instance of <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyTypeObject</span></code></a> represents the Python module type. This
is exposed to Python programs as <code class="docutils literal notranslate"><span class="pre">types.ModuleType</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyModule_Check">
int <code class="descname">PyModule_Check</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyModule_Check" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if <em>p</em> is a module object, or a subtype of a module object.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.2: </span>Allowed subtypes to be accepted.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyModule_CheckExact">
int <code class="descname">PyModule_CheckExact</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyModule_CheckExact" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if <em>p</em> is a module object, but not a subtype of
<a class="reference internal" href="#c.PyModule_Type" title="PyModule_Type"><code class="xref c c-data docutils literal notranslate"><span class="pre">PyModule_Type</span></code></a>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyModule_New">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyModule_New</code><span class="sig-paren">(</span>const char<em> *name</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyModule_New" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p id="index-2">Return a new module object with the <code class="xref py py-attr docutils literal notranslate"><span class="pre">__name__</span></code> attribute set to <em>name</em>.
Only the module’s <code class="xref py py-attr docutils literal notranslate"><span class="pre">__doc__</span></code> and <code class="xref py py-attr docutils literal notranslate"><span class="pre">__name__</span></code> attributes are filled in;
the caller is responsible for providing a <code class="xref py py-attr docutils literal notranslate"><span class="pre">__file__</span></code> attribute.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyModule_GetDict">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyModule_GetDict</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *module</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyModule_GetDict" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Borrowed reference.</em><p id="index-3">Return the dictionary object that implements <em>module</em>’s namespace; this object
is the same as the <a class="reference internal" href="../library/stdtypes.html#object.__dict__" title="object.__dict__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__dict__</span></code></a> attribute of the module object. This
function never fails. It is recommended extensions use other
<code class="xref c c-func docutils literal notranslate"><span class="pre">PyModule_*()</span></code> and <code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_*()</span></code> functions rather than directly
manipulate a module’s <a class="reference internal" href="../library/stdtypes.html#object.__dict__" title="object.__dict__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__dict__</span></code></a>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyModule_GetName">
char* <code class="descname">PyModule_GetName</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *module</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyModule_GetName" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-4">Return <em>module</em>’s <code class="xref py py-attr docutils literal notranslate"><span class="pre">__name__</span></code> value. If the module does not provide one,
or if it is not a string, <a class="reference internal" href="../library/exceptions.html#exceptions.SystemError" title="exceptions.SystemError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SystemError</span></code></a> is raised and <em>NULL</em> is returned.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyModule_GetFilename">
char* <code class="descname">PyModule_GetFilename</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *module</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyModule_GetFilename" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-5">Return the name of the file from which <em>module</em> was loaded using <em>module</em>’s
<code class="xref py py-attr docutils literal notranslate"><span class="pre">__file__</span></code> attribute. If this is not defined, or if it is not a string,
raise <a class="reference internal" href="../library/exceptions.html#exceptions.SystemError" title="exceptions.SystemError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SystemError</span></code></a> and return <em>NULL</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyModule_AddObject">
int <code class="descname">PyModule_AddObject</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *module</em>, const char<em> *name</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *value</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyModule_AddObject" title="Permalink to this definition">¶</a></dt>
<dd><p>Add an object to <em>module</em> as <em>name</em>. This is a convenience function which can
be used from the module’s initialization function. This steals a reference to
<em>value</em>. Return <code class="docutils literal notranslate"><span class="pre">-1</span></code> on error, <code class="docutils literal notranslate"><span class="pre">0</span></code> on success.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.0.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyModule_AddIntConstant">
int <code class="descname">PyModule_AddIntConstant</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *module</em>, const char<em> *name</em>, long<em> value</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyModule_AddIntConstant" title="Permalink to this definition">¶</a></dt>
<dd><p>Add an integer constant to <em>module</em> as <em>name</em>. This convenience function can be
used from the module’s initialization function. Return <code class="docutils literal notranslate"><span class="pre">-1</span></code> on error, <code class="docutils literal notranslate"><span class="pre">0</span></code> on
success.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.0.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyModule_AddStringConstant">
int <code class="descname">PyModule_AddStringConstant</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *module</em>, const char<em> *name</em>, const char<em> *value</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyModule_AddStringConstant" title="Permalink to this definition">¶</a></dt>
<dd><p>Add a string constant to <em>module</em> as <em>name</em>. This convenience function can be
used from the module’s initialization function. The string <em>value</em> must be
null-terminated. Return <code class="docutils literal notranslate"><span class="pre">-1</span></code> on error, <code class="docutils literal notranslate"><span class="pre">0</span></code> on success.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.0.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyModule_AddIntMacro">
int <code class="descname">PyModule_AddIntMacro</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *module</em>, macro<span class="sig-paren">)</span><a class="headerlink" href="#c.PyModule_AddIntMacro" title="Permalink to this definition">¶</a></dt>
<dd><p>Add an int constant to <em>module</em>. The name and the value are taken from
<em>macro</em>. For example <code class="docutils literal notranslate"><span class="pre">PyModule_AddIntMacro(module,</span> <span class="pre">AF_INET)</span></code> adds the int
constant <em>AF_INET</em> with the value of <em>AF_INET</em> to <em>module</em>.
Return <code class="docutils literal notranslate"><span class="pre">-1</span></code> on error, <code class="docutils literal notranslate"><span class="pre">0</span></code> on success.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyModule_AddStringMacro">
int <code class="descname">PyModule_AddStringMacro</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *module</em>, macro<span class="sig-paren">)</span><a class="headerlink" href="#c.PyModule_AddStringMacro" title="Permalink to this definition">¶</a></dt>
<dd><blockquote>
<div>Add a string constant to <em>module</em>.</div></blockquote>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="file.html"
title="previous chapter">File Objects</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="iterator.html"
title="next chapter">Iterator Objects</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/module.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="iterator.html" title="Iterator Objects"
>next</a> |</li>
<li class="right" >
<a href="file.html" title="File Objects"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" >Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\��s�[ [ html/c-api/none.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>The None Object — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Plain Integer Objects" href="int.html" />
<link rel="prev" title="Type Objects" href="type.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/none.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="int.html" title="Plain Integer Objects"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="type.html" title="Type Objects"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" accesskey="U">Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="the-none-object">
<span id="noneobject"></span><h1>The <code class="docutils literal notranslate"><span class="pre">None</span></code> Object<a class="headerlink" href="#the-none-object" title="Permalink to this headline">¶</a></h1>
<p id="index-0">Note that the <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyTypeObject</span></code></a> for <code class="docutils literal notranslate"><span class="pre">None</span></code> is not directly exposed in the
Python/C API. Since <code class="docutils literal notranslate"><span class="pre">None</span></code> is a singleton, testing for object identity (using
<code class="docutils literal notranslate"><span class="pre">==</span></code> in C) is sufficient. There is no <code class="xref c c-func docutils literal notranslate"><span class="pre">PyNone_Check()</span></code> function for the
same reason.</p>
<dl class="var">
<dt id="c.Py_None">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">Py_None</code><a class="headerlink" href="#c.Py_None" title="Permalink to this definition">¶</a></dt>
<dd><p>The Python <code class="docutils literal notranslate"><span class="pre">None</span></code> object, denoting lack of value. This object has no methods.
It needs to be treated just like any other object with respect to reference
counts.</p>
</dd></dl>
<dl class="macro">
<dt id="c.Py_RETURN_NONE">
<code class="descname">Py_RETURN_NONE</code><a class="headerlink" href="#c.Py_RETURN_NONE" title="Permalink to this definition">¶</a></dt>
<dd><p>Properly handle returning <a class="reference internal" href="#c.Py_None" title="Py_None"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_None</span></code></a> from within a C function.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="type.html"
title="previous chapter">Type Objects</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="int.html"
title="next chapter">Plain Integer Objects</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/none.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="int.html" title="Plain Integer Objects"
>next</a> |</li>
<li class="right" >
<a href="type.html" title="Type Objects"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" >Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\�9�½ ½ html/c-api/number.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Number Protocol — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Sequence Protocol" href="sequence.html" />
<link rel="prev" title="Object Protocol" href="object.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/number.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="sequence.html" title="Sequence Protocol"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="object.html" title="Object Protocol"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="abstract.html" accesskey="U">Abstract Objects Layer</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="number-protocol">
<span id="number"></span><h1>Number Protocol<a class="headerlink" href="#number-protocol" title="Permalink to this headline">¶</a></h1>
<dl class="function">
<dt id="c.PyNumber_Check">
int <code class="descname">PyNumber_Check</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyNumber_Check" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns <code class="docutils literal notranslate"><span class="pre">1</span></code> if the object <em>o</em> provides numeric protocols, and false otherwise.
This function always succeeds.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyNumber_Add">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyNumber_Add</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o1</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o2</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyNumber_Add" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Returns the result of adding <em>o1</em> and <em>o2</em>, or <em>NULL</em> on failure. This is the
equivalent of the Python expression <code class="docutils literal notranslate"><span class="pre">o1</span> <span class="pre">+</span> <span class="pre">o2</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyNumber_Subtract">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyNumber_Subtract</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o1</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o2</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyNumber_Subtract" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Returns the result of subtracting <em>o2</em> from <em>o1</em>, or <em>NULL</em> on failure. This is
the equivalent of the Python expression <code class="docutils literal notranslate"><span class="pre">o1</span> <span class="pre">-</span> <span class="pre">o2</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyNumber_Multiply">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyNumber_Multiply</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o1</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o2</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyNumber_Multiply" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Returns the result of multiplying <em>o1</em> and <em>o2</em>, or <em>NULL</em> on failure. This is
the equivalent of the Python expression <code class="docutils literal notranslate"><span class="pre">o1</span> <span class="pre">*</span> <span class="pre">o2</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyNumber_Divide">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyNumber_Divide</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o1</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o2</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyNumber_Divide" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Returns the result of dividing <em>o1</em> by <em>o2</em>, or <em>NULL</em> on failure. This is the
equivalent of the Python expression <code class="docutils literal notranslate"><span class="pre">o1</span> <span class="pre">/</span> <span class="pre">o2</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyNumber_FloorDivide">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyNumber_FloorDivide</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o1</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o2</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyNumber_FloorDivide" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return the floor of <em>o1</em> divided by <em>o2</em>, or <em>NULL</em> on failure. This is
equivalent to the “classic” division of integers.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyNumber_TrueDivide">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyNumber_TrueDivide</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o1</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o2</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyNumber_TrueDivide" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a reasonable approximation for the mathematical value of <em>o1</em> divided by
<em>o2</em>, or <em>NULL</em> on failure. The return value is “approximate” because binary
floating point numbers are approximate; it is not possible to represent all real
numbers in base two. This function can return a floating point value when
passed two integers.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyNumber_Remainder">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyNumber_Remainder</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o1</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o2</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyNumber_Remainder" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Returns the remainder of dividing <em>o1</em> by <em>o2</em>, or <em>NULL</em> on failure. This is
the equivalent of the Python expression <code class="docutils literal notranslate"><span class="pre">o1</span> <span class="pre">%</span> <span class="pre">o2</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyNumber_Divmod">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyNumber_Divmod</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o1</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o2</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyNumber_Divmod" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p id="index-0">See the built-in function <a class="reference internal" href="../library/functions.html#divmod" title="divmod"><code class="xref py py-func docutils literal notranslate"><span class="pre">divmod()</span></code></a>. Returns <em>NULL</em> on failure. This is
the equivalent of the Python expression <code class="docutils literal notranslate"><span class="pre">divmod(o1,</span> <span class="pre">o2)</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyNumber_Power">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyNumber_Power</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o1</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o2</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o3</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyNumber_Power" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p id="index-1">See the built-in function <a class="reference internal" href="../library/functions.html#pow" title="pow"><code class="xref py py-func docutils literal notranslate"><span class="pre">pow()</span></code></a>. Returns <em>NULL</em> on failure. This is the
equivalent of the Python expression <code class="docutils literal notranslate"><span class="pre">pow(o1,</span> <span class="pre">o2,</span> <span class="pre">o3)</span></code>, where <em>o3</em> is optional.
If <em>o3</em> is to be ignored, pass <a class="reference internal" href="none.html#c.Py_None" title="Py_None"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_None</span></code></a> in its place (passing <em>NULL</em> for
<em>o3</em> would cause an illegal memory access).</p>
</dd></dl>
<dl class="function">
<dt id="c.PyNumber_Negative">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyNumber_Negative</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyNumber_Negative" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Returns the negation of <em>o</em> on success, or <em>NULL</em> on failure. This is the
equivalent of the Python expression <code class="docutils literal notranslate"><span class="pre">-o</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyNumber_Positive">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyNumber_Positive</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyNumber_Positive" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Returns <em>o</em> on success, or <em>NULL</em> on failure. This is the equivalent of the
Python expression <code class="docutils literal notranslate"><span class="pre">+o</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyNumber_Absolute">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyNumber_Absolute</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyNumber_Absolute" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p id="index-2">Returns the absolute value of <em>o</em>, or <em>NULL</em> on failure. This is the equivalent
of the Python expression <code class="docutils literal notranslate"><span class="pre">abs(o)</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyNumber_Invert">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyNumber_Invert</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyNumber_Invert" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Returns the bitwise negation of <em>o</em> on success, or <em>NULL</em> on failure. This is
the equivalent of the Python expression <code class="docutils literal notranslate"><span class="pre">~o</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyNumber_Lshift">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyNumber_Lshift</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o1</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o2</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyNumber_Lshift" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Returns the result of left shifting <em>o1</em> by <em>o2</em> on success, or <em>NULL</em> on
failure. This is the equivalent of the Python expression <code class="docutils literal notranslate"><span class="pre">o1</span> <span class="pre"><<</span> <span class="pre">o2</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyNumber_Rshift">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyNumber_Rshift</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o1</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o2</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyNumber_Rshift" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Returns the result of right shifting <em>o1</em> by <em>o2</em> on success, or <em>NULL</em> on
failure. This is the equivalent of the Python expression <code class="docutils literal notranslate"><span class="pre">o1</span> <span class="pre">>></span> <span class="pre">o2</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyNumber_And">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyNumber_And</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o1</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o2</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyNumber_And" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Returns the “bitwise and” of <em>o1</em> and <em>o2</em> on success and <em>NULL</em> on failure.
This is the equivalent of the Python expression <code class="docutils literal notranslate"><span class="pre">o1</span> <span class="pre">&</span> <span class="pre">o2</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyNumber_Xor">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyNumber_Xor</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o1</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o2</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyNumber_Xor" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Returns the “bitwise exclusive or” of <em>o1</em> by <em>o2</em> on success, or <em>NULL</em> on
failure. This is the equivalent of the Python expression <code class="docutils literal notranslate"><span class="pre">o1</span> <span class="pre">^</span> <span class="pre">o2</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyNumber_Or">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyNumber_Or</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o1</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o2</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyNumber_Or" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Returns the “bitwise or” of <em>o1</em> and <em>o2</em> on success, or <em>NULL</em> on failure.
This is the equivalent of the Python expression <code class="docutils literal notranslate"><span class="pre">o1</span> <span class="pre">|</span> <span class="pre">o2</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyNumber_InPlaceAdd">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyNumber_InPlaceAdd</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o1</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o2</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyNumber_InPlaceAdd" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Returns the result of adding <em>o1</em> and <em>o2</em>, or <em>NULL</em> on failure. The operation
is done <em>in-place</em> when <em>o1</em> supports it. This is the equivalent of the Python
statement <code class="docutils literal notranslate"><span class="pre">o1</span> <span class="pre">+=</span> <span class="pre">o2</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyNumber_InPlaceSubtract">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyNumber_InPlaceSubtract</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o1</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o2</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyNumber_InPlaceSubtract" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Returns the result of subtracting <em>o2</em> from <em>o1</em>, or <em>NULL</em> on failure. The
operation is done <em>in-place</em> when <em>o1</em> supports it. This is the equivalent of
the Python statement <code class="docutils literal notranslate"><span class="pre">o1</span> <span class="pre">-=</span> <span class="pre">o2</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyNumber_InPlaceMultiply">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyNumber_InPlaceMultiply</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o1</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o2</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyNumber_InPlaceMultiply" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Returns the result of multiplying <em>o1</em> and <em>o2</em>, or <em>NULL</em> on failure. The
operation is done <em>in-place</em> when <em>o1</em> supports it. This is the equivalent of
the Python statement <code class="docutils literal notranslate"><span class="pre">o1</span> <span class="pre">*=</span> <span class="pre">o2</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyNumber_InPlaceDivide">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyNumber_InPlaceDivide</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o1</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o2</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyNumber_InPlaceDivide" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Returns the result of dividing <em>o1</em> by <em>o2</em>, or <em>NULL</em> on failure. The
operation is done <em>in-place</em> when <em>o1</em> supports it. This is the equivalent of
the Python statement <code class="docutils literal notranslate"><span class="pre">o1</span> <span class="pre">/=</span> <span class="pre">o2</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyNumber_InPlaceFloorDivide">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyNumber_InPlaceFloorDivide</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o1</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o2</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyNumber_InPlaceFloorDivide" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Returns the mathematical floor of dividing <em>o1</em> by <em>o2</em>, or <em>NULL</em> on failure.
The operation is done <em>in-place</em> when <em>o1</em> supports it. This is the equivalent
of the Python statement <code class="docutils literal notranslate"><span class="pre">o1</span> <span class="pre">//=</span> <span class="pre">o2</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyNumber_InPlaceTrueDivide">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyNumber_InPlaceTrueDivide</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o1</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o2</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyNumber_InPlaceTrueDivide" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a reasonable approximation for the mathematical value of <em>o1</em> divided by
<em>o2</em>, or <em>NULL</em> on failure. The return value is “approximate” because binary
floating point numbers are approximate; it is not possible to represent all real
numbers in base two. This function can return a floating point value when
passed two integers. The operation is done <em>in-place</em> when <em>o1</em> supports it.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyNumber_InPlaceRemainder">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyNumber_InPlaceRemainder</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o1</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o2</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyNumber_InPlaceRemainder" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Returns the remainder of dividing <em>o1</em> by <em>o2</em>, or <em>NULL</em> on failure. The
operation is done <em>in-place</em> when <em>o1</em> supports it. This is the equivalent of
the Python statement <code class="docutils literal notranslate"><span class="pre">o1</span> <span class="pre">%=</span> <span class="pre">o2</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyNumber_InPlacePower">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyNumber_InPlacePower</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o1</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o2</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o3</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyNumber_InPlacePower" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p id="index-3">See the built-in function <a class="reference internal" href="../library/functions.html#pow" title="pow"><code class="xref py py-func docutils literal notranslate"><span class="pre">pow()</span></code></a>. Returns <em>NULL</em> on failure. The operation
is done <em>in-place</em> when <em>o1</em> supports it. This is the equivalent of the Python
statement <code class="docutils literal notranslate"><span class="pre">o1</span> <span class="pre">**=</span> <span class="pre">o2</span></code> when o3 is <a class="reference internal" href="none.html#c.Py_None" title="Py_None"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_None</span></code></a>, or an in-place variant of
<code class="docutils literal notranslate"><span class="pre">pow(o1,</span> <span class="pre">o2,</span> <span class="pre">o3)</span></code> otherwise. If <em>o3</em> is to be ignored, pass <a class="reference internal" href="none.html#c.Py_None" title="Py_None"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_None</span></code></a>
in its place (passing <em>NULL</em> for <em>o3</em> would cause an illegal memory access).</p>
</dd></dl>
<dl class="function">
<dt id="c.PyNumber_InPlaceLshift">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyNumber_InPlaceLshift</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o1</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o2</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyNumber_InPlaceLshift" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Returns the result of left shifting <em>o1</em> by <em>o2</em> on success, or <em>NULL</em> on
failure. The operation is done <em>in-place</em> when <em>o1</em> supports it. This is the
equivalent of the Python statement <code class="docutils literal notranslate"><span class="pre">o1</span> <span class="pre"><<=</span> <span class="pre">o2</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyNumber_InPlaceRshift">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyNumber_InPlaceRshift</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o1</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o2</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyNumber_InPlaceRshift" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Returns the result of right shifting <em>o1</em> by <em>o2</em> on success, or <em>NULL</em> on
failure. The operation is done <em>in-place</em> when <em>o1</em> supports it. This is the
equivalent of the Python statement <code class="docutils literal notranslate"><span class="pre">o1</span> <span class="pre">>>=</span> <span class="pre">o2</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyNumber_InPlaceAnd">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyNumber_InPlaceAnd</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o1</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o2</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyNumber_InPlaceAnd" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Returns the “bitwise and” of <em>o1</em> and <em>o2</em> on success and <em>NULL</em> on failure. The
operation is done <em>in-place</em> when <em>o1</em> supports it. This is the equivalent of
the Python statement <code class="docutils literal notranslate"><span class="pre">o1</span> <span class="pre">&=</span> <span class="pre">o2</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyNumber_InPlaceXor">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyNumber_InPlaceXor</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o1</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o2</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyNumber_InPlaceXor" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Returns the “bitwise exclusive or” of <em>o1</em> by <em>o2</em> on success, or <em>NULL</em> on
failure. The operation is done <em>in-place</em> when <em>o1</em> supports it. This is the
equivalent of the Python statement <code class="docutils literal notranslate"><span class="pre">o1</span> <span class="pre">^=</span> <span class="pre">o2</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyNumber_InPlaceOr">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyNumber_InPlaceOr</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o1</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o2</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyNumber_InPlaceOr" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Returns the “bitwise or” of <em>o1</em> and <em>o2</em> on success, or <em>NULL</em> on failure. The
operation is done <em>in-place</em> when <em>o1</em> supports it. This is the equivalent of
the Python statement <code class="docutils literal notranslate"><span class="pre">o1</span> <span class="pre">|=</span> <span class="pre">o2</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyNumber_Coerce">
int <code class="descname">PyNumber_Coerce</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> **p1</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> **p2</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyNumber_Coerce" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-4">This function takes the addresses of two variables of type <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject*</span></code></a>.
If the objects pointed to by <code class="docutils literal notranslate"><span class="pre">*p1</span></code> and <code class="docutils literal notranslate"><span class="pre">*p2</span></code> have the same type, increment
their reference count and return <code class="docutils literal notranslate"><span class="pre">0</span></code> (success). If the objects can be
converted to a common numeric type, replace <code class="docutils literal notranslate"><span class="pre">*p1</span></code> and <code class="docutils literal notranslate"><span class="pre">*p2</span></code> by their
converted value (with ‘new’ reference counts), and return <code class="docutils literal notranslate"><span class="pre">0</span></code>. If no
conversion is possible, or if some other error occurs, return <code class="docutils literal notranslate"><span class="pre">-1</span></code> (failure)
and don’t increment the reference counts. The call <code class="docutils literal notranslate"><span class="pre">PyNumber_Coerce(&o1,</span>
<span class="pre">&o2)</span></code> is equivalent to the Python statement <code class="docutils literal notranslate"><span class="pre">o1,</span> <span class="pre">o2</span> <span class="pre">=</span> <span class="pre">coerce(o1,</span> <span class="pre">o2)</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyNumber_CoerceEx">
int <code class="descname">PyNumber_CoerceEx</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> **p1</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> **p2</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyNumber_CoerceEx" title="Permalink to this definition">¶</a></dt>
<dd><p>This function is similar to <a class="reference internal" href="#c.PyNumber_Coerce" title="PyNumber_Coerce"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyNumber_Coerce()</span></code></a>, except that it returns
<code class="docutils literal notranslate"><span class="pre">1</span></code> when the conversion is not possible and when no error is raised.
Reference counts are still not increased in this case.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyNumber_Int">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyNumber_Int</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyNumber_Int" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p id="index-5">Returns the <em>o</em> converted to an integer object on success, or <em>NULL</em> on failure.
If the argument is outside the integer range a long object will be returned
instead. This is the equivalent of the Python expression <code class="docutils literal notranslate"><span class="pre">int(o)</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyNumber_Long">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyNumber_Long</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyNumber_Long" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p id="index-6">Returns the <em>o</em> converted to a long integer object on success, or <em>NULL</em> on
failure. This is the equivalent of the Python expression <code class="docutils literal notranslate"><span class="pre">long(o)</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyNumber_Float">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyNumber_Float</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyNumber_Float" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p id="index-7">Returns the <em>o</em> converted to a float object on success, or <em>NULL</em> on failure.
This is the equivalent of the Python expression <code class="docutils literal notranslate"><span class="pre">float(o)</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyNumber_Index">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyNumber_Index</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyNumber_Index" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns the <em>o</em> converted to a Python int or long on success or <em>NULL</em> with a
<a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> exception raised on failure.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.5.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyNumber_ToBase">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyNumber_ToBase</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *n</em>, int<em> base</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyNumber_ToBase" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns the integer <em>n</em> converted to <em>base</em> as a string with a base
marker of <code class="docutils literal notranslate"><span class="pre">'0b'</span></code>, <code class="docutils literal notranslate"><span class="pre">'0o'</span></code>, or <code class="docutils literal notranslate"><span class="pre">'0x'</span></code> if applicable. When
<em>base</em> is not 2, 8, 10, or 16, the format is <code class="docutils literal notranslate"><span class="pre">'x#num'</span></code> where x is the
base. If <em>n</em> is not an int object, it is converted with
<a class="reference internal" href="#c.PyNumber_Index" title="PyNumber_Index"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyNumber_Index()</span></code></a> first.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyNumber_AsSsize_t">
Py_ssize_t <code class="descname">PyNumber_AsSsize_t</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *exc</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyNumber_AsSsize_t" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns <em>o</em> converted to a Py_ssize_t value if <em>o</em> can be interpreted as an
integer. If <em>o</em> can be converted to a Python int or long but the attempt to
convert to a Py_ssize_t value would raise an <a class="reference internal" href="../library/exceptions.html#exceptions.OverflowError" title="exceptions.OverflowError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OverflowError</span></code></a>, then the
<em>exc</em> argument is the type of exception that will be raised (usually
<a class="reference internal" href="../library/exceptions.html#exceptions.IndexError" title="exceptions.IndexError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">IndexError</span></code></a> or <a class="reference internal" href="../library/exceptions.html#exceptions.OverflowError" title="exceptions.OverflowError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OverflowError</span></code></a>). If <em>exc</em> is <em>NULL</em>, then the
exception is cleared and the value is clipped to <em>PY_SSIZE_T_MIN</em> for a negative
integer or <em>PY_SSIZE_T_MAX</em> for a positive integer.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.5.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyIndex_Check">
int <code class="descname">PyIndex_Check</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyIndex_Check" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns <code class="docutils literal notranslate"><span class="pre">1</span></code> if <em>o</em> is an index integer (has the nb_index slot of the
tp_as_number structure filled in), and <code class="docutils literal notranslate"><span class="pre">0</span></code> otherwise.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.5.</span></p>
</div>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="object.html"
title="previous chapter">Object Protocol</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="sequence.html"
title="next chapter">Sequence Protocol</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/number.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="sequence.html" title="Sequence Protocol"
>next</a> |</li>
<li class="right" >
<a href="object.html" title="Object Protocol"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="abstract.html" >Abstract Objects Layer</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\?�q0 0 html/c-api/objbuffer.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Old Buffer Protocol — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Concrete Objects Layer" href="concrete.html" />
<link rel="prev" title="Iterator Protocol" href="iter.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/objbuffer.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="concrete.html" title="Concrete Objects Layer"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="iter.html" title="Iterator Protocol"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="abstract.html" accesskey="U">Abstract Objects Layer</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="old-buffer-protocol">
<span id="abstract-buffer"></span><h1>Old Buffer Protocol<a class="headerlink" href="#old-buffer-protocol" title="Permalink to this headline">¶</a></h1>
<p>This section describes the legacy buffer protocol, which has been introduced
in Python 1.6. It is still supported but deprecated in the Python 2.x series.
Python 3 introduces a new buffer protocol which fixes weaknesses and
shortcomings of the protocol, and has been backported to Python 2.6. See
<a class="reference internal" href="buffer.html#bufferobjects"><span class="std std-ref">Buffers and Memoryview Objects</span></a> for more information.</p>
<dl class="function">
<dt id="c.PyObject_AsCharBuffer">
int <code class="descname">PyObject_AsCharBuffer</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *obj</em>, const char<em> **buffer</em>, Py_ssize_t<em> *buffer_len</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_AsCharBuffer" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns a pointer to a read-only memory location usable as character-based
input. The <em>obj</em> argument must support the single-segment character buffer
interface. On success, returns <code class="docutils literal notranslate"><span class="pre">0</span></code>, sets <em>buffer</em> to the memory location
and <em>buffer_len</em> to the buffer length. Returns <code class="docutils literal notranslate"><span class="pre">-1</span></code> and sets a
<a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> on error.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.6.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span> <span class="pre">*</span></code> type for <em>buffer_len</em>. This might
require changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_AsReadBuffer">
int <code class="descname">PyObject_AsReadBuffer</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *obj</em>, const void<em> **buffer</em>, Py_ssize_t<em> *buffer_len</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_AsReadBuffer" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns a pointer to a read-only memory location containing arbitrary data.
The <em>obj</em> argument must support the single-segment readable buffer
interface. On success, returns <code class="docutils literal notranslate"><span class="pre">0</span></code>, sets <em>buffer</em> to the memory location
and <em>buffer_len</em> to the buffer length. Returns <code class="docutils literal notranslate"><span class="pre">-1</span></code> and sets a
<a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> on error.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.6.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span> <span class="pre">*</span></code> type for <em>buffer_len</em>. This might
require changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_CheckReadBuffer">
int <code class="descname">PyObject_CheckReadBuffer</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_CheckReadBuffer" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns <code class="docutils literal notranslate"><span class="pre">1</span></code> if <em>o</em> supports the single-segment readable buffer interface.
Otherwise returns <code class="docutils literal notranslate"><span class="pre">0</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_AsWriteBuffer">
int <code class="descname">PyObject_AsWriteBuffer</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *obj</em>, void<em> **buffer</em>, Py_ssize_t<em> *buffer_len</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_AsWriteBuffer" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns a pointer to a writeable memory location. The <em>obj</em> argument must
support the single-segment, character buffer interface. On success,
returns <code class="docutils literal notranslate"><span class="pre">0</span></code>, sets <em>buffer</em> to the memory location and <em>buffer_len</em> to the
buffer length. Returns <code class="docutils literal notranslate"><span class="pre">-1</span></code> and sets a <a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> on error.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.6.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span> <span class="pre">*</span></code> type for <em>buffer_len</em>. This might
require changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="iter.html"
title="previous chapter">Iterator Protocol</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="concrete.html"
title="next chapter">Concrete Objects Layer</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/objbuffer.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="concrete.html" title="Concrete Objects Layer"
>next</a> |</li>
<li class="right" >
<a href="iter.html" title="Iterator Protocol"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="abstract.html" >Abstract Objects Layer</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\���c�� �� html/c-api/object.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Object Protocol — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Number Protocol" href="number.html" />
<link rel="prev" title="Abstract Objects Layer" href="abstract.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/object.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="number.html" title="Number Protocol"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="abstract.html" title="Abstract Objects Layer"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="abstract.html" accesskey="U">Abstract Objects Layer</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="object-protocol">
<span id="object"></span><h1>Object Protocol<a class="headerlink" href="#object-protocol" title="Permalink to this headline">¶</a></h1>
<dl class="function">
<dt id="c.PyObject_Print">
int <code class="descname">PyObject_Print</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em>, FILE<em> *fp</em>, int<em> flags</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_Print" title="Permalink to this definition">¶</a></dt>
<dd><p>Print an object <em>o</em>, on file <em>fp</em>. Returns <code class="docutils literal notranslate"><span class="pre">-1</span></code> on error. The flags argument
is used to enable certain printing options. The only option currently supported
is <code class="xref py py-const docutils literal notranslate"><span class="pre">Py_PRINT_RAW</span></code>; if given, the <a class="reference internal" href="../library/functions.html#str" title="str"><code class="xref py py-func docutils literal notranslate"><span class="pre">str()</span></code></a> of the object is written
instead of the <a class="reference internal" href="../library/functions.html#repr" title="repr"><code class="xref py py-func docutils literal notranslate"><span class="pre">repr()</span></code></a>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_HasAttr">
int <code class="descname">PyObject_HasAttr</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *attr_name</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_HasAttr" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns <code class="docutils literal notranslate"><span class="pre">1</span></code> if <em>o</em> has the attribute <em>attr_name</em>, and <code class="docutils literal notranslate"><span class="pre">0</span></code> otherwise. This
is equivalent to the Python expression <code class="docutils literal notranslate"><span class="pre">hasattr(o,</span> <span class="pre">attr_name)</span></code>. This function
always succeeds.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_HasAttrString">
int <code class="descname">PyObject_HasAttrString</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em>, const char<em> *attr_name</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_HasAttrString" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns <code class="docutils literal notranslate"><span class="pre">1</span></code> if <em>o</em> has the attribute <em>attr_name</em>, and <code class="docutils literal notranslate"><span class="pre">0</span></code> otherwise. This
is equivalent to the Python expression <code class="docutils literal notranslate"><span class="pre">hasattr(o,</span> <span class="pre">attr_name)</span></code>. This function
always succeeds.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_GetAttr">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyObject_GetAttr</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *attr_name</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_GetAttr" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Retrieve an attribute named <em>attr_name</em> from object <em>o</em>. Returns the attribute
value on success, or <em>NULL</em> on failure. This is the equivalent of the Python
expression <code class="docutils literal notranslate"><span class="pre">o.attr_name</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_GetAttrString">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyObject_GetAttrString</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em>, const char<em> *attr_name</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_GetAttrString" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Retrieve an attribute named <em>attr_name</em> from object <em>o</em>. Returns the attribute
value on success, or <em>NULL</em> on failure. This is the equivalent of the Python
expression <code class="docutils literal notranslate"><span class="pre">o.attr_name</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_GenericGetAttr">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyObject_GenericGetAttr</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *name</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_GenericGetAttr" title="Permalink to this definition">¶</a></dt>
<dd><p>Generic attribute getter function that is meant to be put into a type
object’s <code class="docutils literal notranslate"><span class="pre">tp_getattro</span></code> slot. It looks for a descriptor in the dictionary
of classes in the object’s MRO as well as an attribute in the object’s
<a class="reference internal" href="../library/stdtypes.html#object.__dict__" title="object.__dict__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__dict__</span></code></a> (if present). As outlined in <a class="reference internal" href="../reference/datamodel.html#descriptors"><span class="std std-ref">Implementing Descriptors</span></a>,
data descriptors take preference over instance attributes, while non-data
descriptors don’t. Otherwise, an <a class="reference internal" href="../library/exceptions.html#exceptions.AttributeError" title="exceptions.AttributeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">AttributeError</span></code></a> is raised.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_SetAttr">
int <code class="descname">PyObject_SetAttr</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *attr_name</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *v</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_SetAttr" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the value of the attribute named <em>attr_name</em>, for object <em>o</em>, to the value
<em>v</em>. Raise an exception and return <code class="docutils literal notranslate"><span class="pre">-1</span></code> on failure;
return <code class="docutils literal notranslate"><span class="pre">0</span></code> on success. This is the equivalent of the Python statement
<code class="docutils literal notranslate"><span class="pre">o.attr_name</span> <span class="pre">=</span> <span class="pre">v</span></code>.</p>
<p>If <em>v</em> is <em>NULL</em>, the attribute is deleted, however this feature is
deprecated in favour of using <a class="reference internal" href="#c.PyObject_DelAttr" title="PyObject_DelAttr"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_DelAttr()</span></code></a>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_SetAttrString">
int <code class="descname">PyObject_SetAttrString</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em>, const char<em> *attr_name</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *v</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_SetAttrString" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the value of the attribute named <em>attr_name</em>, for object <em>o</em>, to the value
<em>v</em>. Raise an exception and return <code class="docutils literal notranslate"><span class="pre">-1</span></code> on failure;
return <code class="docutils literal notranslate"><span class="pre">0</span></code> on success. This is the equivalent of the Python statement
<code class="docutils literal notranslate"><span class="pre">o.attr_name</span> <span class="pre">=</span> <span class="pre">v</span></code>.</p>
<p>If <em>v</em> is <em>NULL</em>, the attribute is deleted, however this feature is
deprecated in favour of using <a class="reference internal" href="#c.PyObject_DelAttrString" title="PyObject_DelAttrString"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_DelAttrString()</span></code></a>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_GenericSetAttr">
int <code class="descname">PyObject_GenericSetAttr</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *name</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *value</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_GenericSetAttr" title="Permalink to this definition">¶</a></dt>
<dd><p>Generic attribute setter and deleter function that is meant
to be put into a type object’s <a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_setattro" title="PyTypeObject.tp_setattro"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_setattro</span></code></a>
slot. It looks for a data descriptor in the
dictionary of classes in the object’s MRO, and if found it takes preference
over setting or deleting the attribute in the instance dictionary. Otherwise, the
attribute is set or deleted in the object’s <a class="reference internal" href="../library/stdtypes.html#object.__dict__" title="object.__dict__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__dict__</span></code></a> (if present).
On success, <code class="docutils literal notranslate"><span class="pre">0</span></code> is returned, otherwise an <a class="reference internal" href="../library/exceptions.html#exceptions.AttributeError" title="exceptions.AttributeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">AttributeError</span></code></a>
is raised and <code class="docutils literal notranslate"><span class="pre">-1</span></code> is returned.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_DelAttr">
int <code class="descname">PyObject_DelAttr</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *attr_name</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_DelAttr" title="Permalink to this definition">¶</a></dt>
<dd><p>Delete attribute named <em>attr_name</em>, for object <em>o</em>. Returns <code class="docutils literal notranslate"><span class="pre">-1</span></code> on failure.
This is the equivalent of the Python statement <code class="docutils literal notranslate"><span class="pre">del</span> <span class="pre">o.attr_name</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_DelAttrString">
int <code class="descname">PyObject_DelAttrString</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em>, const char<em> *attr_name</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_DelAttrString" title="Permalink to this definition">¶</a></dt>
<dd><p>Delete attribute named <em>attr_name</em>, for object <em>o</em>. Returns <code class="docutils literal notranslate"><span class="pre">-1</span></code> on failure.
This is the equivalent of the Python statement <code class="docutils literal notranslate"><span class="pre">del</span> <span class="pre">o.attr_name</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_RichCompare">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyObject_RichCompare</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o1</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o2</em>, int<em> opid</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_RichCompare" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Compare the values of <em>o1</em> and <em>o2</em> using the operation specified by <em>opid</em>,
which must be one of <code class="xref py py-const docutils literal notranslate"><span class="pre">Py_LT</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">Py_LE</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">Py_EQ</span></code>,
<code class="xref py py-const docutils literal notranslate"><span class="pre">Py_NE</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">Py_GT</span></code>, or <code class="xref py py-const docutils literal notranslate"><span class="pre">Py_GE</span></code>, corresponding to <code class="docutils literal notranslate"><span class="pre"><</span></code>,
<code class="docutils literal notranslate"><span class="pre"><=</span></code>, <code class="docutils literal notranslate"><span class="pre">==</span></code>, <code class="docutils literal notranslate"><span class="pre">!=</span></code>, <code class="docutils literal notranslate"><span class="pre">></span></code>, or <code class="docutils literal notranslate"><span class="pre">>=</span></code> respectively. This is the equivalent of
the Python expression <code class="docutils literal notranslate"><span class="pre">o1</span> <span class="pre">op</span> <span class="pre">o2</span></code>, where <code class="docutils literal notranslate"><span class="pre">op</span></code> is the operator corresponding
to <em>opid</em>. Returns the value of the comparison on success, or <em>NULL</em> on failure.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_RichCompareBool">
int <code class="descname">PyObject_RichCompareBool</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o1</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o2</em>, int<em> opid</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_RichCompareBool" title="Permalink to this definition">¶</a></dt>
<dd><p>Compare the values of <em>o1</em> and <em>o2</em> using the operation specified by <em>opid</em>,
which must be one of <code class="xref py py-const docutils literal notranslate"><span class="pre">Py_LT</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">Py_LE</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">Py_EQ</span></code>,
<code class="xref py py-const docutils literal notranslate"><span class="pre">Py_NE</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">Py_GT</span></code>, or <code class="xref py py-const docutils literal notranslate"><span class="pre">Py_GE</span></code>, corresponding to <code class="docutils literal notranslate"><span class="pre"><</span></code>,
<code class="docutils literal notranslate"><span class="pre"><=</span></code>, <code class="docutils literal notranslate"><span class="pre">==</span></code>, <code class="docutils literal notranslate"><span class="pre">!=</span></code>, <code class="docutils literal notranslate"><span class="pre">></span></code>, or <code class="docutils literal notranslate"><span class="pre">>=</span></code> respectively. Returns <code class="docutils literal notranslate"><span class="pre">-1</span></code> on error,
<code class="docutils literal notranslate"><span class="pre">0</span></code> if the result is false, <code class="docutils literal notranslate"><span class="pre">1</span></code> otherwise. This is the equivalent of the
Python expression <code class="docutils literal notranslate"><span class="pre">o1</span> <span class="pre">op</span> <span class="pre">o2</span></code>, where <code class="docutils literal notranslate"><span class="pre">op</span></code> is the operator corresponding to
<em>opid</em>.</p>
</dd></dl>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If <em>o1</em> and <em>o2</em> are the same object, <a class="reference internal" href="#c.PyObject_RichCompareBool" title="PyObject_RichCompareBool"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_RichCompareBool()</span></code></a>
will always return <code class="docutils literal notranslate"><span class="pre">1</span></code> for <code class="xref py py-const docutils literal notranslate"><span class="pre">Py_EQ</span></code> and <code class="docutils literal notranslate"><span class="pre">0</span></code> for <code class="xref py py-const docutils literal notranslate"><span class="pre">Py_NE</span></code>.</p>
</div>
<dl class="function">
<dt id="c.PyObject_Cmp">
int <code class="descname">PyObject_Cmp</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o1</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o2</em>, int<em> *result</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_Cmp" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-0">Compare the values of <em>o1</em> and <em>o2</em> using a routine provided by <em>o1</em>, if one
exists, otherwise with a routine provided by <em>o2</em>. The result of the comparison
is returned in <em>result</em>. Returns <code class="docutils literal notranslate"><span class="pre">-1</span></code> on failure. This is the equivalent of
the Python statement <code class="docutils literal notranslate"><span class="pre">result</span> <span class="pre">=</span> <span class="pre">cmp(o1,</span> <span class="pre">o2)</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_Compare">
int <code class="descname">PyObject_Compare</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o1</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o2</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_Compare" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-1">Compare the values of <em>o1</em> and <em>o2</em> using a routine provided by <em>o1</em>, if one
exists, otherwise with a routine provided by <em>o2</em>. Returns the result of the
comparison on success. On error, the value returned is undefined; use
<a class="reference internal" href="exceptions.html#c.PyErr_Occurred" title="PyErr_Occurred"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyErr_Occurred()</span></code></a> to detect an error. This is equivalent to the Python
expression <code class="docutils literal notranslate"><span class="pre">cmp(o1,</span> <span class="pre">o2)</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_Repr">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyObject_Repr</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_Repr" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p id="index-2">Compute a string representation of object <em>o</em>. Returns the string
representation on success, <em>NULL</em> on failure. This is the equivalent of the
Python expression <code class="docutils literal notranslate"><span class="pre">repr(o)</span></code>. Called by the <a class="reference internal" href="../library/functions.html#repr" title="repr"><code class="xref py py-func docutils literal notranslate"><span class="pre">repr()</span></code></a> built-in function and
by reverse quotes.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_Str">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyObject_Str</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_Str" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p id="index-3">Compute a string representation of object <em>o</em>. Returns the string
representation on success, <em>NULL</em> on failure. This is the equivalent of the
Python expression <code class="docutils literal notranslate"><span class="pre">str(o)</span></code>. Called by the <a class="reference internal" href="../library/functions.html#str" title="str"><code class="xref py py-func docutils literal notranslate"><span class="pre">str()</span></code></a> built-in function and
by the <a class="reference internal" href="../reference/simple_stmts.html#print"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">print</span></code></a> statement.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_Bytes">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyObject_Bytes</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_Bytes" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-4">Compute a bytes representation of object <em>o</em>. In 2.x, this is just an alias
for <a class="reference internal" href="#c.PyObject_Str" title="PyObject_Str"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_Str()</span></code></a>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_Unicode">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyObject_Unicode</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_Unicode" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p id="index-5">Compute a Unicode string representation of object <em>o</em>. Returns the Unicode
string representation on success, <em>NULL</em> on failure. This is the equivalent of
the Python expression <code class="docutils literal notranslate"><span class="pre">unicode(o)</span></code>. Called by the <a class="reference internal" href="../library/functions.html#unicode" title="unicode"><code class="xref py py-func docutils literal notranslate"><span class="pre">unicode()</span></code></a> built-in
function.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_IsInstance">
int <code class="descname">PyObject_IsInstance</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *inst</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *cls</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_IsInstance" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns <code class="docutils literal notranslate"><span class="pre">1</span></code> if <em>inst</em> is an instance of the class <em>cls</em> or a subclass of
<em>cls</em>, or <code class="docutils literal notranslate"><span class="pre">0</span></code> if not. On error, returns <code class="docutils literal notranslate"><span class="pre">-1</span></code> and sets an exception. If
<em>cls</em> is a type object rather than a class object, <a class="reference internal" href="#c.PyObject_IsInstance" title="PyObject_IsInstance"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_IsInstance()</span></code></a>
returns <code class="docutils literal notranslate"><span class="pre">1</span></code> if <em>inst</em> is of type <em>cls</em>. If <em>cls</em> is a tuple, the check will
be done against every entry in <em>cls</em>. The result will be <code class="docutils literal notranslate"><span class="pre">1</span></code> when at least one
of the checks returns <code class="docutils literal notranslate"><span class="pre">1</span></code>, otherwise it will be <code class="docutils literal notranslate"><span class="pre">0</span></code>. If <em>inst</em> is not a
class instance and <em>cls</em> is neither a type object, nor a class object, nor a
tuple, <em>inst</em> must have a <a class="reference internal" href="../library/stdtypes.html#instance.__class__" title="instance.__class__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__class__</span></code></a> attribute — the
class relationship of the value of that attribute with <em>cls</em> will be used
to determine the result of this function.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.1.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.2: </span>Support for a tuple as the second argument added.</p>
</div>
</dd></dl>
<p>Subclass determination is done in a fairly straightforward way, but includes a
wrinkle that implementors of extensions to the class system may want to be aware
of. If <code class="xref py py-class docutils literal notranslate"><span class="pre">A</span></code> and <code class="xref py py-class docutils literal notranslate"><span class="pre">B</span></code> are class objects, <code class="xref py py-class docutils literal notranslate"><span class="pre">B</span></code> is a subclass of
<code class="xref py py-class docutils literal notranslate"><span class="pre">A</span></code> if it inherits from <code class="xref py py-class docutils literal notranslate"><span class="pre">A</span></code> either directly or indirectly. If
either is not a class object, a more general mechanism is used to determine the
class relationship of the two objects. When testing if <em>B</em> is a subclass of
<em>A</em>, if <em>A</em> is <em>B</em>, <a class="reference internal" href="#c.PyObject_IsSubclass" title="PyObject_IsSubclass"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_IsSubclass()</span></code></a> returns true. If <em>A</em> and <em>B</em>
are different objects, <em>B</em>’s <a class="reference internal" href="../library/stdtypes.html#class.__bases__" title="class.__bases__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__bases__</span></code></a> attribute is searched in
a depth-first fashion for <em>A</em> — the presence of the <a class="reference internal" href="../library/stdtypes.html#class.__bases__" title="class.__bases__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__bases__</span></code></a>
attribute is considered sufficient for this determination.</p>
<dl class="function">
<dt id="c.PyObject_IsSubclass">
int <code class="descname">PyObject_IsSubclass</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *derived</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *cls</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_IsSubclass" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns <code class="docutils literal notranslate"><span class="pre">1</span></code> if the class <em>derived</em> is identical to or derived from the class
<em>cls</em>, otherwise returns <code class="docutils literal notranslate"><span class="pre">0</span></code>. In case of an error, returns <code class="docutils literal notranslate"><span class="pre">-1</span></code>. If <em>cls</em>
is a tuple, the check will be done against every entry in <em>cls</em>. The result will
be <code class="docutils literal notranslate"><span class="pre">1</span></code> when at least one of the checks returns <code class="docutils literal notranslate"><span class="pre">1</span></code>, otherwise it will be
<code class="docutils literal notranslate"><span class="pre">0</span></code>. If either <em>derived</em> or <em>cls</em> is not an actual class object (or tuple),
this function uses the generic algorithm described above.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.1.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.3: </span>Older versions of Python did not support a tuple as the second argument.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyCallable_Check">
int <code class="descname">PyCallable_Check</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCallable_Check" title="Permalink to this definition">¶</a></dt>
<dd><p>Determine if the object <em>o</em> is callable. Return <code class="docutils literal notranslate"><span class="pre">1</span></code> if the object is callable
and <code class="docutils literal notranslate"><span class="pre">0</span></code> otherwise. This function always succeeds.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_Call">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyObject_Call</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *callable_object</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *args</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *kw</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_Call" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p id="index-6">Call a callable Python object <em>callable_object</em>, with arguments given by the
tuple <em>args</em>, and named arguments given by the dictionary <em>kw</em>. If no named
arguments are needed, <em>kw</em> may be <em>NULL</em>. <em>args</em> must not be <em>NULL</em>, use an
empty tuple if no arguments are needed. Returns the result of the call on
success, or <em>NULL</em> on failure. This is the equivalent of the Python expression
<code class="docutils literal notranslate"><span class="pre">apply(callable_object,</span> <span class="pre">args,</span> <span class="pre">kw)</span></code> or <code class="docutils literal notranslate"><span class="pre">callable_object(*args,</span> <span class="pre">**kw)</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_CallObject">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyObject_CallObject</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *callable_object</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *args</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_CallObject" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p id="index-7">Call a callable Python object <em>callable_object</em>, with arguments given by the
tuple <em>args</em>. If no arguments are needed, then <em>args</em> may be <em>NULL</em>. Returns
the result of the call on success, or <em>NULL</em> on failure. This is the equivalent
of the Python expression <code class="docutils literal notranslate"><span class="pre">apply(callable_object,</span> <span class="pre">args)</span></code> or
<code class="docutils literal notranslate"><span class="pre">callable_object(*args)</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_CallFunction">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyObject_CallFunction</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *callable</em>, char<em> *format</em>, ...<span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_CallFunction" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p id="index-8">Call a callable Python object <em>callable</em>, with a variable number of C arguments.
The C arguments are described using a <a class="reference internal" href="arg.html#c.Py_BuildValue" title="Py_BuildValue"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_BuildValue()</span></code></a> style format
string. The format may be <em>NULL</em>, indicating that no arguments are provided.
Returns the result of the call on success, or <em>NULL</em> on failure. This is the
equivalent of the Python expression <code class="docutils literal notranslate"><span class="pre">apply(callable,</span> <span class="pre">args)</span></code> or
<code class="docutils literal notranslate"><span class="pre">callable(*args)</span></code>. Note that if you only pass <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject</span> <span class="pre">*</span></code></a> args,
<a class="reference internal" href="#c.PyObject_CallFunctionObjArgs" title="PyObject_CallFunctionObjArgs"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_CallFunctionObjArgs()</span></code></a> is a faster alternative.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_CallMethod">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyObject_CallMethod</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em>, char<em> *method</em>, char<em> *format</em>, ...<span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_CallMethod" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Call the method named <em>method</em> of object <em>o</em> with a variable number of C
arguments. The C arguments are described by a <a class="reference internal" href="arg.html#c.Py_BuildValue" title="Py_BuildValue"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_BuildValue()</span></code></a> format
string that should produce a tuple. The format may be <em>NULL</em>, indicating that
no arguments are provided. Returns the result of the call on success, or <em>NULL</em>
on failure. This is the equivalent of the Python expression <code class="docutils literal notranslate"><span class="pre">o.method(args)</span></code>.
Note that if you only pass <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject</span> <span class="pre">*</span></code></a> args,
<a class="reference internal" href="#c.PyObject_CallMethodObjArgs" title="PyObject_CallMethodObjArgs"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_CallMethodObjArgs()</span></code></a> is a faster alternative.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_CallFunctionObjArgs">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyObject_CallFunctionObjArgs</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *callable</em>, ..., NULL<span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_CallFunctionObjArgs" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Call a callable Python object <em>callable</em>, with a variable number of
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject*</span></code></a> arguments. The arguments are provided as a variable number
of parameters followed by <em>NULL</em>. Returns the result of the call on success, or
<em>NULL</em> on failure.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_CallMethodObjArgs">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyObject_CallMethodObjArgs</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *name</em>, ..., NULL<span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_CallMethodObjArgs" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Calls a method of the object <em>o</em>, where the name of the method is given as a
Python string object in <em>name</em>. It is called with a variable number of
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject*</span></code></a> arguments. The arguments are provided as a variable number
of parameters followed by <em>NULL</em>. Returns the result of the call on success, or
<em>NULL</em> on failure.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_Hash">
long <code class="descname">PyObject_Hash</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_Hash" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-9">Compute and return the hash value of an object <em>o</em>. On failure, return <code class="docutils literal notranslate"><span class="pre">-1</span></code>.
This is the equivalent of the Python expression <code class="docutils literal notranslate"><span class="pre">hash(o)</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_HashNotImplemented">
long <code class="descname">PyObject_HashNotImplemented</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_HashNotImplemented" title="Permalink to this definition">¶</a></dt>
<dd><p>Set a <a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> indicating that <code class="docutils literal notranslate"><span class="pre">type(o)</span></code> is not hashable and return <code class="docutils literal notranslate"><span class="pre">-1</span></code>.
This function receives special treatment when stored in a <code class="docutils literal notranslate"><span class="pre">tp_hash</span></code> slot,
allowing a type to explicitly indicate to the interpreter that it is not
hashable.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_IsTrue">
int <code class="descname">PyObject_IsTrue</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_IsTrue" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns <code class="docutils literal notranslate"><span class="pre">1</span></code> if the object <em>o</em> is considered to be true, and <code class="docutils literal notranslate"><span class="pre">0</span></code> otherwise.
This is equivalent to the Python expression <code class="docutils literal notranslate"><span class="pre">not</span> <span class="pre">not</span> <span class="pre">o</span></code>. On failure, return
<code class="docutils literal notranslate"><span class="pre">-1</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_Not">
int <code class="descname">PyObject_Not</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_Not" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns <code class="docutils literal notranslate"><span class="pre">0</span></code> if the object <em>o</em> is considered to be true, and <code class="docutils literal notranslate"><span class="pre">1</span></code> otherwise.
This is equivalent to the Python expression <code class="docutils literal notranslate"><span class="pre">not</span> <span class="pre">o</span></code>. On failure, return
<code class="docutils literal notranslate"><span class="pre">-1</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_Type">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyObject_Type</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_Type" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p id="index-10">When <em>o</em> is non-<em>NULL</em>, returns a type object corresponding to the object type
of object <em>o</em>. On failure, raises <a class="reference internal" href="../library/exceptions.html#exceptions.SystemError" title="exceptions.SystemError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SystemError</span></code></a> and returns <em>NULL</em>. This
is equivalent to the Python expression <code class="docutils literal notranslate"><span class="pre">type(o)</span></code>. This function increments the
reference count of the return value. There’s really no reason to use this
function instead of the common expression <code class="docutils literal notranslate"><span class="pre">o->ob_type</span></code>, which returns a
pointer of type <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyTypeObject*</span></code></a>, except when the incremented reference
count is needed.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_TypeCheck">
int <code class="descname">PyObject_TypeCheck</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em>, <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a><em> *type</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_TypeCheck" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if the object <em>o</em> is of type <em>type</em> or a subtype of <em>type</em>. Both
parameters must be non-<em>NULL</em>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_Length">
Py_ssize_t <code class="descname">PyObject_Length</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_Length" title="Permalink to this definition">¶</a></dt>
<dt id="c.PyObject_Size">
Py_ssize_t <code class="descname">PyObject_Size</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_Size" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-11">Return the length of object <em>o</em>. If the object <em>o</em> provides either the sequence
and mapping protocols, the sequence length is returned. On error, <code class="docutils literal notranslate"><span class="pre">-1</span></code> is
returned. This is the equivalent to the Python expression <code class="docutils literal notranslate"><span class="pre">len(o)</span></code>.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>These functions returned an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_GetItem">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyObject_GetItem</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *key</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_GetItem" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return element of <em>o</em> corresponding to the object <em>key</em> or <em>NULL</em> on failure.
This is the equivalent of the Python expression <code class="docutils literal notranslate"><span class="pre">o[key]</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_SetItem">
int <code class="descname">PyObject_SetItem</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *key</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *v</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_SetItem" title="Permalink to this definition">¶</a></dt>
<dd><p>Map the object <em>key</em> to the value <em>v</em>. Raise an exception and
return <code class="docutils literal notranslate"><span class="pre">-1</span></code> on failure; return <code class="docutils literal notranslate"><span class="pre">0</span></code> on success. This is the
equivalent of the Python statement <code class="docutils literal notranslate"><span class="pre">o[key]</span> <span class="pre">=</span> <span class="pre">v</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_DelItem">
int <code class="descname">PyObject_DelItem</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *key</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_DelItem" title="Permalink to this definition">¶</a></dt>
<dd><p>Delete the mapping for <em>key</em> from <em>o</em>. Returns <code class="docutils literal notranslate"><span class="pre">-1</span></code> on failure. This is the
equivalent of the Python statement <code class="docutils literal notranslate"><span class="pre">del</span> <span class="pre">o[key]</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_AsFileDescriptor">
int <code class="descname">PyObject_AsFileDescriptor</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_AsFileDescriptor" title="Permalink to this definition">¶</a></dt>
<dd><p>Derives a file descriptor from a Python object. If the object is an integer or
long integer, its value is returned. If not, the object’s <code class="xref py py-meth docutils literal notranslate"><span class="pre">fileno()</span></code> method
is called if it exists; the method must return an integer or long integer, which
is returned as the file descriptor value. Returns <code class="docutils literal notranslate"><span class="pre">-1</span></code> on failure.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_Dir">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyObject_Dir</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_Dir" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>This is equivalent to the Python expression <code class="docutils literal notranslate"><span class="pre">dir(o)</span></code>, returning a (possibly
empty) list of strings appropriate for the object argument, or <em>NULL</em> if there
was an error. If the argument is <em>NULL</em>, this is like the Python <code class="docutils literal notranslate"><span class="pre">dir()</span></code>,
returning the names of the current locals; in this case, if no execution frame
is active then <em>NULL</em> is returned but <a class="reference internal" href="exceptions.html#c.PyErr_Occurred" title="PyErr_Occurred"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyErr_Occurred()</span></code></a> will return false.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_GetIter">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyObject_GetIter</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_GetIter" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>This is equivalent to the Python expression <code class="docutils literal notranslate"><span class="pre">iter(o)</span></code>. It returns a new
iterator for the object argument, or the object itself if the object is already
an iterator. Raises <a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> and returns <em>NULL</em> if the object cannot be
iterated.</p>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="abstract.html"
title="previous chapter">Abstract Objects Layer</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="number.html"
title="next chapter">Number Protocol</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/object.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="number.html" title="Number Protocol"
>next</a> |</li>
<li class="right" >
<a href="abstract.html" title="Abstract Objects Layer"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="abstract.html" >Abstract Objects Layer</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\��
Q Q html/c-api/objimpl.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Object Implementation Support — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Allocating Objects on the Heap" href="allocation.html" />
<link rel="prev" title="Memory Management" href="memory.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/objimpl.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="allocation.html" title="Allocating Objects on the Heap"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="memory.html" title="Memory Management"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Python/C API Reference Manual</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="object-implementation-support">
<span id="newtypes"></span><h1>Object Implementation Support<a class="headerlink" href="#object-implementation-support" title="Permalink to this headline">¶</a></h1>
<p>This chapter describes the functions, types, and macros used when defining new
object types.</p>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="allocation.html">Allocating Objects on the Heap</a></li>
<li class="toctree-l1"><a class="reference internal" href="structures.html">Common Object Structures</a></li>
<li class="toctree-l1"><a class="reference internal" href="typeobj.html">Type Objects</a></li>
<li class="toctree-l1"><a class="reference internal" href="typeobj.html#number-object-structures">Number Object Structures</a></li>
<li class="toctree-l1"><a class="reference internal" href="typeobj.html#mapping-object-structures">Mapping Object Structures</a></li>
<li class="toctree-l1"><a class="reference internal" href="typeobj.html#sequence-object-structures">Sequence Object Structures</a></li>
<li class="toctree-l1"><a class="reference internal" href="typeobj.html#buffer-object-structures">Buffer Object Structures</a></li>
<li class="toctree-l1"><a class="reference internal" href="gcsupport.html">Supporting Cyclic Garbage Collection</a></li>
</ul>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="memory.html"
title="previous chapter">Memory Management</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="allocation.html"
title="next chapter">Allocating Objects on the Heap</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/objimpl.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="allocation.html" title="Allocating Objects on the Heap"
>next</a> |</li>
<li class="right" >
<a href="memory.html" title="Memory Management"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\'S�Z,2 ,2 html/c-api/refcounting.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Reference Counting — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Exception Handling" href="exceptions.html" />
<link rel="prev" title="The Very High Level Layer" href="veryhigh.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/refcounting.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="exceptions.html" title="Exception Handling"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="veryhigh.html" title="The Very High Level Layer"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Python/C API Reference Manual</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="reference-counting">
<span id="countingrefs"></span><h1>Reference Counting<a class="headerlink" href="#reference-counting" title="Permalink to this headline">¶</a></h1>
<p>The macros in this section are used for managing reference counts of Python
objects.</p>
<dl class="function">
<dt id="c.Py_INCREF">
void <code class="descname">Py_INCREF</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_INCREF" title="Permalink to this definition">¶</a></dt>
<dd><p>Increment the reference count for object <em>o</em>. The object must not be <em>NULL</em>; if
you aren’t sure that it isn’t <em>NULL</em>, use <a class="reference internal" href="#c.Py_XINCREF" title="Py_XINCREF"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_XINCREF()</span></code></a>.</p>
</dd></dl>
<dl class="function">
<dt id="c.Py_XINCREF">
void <code class="descname">Py_XINCREF</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_XINCREF" title="Permalink to this definition">¶</a></dt>
<dd><p>Increment the reference count for object <em>o</em>. The object may be <em>NULL</em>, in
which case the macro has no effect.</p>
</dd></dl>
<dl class="function">
<dt id="c.Py_DECREF">
void <code class="descname">Py_DECREF</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_DECREF" title="Permalink to this definition">¶</a></dt>
<dd><p>Decrement the reference count for object <em>o</em>. The object must not be <em>NULL</em>; if
you aren’t sure that it isn’t <em>NULL</em>, use <a class="reference internal" href="#c.Py_XDECREF" title="Py_XDECREF"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_XDECREF()</span></code></a>. If the reference
count reaches zero, the object’s type’s deallocation function (which must not be
<em>NULL</em>) is invoked.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">The deallocation function can cause arbitrary Python code to be invoked (e.g.
when a class instance with a <a class="reference internal" href="../reference/datamodel.html#object.__del__" title="object.__del__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__del__()</span></code></a> method is deallocated). While
exceptions in such code are not propagated, the executed code has free access to
all Python global variables. This means that any object that is reachable from
a global variable should be in a consistent state before <a class="reference internal" href="#c.Py_DECREF" title="Py_DECREF"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_DECREF()</span></code></a> is
invoked. For example, code to delete an object from a list should copy a
reference to the deleted object in a temporary variable, update the list data
structure, and then call <a class="reference internal" href="#c.Py_DECREF" title="Py_DECREF"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_DECREF()</span></code></a> for the temporary variable.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.Py_XDECREF">
void <code class="descname">Py_XDECREF</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_XDECREF" title="Permalink to this definition">¶</a></dt>
<dd><p>Decrement the reference count for object <em>o</em>. The object may be <em>NULL</em>, in
which case the macro has no effect; otherwise the effect is the same as for
<a class="reference internal" href="#c.Py_DECREF" title="Py_DECREF"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_DECREF()</span></code></a>, and the same warning applies.</p>
</dd></dl>
<dl class="function">
<dt id="c.Py_CLEAR">
void <code class="descname">Py_CLEAR</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_CLEAR" title="Permalink to this definition">¶</a></dt>
<dd><p>Decrement the reference count for object <em>o</em>. The object may be <em>NULL</em>, in
which case the macro has no effect; otherwise the effect is the same as for
<a class="reference internal" href="#c.Py_DECREF" title="Py_DECREF"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_DECREF()</span></code></a>, except that the argument is also set to <em>NULL</em>. The warning
for <a class="reference internal" href="#c.Py_DECREF" title="Py_DECREF"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_DECREF()</span></code></a> does not apply with respect to the object passed because
the macro carefully uses a temporary variable and sets the argument to <em>NULL</em>
before decrementing its reference count.</p>
<p>It is a good idea to use this macro whenever decrementing the value of a
variable that might be traversed during garbage collection.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
</dd></dl>
<p>The following functions are for runtime dynamic embedding of Python:
<code class="docutils literal notranslate"><span class="pre">Py_IncRef(PyObject</span> <span class="pre">*o)</span></code>, <code class="docutils literal notranslate"><span class="pre">Py_DecRef(PyObject</span> <span class="pre">*o)</span></code>. They are
simply exported function versions of <a class="reference internal" href="#c.Py_XINCREF" title="Py_XINCREF"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_XINCREF()</span></code></a> and
<a class="reference internal" href="#c.Py_XDECREF" title="Py_XDECREF"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_XDECREF()</span></code></a>, respectively.</p>
<p>The following functions or macros are only for use within the interpreter core:
<code class="xref c c-func docutils literal notranslate"><span class="pre">_Py_Dealloc()</span></code>, <code class="xref c c-func docutils literal notranslate"><span class="pre">_Py_ForgetReference()</span></code>, <code class="xref c c-func docutils literal notranslate"><span class="pre">_Py_NewReference()</span></code>,
as well as the global variable <code class="xref c c-data docutils literal notranslate"><span class="pre">_Py_RefTotal</span></code>.</p>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="veryhigh.html"
title="previous chapter">The Very High Level Layer</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="exceptions.html"
title="next chapter">Exception Handling</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/refcounting.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="exceptions.html" title="Exception Handling"
>next</a> |</li>
<li class="right" >
<a href="veryhigh.html" title="The Very High Level Layer"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\_dz��) �) html/c-api/reflection.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Reflection — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Codec registry and support functions" href="codec.html" />
<link rel="prev" title="String conversion and formatting" href="conversion.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/reflection.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="codec.html" title="Codec registry and support functions"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="conversion.html" title="String conversion and formatting"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="utilities.html" accesskey="U">Utilities</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="reflection">
<span id="id1"></span><h1>Reflection<a class="headerlink" href="#reflection" title="Permalink to this headline">¶</a></h1>
<dl class="function">
<dt id="c.PyEval_GetBuiltins">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyEval_GetBuiltins</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyEval_GetBuiltins" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Borrowed reference.</em><p>Return a dictionary of the builtins in the current execution frame,
or the interpreter of the thread state if no frame is currently executing.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyEval_GetLocals">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyEval_GetLocals</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyEval_GetLocals" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Borrowed reference.</em><p>Return a dictionary of the local variables in the current execution frame,
or <em>NULL</em> if no frame is currently executing.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyEval_GetGlobals">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyEval_GetGlobals</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyEval_GetGlobals" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Borrowed reference.</em><p>Return a dictionary of the global variables in the current execution frame,
or <em>NULL</em> if no frame is currently executing.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyEval_GetFrame">
PyFrameObject* <code class="descname">PyEval_GetFrame</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyEval_GetFrame" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Borrowed reference.</em><p>Return the current thread state’s frame, which is <em>NULL</em> if no frame is
currently executing.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyFrame_GetLineNumber">
int <code class="descname">PyFrame_GetLineNumber</code><span class="sig-paren">(</span>PyFrameObject<em> *frame</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFrame_GetLineNumber" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the line number that <em>frame</em> is currently executing.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyEval_GetRestricted">
int <code class="descname">PyEval_GetRestricted</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyEval_GetRestricted" title="Permalink to this definition">¶</a></dt>
<dd><p>If there is a current frame and it is executing in restricted mode, return true,
otherwise false.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyEval_GetFuncName">
const char* <code class="descname">PyEval_GetFuncName</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *func</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyEval_GetFuncName" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the name of <em>func</em> if it is a function, class or instance object, else the
name of <em>func</em>s type.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyEval_GetFuncDesc">
const char* <code class="descname">PyEval_GetFuncDesc</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *func</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyEval_GetFuncDesc" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a description string, depending on the type of <em>func</em>.
Return values include “()” for functions and methods, ” constructor”,
” instance”, and ” object”. Concatenated with the result of
<a class="reference internal" href="#c.PyEval_GetFuncName" title="PyEval_GetFuncName"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyEval_GetFuncName()</span></code></a>, the result will be a description of
<em>func</em>.</p>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="conversion.html"
title="previous chapter">String conversion and formatting</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="codec.html"
title="next chapter">Codec registry and support functions</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/reflection.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="codec.html" title="Codec registry and support functions"
>next</a> |</li>
<li class="right" >
<a href="conversion.html" title="String conversion and formatting"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="utilities.html" >Utilities</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\�c$D~ D~ html/c-api/sequence.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Sequence Protocol — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Mapping Protocol" href="mapping.html" />
<link rel="prev" title="Number Protocol" href="number.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/sequence.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="mapping.html" title="Mapping Protocol"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="number.html" title="Number Protocol"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="abstract.html" accesskey="U">Abstract Objects Layer</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="sequence-protocol">
<span id="sequence"></span><h1>Sequence Protocol<a class="headerlink" href="#sequence-protocol" title="Permalink to this headline">¶</a></h1>
<dl class="function">
<dt id="c.PySequence_Check">
int <code class="descname">PySequence_Check</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySequence_Check" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">1</span></code> if the object provides sequence protocol, and <code class="docutils literal notranslate"><span class="pre">0</span></code> otherwise.
This function always succeeds.</p>
</dd></dl>
<dl class="function">
<dt id="c.PySequence_Size">
Py_ssize_t <code class="descname">PySequence_Size</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySequence_Size" title="Permalink to this definition">¶</a></dt>
<dt id="c.PySequence_Length">
Py_ssize_t <code class="descname">PySequence_Length</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySequence_Length" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-0">Returns the number of objects in sequence <em>o</em> on success, and <code class="docutils literal notranslate"><span class="pre">-1</span></code> on
failure. This is equivalent to the Python expression <code class="docutils literal notranslate"><span class="pre">len(o)</span></code>.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>These functions returned an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PySequence_Concat">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PySequence_Concat</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o1</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o2</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySequence_Concat" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return the concatenation of <em>o1</em> and <em>o2</em> on success, and <em>NULL</em> on failure.
This is the equivalent of the Python expression <code class="docutils literal notranslate"><span class="pre">o1</span> <span class="pre">+</span> <span class="pre">o2</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PySequence_Repeat">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PySequence_Repeat</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em>, Py_ssize_t<em> count</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySequence_Repeat" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return the result of repeating sequence object <em>o</em> <em>count</em> times, or <em>NULL</em> on
failure. This is the equivalent of the Python expression <code class="docutils literal notranslate"><span class="pre">o</span> <span class="pre">*</span> <span class="pre">count</span></code>.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>count</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PySequence_InPlaceConcat">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PySequence_InPlaceConcat</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o1</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o2</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySequence_InPlaceConcat" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return the concatenation of <em>o1</em> and <em>o2</em> on success, and <em>NULL</em> on failure.
The operation is done <em>in-place</em> when <em>o1</em> supports it. This is the equivalent
of the Python expression <code class="docutils literal notranslate"><span class="pre">o1</span> <span class="pre">+=</span> <span class="pre">o2</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PySequence_InPlaceRepeat">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PySequence_InPlaceRepeat</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em>, Py_ssize_t<em> count</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySequence_InPlaceRepeat" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return the result of repeating sequence object <em>o</em> <em>count</em> times, or <em>NULL</em> on
failure. The operation is done <em>in-place</em> when <em>o</em> supports it. This is the
equivalent of the Python expression <code class="docutils literal notranslate"><span class="pre">o</span> <span class="pre">*=</span> <span class="pre">count</span></code>.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>count</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PySequence_GetItem">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PySequence_GetItem</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em>, Py_ssize_t<em> i</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySequence_GetItem" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return the <em>i</em>th element of <em>o</em>, or <em>NULL</em> on failure. This is the equivalent of
the Python expression <code class="docutils literal notranslate"><span class="pre">o[i]</span></code>.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>i</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PySequence_GetSlice">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PySequence_GetSlice</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em>, Py_ssize_t<em> i1</em>, Py_ssize_t<em> i2</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySequence_GetSlice" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return the slice of sequence object <em>o</em> between <em>i1</em> and <em>i2</em>, or <em>NULL</em> on
failure. This is the equivalent of the Python expression <code class="docutils literal notranslate"><span class="pre">o[i1:i2]</span></code>.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>i1</em> and <em>i2</em>. This might
require changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PySequence_SetItem">
int <code class="descname">PySequence_SetItem</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em>, Py_ssize_t<em> i</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *v</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySequence_SetItem" title="Permalink to this definition">¶</a></dt>
<dd><p>Assign object <em>v</em> to the <em>i</em>th element of <em>o</em>. Raise an exception
and return <code class="docutils literal notranslate"><span class="pre">-1</span></code> on failure; return <code class="docutils literal notranslate"><span class="pre">0</span></code> on success. This
is the equivalent of the Python statement <code class="docutils literal notranslate"><span class="pre">o[i]</span> <span class="pre">=</span> <span class="pre">v</span></code>. This function <em>does
not</em> steal a reference to <em>v</em>.</p>
<p>If <em>v</em> is <em>NULL</em>, the element is deleted, however this feature is
deprecated in favour of using <a class="reference internal" href="#c.PySequence_DelItem" title="PySequence_DelItem"><code class="xref c c-func docutils literal notranslate"><span class="pre">PySequence_DelItem()</span></code></a>.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>i</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PySequence_DelItem">
int <code class="descname">PySequence_DelItem</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em>, Py_ssize_t<em> i</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySequence_DelItem" title="Permalink to this definition">¶</a></dt>
<dd><p>Delete the <em>i</em>th element of object <em>o</em>. Returns <code class="docutils literal notranslate"><span class="pre">-1</span></code> on failure. This is the
equivalent of the Python statement <code class="docutils literal notranslate"><span class="pre">del</span> <span class="pre">o[i]</span></code>.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>i</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PySequence_SetSlice">
int <code class="descname">PySequence_SetSlice</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em>, Py_ssize_t<em> i1</em>, Py_ssize_t<em> i2</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *v</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySequence_SetSlice" title="Permalink to this definition">¶</a></dt>
<dd><p>Assign the sequence object <em>v</em> to the slice in sequence object <em>o</em> from <em>i1</em> to
<em>i2</em>. Raise an exception and return <code class="docutils literal notranslate"><span class="pre">-1</span></code> on failure; return <code class="docutils literal notranslate"><span class="pre">0</span></code> on success.
This is the equivalent of the Python statement <code class="docutils literal notranslate"><span class="pre">o[i1:i2]</span> <span class="pre">=</span> <span class="pre">v</span></code>.</p>
<p>If <em>v</em> is <em>NULL</em>, the slice is deleted, however this feature is
deprecated in favour of using <a class="reference internal" href="#c.PySequence_DelSlice" title="PySequence_DelSlice"><code class="xref c c-func docutils literal notranslate"><span class="pre">PySequence_DelSlice()</span></code></a>.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>i1</em> and <em>i2</em>. This might
require changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PySequence_DelSlice">
int <code class="descname">PySequence_DelSlice</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em>, Py_ssize_t<em> i1</em>, Py_ssize_t<em> i2</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySequence_DelSlice" title="Permalink to this definition">¶</a></dt>
<dd><p>Delete the slice in sequence object <em>o</em> from <em>i1</em> to <em>i2</em>. Returns <code class="docutils literal notranslate"><span class="pre">-1</span></code> on
failure. This is the equivalent of the Python statement <code class="docutils literal notranslate"><span class="pre">del</span> <span class="pre">o[i1:i2]</span></code>.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>i1</em> and <em>i2</em>. This might
require changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PySequence_Count">
Py_ssize_t <code class="descname">PySequence_Count</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *value</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySequence_Count" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the number of occurrences of <em>value</em> in <em>o</em>, that is, return the number
of keys for which <code class="docutils literal notranslate"><span class="pre">o[key]</span> <span class="pre">==</span> <span class="pre">value</span></code>. On failure, return <code class="docutils literal notranslate"><span class="pre">-1</span></code>. This is
equivalent to the Python expression <code class="docutils literal notranslate"><span class="pre">o.count(value)</span></code>.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function returned an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type. This might require changes
in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PySequence_Contains">
int <code class="descname">PySequence_Contains</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *value</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySequence_Contains" title="Permalink to this definition">¶</a></dt>
<dd><p>Determine if <em>o</em> contains <em>value</em>. If an item in <em>o</em> is equal to <em>value</em>,
return <code class="docutils literal notranslate"><span class="pre">1</span></code>, otherwise return <code class="docutils literal notranslate"><span class="pre">0</span></code>. On error, return <code class="docutils literal notranslate"><span class="pre">-1</span></code>. This is
equivalent to the Python expression <code class="docutils literal notranslate"><span class="pre">value</span> <span class="pre">in</span> <span class="pre">o</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PySequence_Index">
Py_ssize_t <code class="descname">PySequence_Index</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *value</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySequence_Index" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the first index <em>i</em> for which <code class="docutils literal notranslate"><span class="pre">o[i]</span> <span class="pre">==</span> <span class="pre">value</span></code>. On error, return
<code class="docutils literal notranslate"><span class="pre">-1</span></code>. This is equivalent to the Python expression <code class="docutils literal notranslate"><span class="pre">o.index(value)</span></code>.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function returned an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type. This might require changes
in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PySequence_List">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PySequence_List</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySequence_List" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a list object with the same contents as the arbitrary sequence <em>o</em>. The
returned list is guaranteed to be new.</p>
</dd></dl>
<dl class="function">
<dt id="c.PySequence_Tuple">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PySequence_Tuple</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySequence_Tuple" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p id="index-1">Return a tuple object with the same contents as the arbitrary sequence <em>o</em> or
<em>NULL</em> on failure. If <em>o</em> is a tuple, a new reference will be returned,
otherwise a tuple will be constructed with the appropriate contents. This is
equivalent to the Python expression <code class="docutils literal notranslate"><span class="pre">tuple(o)</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PySequence_Fast">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PySequence_Fast</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em>, const char<em> *m</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySequence_Fast" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return the sequence <em>o</em> as a list, unless it is already a tuple or list, in
which case <em>o</em> is returned. Use <a class="reference internal" href="#c.PySequence_Fast_GET_ITEM" title="PySequence_Fast_GET_ITEM"><code class="xref c c-func docutils literal notranslate"><span class="pre">PySequence_Fast_GET_ITEM()</span></code></a> to access
the members of the result. Returns <em>NULL</em> on failure. If the object is not
a sequence, raises <a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> with <em>m</em> as the message text.</p>
</dd></dl>
<dl class="function">
<dt id="c.PySequence_Fast_GET_ITEM">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PySequence_Fast_GET_ITEM</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em>, Py_ssize_t<em> i</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySequence_Fast_GET_ITEM" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Borrowed reference.</em><p>Return the <em>i</em>th element of <em>o</em>, assuming that <em>o</em> was returned by
<a class="reference internal" href="#c.PySequence_Fast" title="PySequence_Fast"><code class="xref c c-func docutils literal notranslate"><span class="pre">PySequence_Fast()</span></code></a>, <em>o</em> is not <em>NULL</em>, and that <em>i</em> is within bounds.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>i</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PySequence_Fast_ITEMS">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>** <code class="descname">PySequence_Fast_ITEMS</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySequence_Fast_ITEMS" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the underlying array of PyObject pointers. Assumes that <em>o</em> was returned
by <a class="reference internal" href="#c.PySequence_Fast" title="PySequence_Fast"><code class="xref c c-func docutils literal notranslate"><span class="pre">PySequence_Fast()</span></code></a> and <em>o</em> is not <em>NULL</em>.</p>
<p>Note, if a list gets resized, the reallocation may relocate the items array.
So, only use the underlying array pointer in contexts where the sequence
cannot change.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PySequence_ITEM">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PySequence_ITEM</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em>, Py_ssize_t<em> i</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySequence_ITEM" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return the <em>i</em>th element of <em>o</em> or <em>NULL</em> on failure. Macro form of
<a class="reference internal" href="#c.PySequence_GetItem" title="PySequence_GetItem"><code class="xref c c-func docutils literal notranslate"><span class="pre">PySequence_GetItem()</span></code></a> but without checking that
<a class="reference internal" href="#c.PySequence_Check" title="PySequence_Check"><code class="xref c c-func docutils literal notranslate"><span class="pre">PySequence_Check()</span></code></a> on <em>o</em> is true and without adjustment for negative
indices.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.3.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>i</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PySequence_Fast_GET_SIZE">
Py_ssize_t <code class="descname">PySequence_Fast_GET_SIZE</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySequence_Fast_GET_SIZE" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns the length of <em>o</em>, assuming that <em>o</em> was returned by
<a class="reference internal" href="#c.PySequence_Fast" title="PySequence_Fast"><code class="xref c c-func docutils literal notranslate"><span class="pre">PySequence_Fast()</span></code></a> and that <em>o</em> is not <em>NULL</em>. The size can also be
gotten by calling <a class="reference internal" href="#c.PySequence_Size" title="PySequence_Size"><code class="xref c c-func docutils literal notranslate"><span class="pre">PySequence_Size()</span></code></a> on <em>o</em>, but
<a class="reference internal" href="#c.PySequence_Fast_GET_SIZE" title="PySequence_Fast_GET_SIZE"><code class="xref c c-func docutils literal notranslate"><span class="pre">PySequence_Fast_GET_SIZE()</span></code></a> is faster because it can assume <em>o</em> is a list
or tuple.</p>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="number.html"
title="previous chapter">Number Protocol</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="mapping.html"
title="next chapter">Mapping Protocol</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/sequence.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="mapping.html" title="Mapping Protocol"
>next</a> |</li>
<li class="right" >
<a href="number.html" title="Number Protocol"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="abstract.html" >Abstract Objects Layer</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\��� �{ �{ html/c-api/set.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Set Objects — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Code Objects" href="code.html" />
<link rel="prev" title="DateTime Objects" href="datetime.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/set.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="code.html" title="Code Objects"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="datetime.html" title="DateTime Objects"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" accesskey="U">Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="set-objects">
<span id="setobjects"></span><h1>Set Objects<a class="headerlink" href="#set-objects" title="Permalink to this headline">¶</a></h1>
<div class="versionadded" id="index-0">
<p><span class="versionmodified">New in version 2.5.</span></p>
</div>
<p>This section details the public API for <a class="reference internal" href="../library/stdtypes.html#set" title="set"><code class="xref py py-class docutils literal notranslate"><span class="pre">set</span></code></a> and <a class="reference internal" href="../library/stdtypes.html#frozenset" title="frozenset"><code class="xref py py-class docutils literal notranslate"><span class="pre">frozenset</span></code></a>
objects. Any functionality not listed below is best accessed using the either
the abstract object protocol (including <a class="reference internal" href="object.html#c.PyObject_CallMethod" title="PyObject_CallMethod"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_CallMethod()</span></code></a>,
<a class="reference internal" href="object.html#c.PyObject_RichCompareBool" title="PyObject_RichCompareBool"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_RichCompareBool()</span></code></a>, <a class="reference internal" href="object.html#c.PyObject_Hash" title="PyObject_Hash"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_Hash()</span></code></a>,
<a class="reference internal" href="object.html#c.PyObject_Repr" title="PyObject_Repr"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_Repr()</span></code></a>, <a class="reference internal" href="object.html#c.PyObject_IsTrue" title="PyObject_IsTrue"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_IsTrue()</span></code></a>, <a class="reference internal" href="object.html#c.PyObject_Print" title="PyObject_Print"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_Print()</span></code></a>, and
<a class="reference internal" href="object.html#c.PyObject_GetIter" title="PyObject_GetIter"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_GetIter()</span></code></a>) or the abstract number protocol (including
<a class="reference internal" href="number.html#c.PyNumber_And" title="PyNumber_And"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyNumber_And()</span></code></a>, <a class="reference internal" href="number.html#c.PyNumber_Subtract" title="PyNumber_Subtract"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyNumber_Subtract()</span></code></a>, <a class="reference internal" href="number.html#c.PyNumber_Or" title="PyNumber_Or"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyNumber_Or()</span></code></a>,
<a class="reference internal" href="number.html#c.PyNumber_Xor" title="PyNumber_Xor"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyNumber_Xor()</span></code></a>, <a class="reference internal" href="number.html#c.PyNumber_InPlaceAnd" title="PyNumber_InPlaceAnd"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyNumber_InPlaceAnd()</span></code></a>,
<a class="reference internal" href="number.html#c.PyNumber_InPlaceSubtract" title="PyNumber_InPlaceSubtract"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyNumber_InPlaceSubtract()</span></code></a>, <a class="reference internal" href="number.html#c.PyNumber_InPlaceOr" title="PyNumber_InPlaceOr"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyNumber_InPlaceOr()</span></code></a>, and
<a class="reference internal" href="number.html#c.PyNumber_InPlaceXor" title="PyNumber_InPlaceXor"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyNumber_InPlaceXor()</span></code></a>).</p>
<dl class="type">
<dt id="c.PySetObject">
<code class="descname">PySetObject</code><a class="headerlink" href="#c.PySetObject" title="Permalink to this definition">¶</a></dt>
<dd><p>This subtype of <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject</span></code></a> is used to hold the internal data for both
<a class="reference internal" href="../library/stdtypes.html#set" title="set"><code class="xref py py-class docutils literal notranslate"><span class="pre">set</span></code></a> and <a class="reference internal" href="../library/stdtypes.html#frozenset" title="frozenset"><code class="xref py py-class docutils literal notranslate"><span class="pre">frozenset</span></code></a> objects. It is like a <a class="reference internal" href="dict.html#c.PyDictObject" title="PyDictObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyDictObject</span></code></a>
in that it is a fixed size for small sets (much like tuple storage) and will
point to a separate, variable sized block of memory for medium and large sized
sets (much like list storage). None of the fields of this structure should be
considered public and are subject to change. All access should be done through
the documented API rather than by manipulating the values in the structure.</p>
</dd></dl>
<dl class="var">
<dt id="c.PySet_Type">
<a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a> <code class="descname">PySet_Type</code><a class="headerlink" href="#c.PySet_Type" title="Permalink to this definition">¶</a></dt>
<dd><p>This is an instance of <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyTypeObject</span></code></a> representing the Python
<a class="reference internal" href="../library/stdtypes.html#set" title="set"><code class="xref py py-class docutils literal notranslate"><span class="pre">set</span></code></a> type.</p>
</dd></dl>
<dl class="var">
<dt id="c.PyFrozenSet_Type">
<a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a> <code class="descname">PyFrozenSet_Type</code><a class="headerlink" href="#c.PyFrozenSet_Type" title="Permalink to this definition">¶</a></dt>
<dd><p>This is an instance of <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyTypeObject</span></code></a> representing the Python
<a class="reference internal" href="../library/stdtypes.html#frozenset" title="frozenset"><code class="xref py py-class docutils literal notranslate"><span class="pre">frozenset</span></code></a> type.</p>
</dd></dl>
<p>The following type check macros work on pointers to any Python object. Likewise,
the constructor functions work with any iterable Python object.</p>
<dl class="function">
<dt id="c.PySet_Check">
int <code class="descname">PySet_Check</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySet_Check" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if <em>p</em> is a <a class="reference internal" href="../library/stdtypes.html#set" title="set"><code class="xref py py-class docutils literal notranslate"><span class="pre">set</span></code></a> object or an instance of a subtype.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyFrozenSet_Check">
int <code class="descname">PyFrozenSet_Check</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFrozenSet_Check" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if <em>p</em> is a <a class="reference internal" href="../library/stdtypes.html#frozenset" title="frozenset"><code class="xref py py-class docutils literal notranslate"><span class="pre">frozenset</span></code></a> object or an instance of a
subtype.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyAnySet_Check">
int <code class="descname">PyAnySet_Check</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyAnySet_Check" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if <em>p</em> is a <a class="reference internal" href="../library/stdtypes.html#set" title="set"><code class="xref py py-class docutils literal notranslate"><span class="pre">set</span></code></a> object, a <a class="reference internal" href="../library/stdtypes.html#frozenset" title="frozenset"><code class="xref py py-class docutils literal notranslate"><span class="pre">frozenset</span></code></a> object, or an
instance of a subtype.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyAnySet_CheckExact">
int <code class="descname">PyAnySet_CheckExact</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyAnySet_CheckExact" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if <em>p</em> is a <a class="reference internal" href="../library/stdtypes.html#set" title="set"><code class="xref py py-class docutils literal notranslate"><span class="pre">set</span></code></a> object or a <a class="reference internal" href="../library/stdtypes.html#frozenset" title="frozenset"><code class="xref py py-class docutils literal notranslate"><span class="pre">frozenset</span></code></a> object but
not an instance of a subtype.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyFrozenSet_CheckExact">
int <code class="descname">PyFrozenSet_CheckExact</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFrozenSet_CheckExact" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if <em>p</em> is a <a class="reference internal" href="../library/stdtypes.html#frozenset" title="frozenset"><code class="xref py py-class docutils literal notranslate"><span class="pre">frozenset</span></code></a> object but not an instance of a
subtype.</p>
</dd></dl>
<dl class="function">
<dt id="c.PySet_New">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PySet_New</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *iterable</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySet_New" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a new <a class="reference internal" href="../library/stdtypes.html#set" title="set"><code class="xref py py-class docutils literal notranslate"><span class="pre">set</span></code></a> containing objects returned by the <em>iterable</em>. The
<em>iterable</em> may be <em>NULL</em> to create a new empty set. Return the new set on
success or <em>NULL</em> on failure. Raise <a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> if <em>iterable</em> is not
actually iterable. The constructor is also useful for copying a set
(<code class="docutils literal notranslate"><span class="pre">c=set(s)</span></code>).</p>
</dd></dl>
<dl class="function">
<dt id="c.PyFrozenSet_New">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyFrozenSet_New</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *iterable</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFrozenSet_New" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a new <a class="reference internal" href="../library/stdtypes.html#frozenset" title="frozenset"><code class="xref py py-class docutils literal notranslate"><span class="pre">frozenset</span></code></a> containing objects returned by the <em>iterable</em>.
The <em>iterable</em> may be <em>NULL</em> to create a new empty frozenset. Return the new
set on success or <em>NULL</em> on failure. Raise <a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> if <em>iterable</em> is
not actually iterable.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.6: </span>Now guaranteed to return a brand-new <a class="reference internal" href="../library/stdtypes.html#frozenset" title="frozenset"><code class="xref py py-class docutils literal notranslate"><span class="pre">frozenset</span></code></a>. Formerly,
frozensets of zero-length were a singleton. This got in the way of
building-up new frozensets with <code class="xref py py-meth docutils literal notranslate"><span class="pre">PySet_Add()</span></code>.</p>
</div>
</dd></dl>
<p>The following functions and macros are available for instances of <a class="reference internal" href="../library/stdtypes.html#set" title="set"><code class="xref py py-class docutils literal notranslate"><span class="pre">set</span></code></a>
or <a class="reference internal" href="../library/stdtypes.html#frozenset" title="frozenset"><code class="xref py py-class docutils literal notranslate"><span class="pre">frozenset</span></code></a> or instances of their subtypes.</p>
<dl class="function">
<dt id="c.PySet_Size">
Py_ssize_t <code class="descname">PySet_Size</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *anyset</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySet_Size" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-1">Return the length of a <a class="reference internal" href="../library/stdtypes.html#set" title="set"><code class="xref py py-class docutils literal notranslate"><span class="pre">set</span></code></a> or <a class="reference internal" href="../library/stdtypes.html#frozenset" title="frozenset"><code class="xref py py-class docutils literal notranslate"><span class="pre">frozenset</span></code></a> object. Equivalent to
<code class="docutils literal notranslate"><span class="pre">len(anyset)</span></code>. Raises a <code class="xref py py-exc docutils literal notranslate"><span class="pre">PyExc_SystemError</span></code> if <em>anyset</em> is not a
<a class="reference internal" href="../library/stdtypes.html#set" title="set"><code class="xref py py-class docutils literal notranslate"><span class="pre">set</span></code></a>, <a class="reference internal" href="../library/stdtypes.html#frozenset" title="frozenset"><code class="xref py py-class docutils literal notranslate"><span class="pre">frozenset</span></code></a>, or an instance of a subtype.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function returned an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code>. This might require changes in
your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PySet_GET_SIZE">
Py_ssize_t <code class="descname">PySet_GET_SIZE</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *anyset</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySet_GET_SIZE" title="Permalink to this definition">¶</a></dt>
<dd><p>Macro form of <a class="reference internal" href="#c.PySet_Size" title="PySet_Size"><code class="xref c c-func docutils literal notranslate"><span class="pre">PySet_Size()</span></code></a> without error checking.</p>
</dd></dl>
<dl class="function">
<dt id="c.PySet_Contains">
int <code class="descname">PySet_Contains</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *anyset</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *key</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySet_Contains" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">1</span></code> if found, <code class="docutils literal notranslate"><span class="pre">0</span></code> if not found, and <code class="docutils literal notranslate"><span class="pre">-1</span></code> if an error is encountered. Unlike
the Python <a class="reference internal" href="../reference/datamodel.html#object.__contains__" title="object.__contains__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__contains__()</span></code></a> method, this function does not automatically
convert unhashable sets into temporary frozensets. Raise a <a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> if
the <em>key</em> is unhashable. Raise <code class="xref py py-exc docutils literal notranslate"><span class="pre">PyExc_SystemError</span></code> if <em>anyset</em> is not a
<a class="reference internal" href="../library/stdtypes.html#set" title="set"><code class="xref py py-class docutils literal notranslate"><span class="pre">set</span></code></a>, <a class="reference internal" href="../library/stdtypes.html#frozenset" title="frozenset"><code class="xref py py-class docutils literal notranslate"><span class="pre">frozenset</span></code></a>, or an instance of a subtype.</p>
</dd></dl>
<dl class="function">
<dt id="c.PySet_Add">
int <code class="descname">PySet_Add</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *set</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *key</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySet_Add" title="Permalink to this definition">¶</a></dt>
<dd><p>Add <em>key</em> to a <a class="reference internal" href="../library/stdtypes.html#set" title="set"><code class="xref py py-class docutils literal notranslate"><span class="pre">set</span></code></a> instance. Does not apply to <a class="reference internal" href="../library/stdtypes.html#frozenset" title="frozenset"><code class="xref py py-class docutils literal notranslate"><span class="pre">frozenset</span></code></a>
instances. Return <code class="docutils literal notranslate"><span class="pre">0</span></code> on success or <code class="docutils literal notranslate"><span class="pre">-1</span></code> on failure. Raise a <a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> if
the <em>key</em> is unhashable. Raise a <a class="reference internal" href="../library/exceptions.html#exceptions.MemoryError" title="exceptions.MemoryError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">MemoryError</span></code></a> if there is no room to grow.
Raise a <a class="reference internal" href="../library/exceptions.html#exceptions.SystemError" title="exceptions.SystemError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SystemError</span></code></a> if <em>set</em> is not an instance of <a class="reference internal" href="../library/stdtypes.html#set" title="set"><code class="xref py py-class docutils literal notranslate"><span class="pre">set</span></code></a> or its
subtype.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.6: </span>Now works with instances of <a class="reference internal" href="../library/stdtypes.html#frozenset" title="frozenset"><code class="xref py py-class docutils literal notranslate"><span class="pre">frozenset</span></code></a> or its subtypes.
Like <a class="reference internal" href="tuple.html#c.PyTuple_SetItem" title="PyTuple_SetItem"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyTuple_SetItem()</span></code></a> in that it can be used to fill-in the
values of brand new frozensets before they are exposed to other code.</p>
</div>
</dd></dl>
<p>The following functions are available for instances of <a class="reference internal" href="../library/stdtypes.html#set" title="set"><code class="xref py py-class docutils literal notranslate"><span class="pre">set</span></code></a> or its
subtypes but not for instances of <a class="reference internal" href="../library/stdtypes.html#frozenset" title="frozenset"><code class="xref py py-class docutils literal notranslate"><span class="pre">frozenset</span></code></a> or its subtypes.</p>
<dl class="function">
<dt id="c.PySet_Discard">
int <code class="descname">PySet_Discard</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *set</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *key</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySet_Discard" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">1</span></code> if found and removed, <code class="docutils literal notranslate"><span class="pre">0</span></code> if not found (no action taken), and <code class="docutils literal notranslate"><span class="pre">-1</span></code> if an
error is encountered. Does not raise <a class="reference internal" href="../library/exceptions.html#exceptions.KeyError" title="exceptions.KeyError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyError</span></code></a> for missing keys. Raise a
<a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> if the <em>key</em> is unhashable. Unlike the Python <code class="xref py py-meth docutils literal notranslate"><span class="pre">discard()</span></code>
method, this function does not automatically convert unhashable sets into
temporary frozensets. Raise <code class="xref py py-exc docutils literal notranslate"><span class="pre">PyExc_SystemError</span></code> if <em>set</em> is not an
instance of <a class="reference internal" href="../library/stdtypes.html#set" title="set"><code class="xref py py-class docutils literal notranslate"><span class="pre">set</span></code></a> or its subtype.</p>
</dd></dl>
<dl class="function">
<dt id="c.PySet_Pop">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PySet_Pop</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *set</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySet_Pop" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a new reference to an arbitrary object in the <em>set</em>, and removes the
object from the <em>set</em>. Return <em>NULL</em> on failure. Raise <a class="reference internal" href="../library/exceptions.html#exceptions.KeyError" title="exceptions.KeyError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyError</span></code></a> if the
set is empty. Raise a <a class="reference internal" href="../library/exceptions.html#exceptions.SystemError" title="exceptions.SystemError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SystemError</span></code></a> if <em>set</em> is not an instance of
<a class="reference internal" href="../library/stdtypes.html#set" title="set"><code class="xref py py-class docutils literal notranslate"><span class="pre">set</span></code></a> or its subtype.</p>
</dd></dl>
<dl class="function">
<dt id="c.PySet_Clear">
int <code class="descname">PySet_Clear</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *set</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySet_Clear" title="Permalink to this definition">¶</a></dt>
<dd><p>Empty an existing set of all elements.</p>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="datetime.html"
title="previous chapter">DateTime Objects</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="code.html"
title="next chapter">Code Objects</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/set.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="code.html" title="Code Objects"
>next</a> |</li>
<li class="right" >
<a href="datetime.html" title="DateTime Objects"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" >Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\^� �5 5 html/c-api/slice.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Slice Objects — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Weak Reference Objects" href="weakref.html" />
<link rel="prev" title="Descriptor Objects" href="descriptor.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/slice.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="weakref.html" title="Weak Reference Objects"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="descriptor.html" title="Descriptor Objects"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" accesskey="U">Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="slice-objects">
<span id="id1"></span><h1>Slice Objects<a class="headerlink" href="#slice-objects" title="Permalink to this headline">¶</a></h1>
<dl class="var">
<dt id="c.PySlice_Type">
<a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a> <code class="descname">PySlice_Type</code><a class="headerlink" href="#c.PySlice_Type" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-0">The type object for slice objects. This is the same as <code class="docutils literal notranslate"><span class="pre">slice</span></code> and
<code class="docutils literal notranslate"><span class="pre">types.SliceType</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PySlice_Check">
int <code class="descname">PySlice_Check</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *ob</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySlice_Check" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if <em>ob</em> is a slice object; <em>ob</em> must not be <em>NULL</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PySlice_New">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PySlice_New</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *start</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *stop</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *step</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySlice_New" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a new slice object with the given values. The <em>start</em>, <em>stop</em>, and
<em>step</em> parameters are used as the values of the slice object attributes of
the same names. Any of the values may be <em>NULL</em>, in which case the
<code class="docutils literal notranslate"><span class="pre">None</span></code> will be used for the corresponding attribute. Return <em>NULL</em> if
the new object could not be allocated.</p>
</dd></dl>
<dl class="function">
<dt id="c.PySlice_GetIndices">
int <code class="descname">PySlice_GetIndices</code><span class="sig-paren">(</span>PySliceObject<em> *slice</em>, Py_ssize_t<em> length</em>, Py_ssize_t<em> *start</em>, Py_ssize_t<em> *stop</em>, Py_ssize_t<em> *step</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySlice_GetIndices" title="Permalink to this definition">¶</a></dt>
<dd><p>Retrieve the start, stop and step indices from the slice object <em>slice</em>,
assuming a sequence of length <em>length</em>. Treats indices greater than
<em>length</em> as errors.</p>
<p>Returns <code class="docutils literal notranslate"><span class="pre">0</span></code> on success and <code class="docutils literal notranslate"><span class="pre">-1</span></code> on error with no exception set (unless one of
the indices was not <a class="reference internal" href="../library/constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a> and failed to be converted to an integer,
in which case <code class="docutils literal notranslate"><span class="pre">-1</span></code> is returned with an exception set).</p>
<p>You probably do not want to use this function. If you want to use slice
objects in versions of Python prior to 2.3, you would probably do well to
incorporate the source of <a class="reference internal" href="#c.PySlice_GetIndicesEx" title="PySlice_GetIndicesEx"><code class="xref c c-func docutils literal notranslate"><span class="pre">PySlice_GetIndicesEx()</span></code></a>, suitably renamed,
in the source of your extension.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>length</em> and an
<code class="xref c c-type docutils literal notranslate"><span class="pre">int</span> <span class="pre">*</span></code> type for <em>start</em>, <em>stop</em>, and <em>step</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PySlice_GetIndicesEx">
int <code class="descname">PySlice_GetIndicesEx</code><span class="sig-paren">(</span>PySliceObject<em> *slice</em>, Py_ssize_t<em> length</em>, Py_ssize_t<em> *start</em>, Py_ssize_t<em> *stop</em>, Py_ssize_t<em> *step</em>, Py_ssize_t<em> *slicelength</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySlice_GetIndicesEx" title="Permalink to this definition">¶</a></dt>
<dd><p>Usable replacement for <a class="reference internal" href="#c.PySlice_GetIndices" title="PySlice_GetIndices"><code class="xref c c-func docutils literal notranslate"><span class="pre">PySlice_GetIndices()</span></code></a>. Retrieve the start,
stop, and step indices from the slice object <em>slice</em> assuming a sequence of
length <em>length</em>, and store the length of the slice in <em>slicelength</em>. Out
of bounds indices are clipped in a manner consistent with the handling of
normal slices.</p>
<p>Returns <code class="docutils literal notranslate"><span class="pre">0</span></code> on success and <code class="docutils literal notranslate"><span class="pre">-1</span></code> on error with exception set.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.3.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>length</em> and an
<code class="xref c c-type docutils literal notranslate"><span class="pre">int</span> <span class="pre">*</span></code> type for <em>start</em>, <em>stop</em>, <em>step</em>, and <em>slicelength</em>. This
might require changes in your code for properly supporting 64-bit
systems.</p>
</div>
</dd></dl>
</div>
<div class="section" id="ellipsis-object">
<h1>Ellipsis Object<a class="headerlink" href="#ellipsis-object" title="Permalink to this headline">¶</a></h1>
<dl class="var">
<dt id="c.Py_Ellipsis">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *<code class="descname">Py_Ellipsis</code><a class="headerlink" href="#c.Py_Ellipsis" title="Permalink to this definition">¶</a></dt>
<dd><p>The Python <code class="docutils literal notranslate"><span class="pre">Ellipsis</span></code> object. This object has no methods. It needs to be
treated just like any other object with respect to reference counts. Like
<a class="reference internal" href="none.html#c.Py_None" title="Py_None"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_None</span></code></a> it is a singleton object.</p>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Slice Objects</a></li>
<li><a class="reference internal" href="#ellipsis-object">Ellipsis Object</a></li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="descriptor.html"
title="previous chapter">Descriptor Objects</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="weakref.html"
title="next chapter">Weak Reference Objects</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/slice.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="weakref.html" title="Weak Reference Objects"
>next</a> |</li>
<li class="right" >
<a href="descriptor.html" title="Descriptor Objects"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" >Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\���]�� �� html/c-api/string.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>String/Bytes Objects — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Unicode Objects and Codecs" href="unicode.html" />
<link rel="prev" title="Byte Array Objects" href="bytearray.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/string.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="unicode.html" title="Unicode Objects and Codecs"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="bytearray.html" title="Byte Array Objects"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" accesskey="U">Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="string-bytes-objects">
<span id="stringobjects"></span><h1>String/Bytes Objects<a class="headerlink" href="#string-bytes-objects" title="Permalink to this headline">¶</a></h1>
<p>These functions raise <a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> when expecting a string parameter and are
called with a non-string parameter.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">These functions have been renamed to PyBytes_* in Python 3.x. Unless
otherwise noted, the PyBytes functions available in 3.x are aliased to their
PyString_* equivalents to help porting.</p>
</div>
<span class="target" id="index-0"></span><dl class="type">
<dt id="c.PyStringObject">
<code class="descname">PyStringObject</code><a class="headerlink" href="#c.PyStringObject" title="Permalink to this definition">¶</a></dt>
<dd><p>This subtype of <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject</span></code></a> represents a Python string object.</p>
</dd></dl>
<dl class="var">
<dt id="c.PyString_Type">
<a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a> <code class="descname">PyString_Type</code><a class="headerlink" href="#c.PyString_Type" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-1">This instance of <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyTypeObject</span></code></a> represents the Python string type; it is
the same object as <code class="docutils literal notranslate"><span class="pre">str</span></code> and <code class="docutils literal notranslate"><span class="pre">types.StringType</span></code> in the Python layer. .</p>
</dd></dl>
<dl class="function">
<dt id="c.PyString_Check">
int <code class="descname">PyString_Check</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyString_Check" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if the object <em>o</em> is a string object or an instance of a subtype of
the string type.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.2: </span>Allowed subtypes to be accepted.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyString_CheckExact">
int <code class="descname">PyString_CheckExact</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyString_CheckExact" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if the object <em>o</em> is a string object, but not an instance of a
subtype of the string type.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyString_FromString">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyString_FromString</code><span class="sig-paren">(</span>const char<em> *v</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyString_FromString" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a new string object with a copy of the string <em>v</em> as value on success,
and <em>NULL</em> on failure. The parameter <em>v</em> must not be <em>NULL</em>; it will not be
checked.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyString_FromStringAndSize">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyString_FromStringAndSize</code><span class="sig-paren">(</span>const char<em> *v</em>, Py_ssize_t<em> len</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyString_FromStringAndSize" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a new string object with a copy of the string <em>v</em> as value and length
<em>len</em> on success, and <em>NULL</em> on failure. If <em>v</em> is <em>NULL</em>, the contents of the
string are uninitialized.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>len</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyString_FromFormat">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyString_FromFormat</code><span class="sig-paren">(</span>const char<em> *format</em>, ...<span class="sig-paren">)</span><a class="headerlink" href="#c.PyString_FromFormat" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Take a C <code class="xref c c-func docutils literal notranslate"><span class="pre">printf()</span></code>-style <em>format</em> string and a variable number of
arguments, calculate the size of the resulting Python string and return a string
with the values formatted into it. The variable arguments must be C types and
must correspond exactly to the format characters in the <em>format</em> string. The
following format characters are allowed:</p>
<table border="1" class="docutils">
<colgroup>
<col width="29%" />
<col width="23%" />
<col width="48%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Format Characters</th>
<th class="head">Type</th>
<th class="head">Comment</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="xref py py-attr docutils literal notranslate"><span class="pre">%%</span></code></td>
<td><em>n/a</em></td>
<td>The literal % character.</td>
</tr>
<tr class="row-odd"><td><code class="xref py py-attr docutils literal notranslate"><span class="pre">%c</span></code></td>
<td>int</td>
<td>A single character,
represented as a C int.</td>
</tr>
<tr class="row-even"><td><code class="xref py py-attr docutils literal notranslate"><span class="pre">%d</span></code></td>
<td>int</td>
<td>Exactly equivalent to
<code class="docutils literal notranslate"><span class="pre">printf("%d")</span></code>.</td>
</tr>
<tr class="row-odd"><td><code class="xref py py-attr docutils literal notranslate"><span class="pre">%u</span></code></td>
<td>unsigned int</td>
<td>Exactly equivalent to
<code class="docutils literal notranslate"><span class="pre">printf("%u")</span></code>.</td>
</tr>
<tr class="row-even"><td><code class="xref py py-attr docutils literal notranslate"><span class="pre">%ld</span></code></td>
<td>long</td>
<td>Exactly equivalent to
<code class="docutils literal notranslate"><span class="pre">printf("%ld")</span></code>.</td>
</tr>
<tr class="row-odd"><td><code class="xref py py-attr docutils literal notranslate"><span class="pre">%lu</span></code></td>
<td>unsigned long</td>
<td>Exactly equivalent to
<code class="docutils literal notranslate"><span class="pre">printf("%lu")</span></code>.</td>
</tr>
<tr class="row-even"><td><code class="xref py py-attr docutils literal notranslate"><span class="pre">%lld</span></code></td>
<td>long long</td>
<td>Exactly equivalent to
<code class="docutils literal notranslate"><span class="pre">printf("%lld")</span></code>.</td>
</tr>
<tr class="row-odd"><td><code class="xref py py-attr docutils literal notranslate"><span class="pre">%llu</span></code></td>
<td>unsigned
long long</td>
<td>Exactly equivalent to
<code class="docutils literal notranslate"><span class="pre">printf("%llu")</span></code>.</td>
</tr>
<tr class="row-even"><td><code class="xref py py-attr docutils literal notranslate"><span class="pre">%zd</span></code></td>
<td>Py_ssize_t</td>
<td>Exactly equivalent to
<code class="docutils literal notranslate"><span class="pre">printf("%zd")</span></code>.</td>
</tr>
<tr class="row-odd"><td><code class="xref py py-attr docutils literal notranslate"><span class="pre">%zu</span></code></td>
<td>size_t</td>
<td>Exactly equivalent to
<code class="docutils literal notranslate"><span class="pre">printf("%zu")</span></code>.</td>
</tr>
<tr class="row-even"><td><code class="xref py py-attr docutils literal notranslate"><span class="pre">%i</span></code></td>
<td>int</td>
<td>Exactly equivalent to
<code class="docutils literal notranslate"><span class="pre">printf("%i")</span></code>.</td>
</tr>
<tr class="row-odd"><td><code class="xref py py-attr docutils literal notranslate"><span class="pre">%x</span></code></td>
<td>int</td>
<td>Exactly equivalent to
<code class="docutils literal notranslate"><span class="pre">printf("%x")</span></code>.</td>
</tr>
<tr class="row-even"><td><code class="xref py py-attr docutils literal notranslate"><span class="pre">%s</span></code></td>
<td>char*</td>
<td>A null-terminated C character
array.</td>
</tr>
<tr class="row-odd"><td><code class="xref py py-attr docutils literal notranslate"><span class="pre">%p</span></code></td>
<td>void*</td>
<td>The hex representation of a C
pointer. Mostly equivalent to
<code class="docutils literal notranslate"><span class="pre">printf("%p")</span></code> except that
it is guaranteed to start with
the literal <code class="docutils literal notranslate"><span class="pre">0x</span></code> regardless
of what the platform’s
<code class="docutils literal notranslate"><span class="pre">printf</span></code> yields.</td>
</tr>
</tbody>
</table>
<p>An unrecognized format character causes all the rest of the format string to be
copied as-is to the result string, and any extra arguments discarded.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The <cite>“%lld”</cite> and <cite>“%llu”</cite> format specifiers are only available
when <code class="xref py py-const docutils literal notranslate"><span class="pre">HAVE_LONG_LONG</span></code> is defined.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.7: </span>Support for <cite>“%lld”</cite> and <cite>“%llu”</cite> added.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyString_FromFormatV">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyString_FromFormatV</code><span class="sig-paren">(</span>const char<em> *format</em>, va_list<em> vargs</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyString_FromFormatV" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Identical to <a class="reference internal" href="#c.PyString_FromFormat" title="PyString_FromFormat"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyString_FromFormat()</span></code></a> except that it takes exactly two
arguments.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyString_Size">
Py_ssize_t <code class="descname">PyString_Size</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *string</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyString_Size" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the length of the string in string object <em>string</em>.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function returned an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type. This might require changes
in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyString_GET_SIZE">
Py_ssize_t <code class="descname">PyString_GET_SIZE</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *string</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyString_GET_SIZE" title="Permalink to this definition">¶</a></dt>
<dd><p>Macro form of <a class="reference internal" href="#c.PyString_Size" title="PyString_Size"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyString_Size()</span></code></a> but without error checking.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This macro returned an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type. This might require changes in
your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyString_AsString">
char* <code class="descname">PyString_AsString</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *string</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyString_AsString" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a NUL-terminated representation of the contents of <em>string</em>. The pointer
refers to the internal buffer of <em>string</em>, not a copy. The data must not be
modified in any way, unless the string was just created using
<code class="docutils literal notranslate"><span class="pre">PyString_FromStringAndSize(NULL,</span> <span class="pre">size)</span></code>. It must not be deallocated. If
<em>string</em> is a Unicode object, this function computes the default encoding of
<em>string</em> and operates on that. If <em>string</em> is not a string object at all,
<a class="reference internal" href="#c.PyString_AsString" title="PyString_AsString"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyString_AsString()</span></code></a> returns <em>NULL</em> and raises <a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyString_AS_STRING">
char* <code class="descname">PyString_AS_STRING</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *string</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyString_AS_STRING" title="Permalink to this definition">¶</a></dt>
<dd><p>Macro form of <a class="reference internal" href="#c.PyString_AsString" title="PyString_AsString"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyString_AsString()</span></code></a> but without error checking. Only
string objects are supported; no Unicode objects should be passed.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyString_AsStringAndSize">
int <code class="descname">PyString_AsStringAndSize</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *obj</em>, char<em> **buffer</em>, Py_ssize_t<em> *length</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyString_AsStringAndSize" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a NUL-terminated representation of the contents of the object <em>obj</em>
through the output variables <em>buffer</em> and <em>length</em>.</p>
<p>The function accepts both string and Unicode objects as input. For Unicode
objects it returns the default encoded version of the object. If <em>length</em> is
<em>NULL</em>, the resulting buffer may not contain NUL characters; if it does, the
function returns <code class="docutils literal notranslate"><span class="pre">-1</span></code> and a <a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> is raised.</p>
<p>The buffer refers to an internal string buffer of <em>obj</em>, not a copy. The data
must not be modified in any way, unless the string was just created using
<code class="docutils literal notranslate"><span class="pre">PyString_FromStringAndSize(NULL,</span> <span class="pre">size)</span></code>. It must not be deallocated. If
<em>string</em> is a Unicode object, this function computes the default encoding of
<em>string</em> and operates on that. If <em>string</em> is not a string object at all,
<a class="reference internal" href="#c.PyString_AsStringAndSize" title="PyString_AsStringAndSize"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyString_AsStringAndSize()</span></code></a> returns <code class="docutils literal notranslate"><span class="pre">-1</span></code> and raises <a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a>.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span> <span class="pre">*</span></code> type for <em>length</em>. This might
require changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyString_Concat">
void <code class="descname">PyString_Concat</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> **string</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *newpart</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyString_Concat" title="Permalink to this definition">¶</a></dt>
<dd><p>Create a new string object in <em>*string</em> containing the contents of <em>newpart</em>
appended to <em>string</em>; the caller will own the new reference. The reference to
the old value of <em>string</em> will be stolen. If the new string cannot be created,
the old reference to <em>string</em> will still be discarded and the value of
<em>*string</em> will be set to <em>NULL</em>; the appropriate exception will be set.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyString_ConcatAndDel">
void <code class="descname">PyString_ConcatAndDel</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> **string</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *newpart</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyString_ConcatAndDel" title="Permalink to this definition">¶</a></dt>
<dd><p>Create a new string object in <em>*string</em> containing the contents of <em>newpart</em>
appended to <em>string</em>. This version decrements the reference count of <em>newpart</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c._PyString_Resize">
int <code class="descname">_PyString_Resize</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> **string</em>, Py_ssize_t<em> newsize</em><span class="sig-paren">)</span><a class="headerlink" href="#c._PyString_Resize" title="Permalink to this definition">¶</a></dt>
<dd><p>A way to resize a string object even though it is “immutable”. Only use this to
build up a brand new string object; don’t use this if the string may already be
known in other parts of the code. It is an error to call this function if the
refcount on the input string object is not one. Pass the address of an existing
string object as an lvalue (it may be written into), and the new size desired.
On success, <em>*string</em> holds the resized string object and <code class="docutils literal notranslate"><span class="pre">0</span></code> is returned;
the address in <em>*string</em> may differ from its input value. If the reallocation
fails, the original string object at <em>*string</em> is deallocated, <em>*string</em> is
set to <em>NULL</em>, a memory exception is set, and <code class="docutils literal notranslate"><span class="pre">-1</span></code> is returned.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>newsize</em>. This might
require changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyString_Format">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyString_Format</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *format</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *args</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyString_Format" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a new string object from <em>format</em> and <em>args</em>. Analogous to <code class="docutils literal notranslate"><span class="pre">format</span> <span class="pre">%</span>
<span class="pre">args</span></code>. The <em>args</em> argument must be a tuple or dict.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyString_InternInPlace">
void <code class="descname">PyString_InternInPlace</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> **string</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyString_InternInPlace" title="Permalink to this definition">¶</a></dt>
<dd><p>Intern the argument <em>*string</em> in place. The argument must be the address of a
pointer variable pointing to a Python string object. If there is an existing
interned string that is the same as <em>*string</em>, it sets <em>*string</em> to it
(decrementing the reference count of the old string object and incrementing the
reference count of the interned string object), otherwise it leaves <em>*string</em>
alone and interns it (incrementing its reference count). (Clarification: even
though there is a lot of talk about reference counts, think of this function as
reference-count-neutral; you own the object after the call if and only if you
owned it before the call.)</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This function is not available in 3.x and does not have a PyBytes alias.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyString_InternFromString">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyString_InternFromString</code><span class="sig-paren">(</span>const char<em> *v</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyString_InternFromString" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>A combination of <a class="reference internal" href="#c.PyString_FromString" title="PyString_FromString"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyString_FromString()</span></code></a> and
<a class="reference internal" href="#c.PyString_InternInPlace" title="PyString_InternInPlace"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyString_InternInPlace()</span></code></a>, returning either a new string object that has
been interned, or a new (“owned”) reference to an earlier interned string object
with the same value.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This function is not available in 3.x and does not have a PyBytes alias.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyString_Decode">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyString_Decode</code><span class="sig-paren">(</span>const char<em> *s</em>, Py_ssize_t<em> size</em>, const char<em> *encoding</em>, const char<em> *errors</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyString_Decode" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Create an object by decoding <em>size</em> bytes of the encoded buffer <em>s</em> using the
codec registered for <em>encoding</em>. <em>encoding</em> and <em>errors</em> have the same meaning
as the parameters of the same name in the <a class="reference internal" href="../library/functions.html#unicode" title="unicode"><code class="xref py py-func docutils literal notranslate"><span class="pre">unicode()</span></code></a> built-in function.
The codec to be used is looked up using the Python codec registry. Return
<em>NULL</em> if an exception was raised by the codec.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This function is not available in 3.x and does not have a PyBytes alias.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>size</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyString_AsDecodedObject">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyString_AsDecodedObject</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *str</em>, const char<em> *encoding</em>, const char<em> *errors</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyString_AsDecodedObject" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Decode a string object by passing it to the codec registered for <em>encoding</em> and
return the result as Python object. <em>encoding</em> and <em>errors</em> have the same
meaning as the parameters of the same name in the string <code class="xref py py-meth docutils literal notranslate"><span class="pre">encode()</span></code> method.
The codec to be used is looked up using the Python codec registry. Return <em>NULL</em>
if an exception was raised by the codec.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This function is not available in 3.x and does not have a PyBytes alias.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyString_Encode">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyString_Encode</code><span class="sig-paren">(</span>const char<em> *s</em>, Py_ssize_t<em> size</em>, const char<em> *encoding</em>, const char<em> *errors</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyString_Encode" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Encode the <code class="xref c c-type docutils literal notranslate"><span class="pre">char</span></code> buffer of the given size by passing it to the codec
registered for <em>encoding</em> and return a Python object. <em>encoding</em> and <em>errors</em>
have the same meaning as the parameters of the same name in the string
<code class="xref py py-meth docutils literal notranslate"><span class="pre">encode()</span></code> method. The codec to be used is looked up using the Python codec
registry. Return <em>NULL</em> if an exception was raised by the codec.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This function is not available in 3.x and does not have a PyBytes alias.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>size</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyString_AsEncodedObject">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyString_AsEncodedObject</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *str</em>, const char<em> *encoding</em>, const char<em> *errors</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyString_AsEncodedObject" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Encode a string object using the codec registered for <em>encoding</em> and return the
result as Python object. <em>encoding</em> and <em>errors</em> have the same meaning as the
parameters of the same name in the string <code class="xref py py-meth docutils literal notranslate"><span class="pre">encode()</span></code> method. The codec to be
used is looked up using the Python codec registry. Return <em>NULL</em> if an exception
was raised by the codec.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This function is not available in 3.x and does not have a PyBytes alias.</p>
</div>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="bytearray.html"
title="previous chapter">Byte Array Objects</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="unicode.html"
title="next chapter">Unicode Objects and Codecs</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/string.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="unicode.html" title="Unicode Objects and Codecs"
>next</a> |</li>
<li class="right" >
<a href="bytearray.html" title="Byte Array Objects"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" >Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\-�D��� �� html/c-api/structures.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Common Object Structures — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Type Objects" href="typeobj.html" />
<link rel="prev" title="Allocating Objects on the Heap" href="allocation.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/structures.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="typeobj.html" title="Type Objects"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="allocation.html" title="Allocating Objects on the Heap"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="objimpl.html" accesskey="U">Object Implementation Support</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="common-object-structures">
<span id="common-structs"></span><h1>Common Object Structures<a class="headerlink" href="#common-object-structures" title="Permalink to this headline">¶</a></h1>
<p>There are a large number of structures which are used in the definition of
object types for Python. This section describes these structures and how they
are used.</p>
<p>All Python objects ultimately share a small number of fields at the beginning
of the object’s representation in memory. These are represented by the
<a class="reference internal" href="#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject</span></code></a> and <a class="reference internal" href="#c.PyVarObject" title="PyVarObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyVarObject</span></code></a> types, which are defined, in turn,
by the expansions of some macros also used, whether directly or indirectly, in
the definition of all other Python objects.</p>
<dl class="type">
<dt id="c.PyObject">
<code class="descname">PyObject</code><a class="headerlink" href="#c.PyObject" title="Permalink to this definition">¶</a></dt>
<dd><p>All object types are extensions of this type. This is a type which
contains the information Python needs to treat a pointer to an object as an
object. In a normal “release” build, it contains only the object’s
reference count and a pointer to the corresponding type object. It
corresponds to the fields defined by the expansion of the <code class="docutils literal notranslate"><span class="pre">PyObject_HEAD</span></code>
macro.</p>
</dd></dl>
<dl class="type">
<dt id="c.PyVarObject">
<code class="descname">PyVarObject</code><a class="headerlink" href="#c.PyVarObject" title="Permalink to this definition">¶</a></dt>
<dd><p>This is an extension of <a class="reference internal" href="#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject</span></code></a> that adds the <code class="xref py py-attr docutils literal notranslate"><span class="pre">ob_size</span></code>
field. This is only used for objects that have some notion of <em>length</em>.
This type does not often appear in the Python/C API. It corresponds to the
fields defined by the expansion of the <code class="docutils literal notranslate"><span class="pre">PyObject_VAR_HEAD</span></code> macro.</p>
</dd></dl>
<p>These macros are used in the definition of <a class="reference internal" href="#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject</span></code></a> and
<a class="reference internal" href="#c.PyVarObject" title="PyVarObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyVarObject</span></code></a>:</p>
<dl class="macro">
<dt id="c.PyObject_HEAD">
<code class="descname">PyObject_HEAD</code><a class="headerlink" href="#c.PyObject_HEAD" title="Permalink to this definition">¶</a></dt>
<dd><p>This is a macro which expands to the declarations of the fields of the
<a class="reference internal" href="#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject</span></code></a> type; it is used when declaring new types which represent
objects without a varying length. The specific fields it expands to depend
on the definition of <code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_TRACE_REFS</span></code>. By default, that macro is
not defined, and <a class="reference internal" href="#c.PyObject_HEAD" title="PyObject_HEAD"><code class="xref c c-macro docutils literal notranslate"><span class="pre">PyObject_HEAD</span></code></a> expands to:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">Py_ssize_t</span> <span class="n">ob_refcnt</span><span class="p">;</span>
<span class="n">PyTypeObject</span> <span class="o">*</span><span class="n">ob_type</span><span class="p">;</span>
</pre></div>
</div>
<p>When <code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_TRACE_REFS</span></code> is defined, it expands to:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">PyObject</span> <span class="o">*</span><span class="n">_ob_next</span><span class="p">,</span> <span class="o">*</span><span class="n">_ob_prev</span><span class="p">;</span>
<span class="n">Py_ssize_t</span> <span class="n">ob_refcnt</span><span class="p">;</span>
<span class="n">PyTypeObject</span> <span class="o">*</span><span class="n">ob_type</span><span class="p">;</span>
</pre></div>
</div>
</dd></dl>
<dl class="macro">
<dt id="c.PyObject_VAR_HEAD">
<code class="descname">PyObject_VAR_HEAD</code><a class="headerlink" href="#c.PyObject_VAR_HEAD" title="Permalink to this definition">¶</a></dt>
<dd><p>This is a macro which expands to the declarations of the fields of the
<a class="reference internal" href="#c.PyVarObject" title="PyVarObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyVarObject</span></code></a> type; it is used when declaring new types which
represent objects with a length that varies from instance to instance.
This macro always expands to:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">PyObject_HEAD</span>
<span class="n">Py_ssize_t</span> <span class="n">ob_size</span><span class="p">;</span>
</pre></div>
</div>
<p>Note that <a class="reference internal" href="#c.PyObject_HEAD" title="PyObject_HEAD"><code class="xref c c-macro docutils literal notranslate"><span class="pre">PyObject_HEAD</span></code></a> is part of the expansion, and that its own
expansion varies depending on the definition of <code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_TRACE_REFS</span></code>.</p>
</dd></dl>
<dl class="macro">
<dt id="c.Py_TYPE">
<code class="descname">Py_TYPE</code><span class="sig-paren">(</span>o<span class="sig-paren">)</span><a class="headerlink" href="#c.Py_TYPE" title="Permalink to this definition">¶</a></dt>
<dd><p>This macro is used to access the <code class="xref py py-attr docutils literal notranslate"><span class="pre">ob_type</span></code> member of a Python object.
It expands to:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="p">(((</span><span class="n">PyObject</span><span class="o">*</span><span class="p">)(</span><span class="n">o</span><span class="p">))</span><span class="o">-></span><span class="n">ob_type</span><span class="p">)</span>
</pre></div>
</div>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
</dd></dl>
<dl class="macro">
<dt id="c.Py_REFCNT">
<code class="descname">Py_REFCNT</code><span class="sig-paren">(</span>o<span class="sig-paren">)</span><a class="headerlink" href="#c.Py_REFCNT" title="Permalink to this definition">¶</a></dt>
<dd><p>This macro is used to access the <code class="xref py py-attr docutils literal notranslate"><span class="pre">ob_refcnt</span></code> member of a Python
object.
It expands to:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="p">(((</span><span class="n">PyObject</span><span class="o">*</span><span class="p">)(</span><span class="n">o</span><span class="p">))</span><span class="o">-></span><span class="n">ob_refcnt</span><span class="p">)</span>
</pre></div>
</div>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
</dd></dl>
<dl class="macro">
<dt id="c.Py_SIZE">
<code class="descname">Py_SIZE</code><span class="sig-paren">(</span>o<span class="sig-paren">)</span><a class="headerlink" href="#c.Py_SIZE" title="Permalink to this definition">¶</a></dt>
<dd><p>This macro is used to access the <code class="xref py py-attr docutils literal notranslate"><span class="pre">ob_size</span></code> member of a Python object.
It expands to:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="p">(((</span><span class="n">PyVarObject</span><span class="o">*</span><span class="p">)(</span><span class="n">o</span><span class="p">))</span><span class="o">-></span><span class="n">ob_size</span><span class="p">)</span>
</pre></div>
</div>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
</dd></dl>
<dl class="macro">
<dt id="c.PyObject_HEAD_INIT">
<code class="descname">PyObject_HEAD_INIT</code><span class="sig-paren">(</span>type<span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_HEAD_INIT" title="Permalink to this definition">¶</a></dt>
<dd><p>This is a macro which expands to initialization values for a new
<a class="reference internal" href="#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject</span></code></a> type. This macro expands to:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">_PyObject_EXTRA_INIT</span>
<span class="mi">1</span><span class="p">,</span> <span class="n">type</span><span class="p">,</span>
</pre></div>
</div>
</dd></dl>
<dl class="macro">
<dt id="c.PyVarObject_HEAD_INIT">
<code class="descname">PyVarObject_HEAD_INIT</code><span class="sig-paren">(</span>type, size<span class="sig-paren">)</span><a class="headerlink" href="#c.PyVarObject_HEAD_INIT" title="Permalink to this definition">¶</a></dt>
<dd><p>This is a macro which expands to initialization values for a new
<a class="reference internal" href="#c.PyVarObject" title="PyVarObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyVarObject</span></code></a> type, including the <code class="xref py py-attr docutils literal notranslate"><span class="pre">ob_size</span></code> field.
This macro expands to:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">_PyObject_EXTRA_INIT</span>
<span class="mi">1</span><span class="p">,</span> <span class="n">type</span><span class="p">,</span> <span class="n">size</span><span class="p">,</span>
</pre></div>
</div>
</dd></dl>
<dl class="type">
<dt id="c.PyCFunction">
<code class="descname">PyCFunction</code><a class="headerlink" href="#c.PyCFunction" title="Permalink to this definition">¶</a></dt>
<dd><p>Type of the functions used to implement most Python callables in C.
Functions of this type take two <a class="reference internal" href="#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject*</span></code></a> parameters and return
one such value. If the return value is <em>NULL</em>, an exception shall have
been set. If not <em>NULL</em>, the return value is interpreted as the return
value of the function as exposed in Python. The function must return a new
reference.</p>
</dd></dl>
<dl class="type">
<dt id="c.PyMethodDef">
<code class="descname">PyMethodDef</code><a class="headerlink" href="#c.PyMethodDef" title="Permalink to this definition">¶</a></dt>
<dd><p>Structure used to describe a method of an extension type. This structure has
four fields:</p>
<table border="1" class="docutils">
<colgroup>
<col width="29%" />
<col width="21%" />
<col width="50%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Field</th>
<th class="head">C Type</th>
<th class="head">Meaning</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="xref py py-attr docutils literal notranslate"><span class="pre">ml_name</span></code></td>
<td>char *</td>
<td>name of the method</td>
</tr>
<tr class="row-odd"><td><code class="xref py py-attr docutils literal notranslate"><span class="pre">ml_meth</span></code></td>
<td>PyCFunction</td>
<td>pointer to the C
implementation</td>
</tr>
<tr class="row-even"><td><code class="xref py py-attr docutils literal notranslate"><span class="pre">ml_flags</span></code></td>
<td>int</td>
<td>flag bits indicating how the
call should be constructed</td>
</tr>
<tr class="row-odd"><td><code class="xref py py-attr docutils literal notranslate"><span class="pre">ml_doc</span></code></td>
<td>char *</td>
<td>points to the contents of the
docstring</td>
</tr>
</tbody>
</table>
</dd></dl>
<p>The <code class="xref py py-attr docutils literal notranslate"><span class="pre">ml_meth</span></code> is a C function pointer. The functions may be of different
types, but they always return <a class="reference internal" href="#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject*</span></code></a>. If the function is not of
the <a class="reference internal" href="#c.PyCFunction" title="PyCFunction"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyCFunction</span></code></a>, the compiler will require a cast in the method table.
Even though <a class="reference internal" href="#c.PyCFunction" title="PyCFunction"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyCFunction</span></code></a> defines the first parameter as
<a class="reference internal" href="#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject*</span></code></a>, it is common that the method implementation uses the
specific C type of the <em>self</em> object.</p>
<p>The <code class="xref py py-attr docutils literal notranslate"><span class="pre">ml_flags</span></code> field is a bitfield which can include the following flags.
The individual flags indicate either a calling convention or a binding
convention. Of the calling convention flags, only <a class="reference internal" href="#METH_VARARGS" title="METH_VARARGS"><code class="xref py py-const docutils literal notranslate"><span class="pre">METH_VARARGS</span></code></a> and
<a class="reference internal" href="#METH_KEYWORDS" title="METH_KEYWORDS"><code class="xref py py-const docutils literal notranslate"><span class="pre">METH_KEYWORDS</span></code></a> can be combined. Any of the calling convention flags
can be combined with a binding flag.</p>
<dl class="data">
<dt id="METH_VARARGS">
<code class="descname">METH_VARARGS</code><a class="headerlink" href="#METH_VARARGS" title="Permalink to this definition">¶</a></dt>
<dd><p>This is the typical calling convention, where the methods have the type
<a class="reference internal" href="#c.PyCFunction" title="PyCFunction"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyCFunction</span></code></a>. The function expects two <a class="reference internal" href="#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject*</span></code></a> values.
The first one is the <em>self</em> object for methods; for module functions, it is
the module object. The second parameter (often called <em>args</em>) is a tuple
object representing all arguments. This parameter is typically processed
using <a class="reference internal" href="arg.html#c.PyArg_ParseTuple" title="PyArg_ParseTuple"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_ParseTuple()</span></code></a> or <a class="reference internal" href="arg.html#c.PyArg_UnpackTuple" title="PyArg_UnpackTuple"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_UnpackTuple()</span></code></a>.</p>
</dd></dl>
<dl class="data">
<dt id="METH_KEYWORDS">
<code class="descname">METH_KEYWORDS</code><a class="headerlink" href="#METH_KEYWORDS" title="Permalink to this definition">¶</a></dt>
<dd><p>Methods with these flags must be of type <code class="xref c c-type docutils literal notranslate"><span class="pre">PyCFunctionWithKeywords</span></code>.
The function expects three parameters: <em>self</em>, <em>args</em>, and a dictionary of
all the keyword arguments. The flag is typically combined with
<a class="reference internal" href="#METH_VARARGS" title="METH_VARARGS"><code class="xref py py-const docutils literal notranslate"><span class="pre">METH_VARARGS</span></code></a>, and the parameters are typically processed using
<a class="reference internal" href="arg.html#c.PyArg_ParseTupleAndKeywords" title="PyArg_ParseTupleAndKeywords"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_ParseTupleAndKeywords()</span></code></a>.</p>
</dd></dl>
<dl class="data">
<dt id="METH_NOARGS">
<code class="descname">METH_NOARGS</code><a class="headerlink" href="#METH_NOARGS" title="Permalink to this definition">¶</a></dt>
<dd><p>Methods without parameters don’t need to check whether arguments are given if
they are listed with the <a class="reference internal" href="#METH_NOARGS" title="METH_NOARGS"><code class="xref py py-const docutils literal notranslate"><span class="pre">METH_NOARGS</span></code></a> flag. They need to be of type
<a class="reference internal" href="#c.PyCFunction" title="PyCFunction"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyCFunction</span></code></a>. The first parameter is typically named <code class="docutils literal notranslate"><span class="pre">self</span></code> and
will hold a reference to the module or object instance. In all cases the
second parameter will be <em>NULL</em>.</p>
</dd></dl>
<dl class="data">
<dt id="METH_O">
<code class="descname">METH_O</code><a class="headerlink" href="#METH_O" title="Permalink to this definition">¶</a></dt>
<dd><p>Methods with a single object argument can be listed with the <a class="reference internal" href="#METH_O" title="METH_O"><code class="xref py py-const docutils literal notranslate"><span class="pre">METH_O</span></code></a>
flag, instead of invoking <a class="reference internal" href="arg.html#c.PyArg_ParseTuple" title="PyArg_ParseTuple"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_ParseTuple()</span></code></a> with a <code class="docutils literal notranslate"><span class="pre">"O"</span></code> argument.
They have the type <a class="reference internal" href="#c.PyCFunction" title="PyCFunction"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyCFunction</span></code></a>, with the <em>self</em> parameter, and a
<a class="reference internal" href="#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject*</span></code></a> parameter representing the single argument.</p>
</dd></dl>
<dl class="data">
<dt id="METH_OLDARGS">
<code class="descname">METH_OLDARGS</code><a class="headerlink" href="#METH_OLDARGS" title="Permalink to this definition">¶</a></dt>
<dd><p>This calling convention is deprecated. The method must be of type
<a class="reference internal" href="#c.PyCFunction" title="PyCFunction"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyCFunction</span></code></a>. The second argument is <em>NULL</em> if no arguments are
given, a single object if exactly one argument is given, and a tuple of
objects if more than one argument is given. There is no way for a function
using this convention to distinguish between a call with multiple arguments
and a call with a tuple as the only argument.</p>
</dd></dl>
<p>These two constants are not used to indicate the calling convention but the
binding when use with methods of classes. These may not be used for functions
defined for modules. At most one of these flags may be set for any given
method.</p>
<dl class="data">
<dt id="METH_CLASS">
<code class="descname">METH_CLASS</code><a class="headerlink" href="#METH_CLASS" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-0">The method will be passed the type object as the first parameter rather
than an instance of the type. This is used to create <em>class methods</em>,
similar to what is created when using the <a class="reference internal" href="../library/functions.html#classmethod" title="classmethod"><code class="xref py py-func docutils literal notranslate"><span class="pre">classmethod()</span></code></a> built-in
function.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.3.</span></p>
</div>
</dd></dl>
<dl class="data">
<dt id="METH_STATIC">
<code class="descname">METH_STATIC</code><a class="headerlink" href="#METH_STATIC" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-1">The method will be passed <em>NULL</em> as the first parameter rather than an
instance of the type. This is used to create <em>static methods</em>, similar to
what is created when using the <a class="reference internal" href="../library/functions.html#staticmethod" title="staticmethod"><code class="xref py py-func docutils literal notranslate"><span class="pre">staticmethod()</span></code></a> built-in function.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.3.</span></p>
</div>
</dd></dl>
<p>One other constant controls whether a method is loaded in place of another
definition with the same method name.</p>
<dl class="data">
<dt id="METH_COEXIST">
<code class="descname">METH_COEXIST</code><a class="headerlink" href="#METH_COEXIST" title="Permalink to this definition">¶</a></dt>
<dd><p>The method will be loaded in place of existing definitions. Without
<em>METH_COEXIST</em>, the default is to skip repeated definitions. Since slot
wrappers are loaded before the method table, the existence of a
<em>sq_contains</em> slot, for example, would generate a wrapped method named
<a class="reference internal" href="../reference/datamodel.html#object.__contains__" title="object.__contains__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__contains__()</span></code></a> and preclude the loading of a corresponding
PyCFunction with the same name. With the flag defined, the PyCFunction
will be loaded in place of the wrapper object and will co-exist with the
slot. This is helpful because calls to PyCFunctions are optimized more
than wrapper object calls.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
</dd></dl>
<dl class="type">
<dt id="c.PyMemberDef">
<code class="descname">PyMemberDef</code><a class="headerlink" href="#c.PyMemberDef" title="Permalink to this definition">¶</a></dt>
<dd><p>Structure which describes an attribute of a type which corresponds to a C
struct member. Its fields are:</p>
<table border="1" class="docutils">
<colgroup>
<col width="29%" />
<col width="21%" />
<col width="50%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Field</th>
<th class="head">C Type</th>
<th class="head">Meaning</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="xref py py-attr docutils literal notranslate"><span class="pre">name</span></code></td>
<td>char *</td>
<td>name of the member</td>
</tr>
<tr class="row-odd"><td><code class="xref py py-attr docutils literal notranslate"><span class="pre">type</span></code></td>
<td>int</td>
<td>the type of the member in the
C struct</td>
</tr>
<tr class="row-even"><td><code class="xref py py-attr docutils literal notranslate"><span class="pre">offset</span></code></td>
<td>Py_ssize_t</td>
<td>the offset in bytes that the
member is located on the
type’s object struct</td>
</tr>
<tr class="row-odd"><td><code class="xref py py-attr docutils literal notranslate"><span class="pre">flags</span></code></td>
<td>int</td>
<td>flag bits indicating if the
field should be read-only or
writable</td>
</tr>
<tr class="row-even"><td><code class="xref py py-attr docutils literal notranslate"><span class="pre">doc</span></code></td>
<td>char *</td>
<td>points to the contents of the
docstring</td>
</tr>
</tbody>
</table>
<p><code class="xref py py-attr docutils literal notranslate"><span class="pre">type</span></code> can be one of many <code class="docutils literal notranslate"><span class="pre">T_</span></code> macros corresponding to various C
types. When the member is accessed in Python, it will be converted to the
equivalent Python type.</p>
<table border="1" class="docutils">
<colgroup>
<col width="45%" />
<col width="55%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Macro name</th>
<th class="head">C type</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>T_SHORT</td>
<td>short</td>
</tr>
<tr class="row-odd"><td>T_INT</td>
<td>int</td>
</tr>
<tr class="row-even"><td>T_LONG</td>
<td>long</td>
</tr>
<tr class="row-odd"><td>T_FLOAT</td>
<td>float</td>
</tr>
<tr class="row-even"><td>T_DOUBLE</td>
<td>double</td>
</tr>
<tr class="row-odd"><td>T_STRING</td>
<td>char *</td>
</tr>
<tr class="row-even"><td>T_OBJECT</td>
<td>PyObject *</td>
</tr>
<tr class="row-odd"><td>T_OBJECT_EX</td>
<td>PyObject *</td>
</tr>
<tr class="row-even"><td>T_CHAR</td>
<td>char</td>
</tr>
<tr class="row-odd"><td>T_BYTE</td>
<td>char</td>
</tr>
<tr class="row-even"><td>T_UBYTE</td>
<td>unsigned char</td>
</tr>
<tr class="row-odd"><td>T_UINT</td>
<td>unsigned int</td>
</tr>
<tr class="row-even"><td>T_USHORT</td>
<td>unsigned short</td>
</tr>
<tr class="row-odd"><td>T_ULONG</td>
<td>unsigned long</td>
</tr>
<tr class="row-even"><td>T_BOOL</td>
<td>char</td>
</tr>
<tr class="row-odd"><td>T_LONGLONG</td>
<td>long long</td>
</tr>
<tr class="row-even"><td>T_ULONGLONG</td>
<td>unsigned long long</td>
</tr>
<tr class="row-odd"><td>T_PYSSIZET</td>
<td>Py_ssize_t</td>
</tr>
</tbody>
</table>
<p><code class="xref c c-macro docutils literal notranslate"><span class="pre">T_OBJECT</span></code> and <code class="xref c c-macro docutils literal notranslate"><span class="pre">T_OBJECT_EX</span></code> differ in that
<code class="xref c c-macro docutils literal notranslate"><span class="pre">T_OBJECT</span></code> returns <code class="docutils literal notranslate"><span class="pre">None</span></code> if the member is <em>NULL</em> and
<code class="xref c c-macro docutils literal notranslate"><span class="pre">T_OBJECT_EX</span></code> raises an <a class="reference internal" href="../library/exceptions.html#exceptions.AttributeError" title="exceptions.AttributeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">AttributeError</span></code></a>. Try to use
<code class="xref c c-macro docutils literal notranslate"><span class="pre">T_OBJECT_EX</span></code> over <code class="xref c c-macro docutils literal notranslate"><span class="pre">T_OBJECT</span></code> because <code class="xref c c-macro docutils literal notranslate"><span class="pre">T_OBJECT_EX</span></code>
handles use of the <a class="reference internal" href="../reference/simple_stmts.html#del"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">del</span></code></a> statement on that attribute more correctly
than <code class="xref c c-macro docutils literal notranslate"><span class="pre">T_OBJECT</span></code>.</p>
<p><code class="xref py py-attr docutils literal notranslate"><span class="pre">flags</span></code> can be <code class="docutils literal notranslate"><span class="pre">0</span></code> for write and read access or <code class="xref c c-macro docutils literal notranslate"><span class="pre">READONLY</span></code> for
read-only access. Using <code class="xref c c-macro docutils literal notranslate"><span class="pre">T_STRING</span></code> for <a class="reference internal" href="../library/functions.html#type" title="type"><code class="xref py py-attr docutils literal notranslate"><span class="pre">type</span></code></a> implies
<code class="xref c c-macro docutils literal notranslate"><span class="pre">READONLY</span></code>. Only <code class="xref c c-macro docutils literal notranslate"><span class="pre">T_OBJECT</span></code> and <code class="xref c c-macro docutils literal notranslate"><span class="pre">T_OBJECT_EX</span></code>
members can be deleted. (They are set to <em>NULL</em>).</p>
</dd></dl>
<dl class="type">
<dt id="c.PyGetSetDef">
<code class="descname">PyGetSetDef</code><a class="headerlink" href="#c.PyGetSetDef" title="Permalink to this definition">¶</a></dt>
<dd><p>Structure to define property-like access for a type. See also description of
the <a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_getset" title="PyTypeObject.tp_getset"><code class="xref c c-member docutils literal notranslate"><span class="pre">PyTypeObject.tp_getset</span></code></a> slot.</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="27%" />
<col width="53%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Field</th>
<th class="head">C Type</th>
<th class="head">Meaning</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>name</td>
<td>char *</td>
<td>attribute name</td>
</tr>
<tr class="row-odd"><td>get</td>
<td>getter</td>
<td>C Function to get the attribute</td>
</tr>
<tr class="row-even"><td>set</td>
<td>setter</td>
<td>optional C function to set or
delete the attribute, if omitted
the attribute is readonly</td>
</tr>
<tr class="row-odd"><td>doc</td>
<td>char *</td>
<td>optional docstring</td>
</tr>
<tr class="row-even"><td>closure</td>
<td>void *</td>
<td>optional function pointer,
providing additional data for
getter and setter</td>
</tr>
</tbody>
</table>
<p>The <code class="docutils literal notranslate"><span class="pre">get</span></code> function takes one <a class="reference internal" href="#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject*</span></code></a> parameter (the
instance) and a function pointer (the associated <code class="docutils literal notranslate"><span class="pre">closure</span></code>):</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">typedef</span> <span class="n">PyObject</span> <span class="o">*</span><span class="p">(</span><span class="o">*</span><span class="n">getter</span><span class="p">)(</span><span class="n">PyObject</span> <span class="o">*</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="p">);</span>
</pre></div>
</div>
<p>It should return a new reference on success or <em>NULL</em> with a set exception
on failure.</p>
<p><code class="docutils literal notranslate"><span class="pre">set</span></code> functions take two <a class="reference internal" href="#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject*</span></code></a> parameters (the instance and
the value to be set) and a function pointer (the associated <code class="docutils literal notranslate"><span class="pre">closure</span></code>):</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">typedef</span> <span class="nf">int</span> <span class="p">(</span><span class="o">*</span><span class="n">setter</span><span class="p">)(</span><span class="n">PyObject</span> <span class="o">*</span><span class="p">,</span> <span class="n">PyObject</span> <span class="o">*</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="p">);</span>
</pre></div>
</div>
<p>In case the attribute should be deleted the second parameter is <em>NULL</em>.
Should return <code class="docutils literal notranslate"><span class="pre">0</span></code> on success or <code class="docutils literal notranslate"><span class="pre">-1</span></code> with a set exception on failure.</p>
</dd></dl>
<dl class="function">
<dt id="c.Py_FindMethod">
<a class="reference internal" href="#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">Py_FindMethod</code><span class="sig-paren">(</span><a class="reference internal" href="#c.PyMethodDef" title="PyMethodDef">PyMethodDef</a><em> table[]</em>, <a class="reference internal" href="#c.PyObject" title="PyObject">PyObject</a><em> *ob</em>, char<em> *name</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_FindMethod" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a bound method object for an extension type implemented in C. This
can be useful in the implementation of a <a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_getattro" title="PyTypeObject.tp_getattro"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_getattro</span></code></a> or
<a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_getattr" title="PyTypeObject.tp_getattr"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_getattr</span></code></a> handler that does not use the
<a class="reference internal" href="object.html#c.PyObject_GenericGetAttr" title="PyObject_GenericGetAttr"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_GenericGetAttr()</span></code></a> function.</p>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="allocation.html"
title="previous chapter">Allocating Objects on the Heap</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="typeobj.html"
title="next chapter">Type Objects</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/structures.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="typeobj.html" title="Type Objects"
>next</a> |</li>
<li class="right" >
<a href="allocation.html" title="Allocating Objects on the Heap"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="objimpl.html" >Object Implementation Support</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\O+��R �R html/c-api/sys.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Operating System Utilities — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Importing Modules" href="import.html" />
<link rel="prev" title="Utilities" href="utilities.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/sys.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="import.html" title="Importing Modules"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="utilities.html" title="Utilities"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="utilities.html" accesskey="U">Utilities</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="operating-system-utilities">
<span id="os"></span><h1>Operating System Utilities<a class="headerlink" href="#operating-system-utilities" title="Permalink to this headline">¶</a></h1>
<dl class="function">
<dt id="c.Py_FdIsInteractive">
int <code class="descname">Py_FdIsInteractive</code><span class="sig-paren">(</span>FILE<em> *fp</em>, const char<em> *filename</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_FdIsInteractive" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true (nonzero) if the standard I/O file <em>fp</em> with name <em>filename</em> is
deemed interactive. This is the case for files for which <code class="docutils literal notranslate"><span class="pre">isatty(fileno(fp))</span></code>
is true. If the global flag <code class="xref c c-data docutils literal notranslate"><span class="pre">Py_InteractiveFlag</span></code> is true, this function
also returns true if the <em>filename</em> pointer is <em>NULL</em> or if the name is equal to
one of the strings <code class="docutils literal notranslate"><span class="pre">'<stdin>'</span></code> or <code class="docutils literal notranslate"><span class="pre">'???'</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyOS_AfterFork">
void <code class="descname">PyOS_AfterFork</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyOS_AfterFork" title="Permalink to this definition">¶</a></dt>
<dd><p>Function to update some internal state after a process fork; this should be
called in the new process if the Python interpreter will continue to be used.
If a new executable is loaded into the new process, this function does not need
to be called.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyOS_CheckStack">
int <code class="descname">PyOS_CheckStack</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyOS_CheckStack" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true when the interpreter runs out of stack space. This is a reliable
check, but is only available when <code class="xref py py-const docutils literal notranslate"><span class="pre">USE_STACKCHECK</span></code> is defined (currently
on Windows using the Microsoft Visual C++ compiler). <code class="xref py py-const docutils literal notranslate"><span class="pre">USE_STACKCHECK</span></code>
will be defined automatically; you should never change the definition in your
own code.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyOS_getsig">
PyOS_sighandler_t <code class="descname">PyOS_getsig</code><span class="sig-paren">(</span>int<em> i</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyOS_getsig" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the current signal handler for signal <em>i</em>. This is a thin wrapper around
either <code class="xref c c-func docutils literal notranslate"><span class="pre">sigaction()</span></code> or <code class="xref c c-func docutils literal notranslate"><span class="pre">signal()</span></code>. Do not call those functions
directly! <code class="xref c c-type docutils literal notranslate"><span class="pre">PyOS_sighandler_t</span></code> is a typedef alias for <code class="xref c c-type docutils literal notranslate"><span class="pre">void</span>
<span class="pre">(*)(int)</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyOS_setsig">
PyOS_sighandler_t <code class="descname">PyOS_setsig</code><span class="sig-paren">(</span>int<em> i</em>, PyOS_sighandler_t<em> h</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyOS_setsig" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the signal handler for signal <em>i</em> to be <em>h</em>; return the old signal handler.
This is a thin wrapper around either <code class="xref c c-func docutils literal notranslate"><span class="pre">sigaction()</span></code> or <code class="xref c c-func docutils literal notranslate"><span class="pre">signal()</span></code>. Do
not call those functions directly! <code class="xref c c-type docutils literal notranslate"><span class="pre">PyOS_sighandler_t</span></code> is a typedef
alias for <code class="xref c c-type docutils literal notranslate"><span class="pre">void</span> <span class="pre">(*)(int)</span></code>.</p>
</dd></dl>
</div>
<div class="section" id="system-functions">
<span id="systemfunctions"></span><h1>System Functions<a class="headerlink" href="#system-functions" title="Permalink to this headline">¶</a></h1>
<p>These are utility functions that make functionality from the <a class="reference internal" href="../library/sys.html#module-sys" title="sys: Access system-specific parameters and functions."><code class="xref py py-mod docutils literal notranslate"><span class="pre">sys</span></code></a> module
accessible to C code. They all work with the current interpreter thread’s
<a class="reference internal" href="../library/sys.html#module-sys" title="sys: Access system-specific parameters and functions."><code class="xref py py-mod docutils literal notranslate"><span class="pre">sys</span></code></a> module’s dict, which is contained in the internal thread state structure.</p>
<dl class="function">
<dt id="c.PySys_GetObject">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *<code class="descname">PySys_GetObject</code><span class="sig-paren">(</span>char<em> *name</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySys_GetObject" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Borrowed reference.</em><p>Return the object <em>name</em> from the <a class="reference internal" href="../library/sys.html#module-sys" title="sys: Access system-specific parameters and functions."><code class="xref py py-mod docutils literal notranslate"><span class="pre">sys</span></code></a> module or <em>NULL</em> if it does
not exist, without setting an exception.</p>
</dd></dl>
<dl class="function">
<dt id="c.PySys_GetFile">
FILE *<code class="descname">PySys_GetFile</code><span class="sig-paren">(</span>char<em> *name</em>, FILE<em> *def</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySys_GetFile" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the <code class="xref c c-type docutils literal notranslate"><span class="pre">FILE*</span></code> associated with the object <em>name</em> in the
<a class="reference internal" href="../library/sys.html#module-sys" title="sys: Access system-specific parameters and functions."><code class="xref py py-mod docutils literal notranslate"><span class="pre">sys</span></code></a> module, or <em>def</em> if <em>name</em> is not in the module or is not associated
with a <code class="xref c c-type docutils literal notranslate"><span class="pre">FILE*</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PySys_SetObject">
int <code class="descname">PySys_SetObject</code><span class="sig-paren">(</span>char<em> *name</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *v</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySys_SetObject" title="Permalink to this definition">¶</a></dt>
<dd><p>Set <em>name</em> in the <a class="reference internal" href="../library/sys.html#module-sys" title="sys: Access system-specific parameters and functions."><code class="xref py py-mod docutils literal notranslate"><span class="pre">sys</span></code></a> module to <em>v</em> unless <em>v</em> is <em>NULL</em>, in which
case <em>name</em> is deleted from the sys module. Returns <code class="docutils literal notranslate"><span class="pre">0</span></code> on success, <code class="docutils literal notranslate"><span class="pre">-1</span></code>
on error.</p>
</dd></dl>
<dl class="function">
<dt id="c.PySys_ResetWarnOptions">
void <code class="descname">PySys_ResetWarnOptions</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PySys_ResetWarnOptions" title="Permalink to this definition">¶</a></dt>
<dd><p>Reset <a class="reference internal" href="../library/sys.html#sys.warnoptions" title="sys.warnoptions"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.warnoptions</span></code></a> to an empty list.</p>
</dd></dl>
<dl class="function">
<dt id="c.PySys_AddWarnOption">
void <code class="descname">PySys_AddWarnOption</code><span class="sig-paren">(</span>char<em> *s</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySys_AddWarnOption" title="Permalink to this definition">¶</a></dt>
<dd><p>Append <em>s</em> to <a class="reference internal" href="../library/sys.html#sys.warnoptions" title="sys.warnoptions"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.warnoptions</span></code></a>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PySys_SetPath">
void <code class="descname">PySys_SetPath</code><span class="sig-paren">(</span>char<em> *path</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySys_SetPath" title="Permalink to this definition">¶</a></dt>
<dd><p>Set <a class="reference internal" href="../library/sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.path</span></code></a> to a list object of paths found in <em>path</em> which should
be a list of paths separated with the platform’s search path delimiter
(<code class="docutils literal notranslate"><span class="pre">:</span></code> on Unix, <code class="docutils literal notranslate"><span class="pre">;</span></code> on Windows).</p>
</dd></dl>
<dl class="function">
<dt id="c.PySys_WriteStdout">
void <code class="descname">PySys_WriteStdout</code><span class="sig-paren">(</span>const char<em> *format</em>, ...<span class="sig-paren">)</span><a class="headerlink" href="#c.PySys_WriteStdout" title="Permalink to this definition">¶</a></dt>
<dd><p>Write the output string described by <em>format</em> to <a class="reference internal" href="../library/sys.html#sys.stdout" title="sys.stdout"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stdout</span></code></a>. No
exceptions are raised, even if truncation occurs (see below).</p>
<p><em>format</em> should limit the total size of the formatted output string to
1000 bytes or less – after 1000 bytes, the output string is truncated.
In particular, this means that no unrestricted “%s” formats should occur;
these should be limited using “%.<N>s” where <N> is a decimal number
calculated so that <N> plus the maximum size of other formatted text does not
exceed 1000 bytes. Also watch out for “%f”, which can print hundreds of
digits for very large numbers.</p>
<p>If a problem occurs, or <a class="reference internal" href="../library/sys.html#sys.stdout" title="sys.stdout"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stdout</span></code></a> is unset, the formatted message
is written to the real (C level) <em>stdout</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PySys_WriteStderr">
void <code class="descname">PySys_WriteStderr</code><span class="sig-paren">(</span>const char<em> *format</em>, ...<span class="sig-paren">)</span><a class="headerlink" href="#c.PySys_WriteStderr" title="Permalink to this definition">¶</a></dt>
<dd><p>As above, but write to <a class="reference internal" href="../library/sys.html#sys.stderr" title="sys.stderr"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stderr</span></code></a> or <em>stderr</em> instead.</p>
</dd></dl>
</div>
<div class="section" id="process-control">
<span id="processcontrol"></span><h1>Process Control<a class="headerlink" href="#process-control" title="Permalink to this headline">¶</a></h1>
<dl class="function">
<dt id="c.Py_FatalError">
void <code class="descname">Py_FatalError</code><span class="sig-paren">(</span>const char<em> *message</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_FatalError" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-0">Print a fatal error message and kill the process. No cleanup is performed.
This function should only be invoked when a condition is detected that would
make it dangerous to continue using the Python interpreter; e.g., when the
object administration appears to be corrupted. On Unix, the standard C library
function <code class="xref c c-func docutils literal notranslate"><span class="pre">abort()</span></code> is called which will attempt to produce a <code class="file docutils literal notranslate"><span class="pre">core</span></code>
file.</p>
</dd></dl>
<dl class="function">
<dt id="c.Py_Exit">
void <code class="descname">Py_Exit</code><span class="sig-paren">(</span>int<em> status</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_Exit" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-1">Exit the current process. This calls <a class="reference internal" href="init.html#c.Py_Finalize" title="Py_Finalize"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_Finalize()</span></code></a> and then calls the
standard C library function <code class="docutils literal notranslate"><span class="pre">exit(status)</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.Py_AtExit">
int <code class="descname">Py_AtExit</code><span class="sig-paren">(</span>void (<em>*func</em>)()<span class="sig-paren">)</span><a class="headerlink" href="#c.Py_AtExit" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-2">Register a cleanup function to be called by <a class="reference internal" href="init.html#c.Py_Finalize" title="Py_Finalize"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_Finalize()</span></code></a>. The cleanup
function will be called with no arguments and should return no value. At most
32 cleanup functions can be registered. When the registration is successful,
<a class="reference internal" href="#c.Py_AtExit" title="Py_AtExit"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_AtExit()</span></code></a> returns <code class="docutils literal notranslate"><span class="pre">0</span></code>; on failure, it returns <code class="docutils literal notranslate"><span class="pre">-1</span></code>. The cleanup
function registered last is called first. Each cleanup function will be called
at most once. Since Python’s internal finalization will have completed before
the cleanup function, no Python APIs should be called by <em>func</em>.</p>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Operating System Utilities</a></li>
<li><a class="reference internal" href="#system-functions">System Functions</a></li>
<li><a class="reference internal" href="#process-control">Process Control</a></li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="utilities.html"
title="previous chapter">Utilities</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="import.html"
title="next chapter">Importing Modules</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/sys.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="import.html" title="Importing Modules"
>next</a> |</li>
<li class="right" >
<a href="utilities.html" title="Utilities"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="utilities.html" >Utilities</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\����S �S html/c-api/tuple.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Tuple Objects — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="List Objects" href="list.html" />
<link rel="prev" title="Buffers and Memoryview Objects" href="buffer.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/tuple.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="list.html" title="List Objects"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="buffer.html" title="Buffers and Memoryview Objects"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" accesskey="U">Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="tuple-objects">
<span id="tupleobjects"></span><h1>Tuple Objects<a class="headerlink" href="#tuple-objects" title="Permalink to this headline">¶</a></h1>
<span class="target" id="index-0"></span><dl class="type">
<dt id="c.PyTupleObject">
<code class="descname">PyTupleObject</code><a class="headerlink" href="#c.PyTupleObject" title="Permalink to this definition">¶</a></dt>
<dd><p>This subtype of <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject</span></code></a> represents a Python tuple object.</p>
</dd></dl>
<dl class="var">
<dt id="c.PyTuple_Type">
<a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a> <code class="descname">PyTuple_Type</code><a class="headerlink" href="#c.PyTuple_Type" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-1">This instance of <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyTypeObject</span></code></a> represents the Python tuple type; it is
the same object as <code class="docutils literal notranslate"><span class="pre">tuple</span></code> and <code class="docutils literal notranslate"><span class="pre">types.TupleType</span></code> in the Python layer..</p>
</dd></dl>
<dl class="function">
<dt id="c.PyTuple_Check">
int <code class="descname">PyTuple_Check</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyTuple_Check" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if <em>p</em> is a tuple object or an instance of a subtype of the tuple
type.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.2: </span>Allowed subtypes to be accepted.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyTuple_CheckExact">
int <code class="descname">PyTuple_CheckExact</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyTuple_CheckExact" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if <em>p</em> is a tuple object, but not an instance of a subtype of the
tuple type.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyTuple_New">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyTuple_New</code><span class="sig-paren">(</span>Py_ssize_t<em> len</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyTuple_New" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a new tuple object of size <em>len</em>, or <em>NULL</em> on failure.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>len</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyTuple_Pack">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyTuple_Pack</code><span class="sig-paren">(</span>Py_ssize_t<em> n</em>, ...<span class="sig-paren">)</span><a class="headerlink" href="#c.PyTuple_Pack" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a new tuple object of size <em>n</em>, or <em>NULL</em> on failure. The tuple values
are initialized to the subsequent <em>n</em> C arguments pointing to Python objects.
<code class="docutils literal notranslate"><span class="pre">PyTuple_Pack(2,</span> <span class="pre">a,</span> <span class="pre">b)</span></code> is equivalent to <code class="docutils literal notranslate"><span class="pre">Py_BuildValue("(OO)",</span> <span class="pre">a,</span> <span class="pre">b)</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>n</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyTuple_Size">
Py_ssize_t <code class="descname">PyTuple_Size</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyTuple_Size" title="Permalink to this definition">¶</a></dt>
<dd><p>Take a pointer to a tuple object, and return the size of that tuple.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function returned an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type. This might require changes
in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyTuple_GET_SIZE">
Py_ssize_t <code class="descname">PyTuple_GET_SIZE</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyTuple_GET_SIZE" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the size of the tuple <em>p</em>, which must be non-<em>NULL</em> and point to a tuple;
no error checking is performed.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function returned an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type. This might require changes
in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyTuple_GetItem">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyTuple_GetItem</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em>, Py_ssize_t<em> pos</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyTuple_GetItem" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Borrowed reference.</em><p>Return the object at position <em>pos</em> in the tuple pointed to by <em>p</em>. If <em>pos</em> is
out of bounds, return <em>NULL</em> and sets an <a class="reference internal" href="../library/exceptions.html#exceptions.IndexError" title="exceptions.IndexError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">IndexError</span></code></a> exception.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>pos</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyTuple_GET_ITEM">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyTuple_GET_ITEM</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em>, Py_ssize_t<em> pos</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyTuple_GET_ITEM" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Borrowed reference.</em><p>Like <a class="reference internal" href="#c.PyTuple_GetItem" title="PyTuple_GetItem"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyTuple_GetItem()</span></code></a>, but does no checking of its arguments.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>pos</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyTuple_GetSlice">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyTuple_GetSlice</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em>, Py_ssize_t<em> low</em>, Py_ssize_t<em> high</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyTuple_GetSlice" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Take a slice of the tuple pointed to by <em>p</em> from <em>low</em> to <em>high</em> and return it
as a new tuple.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>low</em> and <em>high</em>. This might
require changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyTuple_SetItem">
int <code class="descname">PyTuple_SetItem</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em>, Py_ssize_t<em> pos</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyTuple_SetItem" title="Permalink to this definition">¶</a></dt>
<dd><p>Insert a reference to object <em>o</em> at position <em>pos</em> of the tuple pointed to by
<em>p</em>. Return <code class="docutils literal notranslate"><span class="pre">0</span></code> on success.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This function “steals” a reference to <em>o</em>.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>pos</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyTuple_SET_ITEM">
void <code class="descname">PyTuple_SET_ITEM</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em>, Py_ssize_t<em> pos</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyTuple_SET_ITEM" title="Permalink to this definition">¶</a></dt>
<dd><p>Like <a class="reference internal" href="#c.PyTuple_SetItem" title="PyTuple_SetItem"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyTuple_SetItem()</span></code></a>, but does no error checking, and should <em>only</em> be
used to fill in brand new tuples.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This function “steals” a reference to <em>o</em>.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>pos</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c._PyTuple_Resize">
int <code class="descname">_PyTuple_Resize</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> **p</em>, Py_ssize_t<em> newsize</em><span class="sig-paren">)</span><a class="headerlink" href="#c._PyTuple_Resize" title="Permalink to this definition">¶</a></dt>
<dd><p>Can be used to resize a tuple. <em>newsize</em> will be the new length of the tuple.
Because tuples are <em>supposed</em> to be immutable, this should only be used if there
is only one reference to the object. Do <em>not</em> use this if the tuple may already
be known to some other part of the code. The tuple will always grow or shrink
at the end. Think of this as destroying the old tuple and creating a new one,
only more efficiently. Returns <code class="docutils literal notranslate"><span class="pre">0</span></code> on success. Client code should never
assume that the resulting value of <code class="docutils literal notranslate"><span class="pre">*p</span></code> will be the same as before calling
this function. If the object referenced by <code class="docutils literal notranslate"><span class="pre">*p</span></code> is replaced, the original
<code class="docutils literal notranslate"><span class="pre">*p</span></code> is destroyed. On failure, returns <code class="docutils literal notranslate"><span class="pre">-1</span></code> and sets <code class="docutils literal notranslate"><span class="pre">*p</span></code> to <em>NULL</em>, and
raises <a class="reference internal" href="../library/exceptions.html#exceptions.MemoryError" title="exceptions.MemoryError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">MemoryError</span></code></a> or <a class="reference internal" href="../library/exceptions.html#exceptions.SystemError" title="exceptions.SystemError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SystemError</span></code></a>.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.2: </span>Removed unused third parameter, <em>last_is_sticky</em>.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>newsize</em>. This might
require changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyTuple_ClearFreeList">
int <code class="descname">PyTuple_ClearFreeList</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyTuple_ClearFreeList" title="Permalink to this definition">¶</a></dt>
<dd><p>Clear the free list. Return the total number of freed items.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="buffer.html"
title="previous chapter">Buffers and Memoryview Objects</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="list.html"
title="next chapter">List Objects</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/tuple.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="list.html" title="List Objects"
>next</a> |</li>
<li class="right" >
<a href="buffer.html" title="Buffers and Memoryview Objects"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" >Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\�h���: �: html/c-api/type.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Type Objects — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="The None Object" href="none.html" />
<link rel="prev" title="Concrete Objects Layer" href="concrete.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/type.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="none.html" title="The None Object"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="concrete.html" title="Concrete Objects Layer"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" accesskey="U">Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="type-objects">
<span id="typeobjects"></span><h1>Type Objects<a class="headerlink" href="#type-objects" title="Permalink to this headline">¶</a></h1>
<span class="target" id="index-0"></span><dl class="type">
<dt id="c.PyTypeObject">
<code class="descname">PyTypeObject</code><a class="headerlink" href="#c.PyTypeObject" title="Permalink to this definition">¶</a></dt>
<dd><p>The C structure of the objects used to describe built-in types.</p>
</dd></dl>
<dl class="var">
<dt id="c.PyType_Type">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyType_Type</code><a class="headerlink" href="#c.PyType_Type" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-1">This is the type object for type objects; it is the same object as <code class="docutils literal notranslate"><span class="pre">type</span></code> and
<code class="docutils literal notranslate"><span class="pre">types.TypeType</span></code> in the Python layer.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyType_Check">
int <code class="descname">PyType_Check</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_Check" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if the object <em>o</em> is a type object, including instances of types
derived from the standard type object. Return false in all other cases.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyType_CheckExact">
int <code class="descname">PyType_CheckExact</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_CheckExact" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if the object <em>o</em> is a type object, but not a subtype of the
standard type object. Return false in all other cases.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyType_ClearCache">
unsigned int <code class="descname">PyType_ClearCache</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_ClearCache" title="Permalink to this definition">¶</a></dt>
<dd><p>Clear the internal lookup cache. Return the current version tag.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyType_Modified">
void <code class="descname">PyType_Modified</code><span class="sig-paren">(</span><a class="reference internal" href="#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a><em> *type</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_Modified" title="Permalink to this definition">¶</a></dt>
<dd><p>Invalidate the internal lookup cache for the type and all of its
subtypes. This function must be called after any manual
modification of the attributes or base classes of the type.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyType_HasFeature">
int <code class="descname">PyType_HasFeature</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em>, int<em> feature</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_HasFeature" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if the type object <em>o</em> sets the feature <em>feature</em>. Type features
are denoted by single bit flags.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyType_IS_GC">
int <code class="descname">PyType_IS_GC</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_IS_GC" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if the type object includes support for the cycle detector; this
tests the type flag <a class="reference internal" href="typeobj.html#Py_TPFLAGS_HAVE_GC" title="Py_TPFLAGS_HAVE_GC"><code class="xref py py-const docutils literal notranslate"><span class="pre">Py_TPFLAGS_HAVE_GC</span></code></a>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.0.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyType_IsSubtype">
int <code class="descname">PyType_IsSubtype</code><span class="sig-paren">(</span><a class="reference internal" href="#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a><em> *a</em>, <a class="reference internal" href="#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a><em> *b</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_IsSubtype" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if <em>a</em> is a subtype of <em>b</em>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
<p>This function only checks for actual subtypes, which means that
<a class="reference internal" href="../reference/datamodel.html#class.__subclasscheck__" title="class.__subclasscheck__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__subclasscheck__()</span></code></a> is not called on <em>b</em>. Call
<a class="reference internal" href="object.html#c.PyObject_IsSubclass" title="PyObject_IsSubclass"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_IsSubclass()</span></code></a> to do the same check that <a class="reference internal" href="../library/functions.html#issubclass" title="issubclass"><code class="xref py py-func docutils literal notranslate"><span class="pre">issubclass()</span></code></a>
would do.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyType_GenericAlloc">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyType_GenericAlloc</code><span class="sig-paren">(</span><a class="reference internal" href="#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a><em> *type</em>, Py_ssize_t<em> nitems</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_GenericAlloc" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>nitems</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyType_GenericNew">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyType_GenericNew</code><span class="sig-paren">(</span><a class="reference internal" href="#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a><em> *type</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *args</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *kwds</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_GenericNew" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyType_Ready">
int <code class="descname">PyType_Ready</code><span class="sig-paren">(</span><a class="reference internal" href="#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a><em> *type</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyType_Ready" title="Permalink to this definition">¶</a></dt>
<dd><p>Finalize a type object. This should be called on all type objects to finish
their initialization. This function is responsible for adding inherited slots
from a type’s base class. Return <code class="docutils literal notranslate"><span class="pre">0</span></code> on success, or return <code class="docutils literal notranslate"><span class="pre">-1</span></code> and sets an
exception on error.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="concrete.html"
title="previous chapter">Concrete Objects Layer</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="none.html"
title="next chapter">The <code class="docutils literal notranslate"><span class="pre">None</span></code> Object</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/type.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="none.html" title="The None Object"
>next</a> |</li>
<li class="right" >
<a href="concrete.html" title="Concrete Objects Layer"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" >Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\K�Yi�� �� html/c-api/typeobj.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Type Objects — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Supporting Cyclic Garbage Collection" href="gcsupport.html" />
<link rel="prev" title="Common Object Structures" href="structures.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/typeobj.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="gcsupport.html" title="Supporting Cyclic Garbage Collection"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="structures.html" title="Common Object Structures"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="objimpl.html" accesskey="U">Object Implementation Support</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="type-objects">
<span id="type-structs"></span><h1>Type Objects<a class="headerlink" href="#type-objects" title="Permalink to this headline">¶</a></h1>
<p>Perhaps one of the most important structures of the Python object system is the
structure that defines a new type: the <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyTypeObject</span></code></a> structure. Type
objects can be handled using any of the <code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_*()</span></code> or
<code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_*()</span></code> functions, but do not offer much that’s interesting to most
Python applications. These objects are fundamental to how objects behave, so
they are very important to the interpreter itself and to any extension module
that implements new types.</p>
<p>Type objects are fairly large compared to most of the standard types. The reason
for the size is that each type object stores a large number of values, mostly C
function pointers, each of which implements a small part of the type’s
functionality. The fields of the type object are examined in detail in this
section. The fields will be described in the order in which they occur in the
structure.</p>
<p>Typedefs: unaryfunc, binaryfunc, ternaryfunc, inquiry, coercion, intargfunc,
intintargfunc, intobjargproc, intintobjargproc, objobjargproc, destructor,
freefunc, printfunc, getattrfunc, getattrofunc, setattrfunc, setattrofunc,
cmpfunc, reprfunc, hashfunc</p>
<p>The structure definition for <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyTypeObject</span></code></a> can be found in
<code class="file docutils literal notranslate"><span class="pre">Include/object.h</span></code>. For convenience of reference, this repeats the
definition found there:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">typedef</span> <span class="k">struct</span> <span class="n">_typeobject</span> <span class="p">{</span>
<span class="n">PyObject_VAR_HEAD</span>
<span class="kt">char</span> <span class="o">*</span><span class="n">tp_name</span><span class="p">;</span> <span class="cm">/* For printing, in format "<module>.<name>" */</span>
<span class="kt">int</span> <span class="n">tp_basicsize</span><span class="p">,</span> <span class="n">tp_itemsize</span><span class="p">;</span> <span class="cm">/* For allocation */</span>
<span class="cm">/* Methods to implement standard operations */</span>
<span class="n">destructor</span> <span class="n">tp_dealloc</span><span class="p">;</span>
<span class="n">printfunc</span> <span class="n">tp_print</span><span class="p">;</span>
<span class="n">getattrfunc</span> <span class="n">tp_getattr</span><span class="p">;</span>
<span class="n">setattrfunc</span> <span class="n">tp_setattr</span><span class="p">;</span>
<span class="n">cmpfunc</span> <span class="n">tp_compare</span><span class="p">;</span>
<span class="n">reprfunc</span> <span class="n">tp_repr</span><span class="p">;</span>
<span class="cm">/* Method suites for standard classes */</span>
<span class="n">PyNumberMethods</span> <span class="o">*</span><span class="n">tp_as_number</span><span class="p">;</span>
<span class="n">PySequenceMethods</span> <span class="o">*</span><span class="n">tp_as_sequence</span><span class="p">;</span>
<span class="n">PyMappingMethods</span> <span class="o">*</span><span class="n">tp_as_mapping</span><span class="p">;</span>
<span class="cm">/* More standard operations (here for binary compatibility) */</span>
<span class="n">hashfunc</span> <span class="n">tp_hash</span><span class="p">;</span>
<span class="n">ternaryfunc</span> <span class="n">tp_call</span><span class="p">;</span>
<span class="n">reprfunc</span> <span class="n">tp_str</span><span class="p">;</span>
<span class="n">getattrofunc</span> <span class="n">tp_getattro</span><span class="p">;</span>
<span class="n">setattrofunc</span> <span class="n">tp_setattro</span><span class="p">;</span>
<span class="cm">/* Functions to access object as input/output buffer */</span>
<span class="n">PyBufferProcs</span> <span class="o">*</span><span class="n">tp_as_buffer</span><span class="p">;</span>
<span class="cm">/* Flags to define presence of optional/expanded features */</span>
<span class="kt">long</span> <span class="n">tp_flags</span><span class="p">;</span>
<span class="kt">char</span> <span class="o">*</span><span class="n">tp_doc</span><span class="p">;</span> <span class="cm">/* Documentation string */</span>
<span class="cm">/* Assigned meaning in release 2.0 */</span>
<span class="cm">/* call function for all accessible objects */</span>
<span class="n">traverseproc</span> <span class="n">tp_traverse</span><span class="p">;</span>
<span class="cm">/* delete references to contained objects */</span>
<span class="n">inquiry</span> <span class="n">tp_clear</span><span class="p">;</span>
<span class="cm">/* Assigned meaning in release 2.1 */</span>
<span class="cm">/* rich comparisons */</span>
<span class="n">richcmpfunc</span> <span class="n">tp_richcompare</span><span class="p">;</span>
<span class="cm">/* weak reference enabler */</span>
<span class="kt">long</span> <span class="n">tp_weaklistoffset</span><span class="p">;</span>
<span class="cm">/* Added in release 2.2 */</span>
<span class="cm">/* Iterators */</span>
<span class="n">getiterfunc</span> <span class="n">tp_iter</span><span class="p">;</span>
<span class="n">iternextfunc</span> <span class="n">tp_iternext</span><span class="p">;</span>
<span class="cm">/* Attribute descriptor and subclassing stuff */</span>
<span class="k">struct</span> <span class="n">PyMethodDef</span> <span class="o">*</span><span class="n">tp_methods</span><span class="p">;</span>
<span class="k">struct</span> <span class="n">PyMemberDef</span> <span class="o">*</span><span class="n">tp_members</span><span class="p">;</span>
<span class="k">struct</span> <span class="n">PyGetSetDef</span> <span class="o">*</span><span class="n">tp_getset</span><span class="p">;</span>
<span class="k">struct</span> <span class="n">_typeobject</span> <span class="o">*</span><span class="n">tp_base</span><span class="p">;</span>
<span class="n">PyObject</span> <span class="o">*</span><span class="n">tp_dict</span><span class="p">;</span>
<span class="n">descrgetfunc</span> <span class="n">tp_descr_get</span><span class="p">;</span>
<span class="n">descrsetfunc</span> <span class="n">tp_descr_set</span><span class="p">;</span>
<span class="kt">long</span> <span class="n">tp_dictoffset</span><span class="p">;</span>
<span class="n">initproc</span> <span class="n">tp_init</span><span class="p">;</span>
<span class="n">allocfunc</span> <span class="n">tp_alloc</span><span class="p">;</span>
<span class="n">newfunc</span> <span class="n">tp_new</span><span class="p">;</span>
<span class="n">freefunc</span> <span class="n">tp_free</span><span class="p">;</span> <span class="cm">/* Low-level free-memory routine */</span>
<span class="n">inquiry</span> <span class="n">tp_is_gc</span><span class="p">;</span> <span class="cm">/* For PyObject_IS_GC */</span>
<span class="n">PyObject</span> <span class="o">*</span><span class="n">tp_bases</span><span class="p">;</span>
<span class="n">PyObject</span> <span class="o">*</span><span class="n">tp_mro</span><span class="p">;</span> <span class="cm">/* method resolution order */</span>
<span class="n">PyObject</span> <span class="o">*</span><span class="n">tp_cache</span><span class="p">;</span>
<span class="n">PyObject</span> <span class="o">*</span><span class="n">tp_subclasses</span><span class="p">;</span>
<span class="n">PyObject</span> <span class="o">*</span><span class="n">tp_weaklist</span><span class="p">;</span>
<span class="p">}</span> <span class="n">PyTypeObject</span><span class="p">;</span>
</pre></div>
</div>
<p>The type object structure extends the <a class="reference internal" href="structures.html#c.PyVarObject" title="PyVarObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyVarObject</span></code></a> structure. The
<code class="xref py py-attr docutils literal notranslate"><span class="pre">ob_size</span></code> field is used for dynamic types (created by <code class="xref py py-func docutils literal notranslate"><span class="pre">type_new()</span></code>,
usually called from a class statement). Note that <a class="reference internal" href="type.html#c.PyType_Type" title="PyType_Type"><code class="xref c c-data docutils literal notranslate"><span class="pre">PyType_Type</span></code></a> (the
metatype) initializes <a class="reference internal" href="#c.PyTypeObject.tp_itemsize" title="PyTypeObject.tp_itemsize"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_itemsize</span></code></a>, which means that its instances (i.e.
type objects) <em>must</em> have the <code class="xref py py-attr docutils literal notranslate"><span class="pre">ob_size</span></code> field.</p>
<dl class="member">
<dt id="c.PyObject._ob_next">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyObject._ob_next</code><a class="headerlink" href="#c.PyObject._ob_next" title="Permalink to this definition">¶</a></dt>
<dt id="c.PyObject._ob_prev">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyObject._ob_prev</code><a class="headerlink" href="#c.PyObject._ob_prev" title="Permalink to this definition">¶</a></dt>
<dd><p>These fields are only present when the macro <code class="docutils literal notranslate"><span class="pre">Py_TRACE_REFS</span></code> is defined.
Their initialization to <em>NULL</em> is taken care of by the <code class="docutils literal notranslate"><span class="pre">PyObject_HEAD_INIT</span></code>
macro. For statically allocated objects, these fields always remain <em>NULL</em>.
For dynamically allocated objects, these two fields are used to link the object
into a doubly-linked list of <em>all</em> live objects on the heap. This could be used
for various debugging purposes; currently the only use is to print the objects
that are still alive at the end of a run when the environment variable
<span class="target" id="index-0"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONDUMPREFS"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONDUMPREFS</span></code></a> is set.</p>
<p>These fields are not inherited by subtypes.</p>
</dd></dl>
<dl class="member">
<dt id="c.PyObject.ob_refcnt">
Py_ssize_t <code class="descname">PyObject.ob_refcnt</code><a class="headerlink" href="#c.PyObject.ob_refcnt" title="Permalink to this definition">¶</a></dt>
<dd><p>This is the type object’s reference count, initialized to <code class="docutils literal notranslate"><span class="pre">1</span></code> by the
<code class="docutils literal notranslate"><span class="pre">PyObject_HEAD_INIT</span></code> macro. Note that for statically allocated type objects,
the type’s instances (objects whose <code class="xref py py-attr docutils literal notranslate"><span class="pre">ob_type</span></code> points back to the type) do
<em>not</em> count as references. But for dynamically allocated type objects, the
instances <em>do</em> count as references.</p>
<p>This field is not inherited by subtypes.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This field used to be an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type. This might require changes
in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="member">
<dt id="c.PyObject.ob_type">
<a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a>* <code class="descname">PyObject.ob_type</code><a class="headerlink" href="#c.PyObject.ob_type" title="Permalink to this definition">¶</a></dt>
<dd><p>This is the type’s type, in other words its metatype. It is initialized by the
argument to the <code class="docutils literal notranslate"><span class="pre">PyObject_HEAD_INIT</span></code> macro, and its value should normally be
<code class="docutils literal notranslate"><span class="pre">&PyType_Type</span></code>. However, for dynamically loadable extension modules that must
be usable on Windows (at least), the compiler complains that this is not a valid
initializer. Therefore, the convention is to pass <em>NULL</em> to the
<code class="docutils literal notranslate"><span class="pre">PyObject_HEAD_INIT</span></code> macro and to initialize this field explicitly at the
start of the module’s initialization function, before doing anything else. This
is typically done like this:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">Foo_Type</span><span class="p">.</span><span class="n">ob_type</span> <span class="o">=</span> <span class="o">&</span><span class="n">PyType_Type</span><span class="p">;</span>
</pre></div>
</div>
<p>This should be done before any instances of the type are created.
<a class="reference internal" href="type.html#c.PyType_Ready" title="PyType_Ready"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_Ready()</span></code></a> checks if <code class="xref py py-attr docutils literal notranslate"><span class="pre">ob_type</span></code> is <em>NULL</em>, and if so,
initializes it: in Python 2.2, it is set to <code class="docutils literal notranslate"><span class="pre">&PyType_Type</span></code>; in Python 2.2.1
and later it is initialized to the <code class="xref py py-attr docutils literal notranslate"><span class="pre">ob_type</span></code> field of the base class.
<a class="reference internal" href="type.html#c.PyType_Ready" title="PyType_Ready"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_Ready()</span></code></a> will not change this field if it is non-zero.</p>
<p>In Python 2.2, this field is not inherited by subtypes. In 2.2.1, and in 2.3
and beyond, it is inherited by subtypes.</p>
</dd></dl>
<dl class="member">
<dt id="c.PyVarObject.ob_size">
Py_ssize_t <code class="descname">PyVarObject.ob_size</code><a class="headerlink" href="#c.PyVarObject.ob_size" title="Permalink to this definition">¶</a></dt>
<dd><p>For statically allocated type objects, this should be initialized to zero. For
dynamically allocated type objects, this field has a special internal meaning.</p>
<p>This field is not inherited by subtypes.</p>
</dd></dl>
<dl class="member">
<dt id="c.PyTypeObject.tp_name">
char* <code class="descname">PyTypeObject.tp_name</code><a class="headerlink" href="#c.PyTypeObject.tp_name" title="Permalink to this definition">¶</a></dt>
<dd><p>Pointer to a NUL-terminated string containing the name of the type. For types
that are accessible as module globals, the string should be the full module
name, followed by a dot, followed by the type name; for built-in types, it
should be just the type name. If the module is a submodule of a package, the
full package name is part of the full module name. For example, a type named
<code class="xref py py-class docutils literal notranslate"><span class="pre">T</span></code> defined in module <code class="xref py py-mod docutils literal notranslate"><span class="pre">M</span></code> in subpackage <code class="xref py py-mod docutils literal notranslate"><span class="pre">Q</span></code> in package <code class="xref py py-mod docutils literal notranslate"><span class="pre">P</span></code>
should have the <a class="reference internal" href="#c.PyTypeObject.tp_name" title="PyTypeObject.tp_name"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_name</span></code></a> initializer <code class="docutils literal notranslate"><span class="pre">"P.Q.M.T"</span></code>.</p>
<p>For dynamically allocated type objects, this should just be the type name, and
the module name explicitly stored in the type dict as the value for key
<code class="docutils literal notranslate"><span class="pre">'__module__'</span></code>.</p>
<p>For statically allocated type objects, the tp_name field should contain a dot.
Everything before the last dot is made accessible as the <code class="xref py py-attr docutils literal notranslate"><span class="pre">__module__</span></code>
attribute, and everything after the last dot is made accessible as the
<a class="reference internal" href="../library/stdtypes.html#definition.__name__" title="definition.__name__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__name__</span></code></a> attribute.</p>
<p>If no dot is present, the entire <a class="reference internal" href="#c.PyTypeObject.tp_name" title="PyTypeObject.tp_name"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_name</span></code></a> field is made accessible as the
<a class="reference internal" href="../library/stdtypes.html#definition.__name__" title="definition.__name__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__name__</span></code></a> attribute, and the <code class="xref py py-attr docutils literal notranslate"><span class="pre">__module__</span></code> attribute is undefined
(unless explicitly set in the dictionary, as explained above). This means your
type will be impossible to pickle. Additionally, it will not be listed in
module documentations created with pydoc.</p>
<p>This field is not inherited by subtypes.</p>
</dd></dl>
<dl class="member">
<dt id="c.PyTypeObject.tp_basicsize">
Py_ssize_t <code class="descname">PyTypeObject.tp_basicsize</code><a class="headerlink" href="#c.PyTypeObject.tp_basicsize" title="Permalink to this definition">¶</a></dt>
<dt id="c.PyTypeObject.tp_itemsize">
Py_ssize_t <code class="descname">PyTypeObject.tp_itemsize</code><a class="headerlink" href="#c.PyTypeObject.tp_itemsize" title="Permalink to this definition">¶</a></dt>
<dd><p>These fields allow calculating the size in bytes of instances of the type.</p>
<p>There are two kinds of types: types with fixed-length instances have a zero
<a class="reference internal" href="#c.PyTypeObject.tp_itemsize" title="PyTypeObject.tp_itemsize"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_itemsize</span></code></a> field, types with variable-length instances have a non-zero
<a class="reference internal" href="#c.PyTypeObject.tp_itemsize" title="PyTypeObject.tp_itemsize"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_itemsize</span></code></a> field. For a type with fixed-length instances, all
instances have the same size, given in <a class="reference internal" href="#c.PyTypeObject.tp_basicsize" title="PyTypeObject.tp_basicsize"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_basicsize</span></code></a>.</p>
<p>For a type with variable-length instances, the instances must have an
<code class="xref py py-attr docutils literal notranslate"><span class="pre">ob_size</span></code> field, and the instance size is <a class="reference internal" href="#c.PyTypeObject.tp_basicsize" title="PyTypeObject.tp_basicsize"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_basicsize</span></code></a> plus N
times <a class="reference internal" href="#c.PyTypeObject.tp_itemsize" title="PyTypeObject.tp_itemsize"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_itemsize</span></code></a>, where N is the “length” of the object. The value of
N is typically stored in the instance’s <code class="xref py py-attr docutils literal notranslate"><span class="pre">ob_size</span></code> field. There are
exceptions: for example, long ints use a negative <code class="xref py py-attr docutils literal notranslate"><span class="pre">ob_size</span></code> to indicate a
negative number, and N is <code class="docutils literal notranslate"><span class="pre">abs(ob_size)</span></code> there. Also, the presence of an
<code class="xref py py-attr docutils literal notranslate"><span class="pre">ob_size</span></code> field in the instance layout doesn’t mean that the instance
structure is variable-length (for example, the structure for the list type has
fixed-length instances, yet those instances have a meaningful <code class="xref py py-attr docutils literal notranslate"><span class="pre">ob_size</span></code>
field).</p>
<p>The basic size includes the fields in the instance declared by the macro
<a class="reference internal" href="structures.html#c.PyObject_HEAD" title="PyObject_HEAD"><code class="xref c c-macro docutils literal notranslate"><span class="pre">PyObject_HEAD</span></code></a> or <a class="reference internal" href="structures.html#c.PyObject_VAR_HEAD" title="PyObject_VAR_HEAD"><code class="xref c c-macro docutils literal notranslate"><span class="pre">PyObject_VAR_HEAD</span></code></a> (whichever is used to
declare the instance struct) and this in turn includes the <code class="xref py py-attr docutils literal notranslate"><span class="pre">_ob_prev</span></code> and
<code class="xref py py-attr docutils literal notranslate"><span class="pre">_ob_next</span></code> fields if they are present. This means that the only correct
way to get an initializer for the <a class="reference internal" href="#c.PyTypeObject.tp_basicsize" title="PyTypeObject.tp_basicsize"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_basicsize</span></code></a> is to use the
<code class="docutils literal notranslate"><span class="pre">sizeof</span></code> operator on the struct used to declare the instance layout.
The basic size does not include the GC header size (this is new in Python 2.2;
in 2.1 and 2.0, the GC header size was included in <a class="reference internal" href="#c.PyTypeObject.tp_basicsize" title="PyTypeObject.tp_basicsize"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_basicsize</span></code></a>).</p>
<p>These fields are inherited separately by subtypes. If the base type has a
non-zero <a class="reference internal" href="#c.PyTypeObject.tp_itemsize" title="PyTypeObject.tp_itemsize"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_itemsize</span></code></a>, it is generally not safe to set
<a class="reference internal" href="#c.PyTypeObject.tp_itemsize" title="PyTypeObject.tp_itemsize"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_itemsize</span></code></a> to a different non-zero value in a subtype (though this
depends on the implementation of the base type).</p>
<p>A note about alignment: if the variable items require a particular alignment,
this should be taken care of by the value of <a class="reference internal" href="#c.PyTypeObject.tp_basicsize" title="PyTypeObject.tp_basicsize"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_basicsize</span></code></a>. Example:
suppose a type implements an array of <code class="docutils literal notranslate"><span class="pre">double</span></code>. <a class="reference internal" href="#c.PyTypeObject.tp_itemsize" title="PyTypeObject.tp_itemsize"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_itemsize</span></code></a> is
<code class="docutils literal notranslate"><span class="pre">sizeof(double)</span></code>. It is the programmer’s responsibility that
<a class="reference internal" href="#c.PyTypeObject.tp_basicsize" title="PyTypeObject.tp_basicsize"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_basicsize</span></code></a> is a multiple of <code class="docutils literal notranslate"><span class="pre">sizeof(double)</span></code> (assuming this is the
alignment requirement for <code class="docutils literal notranslate"><span class="pre">double</span></code>).</p>
</dd></dl>
<dl class="member">
<dt id="c.PyTypeObject.tp_dealloc">
destructor <code class="descname">PyTypeObject.tp_dealloc</code><a class="headerlink" href="#c.PyTypeObject.tp_dealloc" title="Permalink to this definition">¶</a></dt>
<dd><p>A pointer to the instance destructor function. This function must be defined
unless the type guarantees that its instances will never be deallocated (as is
the case for the singletons <code class="docutils literal notranslate"><span class="pre">None</span></code> and <code class="docutils literal notranslate"><span class="pre">Ellipsis</span></code>).</p>
<p>The destructor function is called by the <a class="reference internal" href="refcounting.html#c.Py_DECREF" title="Py_DECREF"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_DECREF()</span></code></a> and
<a class="reference internal" href="refcounting.html#c.Py_XDECREF" title="Py_XDECREF"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_XDECREF()</span></code></a> macros when the new reference count is zero. At this point,
the instance is still in existence, but there are no references to it. The
destructor function should free all references which the instance owns, free all
memory buffers owned by the instance (using the freeing function corresponding
to the allocation function used to allocate the buffer), and finally (as its
last action) call the type’s <a class="reference internal" href="#c.PyTypeObject.tp_free" title="PyTypeObject.tp_free"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_free</span></code></a> function. If the type is not
subtypable (doesn’t have the <a class="reference internal" href="#Py_TPFLAGS_BASETYPE" title="Py_TPFLAGS_BASETYPE"><code class="xref py py-const docutils literal notranslate"><span class="pre">Py_TPFLAGS_BASETYPE</span></code></a> flag bit set), it is
permissible to call the object deallocator directly instead of via
<a class="reference internal" href="#c.PyTypeObject.tp_free" title="PyTypeObject.tp_free"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_free</span></code></a>. The object deallocator should be the one used to allocate the
instance; this is normally <a class="reference internal" href="allocation.html#c.PyObject_Del" title="PyObject_Del"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_Del()</span></code></a> if the instance was allocated
using <a class="reference internal" href="allocation.html#c.PyObject_New" title="PyObject_New"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_New()</span></code></a> or <code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_VarNew()</span></code>, or
<a class="reference internal" href="gcsupport.html#c.PyObject_GC_Del" title="PyObject_GC_Del"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_GC_Del()</span></code></a> if the instance was allocated using
<a class="reference internal" href="gcsupport.html#c.PyObject_GC_New" title="PyObject_GC_New"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_GC_New()</span></code></a> or <a class="reference internal" href="gcsupport.html#c.PyObject_GC_NewVar" title="PyObject_GC_NewVar"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_GC_NewVar()</span></code></a>.</p>
<p>This field is inherited by subtypes.</p>
</dd></dl>
<dl class="member">
<dt id="c.PyTypeObject.tp_print">
printfunc <code class="descname">PyTypeObject.tp_print</code><a class="headerlink" href="#c.PyTypeObject.tp_print" title="Permalink to this definition">¶</a></dt>
<dd><p>An optional pointer to the instance print function.</p>
<p>The print function is only called when the instance is printed to a <em>real</em> file;
when it is printed to a pseudo-file (like a <a class="reference internal" href="../library/stringio.html#StringIO.StringIO" title="StringIO.StringIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">StringIO</span></code></a> instance), the
instance’s <a class="reference internal" href="#c.PyTypeObject.tp_repr" title="PyTypeObject.tp_repr"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_repr</span></code></a> or <a class="reference internal" href="#c.PyTypeObject.tp_str" title="PyTypeObject.tp_str"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_str</span></code></a> function is called to convert it to
a string. These are also called when the type’s <a class="reference internal" href="#c.PyTypeObject.tp_print" title="PyTypeObject.tp_print"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_print</span></code></a> field is
<em>NULL</em>. A type should never implement <a class="reference internal" href="#c.PyTypeObject.tp_print" title="PyTypeObject.tp_print"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_print</span></code></a> in a way that produces
different output than <a class="reference internal" href="#c.PyTypeObject.tp_repr" title="PyTypeObject.tp_repr"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_repr</span></code></a> or <a class="reference internal" href="#c.PyTypeObject.tp_str" title="PyTypeObject.tp_str"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_str</span></code></a> would.</p>
<p>The print function is called with the same signature as <a class="reference internal" href="object.html#c.PyObject_Print" title="PyObject_Print"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_Print()</span></code></a>:
<code class="docutils literal notranslate"><span class="pre">int</span> <span class="pre">tp_print(PyObject</span> <span class="pre">*self,</span> <span class="pre">FILE</span> <span class="pre">*file,</span> <span class="pre">int</span> <span class="pre">flags)</span></code>. The <em>self</em> argument is
the instance to be printed. The <em>file</em> argument is the stdio file to which it
is to be printed. The <em>flags</em> argument is composed of flag bits. The only flag
bit currently defined is <code class="xref py py-const docutils literal notranslate"><span class="pre">Py_PRINT_RAW</span></code>. When the <code class="xref py py-const docutils literal notranslate"><span class="pre">Py_PRINT_RAW</span></code>
flag bit is set, the instance should be printed the same way as <a class="reference internal" href="#c.PyTypeObject.tp_str" title="PyTypeObject.tp_str"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_str</span></code></a>
would format it; when the <code class="xref py py-const docutils literal notranslate"><span class="pre">Py_PRINT_RAW</span></code> flag bit is clear, the instance
should be printed the same was as <a class="reference internal" href="#c.PyTypeObject.tp_repr" title="PyTypeObject.tp_repr"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_repr</span></code></a> would format it. It should
return <code class="docutils literal notranslate"><span class="pre">-1</span></code> and set an exception condition when an error occurred during the
comparison.</p>
<p>It is possible that the <a class="reference internal" href="#c.PyTypeObject.tp_print" title="PyTypeObject.tp_print"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_print</span></code></a> field will be deprecated. In any case,
it is recommended not to define <a class="reference internal" href="#c.PyTypeObject.tp_print" title="PyTypeObject.tp_print"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_print</span></code></a>, but instead to rely on
<a class="reference internal" href="#c.PyTypeObject.tp_repr" title="PyTypeObject.tp_repr"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_repr</span></code></a> and <a class="reference internal" href="#c.PyTypeObject.tp_str" title="PyTypeObject.tp_str"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_str</span></code></a> for printing.</p>
<p>This field is inherited by subtypes.</p>
</dd></dl>
<dl class="member">
<dt id="c.PyTypeObject.tp_getattr">
getattrfunc <code class="descname">PyTypeObject.tp_getattr</code><a class="headerlink" href="#c.PyTypeObject.tp_getattr" title="Permalink to this definition">¶</a></dt>
<dd><p>An optional pointer to the get-attribute-string function.</p>
<p>This field is deprecated. When it is defined, it should point to a function
that acts the same as the <a class="reference internal" href="#c.PyTypeObject.tp_getattro" title="PyTypeObject.tp_getattro"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_getattro</span></code></a> function, but taking a C string
instead of a Python string object to give the attribute name. The signature is</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">PyObject</span> <span class="o">*</span> <span class="nf">tp_getattr</span><span class="p">(</span><span class="n">PyObject</span> <span class="o">*</span><span class="n">o</span><span class="p">,</span> <span class="kt">char</span> <span class="o">*</span><span class="n">attr_name</span><span class="p">);</span>
</pre></div>
</div>
<p>This field is inherited by subtypes together with <a class="reference internal" href="#c.PyTypeObject.tp_getattro" title="PyTypeObject.tp_getattro"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_getattro</span></code></a>: a subtype
inherits both <a class="reference internal" href="#c.PyTypeObject.tp_getattr" title="PyTypeObject.tp_getattr"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_getattr</span></code></a> and <a class="reference internal" href="#c.PyTypeObject.tp_getattro" title="PyTypeObject.tp_getattro"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_getattro</span></code></a> from its base type when
the subtype’s <a class="reference internal" href="#c.PyTypeObject.tp_getattr" title="PyTypeObject.tp_getattr"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_getattr</span></code></a> and <a class="reference internal" href="#c.PyTypeObject.tp_getattro" title="PyTypeObject.tp_getattro"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_getattro</span></code></a> are both <em>NULL</em>.</p>
</dd></dl>
<dl class="member">
<dt id="c.PyTypeObject.tp_setattr">
setattrfunc <code class="descname">PyTypeObject.tp_setattr</code><a class="headerlink" href="#c.PyTypeObject.tp_setattr" title="Permalink to this definition">¶</a></dt>
<dd><p>An optional pointer to the function for setting and deleting attributes.</p>
<p>This field is deprecated. When it is defined, it should point to a function
that acts the same as the <a class="reference internal" href="#c.PyTypeObject.tp_setattro" title="PyTypeObject.tp_setattro"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_setattro</span></code></a> function, but taking a C string
instead of a Python string object to give the attribute name. The signature is</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">PyObject</span> <span class="o">*</span> <span class="nf">tp_setattr</span><span class="p">(</span><span class="n">PyObject</span> <span class="o">*</span><span class="n">o</span><span class="p">,</span> <span class="kt">char</span> <span class="o">*</span><span class="n">attr_name</span><span class="p">,</span> <span class="n">PyObject</span> <span class="o">*</span><span class="n">v</span><span class="p">);</span>
</pre></div>
</div>
<p>The <em>v</em> argument is set to <em>NULL</em> to delete the attribute.
This field is inherited by subtypes together with <a class="reference internal" href="#c.PyTypeObject.tp_setattro" title="PyTypeObject.tp_setattro"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_setattro</span></code></a>: a subtype
inherits both <a class="reference internal" href="#c.PyTypeObject.tp_setattr" title="PyTypeObject.tp_setattr"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_setattr</span></code></a> and <a class="reference internal" href="#c.PyTypeObject.tp_setattro" title="PyTypeObject.tp_setattro"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_setattro</span></code></a> from its base type when
the subtype’s <a class="reference internal" href="#c.PyTypeObject.tp_setattr" title="PyTypeObject.tp_setattr"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_setattr</span></code></a> and <a class="reference internal" href="#c.PyTypeObject.tp_setattro" title="PyTypeObject.tp_setattro"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_setattro</span></code></a> are both <em>NULL</em>.</p>
</dd></dl>
<dl class="member">
<dt id="c.PyTypeObject.tp_compare">
cmpfunc <code class="descname">PyTypeObject.tp_compare</code><a class="headerlink" href="#c.PyTypeObject.tp_compare" title="Permalink to this definition">¶</a></dt>
<dd><p>An optional pointer to the three-way comparison function.</p>
<p>The signature is the same as for <a class="reference internal" href="object.html#c.PyObject_Compare" title="PyObject_Compare"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_Compare()</span></code></a>. The function should
return <code class="docutils literal notranslate"><span class="pre">1</span></code> if <em>self</em> greater than <em>other</em>, <code class="docutils literal notranslate"><span class="pre">0</span></code> if <em>self</em> is equal to
<em>other</em>, and <code class="docutils literal notranslate"><span class="pre">-1</span></code> if <em>self</em> less than <em>other</em>. It should return <code class="docutils literal notranslate"><span class="pre">-1</span></code> and
set an exception condition when an error occurred during the comparison.</p>
<p>This field is inherited by subtypes together with <a class="reference internal" href="#c.PyTypeObject.tp_richcompare" title="PyTypeObject.tp_richcompare"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_richcompare</span></code></a> and
<a class="reference internal" href="#c.PyTypeObject.tp_hash" title="PyTypeObject.tp_hash"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_hash</span></code></a>: a subtypes inherits all three of <a class="reference internal" href="#c.PyTypeObject.tp_compare" title="PyTypeObject.tp_compare"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_compare</span></code></a>,
<a class="reference internal" href="#c.PyTypeObject.tp_richcompare" title="PyTypeObject.tp_richcompare"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_richcompare</span></code></a>, and <a class="reference internal" href="#c.PyTypeObject.tp_hash" title="PyTypeObject.tp_hash"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_hash</span></code></a> when the subtype’s
<a class="reference internal" href="#c.PyTypeObject.tp_compare" title="PyTypeObject.tp_compare"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_compare</span></code></a>, <a class="reference internal" href="#c.PyTypeObject.tp_richcompare" title="PyTypeObject.tp_richcompare"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_richcompare</span></code></a>, and <a class="reference internal" href="#c.PyTypeObject.tp_hash" title="PyTypeObject.tp_hash"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_hash</span></code></a> are all <em>NULL</em>.</p>
</dd></dl>
<dl class="member">
<dt id="c.PyTypeObject.tp_repr">
reprfunc <code class="descname">PyTypeObject.tp_repr</code><a class="headerlink" href="#c.PyTypeObject.tp_repr" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-1">An optional pointer to a function that implements the built-in function
<a class="reference internal" href="../library/functions.html#repr" title="repr"><code class="xref py py-func docutils literal notranslate"><span class="pre">repr()</span></code></a>.</p>
<p>The signature is the same as for <a class="reference internal" href="object.html#c.PyObject_Repr" title="PyObject_Repr"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_Repr()</span></code></a>; it must return a string
or a Unicode object. Ideally, this function should return a string that, when
passed to <a class="reference internal" href="../library/functions.html#eval" title="eval"><code class="xref py py-func docutils literal notranslate"><span class="pre">eval()</span></code></a>, given a suitable environment, returns an object with the
same value. If this is not feasible, it should return a string starting with
<code class="docutils literal notranslate"><span class="pre">'<'</span></code> and ending with <code class="docutils literal notranslate"><span class="pre">'>'</span></code> from which both the type and the value of the
object can be deduced.</p>
<p>When this field is not set, a string of the form <code class="docutils literal notranslate"><span class="pre"><%s</span> <span class="pre">object</span> <span class="pre">at</span> <span class="pre">%p></span></code> is
returned, where <code class="docutils literal notranslate"><span class="pre">%s</span></code> is replaced by the type name, and <code class="docutils literal notranslate"><span class="pre">%p</span></code> by the object’s
memory address.</p>
<p>This field is inherited by subtypes.</p>
</dd></dl>
<dl class="member">
<dt id="c.tp_as_number">
<a class="reference internal" href="#c.PyNumberMethods" title="PyNumberMethods">PyNumberMethods</a>* <code class="descname">tp_as_number</code><a class="headerlink" href="#c.tp_as_number" title="Permalink to this definition">¶</a></dt>
<dd><p>Pointer to an additional structure that contains fields relevant only to
objects which implement the number protocol. These fields are documented in
<a class="reference internal" href="#number-structs"><span class="std std-ref">Number Object Structures</span></a>.</p>
<p>The <code class="xref c c-member docutils literal notranslate"><span class="pre">tp_as_number</span></code> field is not inherited, but the contained fields are
inherited individually.</p>
</dd></dl>
<dl class="member">
<dt id="c.tp_as_sequence">
<a class="reference internal" href="#c.PySequenceMethods" title="PySequenceMethods">PySequenceMethods</a>* <code class="descname">tp_as_sequence</code><a class="headerlink" href="#c.tp_as_sequence" title="Permalink to this definition">¶</a></dt>
<dd><p>Pointer to an additional structure that contains fields relevant only to
objects which implement the sequence protocol. These fields are documented
in <a class="reference internal" href="#sequence-structs"><span class="std std-ref">Sequence Object Structures</span></a>.</p>
<p>The <code class="xref c c-member docutils literal notranslate"><span class="pre">tp_as_sequence</span></code> field is not inherited, but the contained fields
are inherited individually.</p>
</dd></dl>
<dl class="member">
<dt id="c.tp_as_mapping">
<a class="reference internal" href="#c.PyMappingMethods" title="PyMappingMethods">PyMappingMethods</a>* <code class="descname">tp_as_mapping</code><a class="headerlink" href="#c.tp_as_mapping" title="Permalink to this definition">¶</a></dt>
<dd><p>Pointer to an additional structure that contains fields relevant only to
objects which implement the mapping protocol. These fields are documented in
<a class="reference internal" href="#mapping-structs"><span class="std std-ref">Mapping Object Structures</span></a>.</p>
<p>The <code class="xref c c-member docutils literal notranslate"><span class="pre">tp_as_mapping</span></code> field is not inherited, but the contained fields
are inherited individually.</p>
</dd></dl>
<dl class="member">
<dt id="c.PyTypeObject.tp_hash">
hashfunc <code class="descname">PyTypeObject.tp_hash</code><a class="headerlink" href="#c.PyTypeObject.tp_hash" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-2">An optional pointer to a function that implements the built-in function
<a class="reference internal" href="../library/functions.html#hash" title="hash"><code class="xref py py-func docutils literal notranslate"><span class="pre">hash()</span></code></a>.</p>
<p>The signature is the same as for <a class="reference internal" href="object.html#c.PyObject_Hash" title="PyObject_Hash"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_Hash()</span></code></a>; it must return a C
long. The value <code class="docutils literal notranslate"><span class="pre">-1</span></code> should not be returned as a normal return value; when an
error occurs during the computation of the hash value, the function should set
an exception and return <code class="docutils literal notranslate"><span class="pre">-1</span></code>.</p>
<p>This field can be set explicitly to <a class="reference internal" href="object.html#c.PyObject_HashNotImplemented" title="PyObject_HashNotImplemented"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_HashNotImplemented()</span></code></a> to
block inheritance of the hash method from a parent type. This is interpreted
as the equivalent of <code class="docutils literal notranslate"><span class="pre">__hash__</span> <span class="pre">=</span> <span class="pre">None</span></code> at the Python level, causing
<code class="docutils literal notranslate"><span class="pre">isinstance(o,</span> <span class="pre">collections.Hashable)</span></code> to correctly return <code class="docutils literal notranslate"><span class="pre">False</span></code>. Note
that the converse is also true - setting <code class="docutils literal notranslate"><span class="pre">__hash__</span> <span class="pre">=</span> <span class="pre">None</span></code> on a class at
the Python level will result in the <code class="docutils literal notranslate"><span class="pre">tp_hash</span></code> slot being set to
<a class="reference internal" href="object.html#c.PyObject_HashNotImplemented" title="PyObject_HashNotImplemented"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_HashNotImplemented()</span></code></a>.</p>
<p>When this field is not set, two possibilities exist: if the <a class="reference internal" href="#c.PyTypeObject.tp_compare" title="PyTypeObject.tp_compare"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_compare</span></code></a>
and <a class="reference internal" href="#c.PyTypeObject.tp_richcompare" title="PyTypeObject.tp_richcompare"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_richcompare</span></code></a> fields are both <em>NULL</em>, a default hash value based on
the object’s address is returned; otherwise, a <a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> is raised.</p>
<p>This field is inherited by subtypes together with <a class="reference internal" href="#c.PyTypeObject.tp_richcompare" title="PyTypeObject.tp_richcompare"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_richcompare</span></code></a> and
<a class="reference internal" href="#c.PyTypeObject.tp_compare" title="PyTypeObject.tp_compare"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_compare</span></code></a>: a subtypes inherits all three of <a class="reference internal" href="#c.PyTypeObject.tp_compare" title="PyTypeObject.tp_compare"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_compare</span></code></a>,
<a class="reference internal" href="#c.PyTypeObject.tp_richcompare" title="PyTypeObject.tp_richcompare"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_richcompare</span></code></a>, and <a class="reference internal" href="#c.PyTypeObject.tp_hash" title="PyTypeObject.tp_hash"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_hash</span></code></a>, when the subtype’s
<a class="reference internal" href="#c.PyTypeObject.tp_compare" title="PyTypeObject.tp_compare"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_compare</span></code></a>, <a class="reference internal" href="#c.PyTypeObject.tp_richcompare" title="PyTypeObject.tp_richcompare"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_richcompare</span></code></a> and <a class="reference internal" href="#c.PyTypeObject.tp_hash" title="PyTypeObject.tp_hash"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_hash</span></code></a> are all <em>NULL</em>.</p>
</dd></dl>
<dl class="member">
<dt id="c.PyTypeObject.tp_call">
ternaryfunc <code class="descname">PyTypeObject.tp_call</code><a class="headerlink" href="#c.PyTypeObject.tp_call" title="Permalink to this definition">¶</a></dt>
<dd><p>An optional pointer to a function that implements calling the object. This
should be <em>NULL</em> if the object is not callable. The signature is the same as
for <a class="reference internal" href="object.html#c.PyObject_Call" title="PyObject_Call"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_Call()</span></code></a>.</p>
<p>This field is inherited by subtypes.</p>
</dd></dl>
<dl class="member">
<dt id="c.PyTypeObject.tp_str">
reprfunc <code class="descname">PyTypeObject.tp_str</code><a class="headerlink" href="#c.PyTypeObject.tp_str" title="Permalink to this definition">¶</a></dt>
<dd><p>An optional pointer to a function that implements the built-in operation
<a class="reference internal" href="../library/functions.html#str" title="str"><code class="xref py py-func docutils literal notranslate"><span class="pre">str()</span></code></a>. (Note that <a class="reference internal" href="../library/functions.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> is a type now, and <a class="reference internal" href="../library/functions.html#str" title="str"><code class="xref py py-func docutils literal notranslate"><span class="pre">str()</span></code></a> calls the
constructor for that type. This constructor calls <a class="reference internal" href="object.html#c.PyObject_Str" title="PyObject_Str"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_Str()</span></code></a> to do
the actual work, and <a class="reference internal" href="object.html#c.PyObject_Str" title="PyObject_Str"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_Str()</span></code></a> will call this handler.)</p>
<p>The signature is the same as for <a class="reference internal" href="object.html#c.PyObject_Str" title="PyObject_Str"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_Str()</span></code></a>; it must return a string
or a Unicode object. This function should return a “friendly” string
representation of the object, as this is the representation that will be used by
the print statement.</p>
<p>When this field is not set, <a class="reference internal" href="object.html#c.PyObject_Repr" title="PyObject_Repr"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_Repr()</span></code></a> is called to return a string
representation.</p>
<p>This field is inherited by subtypes.</p>
</dd></dl>
<dl class="member">
<dt id="c.PyTypeObject.tp_getattro">
getattrofunc <code class="descname">PyTypeObject.tp_getattro</code><a class="headerlink" href="#c.PyTypeObject.tp_getattro" title="Permalink to this definition">¶</a></dt>
<dd><p>An optional pointer to the get-attribute function.</p>
<p>The signature is the same as for <a class="reference internal" href="object.html#c.PyObject_GetAttr" title="PyObject_GetAttr"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_GetAttr()</span></code></a>. It is usually
convenient to set this field to <a class="reference internal" href="object.html#c.PyObject_GenericGetAttr" title="PyObject_GenericGetAttr"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_GenericGetAttr()</span></code></a>, which
implements the normal way of looking for object attributes.</p>
<p>This field is inherited by subtypes together with <a class="reference internal" href="#c.PyTypeObject.tp_getattr" title="PyTypeObject.tp_getattr"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_getattr</span></code></a>: a subtype
inherits both <a class="reference internal" href="#c.PyTypeObject.tp_getattr" title="PyTypeObject.tp_getattr"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_getattr</span></code></a> and <a class="reference internal" href="#c.PyTypeObject.tp_getattro" title="PyTypeObject.tp_getattro"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_getattro</span></code></a> from its base type when
the subtype’s <a class="reference internal" href="#c.PyTypeObject.tp_getattr" title="PyTypeObject.tp_getattr"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_getattr</span></code></a> and <a class="reference internal" href="#c.PyTypeObject.tp_getattro" title="PyTypeObject.tp_getattro"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_getattro</span></code></a> are both <em>NULL</em>.</p>
</dd></dl>
<dl class="member">
<dt id="c.PyTypeObject.tp_setattro">
setattrofunc <code class="descname">PyTypeObject.tp_setattro</code><a class="headerlink" href="#c.PyTypeObject.tp_setattro" title="Permalink to this definition">¶</a></dt>
<dd><p>An optional pointer to the function for setting and deleting attributes.</p>
<p>The signature is the same as for <a class="reference internal" href="object.html#c.PyObject_SetAttr" title="PyObject_SetAttr"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_SetAttr()</span></code></a>, but setting
<em>v</em> to <em>NULL</em> to delete an attribute must be supported. It is usually
convenient to set this field to <a class="reference internal" href="object.html#c.PyObject_GenericSetAttr" title="PyObject_GenericSetAttr"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_GenericSetAttr()</span></code></a>, which
implements the normal way of setting object attributes.</p>
<p>This field is inherited by subtypes together with <a class="reference internal" href="#c.PyTypeObject.tp_setattr" title="PyTypeObject.tp_setattr"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_setattr</span></code></a>: a subtype
inherits both <a class="reference internal" href="#c.PyTypeObject.tp_setattr" title="PyTypeObject.tp_setattr"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_setattr</span></code></a> and <a class="reference internal" href="#c.PyTypeObject.tp_setattro" title="PyTypeObject.tp_setattro"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_setattro</span></code></a> from its base type when
the subtype’s <a class="reference internal" href="#c.PyTypeObject.tp_setattr" title="PyTypeObject.tp_setattr"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_setattr</span></code></a> and <a class="reference internal" href="#c.PyTypeObject.tp_setattro" title="PyTypeObject.tp_setattro"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_setattro</span></code></a> are both <em>NULL</em>.</p>
</dd></dl>
<dl class="member">
<dt id="c.PyTypeObject.tp_as_buffer">
<a class="reference internal" href="#c.PyBufferProcs" title="PyBufferProcs">PyBufferProcs</a>* <code class="descname">PyTypeObject.tp_as_buffer</code><a class="headerlink" href="#c.PyTypeObject.tp_as_buffer" title="Permalink to this definition">¶</a></dt>
<dd><p>Pointer to an additional structure that contains fields relevant only to objects
which implement the buffer interface. These fields are documented in
<a class="reference internal" href="#buffer-structs"><span class="std std-ref">Buffer Object Structures</span></a>.</p>
<p>The <a class="reference internal" href="#c.PyTypeObject.tp_as_buffer" title="PyTypeObject.tp_as_buffer"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_as_buffer</span></code></a> field is not inherited, but the contained fields are
inherited individually.</p>
</dd></dl>
<dl class="member">
<dt id="c.PyTypeObject.tp_flags">
long <code class="descname">PyTypeObject.tp_flags</code><a class="headerlink" href="#c.PyTypeObject.tp_flags" title="Permalink to this definition">¶</a></dt>
<dd><p>This field is a bit mask of various flags. Some flags indicate variant
semantics for certain situations; others are used to indicate that certain
fields in the type object (or in the extension structures referenced via
<code class="xref c c-member docutils literal notranslate"><span class="pre">tp_as_number</span></code>, <code class="xref c c-member docutils literal notranslate"><span class="pre">tp_as_sequence</span></code>, <code class="xref c c-member docutils literal notranslate"><span class="pre">tp_as_mapping</span></code>, and
<a class="reference internal" href="#c.PyTypeObject.tp_as_buffer" title="PyTypeObject.tp_as_buffer"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_as_buffer</span></code></a>) that were historically not always present are valid; if
such a flag bit is clear, the type fields it guards must not be accessed and
must be considered to have a zero or <em>NULL</em> value instead.</p>
<p>Inheritance of this field is complicated. Most flag bits are inherited
individually, i.e. if the base type has a flag bit set, the subtype inherits
this flag bit. The flag bits that pertain to extension structures are strictly
inherited if the extension structure is inherited, i.e. the base type’s value of
the flag bit is copied into the subtype together with a pointer to the extension
structure. The <a class="reference internal" href="#Py_TPFLAGS_HAVE_GC" title="Py_TPFLAGS_HAVE_GC"><code class="xref py py-const docutils literal notranslate"><span class="pre">Py_TPFLAGS_HAVE_GC</span></code></a> flag bit is inherited together with
the <a class="reference internal" href="#c.PyTypeObject.tp_traverse" title="PyTypeObject.tp_traverse"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_traverse</span></code></a> and <a class="reference internal" href="#c.PyTypeObject.tp_clear" title="PyTypeObject.tp_clear"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_clear</span></code></a> fields, i.e. if the
<a class="reference internal" href="#Py_TPFLAGS_HAVE_GC" title="Py_TPFLAGS_HAVE_GC"><code class="xref py py-const docutils literal notranslate"><span class="pre">Py_TPFLAGS_HAVE_GC</span></code></a> flag bit is clear in the subtype and the
<a class="reference internal" href="#c.PyTypeObject.tp_traverse" title="PyTypeObject.tp_traverse"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_traverse</span></code></a> and <a class="reference internal" href="#c.PyTypeObject.tp_clear" title="PyTypeObject.tp_clear"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_clear</span></code></a> fields in the subtype exist (as
indicated by the <a class="reference internal" href="#Py_TPFLAGS_HAVE_RICHCOMPARE" title="Py_TPFLAGS_HAVE_RICHCOMPARE"><code class="xref py py-const docutils literal notranslate"><span class="pre">Py_TPFLAGS_HAVE_RICHCOMPARE</span></code></a> flag bit) and have <em>NULL</em>
values.</p>
<p>The following bit masks are currently defined; these can be ORed together using
the <code class="docutils literal notranslate"><span class="pre">|</span></code> operator to form the value of the <a class="reference internal" href="#c.PyTypeObject.tp_flags" title="PyTypeObject.tp_flags"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_flags</span></code></a> field. The macro
<a class="reference internal" href="type.html#c.PyType_HasFeature" title="PyType_HasFeature"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_HasFeature()</span></code></a> takes a type and a flags value, <em>tp</em> and <em>f</em>, and
checks whether <code class="docutils literal notranslate"><span class="pre">tp->tp_flags</span> <span class="pre">&</span> <span class="pre">f</span></code> is non-zero.</p>
<dl class="data">
<dt id="Py_TPFLAGS_HAVE_GETCHARBUFFER">
<code class="descname">Py_TPFLAGS_HAVE_GETCHARBUFFER</code><a class="headerlink" href="#Py_TPFLAGS_HAVE_GETCHARBUFFER" title="Permalink to this definition">¶</a></dt>
<dd><p>If this bit is set, the <a class="reference internal" href="#c.PyBufferProcs" title="PyBufferProcs"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyBufferProcs</span></code></a> struct referenced by
<a class="reference internal" href="#c.PyTypeObject.tp_as_buffer" title="PyTypeObject.tp_as_buffer"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_as_buffer</span></code></a> has the <code class="xref py py-attr docutils literal notranslate"><span class="pre">bf_getcharbuffer</span></code> field.</p>
</dd></dl>
<dl class="data">
<dt id="Py_TPFLAGS_HAVE_SEQUENCE_IN">
<code class="descname">Py_TPFLAGS_HAVE_SEQUENCE_IN</code><a class="headerlink" href="#Py_TPFLAGS_HAVE_SEQUENCE_IN" title="Permalink to this definition">¶</a></dt>
<dd><p>If this bit is set, the <a class="reference internal" href="#c.PySequenceMethods" title="PySequenceMethods"><code class="xref c c-type docutils literal notranslate"><span class="pre">PySequenceMethods</span></code></a> struct referenced by
<code class="xref c c-member docutils literal notranslate"><span class="pre">tp_as_sequence</span></code> has the <code class="xref py py-attr docutils literal notranslate"><span class="pre">sq_contains</span></code> field.</p>
</dd></dl>
<dl class="data">
<dt id="Py_TPFLAGS_GC">
<code class="descname">Py_TPFLAGS_GC</code><a class="headerlink" href="#Py_TPFLAGS_GC" title="Permalink to this definition">¶</a></dt>
<dd><p>This bit is obsolete. The bit it used to name is no longer in use. The symbol
is now defined as zero.</p>
</dd></dl>
<dl class="data">
<dt id="Py_TPFLAGS_HAVE_INPLACEOPS">
<code class="descname">Py_TPFLAGS_HAVE_INPLACEOPS</code><a class="headerlink" href="#Py_TPFLAGS_HAVE_INPLACEOPS" title="Permalink to this definition">¶</a></dt>
<dd><p>If this bit is set, the <a class="reference internal" href="#c.PySequenceMethods" title="PySequenceMethods"><code class="xref c c-type docutils literal notranslate"><span class="pre">PySequenceMethods</span></code></a> struct referenced by
<code class="xref c c-member docutils literal notranslate"><span class="pre">tp_as_sequence</span></code> and the <a class="reference internal" href="#c.PyNumberMethods" title="PyNumberMethods"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyNumberMethods</span></code></a> structure referenced by
<code class="xref c c-member docutils literal notranslate"><span class="pre">tp_as_number</span></code> contain the fields for in-place operators. In particular,
this means that the <a class="reference internal" href="#c.PyNumberMethods" title="PyNumberMethods"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyNumberMethods</span></code></a> structure has the fields
<code class="xref py py-attr docutils literal notranslate"><span class="pre">nb_inplace_add</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">nb_inplace_subtract</span></code>,
<code class="xref py py-attr docutils literal notranslate"><span class="pre">nb_inplace_multiply</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">nb_inplace_divide</span></code>,
<code class="xref py py-attr docutils literal notranslate"><span class="pre">nb_inplace_remainder</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">nb_inplace_power</span></code>,
<code class="xref py py-attr docutils literal notranslate"><span class="pre">nb_inplace_lshift</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">nb_inplace_rshift</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">nb_inplace_and</span></code>,
<code class="xref py py-attr docutils literal notranslate"><span class="pre">nb_inplace_xor</span></code>, and <code class="xref py py-attr docutils literal notranslate"><span class="pre">nb_inplace_or</span></code>; and the
<a class="reference internal" href="#c.PySequenceMethods" title="PySequenceMethods"><code class="xref c c-type docutils literal notranslate"><span class="pre">PySequenceMethods</span></code></a> struct has the fields <code class="xref py py-attr docutils literal notranslate"><span class="pre">sq_inplace_concat</span></code> and
<code class="xref py py-attr docutils literal notranslate"><span class="pre">sq_inplace_repeat</span></code>.</p>
</dd></dl>
<dl class="data">
<dt id="Py_TPFLAGS_CHECKTYPES">
<code class="descname">Py_TPFLAGS_CHECKTYPES</code><a class="headerlink" href="#Py_TPFLAGS_CHECKTYPES" title="Permalink to this definition">¶</a></dt>
<dd><p>If this bit is set, the binary and ternary operations in the
<a class="reference internal" href="#c.PyNumberMethods" title="PyNumberMethods"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyNumberMethods</span></code></a> structure referenced by <code class="xref c c-member docutils literal notranslate"><span class="pre">tp_as_number</span></code> accept
arguments of arbitrary object types, and do their own type conversions if
needed. If this bit is clear, those operations require that all arguments have
the current type as their type, and the caller is supposed to perform a coercion
operation first. This applies to <code class="xref py py-attr docutils literal notranslate"><span class="pre">nb_add</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">nb_subtract</span></code>,
<code class="xref py py-attr docutils literal notranslate"><span class="pre">nb_multiply</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">nb_divide</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">nb_remainder</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">nb_divmod</span></code>,
<code class="xref py py-attr docutils literal notranslate"><span class="pre">nb_power</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">nb_lshift</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">nb_rshift</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">nb_and</span></code>,
<code class="xref py py-attr docutils literal notranslate"><span class="pre">nb_xor</span></code>, and <code class="xref py py-attr docutils literal notranslate"><span class="pre">nb_or</span></code>.</p>
</dd></dl>
<dl class="data">
<dt id="Py_TPFLAGS_HAVE_RICHCOMPARE">
<code class="descname">Py_TPFLAGS_HAVE_RICHCOMPARE</code><a class="headerlink" href="#Py_TPFLAGS_HAVE_RICHCOMPARE" title="Permalink to this definition">¶</a></dt>
<dd><p>If this bit is set, the type object has the <a class="reference internal" href="#c.PyTypeObject.tp_richcompare" title="PyTypeObject.tp_richcompare"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_richcompare</span></code></a> field, as
well as the <a class="reference internal" href="#c.PyTypeObject.tp_traverse" title="PyTypeObject.tp_traverse"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_traverse</span></code></a> and the <a class="reference internal" href="#c.PyTypeObject.tp_clear" title="PyTypeObject.tp_clear"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_clear</span></code></a> fields.</p>
</dd></dl>
<dl class="data">
<dt id="Py_TPFLAGS_HAVE_WEAKREFS">
<code class="descname">Py_TPFLAGS_HAVE_WEAKREFS</code><a class="headerlink" href="#Py_TPFLAGS_HAVE_WEAKREFS" title="Permalink to this definition">¶</a></dt>
<dd><p>If this bit is set, the <a class="reference internal" href="#c.PyTypeObject.tp_weaklistoffset" title="PyTypeObject.tp_weaklistoffset"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_weaklistoffset</span></code></a> field is defined. Instances
of a type are weakly referenceable if the type’s <a class="reference internal" href="#c.PyTypeObject.tp_weaklistoffset" title="PyTypeObject.tp_weaklistoffset"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_weaklistoffset</span></code></a> field
has a value greater than zero.</p>
</dd></dl>
<dl class="data">
<dt id="Py_TPFLAGS_HAVE_ITER">
<code class="descname">Py_TPFLAGS_HAVE_ITER</code><a class="headerlink" href="#Py_TPFLAGS_HAVE_ITER" title="Permalink to this definition">¶</a></dt>
<dd><p>If this bit is set, the type object has the <a class="reference internal" href="#c.PyTypeObject.tp_iter" title="PyTypeObject.tp_iter"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_iter</span></code></a> and
<a class="reference internal" href="#c.PyTypeObject.tp_iternext" title="PyTypeObject.tp_iternext"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_iternext</span></code></a> fields.</p>
</dd></dl>
<dl class="data">
<dt id="Py_TPFLAGS_HAVE_CLASS">
<code class="descname">Py_TPFLAGS_HAVE_CLASS</code><a class="headerlink" href="#Py_TPFLAGS_HAVE_CLASS" title="Permalink to this definition">¶</a></dt>
<dd><p>If this bit is set, the type object has several new fields defined starting in
Python 2.2: <a class="reference internal" href="#c.PyTypeObject.tp_methods" title="PyTypeObject.tp_methods"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_methods</span></code></a>, <a class="reference internal" href="#c.PyTypeObject.tp_members" title="PyTypeObject.tp_members"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_members</span></code></a>, <a class="reference internal" href="#c.PyTypeObject.tp_getset" title="PyTypeObject.tp_getset"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_getset</span></code></a>,
<a class="reference internal" href="#c.PyTypeObject.tp_base" title="PyTypeObject.tp_base"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_base</span></code></a>, <a class="reference internal" href="#c.PyTypeObject.tp_dict" title="PyTypeObject.tp_dict"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_dict</span></code></a>, <a class="reference internal" href="#c.PyTypeObject.tp_descr_get" title="PyTypeObject.tp_descr_get"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_descr_get</span></code></a>, <a class="reference internal" href="#c.PyTypeObject.tp_descr_set" title="PyTypeObject.tp_descr_set"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_descr_set</span></code></a>,
<a class="reference internal" href="#c.PyTypeObject.tp_dictoffset" title="PyTypeObject.tp_dictoffset"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_dictoffset</span></code></a>, <a class="reference internal" href="#c.PyTypeObject.tp_init" title="PyTypeObject.tp_init"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_init</span></code></a>, <a class="reference internal" href="#c.PyTypeObject.tp_alloc" title="PyTypeObject.tp_alloc"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_alloc</span></code></a>, <a class="reference internal" href="#c.PyTypeObject.tp_new" title="PyTypeObject.tp_new"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_new</span></code></a>,
<a class="reference internal" href="#c.PyTypeObject.tp_free" title="PyTypeObject.tp_free"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_free</span></code></a>, <a class="reference internal" href="#c.PyTypeObject.tp_is_gc" title="PyTypeObject.tp_is_gc"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_is_gc</span></code></a>, <a class="reference internal" href="#c.PyTypeObject.tp_bases" title="PyTypeObject.tp_bases"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_bases</span></code></a>, <a class="reference internal" href="#c.PyTypeObject.tp_mro" title="PyTypeObject.tp_mro"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_mro</span></code></a>,
<a class="reference internal" href="#c.PyTypeObject.tp_cache" title="PyTypeObject.tp_cache"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_cache</span></code></a>, <a class="reference internal" href="#c.PyTypeObject.tp_subclasses" title="PyTypeObject.tp_subclasses"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_subclasses</span></code></a>, and <a class="reference internal" href="#c.PyTypeObject.tp_weaklist" title="PyTypeObject.tp_weaklist"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_weaklist</span></code></a>.</p>
</dd></dl>
<dl class="data">
<dt id="Py_TPFLAGS_HEAPTYPE">
<code class="descname">Py_TPFLAGS_HEAPTYPE</code><a class="headerlink" href="#Py_TPFLAGS_HEAPTYPE" title="Permalink to this definition">¶</a></dt>
<dd><p>This bit is set when the type object itself is allocated on the heap. In this
case, the <code class="xref py py-attr docutils literal notranslate"><span class="pre">ob_type</span></code> field of its instances is considered a reference to
the type, and the type object is INCREF’ed when a new instance is created, and
DECREF’ed when an instance is destroyed (this does not apply to instances of
subtypes; only the type referenced by the instance’s ob_type gets INCREF’ed or
DECREF’ed).</p>
</dd></dl>
<dl class="data">
<dt id="Py_TPFLAGS_BASETYPE">
<code class="descname">Py_TPFLAGS_BASETYPE</code><a class="headerlink" href="#Py_TPFLAGS_BASETYPE" title="Permalink to this definition">¶</a></dt>
<dd><p>This bit is set when the type can be used as the base type of another type. If
this bit is clear, the type cannot be subtyped (similar to a “final” class in
Java).</p>
</dd></dl>
<dl class="data">
<dt id="Py_TPFLAGS_READY">
<code class="descname">Py_TPFLAGS_READY</code><a class="headerlink" href="#Py_TPFLAGS_READY" title="Permalink to this definition">¶</a></dt>
<dd><p>This bit is set when the type object has been fully initialized by
<a class="reference internal" href="type.html#c.PyType_Ready" title="PyType_Ready"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_Ready()</span></code></a>.</p>
</dd></dl>
<dl class="data">
<dt id="Py_TPFLAGS_READYING">
<code class="descname">Py_TPFLAGS_READYING</code><a class="headerlink" href="#Py_TPFLAGS_READYING" title="Permalink to this definition">¶</a></dt>
<dd><p>This bit is set while <a class="reference internal" href="type.html#c.PyType_Ready" title="PyType_Ready"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_Ready()</span></code></a> is in the process of initializing
the type object.</p>
</dd></dl>
<dl class="data">
<dt id="Py_TPFLAGS_HAVE_GC">
<code class="descname">Py_TPFLAGS_HAVE_GC</code><a class="headerlink" href="#Py_TPFLAGS_HAVE_GC" title="Permalink to this definition">¶</a></dt>
<dd><p>This bit is set when the object supports garbage collection. If this bit
is set, instances must be created using <a class="reference internal" href="gcsupport.html#c.PyObject_GC_New" title="PyObject_GC_New"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_GC_New()</span></code></a> and
destroyed using <a class="reference internal" href="gcsupport.html#c.PyObject_GC_Del" title="PyObject_GC_Del"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_GC_Del()</span></code></a>. More information in section
<a class="reference internal" href="gcsupport.html#supporting-cycle-detection"><span class="std std-ref">Supporting Cyclic Garbage Collection</span></a>. This bit also implies that the
GC-related fields <a class="reference internal" href="#c.PyTypeObject.tp_traverse" title="PyTypeObject.tp_traverse"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_traverse</span></code></a> and <a class="reference internal" href="#c.PyTypeObject.tp_clear" title="PyTypeObject.tp_clear"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_clear</span></code></a> are present in
the type object; but those fields also exist when
<a class="reference internal" href="#Py_TPFLAGS_HAVE_GC" title="Py_TPFLAGS_HAVE_GC"><code class="xref py py-const docutils literal notranslate"><span class="pre">Py_TPFLAGS_HAVE_GC</span></code></a> is clear but
<a class="reference internal" href="#Py_TPFLAGS_HAVE_RICHCOMPARE" title="Py_TPFLAGS_HAVE_RICHCOMPARE"><code class="xref py py-const docutils literal notranslate"><span class="pre">Py_TPFLAGS_HAVE_RICHCOMPARE</span></code></a> is set.</p>
</dd></dl>
<dl class="data">
<dt id="Py_TPFLAGS_DEFAULT">
<code class="descname">Py_TPFLAGS_DEFAULT</code><a class="headerlink" href="#Py_TPFLAGS_DEFAULT" title="Permalink to this definition">¶</a></dt>
<dd><p>This is a bitmask of all the bits that pertain to the existence of certain
fields in the type object and its extension structures. Currently, it includes
the following bits: <a class="reference internal" href="#Py_TPFLAGS_HAVE_GETCHARBUFFER" title="Py_TPFLAGS_HAVE_GETCHARBUFFER"><code class="xref py py-const docutils literal notranslate"><span class="pre">Py_TPFLAGS_HAVE_GETCHARBUFFER</span></code></a>,
<a class="reference internal" href="#Py_TPFLAGS_HAVE_SEQUENCE_IN" title="Py_TPFLAGS_HAVE_SEQUENCE_IN"><code class="xref py py-const docutils literal notranslate"><span class="pre">Py_TPFLAGS_HAVE_SEQUENCE_IN</span></code></a>, <a class="reference internal" href="#Py_TPFLAGS_HAVE_INPLACEOPS" title="Py_TPFLAGS_HAVE_INPLACEOPS"><code class="xref py py-const docutils literal notranslate"><span class="pre">Py_TPFLAGS_HAVE_INPLACEOPS</span></code></a>,
<a class="reference internal" href="#Py_TPFLAGS_HAVE_RICHCOMPARE" title="Py_TPFLAGS_HAVE_RICHCOMPARE"><code class="xref py py-const docutils literal notranslate"><span class="pre">Py_TPFLAGS_HAVE_RICHCOMPARE</span></code></a>, <a class="reference internal" href="#Py_TPFLAGS_HAVE_WEAKREFS" title="Py_TPFLAGS_HAVE_WEAKREFS"><code class="xref py py-const docutils literal notranslate"><span class="pre">Py_TPFLAGS_HAVE_WEAKREFS</span></code></a>,
<a class="reference internal" href="#Py_TPFLAGS_HAVE_ITER" title="Py_TPFLAGS_HAVE_ITER"><code class="xref py py-const docutils literal notranslate"><span class="pre">Py_TPFLAGS_HAVE_ITER</span></code></a>, and <a class="reference internal" href="#Py_TPFLAGS_HAVE_CLASS" title="Py_TPFLAGS_HAVE_CLASS"><code class="xref py py-const docutils literal notranslate"><span class="pre">Py_TPFLAGS_HAVE_CLASS</span></code></a>.</p>
</dd></dl>
</dd></dl>
<dl class="member">
<dt id="c.PyTypeObject.tp_doc">
char* <code class="descname">PyTypeObject.tp_doc</code><a class="headerlink" href="#c.PyTypeObject.tp_doc" title="Permalink to this definition">¶</a></dt>
<dd><p>An optional pointer to a NUL-terminated C string giving the docstring for this
type object. This is exposed as the <code class="xref py py-attr docutils literal notranslate"><span class="pre">__doc__</span></code> attribute on the type and
instances of the type.</p>
<p>This field is <em>not</em> inherited by subtypes.</p>
</dd></dl>
<p>The following three fields only exist if the
<a class="reference internal" href="#Py_TPFLAGS_HAVE_RICHCOMPARE" title="Py_TPFLAGS_HAVE_RICHCOMPARE"><code class="xref py py-const docutils literal notranslate"><span class="pre">Py_TPFLAGS_HAVE_RICHCOMPARE</span></code></a> flag bit is set.</p>
<dl class="member">
<dt id="c.PyTypeObject.tp_traverse">
<a class="reference internal" href="gcsupport.html#c.traverseproc" title="traverseproc">traverseproc</a> <code class="descname">PyTypeObject.tp_traverse</code><a class="headerlink" href="#c.PyTypeObject.tp_traverse" title="Permalink to this definition">¶</a></dt>
<dd><p>An optional pointer to a traversal function for the garbage collector. This is
only used if the <a class="reference internal" href="#Py_TPFLAGS_HAVE_GC" title="Py_TPFLAGS_HAVE_GC"><code class="xref py py-const docutils literal notranslate"><span class="pre">Py_TPFLAGS_HAVE_GC</span></code></a> flag bit is set. More information
about Python’s garbage collection scheme can be found in section
<a class="reference internal" href="gcsupport.html#supporting-cycle-detection"><span class="std std-ref">Supporting Cyclic Garbage Collection</span></a>.</p>
<p>The <a class="reference internal" href="#c.PyTypeObject.tp_traverse" title="PyTypeObject.tp_traverse"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_traverse</span></code></a> pointer is used by the garbage collector to detect
reference cycles. A typical implementation of a <a class="reference internal" href="#c.PyTypeObject.tp_traverse" title="PyTypeObject.tp_traverse"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_traverse</span></code></a> function
simply calls <a class="reference internal" href="gcsupport.html#c.Py_VISIT" title="Py_VISIT"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_VISIT()</span></code></a> on each of the instance’s members that are Python
objects. For example, this is function <code class="xref c c-func docutils literal notranslate"><span class="pre">local_traverse()</span></code> from the
<a class="reference internal" href="../library/thread.html#module-thread" title="thread: Create multiple threads of control within one interpreter."><code class="xref py py-mod docutils literal notranslate"><span class="pre">thread</span></code></a> extension module:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">static</span> <span class="kt">int</span>
<span class="nf">local_traverse</span><span class="p">(</span><span class="n">localobject</span> <span class="o">*</span><span class="n">self</span><span class="p">,</span> <span class="n">visitproc</span> <span class="n">visit</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="n">arg</span><span class="p">)</span>
<span class="p">{</span>
<span class="n">Py_VISIT</span><span class="p">(</span><span class="n">self</span><span class="o">-></span><span class="n">args</span><span class="p">);</span>
<span class="n">Py_VISIT</span><span class="p">(</span><span class="n">self</span><span class="o">-></span><span class="n">kw</span><span class="p">);</span>
<span class="n">Py_VISIT</span><span class="p">(</span><span class="n">self</span><span class="o">-></span><span class="n">dict</span><span class="p">);</span>
<span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Note that <a class="reference internal" href="gcsupport.html#c.Py_VISIT" title="Py_VISIT"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_VISIT()</span></code></a> is called only on those members that can participate
in reference cycles. Although there is also a <code class="docutils literal notranslate"><span class="pre">self->key</span></code> member, it can only
be <em>NULL</em> or a Python string and therefore cannot be part of a reference cycle.</p>
<p>On the other hand, even if you know a member can never be part of a cycle, as a
debugging aid you may want to visit it anyway just so the <a class="reference internal" href="../library/gc.html#module-gc" title="gc: Interface to the cycle-detecting garbage collector."><code class="xref py py-mod docutils literal notranslate"><span class="pre">gc</span></code></a> module’s
<a class="reference internal" href="../library/gc.html#gc.get_referents" title="gc.get_referents"><code class="xref py py-func docutils literal notranslate"><span class="pre">get_referents()</span></code></a> function will include it.</p>
<p>Note that <a class="reference internal" href="gcsupport.html#c.Py_VISIT" title="Py_VISIT"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_VISIT()</span></code></a> requires the <em>visit</em> and <em>arg</em> parameters to
<code class="xref c c-func docutils literal notranslate"><span class="pre">local_traverse()</span></code> to have these specific names; don’t name them just
anything.</p>
<p>This field is inherited by subtypes together with <a class="reference internal" href="#c.PyTypeObject.tp_clear" title="PyTypeObject.tp_clear"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_clear</span></code></a> and the
<a class="reference internal" href="#Py_TPFLAGS_HAVE_GC" title="Py_TPFLAGS_HAVE_GC"><code class="xref py py-const docutils literal notranslate"><span class="pre">Py_TPFLAGS_HAVE_GC</span></code></a> flag bit: the flag bit, <a class="reference internal" href="#c.PyTypeObject.tp_traverse" title="PyTypeObject.tp_traverse"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_traverse</span></code></a>, and
<a class="reference internal" href="#c.PyTypeObject.tp_clear" title="PyTypeObject.tp_clear"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_clear</span></code></a> are all inherited from the base type if they are all zero in
the subtype <em>and</em> the subtype has the <a class="reference internal" href="#Py_TPFLAGS_HAVE_RICHCOMPARE" title="Py_TPFLAGS_HAVE_RICHCOMPARE"><code class="xref py py-const docutils literal notranslate"><span class="pre">Py_TPFLAGS_HAVE_RICHCOMPARE</span></code></a> flag
bit set.</p>
</dd></dl>
<dl class="member">
<dt id="c.PyTypeObject.tp_clear">
<a class="reference internal" href="gcsupport.html#c.inquiry" title="inquiry">inquiry</a> <code class="descname">PyTypeObject.tp_clear</code><a class="headerlink" href="#c.PyTypeObject.tp_clear" title="Permalink to this definition">¶</a></dt>
<dd><p>An optional pointer to a clear function for the garbage collector. This is only
used if the <a class="reference internal" href="#Py_TPFLAGS_HAVE_GC" title="Py_TPFLAGS_HAVE_GC"><code class="xref py py-const docutils literal notranslate"><span class="pre">Py_TPFLAGS_HAVE_GC</span></code></a> flag bit is set.</p>
<p>The <a class="reference internal" href="#c.PyTypeObject.tp_clear" title="PyTypeObject.tp_clear"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_clear</span></code></a> member function is used to break reference cycles in cyclic
garbage detected by the garbage collector. Taken together, all <a class="reference internal" href="#c.PyTypeObject.tp_clear" title="PyTypeObject.tp_clear"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_clear</span></code></a>
functions in the system must combine to break all reference cycles. This is
subtle, and if in any doubt supply a <a class="reference internal" href="#c.PyTypeObject.tp_clear" title="PyTypeObject.tp_clear"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_clear</span></code></a> function. For example,
the tuple type does not implement a <a class="reference internal" href="#c.PyTypeObject.tp_clear" title="PyTypeObject.tp_clear"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_clear</span></code></a> function, because it’s
possible to prove that no reference cycle can be composed entirely of tuples.
Therefore the <a class="reference internal" href="#c.PyTypeObject.tp_clear" title="PyTypeObject.tp_clear"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_clear</span></code></a> functions of other types must be sufficient to
break any cycle containing a tuple. This isn’t immediately obvious, and there’s
rarely a good reason to avoid implementing <a class="reference internal" href="#c.PyTypeObject.tp_clear" title="PyTypeObject.tp_clear"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_clear</span></code></a>.</p>
<p>Implementations of <a class="reference internal" href="#c.PyTypeObject.tp_clear" title="PyTypeObject.tp_clear"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_clear</span></code></a> should drop the instance’s references to
those of its members that may be Python objects, and set its pointers to those
members to <em>NULL</em>, as in the following example:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">static</span> <span class="kt">int</span>
<span class="nf">local_clear</span><span class="p">(</span><span class="n">localobject</span> <span class="o">*</span><span class="n">self</span><span class="p">)</span>
<span class="p">{</span>
<span class="n">Py_CLEAR</span><span class="p">(</span><span class="n">self</span><span class="o">-></span><span class="n">key</span><span class="p">);</span>
<span class="n">Py_CLEAR</span><span class="p">(</span><span class="n">self</span><span class="o">-></span><span class="n">args</span><span class="p">);</span>
<span class="n">Py_CLEAR</span><span class="p">(</span><span class="n">self</span><span class="o">-></span><span class="n">kw</span><span class="p">);</span>
<span class="n">Py_CLEAR</span><span class="p">(</span><span class="n">self</span><span class="o">-></span><span class="n">dict</span><span class="p">);</span>
<span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
<p>The <a class="reference internal" href="refcounting.html#c.Py_CLEAR" title="Py_CLEAR"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_CLEAR()</span></code></a> macro should be used, because clearing references is
delicate: the reference to the contained object must not be decremented until
after the pointer to the contained object is set to <em>NULL</em>. This is because
decrementing the reference count may cause the contained object to become trash,
triggering a chain of reclamation activity that may include invoking arbitrary
Python code (due to finalizers, or weakref callbacks, associated with the
contained object). If it’s possible for such code to reference <em>self</em> again,
it’s important that the pointer to the contained object be <em>NULL</em> at that time,
so that <em>self</em> knows the contained object can no longer be used. The
<a class="reference internal" href="refcounting.html#c.Py_CLEAR" title="Py_CLEAR"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_CLEAR()</span></code></a> macro performs the operations in a safe order.</p>
<p>Because the goal of <a class="reference internal" href="#c.PyTypeObject.tp_clear" title="PyTypeObject.tp_clear"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_clear</span></code></a> functions is to break reference cycles,
it’s not necessary to clear contained objects like Python strings or Python
integers, which can’t participate in reference cycles. On the other hand, it may
be convenient to clear all contained Python objects, and write the type’s
<a class="reference internal" href="#c.PyTypeObject.tp_dealloc" title="PyTypeObject.tp_dealloc"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_dealloc</span></code></a> function to invoke <a class="reference internal" href="#c.PyTypeObject.tp_clear" title="PyTypeObject.tp_clear"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_clear</span></code></a>.</p>
<p>More information about Python’s garbage collection scheme can be found in
section <a class="reference internal" href="gcsupport.html#supporting-cycle-detection"><span class="std std-ref">Supporting Cyclic Garbage Collection</span></a>.</p>
<p>This field is inherited by subtypes together with <a class="reference internal" href="#c.PyTypeObject.tp_traverse" title="PyTypeObject.tp_traverse"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_traverse</span></code></a> and the
<a class="reference internal" href="#Py_TPFLAGS_HAVE_GC" title="Py_TPFLAGS_HAVE_GC"><code class="xref py py-const docutils literal notranslate"><span class="pre">Py_TPFLAGS_HAVE_GC</span></code></a> flag bit: the flag bit, <a class="reference internal" href="#c.PyTypeObject.tp_traverse" title="PyTypeObject.tp_traverse"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_traverse</span></code></a>, and
<a class="reference internal" href="#c.PyTypeObject.tp_clear" title="PyTypeObject.tp_clear"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_clear</span></code></a> are all inherited from the base type if they are all zero in
the subtype <em>and</em> the subtype has the <a class="reference internal" href="#Py_TPFLAGS_HAVE_RICHCOMPARE" title="Py_TPFLAGS_HAVE_RICHCOMPARE"><code class="xref py py-const docutils literal notranslate"><span class="pre">Py_TPFLAGS_HAVE_RICHCOMPARE</span></code></a> flag
bit set.</p>
</dd></dl>
<dl class="member">
<dt id="c.PyTypeObject.tp_richcompare">
richcmpfunc <code class="descname">PyTypeObject.tp_richcompare</code><a class="headerlink" href="#c.PyTypeObject.tp_richcompare" title="Permalink to this definition">¶</a></dt>
<dd><p>An optional pointer to the rich comparison function, whose signature is
<code class="docutils literal notranslate"><span class="pre">PyObject</span> <span class="pre">*tp_richcompare(PyObject</span> <span class="pre">*a,</span> <span class="pre">PyObject</span> <span class="pre">*b,</span> <span class="pre">int</span> <span class="pre">op)</span></code>.</p>
<p>The function should return the result of the comparison (usually <code class="docutils literal notranslate"><span class="pre">Py_True</span></code>
or <code class="docutils literal notranslate"><span class="pre">Py_False</span></code>). If the comparison is undefined, it must return
<code class="docutils literal notranslate"><span class="pre">Py_NotImplemented</span></code>, if another error occurred it must return <code class="docutils literal notranslate"><span class="pre">NULL</span></code> and
set an exception condition.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If you want to implement a type for which only a limited set of
comparisons makes sense (e.g. <code class="docutils literal notranslate"><span class="pre">==</span></code> and <code class="docutils literal notranslate"><span class="pre">!=</span></code>, but not <code class="docutils literal notranslate"><span class="pre"><</span></code> and
friends), directly raise <a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> in the rich comparison function.</p>
</div>
<p>This field is inherited by subtypes together with <a class="reference internal" href="#c.PyTypeObject.tp_compare" title="PyTypeObject.tp_compare"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_compare</span></code></a> and
<a class="reference internal" href="#c.PyTypeObject.tp_hash" title="PyTypeObject.tp_hash"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_hash</span></code></a>: a subtype inherits all three of <a class="reference internal" href="#c.PyTypeObject.tp_compare" title="PyTypeObject.tp_compare"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_compare</span></code></a>,
<a class="reference internal" href="#c.PyTypeObject.tp_richcompare" title="PyTypeObject.tp_richcompare"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_richcompare</span></code></a>, and <a class="reference internal" href="#c.PyTypeObject.tp_hash" title="PyTypeObject.tp_hash"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_hash</span></code></a>, when the subtype’s
<a class="reference internal" href="#c.PyTypeObject.tp_compare" title="PyTypeObject.tp_compare"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_compare</span></code></a>, <a class="reference internal" href="#c.PyTypeObject.tp_richcompare" title="PyTypeObject.tp_richcompare"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_richcompare</span></code></a>, and <a class="reference internal" href="#c.PyTypeObject.tp_hash" title="PyTypeObject.tp_hash"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_hash</span></code></a> are all <em>NULL</em>.</p>
<p>The following constants are defined to be used as the third argument for
<a class="reference internal" href="#c.PyTypeObject.tp_richcompare" title="PyTypeObject.tp_richcompare"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_richcompare</span></code></a> and for <a class="reference internal" href="object.html#c.PyObject_RichCompare" title="PyObject_RichCompare"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_RichCompare()</span></code></a>:</p>
<table border="1" class="docutils">
<colgroup>
<col width="57%" />
<col width="43%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Constant</th>
<th class="head">Comparison</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="xref py py-const docutils literal notranslate"><span class="pre">Py_LT</span></code></td>
<td><code class="docutils literal notranslate"><span class="pre"><</span></code></td>
</tr>
<tr class="row-odd"><td><code class="xref py py-const docutils literal notranslate"><span class="pre">Py_LE</span></code></td>
<td><code class="docutils literal notranslate"><span class="pre"><=</span></code></td>
</tr>
<tr class="row-even"><td><code class="xref py py-const docutils literal notranslate"><span class="pre">Py_EQ</span></code></td>
<td><code class="docutils literal notranslate"><span class="pre">==</span></code></td>
</tr>
<tr class="row-odd"><td><code class="xref py py-const docutils literal notranslate"><span class="pre">Py_NE</span></code></td>
<td><code class="docutils literal notranslate"><span class="pre">!=</span></code></td>
</tr>
<tr class="row-even"><td><code class="xref py py-const docutils literal notranslate"><span class="pre">Py_GT</span></code></td>
<td><code class="docutils literal notranslate"><span class="pre">></span></code></td>
</tr>
<tr class="row-odd"><td><code class="xref py py-const docutils literal notranslate"><span class="pre">Py_GE</span></code></td>
<td><code class="docutils literal notranslate"><span class="pre">>=</span></code></td>
</tr>
</tbody>
</table>
</dd></dl>
<p>The next field only exists if the <a class="reference internal" href="#Py_TPFLAGS_HAVE_WEAKREFS" title="Py_TPFLAGS_HAVE_WEAKREFS"><code class="xref py py-const docutils literal notranslate"><span class="pre">Py_TPFLAGS_HAVE_WEAKREFS</span></code></a> flag bit is
set.</p>
<dl class="member">
<dt id="c.PyTypeObject.tp_weaklistoffset">
long <code class="descname">PyTypeObject.tp_weaklistoffset</code><a class="headerlink" href="#c.PyTypeObject.tp_weaklistoffset" title="Permalink to this definition">¶</a></dt>
<dd><p>If the instances of this type are weakly referenceable, this field is greater
than zero and contains the offset in the instance structure of the weak
reference list head (ignoring the GC header, if present); this offset is used by
<code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_ClearWeakRefs()</span></code> and the <code class="xref c c-func docutils literal notranslate"><span class="pre">PyWeakref_*()</span></code> functions. The
instance structure needs to include a field of type <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject*</span></code></a> which is
initialized to <em>NULL</em>.</p>
<p>Do not confuse this field with <a class="reference internal" href="#c.PyTypeObject.tp_weaklist" title="PyTypeObject.tp_weaklist"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_weaklist</span></code></a>; that is the list head for
weak references to the type object itself.</p>
<p>This field is inherited by subtypes, but see the rules listed below. A subtype
may override this offset; this means that the subtype uses a different weak
reference list head than the base type. Since the list head is always found via
<a class="reference internal" href="#c.PyTypeObject.tp_weaklistoffset" title="PyTypeObject.tp_weaklistoffset"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_weaklistoffset</span></code></a>, this should not be a problem.</p>
<p>When a type defined by a class statement has no <code class="xref py py-attr docutils literal notranslate"><span class="pre">__slots__</span></code> declaration,
and none of its base types are weakly referenceable, the type is made weakly
referenceable by adding a weak reference list head slot to the instance layout
and setting the <a class="reference internal" href="#c.PyTypeObject.tp_weaklistoffset" title="PyTypeObject.tp_weaklistoffset"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_weaklistoffset</span></code></a> of that slot’s offset.</p>
<p>When a type’s <a class="reference internal" href="../reference/datamodel.html#__slots__" title="__slots__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__slots__</span></code></a> declaration contains a slot named
<code class="xref py py-attr docutils literal notranslate"><span class="pre">__weakref__</span></code>, that slot becomes the weak reference list head for
instances of the type, and the slot’s offset is stored in the type’s
<a class="reference internal" href="#c.PyTypeObject.tp_weaklistoffset" title="PyTypeObject.tp_weaklistoffset"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_weaklistoffset</span></code></a>.</p>
<p>When a type’s <a class="reference internal" href="../reference/datamodel.html#__slots__" title="__slots__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__slots__</span></code></a> declaration does not contain a slot named
<code class="xref py py-attr docutils literal notranslate"><span class="pre">__weakref__</span></code>, the type inherits its <a class="reference internal" href="#c.PyTypeObject.tp_weaklistoffset" title="PyTypeObject.tp_weaklistoffset"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_weaklistoffset</span></code></a> from its
base type.</p>
</dd></dl>
<p>The next two fields only exist if the <a class="reference internal" href="#Py_TPFLAGS_HAVE_ITER" title="Py_TPFLAGS_HAVE_ITER"><code class="xref py py-const docutils literal notranslate"><span class="pre">Py_TPFLAGS_HAVE_ITER</span></code></a> flag bit is
set.</p>
<dl class="member">
<dt id="c.PyTypeObject.tp_iter">
getiterfunc <code class="descname">PyTypeObject.tp_iter</code><a class="headerlink" href="#c.PyTypeObject.tp_iter" title="Permalink to this definition">¶</a></dt>
<dd><p>An optional pointer to a function that returns an iterator for the object. Its
presence normally signals that the instances of this type are iterable (although
sequences may be iterable without this function, and classic instances always
have this function, even if they don’t define an <a class="reference internal" href="../reference/datamodel.html#object.__iter__" title="object.__iter__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__iter__()</span></code></a> method).</p>
<p>This function has the same signature as <a class="reference internal" href="object.html#c.PyObject_GetIter" title="PyObject_GetIter"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_GetIter()</span></code></a>.</p>
<p>This field is inherited by subtypes.</p>
</dd></dl>
<dl class="member">
<dt id="c.PyTypeObject.tp_iternext">
iternextfunc <code class="descname">PyTypeObject.tp_iternext</code><a class="headerlink" href="#c.PyTypeObject.tp_iternext" title="Permalink to this definition">¶</a></dt>
<dd><p>An optional pointer to a function that returns the next item in an iterator.
When the iterator is exhausted, it must return <em>NULL</em>; a <a class="reference internal" href="../library/exceptions.html#exceptions.StopIteration" title="exceptions.StopIteration"><code class="xref py py-exc docutils literal notranslate"><span class="pre">StopIteration</span></code></a>
exception may or may not be set. When another error occurs, it must return
<em>NULL</em> too. Its presence normally signals that the instances of this type
are iterators (although classic instances always have this function, even if
they don’t define a <a class="reference internal" href="../library/stdtypes.html#iterator.next" title="iterator.next"><code class="xref py py-meth docutils literal notranslate"><span class="pre">next()</span></code></a> method).</p>
<p>Iterator types should also define the <a class="reference internal" href="#c.PyTypeObject.tp_iter" title="PyTypeObject.tp_iter"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_iter</span></code></a> function, and that
function should return the iterator instance itself (not a new iterator
instance).</p>
<p>This function has the same signature as <a class="reference internal" href="iter.html#c.PyIter_Next" title="PyIter_Next"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyIter_Next()</span></code></a>.</p>
<p>This field is inherited by subtypes.</p>
</dd></dl>
<p>The next fields, up to and including <a class="reference internal" href="#c.PyTypeObject.tp_weaklist" title="PyTypeObject.tp_weaklist"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_weaklist</span></code></a>, only exist if the
<a class="reference internal" href="#Py_TPFLAGS_HAVE_CLASS" title="Py_TPFLAGS_HAVE_CLASS"><code class="xref py py-const docutils literal notranslate"><span class="pre">Py_TPFLAGS_HAVE_CLASS</span></code></a> flag bit is set.</p>
<dl class="member">
<dt id="c.PyTypeObject.tp_methods">
struct <a class="reference internal" href="structures.html#c.PyMethodDef" title="PyMethodDef">PyMethodDef</a>* <code class="descname">PyTypeObject.tp_methods</code><a class="headerlink" href="#c.PyTypeObject.tp_methods" title="Permalink to this definition">¶</a></dt>
<dd><p>An optional pointer to a static <em>NULL</em>-terminated array of <a class="reference internal" href="structures.html#c.PyMethodDef" title="PyMethodDef"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyMethodDef</span></code></a>
structures, declaring regular methods of this type.</p>
<p>For each entry in the array, an entry is added to the type’s dictionary (see
<a class="reference internal" href="#c.PyTypeObject.tp_dict" title="PyTypeObject.tp_dict"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_dict</span></code></a> below) containing a method descriptor.</p>
<p>This field is not inherited by subtypes (methods are inherited through a
different mechanism).</p>
</dd></dl>
<dl class="member">
<dt id="c.PyTypeObject.tp_members">
struct <a class="reference internal" href="structures.html#c.PyMemberDef" title="PyMemberDef">PyMemberDef</a>* <code class="descname">PyTypeObject.tp_members</code><a class="headerlink" href="#c.PyTypeObject.tp_members" title="Permalink to this definition">¶</a></dt>
<dd><p>An optional pointer to a static <em>NULL</em>-terminated array of <a class="reference internal" href="structures.html#c.PyMemberDef" title="PyMemberDef"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyMemberDef</span></code></a>
structures, declaring regular data members (fields or slots) of instances of
this type.</p>
<p>For each entry in the array, an entry is added to the type’s dictionary (see
<a class="reference internal" href="#c.PyTypeObject.tp_dict" title="PyTypeObject.tp_dict"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_dict</span></code></a> below) containing a member descriptor.</p>
<p>This field is not inherited by subtypes (members are inherited through a
different mechanism).</p>
</dd></dl>
<dl class="member">
<dt id="c.PyTypeObject.tp_getset">
struct <a class="reference internal" href="structures.html#c.PyGetSetDef" title="PyGetSetDef">PyGetSetDef</a>* <code class="descname">PyTypeObject.tp_getset</code><a class="headerlink" href="#c.PyTypeObject.tp_getset" title="Permalink to this definition">¶</a></dt>
<dd><p>An optional pointer to a static <em>NULL</em>-terminated array of <a class="reference internal" href="structures.html#c.PyGetSetDef" title="PyGetSetDef"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyGetSetDef</span></code></a>
structures, declaring computed attributes of instances of this type.</p>
<p>For each entry in the array, an entry is added to the type’s dictionary (see
<a class="reference internal" href="#c.PyTypeObject.tp_dict" title="PyTypeObject.tp_dict"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_dict</span></code></a> below) containing a getset descriptor.</p>
<p>This field is not inherited by subtypes (computed attributes are inherited
through a different mechanism).</p>
</dd></dl>
<dl class="member">
<dt id="c.PyTypeObject.tp_base">
<a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a>* <code class="descname">PyTypeObject.tp_base</code><a class="headerlink" href="#c.PyTypeObject.tp_base" title="Permalink to this definition">¶</a></dt>
<dd><p>An optional pointer to a base type from which type properties are inherited. At
this level, only single inheritance is supported; multiple inheritance require
dynamically creating a type object by calling the metatype.</p>
<p>This field is not inherited by subtypes (obviously), but it defaults to
<code class="docutils literal notranslate"><span class="pre">&PyBaseObject_Type</span></code> (which to Python programmers is known as the type
<a class="reference internal" href="../library/functions.html#object" title="object"><code class="xref py py-class docutils literal notranslate"><span class="pre">object</span></code></a>).</p>
</dd></dl>
<dl class="member">
<dt id="c.PyTypeObject.tp_dict">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyTypeObject.tp_dict</code><a class="headerlink" href="#c.PyTypeObject.tp_dict" title="Permalink to this definition">¶</a></dt>
<dd><p>The type’s dictionary is stored here by <a class="reference internal" href="type.html#c.PyType_Ready" title="PyType_Ready"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_Ready()</span></code></a>.</p>
<p>This field should normally be initialized to <em>NULL</em> before PyType_Ready is
called; it may also be initialized to a dictionary containing initial attributes
for the type. Once <a class="reference internal" href="type.html#c.PyType_Ready" title="PyType_Ready"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_Ready()</span></code></a> has initialized the type, extra
attributes for the type may be added to this dictionary only if they don’t
correspond to overloaded operations (like <a class="reference internal" href="../reference/datamodel.html#object.__add__" title="object.__add__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__add__()</span></code></a>).</p>
<p>This field is not inherited by subtypes (though the attributes defined in here
are inherited through a different mechanism).</p>
</dd></dl>
<dl class="member">
<dt id="c.PyTypeObject.tp_descr_get">
descrgetfunc <code class="descname">PyTypeObject.tp_descr_get</code><a class="headerlink" href="#c.PyTypeObject.tp_descr_get" title="Permalink to this definition">¶</a></dt>
<dd><p>An optional pointer to a “descriptor get” function.</p>
<p>The function signature is</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">PyObject</span> <span class="o">*</span> <span class="nf">tp_descr_get</span><span class="p">(</span><span class="n">PyObject</span> <span class="o">*</span><span class="n">self</span><span class="p">,</span> <span class="n">PyObject</span> <span class="o">*</span><span class="n">obj</span><span class="p">,</span> <span class="n">PyObject</span> <span class="o">*</span><span class="n">type</span><span class="p">);</span>
</pre></div>
</div>
<p>This field is inherited by subtypes.</p>
</dd></dl>
<dl class="member">
<dt id="c.PyTypeObject.tp_descr_set">
descrsetfunc <code class="descname">PyTypeObject.tp_descr_set</code><a class="headerlink" href="#c.PyTypeObject.tp_descr_set" title="Permalink to this definition">¶</a></dt>
<dd><p>An optional pointer to a function for setting and deleting
a descriptor’s value.</p>
<p>The function signature is</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="nf">tp_descr_set</span><span class="p">(</span><span class="n">PyObject</span> <span class="o">*</span><span class="n">self</span><span class="p">,</span> <span class="n">PyObject</span> <span class="o">*</span><span class="n">obj</span><span class="p">,</span> <span class="n">PyObject</span> <span class="o">*</span><span class="n">value</span><span class="p">);</span>
</pre></div>
</div>
<p>The <em>value</em> argument is set to <em>NULL</em> to delete the value.
This field is inherited by subtypes.</p>
</dd></dl>
<dl class="member">
<dt id="c.PyTypeObject.tp_dictoffset">
long <code class="descname">PyTypeObject.tp_dictoffset</code><a class="headerlink" href="#c.PyTypeObject.tp_dictoffset" title="Permalink to this definition">¶</a></dt>
<dd><p>If the instances of this type have a dictionary containing instance variables,
this field is non-zero and contains the offset in the instances of the type of
the instance variable dictionary; this offset is used by
<a class="reference internal" href="object.html#c.PyObject_GenericGetAttr" title="PyObject_GenericGetAttr"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_GenericGetAttr()</span></code></a>.</p>
<p>Do not confuse this field with <a class="reference internal" href="#c.PyTypeObject.tp_dict" title="PyTypeObject.tp_dict"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_dict</span></code></a>; that is the dictionary for
attributes of the type object itself.</p>
<p>If the value of this field is greater than zero, it specifies the offset from
the start of the instance structure. If the value is less than zero, it
specifies the offset from the <em>end</em> of the instance structure. A negative
offset is more expensive to use, and should only be used when the instance
structure contains a variable-length part. This is used for example to add an
instance variable dictionary to subtypes of <a class="reference internal" href="../library/functions.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> or <a class="reference internal" href="../library/functions.html#tuple" title="tuple"><code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code></a>. Note
that the <a class="reference internal" href="#c.PyTypeObject.tp_basicsize" title="PyTypeObject.tp_basicsize"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_basicsize</span></code></a> field should account for the dictionary added to
the end in that case, even though the dictionary is not included in the basic
object layout. On a system with a pointer size of 4 bytes,
<a class="reference internal" href="#c.PyTypeObject.tp_dictoffset" title="PyTypeObject.tp_dictoffset"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_dictoffset</span></code></a> should be set to <code class="docutils literal notranslate"><span class="pre">-4</span></code> to indicate that the dictionary is
at the very end of the structure.</p>
<p>The real dictionary offset in an instance can be computed from a negative
<a class="reference internal" href="#c.PyTypeObject.tp_dictoffset" title="PyTypeObject.tp_dictoffset"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_dictoffset</span></code></a> as follows:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">dictoffset</span> <span class="o">=</span> <span class="n">tp_basicsize</span> <span class="o">+</span> <span class="n">abs</span><span class="p">(</span><span class="n">ob_size</span><span class="p">)</span><span class="o">*</span><span class="n">tp_itemsize</span> <span class="o">+</span> <span class="n">tp_dictoffset</span>
<span class="k">if</span> <span class="n">dictoffset</span> <span class="n">is</span> <span class="n">not</span> <span class="n">aligned</span> <span class="n">on</span> <span class="k">sizeof</span><span class="p">(</span><span class="kt">void</span><span class="o">*</span><span class="p">)</span><span class="o">:</span>
<span class="n">round</span> <span class="n">up</span> <span class="n">to</span> <span class="k">sizeof</span><span class="p">(</span><span class="kt">void</span><span class="o">*</span><span class="p">)</span>
</pre></div>
</div>
<p>where <a class="reference internal" href="#c.PyTypeObject.tp_basicsize" title="PyTypeObject.tp_basicsize"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_basicsize</span></code></a>, <a class="reference internal" href="#c.PyTypeObject.tp_itemsize" title="PyTypeObject.tp_itemsize"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_itemsize</span></code></a> and <a class="reference internal" href="#c.PyTypeObject.tp_dictoffset" title="PyTypeObject.tp_dictoffset"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_dictoffset</span></code></a> are
taken from the type object, and <code class="xref py py-attr docutils literal notranslate"><span class="pre">ob_size</span></code> is taken from the instance. The
absolute value is taken because long ints use the sign of <code class="xref py py-attr docutils literal notranslate"><span class="pre">ob_size</span></code> to
store the sign of the number. (There’s never a need to do this calculation
yourself; it is done for you by <code class="xref c c-func docutils literal notranslate"><span class="pre">_PyObject_GetDictPtr()</span></code>.)</p>
<p>This field is inherited by subtypes, but see the rules listed below. A subtype
may override this offset; this means that the subtype instances store the
dictionary at a difference offset than the base type. Since the dictionary is
always found via <a class="reference internal" href="#c.PyTypeObject.tp_dictoffset" title="PyTypeObject.tp_dictoffset"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_dictoffset</span></code></a>, this should not be a problem.</p>
<p>When a type defined by a class statement has no <code class="xref py py-attr docutils literal notranslate"><span class="pre">__slots__</span></code> declaration,
and none of its base types has an instance variable dictionary, a dictionary
slot is added to the instance layout and the <a class="reference internal" href="#c.PyTypeObject.tp_dictoffset" title="PyTypeObject.tp_dictoffset"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_dictoffset</span></code></a> is set to
that slot’s offset.</p>
<p>When a type defined by a class statement has a <a class="reference internal" href="../reference/datamodel.html#__slots__" title="__slots__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__slots__</span></code></a> declaration,
the type inherits its <a class="reference internal" href="#c.PyTypeObject.tp_dictoffset" title="PyTypeObject.tp_dictoffset"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_dictoffset</span></code></a> from its base type.</p>
<p>(Adding a slot named <a class="reference internal" href="../library/stdtypes.html#object.__dict__" title="object.__dict__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__dict__</span></code></a> to the <a class="reference internal" href="../reference/datamodel.html#__slots__" title="__slots__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__slots__</span></code></a> declaration does
not have the expected effect, it just causes confusion. Maybe this should be
added as a feature just like <code class="xref py py-attr docutils literal notranslate"><span class="pre">__weakref__</span></code> though.)</p>
</dd></dl>
<dl class="member">
<dt id="c.PyTypeObject.tp_init">
initproc <code class="descname">PyTypeObject.tp_init</code><a class="headerlink" href="#c.PyTypeObject.tp_init" title="Permalink to this definition">¶</a></dt>
<dd><p>An optional pointer to an instance initialization function.</p>
<p>This function corresponds to the <a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a> method of classes. Like
<a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a>, it is possible to create an instance without calling
<a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a>, and it is possible to reinitialize an instance by calling its
<a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a> method again.</p>
<p>The function signature is</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="n">tp_init</span><span class="p">(</span><span class="n">PyObject</span> <span class="o">*</span><span class="n">self</span><span class="p">,</span> <span class="n">PyObject</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="n">PyObject</span> <span class="o">*</span><span class="n">kwds</span><span class="p">)</span>
</pre></div>
</div>
<p>The self argument is the instance to be initialized; the <em>args</em> and <em>kwds</em>
arguments represent positional and keyword arguments of the call to
<a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a>.</p>
<p>The <a class="reference internal" href="#c.PyTypeObject.tp_init" title="PyTypeObject.tp_init"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_init</span></code></a> function, if not <em>NULL</em>, is called when an instance is
created normally by calling its type, after the type’s <a class="reference internal" href="#c.PyTypeObject.tp_new" title="PyTypeObject.tp_new"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_new</span></code></a> function
has returned an instance of the type. If the <a class="reference internal" href="#c.PyTypeObject.tp_new" title="PyTypeObject.tp_new"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_new</span></code></a> function returns an
instance of some other type that is not a subtype of the original type, no
<a class="reference internal" href="#c.PyTypeObject.tp_init" title="PyTypeObject.tp_init"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_init</span></code></a> function is called; if <a class="reference internal" href="#c.PyTypeObject.tp_new" title="PyTypeObject.tp_new"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_new</span></code></a> returns an instance of a
subtype of the original type, the subtype’s <a class="reference internal" href="#c.PyTypeObject.tp_init" title="PyTypeObject.tp_init"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_init</span></code></a> is called. (VERSION
NOTE: described here is what is implemented in Python 2.2.1 and later. In
Python 2.2, the <a class="reference internal" href="#c.PyTypeObject.tp_init" title="PyTypeObject.tp_init"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_init</span></code></a> of the type of the object returned by
<a class="reference internal" href="#c.PyTypeObject.tp_new" title="PyTypeObject.tp_new"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_new</span></code></a> was always called, if not <em>NULL</em>.)</p>
<p>This field is inherited by subtypes.</p>
</dd></dl>
<dl class="member">
<dt id="c.PyTypeObject.tp_alloc">
allocfunc <code class="descname">PyTypeObject.tp_alloc</code><a class="headerlink" href="#c.PyTypeObject.tp_alloc" title="Permalink to this definition">¶</a></dt>
<dd><p>An optional pointer to an instance allocation function.</p>
<p>The function signature is</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">PyObject</span> <span class="o">*</span><span class="n">tp_alloc</span><span class="p">(</span><span class="n">PyTypeObject</span> <span class="o">*</span><span class="n">self</span><span class="p">,</span> <span class="n">Py_ssize_t</span> <span class="n">nitems</span><span class="p">)</span>
</pre></div>
</div>
<p>The purpose of this function is to separate memory allocation from memory
initialization. It should return a pointer to a block of memory of adequate
length for the instance, suitably aligned, and initialized to zeros, but with
<code class="xref py py-attr docutils literal notranslate"><span class="pre">ob_refcnt</span></code> set to <code class="docutils literal notranslate"><span class="pre">1</span></code> and <code class="xref py py-attr docutils literal notranslate"><span class="pre">ob_type</span></code> set to the type argument. If
the type’s <a class="reference internal" href="#c.PyTypeObject.tp_itemsize" title="PyTypeObject.tp_itemsize"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_itemsize</span></code></a> is non-zero, the object’s <code class="xref py py-attr docutils literal notranslate"><span class="pre">ob_size</span></code> field
should be initialized to <em>nitems</em> and the length of the allocated memory block
should be <code class="docutils literal notranslate"><span class="pre">tp_basicsize</span> <span class="pre">+</span> <span class="pre">nitems*tp_itemsize</span></code>, rounded up to a multiple of
<code class="docutils literal notranslate"><span class="pre">sizeof(void*)</span></code>; otherwise, <em>nitems</em> is not used and the length of the block
should be <a class="reference internal" href="#c.PyTypeObject.tp_basicsize" title="PyTypeObject.tp_basicsize"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_basicsize</span></code></a>.</p>
<p>Do not use this function to do any other instance initialization, not even to
allocate additional memory; that should be done by <a class="reference internal" href="#c.PyTypeObject.tp_new" title="PyTypeObject.tp_new"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_new</span></code></a>.</p>
<p>This field is inherited by static subtypes, but not by dynamic subtypes
(subtypes created by a class statement); in the latter, this field is always set
to <a class="reference internal" href="type.html#c.PyType_GenericAlloc" title="PyType_GenericAlloc"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_GenericAlloc()</span></code></a>, to force a standard heap allocation strategy.
That is also the recommended value for statically defined types.</p>
</dd></dl>
<dl class="member">
<dt id="c.PyTypeObject.tp_new">
newfunc <code class="descname">PyTypeObject.tp_new</code><a class="headerlink" href="#c.PyTypeObject.tp_new" title="Permalink to this definition">¶</a></dt>
<dd><p>An optional pointer to an instance creation function.</p>
<p>If this function is <em>NULL</em> for a particular type, that type cannot be called to
create new instances; presumably there is some other way to create instances,
like a factory function.</p>
<p>The function signature is</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">PyObject</span> <span class="o">*</span><span class="n">tp_new</span><span class="p">(</span><span class="n">PyTypeObject</span> <span class="o">*</span><span class="n">subtype</span><span class="p">,</span> <span class="n">PyObject</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="n">PyObject</span> <span class="o">*</span><span class="n">kwds</span><span class="p">)</span>
</pre></div>
</div>
<p>The subtype argument is the type of the object being created; the <em>args</em> and
<em>kwds</em> arguments represent positional and keyword arguments of the call to the
type. Note that subtype doesn’t have to equal the type whose <a class="reference internal" href="#c.PyTypeObject.tp_new" title="PyTypeObject.tp_new"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_new</span></code></a>
function is called; it may be a subtype of that type (but not an unrelated
type).</p>
<p>The <a class="reference internal" href="#c.PyTypeObject.tp_new" title="PyTypeObject.tp_new"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_new</span></code></a> function should call <code class="docutils literal notranslate"><span class="pre">subtype->tp_alloc(subtype,</span> <span class="pre">nitems)</span></code>
to allocate space for the object, and then do only as much further
initialization as is absolutely necessary. Initialization that can safely be
ignored or repeated should be placed in the <a class="reference internal" href="#c.PyTypeObject.tp_init" title="PyTypeObject.tp_init"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_init</span></code></a> handler. A good
rule of thumb is that for immutable types, all initialization should take place
in <a class="reference internal" href="#c.PyTypeObject.tp_new" title="PyTypeObject.tp_new"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_new</span></code></a>, while for mutable types, most initialization should be
deferred to <a class="reference internal" href="#c.PyTypeObject.tp_init" title="PyTypeObject.tp_init"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_init</span></code></a>.</p>
<p>This field is inherited by subtypes, except it is not inherited by static types
whose <a class="reference internal" href="#c.PyTypeObject.tp_base" title="PyTypeObject.tp_base"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_base</span></code></a> is <em>NULL</em> or <code class="docutils literal notranslate"><span class="pre">&PyBaseObject_Type</span></code>. The latter exception
is a precaution so that old extension types don’t become callable simply by
being linked with Python 2.2.</p>
</dd></dl>
<dl class="member">
<dt id="c.PyTypeObject.tp_free">
destructor <code class="descname">PyTypeObject.tp_free</code><a class="headerlink" href="#c.PyTypeObject.tp_free" title="Permalink to this definition">¶</a></dt>
<dd><p>An optional pointer to an instance deallocation function.</p>
<p>The signature of this function has changed slightly: in Python 2.2 and 2.2.1,
its signature is <code class="xref c c-type docutils literal notranslate"><span class="pre">destructor</span></code>:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="n">tp_free</span><span class="p">(</span><span class="n">PyObject</span> <span class="o">*</span><span class="p">)</span>
</pre></div>
</div>
<p>In Python 2.3 and beyond, its signature is <code class="xref c c-type docutils literal notranslate"><span class="pre">freefunc</span></code>:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="n">tp_free</span><span class="p">(</span><span class="kt">void</span> <span class="o">*</span><span class="p">)</span>
</pre></div>
</div>
<p>The only initializer that is compatible with both versions is <code class="docutils literal notranslate"><span class="pre">_PyObject_Del</span></code>,
whose definition has suitably adapted in Python 2.3.</p>
<p>This field is inherited by static subtypes, but not by dynamic subtypes
(subtypes created by a class statement); in the latter, this field is set to a
deallocator suitable to match <a class="reference internal" href="type.html#c.PyType_GenericAlloc" title="PyType_GenericAlloc"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_GenericAlloc()</span></code></a> and the value of the
<a class="reference internal" href="#Py_TPFLAGS_HAVE_GC" title="Py_TPFLAGS_HAVE_GC"><code class="xref py py-const docutils literal notranslate"><span class="pre">Py_TPFLAGS_HAVE_GC</span></code></a> flag bit.</p>
</dd></dl>
<dl class="member">
<dt id="c.PyTypeObject.tp_is_gc">
<a class="reference internal" href="gcsupport.html#c.inquiry" title="inquiry">inquiry</a> <code class="descname">PyTypeObject.tp_is_gc</code><a class="headerlink" href="#c.PyTypeObject.tp_is_gc" title="Permalink to this definition">¶</a></dt>
<dd><p>An optional pointer to a function called by the garbage collector.</p>
<p>The garbage collector needs to know whether a particular object is collectible
or not. Normally, it is sufficient to look at the object’s type’s
<a class="reference internal" href="#c.PyTypeObject.tp_flags" title="PyTypeObject.tp_flags"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_flags</span></code></a> field, and check the <a class="reference internal" href="#Py_TPFLAGS_HAVE_GC" title="Py_TPFLAGS_HAVE_GC"><code class="xref py py-const docutils literal notranslate"><span class="pre">Py_TPFLAGS_HAVE_GC</span></code></a> flag bit. But
some types have a mixture of statically and dynamically allocated instances, and
the statically allocated instances are not collectible. Such types should
define this function; it should return <code class="docutils literal notranslate"><span class="pre">1</span></code> for a collectible instance, and
<code class="docutils literal notranslate"><span class="pre">0</span></code> for a non-collectible instance. The signature is</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="n">tp_is_gc</span><span class="p">(</span><span class="n">PyObject</span> <span class="o">*</span><span class="n">self</span><span class="p">)</span>
</pre></div>
</div>
<p>(The only example of this are types themselves. The metatype,
<a class="reference internal" href="type.html#c.PyType_Type" title="PyType_Type"><code class="xref c c-data docutils literal notranslate"><span class="pre">PyType_Type</span></code></a>, defines this function to distinguish between statically
and dynamically allocated types.)</p>
<p>This field is inherited by subtypes. (VERSION NOTE: in Python 2.2, it was not
inherited. It is inherited in 2.2.1 and later versions.)</p>
</dd></dl>
<dl class="member">
<dt id="c.PyTypeObject.tp_bases">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyTypeObject.tp_bases</code><a class="headerlink" href="#c.PyTypeObject.tp_bases" title="Permalink to this definition">¶</a></dt>
<dd><p>Tuple of base types.</p>
<p>This is set for types created by a class statement. It should be <em>NULL</em> for
statically defined types.</p>
<p>This field is not inherited.</p>
</dd></dl>
<dl class="member">
<dt id="c.PyTypeObject.tp_mro">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyTypeObject.tp_mro</code><a class="headerlink" href="#c.PyTypeObject.tp_mro" title="Permalink to this definition">¶</a></dt>
<dd><p>Tuple containing the expanded set of base types, starting with the type itself
and ending with <a class="reference internal" href="../library/functions.html#object" title="object"><code class="xref py py-class docutils literal notranslate"><span class="pre">object</span></code></a>, in Method Resolution Order.</p>
<p>This field is not inherited; it is calculated fresh by <a class="reference internal" href="type.html#c.PyType_Ready" title="PyType_Ready"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_Ready()</span></code></a>.</p>
</dd></dl>
<dl class="member">
<dt id="c.PyTypeObject.tp_cache">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyTypeObject.tp_cache</code><a class="headerlink" href="#c.PyTypeObject.tp_cache" title="Permalink to this definition">¶</a></dt>
<dd><p>Unused. Not inherited. Internal use only.</p>
</dd></dl>
<dl class="member">
<dt id="c.PyTypeObject.tp_subclasses">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyTypeObject.tp_subclasses</code><a class="headerlink" href="#c.PyTypeObject.tp_subclasses" title="Permalink to this definition">¶</a></dt>
<dd><p>List of weak references to subclasses. Not inherited. Internal use only.</p>
</dd></dl>
<dl class="member">
<dt id="c.PyTypeObject.tp_weaklist">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyTypeObject.tp_weaklist</code><a class="headerlink" href="#c.PyTypeObject.tp_weaklist" title="Permalink to this definition">¶</a></dt>
<dd><p>Weak reference list head, for weak references to this type object. Not
inherited. Internal use only.</p>
</dd></dl>
<p>The remaining fields are only defined if the feature test macro
<code class="xref py py-const docutils literal notranslate"><span class="pre">COUNT_ALLOCS</span></code> is defined, and are for internal use only. They are
documented here for completeness. None of these fields are inherited by
subtypes. See the <span class="target" id="index-3"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONSHOWALLOCCOUNT"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONSHOWALLOCCOUNT</span></code></a> environment variable.</p>
<dl class="member">
<dt id="c.PyTypeObject.tp_allocs">
Py_ssize_t <code class="descname">PyTypeObject.tp_allocs</code><a class="headerlink" href="#c.PyTypeObject.tp_allocs" title="Permalink to this definition">¶</a></dt>
<dd><p>Number of allocations.</p>
</dd></dl>
<dl class="member">
<dt id="c.PyTypeObject.tp_frees">
Py_ssize_t <code class="descname">PyTypeObject.tp_frees</code><a class="headerlink" href="#c.PyTypeObject.tp_frees" title="Permalink to this definition">¶</a></dt>
<dd><p>Number of frees.</p>
</dd></dl>
<dl class="member">
<dt id="c.PyTypeObject.tp_maxalloc">
Py_ssize_t <code class="descname">PyTypeObject.tp_maxalloc</code><a class="headerlink" href="#c.PyTypeObject.tp_maxalloc" title="Permalink to this definition">¶</a></dt>
<dd><p>Maximum simultaneously allocated objects.</p>
</dd></dl>
<dl class="member">
<dt id="c.PyTypeObject.tp_next">
<a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a>* <code class="descname">PyTypeObject.tp_next</code><a class="headerlink" href="#c.PyTypeObject.tp_next" title="Permalink to this definition">¶</a></dt>
<dd><p>Pointer to the next type object with a non-zero <a class="reference internal" href="#c.PyTypeObject.tp_allocs" title="PyTypeObject.tp_allocs"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_allocs</span></code></a> field.</p>
</dd></dl>
<p>Also, note that, in a garbage collected Python, tp_dealloc may be called from
any Python thread, not just the thread which created the object (if the object
becomes part of a refcount cycle, that cycle might be collected by a garbage
collection on any thread). This is not a problem for Python API calls, since
the thread on which tp_dealloc is called will own the Global Interpreter Lock
(GIL). However, if the object being destroyed in turn destroys objects from some
other C or C++ library, care should be taken to ensure that destroying those
objects on the thread which called tp_dealloc will not violate any assumptions
of the library.</p>
</div>
<div class="section" id="number-object-structures">
<span id="number-structs"></span><h1>Number Object Structures<a class="headerlink" href="#number-object-structures" title="Permalink to this headline">¶</a></h1>
<dl class="type">
<dt id="c.PyNumberMethods">
<code class="descname">PyNumberMethods</code><a class="headerlink" href="#c.PyNumberMethods" title="Permalink to this definition">¶</a></dt>
<dd><p>This structure holds pointers to the functions which an object uses to
implement the number protocol. Almost every function below is used by the
function of similar name documented in the <a class="reference internal" href="number.html#number"><span class="std std-ref">Number Protocol</span></a> section.</p>
<p>Here is the structure definition:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">typedef</span> <span class="k">struct</span> <span class="p">{</span>
<span class="n">binaryfunc</span> <span class="n">nb_add</span><span class="p">;</span>
<span class="n">binaryfunc</span> <span class="n">nb_subtract</span><span class="p">;</span>
<span class="n">binaryfunc</span> <span class="n">nb_multiply</span><span class="p">;</span>
<span class="n">binaryfunc</span> <span class="n">nb_divide</span><span class="p">;</span>
<span class="n">binaryfunc</span> <span class="n">nb_remainder</span><span class="p">;</span>
<span class="n">binaryfunc</span> <span class="n">nb_divmod</span><span class="p">;</span>
<span class="n">ternaryfunc</span> <span class="n">nb_power</span><span class="p">;</span>
<span class="n">unaryfunc</span> <span class="n">nb_negative</span><span class="p">;</span>
<span class="n">unaryfunc</span> <span class="n">nb_positive</span><span class="p">;</span>
<span class="n">unaryfunc</span> <span class="n">nb_absolute</span><span class="p">;</span>
<span class="n">inquiry</span> <span class="n">nb_nonzero</span><span class="p">;</span> <span class="cm">/* Used by PyObject_IsTrue */</span>
<span class="n">unaryfunc</span> <span class="n">nb_invert</span><span class="p">;</span>
<span class="n">binaryfunc</span> <span class="n">nb_lshift</span><span class="p">;</span>
<span class="n">binaryfunc</span> <span class="n">nb_rshift</span><span class="p">;</span>
<span class="n">binaryfunc</span> <span class="n">nb_and</span><span class="p">;</span>
<span class="n">binaryfunc</span> <span class="n">nb_xor</span><span class="p">;</span>
<span class="n">binaryfunc</span> <span class="n">nb_or</span><span class="p">;</span>
<span class="n">coercion</span> <span class="n">nb_coerce</span><span class="p">;</span> <span class="cm">/* Used by the coerce() function */</span>
<span class="n">unaryfunc</span> <span class="n">nb_int</span><span class="p">;</span>
<span class="n">unaryfunc</span> <span class="n">nb_long</span><span class="p">;</span>
<span class="n">unaryfunc</span> <span class="n">nb_float</span><span class="p">;</span>
<span class="n">unaryfunc</span> <span class="n">nb_oct</span><span class="p">;</span>
<span class="n">unaryfunc</span> <span class="n">nb_hex</span><span class="p">;</span>
<span class="cm">/* Added in release 2.0 */</span>
<span class="n">binaryfunc</span> <span class="n">nb_inplace_add</span><span class="p">;</span>
<span class="n">binaryfunc</span> <span class="n">nb_inplace_subtract</span><span class="p">;</span>
<span class="n">binaryfunc</span> <span class="n">nb_inplace_multiply</span><span class="p">;</span>
<span class="n">binaryfunc</span> <span class="n">nb_inplace_divide</span><span class="p">;</span>
<span class="n">binaryfunc</span> <span class="n">nb_inplace_remainder</span><span class="p">;</span>
<span class="n">ternaryfunc</span> <span class="n">nb_inplace_power</span><span class="p">;</span>
<span class="n">binaryfunc</span> <span class="n">nb_inplace_lshift</span><span class="p">;</span>
<span class="n">binaryfunc</span> <span class="n">nb_inplace_rshift</span><span class="p">;</span>
<span class="n">binaryfunc</span> <span class="n">nb_inplace_and</span><span class="p">;</span>
<span class="n">binaryfunc</span> <span class="n">nb_inplace_xor</span><span class="p">;</span>
<span class="n">binaryfunc</span> <span class="n">nb_inplace_or</span><span class="p">;</span>
<span class="cm">/* Added in release 2.2 */</span>
<span class="n">binaryfunc</span> <span class="n">nb_floor_divide</span><span class="p">;</span>
<span class="n">binaryfunc</span> <span class="n">nb_true_divide</span><span class="p">;</span>
<span class="n">binaryfunc</span> <span class="n">nb_inplace_floor_divide</span><span class="p">;</span>
<span class="n">binaryfunc</span> <span class="n">nb_inplace_true_divide</span><span class="p">;</span>
<span class="cm">/* Added in release 2.5 */</span>
<span class="n">unaryfunc</span> <span class="n">nb_index</span><span class="p">;</span>
<span class="p">}</span> <span class="n">PyNumberMethods</span><span class="p">;</span>
</pre></div>
</div>
</dd></dl>
<p>Binary and ternary functions may receive different kinds of arguments, depending
on the flag bit <a class="reference internal" href="#Py_TPFLAGS_CHECKTYPES" title="Py_TPFLAGS_CHECKTYPES"><code class="xref py py-const docutils literal notranslate"><span class="pre">Py_TPFLAGS_CHECKTYPES</span></code></a>:</p>
<ul>
<li><p class="first">If <a class="reference internal" href="#Py_TPFLAGS_CHECKTYPES" title="Py_TPFLAGS_CHECKTYPES"><code class="xref py py-const docutils literal notranslate"><span class="pre">Py_TPFLAGS_CHECKTYPES</span></code></a> is not set, the function arguments are
guaranteed to be of the object’s type; the caller is responsible for calling
the coercion method specified by the <code class="xref py py-attr docutils literal notranslate"><span class="pre">nb_coerce</span></code> member to convert the
arguments:</p>
<dl class="member">
<dt id="c.PyNumberMethods.nb_coerce">
coercion <code class="descname">PyNumberMethods.nb_coerce</code><a class="headerlink" href="#c.PyNumberMethods.nb_coerce" title="Permalink to this definition">¶</a></dt>
<dd><p>This function is used by <a class="reference internal" href="number.html#c.PyNumber_CoerceEx" title="PyNumber_CoerceEx"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyNumber_CoerceEx()</span></code></a> and has the same
signature. The first argument is always a pointer to an object of the
defined type. If the conversion to a common “larger” type is possible, the
function replaces the pointers with new references to the converted objects
and returns <code class="docutils literal notranslate"><span class="pre">0</span></code>. If the conversion is not possible, the function returns
<code class="docutils literal notranslate"><span class="pre">1</span></code>. If an error condition is set, it will return <code class="docutils literal notranslate"><span class="pre">-1</span></code>.</p>
</dd></dl>
</li>
<li><p class="first">If the <a class="reference internal" href="#Py_TPFLAGS_CHECKTYPES" title="Py_TPFLAGS_CHECKTYPES"><code class="xref py py-const docutils literal notranslate"><span class="pre">Py_TPFLAGS_CHECKTYPES</span></code></a> flag is set, binary and ternary
functions must check the type of all their operands, and implement the
necessary conversions (at least one of the operands is an instance of the
defined type). This is the recommended way; with Python 3 coercion will
disappear completely.</p>
</li>
</ul>
<p>If the operation is not defined for the given operands, binary and ternary
functions must return <code class="docutils literal notranslate"><span class="pre">Py_NotImplemented</span></code>, if another error occurred they must
return <code class="docutils literal notranslate"><span class="pre">NULL</span></code> and set an exception.</p>
</div>
<div class="section" id="mapping-object-structures">
<span id="mapping-structs"></span><h1>Mapping Object Structures<a class="headerlink" href="#mapping-object-structures" title="Permalink to this headline">¶</a></h1>
<dl class="type">
<dt id="c.PyMappingMethods">
<code class="descname">PyMappingMethods</code><a class="headerlink" href="#c.PyMappingMethods" title="Permalink to this definition">¶</a></dt>
<dd><p>This structure holds pointers to the functions which an object uses to
implement the mapping protocol. It has three members:</p>
</dd></dl>
<dl class="member">
<dt id="c.PyMappingMethods.mp_length">
lenfunc <code class="descname">PyMappingMethods.mp_length</code><a class="headerlink" href="#c.PyMappingMethods.mp_length" title="Permalink to this definition">¶</a></dt>
<dd><p>This function is used by <a class="reference internal" href="mapping.html#c.PyMapping_Length" title="PyMapping_Length"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyMapping_Length()</span></code></a> and
<a class="reference internal" href="object.html#c.PyObject_Size" title="PyObject_Size"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_Size()</span></code></a>, and has the same signature. This slot may be set to
<em>NULL</em> if the object has no defined length.</p>
</dd></dl>
<dl class="member">
<dt id="c.PyMappingMethods.mp_subscript">
binaryfunc <code class="descname">PyMappingMethods.mp_subscript</code><a class="headerlink" href="#c.PyMappingMethods.mp_subscript" title="Permalink to this definition">¶</a></dt>
<dd><p>This function is used by <a class="reference internal" href="object.html#c.PyObject_GetItem" title="PyObject_GetItem"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_GetItem()</span></code></a> and has the same
signature. This slot must be filled for the <a class="reference internal" href="mapping.html#c.PyMapping_Check" title="PyMapping_Check"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyMapping_Check()</span></code></a>
function to return <code class="docutils literal notranslate"><span class="pre">1</span></code>, it can be <em>NULL</em> otherwise.</p>
</dd></dl>
<dl class="member">
<dt id="c.PyMappingMethods.mp_ass_subscript">
objobjargproc <code class="descname">PyMappingMethods.mp_ass_subscript</code><a class="headerlink" href="#c.PyMappingMethods.mp_ass_subscript" title="Permalink to this definition">¶</a></dt>
<dd><p>This function is used by <a class="reference internal" href="object.html#c.PyObject_SetItem" title="PyObject_SetItem"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_SetItem()</span></code></a> and
<a class="reference internal" href="object.html#c.PyObject_DelItem" title="PyObject_DelItem"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_DelItem()</span></code></a>. It has the same signature as
<a class="reference internal" href="object.html#c.PyObject_SetItem" title="PyObject_SetItem"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_SetItem()</span></code></a>, but <em>v</em> can also be set to <em>NULL</em> to delete
an item. If this slot is <em>NULL</em>, the object does not support item
assignment and deletion.</p>
</dd></dl>
</div>
<div class="section" id="sequence-object-structures">
<span id="sequence-structs"></span><h1>Sequence Object Structures<a class="headerlink" href="#sequence-object-structures" title="Permalink to this headline">¶</a></h1>
<dl class="type">
<dt id="c.PySequenceMethods">
<code class="descname">PySequenceMethods</code><a class="headerlink" href="#c.PySequenceMethods" title="Permalink to this definition">¶</a></dt>
<dd><p>This structure holds pointers to the functions which an object uses to
implement the sequence protocol.</p>
</dd></dl>
<dl class="member">
<dt id="c.PySequenceMethods.sq_length">
lenfunc <code class="descname">PySequenceMethods.sq_length</code><a class="headerlink" href="#c.PySequenceMethods.sq_length" title="Permalink to this definition">¶</a></dt>
<dd><p>This function is used by <a class="reference internal" href="sequence.html#c.PySequence_Size" title="PySequence_Size"><code class="xref c c-func docutils literal notranslate"><span class="pre">PySequence_Size()</span></code></a> and <a class="reference internal" href="object.html#c.PyObject_Size" title="PyObject_Size"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_Size()</span></code></a>,
and has the same signature.</p>
</dd></dl>
<dl class="member">
<dt id="c.PySequenceMethods.sq_concat">
binaryfunc <code class="descname">PySequenceMethods.sq_concat</code><a class="headerlink" href="#c.PySequenceMethods.sq_concat" title="Permalink to this definition">¶</a></dt>
<dd><p>This function is used by <a class="reference internal" href="sequence.html#c.PySequence_Concat" title="PySequence_Concat"><code class="xref c c-func docutils literal notranslate"><span class="pre">PySequence_Concat()</span></code></a> and has the same
signature. It is also used by the <code class="docutils literal notranslate"><span class="pre">+</span></code> operator, after trying the numeric
addition via the <code class="xref c c-member docutils literal notranslate"><span class="pre">nb_add</span></code> slot.</p>
</dd></dl>
<dl class="member">
<dt id="c.PySequenceMethods.sq_repeat">
ssizeargfunc <code class="descname">PySequenceMethods.sq_repeat</code><a class="headerlink" href="#c.PySequenceMethods.sq_repeat" title="Permalink to this definition">¶</a></dt>
<dd><p>This function is used by <a class="reference internal" href="sequence.html#c.PySequence_Repeat" title="PySequence_Repeat"><code class="xref c c-func docutils literal notranslate"><span class="pre">PySequence_Repeat()</span></code></a> and has the same
signature. It is also used by the <code class="docutils literal notranslate"><span class="pre">*</span></code> operator, after trying numeric
multiplication via the <code class="xref c c-member docutils literal notranslate"><span class="pre">nb_multiply</span></code>
slot.</p>
</dd></dl>
<dl class="member">
<dt id="c.PySequenceMethods.sq_item">
ssizeargfunc <code class="descname">PySequenceMethods.sq_item</code><a class="headerlink" href="#c.PySequenceMethods.sq_item" title="Permalink to this definition">¶</a></dt>
<dd><p>This function is used by <a class="reference internal" href="sequence.html#c.PySequence_GetItem" title="PySequence_GetItem"><code class="xref c c-func docutils literal notranslate"><span class="pre">PySequence_GetItem()</span></code></a> and has the same
signature. This slot must be filled for the <a class="reference internal" href="sequence.html#c.PySequence_Check" title="PySequence_Check"><code class="xref c c-func docutils literal notranslate"><span class="pre">PySequence_Check()</span></code></a>
function to return <code class="docutils literal notranslate"><span class="pre">1</span></code>, it can be <em>NULL</em> otherwise.</p>
<p>Negative indexes are handled as follows: if the <code class="xref py py-attr docutils literal notranslate"><span class="pre">sq_length</span></code> slot is
filled, it is called and the sequence length is used to compute a positive
index which is passed to <code class="xref py py-attr docutils literal notranslate"><span class="pre">sq_item</span></code>. If <code class="xref py py-attr docutils literal notranslate"><span class="pre">sq_length</span></code> is <em>NULL</em>,
the index is passed as is to the function.</p>
</dd></dl>
<dl class="member">
<dt id="c.PySequenceMethods.sq_ass_item">
ssizeobjargproc <code class="descname">PySequenceMethods.sq_ass_item</code><a class="headerlink" href="#c.PySequenceMethods.sq_ass_item" title="Permalink to this definition">¶</a></dt>
<dd><p>This function is used by <a class="reference internal" href="sequence.html#c.PySequence_SetItem" title="PySequence_SetItem"><code class="xref c c-func docutils literal notranslate"><span class="pre">PySequence_SetItem()</span></code></a> and has the same
signature. This slot may be left to <em>NULL</em> if the object does not support
item assignment and deletion.</p>
</dd></dl>
<dl class="member">
<dt id="c.PySequenceMethods.sq_contains">
objobjproc <code class="descname">PySequenceMethods.sq_contains</code><a class="headerlink" href="#c.PySequenceMethods.sq_contains" title="Permalink to this definition">¶</a></dt>
<dd><p>This function may be used by <a class="reference internal" href="sequence.html#c.PySequence_Contains" title="PySequence_Contains"><code class="xref c c-func docutils literal notranslate"><span class="pre">PySequence_Contains()</span></code></a> and has the same
signature. This slot may be left to <em>NULL</em>, in this case
<a class="reference internal" href="sequence.html#c.PySequence_Contains" title="PySequence_Contains"><code class="xref c c-func docutils literal notranslate"><span class="pre">PySequence_Contains()</span></code></a> simply traverses the sequence until it finds a
match.</p>
</dd></dl>
<dl class="member">
<dt id="c.PySequenceMethods.sq_inplace_concat">
binaryfunc <code class="descname">PySequenceMethods.sq_inplace_concat</code><a class="headerlink" href="#c.PySequenceMethods.sq_inplace_concat" title="Permalink to this definition">¶</a></dt>
<dd><p>This function is used by <a class="reference internal" href="sequence.html#c.PySequence_InPlaceConcat" title="PySequence_InPlaceConcat"><code class="xref c c-func docutils literal notranslate"><span class="pre">PySequence_InPlaceConcat()</span></code></a> and has the same
signature. It should modify its first operand, and return it.</p>
</dd></dl>
<dl class="member">
<dt id="c.PySequenceMethods.sq_inplace_repeat">
ssizeargfunc <code class="descname">PySequenceMethods.sq_inplace_repeat</code><a class="headerlink" href="#c.PySequenceMethods.sq_inplace_repeat" title="Permalink to this definition">¶</a></dt>
<dd><p>This function is used by <a class="reference internal" href="sequence.html#c.PySequence_InPlaceRepeat" title="PySequence_InPlaceRepeat"><code class="xref c c-func docutils literal notranslate"><span class="pre">PySequence_InPlaceRepeat()</span></code></a> and has the same
signature. It should modify its first operand, and return it.</p>
</dd></dl>
</div>
<div class="section" id="buffer-object-structures">
<span id="buffer-structs"></span><h1>Buffer Object Structures<a class="headerlink" href="#buffer-object-structures" title="Permalink to this headline">¶</a></h1>
<p>The buffer interface exports a model where an object can expose its internal
data as a set of chunks of data, where each chunk is specified as a
pointer/length pair. These chunks are called <em class="dfn">segments</em> and are presumed
to be non-contiguous in memory.</p>
<p>If an object does not export the buffer interface, then its <a class="reference internal" href="#c.PyTypeObject.tp_as_buffer" title="PyTypeObject.tp_as_buffer"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_as_buffer</span></code></a>
member in the <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyTypeObject</span></code></a> structure should be <em>NULL</em>. Otherwise, the
<a class="reference internal" href="#c.PyTypeObject.tp_as_buffer" title="PyTypeObject.tp_as_buffer"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_as_buffer</span></code></a> will point to a <a class="reference internal" href="#c.PyBufferProcs" title="PyBufferProcs"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyBufferProcs</span></code></a> structure.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">It is very important that your <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyTypeObject</span></code></a> structure uses
<a class="reference internal" href="#Py_TPFLAGS_DEFAULT" title="Py_TPFLAGS_DEFAULT"><code class="xref py py-const docutils literal notranslate"><span class="pre">Py_TPFLAGS_DEFAULT</span></code></a> for the value of the <a class="reference internal" href="#c.PyTypeObject.tp_flags" title="PyTypeObject.tp_flags"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_flags</span></code></a> member rather
than <code class="docutils literal notranslate"><span class="pre">0</span></code>. This tells the Python runtime that your <a class="reference internal" href="#c.PyBufferProcs" title="PyBufferProcs"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyBufferProcs</span></code></a>
structure contains the <code class="xref py py-attr docutils literal notranslate"><span class="pre">bf_getcharbuffer</span></code> slot. Older versions of Python
did not have this member, so a new Python interpreter using an old extension
needs to be able to test for its presence before using it.</p>
</div>
<dl class="type">
<dt id="c.PyBufferProcs">
<code class="descname">PyBufferProcs</code><a class="headerlink" href="#c.PyBufferProcs" title="Permalink to this definition">¶</a></dt>
<dd><p>Structure used to hold the function pointers which define an implementation of
the buffer protocol.</p>
<p>The first slot is <code class="xref py py-attr docutils literal notranslate"><span class="pre">bf_getreadbuffer</span></code>, of type <a class="reference internal" href="#c.readbufferproc" title="readbufferproc"><code class="xref c c-type docutils literal notranslate"><span class="pre">readbufferproc</span></code></a>.
If this slot is <em>NULL</em>, then the object does not support reading from the
internal data. This is non-sensical, so implementors should fill this in, but
callers should test that the slot contains a non-<em>NULL</em> value.</p>
<p>The next slot is <code class="xref py py-attr docutils literal notranslate"><span class="pre">bf_getwritebuffer</span></code> having type
<a class="reference internal" href="#c.writebufferproc" title="writebufferproc"><code class="xref c c-type docutils literal notranslate"><span class="pre">writebufferproc</span></code></a>. This slot may be <em>NULL</em> if the object does not
allow writing into its returned buffers.</p>
<p>The third slot is <code class="xref py py-attr docutils literal notranslate"><span class="pre">bf_getsegcount</span></code>, with type <a class="reference internal" href="#c.segcountproc" title="segcountproc"><code class="xref c c-type docutils literal notranslate"><span class="pre">segcountproc</span></code></a>.
This slot must not be <em>NULL</em> and is used to inform the caller how many segments
the object contains. Simple objects such as <a class="reference internal" href="string.html#c.PyString_Type" title="PyString_Type"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyString_Type</span></code></a> and
<a class="reference internal" href="buffer.html#c.PyBuffer_Type" title="PyBuffer_Type"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyBuffer_Type</span></code></a> objects contain a single segment.</p>
<p id="index-4">The last slot is <code class="xref py py-attr docutils literal notranslate"><span class="pre">bf_getcharbuffer</span></code>, of type <a class="reference internal" href="#c.charbufferproc" title="charbufferproc"><code class="xref c c-type docutils literal notranslate"><span class="pre">charbufferproc</span></code></a>.
This slot will only be present if the <a class="reference internal" href="#Py_TPFLAGS_HAVE_GETCHARBUFFER" title="Py_TPFLAGS_HAVE_GETCHARBUFFER"><code class="xref py py-const docutils literal notranslate"><span class="pre">Py_TPFLAGS_HAVE_GETCHARBUFFER</span></code></a>
flag is present in the <a class="reference internal" href="#c.PyTypeObject.tp_flags" title="PyTypeObject.tp_flags"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_flags</span></code></a> field of the object’s
<a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyTypeObject</span></code></a>. Before using this slot, the caller should test whether it
is present by using the <a class="reference internal" href="type.html#c.PyType_HasFeature" title="PyType_HasFeature"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyType_HasFeature()</span></code></a> function. If the flag is
present, <code class="xref py py-attr docutils literal notranslate"><span class="pre">bf_getcharbuffer</span></code> may be <em>NULL</em>, indicating that the object’s
contents cannot be used as <em>8-bit characters</em>. The slot function may also raise
an error if the object’s contents cannot be interpreted as 8-bit characters.
For example, if the object is an array which is configured to hold floating
point values, an exception may be raised if a caller attempts to use
<code class="xref py py-attr docutils literal notranslate"><span class="pre">bf_getcharbuffer</span></code> to fetch a sequence of 8-bit characters. This notion of
exporting the internal buffers as “text” is used to distinguish between objects
that are binary in nature, and those which have character-based content.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The current policy seems to state that these characters may be multi-byte
characters. This implies that a buffer size of <em>N</em> does not mean there are <em>N</em>
characters present.</p>
</div>
</dd></dl>
<dl class="data">
<dt>
<code class="descname">Py_TPFLAGS_HAVE_GETCHARBUFFER</code></dt>
<dd><p>Flag bit set in the type structure to indicate that the <code class="xref py py-attr docutils literal notranslate"><span class="pre">bf_getcharbuffer</span></code>
slot is known. This being set does not indicate that the object supports the
buffer interface or that the <code class="xref py py-attr docutils literal notranslate"><span class="pre">bf_getcharbuffer</span></code> slot is non-<em>NULL</em>.</p>
</dd></dl>
<dl class="type">
<dt id="c.readbufferproc">
Py_ssize_t <code class="descname">(*readbufferproc)</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *self</em>, Py_ssize_t<em> segment</em>, void<em> **ptrptr</em><span class="sig-paren">)</span><a class="headerlink" href="#c.readbufferproc" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a pointer to a readable segment of the buffer in <code class="docutils literal notranslate"><span class="pre">*ptrptr</span></code>. This
function is allowed to raise an exception, in which case it must return <code class="docutils literal notranslate"><span class="pre">-1</span></code>.
The <em>segment</em> which is specified must be zero or positive, and strictly less
than the number of segments returned by the <code class="xref py py-attr docutils literal notranslate"><span class="pre">bf_getsegcount</span></code> slot
function. On success, it returns the length of the segment, and sets
<code class="docutils literal notranslate"><span class="pre">*ptrptr</span></code> to a pointer to that memory.</p>
</dd></dl>
<dl class="type">
<dt id="c.writebufferproc">
Py_ssize_t <code class="descname">(*writebufferproc)</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *self</em>, Py_ssize_t<em> segment</em>, void<em> **ptrptr</em><span class="sig-paren">)</span><a class="headerlink" href="#c.writebufferproc" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a pointer to a writable memory buffer in <code class="docutils literal notranslate"><span class="pre">*ptrptr</span></code>, and the length of
that segment as the function return value. The memory buffer must correspond to
buffer segment <em>segment</em>. Must return <code class="docutils literal notranslate"><span class="pre">-1</span></code> and set an exception on error.
<a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> should be raised if the object only supports read-only buffers,
and <a class="reference internal" href="../library/exceptions.html#exceptions.SystemError" title="exceptions.SystemError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SystemError</span></code></a> should be raised when <em>segment</em> specifies a segment that
doesn’t exist.</p>
</dd></dl>
<dl class="type">
<dt id="c.segcountproc">
Py_ssize_t <code class="descname">(*segcountproc)</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *self</em>, Py_ssize_t<em> *lenp</em><span class="sig-paren">)</span><a class="headerlink" href="#c.segcountproc" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the number of memory segments which comprise the buffer. If <em>lenp</em> is
not <em>NULL</em>, the implementation must report the sum of the sizes (in bytes) of
all segments in <code class="docutils literal notranslate"><span class="pre">*lenp</span></code>. The function cannot fail.</p>
</dd></dl>
<dl class="type">
<dt id="c.charbufferproc">
Py_ssize_t <code class="descname">(*charbufferproc)</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *self</em>, Py_ssize_t<em> segment</em>, char<em> **ptrptr</em><span class="sig-paren">)</span><a class="headerlink" href="#c.charbufferproc" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the size of the segment <em>segment</em> that <em>ptrptr</em> is set to. <code class="docutils literal notranslate"><span class="pre">*ptrptr</span></code>
is set to the memory buffer. Returns <code class="docutils literal notranslate"><span class="pre">-1</span></code> on error.</p>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Type Objects</a></li>
<li><a class="reference internal" href="#number-object-structures">Number Object Structures</a></li>
<li><a class="reference internal" href="#mapping-object-structures">Mapping Object Structures</a></li>
<li><a class="reference internal" href="#sequence-object-structures">Sequence Object Structures</a></li>
<li><a class="reference internal" href="#buffer-object-structures">Buffer Object Structures</a></li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="structures.html"
title="previous chapter">Common Object Structures</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="gcsupport.html"
title="next chapter">Supporting Cyclic Garbage Collection</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/typeobj.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="gcsupport.html" title="Supporting Cyclic Garbage Collection"
>next</a> |</li>
<li class="right" >
<a href="structures.html" title="Common Object Structures"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="objimpl.html" >Object Implementation Support</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\)�i�i� i� html/c-api/unicode.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Unicode Objects and Codecs — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Buffers and Memoryview Objects" href="buffer.html" />
<link rel="prev" title="String/Bytes Objects" href="string.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/unicode.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="buffer.html" title="Buffers and Memoryview Objects"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="string.html" title="String/Bytes Objects"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" accesskey="U">Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="unicode-objects-and-codecs">
<span id="unicodeobjects"></span><h1>Unicode Objects and Codecs<a class="headerlink" href="#unicode-objects-and-codecs" title="Permalink to this headline">¶</a></h1>
<div class="section" id="unicode-objects">
<h2>Unicode Objects<a class="headerlink" href="#unicode-objects" title="Permalink to this headline">¶</a></h2>
<div class="section" id="unicode-type">
<h3>Unicode Type<a class="headerlink" href="#unicode-type" title="Permalink to this headline">¶</a></h3>
<p>These are the basic Unicode object types used for the Unicode implementation in
Python:</p>
<dl class="type">
<dt id="c.Py_UNICODE">
<code class="descname">Py_UNICODE</code><a class="headerlink" href="#c.Py_UNICODE" title="Permalink to this definition">¶</a></dt>
<dd><p>This type represents the storage type which is used by Python internally as
basis for holding Unicode ordinals. Python’s default builds use a 16-bit type
for <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_UNICODE</span></code></a> and store Unicode values internally as UCS2. It is also
possible to build a UCS4 version of Python (most recent Linux distributions come
with UCS4 builds of Python). These builds then use a 32-bit type for
<a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_UNICODE</span></code></a> and store Unicode data internally as UCS4. On platforms
where <code class="xref c c-type docutils literal notranslate"><span class="pre">wchar_t</span></code> is available and compatible with the chosen Python
Unicode build variant, <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_UNICODE</span></code></a> is a typedef alias for
<code class="xref c c-type docutils literal notranslate"><span class="pre">wchar_t</span></code> to enhance native platform compatibility. On all other
platforms, <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_UNICODE</span></code></a> is a typedef alias for either <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span>
<span class="pre">short</span></code> (UCS2) or <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">long</span></code> (UCS4).</p>
</dd></dl>
<p>Note that UCS2 and UCS4 Python builds are not binary compatible. Please keep
this in mind when writing extensions or interfaces.</p>
<dl class="type">
<dt id="c.PyUnicodeObject">
<code class="descname">PyUnicodeObject</code><a class="headerlink" href="#c.PyUnicodeObject" title="Permalink to this definition">¶</a></dt>
<dd><p>This subtype of <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject</span></code></a> represents a Python Unicode object.</p>
</dd></dl>
<dl class="var">
<dt id="c.PyUnicode_Type">
<a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a> <code class="descname">PyUnicode_Type</code><a class="headerlink" href="#c.PyUnicode_Type" title="Permalink to this definition">¶</a></dt>
<dd><p>This instance of <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyTypeObject</span></code></a> represents the Python Unicode type. It
is exposed to Python code as <code class="docutils literal notranslate"><span class="pre">unicode</span></code> and <code class="docutils literal notranslate"><span class="pre">types.UnicodeType</span></code>.</p>
</dd></dl>
<p>The following APIs are really C macros and can be used to do fast checks and to
access internal read-only data of Unicode objects:</p>
<dl class="function">
<dt id="c.PyUnicode_Check">
int <code class="descname">PyUnicode_Check</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_Check" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if the object <em>o</em> is a Unicode object or an instance of a Unicode
subtype.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.2: </span>Allowed subtypes to be accepted.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_CheckExact">
int <code class="descname">PyUnicode_CheckExact</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_CheckExact" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if the object <em>o</em> is a Unicode object, but not an instance of a
subtype.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_GET_SIZE">
Py_ssize_t <code class="descname">PyUnicode_GET_SIZE</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_GET_SIZE" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the size of the object. <em>o</em> has to be a <a class="reference internal" href="#c.PyUnicodeObject" title="PyUnicodeObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyUnicodeObject</span></code></a> (not
checked).</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function returned an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type. This might require changes
in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_GET_DATA_SIZE">
Py_ssize_t <code class="descname">PyUnicode_GET_DATA_SIZE</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_GET_DATA_SIZE" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the size of the object’s internal buffer in bytes. <em>o</em> has to be a
<a class="reference internal" href="#c.PyUnicodeObject" title="PyUnicodeObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyUnicodeObject</span></code></a> (not checked).</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function returned an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type. This might require changes
in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_AS_UNICODE">
<a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a>* <code class="descname">PyUnicode_AS_UNICODE</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_AS_UNICODE" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a pointer to the internal <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_UNICODE</span></code></a> buffer of the object. <em>o</em>
has to be a <a class="reference internal" href="#c.PyUnicodeObject" title="PyUnicodeObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyUnicodeObject</span></code></a> (not checked).</p>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_AS_DATA">
const char* <code class="descname">PyUnicode_AS_DATA</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_AS_DATA" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a pointer to the internal buffer of the object. <em>o</em> has to be a
<a class="reference internal" href="#c.PyUnicodeObject" title="PyUnicodeObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyUnicodeObject</span></code></a> (not checked).</p>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_ClearFreeList">
int <code class="descname">PyUnicode_ClearFreeList</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_ClearFreeList" title="Permalink to this definition">¶</a></dt>
<dd><p>Clear the free list. Return the total number of freed items.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
</dd></dl>
</div>
<div class="section" id="unicode-character-properties">
<h3>Unicode Character Properties<a class="headerlink" href="#unicode-character-properties" title="Permalink to this headline">¶</a></h3>
<p>Unicode provides many different character properties. The most often needed ones
are available through these macros which are mapped to C functions depending on
the Python configuration.</p>
<dl class="function">
<dt id="c.Py_UNICODE_ISSPACE">
int <code class="descname">Py_UNICODE_ISSPACE</code><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a><em> ch</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_UNICODE_ISSPACE" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">1</span></code> or <code class="docutils literal notranslate"><span class="pre">0</span></code> depending on whether <em>ch</em> is a whitespace character.</p>
</dd></dl>
<dl class="function">
<dt id="c.Py_UNICODE_ISLOWER">
int <code class="descname">Py_UNICODE_ISLOWER</code><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a><em> ch</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_UNICODE_ISLOWER" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">1</span></code> or <code class="docutils literal notranslate"><span class="pre">0</span></code> depending on whether <em>ch</em> is a lowercase character.</p>
</dd></dl>
<dl class="function">
<dt id="c.Py_UNICODE_ISUPPER">
int <code class="descname">Py_UNICODE_ISUPPER</code><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a><em> ch</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_UNICODE_ISUPPER" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">1</span></code> or <code class="docutils literal notranslate"><span class="pre">0</span></code> depending on whether <em>ch</em> is an uppercase character.</p>
</dd></dl>
<dl class="function">
<dt id="c.Py_UNICODE_ISTITLE">
int <code class="descname">Py_UNICODE_ISTITLE</code><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a><em> ch</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_UNICODE_ISTITLE" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">1</span></code> or <code class="docutils literal notranslate"><span class="pre">0</span></code> depending on whether <em>ch</em> is a titlecase character.</p>
</dd></dl>
<dl class="function">
<dt id="c.Py_UNICODE_ISLINEBREAK">
int <code class="descname">Py_UNICODE_ISLINEBREAK</code><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a><em> ch</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_UNICODE_ISLINEBREAK" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">1</span></code> or <code class="docutils literal notranslate"><span class="pre">0</span></code> depending on whether <em>ch</em> is a linebreak character.</p>
</dd></dl>
<dl class="function">
<dt id="c.Py_UNICODE_ISDECIMAL">
int <code class="descname">Py_UNICODE_ISDECIMAL</code><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a><em> ch</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_UNICODE_ISDECIMAL" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">1</span></code> or <code class="docutils literal notranslate"><span class="pre">0</span></code> depending on whether <em>ch</em> is a decimal character.</p>
</dd></dl>
<dl class="function">
<dt id="c.Py_UNICODE_ISDIGIT">
int <code class="descname">Py_UNICODE_ISDIGIT</code><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a><em> ch</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_UNICODE_ISDIGIT" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">1</span></code> or <code class="docutils literal notranslate"><span class="pre">0</span></code> depending on whether <em>ch</em> is a digit character.</p>
</dd></dl>
<dl class="function">
<dt id="c.Py_UNICODE_ISNUMERIC">
int <code class="descname">Py_UNICODE_ISNUMERIC</code><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a><em> ch</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_UNICODE_ISNUMERIC" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">1</span></code> or <code class="docutils literal notranslate"><span class="pre">0</span></code> depending on whether <em>ch</em> is a numeric character.</p>
</dd></dl>
<dl class="function">
<dt id="c.Py_UNICODE_ISALPHA">
int <code class="descname">Py_UNICODE_ISALPHA</code><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a><em> ch</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_UNICODE_ISALPHA" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">1</span></code> or <code class="docutils literal notranslate"><span class="pre">0</span></code> depending on whether <em>ch</em> is an alphabetic character.</p>
</dd></dl>
<dl class="function">
<dt id="c.Py_UNICODE_ISALNUM">
int <code class="descname">Py_UNICODE_ISALNUM</code><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a><em> ch</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_UNICODE_ISALNUM" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">1</span></code> or <code class="docutils literal notranslate"><span class="pre">0</span></code> depending on whether <em>ch</em> is an alphanumeric character.</p>
</dd></dl>
<p>These APIs can be used for fast direct character conversions:</p>
<dl class="function">
<dt id="c.Py_UNICODE_TOLOWER">
<a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a> <code class="descname">Py_UNICODE_TOLOWER</code><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a><em> ch</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_UNICODE_TOLOWER" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the character <em>ch</em> converted to lower case.</p>
</dd></dl>
<dl class="function">
<dt id="c.Py_UNICODE_TOUPPER">
<a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a> <code class="descname">Py_UNICODE_TOUPPER</code><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a><em> ch</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_UNICODE_TOUPPER" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the character <em>ch</em> converted to upper case.</p>
</dd></dl>
<dl class="function">
<dt id="c.Py_UNICODE_TOTITLE">
<a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a> <code class="descname">Py_UNICODE_TOTITLE</code><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a><em> ch</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_UNICODE_TOTITLE" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the character <em>ch</em> converted to title case.</p>
</dd></dl>
<dl class="function">
<dt id="c.Py_UNICODE_TODECIMAL">
int <code class="descname">Py_UNICODE_TODECIMAL</code><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a><em> ch</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_UNICODE_TODECIMAL" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the character <em>ch</em> converted to a decimal positive integer. Return
<code class="docutils literal notranslate"><span class="pre">-1</span></code> if this is not possible. This macro does not raise exceptions.</p>
</dd></dl>
<dl class="function">
<dt id="c.Py_UNICODE_TODIGIT">
int <code class="descname">Py_UNICODE_TODIGIT</code><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a><em> ch</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_UNICODE_TODIGIT" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the character <em>ch</em> converted to a single digit integer. Return <code class="docutils literal notranslate"><span class="pre">-1</span></code> if
this is not possible. This macro does not raise exceptions.</p>
</dd></dl>
<dl class="function">
<dt id="c.Py_UNICODE_TONUMERIC">
double <code class="descname">Py_UNICODE_TONUMERIC</code><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a><em> ch</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_UNICODE_TONUMERIC" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the character <em>ch</em> converted to a double. Return <code class="docutils literal notranslate"><span class="pre">-1.0</span></code> if this is not
possible. This macro does not raise exceptions.</p>
</dd></dl>
</div>
<div class="section" id="plain-py-unicode">
<h3>Plain Py_UNICODE<a class="headerlink" href="#plain-py-unicode" title="Permalink to this headline">¶</a></h3>
<p>To create Unicode objects and access their basic sequence properties, use these
APIs:</p>
<dl class="function">
<dt id="c.PyUnicode_FromUnicode">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_FromUnicode</code><span class="sig-paren">(</span>const <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a><em> *u</em>, Py_ssize_t<em> size</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_FromUnicode" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Create a Unicode object from the Py_UNICODE buffer <em>u</em> of the given size. <em>u</em>
may be <em>NULL</em> which causes the contents to be undefined. It is the user’s
responsibility to fill in the needed data. The buffer is copied into the new
object. If the buffer is not <em>NULL</em>, the return value might be a shared object.
Therefore, modification of the resulting Unicode object is only allowed when <em>u</em>
is <em>NULL</em>.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>size</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_FromStringAndSize">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_FromStringAndSize</code><span class="sig-paren">(</span>const char<em> *u</em>, Py_ssize_t<em> size</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_FromStringAndSize" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Create a Unicode object from the char buffer <em>u</em>. The bytes will be interpreted
as being UTF-8 encoded. <em>u</em> may also be <em>NULL</em> which
causes the contents to be undefined. It is the user’s responsibility to fill in
the needed data. The buffer is copied into the new object. If the buffer is not
<em>NULL</em>, the return value might be a shared object. Therefore, modification of
the resulting Unicode object is only allowed when <em>u</em> is <em>NULL</em>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_FromString">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *<code class="descname">PyUnicode_FromString</code><span class="sig-paren">(</span>const char<em> *u</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_FromString" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Create a Unicode object from a UTF-8 encoded null-terminated char buffer
<em>u</em>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_FromFormat">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_FromFormat</code><span class="sig-paren">(</span>const char<em> *format</em>, ...<span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_FromFormat" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Take a C <code class="xref c c-func docutils literal notranslate"><span class="pre">printf()</span></code>-style <em>format</em> string and a variable number of
arguments, calculate the size of the resulting Python unicode string and return
a string with the values formatted into it. The variable arguments must be C
types and must correspond exactly to the format characters in the <em>format</em>
string. The following format characters are allowed:</p>
<table border="1" class="docutils">
<colgroup>
<col width="26%" />
<col width="29%" />
<col width="44%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Format Characters</th>
<th class="head">Type</th>
<th class="head">Comment</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="xref py py-attr docutils literal notranslate"><span class="pre">%%</span></code></td>
<td><em>n/a</em></td>
<td>The literal % character.</td>
</tr>
<tr class="row-odd"><td><code class="xref py py-attr docutils literal notranslate"><span class="pre">%c</span></code></td>
<td>int</td>
<td>A single character,
represented as a C int.</td>
</tr>
<tr class="row-even"><td><code class="xref py py-attr docutils literal notranslate"><span class="pre">%d</span></code></td>
<td>int</td>
<td>Exactly equivalent to
<code class="docutils literal notranslate"><span class="pre">printf("%d")</span></code>.</td>
</tr>
<tr class="row-odd"><td><code class="xref py py-attr docutils literal notranslate"><span class="pre">%u</span></code></td>
<td>unsigned int</td>
<td>Exactly equivalent to
<code class="docutils literal notranslate"><span class="pre">printf("%u")</span></code>.</td>
</tr>
<tr class="row-even"><td><code class="xref py py-attr docutils literal notranslate"><span class="pre">%ld</span></code></td>
<td>long</td>
<td>Exactly equivalent to
<code class="docutils literal notranslate"><span class="pre">printf("%ld")</span></code>.</td>
</tr>
<tr class="row-odd"><td><code class="xref py py-attr docutils literal notranslate"><span class="pre">%lu</span></code></td>
<td>unsigned long</td>
<td>Exactly equivalent to
<code class="docutils literal notranslate"><span class="pre">printf("%lu")</span></code>.</td>
</tr>
<tr class="row-even"><td><code class="xref py py-attr docutils literal notranslate"><span class="pre">%zd</span></code></td>
<td>Py_ssize_t</td>
<td>Exactly equivalent to
<code class="docutils literal notranslate"><span class="pre">printf("%zd")</span></code>.</td>
</tr>
<tr class="row-odd"><td><code class="xref py py-attr docutils literal notranslate"><span class="pre">%zu</span></code></td>
<td>size_t</td>
<td>Exactly equivalent to
<code class="docutils literal notranslate"><span class="pre">printf("%zu")</span></code>.</td>
</tr>
<tr class="row-even"><td><code class="xref py py-attr docutils literal notranslate"><span class="pre">%i</span></code></td>
<td>int</td>
<td>Exactly equivalent to
<code class="docutils literal notranslate"><span class="pre">printf("%i")</span></code>.</td>
</tr>
<tr class="row-odd"><td><code class="xref py py-attr docutils literal notranslate"><span class="pre">%x</span></code></td>
<td>int</td>
<td>Exactly equivalent to
<code class="docutils literal notranslate"><span class="pre">printf("%x")</span></code>.</td>
</tr>
<tr class="row-even"><td><code class="xref py py-attr docutils literal notranslate"><span class="pre">%s</span></code></td>
<td>char*</td>
<td>A null-terminated C character
array.</td>
</tr>
<tr class="row-odd"><td><code class="xref py py-attr docutils literal notranslate"><span class="pre">%p</span></code></td>
<td>void*</td>
<td>The hex representation of a C
pointer. Mostly equivalent to
<code class="docutils literal notranslate"><span class="pre">printf("%p")</span></code> except that
it is guaranteed to start with
the literal <code class="docutils literal notranslate"><span class="pre">0x</span></code> regardless
of what the platform’s
<code class="docutils literal notranslate"><span class="pre">printf</span></code> yields.</td>
</tr>
<tr class="row-even"><td><code class="xref py py-attr docutils literal notranslate"><span class="pre">%U</span></code></td>
<td>PyObject*</td>
<td>A unicode object.</td>
</tr>
<tr class="row-odd"><td><code class="xref py py-attr docutils literal notranslate"><span class="pre">%V</span></code></td>
<td>PyObject*, char *</td>
<td>A unicode object (which may be
<em>NULL</em>) and a null-terminated
C character array as a second
parameter (which will be used,
if the first parameter is
<em>NULL</em>).</td>
</tr>
<tr class="row-even"><td><code class="xref py py-attr docutils literal notranslate"><span class="pre">%S</span></code></td>
<td>PyObject*</td>
<td>The result of calling
<code class="xref py py-func docutils literal notranslate"><span class="pre">PyObject_Unicode()</span></code>.</td>
</tr>
<tr class="row-odd"><td><code class="xref py py-attr docutils literal notranslate"><span class="pre">%R</span></code></td>
<td>PyObject*</td>
<td>The result of calling
<code class="xref py py-func docutils literal notranslate"><span class="pre">PyObject_Repr()</span></code>.</td>
</tr>
</tbody>
</table>
<p>An unrecognized format character causes all the rest of the format string to be
copied as-is to the result string, and any extra arguments discarded.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_FromFormatV">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_FromFormatV</code><span class="sig-paren">(</span>const char<em> *format</em>, va_list<em> vargs</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_FromFormatV" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Identical to <code class="xref py py-func docutils literal notranslate"><span class="pre">PyUnicode_FromFormat()</span></code> except that it takes exactly two
arguments.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_AsUnicode">
<a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a>* <code class="descname">PyUnicode_AsUnicode</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *unicode</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_AsUnicode" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a read-only pointer to the Unicode object’s internal
<a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_UNICODE</span></code></a> buffer, <em>NULL</em> if <em>unicode</em> is not a Unicode object.
Note that the resulting <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_UNICODE*</span></code></a> string may contain embedded
null characters, which would cause the string to be truncated when used in
most C functions.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_GetSize">
Py_ssize_t <code class="descname">PyUnicode_GetSize</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *unicode</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_GetSize" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the length of the Unicode object.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function returned an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type. This might require changes
in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_FromEncodedObject">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_FromEncodedObject</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *obj</em>, const char<em> *encoding</em>, const char<em> *errors</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_FromEncodedObject" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Coerce an encoded object <em>obj</em> to a Unicode object and return a reference with
incremented refcount.</p>
<p>String and other char buffer compatible objects are decoded according to the
given encoding and using the error handling defined by errors. Both can be
<em>NULL</em> to have the interface use the default values (see the next section for
details).</p>
<p>All other objects, including Unicode objects, cause a <a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> to be
set.</p>
<p>The API returns <em>NULL</em> if there was an error. The caller is responsible for
decref’ing the returned objects.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_FromObject">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_FromObject</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *obj</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_FromObject" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Shortcut for <code class="docutils literal notranslate"><span class="pre">PyUnicode_FromEncodedObject(obj,</span> <span class="pre">NULL,</span> <span class="pre">"strict")</span></code> which is used
throughout the interpreter whenever coercion to Unicode is needed.</p>
</dd></dl>
<p>If the platform supports <code class="xref c c-type docutils literal notranslate"><span class="pre">wchar_t</span></code> and provides a header file wchar.h,
Python can interface directly to this type using the following functions.
Support is optimized if Python’s own <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_UNICODE</span></code></a> type is identical to
the system’s <code class="xref c c-type docutils literal notranslate"><span class="pre">wchar_t</span></code>.</p>
</div>
<div class="section" id="wchar-t-support">
<h3>wchar_t Support<a class="headerlink" href="#wchar-t-support" title="Permalink to this headline">¶</a></h3>
<p><code class="xref c c-type docutils literal notranslate"><span class="pre">wchar_t</span></code> support for platforms which support it:</p>
<dl class="function">
<dt id="c.PyUnicode_FromWideChar">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_FromWideChar</code><span class="sig-paren">(</span>const wchar_t<em> *w</em>, Py_ssize_t<em> size</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_FromWideChar" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Create a Unicode object from the <code class="xref c c-type docutils literal notranslate"><span class="pre">wchar_t</span></code> buffer <em>w</em> of the given <em>size</em>.
Return <em>NULL</em> on failure.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>size</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_AsWideChar">
Py_ssize_t <code class="descname">PyUnicode_AsWideChar</code><span class="sig-paren">(</span><a class="reference internal" href="#c.PyUnicodeObject" title="PyUnicodeObject">PyUnicodeObject</a><em> *unicode</em>, wchar_t<em> *w</em>, Py_ssize_t<em> size</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_AsWideChar" title="Permalink to this definition">¶</a></dt>
<dd><p>Copy the Unicode object contents into the <code class="xref c c-type docutils literal notranslate"><span class="pre">wchar_t</span></code> buffer <em>w</em>. At most
<em>size</em> <code class="xref c c-type docutils literal notranslate"><span class="pre">wchar_t</span></code> characters are copied (excluding a possibly trailing
0-termination character). Return the number of <code class="xref c c-type docutils literal notranslate"><span class="pre">wchar_t</span></code> characters
copied or <code class="docutils literal notranslate"><span class="pre">-1</span></code> in case of an error. Note that the resulting <code class="xref c c-type docutils literal notranslate"><span class="pre">wchar_t</span></code>
string may or may not be 0-terminated. It is the responsibility of the caller
to make sure that the <code class="xref c c-type docutils literal notranslate"><span class="pre">wchar_t</span></code> string is 0-terminated in case this is
required by the application. Also, note that the <code class="xref c c-type docutils literal notranslate"><span class="pre">wchar_t*</span></code> string
might contain null characters, which would cause the string to be truncated
when used with most C functions.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function returned an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type and used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code>
type for <em>size</em>. This might require changes in your code for properly
supporting 64-bit systems.</p>
</div>
</dd></dl>
</div>
</div>
<div class="section" id="built-in-codecs">
<span id="builtincodecs"></span><h2>Built-in Codecs<a class="headerlink" href="#built-in-codecs" title="Permalink to this headline">¶</a></h2>
<p>Python provides a set of built-in codecs which are written in C for speed. All of
these codecs are directly usable via the following functions.</p>
<p>Many of the following APIs take two arguments encoding and errors, and they
have the same semantics as the ones of the built-in <a class="reference internal" href="../library/functions.html#unicode" title="unicode"><code class="xref py py-func docutils literal notranslate"><span class="pre">unicode()</span></code></a> Unicode
object constructor.</p>
<p>Setting encoding to <em>NULL</em> causes the default encoding to be used which is
ASCII. The file system calls should use <code class="xref c c-data docutils literal notranslate"><span class="pre">Py_FileSystemDefaultEncoding</span></code>
as the encoding for file names. This variable should be treated as read-only: on
some systems, it will be a pointer to a static string, on others, it will change
at run-time (such as when the application invokes setlocale).</p>
<p>Error handling is set by errors which may also be set to <em>NULL</em> meaning to use
the default handling defined for the codec. Default error handling for all
built-in codecs is “strict” (<a class="reference internal" href="../library/exceptions.html#exceptions.ValueError" title="exceptions.ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> is raised).</p>
<p>The codecs all use a similar interface. Only deviation from the following
generic ones are documented for simplicity.</p>
<div class="section" id="generic-codecs">
<h3>Generic Codecs<a class="headerlink" href="#generic-codecs" title="Permalink to this headline">¶</a></h3>
<p>These are the generic codec APIs:</p>
<dl class="function">
<dt id="c.PyUnicode_Decode">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_Decode</code><span class="sig-paren">(</span>const char<em> *s</em>, Py_ssize_t<em> size</em>, const char<em> *encoding</em>, const char<em> *errors</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_Decode" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Create a Unicode object by decoding <em>size</em> bytes of the encoded string <em>s</em>.
<em>encoding</em> and <em>errors</em> have the same meaning as the parameters of the same name
in the <a class="reference internal" href="../library/functions.html#unicode" title="unicode"><code class="xref py py-func docutils literal notranslate"><span class="pre">unicode()</span></code></a> built-in function. The codec to be used is looked up
using the Python codec registry. Return <em>NULL</em> if an exception was raised by
the codec.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>size</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_Encode">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_Encode</code><span class="sig-paren">(</span>const <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a><em> *s</em>, Py_ssize_t<em> size</em>, const char<em> *encoding</em>, const char<em> *errors</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_Encode" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Encode the <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_UNICODE</span></code></a> buffer <em>s</em> of the given <em>size</em> and return a Python
string object. <em>encoding</em> and <em>errors</em> have the same meaning as the parameters
of the same name in the Unicode <code class="xref py py-meth docutils literal notranslate"><span class="pre">encode()</span></code> method. The codec
to be used is looked up using the Python codec registry. Return <em>NULL</em> if
an exception was raised by the codec.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>size</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_AsEncodedString">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_AsEncodedString</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *unicode</em>, const char<em> *encoding</em>, const char<em> *errors</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_AsEncodedString" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Encode a Unicode object and return the result as Python string object.
<em>encoding</em> and <em>errors</em> have the same meaning as the parameters of the same name
in the Unicode <code class="xref py py-meth docutils literal notranslate"><span class="pre">encode()</span></code> method. The codec to be used is looked up using
the Python codec registry. Return <em>NULL</em> if an exception was raised by the
codec.</p>
</dd></dl>
</div>
<div class="section" id="utf-8-codecs">
<h3>UTF-8 Codecs<a class="headerlink" href="#utf-8-codecs" title="Permalink to this headline">¶</a></h3>
<p>These are the UTF-8 codec APIs:</p>
<dl class="function">
<dt id="c.PyUnicode_DecodeUTF8">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_DecodeUTF8</code><span class="sig-paren">(</span>const char<em> *s</em>, Py_ssize_t<em> size</em>, const char<em> *errors</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_DecodeUTF8" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Create a Unicode object by decoding <em>size</em> bytes of the UTF-8 encoded string
<em>s</em>. Return <em>NULL</em> if an exception was raised by the codec.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>size</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_DecodeUTF8Stateful">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_DecodeUTF8Stateful</code><span class="sig-paren">(</span>const char<em> *s</em>, Py_ssize_t<em> size</em>, const char<em> *errors</em>, Py_ssize_t<em> *consumed</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_DecodeUTF8Stateful" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>If <em>consumed</em> is <em>NULL</em>, behave like <a class="reference internal" href="#c.PyUnicode_DecodeUTF8" title="PyUnicode_DecodeUTF8"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_DecodeUTF8()</span></code></a>. If
<em>consumed</em> is not <em>NULL</em>, trailing incomplete UTF-8 byte sequences will not be
treated as an error. Those bytes will not be decoded and the number of bytes
that have been decoded will be stored in <em>consumed</em>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>size</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_EncodeUTF8">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_EncodeUTF8</code><span class="sig-paren">(</span>const <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a><em> *s</em>, Py_ssize_t<em> size</em>, const char<em> *errors</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_EncodeUTF8" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Encode the <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_UNICODE</span></code></a> buffer <em>s</em> of the given <em>size</em> using UTF-8 and return a
Python string object. Return <em>NULL</em> if an exception was raised by the codec.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>size</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_AsUTF8String">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_AsUTF8String</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *unicode</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_AsUTF8String" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Encode a Unicode object using UTF-8 and return the result as Python string
object. Error handling is “strict”. Return <em>NULL</em> if an exception was raised
by the codec.</p>
</dd></dl>
</div>
<div class="section" id="utf-32-codecs">
<h3>UTF-32 Codecs<a class="headerlink" href="#utf-32-codecs" title="Permalink to this headline">¶</a></h3>
<p>These are the UTF-32 codec APIs:</p>
<dl class="function">
<dt id="c.PyUnicode_DecodeUTF32">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_DecodeUTF32</code><span class="sig-paren">(</span>const char<em> *s</em>, Py_ssize_t<em> size</em>, const char<em> *errors</em>, int<em> *byteorder</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_DecodeUTF32" title="Permalink to this definition">¶</a></dt>
<dd><p>Decode <em>size</em> bytes from a UTF-32 encoded buffer string and return the
corresponding Unicode object. <em>errors</em> (if non-<em>NULL</em>) defines the error
handling. It defaults to “strict”.</p>
<p>If <em>byteorder</em> is non-<em>NULL</em>, the decoder starts decoding using the given byte
order:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="o">*</span><span class="n">byteorder</span> <span class="o">==</span> <span class="o">-</span><span class="mi">1</span><span class="o">:</span> <span class="n">little</span> <span class="n">endian</span>
<span class="o">*</span><span class="n">byteorder</span> <span class="o">==</span> <span class="mi">0</span><span class="o">:</span> <span class="n">native</span> <span class="n">order</span>
<span class="o">*</span><span class="n">byteorder</span> <span class="o">==</span> <span class="mi">1</span><span class="o">:</span> <span class="n">big</span> <span class="n">endian</span>
</pre></div>
</div>
<p>If <code class="docutils literal notranslate"><span class="pre">*byteorder</span></code> is zero, and the first four bytes of the input data are a
byte order mark (BOM), the decoder switches to this byte order and the BOM is
not copied into the resulting Unicode string. If <code class="docutils literal notranslate"><span class="pre">*byteorder</span></code> is <code class="docutils literal notranslate"><span class="pre">-1</span></code> or
<code class="docutils literal notranslate"><span class="pre">1</span></code>, any byte order mark is copied to the output.</p>
<p>After completion, <em>*byteorder</em> is set to the current byte order at the end
of input data.</p>
<p>In a narrow build code points outside the BMP will be decoded as surrogate pairs.</p>
<p>If <em>byteorder</em> is <em>NULL</em>, the codec starts in native order mode.</p>
<p>Return <em>NULL</em> if an exception was raised by the codec.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_DecodeUTF32Stateful">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_DecodeUTF32Stateful</code><span class="sig-paren">(</span>const char<em> *s</em>, Py_ssize_t<em> size</em>, const char<em> *errors</em>, int<em> *byteorder</em>, Py_ssize_t<em> *consumed</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_DecodeUTF32Stateful" title="Permalink to this definition">¶</a></dt>
<dd><p>If <em>consumed</em> is <em>NULL</em>, behave like <a class="reference internal" href="#c.PyUnicode_DecodeUTF32" title="PyUnicode_DecodeUTF32"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_DecodeUTF32()</span></code></a>. If
<em>consumed</em> is not <em>NULL</em>, <a class="reference internal" href="#c.PyUnicode_DecodeUTF32Stateful" title="PyUnicode_DecodeUTF32Stateful"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_DecodeUTF32Stateful()</span></code></a> will not treat
trailing incomplete UTF-32 byte sequences (such as a number of bytes not divisible
by four) as an error. Those bytes will not be decoded and the number of bytes
that have been decoded will be stored in <em>consumed</em>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_EncodeUTF32">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_EncodeUTF32</code><span class="sig-paren">(</span>const <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a><em> *s</em>, Py_ssize_t<em> size</em>, const char<em> *errors</em>, int<em> byteorder</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_EncodeUTF32" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a Python bytes object holding the UTF-32 encoded value of the Unicode
data in <em>s</em>. Output is written according to the following byte order:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">byteorder</span> <span class="o">==</span> <span class="o">-</span><span class="mi">1</span><span class="o">:</span> <span class="n">little</span> <span class="n">endian</span>
<span class="n">byteorder</span> <span class="o">==</span> <span class="mi">0</span><span class="o">:</span> <span class="n">native</span> <span class="n">byte</span> <span class="n">order</span> <span class="p">(</span><span class="n">writes</span> <span class="n">a</span> <span class="n">BOM</span> <span class="n">mark</span><span class="p">)</span>
<span class="n">byteorder</span> <span class="o">==</span> <span class="mi">1</span><span class="o">:</span> <span class="n">big</span> <span class="n">endian</span>
</pre></div>
</div>
<p>If byteorder is <code class="docutils literal notranslate"><span class="pre">0</span></code>, the output string will always start with the Unicode BOM
mark (U+FEFF). In the other two modes, no BOM mark is prepended.</p>
<p>If <em>Py_UNICODE_WIDE</em> is not defined, surrogate pairs will be output
as a single code point.</p>
<p>Return <em>NULL</em> if an exception was raised by the codec.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_AsUTF32String">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_AsUTF32String</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *unicode</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_AsUTF32String" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a Python string using the UTF-32 encoding in native byte order. The
string always starts with a BOM mark. Error handling is “strict”. Return
<em>NULL</em> if an exception was raised by the codec.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
</dd></dl>
</div>
<div class="section" id="utf-16-codecs">
<h3>UTF-16 Codecs<a class="headerlink" href="#utf-16-codecs" title="Permalink to this headline">¶</a></h3>
<p>These are the UTF-16 codec APIs:</p>
<dl class="function">
<dt id="c.PyUnicode_DecodeUTF16">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_DecodeUTF16</code><span class="sig-paren">(</span>const char<em> *s</em>, Py_ssize_t<em> size</em>, const char<em> *errors</em>, int<em> *byteorder</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_DecodeUTF16" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Decode <em>size</em> bytes from a UTF-16 encoded buffer string and return the
corresponding Unicode object. <em>errors</em> (if non-<em>NULL</em>) defines the error
handling. It defaults to “strict”.</p>
<p>If <em>byteorder</em> is non-<em>NULL</em>, the decoder starts decoding using the given byte
order:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="o">*</span><span class="n">byteorder</span> <span class="o">==</span> <span class="o">-</span><span class="mi">1</span><span class="o">:</span> <span class="n">little</span> <span class="n">endian</span>
<span class="o">*</span><span class="n">byteorder</span> <span class="o">==</span> <span class="mi">0</span><span class="o">:</span> <span class="n">native</span> <span class="n">order</span>
<span class="o">*</span><span class="n">byteorder</span> <span class="o">==</span> <span class="mi">1</span><span class="o">:</span> <span class="n">big</span> <span class="n">endian</span>
</pre></div>
</div>
<p>If <code class="docutils literal notranslate"><span class="pre">*byteorder</span></code> is zero, and the first two bytes of the input data are a
byte order mark (BOM), the decoder switches to this byte order and the BOM is
not copied into the resulting Unicode string. If <code class="docutils literal notranslate"><span class="pre">*byteorder</span></code> is <code class="docutils literal notranslate"><span class="pre">-1</span></code> or
<code class="docutils literal notranslate"><span class="pre">1</span></code>, any byte order mark is copied to the output (where it will result in
either a <code class="docutils literal notranslate"><span class="pre">\ufeff</span></code> or a <code class="docutils literal notranslate"><span class="pre">\ufffe</span></code> character).</p>
<p>After completion, <em>*byteorder</em> is set to the current byte order at the end
of input data.</p>
<p>If <em>byteorder</em> is <em>NULL</em>, the codec starts in native order mode.</p>
<p>Return <em>NULL</em> if an exception was raised by the codec.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>size</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_DecodeUTF16Stateful">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_DecodeUTF16Stateful</code><span class="sig-paren">(</span>const char<em> *s</em>, Py_ssize_t<em> size</em>, const char<em> *errors</em>, int<em> *byteorder</em>, Py_ssize_t<em> *consumed</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_DecodeUTF16Stateful" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>If <em>consumed</em> is <em>NULL</em>, behave like <a class="reference internal" href="#c.PyUnicode_DecodeUTF16" title="PyUnicode_DecodeUTF16"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_DecodeUTF16()</span></code></a>. If
<em>consumed</em> is not <em>NULL</em>, <a class="reference internal" href="#c.PyUnicode_DecodeUTF16Stateful" title="PyUnicode_DecodeUTF16Stateful"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_DecodeUTF16Stateful()</span></code></a> will not treat
trailing incomplete UTF-16 byte sequences (such as an odd number of bytes or a
split surrogate pair) as an error. Those bytes will not be decoded and the
number of bytes that have been decoded will be stored in <em>consumed</em>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>size</em> and an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span> <span class="pre">*</span></code>
type for <em>consumed</em>. This might require changes in your code for
properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_EncodeUTF16">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_EncodeUTF16</code><span class="sig-paren">(</span>const <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a><em> *s</em>, Py_ssize_t<em> size</em>, const char<em> *errors</em>, int<em> byteorder</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_EncodeUTF16" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a Python string object holding the UTF-16 encoded value of the Unicode
data in <em>s</em>. Output is written according to the following byte order:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">byteorder</span> <span class="o">==</span> <span class="o">-</span><span class="mi">1</span><span class="o">:</span> <span class="n">little</span> <span class="n">endian</span>
<span class="n">byteorder</span> <span class="o">==</span> <span class="mi">0</span><span class="o">:</span> <span class="n">native</span> <span class="n">byte</span> <span class="n">order</span> <span class="p">(</span><span class="n">writes</span> <span class="n">a</span> <span class="n">BOM</span> <span class="n">mark</span><span class="p">)</span>
<span class="n">byteorder</span> <span class="o">==</span> <span class="mi">1</span><span class="o">:</span> <span class="n">big</span> <span class="n">endian</span>
</pre></div>
</div>
<p>If byteorder is <code class="docutils literal notranslate"><span class="pre">0</span></code>, the output string will always start with the Unicode BOM
mark (U+FEFF). In the other two modes, no BOM mark is prepended.</p>
<p>If <em>Py_UNICODE_WIDE</em> is defined, a single <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_UNICODE</span></code></a> value may get
represented as a surrogate pair. If it is not defined, each <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_UNICODE</span></code></a>
values is interpreted as a UCS-2 character.</p>
<p>Return <em>NULL</em> if an exception was raised by the codec.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>size</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_AsUTF16String">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_AsUTF16String</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *unicode</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_AsUTF16String" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a Python string using the UTF-16 encoding in native byte order. The
string always starts with a BOM mark. Error handling is “strict”. Return
<em>NULL</em> if an exception was raised by the codec.</p>
</dd></dl>
</div>
<div class="section" id="utf-7-codecs">
<h3>UTF-7 Codecs<a class="headerlink" href="#utf-7-codecs" title="Permalink to this headline">¶</a></h3>
<p>These are the UTF-7 codec APIs:</p>
<dl class="function">
<dt id="c.PyUnicode_DecodeUTF7">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_DecodeUTF7</code><span class="sig-paren">(</span>const char<em> *s</em>, Py_ssize_t<em> size</em>, const char<em> *errors</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_DecodeUTF7" title="Permalink to this definition">¶</a></dt>
<dd><p>Create a Unicode object by decoding <em>size</em> bytes of the UTF-7 encoded string
<em>s</em>. Return <em>NULL</em> if an exception was raised by the codec.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_DecodeUTF7Stateful">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_DecodeUTF7Stateful</code><span class="sig-paren">(</span>const char<em> *s</em>, Py_ssize_t<em> size</em>, const char<em> *errors</em>, Py_ssize_t<em> *consumed</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_DecodeUTF7Stateful" title="Permalink to this definition">¶</a></dt>
<dd><p>If <em>consumed</em> is <em>NULL</em>, behave like <a class="reference internal" href="#c.PyUnicode_DecodeUTF7" title="PyUnicode_DecodeUTF7"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_DecodeUTF7()</span></code></a>. If
<em>consumed</em> is not <em>NULL</em>, trailing incomplete UTF-7 base-64 sections will not
be treated as an error. Those bytes will not be decoded and the number of
bytes that have been decoded will be stored in <em>consumed</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_EncodeUTF7">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_EncodeUTF7</code><span class="sig-paren">(</span>const <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a><em> *s</em>, Py_ssize_t<em> size</em>, int<em> base64SetO</em>, int<em> base64WhiteSpace</em>, const char<em> *errors</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_EncodeUTF7" title="Permalink to this definition">¶</a></dt>
<dd><p>Encode the <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_UNICODE</span></code></a> buffer of the given size using UTF-7 and
return a Python bytes object. Return <em>NULL</em> if an exception was raised by
the codec.</p>
<p>If <em>base64SetO</em> is nonzero, “Set O” (punctuation that has no otherwise
special meaning) will be encoded in base-64. If <em>base64WhiteSpace</em> is
nonzero, whitespace will be encoded in base-64. Both are set to zero for the
Python “utf-7” codec.</p>
</dd></dl>
</div>
<div class="section" id="unicode-escape-codecs">
<h3>Unicode-Escape Codecs<a class="headerlink" href="#unicode-escape-codecs" title="Permalink to this headline">¶</a></h3>
<p>These are the “Unicode Escape” codec APIs:</p>
<dl class="function">
<dt id="c.PyUnicode_DecodeUnicodeEscape">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_DecodeUnicodeEscape</code><span class="sig-paren">(</span>const char<em> *s</em>, Py_ssize_t<em> size</em>, const char<em> *errors</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_DecodeUnicodeEscape" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Create a Unicode object by decoding <em>size</em> bytes of the Unicode-Escape encoded
string <em>s</em>. Return <em>NULL</em> if an exception was raised by the codec.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>size</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_EncodeUnicodeEscape">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_EncodeUnicodeEscape</code><span class="sig-paren">(</span>const <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a><em> *s</em>, Py_ssize_t<em> size</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_EncodeUnicodeEscape" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Encode the <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_UNICODE</span></code></a> buffer of the given <em>size</em> using Unicode-Escape and
return a Python string object. Return <em>NULL</em> if an exception was raised by the
codec.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>size</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_AsUnicodeEscapeString">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_AsUnicodeEscapeString</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *unicode</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_AsUnicodeEscapeString" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Encode a Unicode object using Unicode-Escape and return the result as Python
string object. Error handling is “strict”. Return <em>NULL</em> if an exception was
raised by the codec.</p>
</dd></dl>
</div>
<div class="section" id="raw-unicode-escape-codecs">
<h3>Raw-Unicode-Escape Codecs<a class="headerlink" href="#raw-unicode-escape-codecs" title="Permalink to this headline">¶</a></h3>
<p>These are the “Raw Unicode Escape” codec APIs:</p>
<dl class="function">
<dt id="c.PyUnicode_DecodeRawUnicodeEscape">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_DecodeRawUnicodeEscape</code><span class="sig-paren">(</span>const char<em> *s</em>, Py_ssize_t<em> size</em>, const char<em> *errors</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_DecodeRawUnicodeEscape" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Create a Unicode object by decoding <em>size</em> bytes of the Raw-Unicode-Escape
encoded string <em>s</em>. Return <em>NULL</em> if an exception was raised by the codec.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>size</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_EncodeRawUnicodeEscape">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_EncodeRawUnicodeEscape</code><span class="sig-paren">(</span>const <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a><em> *s</em>, Py_ssize_t<em> size</em>, const char<em> *errors</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_EncodeRawUnicodeEscape" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Encode the <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_UNICODE</span></code></a> buffer of the given <em>size</em> using Raw-Unicode-Escape
and return a Python string object. Return <em>NULL</em> if an exception was raised by
the codec.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>size</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_AsRawUnicodeEscapeString">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_AsRawUnicodeEscapeString</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *unicode</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_AsRawUnicodeEscapeString" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Encode a Unicode object using Raw-Unicode-Escape and return the result as
Python string object. Error handling is “strict”. Return <em>NULL</em> if an exception
was raised by the codec.</p>
</dd></dl>
</div>
<div class="section" id="latin-1-codecs">
<h3>Latin-1 Codecs<a class="headerlink" href="#latin-1-codecs" title="Permalink to this headline">¶</a></h3>
<p>These are the Latin-1 codec APIs: Latin-1 corresponds to the first 256 Unicode
ordinals and only these are accepted by the codecs during encoding.</p>
<dl class="function">
<dt id="c.PyUnicode_DecodeLatin1">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_DecodeLatin1</code><span class="sig-paren">(</span>const char<em> *s</em>, Py_ssize_t<em> size</em>, const char<em> *errors</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_DecodeLatin1" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Create a Unicode object by decoding <em>size</em> bytes of the Latin-1 encoded string
<em>s</em>. Return <em>NULL</em> if an exception was raised by the codec.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>size</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_EncodeLatin1">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_EncodeLatin1</code><span class="sig-paren">(</span>const <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a><em> *s</em>, Py_ssize_t<em> size</em>, const char<em> *errors</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_EncodeLatin1" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Encode the <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_UNICODE</span></code></a> buffer of the given <em>size</em> using Latin-1 and return
a Python string object. Return <em>NULL</em> if an exception was raised by the codec.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>size</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_AsLatin1String">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_AsLatin1String</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *unicode</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_AsLatin1String" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Encode a Unicode object using Latin-1 and return the result as Python string
object. Error handling is “strict”. Return <em>NULL</em> if an exception was raised
by the codec.</p>
</dd></dl>
</div>
<div class="section" id="ascii-codecs">
<h3>ASCII Codecs<a class="headerlink" href="#ascii-codecs" title="Permalink to this headline">¶</a></h3>
<p>These are the ASCII codec APIs. Only 7-bit ASCII data is accepted. All other
codes generate errors.</p>
<dl class="function">
<dt id="c.PyUnicode_DecodeASCII">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_DecodeASCII</code><span class="sig-paren">(</span>const char<em> *s</em>, Py_ssize_t<em> size</em>, const char<em> *errors</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_DecodeASCII" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Create a Unicode object by decoding <em>size</em> bytes of the ASCII encoded string
<em>s</em>. Return <em>NULL</em> if an exception was raised by the codec.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>size</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_EncodeASCII">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_EncodeASCII</code><span class="sig-paren">(</span>const <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a><em> *s</em>, Py_ssize_t<em> size</em>, const char<em> *errors</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_EncodeASCII" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Encode the <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_UNICODE</span></code></a> buffer of the given <em>size</em> using ASCII and return a
Python string object. Return <em>NULL</em> if an exception was raised by the codec.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>size</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_AsASCIIString">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_AsASCIIString</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *unicode</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_AsASCIIString" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Encode a Unicode object using ASCII and return the result as Python string
object. Error handling is “strict”. Return <em>NULL</em> if an exception was raised
by the codec.</p>
</dd></dl>
</div>
<div class="section" id="character-map-codecs">
<h3>Character Map Codecs<a class="headerlink" href="#character-map-codecs" title="Permalink to this headline">¶</a></h3>
<p>This codec is special in that it can be used to implement many different codecs
(and this is in fact what was done to obtain most of the standard codecs
included in the <code class="xref py py-mod docutils literal notranslate"><span class="pre">encodings</span></code> package). The codec uses mapping to encode and
decode characters.</p>
<p>Decoding mappings must map single string characters to single Unicode
characters, integers (which are then interpreted as Unicode ordinals) or <code class="docutils literal notranslate"><span class="pre">None</span></code>
(meaning “undefined mapping” and causing an error).</p>
<p>Encoding mappings must map single Unicode characters to single string
characters, integers (which are then interpreted as Latin-1 ordinals) or <code class="docutils literal notranslate"><span class="pre">None</span></code>
(meaning “undefined mapping” and causing an error).</p>
<p>The mapping objects provided must only support the __getitem__ mapping
interface.</p>
<p>If a character lookup fails with a LookupError, the character is copied as-is
meaning that its ordinal value will be interpreted as Unicode or Latin-1 ordinal
resp. Because of this, mappings only need to contain those mappings which map
characters to different code points.</p>
<p>These are the mapping codec APIs:</p>
<dl class="function">
<dt id="c.PyUnicode_DecodeCharmap">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_DecodeCharmap</code><span class="sig-paren">(</span>const char<em> *s</em>, Py_ssize_t<em> size</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *mapping</em>, const char<em> *errors</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_DecodeCharmap" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Create a Unicode object by decoding <em>size</em> bytes of the encoded string <em>s</em> using
the given <em>mapping</em> object. Return <em>NULL</em> if an exception was raised by the
codec. If <em>mapping</em> is <em>NULL</em> latin-1 decoding will be done. Else it can be a
dictionary mapping byte or a unicode string, which is treated as a lookup table.
Byte values greater that the length of the string and U+FFFE “characters” are
treated as “undefined mapping”.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.4: </span>Allowed unicode string as mapping argument.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>size</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_EncodeCharmap">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_EncodeCharmap</code><span class="sig-paren">(</span>const <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a><em> *s</em>, Py_ssize_t<em> size</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *mapping</em>, const char<em> *errors</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_EncodeCharmap" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Encode the <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_UNICODE</span></code></a> buffer of the given <em>size</em> using the given
<em>mapping</em> object and return a Python string object. Return <em>NULL</em> if an
exception was raised by the codec.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>size</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_AsCharmapString">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_AsCharmapString</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *unicode</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *mapping</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_AsCharmapString" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Encode a Unicode object using the given <em>mapping</em> object and return the result
as Python string object. Error handling is “strict”. Return <em>NULL</em> if an
exception was raised by the codec.</p>
</dd></dl>
<p>The following codec API is special in that maps Unicode to Unicode.</p>
<dl class="function">
<dt id="c.PyUnicode_TranslateCharmap">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_TranslateCharmap</code><span class="sig-paren">(</span>const <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a><em> *s</em>, Py_ssize_t<em> size</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *table</em>, const char<em> *errors</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_TranslateCharmap" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Translate a <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_UNICODE</span></code></a> buffer of the given <em>size</em> by applying a
character mapping <em>table</em> to it and return the resulting Unicode object. Return
<em>NULL</em> when an exception was raised by the codec.</p>
<p>The <em>mapping</em> table must map Unicode ordinal integers to Unicode ordinal
integers or <code class="docutils literal notranslate"><span class="pre">None</span></code> (causing deletion of the character).</p>
<p>Mapping tables need only provide the <a class="reference internal" href="../reference/datamodel.html#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getitem__()</span></code></a> interface; dictionaries
and sequences work well. Unmapped character ordinals (ones which cause a
<a class="reference internal" href="../library/exceptions.html#exceptions.LookupError" title="exceptions.LookupError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">LookupError</span></code></a>) are left untouched and are copied as-is.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>size</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
</div>
<div class="section" id="mbcs-codecs-for-windows">
<h3>MBCS codecs for Windows<a class="headerlink" href="#mbcs-codecs-for-windows" title="Permalink to this headline">¶</a></h3>
<p>These are the MBCS codec APIs. They are currently only available on Windows and
use the Win32 MBCS converters to implement the conversions. Note that MBCS (or
DBCS) is a class of encodings, not just one. The target encoding is defined by
the user settings on the machine running the codec.</p>
<dl class="function">
<dt id="c.PyUnicode_DecodeMBCS">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_DecodeMBCS</code><span class="sig-paren">(</span>const char<em> *s</em>, Py_ssize_t<em> size</em>, const char<em> *errors</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_DecodeMBCS" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Create a Unicode object by decoding <em>size</em> bytes of the MBCS encoded string <em>s</em>.
Return <em>NULL</em> if an exception was raised by the codec.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>size</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_DecodeMBCSStateful">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_DecodeMBCSStateful</code><span class="sig-paren">(</span>const char<em> *s</em>, int<em> size</em>, const char<em> *errors</em>, int<em> *consumed</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_DecodeMBCSStateful" title="Permalink to this definition">¶</a></dt>
<dd><p>If <em>consumed</em> is <em>NULL</em>, behave like <a class="reference internal" href="#c.PyUnicode_DecodeMBCS" title="PyUnicode_DecodeMBCS"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_DecodeMBCS()</span></code></a>. If
<em>consumed</em> is not <em>NULL</em>, <a class="reference internal" href="#c.PyUnicode_DecodeMBCSStateful" title="PyUnicode_DecodeMBCSStateful"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyUnicode_DecodeMBCSStateful()</span></code></a> will not decode
trailing lead byte and the number of bytes that have been decoded will be stored
in <em>consumed</em>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.5.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_EncodeMBCS">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_EncodeMBCS</code><span class="sig-paren">(</span>const <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a><em> *s</em>, Py_ssize_t<em> size</em>, const char<em> *errors</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_EncodeMBCS" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Encode the <a class="reference internal" href="#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_UNICODE</span></code></a> buffer of the given <em>size</em> using MBCS and return a
Python string object. Return <em>NULL</em> if an exception was raised by the codec.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>size</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_AsMBCSString">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_AsMBCSString</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *unicode</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_AsMBCSString" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Encode a Unicode object using MBCS and return the result as Python string
object. Error handling is “strict”. Return <em>NULL</em> if an exception was raised
by the codec.</p>
</dd></dl>
</div>
<div class="section" id="methods-slots">
<h3>Methods & Slots<a class="headerlink" href="#methods-slots" title="Permalink to this headline">¶</a></h3>
</div>
</div>
<div class="section" id="methods-and-slot-functions">
<span id="unicodemethodsandslots"></span><h2>Methods and Slot Functions<a class="headerlink" href="#methods-and-slot-functions" title="Permalink to this headline">¶</a></h2>
<p>The following APIs are capable of handling Unicode objects and strings on input
(we refer to them as strings in the descriptions) and return Unicode objects or
integers as appropriate.</p>
<p>They all return <em>NULL</em> or <code class="docutils literal notranslate"><span class="pre">-1</span></code> if an exception occurs.</p>
<dl class="function">
<dt id="c.PyUnicode_Concat">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_Concat</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *left</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *right</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_Concat" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Concat two strings giving a new Unicode string.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_Split">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_Split</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *s</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *sep</em>, Py_ssize_t<em> maxsplit</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_Split" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Split a string giving a list of Unicode strings. If <em>sep</em> is <em>NULL</em>, splitting
will be done at all whitespace substrings. Otherwise, splits occur at the given
separator. At most <em>maxsplit</em> splits will be done. If negative, no limit is
set. Separators are not included in the resulting list.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>maxsplit</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_Splitlines">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_Splitlines</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *s</em>, int<em> keepend</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_Splitlines" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Split a Unicode string at line breaks, returning a list of Unicode strings.
CRLF is considered to be one line break. If <em>keepend</em> is <code class="docutils literal notranslate"><span class="pre">0</span></code>, the Line break
characters are not included in the resulting strings.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_Translate">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_Translate</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *str</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *table</em>, const char<em> *errors</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_Translate" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Translate a string by applying a character mapping table to it and return the
resulting Unicode object.</p>
<p>The mapping table must map Unicode ordinal integers to Unicode ordinal integers
or <code class="docutils literal notranslate"><span class="pre">None</span></code> (causing deletion of the character).</p>
<p>Mapping tables need only provide the <a class="reference internal" href="../reference/datamodel.html#object.__getitem__" title="object.__getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getitem__()</span></code></a> interface; dictionaries
and sequences work well. Unmapped character ordinals (ones which cause a
<a class="reference internal" href="../library/exceptions.html#exceptions.LookupError" title="exceptions.LookupError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">LookupError</span></code></a>) are left untouched and are copied as-is.</p>
<p><em>errors</em> has the usual meaning for codecs. It may be <em>NULL</em> which indicates to
use the default error handling.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_Join">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_Join</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *separator</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *seq</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_Join" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Join a sequence of strings using the given <em>separator</em> and return the resulting
Unicode string.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_Tailmatch">
Py_ssize_t <code class="descname">PyUnicode_Tailmatch</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *str</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *substr</em>, Py_ssize_t<em> start</em>, Py_ssize_t<em> end</em>, int<em> direction</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_Tailmatch" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">1</span></code> if <em>substr</em> matches <code class="docutils literal notranslate"><span class="pre">str[start:end]</span></code> at the given tail end
(<em>direction</em> == <code class="docutils literal notranslate"><span class="pre">-1</span></code> means to do a prefix match, <em>direction</em> == <code class="docutils literal notranslate"><span class="pre">1</span></code> a suffix match),
<code class="docutils literal notranslate"><span class="pre">0</span></code> otherwise. Return <code class="docutils literal notranslate"><span class="pre">-1</span></code> if an error occurred.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>start</em> and <em>end</em>. This
might require changes in your code for properly supporting 64-bit
systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_Find">
Py_ssize_t <code class="descname">PyUnicode_Find</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *str</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *substr</em>, Py_ssize_t<em> start</em>, Py_ssize_t<em> end</em>, int<em> direction</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_Find" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the first position of <em>substr</em> in <code class="docutils literal notranslate"><span class="pre">str[start:end]</span></code> using the given
<em>direction</em> (<em>direction</em> == <code class="docutils literal notranslate"><span class="pre">1</span></code> means to do a forward search, <em>direction</em> == <code class="docutils literal notranslate"><span class="pre">-1</span></code> a
backward search). The return value is the index of the first match; a value of
<code class="docutils literal notranslate"><span class="pre">-1</span></code> indicates that no match was found, and <code class="docutils literal notranslate"><span class="pre">-2</span></code> indicates that an error
occurred and an exception has been set.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>start</em> and <em>end</em>. This
might require changes in your code for properly supporting 64-bit
systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_Count">
Py_ssize_t <code class="descname">PyUnicode_Count</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *str</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *substr</em>, Py_ssize_t<em> start</em>, Py_ssize_t<em> end</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_Count" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the number of non-overlapping occurrences of <em>substr</em> in
<code class="docutils literal notranslate"><span class="pre">str[start:end]</span></code>. Return <code class="docutils literal notranslate"><span class="pre">-1</span></code> if an error occurred.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function returned an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type and used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code>
type for <em>start</em> and <em>end</em>. This might require changes in your code for
properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_Replace">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_Replace</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *str</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *substr</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *replstr</em>, Py_ssize_t<em> maxcount</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_Replace" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Replace at most <em>maxcount</em> occurrences of <em>substr</em> in <em>str</em> with <em>replstr</em> and
return the resulting Unicode object. <em>maxcount</em> == <code class="docutils literal notranslate"><span class="pre">-1</span></code> means replace all
occurrences.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>maxcount</em>. This might
require changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_Compare">
int <code class="descname">PyUnicode_Compare</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *left</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *right</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_Compare" title="Permalink to this definition">¶</a></dt>
<dd><p>Compare two strings and return <code class="docutils literal notranslate"><span class="pre">-1</span></code>, <code class="docutils literal notranslate"><span class="pre">0</span></code>, <code class="docutils literal notranslate"><span class="pre">1</span></code> for less than, equal, and greater than,
respectively.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_RichCompare">
int <code class="descname">PyUnicode_RichCompare</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *left</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *right</em>, int<em> op</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_RichCompare" title="Permalink to this definition">¶</a></dt>
<dd><p>Rich compare two unicode strings and return one of the following:</p>
<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">NULL</span></code> in case an exception was raised</li>
<li><code class="xref py py-const docutils literal notranslate"><span class="pre">Py_True</span></code> or <code class="xref py py-const docutils literal notranslate"><span class="pre">Py_False</span></code> for successful comparisons</li>
<li><code class="xref py py-const docutils literal notranslate"><span class="pre">Py_NotImplemented</span></code> in case the type combination is unknown</li>
</ul>
<p>Note that <code class="xref py py-const docutils literal notranslate"><span class="pre">Py_EQ</span></code> and <code class="xref py py-const docutils literal notranslate"><span class="pre">Py_NE</span></code> comparisons can cause a
<a class="reference internal" href="../library/exceptions.html#exceptions.UnicodeWarning" title="exceptions.UnicodeWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">UnicodeWarning</span></code></a> in case the conversion of the arguments to Unicode fails
with a <a class="reference internal" href="../library/exceptions.html#exceptions.UnicodeDecodeError" title="exceptions.UnicodeDecodeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">UnicodeDecodeError</span></code></a>.</p>
<p>Possible values for <em>op</em> are <code class="xref py py-const docutils literal notranslate"><span class="pre">Py_GT</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">Py_GE</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">Py_EQ</span></code>,
<code class="xref py py-const docutils literal notranslate"><span class="pre">Py_NE</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">Py_LT</span></code>, and <code class="xref py py-const docutils literal notranslate"><span class="pre">Py_LE</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_Format">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicode_Format</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *format</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *args</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_Format" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a new string object from <em>format</em> and <em>args</em>; this is analogous to
<code class="docutils literal notranslate"><span class="pre">format</span> <span class="pre">%</span> <span class="pre">args</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicode_Contains">
int <code class="descname">PyUnicode_Contains</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *container</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *element</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicode_Contains" title="Permalink to this definition">¶</a></dt>
<dd><p>Check whether <em>element</em> is contained in <em>container</em> and return true or false
accordingly.</p>
<p><em>element</em> has to coerce to a one element Unicode string. <code class="docutils literal notranslate"><span class="pre">-1</span></code> is returned if
there was an error.</p>
</dd></dl>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Unicode Objects and Codecs</a><ul>
<li><a class="reference internal" href="#unicode-objects">Unicode Objects</a><ul>
<li><a class="reference internal" href="#unicode-type">Unicode Type</a></li>
<li><a class="reference internal" href="#unicode-character-properties">Unicode Character Properties</a></li>
<li><a class="reference internal" href="#plain-py-unicode">Plain Py_UNICODE</a></li>
<li><a class="reference internal" href="#wchar-t-support">wchar_t Support</a></li>
</ul>
</li>
<li><a class="reference internal" href="#built-in-codecs">Built-in Codecs</a><ul>
<li><a class="reference internal" href="#generic-codecs">Generic Codecs</a></li>
<li><a class="reference internal" href="#utf-8-codecs">UTF-8 Codecs</a></li>
<li><a class="reference internal" href="#utf-32-codecs">UTF-32 Codecs</a></li>
<li><a class="reference internal" href="#utf-16-codecs">UTF-16 Codecs</a></li>
<li><a class="reference internal" href="#utf-7-codecs">UTF-7 Codecs</a></li>
<li><a class="reference internal" href="#unicode-escape-codecs">Unicode-Escape Codecs</a></li>
<li><a class="reference internal" href="#raw-unicode-escape-codecs">Raw-Unicode-Escape Codecs</a></li>
<li><a class="reference internal" href="#latin-1-codecs">Latin-1 Codecs</a></li>
<li><a class="reference internal" href="#ascii-codecs">ASCII Codecs</a></li>
<li><a class="reference internal" href="#character-map-codecs">Character Map Codecs</a></li>
<li><a class="reference internal" href="#mbcs-codecs-for-windows">MBCS codecs for Windows</a></li>
<li><a class="reference internal" href="#methods-slots">Methods & Slots</a></li>
</ul>
</li>
<li><a class="reference internal" href="#methods-and-slot-functions">Methods and Slot Functions</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="string.html"
title="previous chapter">String/Bytes Objects</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="buffer.html"
title="next chapter">Buffers and Memoryview Objects</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/unicode.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="buffer.html" title="Buffers and Memoryview Objects"
>next</a> |</li>
<li class="right" >
<a href="string.html" title="String/Bytes Objects"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" >Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\���ɤ � html/c-api/utilities.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Utilities — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Operating System Utilities" href="sys.html" />
<link rel="prev" title="Exception Handling" href="exceptions.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/utilities.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="sys.html" title="Operating System Utilities"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="exceptions.html" title="Exception Handling"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Python/C API Reference Manual</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="utilities">
<span id="id1"></span><h1>Utilities<a class="headerlink" href="#utilities" title="Permalink to this headline">¶</a></h1>
<p>The functions in this chapter perform various utility tasks, ranging from
helping C code be more portable across platforms, using Python modules from C,
and parsing function arguments and constructing Python values from C values.</p>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="sys.html">Operating System Utilities</a></li>
<li class="toctree-l1"><a class="reference internal" href="sys.html#system-functions">System Functions</a></li>
<li class="toctree-l1"><a class="reference internal" href="sys.html#process-control">Process Control</a></li>
<li class="toctree-l1"><a class="reference internal" href="import.html">Importing Modules</a></li>
<li class="toctree-l1"><a class="reference internal" href="marshal.html">Data marshalling support</a></li>
<li class="toctree-l1"><a class="reference internal" href="arg.html">Parsing arguments and building values</a></li>
<li class="toctree-l1"><a class="reference internal" href="conversion.html">String conversion and formatting</a></li>
<li class="toctree-l1"><a class="reference internal" href="reflection.html">Reflection</a></li>
<li class="toctree-l1"><a class="reference internal" href="codec.html">Codec registry and support functions</a><ul>
<li class="toctree-l2"><a class="reference internal" href="codec.html#codec-lookup-api">Codec lookup API</a></li>
<li class="toctree-l2"><a class="reference internal" href="codec.html#registry-api-for-unicode-encoding-error-handlers">Registry API for Unicode encoding error handlers</a></li>
</ul>
</li>
</ul>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="exceptions.html"
title="previous chapter">Exception Handling</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="sys.html"
title="next chapter">Operating System Utilities</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/utilities.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="sys.html" title="Operating System Utilities"
>next</a> |</li>
<li class="right" >
<a href="exceptions.html" title="Exception Handling"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\<��ޭ ޭ html/c-api/veryhigh.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>The Very High Level Layer — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Reference Counting" href="refcounting.html" />
<link rel="prev" title="Introduction" href="intro.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/veryhigh.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="refcounting.html" title="Reference Counting"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="intro.html" title="Introduction"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Python/C API Reference Manual</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="the-very-high-level-layer">
<span id="veryhigh"></span><h1>The Very High Level Layer<a class="headerlink" href="#the-very-high-level-layer" title="Permalink to this headline">¶</a></h1>
<p>The functions in this chapter will let you execute Python source code given in a
file or a buffer, but they will not let you interact in a more detailed way with
the interpreter.</p>
<p>Several of these functions accept a start symbol from the grammar as a
parameter. The available start symbols are <code class="xref py py-const docutils literal notranslate"><span class="pre">Py_eval_input</span></code>,
<code class="xref py py-const docutils literal notranslate"><span class="pre">Py_file_input</span></code>, and <code class="xref py py-const docutils literal notranslate"><span class="pre">Py_single_input</span></code>. These are described
following the functions which accept them as parameters.</p>
<p>Note also that several of these functions take <code class="xref c c-type docutils literal notranslate"><span class="pre">FILE*</span></code> parameters. One
particular issue which needs to be handled carefully is that the <code class="xref c c-type docutils literal notranslate"><span class="pre">FILE</span></code>
structure for different C libraries can be different and incompatible. Under
Windows (at least), it is possible for dynamically linked extensions to actually
use different libraries, so care should be taken that <code class="xref c c-type docutils literal notranslate"><span class="pre">FILE*</span></code> parameters
are only passed to these functions if it is certain that they were created by
the same library that the Python runtime is using.</p>
<dl class="function">
<dt id="c.Py_Main">
int <code class="descname">Py_Main</code><span class="sig-paren">(</span>int<em> argc</em>, char<em> **argv</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_Main" title="Permalink to this definition">¶</a></dt>
<dd><p>The main program for the standard interpreter. This is made available for
programs which embed Python. The <em>argc</em> and <em>argv</em> parameters should be
prepared exactly as those which are passed to a C program’s <code class="xref c c-func docutils literal notranslate"><span class="pre">main()</span></code>
function. It is important to note that the argument list may be modified (but
the contents of the strings pointed to by the argument list are not). The return
value will be <code class="docutils literal notranslate"><span class="pre">0</span></code> if the interpreter exits normally (ie, without an
exception), <code class="docutils literal notranslate"><span class="pre">1</span></code> if the interpreter exits due to an exception, or <code class="docutils literal notranslate"><span class="pre">2</span></code>
if the parameter list does not represent a valid Python command line.</p>
<p>Note that if an otherwise unhandled <a class="reference internal" href="../library/exceptions.html#exceptions.SystemExit" title="exceptions.SystemExit"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SystemExit</span></code></a> is raised, this
function will not return <code class="docutils literal notranslate"><span class="pre">1</span></code>, but exit the process, as long as
<code class="docutils literal notranslate"><span class="pre">Py_InspectFlag</span></code> is not set.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyRun_AnyFile">
int <code class="descname">PyRun_AnyFile</code><span class="sig-paren">(</span>FILE<em> *fp</em>, const char<em> *filename</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyRun_AnyFile" title="Permalink to this definition">¶</a></dt>
<dd><p>This is a simplified interface to <a class="reference internal" href="#c.PyRun_AnyFileExFlags" title="PyRun_AnyFileExFlags"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyRun_AnyFileExFlags()</span></code></a> below, leaving
<em>closeit</em> set to <code class="docutils literal notranslate"><span class="pre">0</span></code> and <em>flags</em> set to <em>NULL</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyRun_AnyFileFlags">
int <code class="descname">PyRun_AnyFileFlags</code><span class="sig-paren">(</span>FILE<em> *fp</em>, const char<em> *filename</em>, <a class="reference internal" href="#c.PyCompilerFlags" title="PyCompilerFlags">PyCompilerFlags</a><em> *flags</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyRun_AnyFileFlags" title="Permalink to this definition">¶</a></dt>
<dd><p>This is a simplified interface to <a class="reference internal" href="#c.PyRun_AnyFileExFlags" title="PyRun_AnyFileExFlags"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyRun_AnyFileExFlags()</span></code></a> below, leaving
the <em>closeit</em> argument set to <code class="docutils literal notranslate"><span class="pre">0</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyRun_AnyFileEx">
int <code class="descname">PyRun_AnyFileEx</code><span class="sig-paren">(</span>FILE<em> *fp</em>, const char<em> *filename</em>, int<em> closeit</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyRun_AnyFileEx" title="Permalink to this definition">¶</a></dt>
<dd><p>This is a simplified interface to <a class="reference internal" href="#c.PyRun_AnyFileExFlags" title="PyRun_AnyFileExFlags"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyRun_AnyFileExFlags()</span></code></a> below, leaving
the <em>flags</em> argument set to <em>NULL</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyRun_AnyFileExFlags">
int <code class="descname">PyRun_AnyFileExFlags</code><span class="sig-paren">(</span>FILE<em> *fp</em>, const char<em> *filename</em>, int<em> closeit</em>, <a class="reference internal" href="#c.PyCompilerFlags" title="PyCompilerFlags">PyCompilerFlags</a><em> *flags</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyRun_AnyFileExFlags" title="Permalink to this definition">¶</a></dt>
<dd><p>If <em>fp</em> refers to a file associated with an interactive device (console or
terminal input or Unix pseudo-terminal), return the value of
<a class="reference internal" href="#c.PyRun_InteractiveLoop" title="PyRun_InteractiveLoop"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyRun_InteractiveLoop()</span></code></a>, otherwise return the result of
<a class="reference internal" href="#c.PyRun_SimpleFile" title="PyRun_SimpleFile"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyRun_SimpleFile()</span></code></a>. If <em>filename</em> is <em>NULL</em>, this function uses
<code class="docutils literal notranslate"><span class="pre">"???"</span></code> as the filename.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyRun_SimpleString">
int <code class="descname">PyRun_SimpleString</code><span class="sig-paren">(</span>const char<em> *command</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyRun_SimpleString" title="Permalink to this definition">¶</a></dt>
<dd><p>This is a simplified interface to <a class="reference internal" href="#c.PyRun_SimpleStringFlags" title="PyRun_SimpleStringFlags"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyRun_SimpleStringFlags()</span></code></a> below,
leaving the <em>PyCompilerFlags*</em> argument set to NULL.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyRun_SimpleStringFlags">
int <code class="descname">PyRun_SimpleStringFlags</code><span class="sig-paren">(</span>const char<em> *command</em>, <a class="reference internal" href="#c.PyCompilerFlags" title="PyCompilerFlags">PyCompilerFlags</a><em> *flags</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyRun_SimpleStringFlags" title="Permalink to this definition">¶</a></dt>
<dd><p>Executes the Python source code from <em>command</em> in the <a class="reference internal" href="../library/__main__.html#module-__main__" title="__main__: The environment where the top-level script is run."><code class="xref py py-mod docutils literal notranslate"><span class="pre">__main__</span></code></a> module
according to the <em>flags</em> argument. If <a class="reference internal" href="../library/__main__.html#module-__main__" title="__main__: The environment where the top-level script is run."><code class="xref py py-mod docutils literal notranslate"><span class="pre">__main__</span></code></a> does not already exist, it
is created. Returns <code class="docutils literal notranslate"><span class="pre">0</span></code> on success or <code class="docutils literal notranslate"><span class="pre">-1</span></code> if an exception was raised. If
there was an error, there is no way to get the exception information. For the
meaning of <em>flags</em>, see below.</p>
<p>Note that if an otherwise unhandled <a class="reference internal" href="../library/exceptions.html#exceptions.SystemExit" title="exceptions.SystemExit"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SystemExit</span></code></a> is raised, this
function will not return <code class="docutils literal notranslate"><span class="pre">-1</span></code>, but exit the process, as long as
<code class="docutils literal notranslate"><span class="pre">Py_InspectFlag</span></code> is not set.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyRun_SimpleFile">
int <code class="descname">PyRun_SimpleFile</code><span class="sig-paren">(</span>FILE<em> *fp</em>, const char<em> *filename</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyRun_SimpleFile" title="Permalink to this definition">¶</a></dt>
<dd><p>This is a simplified interface to <a class="reference internal" href="#c.PyRun_SimpleFileExFlags" title="PyRun_SimpleFileExFlags"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyRun_SimpleFileExFlags()</span></code></a> below,
leaving <em>closeit</em> set to <code class="docutils literal notranslate"><span class="pre">0</span></code> and <em>flags</em> set to <em>NULL</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyRun_SimpleFileFlags">
int <code class="descname">PyRun_SimpleFileFlags</code><span class="sig-paren">(</span>FILE<em> *fp</em>, const char<em> *filename</em>, <a class="reference internal" href="#c.PyCompilerFlags" title="PyCompilerFlags">PyCompilerFlags</a><em> *flags</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyRun_SimpleFileFlags" title="Permalink to this definition">¶</a></dt>
<dd><p>This is a simplified interface to <a class="reference internal" href="#c.PyRun_SimpleFileExFlags" title="PyRun_SimpleFileExFlags"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyRun_SimpleFileExFlags()</span></code></a> below,
leaving <em>closeit</em> set to <code class="docutils literal notranslate"><span class="pre">0</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyRun_SimpleFileEx">
int <code class="descname">PyRun_SimpleFileEx</code><span class="sig-paren">(</span>FILE<em> *fp</em>, const char<em> *filename</em>, int<em> closeit</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyRun_SimpleFileEx" title="Permalink to this definition">¶</a></dt>
<dd><p>This is a simplified interface to <a class="reference internal" href="#c.PyRun_SimpleFileExFlags" title="PyRun_SimpleFileExFlags"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyRun_SimpleFileExFlags()</span></code></a> below,
leaving <em>flags</em> set to <em>NULL</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyRun_SimpleFileExFlags">
int <code class="descname">PyRun_SimpleFileExFlags</code><span class="sig-paren">(</span>FILE<em> *fp</em>, const char<em> *filename</em>, int<em> closeit</em>, <a class="reference internal" href="#c.PyCompilerFlags" title="PyCompilerFlags">PyCompilerFlags</a><em> *flags</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyRun_SimpleFileExFlags" title="Permalink to this definition">¶</a></dt>
<dd><p>Similar to <a class="reference internal" href="#c.PyRun_SimpleStringFlags" title="PyRun_SimpleStringFlags"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyRun_SimpleStringFlags()</span></code></a>, but the Python source code is read
from <em>fp</em> instead of an in-memory string. <em>filename</em> should be the name of the
file. If <em>closeit</em> is true, the file is closed before PyRun_SimpleFileExFlags
returns.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyRun_InteractiveOne">
int <code class="descname">PyRun_InteractiveOne</code><span class="sig-paren">(</span>FILE<em> *fp</em>, const char<em> *filename</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyRun_InteractiveOne" title="Permalink to this definition">¶</a></dt>
<dd><p>This is a simplified interface to <a class="reference internal" href="#c.PyRun_InteractiveOneFlags" title="PyRun_InteractiveOneFlags"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyRun_InteractiveOneFlags()</span></code></a> below,
leaving <em>flags</em> set to <em>NULL</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyRun_InteractiveOneFlags">
int <code class="descname">PyRun_InteractiveOneFlags</code><span class="sig-paren">(</span>FILE<em> *fp</em>, const char<em> *filename</em>, <a class="reference internal" href="#c.PyCompilerFlags" title="PyCompilerFlags">PyCompilerFlags</a><em> *flags</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyRun_InteractiveOneFlags" title="Permalink to this definition">¶</a></dt>
<dd><p>Read and execute a single statement from a file associated with an
interactive device according to the <em>flags</em> argument. The user will be
prompted using <code class="docutils literal notranslate"><span class="pre">sys.ps1</span></code> and <code class="docutils literal notranslate"><span class="pre">sys.ps2</span></code>. Returns <code class="docutils literal notranslate"><span class="pre">0</span></code> when the input was
executed successfully, <code class="docutils literal notranslate"><span class="pre">-1</span></code> if there was an exception, or an error code
from the <code class="file docutils literal notranslate"><span class="pre">errcode.h</span></code> include file distributed as part of Python if
there was a parse error. (Note that <code class="file docutils literal notranslate"><span class="pre">errcode.h</span></code> is not included by
<code class="file docutils literal notranslate"><span class="pre">Python.h</span></code>, so must be included specifically if needed.)</p>
</dd></dl>
<dl class="function">
<dt id="c.PyRun_InteractiveLoop">
int <code class="descname">PyRun_InteractiveLoop</code><span class="sig-paren">(</span>FILE<em> *fp</em>, const char<em> *filename</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyRun_InteractiveLoop" title="Permalink to this definition">¶</a></dt>
<dd><p>This is a simplified interface to <a class="reference internal" href="#c.PyRun_InteractiveLoopFlags" title="PyRun_InteractiveLoopFlags"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyRun_InteractiveLoopFlags()</span></code></a> below,
leaving <em>flags</em> set to <em>NULL</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyRun_InteractiveLoopFlags">
int <code class="descname">PyRun_InteractiveLoopFlags</code><span class="sig-paren">(</span>FILE<em> *fp</em>, const char<em> *filename</em>, <a class="reference internal" href="#c.PyCompilerFlags" title="PyCompilerFlags">PyCompilerFlags</a><em> *flags</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyRun_InteractiveLoopFlags" title="Permalink to this definition">¶</a></dt>
<dd><p>Read and execute statements from a file associated with an interactive device
until EOF is reached. The user will be prompted using <code class="docutils literal notranslate"><span class="pre">sys.ps1</span></code> and
<code class="docutils literal notranslate"><span class="pre">sys.ps2</span></code>. Returns <code class="docutils literal notranslate"><span class="pre">0</span></code> at EOF.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyParser_SimpleParseString">
struct _node* <code class="descname">PyParser_SimpleParseString</code><span class="sig-paren">(</span>const char<em> *str</em>, int<em> start</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyParser_SimpleParseString" title="Permalink to this definition">¶</a></dt>
<dd><p>This is a simplified interface to
<a class="reference internal" href="#c.PyParser_SimpleParseStringFlagsFilename" title="PyParser_SimpleParseStringFlagsFilename"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyParser_SimpleParseStringFlagsFilename()</span></code></a> below, leaving <em>filename</em> set
to <em>NULL</em> and <em>flags</em> set to <code class="docutils literal notranslate"><span class="pre">0</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyParser_SimpleParseStringFlags">
struct _node* <code class="descname">PyParser_SimpleParseStringFlags</code><span class="sig-paren">(</span>const char<em> *str</em>, int<em> start</em>, int<em> flags</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyParser_SimpleParseStringFlags" title="Permalink to this definition">¶</a></dt>
<dd><p>This is a simplified interface to
<a class="reference internal" href="#c.PyParser_SimpleParseStringFlagsFilename" title="PyParser_SimpleParseStringFlagsFilename"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyParser_SimpleParseStringFlagsFilename()</span></code></a> below, leaving <em>filename</em> set
to <em>NULL</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyParser_SimpleParseStringFlagsFilename">
struct _node* <code class="descname">PyParser_SimpleParseStringFlagsFilename</code><span class="sig-paren">(</span>const char<em> *str</em>, const char<em> *filename</em>, int<em> start</em>, int<em> flags</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyParser_SimpleParseStringFlagsFilename" title="Permalink to this definition">¶</a></dt>
<dd><p>Parse Python source code from <em>str</em> using the start token <em>start</em> according to
the <em>flags</em> argument. The result can be used to create a code object which can
be evaluated efficiently. This is useful if a code fragment must be evaluated
many times.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyParser_SimpleParseFile">
struct _node* <code class="descname">PyParser_SimpleParseFile</code><span class="sig-paren">(</span>FILE<em> *fp</em>, const char<em> *filename</em>, int<em> start</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyParser_SimpleParseFile" title="Permalink to this definition">¶</a></dt>
<dd><p>This is a simplified interface to <a class="reference internal" href="#c.PyParser_SimpleParseFileFlags" title="PyParser_SimpleParseFileFlags"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyParser_SimpleParseFileFlags()</span></code></a> below,
leaving <em>flags</em> set to <code class="docutils literal notranslate"><span class="pre">0</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyParser_SimpleParseFileFlags">
struct _node* <code class="descname">PyParser_SimpleParseFileFlags</code><span class="sig-paren">(</span>FILE<em> *fp</em>, const char<em> *filename</em>, int<em> start</em>, int<em> flags</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyParser_SimpleParseFileFlags" title="Permalink to this definition">¶</a></dt>
<dd><p>Similar to <a class="reference internal" href="#c.PyParser_SimpleParseStringFlagsFilename" title="PyParser_SimpleParseStringFlagsFilename"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyParser_SimpleParseStringFlagsFilename()</span></code></a>, but the Python
source code is read from <em>fp</em> instead of an in-memory string.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyRun_String">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyRun_String</code><span class="sig-paren">(</span>const char<em> *str</em>, int<em> start</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *globals</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *locals</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyRun_String" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>This is a simplified interface to <a class="reference internal" href="#c.PyRun_StringFlags" title="PyRun_StringFlags"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyRun_StringFlags()</span></code></a> below, leaving
<em>flags</em> set to <em>NULL</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyRun_StringFlags">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyRun_StringFlags</code><span class="sig-paren">(</span>const char<em> *str</em>, int<em> start</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *globals</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *locals</em>, <a class="reference internal" href="#c.PyCompilerFlags" title="PyCompilerFlags">PyCompilerFlags</a><em> *flags</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyRun_StringFlags" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Execute Python source code from <em>str</em> in the context specified by the
dictionaries <em>globals</em> and <em>locals</em> with the compiler flags specified by
<em>flags</em>. The parameter <em>start</em> specifies the start token that should be used to
parse the source code.</p>
<p>Returns the result of executing the code as a Python object, or <em>NULL</em> if an
exception was raised.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyRun_File">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyRun_File</code><span class="sig-paren">(</span>FILE<em> *fp</em>, const char<em> *filename</em>, int<em> start</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *globals</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *locals</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyRun_File" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>This is a simplified interface to <a class="reference internal" href="#c.PyRun_FileExFlags" title="PyRun_FileExFlags"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyRun_FileExFlags()</span></code></a> below, leaving
<em>closeit</em> set to <code class="docutils literal notranslate"><span class="pre">0</span></code> and <em>flags</em> set to <em>NULL</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyRun_FileEx">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyRun_FileEx</code><span class="sig-paren">(</span>FILE<em> *fp</em>, const char<em> *filename</em>, int<em> start</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *globals</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *locals</em>, int<em> closeit</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyRun_FileEx" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>This is a simplified interface to <a class="reference internal" href="#c.PyRun_FileExFlags" title="PyRun_FileExFlags"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyRun_FileExFlags()</span></code></a> below, leaving
<em>flags</em> set to <em>NULL</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyRun_FileFlags">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyRun_FileFlags</code><span class="sig-paren">(</span>FILE<em> *fp</em>, const char<em> *filename</em>, int<em> start</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *globals</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *locals</em>, <a class="reference internal" href="#c.PyCompilerFlags" title="PyCompilerFlags">PyCompilerFlags</a><em> *flags</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyRun_FileFlags" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>This is a simplified interface to <a class="reference internal" href="#c.PyRun_FileExFlags" title="PyRun_FileExFlags"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyRun_FileExFlags()</span></code></a> below, leaving
<em>closeit</em> set to <code class="docutils literal notranslate"><span class="pre">0</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyRun_FileExFlags">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyRun_FileExFlags</code><span class="sig-paren">(</span>FILE<em> *fp</em>, const char<em> *filename</em>, int<em> start</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *globals</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *locals</em>, int<em> closeit</em>, <a class="reference internal" href="#c.PyCompilerFlags" title="PyCompilerFlags">PyCompilerFlags</a><em> *flags</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyRun_FileExFlags" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Similar to <a class="reference internal" href="#c.PyRun_StringFlags" title="PyRun_StringFlags"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyRun_StringFlags()</span></code></a>, but the Python source code is read from
<em>fp</em> instead of an in-memory string. <em>filename</em> should be the name of the file.
If <em>closeit</em> is true, the file is closed before <a class="reference internal" href="#c.PyRun_FileExFlags" title="PyRun_FileExFlags"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyRun_FileExFlags()</span></code></a>
returns.</p>
</dd></dl>
<dl class="function">
<dt id="c.Py_CompileString">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">Py_CompileString</code><span class="sig-paren">(</span>const char<em> *str</em>, const char<em> *filename</em>, int<em> start</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_CompileString" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>This is a simplified interface to <a class="reference internal" href="#c.Py_CompileStringFlags" title="Py_CompileStringFlags"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_CompileStringFlags()</span></code></a> below, leaving
<em>flags</em> set to <em>NULL</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.Py_CompileStringFlags">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">Py_CompileStringFlags</code><span class="sig-paren">(</span>const char<em> *str</em>, const char<em> *filename</em>, int<em> start</em>, <a class="reference internal" href="#c.PyCompilerFlags" title="PyCompilerFlags">PyCompilerFlags</a><em> *flags</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_CompileStringFlags" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Parse and compile the Python source code in <em>str</em>, returning the resulting code
object. The start token is given by <em>start</em>; this can be used to constrain the
code which can be compiled and should be <code class="xref py py-const docutils literal notranslate"><span class="pre">Py_eval_input</span></code>,
<code class="xref py py-const docutils literal notranslate"><span class="pre">Py_file_input</span></code>, or <code class="xref py py-const docutils literal notranslate"><span class="pre">Py_single_input</span></code>. The filename specified by
<em>filename</em> is used to construct the code object and may appear in tracebacks or
<a class="reference internal" href="../library/exceptions.html#exceptions.SyntaxError" title="exceptions.SyntaxError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SyntaxError</span></code></a> exception messages. This returns <em>NULL</em> if the code cannot
be parsed or compiled.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyEval_EvalCode">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyEval_EvalCode</code><span class="sig-paren">(</span><a class="reference internal" href="code.html#c.PyCodeObject" title="PyCodeObject">PyCodeObject</a><em> *co</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *globals</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *locals</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyEval_EvalCode" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>This is a simplified interface to <a class="reference internal" href="#c.PyEval_EvalCodeEx" title="PyEval_EvalCodeEx"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyEval_EvalCodeEx()</span></code></a>, with just
the code object, and the dictionaries of global and local variables.
The other arguments are set to <em>NULL</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyEval_EvalCodeEx">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyEval_EvalCodeEx</code><span class="sig-paren">(</span><a class="reference internal" href="code.html#c.PyCodeObject" title="PyCodeObject">PyCodeObject</a><em> *co</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *globals</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *locals</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> **args</em>, int<em> argcount</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> **kws</em>, int<em> kwcount</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> **defs</em>, int<em> defcount</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *closure</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyEval_EvalCodeEx" title="Permalink to this definition">¶</a></dt>
<dd><p>Evaluate a precompiled code object, given a particular environment for its
evaluation. This environment consists of dictionaries of global and local
variables, arrays of arguments, keywords and defaults, and a closure tuple of
cells.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyEval_EvalFrame">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyEval_EvalFrame</code><span class="sig-paren">(</span>PyFrameObject<em> *f</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyEval_EvalFrame" title="Permalink to this definition">¶</a></dt>
<dd><p>Evaluate an execution frame. This is a simplified interface to
PyEval_EvalFrameEx, for backward compatibility.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyEval_EvalFrameEx">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyEval_EvalFrameEx</code><span class="sig-paren">(</span>PyFrameObject<em> *f</em>, int<em> throwflag</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyEval_EvalFrameEx" title="Permalink to this definition">¶</a></dt>
<dd><p>This is the main, unvarnished function of Python interpretation. It is
literally 2000 lines long. The code object associated with the execution
frame <em>f</em> is executed, interpreting bytecode and executing calls as needed.
The additional <em>throwflag</em> parameter can mostly be ignored - if true, then
it causes an exception to immediately be thrown; this is used for the
<a class="reference internal" href="../reference/expressions.html#generator.throw" title="generator.throw"><code class="xref py py-meth docutils literal notranslate"><span class="pre">throw()</span></code></a> methods of generator objects.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyEval_MergeCompilerFlags">
int <code class="descname">PyEval_MergeCompilerFlags</code><span class="sig-paren">(</span><a class="reference internal" href="#c.PyCompilerFlags" title="PyCompilerFlags">PyCompilerFlags</a><em> *cf</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyEval_MergeCompilerFlags" title="Permalink to this definition">¶</a></dt>
<dd><p>This function changes the flags of the current evaluation frame, and returns
true on success, false on failure.</p>
</dd></dl>
<dl class="var">
<dt id="c.Py_eval_input">
int <code class="descname">Py_eval_input</code><a class="headerlink" href="#c.Py_eval_input" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-0">The start symbol from the Python grammar for isolated expressions; for use with
<a class="reference internal" href="#c.Py_CompileString" title="Py_CompileString"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_CompileString()</span></code></a>.</p>
</dd></dl>
<dl class="var">
<dt id="c.Py_file_input">
int <code class="descname">Py_file_input</code><a class="headerlink" href="#c.Py_file_input" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-1">The start symbol from the Python grammar for sequences of statements as read
from a file or other source; for use with <a class="reference internal" href="#c.Py_CompileString" title="Py_CompileString"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_CompileString()</span></code></a>. This is
the symbol to use when compiling arbitrarily long Python source code.</p>
</dd></dl>
<dl class="var">
<dt id="c.Py_single_input">
int <code class="descname">Py_single_input</code><a class="headerlink" href="#c.Py_single_input" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-2">The start symbol from the Python grammar for a single statement; for use with
<a class="reference internal" href="#c.Py_CompileString" title="Py_CompileString"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_CompileString()</span></code></a>. This is the symbol used for the interactive
interpreter loop.</p>
</dd></dl>
<dl class="type">
<dt id="c.PyCompilerFlags">
struct <code class="descname">PyCompilerFlags</code><a class="headerlink" href="#c.PyCompilerFlags" title="Permalink to this definition">¶</a></dt>
<dd><p>This is the structure used to hold compiler flags. In cases where code is only
being compiled, it is passed as <code class="docutils literal notranslate"><span class="pre">int</span> <span class="pre">flags</span></code>, and in cases where code is being
executed, it is passed as <code class="docutils literal notranslate"><span class="pre">PyCompilerFlags</span> <span class="pre">*flags</span></code>. In this case, <code class="docutils literal notranslate"><span class="pre">from</span>
<span class="pre">__future__</span> <span class="pre">import</span></code> can modify <em>flags</em>.</p>
<p>Whenever <code class="docutils literal notranslate"><span class="pre">PyCompilerFlags</span> <span class="pre">*flags</span></code> is <em>NULL</em>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">cf_flags</span></code> is treated as
equal to <code class="docutils literal notranslate"><span class="pre">0</span></code>, and any modification due to <code class="docutils literal notranslate"><span class="pre">from</span> <span class="pre">__future__</span> <span class="pre">import</span></code> is
discarded.</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="n">PyCompilerFlags</span> <span class="p">{</span>
<span class="kt">int</span> <span class="n">cf_flags</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
</dd></dl>
<dl class="var">
<dt id="c.CO_FUTURE_DIVISION">
int <code class="descname">CO_FUTURE_DIVISION</code><a class="headerlink" href="#c.CO_FUTURE_DIVISION" title="Permalink to this definition">¶</a></dt>
<dd><p>This bit can be set in <em>flags</em> to cause division operator <code class="docutils literal notranslate"><span class="pre">/</span></code> to be
interpreted as “true division” according to <span class="target" id="index-3"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0238"><strong>PEP 238</strong></a>.</p>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="intro.html"
title="previous chapter">Introduction</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="refcounting.html"
title="next chapter">Reference Counting</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/veryhigh.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="refcounting.html" title="Reference Counting"
>next</a> |</li>
<li class="right" >
<a href="intro.html" title="Introduction"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\��ۄ#5 #5 html/c-api/weakref.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Weak Reference Objects — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Capsules" href="capsule.html" />
<link rel="prev" title="Slice Objects" href="slice.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/weakref.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="capsule.html" title="Capsules"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="slice.html" title="Slice Objects"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" accesskey="U">Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="weak-reference-objects">
<span id="weakrefobjects"></span><h1>Weak Reference Objects<a class="headerlink" href="#weak-reference-objects" title="Permalink to this headline">¶</a></h1>
<p>Python supports <em>weak references</em> as first-class objects. There are two
specific object types which directly implement weak references. The first is a
simple reference object, and the second acts as a proxy for the original object
as much as it can.</p>
<dl class="function">
<dt id="c.PyWeakref_Check">
int <code class="descname">PyWeakref_Check</code><span class="sig-paren">(</span>ob<span class="sig-paren">)</span><a class="headerlink" href="#c.PyWeakref_Check" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if <em>ob</em> is either a reference or proxy object.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyWeakref_CheckRef">
int <code class="descname">PyWeakref_CheckRef</code><span class="sig-paren">(</span>ob<span class="sig-paren">)</span><a class="headerlink" href="#c.PyWeakref_CheckRef" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if <em>ob</em> is a reference object.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyWeakref_CheckProxy">
int <code class="descname">PyWeakref_CheckProxy</code><span class="sig-paren">(</span>ob<span class="sig-paren">)</span><a class="headerlink" href="#c.PyWeakref_CheckProxy" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if <em>ob</em> is a proxy object.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyWeakref_NewRef">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyWeakref_NewRef</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *ob</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *callback</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyWeakref_NewRef" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a weak reference object for the object <em>ob</em>. This will always return
a new reference, but is not guaranteed to create a new object; an existing
reference object may be returned. The second parameter, <em>callback</em>, can be a
callable object that receives notification when <em>ob</em> is garbage collected; it
should accept a single parameter, which will be the weak reference object
itself. <em>callback</em> may also be <code class="docutils literal notranslate"><span class="pre">None</span></code> or <em>NULL</em>. If <em>ob</em> is not a
weakly-referencable object, or if <em>callback</em> is not callable, <code class="docutils literal notranslate"><span class="pre">None</span></code>, or
<em>NULL</em>, this will return <em>NULL</em> and raise <a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyWeakref_NewProxy">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyWeakref_NewProxy</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *ob</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *callback</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyWeakref_NewProxy" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a weak reference proxy object for the object <em>ob</em>. This will always
return a new reference, but is not guaranteed to create a new object; an
existing proxy object may be returned. The second parameter, <em>callback</em>, can
be a callable object that receives notification when <em>ob</em> is garbage
collected; it should accept a single parameter, which will be the weak
reference object itself. <em>callback</em> may also be <code class="docutils literal notranslate"><span class="pre">None</span></code> or <em>NULL</em>. If <em>ob</em>
is not a weakly-referencable object, or if <em>callback</em> is not callable,
<code class="docutils literal notranslate"><span class="pre">None</span></code>, or <em>NULL</em>, this will return <em>NULL</em> and raise <a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyWeakref_GetObject">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyWeakref_GetObject</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *ref</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyWeakref_GetObject" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Borrowed reference.</em><p>Return the referenced object from a weak reference, <em>ref</em>. If the referent is
no longer live, returns <code class="xref py py-const docutils literal notranslate"><span class="pre">Py_None</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">This function returns a <strong>borrowed reference</strong> to the referenced object.
This means that you should always call <a class="reference internal" href="refcounting.html#c.Py_INCREF" title="Py_INCREF"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_INCREF()</span></code></a> on the object
except if you know that it cannot be destroyed while you are still
using it.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyWeakref_GET_OBJECT">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyWeakref_GET_OBJECT</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *ref</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyWeakref_GET_OBJECT" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Borrowed reference.</em><p>Similar to <a class="reference internal" href="#c.PyWeakref_GetObject" title="PyWeakref_GetObject"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyWeakref_GetObject()</span></code></a>, but implemented as a macro that does no
error checking.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="slice.html"
title="previous chapter">Slice Objects</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="capsule.html"
title="next chapter">Capsules</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/weakref.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="capsule.html" title="Capsules"
>next</a> |</li>
<li class="right" >
<a href="slice.html" title="Slice Objects"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" >Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\�HĴ3 3 html/c-api/abstract.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Abstract Objects Layer — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Object Protocol" href="object.html" />
<link rel="prev" title="Codec registry and support functions" href="codec.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/abstract.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="object.html" title="Object Protocol"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="codec.html" title="Codec registry and support functions"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Python/C API Reference Manual</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="abstract-objects-layer">
<span id="abstract"></span><h1>Abstract Objects Layer<a class="headerlink" href="#abstract-objects-layer" title="Permalink to this headline">¶</a></h1>
<p>The functions in this chapter interact with Python objects regardless of their
type, or with wide classes of object types (e.g. all numerical types, or all
sequence types). When used on object types for which they do not apply, they
will raise a Python exception.</p>
<p>It is not possible to use these functions on objects that are not properly
initialized, such as a list object that has been created by <a class="reference internal" href="list.html#c.PyList_New" title="PyList_New"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyList_New()</span></code></a>,
but whose items have not been set to some non-<code class="docutils literal notranslate"><span class="pre">NULL</span></code> value yet.</p>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="object.html">Object Protocol</a></li>
<li class="toctree-l1"><a class="reference internal" href="number.html">Number Protocol</a></li>
<li class="toctree-l1"><a class="reference internal" href="sequence.html">Sequence Protocol</a></li>
<li class="toctree-l1"><a class="reference internal" href="mapping.html">Mapping Protocol</a></li>
<li class="toctree-l1"><a class="reference internal" href="iter.html">Iterator Protocol</a></li>
<li class="toctree-l1"><a class="reference internal" href="objbuffer.html">Old Buffer Protocol</a></li>
</ul>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="codec.html"
title="previous chapter">Codec registry and support functions</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="object.html"
title="next chapter">Object Protocol</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/abstract.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="object.html" title="Object Protocol"
>next</a> |</li>
<li class="right" >
<a href="codec.html" title="Codec registry and support functions"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\"8t_I _I html/c-api/allocation.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Allocating Objects on the Heap — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Common Object Structures" href="structures.html" />
<link rel="prev" title="Object Implementation Support" href="objimpl.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/allocation.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="structures.html" title="Common Object Structures"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="objimpl.html" title="Object Implementation Support"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="objimpl.html" accesskey="U">Object Implementation Support</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="allocating-objects-on-the-heap">
<span id="allocating-objects"></span><h1>Allocating Objects on the Heap<a class="headerlink" href="#allocating-objects-on-the-heap" title="Permalink to this headline">¶</a></h1>
<dl class="function">
<dt id="c._PyObject_New">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">_PyObject_New</code><span class="sig-paren">(</span><a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a><em> *type</em><span class="sig-paren">)</span><a class="headerlink" href="#c._PyObject_New" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em></dd></dl>
<dl class="function">
<dt id="c._PyObject_NewVar">
<a class="reference internal" href="structures.html#c.PyVarObject" title="PyVarObject">PyVarObject</a>* <code class="descname">_PyObject_NewVar</code><span class="sig-paren">(</span><a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a><em> *type</em>, Py_ssize_t<em> size</em><span class="sig-paren">)</span><a class="headerlink" href="#c._PyObject_NewVar" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>size</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c._PyObject_Del">
void <code class="descname">_PyObject_Del</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *op</em><span class="sig-paren">)</span><a class="headerlink" href="#c._PyObject_Del" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="function">
<dt id="c.PyObject_Init">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyObject_Init</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *op</em>, <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a><em> *type</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_Init" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Borrowed reference.</em><p>Initialize a newly-allocated object <em>op</em> with its type and initial
reference. Returns the initialized object. If <em>type</em> indicates that the
object participates in the cyclic garbage detector, it is added to the
detector’s set of observed objects. Other fields of the object are not
affected.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_InitVar">
<a class="reference internal" href="structures.html#c.PyVarObject" title="PyVarObject">PyVarObject</a>* <code class="descname">PyObject_InitVar</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyVarObject" title="PyVarObject">PyVarObject</a><em> *op</em>, <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a><em> *type</em>, Py_ssize_t<em> size</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_InitVar" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Borrowed reference.</em><p>This does everything <a class="reference internal" href="#c.PyObject_Init" title="PyObject_Init"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_Init()</span></code></a> does, and also initializes the
length information for a variable-size object.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>size</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_New">
TYPE* <code class="descname">PyObject_New</code><span class="sig-paren">(</span>TYPE, <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a><em> *type</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_New" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Allocate a new Python object using the C structure type <em>TYPE</em> and the
Python type object <em>type</em>. Fields not defined by the Python object header
are not initialized; the object’s reference count will be one. The size of
the memory allocation is determined from the <a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_basicsize" title="PyTypeObject.tp_basicsize"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_basicsize</span></code></a> field of
the type object.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_NewVar">
TYPE* <code class="descname">PyObject_NewVar</code><span class="sig-paren">(</span>TYPE, <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a><em> *type</em>, Py_ssize_t<em> size</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_NewVar" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Allocate a new Python object using the C structure type <em>TYPE</em> and the
Python type object <em>type</em>. Fields not defined by the Python object header
are not initialized. The allocated memory allows for the <em>TYPE</em> structure
plus <em>size</em> fields of the size given by the <a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_itemsize" title="PyTypeObject.tp_itemsize"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_itemsize</span></code></a> field of
<em>type</em>. This is useful for implementing objects like tuples, which are
able to determine their size at construction time. Embedding the array of
fields into the same allocation decreases the number of allocations,
improving the memory management efficiency.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>size</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_Del">
void <code class="descname">PyObject_Del</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *op</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_Del" title="Permalink to this definition">¶</a></dt>
<dd><p>Releases memory allocated to an object using <a class="reference internal" href="#c.PyObject_New" title="PyObject_New"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_New()</span></code></a> or
<a class="reference internal" href="#c.PyObject_NewVar" title="PyObject_NewVar"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_NewVar()</span></code></a>. This is normally called from the
<a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_dealloc" title="PyTypeObject.tp_dealloc"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_dealloc</span></code></a> handler specified in the object’s type. The fields of
the object should not be accessed after this call as the memory is no
longer a valid Python object.</p>
</dd></dl>
<dl class="function">
<dt id="c.Py_InitModule">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">Py_InitModule</code><span class="sig-paren">(</span>char<em> *name</em>, <a class="reference internal" href="structures.html#c.PyMethodDef" title="PyMethodDef">PyMethodDef</a><em> *methods</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_InitModule" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Borrowed reference.</em><p>Create a new module object based on a name and table of functions,
returning the new module object.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.3: </span>Older versions of Python did not support <em>NULL</em> as the value for the
<em>methods</em> argument.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.Py_InitModule3">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">Py_InitModule3</code><span class="sig-paren">(</span>char<em> *name</em>, <a class="reference internal" href="structures.html#c.PyMethodDef" title="PyMethodDef">PyMethodDef</a><em> *methods</em>, char<em> *doc</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_InitModule3" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Borrowed reference.</em><p>Create a new module object based on a name and table of functions,
returning the new module object. If <em>doc</em> is non-<em>NULL</em>, it will be used
to define the docstring for the module.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.3: </span>Older versions of Python did not support <em>NULL</em> as the value for the
<em>methods</em> argument.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.Py_InitModule4">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">Py_InitModule4</code><span class="sig-paren">(</span>char<em> *name</em>, <a class="reference internal" href="structures.html#c.PyMethodDef" title="PyMethodDef">PyMethodDef</a><em> *methods</em>, char<em> *doc</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *self</em>, int<em> apiver</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_InitModule4" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Borrowed reference.</em><p>Create a new module object based on a name and table of functions,
returning the new module object. If <em>doc</em> is non-<em>NULL</em>, it will be used
to define the docstring for the module. If <em>self</em> is non-<em>NULL</em>, it will
be passed to the functions of the module as their (otherwise <em>NULL</em>) first
parameter. (This was added as an experimental feature, and there are no
known uses in the current version of Python.) For <em>apiver</em>, the only value
which should be passed is defined by the constant
<code class="xref py py-const docutils literal notranslate"><span class="pre">PYTHON_API_VERSION</span></code>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Most uses of this function should probably be using the
<a class="reference internal" href="#c.Py_InitModule3" title="Py_InitModule3"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_InitModule3()</span></code></a> instead; only use this if you are sure you need
it.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.3: </span>Older versions of Python did not support <em>NULL</em> as the value for the
<em>methods</em> argument.</p>
</div>
</dd></dl>
<dl class="var">
<dt id="c._Py_NoneStruct">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> <code class="descname">_Py_NoneStruct</code><a class="headerlink" href="#c._Py_NoneStruct" title="Permalink to this definition">¶</a></dt>
<dd><p>Object which is visible in Python as <code class="docutils literal notranslate"><span class="pre">None</span></code>. This should only be
accessed using the <code class="docutils literal notranslate"><span class="pre">Py_None</span></code> macro, which evaluates to a pointer to this
object.</p>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="objimpl.html"
title="previous chapter">Object Implementation Support</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="structures.html"
title="next chapter">Common Object Structures</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/allocation.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="structures.html" title="Common Object Structures"
>next</a> |</li>
<li class="right" >
<a href="objimpl.html" title="Object Implementation Support"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="objimpl.html" >Object Implementation Support</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\Q���2� 2� html/c-api/arg.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Parsing arguments and building values — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="String conversion and formatting" href="conversion.html" />
<link rel="prev" title="Data marshalling support" href="marshal.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/arg.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="conversion.html" title="String conversion and formatting"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="marshal.html" title="Data marshalling support"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="utilities.html" accesskey="U">Utilities</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="parsing-arguments-and-building-values">
<span id="arg-parsing"></span><h1>Parsing arguments and building values<a class="headerlink" href="#parsing-arguments-and-building-values" title="Permalink to this headline">¶</a></h1>
<p>These functions are useful when creating your own extensions functions and
methods. Additional information and examples are available in
<a class="reference internal" href="../extending/index.html#extending-index"><span class="std std-ref">Extending and Embedding the Python Interpreter</span></a>.</p>
<p>The first three of these functions described, <a class="reference internal" href="#c.PyArg_ParseTuple" title="PyArg_ParseTuple"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_ParseTuple()</span></code></a>,
<a class="reference internal" href="#c.PyArg_ParseTupleAndKeywords" title="PyArg_ParseTupleAndKeywords"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_ParseTupleAndKeywords()</span></code></a>, and <a class="reference internal" href="#c.PyArg_Parse" title="PyArg_Parse"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_Parse()</span></code></a>, all use
<em>format strings</em> which are used to tell the function about the expected
arguments. The format strings use the same syntax for each of these
functions.</p>
<p>A format string consists of zero or more “format units.” A format unit
describes one Python object; it is usually a single character or a
parenthesized sequence of format units. With a few exceptions, a format unit
that is not a parenthesized sequence normally corresponds to a single address
argument to these functions. In the following description, the quoted form is
the format unit; the entry in (round) parentheses is the Python object type
that matches the format unit; and the entry in [square] brackets is the type
of the C variable(s) whose address should be passed.</p>
<p>These formats allow accessing an object as a contiguous chunk of memory.
You don’t have to provide raw storage for the returned unicode or bytes
area. Also, you won’t have to release any memory yourself, except with the
<code class="docutils literal notranslate"><span class="pre">es</span></code>, <code class="docutils literal notranslate"><span class="pre">es#</span></code>, <code class="docutils literal notranslate"><span class="pre">et</span></code> and <code class="docutils literal notranslate"><span class="pre">et#</span></code> formats.</p>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">s</span></code> (string or Unicode) [const char *]</dt>
<dd>Convert a Python string or Unicode object to a C pointer to a character
string. You must not provide storage for the string itself; a pointer to
an existing string is stored into the character pointer variable whose
address you pass. The C string is NUL-terminated. The Python string must
not contain embedded NUL bytes; if it does, a <a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> exception is
raised. Unicode objects are converted to C strings using the default
encoding. If this conversion fails, a <a class="reference internal" href="../library/exceptions.html#exceptions.UnicodeError" title="exceptions.UnicodeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">UnicodeError</span></code></a> is raised.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">s#</span></code> (string, Unicode or any read buffer compatible object) [const char *, int (or <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code>, see below)]</dt>
<dd><p class="first">This variant on <code class="docutils literal notranslate"><span class="pre">s</span></code> stores into two C variables, the first one a pointer
to a character string, the second one its length. In this case the Python
string may contain embedded null bytes. Unicode objects pass back a
pointer to the default encoded string version of the object if such a
conversion is possible. All other read-buffer compatible objects pass back
a reference to the raw internal data representation.</p>
<p class="last">Starting with Python 2.5 the type of the length argument can be controlled
by defining the macro <code class="xref c c-macro docutils literal notranslate"><span class="pre">PY_SSIZE_T_CLEAN</span></code> before including
<code class="file docutils literal notranslate"><span class="pre">Python.h</span></code>. If the macro is defined, length is a <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code>
rather than an int.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">s*</span></code> (string, Unicode, or any buffer compatible object) [Py_buffer]</dt>
<dd><p class="first">Similar to <code class="docutils literal notranslate"><span class="pre">s#</span></code>, this code fills a Py_buffer structure provided by the
caller. The buffer gets locked, so that the caller can subsequently use
the buffer even inside a <code class="docutils literal notranslate"><span class="pre">Py_BEGIN_ALLOW_THREADS</span></code> block; the caller is
responsible for calling <code class="docutils literal notranslate"><span class="pre">PyBuffer_Release</span></code> with the structure after it
has processed the data.</p>
<div class="last versionadded">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">z</span></code> (string, Unicode or <code class="docutils literal notranslate"><span class="pre">None</span></code>) [const char *]</dt>
<dd>Like <code class="docutils literal notranslate"><span class="pre">s</span></code>, but the Python object may also be <code class="docutils literal notranslate"><span class="pre">None</span></code>, in which case the C
pointer is set to <em>NULL</em>.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">z#</span></code> (string, Unicode, <code class="docutils literal notranslate"><span class="pre">None</span></code> or any read buffer compatible object) [const char *, int]</dt>
<dd>This is to <code class="docutils literal notranslate"><span class="pre">s#</span></code> as <code class="docutils literal notranslate"><span class="pre">z</span></code> is to <code class="docutils literal notranslate"><span class="pre">s</span></code>.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">z*</span></code> (string, Unicode, <code class="docutils literal notranslate"><span class="pre">None</span></code> or any buffer compatible object) [Py_buffer]</dt>
<dd><p class="first">This is to <code class="docutils literal notranslate"><span class="pre">s*</span></code> as <code class="docutils literal notranslate"><span class="pre">z</span></code> is to <code class="docutils literal notranslate"><span class="pre">s</span></code>.</p>
<div class="last versionadded">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">u</span></code> (Unicode) [Py_UNICODE *]</dt>
<dd>Convert a Python Unicode object to a C pointer to a NUL-terminated buffer
of 16-bit Unicode (UTF-16) data. As with <code class="docutils literal notranslate"><span class="pre">s</span></code>, there is no need to
provide storage for the Unicode data buffer; a pointer to the existing
Unicode data is stored into the <a class="reference internal" href="unicode.html#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_UNICODE</span></code></a> pointer variable whose
address you pass.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">u#</span></code> (Unicode) [Py_UNICODE *, int]</dt>
<dd>This variant on <code class="docutils literal notranslate"><span class="pre">u</span></code> stores into two C variables, the first one a pointer
to a Unicode data buffer, the second one its length. Non-Unicode objects
are handled by interpreting their read-buffer pointer as pointer to a
<a class="reference internal" href="unicode.html#c.Py_UNICODE" title="Py_UNICODE"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_UNICODE</span></code></a> array.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">es</span></code> (string, Unicode or character buffer compatible object) [const char *encoding, char **buffer]</dt>
<dd><p class="first">This variant on <code class="docutils literal notranslate"><span class="pre">s</span></code> is used for encoding Unicode and objects convertible
to Unicode into a character buffer. It only works for encoded data without
embedded NUL bytes.</p>
<p>This format requires two arguments. The first is only used as input, and
must be a <code class="xref c c-type docutils literal notranslate"><span class="pre">const</span> <span class="pre">char*</span></code> which points to the name of an encoding as
a NUL-terminated string, or <em>NULL</em>, in which case the default encoding is
used. An exception is raised if the named encoding is not known to Python.
The second argument must be a <code class="xref c c-type docutils literal notranslate"><span class="pre">char**</span></code>; the value of the pointer
it references will be set to a buffer with the contents of the argument
text. The text will be encoded in the encoding specified by the first
argument.</p>
<p class="last"><a class="reference internal" href="#c.PyArg_ParseTuple" title="PyArg_ParseTuple"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_ParseTuple()</span></code></a> will allocate a buffer of the needed size, copy
the encoded data into this buffer and adjust <em>*buffer</em> to reference the
newly allocated storage. The caller is responsible for calling
<a class="reference internal" href="memory.html#c.PyMem_Free" title="PyMem_Free"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyMem_Free()</span></code></a> to free the allocated buffer after use.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">et</span></code> (string, Unicode or character buffer compatible object) [const char *encoding, char **buffer]</dt>
<dd>Same as <code class="docutils literal notranslate"><span class="pre">es</span></code> except that 8-bit string objects are passed through without
recoding them. Instead, the implementation assumes that the string object
uses the encoding passed in as parameter.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">es#</span></code> (string, Unicode or character buffer compatible object) [const char *encoding, char **buffer, int *buffer_length]</dt>
<dd><p class="first">This variant on <code class="docutils literal notranslate"><span class="pre">s#</span></code> is used for encoding Unicode and objects convertible
to Unicode into a character buffer. Unlike the <code class="docutils literal notranslate"><span class="pre">es</span></code> format, this variant
allows input data which contains NUL characters.</p>
<p>It requires three arguments. The first is only used as input, and must be
a <code class="xref c c-type docutils literal notranslate"><span class="pre">const</span> <span class="pre">char*</span></code> which points to the name of an encoding as a
NUL-terminated string, or <em>NULL</em>, in which case the default encoding is
used. An exception is raised if the named encoding is not known to Python.
The second argument must be a <code class="xref c c-type docutils literal notranslate"><span class="pre">char**</span></code>; the value of the pointer
it references will be set to a buffer with the contents of the argument
text. The text will be encoded in the encoding specified by the first
argument. The third argument must be a pointer to an integer; the
referenced integer will be set to the number of bytes in the output buffer.</p>
<p>There are two modes of operation:</p>
<p>If <em>*buffer</em> points a <em>NULL</em> pointer, the function will allocate a buffer
of the needed size, copy the encoded data into this buffer and set
<em>*buffer</em> to reference the newly allocated storage. The caller is
responsible for calling <a class="reference internal" href="memory.html#c.PyMem_Free" title="PyMem_Free"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyMem_Free()</span></code></a> to free the allocated buffer
after usage.</p>
<p>If <em>*buffer</em> points to a non-<em>NULL</em> pointer (an already allocated buffer),
<a class="reference internal" href="#c.PyArg_ParseTuple" title="PyArg_ParseTuple"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_ParseTuple()</span></code></a> will use this location as the buffer and
interpret the initial value of <em>*buffer_length</em> as the buffer size. It
will then copy the encoded data into the buffer and NUL-terminate it. If
the buffer is not large enough, a <a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> will be set.
Note: starting from Python 3.6 a <a class="reference internal" href="../library/exceptions.html#exceptions.ValueError" title="exceptions.ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> will be set.</p>
<p class="last">In both cases, <em>*buffer_length</em> is set to the length of the encoded data
without the trailing NUL byte.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">et#</span></code> (string, Unicode or character buffer compatible object) [const char *encoding, char **buffer, int *buffer_length]</dt>
<dd>Same as <code class="docutils literal notranslate"><span class="pre">es#</span></code> except that string objects are passed through without
recoding them. Instead, the implementation assumes that the string object
uses the encoding passed in as parameter.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">b</span></code> (integer) [unsigned char]</dt>
<dd>Convert a nonnegative Python integer to an unsigned tiny int, stored in a C
<code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">char</span></code>.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">B</span></code> (integer) [unsigned char]</dt>
<dd><p class="first">Convert a Python integer to a tiny int without overflow checking, stored in
a C <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">char</span></code>.</p>
<div class="last versionadded">
<p><span class="versionmodified">New in version 2.3.</span></p>
</div>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">h</span></code> (integer) [short int]</dt>
<dd>Convert a Python integer to a C <code class="xref c c-type docutils literal notranslate"><span class="pre">short</span> <span class="pre">int</span></code>.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">H</span></code> (integer) [unsigned short int]</dt>
<dd><p class="first">Convert a Python integer to a C <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">short</span> <span class="pre">int</span></code>, without
overflow checking.</p>
<div class="last versionadded">
<p><span class="versionmodified">New in version 2.3.</span></p>
</div>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">i</span></code> (integer) [int]</dt>
<dd>Convert a Python integer to a plain C <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code>.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">I</span></code> (integer) [unsigned int]</dt>
<dd><p class="first">Convert a Python integer to a C <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">int</span></code>, without overflow
checking.</p>
<div class="last versionadded">
<p><span class="versionmodified">New in version 2.3.</span></p>
</div>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">l</span></code> (integer) [long int]</dt>
<dd>Convert a Python integer to a C <code class="xref c c-type docutils literal notranslate"><span class="pre">long</span> <span class="pre">int</span></code>.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">k</span></code> (integer) [unsigned long]</dt>
<dd><p class="first">Convert a Python integer or long integer to a C <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">long</span></code>
without overflow checking.</p>
<div class="last versionadded">
<p><span class="versionmodified">New in version 2.3.</span></p>
</div>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">L</span></code> (integer) [PY_LONG_LONG]</dt>
<dd>Convert a Python integer to a C <code class="xref c c-type docutils literal notranslate"><span class="pre">long</span> <span class="pre">long</span></code>. This format is only
available on platforms that support <code class="xref c c-type docutils literal notranslate"><span class="pre">long</span> <span class="pre">long</span></code> (or <code class="xref c c-type docutils literal notranslate"><span class="pre">_int64</span></code>
on Windows).</dd>
<dt><code class="docutils literal notranslate"><span class="pre">K</span></code> (integer) [unsigned PY_LONG_LONG]</dt>
<dd><p class="first">Convert a Python integer or long integer to a C <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">long</span> <span class="pre">long</span></code>
without overflow checking. This format is only available on platforms that
support <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">long</span> <span class="pre">long</span></code> (or <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">_int64</span></code> on
Windows).</p>
<div class="last versionadded">
<p><span class="versionmodified">New in version 2.3.</span></p>
</div>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">n</span></code> (integer) [Py_ssize_t]</dt>
<dd><p class="first">Convert a Python integer or long integer to a C <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code>.</p>
<div class="last versionadded">
<p><span class="versionmodified">New in version 2.5.</span></p>
</div>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">c</span></code> (string of length 1) [char]</dt>
<dd>Convert a Python character, represented as a string of length 1, to a C
<code class="xref c c-type docutils literal notranslate"><span class="pre">char</span></code>.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">f</span></code> (float) [float]</dt>
<dd>Convert a Python floating point number to a C <code class="xref c c-type docutils literal notranslate"><span class="pre">float</span></code>.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">d</span></code> (float) [double]</dt>
<dd>Convert a Python floating point number to a C <code class="xref c c-type docutils literal notranslate"><span class="pre">double</span></code>.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">D</span></code> (complex) [Py_complex]</dt>
<dd>Convert a Python complex number to a C <a class="reference internal" href="complex.html#c.Py_complex" title="Py_complex"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_complex</span></code></a> structure.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">O</span></code> (object) [PyObject *]</dt>
<dd>Store a Python object (without any conversion) in a C object pointer. The
C program thus receives the actual object that was passed. The object’s
reference count is not increased. The pointer stored is not <em>NULL</em>.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">O!</span></code> (object) [<em>typeobject</em>, PyObject *]</dt>
<dd>Store a Python object in a C object pointer. This is similar to <code class="docutils literal notranslate"><span class="pre">O</span></code>, but
takes two C arguments: the first is the address of a Python type object,
the second is the address of the C variable (of type <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject*</span></code></a>)
into which the object pointer is stored. If the Python object does not
have the required type, <a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> is raised.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">O&</span></code> (object) [<em>converter</em>, <em>anything</em>]</dt>
<dd><p class="first">Convert a Python object to a C variable through a <em>converter</em> function.
This takes two arguments: the first is a function, the second is the
address of a C variable (of arbitrary type), converted to <code class="xref c c-type docutils literal notranslate"><span class="pre">void</span> <span class="pre">*</span></code>.
The <em>converter</em> function in turn is called as follows:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">status</span> <span class="o">=</span> <span class="n">converter</span><span class="p">(</span><span class="n">object</span><span class="p">,</span> <span class="n">address</span><span class="p">);</span>
</pre></div>
</div>
<p class="last">where <em>object</em> is the Python object to be converted and <em>address</em> is the
<code class="xref c c-type docutils literal notranslate"><span class="pre">void*</span></code> argument that was passed to the <a class="reference internal" href="#c.PyArg_Parse" title="PyArg_Parse"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_Parse*()</span></code></a>
function. The returned <em>status</em> should be <code class="docutils literal notranslate"><span class="pre">1</span></code> for a successful
conversion and <code class="docutils literal notranslate"><span class="pre">0</span></code> if the conversion has failed. When the conversion
fails, the <em>converter</em> function should raise an exception and leave the
content of <em>address</em> unmodified.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">S</span></code> (string) [PyStringObject *]</dt>
<dd>Like <code class="docutils literal notranslate"><span class="pre">O</span></code> but requires that the Python object is a string object. Raises
<a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> if the object is not a string object. The C variable may
also be declared as <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject*</span></code></a>.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">U</span></code> (Unicode string) [PyUnicodeObject *]</dt>
<dd>Like <code class="docutils literal notranslate"><span class="pre">O</span></code> but requires that the Python object is a Unicode object. Raises
<a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> if the object is not a Unicode object. The C variable may
also be declared as <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject*</span></code></a>.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">t#</span></code> (read-only character buffer) [char *, int]</dt>
<dd>Like <code class="docutils literal notranslate"><span class="pre">s#</span></code>, but accepts any object which implements the read-only buffer
interface. The <code class="xref c c-type docutils literal notranslate"><span class="pre">char*</span></code> variable is set to point to the first byte
of the buffer, and the <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> is set to the length of the buffer.
Only single-segment buffer objects are accepted; <a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> is raised
for all others.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">w</span></code> (read-write character buffer) [char *]</dt>
<dd>Similar to <code class="docutils literal notranslate"><span class="pre">s</span></code>, but accepts any object which implements the read-write
buffer interface. The caller must determine the length of the buffer by
other means, or use <code class="docutils literal notranslate"><span class="pre">w#</span></code> instead. Only single-segment buffer objects are
accepted; <a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> is raised for all others.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">w#</span></code> (read-write character buffer) [char *, Py_ssize_t]</dt>
<dd>Like <code class="docutils literal notranslate"><span class="pre">s#</span></code>, but accepts any object which implements the read-write buffer
interface. The <code class="xref c c-type docutils literal notranslate"><span class="pre">char</span> <span class="pre">*</span></code> variable is set to point to the first byte
of the buffer, and the <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code> is set to the length of the
buffer. Only single-segment buffer objects are accepted; <a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a>
is raised for all others.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">w*</span></code> (read-write byte-oriented buffer) [Py_buffer]</dt>
<dd><p class="first">This is to <code class="docutils literal notranslate"><span class="pre">w</span></code> what <code class="docutils literal notranslate"><span class="pre">s*</span></code> is to <code class="docutils literal notranslate"><span class="pre">s</span></code>.</p>
<div class="last versionadded">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">(items)</span></code> (tuple) [<em>matching-items</em>]</dt>
<dd><p class="first">The object must be a Python sequence whose length is the number of format
units in <em>items</em>. The C arguments must correspond to the individual format
units in <em>items</em>. Format units for sequences may be nested.</p>
<div class="last admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Prior to Python version 1.5.2, this format specifier only accepted a
tuple containing the individual parameters, not an arbitrary sequence.
Code which previously caused <a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> to be raised here may now
proceed without an exception. This is not expected to be a problem for
existing code.</p>
</div>
</dd>
</dl>
<p>It is possible to pass Python long integers where integers are requested;
however no proper range checking is done — the most significant bits are
silently truncated when the receiving field is too small to receive the value
(actually, the semantics are inherited from downcasts in C — your mileage
may vary).</p>
<p>A few other characters have a meaning in a format string. These may not occur
inside nested parentheses. They are:</p>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">|</span></code></dt>
<dd>Indicates that the remaining arguments in the Python argument list are
optional. The C variables corresponding to optional arguments should be
initialized to their default value — when an optional argument is not
specified, <a class="reference internal" href="#c.PyArg_ParseTuple" title="PyArg_ParseTuple"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_ParseTuple()</span></code></a> does not touch the contents of the
corresponding C variable(s).</dd>
<dt><code class="docutils literal notranslate"><span class="pre">:</span></code></dt>
<dd>The list of format units ends here; the string after the colon is used as
the function name in error messages (the “associated value” of the
exception that <a class="reference internal" href="#c.PyArg_ParseTuple" title="PyArg_ParseTuple"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_ParseTuple()</span></code></a> raises).</dd>
<dt><code class="docutils literal notranslate"><span class="pre">;</span></code></dt>
<dd>The list of format units ends here; the string after the semicolon is used
as the error message <em>instead</em> of the default error message. <code class="docutils literal notranslate"><span class="pre">:</span></code> and
<code class="docutils literal notranslate"><span class="pre">;</span></code> mutually exclude each other.</dd>
</dl>
<p>Note that any Python object references which are provided to the caller are
<em>borrowed</em> references; do not decrement their reference count!</p>
<p>Additional arguments passed to these functions must be addresses of variables
whose type is determined by the format string; these are used to store values
from the input tuple. There are a few cases, as described in the list of
format units above, where these parameters are used as input values; they
should match what is specified for the corresponding format unit in that case.</p>
<p>For the conversion to succeed, the <em>arg</em> object must match the format and the
format must be exhausted. On success, the <a class="reference internal" href="#c.PyArg_Parse" title="PyArg_Parse"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_Parse*()</span></code></a> functions
return true, otherwise they return false and raise an appropriate exception.
When the <a class="reference internal" href="#c.PyArg_Parse" title="PyArg_Parse"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_Parse*()</span></code></a> functions fail due to conversion failure in
one of the format units, the variables at the addresses corresponding to that
and the following format units are left untouched.</p>
<dl class="function">
<dt id="c.PyArg_ParseTuple">
int <code class="descname">PyArg_ParseTuple</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *args</em>, const char<em> *format</em>, ...<span class="sig-paren">)</span><a class="headerlink" href="#c.PyArg_ParseTuple" title="Permalink to this definition">¶</a></dt>
<dd><p>Parse the parameters of a function that takes only positional parameters
into local variables. Returns true on success; on failure, it returns
false and raises the appropriate exception.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyArg_VaParse">
int <code class="descname">PyArg_VaParse</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *args</em>, const char<em> *format</em>, va_list<em> vargs</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyArg_VaParse" title="Permalink to this definition">¶</a></dt>
<dd><p>Identical to <a class="reference internal" href="#c.PyArg_ParseTuple" title="PyArg_ParseTuple"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_ParseTuple()</span></code></a>, except that it accepts a va_list
rather than a variable number of arguments.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyArg_ParseTupleAndKeywords">
int <code class="descname">PyArg_ParseTupleAndKeywords</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *args</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *kw</em>, const char<em> *format</em>, char<em> *keywords[]</em>, ...<span class="sig-paren">)</span><a class="headerlink" href="#c.PyArg_ParseTupleAndKeywords" title="Permalink to this definition">¶</a></dt>
<dd><p>Parse the parameters of a function that takes both positional and keyword
parameters into local variables. Returns true on success; on failure, it
returns false and raises the appropriate exception.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyArg_VaParseTupleAndKeywords">
int <code class="descname">PyArg_VaParseTupleAndKeywords</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *args</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *kw</em>, const char<em> *format</em>, char<em> *keywords[]</em>, va_list<em> vargs</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyArg_VaParseTupleAndKeywords" title="Permalink to this definition">¶</a></dt>
<dd><p>Identical to <a class="reference internal" href="#c.PyArg_ParseTupleAndKeywords" title="PyArg_ParseTupleAndKeywords"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_ParseTupleAndKeywords()</span></code></a>, except that it accepts a
va_list rather than a variable number of arguments.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyArg_Parse">
int <code class="descname">PyArg_Parse</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *args</em>, const char<em> *format</em>, ...<span class="sig-paren">)</span><a class="headerlink" href="#c.PyArg_Parse" title="Permalink to this definition">¶</a></dt>
<dd><p>Function used to deconstruct the argument lists of “old-style” functions
— these are functions which use the <a class="reference internal" href="structures.html#METH_OLDARGS" title="METH_OLDARGS"><code class="xref py py-const docutils literal notranslate"><span class="pre">METH_OLDARGS</span></code></a> parameter
parsing method. This is not recommended for use in parameter parsing in
new code, and most code in the standard interpreter has been modified to no
longer use this for that purpose. It does remain a convenient way to
decompose other tuples, however, and may continue to be used for that
purpose.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyArg_UnpackTuple">
int <code class="descname">PyArg_UnpackTuple</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *args</em>, const char<em> *name</em>, Py_ssize_t<em> min</em>, Py_ssize_t<em> max</em>, ...<span class="sig-paren">)</span><a class="headerlink" href="#c.PyArg_UnpackTuple" title="Permalink to this definition">¶</a></dt>
<dd><p>A simpler form of parameter retrieval which does not use a format string to
specify the types of the arguments. Functions which use this method to
retrieve their parameters should be declared as <a class="reference internal" href="structures.html#METH_VARARGS" title="METH_VARARGS"><code class="xref py py-const docutils literal notranslate"><span class="pre">METH_VARARGS</span></code></a> in
function or method tables. The tuple containing the actual parameters
should be passed as <em>args</em>; it must actually be a tuple. The length of the
tuple must be at least <em>min</em> and no more than <em>max</em>; <em>min</em> and <em>max</em> may be
equal. Additional arguments must be passed to the function, each of which
should be a pointer to a <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject*</span></code></a> variable; these will be filled
in with the values from <em>args</em>; they will contain borrowed references. The
variables which correspond to optional parameters not given by <em>args</em> will
not be filled in; these should be initialized by the caller. This function
returns true on success and false if <em>args</em> is not a tuple or contains the
wrong number of elements; an exception will be set if there was a failure.</p>
<p>This is an example of the use of this function, taken from the sources for
the <code class="xref py py-mod docutils literal notranslate"><span class="pre">_weakref</span></code> helper module for weak references:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">static</span> <span class="n">PyObject</span> <span class="o">*</span>
<span class="nf">weakref_ref</span><span class="p">(</span><span class="n">PyObject</span> <span class="o">*</span><span class="n">self</span><span class="p">,</span> <span class="n">PyObject</span> <span class="o">*</span><span class="n">args</span><span class="p">)</span>
<span class="p">{</span>
<span class="n">PyObject</span> <span class="o">*</span><span class="n">object</span><span class="p">;</span>
<span class="n">PyObject</span> <span class="o">*</span><span class="n">callback</span> <span class="o">=</span> <span class="nb">NULL</span><span class="p">;</span>
<span class="n">PyObject</span> <span class="o">*</span><span class="n">result</span> <span class="o">=</span> <span class="nb">NULL</span><span class="p">;</span>
<span class="k">if</span> <span class="p">(</span><span class="n">PyArg_UnpackTuple</span><span class="p">(</span><span class="n">args</span><span class="p">,</span> <span class="s">"ref"</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="o">&</span><span class="n">object</span><span class="p">,</span> <span class="o">&</span><span class="n">callback</span><span class="p">))</span> <span class="p">{</span>
<span class="n">result</span> <span class="o">=</span> <span class="n">PyWeakref_NewRef</span><span class="p">(</span><span class="n">object</span><span class="p">,</span> <span class="n">callback</span><span class="p">);</span>
<span class="p">}</span>
<span class="k">return</span> <span class="n">result</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
<p>The call to <a class="reference internal" href="#c.PyArg_UnpackTuple" title="PyArg_UnpackTuple"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_UnpackTuple()</span></code></a> in this example is entirely
equivalent to this call to <a class="reference internal" href="#c.PyArg_ParseTuple" title="PyArg_ParseTuple"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_ParseTuple()</span></code></a>:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">PyArg_ParseTuple</span><span class="p">(</span><span class="n">args</span><span class="p">,</span> <span class="s">"O|O:ref"</span><span class="p">,</span> <span class="o">&</span><span class="n">object</span><span class="p">,</span> <span class="o">&</span><span class="n">callback</span><span class="p">)</span>
</pre></div>
</div>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>min</em> and <em>max</em>. This might
require changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.Py_BuildValue">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">Py_BuildValue</code><span class="sig-paren">(</span>const char<em> *format</em>, ...<span class="sig-paren">)</span><a class="headerlink" href="#c.Py_BuildValue" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Create a new value based on a format string similar to those accepted by
the <a class="reference internal" href="#c.PyArg_Parse" title="PyArg_Parse"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_Parse*()</span></code></a> family of functions and a sequence of values.
Returns the value or <em>NULL</em> in the case of an error; an exception will be
raised if <em>NULL</em> is returned.</p>
<p><a class="reference internal" href="#c.Py_BuildValue" title="Py_BuildValue"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_BuildValue()</span></code></a> does not always build a tuple. It builds a tuple
only if its format string contains two or more format units. If the format
string is empty, it returns <code class="docutils literal notranslate"><span class="pre">None</span></code>; if it contains exactly one format
unit, it returns whatever object is described by that format unit. To
force it to return a tuple of size <code class="docutils literal notranslate"><span class="pre">0</span></code> or one, parenthesize the format
string.</p>
<p>When memory buffers are passed as parameters to supply data to build
objects, as for the <code class="docutils literal notranslate"><span class="pre">s</span></code> and <code class="docutils literal notranslate"><span class="pre">s#</span></code> formats, the required data is copied.
Buffers provided by the caller are never referenced by the objects created
by <a class="reference internal" href="#c.Py_BuildValue" title="Py_BuildValue"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_BuildValue()</span></code></a>. In other words, if your code invokes
<code class="xref c c-func docutils literal notranslate"><span class="pre">malloc()</span></code> and passes the allocated memory to <a class="reference internal" href="#c.Py_BuildValue" title="Py_BuildValue"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_BuildValue()</span></code></a>,
your code is responsible for calling <code class="xref c c-func docutils literal notranslate"><span class="pre">free()</span></code> for that memory once
<a class="reference internal" href="#c.Py_BuildValue" title="Py_BuildValue"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_BuildValue()</span></code></a> returns.</p>
<p>In the following description, the quoted form is the format unit; the entry
in (round) parentheses is the Python object type that the format unit will
return; and the entry in [square] brackets is the type of the C value(s) to
be passed.</p>
<p>The characters space, tab, colon and comma are ignored in format strings
(but not within format units such as <code class="docutils literal notranslate"><span class="pre">s#</span></code>). This can be used to make
long format strings a tad more readable.</p>
<dl class="docutils">
<dt><code class="docutils literal notranslate"><span class="pre">s</span></code> (string) [char *]</dt>
<dd>Convert a null-terminated C string to a Python object. If the C string
pointer is <em>NULL</em>, <code class="docutils literal notranslate"><span class="pre">None</span></code> is used.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">s#</span></code> (string) [char *, int]</dt>
<dd>Convert a C string and its length to a Python object. If the C string
pointer is <em>NULL</em>, the length is ignored and <code class="docutils literal notranslate"><span class="pre">None</span></code> is returned.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">z</span></code> (string or <code class="docutils literal notranslate"><span class="pre">None</span></code>) [char *]</dt>
<dd>Same as <code class="docutils literal notranslate"><span class="pre">s</span></code>.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">z#</span></code> (string or <code class="docutils literal notranslate"><span class="pre">None</span></code>) [char *, int]</dt>
<dd>Same as <code class="docutils literal notranslate"><span class="pre">s#</span></code>.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">u</span></code> (Unicode string) [Py_UNICODE *]</dt>
<dd>Convert a null-terminated buffer of Unicode (UCS-2 or UCS-4) data to a
Python Unicode object. If the Unicode buffer pointer is <em>NULL</em>,
<code class="docutils literal notranslate"><span class="pre">None</span></code> is returned.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">u#</span></code> (Unicode string) [Py_UNICODE *, int]</dt>
<dd>Convert a Unicode (UCS-2 or UCS-4) data buffer and its length to a
Python Unicode object. If the Unicode buffer pointer is <em>NULL</em>, the
length is ignored and <code class="docutils literal notranslate"><span class="pre">None</span></code> is returned.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">i</span></code> (integer) [int]</dt>
<dd>Convert a plain C <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> to a Python integer object.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">b</span></code> (integer) [char]</dt>
<dd>Convert a plain C <code class="xref c c-type docutils literal notranslate"><span class="pre">char</span></code> to a Python integer object.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">h</span></code> (integer) [short int]</dt>
<dd>Convert a plain C <code class="xref c c-type docutils literal notranslate"><span class="pre">short</span> <span class="pre">int</span></code> to a Python integer object.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">l</span></code> (integer) [long int]</dt>
<dd>Convert a C <code class="xref c c-type docutils literal notranslate"><span class="pre">long</span> <span class="pre">int</span></code> to a Python integer object.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">B</span></code> (integer) [unsigned char]</dt>
<dd>Convert a C <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">char</span></code> to a Python integer object.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">H</span></code> (integer) [unsigned short int]</dt>
<dd>Convert a C <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">short</span> <span class="pre">int</span></code> to a Python integer object.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">I</span></code> (integer/long) [unsigned int]</dt>
<dd>Convert a C <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">int</span></code> to a Python integer object or a Python
long integer object, if it is larger than <code class="docutils literal notranslate"><span class="pre">sys.maxint</span></code>.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">k</span></code> (integer/long) [unsigned long]</dt>
<dd>Convert a C <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">long</span></code> to a Python integer object or a
Python long integer object, if it is larger than <code class="docutils literal notranslate"><span class="pre">sys.maxint</span></code>.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">L</span></code> (long) [PY_LONG_LONG]</dt>
<dd>Convert a C <code class="xref c c-type docutils literal notranslate"><span class="pre">long</span> <span class="pre">long</span></code> to a Python long integer object. Only
available on platforms that support <code class="xref c c-type docutils literal notranslate"><span class="pre">long</span> <span class="pre">long</span></code>.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">K</span></code> (long) [unsigned PY_LONG_LONG]</dt>
<dd>Convert a C <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">long</span> <span class="pre">long</span></code> to a Python long integer object.
Only available on platforms that support <code class="xref c c-type docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">long</span> <span class="pre">long</span></code>.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">n</span></code> (int) [Py_ssize_t]</dt>
<dd><p class="first">Convert a C <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code> to a Python integer or long integer.</p>
<div class="last versionadded">
<p><span class="versionmodified">New in version 2.5.</span></p>
</div>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">c</span></code> (string of length 1) [char]</dt>
<dd>Convert a C <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> representing a character to a Python string of
length 1.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">d</span></code> (float) [double]</dt>
<dd>Convert a C <code class="xref c c-type docutils literal notranslate"><span class="pre">double</span></code> to a Python floating point number.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">f</span></code> (float) [float]</dt>
<dd>Same as <code class="docutils literal notranslate"><span class="pre">d</span></code>.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">D</span></code> (complex) [Py_complex *]</dt>
<dd>Convert a C <a class="reference internal" href="complex.html#c.Py_complex" title="Py_complex"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_complex</span></code></a> structure to a Python complex number.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">O</span></code> (object) [PyObject *]</dt>
<dd>Pass a Python object untouched (except for its reference count, which is
incremented by one). If the object passed in is a <em>NULL</em> pointer, it is
assumed that this was caused because the call producing the argument
found an error and set an exception. Therefore, <a class="reference internal" href="#c.Py_BuildValue" title="Py_BuildValue"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_BuildValue()</span></code></a>
will return <em>NULL</em> but won’t raise an exception. If no exception has
been raised yet, <a class="reference internal" href="../library/exceptions.html#exceptions.SystemError" title="exceptions.SystemError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SystemError</span></code></a> is set.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">S</span></code> (object) [PyObject *]</dt>
<dd>Same as <code class="docutils literal notranslate"><span class="pre">O</span></code>.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">N</span></code> (object) [PyObject *]</dt>
<dd>Same as <code class="docutils literal notranslate"><span class="pre">O</span></code>, except it doesn’t increment the reference count on the
object. Useful when the object is created by a call to an object
constructor in the argument list.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">O&</span></code> (object) [<em>converter</em>, <em>anything</em>]</dt>
<dd>Convert <em>anything</em> to a Python object through a <em>converter</em> function.
The function is called with <em>anything</em> (which should be compatible with
<code class="xref c c-type docutils literal notranslate"><span class="pre">void</span> <span class="pre">*</span></code>) as its argument and should return a “new” Python
object, or <em>NULL</em> if an error occurred.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">(items)</span></code> (tuple) [<em>matching-items</em>]</dt>
<dd>Convert a sequence of C values to a Python tuple with the same number of
items.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">[items]</span></code> (list) [<em>matching-items</em>]</dt>
<dd>Convert a sequence of C values to a Python list with the same number of
items.</dd>
<dt><code class="docutils literal notranslate"><span class="pre">{items}</span></code> (dictionary) [<em>matching-items</em>]</dt>
<dd>Convert a sequence of C values to a Python dictionary. Each pair of
consecutive C values adds one item to the dictionary, serving as key and
value, respectively.</dd>
</dl>
<p>If there is an error in the format string, the <a class="reference internal" href="../library/exceptions.html#exceptions.SystemError" title="exceptions.SystemError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SystemError</span></code></a> exception
is set and <em>NULL</em> returned.</p>
</dd></dl>
<dl class="function">
<dt id="c.Py_VaBuildValue">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">Py_VaBuildValue</code><span class="sig-paren">(</span>const char<em> *format</em>, va_list<em> vargs</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_VaBuildValue" title="Permalink to this definition">¶</a></dt>
<dd><p>Identical to <a class="reference internal" href="#c.Py_BuildValue" title="Py_BuildValue"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_BuildValue()</span></code></a>, except that it accepts a va_list
rather than a variable number of arguments.</p>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="marshal.html"
title="previous chapter">Data marshalling support</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="conversion.html"
title="next chapter">String conversion and formatting</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/arg.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="conversion.html" title="String conversion and formatting"
>next</a> |</li>
<li class="right" >
<a href="marshal.html" title="Data marshalling support"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="utilities.html" >Utilities</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\Tn�8)' )' html/c-api/bool.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Boolean Objects — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Long Integer Objects" href="long.html" />
<link rel="prev" title="Plain Integer Objects" href="int.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/bool.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="long.html" title="Long Integer Objects"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="int.html" title="Plain Integer Objects"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" accesskey="U">Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="boolean-objects">
<span id="boolobjects"></span><h1>Boolean Objects<a class="headerlink" href="#boolean-objects" title="Permalink to this headline">¶</a></h1>
<p>Booleans in Python are implemented as a subclass of integers. There are only
two booleans, <code class="xref py py-const docutils literal notranslate"><span class="pre">Py_False</span></code> and <code class="xref py py-const docutils literal notranslate"><span class="pre">Py_True</span></code>. As such, the normal
creation and deletion functions don’t apply to booleans. The following macros
are available, however.</p>
<dl class="function">
<dt id="c.PyBool_Check">
int <code class="descname">PyBool_Check</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyBool_Check" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if <em>o</em> is of type <code class="xref c c-data docutils literal notranslate"><span class="pre">PyBool_Type</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.3.</span></p>
</div>
</dd></dl>
<dl class="var">
<dt id="c.Py_False">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">Py_False</code><a class="headerlink" href="#c.Py_False" title="Permalink to this definition">¶</a></dt>
<dd><p>The Python <code class="docutils literal notranslate"><span class="pre">False</span></code> object. This object has no methods. It needs to be
treated just like any other object with respect to reference counts.</p>
</dd></dl>
<dl class="var">
<dt id="c.Py_True">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">Py_True</code><a class="headerlink" href="#c.Py_True" title="Permalink to this definition">¶</a></dt>
<dd><p>The Python <code class="docutils literal notranslate"><span class="pre">True</span></code> object. This object has no methods. It needs to be treated
just like any other object with respect to reference counts.</p>
</dd></dl>
<dl class="macro">
<dt id="c.Py_RETURN_FALSE">
<code class="descname">Py_RETURN_FALSE</code><a class="headerlink" href="#c.Py_RETURN_FALSE" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <code class="xref py py-const docutils literal notranslate"><span class="pre">Py_False</span></code> from a function, properly incrementing its reference
count.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
</dd></dl>
<dl class="macro">
<dt id="c.Py_RETURN_TRUE">
<code class="descname">Py_RETURN_TRUE</code><a class="headerlink" href="#c.Py_RETURN_TRUE" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <code class="xref py py-const docutils literal notranslate"><span class="pre">Py_True</span></code> from a function, properly incrementing its reference
count.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyBool_FromLong">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyBool_FromLong</code><span class="sig-paren">(</span>long<em> v</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyBool_FromLong" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a new reference to <code class="xref py py-const docutils literal notranslate"><span class="pre">Py_True</span></code> or <code class="xref py py-const docutils literal notranslate"><span class="pre">Py_False</span></code> depending on the
truth value of <em>v</em>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.3.</span></p>
</div>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="int.html"
title="previous chapter">Plain Integer Objects</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="long.html"
title="next chapter">Long Integer Objects</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/bool.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="long.html" title="Long Integer Objects"
>next</a> |</li>
<li class="right" >
<a href="int.html" title="Plain Integer Objects"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" >Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\y���g� g� html/c-api/buffer.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Buffers and Memoryview Objects — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Tuple Objects" href="tuple.html" />
<link rel="prev" title="Unicode Objects and Codecs" href="unicode.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/buffer.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="tuple.html" title="Tuple Objects"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="unicode.html" title="Unicode Objects and Codecs"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" accesskey="U">Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="buffers-and-memoryview-objects">
<span id="bufferobjects"></span><h1>Buffers and Memoryview Objects<a class="headerlink" href="#buffers-and-memoryview-objects" title="Permalink to this headline">¶</a></h1>
<p id="index-0">Python objects implemented in C can export a group of functions called the
“buffer interface.” These functions can be used by an object to expose its
data in a raw, byte-oriented format. Clients of the object can use the buffer
interface to access the object data directly, without needing to copy it
first.</p>
<p>Two examples of objects that support the buffer interface are strings and
arrays. The string object exposes the character contents in the buffer
interface’s byte-oriented form. An array can only expose its contents via the
old-style buffer interface. This limitation does not apply to Python 3,
where <a class="reference internal" href="../library/stdtypes.html#memoryview" title="memoryview"><code class="xref py py-class docutils literal notranslate"><span class="pre">memoryview</span></code></a> objects can be constructed from arrays, too.
Array elements may be multi-byte values.</p>
<p>An example user of the buffer interface is the file object’s <code class="xref py py-meth docutils literal notranslate"><span class="pre">write()</span></code>
method. Any object that can export a series of bytes through the buffer
interface can be written to a file. There are a number of format codes to
<a class="reference internal" href="arg.html#c.PyArg_ParseTuple" title="PyArg_ParseTuple"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_ParseTuple()</span></code></a> that operate against an object’s buffer interface,
returning data from the target object.</p>
<p>Starting from version 1.6, Python has been providing Python-level buffer
objects and a C-level buffer API so that any built-in or used-defined type can
expose its characteristics. Both, however, have been deprecated because of
various shortcomings, and have been officially removed in Python 3 in favour
of a new C-level buffer API and a new Python-level object named
<a class="reference internal" href="../library/stdtypes.html#memoryview" title="memoryview"><code class="xref py py-class docutils literal notranslate"><span class="pre">memoryview</span></code></a>.</p>
<p>The new buffer API has been backported to Python 2.6, and the
<a class="reference internal" href="../library/stdtypes.html#memoryview" title="memoryview"><code class="xref py py-class docutils literal notranslate"><span class="pre">memoryview</span></code></a> object has been backported to Python 2.7. It is strongly
advised to use them rather than the old APIs, unless you are blocked from
doing so for compatibility reasons.</p>
<div class="section" id="the-new-style-py-buffer-struct">
<h2>The new-style Py_buffer struct<a class="headerlink" href="#the-new-style-py-buffer-struct" title="Permalink to this headline">¶</a></h2>
<dl class="type">
<dt id="c.Py_buffer">
<code class="descname">Py_buffer</code><a class="headerlink" href="#c.Py_buffer" title="Permalink to this definition">¶</a></dt>
<dd><dl class="member">
<dt id="c.Py_buffer.buf">
void *<code class="descname">buf</code><a class="headerlink" href="#c.Py_buffer.buf" title="Permalink to this definition">¶</a></dt>
<dd><p>A pointer to the start of the memory for the object.</p>
</dd></dl>
<dl class="member">
<dt>
Py_ssize_t <code class="descname">len</code></dt>
<dd><p>The total length of the memory in bytes.</p>
</dd></dl>
<dl class="member">
<dt id="c.Py_buffer.readonly">
int <code class="descname">readonly</code><a class="headerlink" href="#c.Py_buffer.readonly" title="Permalink to this definition">¶</a></dt>
<dd><p>An indicator of whether the buffer is read only.</p>
</dd></dl>
<dl class="member">
<dt>
const char *<code class="descname">format</code></dt>
<dd><p>A <em>NULL</em> terminated string in <a class="reference internal" href="../library/struct.html#module-struct" title="struct: Interpret strings as packed binary data."><code class="xref py py-mod docutils literal notranslate"><span class="pre">struct</span></code></a> module style syntax giving
the contents of the elements available through the buffer. If this is
<em>NULL</em>, <code class="docutils literal notranslate"><span class="pre">"B"</span></code> (unsigned bytes) is assumed.</p>
</dd></dl>
<dl class="member">
<dt id="c.Py_buffer.ndim">
int <code class="descname">ndim</code><a class="headerlink" href="#c.Py_buffer.ndim" title="Permalink to this definition">¶</a></dt>
<dd><p>The number of dimensions the memory represents as a multi-dimensional
array. If it is <code class="docutils literal notranslate"><span class="pre">0</span></code>, <code class="xref c c-data docutils literal notranslate"><span class="pre">strides</span></code> and <code class="xref c c-data docutils literal notranslate"><span class="pre">suboffsets</span></code> must be
<em>NULL</em>.</p>
</dd></dl>
<dl class="member">
<dt id="c.Py_buffer.shape">
Py_ssize_t *<code class="descname">shape</code><a class="headerlink" href="#c.Py_buffer.shape" title="Permalink to this definition">¶</a></dt>
<dd><p>An array of <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code>s the length of <code class="xref c c-data docutils literal notranslate"><span class="pre">ndim</span></code> giving the
shape of the memory as a multi-dimensional array. Note that
<code class="docutils literal notranslate"><span class="pre">((*shape)[0]</span> <span class="pre">*</span> <span class="pre">...</span> <span class="pre">*</span> <span class="pre">(*shape)[ndims-1])*itemsize</span></code> should be equal to
<code class="xref c c-data docutils literal notranslate"><span class="pre">len</span></code>.</p>
</dd></dl>
<dl class="member">
<dt id="c.Py_buffer.strides">
Py_ssize_t *<code class="descname">strides</code><a class="headerlink" href="#c.Py_buffer.strides" title="Permalink to this definition">¶</a></dt>
<dd><p>An array of <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code>s the length of <code class="xref c c-data docutils literal notranslate"><span class="pre">ndim</span></code> giving the
number of bytes to skip to get to a new element in each dimension.</p>
</dd></dl>
<dl class="member">
<dt id="c.Py_buffer.suboffsets">
Py_ssize_t *<code class="descname">suboffsets</code><a class="headerlink" href="#c.Py_buffer.suboffsets" title="Permalink to this definition">¶</a></dt>
<dd><p>An array of <code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code>s the length of <code class="xref c c-data docutils literal notranslate"><span class="pre">ndim</span></code>. If these
suboffset numbers are greater than or equal to 0, then the value stored
along the indicated dimension is a pointer and the suboffset value
dictates how many bytes to add to the pointer after de-referencing. A
suboffset value that it negative indicates that no de-referencing should
occur (striding in a contiguous memory block).</p>
<p>If all suboffsets are negative (i.e. no de-referencing is needed), then
this field must be NULL (the default value).</p>
<p>Here is a function that returns a pointer to the element in an N-D array
pointed to by an N-dimensional index when there are both non-NULL strides
and suboffsets:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="o">*</span><span class="nf">get_item_pointer</span><span class="p">(</span><span class="kt">int</span> <span class="n">ndim</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="n">buf</span><span class="p">,</span> <span class="n">Py_ssize_t</span> <span class="o">*</span><span class="n">strides</span><span class="p">,</span>
<span class="n">Py_ssize_t</span> <span class="o">*</span><span class="n">suboffsets</span><span class="p">,</span> <span class="n">Py_ssize_t</span> <span class="o">*</span><span class="n">indices</span><span class="p">)</span> <span class="p">{</span>
<span class="kt">char</span> <span class="o">*</span><span class="n">pointer</span> <span class="o">=</span> <span class="p">(</span><span class="kt">char</span><span class="o">*</span><span class="p">)</span><span class="n">buf</span><span class="p">;</span>
<span class="kt">int</span> <span class="n">i</span><span class="p">;</span>
<span class="k">for</span> <span class="p">(</span><span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">ndim</span><span class="p">;</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span> <span class="p">{</span>
<span class="n">pointer</span> <span class="o">+=</span> <span class="n">strides</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">*</span> <span class="n">indices</span><span class="p">[</span><span class="n">i</span><span class="p">];</span>
<span class="k">if</span> <span class="p">(</span><span class="n">suboffsets</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">>=</span><span class="mi">0</span> <span class="p">)</span> <span class="p">{</span>
<span class="n">pointer</span> <span class="o">=</span> <span class="o">*</span><span class="p">((</span><span class="kt">char</span><span class="o">**</span><span class="p">)</span><span class="n">pointer</span><span class="p">)</span> <span class="o">+</span> <span class="n">suboffsets</span><span class="p">[</span><span class="n">i</span><span class="p">];</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="k">return</span> <span class="p">(</span><span class="kt">void</span><span class="o">*</span><span class="p">)</span><span class="n">pointer</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
</dd></dl>
<dl class="member">
<dt id="c.Py_buffer.itemsize">
Py_ssize_t <code class="descname">itemsize</code><a class="headerlink" href="#c.Py_buffer.itemsize" title="Permalink to this definition">¶</a></dt>
<dd><p>This is a storage for the itemsize (in bytes) of each element of the
shared memory. It is technically un-necessary as it can be obtained
using <a class="reference internal" href="#c.PyBuffer_SizeFromFormat" title="PyBuffer_SizeFromFormat"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyBuffer_SizeFromFormat()</span></code></a>, however an exporter may know
this information without parsing the format string and it is necessary
to know the itemsize for proper interpretation of striding. Therefore,
storing it is more convenient and faster.</p>
</dd></dl>
<dl class="member">
<dt id="c.Py_buffer.internal">
void *<code class="descname">internal</code><a class="headerlink" href="#c.Py_buffer.internal" title="Permalink to this definition">¶</a></dt>
<dd><p>This is for use internally by the exporting object. For example, this
might be re-cast as an integer by the exporter and used to store flags
about whether or not the shape, strides, and suboffsets arrays must be
freed when the buffer is released. The consumer should never alter this
value.</p>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="buffer-related-functions">
<h2>Buffer related functions<a class="headerlink" href="#buffer-related-functions" title="Permalink to this headline">¶</a></h2>
<dl class="function">
<dt id="c.PyObject_CheckBuffer">
int <code class="descname">PyObject_CheckBuffer</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *obj</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_CheckBuffer" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">1</span></code> if <em>obj</em> supports the buffer interface otherwise <code class="docutils literal notranslate"><span class="pre">0</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_GetBuffer">
int <code class="descname">PyObject_GetBuffer</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *obj</em>, <a class="reference internal" href="#c.Py_buffer" title="Py_buffer">Py_buffer</a><em> *view</em>, int<em> flags</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_GetBuffer" title="Permalink to this definition">¶</a></dt>
<dd><p>Export <em>obj</em> into a <a class="reference internal" href="#c.Py_buffer" title="Py_buffer"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_buffer</span></code></a>, <em>view</em>. These arguments must
never be <em>NULL</em>. The <em>flags</em> argument is a bit field indicating what
kind of buffer the caller is prepared to deal with and therefore what
kind of buffer the exporter is allowed to return. The buffer interface
allows for complicated memory sharing possibilities, but some caller may
not be able to handle all the complexity but may want to see if the
exporter will let them take a simpler view to its memory.</p>
<p>Some exporters may not be able to share memory in every possible way and
may need to raise errors to signal to some consumers that something is
just not possible. These errors should be a <a class="reference internal" href="../library/exceptions.html#exceptions.BufferError" title="exceptions.BufferError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">BufferError</span></code></a> unless
there is another error that is actually causing the problem. The
exporter can use flags information to simplify how much of the
<a class="reference internal" href="#c.Py_buffer" title="Py_buffer"><code class="xref c c-data docutils literal notranslate"><span class="pre">Py_buffer</span></code></a> structure is filled in with non-default values and/or
raise an error if the object can’t support a simpler view of its memory.</p>
<p><code class="docutils literal notranslate"><span class="pre">0</span></code> is returned on success and <code class="docutils literal notranslate"><span class="pre">-1</span></code> on error.</p>
<p>The following table gives possible values to the <em>flags</em> arguments.</p>
<table border="1" class="docutils">
<colgroup>
<col width="38%" />
<col width="62%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Flag</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="xref c c-macro docutils literal notranslate"><span class="pre">PyBUF_SIMPLE</span></code></td>
<td>This is the default flag state. The returned
buffer may or may not have writable memory. The
format of the data will be assumed to be unsigned
bytes. This is a “stand-alone” flag constant. It
never needs to be ‘|’d to the others. The exporter
will raise an error if it cannot provide such a
contiguous buffer of bytes.</td>
</tr>
<tr class="row-odd"><td><code class="xref c c-macro docutils literal notranslate"><span class="pre">PyBUF_WRITABLE</span></code></td>
<td>The returned buffer must be writable. If it is
not writable, then raise an error.</td>
</tr>
<tr class="row-even"><td><code class="xref c c-macro docutils literal notranslate"><span class="pre">PyBUF_STRIDES</span></code></td>
<td>This implies <code class="xref c c-macro docutils literal notranslate"><span class="pre">PyBUF_ND</span></code>. The returned
buffer must provide strides information (i.e. the
strides cannot be NULL). This would be used when
the consumer can handle strided, discontiguous
arrays. Handling strides automatically assumes
you can handle shape. The exporter can raise an
error if a strided representation of the data is
not possible (i.e. without the suboffsets).</td>
</tr>
<tr class="row-odd"><td><code class="xref c c-macro docutils literal notranslate"><span class="pre">PyBUF_ND</span></code></td>
<td>The returned buffer must provide shape
information. The memory will be assumed C-style
contiguous (last dimension varies the
fastest). The exporter may raise an error if it
cannot provide this kind of contiguous buffer. If
this is not given then shape will be <em>NULL</em>.</td>
</tr>
<tr class="row-even"><td><code class="xref c c-macro docutils literal notranslate"><span class="pre">PyBUF_C_CONTIGUOUS</span></code>
<code class="xref c c-macro docutils literal notranslate"><span class="pre">PyBUF_F_CONTIGUOUS</span></code>
<code class="xref c c-macro docutils literal notranslate"><span class="pre">PyBUF_ANY_CONTIGUOUS</span></code></td>
<td>These flags indicate that the contiguity returned
buffer must be respectively, C-contiguous (last
dimension varies the fastest), Fortran contiguous
(first dimension varies the fastest) or either
one. All of these flags imply
<code class="xref c c-macro docutils literal notranslate"><span class="pre">PyBUF_STRIDES</span></code> and guarantee that the
strides buffer info structure will be filled in
correctly.</td>
</tr>
<tr class="row-odd"><td><code class="xref c c-macro docutils literal notranslate"><span class="pre">PyBUF_INDIRECT</span></code></td>
<td>This flag indicates the returned buffer must have
suboffsets information (which can be NULL if no
suboffsets are needed). This can be used when
the consumer can handle indirect array
referencing implied by these suboffsets. This
implies <code class="xref c c-macro docutils literal notranslate"><span class="pre">PyBUF_STRIDES</span></code>.</td>
</tr>
<tr class="row-even"><td><code class="xref c c-macro docutils literal notranslate"><span class="pre">PyBUF_FORMAT</span></code></td>
<td>The returned buffer must have true format
information if this flag is provided. This would
be used when the consumer is going to be checking
for what ‘kind’ of data is actually stored. An
exporter should always be able to provide this
information if requested. If format is not
explicitly requested then the format must be
returned as <em>NULL</em> (which means <code class="docutils literal notranslate"><span class="pre">'B'</span></code>, or
unsigned bytes)</td>
</tr>
<tr class="row-odd"><td><code class="xref c c-macro docutils literal notranslate"><span class="pre">PyBUF_STRIDED</span></code></td>
<td>This is equivalent to <code class="docutils literal notranslate"><span class="pre">(PyBUF_STRIDES</span> <span class="pre">|</span>
<span class="pre">PyBUF_WRITABLE)</span></code>.</td>
</tr>
<tr class="row-even"><td><code class="xref c c-macro docutils literal notranslate"><span class="pre">PyBUF_STRIDED_RO</span></code></td>
<td>This is equivalent to <code class="docutils literal notranslate"><span class="pre">(PyBUF_STRIDES)</span></code>.</td>
</tr>
<tr class="row-odd"><td><code class="xref c c-macro docutils literal notranslate"><span class="pre">PyBUF_RECORDS</span></code></td>
<td>This is equivalent to <code class="docutils literal notranslate"><span class="pre">(PyBUF_STRIDES</span> <span class="pre">|</span>
<span class="pre">PyBUF_FORMAT</span> <span class="pre">|</span> <span class="pre">PyBUF_WRITABLE)</span></code>.</td>
</tr>
<tr class="row-even"><td><code class="xref c c-macro docutils literal notranslate"><span class="pre">PyBUF_RECORDS_RO</span></code></td>
<td>This is equivalent to <code class="docutils literal notranslate"><span class="pre">(PyBUF_STRIDES</span> <span class="pre">|</span>
<span class="pre">PyBUF_FORMAT)</span></code>.</td>
</tr>
<tr class="row-odd"><td><code class="xref c c-macro docutils literal notranslate"><span class="pre">PyBUF_FULL</span></code></td>
<td>This is equivalent to <code class="docutils literal notranslate"><span class="pre">(PyBUF_INDIRECT</span> <span class="pre">|</span>
<span class="pre">PyBUF_FORMAT</span> <span class="pre">|</span> <span class="pre">PyBUF_WRITABLE)</span></code>.</td>
</tr>
<tr class="row-even"><td><code class="xref c c-macro docutils literal notranslate"><span class="pre">PyBUF_FULL_RO</span></code></td>
<td>This is equivalent to <code class="docutils literal notranslate"><span class="pre">(PyBUF_INDIRECT</span> <span class="pre">|</span>
<span class="pre">PyBUF_FORMAT)</span></code>.</td>
</tr>
<tr class="row-odd"><td><code class="xref c c-macro docutils literal notranslate"><span class="pre">PyBUF_CONTIG</span></code></td>
<td>This is equivalent to <code class="docutils literal notranslate"><span class="pre">(PyBUF_ND</span> <span class="pre">|</span>
<span class="pre">PyBUF_WRITABLE)</span></code>.</td>
</tr>
<tr class="row-even"><td><code class="xref c c-macro docutils literal notranslate"><span class="pre">PyBUF_CONTIG_RO</span></code></td>
<td>This is equivalent to <code class="docutils literal notranslate"><span class="pre">(PyBUF_ND)</span></code>.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="function">
<dt id="c.PyBuffer_Release">
void <code class="descname">PyBuffer_Release</code><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_buffer" title="Py_buffer">Py_buffer</a><em> *view</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyBuffer_Release" title="Permalink to this definition">¶</a></dt>
<dd><p>Release the buffer <em>view</em>. This should be called when the buffer
is no longer being used as it may free memory from it.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyBuffer_SizeFromFormat">
Py_ssize_t <code class="descname">PyBuffer_SizeFromFormat</code><span class="sig-paren">(</span>const char<em> *</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyBuffer_SizeFromFormat" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the implied <a class="reference internal" href="#c.Py_buffer.itemsize" title="Py_buffer.itemsize"><code class="xref c c-data docutils literal notranslate"><span class="pre">itemsize</span></code></a> from the struct-stype
<code class="xref c c-data docutils literal notranslate"><span class="pre">format</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyBuffer_IsContiguous">
int <code class="descname">PyBuffer_IsContiguous</code><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_buffer" title="Py_buffer">Py_buffer</a><em> *view</em>, char<em> fortran</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyBuffer_IsContiguous" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">1</span></code> if the memory defined by the <em>view</em> is C-style (<em>fortran</em> is
<code class="docutils literal notranslate"><span class="pre">'C'</span></code>) or Fortran-style (<em>fortran</em> is <code class="docutils literal notranslate"><span class="pre">'F'</span></code>) contiguous or either one
(<em>fortran</em> is <code class="docutils literal notranslate"><span class="pre">'A'</span></code>). Return <code class="docutils literal notranslate"><span class="pre">0</span></code> otherwise.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyBuffer_FillContiguousStrides">
void <code class="descname">PyBuffer_FillContiguousStrides</code><span class="sig-paren">(</span>int<em> ndims</em>, Py_ssize_t<em> *shape</em>, Py_ssize_t<em> *strides</em>, int<em> itemsize</em>, char<em> fortran</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyBuffer_FillContiguousStrides" title="Permalink to this definition">¶</a></dt>
<dd><p>Fill the <em>strides</em> array with byte-strides of a contiguous (C-style if
<em>fortran</em> is <code class="docutils literal notranslate"><span class="pre">'C'</span></code> or Fortran-style if <em>fortran</em> is <code class="docutils literal notranslate"><span class="pre">'F'</span></code>) array of the
given shape with the given number of bytes per element.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyBuffer_FillInfo">
int <code class="descname">PyBuffer_FillInfo</code><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_buffer" title="Py_buffer">Py_buffer</a><em> *view</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *obj</em>, void<em> *buf</em>, Py_ssize_t<em> len</em>, int<em> readonly</em>, int<em> infoflags</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyBuffer_FillInfo" title="Permalink to this definition">¶</a></dt>
<dd><p>Fill in a buffer-info structure, <em>view</em>, correctly for an exporter that can
only share a contiguous chunk of memory of “unsigned bytes” of the given
length. Return <code class="docutils literal notranslate"><span class="pre">0</span></code> on success and <code class="docutils literal notranslate"><span class="pre">-1</span></code> (with raising an error) on error.</p>
</dd></dl>
</div>
<div class="section" id="memoryview-objects">
<h2>MemoryView objects<a class="headerlink" href="#memoryview-objects" title="Permalink to this headline">¶</a></h2>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.7.</span></p>
</div>
<p>A <a class="reference internal" href="../library/stdtypes.html#memoryview" title="memoryview"><code class="xref py py-class docutils literal notranslate"><span class="pre">memoryview</span></code></a> object exposes the new C level buffer interface as a
Python object which can then be passed around like any other object.</p>
<dl class="function">
<dt id="c.PyMemoryView_FromObject">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *<code class="descname">PyMemoryView_FromObject</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *obj</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyMemoryView_FromObject" title="Permalink to this definition">¶</a></dt>
<dd><p>Create a memoryview object from an object that defines the new buffer
interface.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyMemoryView_FromBuffer">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *<code class="descname">PyMemoryView_FromBuffer</code><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_buffer" title="Py_buffer">Py_buffer</a><em> *view</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyMemoryView_FromBuffer" title="Permalink to this definition">¶</a></dt>
<dd><p>Create a memoryview object wrapping the given buffer-info structure <em>view</em>.
The memoryview object then owns the buffer, which means you shouldn’t
try to release it yourself: it will be released on deallocation of the
memoryview object.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyMemoryView_GetContiguous">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a> *<code class="descname">PyMemoryView_GetContiguous</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *obj</em>, int<em> buffertype</em>, char<em> order</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyMemoryView_GetContiguous" title="Permalink to this definition">¶</a></dt>
<dd><p>Create a memoryview object to a contiguous chunk of memory (in either
‘C’ or ‘F’ortran <em>order</em>) from an object that defines the buffer
interface. If memory is contiguous, the memoryview object points to the
original memory. Otherwise copy is made and the memoryview points to a
new bytes object.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyMemoryView_Check">
int <code class="descname">PyMemoryView_Check</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *obj</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyMemoryView_Check" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if the object <em>obj</em> is a memoryview object. It is not
currently allowed to create subclasses of <a class="reference internal" href="../library/stdtypes.html#memoryview" title="memoryview"><code class="xref py py-class docutils literal notranslate"><span class="pre">memoryview</span></code></a>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyMemoryView_GET_BUFFER">
<a class="reference internal" href="#c.Py_buffer" title="Py_buffer">Py_buffer</a> *<code class="descname">PyMemoryView_GET_BUFFER</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *obj</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyMemoryView_GET_BUFFER" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a pointer to the buffer-info structure wrapped by the given
object. The object <strong>must</strong> be a memoryview instance; this macro doesn’t
check its type, you must do it yourself or you will risk crashes.</p>
</dd></dl>
</div>
<div class="section" id="old-style-buffer-objects">
<h2>Old-style buffer objects<a class="headerlink" href="#old-style-buffer-objects" title="Permalink to this headline">¶</a></h2>
<p id="index-1">More information on the old buffer interface is provided in the section
<a class="reference internal" href="typeobj.html#buffer-structs"><span class="std std-ref">Buffer Object Structures</span></a>, under the description for <a class="reference internal" href="typeobj.html#c.PyBufferProcs" title="PyBufferProcs"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyBufferProcs</span></code></a>.</p>
<p>A “buffer object” is defined in the <code class="file docutils literal notranslate"><span class="pre">bufferobject.h</span></code> header (included by
<code class="file docutils literal notranslate"><span class="pre">Python.h</span></code>). These objects look very similar to string objects at the
Python programming level: they support slicing, indexing, concatenation, and
some other standard string operations. However, their data can come from one
of two sources: from a block of memory, or from another object which exports
the buffer interface.</p>
<p>Buffer objects are useful as a way to expose the data from another object’s
buffer interface to the Python programmer. They can also be used as a
zero-copy slicing mechanism. Using their ability to reference a block of
memory, it is possible to expose any data to the Python programmer quite
easily. The memory could be a large, constant array in a C extension, it could
be a raw block of memory for manipulation before passing to an operating
system library, or it could be used to pass around structured data in its
native, in-memory format.</p>
<dl class="type">
<dt id="c.PyBufferObject">
<code class="descname">PyBufferObject</code><a class="headerlink" href="#c.PyBufferObject" title="Permalink to this definition">¶</a></dt>
<dd><p>This subtype of <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject</span></code></a> represents a buffer object.</p>
</dd></dl>
<dl class="var">
<dt id="c.PyBuffer_Type">
<a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a> <code class="descname">PyBuffer_Type</code><a class="headerlink" href="#c.PyBuffer_Type" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-2">The instance of <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyTypeObject</span></code></a> which represents the Python buffer type;
it is the same object as <code class="docutils literal notranslate"><span class="pre">buffer</span></code> and <code class="docutils literal notranslate"><span class="pre">types.BufferType</span></code> in the Python
layer. .</p>
</dd></dl>
<dl class="var">
<dt id="c.Py_END_OF_BUFFER">
int <code class="descname">Py_END_OF_BUFFER</code><a class="headerlink" href="#c.Py_END_OF_BUFFER" title="Permalink to this definition">¶</a></dt>
<dd><p>This constant may be passed as the <em>size</em> parameter to
<a class="reference internal" href="#c.PyBuffer_FromObject" title="PyBuffer_FromObject"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyBuffer_FromObject()</span></code></a> or <a class="reference internal" href="#c.PyBuffer_FromReadWriteObject" title="PyBuffer_FromReadWriteObject"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyBuffer_FromReadWriteObject()</span></code></a>. It
indicates that the new <a class="reference internal" href="#c.PyBufferObject" title="PyBufferObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyBufferObject</span></code></a> should refer to <em>base</em>
object from the specified <em>offset</em> to the end of its exported buffer.
Using this enables the caller to avoid querying the <em>base</em> object for its
length.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyBuffer_Check">
int <code class="descname">PyBuffer_Check</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyBuffer_Check" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if the argument has type <a class="reference internal" href="#c.PyBuffer_Type" title="PyBuffer_Type"><code class="xref c c-data docutils literal notranslate"><span class="pre">PyBuffer_Type</span></code></a>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyBuffer_FromObject">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyBuffer_FromObject</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *base</em>, Py_ssize_t<em> offset</em>, Py_ssize_t<em> size</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyBuffer_FromObject" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a new read-only buffer object. This raises <a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> if
<em>base</em> doesn’t support the read-only buffer protocol or doesn’t provide
exactly one buffer segment, or it raises <a class="reference internal" href="../library/exceptions.html#exceptions.ValueError" title="exceptions.ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> if <em>offset</em> is
less than zero. The buffer will hold a reference to the <em>base</em> object, and
the buffer’s contents will refer to the <em>base</em> object’s buffer interface,
starting as position <em>offset</em> and extending for <em>size</em> bytes. If <em>size</em> is
<code class="xref py py-const docutils literal notranslate"><span class="pre">Py_END_OF_BUFFER</span></code>, then the new buffer’s contents extend to the
length of the <em>base</em> object’s exported buffer data.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>offset</em> and <em>size</em>. This
might require changes in your code for properly supporting 64-bit
systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyBuffer_FromReadWriteObject">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyBuffer_FromReadWriteObject</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *base</em>, Py_ssize_t<em> offset</em>, Py_ssize_t<em> size</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyBuffer_FromReadWriteObject" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a new writable buffer object. Parameters and exceptions are similar
to those for <a class="reference internal" href="#c.PyBuffer_FromObject" title="PyBuffer_FromObject"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyBuffer_FromObject()</span></code></a>. If the <em>base</em> object does not
export the writeable buffer protocol, then <a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> is raised.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>offset</em> and <em>size</em>. This
might require changes in your code for properly supporting 64-bit
systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyBuffer_FromMemory">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyBuffer_FromMemory</code><span class="sig-paren">(</span>void<em> *ptr</em>, Py_ssize_t<em> size</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyBuffer_FromMemory" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a new read-only buffer object that reads from a specified location
in memory, with a specified size. The caller is responsible for ensuring
that the memory buffer, passed in as <em>ptr</em>, is not deallocated while the
returned buffer object exists. Raises <a class="reference internal" href="../library/exceptions.html#exceptions.ValueError" title="exceptions.ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> if <em>size</em> is less
than zero. Note that <code class="xref py py-const docutils literal notranslate"><span class="pre">Py_END_OF_BUFFER</span></code> may <em>not</em> be passed for the
<em>size</em> parameter; <a class="reference internal" href="../library/exceptions.html#exceptions.ValueError" title="exceptions.ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> will be raised in that case.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>size</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyBuffer_FromReadWriteMemory">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyBuffer_FromReadWriteMemory</code><span class="sig-paren">(</span>void<em> *ptr</em>, Py_ssize_t<em> size</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyBuffer_FromReadWriteMemory" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Similar to <a class="reference internal" href="#c.PyBuffer_FromMemory" title="PyBuffer_FromMemory"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyBuffer_FromMemory()</span></code></a>, but the returned buffer is
writable.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>size</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyBuffer_New">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyBuffer_New</code><span class="sig-paren">(</span>Py_ssize_t<em> size</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyBuffer_New" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a new writable buffer object that maintains its own memory buffer of
<em>size</em> bytes. <a class="reference internal" href="../library/exceptions.html#exceptions.ValueError" title="exceptions.ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> is returned if <em>size</em> is not zero or
positive. Note that the memory buffer (as returned by
<a class="reference internal" href="objbuffer.html#c.PyObject_AsWriteBuffer" title="PyObject_AsWriteBuffer"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_AsWriteBuffer()</span></code></a>) is not specifically aligned.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>size</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Buffers and Memoryview Objects</a><ul>
<li><a class="reference internal" href="#the-new-style-py-buffer-struct">The new-style Py_buffer struct</a></li>
<li><a class="reference internal" href="#buffer-related-functions">Buffer related functions</a></li>
<li><a class="reference internal" href="#memoryview-objects">MemoryView objects</a></li>
<li><a class="reference internal" href="#old-style-buffer-objects">Old-style buffer objects</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="unicode.html"
title="previous chapter">Unicode Objects and Codecs</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="tuple.html"
title="next chapter">Tuple Objects</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/buffer.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="tuple.html" title="Tuple Objects"
>next</a> |</li>
<li class="right" >
<a href="unicode.html" title="Unicode Objects and Codecs"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" >Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\��1�}7 }7 html/c-api/bytearray.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Byte Array Objects — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="String/Bytes Objects" href="string.html" />
<link rel="prev" title="Complex Number Objects" href="complex.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/bytearray.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="string.html" title="String/Bytes Objects"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="complex.html" title="Complex Number Objects"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" accesskey="U">Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="byte-array-objects">
<span id="bytearrayobjects"></span><h1>Byte Array Objects<a class="headerlink" href="#byte-array-objects" title="Permalink to this headline">¶</a></h1>
<div class="versionadded" id="index-0">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
<dl class="type">
<dt id="c.PyByteArrayObject">
<code class="descname">PyByteArrayObject</code><a class="headerlink" href="#c.PyByteArrayObject" title="Permalink to this definition">¶</a></dt>
<dd><p>This subtype of <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject</span></code></a> represents a Python bytearray object.</p>
</dd></dl>
<dl class="var">
<dt id="c.PyByteArray_Type">
<a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a> <code class="descname">PyByteArray_Type</code><a class="headerlink" href="#c.PyByteArray_Type" title="Permalink to this definition">¶</a></dt>
<dd><p>This instance of <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyTypeObject</span></code></a> represents the Python bytearray type;
it is the same object as <code class="docutils literal notranslate"><span class="pre">bytearray</span></code> in the Python layer.</p>
</dd></dl>
<div class="section" id="type-check-macros">
<h2>Type check macros<a class="headerlink" href="#type-check-macros" title="Permalink to this headline">¶</a></h2>
<dl class="function">
<dt id="c.PyByteArray_Check">
int <code class="descname">PyByteArray_Check</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyByteArray_Check" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if the object <em>o</em> is a bytearray object or an instance of a
subtype of the bytearray type.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyByteArray_CheckExact">
int <code class="descname">PyByteArray_CheckExact</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyByteArray_CheckExact" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if the object <em>o</em> is a bytearray object, but not an instance of a
subtype of the bytearray type.</p>
</dd></dl>
</div>
<div class="section" id="direct-api-functions">
<h2>Direct API functions<a class="headerlink" href="#direct-api-functions" title="Permalink to this headline">¶</a></h2>
<dl class="function">
<dt id="c.PyByteArray_FromObject">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyByteArray_FromObject</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyByteArray_FromObject" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a new bytearray object from any object, <em>o</em>, that implements the
buffer protocol.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyByteArray_FromStringAndSize">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyByteArray_FromStringAndSize</code><span class="sig-paren">(</span>const char<em> *string</em>, Py_ssize_t<em> len</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyByteArray_FromStringAndSize" title="Permalink to this definition">¶</a></dt>
<dd><p>Create a new bytearray object from <em>string</em> and its length, <em>len</em>. On
failure, <em>NULL</em> is returned.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyByteArray_Concat">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyByteArray_Concat</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *a</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *b</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyByteArray_Concat" title="Permalink to this definition">¶</a></dt>
<dd><p>Concat bytearrays <em>a</em> and <em>b</em> and return a new bytearray with the result.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyByteArray_Size">
Py_ssize_t <code class="descname">PyByteArray_Size</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *bytearray</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyByteArray_Size" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the size of <em>bytearray</em> after checking for a <em>NULL</em> pointer.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyByteArray_AsString">
char* <code class="descname">PyByteArray_AsString</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *bytearray</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyByteArray_AsString" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the contents of <em>bytearray</em> as a char array after checking for a
<em>NULL</em> pointer.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyByteArray_Resize">
int <code class="descname">PyByteArray_Resize</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *bytearray</em>, Py_ssize_t<em> len</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyByteArray_Resize" title="Permalink to this definition">¶</a></dt>
<dd><p>Resize the internal buffer of <em>bytearray</em> to <em>len</em>.</p>
</dd></dl>
</div>
<div class="section" id="macros">
<h2>Macros<a class="headerlink" href="#macros" title="Permalink to this headline">¶</a></h2>
<p>These macros trade safety for speed and they don’t check pointers.</p>
<dl class="function">
<dt id="c.PyByteArray_AS_STRING">
char* <code class="descname">PyByteArray_AS_STRING</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *bytearray</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyByteArray_AS_STRING" title="Permalink to this definition">¶</a></dt>
<dd><p>Macro version of <a class="reference internal" href="#c.PyByteArray_AsString" title="PyByteArray_AsString"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyByteArray_AsString()</span></code></a>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyByteArray_GET_SIZE">
Py_ssize_t <code class="descname">PyByteArray_GET_SIZE</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *bytearray</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyByteArray_GET_SIZE" title="Permalink to this definition">¶</a></dt>
<dd><p>Macro version of <a class="reference internal" href="#c.PyByteArray_Size" title="PyByteArray_Size"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyByteArray_Size()</span></code></a>.</p>
</dd></dl>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Byte Array Objects</a><ul>
<li><a class="reference internal" href="#type-check-macros">Type check macros</a></li>
<li><a class="reference internal" href="#direct-api-functions">Direct API functions</a></li>
<li><a class="reference internal" href="#macros">Macros</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="complex.html"
title="previous chapter">Complex Number Objects</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="string.html"
title="next chapter">String/Bytes Objects</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/bytearray.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="string.html" title="String/Bytes Objects"
>next</a> |</li>
<li class="right" >
<a href="complex.html" title="Complex Number Objects"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" >Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\��o�Q �Q html/c-api/capsule.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Capsules — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="CObjects" href="cobject.html" />
<link rel="prev" title="Weak Reference Objects" href="weakref.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/capsule.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="cobject.html" title="CObjects"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="weakref.html" title="Weak Reference Objects"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" accesskey="U">Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="capsules">
<span id="id1"></span><h1>Capsules<a class="headerlink" href="#capsules" title="Permalink to this headline">¶</a></h1>
<p id="index-0">Refer to <a class="reference internal" href="../extending/extending.html#using-capsules"><span class="std std-ref">Providing a C API for an Extension Module</span></a> for more information on using these objects.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.7.</span></p>
</div>
<dl class="type">
<dt id="c.PyCapsule">
<code class="descname">PyCapsule</code><a class="headerlink" href="#c.PyCapsule" title="Permalink to this definition">¶</a></dt>
<dd><p>This subtype of <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject</span></code></a> represents an opaque value, useful for C
extension modules who need to pass an opaque value (as a <code class="xref c c-type docutils literal notranslate"><span class="pre">void*</span></code>
pointer) through Python code to other C code. It is often used to make a C
function pointer defined in one module available to other modules, so the
regular import mechanism can be used to access C APIs defined in dynamically
loaded modules.</p>
</dd></dl>
<dl class="type">
<dt id="c.PyCapsule_Destructor">
<code class="descname">PyCapsule_Destructor</code><a class="headerlink" href="#c.PyCapsule_Destructor" title="Permalink to this definition">¶</a></dt>
<dd><p>The type of a destructor callback for a capsule. Defined as:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">typedef</span> <span class="nf">void</span> <span class="p">(</span><span class="o">*</span><span class="n">PyCapsule_Destructor</span><span class="p">)(</span><span class="n">PyObject</span> <span class="o">*</span><span class="p">);</span>
</pre></div>
</div>
<p>See <a class="reference internal" href="#c.PyCapsule_New" title="PyCapsule_New"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyCapsule_New()</span></code></a> for the semantics of PyCapsule_Destructor
callbacks.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyCapsule_CheckExact">
int <code class="descname">PyCapsule_CheckExact</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCapsule_CheckExact" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if its argument is a <a class="reference internal" href="#c.PyCapsule" title="PyCapsule"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyCapsule</span></code></a>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyCapsule_New">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyCapsule_New</code><span class="sig-paren">(</span>void<em> *pointer</em>, const char<em> *name</em>, <a class="reference internal" href="#c.PyCapsule_Destructor" title="PyCapsule_Destructor">PyCapsule_Destructor</a><em> destructor</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCapsule_New" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Create a <a class="reference internal" href="#c.PyCapsule" title="PyCapsule"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyCapsule</span></code></a> encapsulating the <em>pointer</em>. The <em>pointer</em>
argument may not be <em>NULL</em>.</p>
<p>On failure, set an exception and return <em>NULL</em>.</p>
<p>The <em>name</em> string may either be <em>NULL</em> or a pointer to a valid C string. If
non-<em>NULL</em>, this string must outlive the capsule. (Though it is permitted to
free it inside the <em>destructor</em>.)</p>
<p>If the <em>destructor</em> argument is not <em>NULL</em>, it will be called with the
capsule as its argument when it is destroyed.</p>
<p>If this capsule will be stored as an attribute of a module, the <em>name</em> should
be specified as <code class="docutils literal notranslate"><span class="pre">modulename.attributename</span></code>. This will enable other modules
to import the capsule using <a class="reference internal" href="#c.PyCapsule_Import" title="PyCapsule_Import"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyCapsule_Import()</span></code></a>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyCapsule_GetPointer">
void* <code class="descname">PyCapsule_GetPointer</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *capsule</em>, const char<em> *name</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCapsule_GetPointer" title="Permalink to this definition">¶</a></dt>
<dd><p>Retrieve the <em>pointer</em> stored in the capsule. On failure, set an exception
and return <em>NULL</em>.</p>
<p>The <em>name</em> parameter must compare exactly to the name stored in the capsule.
If the name stored in the capsule is <em>NULL</em>, the <em>name</em> passed in must also
be <em>NULL</em>. Python uses the C function <code class="xref c c-func docutils literal notranslate"><span class="pre">strcmp()</span></code> to compare capsule
names.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyCapsule_GetDestructor">
<a class="reference internal" href="#c.PyCapsule_Destructor" title="PyCapsule_Destructor">PyCapsule_Destructor</a> <code class="descname">PyCapsule_GetDestructor</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *capsule</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCapsule_GetDestructor" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the current destructor stored in the capsule. On failure, set an
exception and return <em>NULL</em>.</p>
<p>It is legal for a capsule to have a <em>NULL</em> destructor. This makes a <em>NULL</em>
return code somewhat ambiguous; use <a class="reference internal" href="#c.PyCapsule_IsValid" title="PyCapsule_IsValid"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyCapsule_IsValid()</span></code></a> or
<a class="reference internal" href="exceptions.html#c.PyErr_Occurred" title="PyErr_Occurred"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyErr_Occurred()</span></code></a> to disambiguate.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyCapsule_GetContext">
void* <code class="descname">PyCapsule_GetContext</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *capsule</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCapsule_GetContext" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the current context stored in the capsule. On failure, set an
exception and return <em>NULL</em>.</p>
<p>It is legal for a capsule to have a <em>NULL</em> context. This makes a <em>NULL</em>
return code somewhat ambiguous; use <a class="reference internal" href="#c.PyCapsule_IsValid" title="PyCapsule_IsValid"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyCapsule_IsValid()</span></code></a> or
<a class="reference internal" href="exceptions.html#c.PyErr_Occurred" title="PyErr_Occurred"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyErr_Occurred()</span></code></a> to disambiguate.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyCapsule_GetName">
const char* <code class="descname">PyCapsule_GetName</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *capsule</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCapsule_GetName" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the current name stored in the capsule. On failure, set an exception
and return <em>NULL</em>.</p>
<p>It is legal for a capsule to have a <em>NULL</em> name. This makes a <em>NULL</em> return
code somewhat ambiguous; use <a class="reference internal" href="#c.PyCapsule_IsValid" title="PyCapsule_IsValid"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyCapsule_IsValid()</span></code></a> or
<a class="reference internal" href="exceptions.html#c.PyErr_Occurred" title="PyErr_Occurred"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyErr_Occurred()</span></code></a> to disambiguate.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyCapsule_Import">
void* <code class="descname">PyCapsule_Import</code><span class="sig-paren">(</span>const char<em> *name</em>, int<em> no_block</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCapsule_Import" title="Permalink to this definition">¶</a></dt>
<dd><p>Import a pointer to a C object from a capsule attribute in a module. The
<em>name</em> parameter should specify the full name to the attribute, as in
<code class="docutils literal notranslate"><span class="pre">module.attribute</span></code>. The <em>name</em> stored in the capsule must match this
string exactly. If <em>no_block</em> is true, import the module without blocking
(using <a class="reference internal" href="import.html#c.PyImport_ImportModuleNoBlock" title="PyImport_ImportModuleNoBlock"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyImport_ImportModuleNoBlock()</span></code></a>). If <em>no_block</em> is false,
import the module conventionally (using <a class="reference internal" href="import.html#c.PyImport_ImportModule" title="PyImport_ImportModule"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyImport_ImportModule()</span></code></a>).</p>
<p>Return the capsule’s internal <em>pointer</em> on success. On failure, set an
exception and return <em>NULL</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyCapsule_IsValid">
int <code class="descname">PyCapsule_IsValid</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *capsule</em>, const char<em> *name</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCapsule_IsValid" title="Permalink to this definition">¶</a></dt>
<dd><p>Determines whether or not <em>capsule</em> is a valid capsule. A valid capsule is
non-<em>NULL</em>, passes <a class="reference internal" href="#c.PyCapsule_CheckExact" title="PyCapsule_CheckExact"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyCapsule_CheckExact()</span></code></a>, has a non-<em>NULL</em> pointer
stored in it, and its internal name matches the <em>name</em> parameter. (See
<a class="reference internal" href="#c.PyCapsule_GetPointer" title="PyCapsule_GetPointer"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyCapsule_GetPointer()</span></code></a> for information on how capsule names are
compared.)</p>
<p>In other words, if <a class="reference internal" href="#c.PyCapsule_IsValid" title="PyCapsule_IsValid"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyCapsule_IsValid()</span></code></a> returns a true value, calls to
any of the accessors (any function starting with <code class="xref c c-func docutils literal notranslate"><span class="pre">PyCapsule_Get()</span></code>) are
guaranteed to succeed.</p>
<p>Return a nonzero value if the object is valid and matches the name passed in.
Return <code class="docutils literal notranslate"><span class="pre">0</span></code> otherwise. This function will not fail.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyCapsule_SetContext">
int <code class="descname">PyCapsule_SetContext</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *capsule</em>, void<em> *context</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCapsule_SetContext" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the context pointer inside <em>capsule</em> to <em>context</em>.</p>
<p>Return <code class="docutils literal notranslate"><span class="pre">0</span></code> on success. Return nonzero and set an exception on failure.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyCapsule_SetDestructor">
int <code class="descname">PyCapsule_SetDestructor</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *capsule</em>, <a class="reference internal" href="#c.PyCapsule_Destructor" title="PyCapsule_Destructor">PyCapsule_Destructor</a><em> destructor</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCapsule_SetDestructor" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the destructor inside <em>capsule</em> to <em>destructor</em>.</p>
<p>Return <code class="docutils literal notranslate"><span class="pre">0</span></code> on success. Return nonzero and set an exception on failure.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyCapsule_SetName">
int <code class="descname">PyCapsule_SetName</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *capsule</em>, const char<em> *name</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCapsule_SetName" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the name inside <em>capsule</em> to <em>name</em>. If non-<em>NULL</em>, the name must
outlive the capsule. If the previous <em>name</em> stored in the capsule was not
<em>NULL</em>, no attempt is made to free it.</p>
<p>Return <code class="docutils literal notranslate"><span class="pre">0</span></code> on success. Return nonzero and set an exception on failure.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyCapsule_SetPointer">
int <code class="descname">PyCapsule_SetPointer</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *capsule</em>, void<em> *pointer</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCapsule_SetPointer" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the void pointer inside <em>capsule</em> to <em>pointer</em>. The pointer may not be
<em>NULL</em>.</p>
<p>Return <code class="docutils literal notranslate"><span class="pre">0</span></code> on success. Return nonzero and set an exception on failure.</p>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="weakref.html"
title="previous chapter">Weak Reference Objects</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="cobject.html"
title="next chapter">CObjects</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/capsule.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="cobject.html" title="CObjects"
>next</a> |</li>
<li class="right" >
<a href="weakref.html" title="Weak Reference Objects"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" >Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\� ��+ �+ html/c-api/cell.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Cell Objects — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Generator Objects" href="gen.html" />
<link rel="prev" title="CObjects" href="cobject.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/cell.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="gen.html" title="Generator Objects"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="cobject.html" title="CObjects"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" accesskey="U">Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="cell-objects">
<span id="id1"></span><h1>Cell Objects<a class="headerlink" href="#cell-objects" title="Permalink to this headline">¶</a></h1>
<p>“Cell” objects are used to implement variables referenced by multiple scopes.
For each such variable, a cell object is created to store the value; the local
variables of each stack frame that references the value contains a reference to
the cells from outer scopes which also use that variable. When the value is
accessed, the value contained in the cell is used instead of the cell object
itself. This de-referencing of the cell object requires support from the
generated byte-code; these are not automatically de-referenced when accessed.
Cell objects are not likely to be useful elsewhere.</p>
<dl class="type">
<dt id="c.PyCellObject">
<code class="descname">PyCellObject</code><a class="headerlink" href="#c.PyCellObject" title="Permalink to this definition">¶</a></dt>
<dd><p>The C structure used for cell objects.</p>
</dd></dl>
<dl class="var">
<dt id="c.PyCell_Type">
<a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a> <code class="descname">PyCell_Type</code><a class="headerlink" href="#c.PyCell_Type" title="Permalink to this definition">¶</a></dt>
<dd><p>The type object corresponding to cell objects.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyCell_Check">
int <code class="descname">PyCell_Check</code><span class="sig-paren">(</span>ob<span class="sig-paren">)</span><a class="headerlink" href="#c.PyCell_Check" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if <em>ob</em> is a cell object; <em>ob</em> must not be <em>NULL</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyCell_New">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyCell_New</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *ob</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCell_New" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Create and return a new cell object containing the value <em>ob</em>. The parameter may
be <em>NULL</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyCell_Get">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyCell_Get</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *cell</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCell_Get" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return the contents of the cell <em>cell</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyCell_GET">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyCell_GET</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *cell</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCell_GET" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Borrowed reference.</em><p>Return the contents of the cell <em>cell</em>, but without checking that <em>cell</em> is
non-<em>NULL</em> and a cell object.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyCell_Set">
int <code class="descname">PyCell_Set</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *cell</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *value</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCell_Set" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the contents of the cell object <em>cell</em> to <em>value</em>. This releases the
reference to any current content of the cell. <em>value</em> may be <em>NULL</em>. <em>cell</em>
must be non-<em>NULL</em>; if it is not a cell object, <code class="docutils literal notranslate"><span class="pre">-1</span></code> will be returned. On
success, <code class="docutils literal notranslate"><span class="pre">0</span></code> will be returned.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyCell_SET">
void <code class="descname">PyCell_SET</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *cell</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *value</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCell_SET" title="Permalink to this definition">¶</a></dt>
<dd><p>Sets the value of the cell object <em>cell</em> to <em>value</em>. No reference counts are
adjusted, and no checks are made for safety; <em>cell</em> must be non-<em>NULL</em> and must
be a cell object.</p>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="cobject.html"
title="previous chapter">CObjects</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="gen.html"
title="next chapter">Generator Objects</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/cell.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="gen.html" title="Generator Objects"
>next</a> |</li>
<li class="right" >
<a href="cobject.html" title="CObjects"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" >Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\
�N&�, �, html/c-api/class.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Class and Instance Objects — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Function Objects" href="function.html" />
<link rel="prev" title="Dictionary Objects" href="dict.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/class.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="function.html" title="Function Objects"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="dict.html" title="Dictionary Objects"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" accesskey="U">Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="class-and-instance-objects">
<span id="classobjects"></span><h1>Class and Instance Objects<a class="headerlink" href="#class-and-instance-objects" title="Permalink to this headline">¶</a></h1>
<p id="index-0">Note that the class objects described here represent old-style classes, which
will go away in Python 3. When creating new types for extension modules, you
will want to work with type objects (section <a class="reference internal" href="type.html#typeobjects"><span class="std std-ref">Type Objects</span></a>).</p>
<dl class="type">
<dt id="c.PyClassObject">
<code class="descname">PyClassObject</code><a class="headerlink" href="#c.PyClassObject" title="Permalink to this definition">¶</a></dt>
<dd><p>The C structure of the objects used to describe built-in classes.</p>
</dd></dl>
<dl class="var">
<dt id="c.PyClass_Type">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyClass_Type</code><a class="headerlink" href="#c.PyClass_Type" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-1">This is the type object for class objects; it is the same object as
<code class="docutils literal notranslate"><span class="pre">types.ClassType</span></code> in the Python layer.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyClass_Check">
int <code class="descname">PyClass_Check</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyClass_Check" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if the object <em>o</em> is a class object, including instances of types
derived from the standard class object. Return false in all other cases.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyClass_IsSubclass">
int <code class="descname">PyClass_IsSubclass</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *klass</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *base</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyClass_IsSubclass" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if <em>klass</em> is a subclass of <em>base</em>. Return false in all other cases.</p>
</dd></dl>
<p id="index-2">There are very few functions specific to instance objects.</p>
<dl class="var">
<dt id="c.PyInstance_Type">
<a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a> <code class="descname">PyInstance_Type</code><a class="headerlink" href="#c.PyInstance_Type" title="Permalink to this definition">¶</a></dt>
<dd><p>Type object for class instances.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyInstance_Check">
int <code class="descname">PyInstance_Check</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *obj</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyInstance_Check" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if <em>obj</em> is an instance.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyInstance_New">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyInstance_New</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *class</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *arg</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *kw</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyInstance_New" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Create a new instance of a specific class. The parameters <em>arg</em> and <em>kw</em> are
used as the positional and keyword parameters to the object’s constructor.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyInstance_NewRaw">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyInstance_NewRaw</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *class</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *dict</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyInstance_NewRaw" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Create a new instance of a specific class without calling its constructor.
<em>class</em> is the class of new object. The <em>dict</em> parameter will be used as the
object’s <a class="reference internal" href="../library/stdtypes.html#object.__dict__" title="object.__dict__"><code class="xref py py-attr docutils literal notranslate"><span class="pre">__dict__</span></code></a>; if <em>NULL</em>, a new dictionary will be created for the
instance.</p>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="dict.html"
title="previous chapter">Dictionary Objects</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="function.html"
title="next chapter">Function Objects</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/class.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="function.html" title="Function Objects"
>next</a> |</li>
<li class="right" >
<a href="dict.html" title="Dictionary Objects"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" >Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\m��2/ 2/ html/c-api/cobject.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>CObjects — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Cell Objects" href="cell.html" />
<link rel="prev" title="Capsules" href="capsule.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/cobject.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="cell.html" title="Cell Objects"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="capsule.html" title="Capsules"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" accesskey="U">Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="cobjects">
<span id="id1"></span><h1>CObjects<a class="headerlink" href="#cobjects" title="Permalink to this headline">¶</a></h1>
<div class="admonition warning" id="index-0">
<p class="first admonition-title">Warning</p>
<p class="last">The CObject API is deprecated as of Python 2.7. Please switch to the new
<a class="reference internal" href="capsule.html#capsules"><span class="std std-ref">Capsules</span></a> API.</p>
</div>
<dl class="type">
<dt id="c.PyCObject">
<code class="descname">PyCObject</code><a class="headerlink" href="#c.PyCObject" title="Permalink to this definition">¶</a></dt>
<dd><p>This subtype of <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject</span></code></a> represents an opaque value, useful for C
extension modules who need to pass an opaque value (as a <code class="xref c c-type docutils literal notranslate"><span class="pre">void*</span></code>
pointer) through Python code to other C code. It is often used to make a C
function pointer defined in one module available to other modules, so the
regular import mechanism can be used to access C APIs defined in dynamically
loaded modules.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyCObject_Check">
int <code class="descname">PyCObject_Check</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCObject_Check" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if its argument is a <a class="reference internal" href="#c.PyCObject" title="PyCObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyCObject</span></code></a>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyCObject_FromVoidPtr">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyCObject_FromVoidPtr</code><span class="sig-paren">(</span>void*<em> cobj</em>, void (<em>*destr</em>)(void *)<span class="sig-paren">)</span><a class="headerlink" href="#c.PyCObject_FromVoidPtr" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Create a <a class="reference internal" href="#c.PyCObject" title="PyCObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyCObject</span></code></a> from the <code class="docutils literal notranslate"><span class="pre">void</span> <span class="pre">*</span></code> <em>cobj</em>. The <em>destr</em> function
will be called when the object is reclaimed, unless it is <em>NULL</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyCObject_FromVoidPtrAndDesc">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyCObject_FromVoidPtrAndDesc</code><span class="sig-paren">(</span>void*<em> cobj</em>, void*<em> desc</em>, void (<em>*destr</em>)(void *, void *)<span class="sig-paren">)</span><a class="headerlink" href="#c.PyCObject_FromVoidPtrAndDesc" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Create a <a class="reference internal" href="#c.PyCObject" title="PyCObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyCObject</span></code></a> from the <code class="xref c c-type docutils literal notranslate"><span class="pre">void</span> <span class="pre">*</span></code> <em>cobj</em>. The <em>destr</em>
function will be called when the object is reclaimed. The <em>desc</em> argument can
be used to pass extra callback data for the destructor function.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyCObject_AsVoidPtr">
void* <code class="descname">PyCObject_AsVoidPtr</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>*<em> self</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCObject_AsVoidPtr" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the object <code class="xref c c-type docutils literal notranslate"><span class="pre">void</span> <span class="pre">*</span></code> that the <a class="reference internal" href="#c.PyCObject" title="PyCObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyCObject</span></code></a> <em>self</em> was
created with.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyCObject_GetDesc">
void* <code class="descname">PyCObject_GetDesc</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>*<em> self</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCObject_GetDesc" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the description <code class="xref c c-type docutils literal notranslate"><span class="pre">void</span> <span class="pre">*</span></code> that the <a class="reference internal" href="#c.PyCObject" title="PyCObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyCObject</span></code></a> <em>self</em> was
created with.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyCObject_SetVoidPtr">
int <code class="descname">PyCObject_SetVoidPtr</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>*<em> self</em>, void*<em> cobj</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCObject_SetVoidPtr" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the void pointer inside <em>self</em> to <em>cobj</em>. The <a class="reference internal" href="#c.PyCObject" title="PyCObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyCObject</span></code></a> must not
have an associated destructor. Return true on success, false on failure.</p>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="capsule.html"
title="previous chapter">Capsules</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="cell.html"
title="next chapter">Cell Objects</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/cobject.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="cell.html" title="Cell Objects"
>next</a> |</li>
<li class="right" >
<a href="capsule.html" title="Capsules"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" >Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\����- �- html/c-api/code.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Code Objects — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Initialization, Finalization, and Threads" href="init.html" />
<link rel="prev" title="Set Objects" href="set.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/code.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="init.html" title="Initialization, Finalization, and Threads"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="set.html" title="Set Objects"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" accesskey="U">Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<span class="target" id="codeobjects"></span><div class="section" id="code-objects">
<span id="index-0"></span><h1>Code Objects<a class="headerlink" href="#code-objects" title="Permalink to this headline">¶</a></h1>
<p>Code objects are a low-level detail of the CPython implementation.
Each one represents a chunk of executable code that hasn’t yet been
bound into a function.</p>
<dl class="type">
<dt id="c.PyCodeObject">
<code class="descname">PyCodeObject</code><a class="headerlink" href="#c.PyCodeObject" title="Permalink to this definition">¶</a></dt>
<dd><p>The C structure of the objects used to describe code objects. The
fields of this type are subject to change at any time.</p>
</dd></dl>
<dl class="var">
<dt id="c.PyCode_Type">
<a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a> <code class="descname">PyCode_Type</code><a class="headerlink" href="#c.PyCode_Type" title="Permalink to this definition">¶</a></dt>
<dd><p>This is an instance of <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyTypeObject</span></code></a> representing the Python
<a class="reference internal" href="../library/code.html#module-code" title="code: Facilities to implement read-eval-print loops."><code class="xref py py-class docutils literal notranslate"><span class="pre">code</span></code></a> type.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyCode_Check">
int <code class="descname">PyCode_Check</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *co</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCode_Check" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if <em>co</em> is a <a class="reference internal" href="../library/code.html#module-code" title="code: Facilities to implement read-eval-print loops."><code class="xref py py-class docutils literal notranslate"><span class="pre">code</span></code></a> object.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyCode_GetNumFree">
int <code class="descname">PyCode_GetNumFree</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *co</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCode_GetNumFree" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the number of free variables in <em>co</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyCode_New">
<a class="reference internal" href="#c.PyCodeObject" title="PyCodeObject">PyCodeObject</a> *<code class="descname">PyCode_New</code><span class="sig-paren">(</span>int<em> argcount</em>, int<em> nlocals</em>, int<em> stacksize</em>, int<em> flags</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *code</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *consts</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *names</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *varnames</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *freevars</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *cellvars</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *filename</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *name</em>, int<em> firstlineno</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *lnotab</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCode_New" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a new code object. If you need a dummy code object to
create a frame, use <a class="reference internal" href="#c.PyCode_NewEmpty" title="PyCode_NewEmpty"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyCode_NewEmpty()</span></code></a> instead. Calling
<a class="reference internal" href="#c.PyCode_New" title="PyCode_New"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyCode_New()</span></code></a> directly can bind you to a precise Python
version since the definition of the bytecode changes often.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyCode_NewEmpty">
int <code class="descname">PyCode_NewEmpty</code><span class="sig-paren">(</span>const char<em> *filename</em>, const char<em> *funcname</em>, int<em> firstlineno</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCode_NewEmpty" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a new empty code object with the specified filename,
function name, and first line number. It is illegal to
<a class="reference internal" href="../reference/simple_stmts.html#exec"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">exec</span></code></a> or <a class="reference internal" href="../library/functions.html#eval" title="eval"><code class="xref py py-func docutils literal notranslate"><span class="pre">eval()</span></code></a> the resulting code object.</p>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="set.html"
title="previous chapter">Set Objects</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="init.html"
title="next chapter">Initialization, Finalization, and Threads</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/code.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="init.html" title="Initialization, Finalization, and Threads"
>next</a> |</li>
<li class="right" >
<a href="set.html" title="Set Objects"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" >Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\�R<IS IS html/c-api/codec.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Codec registry and support functions — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Abstract Objects Layer" href="abstract.html" />
<link rel="prev" title="Reflection" href="reflection.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/codec.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="abstract.html" title="Abstract Objects Layer"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="reflection.html" title="Reflection"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="utilities.html" accesskey="U">Utilities</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="codec-registry-and-support-functions">
<span id="codec-registry"></span><h1>Codec registry and support functions<a class="headerlink" href="#codec-registry-and-support-functions" title="Permalink to this headline">¶</a></h1>
<dl class="function">
<dt id="c.PyCodec_Register">
int <code class="descname">PyCodec_Register</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *search_function</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCodec_Register" title="Permalink to this definition">¶</a></dt>
<dd><p>Register a new codec search function.</p>
<p>As side effect, this tries to load the <code class="xref py py-mod docutils literal notranslate"><span class="pre">encodings</span></code> package, if not yet
done, to make sure that it is always first in the list of search functions.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyCodec_KnownEncoding">
int <code class="descname">PyCodec_KnownEncoding</code><span class="sig-paren">(</span>const char<em> *encoding</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCodec_KnownEncoding" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">1</span></code> or <code class="docutils literal notranslate"><span class="pre">0</span></code> depending on whether there is a registered codec for
the given <em>encoding</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyCodec_Encode">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyCodec_Encode</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *object</em>, const char<em> *encoding</em>, const char<em> *errors</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCodec_Encode" title="Permalink to this definition">¶</a></dt>
<dd><p>Generic codec based encoding API.</p>
<p><em>object</em> is passed through the encoder function found for the given
<em>encoding</em> using the error handling method defined by <em>errors</em>. <em>errors</em> may
be <em>NULL</em> to use the default method defined for the codec. Raises a
<a class="reference internal" href="../library/exceptions.html#exceptions.LookupError" title="exceptions.LookupError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">LookupError</span></code></a> if no encoder can be found.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyCodec_Decode">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyCodec_Decode</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *object</em>, const char<em> *encoding</em>, const char<em> *errors</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCodec_Decode" title="Permalink to this definition">¶</a></dt>
<dd><p>Generic codec based decoding API.</p>
<p><em>object</em> is passed through the decoder function found for the given
<em>encoding</em> using the error handling method defined by <em>errors</em>. <em>errors</em> may
be <em>NULL</em> to use the default method defined for the codec. Raises a
<a class="reference internal" href="../library/exceptions.html#exceptions.LookupError" title="exceptions.LookupError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">LookupError</span></code></a> if no encoder can be found.</p>
</dd></dl>
<div class="section" id="codec-lookup-api">
<h2>Codec lookup API<a class="headerlink" href="#codec-lookup-api" title="Permalink to this headline">¶</a></h2>
<p>In the following functions, the <em>encoding</em> string is looked up converted to all
lower-case characters, which makes encodings looked up through this mechanism
effectively case-insensitive. If no codec is found, a <a class="reference internal" href="../library/exceptions.html#exceptions.KeyError" title="exceptions.KeyError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyError</span></code></a> is set
and <em>NULL</em> returned.</p>
<dl class="function">
<dt id="c.PyCodec_Encoder">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyCodec_Encoder</code><span class="sig-paren">(</span>const char<em> *encoding</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCodec_Encoder" title="Permalink to this definition">¶</a></dt>
<dd><p>Get an encoder function for the given <em>encoding</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyCodec_Decoder">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyCodec_Decoder</code><span class="sig-paren">(</span>const char<em> *encoding</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCodec_Decoder" title="Permalink to this definition">¶</a></dt>
<dd><p>Get a decoder function for the given <em>encoding</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyCodec_IncrementalEncoder">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyCodec_IncrementalEncoder</code><span class="sig-paren">(</span>const char<em> *encoding</em>, const char<em> *errors</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCodec_IncrementalEncoder" title="Permalink to this definition">¶</a></dt>
<dd><p>Get an <a class="reference internal" href="../library/codecs.html#codecs.IncrementalEncoder" title="codecs.IncrementalEncoder"><code class="xref py py-class docutils literal notranslate"><span class="pre">IncrementalEncoder</span></code></a> object for the given <em>encoding</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyCodec_IncrementalDecoder">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyCodec_IncrementalDecoder</code><span class="sig-paren">(</span>const char<em> *encoding</em>, const char<em> *errors</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCodec_IncrementalDecoder" title="Permalink to this definition">¶</a></dt>
<dd><p>Get an <a class="reference internal" href="../library/codecs.html#codecs.IncrementalDecoder" title="codecs.IncrementalDecoder"><code class="xref py py-class docutils literal notranslate"><span class="pre">IncrementalDecoder</span></code></a> object for the given <em>encoding</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyCodec_StreamReader">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyCodec_StreamReader</code><span class="sig-paren">(</span>const char<em> *encoding</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *stream</em>, const char<em> *errors</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCodec_StreamReader" title="Permalink to this definition">¶</a></dt>
<dd><p>Get a <a class="reference internal" href="../library/codecs.html#codecs.StreamReader" title="codecs.StreamReader"><code class="xref py py-class docutils literal notranslate"><span class="pre">StreamReader</span></code></a> factory function for the given <em>encoding</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyCodec_StreamWriter">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyCodec_StreamWriter</code><span class="sig-paren">(</span>const char<em> *encoding</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *stream</em>, const char<em> *errors</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCodec_StreamWriter" title="Permalink to this definition">¶</a></dt>
<dd><p>Get a <a class="reference internal" href="../library/codecs.html#codecs.StreamWriter" title="codecs.StreamWriter"><code class="xref py py-class docutils literal notranslate"><span class="pre">StreamWriter</span></code></a> factory function for the given <em>encoding</em>.</p>
</dd></dl>
</div>
<div class="section" id="registry-api-for-unicode-encoding-error-handlers">
<h2>Registry API for Unicode encoding error handlers<a class="headerlink" href="#registry-api-for-unicode-encoding-error-handlers" title="Permalink to this headline">¶</a></h2>
<dl class="function">
<dt id="c.PyCodec_RegisterError">
int <code class="descname">PyCodec_RegisterError</code><span class="sig-paren">(</span>const char<em> *name</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *error</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCodec_RegisterError" title="Permalink to this definition">¶</a></dt>
<dd><p>Register the error handling callback function <em>error</em> under the given <em>name</em>.
This callback function will be called by a codec when it encounters
unencodable characters/undecodable bytes and <em>name</em> is specified as the error
parameter in the call to the encode/decode function.</p>
<p>The callback gets a single argument, an instance of
<a class="reference internal" href="../library/exceptions.html#exceptions.UnicodeEncodeError" title="exceptions.UnicodeEncodeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">UnicodeEncodeError</span></code></a>, <a class="reference internal" href="../library/exceptions.html#exceptions.UnicodeDecodeError" title="exceptions.UnicodeDecodeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">UnicodeDecodeError</span></code></a> or
<a class="reference internal" href="../library/exceptions.html#exceptions.UnicodeTranslateError" title="exceptions.UnicodeTranslateError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">UnicodeTranslateError</span></code></a> that holds information about the problematic
sequence of characters or bytes and their offset in the original string (see
<a class="reference internal" href="exceptions.html#unicodeexceptions"><span class="std std-ref">Unicode Exception Objects</span></a> for functions to extract this information). The
callback must either raise the given exception, or return a two-item tuple
containing the replacement for the problematic sequence, and an integer
giving the offset in the original string at which encoding/decoding should be
resumed.</p>
<p>Return <code class="docutils literal notranslate"><span class="pre">0</span></code> on success, <code class="docutils literal notranslate"><span class="pre">-1</span></code> on error.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyCodec_LookupError">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyCodec_LookupError</code><span class="sig-paren">(</span>const char<em> *name</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCodec_LookupError" title="Permalink to this definition">¶</a></dt>
<dd><p>Lookup the error handling callback function registered under <em>name</em>. As a
special case <em>NULL</em> can be passed, in which case the error handling callback
for “strict” will be returned.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyCodec_StrictErrors">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyCodec_StrictErrors</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *exc</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCodec_StrictErrors" title="Permalink to this definition">¶</a></dt>
<dd><p>Raise <em>exc</em> as an exception.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyCodec_IgnoreErrors">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyCodec_IgnoreErrors</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *exc</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCodec_IgnoreErrors" title="Permalink to this definition">¶</a></dt>
<dd><p>Ignore the unicode error, skipping the faulty input.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyCodec_ReplaceErrors">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyCodec_ReplaceErrors</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *exc</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCodec_ReplaceErrors" title="Permalink to this definition">¶</a></dt>
<dd><p>Replace the unicode encode error with <code class="docutils literal notranslate"><span class="pre">?</span></code> or <code class="docutils literal notranslate"><span class="pre">U+FFFD</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyCodec_XMLCharRefReplaceErrors">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyCodec_XMLCharRefReplaceErrors</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *exc</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCodec_XMLCharRefReplaceErrors" title="Permalink to this definition">¶</a></dt>
<dd><p>Replace the unicode encode error with XML character references.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyCodec_BackslashReplaceErrors">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyCodec_BackslashReplaceErrors</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *exc</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyCodec_BackslashReplaceErrors" title="Permalink to this definition">¶</a></dt>
<dd><p>Replace the unicode encode error with backslash escapes (<code class="docutils literal notranslate"><span class="pre">\x</span></code>, <code class="docutils literal notranslate"><span class="pre">\u</span></code> and
<code class="docutils literal notranslate"><span class="pre">\U</span></code>).</p>
</dd></dl>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Codec registry and support functions</a><ul>
<li><a class="reference internal" href="#codec-lookup-api">Codec lookup API</a></li>
<li><a class="reference internal" href="#registry-api-for-unicode-encoding-error-handlers">Registry API for Unicode encoding error handlers</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="reflection.html"
title="previous chapter">Reflection</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="abstract.html"
title="next chapter">Abstract Objects Layer</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/codec.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="abstract.html" title="Abstract Objects Layer"
>next</a> |</li>
<li class="right" >
<a href="reflection.html" title="Reflection"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="utilities.html" >Utilities</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\��9�Q �Q html/c-api/complex.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Complex Number Objects — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Byte Array Objects" href="bytearray.html" />
<link rel="prev" title="Floating Point Objects" href="float.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/complex.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="bytearray.html" title="Byte Array Objects"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="float.html" title="Floating Point Objects"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" accesskey="U">Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="complex-number-objects">
<span id="complexobjects"></span><h1>Complex Number Objects<a class="headerlink" href="#complex-number-objects" title="Permalink to this headline">¶</a></h1>
<p id="index-0">Python’s complex number objects are implemented as two distinct types when
viewed from the C API: one is the Python object exposed to Python programs, and
the other is a C structure which represents the actual complex number value.
The API provides functions for working with both.</p>
<div class="section" id="complex-numbers-as-c-structures">
<h2>Complex Numbers as C Structures<a class="headerlink" href="#complex-numbers-as-c-structures" title="Permalink to this headline">¶</a></h2>
<p>Note that the functions which accept these structures as parameters and return
them as results do so <em>by value</em> rather than dereferencing them through
pointers. This is consistent throughout the API.</p>
<dl class="type">
<dt id="c.Py_complex">
<code class="descname">Py_complex</code><a class="headerlink" href="#c.Py_complex" title="Permalink to this definition">¶</a></dt>
<dd><p>The C structure which corresponds to the value portion of a Python complex
number object. Most of the functions for dealing with complex number objects
use structures of this type as input or output values, as appropriate. It is
defined as:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">typedef</span> <span class="k">struct</span> <span class="p">{</span>
<span class="kt">double</span> <span class="n">real</span><span class="p">;</span>
<span class="kt">double</span> <span class="n">imag</span><span class="p">;</span>
<span class="p">}</span> <span class="n">Py_complex</span><span class="p">;</span>
</pre></div>
</div>
</dd></dl>
<dl class="function">
<dt id="c._Py_c_sum">
<a class="reference internal" href="#c.Py_complex" title="Py_complex">Py_complex</a> <code class="descname">_Py_c_sum</code><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_complex" title="Py_complex">Py_complex</a><em> left</em>, <a class="reference internal" href="#c.Py_complex" title="Py_complex">Py_complex</a><em> right</em><span class="sig-paren">)</span><a class="headerlink" href="#c._Py_c_sum" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the sum of two complex numbers, using the C <a class="reference internal" href="#c.Py_complex" title="Py_complex"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_complex</span></code></a>
representation.</p>
</dd></dl>
<dl class="function">
<dt id="c._Py_c_diff">
<a class="reference internal" href="#c.Py_complex" title="Py_complex">Py_complex</a> <code class="descname">_Py_c_diff</code><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_complex" title="Py_complex">Py_complex</a><em> left</em>, <a class="reference internal" href="#c.Py_complex" title="Py_complex">Py_complex</a><em> right</em><span class="sig-paren">)</span><a class="headerlink" href="#c._Py_c_diff" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the difference between two complex numbers, using the C
<a class="reference internal" href="#c.Py_complex" title="Py_complex"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_complex</span></code></a> representation.</p>
</dd></dl>
<dl class="function">
<dt id="c._Py_c_neg">
<a class="reference internal" href="#c.Py_complex" title="Py_complex">Py_complex</a> <code class="descname">_Py_c_neg</code><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_complex" title="Py_complex">Py_complex</a><em> complex</em><span class="sig-paren">)</span><a class="headerlink" href="#c._Py_c_neg" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the negation of the complex number <em>complex</em>, using the C
<a class="reference internal" href="#c.Py_complex" title="Py_complex"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_complex</span></code></a> representation.</p>
</dd></dl>
<dl class="function">
<dt id="c._Py_c_prod">
<a class="reference internal" href="#c.Py_complex" title="Py_complex">Py_complex</a> <code class="descname">_Py_c_prod</code><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_complex" title="Py_complex">Py_complex</a><em> left</em>, <a class="reference internal" href="#c.Py_complex" title="Py_complex">Py_complex</a><em> right</em><span class="sig-paren">)</span><a class="headerlink" href="#c._Py_c_prod" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the product of two complex numbers, using the C <a class="reference internal" href="#c.Py_complex" title="Py_complex"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_complex</span></code></a>
representation.</p>
</dd></dl>
<dl class="function">
<dt id="c._Py_c_quot">
<a class="reference internal" href="#c.Py_complex" title="Py_complex">Py_complex</a> <code class="descname">_Py_c_quot</code><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_complex" title="Py_complex">Py_complex</a><em> dividend</em>, <a class="reference internal" href="#c.Py_complex" title="Py_complex">Py_complex</a><em> divisor</em><span class="sig-paren">)</span><a class="headerlink" href="#c._Py_c_quot" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the quotient of two complex numbers, using the C <a class="reference internal" href="#c.Py_complex" title="Py_complex"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_complex</span></code></a>
representation.</p>
<p>If <em>divisor</em> is null, this method returns zero and sets
<code class="xref c c-data docutils literal notranslate"><span class="pre">errno</span></code> to <code class="xref c c-data docutils literal notranslate"><span class="pre">EDOM</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c._Py_c_pow">
<a class="reference internal" href="#c.Py_complex" title="Py_complex">Py_complex</a> <code class="descname">_Py_c_pow</code><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_complex" title="Py_complex">Py_complex</a><em> num</em>, <a class="reference internal" href="#c.Py_complex" title="Py_complex">Py_complex</a><em> exp</em><span class="sig-paren">)</span><a class="headerlink" href="#c._Py_c_pow" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the exponentiation of <em>num</em> by <em>exp</em>, using the C <a class="reference internal" href="#c.Py_complex" title="Py_complex"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_complex</span></code></a>
representation.</p>
<p>If <em>num</em> is null and <em>exp</em> is not a positive real number,
this method returns zero and sets <code class="xref c c-data docutils literal notranslate"><span class="pre">errno</span></code> to <code class="xref c c-data docutils literal notranslate"><span class="pre">EDOM</span></code>.</p>
</dd></dl>
</div>
<div class="section" id="complex-numbers-as-python-objects">
<h2>Complex Numbers as Python Objects<a class="headerlink" href="#complex-numbers-as-python-objects" title="Permalink to this headline">¶</a></h2>
<dl class="type">
<dt id="c.PyComplexObject">
<code class="descname">PyComplexObject</code><a class="headerlink" href="#c.PyComplexObject" title="Permalink to this definition">¶</a></dt>
<dd><p>This subtype of <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject</span></code></a> represents a Python complex number object.</p>
</dd></dl>
<dl class="var">
<dt id="c.PyComplex_Type">
<a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a> <code class="descname">PyComplex_Type</code><a class="headerlink" href="#c.PyComplex_Type" title="Permalink to this definition">¶</a></dt>
<dd><p>This instance of <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyTypeObject</span></code></a> represents the Python complex number
type. It is the same object as <code class="docutils literal notranslate"><span class="pre">complex</span></code> and <code class="docutils literal notranslate"><span class="pre">types.ComplexType</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyComplex_Check">
int <code class="descname">PyComplex_Check</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyComplex_Check" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if its argument is a <a class="reference internal" href="#c.PyComplexObject" title="PyComplexObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyComplexObject</span></code></a> or a subtype of
<a class="reference internal" href="#c.PyComplexObject" title="PyComplexObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyComplexObject</span></code></a>.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.2: </span>Allowed subtypes to be accepted.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyComplex_CheckExact">
int <code class="descname">PyComplex_CheckExact</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyComplex_CheckExact" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if its argument is a <a class="reference internal" href="#c.PyComplexObject" title="PyComplexObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyComplexObject</span></code></a>, but not a subtype of
<a class="reference internal" href="#c.PyComplexObject" title="PyComplexObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyComplexObject</span></code></a>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyComplex_FromCComplex">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyComplex_FromCComplex</code><span class="sig-paren">(</span><a class="reference internal" href="#c.Py_complex" title="Py_complex">Py_complex</a><em> v</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyComplex_FromCComplex" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Create a new Python complex number object from a C <a class="reference internal" href="#c.Py_complex" title="Py_complex"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_complex</span></code></a> value.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyComplex_FromDoubles">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyComplex_FromDoubles</code><span class="sig-paren">(</span>double<em> real</em>, double<em> imag</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyComplex_FromDoubles" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a new <a class="reference internal" href="#c.PyComplexObject" title="PyComplexObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyComplexObject</span></code></a> object from <em>real</em> and <em>imag</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyComplex_RealAsDouble">
double <code class="descname">PyComplex_RealAsDouble</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *op</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyComplex_RealAsDouble" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the real part of <em>op</em> as a C <code class="xref c c-type docutils literal notranslate"><span class="pre">double</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyComplex_ImagAsDouble">
double <code class="descname">PyComplex_ImagAsDouble</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *op</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyComplex_ImagAsDouble" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the imaginary part of <em>op</em> as a C <code class="xref c c-type docutils literal notranslate"><span class="pre">double</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyComplex_AsCComplex">
<a class="reference internal" href="#c.Py_complex" title="Py_complex">Py_complex</a> <code class="descname">PyComplex_AsCComplex</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *op</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyComplex_AsCComplex" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the <a class="reference internal" href="#c.Py_complex" title="Py_complex"><code class="xref c c-type docutils literal notranslate"><span class="pre">Py_complex</span></code></a> value of the complex number <em>op</em>.
Upon failure, this method returns <code class="docutils literal notranslate"><span class="pre">-1.0</span></code> as a real value.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.6: </span>If <em>op</em> is not a Python complex number object but has a <a class="reference internal" href="../reference/datamodel.html#object.__complex__" title="object.__complex__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__complex__()</span></code></a>
method, this method will first be called to convert <em>op</em> to a Python complex
number object.</p>
</div>
</dd></dl>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Complex Number Objects</a><ul>
<li><a class="reference internal" href="#complex-numbers-as-c-structures">Complex Numbers as C Structures</a></li>
<li><a class="reference internal" href="#complex-numbers-as-python-objects">Complex Numbers as Python Objects</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="float.html"
title="previous chapter">Floating Point Objects</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="bytearray.html"
title="next chapter">Byte Array Objects</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/complex.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="bytearray.html" title="Byte Array Objects"
>next</a> |</li>
<li class="right" >
<a href="float.html" title="Floating Point Objects"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" >Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\�;�= �= html/c-api/concrete.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Concrete Objects Layer — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Type Objects" href="type.html" />
<link rel="prev" title="Old Buffer Protocol" href="objbuffer.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/concrete.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="type.html" title="Type Objects"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="objbuffer.html" title="Old Buffer Protocol"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Python/C API Reference Manual</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="concrete-objects-layer">
<span id="concrete"></span><h1>Concrete Objects Layer<a class="headerlink" href="#concrete-objects-layer" title="Permalink to this headline">¶</a></h1>
<p>The functions in this chapter are specific to certain Python object types.
Passing them an object of the wrong type is not a good idea; if you receive an
object from a Python program and you are not sure that it has the right type,
you must perform a type check first; for example, to check that an object is a
dictionary, use <a class="reference internal" href="dict.html#c.PyDict_Check" title="PyDict_Check"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyDict_Check()</span></code></a>. The chapter is structured like the
“family tree” of Python object types.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">While the functions described in this chapter carefully check the type of the
objects which are passed in, many of them do not check for <em>NULL</em> being passed
instead of a valid object. Allowing <em>NULL</em> to be passed in can cause memory
access violations and immediate termination of the interpreter.</p>
</div>
<div class="section" id="fundamental-objects">
<span id="fundamental"></span><h2>Fundamental Objects<a class="headerlink" href="#fundamental-objects" title="Permalink to this headline">¶</a></h2>
<p>This section describes Python type objects and the singleton object <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="type.html">Type Objects</a></li>
<li class="toctree-l1"><a class="reference internal" href="none.html">The <code class="docutils literal notranslate"><span class="pre">None</span></code> Object</a></li>
</ul>
</div>
</div>
<div class="section" id="numeric-objects">
<span id="numericobjects"></span><h2>Numeric Objects<a class="headerlink" href="#numeric-objects" title="Permalink to this headline">¶</a></h2>
<div class="toctree-wrapper compound" id="index-0">
<ul>
<li class="toctree-l1"><a class="reference internal" href="int.html">Plain Integer Objects</a></li>
<li class="toctree-l1"><a class="reference internal" href="bool.html">Boolean Objects</a></li>
<li class="toctree-l1"><a class="reference internal" href="long.html">Long Integer Objects</a></li>
<li class="toctree-l1"><a class="reference internal" href="float.html">Floating Point Objects</a></li>
<li class="toctree-l1"><a class="reference internal" href="complex.html">Complex Number Objects</a><ul>
<li class="toctree-l2"><a class="reference internal" href="complex.html#complex-numbers-as-c-structures">Complex Numbers as C Structures</a></li>
<li class="toctree-l2"><a class="reference internal" href="complex.html#complex-numbers-as-python-objects">Complex Numbers as Python Objects</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div class="section" id="sequence-objects">
<span id="sequenceobjects"></span><h2>Sequence Objects<a class="headerlink" href="#sequence-objects" title="Permalink to this headline">¶</a></h2>
<p id="index-1">Generic operations on sequence objects were discussed in the previous chapter;
this section deals with the specific kinds of sequence objects that are
intrinsic to the Python language.</p>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="bytearray.html">Byte Array Objects</a><ul>
<li class="toctree-l2"><a class="reference internal" href="bytearray.html#type-check-macros">Type check macros</a></li>
<li class="toctree-l2"><a class="reference internal" href="bytearray.html#direct-api-functions">Direct API functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="bytearray.html#macros">Macros</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="string.html">String/Bytes Objects</a></li>
<li class="toctree-l1"><a class="reference internal" href="unicode.html">Unicode Objects and Codecs</a><ul>
<li class="toctree-l2"><a class="reference internal" href="unicode.html#unicode-objects">Unicode Objects</a><ul>
<li class="toctree-l3"><a class="reference internal" href="unicode.html#unicode-type">Unicode Type</a></li>
<li class="toctree-l3"><a class="reference internal" href="unicode.html#unicode-character-properties">Unicode Character Properties</a></li>
<li class="toctree-l3"><a class="reference internal" href="unicode.html#plain-py-unicode">Plain Py_UNICODE</a></li>
<li class="toctree-l3"><a class="reference internal" href="unicode.html#wchar-t-support">wchar_t Support</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="unicode.html#built-in-codecs">Built-in Codecs</a><ul>
<li class="toctree-l3"><a class="reference internal" href="unicode.html#generic-codecs">Generic Codecs</a></li>
<li class="toctree-l3"><a class="reference internal" href="unicode.html#utf-8-codecs">UTF-8 Codecs</a></li>
<li class="toctree-l3"><a class="reference internal" href="unicode.html#utf-32-codecs">UTF-32 Codecs</a></li>
<li class="toctree-l3"><a class="reference internal" href="unicode.html#utf-16-codecs">UTF-16 Codecs</a></li>
<li class="toctree-l3"><a class="reference internal" href="unicode.html#utf-7-codecs">UTF-7 Codecs</a></li>
<li class="toctree-l3"><a class="reference internal" href="unicode.html#unicode-escape-codecs">Unicode-Escape Codecs</a></li>
<li class="toctree-l3"><a class="reference internal" href="unicode.html#raw-unicode-escape-codecs">Raw-Unicode-Escape Codecs</a></li>
<li class="toctree-l3"><a class="reference internal" href="unicode.html#latin-1-codecs">Latin-1 Codecs</a></li>
<li class="toctree-l3"><a class="reference internal" href="unicode.html#ascii-codecs">ASCII Codecs</a></li>
<li class="toctree-l3"><a class="reference internal" href="unicode.html#character-map-codecs">Character Map Codecs</a></li>
<li class="toctree-l3"><a class="reference internal" href="unicode.html#mbcs-codecs-for-windows">MBCS codecs for Windows</a></li>
<li class="toctree-l3"><a class="reference internal" href="unicode.html#methods-slots">Methods & Slots</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="unicode.html#methods-and-slot-functions">Methods and Slot Functions</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="buffer.html">Buffers and Memoryview Objects</a><ul>
<li class="toctree-l2"><a class="reference internal" href="buffer.html#the-new-style-py-buffer-struct">The new-style Py_buffer struct</a></li>
<li class="toctree-l2"><a class="reference internal" href="buffer.html#buffer-related-functions">Buffer related functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="buffer.html#memoryview-objects">MemoryView objects</a></li>
<li class="toctree-l2"><a class="reference internal" href="buffer.html#old-style-buffer-objects">Old-style buffer objects</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="tuple.html">Tuple Objects</a></li>
<li class="toctree-l1"><a class="reference internal" href="list.html">List Objects</a></li>
</ul>
</div>
</div>
<div class="section" id="mapping-objects">
<span id="mapobjects"></span><h2>Mapping Objects<a class="headerlink" href="#mapping-objects" title="Permalink to this headline">¶</a></h2>
<div class="toctree-wrapper compound" id="index-2">
<ul>
<li class="toctree-l1"><a class="reference internal" href="dict.html">Dictionary Objects</a></li>
</ul>
</div>
</div>
<div class="section" id="other-objects">
<span id="otherobjects"></span><h2>Other Objects<a class="headerlink" href="#other-objects" title="Permalink to this headline">¶</a></h2>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="class.html">Class and Instance Objects</a></li>
<li class="toctree-l1"><a class="reference internal" href="function.html">Function Objects</a></li>
<li class="toctree-l1"><a class="reference internal" href="method.html">Method Objects</a></li>
<li class="toctree-l1"><a class="reference internal" href="file.html">File Objects</a></li>
<li class="toctree-l1"><a class="reference internal" href="module.html">Module Objects</a></li>
<li class="toctree-l1"><a class="reference internal" href="iterator.html">Iterator Objects</a></li>
<li class="toctree-l1"><a class="reference internal" href="descriptor.html">Descriptor Objects</a></li>
<li class="toctree-l1"><a class="reference internal" href="slice.html">Slice Objects</a></li>
<li class="toctree-l1"><a class="reference internal" href="slice.html#ellipsis-object">Ellipsis Object</a></li>
<li class="toctree-l1"><a class="reference internal" href="weakref.html">Weak Reference Objects</a></li>
<li class="toctree-l1"><a class="reference internal" href="capsule.html">Capsules</a></li>
<li class="toctree-l1"><a class="reference internal" href="cobject.html">CObjects</a></li>
<li class="toctree-l1"><a class="reference internal" href="cell.html">Cell Objects</a></li>
<li class="toctree-l1"><a class="reference internal" href="gen.html">Generator Objects</a></li>
<li class="toctree-l1"><a class="reference internal" href="datetime.html">DateTime Objects</a></li>
<li class="toctree-l1"><a class="reference internal" href="set.html">Set Objects</a></li>
<li class="toctree-l1"><a class="reference internal" href="code.html">Code Objects</a></li>
</ul>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Concrete Objects Layer</a><ul>
<li><a class="reference internal" href="#fundamental-objects">Fundamental Objects</a></li>
<li><a class="reference internal" href="#numeric-objects">Numeric Objects</a></li>
<li><a class="reference internal" href="#sequence-objects">Sequence Objects</a></li>
<li><a class="reference internal" href="#mapping-objects">Mapping Objects</a></li>
<li><a class="reference internal" href="#other-objects">Other Objects</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="objbuffer.html"
title="previous chapter">Old Buffer Protocol</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="type.html"
title="next chapter">Type Objects</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/concrete.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="type.html" title="Type Objects"
>next</a> |</li>
<li class="right" >
<a href="objbuffer.html" title="Old Buffer Protocol"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\&cn[ n[ html/c-api/conversion.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>String conversion and formatting — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Reflection" href="reflection.html" />
<link rel="prev" title="Parsing arguments and building values" href="arg.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/conversion.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="reflection.html" title="Reflection"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="arg.html" title="Parsing arguments and building values"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="utilities.html" accesskey="U">Utilities</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="string-conversion-and-formatting">
<span id="string-conversion"></span><h1>String conversion and formatting<a class="headerlink" href="#string-conversion-and-formatting" title="Permalink to this headline">¶</a></h1>
<p>Functions for number conversion and formatted string output.</p>
<dl class="function">
<dt id="c.PyOS_snprintf">
int <code class="descname">PyOS_snprintf</code><span class="sig-paren">(</span>char<em> *str</em>, size_t<em> size</em>, const char<em> *format</em>, ...<span class="sig-paren">)</span><a class="headerlink" href="#c.PyOS_snprintf" title="Permalink to this definition">¶</a></dt>
<dd><p>Output not more than <em>size</em> bytes to <em>str</em> according to the format string
<em>format</em> and the extra arguments. See the Unix man page <em class="manpage">snprintf(2)</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyOS_vsnprintf">
int <code class="descname">PyOS_vsnprintf</code><span class="sig-paren">(</span>char<em> *str</em>, size_t<em> size</em>, const char<em> *format</em>, va_list<em> va</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyOS_vsnprintf" title="Permalink to this definition">¶</a></dt>
<dd><p>Output not more than <em>size</em> bytes to <em>str</em> according to the format string
<em>format</em> and the variable argument list <em>va</em>. Unix man page
<em class="manpage">vsnprintf(2)</em>.</p>
</dd></dl>
<p><a class="reference internal" href="#c.PyOS_snprintf" title="PyOS_snprintf"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyOS_snprintf()</span></code></a> and <a class="reference internal" href="#c.PyOS_vsnprintf" title="PyOS_vsnprintf"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyOS_vsnprintf()</span></code></a> wrap the Standard C library
functions <code class="xref c c-func docutils literal notranslate"><span class="pre">snprintf()</span></code> and <code class="xref c c-func docutils literal notranslate"><span class="pre">vsnprintf()</span></code>. Their purpose is to
guarantee consistent behavior in corner cases, which the Standard C functions do
not.</p>
<p>The wrappers ensure that <em>str*[*size</em>-1] is always <code class="docutils literal notranslate"><span class="pre">'\0'</span></code> upon return. They
never write more than <em>size</em> bytes (including the trailing <code class="docutils literal notranslate"><span class="pre">'\0'</span></code> into str.
Both functions require that <code class="docutils literal notranslate"><span class="pre">str</span> <span class="pre">!=</span> <span class="pre">NULL</span></code>, <code class="docutils literal notranslate"><span class="pre">size</span> <span class="pre">></span> <span class="pre">0</span></code> and <code class="docutils literal notranslate"><span class="pre">format</span> <span class="pre">!=</span>
<span class="pre">NULL</span></code>.</p>
<p>If the platform doesn’t have <code class="xref c c-func docutils literal notranslate"><span class="pre">vsnprintf()</span></code> and the buffer size needed to
avoid truncation exceeds <em>size</em> by more than 512 bytes, Python aborts with a
<em>Py_FatalError</em>.</p>
<p>The return value (<em>rv</em>) for these functions should be interpreted as follows:</p>
<ul class="simple">
<li>When <code class="docutils literal notranslate"><span class="pre">0</span> <span class="pre"><=</span> <span class="pre">rv</span> <span class="pre"><</span> <span class="pre">size</span></code>, the output conversion was successful and <em>rv</em>
characters were written to <em>str</em> (excluding the trailing <code class="docutils literal notranslate"><span class="pre">'\0'</span></code> byte at
<em>str*[*rv</em>]).</li>
<li>When <code class="docutils literal notranslate"><span class="pre">rv</span> <span class="pre">>=</span> <span class="pre">size</span></code>, the output conversion was truncated and a buffer with
<code class="docutils literal notranslate"><span class="pre">rv</span> <span class="pre">+</span> <span class="pre">1</span></code> bytes would have been needed to succeed. <em>str*[*size</em>-1] is <code class="docutils literal notranslate"><span class="pre">'\0'</span></code>
in this case.</li>
<li>When <code class="docutils literal notranslate"><span class="pre">rv</span> <span class="pre"><</span> <span class="pre">0</span></code>, “something bad happened.” <em>str*[*size</em>-1] is <code class="docutils literal notranslate"><span class="pre">'\0'</span></code> in
this case too, but the rest of <em>str</em> is undefined. The exact cause of the error
depends on the underlying platform.</li>
</ul>
<p>The following functions provide locale-independent string to number conversions.</p>
<dl class="function">
<dt id="c.PyOS_string_to_double">
double <code class="descname">PyOS_string_to_double</code><span class="sig-paren">(</span>const char<em> *s</em>, char<em> **endptr</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *overflow_exception</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyOS_string_to_double" title="Permalink to this definition">¶</a></dt>
<dd><p>Convert a string <code class="docutils literal notranslate"><span class="pre">s</span></code> to a <code class="xref c c-type docutils literal notranslate"><span class="pre">double</span></code>, raising a Python
exception on failure. The set of accepted strings corresponds to
the set of strings accepted by Python’s <a class="reference internal" href="../library/functions.html#float" title="float"><code class="xref py py-func docutils literal notranslate"><span class="pre">float()</span></code></a> constructor,
except that <code class="docutils literal notranslate"><span class="pre">s</span></code> must not have leading or trailing whitespace.
The conversion is independent of the current locale.</p>
<p>If <code class="docutils literal notranslate"><span class="pre">endptr</span></code> is <code class="docutils literal notranslate"><span class="pre">NULL</span></code>, convert the whole string. Raise
ValueError and return <code class="docutils literal notranslate"><span class="pre">-1.0</span></code> if the string is not a valid
representation of a floating-point number.</p>
<p>If endptr is not <code class="docutils literal notranslate"><span class="pre">NULL</span></code>, convert as much of the string as
possible and set <code class="docutils literal notranslate"><span class="pre">*endptr</span></code> to point to the first unconverted
character. If no initial segment of the string is the valid
representation of a floating-point number, set <code class="docutils literal notranslate"><span class="pre">*endptr</span></code> to point
to the beginning of the string, raise ValueError, and return
<code class="docutils literal notranslate"><span class="pre">-1.0</span></code>.</p>
<p>If <code class="docutils literal notranslate"><span class="pre">s</span></code> represents a value that is too large to store in a float
(for example, <code class="docutils literal notranslate"><span class="pre">"1e500"</span></code> is such a string on many platforms) then
if <code class="docutils literal notranslate"><span class="pre">overflow_exception</span></code> is <code class="docutils literal notranslate"><span class="pre">NULL</span></code> return <code class="docutils literal notranslate"><span class="pre">Py_HUGE_VAL</span></code> (with
an appropriate sign) and don’t set any exception. Otherwise,
<code class="docutils literal notranslate"><span class="pre">overflow_exception</span></code> must point to a Python exception object;
raise that exception and return <code class="docutils literal notranslate"><span class="pre">-1.0</span></code>. In both cases, set
<code class="docutils literal notranslate"><span class="pre">*endptr</span></code> to point to the first character after the converted value.</p>
<p>If any other error occurs during the conversion (for example an
out-of-memory error), set the appropriate Python exception and
return <code class="docutils literal notranslate"><span class="pre">-1.0</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.7.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyOS_ascii_strtod">
double <code class="descname">PyOS_ascii_strtod</code><span class="sig-paren">(</span>const char<em> *nptr</em>, char<em> **endptr</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyOS_ascii_strtod" title="Permalink to this definition">¶</a></dt>
<dd><p>Convert a string to a <code class="xref c c-type docutils literal notranslate"><span class="pre">double</span></code>. This function behaves like the Standard C
function <code class="xref c c-func docutils literal notranslate"><span class="pre">strtod()</span></code> does in the C locale. It does this without changing the
current locale, since that would not be thread-safe.</p>
<p><a class="reference internal" href="#c.PyOS_ascii_strtod" title="PyOS_ascii_strtod"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyOS_ascii_strtod()</span></code></a> should typically be used for reading configuration
files or other non-user input that should be locale independent.</p>
<p>See the Unix man page <em class="manpage">strtod(2)</em> for details.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 2.7: </span>Use <a class="reference internal" href="#c.PyOS_string_to_double" title="PyOS_string_to_double"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyOS_string_to_double()</span></code></a> instead.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyOS_ascii_formatd">
char* <code class="descname">PyOS_ascii_formatd</code><span class="sig-paren">(</span>char<em> *buffer</em>, size_t<em> buf_len</em>, const char<em> *format</em>, double<em> d</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyOS_ascii_formatd" title="Permalink to this definition">¶</a></dt>
<dd><p>Convert a <code class="xref c c-type docutils literal notranslate"><span class="pre">double</span></code> to a string using the <code class="docutils literal notranslate"><span class="pre">'.'</span></code> as the decimal
separator. <em>format</em> is a <code class="xref c c-func docutils literal notranslate"><span class="pre">printf()</span></code>-style format string specifying the
number format. Allowed conversion characters are <code class="docutils literal notranslate"><span class="pre">'e'</span></code>, <code class="docutils literal notranslate"><span class="pre">'E'</span></code>, <code class="docutils literal notranslate"><span class="pre">'f'</span></code>,
<code class="docutils literal notranslate"><span class="pre">'F'</span></code>, <code class="docutils literal notranslate"><span class="pre">'g'</span></code> and <code class="docutils literal notranslate"><span class="pre">'G'</span></code>.</p>
<p>The return value is a pointer to <em>buffer</em> with the converted string or NULL if
the conversion failed.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 2.7: </span>This function is removed in Python 2.7 and 3.1. Use <code class="xref py py-func docutils literal notranslate"><span class="pre">PyOS_double_to_string()</span></code>
instead.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyOS_double_to_string">
char* <code class="descname">PyOS_double_to_string</code><span class="sig-paren">(</span>double<em> val</em>, char<em> format_code</em>, int<em> precision</em>, int<em> flags</em>, int<em> *ptype</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyOS_double_to_string" title="Permalink to this definition">¶</a></dt>
<dd><p>Convert a <code class="xref c c-type docutils literal notranslate"><span class="pre">double</span></code> <em>val</em> to a string using supplied
<em>format_code</em>, <em>precision</em>, and <em>flags</em>.</p>
<p><em>format_code</em> must be one of <code class="docutils literal notranslate"><span class="pre">'e'</span></code>, <code class="docutils literal notranslate"><span class="pre">'E'</span></code>, <code class="docutils literal notranslate"><span class="pre">'f'</span></code>, <code class="docutils literal notranslate"><span class="pre">'F'</span></code>,
<code class="docutils literal notranslate"><span class="pre">'g'</span></code>, <code class="docutils literal notranslate"><span class="pre">'G'</span></code> or <code class="docutils literal notranslate"><span class="pre">'r'</span></code>. For <code class="docutils literal notranslate"><span class="pre">'r'</span></code>, the supplied <em>precision</em>
must be <code class="docutils literal notranslate"><span class="pre">0</span></code> and is ignored. The <code class="docutils literal notranslate"><span class="pre">'r'</span></code> format code specifies the
standard <a class="reference internal" href="../library/functions.html#repr" title="repr"><code class="xref py py-func docutils literal notranslate"><span class="pre">repr()</span></code></a> format.</p>
<p><em>flags</em> can be zero or more of the values <em>Py_DTSF_SIGN</em>,
<em>Py_DTSF_ADD_DOT_0</em>, or <em>Py_DTSF_ALT</em>, or-ed together:</p>
<ul class="simple">
<li><em>Py_DTSF_SIGN</em> means to always precede the returned string with a sign
character, even if <em>val</em> is non-negative.</li>
<li><em>Py_DTSF_ADD_DOT_0</em> means to ensure that the returned string will not look
like an integer.</li>
<li><em>Py_DTSF_ALT</em> means to apply “alternate” formatting rules. See the
documentation for the <a class="reference internal" href="#c.PyOS_snprintf" title="PyOS_snprintf"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyOS_snprintf()</span></code></a> <code class="docutils literal notranslate"><span class="pre">'#'</span></code> specifier for
details.</li>
</ul>
<p>If <em>ptype</em> is non-NULL, then the value it points to will be set to one of
<em>Py_DTST_FINITE</em>, <em>Py_DTST_INFINITE</em>, or <em>Py_DTST_NAN</em>, signifying that
<em>val</em> is a finite number, an infinite number, or not a number, respectively.</p>
<p>The return value is a pointer to <em>buffer</em> with the converted string or
<em>NULL</em> if the conversion failed. The caller is responsible for freeing the
returned string by calling <a class="reference internal" href="memory.html#c.PyMem_Free" title="PyMem_Free"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyMem_Free()</span></code></a>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.7.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyOS_ascii_atof">
double <code class="descname">PyOS_ascii_atof</code><span class="sig-paren">(</span>const char<em> *nptr</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyOS_ascii_atof" title="Permalink to this definition">¶</a></dt>
<dd><p>Convert a string to a <code class="xref c c-type docutils literal notranslate"><span class="pre">double</span></code> in a locale-independent way.</p>
<p>See the Unix man page <em class="manpage">atof(2)</em> for details.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 3.1: </span>Use <a class="reference internal" href="#c.PyOS_string_to_double" title="PyOS_string_to_double"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyOS_string_to_double()</span></code></a> instead.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyOS_stricmp">
char* <code class="descname">PyOS_stricmp</code><span class="sig-paren">(</span>char<em> *s1</em>, char<em> *s2</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyOS_stricmp" title="Permalink to this definition">¶</a></dt>
<dd><p>Case insensitive comparison of strings. The function works almost
identically to <code class="xref c c-func docutils literal notranslate"><span class="pre">strcmp()</span></code> except that it ignores the case.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyOS_strnicmp">
char* <code class="descname">PyOS_strnicmp</code><span class="sig-paren">(</span>char<em> *s1</em>, char<em> *s2</em>, Py_ssize_t <em> size</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyOS_strnicmp" title="Permalink to this definition">¶</a></dt>
<dd><p>Case insensitive comparison of strings. The function works almost
identically to <code class="xref c c-func docutils literal notranslate"><span class="pre">strncmp()</span></code> except that it ignores the case.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="arg.html"
title="previous chapter">Parsing arguments and building values</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="reflection.html"
title="next chapter">Reflection</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/conversion.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="reflection.html" title="Reflection"
>next</a> |</li>
<li class="right" >
<a href="arg.html" title="Parsing arguments and building values"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="utilities.html" >Utilities</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\�g��eg eg html/c-api/datetime.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>DateTime Objects — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Set Objects" href="set.html" />
<link rel="prev" title="Generator Objects" href="gen.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/datetime.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="set.html" title="Set Objects"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="gen.html" title="Generator Objects"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" accesskey="U">Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="datetime-objects">
<span id="datetimeobjects"></span><h1>DateTime Objects<a class="headerlink" href="#datetime-objects" title="Permalink to this headline">¶</a></h1>
<p>Various date and time objects are supplied by the <a class="reference internal" href="../library/datetime.html#module-datetime" title="datetime: Basic date and time types."><code class="xref py py-mod docutils literal notranslate"><span class="pre">datetime</span></code></a> module.
Before using any of these functions, the header file <code class="file docutils literal notranslate"><span class="pre">datetime.h</span></code> must be
included in your source (note that this is not included by <code class="file docutils literal notranslate"><span class="pre">Python.h</span></code>),
and the macro <code class="xref c c-macro docutils literal notranslate"><span class="pre">PyDateTime_IMPORT</span></code> must be invoked, usually as part of
the module initialisation function. The macro puts a pointer to a C structure
into a static variable, <code class="xref c c-data docutils literal notranslate"><span class="pre">PyDateTimeAPI</span></code>, that is used by the following
macros.</p>
<p>Type-check macros:</p>
<dl class="function">
<dt id="c.PyDate_Check">
int <code class="descname">PyDate_Check</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *ob</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDate_Check" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if <em>ob</em> is of type <code class="xref c c-data docutils literal notranslate"><span class="pre">PyDateTime_DateType</span></code> or a subtype of
<code class="xref c c-data docutils literal notranslate"><span class="pre">PyDateTime_DateType</span></code>. <em>ob</em> must not be <em>NULL</em>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyDate_CheckExact">
int <code class="descname">PyDate_CheckExact</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *ob</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDate_CheckExact" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if <em>ob</em> is of type <code class="xref c c-data docutils literal notranslate"><span class="pre">PyDateTime_DateType</span></code>. <em>ob</em> must not be
<em>NULL</em>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyDateTime_Check">
int <code class="descname">PyDateTime_Check</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *ob</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDateTime_Check" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if <em>ob</em> is of type <code class="xref c c-data docutils literal notranslate"><span class="pre">PyDateTime_DateTimeType</span></code> or a subtype of
<code class="xref c c-data docutils literal notranslate"><span class="pre">PyDateTime_DateTimeType</span></code>. <em>ob</em> must not be <em>NULL</em>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyDateTime_CheckExact">
int <code class="descname">PyDateTime_CheckExact</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *ob</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDateTime_CheckExact" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if <em>ob</em> is of type <code class="xref c c-data docutils literal notranslate"><span class="pre">PyDateTime_DateTimeType</span></code>. <em>ob</em> must not
be <em>NULL</em>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyTime_Check">
int <code class="descname">PyTime_Check</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *ob</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyTime_Check" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if <em>ob</em> is of type <code class="xref c c-data docutils literal notranslate"><span class="pre">PyDateTime_TimeType</span></code> or a subtype of
<code class="xref c c-data docutils literal notranslate"><span class="pre">PyDateTime_TimeType</span></code>. <em>ob</em> must not be <em>NULL</em>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyTime_CheckExact">
int <code class="descname">PyTime_CheckExact</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *ob</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyTime_CheckExact" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if <em>ob</em> is of type <code class="xref c c-data docutils literal notranslate"><span class="pre">PyDateTime_TimeType</span></code>. <em>ob</em> must not be
<em>NULL</em>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyDelta_Check">
int <code class="descname">PyDelta_Check</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *ob</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDelta_Check" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if <em>ob</em> is of type <code class="xref c c-data docutils literal notranslate"><span class="pre">PyDateTime_DeltaType</span></code> or a subtype of
<code class="xref c c-data docutils literal notranslate"><span class="pre">PyDateTime_DeltaType</span></code>. <em>ob</em> must not be <em>NULL</em>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyDelta_CheckExact">
int <code class="descname">PyDelta_CheckExact</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *ob</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDelta_CheckExact" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if <em>ob</em> is of type <code class="xref c c-data docutils literal notranslate"><span class="pre">PyDateTime_DeltaType</span></code>. <em>ob</em> must not be
<em>NULL</em>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyTZInfo_Check">
int <code class="descname">PyTZInfo_Check</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *ob</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyTZInfo_Check" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if <em>ob</em> is of type <code class="xref c c-data docutils literal notranslate"><span class="pre">PyDateTime_TZInfoType</span></code> or a subtype of
<code class="xref c c-data docutils literal notranslate"><span class="pre">PyDateTime_TZInfoType</span></code>. <em>ob</em> must not be <em>NULL</em>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyTZInfo_CheckExact">
int <code class="descname">PyTZInfo_CheckExact</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *ob</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyTZInfo_CheckExact" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if <em>ob</em> is of type <code class="xref c c-data docutils literal notranslate"><span class="pre">PyDateTime_TZInfoType</span></code>. <em>ob</em> must not be
<em>NULL</em>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
</dd></dl>
<p>Macros to create objects:</p>
<dl class="function">
<dt id="c.PyDate_FromDate">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyDate_FromDate</code><span class="sig-paren">(</span>int<em> year</em>, int<em> month</em>, int<em> day</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDate_FromDate" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a <code class="docutils literal notranslate"><span class="pre">datetime.date</span></code> object with the specified year, month and day.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyDateTime_FromDateAndTime">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyDateTime_FromDateAndTime</code><span class="sig-paren">(</span>int<em> year</em>, int<em> month</em>, int<em> day</em>, int<em> hour</em>, int<em> minute</em>, int<em> second</em>, int<em> usecond</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDateTime_FromDateAndTime" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a <code class="docutils literal notranslate"><span class="pre">datetime.datetime</span></code> object with the specified year, month, day, hour,
minute, second and microsecond.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyTime_FromTime">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyTime_FromTime</code><span class="sig-paren">(</span>int<em> hour</em>, int<em> minute</em>, int<em> second</em>, int<em> usecond</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyTime_FromTime" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a <code class="docutils literal notranslate"><span class="pre">datetime.time</span></code> object with the specified hour, minute, second and
microsecond.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyDelta_FromDSU">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyDelta_FromDSU</code><span class="sig-paren">(</span>int<em> days</em>, int<em> seconds</em>, int<em> useconds</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDelta_FromDSU" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a <code class="docutils literal notranslate"><span class="pre">datetime.timedelta</span></code> object representing the given number of days,
seconds and microseconds. Normalization is performed so that the resulting
number of microseconds and seconds lie in the ranges documented for
<code class="docutils literal notranslate"><span class="pre">datetime.timedelta</span></code> objects.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
</dd></dl>
<p>Macros to extract fields from date objects. The argument must be an instance of
<code class="xref c c-data docutils literal notranslate"><span class="pre">PyDateTime_Date</span></code>, including subclasses (such as
<code class="xref c c-data docutils literal notranslate"><span class="pre">PyDateTime_DateTime</span></code>). The argument must not be <em>NULL</em>, and the type is
not checked:</p>
<dl class="function">
<dt id="c.PyDateTime_GET_YEAR">
int <code class="descname">PyDateTime_GET_YEAR</code><span class="sig-paren">(</span>PyDateTime_Date<em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDateTime_GET_YEAR" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the year, as a positive int.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyDateTime_GET_MONTH">
int <code class="descname">PyDateTime_GET_MONTH</code><span class="sig-paren">(</span>PyDateTime_Date<em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDateTime_GET_MONTH" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the month, as an int from 1 through 12.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyDateTime_GET_DAY">
int <code class="descname">PyDateTime_GET_DAY</code><span class="sig-paren">(</span>PyDateTime_Date<em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDateTime_GET_DAY" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the day, as an int from 1 through 31.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
</dd></dl>
<p>Macros to extract fields from datetime objects. The argument must be an
instance of <code class="xref c c-data docutils literal notranslate"><span class="pre">PyDateTime_DateTime</span></code>, including subclasses. The argument
must not be <em>NULL</em>, and the type is not checked:</p>
<dl class="function">
<dt id="c.PyDateTime_DATE_GET_HOUR">
int <code class="descname">PyDateTime_DATE_GET_HOUR</code><span class="sig-paren">(</span>PyDateTime_DateTime<em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDateTime_DATE_GET_HOUR" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the hour, as an int from 0 through 23.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyDateTime_DATE_GET_MINUTE">
int <code class="descname">PyDateTime_DATE_GET_MINUTE</code><span class="sig-paren">(</span>PyDateTime_DateTime<em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDateTime_DATE_GET_MINUTE" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the minute, as an int from 0 through 59.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyDateTime_DATE_GET_SECOND">
int <code class="descname">PyDateTime_DATE_GET_SECOND</code><span class="sig-paren">(</span>PyDateTime_DateTime<em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDateTime_DATE_GET_SECOND" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the second, as an int from 0 through 59.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyDateTime_DATE_GET_MICROSECOND">
int <code class="descname">PyDateTime_DATE_GET_MICROSECOND</code><span class="sig-paren">(</span>PyDateTime_DateTime<em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDateTime_DATE_GET_MICROSECOND" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the microsecond, as an int from 0 through 999999.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
</dd></dl>
<p>Macros to extract fields from time objects. The argument must be an instance of
<code class="xref c c-data docutils literal notranslate"><span class="pre">PyDateTime_Time</span></code>, including subclasses. The argument must not be <em>NULL</em>,
and the type is not checked:</p>
<dl class="function">
<dt id="c.PyDateTime_TIME_GET_HOUR">
int <code class="descname">PyDateTime_TIME_GET_HOUR</code><span class="sig-paren">(</span>PyDateTime_Time<em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDateTime_TIME_GET_HOUR" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the hour, as an int from 0 through 23.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyDateTime_TIME_GET_MINUTE">
int <code class="descname">PyDateTime_TIME_GET_MINUTE</code><span class="sig-paren">(</span>PyDateTime_Time<em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDateTime_TIME_GET_MINUTE" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the minute, as an int from 0 through 59.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyDateTime_TIME_GET_SECOND">
int <code class="descname">PyDateTime_TIME_GET_SECOND</code><span class="sig-paren">(</span>PyDateTime_Time<em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDateTime_TIME_GET_SECOND" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the second, as an int from 0 through 59.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyDateTime_TIME_GET_MICROSECOND">
int <code class="descname">PyDateTime_TIME_GET_MICROSECOND</code><span class="sig-paren">(</span>PyDateTime_Time<em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDateTime_TIME_GET_MICROSECOND" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the microsecond, as an int from 0 through 999999.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
</dd></dl>
<p>Macros for the convenience of modules implementing the DB API:</p>
<dl class="function">
<dt id="c.PyDateTime_FromTimestamp">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyDateTime_FromTimestamp</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *args</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDateTime_FromTimestamp" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Create and return a new <code class="docutils literal notranslate"><span class="pre">datetime.datetime</span></code> object given an argument tuple
suitable for passing to <code class="docutils literal notranslate"><span class="pre">datetime.datetime.fromtimestamp()</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyDate_FromTimestamp">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyDate_FromTimestamp</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *args</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDate_FromTimestamp" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Create and return a new <code class="docutils literal notranslate"><span class="pre">datetime.date</span></code> object given an argument tuple
suitable for passing to <code class="docutils literal notranslate"><span class="pre">datetime.date.fromtimestamp()</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="gen.html"
title="previous chapter">Generator Objects</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="set.html"
title="next chapter">Set Objects</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/datetime.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="set.html" title="Set Objects"
>next</a> |</li>
<li class="right" >
<a href="gen.html" title="Generator Objects"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" >Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\
kc/ / html/c-api/descriptor.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Descriptor Objects — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Slice Objects" href="slice.html" />
<link rel="prev" title="Iterator Objects" href="iterator.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/descriptor.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="slice.html" title="Slice Objects"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="iterator.html" title="Iterator Objects"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" accesskey="U">Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="descriptor-objects">
<span id="id1"></span><h1>Descriptor Objects<a class="headerlink" href="#descriptor-objects" title="Permalink to this headline">¶</a></h1>
<p>“Descriptors” are objects that describe some attribute of an object. They are
found in the dictionary of type objects.</p>
<dl class="var">
<dt id="c.PyProperty_Type">
<a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a> <code class="descname">PyProperty_Type</code><a class="headerlink" href="#c.PyProperty_Type" title="Permalink to this definition">¶</a></dt>
<dd><p>The type object for the built-in descriptor types.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyDescr_NewGetSet">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyDescr_NewGetSet</code><span class="sig-paren">(</span><a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a><em> *type</em>, struct <a class="reference internal" href="structures.html#c.PyGetSetDef" title="PyGetSetDef">PyGetSetDef</a><em> *getset</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDescr_NewGetSet" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyDescr_NewMember">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyDescr_NewMember</code><span class="sig-paren">(</span><a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a><em> *type</em>, struct <a class="reference internal" href="structures.html#c.PyMemberDef" title="PyMemberDef">PyMemberDef</a><em> *meth</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDescr_NewMember" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyDescr_NewMethod">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyDescr_NewMethod</code><span class="sig-paren">(</span><a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a><em> *type</em>, struct <a class="reference internal" href="structures.html#c.PyMethodDef" title="PyMethodDef">PyMethodDef</a><em> *meth</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDescr_NewMethod" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyDescr_NewWrapper">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyDescr_NewWrapper</code><span class="sig-paren">(</span><a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a><em> *type</em>, struct wrapperbase<em> *wrapper</em>, void<em> *wrapped</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDescr_NewWrapper" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyDescr_NewClassMethod">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyDescr_NewClassMethod</code><span class="sig-paren">(</span><a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a><em> *type</em>, <a class="reference internal" href="structures.html#c.PyMethodDef" title="PyMethodDef">PyMethodDef</a><em> *method</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDescr_NewClassMethod" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><div class="versionadded">
<p><span class="versionmodified">New in version 2.3.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyDescr_IsData">
int <code class="descname">PyDescr_IsData</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *descr</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDescr_IsData" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if the descriptor objects <em>descr</em> describes a data attribute, or
false if it describes a method. <em>descr</em> must be a descriptor object; there is
no error checking.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyWrapper_New">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyWrapper_New</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyWrapper_New" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="iterator.html"
title="previous chapter">Iterator Objects</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="slice.html"
title="next chapter">Slice Objects</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/descriptor.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="slice.html" title="Slice Objects"
>next</a> |</li>
<li class="right" >
<a href="iterator.html" title="Iterator Objects"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" >Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\��Ɓ Ɓ html/c-api/dict.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Dictionary Objects — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Class and Instance Objects" href="class.html" />
<link rel="prev" title="List Objects" href="list.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/dict.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="class.html" title="Class and Instance Objects"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="list.html" title="List Objects"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" accesskey="U">Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="dictionary-objects">
<span id="dictobjects"></span><h1>Dictionary Objects<a class="headerlink" href="#dictionary-objects" title="Permalink to this headline">¶</a></h1>
<span class="target" id="index-0"></span><dl class="type">
<dt id="c.PyDictObject">
<code class="descname">PyDictObject</code><a class="headerlink" href="#c.PyDictObject" title="Permalink to this definition">¶</a></dt>
<dd><p>This subtype of <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject</span></code></a> represents a Python dictionary object.</p>
</dd></dl>
<dl class="var">
<dt id="c.PyDict_Type">
<a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a> <code class="descname">PyDict_Type</code><a class="headerlink" href="#c.PyDict_Type" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-1">This instance of <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyTypeObject</span></code></a> represents the Python dictionary
type. This is exposed to Python programs as <code class="docutils literal notranslate"><span class="pre">dict</span></code> and
<code class="docutils literal notranslate"><span class="pre">types.DictType</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyDict_Check">
int <code class="descname">PyDict_Check</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDict_Check" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if <em>p</em> is a dict object or an instance of a subtype of the dict
type.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.2: </span>Allowed subtypes to be accepted.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyDict_CheckExact">
int <code class="descname">PyDict_CheckExact</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDict_CheckExact" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if <em>p</em> is a dict object, but not an instance of a subtype of
the dict type.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyDict_New">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyDict_New</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDict_New" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a new empty dictionary, or <em>NULL</em> on failure.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyDictProxy_New">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyDictProxy_New</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *dict</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDictProxy_New" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a proxy object for a mapping which enforces read-only behavior.
This is normally used to create a proxy to prevent modification of the
dictionary for non-dynamic class types.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyDict_Clear">
void <code class="descname">PyDict_Clear</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDict_Clear" title="Permalink to this definition">¶</a></dt>
<dd><p>Empty an existing dictionary of all key-value pairs.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyDict_Contains">
int <code class="descname">PyDict_Contains</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *key</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDict_Contains" title="Permalink to this definition">¶</a></dt>
<dd><p>Determine if dictionary <em>p</em> contains <em>key</em>. If an item in <em>p</em> is matches
<em>key</em>, return <code class="docutils literal notranslate"><span class="pre">1</span></code>, otherwise return <code class="docutils literal notranslate"><span class="pre">0</span></code>. On error, return <code class="docutils literal notranslate"><span class="pre">-1</span></code>.
This is equivalent to the Python expression <code class="docutils literal notranslate"><span class="pre">key</span> <span class="pre">in</span> <span class="pre">p</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyDict_Copy">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyDict_Copy</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDict_Copy" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a new dictionary that contains the same key-value pairs as <em>p</em>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.6.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyDict_SetItem">
int <code class="descname">PyDict_SetItem</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *key</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *val</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDict_SetItem" title="Permalink to this definition">¶</a></dt>
<dd><p>Insert <em>value</em> into the dictionary <em>p</em> with a key of <em>key</em>. <em>key</em> must be
<a class="reference internal" href="../glossary.html#term-hashable"><span class="xref std std-term">hashable</span></a>; if it isn’t, <a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> will be raised. Return
<code class="docutils literal notranslate"><span class="pre">0</span></code> on success or <code class="docutils literal notranslate"><span class="pre">-1</span></code> on failure.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyDict_SetItemString">
int <code class="descname">PyDict_SetItemString</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em>, const char<em> *key</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *val</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDict_SetItemString" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-2">Insert <em>value</em> into the dictionary <em>p</em> using <em>key</em> as a key. <em>key</em> should
be a <code class="xref c c-type docutils literal notranslate"><span class="pre">char*</span></code>. The key object is created using
<code class="docutils literal notranslate"><span class="pre">PyString_FromString(key)</span></code>. Return <code class="docutils literal notranslate"><span class="pre">0</span></code> on success or <code class="docutils literal notranslate"><span class="pre">-1</span></code> on
failure.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyDict_DelItem">
int <code class="descname">PyDict_DelItem</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *key</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDict_DelItem" title="Permalink to this definition">¶</a></dt>
<dd><p>Remove the entry in dictionary <em>p</em> with key <em>key</em>. <em>key</em> must be hashable;
if it isn’t, <a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> is raised. Return <code class="docutils literal notranslate"><span class="pre">0</span></code> on success or <code class="docutils literal notranslate"><span class="pre">-1</span></code>
on failure.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyDict_DelItemString">
int <code class="descname">PyDict_DelItemString</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em>, char<em> *key</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDict_DelItemString" title="Permalink to this definition">¶</a></dt>
<dd><p>Remove the entry in dictionary <em>p</em> which has a key specified by the string
<em>key</em>. Return <code class="docutils literal notranslate"><span class="pre">0</span></code> on success or <code class="docutils literal notranslate"><span class="pre">-1</span></code> on failure.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyDict_GetItem">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyDict_GetItem</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *key</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDict_GetItem" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Borrowed reference.</em><p>Return the object from dictionary <em>p</em> which has a key <em>key</em>. Return <em>NULL</em>
if the key <em>key</em> is not present, but <em>without</em> setting an exception.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyDict_GetItemString">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyDict_GetItemString</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em>, const char<em> *key</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDict_GetItemString" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Borrowed reference.</em><p>This is the same as <a class="reference internal" href="#c.PyDict_GetItem" title="PyDict_GetItem"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyDict_GetItem()</span></code></a>, but <em>key</em> is specified as a
<code class="xref c c-type docutils literal notranslate"><span class="pre">char*</span></code>, rather than a <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject*</span></code></a>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyDict_Items">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyDict_Items</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDict_Items" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a <a class="reference internal" href="list.html#c.PyListObject" title="PyListObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyListObject</span></code></a> containing all the items from the
dictionary, as in the dictionary method <a class="reference internal" href="../library/stdtypes.html#dict.items" title="dict.items"><code class="xref py py-meth docutils literal notranslate"><span class="pre">dict.items()</span></code></a>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyDict_Keys">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyDict_Keys</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDict_Keys" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a <a class="reference internal" href="list.html#c.PyListObject" title="PyListObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyListObject</span></code></a> containing all the keys from the dictionary,
as in the dictionary method <a class="reference internal" href="../library/stdtypes.html#dict.keys" title="dict.keys"><code class="xref py py-meth docutils literal notranslate"><span class="pre">dict.keys()</span></code></a>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyDict_Values">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyDict_Values</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDict_Values" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a <a class="reference internal" href="list.html#c.PyListObject" title="PyListObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyListObject</span></code></a> containing all the values from the
dictionary <em>p</em>, as in the dictionary method <a class="reference internal" href="../library/stdtypes.html#dict.values" title="dict.values"><code class="xref py py-meth docutils literal notranslate"><span class="pre">dict.values()</span></code></a>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyDict_Size">
Py_ssize_t <code class="descname">PyDict_Size</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDict_Size" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-3">Return the number of items in the dictionary. This is equivalent to
<code class="docutils literal notranslate"><span class="pre">len(p)</span></code> on a dictionary.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function returned an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type. This might require changes
in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyDict_Next">
int <code class="descname">PyDict_Next</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em>, Py_ssize_t<em> *ppos</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> **pkey</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> **pvalue</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDict_Next" title="Permalink to this definition">¶</a></dt>
<dd><p>Iterate over all key-value pairs in the dictionary <em>p</em>. The
<code class="xref c c-type docutils literal notranslate"><span class="pre">Py_ssize_t</span></code> referred to by <em>ppos</em> must be initialized to <code class="docutils literal notranslate"><span class="pre">0</span></code>
prior to the first call to this function to start the iteration; the
function returns true for each pair in the dictionary, and false once all
pairs have been reported. The parameters <em>pkey</em> and <em>pvalue</em> should either
point to <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject*</span></code></a> variables that will be filled in with each key
and value, respectively, or may be <em>NULL</em>. Any references returned through
them are borrowed. <em>ppos</em> should not be altered during iteration. Its
value represents offsets within the internal dictionary structure, and
since the structure is sparse, the offsets are not consecutive.</p>
<p>For example:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">PyObject</span> <span class="o">*</span><span class="n">key</span><span class="p">,</span> <span class="o">*</span><span class="n">value</span><span class="p">;</span>
<span class="n">Py_ssize_t</span> <span class="n">pos</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
<span class="k">while</span> <span class="p">(</span><span class="n">PyDict_Next</span><span class="p">(</span><span class="n">self</span><span class="o">-></span><span class="n">dict</span><span class="p">,</span> <span class="o">&</span><span class="n">pos</span><span class="p">,</span> <span class="o">&</span><span class="n">key</span><span class="p">,</span> <span class="o">&</span><span class="n">value</span><span class="p">))</span> <span class="p">{</span>
<span class="cm">/* do something interesting with the values... */</span>
<span class="p">...</span>
<span class="p">}</span>
</pre></div>
</div>
<p>The dictionary <em>p</em> should not be mutated during iteration. It is safe
(since Python 2.1) to modify the values of the keys as you iterate over the
dictionary, but only so long as the set of keys does not change. For
example:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">PyObject</span> <span class="o">*</span><span class="n">key</span><span class="p">,</span> <span class="o">*</span><span class="n">value</span><span class="p">;</span>
<span class="n">Py_ssize_t</span> <span class="n">pos</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
<span class="k">while</span> <span class="p">(</span><span class="n">PyDict_Next</span><span class="p">(</span><span class="n">self</span><span class="o">-></span><span class="n">dict</span><span class="p">,</span> <span class="o">&</span><span class="n">pos</span><span class="p">,</span> <span class="o">&</span><span class="n">key</span><span class="p">,</span> <span class="o">&</span><span class="n">value</span><span class="p">))</span> <span class="p">{</span>
<span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="n">PyInt_AS_LONG</span><span class="p">(</span><span class="n">value</span><span class="p">)</span> <span class="o">+</span> <span class="mi">1</span><span class="p">;</span>
<span class="n">PyObject</span> <span class="o">*</span><span class="n">o</span> <span class="o">=</span> <span class="n">PyInt_FromLong</span><span class="p">(</span><span class="n">i</span><span class="p">);</span>
<span class="k">if</span> <span class="p">(</span><span class="n">o</span> <span class="o">==</span> <span class="nb">NULL</span><span class="p">)</span>
<span class="k">return</span> <span class="o">-</span><span class="mi">1</span><span class="p">;</span>
<span class="k">if</span> <span class="p">(</span><span class="n">PyDict_SetItem</span><span class="p">(</span><span class="n">self</span><span class="o">-></span><span class="n">dict</span><span class="p">,</span> <span class="n">key</span><span class="p">,</span> <span class="n">o</span><span class="p">)</span> <span class="o"><</span> <span class="mi">0</span><span class="p">)</span> <span class="p">{</span>
<span class="n">Py_DECREF</span><span class="p">(</span><span class="n">o</span><span class="p">);</span>
<span class="k">return</span> <span class="o">-</span><span class="mi">1</span><span class="p">;</span>
<span class="p">}</span>
<span class="n">Py_DECREF</span><span class="p">(</span><span class="n">o</span><span class="p">);</span>
<span class="p">}</span>
</pre></div>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span> <span class="pre">*</span></code> type for <em>ppos</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyDict_Merge">
int <code class="descname">PyDict_Merge</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *a</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *b</em>, int<em> override</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDict_Merge" title="Permalink to this definition">¶</a></dt>
<dd><p>Iterate over mapping object <em>b</em> adding key-value pairs to dictionary <em>a</em>.
<em>b</em> may be a dictionary, or any object supporting <a class="reference internal" href="mapping.html#c.PyMapping_Keys" title="PyMapping_Keys"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyMapping_Keys()</span></code></a>
and <a class="reference internal" href="object.html#c.PyObject_GetItem" title="PyObject_GetItem"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_GetItem()</span></code></a>. If <em>override</em> is true, existing pairs in <em>a</em>
will be replaced if a matching key is found in <em>b</em>, otherwise pairs will
only be added if there is not a matching key in <em>a</em>. Return <code class="docutils literal notranslate"><span class="pre">0</span></code> on
success or <code class="docutils literal notranslate"><span class="pre">-1</span></code> if an exception was raised.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyDict_Update">
int <code class="descname">PyDict_Update</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *a</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *b</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDict_Update" title="Permalink to this definition">¶</a></dt>
<dd><p>This is the same as <code class="docutils literal notranslate"><span class="pre">PyDict_Merge(a,</span> <span class="pre">b,</span> <span class="pre">1)</span></code> in C, and is similar to
<code class="docutils literal notranslate"><span class="pre">a.update(b)</span></code> in Python except that <a class="reference internal" href="#c.PyDict_Update" title="PyDict_Update"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyDict_Update()</span></code></a> doesn’t fall
back to the iterating over a sequence of key value pairs if the second
argument has no “keys” attribute. Return <code class="docutils literal notranslate"><span class="pre">0</span></code> on success or <code class="docutils literal notranslate"><span class="pre">-1</span></code> if an
exception was raised.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyDict_MergeFromSeq2">
int <code class="descname">PyDict_MergeFromSeq2</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *a</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *seq2</em>, int<em> override</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyDict_MergeFromSeq2" title="Permalink to this definition">¶</a></dt>
<dd><p>Update or merge into dictionary <em>a</em>, from the key-value pairs in <em>seq2</em>.
<em>seq2</em> must be an iterable object producing iterable objects of length 2,
viewed as key-value pairs. In case of duplicate keys, the last wins if
<em>override</em> is true, else the first wins. Return <code class="docutils literal notranslate"><span class="pre">0</span></code> on success or <code class="docutils literal notranslate"><span class="pre">-1</span></code>
if an exception was raised. Equivalent Python (except for the return
value):</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">def</span> <span class="n">PyDict_MergeFromSeq2</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">seq2</span><span class="p">,</span> <span class="n">override</span><span class="p">)</span><span class="o">:</span>
<span class="k">for</span> <span class="n">key</span><span class="p">,</span> <span class="n">value</span> <span class="n">in</span> <span class="nl">seq2</span><span class="p">:</span>
<span class="k">if</span> <span class="n">override</span> <span class="n">or</span> <span class="n">key</span> <span class="n">not</span> <span class="n">in</span> <span class="nl">a</span><span class="p">:</span>
<span class="n">a</span><span class="p">[</span><span class="n">key</span><span class="p">]</span> <span class="o">=</span> <span class="n">value</span>
</pre></div>
</div>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="list.html"
title="previous chapter">List Objects</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="class.html"
title="next chapter">Class and Instance Objects</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/dict.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="class.html" title="Class and Instance Objects"
>next</a> |</li>
<li class="right" >
<a href="list.html" title="List Objects"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" >Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\�Q\tGk Gk html/c-api/exceptions.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Exception Handling — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Utilities" href="utilities.html" />
<link rel="prev" title="Reference Counting" href="refcounting.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/exceptions.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="utilities.html" title="Utilities"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="refcounting.html" title="Reference Counting"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Python/C API Reference Manual</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="exception-handling">
<span id="exceptionhandling"></span><h1>Exception Handling<a class="headerlink" href="#exception-handling" title="Permalink to this headline">¶</a></h1>
<p>The functions described in this chapter will let you handle and raise Python
exceptions. It is important to understand some of the basics of Python
exception handling. It works somewhat like the Unix <code class="xref c c-data docutils literal notranslate"><span class="pre">errno</span></code> variable:
there is a global indicator (per thread) of the last error that occurred. Most
functions don’t clear this on success, but will set it to indicate the cause of
the error on failure. Most functions also return an error indicator, usually
<em>NULL</em> if they are supposed to return a pointer, or <code class="docutils literal notranslate"><span class="pre">-1</span></code> if they return an
integer (exception: the <code class="xref c c-func docutils literal notranslate"><span class="pre">PyArg_*()</span></code> functions return <code class="docutils literal notranslate"><span class="pre">1</span></code> for success and
<code class="docutils literal notranslate"><span class="pre">0</span></code> for failure).</p>
<p>When a function must fail because some function it called failed, it generally
doesn’t set the error indicator; the function it called already set it. It is
responsible for either handling the error and clearing the exception or
returning after cleaning up any resources it holds (such as object references or
memory allocations); it should <em>not</em> continue normally if it is not prepared to
handle the error. If returning due to an error, it is important to indicate to
the caller that an error has been set. If the error is not handled or carefully
propagated, additional calls into the Python/C API may not behave as intended
and may fail in mysterious ways.</p>
<p id="index-0">The error indicator consists of three Python objects corresponding to the
Python variables <code class="docutils literal notranslate"><span class="pre">sys.exc_type</span></code>, <code class="docutils literal notranslate"><span class="pre">sys.exc_value</span></code> and <code class="docutils literal notranslate"><span class="pre">sys.exc_traceback</span></code>.
API functions exist to interact with the error indicator in various ways. There
is a separate error indicator for each thread.</p>
<dl class="function">
<dt id="c.PyErr_PrintEx">
void <code class="descname">PyErr_PrintEx</code><span class="sig-paren">(</span>int<em> set_sys_last_vars</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyErr_PrintEx" title="Permalink to this definition">¶</a></dt>
<dd><p>Print a standard traceback to <code class="docutils literal notranslate"><span class="pre">sys.stderr</span></code> and clear the error indicator.
Call this function only when the error indicator is set. (Otherwise it will
cause a fatal error!)</p>
<p>If <em>set_sys_last_vars</em> is nonzero, the variables <a class="reference internal" href="../library/sys.html#sys.last_type" title="sys.last_type"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.last_type</span></code></a>,
<a class="reference internal" href="../library/sys.html#sys.last_value" title="sys.last_value"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.last_value</span></code></a> and <a class="reference internal" href="../library/sys.html#sys.last_traceback" title="sys.last_traceback"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.last_traceback</span></code></a> will be set to the
type, value and traceback of the printed exception, respectively.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyErr_Print">
void <code class="descname">PyErr_Print</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyErr_Print" title="Permalink to this definition">¶</a></dt>
<dd><p>Alias for <code class="docutils literal notranslate"><span class="pre">PyErr_PrintEx(1)</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyErr_Occurred">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyErr_Occurred</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyErr_Occurred" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Borrowed reference.</em><p>Test whether the error indicator is set. If set, return the exception <em>type</em>
(the first argument to the last call to one of the <code class="xref c c-func docutils literal notranslate"><span class="pre">PyErr_Set*()</span></code>
functions or to <a class="reference internal" href="#c.PyErr_Restore" title="PyErr_Restore"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyErr_Restore()</span></code></a>). If not set, return <em>NULL</em>. You do not
own a reference to the return value, so you do not need to <a class="reference internal" href="refcounting.html#c.Py_DECREF" title="Py_DECREF"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_DECREF()</span></code></a>
it.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Do not compare the return value to a specific exception; use
<a class="reference internal" href="#c.PyErr_ExceptionMatches" title="PyErr_ExceptionMatches"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyErr_ExceptionMatches()</span></code></a> instead, shown below. (The comparison could
easily fail since the exception may be an instance instead of a class, in the
case of a class exception, or it may be a subclass of the expected exception.)</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyErr_ExceptionMatches">
int <code class="descname">PyErr_ExceptionMatches</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *exc</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyErr_ExceptionMatches" title="Permalink to this definition">¶</a></dt>
<dd><p>Equivalent to <code class="docutils literal notranslate"><span class="pre">PyErr_GivenExceptionMatches(PyErr_Occurred(),</span> <span class="pre">exc)</span></code>. This
should only be called when an exception is actually set; a memory access
violation will occur if no exception has been raised.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyErr_GivenExceptionMatches">
int <code class="descname">PyErr_GivenExceptionMatches</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *given</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *exc</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyErr_GivenExceptionMatches" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if the <em>given</em> exception matches the exception in <em>exc</em>. If
<em>exc</em> is a class object, this also returns true when <em>given</em> is an instance
of a subclass. If <em>exc</em> is a tuple, all exceptions in the tuple (and
recursively in subtuples) are searched for a match.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyErr_NormalizeException">
void <code class="descname">PyErr_NormalizeException</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>**exc, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>**val, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>**tb<span class="sig-paren">)</span><a class="headerlink" href="#c.PyErr_NormalizeException" title="Permalink to this definition">¶</a></dt>
<dd><p>Under certain circumstances, the values returned by <a class="reference internal" href="#c.PyErr_Fetch" title="PyErr_Fetch"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyErr_Fetch()</span></code></a> below
can be “unnormalized”, meaning that <code class="docutils literal notranslate"><span class="pre">*exc</span></code> is a class object but <code class="docutils literal notranslate"><span class="pre">*val</span></code> is
not an instance of the same class. This function can be used to instantiate
the class in that case. If the values are already normalized, nothing happens.
The delayed normalization is implemented to improve performance.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyErr_Clear">
void <code class="descname">PyErr_Clear</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyErr_Clear" title="Permalink to this definition">¶</a></dt>
<dd><p>Clear the error indicator. If the error indicator is not set, there is no
effect.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyErr_Fetch">
void <code class="descname">PyErr_Fetch</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> **ptype</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> **pvalue</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> **ptraceback</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyErr_Fetch" title="Permalink to this definition">¶</a></dt>
<dd><p>Retrieve the error indicator into three variables whose addresses are passed.
If the error indicator is not set, set all three variables to <em>NULL</em>. If it is
set, it will be cleared and you own a reference to each object retrieved. The
value and traceback object may be <em>NULL</em> even when the type object is not.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This function is normally only used by code that needs to handle exceptions or
by code that needs to save and restore the error indicator temporarily.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyErr_Restore">
void <code class="descname">PyErr_Restore</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *type</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *value</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *traceback</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyErr_Restore" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the error indicator from the three objects. If the error indicator is
already set, it is cleared first. If the objects are <em>NULL</em>, the error
indicator is cleared. Do not pass a <em>NULL</em> type and non-<em>NULL</em> value or
traceback. The exception type should be a class. Do not pass an invalid
exception type or value. (Violating these rules will cause subtle problems
later.) This call takes away a reference to each object: you must own a
reference to each object before the call and after the call you no longer own
these references. (If you don’t understand this, don’t use this function. I
warned you.)</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This function is normally only used by code that needs to save and restore the
error indicator temporarily; use <a class="reference internal" href="#c.PyErr_Fetch" title="PyErr_Fetch"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyErr_Fetch()</span></code></a> to save the current
exception state.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyErr_SetString">
void <code class="descname">PyErr_SetString</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *type</em>, const char<em> *message</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyErr_SetString" title="Permalink to this definition">¶</a></dt>
<dd><p>This is the most common way to set the error indicator. The first argument
specifies the exception type; it is normally one of the standard exceptions,
e.g. <code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_RuntimeError</span></code>. You need not increment its reference count.
The second argument is an error message; it is converted to a string object.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyErr_SetObject">
void <code class="descname">PyErr_SetObject</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *type</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *value</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyErr_SetObject" title="Permalink to this definition">¶</a></dt>
<dd><p>This function is similar to <a class="reference internal" href="#c.PyErr_SetString" title="PyErr_SetString"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyErr_SetString()</span></code></a> but lets you specify an
arbitrary Python object for the “value” of the exception.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyErr_Format">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyErr_Format</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *exception</em>, const char<em> *format</em>, ...<span class="sig-paren">)</span><a class="headerlink" href="#c.PyErr_Format" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Always NULL.</em><p>This function sets the error indicator and returns <em>NULL</em>. <em>exception</em>
should be a Python exception class. The <em>format</em> and subsequent
parameters help format the error message; they have the same meaning and
values as in <a class="reference internal" href="string.html#c.PyString_FromFormat" title="PyString_FromFormat"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyString_FromFormat()</span></code></a>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyErr_SetNone">
void <code class="descname">PyErr_SetNone</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *type</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyErr_SetNone" title="Permalink to this definition">¶</a></dt>
<dd><p>This is a shorthand for <code class="docutils literal notranslate"><span class="pre">PyErr_SetObject(type,</span> <span class="pre">Py_None)</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyErr_BadArgument">
int <code class="descname">PyErr_BadArgument</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyErr_BadArgument" title="Permalink to this definition">¶</a></dt>
<dd><p>This is a shorthand for <code class="docutils literal notranslate"><span class="pre">PyErr_SetString(PyExc_TypeError,</span> <span class="pre">message)</span></code>, where
<em>message</em> indicates that a built-in operation was invoked with an illegal
argument. It is mostly for internal use.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyErr_NoMemory">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyErr_NoMemory</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyErr_NoMemory" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Always NULL.</em><p>This is a shorthand for <code class="docutils literal notranslate"><span class="pre">PyErr_SetNone(PyExc_MemoryError)</span></code>; it returns <em>NULL</em>
so an object allocation function can write <code class="docutils literal notranslate"><span class="pre">return</span> <span class="pre">PyErr_NoMemory();</span></code> when it
runs out of memory.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyErr_SetFromErrno">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyErr_SetFromErrno</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *type</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyErr_SetFromErrno" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Always NULL.</em><p id="index-1">This is a convenience function to raise an exception when a C library function
has returned an error and set the C variable <code class="xref c c-data docutils literal notranslate"><span class="pre">errno</span></code>. It constructs a
tuple object whose first item is the integer <code class="xref c c-data docutils literal notranslate"><span class="pre">errno</span></code> value and whose
second item is the corresponding error message (gotten from <code class="xref c c-func docutils literal notranslate"><span class="pre">strerror()</span></code>),
and then calls <code class="docutils literal notranslate"><span class="pre">PyErr_SetObject(type,</span> <span class="pre">object)</span></code>. On Unix, when the
<code class="xref c c-data docutils literal notranslate"><span class="pre">errno</span></code> value is <code class="xref py py-const docutils literal notranslate"><span class="pre">EINTR</span></code>, indicating an interrupted system call,
this calls <a class="reference internal" href="#c.PyErr_CheckSignals" title="PyErr_CheckSignals"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyErr_CheckSignals()</span></code></a>, and if that set the error indicator,
leaves it set to that. The function always returns <em>NULL</em>, so a wrapper
function around a system call can write <code class="docutils literal notranslate"><span class="pre">return</span> <span class="pre">PyErr_SetFromErrno(type);</span></code>
when the system call returns an error.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyErr_SetFromErrnoWithFilenameObject">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyErr_SetFromErrnoWithFilenameObject</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *type</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *filenameObject</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyErr_SetFromErrnoWithFilenameObject" title="Permalink to this definition">¶</a></dt>
<dd><p>Similar to <a class="reference internal" href="#c.PyErr_SetFromErrno" title="PyErr_SetFromErrno"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyErr_SetFromErrno()</span></code></a>, with the additional behavior that if
<em>filenameObject</em> is not <em>NULL</em>, it is passed to the constructor of <em>type</em> as
a third parameter. In the case of exceptions such as <a class="reference internal" href="../library/exceptions.html#exceptions.IOError" title="exceptions.IOError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">IOError</span></code></a> and
<a class="reference internal" href="../library/exceptions.html#exceptions.OSError" title="exceptions.OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a>, this is used to define the <code class="xref py py-attr docutils literal notranslate"><span class="pre">filename</span></code> attribute of the
exception instance.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyErr_SetFromErrnoWithFilename">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyErr_SetFromErrnoWithFilename</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *type</em>, const char<em> *filename</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyErr_SetFromErrnoWithFilename" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Always NULL.</em><p>Similar to <a class="reference internal" href="#c.PyErr_SetFromErrnoWithFilenameObject" title="PyErr_SetFromErrnoWithFilenameObject"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyErr_SetFromErrnoWithFilenameObject()</span></code></a>, but the filename
is given as a C string.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyErr_SetFromWindowsErr">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyErr_SetFromWindowsErr</code><span class="sig-paren">(</span>int<em> ierr</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyErr_SetFromWindowsErr" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Always NULL.</em><p>This is a convenience function to raise <a class="reference internal" href="../library/exceptions.html#exceptions.WindowsError" title="exceptions.WindowsError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">WindowsError</span></code></a>. If called with
<em>ierr</em> of <code class="xref c c-data docutils literal notranslate"><span class="pre">0</span></code>, the error code returned by a call to <code class="xref c c-func docutils literal notranslate"><span class="pre">GetLastError()</span></code>
is used instead. It calls the Win32 function <code class="xref c c-func docutils literal notranslate"><span class="pre">FormatMessage()</span></code> to retrieve
the Windows description of error code given by <em>ierr</em> or <code class="xref c c-func docutils literal notranslate"><span class="pre">GetLastError()</span></code>,
then it constructs a tuple object whose first item is the <em>ierr</em> value and whose
second item is the corresponding error message (gotten from
<code class="xref c c-func docutils literal notranslate"><span class="pre">FormatMessage()</span></code>), and then calls <code class="docutils literal notranslate"><span class="pre">PyErr_SetObject(PyExc_WindowsError,</span>
<span class="pre">object)</span></code>. This function always returns <em>NULL</em>. Availability: Windows.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyErr_SetExcFromWindowsErr">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyErr_SetExcFromWindowsErr</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *type</em>, int<em> ierr</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyErr_SetExcFromWindowsErr" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Always NULL.</em><p>Similar to <a class="reference internal" href="#c.PyErr_SetFromWindowsErr" title="PyErr_SetFromWindowsErr"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyErr_SetFromWindowsErr()</span></code></a>, with an additional parameter
specifying the exception type to be raised. Availability: Windows.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.3.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyErr_SetFromWindowsErrWithFilenameObject">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyErr_SetFromWindowsErrWithFilenameObject</code><span class="sig-paren">(</span>int<em> ierr</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *filenameObject</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyErr_SetFromWindowsErrWithFilenameObject" title="Permalink to this definition">¶</a></dt>
<dd><p>Similar to <a class="reference internal" href="#c.PyErr_SetFromWindowsErr" title="PyErr_SetFromWindowsErr"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyErr_SetFromWindowsErr()</span></code></a>, with the additional behavior that
if <em>filenameObject</em> is not <em>NULL</em>, it is passed to the constructor of
<a class="reference internal" href="../library/exceptions.html#exceptions.WindowsError" title="exceptions.WindowsError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">WindowsError</span></code></a> as a third parameter. Availability: Windows.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyErr_SetFromWindowsErrWithFilename">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyErr_SetFromWindowsErrWithFilename</code><span class="sig-paren">(</span>int<em> ierr</em>, const char<em> *filename</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyErr_SetFromWindowsErrWithFilename" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Always NULL.</em><p>Similar to <a class="reference internal" href="#c.PyErr_SetFromWindowsErrWithFilenameObject" title="PyErr_SetFromWindowsErrWithFilenameObject"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyErr_SetFromWindowsErrWithFilenameObject()</span></code></a>, but the
filename is given as a C string. Availability: Windows.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyErr_SetExcFromWindowsErrWithFilenameObject">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyErr_SetExcFromWindowsErrWithFilenameObject</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *type</em>, int<em> ierr</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *filename</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyErr_SetExcFromWindowsErrWithFilenameObject" title="Permalink to this definition">¶</a></dt>
<dd><p>Similar to <a class="reference internal" href="#c.PyErr_SetFromWindowsErrWithFilenameObject" title="PyErr_SetFromWindowsErrWithFilenameObject"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyErr_SetFromWindowsErrWithFilenameObject()</span></code></a>, with an
additional parameter specifying the exception type to be raised.
Availability: Windows.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.3.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyErr_SetExcFromWindowsErrWithFilename">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyErr_SetExcFromWindowsErrWithFilename</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *type</em>, int<em> ierr</em>, const char<em> *filename</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyErr_SetExcFromWindowsErrWithFilename" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Always NULL.</em><p>Similar to <a class="reference internal" href="#c.PyErr_SetFromWindowsErrWithFilename" title="PyErr_SetFromWindowsErrWithFilename"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyErr_SetFromWindowsErrWithFilename()</span></code></a>, with an additional
parameter specifying the exception type to be raised. Availability: Windows.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.3.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyErr_BadInternalCall">
void <code class="descname">PyErr_BadInternalCall</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyErr_BadInternalCall" title="Permalink to this definition">¶</a></dt>
<dd><p>This is a shorthand for <code class="docutils literal notranslate"><span class="pre">PyErr_SetString(PyExc_SystemError,</span> <span class="pre">message)</span></code>,
where <em>message</em> indicates that an internal operation (e.g. a Python/C API
function) was invoked with an illegal argument. It is mostly for internal
use.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyErr_WarnEx">
int <code class="descname">PyErr_WarnEx</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *category</em>, char<em> *message</em>, int<em> stacklevel</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyErr_WarnEx" title="Permalink to this definition">¶</a></dt>
<dd><p>Issue a warning message. The <em>category</em> argument is a warning category (see
below) or <em>NULL</em>; the <em>message</em> argument is a message string. <em>stacklevel</em> is a
positive number giving a number of stack frames; the warning will be issued from
the currently executing line of code in that stack frame. A <em>stacklevel</em> of 1
is the function calling <a class="reference internal" href="#c.PyErr_WarnEx" title="PyErr_WarnEx"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyErr_WarnEx()</span></code></a>, 2 is the function above that,
and so forth.</p>
<p>This function normally prints a warning message to <em>sys.stderr</em>; however, it is
also possible that the user has specified that warnings are to be turned into
errors, and in that case this will raise an exception. It is also possible that
the function raises an exception because of a problem with the warning machinery
(the implementation imports the <a class="reference internal" href="../library/warnings.html#module-warnings" title="warnings: Issue warning messages and control their disposition."><code class="xref py py-mod docutils literal notranslate"><span class="pre">warnings</span></code></a> module to do the heavy lifting).
The return value is <code class="docutils literal notranslate"><span class="pre">0</span></code> if no exception is raised, or <code class="docutils literal notranslate"><span class="pre">-1</span></code> if an exception
is raised. (It is not possible to determine whether a warning message is
actually printed, nor what the reason is for the exception; this is
intentional.) If an exception is raised, the caller should do its normal
exception handling (for example, <a class="reference internal" href="refcounting.html#c.Py_DECREF" title="Py_DECREF"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_DECREF()</span></code></a> owned references and return
an error value).</p>
<p>Warning categories must be subclasses of <code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_Warning</span></code>;
<code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_Warning</span></code> is a subclass of <code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_Exception</span></code>;
the default warning category is <code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_RuntimeWarning</span></code>. The standard
Python warning categories are available as global variables whose names are
enumerated at <a class="reference internal" href="#standardwarningcategories"><span class="std std-ref">Standard Warning Categories</span></a>.</p>
<p>For information about warning control, see the documentation for the
<a class="reference internal" href="../library/warnings.html#module-warnings" title="warnings: Issue warning messages and control their disposition."><code class="xref py py-mod docutils literal notranslate"><span class="pre">warnings</span></code></a> module and the <a class="reference internal" href="../using/cmdline.html#cmdoption-w"><code class="xref std std-option docutils literal notranslate"><span class="pre">-W</span></code></a> option in the command line
documentation. There is no C API for warning control.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyErr_Warn">
int <code class="descname">PyErr_Warn</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *category</em>, char<em> *message</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyErr_Warn" title="Permalink to this definition">¶</a></dt>
<dd><p>Issue a warning message. The <em>category</em> argument is a warning category (see
below) or <em>NULL</em>; the <em>message</em> argument is a message string. The warning will
appear to be issued from the function calling <a class="reference internal" href="#c.PyErr_Warn" title="PyErr_Warn"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyErr_Warn()</span></code></a>, equivalent to
calling <a class="reference internal" href="#c.PyErr_WarnEx" title="PyErr_WarnEx"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyErr_WarnEx()</span></code></a> with a <em>stacklevel</em> of 1.</p>
<p>Deprecated; use <a class="reference internal" href="#c.PyErr_WarnEx" title="PyErr_WarnEx"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyErr_WarnEx()</span></code></a> instead.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyErr_WarnExplicit">
int <code class="descname">PyErr_WarnExplicit</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *category</em>, const char<em> *message</em>, const char<em> *filename</em>, int<em> lineno</em>, const char<em> *module</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *registry</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyErr_WarnExplicit" title="Permalink to this definition">¶</a></dt>
<dd><p>Issue a warning message with explicit control over all warning attributes. This
is a straightforward wrapper around the Python function
<a class="reference internal" href="../library/warnings.html#warnings.warn_explicit" title="warnings.warn_explicit"><code class="xref py py-func docutils literal notranslate"><span class="pre">warnings.warn_explicit()</span></code></a>, see there for more information. The <em>module</em>
and <em>registry</em> arguments may be set to <em>NULL</em> to get the default effect
described there.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyErr_WarnPy3k">
int <code class="descname">PyErr_WarnPy3k</code><span class="sig-paren">(</span>char<em> *message</em>, int<em> stacklevel</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyErr_WarnPy3k" title="Permalink to this definition">¶</a></dt>
<dd><p>Issue a <a class="reference internal" href="../library/exceptions.html#exceptions.DeprecationWarning" title="exceptions.DeprecationWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">DeprecationWarning</span></code></a> with the given <em>message</em> and <em>stacklevel</em>
if the <code class="xref c c-data docutils literal notranslate"><span class="pre">Py_Py3kWarningFlag</span></code> flag is enabled.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyErr_CheckSignals">
int <code class="descname">PyErr_CheckSignals</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyErr_CheckSignals" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-2">This function interacts with Python’s signal handling. It checks whether a
signal has been sent to the processes and if so, invokes the corresponding
signal handler. If the <a class="reference internal" href="../library/signal.html#module-signal" title="signal: Set handlers for asynchronous events."><code class="xref py py-mod docutils literal notranslate"><span class="pre">signal</span></code></a> module is supported, this can invoke a
signal handler written in Python. In all cases, the default effect for
<code class="xref py py-const docutils literal notranslate"><span class="pre">SIGINT</span></code> is to raise the <a class="reference internal" href="../library/exceptions.html#exceptions.KeyboardInterrupt" title="exceptions.KeyboardInterrupt"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyboardInterrupt</span></code></a> exception. If an
exception is raised the error indicator is set and the function returns <code class="docutils literal notranslate"><span class="pre">-1</span></code>;
otherwise the function returns <code class="docutils literal notranslate"><span class="pre">0</span></code>. The error indicator may or may not be
cleared if it was previously set.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyErr_SetInterrupt">
void <code class="descname">PyErr_SetInterrupt</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyErr_SetInterrupt" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-3">This function simulates the effect of a <code class="xref py py-const docutils literal notranslate"><span class="pre">SIGINT</span></code> signal arriving — the
next time <a class="reference internal" href="#c.PyErr_CheckSignals" title="PyErr_CheckSignals"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyErr_CheckSignals()</span></code></a> is called, <a class="reference internal" href="../library/exceptions.html#exceptions.KeyboardInterrupt" title="exceptions.KeyboardInterrupt"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyboardInterrupt</span></code></a> will
be raised. It may be called without holding the interpreter lock.</p>
</dd></dl>
<dl class="function">
<dt id="c.PySignal_SetWakeupFd">
int <code class="descname">PySignal_SetWakeupFd</code><span class="sig-paren">(</span>int<em> fd</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PySignal_SetWakeupFd" title="Permalink to this definition">¶</a></dt>
<dd><p>This utility function specifies a file descriptor to which a <code class="docutils literal notranslate"><span class="pre">'\0'</span></code> byte will
be written whenever a signal is received. It returns the previous such file
descriptor. The value <code class="docutils literal notranslate"><span class="pre">-1</span></code> disables the feature; this is the initial state.
This is equivalent to <a class="reference internal" href="../library/signal.html#signal.set_wakeup_fd" title="signal.set_wakeup_fd"><code class="xref py py-func docutils literal notranslate"><span class="pre">signal.set_wakeup_fd()</span></code></a> in Python, but without any
error checking. <em>fd</em> should be a valid file descriptor. The function should
only be called from the main thread.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyErr_NewException">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyErr_NewException</code><span class="sig-paren">(</span>char<em> *name</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *base</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *dict</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyErr_NewException" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>This utility function creates and returns a new exception class. The <em>name</em>
argument must be the name of the new exception, a C string of the form
<code class="docutils literal notranslate"><span class="pre">module.classname</span></code>. The <em>base</em> and <em>dict</em> arguments are normally <em>NULL</em>.
This creates a class object derived from <a class="reference internal" href="../library/exceptions.html#exceptions.Exception" title="exceptions.Exception"><code class="xref py py-exc docutils literal notranslate"><span class="pre">Exception</span></code></a> (accessible in C as
<code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_Exception</span></code>).</p>
<p>The <code class="xref py py-attr docutils literal notranslate"><span class="pre">__module__</span></code> attribute of the new class is set to the first part (up
to the last dot) of the <em>name</em> argument, and the class name is set to the last
part (after the last dot). The <em>base</em> argument can be used to specify alternate
base classes; it can either be only one class or a tuple of classes. The <em>dict</em>
argument can be used to specify a dictionary of class variables and methods.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyErr_NewExceptionWithDoc">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyErr_NewExceptionWithDoc</code><span class="sig-paren">(</span>char<em> *name</em>, char<em> *doc</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *base</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *dict</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyErr_NewExceptionWithDoc" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Same as <a class="reference internal" href="#c.PyErr_NewException" title="PyErr_NewException"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyErr_NewException()</span></code></a>, except that the new exception class can
easily be given a docstring: If <em>doc</em> is non-<em>NULL</em>, it will be used as the
docstring for the exception class.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.7.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyErr_WriteUnraisable">
void <code class="descname">PyErr_WriteUnraisable</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *obj</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyErr_WriteUnraisable" title="Permalink to this definition">¶</a></dt>
<dd><p>This utility function prints a warning message to <code class="docutils literal notranslate"><span class="pre">sys.stderr</span></code> when an
exception has been set but it is impossible for the interpreter to actually
raise the exception. It is used, for example, when an exception occurs in an
<a class="reference internal" href="../reference/datamodel.html#object.__del__" title="object.__del__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__del__()</span></code></a> method.</p>
<p>The function is called with a single argument <em>obj</em> that identifies the context
in which the unraisable exception occurred. If possible,
the repr of <em>obj</em> will be printed in the warning message.</p>
</dd></dl>
<div class="section" id="unicode-exception-objects">
<span id="unicodeexceptions"></span><h2>Unicode Exception Objects<a class="headerlink" href="#unicode-exception-objects" title="Permalink to this headline">¶</a></h2>
<p>The following functions are used to create and modify Unicode exceptions from C.</p>
<dl class="function">
<dt id="c.PyUnicodeDecodeError_Create">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicodeDecodeError_Create</code><span class="sig-paren">(</span>const char<em> *encoding</em>, const char<em> *object</em>, Py_ssize_t<em> length</em>, Py_ssize_t<em> start</em>, Py_ssize_t<em> end</em>, const char<em> *reason</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicodeDecodeError_Create" title="Permalink to this definition">¶</a></dt>
<dd><p>Create a <code class="xref py py-class docutils literal notranslate"><span class="pre">UnicodeDecodeError</span></code> object with the attributes <em>encoding</em>,
<em>object</em>, <em>length</em>, <em>start</em>, <em>end</em> and <em>reason</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicodeEncodeError_Create">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicodeEncodeError_Create</code><span class="sig-paren">(</span>const char<em> *encoding</em>, const <a class="reference internal" href="unicode.html#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a><em> *object</em>, Py_ssize_t<em> length</em>, Py_ssize_t<em> start</em>, Py_ssize_t<em> end</em>, const char<em> *reason</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicodeEncodeError_Create" title="Permalink to this definition">¶</a></dt>
<dd><p>Create a <code class="xref py py-class docutils literal notranslate"><span class="pre">UnicodeEncodeError</span></code> object with the attributes <em>encoding</em>,
<em>object</em>, <em>length</em>, <em>start</em>, <em>end</em> and <em>reason</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicodeTranslateError_Create">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicodeTranslateError_Create</code><span class="sig-paren">(</span>const <a class="reference internal" href="unicode.html#c.Py_UNICODE" title="Py_UNICODE">Py_UNICODE</a><em> *object</em>, Py_ssize_t<em> length</em>, Py_ssize_t<em> start</em>, Py_ssize_t<em> end</em>, const char<em> *reason</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicodeTranslateError_Create" title="Permalink to this definition">¶</a></dt>
<dd><p>Create a <code class="xref py py-class docutils literal notranslate"><span class="pre">UnicodeTranslateError</span></code> object with the attributes <em>object</em>,
<em>length</em>, <em>start</em>, <em>end</em> and <em>reason</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicodeDecodeError_GetEncoding">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicodeDecodeError_GetEncoding</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *exc</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicodeDecodeError_GetEncoding" title="Permalink to this definition">¶</a></dt>
<dt id="c.PyUnicodeEncodeError_GetEncoding">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicodeEncodeError_GetEncoding</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *exc</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicodeEncodeError_GetEncoding" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the <em>encoding</em> attribute of the given exception object.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicodeDecodeError_GetObject">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicodeDecodeError_GetObject</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *exc</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicodeDecodeError_GetObject" title="Permalink to this definition">¶</a></dt>
<dt id="c.PyUnicodeEncodeError_GetObject">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicodeEncodeError_GetObject</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *exc</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicodeEncodeError_GetObject" title="Permalink to this definition">¶</a></dt>
<dt id="c.PyUnicodeTranslateError_GetObject">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicodeTranslateError_GetObject</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *exc</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicodeTranslateError_GetObject" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the <em>object</em> attribute of the given exception object.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicodeDecodeError_GetStart">
int <code class="descname">PyUnicodeDecodeError_GetStart</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *exc</em>, Py_ssize_t<em> *start</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicodeDecodeError_GetStart" title="Permalink to this definition">¶</a></dt>
<dt id="c.PyUnicodeEncodeError_GetStart">
int <code class="descname">PyUnicodeEncodeError_GetStart</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *exc</em>, Py_ssize_t<em> *start</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicodeEncodeError_GetStart" title="Permalink to this definition">¶</a></dt>
<dt id="c.PyUnicodeTranslateError_GetStart">
int <code class="descname">PyUnicodeTranslateError_GetStart</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *exc</em>, Py_ssize_t<em> *start</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicodeTranslateError_GetStart" title="Permalink to this definition">¶</a></dt>
<dd><p>Get the <em>start</em> attribute of the given exception object and place it into
<em>*start</em>. <em>start</em> must not be <em>NULL</em>. Return <code class="docutils literal notranslate"><span class="pre">0</span></code> on success, <code class="docutils literal notranslate"><span class="pre">-1</span></code> on
failure.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicodeDecodeError_SetStart">
int <code class="descname">PyUnicodeDecodeError_SetStart</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *exc</em>, Py_ssize_t<em> start</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicodeDecodeError_SetStart" title="Permalink to this definition">¶</a></dt>
<dt id="c.PyUnicodeEncodeError_SetStart">
int <code class="descname">PyUnicodeEncodeError_SetStart</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *exc</em>, Py_ssize_t<em> start</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicodeEncodeError_SetStart" title="Permalink to this definition">¶</a></dt>
<dt id="c.PyUnicodeTranslateError_SetStart">
int <code class="descname">PyUnicodeTranslateError_SetStart</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *exc</em>, Py_ssize_t<em> start</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicodeTranslateError_SetStart" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the <em>start</em> attribute of the given exception object to <em>start</em>. Return
<code class="docutils literal notranslate"><span class="pre">0</span></code> on success, <code class="docutils literal notranslate"><span class="pre">-1</span></code> on failure.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicodeDecodeError_GetEnd">
int <code class="descname">PyUnicodeDecodeError_GetEnd</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *exc</em>, Py_ssize_t<em> *end</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicodeDecodeError_GetEnd" title="Permalink to this definition">¶</a></dt>
<dt id="c.PyUnicodeEncodeError_GetEnd">
int <code class="descname">PyUnicodeEncodeError_GetEnd</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *exc</em>, Py_ssize_t<em> *end</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicodeEncodeError_GetEnd" title="Permalink to this definition">¶</a></dt>
<dt id="c.PyUnicodeTranslateError_GetEnd">
int <code class="descname">PyUnicodeTranslateError_GetEnd</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *exc</em>, Py_ssize_t<em> *end</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicodeTranslateError_GetEnd" title="Permalink to this definition">¶</a></dt>
<dd><p>Get the <em>end</em> attribute of the given exception object and place it into
<em>*end</em>. <em>end</em> must not be <em>NULL</em>. Return <code class="docutils literal notranslate"><span class="pre">0</span></code> on success, <code class="docutils literal notranslate"><span class="pre">-1</span></code> on
failure.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicodeDecodeError_SetEnd">
int <code class="descname">PyUnicodeDecodeError_SetEnd</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *exc</em>, Py_ssize_t<em> end</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicodeDecodeError_SetEnd" title="Permalink to this definition">¶</a></dt>
<dt id="c.PyUnicodeEncodeError_SetEnd">
int <code class="descname">PyUnicodeEncodeError_SetEnd</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *exc</em>, Py_ssize_t<em> end</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicodeEncodeError_SetEnd" title="Permalink to this definition">¶</a></dt>
<dt id="c.PyUnicodeTranslateError_SetEnd">
int <code class="descname">PyUnicodeTranslateError_SetEnd</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *exc</em>, Py_ssize_t<em> end</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicodeTranslateError_SetEnd" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the <em>end</em> attribute of the given exception object to <em>end</em>. Return <code class="docutils literal notranslate"><span class="pre">0</span></code>
on success, <code class="docutils literal notranslate"><span class="pre">-1</span></code> on failure.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicodeDecodeError_GetReason">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicodeDecodeError_GetReason</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *exc</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicodeDecodeError_GetReason" title="Permalink to this definition">¶</a></dt>
<dt id="c.PyUnicodeEncodeError_GetReason">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicodeEncodeError_GetReason</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *exc</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicodeEncodeError_GetReason" title="Permalink to this definition">¶</a></dt>
<dt id="c.PyUnicodeTranslateError_GetReason">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyUnicodeTranslateError_GetReason</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *exc</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicodeTranslateError_GetReason" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the <em>reason</em> attribute of the given exception object.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyUnicodeDecodeError_SetReason">
int <code class="descname">PyUnicodeDecodeError_SetReason</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *exc</em>, const char<em> *reason</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicodeDecodeError_SetReason" title="Permalink to this definition">¶</a></dt>
<dt id="c.PyUnicodeEncodeError_SetReason">
int <code class="descname">PyUnicodeEncodeError_SetReason</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *exc</em>, const char<em> *reason</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicodeEncodeError_SetReason" title="Permalink to this definition">¶</a></dt>
<dt id="c.PyUnicodeTranslateError_SetReason">
int <code class="descname">PyUnicodeTranslateError_SetReason</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *exc</em>, const char<em> *reason</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyUnicodeTranslateError_SetReason" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the <em>reason</em> attribute of the given exception object to <em>reason</em>. Return
<code class="docutils literal notranslate"><span class="pre">0</span></code> on success, <code class="docutils literal notranslate"><span class="pre">-1</span></code> on failure.</p>
</dd></dl>
</div>
<div class="section" id="recursion-control">
<h2>Recursion Control<a class="headerlink" href="#recursion-control" title="Permalink to this headline">¶</a></h2>
<p>These two functions provide a way to perform safe recursive calls at the C
level, both in the core and in extension modules. They are needed if the
recursive code does not necessarily invoke Python code (which tracks its
recursion depth automatically).</p>
<dl class="function">
<dt id="c.Py_EnterRecursiveCall">
int <code class="descname">Py_EnterRecursiveCall</code><span class="sig-paren">(</span>const char<em> *where</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_EnterRecursiveCall" title="Permalink to this definition">¶</a></dt>
<dd><p>Marks a point where a recursive C-level call is about to be performed.</p>
<p>If <code class="xref py py-const docutils literal notranslate"><span class="pre">USE_STACKCHECK</span></code> is defined, this function checks if the OS
stack overflowed using <a class="reference internal" href="sys.html#c.PyOS_CheckStack" title="PyOS_CheckStack"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyOS_CheckStack()</span></code></a>. In this is the case, it
sets a <a class="reference internal" href="../library/exceptions.html#exceptions.MemoryError" title="exceptions.MemoryError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">MemoryError</span></code></a> and returns a nonzero value.</p>
<p>The function then checks if the recursion limit is reached. If this is the
case, a <a class="reference internal" href="../library/exceptions.html#exceptions.RuntimeError" title="exceptions.RuntimeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">RuntimeError</span></code></a> is set and a nonzero value is returned.
Otherwise, zero is returned.</p>
<p><em>where</em> should be a string such as <code class="docutils literal notranslate"><span class="pre">"</span> <span class="pre">in</span> <span class="pre">instance</span> <span class="pre">check"</span></code> to be
concatenated to the <a class="reference internal" href="../library/exceptions.html#exceptions.RuntimeError" title="exceptions.RuntimeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">RuntimeError</span></code></a> message caused by the recursion depth
limit.</p>
</dd></dl>
<dl class="function">
<dt id="c.Py_LeaveRecursiveCall">
void <code class="descname">Py_LeaveRecursiveCall</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_LeaveRecursiveCall" title="Permalink to this definition">¶</a></dt>
<dd><p>Ends a <a class="reference internal" href="#c.Py_EnterRecursiveCall" title="Py_EnterRecursiveCall"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_EnterRecursiveCall()</span></code></a>. Must be called once for each
<em>successful</em> invocation of <a class="reference internal" href="#c.Py_EnterRecursiveCall" title="Py_EnterRecursiveCall"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_EnterRecursiveCall()</span></code></a>.</p>
</dd></dl>
</div>
<div class="section" id="standard-exceptions">
<span id="standardexceptions"></span><h2>Standard Exceptions<a class="headerlink" href="#standard-exceptions" title="Permalink to this headline">¶</a></h2>
<p>All standard Python exceptions are available as global variables whose names are
<code class="docutils literal notranslate"><span class="pre">PyExc_</span></code> followed by the Python exception name. These have the type
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject*</span></code></a>; they are all class objects. For completeness, here are all
the variables:</p>
<table border="1" class="docutils" id="index-4">
<colgroup>
<col width="49%" />
<col width="39%" />
<col width="12%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">C Name</th>
<th class="head">Python Name</th>
<th class="head">Notes</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_BaseException</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.BaseException" title="exceptions.BaseException"><code class="xref py py-exc docutils literal notranslate"><span class="pre">BaseException</span></code></a></td>
<td>(1), (4)</td>
</tr>
<tr class="row-odd"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_Exception</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.Exception" title="exceptions.Exception"><code class="xref py py-exc docutils literal notranslate"><span class="pre">Exception</span></code></a></td>
<td>(1)</td>
</tr>
<tr class="row-even"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_StandardError</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.StandardError" title="exceptions.StandardError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">StandardError</span></code></a></td>
<td>(1)</td>
</tr>
<tr class="row-odd"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_ArithmeticError</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.ArithmeticError" title="exceptions.ArithmeticError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ArithmeticError</span></code></a></td>
<td>(1)</td>
</tr>
<tr class="row-even"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_AssertionError</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.AssertionError" title="exceptions.AssertionError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">AssertionError</span></code></a></td>
<td> </td>
</tr>
<tr class="row-odd"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_AttributeError</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.AttributeError" title="exceptions.AttributeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">AttributeError</span></code></a></td>
<td> </td>
</tr>
<tr class="row-even"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_BufferError</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.BufferError" title="exceptions.BufferError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">BufferError</span></code></a></td>
<td> </td>
</tr>
<tr class="row-odd"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_EnvironmentError</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.EnvironmentError" title="exceptions.EnvironmentError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">EnvironmentError</span></code></a></td>
<td>(1)</td>
</tr>
<tr class="row-even"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_EOFError</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.EOFError" title="exceptions.EOFError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">EOFError</span></code></a></td>
<td> </td>
</tr>
<tr class="row-odd"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_FloatingPointError</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.FloatingPointError" title="exceptions.FloatingPointError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">FloatingPointError</span></code></a></td>
<td> </td>
</tr>
<tr class="row-even"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_GeneratorExit</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.GeneratorExit" title="exceptions.GeneratorExit"><code class="xref py py-exc docutils literal notranslate"><span class="pre">GeneratorExit</span></code></a></td>
<td> </td>
</tr>
<tr class="row-odd"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_ImportError</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.ImportError" title="exceptions.ImportError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ImportError</span></code></a></td>
<td> </td>
</tr>
<tr class="row-even"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_IndentationError</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.IndentationError" title="exceptions.IndentationError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">IndentationError</span></code></a></td>
<td> </td>
</tr>
<tr class="row-odd"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_IndexError</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.IndexError" title="exceptions.IndexError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">IndexError</span></code></a></td>
<td> </td>
</tr>
<tr class="row-even"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_IOError</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.IOError" title="exceptions.IOError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">IOError</span></code></a></td>
<td> </td>
</tr>
<tr class="row-odd"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_KeyError</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.KeyError" title="exceptions.KeyError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyError</span></code></a></td>
<td> </td>
</tr>
<tr class="row-even"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_KeyboardInterrupt</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.KeyboardInterrupt" title="exceptions.KeyboardInterrupt"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyboardInterrupt</span></code></a></td>
<td> </td>
</tr>
<tr class="row-odd"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_LookupError</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.LookupError" title="exceptions.LookupError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">LookupError</span></code></a></td>
<td>(1)</td>
</tr>
<tr class="row-even"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_MemoryError</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.MemoryError" title="exceptions.MemoryError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">MemoryError</span></code></a></td>
<td> </td>
</tr>
<tr class="row-odd"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_NameError</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.NameError" title="exceptions.NameError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">NameError</span></code></a></td>
<td> </td>
</tr>
<tr class="row-even"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_NotImplementedError</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.NotImplementedError" title="exceptions.NotImplementedError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">NotImplementedError</span></code></a></td>
<td> </td>
</tr>
<tr class="row-odd"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_OSError</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.OSError" title="exceptions.OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a></td>
<td> </td>
</tr>
<tr class="row-even"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_OverflowError</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.OverflowError" title="exceptions.OverflowError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OverflowError</span></code></a></td>
<td> </td>
</tr>
<tr class="row-odd"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_ReferenceError</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.ReferenceError" title="exceptions.ReferenceError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ReferenceError</span></code></a></td>
<td>(2)</td>
</tr>
<tr class="row-even"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_RuntimeError</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.RuntimeError" title="exceptions.RuntimeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">RuntimeError</span></code></a></td>
<td> </td>
</tr>
<tr class="row-odd"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_StopIteration</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.StopIteration" title="exceptions.StopIteration"><code class="xref py py-exc docutils literal notranslate"><span class="pre">StopIteration</span></code></a></td>
<td> </td>
</tr>
<tr class="row-even"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_SyntaxError</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.SyntaxError" title="exceptions.SyntaxError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SyntaxError</span></code></a></td>
<td> </td>
</tr>
<tr class="row-odd"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_SystemError</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.SystemError" title="exceptions.SystemError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SystemError</span></code></a></td>
<td> </td>
</tr>
<tr class="row-even"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_SystemExit</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.SystemExit" title="exceptions.SystemExit"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SystemExit</span></code></a></td>
<td> </td>
</tr>
<tr class="row-odd"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_TabError</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.TabError" title="exceptions.TabError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TabError</span></code></a></td>
<td> </td>
</tr>
<tr class="row-even"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_TypeError</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a></td>
<td> </td>
</tr>
<tr class="row-odd"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_UnboundLocalError</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.UnboundLocalError" title="exceptions.UnboundLocalError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">UnboundLocalError</span></code></a></td>
<td> </td>
</tr>
<tr class="row-even"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_UnicodeDecodeError</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.UnicodeDecodeError" title="exceptions.UnicodeDecodeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">UnicodeDecodeError</span></code></a></td>
<td> </td>
</tr>
<tr class="row-odd"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_UnicodeEncodeError</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.UnicodeEncodeError" title="exceptions.UnicodeEncodeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">UnicodeEncodeError</span></code></a></td>
<td> </td>
</tr>
<tr class="row-even"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_UnicodeError</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.UnicodeError" title="exceptions.UnicodeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">UnicodeError</span></code></a></td>
<td> </td>
</tr>
<tr class="row-odd"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_UnicodeTranslateError</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.UnicodeTranslateError" title="exceptions.UnicodeTranslateError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">UnicodeTranslateError</span></code></a></td>
<td> </td>
</tr>
<tr class="row-even"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_VMSError</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.VMSError" title="exceptions.VMSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">VMSError</span></code></a></td>
<td>(5)</td>
</tr>
<tr class="row-odd"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_ValueError</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.ValueError" title="exceptions.ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a></td>
<td> </td>
</tr>
<tr class="row-even"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_WindowsError</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.WindowsError" title="exceptions.WindowsError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">WindowsError</span></code></a></td>
<td>(3)</td>
</tr>
<tr class="row-odd"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_ZeroDivisionError</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.ZeroDivisionError" title="exceptions.ZeroDivisionError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ZeroDivisionError</span></code></a></td>
<td> </td>
</tr>
</tbody>
</table>
<p>Notes:</p>
<ol class="arabic">
<li><p class="first">This is a base class for other standard exceptions.</p>
</li>
<li><p class="first">This is the same as <a class="reference internal" href="../library/weakref.html#weakref.ReferenceError" title="weakref.ReferenceError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">weakref.ReferenceError</span></code></a>.</p>
</li>
<li><p class="first">Only defined on Windows; protect code that uses this by testing that the
preprocessor macro <code class="docutils literal notranslate"><span class="pre">MS_WINDOWS</span></code> is defined.</p>
</li>
<li><div class="first versionadded">
<p><span class="versionmodified">New in version 2.5.</span></p>
</div>
</li>
<li><p class="first">Only defined on VMS; protect code that uses this by testing that the
preprocessor macro <code class="docutils literal notranslate"><span class="pre">__VMS</span></code> is defined.</p>
</li>
</ol>
</div>
<div class="section" id="standard-warning-categories">
<span id="standardwarningcategories"></span><h2>Standard Warning Categories<a class="headerlink" href="#standard-warning-categories" title="Permalink to this headline">¶</a></h2>
<p>All standard Python warning categories are available as global variables whose
names are <code class="docutils literal notranslate"><span class="pre">PyExc_</span></code> followed by the Python exception name. These have the type
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject*</span></code></a>; they are all class objects. For completeness, here are all
the variables:</p>
<table border="1" class="docutils" id="index-5">
<colgroup>
<col width="49%" />
<col width="39%" />
<col width="12%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">C Name</th>
<th class="head">Python Name</th>
<th class="head">Notes</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_Warning</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.Warning" title="exceptions.Warning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">Warning</span></code></a></td>
<td>(1)</td>
</tr>
<tr class="row-odd"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_BytesWarning</span></code></td>
<td><code class="xref py py-exc docutils literal notranslate"><span class="pre">BytesWarning</span></code></td>
<td> </td>
</tr>
<tr class="row-even"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_DeprecationWarning</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.DeprecationWarning" title="exceptions.DeprecationWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">DeprecationWarning</span></code></a></td>
<td> </td>
</tr>
<tr class="row-odd"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_FutureWarning</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.FutureWarning" title="exceptions.FutureWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">FutureWarning</span></code></a></td>
<td> </td>
</tr>
<tr class="row-even"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_ImportWarning</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.ImportWarning" title="exceptions.ImportWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ImportWarning</span></code></a></td>
<td> </td>
</tr>
<tr class="row-odd"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_PendingDeprecationWarning</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.PendingDeprecationWarning" title="exceptions.PendingDeprecationWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">PendingDeprecationWarning</span></code></a></td>
<td> </td>
</tr>
<tr class="row-even"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_RuntimeWarning</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.RuntimeWarning" title="exceptions.RuntimeWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">RuntimeWarning</span></code></a></td>
<td> </td>
</tr>
<tr class="row-odd"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_SyntaxWarning</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.SyntaxWarning" title="exceptions.SyntaxWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SyntaxWarning</span></code></a></td>
<td> </td>
</tr>
<tr class="row-even"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_UnicodeWarning</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.UnicodeWarning" title="exceptions.UnicodeWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">UnicodeWarning</span></code></a></td>
<td> </td>
</tr>
<tr class="row-odd"><td><code class="xref c c-data docutils literal notranslate"><span class="pre">PyExc_UserWarning</span></code></td>
<td><a class="reference internal" href="../library/exceptions.html#exceptions.UserWarning" title="exceptions.UserWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">UserWarning</span></code></a></td>
<td> </td>
</tr>
</tbody>
</table>
<p>Notes:</p>
<ol class="arabic simple">
<li>This is a base class for other standard warning categories.</li>
</ol>
</div>
<div class="section" id="string-exceptions">
<h2>String Exceptions<a class="headerlink" href="#string-exceptions" title="Permalink to this headline">¶</a></h2>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.6: </span>All exceptions to be raised or caught must be derived from <a class="reference internal" href="../library/exceptions.html#exceptions.BaseException" title="exceptions.BaseException"><code class="xref py py-exc docutils literal notranslate"><span class="pre">BaseException</span></code></a>.
Trying to raise a string exception now raises <a class="reference internal" href="../library/exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a>.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Exception Handling</a><ul>
<li><a class="reference internal" href="#unicode-exception-objects">Unicode Exception Objects</a></li>
<li><a class="reference internal" href="#recursion-control">Recursion Control</a></li>
<li><a class="reference internal" href="#standard-exceptions">Standard Exceptions</a></li>
<li><a class="reference internal" href="#standard-warning-categories">Standard Warning Categories</a></li>
<li><a class="reference internal" href="#string-exceptions">String Exceptions</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="refcounting.html"
title="previous chapter">Reference Counting</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="utilities.html"
title="next chapter">Utilities</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/exceptions.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="utilities.html" title="Utilities"
>next</a> |</li>
<li class="right" >
<a href="refcounting.html" title="Reference Counting"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\'��^ �^ html/c-api/file.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>File Objects — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Module Objects" href="module.html" />
<link rel="prev" title="Method Objects" href="method.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/file.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="module.html" title="Module Objects"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="method.html" title="Method Objects"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" accesskey="U">Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="file-objects">
<span id="fileobjects"></span><h1>File Objects<a class="headerlink" href="#file-objects" title="Permalink to this headline">¶</a></h1>
<p id="index-0">Python’s built-in file objects are implemented entirely on the <code class="xref c c-type docutils literal notranslate"><span class="pre">FILE*</span></code>
support from the C standard library. This is an implementation detail and may
change in future releases of Python.</p>
<dl class="type">
<dt id="c.PyFileObject">
<code class="descname">PyFileObject</code><a class="headerlink" href="#c.PyFileObject" title="Permalink to this definition">¶</a></dt>
<dd><p>This subtype of <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject</span></code></a> represents a Python file object.</p>
</dd></dl>
<dl class="var">
<dt id="c.PyFile_Type">
<a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a> <code class="descname">PyFile_Type</code><a class="headerlink" href="#c.PyFile_Type" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-1">This instance of <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyTypeObject</span></code></a> represents the Python file type. This is
exposed to Python programs as <code class="docutils literal notranslate"><span class="pre">file</span></code> and <code class="docutils literal notranslate"><span class="pre">types.FileType</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyFile_Check">
int <code class="descname">PyFile_Check</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFile_Check" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if its argument is a <a class="reference internal" href="#c.PyFileObject" title="PyFileObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyFileObject</span></code></a> or a subtype of
<a class="reference internal" href="#c.PyFileObject" title="PyFileObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyFileObject</span></code></a>.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.2: </span>Allowed subtypes to be accepted.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyFile_CheckExact">
int <code class="descname">PyFile_CheckExact</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFile_CheckExact" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if its argument is a <a class="reference internal" href="#c.PyFileObject" title="PyFileObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyFileObject</span></code></a>, but not a subtype of
<a class="reference internal" href="#c.PyFileObject" title="PyFileObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyFileObject</span></code></a>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyFile_FromString">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyFile_FromString</code><span class="sig-paren">(</span>char<em> *filename</em>, char<em> *mode</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFile_FromString" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p id="index-2">On success, return a new file object that is opened on the file given by
<em>filename</em>, with a file mode given by <em>mode</em>, where <em>mode</em> has the same
semantics as the standard C routine <code class="xref c c-func docutils literal notranslate"><span class="pre">fopen()</span></code>. On failure, return <em>NULL</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyFile_FromFile">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyFile_FromFile</code><span class="sig-paren">(</span>FILE<em> *fp</em>, char<em> *name</em>, char<em> *mode</em>, int (<em>*close</em>)(FILE*)<span class="sig-paren">)</span><a class="headerlink" href="#c.PyFile_FromFile" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Create a new <a class="reference internal" href="#c.PyFileObject" title="PyFileObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyFileObject</span></code></a> from the already-open standard C file
pointer, <em>fp</em>. The function <em>close</em> will be called when the file should be
closed. Return <em>NULL</em> and close the file using <em>close</em> on failure.
<em>close</em> is optional and can be set to <em>NULL</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyFile_AsFile">
FILE* <code class="descname">PyFile_AsFile</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFile_AsFile" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the file object associated with <em>p</em> as a <code class="xref c c-type docutils literal notranslate"><span class="pre">FILE*</span></code>.</p>
<p>If the caller will ever use the returned <code class="xref c c-type docutils literal notranslate"><span class="pre">FILE*</span></code> object while
the <a class="reference internal" href="../glossary.html#term-gil"><span class="xref std std-term">GIL</span></a> is released it must also call the <a class="reference internal" href="#c.PyFile_IncUseCount" title="PyFile_IncUseCount"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyFile_IncUseCount()</span></code></a> and
<a class="reference internal" href="#c.PyFile_DecUseCount" title="PyFile_DecUseCount"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyFile_DecUseCount()</span></code></a> functions described below as appropriate.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyFile_IncUseCount">
void <code class="descname">PyFile_IncUseCount</code><span class="sig-paren">(</span><a class="reference internal" href="#c.PyFileObject" title="PyFileObject">PyFileObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFile_IncUseCount" title="Permalink to this definition">¶</a></dt>
<dd><p>Increments the PyFileObject’s internal use count to indicate
that the underlying <code class="xref c c-type docutils literal notranslate"><span class="pre">FILE*</span></code> is being used.
This prevents Python from calling f_close() on it from another thread.
Callers of this must call <a class="reference internal" href="#c.PyFile_DecUseCount" title="PyFile_DecUseCount"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyFile_DecUseCount()</span></code></a> when they are
finished with the <code class="xref c c-type docutils literal notranslate"><span class="pre">FILE*</span></code>. Otherwise the file object will
never be closed by Python.</p>
<p>The <a class="reference internal" href="../glossary.html#term-gil"><span class="xref std std-term">GIL</span></a> must be held while calling this function.</p>
<p>The suggested use is to call this after <a class="reference internal" href="#c.PyFile_AsFile" title="PyFile_AsFile"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyFile_AsFile()</span></code></a> and before
you release the GIL:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">FILE</span> <span class="o">*</span><span class="n">fp</span> <span class="o">=</span> <span class="n">PyFile_AsFile</span><span class="p">(</span><span class="n">p</span><span class="p">);</span>
<span class="n">PyFile_IncUseCount</span><span class="p">(</span><span class="n">p</span><span class="p">);</span>
<span class="cm">/* ... */</span>
<span class="n">Py_BEGIN_ALLOW_THREADS</span>
<span class="nf">do_something</span><span class="p">(</span><span class="n">fp</span><span class="p">);</span>
<span class="n">Py_END_ALLOW_THREADS</span>
<span class="cm">/* ... */</span>
<span class="n">PyFile_DecUseCount</span><span class="p">(</span><span class="n">p</span><span class="p">);</span>
</pre></div>
</div>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyFile_DecUseCount">
void <code class="descname">PyFile_DecUseCount</code><span class="sig-paren">(</span><a class="reference internal" href="#c.PyFileObject" title="PyFileObject">PyFileObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFile_DecUseCount" title="Permalink to this definition">¶</a></dt>
<dd><p>Decrements the PyFileObject’s internal unlocked_count member to
indicate that the caller is done with its own use of the <code class="xref c c-type docutils literal notranslate"><span class="pre">FILE*</span></code>.
This may only be called to undo a prior call to <a class="reference internal" href="#c.PyFile_IncUseCount" title="PyFile_IncUseCount"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyFile_IncUseCount()</span></code></a>.</p>
<p>The <a class="reference internal" href="../glossary.html#term-gil"><span class="xref std std-term">GIL</span></a> must be held while calling this function (see the example
above).</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyFile_GetLine">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyFile_GetLine</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em>, int<em> n</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFile_GetLine" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p id="index-3">Equivalent to <code class="docutils literal notranslate"><span class="pre">p.readline([n])</span></code>, this function reads one line from the
object <em>p</em>. <em>p</em> may be a file object or any object with a
<a class="reference internal" href="../library/io.html#io.IOBase.readline" title="io.IOBase.readline"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readline()</span></code></a>
method. If <em>n</em> is <code class="docutils literal notranslate"><span class="pre">0</span></code>, exactly one line is read, regardless of the length of
the line. If <em>n</em> is greater than <code class="docutils literal notranslate"><span class="pre">0</span></code>, no more than <em>n</em> bytes will be read
from the file; a partial line can be returned. In both cases, an empty string
is returned if the end of the file is reached immediately. If <em>n</em> is less than
<code class="docutils literal notranslate"><span class="pre">0</span></code>, however, one line is read regardless of length, but <a class="reference internal" href="../library/exceptions.html#exceptions.EOFError" title="exceptions.EOFError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">EOFError</span></code></a> is
raised if the end of the file is reached immediately.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyFile_Name">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyFile_Name</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFile_Name" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Borrowed reference.</em><p>Return the name of the file specified by <em>p</em> as a string object.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyFile_SetBufSize">
void <code class="descname">PyFile_SetBufSize</code><span class="sig-paren">(</span><a class="reference internal" href="#c.PyFileObject" title="PyFileObject">PyFileObject</a><em> *p</em>, int<em> n</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFile_SetBufSize" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-4">Available on systems with <code class="xref c c-func docutils literal notranslate"><span class="pre">setvbuf()</span></code> only. This should only be called
immediately after file object creation.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyFile_SetEncoding">
int <code class="descname">PyFile_SetEncoding</code><span class="sig-paren">(</span><a class="reference internal" href="#c.PyFileObject" title="PyFileObject">PyFileObject</a><em> *p</em>, const char<em> *enc</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFile_SetEncoding" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the file’s encoding for Unicode output to <em>enc</em>. Return <code class="docutils literal notranslate"><span class="pre">1</span></code> on success and <code class="docutils literal notranslate"><span class="pre">0</span></code>
on failure.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.3.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyFile_SetEncodingAndErrors">
int <code class="descname">PyFile_SetEncodingAndErrors</code><span class="sig-paren">(</span><a class="reference internal" href="#c.PyFileObject" title="PyFileObject">PyFileObject</a><em> *p</em>, const char<em> *enc</em>, *errors<span class="sig-paren">)</span><a class="headerlink" href="#c.PyFile_SetEncodingAndErrors" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the file’s encoding for Unicode output to <em>enc</em>, and its error
mode to <em>err</em>. Return <code class="docutils literal notranslate"><span class="pre">1</span></code> on success and <code class="docutils literal notranslate"><span class="pre">0</span></code> on failure.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyFile_SoftSpace">
int <code class="descname">PyFile_SoftSpace</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em>, int<em> newflag</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFile_SoftSpace" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-5">This function exists for internal use by the interpreter. Set the
<code class="xref py py-attr docutils literal notranslate"><span class="pre">softspace</span></code> attribute of <em>p</em> to <em>newflag</em> and return the previous value.
<em>p</em> does not have to be a file object for this function to work properly; any
object is supported (thought its only interesting if the <code class="xref py py-attr docutils literal notranslate"><span class="pre">softspace</span></code>
attribute can be set). This function clears any errors, and will return <code class="docutils literal notranslate"><span class="pre">0</span></code>
as the previous value if the attribute either does not exist or if there were
errors in retrieving it. There is no way to detect errors from this function,
but doing so should not be needed.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyFile_WriteObject">
int <code class="descname">PyFile_WriteObject</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *obj</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em>, int<em> flags</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFile_WriteObject" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-6">Write object <em>obj</em> to file object <em>p</em>. The only supported flag for <em>flags</em> is
<code class="xref py py-const docutils literal notranslate"><span class="pre">Py_PRINT_RAW</span></code>; if given, the <a class="reference internal" href="../library/functions.html#str" title="str"><code class="xref py py-func docutils literal notranslate"><span class="pre">str()</span></code></a> of the object is written
instead of the <a class="reference internal" href="../library/functions.html#repr" title="repr"><code class="xref py py-func docutils literal notranslate"><span class="pre">repr()</span></code></a>. Return <code class="docutils literal notranslate"><span class="pre">0</span></code> on success or <code class="docutils literal notranslate"><span class="pre">-1</span></code> on failure; the
appropriate exception will be set.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyFile_WriteString">
int <code class="descname">PyFile_WriteString</code><span class="sig-paren">(</span>const char<em> *s</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFile_WriteString" title="Permalink to this definition">¶</a></dt>
<dd><p>Write string <em>s</em> to file object <em>p</em>. Return <code class="docutils literal notranslate"><span class="pre">0</span></code> on success or <code class="docutils literal notranslate"><span class="pre">-1</span></code> on
failure; the appropriate exception will be set.</p>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="method.html"
title="previous chapter">Method Objects</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="module.html"
title="next chapter">Module Objects</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/file.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="module.html" title="Module Objects"
>next</a> |</li>
<li class="right" >
<a href="method.html" title="Method Objects"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" >Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\"�:�vD vD html/c-api/float.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Floating Point Objects — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Complex Number Objects" href="complex.html" />
<link rel="prev" title="Long Integer Objects" href="long.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/float.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="complex.html" title="Complex Number Objects"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="long.html" title="Long Integer Objects"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" accesskey="U">Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="floating-point-objects">
<span id="floatobjects"></span><h1>Floating Point Objects<a class="headerlink" href="#floating-point-objects" title="Permalink to this headline">¶</a></h1>
<span class="target" id="index-0"></span><dl class="type">
<dt id="c.PyFloatObject">
<code class="descname">PyFloatObject</code><a class="headerlink" href="#c.PyFloatObject" title="Permalink to this definition">¶</a></dt>
<dd><p>This subtype of <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject</span></code></a> represents a Python floating point object.</p>
</dd></dl>
<dl class="var">
<dt id="c.PyFloat_Type">
<a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a> <code class="descname">PyFloat_Type</code><a class="headerlink" href="#c.PyFloat_Type" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-1">This instance of <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyTypeObject</span></code></a> represents the Python floating point
type. This is the same object as <code class="docutils literal notranslate"><span class="pre">float</span></code> and <code class="docutils literal notranslate"><span class="pre">types.FloatType</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyFloat_Check">
int <code class="descname">PyFloat_Check</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFloat_Check" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if its argument is a <a class="reference internal" href="#c.PyFloatObject" title="PyFloatObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyFloatObject</span></code></a> or a subtype of
<a class="reference internal" href="#c.PyFloatObject" title="PyFloatObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyFloatObject</span></code></a>.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.2: </span>Allowed subtypes to be accepted.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyFloat_CheckExact">
int <code class="descname">PyFloat_CheckExact</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFloat_CheckExact" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if its argument is a <a class="reference internal" href="#c.PyFloatObject" title="PyFloatObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyFloatObject</span></code></a>, but not a subtype of
<a class="reference internal" href="#c.PyFloatObject" title="PyFloatObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyFloatObject</span></code></a>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.2.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyFloat_FromString">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyFloat_FromString</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *str</em>, char<em> **pend</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFloat_FromString" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Create a <a class="reference internal" href="#c.PyFloatObject" title="PyFloatObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyFloatObject</span></code></a> object based on the string value in <em>str</em>, or
<em>NULL</em> on failure. The <em>pend</em> argument is ignored. It remains only for
backward compatibility.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyFloat_FromDouble">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyFloat_FromDouble</code><span class="sig-paren">(</span>double<em> v</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFloat_FromDouble" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Create a <a class="reference internal" href="#c.PyFloatObject" title="PyFloatObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyFloatObject</span></code></a> object from <em>v</em>, or <em>NULL</em> on failure.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyFloat_AsDouble">
double <code class="descname">PyFloat_AsDouble</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *pyfloat</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFloat_AsDouble" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a C <code class="xref c c-type docutils literal notranslate"><span class="pre">double</span></code> representation of the contents of <em>pyfloat</em>. If
<em>pyfloat</em> is not a Python floating point object but has a <a class="reference internal" href="../reference/datamodel.html#object.__float__" title="object.__float__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__float__()</span></code></a>
method, this method will first be called to convert <em>pyfloat</em> into a float.
This method returns <code class="docutils literal notranslate"><span class="pre">-1.0</span></code> upon failure, so one should call
<a class="reference internal" href="exceptions.html#c.PyErr_Occurred" title="PyErr_Occurred"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyErr_Occurred()</span></code></a> to check for errors.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyFloat_AS_DOUBLE">
double <code class="descname">PyFloat_AS_DOUBLE</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *pyfloat</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFloat_AS_DOUBLE" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a C <code class="xref c c-type docutils literal notranslate"><span class="pre">double</span></code> representation of the contents of <em>pyfloat</em>, but
without error checking.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyFloat_GetInfo">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyFloat_GetInfo</code><span class="sig-paren">(</span>void<span class="sig-paren">)</span><a class="headerlink" href="#c.PyFloat_GetInfo" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a structseq instance which contains information about the
precision, minimum and maximum values of a float. It’s a thin wrapper
around the header file <code class="file docutils literal notranslate"><span class="pre">float.h</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyFloat_GetMax">
double <code class="descname">PyFloat_GetMax</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFloat_GetMax" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the maximum representable finite float <em>DBL_MAX</em> as C <code class="xref c c-type docutils literal notranslate"><span class="pre">double</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyFloat_GetMin">
double <code class="descname">PyFloat_GetMin</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFloat_GetMin" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the minimum normalized positive float <em>DBL_MIN</em> as C <code class="xref c c-type docutils literal notranslate"><span class="pre">double</span></code>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyFloat_ClearFreeList">
int <code class="descname">PyFloat_ClearFreeList</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFloat_ClearFreeList" title="Permalink to this definition">¶</a></dt>
<dd><p>Clear the float free list. Return the number of items that could not
be freed.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.6.</span></p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyFloat_AsString">
void <code class="descname">PyFloat_AsString</code><span class="sig-paren">(</span>char<em> *buf</em>, <a class="reference internal" href="#c.PyFloatObject" title="PyFloatObject">PyFloatObject</a><em> *v</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFloat_AsString" title="Permalink to this definition">¶</a></dt>
<dd><p>Convert the argument <em>v</em> to a string, using the same rules as
<a class="reference internal" href="../library/functions.html#str" title="str"><code class="xref py py-func docutils literal notranslate"><span class="pre">str()</span></code></a>. The length of <em>buf</em> should be at least 100.</p>
<p>This function is unsafe to call because it writes to a buffer whose
length it does not know.</p>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 2.7: </span>Use <code class="xref py py-func docutils literal notranslate"><span class="pre">PyObject_Str()</span></code> or <code class="xref py py-func docutils literal notranslate"><span class="pre">PyOS_double_to_string()</span></code> instead.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyFloat_AsReprString">
void <code class="descname">PyFloat_AsReprString</code><span class="sig-paren">(</span>char<em> *buf</em>, <a class="reference internal" href="#c.PyFloatObject" title="PyFloatObject">PyFloatObject</a><em> *v</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFloat_AsReprString" title="Permalink to this definition">¶</a></dt>
<dd><p>Same as PyFloat_AsString, except uses the same rules as
<a class="reference internal" href="../library/functions.html#repr" title="repr"><code class="xref py py-func docutils literal notranslate"><span class="pre">repr()</span></code></a>. The length of <em>buf</em> should be at least 100.</p>
<p>This function is unsafe to call because it writes to a buffer whose
length it does not know.</p>
<div class="deprecated">
<p><span class="versionmodified">Deprecated since version 2.7: </span>Use <code class="xref py py-func docutils literal notranslate"><span class="pre">PyObject_Repr()</span></code> or <code class="xref py py-func docutils literal notranslate"><span class="pre">PyOS_double_to_string()</span></code> instead.</p>
</div>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="long.html"
title="previous chapter">Long Integer Objects</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="complex.html"
title="next chapter">Complex Number Objects</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/float.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="complex.html" title="Complex Number Objects"
>next</a> |</li>
<li class="right" >
<a href="long.html" title="Long Integer Objects"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" >Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\I;sy�7 �7 html/c-api/function.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Function Objects — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Method Objects" href="method.html" />
<link rel="prev" title="Class and Instance Objects" href="class.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/function.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="method.html" title="Method Objects"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="class.html" title="Class and Instance Objects"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" accesskey="U">Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="function-objects">
<span id="id1"></span><h1>Function Objects<a class="headerlink" href="#function-objects" title="Permalink to this headline">¶</a></h1>
<p id="index-0">There are a few functions specific to Python functions.</p>
<dl class="type">
<dt id="c.PyFunctionObject">
<code class="descname">PyFunctionObject</code><a class="headerlink" href="#c.PyFunctionObject" title="Permalink to this definition">¶</a></dt>
<dd><p>The C structure used for functions.</p>
</dd></dl>
<dl class="var">
<dt id="c.PyFunction_Type">
<a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a> <code class="descname">PyFunction_Type</code><a class="headerlink" href="#c.PyFunction_Type" title="Permalink to this definition">¶</a></dt>
<dd><p id="index-1">This is an instance of <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyTypeObject</span></code></a> and represents the Python function
type. It is exposed to Python programmers as <code class="docutils literal notranslate"><span class="pre">types.FunctionType</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyFunction_Check">
int <code class="descname">PyFunction_Check</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFunction_Check" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if <em>o</em> is a function object (has type <a class="reference internal" href="#c.PyFunction_Type" title="PyFunction_Type"><code class="xref c c-data docutils literal notranslate"><span class="pre">PyFunction_Type</span></code></a>).
The parameter must not be <em>NULL</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyFunction_New">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyFunction_New</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *code</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *globals</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFunction_New" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: New reference.</em><p>Return a new function object associated with the code object <em>code</em>. <em>globals</em>
must be a dictionary with the global variables accessible to the function.</p>
<p>The function’s docstring, name and <em>__module__</em> are retrieved from the code
object, the argument defaults and closure are set to <em>NULL</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyFunction_GetCode">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyFunction_GetCode</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *op</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFunction_GetCode" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Borrowed reference.</em><p>Return the code object associated with the function object <em>op</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyFunction_GetGlobals">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyFunction_GetGlobals</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *op</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFunction_GetGlobals" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Borrowed reference.</em><p>Return the globals dictionary associated with the function object <em>op</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyFunction_GetModule">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyFunction_GetModule</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *op</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFunction_GetModule" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Borrowed reference.</em><p>Return the <em>__module__</em> attribute of the function object <em>op</em>. This is normally
a string containing the module name, but can be set to any other object by
Python code.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyFunction_GetDefaults">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyFunction_GetDefaults</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *op</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFunction_GetDefaults" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Borrowed reference.</em><p>Return the argument default values of the function object <em>op</em>. This can be a
tuple of arguments or <em>NULL</em>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyFunction_SetDefaults">
int <code class="descname">PyFunction_SetDefaults</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *op</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *defaults</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFunction_SetDefaults" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the argument default values for the function object <em>op</em>. <em>defaults</em> must be
<em>Py_None</em> or a tuple.</p>
<p>Raises <a class="reference internal" href="../library/exceptions.html#exceptions.SystemError" title="exceptions.SystemError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SystemError</span></code></a> and returns <code class="docutils literal notranslate"><span class="pre">-1</span></code> on failure.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyFunction_GetClosure">
<a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyFunction_GetClosure</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *op</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFunction_GetClosure" title="Permalink to this definition">¶</a></dt>
<dd><em class="refcount">Return value: Borrowed reference.</em><p>Return the closure associated with the function object <em>op</em>. This can be <em>NULL</em>
or a tuple of cell objects.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyFunction_SetClosure">
int <code class="descname">PyFunction_SetClosure</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *op</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *closure</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFunction_SetClosure" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the closure associated with the function object <em>op</em>. <em>closure</em> must be
<em>Py_None</em> or a tuple of cell objects.</p>
<p>Raises <a class="reference internal" href="../library/exceptions.html#exceptions.SystemError" title="exceptions.SystemError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SystemError</span></code></a> and returns <code class="docutils literal notranslate"><span class="pre">-1</span></code> on failure.</p>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="class.html"
title="previous chapter">Class and Instance Objects</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="method.html"
title="next chapter">Method Objects</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/function.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="method.html" title="Method Objects"
>next</a> |</li>
<li class="right" >
<a href="class.html" title="Class and Instance Objects"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="concrete.html" >Concrete Objects Layer</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\��z�F] F] html/c-api/gcsupport.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Supporting Cyclic Garbage Collection — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Distributing Python Modules" href="../distributing/index.html" />
<link rel="prev" title="Type Objects" href="typeobj.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/c-api/gcsupport.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="../distributing/index.html" title="Distributing Python Modules"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="typeobj.html" title="Type Objects"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="objimpl.html" accesskey="U">Object Implementation Support</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="supporting-cyclic-garbage-collection">
<span id="supporting-cycle-detection"></span><h1>Supporting Cyclic Garbage Collection<a class="headerlink" href="#supporting-cyclic-garbage-collection" title="Permalink to this headline">¶</a></h1>
<p>Python’s support for detecting and collecting garbage which involves circular
references requires support from object types which are “containers” for other
objects which may also be containers. Types which do not store references to
other objects, or which only store references to atomic types (such as numbers
or strings), do not need to provide any explicit support for garbage
collection.</p>
<p>To create a container type, the <a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_flags" title="PyTypeObject.tp_flags"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_flags</span></code></a> field of the type object must
include the <a class="reference internal" href="typeobj.html#Py_TPFLAGS_HAVE_GC" title="Py_TPFLAGS_HAVE_GC"><code class="xref py py-const docutils literal notranslate"><span class="pre">Py_TPFLAGS_HAVE_GC</span></code></a> and provide an implementation of the
<a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_traverse" title="PyTypeObject.tp_traverse"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_traverse</span></code></a> handler. If instances of the type are mutable, a
<a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_clear" title="PyTypeObject.tp_clear"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_clear</span></code></a> implementation must also be provided.</p>
<dl class="data">
<dt>
<code class="descname">Py_TPFLAGS_HAVE_GC</code></dt>
<dd><p>Objects with a type with this flag set must conform with the rules
documented here. For convenience these objects will be referred to as
container objects.</p>
</dd></dl>
<p>Constructors for container types must conform to two rules:</p>
<ol class="arabic simple">
<li>The memory for the object must be allocated using <a class="reference internal" href="#c.PyObject_GC_New" title="PyObject_GC_New"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_GC_New()</span></code></a>
or <a class="reference internal" href="#c.PyObject_GC_NewVar" title="PyObject_GC_NewVar"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_GC_NewVar()</span></code></a>.</li>
<li>Once all the fields which may contain references to other containers are
initialized, it must call <a class="reference internal" href="#c.PyObject_GC_Track" title="PyObject_GC_Track"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_GC_Track()</span></code></a>.</li>
</ol>
<dl class="function">
<dt id="c.PyObject_GC_New">
TYPE* <code class="descname">PyObject_GC_New</code><span class="sig-paren">(</span>TYPE, <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a><em> *type</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_GC_New" title="Permalink to this definition">¶</a></dt>
<dd><p>Analogous to <a class="reference internal" href="allocation.html#c.PyObject_New" title="PyObject_New"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_New()</span></code></a> but for container objects with the
<a class="reference internal" href="typeobj.html#Py_TPFLAGS_HAVE_GC" title="Py_TPFLAGS_HAVE_GC"><code class="xref py py-const docutils literal notranslate"><span class="pre">Py_TPFLAGS_HAVE_GC</span></code></a> flag set.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_GC_NewVar">
TYPE* <code class="descname">PyObject_GC_NewVar</code><span class="sig-paren">(</span>TYPE, <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a><em> *type</em>, Py_ssize_t<em> size</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_GC_NewVar" title="Permalink to this definition">¶</a></dt>
<dd><p>Analogous to <a class="reference internal" href="allocation.html#c.PyObject_NewVar" title="PyObject_NewVar"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_NewVar()</span></code></a> but for container objects with the
<a class="reference internal" href="typeobj.html#Py_TPFLAGS_HAVE_GC" title="Py_TPFLAGS_HAVE_GC"><code class="xref py py-const docutils literal notranslate"><span class="pre">Py_TPFLAGS_HAVE_GC</span></code></a> flag set.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>size</em>. This might require
changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_GC_Resize">
TYPE* <code class="descname">PyObject_GC_Resize</code><span class="sig-paren">(</span>TYPE, <a class="reference internal" href="structures.html#c.PyVarObject" title="PyVarObject">PyVarObject</a><em> *op</em>, Py_ssize_t<em> newsize</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_GC_Resize" title="Permalink to this definition">¶</a></dt>
<dd><p>Resize an object allocated by <a class="reference internal" href="allocation.html#c.PyObject_NewVar" title="PyObject_NewVar"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_NewVar()</span></code></a>. Returns the
resized object or <em>NULL</em> on failure. <em>op</em> must not be tracked by the collector yet.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.5: </span>This function used an <code class="xref c c-type docutils literal notranslate"><span class="pre">int</span></code> type for <em>newsize</em>. This might
require changes in your code for properly supporting 64-bit systems.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_GC_Track">
void <code class="descname">PyObject_GC_Track</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *op</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_GC_Track" title="Permalink to this definition">¶</a></dt>
<dd><p>Adds the object <em>op</em> to the set of container objects tracked by the
collector. The collector can run at unexpected times so objects must be
valid while being tracked. This should be called once all the fields
followed by the <a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_traverse" title="PyTypeObject.tp_traverse"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_traverse</span></code></a> handler become valid, usually near the
end of the constructor.</p>
</dd></dl>
<dl class="function">
<dt id="c._PyObject_GC_TRACK">
void <code class="descname">_PyObject_GC_TRACK</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *op</em><span class="sig-paren">)</span><a class="headerlink" href="#c._PyObject_GC_TRACK" title="Permalink to this definition">¶</a></dt>
<dd><p>A macro version of <a class="reference internal" href="#c.PyObject_GC_Track" title="PyObject_GC_Track"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_GC_Track()</span></code></a>. It should not be used for
extension modules.</p>
</dd></dl>
<p>Similarly, the deallocator for the object must conform to a similar pair of
rules:</p>
<ol class="arabic simple">
<li>Before fields which refer to other containers are invalidated,
<a class="reference internal" href="#c.PyObject_GC_UnTrack" title="PyObject_GC_UnTrack"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_GC_UnTrack()</span></code></a> must be called.</li>
<li>The object’s memory must be deallocated using <a class="reference internal" href="#c.PyObject_GC_Del" title="PyObject_GC_Del"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_GC_Del()</span></code></a>.</li>
</ol>
<dl class="function">
<dt id="c.PyObject_GC_Del">
void <code class="descname">PyObject_GC_Del</code><span class="sig-paren">(</span>void<em> *op</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_GC_Del" title="Permalink to this definition">¶</a></dt>
<dd><p>Releases memory allocated to an object using <a class="reference internal" href="#c.PyObject_GC_New" title="PyObject_GC_New"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_GC_New()</span></code></a> or
<a class="reference internal" href="#c.PyObject_GC_NewVar" title="PyObject_GC_NewVar"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_GC_NewVar()</span></code></a>.</p>
</dd></dl>
<dl class="function">
<dt id="c.PyObject_GC_UnTrack">
void <code class="descname">PyObject_GC_UnTrack</code><span class="sig-paren">(</span>void<em> *op</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyObject_GC_UnTrack" title="Permalink to this definition">¶</a></dt>
<dd><p>Remove the object <em>op</em> from the set of container objects tracked by the
collector. Note that <a class="reference internal" href="#c.PyObject_GC_Track" title="PyObject_GC_Track"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_GC_Track()</span></code></a> can be called again on
this object to add it back to the set of tracked objects. The deallocator
(<a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_dealloc" title="PyTypeObject.tp_dealloc"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_dealloc</span></code></a> handler) should call this for the object before any of
the fields used by the <a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_traverse" title="PyTypeObject.tp_traverse"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_traverse</span></code></a> handler become invalid.</p>
</dd></dl>
<dl class="function">
<dt id="c._PyObject_GC_UNTRACK">
void <code class="descname">_PyObject_GC_UNTRACK</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *op</em><span class="sig-paren">)</span><a class="headerlink" href="#c._PyObject_GC_UNTRACK" title="Permalink to this definition">¶</a></dt>
<dd><p>A macro version of <a class="reference internal" href="#c.PyObject_GC_UnTrack" title="PyObject_GC_UnTrack"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyObject_GC_UnTrack()</span></code></a>. It should not be used for
extension modules.</p>
</dd></dl>
<p>The <a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_traverse" title="PyTypeObject.tp_traverse"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_traverse</span></code></a> handler accepts a function parameter of this type:</p>
<dl class="type">
<dt id="c.visitproc">
int <code class="descname">(*visitproc)</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *object</em>, void<em> *arg</em><span class="sig-paren">)</span><a class="headerlink" href="#c.visitproc" title="Permalink to this definition">¶</a></dt>
<dd><p>Type of the visitor function passed to the <a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_traverse" title="PyTypeObject.tp_traverse"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_traverse</span></code></a> handler.
The function should be called with an object to traverse as <em>object</em> and
the third parameter to the <a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_traverse" title="PyTypeObject.tp_traverse"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_traverse</span></code></a> handler as <em>arg</em>. The
Python core uses several visitor functions to implement cyclic garbage
detection; it’s not expected that users will need to write their own
visitor functions.</p>
</dd></dl>
<p>The <a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_traverse" title="PyTypeObject.tp_traverse"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_traverse</span></code></a> handler must have the following type:</p>
<dl class="type">
<dt id="c.traverseproc">
int <code class="descname">(*traverseproc)</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *self</em>, <a class="reference internal" href="#c.visitproc" title="visitproc">visitproc</a><em> visit</em>, void<em> *arg</em><span class="sig-paren">)</span><a class="headerlink" href="#c.traverseproc" title="Permalink to this definition">¶</a></dt>
<dd><p>Traversal function for a container object. Implementations must call the
<em>visit</em> function for each object directly contained by <em>self</em>, with the
parameters to <em>visit</em> being the contained object and the <em>arg</em> value passed
to the handler. The <em>visit</em> function must not be called with a <em>NULL</em>
object argument. If <em>visit</em> returns a non-zero value that value should be
returned immediately.</p>
</dd></dl>
<p>To simplify writing <a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_traverse" title="PyTypeObject.tp_traverse"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_traverse</span></code></a> handlers, a <a class="reference internal" href="#c.Py_VISIT" title="Py_VISIT"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_VISIT()</span></code></a> macro is
provided. In order to use this macro, the <a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_traverse" title="PyTypeObject.tp_traverse"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_traverse</span></code></a> implementation
must name its arguments exactly <em>visit</em> and <em>arg</em>:</p>
<dl class="function">
<dt id="c.Py_VISIT">
void <code class="descname">Py_VISIT</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *o</em><span class="sig-paren">)</span><a class="headerlink" href="#c.Py_VISIT" title="Permalink to this definition">¶</a></dt>
<dd><p>If <em>o</em> is not <em>NULL</em>, call the <em>visit</em> callback, with arguments <em>o</em>
and <em>arg</em>. If <em>visit</em> returns a non-zero value, then return it.
Using this macro, <a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_traverse" title="PyTypeObject.tp_traverse"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_traverse</span></code></a> handlers
look like:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">static</span> <span class="kt">int</span>
<span class="nf">my_traverse</span><span class="p">(</span><span class="n">Noddy</span> <span class="o">*</span><span class="n">self</span><span class="p">,</span> <span class="n">visitproc</span> <span class="n">visit</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="n">arg</span><span class="p">)</span>
<span class="p">{</span>
<span class="n">Py_VISIT</span><span class="p">(</span><span class="n">self</span><span class="o">-></span><span class="n">foo</span><span class="p">);</span>
<span class="n">Py_VISIT</span><span class="p">(</span><span class="n">self</span><span class="o">-></span><span class="n">bar</span><span class="p">);</span>
<span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
</dd></dl>
<p>The <a class="reference internal" href="typeobj.html#c.PyTypeObject.tp_clear" title="PyTypeObject.tp_clear"><code class="xref c c-member docutils literal notranslate"><span class="pre">tp_clear</span></code></a> handler must be of the <a class="reference internal" href="#c.inquiry" title="inquiry"><code class="xref c c-type docutils literal notranslate"><span class="pre">inquiry</span></code></a> type, or <em>NULL</em>
if the object is immutable.</p>
<dl class="type">
<dt id="c.inquiry">
int <code class="descname">(*inquiry)</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *self</em><span class="sig-paren">)</span><a class="headerlink" href="#c.inquiry" title="Permalink to this definition">¶</a></dt>
<dd><p>Drop references that may have created reference cycles. Immutable objects
do not have to define this method since they can never directly create
reference cycles. Note that the object must still be valid after calling
this method (don’t just call <a class="reference internal" href="refcounting.html#c.Py_DECREF" title="Py_DECREF"><code class="xref c c-func docutils literal notranslate"><span class="pre">Py_DECREF()</span></code></a> on a reference). The
collector will call this method if it detects that this object is involved
in a reference cycle.</p>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="typeobj.html"
title="previous chapter">Type Objects</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="../distributing/index.html"
title="next chapter">Distributing Python Modules</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/c-api/gcsupport.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="../distributing/index.html" title="Distributing Python Modules"
>next</a> |</li>
<li class="right" >
<a href="typeobj.html" title="Type Objects"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li>
<li class="nav-item nav-item-2"><a href="objimpl.html" >Object Implementation Support</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\,� ~!F !F html/distributing/index.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Distributing Python Modules — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Installing Python Modules" href="../installing/index.html" />
<link rel="prev" title="Supporting Cyclic Garbage Collection" href="../c-api/gcsupport.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/distributing/index.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="../installing/index.html" title="Installing Python Modules"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="../c-api/gcsupport.html" title="Supporting Cyclic Garbage Collection"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="distributing-python-modules">
<span id="distributing-index"></span><h1>Distributing Python Modules<a class="headerlink" href="#distributing-python-modules" title="Permalink to this headline">¶</a></h1>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Email:</th><td class="field-body"><a class="reference external" href="mailto:distutils-sig%40python.org">distutils-sig<span>@</span>python<span>.</span>org</a></td>
</tr>
</tbody>
</table>
<p>As a popular open source development project, Python has an active
supporting community of contributors and users that also make their software
available for other Python developers to use under open source license terms.</p>
<p>This allows Python users to share and collaborate effectively, benefiting
from the solutions others have already created to common (and sometimes
even rare!) problems, as well as potentially contributing their own
solutions to the common pool.</p>
<p>This guide covers the distribution part of the process. For a guide to
installing other Python projects, refer to the
<a class="reference internal" href="../installing/index.html#installing-index"><span class="std std-ref">installation guide</span></a>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">For corporate and other institutional users, be aware that many
organisations have their own policies around using and contributing to
open source software. Please take such policies into account when making
use of the distribution and installation tools provided with Python.</p>
</div>
<div class="section" id="key-terms">
<h2>Key terms<a class="headerlink" href="#key-terms" title="Permalink to this headline">¶</a></h2>
<ul class="simple">
<li>the <a class="reference external" href="https://pypi.org">Python Packaging Index</a> is a public
repository of open source licensed packages made available for use by
other Python users</li>
<li>the <a class="reference external" href="https://www.pypa.io/">Python Packaging Authority</a> are the group of
developers and documentation authors responsible for the maintenance and
evolution of the standard packaging tools and the associated metadata and
file format standards. They maintain a variety of tools, documentation
and issue trackers on both <a class="reference external" href="https://github.com/pypa">GitHub</a> and
<a class="reference external" href="https://bitbucket.org/pypa/">BitBucket</a>.</li>
<li><a class="reference internal" href="../library/distutils.html#module-distutils" title="distutils: Support for building and installing Python modules into an existing Python installation."><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils</span></code></a> is the original build and distribution system first added
to the Python standard library in 1998. While direct use of <a class="reference internal" href="../library/distutils.html#module-distutils" title="distutils: Support for building and installing Python modules into an existing Python installation."><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils</span></code></a>
is being phased out, it still laid the foundation for the current packaging
and distribution infrastructure, and it not only remains part of the
standard library, but its name lives on in other ways (such as the name
of the mailing list used to coordinate Python packaging standards
development).</li>
<li><a class="reference external" href="https://setuptools.readthedocs.io/en/latest/">setuptools</a> is a (largely) drop-in replacement for <a class="reference internal" href="../library/distutils.html#module-distutils" title="distutils: Support for building and installing Python modules into an existing Python installation."><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils</span></code></a> first
published in 2004. Its most notable addition over the unmodified
<a class="reference internal" href="../library/distutils.html#module-distutils" title="distutils: Support for building and installing Python modules into an existing Python installation."><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils</span></code></a> tools was the ability to declare dependencies on other
packages. It is currently recommended as a more regularly updated
alternative to <a class="reference internal" href="../library/distutils.html#module-distutils" title="distutils: Support for building and installing Python modules into an existing Python installation."><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils</span></code></a> that offers consistent support for more
recent packaging standards across a wide range of Python versions.</li>
<li><a class="reference external" href="https://wheel.readthedocs.org">wheel</a> (in this context) is a project that adds the <code class="docutils literal notranslate"><span class="pre">bdist_wheel</span></code>
command to <a class="reference internal" href="../library/distutils.html#module-distutils" title="distutils: Support for building and installing Python modules into an existing Python installation."><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils</span></code></a>/<a class="reference external" href="https://setuptools.readthedocs.io/en/latest/">setuptools</a>. This produces a cross platform
binary packaging format (called “wheels” or “wheel files” and defined in
<span class="target" id="index-0"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0427"><strong>PEP 427</strong></a>) that allows Python libraries, even those including binary
extensions, to be installed on a system without needing to be built
locally.</li>
</ul>
</div>
<div class="section" id="open-source-licensing-and-collaboration">
<h2>Open source licensing and collaboration<a class="headerlink" href="#open-source-licensing-and-collaboration" title="Permalink to this headline">¶</a></h2>
<p>In most parts of the world, software is automatically covered by copyright.
This means that other developers require explicit permission to copy, use,
modify and redistribute the software.</p>
<p>Open source licensing is a way of explicitly granting such permission in a
relatively consistent way, allowing developers to share and collaborate
efficiently by making common solutions to various problems freely available.
This leaves many developers free to spend more time focusing on the problems
that are relatively unique to their specific situation.</p>
<p>The distribution tools provided with Python are designed to make it
reasonably straightforward for developers to make their own contributions
back to that common pool of software if they choose to do so.</p>
<p>The same distribution tools can also be used to distribute software within
an organisation, regardless of whether that software is published as open
source software or not.</p>
</div>
<div class="section" id="installing-the-tools">
<h2>Installing the tools<a class="headerlink" href="#installing-the-tools" title="Permalink to this headline">¶</a></h2>
<p>The standard library does not include build tools that support modern
Python packaging standards, as the core development team has found that it
is important to have standard tools that work consistently, even on older
versions of Python.</p>
<p>The currently recommended build and distribution tools can be installed
by invoking the <code class="docutils literal notranslate"><span class="pre">pip</span></code> module at the command line:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="o">-</span><span class="n">m</span> <span class="n">pip</span> <span class="n">install</span> <span class="n">setuptools</span> <span class="n">wheel</span> <span class="n">twine</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>For POSIX users (including Mac OS X and Linux users), these instructions
assume the use of a <a class="reference internal" href="../glossary.html#term-virtual-environment"><span class="xref std std-term">virtual environment</span></a>.</p>
<p class="last">For Windows users, these instructions assume that the option to
adjust the system PATH environment variable was selected when installing
Python.</p>
</div>
<p>The Python Packaging User Guide includes more details on the <a class="reference external" href="https://packaging.python.org/en/latest/current/#packaging-tool-recommendations">currently
recommended tools</a>.</p>
</div>
<div class="section" id="reading-the-guide">
<h2>Reading the guide<a class="headerlink" href="#reading-the-guide" title="Permalink to this headline">¶</a></h2>
<p>The Python Packaging User Guide covers the various key steps and elements
involved in creating a project:</p>
<ul class="simple">
<li><a class="reference external" href=" https://packaging.python.org/en/latest/distributing/">Project structure</a></li>
<li><a class="reference external" href=" https://packaging.python.org/en/latest/distributing/#packaging-your-project">Building and packaging the project</a></li>
<li><a class="reference external" href=" https://packaging.python.org/en/latest/distributing/#uploading-your-project-to-pypi">Uploading the project to the Python Packaging Index</a></li>
</ul>
</div>
<div class="section" id="how-do-i">
<h2>How do I…?<a class="headerlink" href="#how-do-i" title="Permalink to this headline">¶</a></h2>
<p>These are quick answers or links for some common tasks.</p>
<div class="section" id="choose-a-name-for-my-project">
<h3>… choose a name for my project?<a class="headerlink" href="#choose-a-name-for-my-project" title="Permalink to this headline">¶</a></h3>
<p>This isn’t an easy topic, but here are a few tips:</p>
<ul class="simple">
<li>check the Python Packaging Index to see if the name is already in use</li>
<li>check popular hosting sites like GitHub, BitBucket, etc to see if there
is already a project with that name</li>
<li>check what comes up in a web search for the name you’re considering</li>
<li>avoid particularly common words, especially ones with multiple meanings,
as they can make it difficult for users to find your software when
searching for it</li>
</ul>
</div>
<div class="section" id="create-and-distribute-binary-extensions">
<h3>… create and distribute binary extensions?<a class="headerlink" href="#create-and-distribute-binary-extensions" title="Permalink to this headline">¶</a></h3>
<p>This is actually quite a complex topic, with a variety of alternatives
available depending on exactly what you’re aiming to achieve. See the
Python Packaging User Guide for more information and recommendations.</p>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference external" href="https://packaging.python.org/en/latest/extensions">Python Packaging User Guide: Binary Extensions</a></p>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Distributing Python Modules</a><ul>
<li><a class="reference internal" href="#key-terms">Key terms</a></li>
<li><a class="reference internal" href="#open-source-licensing-and-collaboration">Open source licensing and collaboration</a></li>
<li><a class="reference internal" href="#installing-the-tools">Installing the tools</a></li>
<li><a class="reference internal" href="#reading-the-guide">Reading the guide</a></li>
<li><a class="reference internal" href="#how-do-i">How do I…?</a><ul>
<li><a class="reference internal" href="#choose-a-name-for-my-project">… choose a name for my project?</a></li>
<li><a class="reference internal" href="#create-and-distribute-binary-extensions">… create and distribute binary extensions?</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="../c-api/gcsupport.html"
title="previous chapter">Supporting Cyclic Garbage Collection</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="../installing/index.html"
title="next chapter">Installing Python Modules</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/distributing/index.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="../installing/index.html" title="Installing Python Modules"
>next</a> |</li>
<li class="right" >
<a href="../c-api/gcsupport.html" title="Supporting Cyclic Garbage Collection"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\)��b� b� html/distutils/apiref.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>10. API Reference — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Installing Python Modules (Legacy version)" href="../install/index.html" />
<link rel="prev" title="9. Command Reference" href="commandref.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/distutils/apiref.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="../install/index.html" title="Installing Python Modules (Legacy version)"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="commandref.html" title="9. Command Reference"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Distributing Python Modules (Legacy version)</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="api-reference">
<span id="id1"></span><h1>10. API Reference<a class="headerlink" href="#api-reference" title="Permalink to this headline">¶</a></h1>
<div class="section" id="module-distutils.core">
<span id="distutils-core-core-distutils-functionality"></span><h2>10.1. <a class="reference internal" href="#module-distutils.core" title="distutils.core: The core Distutils functionality"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.core</span></code></a> — Core Distutils functionality<a class="headerlink" href="#module-distutils.core" title="Permalink to this headline">¶</a></h2>
<p>The <a class="reference internal" href="#module-distutils.core" title="distutils.core: The core Distutils functionality"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.core</span></code></a> module is the only module that needs to be installed
to use the Distutils. It provides the <a class="reference internal" href="#distutils.core.setup" title="distutils.core.setup"><code class="xref py py-func docutils literal notranslate"><span class="pre">setup()</span></code></a> (which is called from the
setup script). Indirectly provides the <code class="xref py py-class docutils literal notranslate"><span class="pre">distutils.dist.Distribution</span></code> and
<a class="reference internal" href="#distutils.cmd.Command" title="distutils.cmd.Command"><code class="xref py py-class docutils literal notranslate"><span class="pre">distutils.cmd.Command</span></code></a> class.</p>
<dl class="function">
<dt id="distutils.core.setup">
<code class="descclassname">distutils.core.</code><code class="descname">setup</code><span class="sig-paren">(</span><em>arguments</em><span class="sig-paren">)</span><a class="headerlink" href="#distutils.core.setup" title="Permalink to this definition">¶</a></dt>
<dd><p>The basic do-everything function that does most everything you could ever ask
for from a Distutils method.</p>
<p>The setup function takes a large number of arguments. These are laid out in the
following table.</p>
<table border="1" class="docutils">
<colgroup>
<col width="18%" />
<col width="28%" />
<col width="54%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">argument name</th>
<th class="head">value</th>
<th class="head">type</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><em>name</em></td>
<td>The name of the package</td>
<td>a string</td>
</tr>
<tr class="row-odd"><td><em>version</em></td>
<td>The version number of the
package; see
<a class="reference internal" href="#module-distutils.version" title="distutils.version: implements classes that represent module version numbers."><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.version</span></code></a></td>
<td>a string</td>
</tr>
<tr class="row-even"><td><em>description</em></td>
<td>A single line describing the
package</td>
<td>a string</td>
</tr>
<tr class="row-odd"><td><em>long_description</em></td>
<td>Longer description of the
package</td>
<td>a string</td>
</tr>
<tr class="row-even"><td><em>author</em></td>
<td>The name of the package author</td>
<td>a string</td>
</tr>
<tr class="row-odd"><td><em>author_email</em></td>
<td>The email address of the
package author</td>
<td>a string</td>
</tr>
<tr class="row-even"><td><em>maintainer</em></td>
<td>The name of the current
maintainer, if different from
the author. Note that if
the maintainer is provided,
distutils will use it as the
author in <code class="file docutils literal notranslate"><span class="pre">PKG-INFO</span></code></td>
<td>a string</td>
</tr>
<tr class="row-odd"><td><em>maintainer_email</em></td>
<td>The email address of the
current maintainer, if
different from the author</td>
<td>a string</td>
</tr>
<tr class="row-even"><td><em>url</em></td>
<td>A URL for the package
(homepage)</td>
<td>a string</td>
</tr>
<tr class="row-odd"><td><em>download_url</em></td>
<td>A URL to download the package</td>
<td>a string</td>
</tr>
<tr class="row-even"><td><em>packages</em></td>
<td>A list of Python packages that
distutils will manipulate</td>
<td>a list of strings</td>
</tr>
<tr class="row-odd"><td><em>py_modules</em></td>
<td>A list of Python modules that
distutils will manipulate</td>
<td>a list of strings</td>
</tr>
<tr class="row-even"><td><em>scripts</em></td>
<td>A list of standalone script
files to be built and
installed</td>
<td>a list of strings</td>
</tr>
<tr class="row-odd"><td><em>ext_modules</em></td>
<td>A list of Python extensions to
be built</td>
<td>a list of instances of
<a class="reference internal" href="#distutils.core.Extension" title="distutils.core.Extension"><code class="xref py py-class docutils literal notranslate"><span class="pre">distutils.core.Extension</span></code></a></td>
</tr>
<tr class="row-even"><td><em>classifiers</em></td>
<td>A list of categories for the
package</td>
<td>a list of strings; valid classifiers are listed on <a class="reference external" href="https://pypi.org/classifiers">PyPI</a>.</td>
</tr>
<tr class="row-odd"><td><em>distclass</em></td>
<td>the <a class="reference internal" href="#distutils.core.Distribution" title="distutils.core.Distribution"><code class="xref py py-class docutils literal notranslate"><span class="pre">Distribution</span></code></a>
class to use</td>
<td>a subclass of
<a class="reference internal" href="#distutils.core.Distribution" title="distutils.core.Distribution"><code class="xref py py-class docutils literal notranslate"><span class="pre">distutils.core.Distribution</span></code></a></td>
</tr>
<tr class="row-even"><td><em>script_name</em></td>
<td>The name of the setup.py
script - defaults to
<code class="docutils literal notranslate"><span class="pre">sys.argv[0]</span></code></td>
<td>a string</td>
</tr>
<tr class="row-odd"><td><em>script_args</em></td>
<td>Arguments to supply to the
setup script</td>
<td>a list of strings</td>
</tr>
<tr class="row-even"><td><em>options</em></td>
<td>default options for the setup
script</td>
<td>a dictionary</td>
</tr>
<tr class="row-odd"><td><em>license</em></td>
<td>The license for the package</td>
<td>a string</td>
</tr>
<tr class="row-even"><td><em>keywords</em></td>
<td>Descriptive meta-data, see
<span class="target" id="index-0"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0314"><strong>PEP 314</strong></a></td>
<td>a list of strings or a comma-separated string</td>
</tr>
<tr class="row-odd"><td><em>platforms</em></td>
<td> </td>
<td>a list of strings or a comma-separated string</td>
</tr>
<tr class="row-even"><td><em>cmdclass</em></td>
<td>A mapping of command names to
<a class="reference internal" href="#distutils.core.Command" title="distutils.core.Command"><code class="xref py py-class docutils literal notranslate"><span class="pre">Command</span></code></a> subclasses</td>
<td>a dictionary</td>
</tr>
<tr class="row-odd"><td><em>data_files</em></td>
<td>A list of data files to
install</td>
<td>a list</td>
</tr>
<tr class="row-even"><td><em>package_dir</em></td>
<td>A mapping of package to
directory names</td>
<td>a dictionary</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="function">
<dt id="distutils.core.run_setup">
<code class="descclassname">distutils.core.</code><code class="descname">run_setup</code><span class="sig-paren">(</span><em>script_name</em><span class="optional">[</span>, <em>script_args=None</em>, <em>stop_after='run'</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.core.run_setup" title="Permalink to this definition">¶</a></dt>
<dd><p>Run a setup script in a somewhat controlled environment, and return the
<code class="xref py py-class docutils literal notranslate"><span class="pre">distutils.dist.Distribution</span></code> instance that drives things. This is
useful if you need to find out the distribution meta-data (passed as keyword
args from <em>script</em> to <a class="reference internal" href="#distutils.core.setup" title="distutils.core.setup"><code class="xref py py-func docutils literal notranslate"><span class="pre">setup()</span></code></a>), or the contents of the config files or
command-line.</p>
<p><em>script_name</em> is a file that will be run with <a class="reference internal" href="../library/functions.html#execfile" title="execfile"><code class="xref py py-func docutils literal notranslate"><span class="pre">execfile()</span></code></a> <code class="docutils literal notranslate"><span class="pre">sys.argv[0]</span></code>
will be replaced with <em>script</em> for the duration of the call. <em>script_args</em> is a
list of strings; if supplied, <code class="docutils literal notranslate"><span class="pre">sys.argv[1:]</span></code> will be replaced by <em>script_args</em>
for the duration of the call.</p>
<p><em>stop_after</em> tells <a class="reference internal" href="#distutils.core.setup" title="distutils.core.setup"><code class="xref py py-func docutils literal notranslate"><span class="pre">setup()</span></code></a> when to stop processing; possible values:</p>
<table border="1" class="docutils">
<colgroup>
<col width="25%" />
<col width="75%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">value</th>
<th class="head">description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><em>init</em></td>
<td>Stop after the <a class="reference internal" href="#distutils.core.Distribution" title="distutils.core.Distribution"><code class="xref py py-class docutils literal notranslate"><span class="pre">Distribution</span></code></a>
instance has been created and populated
with the keyword arguments to <a class="reference internal" href="#distutils.core.setup" title="distutils.core.setup"><code class="xref py py-func docutils literal notranslate"><span class="pre">setup()</span></code></a></td>
</tr>
<tr class="row-odd"><td><em>config</em></td>
<td>Stop after config files have been parsed
(and their data stored in the
<a class="reference internal" href="#distutils.core.Distribution" title="distutils.core.Distribution"><code class="xref py py-class docutils literal notranslate"><span class="pre">Distribution</span></code></a> instance)</td>
</tr>
<tr class="row-even"><td><em>commandline</em></td>
<td>Stop after the command-line
(<code class="docutils literal notranslate"><span class="pre">sys.argv[1:]</span></code> or <em>script_args</em>) have
been parsed (and the data stored in the
<a class="reference internal" href="#distutils.core.Distribution" title="distutils.core.Distribution"><code class="xref py py-class docutils literal notranslate"><span class="pre">Distribution</span></code></a> instance.)</td>
</tr>
<tr class="row-odd"><td><em>run</em></td>
<td>Stop after all commands have been run (the
same as if <a class="reference internal" href="#distutils.core.setup" title="distutils.core.setup"><code class="xref py py-func docutils literal notranslate"><span class="pre">setup()</span></code></a> had been called
in the usual way). This is the default
value.</td>
</tr>
</tbody>
</table>
</dd></dl>
<p>In addition, the <a class="reference internal" href="#module-distutils.core" title="distutils.core: The core Distutils functionality"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.core</span></code></a> module exposed a number of classes that
live elsewhere.</p>
<ul class="simple">
<li><code class="xref py py-class docutils literal notranslate"><span class="pre">Extension</span></code> from <a class="reference internal" href="#module-distutils.extension" title="distutils.extension: Provides the Extension class, used to describe C/C++ extension modules in setup scripts"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.extension</span></code></a></li>
<li><a class="reference internal" href="#distutils.cmd.Command" title="distutils.cmd.Command"><code class="xref py py-class docutils literal notranslate"><span class="pre">Command</span></code></a> from <a class="reference internal" href="#module-distutils.cmd" title="distutils.cmd: This module provides the abstract base class Command. This class is subclassed by the modules in the distutils.command subpackage."><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.cmd</span></code></a></li>
<li><code class="xref py py-class docutils literal notranslate"><span class="pre">Distribution</span></code> from <a class="reference internal" href="#module-distutils.dist" title="distutils.dist: Provides the Distribution class, which represents the module distribution being built/installed/distributed"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.dist</span></code></a></li>
</ul>
<p>A short description of each of these follows, but see the relevant module for
the full reference.</p>
<dl class="class">
<dt id="distutils.core.Extension">
<em class="property">class </em><code class="descclassname">distutils.core.</code><code class="descname">Extension</code><a class="headerlink" href="#distutils.core.Extension" title="Permalink to this definition">¶</a></dt>
<dd><p>The Extension class describes a single C or C++ extension module in a setup
script. It accepts the following keyword arguments in its constructor</p>
<table border="1" class="docutils">
<colgroup>
<col width="29%" />
<col width="39%" />
<col width="33%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">argument name</th>
<th class="head">value</th>
<th class="head">type</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><em>name</em></td>
<td>the full name of the
extension, including any
packages — ie. <em>not</em> a
filename or pathname, but
Python dotted name</td>
<td>a string</td>
</tr>
<tr class="row-odd"><td><em>sources</em></td>
<td>list of source filenames,
relative to the distribution
root (where the setup script
lives), in Unix form (slash-
separated) for portability.
Source files may be C, C++,
SWIG (.i), platform-specific
resource files, or whatever
else is recognized by the
<strong class="command">build_ext</strong> command
as source for a Python
extension.</td>
<td>a list of strings</td>
</tr>
<tr class="row-even"><td><em>include_dirs</em></td>
<td>list of directories to search
for C/C++ header files (in
Unix form for portability)</td>
<td>a list of strings</td>
</tr>
<tr class="row-odd"><td><em>define_macros</em></td>
<td>list of macros to define; each
macro is defined using a
2-tuple <code class="docutils literal notranslate"><span class="pre">(name,</span> <span class="pre">value)</span></code>,
where <em>value</em> is
either the string to define it
to or <code class="docutils literal notranslate"><span class="pre">None</span></code> to define it
without a particular value
(equivalent of <code class="docutils literal notranslate"><span class="pre">#define</span> <span class="pre">FOO</span></code>
in source or <code class="xref std std-option docutils literal notranslate"><span class="pre">-DFOO</span></code>
on Unix C compiler command
line)</td>
<td>a list of tuples</td>
</tr>
<tr class="row-even"><td><em>undef_macros</em></td>
<td>list of macros to undefine
explicitly</td>
<td>a list of strings</td>
</tr>
<tr class="row-odd"><td><em>library_dirs</em></td>
<td>list of directories to search
for C/C++ libraries at link
time</td>
<td>a list of strings</td>
</tr>
<tr class="row-even"><td><em>libraries</em></td>
<td>list of library names (not
filenames or paths) to link
against</td>
<td>a list of strings</td>
</tr>
<tr class="row-odd"><td><em>runtime_library_dirs</em></td>
<td>list of directories to search
for C/C++ libraries at run
time (for shared extensions,
this is when the extension is
loaded)</td>
<td>a list of strings</td>
</tr>
<tr class="row-even"><td><em>extra_objects</em></td>
<td>list of extra files to link
with (eg. object files not
implied by ‘sources’, static
library that must be
explicitly specified, binary
resource files, etc.)</td>
<td>a list of strings</td>
</tr>
<tr class="row-odd"><td><em>extra_compile_args</em></td>
<td>any extra platform- and
compiler-specific information
to use when compiling the
source files in ‘sources’. For
platforms and compilers where
a command line makes sense,
this is typically a list of
command-line arguments, but
for other platforms it could
be anything.</td>
<td>a list of strings</td>
</tr>
<tr class="row-even"><td><em>extra_link_args</em></td>
<td>any extra platform- and
compiler-specific information
to use when linking object
files together to create the
extension (or to create a new
static Python interpreter).
Similar interpretation as for
‘extra_compile_args’.</td>
<td>a list of strings</td>
</tr>
<tr class="row-odd"><td><em>export_symbols</em></td>
<td>list of symbols to be exported
from a shared extension. Not
used on all platforms, and not
generally necessary for Python
extensions, which typically
export exactly one symbol:
<code class="docutils literal notranslate"><span class="pre">init</span></code> + extension_name.</td>
<td>a list of strings</td>
</tr>
<tr class="row-even"><td><em>depends</em></td>
<td>list of files that the
extension depends on</td>
<td>a list of strings</td>
</tr>
<tr class="row-odd"><td><em>language</em></td>
<td>extension language (i.e.
<code class="docutils literal notranslate"><span class="pre">'c'</span></code>, <code class="docutils literal notranslate"><span class="pre">'c++'</span></code>,
<code class="docutils literal notranslate"><span class="pre">'objc'</span></code>). Will be detected
from the source extensions if
not provided.</td>
<td>a string</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="class">
<dt id="distutils.core.Distribution">
<em class="property">class </em><code class="descclassname">distutils.core.</code><code class="descname">Distribution</code><a class="headerlink" href="#distutils.core.Distribution" title="Permalink to this definition">¶</a></dt>
<dd><p>A <a class="reference internal" href="#distutils.core.Distribution" title="distutils.core.Distribution"><code class="xref py py-class docutils literal notranslate"><span class="pre">Distribution</span></code></a> describes how to build, install and package up a Python
software package.</p>
<p>See the <a class="reference internal" href="#distutils.core.setup" title="distutils.core.setup"><code class="xref py py-func docutils literal notranslate"><span class="pre">setup()</span></code></a> function for a list of keyword arguments accepted by the
Distribution constructor. <a class="reference internal" href="#distutils.core.setup" title="distutils.core.setup"><code class="xref py py-func docutils literal notranslate"><span class="pre">setup()</span></code></a> creates a Distribution instance.</p>
</dd></dl>
<dl class="class">
<dt id="distutils.core.Command">
<em class="property">class </em><code class="descclassname">distutils.core.</code><code class="descname">Command</code><a class="headerlink" href="#distutils.core.Command" title="Permalink to this definition">¶</a></dt>
<dd><p>A <a class="reference internal" href="#distutils.core.Command" title="distutils.core.Command"><code class="xref py py-class docutils literal notranslate"><span class="pre">Command</span></code></a> class (or rather, an instance of one of its subclasses)
implement a single distutils command.</p>
</dd></dl>
</div>
<div class="section" id="module-distutils.ccompiler">
<span id="distutils-ccompiler-ccompiler-base-class"></span><h2>10.2. <a class="reference internal" href="#module-distutils.ccompiler" title="distutils.ccompiler: Abstract CCompiler class"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.ccompiler</span></code></a> — CCompiler base class<a class="headerlink" href="#module-distutils.ccompiler" title="Permalink to this headline">¶</a></h2>
<p>This module provides the abstract base class for the <a class="reference internal" href="#distutils.ccompiler.CCompiler" title="distutils.ccompiler.CCompiler"><code class="xref py py-class docutils literal notranslate"><span class="pre">CCompiler</span></code></a>
classes. A <a class="reference internal" href="#distutils.ccompiler.CCompiler" title="distutils.ccompiler.CCompiler"><code class="xref py py-class docutils literal notranslate"><span class="pre">CCompiler</span></code></a> instance can be used for all the compile and
link steps needed to build a single project. Methods are provided to set
options for the compiler — macro definitions, include directories, link path,
libraries and the like.</p>
<p>This module provides the following functions.</p>
<dl class="function">
<dt id="distutils.ccompiler.gen_lib_options">
<code class="descclassname">distutils.ccompiler.</code><code class="descname">gen_lib_options</code><span class="sig-paren">(</span><em>compiler</em>, <em>library_dirs</em>, <em>runtime_library_dirs</em>, <em>libraries</em><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.gen_lib_options" title="Permalink to this definition">¶</a></dt>
<dd><p>Generate linker options for searching library directories and linking with
specific libraries. <em>libraries</em> and <em>library_dirs</em> are, respectively, lists of
library names (not filenames!) and search directories. Returns a list of
command-line options suitable for use with some compiler (depending on the two
format strings passed in).</p>
</dd></dl>
<dl class="function">
<dt id="distutils.ccompiler.gen_preprocess_options">
<code class="descclassname">distutils.ccompiler.</code><code class="descname">gen_preprocess_options</code><span class="sig-paren">(</span><em>macros</em>, <em>include_dirs</em><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.gen_preprocess_options" title="Permalink to this definition">¶</a></dt>
<dd><p>Generate C pre-processor options (<code class="xref std std-option docutils literal notranslate"><span class="pre">-D</span></code>, <code class="xref std std-option docutils literal notranslate"><span class="pre">-U</span></code>, <code class="xref std std-option docutils literal notranslate"><span class="pre">-I</span></code>) as
used by at least two types of compilers: the typical Unix compiler and Visual
C++. <em>macros</em> is the usual thing, a list of 1- or 2-tuples, where <code class="docutils literal notranslate"><span class="pre">(name,)</span></code>
means undefine (<code class="xref std std-option docutils literal notranslate"><span class="pre">-U</span></code>) macro <em>name</em>, and <code class="docutils literal notranslate"><span class="pre">(name,</span> <span class="pre">value)</span></code> means define
(<code class="xref std std-option docutils literal notranslate"><span class="pre">-D</span></code>) macro <em>name</em> to <em>value</em>. <em>include_dirs</em> is just a list of
directory names to be added to the header file search path (<code class="xref std std-option docutils literal notranslate"><span class="pre">-I</span></code>).
Returns a list of command-line options suitable for either Unix compilers or
Visual C++.</p>
</dd></dl>
<dl class="function">
<dt id="distutils.ccompiler.get_default_compiler">
<code class="descclassname">distutils.ccompiler.</code><code class="descname">get_default_compiler</code><span class="sig-paren">(</span><em>osname</em>, <em>platform</em><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.get_default_compiler" title="Permalink to this definition">¶</a></dt>
<dd><p>Determine the default compiler to use for the given platform.</p>
<p><em>osname</em> should be one of the standard Python OS names (i.e. the ones returned
by <code class="docutils literal notranslate"><span class="pre">os.name</span></code>) and <em>platform</em> the common value returned by <code class="docutils literal notranslate"><span class="pre">sys.platform</span></code> for
the platform in question.</p>
<p>The default values are <code class="docutils literal notranslate"><span class="pre">os.name</span></code> and <code class="docutils literal notranslate"><span class="pre">sys.platform</span></code> in case the parameters
are not given.</p>
</dd></dl>
<dl class="function">
<dt id="distutils.ccompiler.new_compiler">
<code class="descclassname">distutils.ccompiler.</code><code class="descname">new_compiler</code><span class="sig-paren">(</span><em>plat=None</em>, <em>compiler=None</em>, <em>verbose=0</em>, <em>dry_run=0</em>, <em>force=0</em><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.new_compiler" title="Permalink to this definition">¶</a></dt>
<dd><p>Factory function to generate an instance of some CCompiler subclass for the
supplied platform/compiler combination. <em>plat</em> defaults to <code class="docutils literal notranslate"><span class="pre">os.name</span></code> (eg.
<code class="docutils literal notranslate"><span class="pre">'posix'</span></code>, <code class="docutils literal notranslate"><span class="pre">'nt'</span></code>), and <em>compiler</em> defaults to the default compiler for
that platform. Currently only <code class="docutils literal notranslate"><span class="pre">'posix'</span></code> and <code class="docutils literal notranslate"><span class="pre">'nt'</span></code> are supported, and the
default compilers are “traditional Unix interface” (<code class="xref py py-class docutils literal notranslate"><span class="pre">UnixCCompiler</span></code>
class) and Visual C++ (<code class="xref py py-class docutils literal notranslate"><span class="pre">MSVCCompiler</span></code> class). Note that it’s perfectly
possible to ask for a Unix compiler object under Windows, and a Microsoft
compiler object under Unix—if you supply a value for <em>compiler</em>, <em>plat</em> is
ignored.</p>
</dd></dl>
<dl class="function">
<dt id="distutils.ccompiler.show_compilers">
<code class="descclassname">distutils.ccompiler.</code><code class="descname">show_compilers</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.show_compilers" title="Permalink to this definition">¶</a></dt>
<dd><p>Print list of available compilers (used by the <code class="xref std std-option docutils literal notranslate"><span class="pre">--help-compiler</span></code> options
to <strong class="command">build</strong>, <strong class="command">build_ext</strong>, <strong class="command">build_clib</strong>).</p>
</dd></dl>
<dl class="class">
<dt id="distutils.ccompiler.CCompiler">
<em class="property">class </em><code class="descclassname">distutils.ccompiler.</code><code class="descname">CCompiler</code><span class="sig-paren">(</span><span class="optional">[</span><em>verbose=0</em>, <em>dry_run=0</em>, <em>force=0</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.CCompiler" title="Permalink to this definition">¶</a></dt>
<dd><p>The abstract base class <a class="reference internal" href="#distutils.ccompiler.CCompiler" title="distutils.ccompiler.CCompiler"><code class="xref py py-class docutils literal notranslate"><span class="pre">CCompiler</span></code></a> defines the interface that must be
implemented by real compiler classes. The class also has some utility methods
used by several compiler classes.</p>
<p>The basic idea behind a compiler abstraction class is that each instance can be
used for all the compile/link steps in building a single project. Thus,
attributes common to all of those compile and link steps — include
directories, macros to define, libraries to link against, etc. — are
attributes of the compiler instance. To allow for variability in how individual
files are treated, most of those attributes may be varied on a per-compilation
or per-link basis.</p>
<p>The constructor for each subclass creates an instance of the Compiler object.
Flags are <em>verbose</em> (show verbose output), <em>dry_run</em> (don’t actually execute the
steps) and <em>force</em> (rebuild everything, regardless of dependencies). All of
these flags default to <code class="docutils literal notranslate"><span class="pre">0</span></code> (off). Note that you probably don’t want to
instantiate <a class="reference internal" href="#distutils.ccompiler.CCompiler" title="distutils.ccompiler.CCompiler"><code class="xref py py-class docutils literal notranslate"><span class="pre">CCompiler</span></code></a> or one of its subclasses directly - use the
<code class="xref py py-func docutils literal notranslate"><span class="pre">distutils.CCompiler.new_compiler()</span></code> factory function instead.</p>
<p>The following methods allow you to manually alter compiler options for the
instance of the Compiler class.</p>
<dl class="method">
<dt id="distutils.ccompiler.CCompiler.add_include_dir">
<code class="descname">add_include_dir</code><span class="sig-paren">(</span><em>dir</em><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.CCompiler.add_include_dir" title="Permalink to this definition">¶</a></dt>
<dd><p>Add <em>dir</em> to the list of directories that will be searched for header files.
The compiler is instructed to search directories in the order in which they are
supplied by successive calls to <a class="reference internal" href="#distutils.ccompiler.CCompiler.add_include_dir" title="distutils.ccompiler.CCompiler.add_include_dir"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_include_dir()</span></code></a>.</p>
</dd></dl>
<dl class="method">
<dt id="distutils.ccompiler.CCompiler.set_include_dirs">
<code class="descname">set_include_dirs</code><span class="sig-paren">(</span><em>dirs</em><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.CCompiler.set_include_dirs" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the list of directories that will be searched to <em>dirs</em> (a list of strings).
Overrides any preceding calls to <a class="reference internal" href="#distutils.ccompiler.CCompiler.add_include_dir" title="distutils.ccompiler.CCompiler.add_include_dir"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_include_dir()</span></code></a>; subsequent calls to
<a class="reference internal" href="#distutils.ccompiler.CCompiler.add_include_dir" title="distutils.ccompiler.CCompiler.add_include_dir"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_include_dir()</span></code></a> add to the list passed to <a class="reference internal" href="#distutils.ccompiler.CCompiler.set_include_dirs" title="distutils.ccompiler.CCompiler.set_include_dirs"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_include_dirs()</span></code></a>.
This does not affect any list of standard include directories that the compiler
may search by default.</p>
</dd></dl>
<dl class="method">
<dt id="distutils.ccompiler.CCompiler.add_library">
<code class="descname">add_library</code><span class="sig-paren">(</span><em>libname</em><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.CCompiler.add_library" title="Permalink to this definition">¶</a></dt>
<dd><p>Add <em>libname</em> to the list of libraries that will be included in all links driven
by this compiler object. Note that <em>libname</em> should *not* be the name of a
file containing a library, but the name of the library itself: the actual
filename will be inferred by the linker, the compiler, or the compiler class
(depending on the platform).</p>
<p>The linker will be instructed to link against libraries in the order they were
supplied to <a class="reference internal" href="#distutils.ccompiler.CCompiler.add_library" title="distutils.ccompiler.CCompiler.add_library"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_library()</span></code></a> and/or <a class="reference internal" href="#distutils.ccompiler.CCompiler.set_libraries" title="distutils.ccompiler.CCompiler.set_libraries"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_libraries()</span></code></a>. It is perfectly
valid to duplicate library names; the linker will be instructed to link against
libraries as many times as they are mentioned.</p>
</dd></dl>
<dl class="method">
<dt id="distutils.ccompiler.CCompiler.set_libraries">
<code class="descname">set_libraries</code><span class="sig-paren">(</span><em>libnames</em><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.CCompiler.set_libraries" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the list of libraries to be included in all links driven by this compiler
object to <em>libnames</em> (a list of strings). This does not affect any standard
system libraries that the linker may include by default.</p>
</dd></dl>
<dl class="method">
<dt id="distutils.ccompiler.CCompiler.add_library_dir">
<code class="descname">add_library_dir</code><span class="sig-paren">(</span><em>dir</em><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.CCompiler.add_library_dir" title="Permalink to this definition">¶</a></dt>
<dd><p>Add <em>dir</em> to the list of directories that will be searched for libraries
specified to <a class="reference internal" href="#distutils.ccompiler.CCompiler.add_library" title="distutils.ccompiler.CCompiler.add_library"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_library()</span></code></a> and <a class="reference internal" href="#distutils.ccompiler.CCompiler.set_libraries" title="distutils.ccompiler.CCompiler.set_libraries"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_libraries()</span></code></a>. The linker will be
instructed to search for libraries in the order they are supplied to
<a class="reference internal" href="#distutils.ccompiler.CCompiler.add_library_dir" title="distutils.ccompiler.CCompiler.add_library_dir"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_library_dir()</span></code></a> and/or <a class="reference internal" href="#distutils.ccompiler.CCompiler.set_library_dirs" title="distutils.ccompiler.CCompiler.set_library_dirs"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_library_dirs()</span></code></a>.</p>
</dd></dl>
<dl class="method">
<dt id="distutils.ccompiler.CCompiler.set_library_dirs">
<code class="descname">set_library_dirs</code><span class="sig-paren">(</span><em>dirs</em><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.CCompiler.set_library_dirs" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the list of library search directories to <em>dirs</em> (a list of strings). This
does not affect any standard library search path that the linker may search by
default.</p>
</dd></dl>
<dl class="method">
<dt id="distutils.ccompiler.CCompiler.add_runtime_library_dir">
<code class="descname">add_runtime_library_dir</code><span class="sig-paren">(</span><em>dir</em><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.CCompiler.add_runtime_library_dir" title="Permalink to this definition">¶</a></dt>
<dd><p>Add <em>dir</em> to the list of directories that will be searched for shared libraries
at runtime.</p>
</dd></dl>
<dl class="method">
<dt id="distutils.ccompiler.CCompiler.set_runtime_library_dirs">
<code class="descname">set_runtime_library_dirs</code><span class="sig-paren">(</span><em>dirs</em><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.CCompiler.set_runtime_library_dirs" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the list of directories to search for shared libraries at runtime to <em>dirs</em>
(a list of strings). This does not affect any standard search path that the
runtime linker may search by default.</p>
</dd></dl>
<dl class="method">
<dt id="distutils.ccompiler.CCompiler.define_macro">
<code class="descname">define_macro</code><span class="sig-paren">(</span><em>name</em><span class="optional">[</span>, <em>value=None</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.CCompiler.define_macro" title="Permalink to this definition">¶</a></dt>
<dd><p>Define a preprocessor macro for all compilations driven by this compiler object.
The optional parameter <em>value</em> should be a string; if it is not supplied, then
the macro will be defined without an explicit value and the exact outcome
depends on the compiler used.</p>
</dd></dl>
<dl class="method">
<dt id="distutils.ccompiler.CCompiler.undefine_macro">
<code class="descname">undefine_macro</code><span class="sig-paren">(</span><em>name</em><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.CCompiler.undefine_macro" title="Permalink to this definition">¶</a></dt>
<dd><p>Undefine a preprocessor macro for all compilations driven by this compiler
object. If the same macro is defined by <a class="reference internal" href="#distutils.ccompiler.CCompiler.define_macro" title="distutils.ccompiler.CCompiler.define_macro"><code class="xref py py-meth docutils literal notranslate"><span class="pre">define_macro()</span></code></a> and
undefined by <a class="reference internal" href="#distutils.ccompiler.CCompiler.undefine_macro" title="distutils.ccompiler.CCompiler.undefine_macro"><code class="xref py py-meth docutils literal notranslate"><span class="pre">undefine_macro()</span></code></a> the last call takes precedence
(including multiple redefinitions or undefinitions). If the macro is
redefined/undefined on a per-compilation basis (ie. in the call to
<a class="reference internal" href="../library/functions.html#compile" title="compile"><code class="xref py py-meth docutils literal notranslate"><span class="pre">compile()</span></code></a>), then that takes precedence.</p>
</dd></dl>
<dl class="method">
<dt id="distutils.ccompiler.CCompiler.add_link_object">
<code class="descname">add_link_object</code><span class="sig-paren">(</span><em>object</em><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.CCompiler.add_link_object" title="Permalink to this definition">¶</a></dt>
<dd><p>Add <em>object</em> to the list of object files (or analogues, such as explicitly named
library files or the output of “resource compilers”) to be included in every
link driven by this compiler object.</p>
</dd></dl>
<dl class="method">
<dt id="distutils.ccompiler.CCompiler.set_link_objects">
<code class="descname">set_link_objects</code><span class="sig-paren">(</span><em>objects</em><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.CCompiler.set_link_objects" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the list of object files (or analogues) to be included in every link to
<em>objects</em>. This does not affect any standard object files that the linker may
include by default (such as system libraries).</p>
</dd></dl>
<p>The following methods implement methods for autodetection of compiler options,
providing some functionality similar to GNU <strong class="program">autoconf</strong>.</p>
<dl class="method">
<dt id="distutils.ccompiler.CCompiler.detect_language">
<code class="descname">detect_language</code><span class="sig-paren">(</span><em>sources</em><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.CCompiler.detect_language" title="Permalink to this definition">¶</a></dt>
<dd><p>Detect the language of a given file, or list of files. Uses the instance
attributes <code class="xref py py-attr docutils literal notranslate"><span class="pre">language_map</span></code> (a dictionary), and <code class="xref py py-attr docutils literal notranslate"><span class="pre">language_order</span></code> (a
list) to do the job.</p>
</dd></dl>
<dl class="method">
<dt id="distutils.ccompiler.CCompiler.find_library_file">
<code class="descname">find_library_file</code><span class="sig-paren">(</span><em>dirs</em>, <em>lib</em><span class="optional">[</span>, <em>debug=0</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.CCompiler.find_library_file" title="Permalink to this definition">¶</a></dt>
<dd><p>Search the specified list of directories for a static or shared library file
<em>lib</em> and return the full path to that file. If <em>debug</em> is true, look for a
debugging version (if that makes sense on the current platform). Return
<code class="docutils literal notranslate"><span class="pre">None</span></code> if <em>lib</em> wasn’t found in any of the specified directories.</p>
</dd></dl>
<dl class="method">
<dt id="distutils.ccompiler.CCompiler.has_function">
<code class="descname">has_function</code><span class="sig-paren">(</span><em>funcname</em><span class="optional">[</span>, <em>includes=None</em>, <em>include_dirs=None</em>, <em>libraries=None</em>, <em>library_dirs=None</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.CCompiler.has_function" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a boolean indicating whether <em>funcname</em> is supported on the current
platform. The optional arguments can be used to augment the compilation
environment by providing additional include files and paths and libraries and
paths.</p>
</dd></dl>
<dl class="method">
<dt id="distutils.ccompiler.CCompiler.library_dir_option">
<code class="descname">library_dir_option</code><span class="sig-paren">(</span><em>dir</em><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.CCompiler.library_dir_option" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the compiler option to add <em>dir</em> to the list of directories searched for
libraries.</p>
</dd></dl>
<dl class="method">
<dt id="distutils.ccompiler.CCompiler.library_option">
<code class="descname">library_option</code><span class="sig-paren">(</span><em>lib</em><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.CCompiler.library_option" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the compiler option to add <em>lib</em> to the list of libraries linked into the
shared library or executable.</p>
</dd></dl>
<dl class="method">
<dt id="distutils.ccompiler.CCompiler.runtime_library_dir_option">
<code class="descname">runtime_library_dir_option</code><span class="sig-paren">(</span><em>dir</em><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.CCompiler.runtime_library_dir_option" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the compiler option to add <em>dir</em> to the list of directories searched for
runtime libraries.</p>
</dd></dl>
<dl class="method">
<dt id="distutils.ccompiler.CCompiler.set_executables">
<code class="descname">set_executables</code><span class="sig-paren">(</span><em>**args</em><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.CCompiler.set_executables" title="Permalink to this definition">¶</a></dt>
<dd><p>Define the executables (and options for them) that will be run to perform the
various stages of compilation. The exact set of executables that may be
specified here depends on the compiler class (via the ‘executables’ class
attribute), but most will have:</p>
<table border="1" class="docutils">
<colgroup>
<col width="25%" />
<col width="75%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">attribute</th>
<th class="head">description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><em>compiler</em></td>
<td>the C/C++ compiler</td>
</tr>
<tr class="row-odd"><td><em>linker_so</em></td>
<td>linker used to create shared objects and
libraries</td>
</tr>
<tr class="row-even"><td><em>linker_exe</em></td>
<td>linker used to create binary executables</td>
</tr>
<tr class="row-odd"><td><em>archiver</em></td>
<td>static library creator</td>
</tr>
</tbody>
</table>
<p>On platforms with a command-line (Unix, DOS/Windows), each of these is a string
that will be split into executable name and (optional) list of arguments.
(Splitting the string is done similarly to how Unix shells operate: words are
delimited by spaces, but quotes and backslashes can override this. See
<a class="reference internal" href="#distutils.util.split_quoted" title="distutils.util.split_quoted"><code class="xref py py-func docutils literal notranslate"><span class="pre">distutils.util.split_quoted()</span></code></a>.)</p>
</dd></dl>
<p>The following methods invoke stages in the build process.</p>
<dl class="method">
<dt id="distutils.ccompiler.CCompiler.compile">
<code class="descname">compile</code><span class="sig-paren">(</span><em>sources</em><span class="optional">[</span>, <em>output_dir=None</em>, <em>macros=None</em>, <em>include_dirs=None</em>, <em>debug=0</em>, <em>extra_preargs=None</em>, <em>extra_postargs=None</em>, <em>depends=None</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.CCompiler.compile" title="Permalink to this definition">¶</a></dt>
<dd><p>Compile one or more source files. Generates object files (e.g. transforms a
<code class="file docutils literal notranslate"><span class="pre">.c</span></code> file to a <code class="file docutils literal notranslate"><span class="pre">.o</span></code> file.)</p>
<p><em>sources</em> must be a list of filenames, most likely C/C++ files, but in reality
anything that can be handled by a particular compiler and compiler class (eg.
<code class="xref py py-class docutils literal notranslate"><span class="pre">MSVCCompiler</span></code> can handle resource files in <em>sources</em>). Return a list of
object filenames, one per source filename in <em>sources</em>. Depending on the
implementation, not all source files will necessarily be compiled, but all
corresponding object filenames will be returned.</p>
<p>If <em>output_dir</em> is given, object files will be put under it, while retaining
their original path component. That is, <code class="file docutils literal notranslate"><span class="pre">foo/bar.c</span></code> normally compiles to
<code class="file docutils literal notranslate"><span class="pre">foo/bar.o</span></code> (for a Unix implementation); if <em>output_dir</em> is <em>build</em>, then
it would compile to <code class="file docutils literal notranslate"><span class="pre">build/foo/bar.o</span></code>.</p>
<p><em>macros</em>, if given, must be a list of macro definitions. A macro definition is
either a <code class="docutils literal notranslate"><span class="pre">(name,</span> <span class="pre">value)</span></code> 2-tuple or a <code class="docutils literal notranslate"><span class="pre">(name,)</span></code> 1-tuple. The former defines
a macro; if the value is <code class="docutils literal notranslate"><span class="pre">None</span></code>, the macro is defined without an explicit
value. The 1-tuple case undefines a macro. Later
definitions/redefinitions/undefinitions take precedence.</p>
<p><em>include_dirs</em>, if given, must be a list of strings, the directories to add to
the default include file search path for this compilation only.</p>
<p><em>debug</em> is a boolean; if true, the compiler will be instructed to output debug
symbols in (or alongside) the object file(s).</p>
<p><em>extra_preargs</em> and <em>extra_postargs</em> are implementation-dependent. On platforms
that have the notion of a command-line (e.g. Unix, DOS/Windows), they are most
likely lists of strings: extra command-line arguments to prepend/append to the
compiler command line. On other platforms, consult the implementation class
documentation. In any event, they are intended as an escape hatch for those
occasions when the abstract compiler framework doesn’t cut the mustard.</p>
<p><em>depends</em>, if given, is a list of filenames that all targets depend on. If a
source file is older than any file in depends, then the source file will be
recompiled. This supports dependency tracking, but only at a coarse
granularity.</p>
<p>Raises <code class="xref py py-exc docutils literal notranslate"><span class="pre">CompileError</span></code> on failure.</p>
</dd></dl>
<dl class="method">
<dt id="distutils.ccompiler.CCompiler.create_static_lib">
<code class="descname">create_static_lib</code><span class="sig-paren">(</span><em>objects</em>, <em>output_libname</em><span class="optional">[</span>, <em>output_dir=None</em>, <em>debug=0</em>, <em>target_lang=None</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.CCompiler.create_static_lib" title="Permalink to this definition">¶</a></dt>
<dd><p>Link a bunch of stuff together to create a static library file. The “bunch of
stuff” consists of the list of object files supplied as <em>objects</em>, the extra
object files supplied to <a class="reference internal" href="#distutils.ccompiler.CCompiler.add_link_object" title="distutils.ccompiler.CCompiler.add_link_object"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_link_object()</span></code></a> and/or
<a class="reference internal" href="#distutils.ccompiler.CCompiler.set_link_objects" title="distutils.ccompiler.CCompiler.set_link_objects"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_link_objects()</span></code></a>, the libraries supplied to <a class="reference internal" href="#distutils.ccompiler.CCompiler.add_library" title="distutils.ccompiler.CCompiler.add_library"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_library()</span></code></a> and/or
<a class="reference internal" href="#distutils.ccompiler.CCompiler.set_libraries" title="distutils.ccompiler.CCompiler.set_libraries"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_libraries()</span></code></a>, and the libraries supplied as <em>libraries</em> (if any).</p>
<p><em>output_libname</em> should be a library name, not a filename; the filename will be
inferred from the library name. <em>output_dir</em> is the directory where the library
file will be put.</p>
<p><em>debug</em> is a boolean; if true, debugging information will be included in the
library (note that on most platforms, it is the compile step where this matters:
the <em>debug</em> flag is included here just for consistency).</p>
<p><em>target_lang</em> is the target language for which the given objects are being
compiled. This allows specific linkage time treatment of certain languages.</p>
<p>Raises <code class="xref py py-exc docutils literal notranslate"><span class="pre">LibError</span></code> on failure.</p>
</dd></dl>
<dl class="method">
<dt id="distutils.ccompiler.CCompiler.link">
<code class="descname">link</code><span class="sig-paren">(</span><em>target_desc</em>, <em>objects</em>, <em>output_filename</em><span class="optional">[</span>, <em>output_dir=None</em>, <em>libraries=None</em>, <em>library_dirs=None</em>, <em>runtime_library_dirs=None</em>, <em>export_symbols=None</em>, <em>debug=0</em>, <em>extra_preargs=None</em>, <em>extra_postargs=None</em>, <em>build_temp=None</em>, <em>target_lang=None</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.CCompiler.link" title="Permalink to this definition">¶</a></dt>
<dd><p>Link a bunch of stuff together to create an executable or shared library file.</p>
<p>The “bunch of stuff” consists of the list of object files supplied as <em>objects</em>.
<em>output_filename</em> should be a filename. If <em>output_dir</em> is supplied,
<em>output_filename</em> is relative to it (i.e. <em>output_filename</em> can provide
directory components if needed).</p>
<p><em>libraries</em> is a list of libraries to link against. These are library names,
not filenames, since they’re translated into filenames in a platform-specific
way (eg. <em>foo</em> becomes <code class="file docutils literal notranslate"><span class="pre">libfoo.a</span></code> on Unix and <code class="file docutils literal notranslate"><span class="pre">foo.lib</span></code> on
DOS/Windows). However, they can include a directory component, which means the
linker will look in that specific directory rather than searching all the normal
locations.</p>
<p><em>library_dirs</em>, if supplied, should be a list of directories to search for
libraries that were specified as bare library names (ie. no directory
component). These are on top of the system default and those supplied to
<a class="reference internal" href="#distutils.ccompiler.CCompiler.add_library_dir" title="distutils.ccompiler.CCompiler.add_library_dir"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_library_dir()</span></code></a> and/or <a class="reference internal" href="#distutils.ccompiler.CCompiler.set_library_dirs" title="distutils.ccompiler.CCompiler.set_library_dirs"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_library_dirs()</span></code></a>. <em>runtime_library_dirs</em>
is a list of directories that will be embedded into the shared library and used
to search for other shared libraries that *it* depends on at run-time. (This
may only be relevant on Unix.)</p>
<p><em>export_symbols</em> is a list of symbols that the shared library will export.
(This appears to be relevant only on Windows.)</p>
<p><em>debug</em> is as for <a class="reference internal" href="../library/functions.html#compile" title="compile"><code class="xref py py-meth docutils literal notranslate"><span class="pre">compile()</span></code></a> and <a class="reference internal" href="#distutils.ccompiler.CCompiler.create_static_lib" title="distutils.ccompiler.CCompiler.create_static_lib"><code class="xref py py-meth docutils literal notranslate"><span class="pre">create_static_lib()</span></code></a>, with the
slight distinction that it actually matters on most platforms (as opposed to
<a class="reference internal" href="#distutils.ccompiler.CCompiler.create_static_lib" title="distutils.ccompiler.CCompiler.create_static_lib"><code class="xref py py-meth docutils literal notranslate"><span class="pre">create_static_lib()</span></code></a>, which includes a <em>debug</em> flag mostly for form’s
sake).</p>
<p><em>extra_preargs</em> and <em>extra_postargs</em> are as for <a class="reference internal" href="../library/functions.html#compile" title="compile"><code class="xref py py-meth docutils literal notranslate"><span class="pre">compile()</span></code></a> (except of
course that they supply command-line arguments for the particular linker being
used).</p>
<p><em>target_lang</em> is the target language for which the given objects are being
compiled. This allows specific linkage time treatment of certain languages.</p>
<p>Raises <code class="xref py py-exc docutils literal notranslate"><span class="pre">LinkError</span></code> on failure.</p>
</dd></dl>
<dl class="method">
<dt id="distutils.ccompiler.CCompiler.link_executable">
<code class="descname">link_executable</code><span class="sig-paren">(</span><em>objects</em>, <em>output_progname</em><span class="optional">[</span>, <em>output_dir=None</em>, <em>libraries=None</em>, <em>library_dirs=None</em>, <em>runtime_library_dirs=None</em>, <em>debug=0</em>, <em>extra_preargs=None</em>, <em>extra_postargs=None</em>, <em>target_lang=None</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.CCompiler.link_executable" title="Permalink to this definition">¶</a></dt>
<dd><p>Link an executable. <em>output_progname</em> is the name of the file executable, while
<em>objects</em> are a list of object filenames to link in. Other arguments are as for
the <a class="reference internal" href="#distutils.ccompiler.CCompiler.link" title="distutils.ccompiler.CCompiler.link"><code class="xref py py-meth docutils literal notranslate"><span class="pre">link()</span></code></a> method.</p>
</dd></dl>
<dl class="method">
<dt id="distutils.ccompiler.CCompiler.link_shared_lib">
<code class="descname">link_shared_lib</code><span class="sig-paren">(</span><em>objects</em>, <em>output_libname</em><span class="optional">[</span>, <em>output_dir=None</em>, <em>libraries=None</em>, <em>library_dirs=None</em>, <em>runtime_library_dirs=None</em>, <em>export_symbols=None</em>, <em>debug=0</em>, <em>extra_preargs=None</em>, <em>extra_postargs=None</em>, <em>build_temp=None</em>, <em>target_lang=None</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.CCompiler.link_shared_lib" title="Permalink to this definition">¶</a></dt>
<dd><p>Link a shared library. <em>output_libname</em> is the name of the output library,
while <em>objects</em> is a list of object filenames to link in. Other arguments are
as for the <a class="reference internal" href="#distutils.ccompiler.CCompiler.link" title="distutils.ccompiler.CCompiler.link"><code class="xref py py-meth docutils literal notranslate"><span class="pre">link()</span></code></a> method.</p>
</dd></dl>
<dl class="method">
<dt id="distutils.ccompiler.CCompiler.link_shared_object">
<code class="descname">link_shared_object</code><span class="sig-paren">(</span><em>objects</em>, <em>output_filename</em><span class="optional">[</span>, <em>output_dir=None</em>, <em>libraries=None</em>, <em>library_dirs=None</em>, <em>runtime_library_dirs=None</em>, <em>export_symbols=None</em>, <em>debug=0</em>, <em>extra_preargs=None</em>, <em>extra_postargs=None</em>, <em>build_temp=None</em>, <em>target_lang=None</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.CCompiler.link_shared_object" title="Permalink to this definition">¶</a></dt>
<dd><p>Link a shared object. <em>output_filename</em> is the name of the shared object that
will be created, while <em>objects</em> is a list of object filenames to link in.
Other arguments are as for the <a class="reference internal" href="#distutils.ccompiler.CCompiler.link" title="distutils.ccompiler.CCompiler.link"><code class="xref py py-meth docutils literal notranslate"><span class="pre">link()</span></code></a> method.</p>
</dd></dl>
<dl class="method">
<dt id="distutils.ccompiler.CCompiler.preprocess">
<code class="descname">preprocess</code><span class="sig-paren">(</span><em>source</em><span class="optional">[</span>, <em>output_file=None</em>, <em>macros=None</em>, <em>include_dirs=None</em>, <em>extra_preargs=None</em>, <em>extra_postargs=None</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.CCompiler.preprocess" title="Permalink to this definition">¶</a></dt>
<dd><p>Preprocess a single C/C++ source file, named in <em>source</em>. Output will be written
to file named <em>output_file</em>, or <em>stdout</em> if <em>output_file</em> not supplied.
<em>macros</em> is a list of macro definitions as for <a class="reference internal" href="../library/functions.html#compile" title="compile"><code class="xref py py-meth docutils literal notranslate"><span class="pre">compile()</span></code></a>, which will
augment the macros set with <a class="reference internal" href="#distutils.ccompiler.CCompiler.define_macro" title="distutils.ccompiler.CCompiler.define_macro"><code class="xref py py-meth docutils literal notranslate"><span class="pre">define_macro()</span></code></a> and <a class="reference internal" href="#distutils.ccompiler.CCompiler.undefine_macro" title="distutils.ccompiler.CCompiler.undefine_macro"><code class="xref py py-meth docutils literal notranslate"><span class="pre">undefine_macro()</span></code></a>.
<em>include_dirs</em> is a list of directory names that will be added to the default
list, in the same way as <a class="reference internal" href="#distutils.ccompiler.CCompiler.add_include_dir" title="distutils.ccompiler.CCompiler.add_include_dir"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_include_dir()</span></code></a>.</p>
<p>Raises <code class="xref py py-exc docutils literal notranslate"><span class="pre">PreprocessError</span></code> on failure.</p>
</dd></dl>
<p>The following utility methods are defined by the <a class="reference internal" href="#distutils.ccompiler.CCompiler" title="distutils.ccompiler.CCompiler"><code class="xref py py-class docutils literal notranslate"><span class="pre">CCompiler</span></code></a> class, for
use by the various concrete subclasses.</p>
<dl class="method">
<dt id="distutils.ccompiler.CCompiler.executable_filename">
<code class="descname">executable_filename</code><span class="sig-paren">(</span><em>basename</em><span class="optional">[</span>, <em>strip_dir=0</em>, <em>output_dir=''</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.CCompiler.executable_filename" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns the filename of the executable for the given <em>basename</em>. Typically for
non-Windows platforms this is the same as the basename, while Windows will get
a <code class="file docutils literal notranslate"><span class="pre">.exe</span></code> added.</p>
</dd></dl>
<dl class="method">
<dt id="distutils.ccompiler.CCompiler.library_filename">
<code class="descname">library_filename</code><span class="sig-paren">(</span><em>libname</em><span class="optional">[</span>, <em>lib_type='static'</em>, <em>strip_dir=0</em>, <em>output_dir=''</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.CCompiler.library_filename" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns the filename for the given library name on the current platform. On Unix
a library with <em>lib_type</em> of <code class="docutils literal notranslate"><span class="pre">'static'</span></code> will typically be of the form
<code class="file docutils literal notranslate"><span class="pre">liblibname.a</span></code>, while a <em>lib_type</em> of <code class="docutils literal notranslate"><span class="pre">'dynamic'</span></code> will be of the form
<code class="file docutils literal notranslate"><span class="pre">liblibname.so</span></code>.</p>
</dd></dl>
<dl class="method">
<dt id="distutils.ccompiler.CCompiler.object_filenames">
<code class="descname">object_filenames</code><span class="sig-paren">(</span><em>source_filenames</em><span class="optional">[</span>, <em>strip_dir=0</em>, <em>output_dir=''</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.CCompiler.object_filenames" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns the name of the object files for the given source files.
<em>source_filenames</em> should be a list of filenames.</p>
</dd></dl>
<dl class="method">
<dt id="distutils.ccompiler.CCompiler.shared_object_filename">
<code class="descname">shared_object_filename</code><span class="sig-paren">(</span><em>basename</em><span class="optional">[</span>, <em>strip_dir=0</em>, <em>output_dir=''</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.CCompiler.shared_object_filename" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns the name of a shared object file for the given file name <em>basename</em>.</p>
</dd></dl>
<dl class="method">
<dt id="distutils.ccompiler.CCompiler.execute">
<code class="descname">execute</code><span class="sig-paren">(</span><em>func</em>, <em>args</em><span class="optional">[</span>, <em>msg=None</em>, <em>level=1</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.CCompiler.execute" title="Permalink to this definition">¶</a></dt>
<dd><p>Invokes <a class="reference internal" href="#distutils.util.execute" title="distutils.util.execute"><code class="xref py py-func docutils literal notranslate"><span class="pre">distutils.util.execute()</span></code></a>. This method invokes a Python function
<em>func</em> with the given arguments <em>args</em>, after logging and taking into account
the <em>dry_run</em> flag.</p>
</dd></dl>
<dl class="method">
<dt id="distutils.ccompiler.CCompiler.spawn">
<code class="descname">spawn</code><span class="sig-paren">(</span><em>cmd</em><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.CCompiler.spawn" title="Permalink to this definition">¶</a></dt>
<dd><p>Invokes <code class="xref py py-func docutils literal notranslate"><span class="pre">distutils.util.spawn()</span></code>. This invokes an external process to run
the given command.</p>
</dd></dl>
<dl class="method">
<dt id="distutils.ccompiler.CCompiler.mkpath">
<code class="descname">mkpath</code><span class="sig-paren">(</span><em>name</em><span class="optional">[</span>, <em>mode=511</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.CCompiler.mkpath" title="Permalink to this definition">¶</a></dt>
<dd><p>Invokes <a class="reference internal" href="#distutils.dir_util.mkpath" title="distutils.dir_util.mkpath"><code class="xref py py-func docutils literal notranslate"><span class="pre">distutils.dir_util.mkpath()</span></code></a>. This creates a directory and any
missing ancestor directories.</p>
</dd></dl>
<dl class="method">
<dt id="distutils.ccompiler.CCompiler.move_file">
<code class="descname">move_file</code><span class="sig-paren">(</span><em>src</em>, <em>dst</em><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.CCompiler.move_file" title="Permalink to this definition">¶</a></dt>
<dd><p>Invokes <a class="reference internal" href="#distutils.file_util.move_file" title="distutils.file_util.move_file"><code class="xref py py-meth docutils literal notranslate"><span class="pre">distutils.file_util.move_file()</span></code></a>. Renames <em>src</em> to <em>dst</em>.</p>
</dd></dl>
<dl class="method">
<dt id="distutils.ccompiler.CCompiler.announce">
<code class="descname">announce</code><span class="sig-paren">(</span><em>msg</em><span class="optional">[</span>, <em>level=1</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.CCompiler.announce" title="Permalink to this definition">¶</a></dt>
<dd><p>Write a message using <code class="xref py py-func docutils literal notranslate"><span class="pre">distutils.log.debug()</span></code>.</p>
</dd></dl>
<dl class="method">
<dt id="distutils.ccompiler.CCompiler.warn">
<code class="descname">warn</code><span class="sig-paren">(</span><em>msg</em><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.CCompiler.warn" title="Permalink to this definition">¶</a></dt>
<dd><p>Write a warning message <em>msg</em> to standard error.</p>
</dd></dl>
<dl class="method">
<dt id="distutils.ccompiler.CCompiler.debug_print">
<code class="descname">debug_print</code><span class="sig-paren">(</span><em>msg</em><span class="sig-paren">)</span><a class="headerlink" href="#distutils.ccompiler.CCompiler.debug_print" title="Permalink to this definition">¶</a></dt>
<dd><p>If the <em>debug</em> flag is set on this <a class="reference internal" href="#distutils.ccompiler.CCompiler" title="distutils.ccompiler.CCompiler"><code class="xref py py-class docutils literal notranslate"><span class="pre">CCompiler</span></code></a> instance, print <em>msg</em> to
standard output, otherwise do nothing.</p>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="module-distutils.unixccompiler">
<span id="distutils-unixccompiler-unix-c-compiler"></span><h2>10.3. <a class="reference internal" href="#module-distutils.unixccompiler" title="distutils.unixccompiler: UNIX C Compiler"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.unixccompiler</span></code></a> — Unix C Compiler<a class="headerlink" href="#module-distutils.unixccompiler" title="Permalink to this headline">¶</a></h2>
<p>This module provides the <code class="xref py py-class docutils literal notranslate"><span class="pre">UnixCCompiler</span></code> class, a subclass of
<code class="xref py py-class docutils literal notranslate"><span class="pre">CCompiler</span></code> that handles the typical Unix-style command-line C compiler:</p>
<ul class="simple">
<li>macros defined with <code class="xref std std-option docutils literal notranslate"><span class="pre">-Dname[=value]</span></code></li>
<li>macros undefined with <code class="xref std std-option docutils literal notranslate"><span class="pre">-Uname</span></code></li>
<li>include search directories specified with <code class="xref std std-option docutils literal notranslate"><span class="pre">-Idir</span></code></li>
<li>libraries specified with <code class="xref std std-option docutils literal notranslate"><span class="pre">-llib</span></code></li>
<li>library search directories specified with <code class="xref std std-option docutils literal notranslate"><span class="pre">-Ldir</span></code></li>
<li>compile handled by <strong class="program">cc</strong> (or similar) executable with <code class="xref std std-option docutils literal notranslate"><span class="pre">-c</span></code>
option: compiles <code class="file docutils literal notranslate"><span class="pre">.c</span></code> to <code class="file docutils literal notranslate"><span class="pre">.o</span></code></li>
<li>link static library handled by <strong class="program">ar</strong> command (possibly with
<strong class="program">ranlib</strong>)</li>
<li>link shared library handled by <strong class="program">cc</strong> <code class="xref std std-option docutils literal notranslate"><span class="pre">-shared</span></code></li>
</ul>
</div>
<div class="section" id="module-distutils.msvccompiler">
<span id="distutils-msvccompiler-microsoft-compiler"></span><h2>10.4. <a class="reference internal" href="#module-distutils.msvccompiler" title="distutils.msvccompiler: Microsoft Compiler"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.msvccompiler</span></code></a> — Microsoft Compiler<a class="headerlink" href="#module-distutils.msvccompiler" title="Permalink to this headline">¶</a></h2>
<p>This module provides <code class="xref py py-class docutils literal notranslate"><span class="pre">MSVCCompiler</span></code>, an implementation of the abstract
<code class="xref py py-class docutils literal notranslate"><span class="pre">CCompiler</span></code> class for Microsoft Visual Studio. Typically, extension
modules need to be compiled with the same compiler that was used to compile
Python. For Python 2.3 and earlier, the compiler was Visual Studio 6. For Python
2.4 and 2.5, the compiler is Visual Studio .NET 2003. The AMD64 and Itanium
binaries are created using the Platform SDK.</p>
<p><code class="xref py py-class docutils literal notranslate"><span class="pre">MSVCCompiler</span></code> will normally choose the right compiler, linker etc. on
its own. To override this choice, the environment variables <em>DISTUTILS_USE_SDK</em>
and <em>MSSdk</em> must be both set. <em>MSSdk</em> indicates that the current environment has
been setup by the SDK’s <code class="docutils literal notranslate"><span class="pre">SetEnv.Cmd</span></code> script, or that the environment variables
had been registered when the SDK was installed; <em>DISTUTILS_USE_SDK</em> indicates
that the distutils user has made an explicit choice to override the compiler
selection by <code class="xref py py-class docutils literal notranslate"><span class="pre">MSVCCompiler</span></code>.</p>
</div>
<div class="section" id="module-distutils.bcppcompiler">
<span id="distutils-bcppcompiler-borland-compiler"></span><h2>10.5. <a class="reference internal" href="#module-distutils.bcppcompiler" title="distutils.bcppcompiler"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.bcppcompiler</span></code></a> — Borland Compiler<a class="headerlink" href="#module-distutils.bcppcompiler" title="Permalink to this headline">¶</a></h2>
<p>This module provides <code class="xref py py-class docutils literal notranslate"><span class="pre">BorlandCCompiler</span></code>, a subclass of the abstract
<code class="xref py py-class docutils literal notranslate"><span class="pre">CCompiler</span></code> class for the Borland C++ compiler.</p>
</div>
<div class="section" id="module-distutils.cygwinccompiler">
<span id="distutils-cygwincompiler-cygwin-compiler"></span><h2>10.6. <code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.cygwincompiler</span></code> — Cygwin Compiler<a class="headerlink" href="#module-distutils.cygwinccompiler" title="Permalink to this headline">¶</a></h2>
<p>This module provides the <code class="xref py py-class docutils literal notranslate"><span class="pre">CygwinCCompiler</span></code> class, a subclass of
<code class="xref py py-class docutils literal notranslate"><span class="pre">UnixCCompiler</span></code> that handles the Cygwin port of the GNU C compiler to
Windows. It also contains the Mingw32CCompiler class which handles the mingw32
port of GCC (same as cygwin in no-cygwin mode).</p>
</div>
<div class="section" id="module-distutils.emxccompiler">
<span id="distutils-emxccompiler-os-2-emx-compiler"></span><h2>10.7. <a class="reference internal" href="#module-distutils.emxccompiler" title="distutils.emxccompiler: OS/2 EMX Compiler support"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.emxccompiler</span></code></a> — OS/2 EMX Compiler<a class="headerlink" href="#module-distutils.emxccompiler" title="Permalink to this headline">¶</a></h2>
<p>This module provides the EMXCCompiler class, a subclass of
<code class="xref py py-class docutils literal notranslate"><span class="pre">UnixCCompiler</span></code> that handles the EMX port of the GNU C compiler to OS/2.</p>
</div>
<div class="section" id="module-distutils.archive_util">
<span id="distutils-archive-util-archiving-utilities"></span><h2>10.8. <a class="reference internal" href="#module-distutils.archive_util" title="distutils.archive_util: Utility functions for creating archive files (tarballs, zip files, ...)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.archive_util</span></code></a> — Archiving utilities<a class="headerlink" href="#module-distutils.archive_util" title="Permalink to this headline">¶</a></h2>
<p>This module provides a few functions for creating archive files, such as
tarballs or zipfiles.</p>
<dl class="function">
<dt id="distutils.archive_util.make_archive">
<code class="descclassname">distutils.archive_util.</code><code class="descname">make_archive</code><span class="sig-paren">(</span><em>base_name</em>, <em>format</em><span class="optional">[</span>, <em>root_dir=None</em>, <em>base_dir=None</em>, <em>verbose=0</em>, <em>dry_run=0</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.archive_util.make_archive" title="Permalink to this definition">¶</a></dt>
<dd><p>Create an archive file (eg. <code class="docutils literal notranslate"><span class="pre">zip</span></code> or <code class="docutils literal notranslate"><span class="pre">tar</span></code>). <em>base_name</em> is the name of
the file to create, minus any format-specific extension; <em>format</em> is the
archive format: one of <code class="docutils literal notranslate"><span class="pre">zip</span></code>, <code class="docutils literal notranslate"><span class="pre">tar</span></code>, <code class="docutils literal notranslate"><span class="pre">ztar</span></code>, or <code class="docutils literal notranslate"><span class="pre">gztar</span></code>. <em>root_dir</em> is
a directory that will be the root directory of the archive; ie. we typically
<code class="docutils literal notranslate"><span class="pre">chdir</span></code> into <em>root_dir</em> before creating the archive. <em>base_dir</em> is the
directory where we start archiving from; ie. <em>base_dir</em> will be the common
prefix of all files and directories in the archive. <em>root_dir</em> and <em>base_dir</em>
both default to the current directory. Returns the name of the archive file.</p>
</dd></dl>
<dl class="function">
<dt id="distutils.archive_util.make_tarball">
<code class="descclassname">distutils.archive_util.</code><code class="descname">make_tarball</code><span class="sig-paren">(</span><em>base_name</em>, <em>base_dir</em><span class="optional">[</span>, <em>compress='gzip'</em>, <em>verbose=0</em>, <em>dry_run=0</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.archive_util.make_tarball" title="Permalink to this definition">¶</a></dt>
<dd><p>‘Create an (optional compressed) archive as a tar file from all files in and
under <em>base_dir</em>. <em>compress</em> must be <code class="docutils literal notranslate"><span class="pre">'gzip'</span></code> (the default), <code class="docutils literal notranslate"><span class="pre">'compress'</span></code>,
<code class="docutils literal notranslate"><span class="pre">'bzip2'</span></code>, or <code class="docutils literal notranslate"><span class="pre">None</span></code>. Both <strong class="program">tar</strong> and the compression utility named
by <em>compress</em> must be on the default program search path, so this is probably
Unix-specific. The output tar file will be named <code class="file docutils literal notranslate"><span class="pre">base_dir.tar</span></code>,
possibly plus the appropriate compression extension (<code class="file docutils literal notranslate"><span class="pre">.gz</span></code>, <code class="file docutils literal notranslate"><span class="pre">.bz2</span></code>
or <code class="file docutils literal notranslate"><span class="pre">.Z</span></code>). Return the output filename.</p>
</dd></dl>
<dl class="function">
<dt id="distutils.archive_util.make_zipfile">
<code class="descclassname">distutils.archive_util.</code><code class="descname">make_zipfile</code><span class="sig-paren">(</span><em>base_name</em>, <em>base_dir</em><span class="optional">[</span>, <em>verbose=0</em>, <em>dry_run=0</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.archive_util.make_zipfile" title="Permalink to this definition">¶</a></dt>
<dd><p>Create a zip file from all files in and under <em>base_dir</em>. The output zip file
will be named <em>base_name</em> + <code class="file docutils literal notranslate"><span class="pre">.zip</span></code>. Uses either the <a class="reference internal" href="../library/zipfile.html#module-zipfile" title="zipfile: Read and write ZIP-format archive files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">zipfile</span></code></a> Python
module (if available) or the InfoZIP <code class="file docutils literal notranslate"><span class="pre">zip</span></code> utility (if installed and
found on the default search path). If neither tool is available, raises
<code class="xref py py-exc docutils literal notranslate"><span class="pre">DistutilsExecError</span></code>. Returns the name of the output zip file.</p>
</dd></dl>
</div>
<div class="section" id="module-distutils.dep_util">
<span id="distutils-dep-util-dependency-checking"></span><h2>10.9. <a class="reference internal" href="#module-distutils.dep_util" title="distutils.dep_util: Utility functions for simple dependency checking"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.dep_util</span></code></a> — Dependency checking<a class="headerlink" href="#module-distutils.dep_util" title="Permalink to this headline">¶</a></h2>
<p>This module provides functions for performing simple, timestamp-based
dependency of files and groups of files; also, functions based entirely on such
timestamp dependency analysis.</p>
<dl class="function">
<dt id="distutils.dep_util.newer">
<code class="descclassname">distutils.dep_util.</code><code class="descname">newer</code><span class="sig-paren">(</span><em>source</em>, <em>target</em><span class="sig-paren">)</span><a class="headerlink" href="#distutils.dep_util.newer" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if <em>source</em> exists and is more recently modified than <em>target</em>, or
if <em>source</em> exists and <em>target</em> doesn’t. Return false if both exist and <em>target</em>
is the same age or newer than <em>source</em>. Raise <code class="xref py py-exc docutils literal notranslate"><span class="pre">DistutilsFileError</span></code> if
<em>source</em> does not exist.</p>
</dd></dl>
<dl class="function">
<dt id="distutils.dep_util.newer_pairwise">
<code class="descclassname">distutils.dep_util.</code><code class="descname">newer_pairwise</code><span class="sig-paren">(</span><em>sources</em>, <em>targets</em><span class="sig-paren">)</span><a class="headerlink" href="#distutils.dep_util.newer_pairwise" title="Permalink to this definition">¶</a></dt>
<dd><p>Walk two filename lists in parallel, testing if each source is newer than its
corresponding target. Return a pair of lists (<em>sources</em>, <em>targets</em>) where
source is newer than target, according to the semantics of <a class="reference internal" href="#distutils.dep_util.newer" title="distutils.dep_util.newer"><code class="xref py py-func docutils literal notranslate"><span class="pre">newer()</span></code></a>.</p>
</dd></dl>
<dl class="function">
<dt id="distutils.dep_util.newer_group">
<code class="descclassname">distutils.dep_util.</code><code class="descname">newer_group</code><span class="sig-paren">(</span><em>sources</em>, <em>target</em><span class="optional">[</span>, <em>missing='error'</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.dep_util.newer_group" title="Permalink to this definition">¶</a></dt>
<dd><p>Return true if <em>target</em> is out-of-date with respect to any file listed in
<em>sources</em>. In other words, if <em>target</em> exists and is newer than every file in
<em>sources</em>, return false; otherwise return true. <em>missing</em> controls what we do
when a source file is missing; the default (<code class="docutils literal notranslate"><span class="pre">'error'</span></code>) is to blow up with an
<a class="reference internal" href="../library/exceptions.html#exceptions.OSError" title="exceptions.OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> from inside <a class="reference internal" href="../library/os.html#os.stat" title="os.stat"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.stat()</span></code></a>; if it is <code class="docutils literal notranslate"><span class="pre">'ignore'</span></code>, we silently
drop any missing source files; if it is <code class="docutils literal notranslate"><span class="pre">'newer'</span></code>, any missing source files
make us assume that <em>target</em> is out-of-date (this is handy in “dry-run” mode:
it’ll make you pretend to carry out commands that wouldn’t work because inputs
are missing, but that doesn’t matter because you’re not actually going to run
the commands).</p>
</dd></dl>
</div>
<div class="section" id="module-distutils.dir_util">
<span id="distutils-dir-util-directory-tree-operations"></span><h2>10.10. <a class="reference internal" href="#module-distutils.dir_util" title="distutils.dir_util: Utility functions for operating on directories and directory trees"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.dir_util</span></code></a> — Directory tree operations<a class="headerlink" href="#module-distutils.dir_util" title="Permalink to this headline">¶</a></h2>
<p>This module provides functions for operating on directories and trees of
directories.</p>
<dl class="function">
<dt id="distutils.dir_util.mkpath">
<code class="descclassname">distutils.dir_util.</code><code class="descname">mkpath</code><span class="sig-paren">(</span><em>name</em><span class="optional">[</span>, <em>mode=0777</em>, <em>verbose=0</em>, <em>dry_run=0</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.dir_util.mkpath" title="Permalink to this definition">¶</a></dt>
<dd><p>Create a directory and any missing ancestor directories. If the directory
already exists (or if <em>name</em> is the empty string, which means the current
directory, which of course exists), then do nothing. Raise
<code class="xref py py-exc docutils literal notranslate"><span class="pre">DistutilsFileError</span></code> if unable to create some directory along the way (eg.
some sub-path exists, but is a file rather than a directory). If <em>verbose</em> is
true, print a one-line summary of each mkdir to stdout. Return the list of
directories actually created.</p>
</dd></dl>
<dl class="function">
<dt id="distutils.dir_util.create_tree">
<code class="descclassname">distutils.dir_util.</code><code class="descname">create_tree</code><span class="sig-paren">(</span><em>base_dir</em>, <em>files</em><span class="optional">[</span>, <em>mode=0777</em>, <em>verbose=0</em>, <em>dry_run=0</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.dir_util.create_tree" title="Permalink to this definition">¶</a></dt>
<dd><p>Create all the empty directories under <em>base_dir</em> needed to put <em>files</em> there.
<em>base_dir</em> is just the name of a directory which doesn’t necessarily exist
yet; <em>files</em> is a list of filenames to be interpreted relative to <em>base_dir</em>.
<em>base_dir</em> + the directory portion of every file in <em>files</em> will be created if
it doesn’t already exist. <em>mode</em>, <em>verbose</em> and <em>dry_run</em> flags are as for
<a class="reference internal" href="#distutils.dir_util.mkpath" title="distutils.dir_util.mkpath"><code class="xref py py-func docutils literal notranslate"><span class="pre">mkpath()</span></code></a>.</p>
</dd></dl>
<dl class="function">
<dt id="distutils.dir_util.copy_tree">
<code class="descclassname">distutils.dir_util.</code><code class="descname">copy_tree</code><span class="sig-paren">(</span><em>src</em>, <em>dst</em><span class="optional">[</span>, <em>preserve_mode=1</em>, <em>preserve_times=1</em>, <em>preserve_symlinks=0</em>, <em>update=0</em>, <em>verbose=0</em>, <em>dry_run=0</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.dir_util.copy_tree" title="Permalink to this definition">¶</a></dt>
<dd><p>Copy an entire directory tree <em>src</em> to a new location <em>dst</em>. Both <em>src</em> and
<em>dst</em> must be directory names. If <em>src</em> is not a directory, raise
<code class="xref py py-exc docutils literal notranslate"><span class="pre">DistutilsFileError</span></code>. If <em>dst</em> does not exist, it is created with
<a class="reference internal" href="#distutils.dir_util.mkpath" title="distutils.dir_util.mkpath"><code class="xref py py-func docutils literal notranslate"><span class="pre">mkpath()</span></code></a>. The end result of the copy is that every file in <em>src</em> is
copied to <em>dst</em>, and directories under <em>src</em> are recursively copied to <em>dst</em>.
Return the list of files that were copied or might have been copied, using their
output name. The return value is unaffected by <em>update</em> or <em>dry_run</em>: it is
simply the list of all files under <em>src</em>, with the names changed to be under
<em>dst</em>.</p>
<p><em>preserve_mode</em> and <em>preserve_times</em> are the same as for
<a class="reference internal" href="#distutils.file_util.copy_file" title="distutils.file_util.copy_file"><code class="xref py py-func docutils literal notranslate"><span class="pre">distutils.file_util.copy_file()</span></code></a>; note that they only apply to
regular files, not to
directories. If <em>preserve_symlinks</em> is true, symlinks will be copied as
symlinks (on platforms that support them!); otherwise (the default), the
destination of the symlink will be copied. <em>update</em> and <em>verbose</em> are the same
as for <code class="xref py py-func docutils literal notranslate"><span class="pre">copy_file()</span></code>.</p>
<p>Files in <em>src</em> that begin with <code class="file docutils literal notranslate"><span class="pre">.nfs</span></code> are skipped (more information on
these files is available in answer D2 of the <a class="reference external" href="http://nfs.sourceforge.net/#section_d">NFS FAQ page</a>.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.7.4: </span>NFS files are ignored.</p>
</div>
</dd></dl>
<dl class="function">
<dt id="distutils.dir_util.remove_tree">
<code class="descclassname">distutils.dir_util.</code><code class="descname">remove_tree</code><span class="sig-paren">(</span><em>directory</em><span class="optional">[</span>, <em>verbose=0</em>, <em>dry_run=0</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.dir_util.remove_tree" title="Permalink to this definition">¶</a></dt>
<dd><p>Recursively remove <em>directory</em> and all files and directories underneath it. Any
errors are ignored (apart from being reported to <code class="docutils literal notranslate"><span class="pre">sys.stdout</span></code> if <em>verbose</em> is
true).</p>
</dd></dl>
</div>
<div class="section" id="module-distutils.file_util">
<span id="distutils-file-util-single-file-operations"></span><h2>10.11. <a class="reference internal" href="#module-distutils.file_util" title="distutils.file_util: Utility functions for operating on single files"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.file_util</span></code></a> — Single file operations<a class="headerlink" href="#module-distutils.file_util" title="Permalink to this headline">¶</a></h2>
<p>This module contains some utility functions for operating on individual files.</p>
<dl class="function">
<dt id="distutils.file_util.copy_file">
<code class="descclassname">distutils.file_util.</code><code class="descname">copy_file</code><span class="sig-paren">(</span><em>src</em>, <em>dst</em><span class="optional">[</span>, <em>preserve_mode=1</em>, <em>preserve_times=1</em>, <em>update=0</em>, <em>link=None</em>, <em>verbose=0</em>, <em>dry_run=0</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.file_util.copy_file" title="Permalink to this definition">¶</a></dt>
<dd><p>Copy file <em>src</em> to <em>dst</em>. If <em>dst</em> is a directory, then <em>src</em> is copied there
with the same name; otherwise, it must be a filename. (If the file exists, it
will be ruthlessly clobbered.) If <em>preserve_mode</em> is true (the default), the
file’s mode (type and permission bits, or whatever is analogous on the
current platform) is copied. If <em>preserve_times</em> is true (the default), the
last-modified and last-access times are copied as well. If <em>update</em> is true,
<em>src</em> will only be copied if <em>dst</em> does not exist, or if <em>dst</em> does exist but
is older than <em>src</em>.</p>
<p><em>link</em> allows you to make hard links (using <a class="reference internal" href="../library/os.html#os.link" title="os.link"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.link()</span></code></a>) or symbolic links
(using <a class="reference internal" href="../library/os.html#os.symlink" title="os.symlink"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.symlink()</span></code></a>) instead of copying: set it to <code class="docutils literal notranslate"><span class="pre">'hard'</span></code> or
<code class="docutils literal notranslate"><span class="pre">'sym'</span></code>; if it is <code class="docutils literal notranslate"><span class="pre">None</span></code> (the default), files are copied. Don’t set <em>link</em>
on systems that don’t support it: <a class="reference internal" href="#distutils.file_util.copy_file" title="distutils.file_util.copy_file"><code class="xref py py-func docutils literal notranslate"><span class="pre">copy_file()</span></code></a> doesn’t check if hard or
symbolic linking is available. It uses <code class="xref py py-func docutils literal notranslate"><span class="pre">_copy_file_contents()</span></code> to copy file
contents.</p>
<p>Return a tuple <code class="docutils literal notranslate"><span class="pre">(dest_name,</span> <span class="pre">copied)</span></code>: <em>dest_name</em> is the actual name of the
output file, and <em>copied</em> is true if the file was copied (or would have been
copied, if <em>dry_run</em> true).</p>
</dd></dl>
<dl class="function">
<dt id="distutils.file_util.move_file">
<code class="descclassname">distutils.file_util.</code><code class="descname">move_file</code><span class="sig-paren">(</span><em>src</em>, <em>dst</em><span class="optional">[</span>, <em>verbose</em>, <em>dry_run</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.file_util.move_file" title="Permalink to this definition">¶</a></dt>
<dd><p>Move file <em>src</em> to <em>dst</em>. If <em>dst</em> is a directory, the file will be moved into
it with the same name; otherwise, <em>src</em> is just renamed to <em>dst</em>. Returns the
new full name of the file.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Handles cross-device moves on Unix using <a class="reference internal" href="#distutils.file_util.copy_file" title="distutils.file_util.copy_file"><code class="xref py py-func docutils literal notranslate"><span class="pre">copy_file()</span></code></a>. What about
other systems?</p>
</div>
</dd></dl>
<dl class="function">
<dt id="distutils.file_util.write_file">
<code class="descclassname">distutils.file_util.</code><code class="descname">write_file</code><span class="sig-paren">(</span><em>filename</em>, <em>contents</em><span class="sig-paren">)</span><a class="headerlink" href="#distutils.file_util.write_file" title="Permalink to this definition">¶</a></dt>
<dd><p>Create a file called <em>filename</em> and write <em>contents</em> (a sequence of strings
without line terminators) to it.</p>
</dd></dl>
</div>
<div class="section" id="module-distutils.util">
<span id="distutils-util-miscellaneous-other-utility-functions"></span><h2>10.12. <a class="reference internal" href="#module-distutils.util" title="distutils.util: Miscellaneous other utility functions"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.util</span></code></a> — Miscellaneous other utility functions<a class="headerlink" href="#module-distutils.util" title="Permalink to this headline">¶</a></h2>
<p>This module contains other assorted bits and pieces that don’t fit into any
other utility module.</p>
<dl class="function">
<dt id="distutils.util.get_platform">
<code class="descclassname">distutils.util.</code><code class="descname">get_platform</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.util.get_platform" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a string that identifies the current platform. This is used mainly to
distinguish platform-specific build directories and platform-specific built
distributions. Typically includes the OS name and version and the architecture
(as supplied by ‘os.uname()’), although the exact information included depends
on the OS; eg. for IRIX the architecture isn’t particularly important (IRIX only
runs on SGI hardware), but for Linux the kernel version isn’t particularly
important.</p>
<p>Examples of returned values:</p>
<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">linux-i586</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">linux-alpha</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">solaris-2.6-sun4u</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">irix-5.3</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">irix64-6.2</span></code></li>
</ul>
<p>For non-POSIX platforms, currently just returns <code class="docutils literal notranslate"><span class="pre">sys.platform</span></code>.</p>
<p>For Mac OS X systems the OS version reflects the minimal version on which
binaries will run (that is, the value of <code class="docutils literal notranslate"><span class="pre">MACOSX_DEPLOYMENT_TARGET</span></code>
during the build of Python), not the OS version of the current system.</p>
<p>For universal binary builds on Mac OS X the architecture value reflects
the universal binary status instead of the architecture of the current
processor. For 32-bit universal binaries the architecture is <code class="docutils literal notranslate"><span class="pre">fat</span></code>,
for 64-bit universal binaries the architecture is <code class="docutils literal notranslate"><span class="pre">fat64</span></code>, and
for 4-way universal binaries the architecture is <code class="docutils literal notranslate"><span class="pre">universal</span></code>. Starting
from Python 2.7 and Python 3.2 the architecture <code class="docutils literal notranslate"><span class="pre">fat3</span></code> is used for
a 3-way universal build (ppc, i386, x86_64) and <code class="docutils literal notranslate"><span class="pre">intel</span></code> is used for
a universal build with the i386 and x86_64 architectures</p>
<p>Examples of returned values on Mac OS X:</p>
<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">macosx-10.3-ppc</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">macosx-10.3-fat</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">macosx-10.5-universal</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">macosx-10.6-intel</span></code></li>
</ul>
</dd></dl>
<dl class="function">
<dt id="distutils.util.convert_path">
<code class="descclassname">distutils.util.</code><code class="descname">convert_path</code><span class="sig-paren">(</span><em>pathname</em><span class="sig-paren">)</span><a class="headerlink" href="#distutils.util.convert_path" title="Permalink to this definition">¶</a></dt>
<dd><p>Return ‘pathname’ as a name that will work on the native filesystem, i.e. split
it on ‘/’ and put it back together again using the current directory separator.
Needed because filenames in the setup script are always supplied in Unix style,
and have to be converted to the local convention before we can actually use them
in the filesystem. Raises <a class="reference internal" href="../library/exceptions.html#exceptions.ValueError" title="exceptions.ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> on non-Unix-ish systems if
<em>pathname</em> either starts or ends with a slash.</p>
</dd></dl>
<dl class="function">
<dt id="distutils.util.change_root">
<code class="descclassname">distutils.util.</code><code class="descname">change_root</code><span class="sig-paren">(</span><em>new_root</em>, <em>pathname</em><span class="sig-paren">)</span><a class="headerlink" href="#distutils.util.change_root" title="Permalink to this definition">¶</a></dt>
<dd><p>Return <em>pathname</em> with <em>new_root</em> prepended. If <em>pathname</em> is relative, this is
equivalent to <code class="docutils literal notranslate"><span class="pre">os.path.join(new_root,pathname)</span></code> Otherwise, it requires making
<em>pathname</em> relative and then joining the two, which is tricky on DOS/Windows.</p>
</dd></dl>
<dl class="function">
<dt id="distutils.util.check_environ">
<code class="descclassname">distutils.util.</code><code class="descname">check_environ</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.util.check_environ" title="Permalink to this definition">¶</a></dt>
<dd><p>Ensure that ‘os.environ’ has all the environment variables we guarantee that
users can use in config files, command-line options, etc. Currently this
includes:</p>
<ul class="simple">
<li><span class="target" id="index-1"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">HOME</span></code> - user’s home directory (Unix only)</li>
<li><span class="target" id="index-2"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PLAT</span></code> - description of the current platform, including hardware and
OS (see <a class="reference internal" href="#distutils.util.get_platform" title="distutils.util.get_platform"><code class="xref py py-func docutils literal notranslate"><span class="pre">get_platform()</span></code></a>)</li>
</ul>
</dd></dl>
<dl class="function">
<dt id="distutils.util.subst_vars">
<code class="descclassname">distutils.util.</code><code class="descname">subst_vars</code><span class="sig-paren">(</span><em>s</em>, <em>local_vars</em><span class="sig-paren">)</span><a class="headerlink" href="#distutils.util.subst_vars" title="Permalink to this definition">¶</a></dt>
<dd><p>Perform shell/Perl-style variable substitution on <em>s</em>. Every occurrence of
<code class="docutils literal notranslate"><span class="pre">$</span></code> followed by a name is considered a variable, and variable is substituted
by the value found in the <em>local_vars</em> dictionary, or in <code class="docutils literal notranslate"><span class="pre">os.environ</span></code> if it’s
not in <em>local_vars</em>. <em>os.environ</em> is first checked/augmented to guarantee that
it contains certain values: see <a class="reference internal" href="#distutils.util.check_environ" title="distutils.util.check_environ"><code class="xref py py-func docutils literal notranslate"><span class="pre">check_environ()</span></code></a>. Raise <a class="reference internal" href="../library/exceptions.html#exceptions.ValueError" title="exceptions.ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a>
for any variables not found in either <em>local_vars</em> or <code class="docutils literal notranslate"><span class="pre">os.environ</span></code>.</p>
<p>Note that this is not a fully-fledged string interpolation function. A valid
<code class="docutils literal notranslate"><span class="pre">$variable</span></code> can consist only of upper and lower case letters, numbers and an
underscore. No { } or ( ) style quoting is available.</p>
</dd></dl>
<dl class="function">
<dt id="distutils.util.split_quoted">
<code class="descclassname">distutils.util.</code><code class="descname">split_quoted</code><span class="sig-paren">(</span><em>s</em><span class="sig-paren">)</span><a class="headerlink" href="#distutils.util.split_quoted" title="Permalink to this definition">¶</a></dt>
<dd><p>Split a string up according to Unix shell-like rules for quotes and backslashes.
In short: words are delimited by spaces, as long as those spaces are not escaped
by a backslash, or inside a quoted string. Single and double quotes are
equivalent, and the quote characters can be backslash-escaped. The backslash is
stripped from any two-character escape sequence, leaving only the escaped
character. The quote characters are stripped from any quoted string. Returns a
list of words.</p>
</dd></dl>
<dl class="function">
<dt id="distutils.util.execute">
<code class="descclassname">distutils.util.</code><code class="descname">execute</code><span class="sig-paren">(</span><em>func</em>, <em>args</em><span class="optional">[</span>, <em>msg=None</em>, <em>verbose=0</em>, <em>dry_run=0</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.util.execute" title="Permalink to this definition">¶</a></dt>
<dd><p>Perform some action that affects the outside world (for instance, writing to the
filesystem). Such actions are special because they are disabled by the
<em>dry_run</em> flag. This method takes care of all that bureaucracy for you; all
you have to do is supply the function to call and an argument tuple for it (to
embody the “external action” being performed), and an optional message to print.</p>
</dd></dl>
<dl class="function">
<dt id="distutils.util.strtobool">
<code class="descclassname">distutils.util.</code><code class="descname">strtobool</code><span class="sig-paren">(</span><em>val</em><span class="sig-paren">)</span><a class="headerlink" href="#distutils.util.strtobool" title="Permalink to this definition">¶</a></dt>
<dd><p>Convert a string representation of truth to true (1) or false (0).</p>
<p>True values are <code class="docutils literal notranslate"><span class="pre">y</span></code>, <code class="docutils literal notranslate"><span class="pre">yes</span></code>, <code class="docutils literal notranslate"><span class="pre">t</span></code>, <code class="docutils literal notranslate"><span class="pre">true</span></code>, <code class="docutils literal notranslate"><span class="pre">on</span></code> and <code class="docutils literal notranslate"><span class="pre">1</span></code>; false values
are <code class="docutils literal notranslate"><span class="pre">n</span></code>, <code class="docutils literal notranslate"><span class="pre">no</span></code>, <code class="docutils literal notranslate"><span class="pre">f</span></code>, <code class="docutils literal notranslate"><span class="pre">false</span></code>, <code class="docutils literal notranslate"><span class="pre">off</span></code> and <code class="docutils literal notranslate"><span class="pre">0</span></code>. Raises
<a class="reference internal" href="../library/exceptions.html#exceptions.ValueError" title="exceptions.ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> if <em>val</em> is anything else.</p>
</dd></dl>
<dl class="function">
<dt id="distutils.util.byte_compile">
<code class="descclassname">distutils.util.</code><code class="descname">byte_compile</code><span class="sig-paren">(</span><em>py_files</em><span class="optional">[</span>, <em>optimize=0</em>, <em>force=0</em>, <em>prefix=None</em>, <em>base_dir=None</em>, <em>verbose=1</em>, <em>dry_run=0</em>, <em>direct=None</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.util.byte_compile" title="Permalink to this definition">¶</a></dt>
<dd><p>Byte-compile a collection of Python source files to either <code class="file docutils literal notranslate"><span class="pre">.pyc</span></code> or
<code class="file docutils literal notranslate"><span class="pre">.pyo</span></code> files in the same directory. <em>py_files</em> is a list of files to
compile; any files that don’t end in <code class="file docutils literal notranslate"><span class="pre">.py</span></code> are silently skipped.
<em>optimize</em> must be one of the following:</p>
<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">0</span></code> - don’t optimize (generate <code class="file docutils literal notranslate"><span class="pre">.pyc</span></code>)</li>
<li><code class="docutils literal notranslate"><span class="pre">1</span></code> - normal optimization (like <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">-O</span></code>)</li>
<li><code class="docutils literal notranslate"><span class="pre">2</span></code> - extra optimization (like <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">-OO</span></code>)</li>
</ul>
<p>If <em>force</em> is true, all files are recompiled regardless of timestamps.</p>
<p>The source filename encoded in each <a class="reference internal" href="../glossary.html#term-bytecode"><span class="xref std std-term">bytecode</span></a> file defaults to the filenames
listed in <em>py_files</em>; you can modify these with <em>prefix</em> and <em>basedir</em>.
<em>prefix</em> is a string that will be stripped off of each source filename, and
<em>base_dir</em> is a directory name that will be prepended (after <em>prefix</em> is
stripped). You can supply either or both (or neither) of <em>prefix</em> and
<em>base_dir</em>, as you wish.</p>
<p>If <em>dry_run</em> is true, doesn’t actually do anything that would affect the
filesystem.</p>
<p>Byte-compilation is either done directly in this interpreter process with the
standard <a class="reference internal" href="../library/py_compile.html#module-py_compile" title="py_compile: Generate byte-code files from Python source files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">py_compile</span></code></a> module, or indirectly by writing a temporary script
and executing it. Normally, you should let <a class="reference internal" href="#distutils.util.byte_compile" title="distutils.util.byte_compile"><code class="xref py py-func docutils literal notranslate"><span class="pre">byte_compile()</span></code></a> figure out to
use direct compilation or not (see the source for details). The <em>direct</em> flag
is used by the script generated in indirect mode; unless you know what you’re
doing, leave it set to <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="distutils.util.rfc822_escape">
<code class="descclassname">distutils.util.</code><code class="descname">rfc822_escape</code><span class="sig-paren">(</span><em>header</em><span class="sig-paren">)</span><a class="headerlink" href="#distutils.util.rfc822_escape" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a version of <em>header</em> escaped for inclusion in an <span class="target" id="index-3"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc822.html"><strong>RFC 822</strong></a> header, by
ensuring there are 8 spaces space after each newline. Note that it does no other
modification of the string.</p>
</dd></dl>
</div>
<div class="section" id="module-distutils.dist">
<span id="distutils-dist-the-distribution-class"></span><h2>10.13. <a class="reference internal" href="#module-distutils.dist" title="distutils.dist: Provides the Distribution class, which represents the module distribution being built/installed/distributed"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.dist</span></code></a> — The Distribution class<a class="headerlink" href="#module-distutils.dist" title="Permalink to this headline">¶</a></h2>
<p>This module provides the <a class="reference internal" href="#distutils.core.Distribution" title="distutils.core.Distribution"><code class="xref py py-class docutils literal notranslate"><span class="pre">Distribution</span></code></a> class, which
represents the module distribution being built/installed/distributed.</p>
</div>
<div class="section" id="module-distutils.extension">
<span id="distutils-extension-the-extension-class"></span><h2>10.14. <a class="reference internal" href="#module-distutils.extension" title="distutils.extension: Provides the Extension class, used to describe C/C++ extension modules in setup scripts"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.extension</span></code></a> — The Extension class<a class="headerlink" href="#module-distutils.extension" title="Permalink to this headline">¶</a></h2>
<p>This module provides the <code class="xref py py-class docutils literal notranslate"><span class="pre">Extension</span></code> class, used to describe C/C++
extension modules in setup scripts.</p>
</div>
<div class="section" id="module-distutils.debug">
<span id="distutils-debug-distutils-debug-mode"></span><h2>10.15. <a class="reference internal" href="#module-distutils.debug" title="distutils.debug: Provides the debug flag for distutils"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.debug</span></code></a> — Distutils debug mode<a class="headerlink" href="#module-distutils.debug" title="Permalink to this headline">¶</a></h2>
<p>This module provides the DEBUG flag.</p>
</div>
<div class="section" id="module-distutils.errors">
<span id="distutils-errors-distutils-exceptions"></span><h2>10.16. <a class="reference internal" href="#module-distutils.errors" title="distutils.errors: Provides standard distutils exceptions"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.errors</span></code></a> — Distutils exceptions<a class="headerlink" href="#module-distutils.errors" title="Permalink to this headline">¶</a></h2>
<p>Provides exceptions used by the Distutils modules. Note that Distutils modules
may raise standard exceptions; in particular, SystemExit is usually raised for
errors that are obviously the end-user’s fault (eg. bad command-line arguments).</p>
<p>This module is safe to use in <code class="docutils literal notranslate"><span class="pre">from</span> <span class="pre">...</span> <span class="pre">import</span> <span class="pre">*</span></code> mode; it only exports
symbols whose names start with <code class="docutils literal notranslate"><span class="pre">Distutils</span></code> and end with <code class="docutils literal notranslate"><span class="pre">Error</span></code>.</p>
</div>
<div class="section" id="module-distutils.fancy_getopt">
<span id="distutils-fancy-getopt-wrapper-around-the-standard-getopt-module"></span><h2>10.17. <a class="reference internal" href="#module-distutils.fancy_getopt" title="distutils.fancy_getopt: Additional getopt functionality"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.fancy_getopt</span></code></a> — Wrapper around the standard getopt module<a class="headerlink" href="#module-distutils.fancy_getopt" title="Permalink to this headline">¶</a></h2>
<p>This module provides a wrapper around the standard <a class="reference internal" href="../library/getopt.html#module-getopt" title="getopt: Portable parser for command line options; support both short and long option names."><code class="xref py py-mod docutils literal notranslate"><span class="pre">getopt</span></code></a> module that
provides the following additional features:</p>
<ul class="simple">
<li>short and long options are tied together</li>
<li>options have help strings, so <a class="reference internal" href="#distutils.fancy_getopt.fancy_getopt" title="distutils.fancy_getopt.fancy_getopt"><code class="xref py py-func docutils literal notranslate"><span class="pre">fancy_getopt()</span></code></a> could potentially create a
complete usage summary</li>
<li>options set attributes of a passed-in object</li>
<li>boolean options can have “negative aliases” — eg. if <code class="xref std std-option docutils literal notranslate"><span class="pre">--quiet</span></code> is
the “negative alias” of <code class="xref std std-option docutils literal notranslate"><span class="pre">--verbose</span></code>, then <code class="xref std std-option docutils literal notranslate"><span class="pre">--quiet</span></code> on the
command line sets <em>verbose</em> to false.</li>
</ul>
<dl class="function">
<dt id="distutils.fancy_getopt.fancy_getopt">
<code class="descclassname">distutils.fancy_getopt.</code><code class="descname">fancy_getopt</code><span class="sig-paren">(</span><em>options</em>, <em>negative_opt</em>, <em>object</em>, <em>args</em><span class="sig-paren">)</span><a class="headerlink" href="#distutils.fancy_getopt.fancy_getopt" title="Permalink to this definition">¶</a></dt>
<dd><p>Wrapper function. <em>options</em> is a list of <code class="docutils literal notranslate"><span class="pre">(long_option,</span> <span class="pre">short_option,</span>
<span class="pre">help_string)</span></code> 3-tuples as described in the constructor for
<a class="reference internal" href="#distutils.fancy_getopt.FancyGetopt" title="distutils.fancy_getopt.FancyGetopt"><code class="xref py py-class docutils literal notranslate"><span class="pre">FancyGetopt</span></code></a>. <em>negative_opt</em> should be a dictionary mapping option names
to option names, both the key and value should be in the <em>options</em> list.
<em>object</em> is an object which will be used to store values (see the <a class="reference internal" href="../library/getopt.html#module-getopt" title="getopt: Portable parser for command line options; support both short and long option names."><code class="xref py py-meth docutils literal notranslate"><span class="pre">getopt()</span></code></a>
method of the <a class="reference internal" href="#distutils.fancy_getopt.FancyGetopt" title="distutils.fancy_getopt.FancyGetopt"><code class="xref py py-class docutils literal notranslate"><span class="pre">FancyGetopt</span></code></a> class). <em>args</em> is the argument list. Will use
<code class="docutils literal notranslate"><span class="pre">sys.argv[1:]</span></code> if you pass <code class="docutils literal notranslate"><span class="pre">None</span></code> as <em>args</em>.</p>
</dd></dl>
<dl class="function">
<dt id="distutils.fancy_getopt.wrap_text">
<code class="descclassname">distutils.fancy_getopt.</code><code class="descname">wrap_text</code><span class="sig-paren">(</span><em>text</em>, <em>width</em><span class="sig-paren">)</span><a class="headerlink" href="#distutils.fancy_getopt.wrap_text" title="Permalink to this definition">¶</a></dt>
<dd><p>Wraps <em>text</em> to less than <em>width</em> wide.</p>
</dd></dl>
<dl class="class">
<dt id="distutils.fancy_getopt.FancyGetopt">
<em class="property">class </em><code class="descclassname">distutils.fancy_getopt.</code><code class="descname">FancyGetopt</code><span class="sig-paren">(</span><span class="optional">[</span><em>option_table=None</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.fancy_getopt.FancyGetopt" title="Permalink to this definition">¶</a></dt>
<dd><p>The option_table is a list of 3-tuples: <code class="docutils literal notranslate"><span class="pre">(long_option,</span> <span class="pre">short_option,</span>
<span class="pre">help_string)</span></code></p>
<p>If an option takes an argument, its <em>long_option</em> should have <code class="docutils literal notranslate"><span class="pre">'='</span></code> appended;
<em>short_option</em> should just be a single character, no <code class="docutils literal notranslate"><span class="pre">':'</span></code> in any case.
<em>short_option</em> should be <code class="docutils literal notranslate"><span class="pre">None</span></code> if a <em>long_option</em> doesn’t have a
corresponding <em>short_option</em>. All option tuples must have long options.</p>
</dd></dl>
<p>The <a class="reference internal" href="#distutils.fancy_getopt.FancyGetopt" title="distutils.fancy_getopt.FancyGetopt"><code class="xref py py-class docutils literal notranslate"><span class="pre">FancyGetopt</span></code></a> class provides the following methods:</p>
<dl class="method">
<dt id="distutils.fancy_getopt.FancyGetopt.getopt">
<code class="descclassname">FancyGetopt.</code><code class="descname">getopt</code><span class="sig-paren">(</span><span class="optional">[</span><em>args=None</em>, <em>object=None</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.fancy_getopt.FancyGetopt.getopt" title="Permalink to this definition">¶</a></dt>
<dd><p>Parse command-line options in args. Store as attributes on <em>object</em>.</p>
<p>If <em>args</em> is <code class="docutils literal notranslate"><span class="pre">None</span></code> or not supplied, uses <code class="docutils literal notranslate"><span class="pre">sys.argv[1:]</span></code>. If <em>object</em> is
<code class="docutils literal notranslate"><span class="pre">None</span></code> or not supplied, creates a new <code class="xref py py-class docutils literal notranslate"><span class="pre">OptionDummy</span></code> instance, stores
option values there, and returns a tuple <code class="docutils literal notranslate"><span class="pre">(args,</span> <span class="pre">object)</span></code>. If <em>object</em> is
supplied, it is modified in place and <a class="reference internal" href="../library/getopt.html#module-getopt" title="getopt: Portable parser for command line options; support both short and long option names."><code class="xref py py-func docutils literal notranslate"><span class="pre">getopt()</span></code></a> just returns <em>args</em>; in
both cases, the returned <em>args</em> is a modified copy of the passed-in <em>args</em> list,
which is left untouched.</p>
</dd></dl>
<dl class="method">
<dt id="distutils.fancy_getopt.FancyGetopt.get_option_order">
<code class="descclassname">FancyGetopt.</code><code class="descname">get_option_order</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.fancy_getopt.FancyGetopt.get_option_order" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns the list of <code class="docutils literal notranslate"><span class="pre">(option,</span> <span class="pre">value)</span></code> tuples processed by the previous run of
<a class="reference internal" href="../library/getopt.html#module-getopt" title="getopt: Portable parser for command line options; support both short and long option names."><code class="xref py py-meth docutils literal notranslate"><span class="pre">getopt()</span></code></a> Raises <a class="reference internal" href="../library/exceptions.html#exceptions.RuntimeError" title="exceptions.RuntimeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">RuntimeError</span></code></a> if <a class="reference internal" href="../library/getopt.html#module-getopt" title="getopt: Portable parser for command line options; support both short and long option names."><code class="xref py py-meth docutils literal notranslate"><span class="pre">getopt()</span></code></a> hasn’t been called
yet.</p>
</dd></dl>
<dl class="method">
<dt id="distutils.fancy_getopt.FancyGetopt.generate_help">
<code class="descclassname">FancyGetopt.</code><code class="descname">generate_help</code><span class="sig-paren">(</span><span class="optional">[</span><em>header=None</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.fancy_getopt.FancyGetopt.generate_help" title="Permalink to this definition">¶</a></dt>
<dd><p>Generate help text (a list of strings, one per suggested line of output) from
the option table for this <a class="reference internal" href="#distutils.fancy_getopt.FancyGetopt" title="distutils.fancy_getopt.FancyGetopt"><code class="xref py py-class docutils literal notranslate"><span class="pre">FancyGetopt</span></code></a> object.</p>
<p>If supplied, prints the supplied <em>header</em> at the top of the help.</p>
</dd></dl>
</div>
<div class="section" id="module-distutils.filelist">
<span id="distutils-filelist-the-filelist-class"></span><h2>10.18. <a class="reference internal" href="#module-distutils.filelist" title="distutils.filelist: The FileList class, used for poking about the file system and building lists of files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.filelist</span></code></a> — The FileList class<a class="headerlink" href="#module-distutils.filelist" title="Permalink to this headline">¶</a></h2>
<p>This module provides the <code class="xref py py-class docutils literal notranslate"><span class="pre">FileList</span></code> class, used for poking about the
filesystem and building lists of files.</p>
</div>
<div class="section" id="module-distutils.log">
<span id="distutils-log-simple-pep-282-style-logging"></span><h2>10.19. <a class="reference internal" href="#module-distutils.log" title="distutils.log: A simple logging mechanism, 282-style"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.log</span></code></a> — Simple PEP 282-style logging<a class="headerlink" href="#module-distutils.log" title="Permalink to this headline">¶</a></h2>
</div>
<div class="section" id="module-distutils.spawn">
<span id="distutils-spawn-spawn-a-sub-process"></span><h2>10.20. <a class="reference internal" href="#module-distutils.spawn" title="distutils.spawn: Provides the spawn() function"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.spawn</span></code></a> — Spawn a sub-process<a class="headerlink" href="#module-distutils.spawn" title="Permalink to this headline">¶</a></h2>
<p>This module provides the <code class="xref py py-func docutils literal notranslate"><span class="pre">spawn()</span></code> function, a front-end to various
platform-specific functions for launching another program in a sub-process.
Also provides <code class="xref py py-func docutils literal notranslate"><span class="pre">find_executable()</span></code> to search the path for a given executable
name.</p>
</div>
<div class="section" id="module-distutils.sysconfig">
<span id="distutils-sysconfig-system-configuration-information"></span><h2>10.21. <a class="reference internal" href="#module-distutils.sysconfig" title="distutils.sysconfig: Low-level access to configuration information of the Python interpreter."><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.sysconfig</span></code></a> — System configuration information<a class="headerlink" href="#module-distutils.sysconfig" title="Permalink to this headline">¶</a></h2>
<p>The <a class="reference internal" href="#module-distutils.sysconfig" title="distutils.sysconfig: Low-level access to configuration information of the Python interpreter."><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.sysconfig</span></code></a> module provides access to Python’s low-level
configuration information. The specific configuration variables available
depend heavily on the platform and configuration. The specific variables depend
on the build process for the specific version of Python being run; the variables
are those found in the <code class="file docutils literal notranslate"><span class="pre">Makefile</span></code> and configuration header that are
installed with Python on Unix systems. The configuration header is called
<code class="file docutils literal notranslate"><span class="pre">pyconfig.h</span></code> for Python versions starting with 2.2, and <code class="file docutils literal notranslate"><span class="pre">config.h</span></code>
for earlier versions of Python.</p>
<p>Some additional functions are provided which perform some useful manipulations
for other parts of the <a class="reference internal" href="../library/distutils.html#module-distutils" title="distutils: Support for building and installing Python modules into an existing Python installation."><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils</span></code></a> package.</p>
<dl class="data">
<dt id="distutils.sysconfig.PREFIX">
<code class="descclassname">distutils.sysconfig.</code><code class="descname">PREFIX</code><a class="headerlink" href="#distutils.sysconfig.PREFIX" title="Permalink to this definition">¶</a></dt>
<dd><p>The result of <code class="docutils literal notranslate"><span class="pre">os.path.normpath(sys.prefix)</span></code>.</p>
</dd></dl>
<dl class="data">
<dt id="distutils.sysconfig.EXEC_PREFIX">
<code class="descclassname">distutils.sysconfig.</code><code class="descname">EXEC_PREFIX</code><a class="headerlink" href="#distutils.sysconfig.EXEC_PREFIX" title="Permalink to this definition">¶</a></dt>
<dd><p>The result of <code class="docutils literal notranslate"><span class="pre">os.path.normpath(sys.exec_prefix)</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="distutils.sysconfig.get_config_var">
<code class="descclassname">distutils.sysconfig.</code><code class="descname">get_config_var</code><span class="sig-paren">(</span><em>name</em><span class="sig-paren">)</span><a class="headerlink" href="#distutils.sysconfig.get_config_var" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the value of a single variable. This is equivalent to
<code class="docutils literal notranslate"><span class="pre">get_config_vars().get(name)</span></code>.</p>
</dd></dl>
<dl class="function">
<dt id="distutils.sysconfig.get_config_vars">
<code class="descclassname">distutils.sysconfig.</code><code class="descname">get_config_vars</code><span class="sig-paren">(</span><em>...</em><span class="sig-paren">)</span><a class="headerlink" href="#distutils.sysconfig.get_config_vars" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a set of variable definitions. If there are no arguments, this returns a
dictionary mapping names of configuration variables to values. If arguments are
provided, they should be strings, and the return value will be a sequence giving
the associated values. If a given name does not have a corresponding value,
<code class="docutils literal notranslate"><span class="pre">None</span></code> will be included for that variable.</p>
</dd></dl>
<dl class="function">
<dt id="distutils.sysconfig.get_config_h_filename">
<code class="descclassname">distutils.sysconfig.</code><code class="descname">get_config_h_filename</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.sysconfig.get_config_h_filename" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the full path name of the configuration header. For Unix, this will be
the header generated by the <strong class="program">configure</strong> script; for other platforms the
header will have been supplied directly by the Python source distribution. The
file is a platform-specific text file.</p>
</dd></dl>
<dl class="function">
<dt id="distutils.sysconfig.get_makefile_filename">
<code class="descclassname">distutils.sysconfig.</code><code class="descname">get_makefile_filename</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.sysconfig.get_makefile_filename" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the full path name of the <code class="file docutils literal notranslate"><span class="pre">Makefile</span></code> used to build Python. For
Unix, this will be a file generated by the <strong class="program">configure</strong> script; the
meaning for other platforms will vary. The file is a platform-specific text
file, if it exists. This function is only useful on POSIX platforms.</p>
</dd></dl>
<dl class="function">
<dt id="distutils.sysconfig.get_python_inc">
<code class="descclassname">distutils.sysconfig.</code><code class="descname">get_python_inc</code><span class="sig-paren">(</span><span class="optional">[</span><em>plat_specific</em><span class="optional">[</span>, <em>prefix</em><span class="optional">]</span><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.sysconfig.get_python_inc" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the directory for either the general or platform-dependent C include
files. If <em>plat_specific</em> is true, the platform-dependent include directory is
returned; if false or omitted, the platform-independent directory is returned.
If <em>prefix</em> is given, it is used as either the prefix instead of
<a class="reference internal" href="#distutils.sysconfig.PREFIX" title="distutils.sysconfig.PREFIX"><code class="xref py py-const docutils literal notranslate"><span class="pre">PREFIX</span></code></a>, or as the exec-prefix instead of <a class="reference internal" href="#distutils.sysconfig.EXEC_PREFIX" title="distutils.sysconfig.EXEC_PREFIX"><code class="xref py py-const docutils literal notranslate"><span class="pre">EXEC_PREFIX</span></code></a> if
<em>plat_specific</em> is true.</p>
</dd></dl>
<dl class="function">
<dt id="distutils.sysconfig.get_python_lib">
<code class="descclassname">distutils.sysconfig.</code><code class="descname">get_python_lib</code><span class="sig-paren">(</span><span class="optional">[</span><em>plat_specific</em><span class="optional">[</span>, <em>standard_lib</em><span class="optional">[</span>, <em>prefix</em><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.sysconfig.get_python_lib" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the directory for either the general or platform-dependent library
installation. If <em>plat_specific</em> is true, the platform-dependent include
directory is returned; if false or omitted, the platform-independent directory
is returned. If <em>prefix</em> is given, it is used as either the prefix instead of
<a class="reference internal" href="#distutils.sysconfig.PREFIX" title="distutils.sysconfig.PREFIX"><code class="xref py py-const docutils literal notranslate"><span class="pre">PREFIX</span></code></a>, or as the exec-prefix instead of <a class="reference internal" href="#distutils.sysconfig.EXEC_PREFIX" title="distutils.sysconfig.EXEC_PREFIX"><code class="xref py py-const docutils literal notranslate"><span class="pre">EXEC_PREFIX</span></code></a> if
<em>plat_specific</em> is true. If <em>standard_lib</em> is true, the directory for the
standard library is returned rather than the directory for the installation of
third-party extensions.</p>
</dd></dl>
<p>The following function is only intended for use within the <a class="reference internal" href="../library/distutils.html#module-distutils" title="distutils: Support for building and installing Python modules into an existing Python installation."><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils</span></code></a>
package.</p>
<dl class="function">
<dt id="distutils.sysconfig.customize_compiler">
<code class="descclassname">distutils.sysconfig.</code><code class="descname">customize_compiler</code><span class="sig-paren">(</span><em>compiler</em><span class="sig-paren">)</span><a class="headerlink" href="#distutils.sysconfig.customize_compiler" title="Permalink to this definition">¶</a></dt>
<dd><p>Do any platform-specific customization of a
<a class="reference internal" href="#distutils.ccompiler.CCompiler" title="distutils.ccompiler.CCompiler"><code class="xref py py-class docutils literal notranslate"><span class="pre">distutils.ccompiler.CCompiler</span></code></a> instance.</p>
<p>This function is only needed on Unix at this time, but should be called
consistently to support forward-compatibility. It inserts the information that
varies across Unix flavors and is stored in Python’s <code class="file docutils literal notranslate"><span class="pre">Makefile</span></code>. This
information includes the selected compiler, compiler and linker options, and the
extension used by the linker for shared objects.</p>
</dd></dl>
<p>This function is even more special-purpose, and should only be used from
Python’s own build procedures.</p>
<dl class="function">
<dt id="distutils.sysconfig.set_python_build">
<code class="descclassname">distutils.sysconfig.</code><code class="descname">set_python_build</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.sysconfig.set_python_build" title="Permalink to this definition">¶</a></dt>
<dd><p>Inform the <a class="reference internal" href="#module-distutils.sysconfig" title="distutils.sysconfig: Low-level access to configuration information of the Python interpreter."><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.sysconfig</span></code></a> module that it is being used as part of
the build process for Python. This changes a lot of relative locations for
files, allowing them to be located in the build area rather than in an installed
Python.</p>
</dd></dl>
</div>
<div class="section" id="module-distutils.text_file">
<span id="distutils-text-file-the-textfile-class"></span><h2>10.22. <a class="reference internal" href="#module-distutils.text_file" title="distutils.text_file: provides the TextFile class, a simple interface to text files"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.text_file</span></code></a> — The TextFile class<a class="headerlink" href="#module-distutils.text_file" title="Permalink to this headline">¶</a></h2>
<p>This module provides the <a class="reference internal" href="#distutils.text_file.TextFile" title="distutils.text_file.TextFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TextFile</span></code></a> class, which gives an interface to
text files that (optionally) takes care of stripping comments, ignoring blank
lines, and joining lines with backslashes.</p>
<dl class="class">
<dt id="distutils.text_file.TextFile">
<em class="property">class </em><code class="descclassname">distutils.text_file.</code><code class="descname">TextFile</code><span class="sig-paren">(</span><span class="optional">[</span><em>filename=None</em>, <em>file=None</em>, <em>**options</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.text_file.TextFile" title="Permalink to this definition">¶</a></dt>
<dd><p>This class provides a file-like object that takes care of all the things you
commonly want to do when processing a text file that has some line-by-line
syntax: strip comments (as long as <code class="docutils literal notranslate"><span class="pre">#</span></code> is your comment character), skip blank
lines, join adjacent lines by escaping the newline (ie. backslash at end of
line), strip leading and/or trailing whitespace. All of these are optional and
independently controllable.</p>
<p>The class provides a <a class="reference internal" href="#distutils.text_file.TextFile.warn" title="distutils.text_file.TextFile.warn"><code class="xref py py-meth docutils literal notranslate"><span class="pre">warn()</span></code></a> method so you can generate warning messages
that report physical line number, even if the logical line in question spans
multiple physical lines. Also provides <a class="reference internal" href="#distutils.text_file.TextFile.unreadline" title="distutils.text_file.TextFile.unreadline"><code class="xref py py-meth docutils literal notranslate"><span class="pre">unreadline()</span></code></a> for implementing
line-at-a-time lookahead.</p>
<p><a class="reference internal" href="#distutils.text_file.TextFile" title="distutils.text_file.TextFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TextFile</span></code></a> instances are create with either <em>filename</em>, <em>file</em>, or both.
<a class="reference internal" href="../library/exceptions.html#exceptions.RuntimeError" title="exceptions.RuntimeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">RuntimeError</span></code></a> is raised if both are <code class="docutils literal notranslate"><span class="pre">None</span></code>. <em>filename</em> should be a
string, and <em>file</em> a file object (or something that provides <a class="reference internal" href="../library/readline.html#module-readline" title="readline: GNU readline support for Python. (Unix)"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readline()</span></code></a>
and <a class="reference internal" href="#distutils.text_file.TextFile.close" title="distutils.text_file.TextFile.close"><code class="xref py py-meth docutils literal notranslate"><span class="pre">close()</span></code></a> methods). It is recommended that you supply at least
<em>filename</em>, so that <a class="reference internal" href="#distutils.text_file.TextFile" title="distutils.text_file.TextFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TextFile</span></code></a> can include it in warning messages. If
<em>file</em> is not supplied, <a class="reference internal" href="#distutils.text_file.TextFile" title="distutils.text_file.TextFile"><code class="xref py py-class docutils literal notranslate"><span class="pre">TextFile</span></code></a> creates its own using the
<a class="reference internal" href="../library/functions.html#open" title="open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a> built-in function.</p>
<p>The options are all boolean, and affect the values returned by <a class="reference internal" href="../library/readline.html#module-readline" title="readline: GNU readline support for Python. (Unix)"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readline()</span></code></a></p>
<table border="1" class="docutils">
<colgroup>
<col width="31%" />
<col width="54%" />
<col width="15%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">option name</th>
<th class="head">description</th>
<th class="head">default</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><em>strip_comments</em></td>
<td>strip from <code class="docutils literal notranslate"><span class="pre">'#'</span></code> to end-of-
line, as well as any
whitespace leading up to the
<code class="docutils literal notranslate"><span class="pre">'#'</span></code>—unless it is
escaped by a backslash</td>
<td>true</td>
</tr>
<tr class="row-odd"><td><em>lstrip_ws</em></td>
<td>strip leading whitespace from
each line before returning it</td>
<td>false</td>
</tr>
<tr class="row-even"><td><em>rstrip_ws</em></td>
<td>strip trailing whitespace
(including line terminator!)
from each line before
returning it.</td>
<td>true</td>
</tr>
<tr class="row-odd"><td><em>skip_blanks</em></td>
<td>skip lines that are empty
*after* stripping comments
and whitespace. (If both
lstrip_ws and rstrip_ws are
false, then some lines may
consist of solely whitespace:
these will *not* be skipped,
even if <em>skip_blanks</em> is
true.)</td>
<td>true</td>
</tr>
<tr class="row-even"><td><em>join_lines</em></td>
<td>if a backslash is the last
non-newline character on a
line after stripping comments
and whitespace, join the
following line to it to form
one logical line; if N
consecutive lines end with a
backslash, then N+1 physical
lines will be joined to form
one logical line.</td>
<td>false</td>
</tr>
<tr class="row-odd"><td><em>collapse_join</em></td>
<td>strip leading whitespace from
lines that are joined to their
predecessor; only matters if
<code class="docutils literal notranslate"><span class="pre">(join_lines</span> <span class="pre">and</span> <span class="pre">not</span>
<span class="pre">lstrip_ws)</span></code></td>
<td>false</td>
</tr>
</tbody>
</table>
<p>Note that since <em>rstrip_ws</em> can strip the trailing newline, the semantics of
<a class="reference internal" href="../library/readline.html#module-readline" title="readline: GNU readline support for Python. (Unix)"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readline()</span></code></a> must differ from those of the built-in file object’s
<a class="reference internal" href="../library/readline.html#module-readline" title="readline: GNU readline support for Python. (Unix)"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readline()</span></code></a> method! In particular, <a class="reference internal" href="../library/readline.html#module-readline" title="readline: GNU readline support for Python. (Unix)"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readline()</span></code></a> returns <code class="docutils literal notranslate"><span class="pre">None</span></code> for
end-of-file: an empty string might just be a blank line (or an all-whitespace
line), if <em>rstrip_ws</em> is true but <em>skip_blanks</em> is not.</p>
<dl class="method">
<dt id="distutils.text_file.TextFile.open">
<code class="descname">open</code><span class="sig-paren">(</span><em>filename</em><span class="sig-paren">)</span><a class="headerlink" href="#distutils.text_file.TextFile.open" title="Permalink to this definition">¶</a></dt>
<dd><p>Open a new file <em>filename</em>. This overrides any <em>file</em> or <em>filename</em>
constructor arguments.</p>
</dd></dl>
<dl class="method">
<dt id="distutils.text_file.TextFile.close">
<code class="descname">close</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.text_file.TextFile.close" title="Permalink to this definition">¶</a></dt>
<dd><p>Close the current file and forget everything we know about it (including the
filename and the current line number).</p>
</dd></dl>
<dl class="method">
<dt id="distutils.text_file.TextFile.warn">
<code class="descname">warn</code><span class="sig-paren">(</span><em>msg</em><span class="optional">[</span>, <em>line=None</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.text_file.TextFile.warn" title="Permalink to this definition">¶</a></dt>
<dd><p>Print (to stderr) a warning message tied to the current logical line in the
current file. If the current logical line in the file spans multiple physical
lines, the warning refers to the whole range, such as <code class="docutils literal notranslate"><span class="pre">"lines</span> <span class="pre">3-5"</span></code>. If
<em>line</em> is supplied, it overrides the current line number; it may be a list or
tuple to indicate a range of physical lines, or an integer for a single
physical line.</p>
</dd></dl>
<dl class="method">
<dt id="distutils.text_file.TextFile.readline">
<code class="descname">readline</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.text_file.TextFile.readline" title="Permalink to this definition">¶</a></dt>
<dd><p>Read and return a single logical line from the current file (or from an internal
buffer if lines have previously been “unread” with <a class="reference internal" href="#distutils.text_file.TextFile.unreadline" title="distutils.text_file.TextFile.unreadline"><code class="xref py py-meth docutils literal notranslate"><span class="pre">unreadline()</span></code></a>). If the
<em>join_lines</em> option is true, this may involve reading multiple physical lines
concatenated into a single string. Updates the current line number, so calling
<a class="reference internal" href="#distutils.text_file.TextFile.warn" title="distutils.text_file.TextFile.warn"><code class="xref py py-meth docutils literal notranslate"><span class="pre">warn()</span></code></a> after <a class="reference internal" href="../library/readline.html#module-readline" title="readline: GNU readline support for Python. (Unix)"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readline()</span></code></a> emits a warning about the physical line(s)
just read. Returns <code class="docutils literal notranslate"><span class="pre">None</span></code> on end-of-file, since the empty string can occur
if <em>rstrip_ws</em> is true but <em>strip_blanks</em> is not.</p>
</dd></dl>
<dl class="method">
<dt id="distutils.text_file.TextFile.readlines">
<code class="descname">readlines</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.text_file.TextFile.readlines" title="Permalink to this definition">¶</a></dt>
<dd><p>Read and return the list of all logical lines remaining in the current file.
This updates the current line number to the last line of the file.</p>
</dd></dl>
<dl class="method">
<dt id="distutils.text_file.TextFile.unreadline">
<code class="descname">unreadline</code><span class="sig-paren">(</span><em>line</em><span class="sig-paren">)</span><a class="headerlink" href="#distutils.text_file.TextFile.unreadline" title="Permalink to this definition">¶</a></dt>
<dd><p>Push <em>line</em> (a string) onto an internal buffer that will be checked by future
<a class="reference internal" href="../library/readline.html#module-readline" title="readline: GNU readline support for Python. (Unix)"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readline()</span></code></a> calls. Handy for implementing a parser with line-at-a-time
lookahead. Note that lines that are “unread” with <a class="reference internal" href="#distutils.text_file.TextFile.unreadline" title="distutils.text_file.TextFile.unreadline"><code class="xref py py-meth docutils literal notranslate"><span class="pre">unreadline()</span></code></a> are not
subsequently re-cleansed (whitespace stripped, or whatever) when read with
<a class="reference internal" href="../library/readline.html#module-readline" title="readline: GNU readline support for Python. (Unix)"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readline()</span></code></a>. If multiple calls are made to <a class="reference internal" href="#distutils.text_file.TextFile.unreadline" title="distutils.text_file.TextFile.unreadline"><code class="xref py py-meth docutils literal notranslate"><span class="pre">unreadline()</span></code></a> before a call
to <a class="reference internal" href="../library/readline.html#module-readline" title="readline: GNU readline support for Python. (Unix)"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readline()</span></code></a>, the lines will be returned most in most recent first order.</p>
</dd></dl>
</dd></dl>
</div>
<div class="section" id="module-distutils.version">
<span id="distutils-version-version-number-classes"></span><h2>10.23. <a class="reference internal" href="#module-distutils.version" title="distutils.version: implements classes that represent module version numbers."><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.version</span></code></a> — Version number classes<a class="headerlink" href="#module-distutils.version" title="Permalink to this headline">¶</a></h2>
</div>
<div class="section" id="module-distutils.cmd">
<span id="distutils-cmd-abstract-base-class-for-distutils-commands"></span><h2>10.24. <a class="reference internal" href="#module-distutils.cmd" title="distutils.cmd: This module provides the abstract base class Command. This class is subclassed by the modules in the distutils.command subpackage."><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.cmd</span></code></a> — Abstract base class for Distutils commands<a class="headerlink" href="#module-distutils.cmd" title="Permalink to this headline">¶</a></h2>
<p>This module supplies the abstract base class <a class="reference internal" href="#distutils.cmd.Command" title="distutils.cmd.Command"><code class="xref py py-class docutils literal notranslate"><span class="pre">Command</span></code></a>.</p>
<dl class="class">
<dt id="distutils.cmd.Command">
<em class="property">class </em><code class="descclassname">distutils.cmd.</code><code class="descname">Command</code><span class="sig-paren">(</span><em>dist</em><span class="sig-paren">)</span><a class="headerlink" href="#distutils.cmd.Command" title="Permalink to this definition">¶</a></dt>
<dd><p>Abstract base class for defining command classes, the “worker bees” of the
Distutils. A useful analogy for command classes is to think of them as
subroutines with local variables called <em>options</em>. The options are declared
in <a class="reference internal" href="#distutils.cmd.Command.initialize_options" title="distutils.cmd.Command.initialize_options"><code class="xref py py-meth docutils literal notranslate"><span class="pre">initialize_options()</span></code></a> and defined (given their final values) in
<a class="reference internal" href="#distutils.cmd.Command.finalize_options" title="distutils.cmd.Command.finalize_options"><code class="xref py py-meth docutils literal notranslate"><span class="pre">finalize_options()</span></code></a>, both of which must be defined by every command
class. The distinction between the two is necessary because option values
might come from the outside world (command line, config file, …), and any
options dependent on other options must be computed after these outside
influences have been processed — hence <a class="reference internal" href="#distutils.cmd.Command.finalize_options" title="distutils.cmd.Command.finalize_options"><code class="xref py py-meth docutils literal notranslate"><span class="pre">finalize_options()</span></code></a>. The body
of the subroutine, where it does all its work based on the values of its
options, is the <a class="reference internal" href="#distutils.cmd.Command.run" title="distutils.cmd.Command.run"><code class="xref py py-meth docutils literal notranslate"><span class="pre">run()</span></code></a> method, which must also be implemented by every
command class.</p>
<p>The class constructor takes a single argument <em>dist</em>, a
<a class="reference internal" href="#distutils.core.Distribution" title="distutils.core.Distribution"><code class="xref py py-class docutils literal notranslate"><span class="pre">Distribution</span></code></a> instance.</p>
</dd></dl>
</div>
<div class="section" id="creating-a-new-distutils-command">
<h2>10.25. Creating a new Distutils command<a class="headerlink" href="#creating-a-new-distutils-command" title="Permalink to this headline">¶</a></h2>
<p>This section outlines the steps to create a new Distutils command.</p>
<p>A new command lives in a module in the <a class="reference internal" href="#module-distutils.command" title="distutils.command: This subpackage contains one module for each standard Distutils command."><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command</span></code></a> package. There
is a sample template in that directory called <code class="file docutils literal notranslate"><span class="pre">command_template</span></code>. Copy
this file to a new module with the same name as the new command you’re
implementing. This module should implement a class with the same name as the
module (and the command). So, for instance, to create the command
<code class="docutils literal notranslate"><span class="pre">peel_banana</span></code> (so that users can run <code class="docutils literal notranslate"><span class="pre">setup.py</span> <span class="pre">peel_banana</span></code>), you’d copy
<code class="file docutils literal notranslate"><span class="pre">command_template</span></code> to <code class="file docutils literal notranslate"><span class="pre">distutils/command/peel_banana.py</span></code>, then edit
it so that it’s implementing the class <code class="xref py py-class docutils literal notranslate"><span class="pre">peel_banana</span></code>, a subclass of
<a class="reference internal" href="#distutils.cmd.Command" title="distutils.cmd.Command"><code class="xref py py-class docutils literal notranslate"><span class="pre">distutils.cmd.Command</span></code></a>.</p>
<p>Subclasses of <a class="reference internal" href="#distutils.cmd.Command" title="distutils.cmd.Command"><code class="xref py py-class docutils literal notranslate"><span class="pre">Command</span></code></a> must define the following methods.</p>
<dl class="method">
<dt id="distutils.cmd.Command.initialize_options">
<code class="descclassname">Command.</code><code class="descname">initialize_options</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.cmd.Command.initialize_options" title="Permalink to this definition">¶</a></dt>
<dd><p>Set default values for all the options that this command supports. Note that
these defaults may be overridden by other commands, by the setup script, by
config files, or by the command-line. Thus, this is not the place to code
dependencies between options; generally, <a class="reference internal" href="#distutils.cmd.Command.initialize_options" title="distutils.cmd.Command.initialize_options"><code class="xref py py-meth docutils literal notranslate"><span class="pre">initialize_options()</span></code></a>
implementations are just a bunch of <code class="docutils literal notranslate"><span class="pre">self.foo</span> <span class="pre">=</span> <span class="pre">None</span></code> assignments.</p>
</dd></dl>
<dl class="method">
<dt id="distutils.cmd.Command.finalize_options">
<code class="descclassname">Command.</code><code class="descname">finalize_options</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.cmd.Command.finalize_options" title="Permalink to this definition">¶</a></dt>
<dd><p>Set final values for all the options that this command supports. This is
always called as late as possible, ie. after any option assignments from the
command-line or from other commands have been done. Thus, this is the place
to code option dependencies: if <em>foo</em> depends on <em>bar</em>, then it is safe to
set <em>foo</em> from <em>bar</em> as long as <em>foo</em> still has the same value it was
assigned in <a class="reference internal" href="#distutils.cmd.Command.initialize_options" title="distutils.cmd.Command.initialize_options"><code class="xref py py-meth docutils literal notranslate"><span class="pre">initialize_options()</span></code></a>.</p>
</dd></dl>
<dl class="method">
<dt id="distutils.cmd.Command.run">
<code class="descclassname">Command.</code><code class="descname">run</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#distutils.cmd.Command.run" title="Permalink to this definition">¶</a></dt>
<dd><p>A command’s raison d’etre: carry out the action it exists to perform, controlled
by the options initialized in <a class="reference internal" href="#distutils.cmd.Command.initialize_options" title="distutils.cmd.Command.initialize_options"><code class="xref py py-meth docutils literal notranslate"><span class="pre">initialize_options()</span></code></a>, customized by other
commands, the setup script, the command-line, and config files, and finalized in
<a class="reference internal" href="#distutils.cmd.Command.finalize_options" title="distutils.cmd.Command.finalize_options"><code class="xref py py-meth docutils literal notranslate"><span class="pre">finalize_options()</span></code></a>. All terminal output and filesystem interaction should
be done by <a class="reference internal" href="#distutils.cmd.Command.run" title="distutils.cmd.Command.run"><code class="xref py py-meth docutils literal notranslate"><span class="pre">run()</span></code></a>.</p>
</dd></dl>
<dl class="attribute">
<dt id="distutils.cmd.Command.sub_commands">
<code class="descclassname">Command.</code><code class="descname">sub_commands</code><a class="headerlink" href="#distutils.cmd.Command.sub_commands" title="Permalink to this definition">¶</a></dt>
<dd><p><em>sub_commands</em> formalizes the notion of a “family” of commands,
e.g. <code class="docutils literal notranslate"><span class="pre">install</span></code> as the parent with sub-commands <code class="docutils literal notranslate"><span class="pre">install_lib</span></code>,
<code class="docutils literal notranslate"><span class="pre">install_headers</span></code>, etc. The parent of a family of commands defines
<em>sub_commands</em> as a class attribute; it’s a list of 2-tuples <code class="docutils literal notranslate"><span class="pre">(command_name,</span>
<span class="pre">predicate)</span></code>, with <em>command_name</em> a string and <em>predicate</em> a function, a
string or <code class="docutils literal notranslate"><span class="pre">None</span></code>. <em>predicate</em> is a method of the parent command that
determines whether the corresponding command is applicable in the current
situation. (E.g. <code class="docutils literal notranslate"><span class="pre">install_headers</span></code> is only applicable if we have any C
header files to install.) If <em>predicate</em> is <code class="docutils literal notranslate"><span class="pre">None</span></code>, that command is always
applicable.</p>
<p><em>sub_commands</em> is usually defined at the <em>end</em> of a class, because
predicates can be methods of the class, so they must already have been
defined. The canonical example is the <strong class="command">install</strong> command.</p>
</dd></dl>
</div>
<div class="section" id="module-distutils.command">
<span id="distutils-command-individual-distutils-commands"></span><h2>10.26. <a class="reference internal" href="#module-distutils.command" title="distutils.command: This subpackage contains one module for each standard Distutils command."><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command</span></code></a> — Individual Distutils commands<a class="headerlink" href="#module-distutils.command" title="Permalink to this headline">¶</a></h2>
</div>
<div class="section" id="module-distutils.command.bdist">
<span id="distutils-command-bdist-build-a-binary-installer"></span><h2>10.27. <a class="reference internal" href="#module-distutils.command.bdist" title="distutils.command.bdist: Build a binary installer for a package"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command.bdist</span></code></a> — Build a binary installer<a class="headerlink" href="#module-distutils.command.bdist" title="Permalink to this headline">¶</a></h2>
</div>
<div class="section" id="module-distutils.command.bdist_packager">
<span id="distutils-command-bdist-packager-abstract-base-class-for-packagers"></span><h2>10.28. <a class="reference internal" href="#module-distutils.command.bdist_packager" title="distutils.command.bdist_packager: Abstract base class for packagers"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command.bdist_packager</span></code></a> — Abstract base class for packagers<a class="headerlink" href="#module-distutils.command.bdist_packager" title="Permalink to this headline">¶</a></h2>
</div>
<div class="section" id="module-distutils.command.bdist_dumb">
<span id="distutils-command-bdist-dumb-build-a-dumb-installer"></span><h2>10.29. <a class="reference internal" href="#module-distutils.command.bdist_dumb" title="distutils.command.bdist_dumb: Build a "dumb" installer - a simple archive of files"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command.bdist_dumb</span></code></a> — Build a “dumb” installer<a class="headerlink" href="#module-distutils.command.bdist_dumb" title="Permalink to this headline">¶</a></h2>
</div>
<div class="section" id="module-distutils.command.bdist_msi">
<span id="distutils-command-bdist-msi-build-a-microsoft-installer-binary-package"></span><h2>10.30. <a class="reference internal" href="#module-distutils.command.bdist_msi" title="distutils.command.bdist_msi: Build a binary distribution as a Windows MSI file"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command.bdist_msi</span></code></a> — Build a Microsoft Installer binary package<a class="headerlink" href="#module-distutils.command.bdist_msi" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="distutils.command.bdist_msi.bdist_msi">
<em class="property">class </em><code class="descclassname">distutils.command.bdist_msi.</code><code class="descname">bdist_msi</code><a class="headerlink" href="#distutils.command.bdist_msi.bdist_msi" title="Permalink to this definition">¶</a></dt>
<dd><p>Builds a <a class="reference external" href="https://msdn.microsoft.com/en-us/library/cc185688(VS.85).aspx">Windows Installer</a> (.msi) binary package.</p>
<p>In most cases, the <code class="docutils literal notranslate"><span class="pre">bdist_msi</span></code> installer is a better choice than the
<code class="docutils literal notranslate"><span class="pre">bdist_wininst</span></code> installer, because it provides better support for
Win64 platforms, allows administrators to perform non-interactive
installations, and allows installation through group policies.</p>
</dd></dl>
</div>
<div class="section" id="module-distutils.command.bdist_rpm">
<span id="distutils-command-bdist-rpm-build-a-binary-distribution-as-a-redhat-rpm-and-srpm"></span><h2>10.31. <a class="reference internal" href="#module-distutils.command.bdist_rpm" title="distutils.command.bdist_rpm: Build a binary distribution as a Redhat RPM and SRPM"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command.bdist_rpm</span></code></a> — Build a binary distribution as a Redhat RPM and SRPM<a class="headerlink" href="#module-distutils.command.bdist_rpm" title="Permalink to this headline">¶</a></h2>
</div>
<div class="section" id="module-distutils.command.bdist_wininst">
<span id="distutils-command-bdist-wininst-build-a-windows-installer"></span><h2>10.32. <a class="reference internal" href="#module-distutils.command.bdist_wininst" title="distutils.command.bdist_wininst: Build a Windows installer"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command.bdist_wininst</span></code></a> — Build a Windows installer<a class="headerlink" href="#module-distutils.command.bdist_wininst" title="Permalink to this headline">¶</a></h2>
</div>
<div class="section" id="module-distutils.command.sdist">
<span id="distutils-command-sdist-build-a-source-distribution"></span><h2>10.33. <a class="reference internal" href="#module-distutils.command.sdist" title="distutils.command.sdist: Build a source distribution"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command.sdist</span></code></a> — Build a source distribution<a class="headerlink" href="#module-distutils.command.sdist" title="Permalink to this headline">¶</a></h2>
</div>
<div class="section" id="module-distutils.command.build">
<span id="distutils-command-build-build-all-files-of-a-package"></span><h2>10.34. <a class="reference internal" href="#module-distutils.command.build" title="distutils.command.build: Build all files of a package"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command.build</span></code></a> — Build all files of a package<a class="headerlink" href="#module-distutils.command.build" title="Permalink to this headline">¶</a></h2>
</div>
<div class="section" id="module-distutils.command.build_clib">
<span id="distutils-command-build-clib-build-any-c-libraries-in-a-package"></span><h2>10.35. <a class="reference internal" href="#module-distutils.command.build_clib" title="distutils.command.build_clib: Build any C libraries in a package"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command.build_clib</span></code></a> — Build any C libraries in a package<a class="headerlink" href="#module-distutils.command.build_clib" title="Permalink to this headline">¶</a></h2>
</div>
<div class="section" id="module-distutils.command.build_ext">
<span id="distutils-command-build-ext-build-any-extensions-in-a-package"></span><h2>10.36. <a class="reference internal" href="#module-distutils.command.build_ext" title="distutils.command.build_ext: Build any extensions in a package"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command.build_ext</span></code></a> — Build any extensions in a package<a class="headerlink" href="#module-distutils.command.build_ext" title="Permalink to this headline">¶</a></h2>
</div>
<div class="section" id="module-distutils.command.build_py">
<span id="distutils-command-build-py-build-the-py-pyc-files-of-a-package"></span><h2>10.37. <a class="reference internal" href="#module-distutils.command.build_py" title="distutils.command.build_py: Build the .py/.pyc files of a package"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command.build_py</span></code></a> — Build the .py/.pyc files of a package<a class="headerlink" href="#module-distutils.command.build_py" title="Permalink to this headline">¶</a></h2>
</div>
<div class="section" id="module-distutils.command.build_scripts">
<span id="distutils-command-build-scripts-build-the-scripts-of-a-package"></span><h2>10.38. <a class="reference internal" href="#module-distutils.command.build_scripts" title="distutils.command.build_scripts: Build the scripts of a package"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command.build_scripts</span></code></a> — Build the scripts of a package<a class="headerlink" href="#module-distutils.command.build_scripts" title="Permalink to this headline">¶</a></h2>
</div>
<div class="section" id="module-distutils.command.clean">
<span id="distutils-command-clean-clean-a-package-build-area"></span><h2>10.39. <a class="reference internal" href="#module-distutils.command.clean" title="distutils.command.clean: Clean a package build area"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command.clean</span></code></a> — Clean a package build area<a class="headerlink" href="#module-distutils.command.clean" title="Permalink to this headline">¶</a></h2>
<p>This command removes the temporary files created by <strong class="command">build</strong>
and its subcommands, like intermediary compiled object files. With
the <code class="docutils literal notranslate"><span class="pre">--all</span></code> option, the complete build directory will be removed.</p>
<p>Extension modules built <a class="reference internal" href="configfile.html#distutils-build-ext-inplace"><span class="std std-ref">in place</span></a>
will not be cleaned, as they are not in the build directory.</p>
</div>
<div class="section" id="module-distutils.command.config">
<span id="distutils-command-config-perform-package-configuration"></span><h2>10.40. <a class="reference internal" href="#module-distutils.command.config" title="distutils.command.config: Perform package configuration"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command.config</span></code></a> — Perform package configuration<a class="headerlink" href="#module-distutils.command.config" title="Permalink to this headline">¶</a></h2>
</div>
<div class="section" id="module-distutils.command.install">
<span id="distutils-command-install-install-a-package"></span><h2>10.41. <a class="reference internal" href="#module-distutils.command.install" title="distutils.command.install: Install a package"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command.install</span></code></a> — Install a package<a class="headerlink" href="#module-distutils.command.install" title="Permalink to this headline">¶</a></h2>
</div>
<div class="section" id="module-distutils.command.install_data">
<span id="distutils-command-install-data-install-data-files-from-a-package"></span><h2>10.42. <a class="reference internal" href="#module-distutils.command.install_data" title="distutils.command.install_data: Install data files from a package"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command.install_data</span></code></a> — Install data files from a package<a class="headerlink" href="#module-distutils.command.install_data" title="Permalink to this headline">¶</a></h2>
</div>
<div class="section" id="module-distutils.command.install_headers">
<span id="distutils-command-install-headers-install-c-c-header-files-from-a-package"></span><h2>10.43. <a class="reference internal" href="#module-distutils.command.install_headers" title="distutils.command.install_headers: Install C/C++ header files from a package"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command.install_headers</span></code></a> — Install C/C++ header files from a package<a class="headerlink" href="#module-distutils.command.install_headers" title="Permalink to this headline">¶</a></h2>
</div>
<div class="section" id="module-distutils.command.install_lib">
<span id="distutils-command-install-lib-install-library-files-from-a-package"></span><h2>10.44. <a class="reference internal" href="#module-distutils.command.install_lib" title="distutils.command.install_lib: Install library files from a package"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command.install_lib</span></code></a> — Install library files from a package<a class="headerlink" href="#module-distutils.command.install_lib" title="Permalink to this headline">¶</a></h2>
</div>
<div class="section" id="module-distutils.command.install_scripts">
<span id="distutils-command-install-scripts-install-script-files-from-a-package"></span><h2>10.45. <a class="reference internal" href="#module-distutils.command.install_scripts" title="distutils.command.install_scripts: Install script files from a package"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command.install_scripts</span></code></a> — Install script files from a package<a class="headerlink" href="#module-distutils.command.install_scripts" title="Permalink to this headline">¶</a></h2>
</div>
<div class="section" id="module-distutils.command.register">
<span id="distutils-command-register-register-a-module-with-the-python-package-index"></span><h2>10.46. <a class="reference internal" href="#module-distutils.command.register" title="distutils.command.register: Register a module with the Python Package Index"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command.register</span></code></a> — Register a module with the Python Package Index<a class="headerlink" href="#module-distutils.command.register" title="Permalink to this headline">¶</a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">register</span></code> command registers the package with the Python Package Index.
This is described in more detail in <span class="target" id="index-4"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0301"><strong>PEP 301</strong></a>.</p>
</div>
<div class="section" id="module-distutils.command.check">
<span id="distutils-command-check-check-the-meta-data-of-a-package"></span><h2>10.47. <a class="reference internal" href="#module-distutils.command.check" title="distutils.command.check: Check the metadata of a package"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command.check</span></code></a> — Check the meta-data of a package<a class="headerlink" href="#module-distutils.command.check" title="Permalink to this headline">¶</a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">check</span></code> command performs some tests on the meta-data of a package.
For example, it verifies that all required meta-data are provided as
the arguments passed to the <code class="xref py py-func docutils literal notranslate"><span class="pre">setup()</span></code> function.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">10. API Reference</a><ul>
<li><a class="reference internal" href="#module-distutils.core">10.1. <code class="docutils literal notranslate"><span class="pre">distutils.core</span></code> — Core Distutils functionality</a></li>
<li><a class="reference internal" href="#module-distutils.ccompiler">10.2. <code class="docutils literal notranslate"><span class="pre">distutils.ccompiler</span></code> — CCompiler base class</a></li>
<li><a class="reference internal" href="#module-distutils.unixccompiler">10.3. <code class="docutils literal notranslate"><span class="pre">distutils.unixccompiler</span></code> — Unix C Compiler</a></li>
<li><a class="reference internal" href="#module-distutils.msvccompiler">10.4. <code class="docutils literal notranslate"><span class="pre">distutils.msvccompiler</span></code> — Microsoft Compiler</a></li>
<li><a class="reference internal" href="#module-distutils.bcppcompiler">10.5. <code class="docutils literal notranslate"><span class="pre">distutils.bcppcompiler</span></code> — Borland Compiler</a></li>
<li><a class="reference internal" href="#module-distutils.cygwinccompiler">10.6. <code class="docutils literal notranslate"><span class="pre">distutils.cygwincompiler</span></code> — Cygwin Compiler</a></li>
<li><a class="reference internal" href="#module-distutils.emxccompiler">10.7. <code class="docutils literal notranslate"><span class="pre">distutils.emxccompiler</span></code> — OS/2 EMX Compiler</a></li>
<li><a class="reference internal" href="#module-distutils.archive_util">10.8. <code class="docutils literal notranslate"><span class="pre">distutils.archive_util</span></code> — Archiving utilities</a></li>
<li><a class="reference internal" href="#module-distutils.dep_util">10.9. <code class="docutils literal notranslate"><span class="pre">distutils.dep_util</span></code> — Dependency checking</a></li>
<li><a class="reference internal" href="#module-distutils.dir_util">10.10. <code class="docutils literal notranslate"><span class="pre">distutils.dir_util</span></code> — Directory tree operations</a></li>
<li><a class="reference internal" href="#module-distutils.file_util">10.11. <code class="docutils literal notranslate"><span class="pre">distutils.file_util</span></code> — Single file operations</a></li>
<li><a class="reference internal" href="#module-distutils.util">10.12. <code class="docutils literal notranslate"><span class="pre">distutils.util</span></code> — Miscellaneous other utility functions</a></li>
<li><a class="reference internal" href="#module-distutils.dist">10.13. <code class="docutils literal notranslate"><span class="pre">distutils.dist</span></code> — The Distribution class</a></li>
<li><a class="reference internal" href="#module-distutils.extension">10.14. <code class="docutils literal notranslate"><span class="pre">distutils.extension</span></code> — The Extension class</a></li>
<li><a class="reference internal" href="#module-distutils.debug">10.15. <code class="docutils literal notranslate"><span class="pre">distutils.debug</span></code> — Distutils debug mode</a></li>
<li><a class="reference internal" href="#module-distutils.errors">10.16. <code class="docutils literal notranslate"><span class="pre">distutils.errors</span></code> — Distutils exceptions</a></li>
<li><a class="reference internal" href="#module-distutils.fancy_getopt">10.17. <code class="docutils literal notranslate"><span class="pre">distutils.fancy_getopt</span></code> — Wrapper around the standard getopt module</a></li>
<li><a class="reference internal" href="#module-distutils.filelist">10.18. <code class="docutils literal notranslate"><span class="pre">distutils.filelist</span></code> — The FileList class</a></li>
<li><a class="reference internal" href="#module-distutils.log">10.19. <code class="docutils literal notranslate"><span class="pre">distutils.log</span></code> — Simple PEP 282-style logging</a></li>
<li><a class="reference internal" href="#module-distutils.spawn">10.20. <code class="docutils literal notranslate"><span class="pre">distutils.spawn</span></code> — Spawn a sub-process</a></li>
<li><a class="reference internal" href="#module-distutils.sysconfig">10.21. <code class="docutils literal notranslate"><span class="pre">distutils.sysconfig</span></code> — System configuration information</a></li>
<li><a class="reference internal" href="#module-distutils.text_file">10.22. <code class="docutils literal notranslate"><span class="pre">distutils.text_file</span></code> — The TextFile class</a></li>
<li><a class="reference internal" href="#module-distutils.version">10.23. <code class="docutils literal notranslate"><span class="pre">distutils.version</span></code> — Version number classes</a></li>
<li><a class="reference internal" href="#module-distutils.cmd">10.24. <code class="docutils literal notranslate"><span class="pre">distutils.cmd</span></code> — Abstract base class for Distutils commands</a></li>
<li><a class="reference internal" href="#creating-a-new-distutils-command">10.25. Creating a new Distutils command</a></li>
<li><a class="reference internal" href="#module-distutils.command">10.26. <code class="docutils literal notranslate"><span class="pre">distutils.command</span></code> — Individual Distutils commands</a></li>
<li><a class="reference internal" href="#module-distutils.command.bdist">10.27. <code class="docutils literal notranslate"><span class="pre">distutils.command.bdist</span></code> — Build a binary installer</a></li>
<li><a class="reference internal" href="#module-distutils.command.bdist_packager">10.28. <code class="docutils literal notranslate"><span class="pre">distutils.command.bdist_packager</span></code> — Abstract base class for packagers</a></li>
<li><a class="reference internal" href="#module-distutils.command.bdist_dumb">10.29. <code class="docutils literal notranslate"><span class="pre">distutils.command.bdist_dumb</span></code> — Build a “dumb” installer</a></li>
<li><a class="reference internal" href="#module-distutils.command.bdist_msi">10.30. <code class="docutils literal notranslate"><span class="pre">distutils.command.bdist_msi</span></code> — Build a Microsoft Installer binary package</a></li>
<li><a class="reference internal" href="#module-distutils.command.bdist_rpm">10.31. <code class="docutils literal notranslate"><span class="pre">distutils.command.bdist_rpm</span></code> — Build a binary distribution as a Redhat RPM and SRPM</a></li>
<li><a class="reference internal" href="#module-distutils.command.bdist_wininst">10.32. <code class="docutils literal notranslate"><span class="pre">distutils.command.bdist_wininst</span></code> — Build a Windows installer</a></li>
<li><a class="reference internal" href="#module-distutils.command.sdist">10.33. <code class="docutils literal notranslate"><span class="pre">distutils.command.sdist</span></code> — Build a source distribution</a></li>
<li><a class="reference internal" href="#module-distutils.command.build">10.34. <code class="docutils literal notranslate"><span class="pre">distutils.command.build</span></code> — Build all files of a package</a></li>
<li><a class="reference internal" href="#module-distutils.command.build_clib">10.35. <code class="docutils literal notranslate"><span class="pre">distutils.command.build_clib</span></code> — Build any C libraries in a package</a></li>
<li><a class="reference internal" href="#module-distutils.command.build_ext">10.36. <code class="docutils literal notranslate"><span class="pre">distutils.command.build_ext</span></code> — Build any extensions in a package</a></li>
<li><a class="reference internal" href="#module-distutils.command.build_py">10.37. <code class="docutils literal notranslate"><span class="pre">distutils.command.build_py</span></code> — Build the .py/.pyc files of a package</a></li>
<li><a class="reference internal" href="#module-distutils.command.build_scripts">10.38. <code class="docutils literal notranslate"><span class="pre">distutils.command.build_scripts</span></code> — Build the scripts of a package</a></li>
<li><a class="reference internal" href="#module-distutils.command.clean">10.39. <code class="docutils literal notranslate"><span class="pre">distutils.command.clean</span></code> — Clean a package build area</a></li>
<li><a class="reference internal" href="#module-distutils.command.config">10.40. <code class="docutils literal notranslate"><span class="pre">distutils.command.config</span></code> — Perform package configuration</a></li>
<li><a class="reference internal" href="#module-distutils.command.install">10.41. <code class="docutils literal notranslate"><span class="pre">distutils.command.install</span></code> — Install a package</a></li>
<li><a class="reference internal" href="#module-distutils.command.install_data">10.42. <code class="docutils literal notranslate"><span class="pre">distutils.command.install_data</span></code> — Install data files from a package</a></li>
<li><a class="reference internal" href="#module-distutils.command.install_headers">10.43. <code class="docutils literal notranslate"><span class="pre">distutils.command.install_headers</span></code> — Install C/C++ header files from a package</a></li>
<li><a class="reference internal" href="#module-distutils.command.install_lib">10.44. <code class="docutils literal notranslate"><span class="pre">distutils.command.install_lib</span></code> — Install library files from a package</a></li>
<li><a class="reference internal" href="#module-distutils.command.install_scripts">10.45. <code class="docutils literal notranslate"><span class="pre">distutils.command.install_scripts</span></code> — Install script files from a package</a></li>
<li><a class="reference internal" href="#module-distutils.command.register">10.46. <code class="docutils literal notranslate"><span class="pre">distutils.command.register</span></code> — Register a module with the Python Package Index</a></li>
<li><a class="reference internal" href="#module-distutils.command.check">10.47. <code class="docutils literal notranslate"><span class="pre">distutils.command.check</span></code> — Check the meta-data of a package</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="commandref.html"
title="previous chapter">9. Command Reference</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="../install/index.html"
title="next chapter">Installing Python Modules (Legacy version)</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/distutils/apiref.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="../install/index.html" title="Installing Python Modules (Legacy version)"
>next</a> |</li>
<li class="right" >
<a href="commandref.html" title="9. Command Reference"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Distributing Python Modules (Legacy version)</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\�5�S� � html/distutils/builtdist.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>5. Creating Built Distributions — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="6. The Python Package Index (PyPI)" href="packageindex.html" />
<link rel="prev" title="4. Creating a Source Distribution" href="sourcedist.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/distutils/builtdist.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="packageindex.html" title="6. The Python Package Index (PyPI)"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="sourcedist.html" title="4. Creating a Source Distribution"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Distributing Python Modules (Legacy version)</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="creating-built-distributions">
<span id="built-dist"></span><h1>5. Creating Built Distributions<a class="headerlink" href="#creating-built-distributions" title="Permalink to this headline">¶</a></h1>
<p>A “built distribution” is what you’re probably used to thinking of either as a
“binary package” or an “installer” (depending on your background). It’s not
necessarily binary, though, because it might contain only Python source code
and/or byte-code; and we don’t call it a package, because that word is already
spoken for in Python. (And “installer” is a term specific to the world of
mainstream desktop systems.)</p>
<p>A built distribution is how you make life as easy as possible for installers of
your module distribution: for users of RPM-based Linux systems, it’s a binary
RPM; for Windows users, it’s an executable installer; for Debian-based Linux
users, it’s a Debian package; and so forth. Obviously, no one person will be
able to create built distributions for every platform under the sun, so the
Distutils are designed to enable module developers to concentrate on their
specialty—writing code and creating source distributions—while an
intermediary species called <em>packagers</em> springs up to turn source distributions
into built distributions for as many platforms as there are packagers.</p>
<p>Of course, the module developer could be their own packager; or the packager could
be a volunteer “out there” somewhere who has access to a platform which the
original developer does not; or it could be software periodically grabbing new
source distributions and turning them into built distributions for as many
platforms as the software has access to. Regardless of who they are, a packager
uses the setup script and the <strong class="command">bdist</strong> command family to generate built
distributions.</p>
<p>As a simple example, if I run the following command in the Distutils source
tree:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">bdist</span>
</pre></div>
</div>
<p>then the Distutils builds my module distribution (the Distutils itself in this
case), does a “fake” installation (also in the <code class="file docutils literal notranslate"><span class="pre">build</span></code> directory), and
creates the default type of built distribution for my platform. The default
format for built distributions is a “dumb” tar file on Unix, and a simple
executable installer on Windows. (That tar file is considered “dumb” because it
has to be unpacked in a specific location to work.)</p>
<p>Thus, the above command on a Unix system creates
<code class="file docutils literal notranslate"><span class="pre">Distutils-1.0.</span><em><span class="pre">plat</span></em><span class="pre">.tar.gz</span></code>; unpacking this tarball from the right place
installs the Distutils just as though you had downloaded the source distribution
and run <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">setup.py</span> <span class="pre">install</span></code>. (The “right place” is either the root of
the filesystem or Python’s <code class="file docutils literal notranslate"><em><span class="pre">prefix</span></em></code> directory, depending on the options
given to the <strong class="command">bdist_dumb</strong> command; the default is to make dumb
distributions relative to <code class="file docutils literal notranslate"><em><span class="pre">prefix</span></em></code>.)</p>
<p>Obviously, for pure Python distributions, this isn’t any simpler than just
running <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">setup.py</span> <span class="pre">install</span></code>—but for non-pure distributions, which
include extensions that would need to be compiled, it can mean the difference
between someone being able to use your extensions or not. And creating “smart”
built distributions, such as an RPM package or an executable installer for
Windows, is far more convenient for users even if your distribution doesn’t
include any extensions.</p>
<p>The <strong class="command">bdist</strong> command has a <code class="xref std std-option docutils literal notranslate"><span class="pre">--formats</span></code> option, similar to the
<strong class="command">sdist</strong> command, which you can use to select the types of built
distribution to generate: for example,</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">bdist</span> <span class="o">--</span><span class="nb">format</span><span class="o">=</span><span class="nb">zip</span>
</pre></div>
</div>
<p>would, when run on a Unix system, create <code class="file docutils literal notranslate"><span class="pre">Distutils-1.0.</span><em><span class="pre">plat</span></em><span class="pre">.zip</span></code>—again, this archive would be unpacked from the root directory to install the
Distutils.</p>
<p>The available formats for built distributions are:</p>
<table border="1" class="docutils">
<colgroup>
<col width="25%" />
<col width="58%" />
<col width="17%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Format</th>
<th class="head">Description</th>
<th class="head">Notes</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">gztar</span></code></td>
<td>gzipped tar file
(<code class="file docutils literal notranslate"><span class="pre">.tar.gz</span></code>)</td>
<td>(1),(3)</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">ztar</span></code></td>
<td>compressed tar file
(<code class="file docutils literal notranslate"><span class="pre">.tar.Z</span></code>)</td>
<td>(3)</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">tar</span></code></td>
<td>tar file (<code class="file docutils literal notranslate"><span class="pre">.tar</span></code>)</td>
<td>(3)</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">zip</span></code></td>
<td>zip file (<code class="file docutils literal notranslate"><span class="pre">.zip</span></code>)</td>
<td>(2),(4)</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">rpm</span></code></td>
<td>RPM</td>
<td>(5)</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">pkgtool</span></code></td>
<td>Solaris <strong class="program">pkgtool</strong></td>
<td> </td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">sdux</span></code></td>
<td>HP-UX <strong class="program">swinstall</strong></td>
<td> </td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">wininst</span></code></td>
<td>self-extracting ZIP file for
Windows</td>
<td>(4)</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">msi</span></code></td>
<td>Microsoft Installer.</td>
<td> </td>
</tr>
</tbody>
</table>
<p>Notes:</p>
<ol class="arabic simple">
<li>default on Unix</li>
<li>default on Windows</li>
<li>requires external utilities: <strong class="program">tar</strong> and possibly one of <strong class="program">gzip</strong>,
<strong class="program">bzip2</strong>, or <strong class="program">compress</strong></li>
<li>requires either external <strong class="program">zip</strong> utility or <a class="reference internal" href="../library/zipfile.html#module-zipfile" title="zipfile: Read and write ZIP-format archive files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">zipfile</span></code></a> module (part
of the standard Python library since Python 1.6)</li>
<li>requires external <strong class="program">rpm</strong> utility, version 3.0.4 or better (use <code class="docutils literal notranslate"><span class="pre">rpm</span>
<span class="pre">--version</span></code> to find out which version you have)</li>
</ol>
<p>You don’t have to use the <strong class="command">bdist</strong> command with the <code class="xref std std-option docutils literal notranslate"><span class="pre">--formats</span></code>
option; you can also use the command that directly implements the format you’re
interested in. Some of these <strong class="command">bdist</strong> “sub-commands” actually generate
several similar formats; for instance, the <strong class="command">bdist_dumb</strong> command
generates all the “dumb” archive formats (<code class="docutils literal notranslate"><span class="pre">tar</span></code>, <code class="docutils literal notranslate"><span class="pre">ztar</span></code>, <code class="docutils literal notranslate"><span class="pre">gztar</span></code>, and
<code class="docutils literal notranslate"><span class="pre">zip</span></code>), and <strong class="command">bdist_rpm</strong> generates both binary and source RPMs. The
<strong class="command">bdist</strong> sub-commands, and the formats generated by each, are:</p>
<table border="1" class="docutils">
<colgroup>
<col width="53%" />
<col width="47%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Command</th>
<th class="head">Formats</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><strong class="command">bdist_dumb</strong></td>
<td>tar, ztar, gztar, zip</td>
</tr>
<tr class="row-odd"><td><strong class="command">bdist_rpm</strong></td>
<td>rpm, srpm</td>
</tr>
<tr class="row-even"><td><strong class="command">bdist_wininst</strong></td>
<td>wininst</td>
</tr>
<tr class="row-odd"><td><strong class="command">bdist_msi</strong></td>
<td>msi</td>
</tr>
</tbody>
</table>
<p>The following sections give details on the individual <strong class="command">bdist_*</strong>
commands.</p>
<div class="section" id="creating-dumb-built-distributions">
<span id="creating-dumb"></span><h2>5.1. Creating dumb built distributions<a class="headerlink" href="#creating-dumb-built-distributions" title="Permalink to this headline">¶</a></h2>
</div>
<div class="section" id="creating-rpm-packages">
<span id="creating-rpms"></span><h2>5.2. Creating RPM packages<a class="headerlink" href="#creating-rpm-packages" title="Permalink to this headline">¶</a></h2>
<p>The RPM format is used by many popular Linux distributions, including Red Hat,
SuSE, and Mandrake. If one of these (or any of the other RPM-based Linux
distributions) is your usual environment, creating RPM packages for other users
of that same distribution is trivial. Depending on the complexity of your module
distribution and differences between Linux distributions, you may also be able
to create RPMs that work on different RPM-based distributions.</p>
<p>The usual way to create an RPM of your module distribution is to run the
<strong class="command">bdist_rpm</strong> command:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">bdist_rpm</span>
</pre></div>
</div>
<p>or the <strong class="command">bdist</strong> command with the <code class="xref std std-option docutils literal notranslate"><span class="pre">--format</span></code> option:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">bdist</span> <span class="o">--</span><span class="n">formats</span><span class="o">=</span><span class="n">rpm</span>
</pre></div>
</div>
<p>The former allows you to specify RPM-specific options; the latter allows you to
easily specify multiple formats in one run. If you need to do both, you can
explicitly specify multiple <strong class="command">bdist_*</strong> commands and their options:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">bdist_rpm</span> <span class="o">--</span><span class="n">packager</span><span class="o">=</span><span class="s2">"John Doe <jdoe@example.org>"</span> \
<span class="n">bdist_wininst</span> <span class="o">--</span><span class="n">target</span><span class="o">-</span><span class="n">version</span><span class="o">=</span><span class="s2">"2.0"</span>
</pre></div>
</div>
<p>Creating RPM packages is driven by a <code class="file docutils literal notranslate"><span class="pre">.spec</span></code> file, much as using the
Distutils is driven by the setup script. To make your life easier, the
<strong class="command">bdist_rpm</strong> command normally creates a <code class="file docutils literal notranslate"><span class="pre">.spec</span></code> file based on the
information you supply in the setup script, on the command line, and in any
Distutils configuration files. Various options and sections in the
<code class="file docutils literal notranslate"><span class="pre">.spec</span></code> file are derived from options in the setup script as follows:</p>
<table border="1" class="docutils">
<colgroup>
<col width="48%" />
<col width="52%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">RPM <code class="file docutils literal notranslate"><span class="pre">.spec</span></code> file option or section</th>
<th class="head">Distutils setup script option</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>Name</td>
<td><code class="docutils literal notranslate"><span class="pre">name</span></code></td>
</tr>
<tr class="row-odd"><td>Summary (in preamble)</td>
<td><code class="docutils literal notranslate"><span class="pre">description</span></code></td>
</tr>
<tr class="row-even"><td>Version</td>
<td><code class="docutils literal notranslate"><span class="pre">version</span></code></td>
</tr>
<tr class="row-odd"><td>Vendor</td>
<td><code class="docutils literal notranslate"><span class="pre">author</span></code> and <code class="docutils literal notranslate"><span class="pre">author_email</span></code>,
or — & <code class="docutils literal notranslate"><span class="pre">maintainer</span></code> and
<code class="docutils literal notranslate"><span class="pre">maintainer_email</span></code></td>
</tr>
<tr class="row-even"><td>Copyright</td>
<td><code class="docutils literal notranslate"><span class="pre">license</span></code></td>
</tr>
<tr class="row-odd"><td>Url</td>
<td><code class="docutils literal notranslate"><span class="pre">url</span></code></td>
</tr>
<tr class="row-even"><td>%description (section)</td>
<td><code class="docutils literal notranslate"><span class="pre">long_description</span></code></td>
</tr>
</tbody>
</table>
<p>Additionally, there are many options in <code class="file docutils literal notranslate"><span class="pre">.spec</span></code> files that don’t have
corresponding options in the setup script. Most of these are handled through
options to the <strong class="command">bdist_rpm</strong> command as follows:</p>
<table border="1" class="docutils">
<colgroup>
<col width="36%" />
<col width="34%" />
<col width="29%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">RPM <code class="file docutils literal notranslate"><span class="pre">.spec</span></code> file option
or section</th>
<th class="head"><strong class="command">bdist_rpm</strong> option</th>
<th class="head">default value</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>Release</td>
<td><code class="docutils literal notranslate"><span class="pre">release</span></code></td>
<td>“1”</td>
</tr>
<tr class="row-odd"><td>Group</td>
<td><code class="docutils literal notranslate"><span class="pre">group</span></code></td>
<td>“Development/Libraries”</td>
</tr>
<tr class="row-even"><td>Vendor</td>
<td><code class="docutils literal notranslate"><span class="pre">vendor</span></code></td>
<td>(see above)</td>
</tr>
<tr class="row-odd"><td>Packager</td>
<td><code class="docutils literal notranslate"><span class="pre">packager</span></code></td>
<td>(none)</td>
</tr>
<tr class="row-even"><td>Provides</td>
<td><code class="docutils literal notranslate"><span class="pre">provides</span></code></td>
<td>(none)</td>
</tr>
<tr class="row-odd"><td>Requires</td>
<td><code class="docutils literal notranslate"><span class="pre">requires</span></code></td>
<td>(none)</td>
</tr>
<tr class="row-even"><td>Conflicts</td>
<td><code class="docutils literal notranslate"><span class="pre">conflicts</span></code></td>
<td>(none)</td>
</tr>
<tr class="row-odd"><td>Obsoletes</td>
<td><code class="docutils literal notranslate"><span class="pre">obsoletes</span></code></td>
<td>(none)</td>
</tr>
<tr class="row-even"><td>Distribution</td>
<td><code class="docutils literal notranslate"><span class="pre">distribution_name</span></code></td>
<td>(none)</td>
</tr>
<tr class="row-odd"><td>BuildRequires</td>
<td><code class="docutils literal notranslate"><span class="pre">build_requires</span></code></td>
<td>(none)</td>
</tr>
<tr class="row-even"><td>Icon</td>
<td><code class="docutils literal notranslate"><span class="pre">icon</span></code></td>
<td>(none)</td>
</tr>
</tbody>
</table>
<p>Obviously, supplying even a few of these options on the command-line would be
tedious and error-prone, so it’s usually best to put them in the setup
configuration file, <code class="file docutils literal notranslate"><span class="pre">setup.cfg</span></code>—see section <a class="reference internal" href="configfile.html#setup-config"><span class="std std-ref">Writing the Setup Configuration File</span></a>. If
you distribute or package many Python module distributions, you might want to
put options that apply to all of them in your personal Distutils configuration
file (<code class="file docutils literal notranslate"><span class="pre">~/.pydistutils.cfg</span></code>). If you want to temporarily disable
this file, you can pass the –no-user-cfg option to setup.py.</p>
<p>There are three steps to building a binary RPM package, all of which are
handled automatically by the Distutils:</p>
<ol class="arabic simple">
<li>create a <code class="file docutils literal notranslate"><span class="pre">.spec</span></code> file, which describes the package (analogous to the
Distutils setup script; in fact, much of the information in the setup script
winds up in the <code class="file docutils literal notranslate"><span class="pre">.spec</span></code> file)</li>
<li>create the source RPM</li>
<li>create the “binary” RPM (which may or may not contain binary code, depending
on whether your module distribution contains Python extensions)</li>
</ol>
<p>Normally, RPM bundles the last two steps together; when you use the Distutils,
all three steps are typically bundled together.</p>
<p>If you wish, you can separate these three steps. You can use the
<code class="xref std std-option docutils literal notranslate"><span class="pre">--spec-only</span></code> option to make <strong class="command">bdist_rpm</strong> just create the
<code class="file docutils literal notranslate"><span class="pre">.spec</span></code> file and exit; in this case, the <code class="file docutils literal notranslate"><span class="pre">.spec</span></code> file will be
written to the “distribution directory”—normally <code class="file docutils literal notranslate"><span class="pre">dist/</span></code>, but
customizable with the <code class="xref std std-option docutils literal notranslate"><span class="pre">--dist-dir</span></code> option. (Normally, the <code class="file docutils literal notranslate"><span class="pre">.spec</span></code>
file winds up deep in the “build tree,” in a temporary directory created by
<strong class="command">bdist_rpm</strong>.)</p>
</div>
<div class="section" id="creating-windows-installers">
<span id="creating-wininst"></span><h2>5.3. Creating Windows Installers<a class="headerlink" href="#creating-windows-installers" title="Permalink to this headline">¶</a></h2>
<p>Executable installers are the natural format for binary distributions on
Windows. They display a nice graphical user interface, display some information
about the module distribution to be installed taken from the metadata in the
setup script, let the user select a few options, and start or cancel the
installation.</p>
<p>Since the metadata is taken from the setup script, creating Windows installers
is usually as easy as running:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">bdist_wininst</span>
</pre></div>
</div>
<p>or the <strong class="command">bdist</strong> command with the <code class="xref std std-option docutils literal notranslate"><span class="pre">--formats</span></code> option:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">bdist</span> <span class="o">--</span><span class="n">formats</span><span class="o">=</span><span class="n">wininst</span>
</pre></div>
</div>
<p>If you have a pure module distribution (only containing pure Python modules and
packages), the resulting installer will be version independent and have a name
like <code class="file docutils literal notranslate"><span class="pre">foo-1.0.win32.exe</span></code>. These installers can even be created on Unix
platforms or Mac OS X.</p>
<p>If you have a non-pure distribution, the extensions can only be created on a
Windows platform, and will be Python version dependent. The installer filename
will reflect this and now has the form <code class="file docutils literal notranslate"><span class="pre">foo-1.0.win32-py2.0.exe</span></code>. You
have to create a separate installer for every Python version you want to
support.</p>
<p>The installer will try to compile pure modules into <a class="reference internal" href="../glossary.html#term-bytecode"><span class="xref std std-term">bytecode</span></a> after installation
on the target system in normal and optimizing mode. If you don’t want this to
happen for some reason, you can run the <strong class="command">bdist_wininst</strong> command with
the <code class="xref std std-option docutils literal notranslate"><span class="pre">--no-target-compile</span></code> and/or the <code class="xref std std-option docutils literal notranslate"><span class="pre">--no-target-optimize</span></code>
option.</p>
<p>By default the installer will display the cool “Python Powered” logo when it is
run, but you can also supply your own 152x261 bitmap which must be a Windows
<code class="file docutils literal notranslate"><span class="pre">.bmp</span></code> file with the <code class="xref std std-option docutils literal notranslate"><span class="pre">--bitmap</span></code> option.</p>
<p>The installer will also display a large title on the desktop background window
when it is run, which is constructed from the name of your distribution and the
version number. This can be changed to another text by using the
<code class="xref std std-option docutils literal notranslate"><span class="pre">--title</span></code> option.</p>
<p>The installer file will be written to the “distribution directory” — normally
<code class="file docutils literal notranslate"><span class="pre">dist/</span></code>, but customizable with the <code class="xref std std-option docutils literal notranslate"><span class="pre">--dist-dir</span></code> option.</p>
</div>
<div class="section" id="cross-compiling-on-windows">
<span id="cross-compile-windows"></span><h2>5.4. Cross-compiling on Windows<a class="headerlink" href="#cross-compiling-on-windows" title="Permalink to this headline">¶</a></h2>
<p>Starting with Python 2.6, distutils is capable of cross-compiling between
Windows platforms. In practice, this means that with the correct tools
installed, you can use a 32bit version of Windows to create 64bit extensions
and vice-versa.</p>
<p>To build for an alternate platform, specify the <code class="xref std std-option docutils literal notranslate"><span class="pre">--plat-name</span></code> option
to the build command. Valid values are currently ‘win32’, ‘win-amd64’ and
‘win-ia64’. For example, on a 32bit version of Windows, you could execute:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">build</span> <span class="o">--</span><span class="n">plat</span><span class="o">-</span><span class="n">name</span><span class="o">=</span><span class="n">win</span><span class="o">-</span><span class="n">amd64</span>
</pre></div>
</div>
<p>to build a 64bit version of your extension. The Windows Installers also
support this option, so the command:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">build</span> <span class="o">--</span><span class="n">plat</span><span class="o">-</span><span class="n">name</span><span class="o">=</span><span class="n">win</span><span class="o">-</span><span class="n">amd64</span> <span class="n">bdist_wininst</span>
</pre></div>
</div>
<p>would create a 64bit installation executable on your 32bit version of Windows.</p>
<p>To cross-compile, you must download the Python source code and cross-compile
Python itself for the platform you are targeting - it is not possible from a
binary installation of Python (as the .lib etc file for other platforms are
not included.) In practice, this means the user of a 32 bit operating
system will need to use Visual Studio 2008 to open the
<code class="file docutils literal notranslate"><span class="pre">PCBuild/PCbuild.sln</span></code> solution in the Python source tree and build the
“x64” configuration of the ‘pythoncore’ project before cross-compiling
extensions is possible.</p>
<p>Note that by default, Visual Studio 2008 does not install 64bit compilers or
tools. You may need to reexecute the Visual Studio setup process and select
these tools (using Control Panel->[Add/Remove] Programs is a convenient way to
check or modify your existing install.)</p>
<div class="section" id="the-postinstallation-script">
<span id="postinstallation-script"></span><h3>5.4.1. The Postinstallation script<a class="headerlink" href="#the-postinstallation-script" title="Permalink to this headline">¶</a></h3>
<p>Starting with Python 2.3, a postinstallation script can be specified with the
<code class="xref std std-option docutils literal notranslate"><span class="pre">--install-script</span></code> option. The basename of the script must be
specified, and the script filename must also be listed in the scripts argument
to the setup function.</p>
<p>This script will be run at installation time on the target system after all the
files have been copied, with <code class="docutils literal notranslate"><span class="pre">argv[1]</span></code> set to <code class="xref std std-option docutils literal notranslate"><span class="pre">-install</span></code>, and again at
uninstallation time before the files are removed with <code class="docutils literal notranslate"><span class="pre">argv[1]</span></code> set to
<code class="xref std std-option docutils literal notranslate"><span class="pre">-remove</span></code>.</p>
<p>The installation script runs embedded in the windows installer, every output
(<code class="docutils literal notranslate"><span class="pre">sys.stdout</span></code>, <code class="docutils literal notranslate"><span class="pre">sys.stderr</span></code>) is redirected into a buffer and will be
displayed in the GUI after the script has finished.</p>
<p>Some functions especially useful in this context are available as additional
built-in functions in the installation script.</p>
<dl class="function">
<dt id="directory_created">
<code class="descname">directory_created</code><span class="sig-paren">(</span><em>path</em><span class="sig-paren">)</span><a class="headerlink" href="#directory_created" title="Permalink to this definition">¶</a></dt>
<dt id="file_created">
<code class="descname">file_created</code><span class="sig-paren">(</span><em>path</em><span class="sig-paren">)</span><a class="headerlink" href="#file_created" title="Permalink to this definition">¶</a></dt>
<dd><p>These functions should be called when a directory or file is created by the
postinstall script at installation time. It will register <em>path</em> with the
uninstaller, so that it will be removed when the distribution is uninstalled.
To be safe, directories are only removed if they are empty.</p>
</dd></dl>
<dl class="function">
<dt id="get_special_folder_path">
<code class="descname">get_special_folder_path</code><span class="sig-paren">(</span><em>csidl_string</em><span class="sig-paren">)</span><a class="headerlink" href="#get_special_folder_path" title="Permalink to this definition">¶</a></dt>
<dd><p>This function can be used to retrieve special folder locations on Windows like
the Start Menu or the Desktop. It returns the full path to the folder.
<em>csidl_string</em> must be one of the following strings:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="s2">"CSIDL_APPDATA"</span>
<span class="s2">"CSIDL_COMMON_STARTMENU"</span>
<span class="s2">"CSIDL_STARTMENU"</span>
<span class="s2">"CSIDL_COMMON_DESKTOPDIRECTORY"</span>
<span class="s2">"CSIDL_DESKTOPDIRECTORY"</span>
<span class="s2">"CSIDL_COMMON_STARTUP"</span>
<span class="s2">"CSIDL_STARTUP"</span>
<span class="s2">"CSIDL_COMMON_PROGRAMS"</span>
<span class="s2">"CSIDL_PROGRAMS"</span>
<span class="s2">"CSIDL_FONTS"</span>
</pre></div>
</div>
<p>If the folder cannot be retrieved, <a class="reference internal" href="../library/exceptions.html#exceptions.OSError" title="exceptions.OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> is raised.</p>
<p>Which folders are available depends on the exact Windows version, and probably
also the configuration. For details refer to Microsoft’s documentation of the
<code class="xref c c-func docutils literal notranslate"><span class="pre">SHGetSpecialFolderPath()</span></code> function.</p>
</dd></dl>
<dl class="function">
<dt id="create_shortcut">
<code class="descname">create_shortcut</code><span class="sig-paren">(</span><em>target</em>, <em>description</em>, <em>filename</em><span class="optional">[</span>, <em>arguments</em><span class="optional">[</span>, <em>workdir</em><span class="optional">[</span>, <em>iconpath</em><span class="optional">[</span>, <em>iconindex</em><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#create_shortcut" title="Permalink to this definition">¶</a></dt>
<dd><p>This function creates a shortcut. <em>target</em> is the path to the program to be
started by the shortcut. <em>description</em> is the description of the shortcut.
<em>filename</em> is the title of the shortcut that the user will see. <em>arguments</em>
specifies the command line arguments, if any. <em>workdir</em> is the working directory
for the program. <em>iconpath</em> is the file containing the icon for the shortcut,
and <em>iconindex</em> is the index of the icon in the file <em>iconpath</em>. Again, for
details consult the Microsoft documentation for the <code class="xref py py-class docutils literal notranslate"><span class="pre">IShellLink</span></code>
interface.</p>
</dd></dl>
</div>
</div>
<div class="section" id="vista-user-access-control-uac">
<h2>5.5. Vista User Access Control (UAC)<a class="headerlink" href="#vista-user-access-control-uac" title="Permalink to this headline">¶</a></h2>
<p>Starting with Python 2.6, bdist_wininst supports a <code class="xref std std-option docutils literal notranslate"><span class="pre">--user-access-control</span></code>
option. The default is ‘none’ (meaning no UAC handling is done), and other
valid values are ‘auto’ (meaning prompt for UAC elevation if Python was
installed for all users) and ‘force’ (meaning always prompt for elevation).</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">5. Creating Built Distributions</a><ul>
<li><a class="reference internal" href="#creating-dumb-built-distributions">5.1. Creating dumb built distributions</a></li>
<li><a class="reference internal" href="#creating-rpm-packages">5.2. Creating RPM packages</a></li>
<li><a class="reference internal" href="#creating-windows-installers">5.3. Creating Windows Installers</a></li>
<li><a class="reference internal" href="#cross-compiling-on-windows">5.4. Cross-compiling on Windows</a><ul>
<li><a class="reference internal" href="#the-postinstallation-script">5.4.1. The Postinstallation script</a></li>
</ul>
</li>
<li><a class="reference internal" href="#vista-user-access-control-uac">5.5. Vista User Access Control (UAC)</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="sourcedist.html"
title="previous chapter">4. Creating a Source Distribution</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="packageindex.html"
title="next chapter">6. The Python Package Index (PyPI)</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/distutils/builtdist.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="packageindex.html" title="6. The Python Package Index (PyPI)"
>next</a> |</li>
<li class="right" >
<a href="sourcedist.html" title="4. Creating a Source Distribution"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Distributing Python Modules (Legacy version)</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\�Kg�� � html/distutils/commandref.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>9. Command Reference — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="10. API Reference" href="apiref.html" />
<link rel="prev" title="8. Extending Distutils" href="extending.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/distutils/commandref.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="apiref.html" title="10. API Reference"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="extending.html" title="8. Extending Distutils"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Distributing Python Modules (Legacy version)</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="command-reference">
<span id="reference"></span><h1>9. Command Reference<a class="headerlink" href="#command-reference" title="Permalink to this headline">¶</a></h1>
<div class="section" id="installing-modules-the-install-command-family">
<span id="install-cmd"></span><h2>9.1. Installing modules: the <strong class="command">install</strong> command family<a class="headerlink" href="#installing-modules-the-install-command-family" title="Permalink to this headline">¶</a></h2>
<p>The install command ensures that the build commands have been run and then runs
the subcommands <strong class="command">install_lib</strong>, <strong class="command">install_data</strong> and
<strong class="command">install_scripts</strong>.</p>
<div class="section" id="install-data">
<span id="install-data-cmd"></span><h3>9.1.1. <strong class="command">install_data</strong><a class="headerlink" href="#install-data" title="Permalink to this headline">¶</a></h3>
<p>This command installs all data files provided with the distribution.</p>
</div>
<div class="section" id="install-scripts">
<span id="install-scripts-cmd"></span><h3>9.1.2. <strong class="command">install_scripts</strong><a class="headerlink" href="#install-scripts" title="Permalink to this headline">¶</a></h3>
<p>This command installs all (Python) scripts in the distribution.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">9. Command Reference</a><ul>
<li><a class="reference internal" href="#installing-modules-the-install-command-family">9.1. Installing modules: the <strong class="command">install</strong> command family</a><ul>
<li><a class="reference internal" href="#install-data">9.1.1. <strong class="command">install_data</strong></a></li>
<li><a class="reference internal" href="#install-scripts">9.1.2. <strong class="command">install_scripts</strong></a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="extending.html"
title="previous chapter">8. Extending Distutils</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="apiref.html"
title="next chapter">10. API Reference</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/distutils/commandref.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="apiref.html" title="10. API Reference"
>next</a> |</li>
<li class="right" >
<a href="extending.html" title="8. Extending Distutils"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Distributing Python Modules (Legacy version)</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\i�>H >H html/distutils/configfile.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>3. Writing the Setup Configuration File — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="4. Creating a Source Distribution" href="sourcedist.html" />
<link rel="prev" title="2. Writing the Setup Script" href="setupscript.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/distutils/configfile.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="sourcedist.html" title="4. Creating a Source Distribution"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="setupscript.html" title="2. Writing the Setup Script"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Distributing Python Modules (Legacy version)</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="writing-the-setup-configuration-file">
<span id="setup-config"></span><h1>3. Writing the Setup Configuration File<a class="headerlink" href="#writing-the-setup-configuration-file" title="Permalink to this headline">¶</a></h1>
<p>Often, it’s not possible to write down everything needed to build a distribution
<em>a priori</em>: you may need to get some information from the user, or from the
user’s system, in order to proceed. As long as that information is fairly
simple—a list of directories to search for C header files or libraries, for
example—then providing a configuration file, <code class="file docutils literal notranslate"><span class="pre">setup.cfg</span></code>, for users to
edit is a cheap and easy way to solicit it. Configuration files also let you
provide default values for any command option, which the installer can then
override either on the command-line or by editing the config file.</p>
<p>The setup configuration file is a useful middle-ground between the setup script
—which, ideally, would be opaque to installers <a class="footnote-reference" href="#id2" id="id1">[1]</a>—and the command-line to
the setup script, which is outside of your control and entirely up to the
installer. In fact, <code class="file docutils literal notranslate"><span class="pre">setup.cfg</span></code> (and any other Distutils configuration
files present on the target system) are processed after the contents of the
setup script, but before the command-line. This has several useful
consequences:</p>
<ul class="simple">
<li>installers can override some of what you put in <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code> by editing
<code class="file docutils literal notranslate"><span class="pre">setup.cfg</span></code></li>
<li>you can provide non-standard defaults for options that are not easily set in
<code class="file docutils literal notranslate"><span class="pre">setup.py</span></code></li>
<li>installers can override anything in <code class="file docutils literal notranslate"><span class="pre">setup.cfg</span></code> using the command-line
options to <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code></li>
</ul>
<p>The basic syntax of the configuration file is simple:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">command</span><span class="p">]</span>
<span class="n">option</span><span class="o">=</span><span class="n">value</span>
<span class="o">...</span>
</pre></div>
</div>
<p>where <em>command</em> is one of the Distutils commands (e.g. <strong class="command">build_py</strong>,
<strong class="command">install</strong>), and <em>option</em> is one of the options that command supports.
Any number of options can be supplied for each command, and any number of
command sections can be included in the file. Blank lines are ignored, as are
comments, which run from a <code class="docutils literal notranslate"><span class="pre">'#'</span></code> character until the end of the line. Long
option values can be split across multiple lines simply by indenting the
continuation lines.</p>
<p>You can find out the list of options supported by a particular command with the
universal <code class="xref std std-option docutils literal notranslate"><span class="pre">--help</span></code> option, e.g.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">></span> <span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="o">--</span><span class="n">help</span> <span class="n">build_ext</span>
<span class="p">[</span><span class="o">...</span><span class="p">]</span>
<span class="n">Options</span> <span class="k">for</span> <span class="s1">'build_ext'</span> <span class="n">command</span><span class="p">:</span>
<span class="o">--</span><span class="n">build</span><span class="o">-</span><span class="n">lib</span> <span class="p">(</span><span class="o">-</span><span class="n">b</span><span class="p">)</span> <span class="n">directory</span> <span class="k">for</span> <span class="n">compiled</span> <span class="n">extension</span> <span class="n">modules</span>
<span class="o">--</span><span class="n">build</span><span class="o">-</span><span class="n">temp</span> <span class="p">(</span><span class="o">-</span><span class="n">t</span><span class="p">)</span> <span class="n">directory</span> <span class="k">for</span> <span class="n">temporary</span> <span class="n">files</span> <span class="p">(</span><span class="n">build</span> <span class="n">by</span><span class="o">-</span><span class="n">products</span><span class="p">)</span>
<span class="o">--</span><span class="n">inplace</span> <span class="p">(</span><span class="o">-</span><span class="n">i</span><span class="p">)</span> <span class="n">ignore</span> <span class="n">build</span><span class="o">-</span><span class="n">lib</span> <span class="ow">and</span> <span class="n">put</span> <span class="n">compiled</span> <span class="n">extensions</span> <span class="n">into</span> <span class="n">the</span>
<span class="n">source</span> <span class="n">directory</span> <span class="n">alongside</span> <span class="n">your</span> <span class="n">pure</span> <span class="n">Python</span> <span class="n">modules</span>
<span class="o">--</span><span class="n">include</span><span class="o">-</span><span class="n">dirs</span> <span class="p">(</span><span class="o">-</span><span class="n">I</span><span class="p">)</span> <span class="nb">list</span> <span class="n">of</span> <span class="n">directories</span> <span class="n">to</span> <span class="n">search</span> <span class="k">for</span> <span class="n">header</span> <span class="n">files</span>
<span class="o">--</span><span class="n">define</span> <span class="p">(</span><span class="o">-</span><span class="n">D</span><span class="p">)</span> <span class="n">C</span> <span class="n">preprocessor</span> <span class="n">macros</span> <span class="n">to</span> <span class="n">define</span>
<span class="o">--</span><span class="n">undef</span> <span class="p">(</span><span class="o">-</span><span class="n">U</span><span class="p">)</span> <span class="n">C</span> <span class="n">preprocessor</span> <span class="n">macros</span> <span class="n">to</span> <span class="n">undefine</span>
<span class="o">--</span><span class="n">swig</span><span class="o">-</span><span class="n">opts</span> <span class="nb">list</span> <span class="n">of</span> <span class="n">SWIG</span> <span class="n">command</span> <span class="n">line</span> <span class="n">options</span>
<span class="p">[</span><span class="o">...</span><span class="p">]</span>
</pre></div>
</div>
<p>Note that an option spelled <code class="xref std std-option docutils literal notranslate"><span class="pre">--foo-bar</span></code> on the command-line is spelled
<code class="docutils literal notranslate"><span class="pre">foo_bar</span></code> in configuration files.</p>
<p id="distutils-build-ext-inplace">For example, say you want your extensions to be built “in-place”—that is, you
have an extension <code class="xref py py-mod docutils literal notranslate"><span class="pre">pkg.ext</span></code>, and you want the compiled extension file
(<code class="file docutils literal notranslate"><span class="pre">ext.so</span></code> on Unix, say) to be put in the same source directory as your
pure Python modules <code class="xref py py-mod docutils literal notranslate"><span class="pre">pkg.mod1</span></code> and <code class="xref py py-mod docutils literal notranslate"><span class="pre">pkg.mod2</span></code>. You can always use the
<code class="xref std std-option docutils literal notranslate"><span class="pre">--inplace</span></code> option on the command-line to ensure this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">build_ext</span> <span class="o">--</span><span class="n">inplace</span>
</pre></div>
</div>
<p>But this requires that you always specify the <strong class="command">build_ext</strong> command
explicitly, and remember to provide <code class="xref std std-option docutils literal notranslate"><span class="pre">--inplace</span></code>. An easier way is to
“set and forget” this option, by encoding it in <code class="file docutils literal notranslate"><span class="pre">setup.cfg</span></code>, the
configuration file for this distribution:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">build_ext</span><span class="p">]</span>
<span class="n">inplace</span><span class="o">=</span><span class="mi">1</span>
</pre></div>
</div>
<p>This will affect all builds of this module distribution, whether or not you
explicitly specify <strong class="command">build_ext</strong>. If you include <code class="file docutils literal notranslate"><span class="pre">setup.cfg</span></code> in
your source distribution, it will also affect end-user builds—which is
probably a bad idea for this option, since always building extensions in-place
would break installation of the module distribution. In certain peculiar cases,
though, modules are built right in their installation directory, so this is
conceivably a useful ability. (Distributing extensions that expect to be built
in their installation directory is almost always a bad idea, though.)</p>
<p>Another example: certain commands take a lot of options that don’t change from
run to run; for example, <strong class="command">bdist_rpm</strong> needs to know everything required
to generate a “spec” file for creating an RPM distribution. Some of this
information comes from the setup script, and some is automatically generated by
the Distutils (such as the list of files installed). But some of it has to be
supplied as options to <strong class="command">bdist_rpm</strong>, which would be very tedious to do
on the command-line for every run. Hence, here is a snippet from the Distutils’
own <code class="file docutils literal notranslate"><span class="pre">setup.cfg</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">bdist_rpm</span><span class="p">]</span>
<span class="n">release</span> <span class="o">=</span> <span class="mi">1</span>
<span class="n">packager</span> <span class="o">=</span> <span class="n">Greg</span> <span class="n">Ward</span> <span class="o"><</span><span class="n">gward</span><span class="nd">@python</span><span class="o">.</span><span class="n">net</span><span class="o">></span>
<span class="n">doc_files</span> <span class="o">=</span> <span class="n">CHANGES</span><span class="o">.</span><span class="n">txt</span>
<span class="n">README</span><span class="o">.</span><span class="n">txt</span>
<span class="n">USAGE</span><span class="o">.</span><span class="n">txt</span>
<span class="n">doc</span><span class="o">/</span>
<span class="n">examples</span><span class="o">/</span>
</pre></div>
</div>
<p>Note that the <code class="docutils literal notranslate"><span class="pre">doc_files</span></code> option is simply a whitespace-separated string
split across multiple lines for readability.</p>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<dl class="last docutils">
<dt><a class="reference internal" href="../install/index.html#inst-config-syntax"><span class="std std-ref">Syntax of config files</span></a> in “Installing Python Modules”</dt>
<dd>More information on the configuration files is available in the manual for
system administrators.</dd>
</dl>
</div>
<p class="rubric">Footnotes</p>
<table class="docutils footnote" frame="void" id="id2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>This ideal probably won’t be achieved until auto-configuration is fully
supported by the Distutils.</td></tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="setupscript.html"
title="previous chapter">2. Writing the Setup Script</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="sourcedist.html"
title="next chapter">4. Creating a Source Distribution</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/distutils/configfile.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="sourcedist.html" title="4. Creating a Source Distribution"
>next</a> |</li>
<li class="right" >
<a href="setupscript.html" title="2. Writing the Setup Script"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Distributing Python Modules (Legacy version)</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\�2�Jf Jf html/distutils/examples.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>7. Examples — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="8. Extending Distutils" href="extending.html" />
<link rel="prev" title="6. The Python Package Index (PyPI)" href="packageindex.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/distutils/examples.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="extending.html" title="8. Extending Distutils"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="packageindex.html" title="6. The Python Package Index (PyPI)"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Distributing Python Modules (Legacy version)</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="examples">
<span id="id1"></span><h1>7. Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h1>
<p>This chapter provides a number of basic examples to help get started with
distutils. Additional information about using distutils can be found in the
Distutils Cookbook.</p>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<dl class="last docutils">
<dt><a class="reference external" href="https://wiki.python.org/moin/Distutils/Cookbook">Distutils Cookbook</a></dt>
<dd>Collection of recipes showing how to achieve more control over distutils.</dd>
</dl>
</div>
<div class="section" id="pure-python-distribution-by-module">
<span id="pure-mod"></span><h2>7.1. Pure Python distribution (by module)<a class="headerlink" href="#pure-python-distribution-by-module" title="Permalink to this headline">¶</a></h2>
<p>If you’re just distributing a couple of modules, especially if they don’t live
in a particular package, you can specify them individually using the
<code class="docutils literal notranslate"><span class="pre">py_modules</span></code> option in the setup script.</p>
<p>In the simplest case, you’ll have two files to worry about: a setup script and
the single module you’re distributing, <code class="file docutils literal notranslate"><span class="pre">foo.py</span></code> in this example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o"><</span><span class="n">root</span><span class="o">>/</span>
<span class="n">setup</span><span class="o">.</span><span class="n">py</span>
<span class="n">foo</span><span class="o">.</span><span class="n">py</span>
</pre></div>
</div>
<p>(In all diagrams in this section, <em><root></em> will refer to the distribution root
directory.) A minimal setup script to describe this situation would be:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">distutils.core</span> <span class="k">import</span> <span class="n">setup</span>
<span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'foo'</span><span class="p">,</span>
<span class="n">version</span><span class="o">=</span><span class="s1">'1.0'</span><span class="p">,</span>
<span class="n">py_modules</span><span class="o">=</span><span class="p">[</span><span class="s1">'foo'</span><span class="p">],</span>
<span class="p">)</span>
</pre></div>
</div>
<p>Note that the name of the distribution is specified independently with the
<code class="docutils literal notranslate"><span class="pre">name</span></code> option, and there’s no rule that says it has to be the same as
the name of the sole module in the distribution (although that’s probably a good
convention to follow). However, the distribution name is used to generate
filenames, so you should stick to letters, digits, underscores, and hyphens.</p>
<p>Since <code class="docutils literal notranslate"><span class="pre">py_modules</span></code> is a list, you can of course specify multiple
modules, eg. if you’re distributing modules <code class="xref py py-mod docutils literal notranslate"><span class="pre">foo</span></code> and <code class="xref py py-mod docutils literal notranslate"><span class="pre">bar</span></code>, your
setup might look like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o"><</span><span class="n">root</span><span class="o">>/</span>
<span class="n">setup</span><span class="o">.</span><span class="n">py</span>
<span class="n">foo</span><span class="o">.</span><span class="n">py</span>
<span class="n">bar</span><span class="o">.</span><span class="n">py</span>
</pre></div>
</div>
<p>and the setup script might be</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">distutils.core</span> <span class="k">import</span> <span class="n">setup</span>
<span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'foobar'</span><span class="p">,</span>
<span class="n">version</span><span class="o">=</span><span class="s1">'1.0'</span><span class="p">,</span>
<span class="n">py_modules</span><span class="o">=</span><span class="p">[</span><span class="s1">'foo'</span><span class="p">,</span> <span class="s1">'bar'</span><span class="p">],</span>
<span class="p">)</span>
</pre></div>
</div>
<p>You can put module source files into another directory, but if you have enough
modules to do that, it’s probably easier to specify modules by package rather
than listing them individually.</p>
</div>
<div class="section" id="pure-python-distribution-by-package">
<span id="pure-pkg"></span><h2>7.2. Pure Python distribution (by package)<a class="headerlink" href="#pure-python-distribution-by-package" title="Permalink to this headline">¶</a></h2>
<p>If you have more than a couple of modules to distribute, especially if they are
in multiple packages, it’s probably easier to specify whole packages rather than
individual modules. This works even if your modules are not in a package; you
can just tell the Distutils to process modules from the root package, and that
works the same as any other package (except that you don’t have to have an
<code class="file docutils literal notranslate"><span class="pre">__init__.py</span></code> file).</p>
<p>The setup script from the last example could also be written as</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">distutils.core</span> <span class="k">import</span> <span class="n">setup</span>
<span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'foobar'</span><span class="p">,</span>
<span class="n">version</span><span class="o">=</span><span class="s1">'1.0'</span><span class="p">,</span>
<span class="n">packages</span><span class="o">=</span><span class="p">[</span><span class="s1">''</span><span class="p">],</span>
<span class="p">)</span>
</pre></div>
</div>
<p>(The empty string stands for the root package.)</p>
<p>If those two files are moved into a subdirectory, but remain in the root
package, e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o"><</span><span class="n">root</span><span class="o">>/</span>
<span class="n">setup</span><span class="o">.</span><span class="n">py</span>
<span class="n">src</span><span class="o">/</span> <span class="n">foo</span><span class="o">.</span><span class="n">py</span>
<span class="n">bar</span><span class="o">.</span><span class="n">py</span>
</pre></div>
</div>
<p>then you would still specify the root package, but you have to tell the
Distutils where source files in the root package live:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">distutils.core</span> <span class="k">import</span> <span class="n">setup</span>
<span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'foobar'</span><span class="p">,</span>
<span class="n">version</span><span class="o">=</span><span class="s1">'1.0'</span><span class="p">,</span>
<span class="n">package_dir</span><span class="o">=</span><span class="p">{</span><span class="s1">''</span><span class="p">:</span> <span class="s1">'src'</span><span class="p">},</span>
<span class="n">packages</span><span class="o">=</span><span class="p">[</span><span class="s1">''</span><span class="p">],</span>
<span class="p">)</span>
</pre></div>
</div>
<p>More typically, though, you will want to distribute multiple modules in the same
package (or in sub-packages). For example, if the <code class="xref py py-mod docutils literal notranslate"><span class="pre">foo</span></code> and <code class="xref py py-mod docutils literal notranslate"><span class="pre">bar</span></code>
modules belong in package <code class="xref py py-mod docutils literal notranslate"><span class="pre">foobar</span></code>, one way to layout your source tree is</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o"><</span><span class="n">root</span><span class="o">>/</span>
<span class="n">setup</span><span class="o">.</span><span class="n">py</span>
<span class="n">foobar</span><span class="o">/</span>
<span class="fm">__init__</span><span class="o">.</span><span class="n">py</span>
<span class="n">foo</span><span class="o">.</span><span class="n">py</span>
<span class="n">bar</span><span class="o">.</span><span class="n">py</span>
</pre></div>
</div>
<p>This is in fact the default layout expected by the Distutils, and the one that
requires the least work to describe in your setup script:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">distutils.core</span> <span class="k">import</span> <span class="n">setup</span>
<span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'foobar'</span><span class="p">,</span>
<span class="n">version</span><span class="o">=</span><span class="s1">'1.0'</span><span class="p">,</span>
<span class="n">packages</span><span class="o">=</span><span class="p">[</span><span class="s1">'foobar'</span><span class="p">],</span>
<span class="p">)</span>
</pre></div>
</div>
<p>If you want to put modules in directories not named for their package, then you
need to use the <code class="docutils literal notranslate"><span class="pre">package_dir</span></code> option again. For example, if the
<code class="file docutils literal notranslate"><span class="pre">src</span></code> directory holds modules in the <code class="xref py py-mod docutils literal notranslate"><span class="pre">foobar</span></code> package:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o"><</span><span class="n">root</span><span class="o">>/</span>
<span class="n">setup</span><span class="o">.</span><span class="n">py</span>
<span class="n">src</span><span class="o">/</span>
<span class="fm">__init__</span><span class="o">.</span><span class="n">py</span>
<span class="n">foo</span><span class="o">.</span><span class="n">py</span>
<span class="n">bar</span><span class="o">.</span><span class="n">py</span>
</pre></div>
</div>
<p>an appropriate setup script would be</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">distutils.core</span> <span class="k">import</span> <span class="n">setup</span>
<span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'foobar'</span><span class="p">,</span>
<span class="n">version</span><span class="o">=</span><span class="s1">'1.0'</span><span class="p">,</span>
<span class="n">package_dir</span><span class="o">=</span><span class="p">{</span><span class="s1">'foobar'</span><span class="p">:</span> <span class="s1">'src'</span><span class="p">},</span>
<span class="n">packages</span><span class="o">=</span><span class="p">[</span><span class="s1">'foobar'</span><span class="p">],</span>
<span class="p">)</span>
</pre></div>
</div>
<p>Or, you might put modules from your main package right in the distribution
root:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o"><</span><span class="n">root</span><span class="o">>/</span>
<span class="n">setup</span><span class="o">.</span><span class="n">py</span>
<span class="fm">__init__</span><span class="o">.</span><span class="n">py</span>
<span class="n">foo</span><span class="o">.</span><span class="n">py</span>
<span class="n">bar</span><span class="o">.</span><span class="n">py</span>
</pre></div>
</div>
<p>in which case your setup script would be</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">distutils.core</span> <span class="k">import</span> <span class="n">setup</span>
<span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'foobar'</span><span class="p">,</span>
<span class="n">version</span><span class="o">=</span><span class="s1">'1.0'</span><span class="p">,</span>
<span class="n">package_dir</span><span class="o">=</span><span class="p">{</span><span class="s1">'foobar'</span><span class="p">:</span> <span class="s1">''</span><span class="p">},</span>
<span class="n">packages</span><span class="o">=</span><span class="p">[</span><span class="s1">'foobar'</span><span class="p">],</span>
<span class="p">)</span>
</pre></div>
</div>
<p>(The empty string also stands for the current directory.)</p>
<p>If you have sub-packages, they must be explicitly listed in <code class="docutils literal notranslate"><span class="pre">packages</span></code>,
but any entries in <code class="docutils literal notranslate"><span class="pre">package_dir</span></code> automatically extend to sub-packages.
(In other words, the Distutils does <em>not</em> scan your source tree, trying to
figure out which directories correspond to Python packages by looking for
<code class="file docutils literal notranslate"><span class="pre">__init__.py</span></code> files.) Thus, if the default layout grows a sub-package:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o"><</span><span class="n">root</span><span class="o">>/</span>
<span class="n">setup</span><span class="o">.</span><span class="n">py</span>
<span class="n">foobar</span><span class="o">/</span>
<span class="fm">__init__</span><span class="o">.</span><span class="n">py</span>
<span class="n">foo</span><span class="o">.</span><span class="n">py</span>
<span class="n">bar</span><span class="o">.</span><span class="n">py</span>
<span class="n">subfoo</span><span class="o">/</span>
<span class="fm">__init__</span><span class="o">.</span><span class="n">py</span>
<span class="n">blah</span><span class="o">.</span><span class="n">py</span>
</pre></div>
</div>
<p>then the corresponding setup script would be</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">distutils.core</span> <span class="k">import</span> <span class="n">setup</span>
<span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'foobar'</span><span class="p">,</span>
<span class="n">version</span><span class="o">=</span><span class="s1">'1.0'</span><span class="p">,</span>
<span class="n">packages</span><span class="o">=</span><span class="p">[</span><span class="s1">'foobar'</span><span class="p">,</span> <span class="s1">'foobar.subfoo'</span><span class="p">],</span>
<span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="single-extension-module">
<span id="single-ext"></span><h2>7.3. Single extension module<a class="headerlink" href="#single-extension-module" title="Permalink to this headline">¶</a></h2>
<p>Extension modules are specified using the <code class="docutils literal notranslate"><span class="pre">ext_modules</span></code> option.
<code class="docutils literal notranslate"><span class="pre">package_dir</span></code> has no effect on where extension source files are found;
it only affects the source for pure Python modules. The simplest case, a
single extension module in a single C source file, is:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o"><</span><span class="n">root</span><span class="o">>/</span>
<span class="n">setup</span><span class="o">.</span><span class="n">py</span>
<span class="n">foo</span><span class="o">.</span><span class="n">c</span>
</pre></div>
</div>
<p>If the <code class="xref py py-mod docutils literal notranslate"><span class="pre">foo</span></code> extension belongs in the root package, the setup script for
this could be</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">distutils.core</span> <span class="k">import</span> <span class="n">setup</span>
<span class="kn">from</span> <span class="nn">distutils.extension</span> <span class="k">import</span> <span class="n">Extension</span>
<span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'foobar'</span><span class="p">,</span>
<span class="n">version</span><span class="o">=</span><span class="s1">'1.0'</span><span class="p">,</span>
<span class="n">ext_modules</span><span class="o">=</span><span class="p">[</span><span class="n">Extension</span><span class="p">(</span><span class="s1">'foo'</span><span class="p">,</span> <span class="p">[</span><span class="s1">'foo.c'</span><span class="p">])],</span>
<span class="p">)</span>
</pre></div>
</div>
<p>If the extension actually belongs in a package, say <code class="xref py py-mod docutils literal notranslate"><span class="pre">foopkg</span></code>, then</p>
<p>With exactly the same source tree layout, this extension can be put in the
<code class="xref py py-mod docutils literal notranslate"><span class="pre">foopkg</span></code> package simply by changing the name of the extension:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">distutils.core</span> <span class="k">import</span> <span class="n">setup</span>
<span class="kn">from</span> <span class="nn">distutils.extension</span> <span class="k">import</span> <span class="n">Extension</span>
<span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'foobar'</span><span class="p">,</span>
<span class="n">version</span><span class="o">=</span><span class="s1">'1.0'</span><span class="p">,</span>
<span class="n">ext_modules</span><span class="o">=</span><span class="p">[</span><span class="n">Extension</span><span class="p">(</span><span class="s1">'foopkg.foo'</span><span class="p">,</span> <span class="p">[</span><span class="s1">'foo.c'</span><span class="p">])],</span>
<span class="p">)</span>
</pre></div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">7. Examples</a><ul>
<li><a class="reference internal" href="#pure-python-distribution-by-module">7.1. Pure Python distribution (by module)</a></li>
<li><a class="reference internal" href="#pure-python-distribution-by-package">7.2. Pure Python distribution (by package)</a></li>
<li><a class="reference internal" href="#single-extension-module">7.3. Single extension module</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="packageindex.html"
title="previous chapter">6. The Python Package Index (PyPI)</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="extending.html"
title="next chapter">8. Extending Distutils</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/distutils/examples.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="extending.html" title="8. Extending Distutils"
>next</a> |</li>
<li class="right" >
<a href="packageindex.html" title="6. The Python Package Index (PyPI)"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Distributing Python Modules (Legacy version)</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\9�x�7 �7 html/distutils/extending.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>8. Extending Distutils — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="9. Command Reference" href="commandref.html" />
<link rel="prev" title="7. Examples" href="examples.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/distutils/extending.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="commandref.html" title="9. Command Reference"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="examples.html" title="7. Examples"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Distributing Python Modules (Legacy version)</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="extending-distutils">
<span id="id1"></span><h1>8. Extending Distutils<a class="headerlink" href="#extending-distutils" title="Permalink to this headline">¶</a></h1>
<p>Distutils can be extended in various ways. Most extensions take the form of new
commands or replacements for existing commands. New commands may be written to
support new types of platform-specific packaging, for example, while
replacements for existing commands may be made to modify details of how the
command operates on a package.</p>
<p>Most extensions of the distutils are made within <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code> scripts that
want to modify existing commands; many simply add a few file extensions that
should be copied into packages in addition to <code class="file docutils literal notranslate"><span class="pre">.py</span></code> files as a
convenience.</p>
<p>Most distutils command implementations are subclasses of the
<a class="reference internal" href="apiref.html#distutils.cmd.Command" title="distutils.cmd.Command"><code class="xref py py-class docutils literal notranslate"><span class="pre">distutils.cmd.Command</span></code></a> class. New commands may directly inherit from
<code class="xref py py-class docutils literal notranslate"><span class="pre">Command</span></code>, while replacements often derive from <code class="xref py py-class docutils literal notranslate"><span class="pre">Command</span></code>
indirectly, directly subclassing the command they are replacing. Commands are
required to derive from <code class="xref py py-class docutils literal notranslate"><span class="pre">Command</span></code>.</p>
<div class="section" id="integrating-new-commands">
<h2>8.1. Integrating new commands<a class="headerlink" href="#integrating-new-commands" title="Permalink to this headline">¶</a></h2>
<p>There are different ways to integrate new command implementations into
distutils. The most difficult is to lobby for the inclusion of the new features
in distutils itself, and wait for (and require) a version of Python that
provides that support. This is really hard for many reasons.</p>
<p>The most common, and possibly the most reasonable for most needs, is to include
the new implementations with your <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code> script, and cause the
<a class="reference internal" href="apiref.html#distutils.core.setup" title="distutils.core.setup"><code class="xref py py-func docutils literal notranslate"><span class="pre">distutils.core.setup()</span></code></a> function use them:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">distutils.command.build_py</span> <span class="k">import</span> <span class="n">build_py</span> <span class="k">as</span> <span class="n">_build_py</span>
<span class="kn">from</span> <span class="nn">distutils.core</span> <span class="k">import</span> <span class="n">setup</span>
<span class="k">class</span> <span class="nc">build_py</span><span class="p">(</span><span class="n">_build_py</span><span class="p">):</span>
<span class="sd">"""Specialized Python source builder."""</span>
<span class="c1"># implement whatever needs to be different...</span>
<span class="n">setup</span><span class="p">(</span><span class="n">cmdclass</span><span class="o">=</span><span class="p">{</span><span class="s1">'build_py'</span><span class="p">:</span> <span class="n">build_py</span><span class="p">},</span>
<span class="o">...</span><span class="p">)</span>
</pre></div>
</div>
<p>This approach is most valuable if the new implementations must be used to use a
particular package, as everyone interested in the package will need to have the
new command implementation.</p>
<p>Beginning with Python 2.4, a third option is available, intended to allow new
commands to be added which can support existing <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code> scripts without
requiring modifications to the Python installation. This is expected to allow
third-party extensions to provide support for additional packaging systems, but
the commands can be used for anything distutils commands can be used for. A new
configuration option, <code class="docutils literal notranslate"><span class="pre">command_packages</span></code> (command-line option
<code class="xref std std-option docutils literal notranslate"><span class="pre">--command-packages</span></code>), can be used to specify additional packages to be
searched for modules implementing commands. Like all distutils options, this
can be specified on the command line or in a configuration file. This option
can only be set in the <code class="docutils literal notranslate"><span class="pre">[global]</span></code> section of a configuration file, or before
any commands on the command line. If set in a configuration file, it can be
overridden from the command line; setting it to an empty string on the command
line causes the default to be used. This should never be set in a configuration
file provided with a package.</p>
<p>This new option can be used to add any number of packages to the list of
packages searched for command implementations; multiple package names should be
separated by commas. When not specified, the search is only performed in the
<a class="reference internal" href="apiref.html#module-distutils.command" title="distutils.command: This subpackage contains one module for each standard Distutils command."><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command</span></code></a> package. When <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code> is run with the option
<code class="docutils literal notranslate"><span class="pre">--command-packages</span> <span class="pre">distcmds,buildcmds</span></code>, however, the packages
<a class="reference internal" href="apiref.html#module-distutils.command" title="distutils.command: This subpackage contains one module for each standard Distutils command."><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.command</span></code></a>, <code class="xref py py-mod docutils literal notranslate"><span class="pre">distcmds</span></code>, and <code class="xref py py-mod docutils literal notranslate"><span class="pre">buildcmds</span></code> will be searched
in that order. New commands are expected to be implemented in modules of the
same name as the command by classes sharing the same name. Given the example
command line option above, the command <strong class="command">bdist_openpkg</strong> could be
implemented by the class <code class="xref py py-class docutils literal notranslate"><span class="pre">distcmds.bdist_openpkg.bdist_openpkg</span></code> or
<code class="xref py py-class docutils literal notranslate"><span class="pre">buildcmds.bdist_openpkg.bdist_openpkg</span></code>.</p>
</div>
<div class="section" id="adding-new-distribution-types">
<h2>8.2. Adding new distribution types<a class="headerlink" href="#adding-new-distribution-types" title="Permalink to this headline">¶</a></h2>
<p>Commands that create distributions (files in the <code class="file docutils literal notranslate"><span class="pre">dist/</span></code> directory) need
to add <code class="docutils literal notranslate"><span class="pre">(command,</span> <span class="pre">filename)</span></code> pairs to <code class="docutils literal notranslate"><span class="pre">self.distribution.dist_files</span></code> so that
<strong class="command">upload</strong> can upload it to PyPI. The <em>filename</em> in the pair contains no
path information, only the name of the file itself. In dry-run mode, pairs
should still be added to represent what would have been created.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">8. Extending Distutils</a><ul>
<li><a class="reference internal" href="#integrating-new-commands">8.1. Integrating new commands</a></li>
<li><a class="reference internal" href="#adding-new-distribution-types">8.2. Adding new distribution types</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="examples.html"
title="previous chapter">7. Examples</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="commandref.html"
title="next chapter">9. Command Reference</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/distutils/extending.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="commandref.html" title="9. Command Reference"
>next</a> |</li>
<li class="right" >
<a href="examples.html" title="7. Examples"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Distributing Python Modules (Legacy version)</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\9�0([a [a html/distutils/index.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Distributing Python Modules (Legacy version) — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="1. An Introduction to Distutils" href="introduction.html" />
<link rel="prev" title="History and License" href="../license.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/distutils/index.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="introduction.html" title="1. An Introduction to Distutils"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="../license.html" title="History and License"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="distributing-python-modules-legacy-version">
<span id="distutils-index"></span><h1>Distributing Python Modules (Legacy version)<a class="headerlink" href="#distributing-python-modules-legacy-version" title="Permalink to this headline">¶</a></h1>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Authors:</th><td class="field-body">Greg Ward, Anthony Baxter</td>
</tr>
<tr class="field-even field"><th class="field-name">Email:</th><td class="field-body"><a class="reference external" href="mailto:distutils-sig%40python.org">distutils-sig<span>@</span>python<span>.</span>org</a></td>
</tr>
</tbody>
</table>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<dl class="last docutils">
<dt><a class="reference internal" href="../distributing/index.html#distributing-index"><span class="std std-ref">Distributing Python Modules</span></a></dt>
<dd>The up to date module distribution documentations</dd>
</dl>
</div>
<p>This document describes the Python Distribution Utilities (“Distutils”) from
the module developer’s point of view, describing how to use the Distutils to
make Python modules and extensions easily available to a wider audience with
very little overhead for build/release/install mechanics.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This guide only covers the basic tools for building and distributing
extensions that are provided as part of this version of Python. Third party
tools offer easier to use and more secure alternatives. Refer to the <a class="reference external" href="https://packaging.python.org/en/latest/current/">quick
recommendations section</a>
in the Python Packaging User Guide for more information.</p>
</div>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="introduction.html">1. An Introduction to Distutils</a><ul>
<li class="toctree-l2"><a class="reference internal" href="introduction.html#concepts-terminology">1.1. Concepts & Terminology</a></li>
<li class="toctree-l2"><a class="reference internal" href="introduction.html#a-simple-example">1.2. A Simple Example</a></li>
<li class="toctree-l2"><a class="reference internal" href="introduction.html#general-python-terminology">1.3. General Python terminology</a></li>
<li class="toctree-l2"><a class="reference internal" href="introduction.html#distutils-specific-terminology">1.4. Distutils-specific terminology</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="setupscript.html">2. Writing the Setup Script</a><ul>
<li class="toctree-l2"><a class="reference internal" href="setupscript.html#listing-whole-packages">2.1. Listing whole packages</a></li>
<li class="toctree-l2"><a class="reference internal" href="setupscript.html#listing-individual-modules">2.2. Listing individual modules</a></li>
<li class="toctree-l2"><a class="reference internal" href="setupscript.html#describing-extension-modules">2.3. Describing extension modules</a></li>
<li class="toctree-l2"><a class="reference internal" href="setupscript.html#relationships-between-distributions-and-packages">2.4. Relationships between Distributions and Packages</a></li>
<li class="toctree-l2"><a class="reference internal" href="setupscript.html#installing-scripts">2.5. Installing Scripts</a></li>
<li class="toctree-l2"><a class="reference internal" href="setupscript.html#installing-package-data">2.6. Installing Package Data</a></li>
<li class="toctree-l2"><a class="reference internal" href="setupscript.html#installing-additional-files">2.7. Installing Additional Files</a></li>
<li class="toctree-l2"><a class="reference internal" href="setupscript.html#additional-meta-data">2.8. Additional meta-data</a></li>
<li class="toctree-l2"><a class="reference internal" href="setupscript.html#debugging-the-setup-script">2.9. Debugging the setup script</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="configfile.html">3. Writing the Setup Configuration File</a></li>
<li class="toctree-l1"><a class="reference internal" href="sourcedist.html">4. Creating a Source Distribution</a><ul>
<li class="toctree-l2"><a class="reference internal" href="sourcedist.html#specifying-the-files-to-distribute">4.1. Specifying the files to distribute</a></li>
<li class="toctree-l2"><a class="reference internal" href="sourcedist.html#manifest-related-options">4.2. Manifest-related options</a></li>
<li class="toctree-l2"><a class="reference internal" href="sourcedist.html#the-manifest-in-template">4.3. The MANIFEST.in template</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="builtdist.html">5. Creating Built Distributions</a><ul>
<li class="toctree-l2"><a class="reference internal" href="builtdist.html#creating-dumb-built-distributions">5.1. Creating dumb built distributions</a></li>
<li class="toctree-l2"><a class="reference internal" href="builtdist.html#creating-rpm-packages">5.2. Creating RPM packages</a></li>
<li class="toctree-l2"><a class="reference internal" href="builtdist.html#creating-windows-installers">5.3. Creating Windows Installers</a></li>
<li class="toctree-l2"><a class="reference internal" href="builtdist.html#cross-compiling-on-windows">5.4. Cross-compiling on Windows</a></li>
<li class="toctree-l2"><a class="reference internal" href="builtdist.html#vista-user-access-control-uac">5.5. Vista User Access Control (UAC)</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="packageindex.html">6. The Python Package Index (PyPI)</a><ul>
<li class="toctree-l2"><a class="reference internal" href="packageindex.html#pypi-overview">6.1. PyPI overview</a></li>
<li class="toctree-l2"><a class="reference internal" href="packageindex.html#distutils-commands">6.2. Distutils commands</a></li>
<li class="toctree-l2"><a class="reference internal" href="packageindex.html#pypi-package-display">6.3. PyPI package display</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="examples.html">7. Examples</a><ul>
<li class="toctree-l2"><a class="reference internal" href="examples.html#pure-python-distribution-by-module">7.1. Pure Python distribution (by module)</a></li>
<li class="toctree-l2"><a class="reference internal" href="examples.html#pure-python-distribution-by-package">7.2. Pure Python distribution (by package)</a></li>
<li class="toctree-l2"><a class="reference internal" href="examples.html#single-extension-module">7.3. Single extension module</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="extending.html">8. Extending Distutils</a><ul>
<li class="toctree-l2"><a class="reference internal" href="extending.html#integrating-new-commands">8.1. Integrating new commands</a></li>
<li class="toctree-l2"><a class="reference internal" href="extending.html#adding-new-distribution-types">8.2. Adding new distribution types</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="commandref.html">9. Command Reference</a><ul>
<li class="toctree-l2"><a class="reference internal" href="commandref.html#installing-modules-the-install-command-family">9.1. Installing modules: the <strong class="command">install</strong> command family</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="apiref.html">10. API Reference</a><ul>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.core">10.1. <code class="docutils literal notranslate"><span class="pre">distutils.core</span></code> — Core Distutils functionality</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.ccompiler">10.2. <code class="docutils literal notranslate"><span class="pre">distutils.ccompiler</span></code> — CCompiler base class</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.unixccompiler">10.3. <code class="docutils literal notranslate"><span class="pre">distutils.unixccompiler</span></code> — Unix C Compiler</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.msvccompiler">10.4. <code class="docutils literal notranslate"><span class="pre">distutils.msvccompiler</span></code> — Microsoft Compiler</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.bcppcompiler">10.5. <code class="docutils literal notranslate"><span class="pre">distutils.bcppcompiler</span></code> — Borland Compiler</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.cygwinccompiler">10.6. <code class="docutils literal notranslate"><span class="pre">distutils.cygwincompiler</span></code> — Cygwin Compiler</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.emxccompiler">10.7. <code class="docutils literal notranslate"><span class="pre">distutils.emxccompiler</span></code> — OS/2 EMX Compiler</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.archive_util">10.8. <code class="docutils literal notranslate"><span class="pre">distutils.archive_util</span></code> — Archiving utilities</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.dep_util">10.9. <code class="docutils literal notranslate"><span class="pre">distutils.dep_util</span></code> — Dependency checking</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.dir_util">10.10. <code class="docutils literal notranslate"><span class="pre">distutils.dir_util</span></code> — Directory tree operations</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.file_util">10.11. <code class="docutils literal notranslate"><span class="pre">distutils.file_util</span></code> — Single file operations</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.util">10.12. <code class="docutils literal notranslate"><span class="pre">distutils.util</span></code> — Miscellaneous other utility functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.dist">10.13. <code class="docutils literal notranslate"><span class="pre">distutils.dist</span></code> — The Distribution class</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.extension">10.14. <code class="docutils literal notranslate"><span class="pre">distutils.extension</span></code> — The Extension class</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.debug">10.15. <code class="docutils literal notranslate"><span class="pre">distutils.debug</span></code> — Distutils debug mode</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.errors">10.16. <code class="docutils literal notranslate"><span class="pre">distutils.errors</span></code> — Distutils exceptions</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.fancy_getopt">10.17. <code class="docutils literal notranslate"><span class="pre">distutils.fancy_getopt</span></code> — Wrapper around the standard getopt module</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.filelist">10.18. <code class="docutils literal notranslate"><span class="pre">distutils.filelist</span></code> — The FileList class</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.log">10.19. <code class="docutils literal notranslate"><span class="pre">distutils.log</span></code> — Simple PEP 282-style logging</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.spawn">10.20. <code class="docutils literal notranslate"><span class="pre">distutils.spawn</span></code> — Spawn a sub-process</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.sysconfig">10.21. <code class="docutils literal notranslate"><span class="pre">distutils.sysconfig</span></code> — System configuration information</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.text_file">10.22. <code class="docutils literal notranslate"><span class="pre">distutils.text_file</span></code> — The TextFile class</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.version">10.23. <code class="docutils literal notranslate"><span class="pre">distutils.version</span></code> — Version number classes</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.cmd">10.24. <code class="docutils literal notranslate"><span class="pre">distutils.cmd</span></code> — Abstract base class for Distutils commands</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#creating-a-new-distutils-command">10.25. Creating a new Distutils command</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command">10.26. <code class="docutils literal notranslate"><span class="pre">distutils.command</span></code> — Individual Distutils commands</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command.bdist">10.27. <code class="docutils literal notranslate"><span class="pre">distutils.command.bdist</span></code> — Build a binary installer</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command.bdist_packager">10.28. <code class="docutils literal notranslate"><span class="pre">distutils.command.bdist_packager</span></code> — Abstract base class for packagers</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command.bdist_dumb">10.29. <code class="docutils literal notranslate"><span class="pre">distutils.command.bdist_dumb</span></code> — Build a “dumb” installer</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command.bdist_msi">10.30. <code class="docutils literal notranslate"><span class="pre">distutils.command.bdist_msi</span></code> — Build a Microsoft Installer binary package</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command.bdist_rpm">10.31. <code class="docutils literal notranslate"><span class="pre">distutils.command.bdist_rpm</span></code> — Build a binary distribution as a Redhat RPM and SRPM</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command.bdist_wininst">10.32. <code class="docutils literal notranslate"><span class="pre">distutils.command.bdist_wininst</span></code> — Build a Windows installer</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command.sdist">10.33. <code class="docutils literal notranslate"><span class="pre">distutils.command.sdist</span></code> — Build a source distribution</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command.build">10.34. <code class="docutils literal notranslate"><span class="pre">distutils.command.build</span></code> — Build all files of a package</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command.build_clib">10.35. <code class="docutils literal notranslate"><span class="pre">distutils.command.build_clib</span></code> — Build any C libraries in a package</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command.build_ext">10.36. <code class="docutils literal notranslate"><span class="pre">distutils.command.build_ext</span></code> — Build any extensions in a package</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command.build_py">10.37. <code class="docutils literal notranslate"><span class="pre">distutils.command.build_py</span></code> — Build the .py/.pyc files of a package</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command.build_scripts">10.38. <code class="docutils literal notranslate"><span class="pre">distutils.command.build_scripts</span></code> — Build the scripts of a package</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command.clean">10.39. <code class="docutils literal notranslate"><span class="pre">distutils.command.clean</span></code> — Clean a package build area</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command.config">10.40. <code class="docutils literal notranslate"><span class="pre">distutils.command.config</span></code> — Perform package configuration</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command.install">10.41. <code class="docutils literal notranslate"><span class="pre">distutils.command.install</span></code> — Install a package</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command.install_data">10.42. <code class="docutils literal notranslate"><span class="pre">distutils.command.install_data</span></code> — Install data files from a package</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command.install_headers">10.43. <code class="docutils literal notranslate"><span class="pre">distutils.command.install_headers</span></code> — Install C/C++ header files from a package</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command.install_lib">10.44. <code class="docutils literal notranslate"><span class="pre">distutils.command.install_lib</span></code> — Install library files from a package</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command.install_scripts">10.45. <code class="docutils literal notranslate"><span class="pre">distutils.command.install_scripts</span></code> — Install script files from a package</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command.register">10.46. <code class="docutils literal notranslate"><span class="pre">distutils.command.register</span></code> — Register a module with the Python Package Index</a></li>
<li class="toctree-l2"><a class="reference internal" href="apiref.html#module-distutils.command.check">10.47. <code class="docutils literal notranslate"><span class="pre">distutils.command.check</span></code> — Check the meta-data of a package</a></li>
</ul>
</li>
</ul>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="../license.html"
title="previous chapter">History and License</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="introduction.html"
title="next chapter">1. An Introduction to Distutils</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/distutils/index.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="introduction.html" title="1. An Introduction to Distutils"
>next</a> |</li>
<li class="right" >
<a href="../license.html" title="History and License"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\49�P �P html/distutils/introduction.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>1. An Introduction to Distutils — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="2. Writing the Setup Script" href="setupscript.html" />
<link rel="prev" title="Distributing Python Modules (Legacy version)" href="index.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/distutils/introduction.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="setupscript.html" title="2. Writing the Setup Script"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="index.html" title="Distributing Python Modules (Legacy version)"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Distributing Python Modules (Legacy version)</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="an-introduction-to-distutils">
<span id="distutils-intro"></span><h1>1. An Introduction to Distutils<a class="headerlink" href="#an-introduction-to-distutils" title="Permalink to this headline">¶</a></h1>
<p>This document covers using the Distutils to distribute your Python modules,
concentrating on the role of developer/distributor: if you’re looking for
information on installing Python modules, you should refer to the
<a class="reference internal" href="../install/index.html#install-index"><span class="std std-ref">Installing Python Modules (Legacy version)</span></a> chapter.</p>
<div class="section" id="concepts-terminology">
<span id="distutils-concepts"></span><h2>1.1. Concepts & Terminology<a class="headerlink" href="#concepts-terminology" title="Permalink to this headline">¶</a></h2>
<p>Using the Distutils is quite simple, both for module developers and for
users/administrators installing third-party modules. As a developer, your
responsibilities (apart from writing solid, well-documented and well-tested
code, of course!) are:</p>
<ul class="simple">
<li>write a setup script (<code class="file docutils literal notranslate"><span class="pre">setup.py</span></code> by convention)</li>
<li>(optional) write a setup configuration file</li>
<li>create a source distribution</li>
<li>(optional) create one or more built (binary) distributions</li>
</ul>
<p>Each of these tasks is covered in this document.</p>
<p>Not all module developers have access to a multitude of platforms, so it’s not
always feasible to expect them to create a multitude of built distributions. It
is hoped that a class of intermediaries, called <em>packagers</em>, will arise to
address this need. Packagers will take source distributions released by module
developers, build them on one or more platforms, and release the resulting built
distributions. Thus, users on the most popular platforms will be able to
install most popular Python module distributions in the most natural way for
their platform, without having to run a single setup script or compile a line of
code.</p>
</div>
<div class="section" id="a-simple-example">
<span id="distutils-simple-example"></span><h2>1.2. A Simple Example<a class="headerlink" href="#a-simple-example" title="Permalink to this headline">¶</a></h2>
<p>The setup script is usually quite simple, although since it’s written in Python,
there are no arbitrary limits to what you can do with it, though you should be
careful about putting arbitrarily expensive operations in your setup script.
Unlike, say, Autoconf-style configure scripts, the setup script may be run
multiple times in the course of building and installing your module
distribution.</p>
<p>If all you want to do is distribute a module called <code class="xref py py-mod docutils literal notranslate"><span class="pre">foo</span></code>, contained in a
file <code class="file docutils literal notranslate"><span class="pre">foo.py</span></code>, then your setup script can be as simple as this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">distutils.core</span> <span class="k">import</span> <span class="n">setup</span>
<span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'foo'</span><span class="p">,</span>
<span class="n">version</span><span class="o">=</span><span class="s1">'1.0'</span><span class="p">,</span>
<span class="n">py_modules</span><span class="o">=</span><span class="p">[</span><span class="s1">'foo'</span><span class="p">],</span>
<span class="p">)</span>
</pre></div>
</div>
<p>Some observations:</p>
<ul class="simple">
<li>most information that you supply to the Distutils is supplied as keyword
arguments to the <code class="xref py py-func docutils literal notranslate"><span class="pre">setup()</span></code> function</li>
<li>those keyword arguments fall into two categories: package metadata (name,
version number) and information about what’s in the package (a list of pure
Python modules, in this case)</li>
<li>modules are specified by module name, not filename (the same will hold true
for packages and extensions)</li>
<li>it’s recommended that you supply a little more metadata, in particular your
name, email address and a URL for the project (see section <a class="reference internal" href="setupscript.html#setup-script"><span class="std std-ref">Writing the Setup Script</span></a>
for an example)</li>
</ul>
<p>To create a source distribution for this module, you would create a setup
script, <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code>, containing the above code, and run this command from a
terminal:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">sdist</span>
</pre></div>
</div>
<p>For Windows, open a command prompt windows (<span class="menuselection">Start ‣
Accessories</span>) and change the command to:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">sdist</span>
</pre></div>
</div>
<p><strong class="command">sdist</strong> will create an archive file (e.g., tarball on Unix, ZIP file on Windows)
containing your setup script <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code>, and your module <code class="file docutils literal notranslate"><span class="pre">foo.py</span></code>.
The archive file will be named <code class="file docutils literal notranslate"><span class="pre">foo-1.0.tar.gz</span></code> (or <code class="file docutils literal notranslate"><span class="pre">.zip</span></code>), and
will unpack into a directory <code class="file docutils literal notranslate"><span class="pre">foo-1.0</span></code>.</p>
<p>If an end-user wishes to install your <code class="xref py py-mod docutils literal notranslate"><span class="pre">foo</span></code> module, all they have to do is
download <code class="file docutils literal notranslate"><span class="pre">foo-1.0.tar.gz</span></code> (or <code class="file docutils literal notranslate"><span class="pre">.zip</span></code>), unpack it, and—from the
<code class="file docutils literal notranslate"><span class="pre">foo-1.0</span></code> directory—run</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">install</span>
</pre></div>
</div>
<p>which will ultimately copy <code class="file docutils literal notranslate"><span class="pre">foo.py</span></code> to the appropriate directory for
third-party modules in their Python installation.</p>
<p>This simple example demonstrates some fundamental concepts of the Distutils.
First, both developers and installers have the same basic user interface, i.e.
the setup script. The difference is which Distutils <em>commands</em> they use: the
<strong class="command">sdist</strong> command is almost exclusively for module developers, while
<strong class="command">install</strong> is more often for installers (although most developers will
want to install their own code occasionally).</p>
<p>If you want to make things really easy for your users, you can create one or
more built distributions for them. For instance, if you are running on a
Windows machine, and want to make things easy for other Windows users, you can
create an executable installer (the most appropriate type of built distribution
for this platform) with the <strong class="command">bdist_wininst</strong> command. For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">bdist_wininst</span>
</pre></div>
</div>
<p>will create an executable installer, <code class="file docutils literal notranslate"><span class="pre">foo-1.0.win32.exe</span></code>, in the current
directory.</p>
<p>Other useful built distribution formats are RPM, implemented by the
<strong class="command">bdist_rpm</strong> command, Solaris <strong class="program">pkgtool</strong>
(<strong class="command">bdist_pkgtool</strong>), and HP-UX <strong class="program">swinstall</strong>
(<strong class="command">bdist_sdux</strong>). For example, the following command will create an RPM
file called <code class="file docutils literal notranslate"><span class="pre">foo-1.0.noarch.rpm</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">bdist_rpm</span>
</pre></div>
</div>
<p>(The <strong class="command">bdist_rpm</strong> command uses the <strong class="command">rpm</strong> executable, therefore
this has to be run on an RPM-based system such as Red Hat Linux, SuSE Linux, or
Mandrake Linux.)</p>
<p>You can find out what distribution formats are available at any time by running</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">bdist</span> <span class="o">--</span><span class="n">help</span><span class="o">-</span><span class="n">formats</span>
</pre></div>
</div>
</div>
<div class="section" id="general-python-terminology">
<span id="python-terms"></span><h2>1.3. General Python terminology<a class="headerlink" href="#general-python-terminology" title="Permalink to this headline">¶</a></h2>
<p>If you’re reading this document, you probably have a good idea of what modules,
extensions, and so forth are. Nevertheless, just to be sure that everyone is
operating from a common starting point, we offer the following glossary of
common Python terms:</p>
<dl class="docutils">
<dt>module</dt>
<dd>the basic unit of code reusability in Python: a block of code imported by some
other code. Three types of modules concern us here: pure Python modules,
extension modules, and packages.</dd>
<dt>pure Python module</dt>
<dd>a module written in Python and contained in a single <code class="file docutils literal notranslate"><span class="pre">.py</span></code> file (and
possibly associated <code class="file docutils literal notranslate"><span class="pre">.pyc</span></code> and/or <code class="file docutils literal notranslate"><span class="pre">.pyo</span></code> files). Sometimes referred
to as a “pure module.”</dd>
<dt>extension module</dt>
<dd>a module written in the low-level language of the Python implementation: C/C++
for Python, Java for Jython. Typically contained in a single dynamically
loadable pre-compiled file, e.g. a shared object (<code class="file docutils literal notranslate"><span class="pre">.so</span></code>) file for Python
extensions on Unix, a DLL (given the <code class="file docutils literal notranslate"><span class="pre">.pyd</span></code> extension) for Python
extensions on Windows, or a Java class file for Jython extensions. (Note that
currently, the Distutils only handles C/C++ extensions for Python.)</dd>
<dt>package</dt>
<dd>a module that contains other modules; typically contained in a directory in the
filesystem and distinguished from other directories by the presence of a file
<code class="file docutils literal notranslate"><span class="pre">__init__.py</span></code>.</dd>
<dt>root package</dt>
<dd>the root of the hierarchy of packages. (This isn’t really a package, since it
doesn’t have an <code class="file docutils literal notranslate"><span class="pre">__init__.py</span></code> file. But we have to call it something.)
The vast majority of the standard library is in the root package, as are many
small, standalone third-party modules that don’t belong to a larger module
collection. Unlike regular packages, modules in the root package can be found in
many directories: in fact, every directory listed in <code class="docutils literal notranslate"><span class="pre">sys.path</span></code> contributes
modules to the root package.</dd>
</dl>
</div>
<div class="section" id="distutils-specific-terminology">
<span id="distutils-term"></span><h2>1.4. Distutils-specific terminology<a class="headerlink" href="#distutils-specific-terminology" title="Permalink to this headline">¶</a></h2>
<p>The following terms apply more specifically to the domain of distributing Python
modules using the Distutils:</p>
<dl class="docutils">
<dt>module distribution</dt>
<dd>a collection of Python modules distributed together as a single downloadable
resource and meant to be installed <em>en masse</em>. Examples of some well-known
module distributions are Numeric Python, PyXML, Pillow,
or mxBase. (This would be called a <em>package</em>, except that term is
already taken in the Python context: a single module distribution may contain
zero, one, or many Python packages.)</dd>
<dt>pure module distribution</dt>
<dd>a module distribution that contains only pure Python modules and packages.
Sometimes referred to as a “pure distribution.”</dd>
<dt>non-pure module distribution</dt>
<dd>a module distribution that contains at least one extension module. Sometimes
referred to as a “non-pure distribution.”</dd>
<dt>distribution root</dt>
<dd>the top-level directory of your source tree (or source distribution); the
directory where <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code> exists. Generally <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code> will be
run from this directory.</dd>
</dl>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">1. An Introduction to Distutils</a><ul>
<li><a class="reference internal" href="#concepts-terminology">1.1. Concepts & Terminology</a></li>
<li><a class="reference internal" href="#a-simple-example">1.2. A Simple Example</a></li>
<li><a class="reference internal" href="#general-python-terminology">1.3. General Python terminology</a></li>
<li><a class="reference internal" href="#distutils-specific-terminology">1.4. Distutils-specific terminology</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="index.html"
title="previous chapter">Distributing Python Modules (Legacy version)</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="setupscript.html"
title="next chapter">2. Writing the Setup Script</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/distutils/introduction.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="setupscript.html" title="2. Writing the Setup Script"
>next</a> |</li>
<li class="right" >
<a href="index.html" title="Distributing Python Modules (Legacy version)"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Distributing Python Modules (Legacy version)</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\>$�f �f html/distutils/packageindex.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>6. The Python Package Index (PyPI) — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="7. Examples" href="examples.html" />
<link rel="prev" title="5. Creating Built Distributions" href="builtdist.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/distutils/packageindex.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="examples.html" title="7. Examples"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="builtdist.html" title="5. Creating Built Distributions"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Distributing Python Modules (Legacy version)</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="the-python-package-index-pypi">
<span id="package-index"></span><span id="index-0"></span><h1>6. The Python Package Index (PyPI)<a class="headerlink" href="#the-python-package-index-pypi" title="Permalink to this headline">¶</a></h1>
<p>The <a class="reference external" href="https://pypi.org">Python Package Index (PyPI)</a> stores <a class="reference internal" href="setupscript.html#meta-data"><span class="std std-ref">meta-data</span></a>
describing distributions packaged with distutils, as well as package data like
distribution files if a package author wishes.</p>
<p>Distutils provides the <strong class="command">register</strong> and <strong class="command">upload</strong> commands for
pushing meta-data and distribution files to PyPI, respectively. See
<a class="reference internal" href="#package-commands"><span class="std std-ref">Distutils commands</span></a> for information on these commands.</p>
<div class="section" id="pypi-overview">
<h2>6.1. PyPI overview<a class="headerlink" href="#pypi-overview" title="Permalink to this headline">¶</a></h2>
<p>PyPI lets you submit any number of versions of your distribution to the index.
If you alter the meta-data for a particular version, you can submit it again
and the index will be updated.</p>
<p>PyPI holds a record for each (name, version) combination submitted. The first
user to submit information for a given name is designated the Owner of that
name. Changes can be submitted through the <strong class="command">register</strong> command or
through the web interface. Owners can designate other users as Owners or
Maintainers. Maintainers can edit the package information, but not designate
new Owners or Maintainers.</p>
<p>By default PyPI displays only the newest version of a given package. The web
interface lets one change this default behavior and manually select which
versions to display and hide.</p>
<p>For each version, PyPI displays a home page. The home page is created from
the <code class="docutils literal notranslate"><span class="pre">long_description</span></code> which can be submitted via the <strong class="command">register</strong>
command. See <a class="reference internal" href="#package-display"><span class="std std-ref">PyPI package display</span></a> for more information.</p>
</div>
<div class="section" id="distutils-commands">
<span id="package-commands"></span><h2>6.2. Distutils commands<a class="headerlink" href="#distutils-commands" title="Permalink to this headline">¶</a></h2>
<p>Distutils exposes two commands for submitting package data to PyPI: the
<a class="reference internal" href="#package-register"><span class="std std-ref">register</span></a> command for submitting meta-data to PyPI
and the <a class="reference internal" href="#package-upload"><span class="std std-ref">upload</span></a> command for submitting distribution
files. Both commands read configuration data from a special file called a
<a class="reference internal" href="#pypirc"><span class="std std-ref">.pypirc file</span></a>.</p>
<div class="section" id="the-register-command">
<span id="package-register"></span><h3>6.2.1. The <code class="docutils literal notranslate"><span class="pre">register</span></code> command<a class="headerlink" href="#the-register-command" title="Permalink to this headline">¶</a></h3>
<p>The distutils command <strong class="command">register</strong> is used to submit your distribution’s
meta-data to an index server. It is invoked as follows:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">register</span>
</pre></div>
</div>
<p>Distutils will respond with the following prompt:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">running</span> <span class="n">register</span>
<span class="n">We</span> <span class="n">need</span> <span class="n">to</span> <span class="n">know</span> <span class="n">who</span> <span class="n">you</span> <span class="n">are</span><span class="p">,</span> <span class="n">so</span> <span class="n">please</span> <span class="n">choose</span> <span class="n">either</span><span class="p">:</span>
<span class="mf">1.</span> <span class="n">use</span> <span class="n">your</span> <span class="n">existing</span> <span class="n">login</span><span class="p">,</span>
<span class="mf">2.</span> <span class="n">register</span> <span class="k">as</span> <span class="n">a</span> <span class="n">new</span> <span class="n">user</span><span class="p">,</span>
<span class="mf">3.</span> <span class="n">have</span> <span class="n">the</span> <span class="n">server</span> <span class="n">generate</span> <span class="n">a</span> <span class="n">new</span> <span class="n">password</span> <span class="k">for</span> <span class="n">you</span> <span class="p">(</span><span class="ow">and</span> <span class="n">email</span> <span class="n">it</span> <span class="n">to</span> <span class="n">you</span><span class="p">),</span> <span class="ow">or</span>
<span class="mf">4.</span> <span class="n">quit</span>
<span class="n">Your</span> <span class="n">selection</span> <span class="p">[</span><span class="n">default</span> <span class="mi">1</span><span class="p">]:</span>
</pre></div>
</div>
<p>Note: if your username and password are saved locally, you will not see this
menu. Also, refer to <a class="reference internal" href="#pypirc"><span class="std std-ref">The .pypirc file</span></a> for how to store your credentials in a
<code class="file docutils literal notranslate"><span class="pre">.pypirc</span></code> file.</p>
<p>If you have not registered with PyPI, then you will need to do so now. You
should choose option 2, and enter your details as required. Soon after
submitting your details, you will receive an email which will be used to confirm
your registration.</p>
<p>Once you are registered, you may choose option 1 from the menu. You will be
prompted for your PyPI username and password, and <strong class="command">register</strong> will then
submit your meta-data to the index.</p>
<p>See <a class="reference internal" href="#package-cmdoptions"><span class="std std-ref">Additional command options</span></a> for options to the <strong class="command">register</strong> command.</p>
</div>
<div class="section" id="the-upload-command">
<span id="package-upload"></span><h3>6.2.2. The <code class="docutils literal notranslate"><span class="pre">upload</span></code> command<a class="headerlink" href="#the-upload-command" title="Permalink to this headline">¶</a></h3>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.5.</span></p>
</div>
<p>The distutils command <strong class="command">upload</strong> pushes the distribution files to PyPI.</p>
<p>The command is invoked immediately after building one or more distribution
files. For example, the command</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">sdist</span> <span class="n">bdist_wininst</span> <span class="n">upload</span>
</pre></div>
</div>
<p>will cause the source distribution and the Windows installer to be uploaded to
PyPI. Note that these will be uploaded even if they are built using an earlier
invocation of <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code>, but that only distributions named on the command
line for the invocation including the <strong class="command">upload</strong> command are uploaded.</p>
<p>If a <strong class="command">register</strong> command was previously called in the same command,
and if the password was entered in the prompt, <strong class="command">upload</strong> will reuse the
entered password. This is useful if you do not want to store a password in
clear text in a <code class="file docutils literal notranslate"><span class="pre">.pypirc</span></code> file.</p>
<p>You can use the <code class="docutils literal notranslate"><span class="pre">--sign</span></code> option to tell <strong class="command">upload</strong> to sign each
uploaded file using GPG (GNU Privacy Guard). The <strong class="program">gpg</strong> program must
be available for execution on the system <span class="target" id="index-1"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code>. You can also specify
which key to use for signing using the <code class="docutils literal notranslate"><span class="pre">--identity=name</span></code> option.</p>
<p>See <a class="reference internal" href="#package-cmdoptions"><span class="std std-ref">Additional command options</span></a> for additional options to the <strong class="command">upload</strong>
command.</p>
</div>
<div class="section" id="additional-command-options">
<span id="package-cmdoptions"></span><h3>6.2.3. Additional command options<a class="headerlink" href="#additional-command-options" title="Permalink to this headline">¶</a></h3>
<p>This section describes options common to both the <strong class="command">register</strong> and
<strong class="command">upload</strong> commands.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">--repository</span></code> or <code class="docutils literal notranslate"><span class="pre">-r</span></code> option lets you specify a PyPI server
different from the default. For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">sdist</span> <span class="n">bdist_wininst</span> <span class="n">upload</span> <span class="o">-</span><span class="n">r</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">pypi</span>
</pre></div>
</div>
<p>For convenience, a name can be used in place of the URL when the
<code class="file docutils literal notranslate"><span class="pre">.pypirc</span></code> file is configured to do so. For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">register</span> <span class="o">-</span><span class="n">r</span> <span class="n">other</span>
</pre></div>
</div>
<p>See <a class="reference internal" href="#pypirc"><span class="std std-ref">The .pypirc file</span></a> for more information on defining alternate servers.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">--show-response</span></code> option displays the full response text from the PyPI
server, which is useful when debugging problems with registering and uploading.</p>
</div>
<div class="section" id="the-pypirc-file">
<span id="pypirc"></span><span id="index-2"></span><h3>6.2.4. The <code class="docutils literal notranslate"><span class="pre">.pypirc</span></code> file<a class="headerlink" href="#the-pypirc-file" title="Permalink to this headline">¶</a></h3>
<p>The <strong class="command">register</strong> and <strong class="command">upload</strong> commands both check for the
existence of a <code class="file docutils literal notranslate"><span class="pre">.pypirc</span></code> file at the location <code class="file docutils literal notranslate"><span class="pre">$HOME/.pypirc</span></code>.
If this file exists, the command uses the username, password, and repository
URL configured in the file. The format of a <code class="file docutils literal notranslate"><span class="pre">.pypirc</span></code> file is as
follows:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">distutils</span><span class="p">]</span>
<span class="n">index</span><span class="o">-</span><span class="n">servers</span> <span class="o">=</span>
<span class="n">pypi</span>
<span class="p">[</span><span class="n">pypi</span><span class="p">]</span>
<span class="n">repository</span><span class="p">:</span> <span class="o"><</span><span class="n">repository</span><span class="o">-</span><span class="n">url</span><span class="o">></span>
<span class="n">username</span><span class="p">:</span> <span class="o"><</span><span class="n">username</span><span class="o">></span>
<span class="n">password</span><span class="p">:</span> <span class="o"><</span><span class="n">password</span><span class="o">></span>
</pre></div>
</div>
<p>The <em>distutils</em> section defines an <em>index-servers</em> variable that lists the
name of all sections describing a repository.</p>
<p>Each section describing a repository defines three variables:</p>
<ul class="simple">
<li><dl class="first docutils">
<dt><em>repository</em>, that defines the url of the PyPI server. Defaults to</dt>
<dd><code class="docutils literal notranslate"><span class="pre">https://www.python.org/pypi</span></code>.</dd>
</dl>
</li>
<li><em>username</em>, which is the registered username on the PyPI server.</li>
<li><dl class="first docutils">
<dt><em>password</em>, that will be used to authenticate. If omitted the user</dt>
<dd>will be prompt to type it when needed.</dd>
</dl>
</li>
</ul>
<p>If you want to define another server a new section can be created and
listed in the <em>index-servers</em> variable:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">distutils</span><span class="p">]</span>
<span class="n">index</span><span class="o">-</span><span class="n">servers</span> <span class="o">=</span>
<span class="n">pypi</span>
<span class="n">other</span>
<span class="p">[</span><span class="n">pypi</span><span class="p">]</span>
<span class="n">repository</span><span class="p">:</span> <span class="o"><</span><span class="n">repository</span><span class="o">-</span><span class="n">url</span><span class="o">></span>
<span class="n">username</span><span class="p">:</span> <span class="o"><</span><span class="n">username</span><span class="o">></span>
<span class="n">password</span><span class="p">:</span> <span class="o"><</span><span class="n">password</span><span class="o">></span>
<span class="p">[</span><span class="n">other</span><span class="p">]</span>
<span class="n">repository</span><span class="p">:</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">pypi</span>
<span class="n">username</span><span class="p">:</span> <span class="o"><</span><span class="n">username</span><span class="o">></span>
<span class="n">password</span><span class="p">:</span> <span class="o"><</span><span class="n">password</span><span class="o">></span>
</pre></div>
</div>
<p>This allows the <strong class="command">register</strong> and <strong class="command">upload</strong> commands to be
called with the <code class="docutils literal notranslate"><span class="pre">--repository</span></code> option as described in
<a class="reference internal" href="#package-cmdoptions"><span class="std std-ref">Additional command options</span></a>.</p>
<p>Specifically, you might want to add the <a class="reference external" href="https://wiki.python.org/moin/TestPyPI">PyPI Test Repository</a> to your <code class="docutils literal notranslate"><span class="pre">.pypirc</span></code> to facilitate
testing before doing your first upload to <code class="docutils literal notranslate"><span class="pre">PyPI</span></code> itself.</p>
</div>
</div>
<div class="section" id="pypi-package-display">
<span id="package-display"></span><h2>6.3. PyPI package display<a class="headerlink" href="#pypi-package-display" title="Permalink to this headline">¶</a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">long_description</span></code> field plays a special role at PyPI. It is used by
the server to display a home page for the registered package.</p>
<p>If you use the <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a>
syntax for this field, PyPI will parse it and display an HTML output for
the package home page.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">long_description</span></code> field can be attached to a text file located
in the package:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">distutils.core</span> <span class="k">import</span> <span class="n">setup</span>
<span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">'README.txt'</span><span class="p">)</span> <span class="k">as</span> <span class="n">file</span><span class="p">:</span>
<span class="n">long_description</span> <span class="o">=</span> <span class="n">file</span><span class="o">.</span><span class="n">read</span><span class="p">()</span>
<span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'Distutils'</span><span class="p">,</span>
<span class="n">long_description</span><span class="o">=</span><span class="n">long_description</span><span class="p">)</span>
</pre></div>
</div>
<p>In that case, <code class="file docutils literal notranslate"><span class="pre">README.txt</span></code> is a regular reStructuredText text file located
in the root of the package besides <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code>.</p>
<p>To prevent registering broken reStructuredText content, you can use the
<strong class="program">rst2html</strong> program that is provided by the <code class="xref py py-mod docutils literal notranslate"><span class="pre">docutils</span></code> package and
check the <code class="docutils literal notranslate"><span class="pre">long_description</span></code> from the command line:</p>
<div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> python setup.py --long-description <span class="p">|</span> rst2html.py > output.html
</pre></div>
</div>
<p><code class="xref py py-mod docutils literal notranslate"><span class="pre">docutils</span></code> will display a warning if there’s something wrong with your
syntax. Because PyPI applies additional checks (e.g. by passing <code class="docutils literal notranslate"><span class="pre">--no-raw</span></code>
to <code class="docutils literal notranslate"><span class="pre">rst2html.py</span></code> in the command above), being able to run the command above
without warnings does not guarantee that PyPI will convert the content
successfully.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">6. The Python Package Index (PyPI)</a><ul>
<li><a class="reference internal" href="#pypi-overview">6.1. PyPI overview</a></li>
<li><a class="reference internal" href="#distutils-commands">6.2. Distutils commands</a><ul>
<li><a class="reference internal" href="#the-register-command">6.2.1. The <code class="docutils literal notranslate"><span class="pre">register</span></code> command</a></li>
<li><a class="reference internal" href="#the-upload-command">6.2.2. The <code class="docutils literal notranslate"><span class="pre">upload</span></code> command</a></li>
<li><a class="reference internal" href="#additional-command-options">6.2.3. Additional command options</a></li>
<li><a class="reference internal" href="#the-pypirc-file">6.2.4. The <code class="docutils literal notranslate"><span class="pre">.pypirc</span></code> file</a></li>
</ul>
</li>
<li><a class="reference internal" href="#pypi-package-display">6.3. PyPI package display</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="builtdist.html"
title="previous chapter">5. Creating Built Distributions</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="examples.html"
title="next chapter">7. Examples</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/distutils/packageindex.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="examples.html" title="7. Examples"
>next</a> |</li>
<li class="right" >
<a href="builtdist.html" title="5. Creating Built Distributions"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Distributing Python Modules (Legacy version)</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
</div>
</body>
</html>PK
%�\�����
�
html/distutils/setupscript.htmlnu �[���
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>2. Writing the Setup Script — Python 2.7.16 documentation</title>
<link rel="stylesheet" href="../_static/classic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 2.7.16 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="3. Writing the Setup Configuration File" href="configfile.html" />
<link rel="prev" title="1. An Introduction to Distutils" href="introduction.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/2/distutils/setupscript.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="configfile.html" title="3. Writing the Setup Configuration File"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="introduction.html" title="1. An Introduction to Distutils"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Distributing Python Modules (Legacy version)</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="writing-the-setup-script">
<span id="setup-script"></span><h1>2. Writing the Setup Script<a class="headerlink" href="#writing-the-setup-script" title="Permalink to this headline">¶</a></h1>
<p>The setup script is the centre of all activity in building, distributing, and
installing modules using the Distutils. The main purpose of the setup script is
to describe your module distribution to the Distutils, so that the various
commands that operate on your modules do the right thing. As we saw in section
<a class="reference internal" href="introduction.html#distutils-simple-example"><span class="std std-ref">A Simple Example</span></a> above, the setup script consists mainly of a call to
<code class="xref py py-func docutils literal notranslate"><span class="pre">setup()</span></code>, and most information supplied to the Distutils by the module
developer is supplied as keyword arguments to <code class="xref py py-func docutils literal notranslate"><span class="pre">setup()</span></code>.</p>
<p>Here’s a slightly more involved example, which we’ll follow for the next couple
of sections: the Distutils’ own setup script. (Keep in mind that although the
Distutils are included with Python 1.6 and later, they also have an independent
existence so that Python 1.5.2 users can use them to install other module
distributions. The Distutils’ own setup script, shown here, is used to install
the package into Python 1.5.2.)</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="ch">#!/usr/bin/env python</span>
<span class="kn">from</span> <span class="nn">distutils.core</span> <span class="k">import</span> <span class="n">setup</span>
<span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'Distutils'</span><span class="p">,</span>
<span class="n">version</span><span class="o">=</span><span class="s1">'1.0'</span><span class="p">,</span>
<span class="n">description</span><span class="o">=</span><span class="s1">'Python Distribution Utilities'</span><span class="p">,</span>
<span class="n">author</span><span class="o">=</span><span class="s1">'Greg Ward'</span><span class="p">,</span>
<span class="n">author_email</span><span class="o">=</span><span class="s1">'gward@python.net'</span><span class="p">,</span>
<span class="n">url</span><span class="o">=</span><span class="s1">'https://www.python.org/sigs/distutils-sig/'</span><span class="p">,</span>
<span class="n">packages</span><span class="o">=</span><span class="p">[</span><span class="s1">'distutils'</span><span class="p">,</span> <span class="s1">'distutils.command'</span><span class="p">],</span>
<span class="p">)</span>
</pre></div>
</div>
<p>There are only two differences between this and the trivial one-file
distribution presented in section <a class="reference internal" href="introduction.html#distutils-simple-example"><span class="std std-ref">A Simple Example</span></a>: more metadata, and the
specification of pure Python modules by package, rather than by module. This is
important since the Distutils consist of a couple of dozen modules split into
(so far) two packages; an explicit list of every module would be tedious to
generate and difficult to maintain. For more information on the additional
meta-data, see section <a class="reference internal" href="#meta-data"><span class="std std-ref">Additional meta-data</span></a>.</p>
<p>Note that any pathnames (files or directories) supplied in the setup script
should be written using the Unix convention, i.e. slash-separated. The
Distutils will take care of converting this platform-neutral representation into
whatever is appropriate on your current platform before actually using the
pathname. This makes your setup script portable across operating systems, which
of course is one of the major goals of the Distutils. In this spirit, all
pathnames in this document are slash-separated.</p>
<p>This, of course, only applies to pathnames given to Distutils functions. If
you, for example, use standard Python functions such as <a class="reference internal" href="../library/glob.html#glob.glob" title="glob.glob"><code class="xref py py-func docutils literal notranslate"><span class="pre">glob.glob()</span></code></a> or
<a class="reference internal" href="../library/os.html#os.listdir" title="os.listdir"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.listdir()</span></code></a> to specify files, you should be careful to write portable
code instead of hardcoding path separators:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">glob</span><span class="o">.</span><span class="n">glob</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="s1">'mydir'</span><span class="p">,</span> <span class="s1">'subdir'</span><span class="p">,</span> <span class="s1">'*.html'</span><span class="p">))</span>
<span class="n">os</span><span class="o">.</span><span class="n">listdir</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="s1">'mydir'</span><span class="p">,</span> <span class="s1">'subdir'</span><span class="p">))</span>
</pre></div>
</div>
<div class="section" id="listing-whole-packages">
<span id="listing-packages"></span><h2>2.1. Listing whole packages<a class="headerlink" href="#listing-whole-packages" title="Permalink to this headline">¶</a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">packages</span></code> option tells the Distutils to process (build, distribute,
install, etc.) all pure Python modules found in each package mentioned in the
<code class="docutils literal notranslate"><span class="pre">packages</span></code> list. In order to do this, of course, there has to be a
correspondence between package names and directories in the filesystem. The
default correspondence is the most obvious one, i.e. package <a class="reference internal" href="../library/distutils.html#module-distutils" title="distutils: Support for building and installing Python modules into an existing Python installation."><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils</span></code></a> is
found in the directory <code class="file docutils literal notranslate"><span class="pre">distutils</span></code> relative to the distribution root.
Thus, when you say <code class="docutils literal notranslate"><span class="pre">packages</span> <span class="pre">=</span> <span class="pre">['foo']</span></code> in your setup script, you are
promising that the Distutils will find a file <code class="file docutils literal notranslate"><span class="pre">foo/__init__.py</span></code> (which
might be spelled differently on your system, but you get the idea) relative to
the directory where your setup script lives. If you break this promise, the
Distutils will issue a warning but still process the broken package anyway.</p>
<p>If you use a different convention to lay out your source directory, that’s no
problem: you just have to supply the <code class="docutils literal notranslate"><span class="pre">package_dir</span></code> option to tell the
Distutils about your convention. For example, say you keep all Python source
under <code class="file docutils literal notranslate"><span class="pre">lib</span></code>, so that modules in the “root package” (i.e., not in any
package at all) are in <code class="file docutils literal notranslate"><span class="pre">lib</span></code>, modules in the <code class="xref py py-mod docutils literal notranslate"><span class="pre">foo</span></code> package are in
<code class="file docutils literal notranslate"><span class="pre">lib/foo</span></code>, and so forth. Then you would put</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">package_dir</span> <span class="o">=</span> <span class="p">{</span><span class="s1">''</span><span class="p">:</span> <span class="s1">'lib'</span><span class="p">}</span>
</pre></div>
</div>
<p>in your setup script. The keys to this dictionary are package names, and an
empty package name stands for the root package. The values are directory names
relative to your distribution root. In this case, when you say <code class="docutils literal notranslate"><span class="pre">packages</span> <span class="pre">=</span>
<span class="pre">['foo']</span></code>, you are promising that the file <code class="file docutils literal notranslate"><span class="pre">lib/foo/__init__.py</span></code> exists.</p>
<p>Another possible convention is to put the <code class="xref py py-mod docutils literal notranslate"><span class="pre">foo</span></code> package right in
<code class="file docutils literal notranslate"><span class="pre">lib</span></code>, the <code class="xref py py-mod docutils literal notranslate"><span class="pre">foo.bar</span></code> package in <code class="file docutils literal notranslate"><span class="pre">lib/bar</span></code>, etc. This would be
written in the setup script as</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">package_dir</span> <span class="o">=</span> <span class="p">{</span><span class="s1">'foo'</span><span class="p">:</span> <span class="s1">'lib'</span><span class="p">}</span>
</pre></div>
</div>
<p>A <code class="docutils literal notranslate"><span class="pre">package:</span> <span class="pre">dir</span></code> entry in the <code class="docutils literal notranslate"><span class="pre">package_dir</span></code> dictionary implicitly
applies to all packages below <em>package</em>, so the <code class="xref py py-mod docutils literal notranslate"><span class="pre">foo.bar</span></code> case is
automatically handled here. In this example, having <code class="docutils literal notranslate"><span class="pre">packages</span> <span class="pre">=</span> <span class="pre">['foo',</span>
<span class="pre">'foo.bar']</span></code> tells the Distutils to look for <code class="file docutils literal notranslate"><span class="pre">lib/__init__.py</span></code> and
<code class="file docutils literal notranslate"><span class="pre">lib/bar/__init__.py</span></code>. (Keep in mind that although <code class="docutils literal notranslate"><span class="pre">package_dir</span></code>
applies recursively, you must explicitly list all packages in
<code class="docutils literal notranslate"><span class="pre">packages</span></code>: the Distutils will <em>not</em> recursively scan your source tree
looking for any directory with an <code class="file docutils literal notranslate"><span class="pre">__init__.py</span></code> file.)</p>
</div>
<div class="section" id="listing-individual-modules">
<span id="listing-modules"></span><h2>2.2. Listing individual modules<a class="headerlink" href="#listing-individual-modules" title="Permalink to this headline">¶</a></h2>
<p>For a small module distribution, you might prefer to list all modules rather
than listing packages—especially the case of a single module that goes in the
“root package” (i.e., no package at all). This simplest case was shown in
section <a class="reference internal" href="introduction.html#distutils-simple-example"><span class="std std-ref">A Simple Example</span></a>; here is a slightly more involved example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">py_modules</span> <span class="o">=</span> <span class="p">[</span><span class="s1">'mod1'</span><span class="p">,</span> <span class="s1">'pkg.mod2'</span><span class="p">]</span>
</pre></div>
</div>
<p>This describes two modules, one of them in the “root” package, the other in the
<code class="xref py py-mod docutils literal notranslate"><span class="pre">pkg</span></code> package. Again, the default package/directory layout implies that
these two modules can be found in <code class="file docutils literal notranslate"><span class="pre">mod1.py</span></code> and <code class="file docutils literal notranslate"><span class="pre">pkg/mod2.py</span></code>, and
that <code class="file docutils literal notranslate"><span class="pre">pkg/__init__.py</span></code> exists as well. And again, you can override the
package/directory correspondence using the <code class="docutils literal notranslate"><span class="pre">package_dir</span></code> option.</p>
</div>
<div class="section" id="describing-extension-modules">
<span id="describing-extensions"></span><h2>2.3. Describing extension modules<a class="headerlink" href="#describing-extension-modules" title="Permalink to this headline">¶</a></h2>
<p>Just as writing Python extension modules is a bit more complicated than writing
pure Python modules, describing them to the Distutils is a bit more complicated.
Unlike pure modules, it’s not enough just to list modules or packages and expect
the Distutils to go out and find the right files; you have to specify the
extension name, source file(s), and any compile/link requirements (include
directories, libraries to link with, etc.).</p>
<p>All of this is done through another keyword argument to <code class="xref py py-func docutils literal notranslate"><span class="pre">setup()</span></code>, the
<code class="docutils literal notranslate"><span class="pre">ext_modules</span></code> option. <code class="docutils literal notranslate"><span class="pre">ext_modules</span></code> is just a list of
<a class="reference internal" href="apiref.html#distutils.core.Extension" title="distutils.core.Extension"><code class="xref py py-class docutils literal notranslate"><span class="pre">Extension</span></code></a> instances, each of which describes a
single extension module.
Suppose your distribution includes a single extension, called <code class="xref py py-mod docutils literal notranslate"><span class="pre">foo</span></code> and
implemented by <code class="file docutils literal notranslate"><span class="pre">foo.c</span></code>. If no additional instructions to the
compiler/linker are needed, describing this extension is quite simple:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Extension</span><span class="p">(</span><span class="s1">'foo'</span><span class="p">,</span> <span class="p">[</span><span class="s1">'foo.c'</span><span class="p">])</span>
</pre></div>
</div>
<p>The <code class="xref py py-class docutils literal notranslate"><span class="pre">Extension</span></code> class can be imported from <a class="reference internal" href="apiref.html#module-distutils.core" title="distutils.core: The core Distutils functionality"><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.core</span></code></a> along
with <code class="xref py py-func docutils literal notranslate"><span class="pre">setup()</span></code>. Thus, the setup script for a module distribution that
contains only this one extension and nothing else might be:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">distutils.core</span> <span class="k">import</span> <span class="n">setup</span><span class="p">,</span> <span class="n">Extension</span>
<span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'foo'</span><span class="p">,</span>
<span class="n">version</span><span class="o">=</span><span class="s1">'1.0'</span><span class="p">,</span>
<span class="n">ext_modules</span><span class="o">=</span><span class="p">[</span><span class="n">Extension</span><span class="p">(</span><span class="s1">'foo'</span><span class="p">,</span> <span class="p">[</span><span class="s1">'foo.c'</span><span class="p">])],</span>
<span class="p">)</span>
</pre></div>
</div>
<p>The <code class="xref py py-class docutils literal notranslate"><span class="pre">Extension</span></code> class (actually, the underlying extension-building
machinery implemented by the <strong class="command">build_ext</strong> command) supports a great deal
of flexibility in describing Python extensions, which is explained in the
following sections.</p>
<div class="section" id="extension-names-and-packages">
<h3>2.3.1. Extension names and packages<a class="headerlink" href="#extension-names-and-packages" title="Permalink to this headline">¶</a></h3>
<p>The first argument to the <a class="reference internal" href="apiref.html#distutils.core.Extension" title="distutils.core.Extension"><code class="xref py py-class docutils literal notranslate"><span class="pre">Extension</span></code></a> constructor is
always the name of the extension, including any package names. For example,</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Extension</span><span class="p">(</span><span class="s1">'foo'</span><span class="p">,</span> <span class="p">[</span><span class="s1">'src/foo1.c'</span><span class="p">,</span> <span class="s1">'src/foo2.c'</span><span class="p">])</span>
</pre></div>
</div>
<p>describes an extension that lives in the root package, while</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Extension</span><span class="p">(</span><span class="s1">'pkg.foo'</span><span class="p">,</span> <span class="p">[</span><span class="s1">'src/foo1.c'</span><span class="p">,</span> <span class="s1">'src/foo2.c'</span><span class="p">])</span>
</pre></div>
</div>
<p>describes the same extension in the <code class="xref py py-mod docutils literal notranslate"><span class="pre">pkg</span></code> package. The source files and
resulting object code are identical in both cases; the only difference is where
in the filesystem (and therefore where in Python’s namespace hierarchy) the
resulting extension lives.</p>
<p>If you have a number of extensions all in the same package (or all under the
same base package), use the <code class="docutils literal notranslate"><span class="pre">ext_package</span></code> keyword argument to
<code class="xref py py-func docutils literal notranslate"><span class="pre">setup()</span></code>. For example,</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span><span class="o">...</span><span class="p">,</span>
<span class="n">ext_package</span><span class="o">=</span><span class="s1">'pkg'</span><span class="p">,</span>
<span class="n">ext_modules</span><span class="o">=</span><span class="p">[</span><span class="n">Extension</span><span class="p">(</span><span class="s1">'foo'</span><span class="p">,</span> <span class="p">[</span><span class="s1">'foo.c'</span><span class="p">]),</span>
<span class="n">Extension</span><span class="p">(</span><span class="s1">'subpkg.bar'</span><span class="p">,</span> <span class="p">[</span><span class="s1">'bar.c'</span><span class="p">])],</span>
<span class="p">)</span>
</pre></div>
</div>
<p>will compile <code class="file docutils literal notranslate"><span class="pre">foo.c</span></code> to the extension <code class="xref py py-mod docutils literal notranslate"><span class="pre">pkg.foo</span></code>, and <code class="file docutils literal notranslate"><span class="pre">bar.c</span></code> to
<code class="xref py py-mod docutils literal notranslate"><span class="pre">pkg.subpkg.bar</span></code>.</p>
</div>
<div class="section" id="extension-source-files">
<h3>2.3.2. Extension source files<a class="headerlink" href="#extension-source-files" title="Permalink to this headline">¶</a></h3>
<p>The second argument to the <a class="reference internal" href="apiref.html#distutils.core.Extension" title="distutils.core.Extension"><code class="xref py py-class docutils literal notranslate"><span class="pre">Extension</span></code></a> constructor is
a list of source
files. Since the Distutils currently only support C, C++, and Objective-C
extensions, these are normally C/C++/Objective-C source files. (Be sure to use
appropriate extensions to distinguish C++ source files: <code class="file docutils literal notranslate"><span class="pre">.cc</span></code> and
<code class="file docutils literal notranslate"><span class="pre">.cpp</span></code> seem to be recognized by both Unix and Windows compilers.)</p>
<p>However, you can also include SWIG interface (<code class="file docutils literal notranslate"><span class="pre">.i</span></code>) files in the list; the
<strong class="command">build_ext</strong> command knows how to deal with SWIG extensions: it will run
SWIG on the interface file and compile the resulting C/C++ file into your
extension.</p>
<p>This warning notwithstanding, options to SWIG can be currently passed like
this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span><span class="o">...</span><span class="p">,</span>
<span class="n">ext_modules</span><span class="o">=</span><span class="p">[</span><span class="n">Extension</span><span class="p">(</span><span class="s1">'_foo'</span><span class="p">,</span> <span class="p">[</span><span class="s1">'foo.i'</span><span class="p">],</span>
<span class="n">swig_opts</span><span class="o">=</span><span class="p">[</span><span class="s1">'-modern'</span><span class="p">,</span> <span class="s1">'-I../include'</span><span class="p">])],</span>
<span class="n">py_modules</span><span class="o">=</span><span class="p">[</span><span class="s1">'foo'</span><span class="p">],</span>
<span class="p">)</span>
</pre></div>
</div>
<p>Or on the commandline like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">></span> <span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">build_ext</span> <span class="o">--</span><span class="n">swig</span><span class="o">-</span><span class="n">opts</span><span class="o">=</span><span class="s2">"-modern -I../include"</span>
</pre></div>
</div>
<p>On some platforms, you can include non-source files that are processed by the
compiler and included in your extension. Currently, this just means Windows
message text (<code class="file docutils literal notranslate"><span class="pre">.mc</span></code>) files and resource definition (<code class="file docutils literal notranslate"><span class="pre">.rc</span></code>) files for
Visual C++. These will be compiled to binary resource (<code class="file docutils literal notranslate"><span class="pre">.res</span></code>) files and
linked into the executable.</p>
</div>
<div class="section" id="preprocessor-options">
<h3>2.3.3. Preprocessor options<a class="headerlink" href="#preprocessor-options" title="Permalink to this headline">¶</a></h3>
<p>Three optional arguments to <a class="reference internal" href="apiref.html#distutils.core.Extension" title="distutils.core.Extension"><code class="xref py py-class docutils literal notranslate"><span class="pre">Extension</span></code></a> will help if
you need to specify include directories to search or preprocessor macros to
define/undefine: <code class="docutils literal notranslate"><span class="pre">include_dirs</span></code>, <code class="docutils literal notranslate"><span class="pre">define_macros</span></code>, and <code class="docutils literal notranslate"><span class="pre">undef_macros</span></code>.</p>
<p>For example, if your extension requires header files in the <code class="file docutils literal notranslate"><span class="pre">include</span></code>
directory under your distribution root, use the <code class="docutils literal notranslate"><span class="pre">include_dirs</span></code> option:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Extension</span><span class="p">(</span><span class="s1">'foo'</span><span class="p">,</span> <span class="p">[</span><span class="s1">'foo.c'</span><span class="p">],</span> <span class="n">include_dirs</span><span class="o">=</span><span class="p">[</span><span class="s1">'include'</span><span class="p">])</span>
</pre></div>
</div>
<p>You can specify absolute directories there; if you know that your extension will
only be built on Unix systems with X11R6 installed to <code class="file docutils literal notranslate"><span class="pre">/usr</span></code>, you can get
away with</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Extension</span><span class="p">(</span><span class="s1">'foo'</span><span class="p">,</span> <span class="p">[</span><span class="s1">'foo.c'</span><span class="p">],</span> <span class="n">include_dirs</span><span class="o">=</span><span class="p">[</span><span class="s1">'/usr/include/X11'</span><span class="p">])</span>
</pre></div>
</div>
<p>You should avoid this sort of non-portable usage if you plan to distribute your
code: it’s probably better to write C code like</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1">#include <X11/Xlib.h></span>
</pre></div>
</div>
<p>If you need to include header files from some other Python extension, you can
take advantage of the fact that header files are installed in a consistent way
by the Distutils <strong class="command">install_headers</strong> command. For example, the Numerical
Python header files are installed (on a standard Unix installation) to
<code class="file docutils literal notranslate"><span class="pre">/usr/local/include/python1.5/Numerical</span></code>. (The exact location will differ
according to your platform and Python installation.) Since the Python include
directory—<code class="file docutils literal notranslate"><span class="pre">/usr/local/include/python1.5</span></code> in this case—is always
included in the search path when building Python extensions, the best approach
is to write C code like</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1">#include <Numerical/arrayobject.h></span>
</pre></div>
</div>
<p>If you must put the <code class="file docutils literal notranslate"><span class="pre">Numerical</span></code> include directory right into your header
search path, though, you can find that directory using the Distutils
<a class="reference internal" href="apiref.html#module-distutils.sysconfig" title="distutils.sysconfig: Low-level access to configuration information of the Python interpreter."><code class="xref py py-mod docutils literal notranslate"><span class="pre">distutils.sysconfig</span></code></a> module:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">distutils.sysconfig</span> <span class="k">import</span> <span class="n">get_python_inc</span>
<span class="n">incdir</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">get_python_inc</span><span class="p">(</span><span class="n">plat_specific</span><span class="o">=</span><span class="mi">1</span><span class="p">),</span> <span class="s1">'Numerical'</span><span class="p">)</span>
<span class="n">setup</span><span class="p">(</span><span class="o">...</span><span class="p">,</span>
<span class="n">Extension</span><span class="p">(</span><span class="o">...</span><span class="p">,</span> <span class="n">include_dirs</span><span class="o">=</span><span class="p">[</span><span class="n">incdir</span><span class="p">]),</span>
<span class="p">)</span>
</pre></div>
</div>
<p>Even though this is quite portable—it will work on any Python installation,
regardless of platform—it’s probably easier to just write your C code in the
sensible way.</p>
<p>You can define and undefine pre-processor macros with the <code class="docutils literal notranslate"><span class="pre">define_macros</span></code> and
<code class="docutils literal notranslate"><span class="pre">undef_macros</span></code> options. <code class="docutils literal notranslate"><span class="pre">define_macros</span></code> takes a list of <code class="docutils literal notranslate"><span class="pre">(name,</span> <span class="pre">value)</span></code>
tuples, where <code class="docutils literal notranslate"><span class="pre">name</span></code> is the name of the macro to define (a string) and
<code class="docutils literal notranslate"><span class="pre">value</span></code> is its value: either a string or <code class="docutils literal notranslate"><span class="pre">None</span></code>. (Defining a macro <code class="docutils literal notranslate"><span class="pre">FOO</span></code>
to <code class="docutils literal notranslate"><span class="pre">None</span></code> is the equivalent of a bare <code class="docutils literal notranslate"><span class="pre">#define</span> <span class="pre">FOO</span></code> in your C source: with
most compilers, this sets <code class="docutils literal notranslate"><span class="pre">FOO</span></code> to the string <code class="docutils literal notranslate"><span class="pre">1</span></code>.) <code class="docutils literal notranslate"><span class="pre">undef_macros</span></code> is
just a list of macros to undefine.</p>
<p>For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Extension</span><span class="p">(</span><span class="o">...</span><span class="p">,</span>
<span class="n">define_macros</span><span class="o">=</span><span class="p">[(</span><span class="s1">'NDEBUG'</span><span class="p">,</span> <span class="s1">'1'</span><span class="p">),</span>
<span class="p">(</span><span class="s1">'HAVE_STRFTIME'</span><span class="p">,</span> <span class="kc">None</span><span class="p">)],</span>
<span class="n">undef_macros</span><span class="o">=</span><span class="p">[</span><span class="s1">'HAVE_FOO'</span><span class="p">,</span> <span class="s1">'HAVE_BAR'</span><span class="p">])</span>
</pre></div>
</div>
<p>is the equivalent of having this at the top of every C source file:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1">#define NDEBUG 1</span>
<span class="c1">#define HAVE_STRFTIME</span>
<span class="c1">#undef HAVE_FOO</span>
<span class="c1">#undef HAVE_BAR</span>
</pre></div>
</div>
</div>
<div class="section" id="library-options">
<h3>2.3.4. Library options<a class="headerlink" href="#library-options" title="Permalink to this headline">¶</a></h3>
<p>You can also specify the libraries to link against when building your extension,
and the directories to search for those libraries. The <code class="docutils literal notranslate"><span class="pre">libraries</span></code> option is
a list of libraries to link against, <code class="docutils literal notranslate"><span class="pre">library_dirs</span></code> is a list of directories
to search for libraries at link-time, and <code class="docutils literal notranslate"><span class="pre">runtime_library_dirs</span></code> is a list of
directories to search for shared (dynamically loaded) libraries at run-time.</p>
<p>For example, if you need to link against libraries known to be in the standard
library search path on target systems</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Extension</span><span class="p">(</span><span class="o">...</span><span class="p">,</span>
<span class="n">libraries</span><span class="o">=</span><span class="p">[</span><span class="s1">'gdbm'</span><span class="p">,</span> <span class="s1">'readline'</span><span class="p">])</span>
</pre></div>
</div>
<p>If you need to link with libraries in a non-standard location, you’ll have to
include the location in <code class="docutils literal notranslate"><span class="pre">library_dirs</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Extension</span><span class="p">(</span><span class="o">...</span><span class="p">,</span>
<span class="n">library_dirs</span><span class="o">=</span><span class="p">[</span><span class="s1">'/usr/X11R6/lib'</span><span class="p">],</span>
<span class="n">libraries</span><span class="o">=</span><span class="p">[</span><span class="s1">'X11'</span><span class="p">,</span> <span class="s1">'Xt'</span><span class="p">])</span>
</pre></div>
</div>
<p>(Again, this sort of non-portable construct should be avoided if you intend to
distribute your code.)</p>
</div>
<div class="section" id="other-options">
<h3>2.3.5. Other options<a class="headerlink" href="#other-options" title="Permalink to this headline">¶</a></h3>
<p>There are still some other options which can be used to handle special cases.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">extra_objects</span></code> option is a list of object files to be passed to the
linker. These files must not have extensions, as the default extension for the
compiler is used.</p>
<p><code class="docutils literal notranslate"><span class="pre">extra_compile_args</span></code> and <code class="docutils literal notranslate"><span class="pre">extra_link_args</span></code> can be used to
specify additional command line options for the respective compiler and linker
command lines.</p>
<p><code class="docutils literal notranslate"><span class="pre">export_symbols</span></code> is only useful on Windows. It can contain a list of
symbols (functions or variables) to be exported. This option is not needed when
building compiled extensions: Distutils will automatically add <code class="docutils literal notranslate"><span class="pre">initmodule</span></code>
to the list of exported symbols.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">depends</span></code> option is a list of files that the extension depends on
(for example header files). The build command will call the compiler on the
sources to rebuild extension if any on this files has been modified since the
previous build.</p>
</div>
</div>
<div class="section" id="relationships-between-distributions-and-packages">
<h2>2.4. Relationships between Distributions and Packages<a class="headerlink" href="#relationships-between-distributions-and-packages" title="Permalink to this headline">¶</a></h2>
<p>A distribution may relate to packages in three specific ways:</p>
<ol class="arabic simple">
<li>It can require packages or modules.</li>
<li>It can provide packages or modules.</li>
<li>It can obsolete packages or modules.</li>
</ol>
<p>These relationships can be specified using keyword arguments to the
<a class="reference internal" href="apiref.html#distutils.core.setup" title="distutils.core.setup"><code class="xref py py-func docutils literal notranslate"><span class="pre">distutils.core.setup()</span></code></a> function.</p>
<p>Dependencies on other Python modules and packages can be specified by supplying
the <em>requires</em> keyword argument to <code class="xref py py-func docutils literal notranslate"><span class="pre">setup()</span></code>. The value must be a list of
strings. Each string specifies a package that is required, and optionally what
versions are sufficient.</p>
<p>To specify that any version of a module or package is required, the string
should consist entirely of the module or package name. Examples include
<code class="docutils literal notranslate"><span class="pre">'mymodule'</span></code> and <code class="docutils literal notranslate"><span class="pre">'xml.parsers.expat'</span></code>.</p>
<p>If specific versions are required, a sequence of qualifiers can be supplied in
parentheses. Each qualifier may consist of a comparison operator and a version
number. The accepted comparison operators are:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o"><</span> <span class="o">></span> <span class="o">==</span>
<span class="o"><=</span> <span class="o">>=</span> <span class="o">!=</span>
</pre></div>
</div>
<p>These can be combined by using multiple qualifiers separated by commas (and
optional whitespace). In this case, all of the qualifiers must be matched; a
logical AND is used to combine the evaluations.</p>
<p>Let’s look at a bunch of examples:</p>
<table border="1" class="docutils">
<colgroup>
<col width="35%" />
<col width="65%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Requires Expression</th>
<th class="head">Explanation</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">==1.0</span></code></td>
<td>Only version <code class="docutils literal notranslate"><span class="pre">1.0</span></code> is compatible</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">>1.0,</span> <span class="pre">!=1.5.1,</span> <span class="pre"><2.0</span></code></td>
<td>Any version after <code class="docutils literal notranslate"><span class="pre">1.0</span></code> and before <code class="docutils literal notranslate"><span class="pre">2.0</span></code>
is compatible, except <code class="docutils literal notranslate"><span class="pre">1.5.1</span></code></td>
</tr>
</tbody>
</table>
<p>Now that we can specify dependencies, we also need to be able to specify what we
provide that other distributions can require. This is done using the <em>provides</em>
keyword argument to <code class="xref py py-func docutils literal notranslate"><span class="pre">setup()</span></code>. The value for this keyword is a list of
strings, each of which names a Python module or package, and optionally
identifies the version. If the version is not specified, it is assumed to match
that of the distribution.</p>
<p>Some examples:</p>
<table border="1" class="docutils">
<colgroup>
<col width="31%" />
<col width="69%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Provides Expression</th>
<th class="head">Explanation</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">mypkg</span></code></td>
<td>Provide <code class="docutils literal notranslate"><span class="pre">mypkg</span></code>, using the distribution
version</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">mypkg</span> <span class="pre">(1.1)</span></code></td>
<td>Provide <code class="docutils literal notranslate"><span class="pre">mypkg</span></code> version 1.1, regardless of
the distribution version</td>
</tr>
</tbody>
</table>
<p>A package can declare that it obsoletes other packages using the <em>obsoletes</em>
keyword argument. The value for this is similar to that of the <em>requires</em>
keyword: a list of strings giving module or package specifiers. Each specifier
consists of a module or package name optionally followed by one or more version
qualifiers. Version qualifiers are given in parentheses after the module or
package name.</p>
<p>The versions identified by the qualifiers are those that are obsoleted by the
distribution being described. If no qualifiers are given, all versions of the
named module or package are understood to be obsoleted.</p>
</div>
<div class="section" id="installing-scripts">
<span id="distutils-installing-scripts"></span><h2>2.5. Installing Scripts<a class="headerlink" href="#installing-scripts" title="Permalink to this headline">¶</a></h2>
<p>So far we have been dealing with pure and non-pure Python modules, which are
usually not run by themselves but imported by scripts.</p>
<p>Scripts are files containing Python source code, intended to be started from the
command line. Scripts don’t require Distutils to do anything very complicated.
The only clever feature is that if the first line of the script starts with
<code class="docutils literal notranslate"><span class="pre">#!</span></code> and contains the word “python”, the Distutils will adjust the first line
to refer to the current interpreter location. By default, it is replaced with
the current interpreter location. The <code class="xref std std-option docutils literal notranslate"><span class="pre">--executable</span></code> (or <code class="xref std std-option docutils literal notranslate"><span class="pre">-e</span></code>)
option will allow the interpreter path to be explicitly overridden.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">scripts</span></code> option simply is a list of files to be handled in this
way. From the PyXML setup script:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span><span class="o">...</span><span class="p">,</span>
<span class="n">scripts</span><span class="o">=</span><span class="p">[</span><span class="s1">'scripts/xmlproc_parse'</span><span class="p">,</span> <span class="s1">'scripts/xmlproc_val'</span><span class="p">]</span>
<span class="p">)</span>
</pre></div>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.7: </span>All the scripts will also be added to the <code class="docutils literal notranslate"><span class="pre">MANIFEST</span></code>
file if no template is provided. See <a class="reference internal" href="sourcedist.html#manifest"><span class="std std-ref">Specifying the files to distribute</span></a>.</p>
</div>
</div>
<div class="section" id="installing-package-data">
<span id="distutils-installing-package-data"></span><h2>2.6. Installing Package Data<a class="headerlink" href="#installing-package-data" title="Permalink to this headline">¶</a></h2>
<p>Often, additional files need to be installed into a package. These files are
often data that’s closely related to the package’s implementation, or text files
containing documentation that might be of interest to programmers using the
package. These files are called <em class="dfn">package data</em>.</p>
<p>Package data can be added to packages using the <code class="docutils literal notranslate"><span class="pre">package_data</span></code> keyword
argument to the <code class="xref py py-func docutils literal notranslate"><span class="pre">setup()</span></code> function. The value must be a mapping from
package name to a list of relative path names that should be copied into the
package. The paths are interpreted as relative to the directory containing the
package (information from the <code class="docutils literal notranslate"><span class="pre">package_dir</span></code> mapping is used if appropriate);
that is, the files are expected to be part of the package in the source
directories. They may contain glob patterns as well.</p>
<p>The path names may contain directory portions; any necessary directories will be
created in the installation.</p>
<p>For example, if a package should contain a subdirectory with several data files,
the files can be arranged like this in the source tree:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="o">.</span><span class="n">py</span>
<span class="n">src</span><span class="o">/</span>
<span class="n">mypkg</span><span class="o">/</span>
<span class="fm">__init__</span><span class="o">.</span><span class="n">py</span>
<span class="n">module</span><span class="o">.</span><span class="n">py</span>
<span class="n">data</span><span class="o">/</span>
<span class="n">tables</span><span class="o">.</span><span class="n">dat</span>
<span class="n">spoons</span><span class="o">.</span><span class="n">dat</span>
<span class="n">forks</span><span class="o">.</span><span class="n">dat</span>
</pre></div>
</div>
<p>The corresponding call to <code class="xref py py-func docutils literal notranslate"><span class="pre">setup()</span></code> might be:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span><span class="o">...</span><span class="p">,</span>
<span class="n">packages</span><span class="o">=</span><span class="p">[</span><span class="s1">'mypkg'</span><span class="p">],</span>
<span class="n">package_dir</span><span class="o">=</span><span class="p">{</span><span class="s1">'mypkg'</span><span class="p">:</span> <span class="s1">'src/mypkg'</span><span class="p">},</span>
<span class="n">package_data</span><span class="o">=</span><span class="p">{</span><span class="s1">'mypkg'</span><span class="p">:</span> <span class="p">[</span><span class="s1">'data/*.dat'</span><span class="p">]},</span>
<span class="p">)</span>
</pre></div>
</div>
<div class="versionadded">
<p><span class="versionmodified">New in version 2.4.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.7: </span>All the files that match <code class="docutils literal notranslate"><span class="pre">package_data</span></code> will be added to the <code class="docutils literal notranslate"><span class="pre">MANIFEST</span></code>
file if no template is provided. See <a class="reference internal" href="sourcedist.html#manifest"><span class="std std-ref">Specifying the files to distribute</span></a>.</p>
</div>
</div>
<div class="section" id="installing-additional-files">
<span id="distutils-additional-files"></span><h2>2.7. Installing Additional Files<a class="headerlink" href="#installing-additional-files" title="Permalink to this headline">¶</a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">data_files</span></code> option can be used to specify additional files needed
by the module distribution: configuration files, message catalogs, data files,
anything which doesn’t fit in the previous categories.</p>
<p><code class="docutils literal notranslate"><span class="pre">data_files</span></code> specifies a sequence of (<em>directory</em>, <em>files</em>) pairs in the
following way:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span><span class="o">...</span><span class="p">,</span>
<span class="n">data_files</span><span class="o">=</span><span class="p">[(</span><span class="s1">'bitmaps'</span><span class="p">,</span> <span class="p">[</span><span class="s1">'bm/b1.gif'</span><span class="p">,</span> <span class="s1">'bm/b2.gif'</span><span class="p">]),</span>
<span class="p">(</span><span class="s1">'config'</span><span class="p">,</span> <span class="p">[</span><span class="s1">'cfg/data.cfg'</span><span class="p">]),</span>
<span class="p">)</span>
</pre></div>
</div>
<p>Each (<em>directory</em>, <em>files</em>) pair in the sequence specifies the installation
directory and the files to install there.</p>
<p>Each file name in <em>files</em> is interpreted relative to the <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code>
script at the top of the package source distribution. Note that you can
specify the directory where the data files will be installed, but you cannot
rename the data files themselves.</p>
<p>The <em>directory</em> should be a relative path. It is interpreted relative to the
installation prefix (Python’s <code class="docutils literal notranslate"><span class="pre">sys.prefix</span></code> for system installations;
<code class="docutils literal notranslate"><span class="pre">site.USER_BASE</span></code> for user installations). Distutils allows <em>directory</em> to be
an absolute installation path, but this is discouraged since it is
incompatible with the wheel packaging format. No directory information from
<em>files</em> is used to determine the final location of the installed file; only
the name of the file is used.</p>
<p>You can specify the <code class="docutils literal notranslate"><span class="pre">data_files</span></code> options as a simple sequence of files
without specifying a target directory, but this is not recommended, and the
<strong class="command">install</strong> command will print a warning in this case. To install data
files directly in the target directory, an empty string should be given as the
directory.</p>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 2.7: </span>All the files that match <code class="docutils literal notranslate"><span class="pre">data_files</span></code> will be added to the <code class="docutils literal notranslate"><span class="pre">MANIFEST</span></code>
file if no template is provided. See <a class="reference internal" href="sourcedist.html#manifest"><span class="std std-ref">Specifying the files to distribute</span></a>.</p>
</div>
</div>
<div class="section" id="additional-meta-data">
<span id="meta-data"></span><h2>2.8. Additional meta-data<a class="headerlink" href="#additional-meta-data" title="Permalink to this headline">¶</a></h2>
<p>The setup script may include additional meta-data beyond the name and version.
This information includes:</p>
<table border="1" class="docutils">
<colgroup>
<col width="30%" />
<col width="36%" />
<col width="23%" />
<col width="11%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Meta-Data</th>
<th class="head">Description</th>
<th class="head">Value</th>
<th class="head">Notes</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">name</span></code></td>
<td>name of the package</td>
<td>short string</td>
<td>(1)</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">version</span></code></td>
<td>version of this release</td>
<td>short string</td>
<td>(1)(2)</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">author</span></code></td>
<td>package author’s name</td>
<td>short string</td>
<td>(3)</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">author_email</span></code></td>
<td>email address of the
package author</td>
<td>email address</td>
<td>(3)</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">maintainer</span></code></td>
<td>package maintainer’s name</td>
<td>short string</td>
<td>(3)</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">maintainer_email</span></code></td>
<td>email address of the
package maintainer</td>
<td>email address</td>
<td>(3)</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">url</span></code></td>
<td>home page for the package</td>
<td>URL</td>
<td>(1)</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">description</span></code></td>
<td>short, summary
description of the
package</td>
<td>short string</td>
<td> </td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">long_description</span></code></td>
<td>longer description of the
package</td>
<td>long string</td>
<td>(5)</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">download_url</span></code></td>
<td>location where the
package may be downloaded</td>
<td>URL</td>
<td>(4)</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">classifiers</span></code></td>
<td>a list of classifiers</td>
<td>list of strings</td>
<td>(4)</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">platforms</span></code></td>
<td>a list of platforms</td>
<td>list of strings</td>
<td> </td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">license</span></code></td>
<td>license for the package</td>
<td>short string</td>
<td>(6)</td>
</tr>
</tbody>
</table>
<p>Notes:</p>
<ol class="arabic simple">
<li>These fields are required.</li>
<li>It is recommended that versions take the form <em>major.minor[.patch[.sub]]</em>.</li>
<li>Either the author or the maintainer must be identified. If maintainer is
provided, distutils lists it as the author in <code class="file docutils literal notranslate"><span class="pre">PKG-INFO</span></code>.</li>
<li>These fields should not be used if your package is to be compatible with Python
versions prior to 2.2.3 or 2.3. The list is available from the <a class="reference external" href="https://pypi.org">PyPI website</a>.</li>
<li>The <code class="docutils literal notranslate"><span class="pre">long_description</span></code> field is used by PyPI when you are
<a class="reference internal" href="packageindex.html#package-register"><span class="std std-ref">registering</span></a> a package, to
<a class="reference internal" href="packageindex.html#package-display"><span class="std std-ref">build its home page</span></a>.</li>
<li>The <code class="docutils literal notranslate"><span class="pre">license</span></code> field is a text indicating the license covering the
package where the license is not a selection from the “License” Trove
classifiers. See the <code class="docutils literal notranslate"><span class="pre">Classifier</span></code> field. Notice that
there’s a <code class="docutils literal notranslate"><span class="pre">licence</span></code> distribution option which is deprecated but still
acts as an alias for <code class="docutils literal notranslate"><span class="pre">license</span></code>.</li>
</ol>
<dl class="docutils">
<dt>‘short string’</dt>
<dd>A single line of text, not more than 200 characters.</dd>
<dt>‘long string’</dt>
<dd>Multiple lines of plain text in reStructuredText format (see
<a class="reference external" href="http://docutils.sourceforge.net/">http://docutils.sourceforge.net/</a>).</dd>
<dt>‘list of strings’</dt>
<dd>See below.</dd>
</dl>
<p>None of the string values may be Unicode.</p>
<p>Encoding the version information is an art in itself. Python packages generally
adhere to the version format <em>major.minor[.patch][sub]</em>. The major number is 0
for initial, experimental releases of software. It is incremented for releases
that represent major milestones in a package. The minor number is incremented
when important new features are added to the package. The patch number
increments when bug-fix releases are made. Additional trailing version
information is sometimes used to indicate sub-releases. These are
“a1,a2,…,aN” (for alpha releases, where functionality and API may change),
“b1,b2,…,bN” (for beta releases, which only fix bugs) and “pr1,pr2,…,prN”
(for final pre-release release testing). Some examples:</p>
<dl class="docutils">
<dt>0.1.0</dt>
<dd>the first, experimental release of a package</dd>
<dt>1.0.1a2</dt>
<dd>the second alpha release of the first patch version of 1.0</dd>
</dl>
<p><code class="docutils literal notranslate"><span class="pre">classifiers</span></code> are specified in a Python list:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setup</span><span class="p">(</span><span class="o">...</span><span class="p">,</span>
<span class="n">classifiers</span><span class="o">=</span><span class="p">[</span>
<span class="s1">'Development Status :: 4 - Beta'</span><span class="p">,</span>
<span class="s1">'Environment :: Console'</span><span class="p">,</span>
<span class="s1">'Environment :: Web Environment'</span><span class="p">,</span>
<span class="s1">'Intended Audience :: End Users/Desktop'</span><span class="p">,</span>
<span class="s1">'Intended Audience :: Developers'</span><span class="p">,</span>
<span class="s1">'Intended Audience :: System Administrators'</span><span class="p">,</span>
<span class="s1">'License :: OSI Approved :: Python Software Foundation License'</span><span class="p">,</span>
<span class="s1">'Operating System :: MacOS :: MacOS X'</span><span class="p">,</span>
<span class="s1">'Operating System :: Microsoft :: Windows'</span><span class="p">,</span>
<span class="s1">'Operating System :: POSIX'</span><span class="p">,</span>
<span class="s1">'Programming Language :: Python'</span><span class="p">,</span>
<span class="s1">'Topic :: Communications :: Email'</span><span class="p">,</span>
<span class="s1">'Topic :: Office/Business'</span><span class="p">,</span>
<span class="s1">'Topic :: Software Development :: Bug Tracking'</span><span class="p">,</span>
<span class="p">],</span>
<span class="p">)</span>
</pre></div>
</div>
<p>If you wish to include classifiers in your <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code> file and also wish
to remain backwards-compatible with Python releases prior to 2.2.3, then you can
include the following code fragment in your <code class="file docutils literal notranslate"><span class="pre">setup.py</span></code> before the
<code class="xref py py-func docutils literal notranslate"><span class="pre">setup()</span></code> call.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># patch distutils if it can't cope with the "classifiers" or</span>
<span class="c1"># "download_url" keywords</span>
<span class="kn">from</span> <span class="nn">sys</span> <span class="k">import</span> <span class="n">version</span>
<span class="k">if</span> <span class="n">version</span> <span class="o"><</span> <span class="s1">'2.2.3'</span><span class="p">:</span>
<span class="kn">from</span> <span class="nn">distutils.dist</span> <span class="k">import</span> <span class="n">DistributionMetadata</span>
<span class="n">DistributionMetadata</span><span class="o">.</span><span class="n">classifiers</span> <span class="o">=</span> <span class="kc">None</span>
<span class="n">DistributionMetadata</span><span class="o">.</span><span class="n">download_url</span> <span class="o">=</span> <span class="kc">None</span>
</pre></div>
</div>
</div>
<div class="section" id="debugging-the-setup-script">
<span id="debug-setup-script"></span><h2>2.9. Debugging the setup script<a class="headerlink" href="#debugging-the-setup-script" title="Permalink to this headline">¶</a></h2>
<p>Sometimes things go wrong, and the setup script doesn’t do what the developer
wants.</p>
<p>Distutils catches any exceptions when running the setup script, and print a
simple error message before the script is terminated. The motivation for this
behaviour is to not confuse administrators who don’t know much about Python and
are trying to install a package. If they get a big long traceback from deep
inside the guts of Distutils, they may think the package or the Python
installation is broken because they don’t read all the way down to the bottom
and see that it’s a permission problem.</p>
<p>On the other hand, this doesn’t help the developer to find the cause of the
failure. For this purpose, the <span class="target" id="index-0"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">DISTUTILS_DEBUG</span></code> environment variable can be set
to anything except an empty string, and distutils will now print detailed
information about what it is doing, dump the full traceback when an exception
occurs, and print the whole command line when an external program (like a C
compiler) fails.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">2. Writing the Setup Script</a><ul>
<li><a class="reference internal" href="#listing-whole-packages">2.1. Listing whole packages</a></li>
<li><a class="reference internal" href="#listing-individual-modules">2.2. Listing individual modules</a></li>
<li><a class="reference internal" href="#describing-extension-modules">2.3. Describing extension modules</a><ul>
<li><a class="reference internal" href="#extension-names-and-packages">2.3.1. Extension names and packages</a></li>
<li><a class="reference internal" href="#extension-source-files">2.3.2. Extension source files</a></li>
<li><a class="reference internal" href="#preprocessor-options">2.3.3. Preprocessor options</a></li>
<li><a class="reference internal" href="#library-options">2.3.4. Library options</a></li>
<li><a class="reference internal" href="#other-options">2.3.5. Other options</a></li>
</ul>
</li>
<li><a class="reference internal" href="#relationships-between-distributions-and-packages">2.4. Relationships between Distributions and Packages</a></li>
<li><a class="reference internal" href="#installing-scripts">2.5. Installing Scripts</a></li>
<li><a class="reference internal" href="#installing-package-data">2.6. Installing Package Data</a></li>
<li><a class="reference internal" href="#installing-additional-files">2.7. Installing Additional Files</a></li>
<li><a class="reference internal" href="#additional-meta-data">2.8. Additional meta-data</a></li>
<li><a class="reference internal" href="#debugging-the-setup-script">2.9. Debugging the setup script</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="introduction.html"
title="previous chapter">1. An Introduction to Distutils</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="configfile.html"
title="next chapter">3. Writing the Setup Configuration File</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/distutils/setupscript.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="configfile.html" title="3. Writing the Setup Configuration File"
>next</a> |</li>
<li class="right" >
<a href="introduction.html" title="1. An Introduction to Distutils"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">Python 2.7.16 documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >Distributing Python Modules (Legacy version)</a> »</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Mar 27, 2019.
<a href="